六個步驟，讓它在你的 Slack 上線

照著做就會動。中間任何一步不確定有沒有成功，都有一個指令可以問它。

約 15 分鐘 · macOS / Linux / Windows · 需要 Slack 管理權限

想先看整體長什麼樣子，這張圖上的每一個東西都對應下面某一步。

開始之前，先確認兩件事

你有權限在你們的 Slack 工作區建立 app（沒有的話，請你們的 Slack 管理員做步驟 2 與 3）。
你有一個 Claude 帳號，最後一步會用它登入。
那台機器上有 Claude Code —— legatio-agent 透過它與 AI 對話。還沒有的話：npm install -g @anthropic-ai/claude-code（需要 Node.js）。不確定的話先裝好 legatio-agent，跑一次 legatio-agent doctor，缺什麼它會講。

1 · 下載 legatio-agent

一個檔案，沒有安裝程式。目前發行版是 v0.1.1 —— 它會做什麼、還不會做什麼，見版本說明。

複製對應你機器的那一行貼進終端機：

# macOS（Apple 晶片 · M1 之後）
curl -fsSL -o legatio-agent https://ignikah.dev/legatio/download/legatio-agent_darwin_arm64

# macOS（Intel）
curl -fsSL -o legatio-agent https://ignikah.dev/legatio/download/legatio-agent_darwin_amd64

# Linux（x86_64）
curl -fsSL -o legatio-agent https://ignikah.dev/legatio/download/legatio-agent_linux_amd64

# Linux（ARM · 樹莓派、Graviton…）
curl -fsSL -o legatio-agent https://ignikah.dev/legatio/download/legatio-agent_linux_arm64

不確定自己是哪一種 macOS？終端機打 uname -m —— arm64 選第一個，x86_64 選第二個。

然後給它執行權限、放進 PATH，確認裝好了：

chmod +x legatio-agent
sudo mv legatio-agent /usr/local/bin/

legatio-agent version

Windows 請改用這一段

用 PowerShell（開始選單搜尋 PowerShell）。下載、放進一個固定位置、加進 PATH：

curl.exe -fsSL -o legatio-agent.exe https://ignikah.dev/legatio/download/legatio-agent_windows_amd64.exe

New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\legatio" | Out-Null
Move-Item -Force legatio-agent.exe "$env:LOCALAPPDATA\legatio\"

# 加進 PATH（只需做這一次，之後開新視窗就找得到）
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\legatio",
  "User")

關掉這個視窗、重開一個新的 PowerShell（PATH 的改動要新視窗才生效），然後確認：

legatio-agent version

後面所有步驟裡的 legatio-agent … 指令在 PowerShell 裡一樣可以直接打。只有「設定環境變數」那一步寫法不同 —— 第 4 步有對應的 Windows 版本。

Windows 說「已保護您的電腦」？

那是 SmartScreen 對還沒有大量下載紀錄的程式的預設反應。點其他資訊 → 仍要執行。不放心的話，先做下面的校驗和核對再執行。

Windows 上「執行指令」這項功能不會放行

doctor 的隔離檢查認得的是 Linux 容器。在 Windows 上它一律判定「不在隔離環境內」，因此最後一節那個「讓它會做事」的執行指令開關不會被放行。其餘功能（對話、讀寫檔案的開關、/auth）不受影響。要用到執行指令，請在 Linux 容器裡跑 —— 歡迎跟我們聯絡。

想先核對檔案沒被動過手腳

算出你手上這個檔案的校驗和 —— 看你用哪一種終端機，兩個指令不通用：

macOS / Linux：

shasum -a 256 legatio-agent

Windows（PowerShell）—— 這裡沒有 shasum 這個指令，要用 Get-FileHash：

Get-FileHash "$env:LOCALAPPDATA\legatio\legatio-agent.exe" -Algorithm SHA256

再跟 SHA256SUMS 裡對應你機器那一行比對，兩串字要一模一樣。Windows 印出來的是大寫，比對時不分大小寫 —— F97DFE… 與 f97dfe… 是同一串。

現在什麼都還不會發生

這是刻意的。剛裝好的 legatio-agent 一件事都不會做 —— 它不會連上任何地方、不會讀你的檔案、不會發出任何請求。接下來五個步驟就是一項一項把它需要的東西給它。

隨時可以問它現在的狀況：

legatio-agent doctor

它會逐項檢查並把缺的東西連同怎麼補一起講出來。這個指令不會改動你的電腦，也不會連到外面去。

macOS 說「無法打開，因為無法驗證開發者」？

那是用瀏覽器下載才會遇到的。照上面用 curl 下載就不會 —— 如果你已經用瀏覽器下載了，執行一次 xattr -d com.apple.quarantine legatio-agent 即可。

2 · 在 Slack 建立 app

這是它進到你們聊天室的身分。用現成的設定檔，不用一項一項勾。

打開 api.slack.com/apps → Create New App → 選 From an app manifest
選擇要安裝的工作區
把下面整段貼進去（把 YAML 分頁選起來），按 Next → Create

display_information:
  name: legatio
  description: 團隊裡的 AI 工作夥伴
  background_color: "#2f437e"

features:
  bot_user:
    display_name: legatio
    always_online: true
  slash_commands:
    - command: /auth
      description: 登入 AI 服務
      should_escape: false
    - command: /help
      description: 看它會做什麼
      should_escape: false

oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - im:history
      - im:read
      - im:write
      - commands

settings:
  event_subscriptions:
    bot_events:
      - app_mention
      - message.im
  socket_mode_enabled: true
  org_deploy_enabled: false
  token_rotation_enabled: false

為什麼要用這份，不要自己勾

少了 commands 這一項權限，第 6 步的 /auth 指令會送不到 app，而 Slack 不會告訴你原因 —— 你只會看到它沒有反應。

3 · 取得兩把 token

一把讓它連上 Slack，一把讓它說話。兩把都要。

要拿的	在哪裡	長什麼樣
App-Level Token	左側 Basic Information → App-Level Tokens → Generate Token and Scopes → 隨便取個名字 → 加入 `connections:write` → Generate	`xapp-…`
Bot Token	左側 Install App → Install to Workspace → 允許 → 複製 Bot User OAuth Token	`xoxb-…`

再拿一個東西：你自己的 Slack 使用者 ID。在 Slack 裡點自己的頭像 → 個人檔案 → 右上角「⋮」→ 複製成員 ID，會是 U 開頭的一串字。

這三個值等一下要用，先貼在記事本

兩把 token 等同你們工作區的鑰匙 —— 不要貼到聊天室、不要放進共用文件、不要提交到程式碼裡。

4 · 設定並啟動

把剛才那三個值給它，然後打開你要的功能。

建立一個設定檔（例如 ~/legatio.env），把值填進去：

# ── 你的三個值 ─────────────────────────────
export SLACK_APP_TOKEN=xapp-你的-app-token
export SLACK_BOT_TOKEN=xoxb-你的-bot-token
export LEGATIO_AGENT_OWNER_SLACK_IDS=U你的成員ID

# ── 打開這一輪要用的功能 ────────────────────
#    先只開「能連上、能收指令、能登入」，還不能對話
export LEGATIO_AGENT_FLAG_AGENT_CHAT_SLACK=true
export LEGATIO_AGENT_FLAG_AGENT_COMMAND_DISPATCH=true
export LEGATIO_AGENT_FLAG_AGENT_COMMAND_HELP=true
export LEGATIO_AGENT_FLAG_AGENT_AUTH_LOGIN=true

載入設定，先問它一次，沒問題再啟動：

source ~/legatio.env

legatio-agent doctor     # 有紅色的 ✗ 就照它說的補
legatio-agent run

Windows 的設定檔長這樣

PowerShell 沒有 export／source。建一個 legatio.ps1（放哪都行，例如 $env:USERPROFILE\legatio.ps1），內容改成 $env: 的寫法：

# ── 你的三個值 ─────────────────────────────
$env:SLACK_APP_TOKEN = "xapp-你的-app-token"
$env:SLACK_BOT_TOKEN = "xoxb-你的-bot-token"
$env:LEGATIO_AGENT_OWNER_SLACK_IDS = "U你的成員ID"

# ── 打開這一輪要用的功能 ────────────────────
$env:LEGATIO_AGENT_FLAG_AGENT_CHAT_SLACK = "true"
$env:LEGATIO_AGENT_FLAG_AGENT_COMMAND_DISPATCH = "true"
$env:LEGATIO_AGENT_FLAG_AGENT_COMMAND_HELP = "true"
$env:LEGATIO_AGENT_FLAG_AGENT_AUTH_LOGIN = "true"

載入時前面那個點和空格不能少（少了就會在子行程裡設完即丟，等於沒設）：

. $env:USERPROFILE\legatio.ps1

legatio-agent doctor
legatio-agent run

⚠️ 第一次執行 .ps1 若被擋（「因為這個系統上已停用指令碼執行」），跑一次 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 再試。

啟動後你會看到它把每一項功能的開關狀態列出來。 只有你打開的那幾項是 ON，其餘全是 off —— 這是正常的。

想知道它現在被允許做什麼

legatio-agent flags

這會列出全部功能與它們現在的狀態。以後任何時候覺得「它怎麼不做某件事」，先看這裡。

5 · 在 Slack 測一下

確認它真的連上了，再往下走。

在 Slack 左側找到 legatio（在「應用程式」底下），點開它的私訊
輸入 /help 送出

它應該會回你一段說明。看到回應就代表前四步都成功了。

狀況	原因
完全沒反應	兩把 token 對調了，或 App-Level Token 少了 `connections:write`。停掉它、檢查設定檔、重新啟動。
Slack 說找不到 `/help` 指令	步驟 2 的設定檔沒貼完整。回 app 設定頁確認 Slash Commands 有 `/auth` 與 `/help`。
它說「無此指令」	你的成員 ID 沒填對。它預設誰都不理，只回應名單上的人。

6 · 登入 AI，讓它開始工作

前面五步是把管道接通，這一步才是給它腦袋。

在剛才那個私訊視窗裡：

輸入 /auth login → 它會給你一個授權連結
點開連結，用你的 Claude 帳號登入並授權
把畫面上給你的代碼複製起來
回到 Slack，輸入 /auth code 貼上代碼

看到成功訊息之後，停掉它，打開「可以對話」的功能再啟動一次：

# 加進 ~/legatio.env
export LEGATIO_AGENT_FLAG_AGENT_RUNTIME_CLAUDE=true
export LEGATIO_AGENT_FLAG_AGENT_CHAT_MESSAGE=true
export LEGATIO_AGENT_FLAG_AGENT_CHAT_STREAM=true
export LEGATIO_AGENT_FLAG_AGENT_CHAT_REACTION=true

source ~/legatio.env && legatio-agent run

Windows 就是把同樣四行加進 legatio.ps1（$env:… = "true" 的寫法），再 . $env:USERPROFILE\legatio.ps1 重新載入並啟動。

回到 Slack 對它說句話。它會回你了。

用 /auth 而不是把金鑰貼在設定檔裡

授權碼走的是 Slack 的指令通道，不會留在頻道的對話紀錄裡。憑證由它自己保管在這台機器上。

接下來可以做的事

讓它記得你們的事

你可以給它一份「這個角色是誰、知道什麼」的設定，它每次對話都會帶著這個身分，不用每次重新解釋背景。

讓它會做事，不只是回話

讀檔案、改檔案、執行指令是三個分開的開關，一層一層開。也可以一層都不開，讓它就只是一個很懂你們的問答對象。

要開「執行指令」之前先讀這段

開放執行指令，等於允許聊天室裡的一句話變成這台機器上執行的命令 —— 用的是這台機器的身分、憑證與網路存取權。

所以這一項必須在隔離環境裡跑，doctor 偵測到不符合就會直接拒絕放行。要走到這一步，請先跟我們聯絡，我們會協助你們設定。

讓對話接得下去

打開 LEGATIO_AGENT_FLAG_AGENT_SESSION_PERSIST=true，重新啟動之後對話還能接著講。不打開的話每次啟動都是全新開始 —— 這是你的選擇。

遇到問題

先跑這兩個指令，多數問題會直接顯示在裡面：

legatio-agent doctor    # 這台機器缺什麼
legatio-agent flags     # 它現在被允許做什麼

要回報問題時，這個指令會印出一份不含任何密碼與金鑰的設定摘要，可以安全地貼給我們：

legatio-agent config

1 · 下載 legatio-agent​

2 · 在 Slack 建立 app​

3 · 取得兩把 token​

4 · 設定並啟動​

5 · 在 Slack 測一下​

6 · 登入 AI，讓它開始工作​

接下來可以做的事​

讓它記得你們的事​

讓它會做事，不只是回話​

讓對話接得下去​

遇到問題​