設定 Slack 整合

本指南說明如何把 Slack 連線到 Control Center 工作區——既可以讓 Control Center 建立應用程式，也可以自行建置。

若想要有引導的初次體驗，請參見將 Slack 橋接至工作區。

先決條件

在 Control Center 工作區中具備 owner 或 admin 角色——連線聊天應用程式屬於工作區設定的變更
有權在 Slack 工作區中建立並安裝應用程式
不需要任何可公開觸達的資源：連線是主動外連的（Socket Mode），因此伺服器不需要入站連接埠、隧道或網域

取得應用程式的三種方式

方式	你需要提供	Control Center 會做
引導式	一組應用程式設定 token（`xoxe-…`）	建立應用程式並設定正確的權限範圍、事件、Socket Mode 與斜線指令；把 Slack 沒有 API 可用的兩個步驟交給你
在 Slack 中建立	不需要提供任何內容	以相同的設定預先填好並開啟 Slack；由你挑選工作區並確認
手動	已完成應用程式的 token	驗證這些 token 並建立連線

只有引導式路徑還能讓應用程式可以從 Control Center 管理，而這正是自訂聊天機器人得以實現的前提。透過 在 Slack 中建立 建立的應用程式，之後只要在連線對話框中貼上一組設定 token，就能升級為受管理的應用程式。

產品刻意不提供「安裝 Control Center 的 Slack 應用程式」按鈕。安裝一個對外發佈的 Slack 應用程式需要共享的用戶端密鑰（Slack 沒有 PKCE），而 Socket Mode 會把同一個應用程式的事件隨機分散到它的各條連線上——因此一個共享應用程式會把你工作區的訊息投遞到別人的伺服器上。所以每個工作區都擁有自己的應用程式，而這三條路徑要解決的，就是把這份代價壓到多低。

方式 A：讓 Control Center 建立應用程式

在 api.slack.com/apps 產生一組應用程式設定 token，並複製更新 token（xoxe-…）
在 Control Center 中前往 設定 → 工作區 → 一般，向下捲動至 聊天橋接 卡片
在 Slack 區塊上點擊 幫我建立應用程式
貼上 token，調整應用程式名稱、機器人名稱、說明與斜線指令，然後點擊 建立應用程式
依照對話框顯示的兩個剩餘步驟操作，每個步驟都是一個前往 Slack 的連結：
- Basic Information → App-Level Tokens：產生一個具備 connections:write 權限範圍的 token（xapp-…）
- Install App：安裝到工作區，並複製 Bot User OAuth Token（xoxb-…）
點擊 貼上憑證，然後繼續進行連線

設定 token 每次使用都會輪換。Control Center 會隨手保存輪換後的值，因此你永遠不必再次貼上它。

方式 B：在 Slack 中建立，設定已預先填好

同樣的應用程式，不需要設定 token——Slack 會開啟它自己的建立畫面，整份 manifest 都已經填好。

在 Control Center 中前往 設定 → 工作區 → 一般，向下捲動至 聊天橋接 卡片
在 Slack 區塊上點擊 幫我建立應用程式
調整應用程式名稱、機器人名稱、說明與斜線指令——這些設定會隨連結一起傳遞
點擊 在 Slack 中建立。瀏覽器會開啟 Slack 的應用程式建立頁面，並已預先填入設定
挑選 Slack 工作區並確認。權限範圍、事件、Socket Mode 與斜線指令都已經正確
回到 Control Center，依照對話框顯示的兩個剩餘步驟操作：
- Basic Information → App-Level Tokens：產生一個具備 connections:write 權限範圍的 token（xapp-…）
- Install App：安裝到工作區，並複製 Bot User OAuth Token（xoxb-…）
點擊 貼上憑證，然後繼續進行連線

Slack 不會回報它建立了哪個應用程式，因此 Control Center 無從得知應用程式 id，而第 6 步中的連結會前往你的應用程式清單，而不是直接開啟該應用程式。自訂機器人 需要一組設定 token。

方式 C：自行建置應用程式

在 api.slack.com/apps 建立應用程式，然後依照下列方式設定。

Socket Mode：啟用它，並把所有請求 URL 留空。若一份 manifest 同時要求 Socket Mode 與 webhook 傳遞，Slack 會拒絕。

機器人 token 權限範圍（OAuth & Permissions）：

app_mentions:read
assistant:write
channels:history
chat:write
commands
groups:history
im:history
users:read
users:read.email

事件訂閱（機器人事件）：

app_home_opened
app_mention
message.channels
message.groups
message.im

正是 message.channels 與 message.groups 讓已橋接的 Slack 討論串中的回覆得以運作。少了它們，只會有第一次提及送達。

斜線指令：/cc（名稱可以任意——橋接會使用它最後一次被叫用時所用的指令）。

App Home：啟用 Messages 分頁並保持可寫入，讓成員可以私訊機器人。

Token：產生一個具備 connections:write 的應用程式層級 token，然後安裝應用程式並複製機器人使用者 OAuth token。

連線

前往 設定 → 工作區 → 一般，向下捲動至 聊天橋接 卡片
在 Slack 區塊上點擊 連接 Slack
填寫下列欄位：

欄位	值	在 Slack 中的位置
機器人使用者 OAuth token	`xoxb-…`	OAuth & Permissions → Bot User OAuth Token
應用程式層級 token	`xapp-…`	Basic Information → App-Level Tokens（`connections:write`）
應用程式設定更新 token（選填）	`xoxe-…`	api.slack.com/apps 上的應用程式設定 token 組

每個值的前綴都會在送出任何內容之前由兩側檢查，因此貼錯欄位的值，無論在哪一側被擋下，得到的都是同一句話。

點擊連線

Control Center 會在儲存任何內容之前，用 Slack 的 auth.test 驗證機器人 token，因此打錯字會直接回報給你，而不是變成一個悄悄永不運作的通訊端。應用程式層級 token 只能透過開啟通訊端來證明，因此它有問題時，會在片刻之後以同一列上的連線錯誤呈現。

沒有選填的應用程式設定 token 時，連線照常運作——只是無法從 Control Center 編輯機器人。

連線後會做什麼

把憑證存放在工作區自己的目錄中，就在其資料庫旁邊，且僅限擁有者讀取。它們永遠不會再回到用戶端
為這個工作區開啟一條 Socket Mode 連線，並開始接收提及、Slack 討論串回覆、私訊與斜線指令
重新接上先前已橋接的每一個 Slack 討論串，因此重新連線會延續既有對話，而不是把它們擱置
對沒有聊天應用程式的工作區毫無成本：沒有通訊端、沒有計時器、沒有流量

機器人憑證是每個供應商一個純 JSON 檔案，位於 <dataDir>/<workspaceId>/chat_credentials/，以原子方式寫入並收緊為僅限擁有者。這是刻意如此，而不是疏漏：刪除工作區會解除該目錄的連結，其中的 token 也隨之而去；而 workspace.export 與備份複製的是 workspace.db——不是該目錄——因此你交給別人的工作區，絕不會夾帶仍然有效的機器人 token。由此推得的結果是：把工作區還原到別處，就表示要在那裡重新連接 Slack。

對橋接的存取權來自工作區成員資格，而絕不是持有 token。Slack 帳號必須連結到一位具備可寫入角色的 Control Center 成員使用者。連線、中斷連線、引導式設定、設定連結與機器人自訂，全部只有管理員能操作。

驗證

Slack 資料列會顯示狀態標籤：已上線、連線中…、連線錯誤（旁邊是 Slack 自己的錯誤訊息），或 未連線。若要端對端檢查：

在 Slack 中把機器人邀請到某個頻道：/invite @your-bot-name
用一則請求提及它
會出現一則 Slack 討論串回覆，並在 Control Center 中出現對應的空間

之後，每位想使用橋接的成員都要連結自己的帳號——參見連結你的 Slack 帳號。

回覆在 Slack 中看起來是什麼樣子

在串流輸出的文字上方，是一張分組卡片，每個步驟各佔一列。設定階段是一列，其標題會從 Working on it… 變成 Cloning …，再變成 Starting the agent…。推理會新增一列 Thinking…；該步驟結束時，這一列上可以出現一句簡短的思考。每個工具各佔一列（Read lib/main.dart）。回答會以一般文字的形式出現在卡片下方。回合結束時卡片會變成完成狀態；執行失敗、被中斷，或達到回合上限時，則變成錯誤狀態。

卡片會在機器人接受提及的那一刻開啟——Working on it…——因此當工作區還在建置時，Slack 討論串不會一片沉默。你在 Slack 頻道中的第一次提及會建立對話，而建立對話會複製代理工作的儲存庫，所以那一列設定資訊接著會依序顯示 Cloning acme/widgets…、Setting up Reviewer…、Starting the agent…，等代理真的開始推理時再出現一列 Thinking…。在大型儲存庫上，第一次設定會花上一段時間；卡片就是讓你分辨它正在工作、而不是在忽略你的方式。同一個 Slack 討論串中後續的提及，仍然以 Working on it… 開場，接著跳過複製步驟，因為工作區已經存在。

整面文字牆般的推理與工具輸出，永遠不會離開 Control Center——Thinking… 那一列上的思考只是短短一行，而不是逐字稿。卡片上的 View in Control Center 會在桌面應用程式中開啟完整對話——該連結指向你自己的 Control Center 伺服器，由它把瀏覽器交給應用程式。

如果點擊後沒有任何反應，表示送出該訊息的伺服器無法從你點擊的那臺機器觸達（例如從手機點擊一臺只監聽回送位址的伺服器），或者那臺機器上並沒有執行 Control Center。沒有可觸達位址的伺服器，送出的卡片不會帶按鈕，而不是帶一個通往死路的按鈕。

輪換 token

在連線對話框中重新貼上新值，然後點擊連線。連線會取代這個工作區上原本在執行的任何連線，因此通訊端會以新的憑證重新撥接。

兩個必要 token 在每次連線時都必須填寫。選填的應用程式設定 token 在你把欄位留空時會保留已儲存的值，因此輪換機器人 token 絕不會讓你失去編輯應用程式的能力。

中斷連線

在 Slack 資料列上點擊 中斷連線（僅限管理員）。通訊端會關閉，憑證則會被遺忘。

空間與使用者連結會刻意保留下來：重新連接同一個應用程式會還原每一個已橋接的 Slack 討論串。它們是按工作區範圍歸屬的資料列，因此刪除工作區本來也會一併移除。

疑難排解

資料列顯示「連線錯誤」

請閱讀標籤旁邊顯示的錯誤。被拒絕的憑證（invalid_auth、not_authed、token_revoked、account_inactive）屬於終局狀態——橋接會停止重試並等待新的 token，因為永遠重試一個已撤銷的 token，只會換來速率限制。請在連線對話框中重新貼上 token。

missing_scope 錯誤表示應用程式安裝時取得的權限範圍少於橋接所需。補上缺少的權限範圍，在 Slack 中重新安裝應用程式，然後重新連線。

任何短暫性問題（通訊端中斷、Slack 打嗝）都會自行重新連線，採用上限為 30 秒的指數退避，而 Slack 例行的通訊端輪替不會讓該退避升級。

機器人不回應提及

機器人有加入頻道嗎？ Slack 只會把頻道訊息投遞給屬於成員的應用程式。請執行 /invite @your-bot-name
你完成連結了嗎？ 尚未連結的成員會在該 Slack 討論串中收到一則說明如何連結的回覆。參見連結你的 Slack 帳號
你是這個工作區中具備可寫入角色的成員嗎？ viewer 或 guest 會被告知其角色是唯讀的。橋接絕不會代表一個它無法歸屬的人開始工作
這個工作區有任何代理嗎？ 沒有任何代理時，訊息會被儲存，但沒有人能回答它

它會在頻道中回答，卻忽略一般訊息

這是刻意設計。在私訊之外，橋接只會對提及機器人的訊息，或它所擁有的 Slack 討論串中的回覆採取行動。其他一切都屬於別人的對話。

回覆以單一大型訊息送達，而不是串流

該列會顯示「此 Slack 應用程式已關閉即時串流——回覆會以單一訊息送達。」Slack 的串流回覆需要付費方案中的 Agents & AI Apps 功能；當 Slack 拒絕時，橋接會在這條連線剩下的生命週期內不再請求，改為發布完整回覆。什麼都不會遺失——完整逐字稿一律都在 Control Center。

串流也需要一個 Slack 討論串錨點，因此沒有討論串可供生長的回覆會整則發布。無論哪種情況，任務卡片都照常送達：在完整回覆上，它搭同一則訊息一起送達，而且已經是完成狀態。

回覆上方沒有卡片

Slack 的任務卡片與串流屬於同一個新的 Agents & AI Apps 介面，而 Slack 只在呼叫當下才會拒絕。一旦如此，Control Center 會在這條連線剩下的生命週期內保留回覆並捨棄卡片——有回答而沒有狀態行，勝過有狀態行而沒有回答。

「Control Center 需要應用程式設定 token 才能編輯機器人」

自訂機器人 這一列會停用，因為這條連線沒有應用程式設定 token。對於以手動方式建立，或透過 在 Slack 中建立 建立的應用程式，這是預期行為——Slack 從未告訴 Control Center 它是哪個應用程式。請在 api.slack.com/apps 上產生一組 token，並填好更新 token 後重新連線。

較長的回答被截斷

Slack 把單一訊息的上限設為 40,000 個字元，因此橋接會在 39,000 處截斷，並附加一個指向 Control Center 的指引——縮短的回覆，勝過被 Slack 直接拒收的回覆。完整文字一律都在空間的逐字稿裡。