設定 Slack 整合

本指南說明如何將 Slack 連接到 Control Center 工作區——你可以讓 Control Center 代為建立應用程式，也可以自行建置它。

如想要一次有引導的首次體驗，請參閱將 Slack 橋接到工作區。

Slack 是唯一的聊天提供方

橋接在設計上對提供方一視同仁——由描述元驅動的介面，底下每個提供方各有一個 配接器——但現時存在的配接器只有 Slack 一個。並沒有 Discord、Telegram、Teams 或 Matrix 的實作。

先決條件

• Control Center 工作區中的 owner 或 admin 角色——連接聊天應用程式屬於工作區設定的變更
• 在該 Slack 工作區中建立及安裝應用程式的權限
• 無需任何對外公開的東西：連線是對外發起的（Socket Mode），因此伺服器不需要入站連接埠、通道或網域

取得應用程式的三種方式

途徑	你需要提供	Control Center 會做
引導式	應用程式設定權杖（xoxe-…）	以正確的權限範圍、事件、Socket Mode 與斜線指令建立應用程式；並把你帶到 Slack 沒有 API 可用的那兩個步驟
在 Slack 中建立	無需提供	以相同的設定預先填好並開啟 Slack；你只需挑選工作區並確認
手動	已完成應用程式的權杖	驗證它們並連接

只有引導式途徑會同時讓應用程式可從 Control Center 管理，而這正是自訂聊天機械人得以運作的前提。透過在 Slack 中建立製作的應用程式，之後只要在連接對話框中貼上設定權杖，就能提升為受管理的應用程式。

我們刻意不提供「安裝 Control Center 的 Slack 應用程式」按鈕。安裝一個分散式的 Slack 應用程式需要共用用戶端密鑰（Slack 沒有 PKCE），而 Socket Mode 會把應用程式的事件隨機分散到它的各個連線上——因此一個共用應用程式會把你工作區的訊息送到別人的伺服器。所以每個工作區都擁有自己的應用程式，而這三種途徑要說明的，正是這麼做所需的工夫有多小。

選項 A：讓 Control Center 建立應用程式

1. 在 api.slack.com/apps 產生一組應用程式設定權杖，並複製重新整理權杖（xoxe-…）
2. 在 Control Center 中，前往 設定 → 工作區 → 一般，捲到聊天橋接卡片
3. 在 Slack 區塊上，按一下幫我建立應用程式
4. 貼上權杖，調整應用程式名稱、機械人名稱、描述與斜線指令，然後按一下建立應用程式
5. 依照對話框所示完成餘下兩個步驟，每個都是一條通往 Slack 的連結：
   • Basic Information → App-Level Tokens：產生一個具備 connections:write 權限範圍的權杖（xapp-…）
   • Install App：安裝到工作區，並複製 Bot User OAuth Token（xoxb-…）
6. 按一下貼上憑證，然後繼續前往連接

設定權杖每次使用都會輪替。Control Center 會在使用過程中儲存輪替後的值，因此你永遠不必再貼一次。

選項 B：在 Slack 中建立，並預先填好設定

同一個應用程式，但不需要設定權杖——Slack 會把你帶到它自己的建立畫面，整份 manifest 都已填好。

1. 在 Control Center 中，前往 設定 → 工作區 → 一般，捲到聊天橋接卡片
2. 在 Slack 區塊上，按一下幫我建立應用程式
3. 調整應用程式名稱、機械人名稱、描述與斜線指令——這些會隨連結一併帶過去
4. 按一下在 Slack 中建立。瀏覽器會開啟 Slack 的應用程式建立頁面，並已預先填好設定
5. 挑選 Slack 工作區並確認。權限範圍、事件、Socket Mode 與斜線指令都已正確無誤
6. 回到 Control Center，依照對話框所示的餘下兩個步驟：
   • Basic Information → App-Level Tokens：產生一個具備 connections:write 權限範圍的權杖（xapp-…）
   • Install App：安裝到工作區，並複製 Bot User OAuth Token（xoxb-…）
7. 按一下貼上憑證，然後繼續前往連接

Slack 不會回報它建立了哪個應用程式，因此 Control Center 不會得知該應用程式 id，而第 6 步的連結會指向你的應用程式清單，而不是直接前往該應用程式。自訂機械人需要一個設定權杖。

選項 C：自行建置應用程式

在 api.slack.com/apps 建立一個應用程式，然後按以下方式設定它。

Socket Mode：將它啟用，並把所有 request URL 留空。Slack 會拒絕同時要求 Socket Mode 與 webhook 傳送的 manifest。

Bot token scopes（OAuth & Permissions）：

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

Event subscriptions（機械人事件）：

app_home_opened
app_mention
message.channels
message.groups
message.im

在一個已經橋接的 Slack 討論串中，_回覆_之所以能夠運作，靠的正是 message.channels 與 message.groups。沒有它們，就只有第一次提及會送達。

Slash command：/cc（任何名稱都可以——橋接會沿用最後一次被叫用的那個指令）。

App Home：啟用 Messages 分頁並讓它保持可寫入，成員才能私訊機械人。

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

連接

1. 前往 設定 → 工作區 → 一般，捲到聊天橋接卡片
2. 在 Slack 區塊上，按一下連接 Slack
3. 填寫各欄位：

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

每個值的前綴都會在送出任何內容之前於兩邊檢查，因此貼進錯誤欄位的值，無論從哪一邊看都會以同一句話被拒絕。

4. 按一下連線

Control Center 會在儲存任何內容_之前_以 Slack 的 auth.test 驗證機械人權杖，因此打錯字會回報給你，而不是變成一個永遠無法運作的 Socket 連線。應用程式層級權杖只能靠開啟 Socket 連線來證明，因此一個壞的權杖過一會就會在同一列上顯示為連線錯誤。

沒有選填的應用程式設定權杖，連接仍可正常運作——只是無法從 Control Center 編輯機械人。

連接會做什麼

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

權杖存放在哪裏，以及為何不放進鑰匙圈

機械人憑證是每個提供方一個純 JSON 檔案，位於 <dataDir>/<workspaceId>/chat_credentials/，以原子方式寫入，並收緊至僅擁有者可讀。 這是刻意的，不是疏漏：刪除工作區會解除該目錄的連結，讓它的權杖一併消失； 而 workspace.export 與備份複製的是 workspace.db——不是該目錄——因此你交給 別人的工作區，內裏永遠不會帶着仍然有效的機械人權杖。推論就是：在其他地方還原 工作區，意味着要在那裏重新連接 Slack。

使用橋接的資格是工作區成員身分，而從來不是持有權杖。一個 Slack 帳戶必須 連結到一位身為成員、且具有可寫角色的 Control Center 使用者。連接、中斷連線、 引導式設定、設定連結與機械人自訂，全部只限管理員。

驗證

Slack 那一列會顯示一個狀態標籤：已上線、連線中…、連線錯誤（旁邊是 Slack 自己的錯誤），或未連線。如要作端到端檢查：

1. 在 Slack 中，把機械人邀請到某個頻道：/invite @your-bot-name
2. 以一個請求提及它
3. 一個 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 並未在那裏執行。沒有可達位址的伺服器會送出一張沒有按鈕的卡片，而不是一張通往死路的卡片。

輪替權杖

在連接對話框中重新貼上新值，然後按一下連線。連接會取代此工作區當時正在執行的任何連接，因此 Socket 連線會以新憑證重新撥接。

兩個必要的權杖在每次連接時都必須填寫。選填的應用程式設定權杖在你把該欄留空時，會保留已儲存的值，因此輪替機械人權杖永遠不會令你失去編輯應用程式的能力。

中斷連線

在 Slack 那一列上按一下中斷連線（僅限管理員）。Socket 連線會關閉，而憑證會被忘記。

空間與使用者連結會刻意保留下來：重新連接同一個應用程式，會還原所有已橋接的 Slack 討論串。它們都是以工作區為範圍的資料列，因此刪除工作區無論如何都會移除它們。

疑難排解

該列顯示「連線錯誤」

請細閱標籤旁邊顯示的錯誤。憑證被拒（invalid_auth、not_authed、token_revoked、account_inactive）屬於終結性錯誤——橋接會停止重試並等待新的權杖，因為永遠重試一個已撤銷的權杖，只會令你被限速。請在連接對話框中重新貼上權杖。

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

任何暫時性的問題（Socket 斷線、Slack 一時不順）都會自行以指數退避重新連接，退避上限為 30 秒，而 Slack 例行的 Socket 輪替並不會令該退避加劇。

機械人沒有回應提及

• 機械人在頻道中嗎？ Slack 只會把頻道訊息遞送給身為成員的應用程式。請執行 /invite @your-bot-name
• 你已連結了嗎？ 未連結的成員會在該 Slack 討論串中收到一則回覆，說明如何連結。參閱連結你的 Slack 帳戶
• 你是本工作區的成員，而且具有可寫角色嗎？ viewer 或 guest 會被告知其角色是唯讀。橋接永遠不會代它無法歸屬的人開始工作
• 工作區有任何代理嗎？ 沒有代理時，訊息會被儲存，但沒有人能回答它

它在頻道中會回答，但忽略普通訊息

這是刻意如此。在私訊以外，橋接只會對提及機械人的訊息，或它已擁有的 Slack 討論串中的回覆採取行動。其他一切，都是別人的對話。

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

該列會顯示「此 Slack 應用程式已關閉即時串流——回覆會以單一訊息送達。」Slack 的串流回覆需要在付費方案上具備 Agents & AI Apps 功能；當 Slack 拒絕時，橋接在該次連接的餘生都不會再嘗試要求，改為張貼整段回覆。沒有任何內容會遺失——完整的逐字紀錄永遠都在 Control Center。

串流也需要一個 Slack 討論串錨點，因此一條沒有 Slack 討論串可供依附成長的回覆，會以整段形式張貼。無論哪種情況，任務卡片仍然會送達：在整段回覆上，它會搭在同一則訊息上一併送出，而且已經是完成狀態。

回覆上方沒有卡片

Slack 的任務卡片與串流同屬新增的 Agents & AI Apps 介面，而 Slack 只在呼叫當下才會拒絕。遇到這種情況時，Control Center 會保留回覆，並在該次連接的餘生都不再送出卡片——一個沒有狀態列的答案，勝過一個沒有答案的狀態列。

「Control Center 需要應用程式設定權杖才能編輯機械人」

自訂機械人那一列會停用，因為該連接沒有應用程式設定權杖。對於手動製作、或透過在 Slack 中建立製作的應用程式，這是預期之中的——Slack 從未告訴 Control Center 它是哪個應用程式。請在 api.slack.com/apps 產生一組權杖，並在填好重新整理權杖的情況下重新連接。

過長的答案被截斷

Slack 把單一訊息上限定為 40,000 個字元，因此橋接會在 39,000 個字元處截斷，並附加一個指向 Control Center 的提示——一段縮短了的回覆，勝過一段被 Slack 直接拒絕的回覆。完整文字永遠都在空間的逐字紀錄中。

相關指南

• 連結你的 Slack 帳戶
• 自訂聊天機械人
• 聊天橋接

相關概念

• 聊天橋接