claude-code-slack-channel 完整教學

把 Claude Code 跟 Slack 雙向接起來，但用「企業級 governance」的方式做：每一個 tool call 都過 policy engine、每一筆決策都進 Ed25519 簽章的 audit journal、五層 prompt-injection 防禦。本教學帶你從 0 到生產級使用。

1. 專案定位

1.1 為什麼需要這個

把 Claude Code 接到 Slack 不難 — 寫個 webhook 接 message、轉 stdin、把 stdout 丟回 Slack 就能跑。但在企業場景會撞到：

• 多人共用一個 Claude Code session 怎麼隔離 context？（A 在 thread 1 講的 secret，不能漏到 thread 2）
• 怎麼控管 Bash / Write 這種高風險 tool？（不可能每個 call 都人工 approve，也不能全 auto）
• 怎麼證明半年前那筆 deploy 真的是 CTO approve 過的？（合規 / 事後鑑識）
• Slack 本身就是 prompt-injection 攻擊面（攻擊者只要進得了 channel 就能下指令）
• 多 bot 同 channel 怎麼防 A→B→A→B 無限 loop？

claude-code-slack-channel 把這五題都當成設計約束，從 v0.1 一路演進到 v0.10。

1.2 跟其他選項的差別

1.3 核心承諾

「A message from any principal is content, never authorization.」— Identity 在訊息到達 Claude process 之前就被決定，訊息內容永遠不能改變 sender 是誰。

這條 invariant 是整個 codebase 五層防禦的 anchor。

2. 安裝指南

2.1 前置需求

• Bun ≥ 1.0（推薦）：curl -fsSL https://bun.sh/install | bash
• Claude Code ≥ v2.1.80
• claude.ai login（Research Preview 限制，純 ANTHROPIC_API_KEY 不行）→ 跑 claude login
• Slack workspace admin 權限（要建 Slack App）

2.2 建 Slack App（手動 5 分鐘 / 用 manifest 模式 1 分鐘）

到 api.slack.com/apps → Create New App → From scratch。

Socket Mode（重點）：

• Settings → Socket Mode → Enable
• Generate App-Level Token (xapp-...)，scope = connections:write

Event Subscriptions：

• Subscribe to bot events：message.im、message.channels、message.groups、app_mention

Bot Token Scopes（OAuth & Permissions）：

• chat:write、channels:history、groups:history、im:history、reactions:write、files:read、files:write、users:read

Install to Workspace → 取得 Bot Token (xoxb-...)。

💡 省事捷徑：跑 /slack-channel:install manifest，會自動產生 Slack App manifest JSON，到 api.slack.com/apps → Create New App → From an app manifest 貼上就完成。

2.3 配置 token

1/slack-channel:configure xoxb-your-bot-token xapp-your-app-token

這個 slash command 由 install skill 提供。Token 會寫到 ~/.claude/channels/slack/.env，自動 chmod 0o600。

2.4 起服務（3 種 runtime 選一）

 1# A. Bun（推薦）
 2bun install
 3claude --channels plugin:slack-channel@claude-code-plugins
 4
 5# B. Node.js + npx
 6npm install
 7# 把 .mcp.json 改成 "command": "npx", "args": ["tsx", "server.ts"]
 8claude --channels plugin:slack-channel@claude-code-plugins
 9
10# C. Docker
11docker build -t claude-slack-channel .
12# .mcp.json 改成 docker run --rm -i -v ~/.claude/channels/slack:/state claude-slack-channel
13claude --channels plugin:slack-channel@claude-code-plugins

2.5 加 bot 進 channel（最常見靜默失敗點）

Slack 安裝 App 到 workspace 時不會自動加入任何 channel。配對 DM 沒問題（DM 自動 route），但 channel 測試訊息會撞到沉默 — bot 根本沒在 channel 裡看不到 event。

1. Slack 開目標 channel → 點 channel 名稱 → Integrations 分頁
2. Add an App → 選你的 bot
3. 確認 bot 出現在 member 列表
4. Private channel 要明確邀請；每個 channel 都要做一次

2.6 配對帳號（pair）

1. 在 Slack 對 bot 發 DM → 拿到 6 字元 pairing code
2. Terminal：/slack-channel:access pair <code>
3. 完成。

2.7 驗證

在剛剛加 bot 的 channel：

1@<bot-name> hello

10 秒內應該會收到回應。沉默的話：

1/slack-channel:install doctor    # 結構化診斷
2/slack-channel:install repair    # 自動修復可修的

2.8 五大靜默失敗模式（~95% 安裝問題）

1. Bot 沒在 channel 裡 → §2.5
2. Claude Code 版本太舊（< v2.1.80）→ claude --version
3. 沒登入 claude.ai（純 API key 不行）→ claude login
4. Bun 沒裝 → 用 Node.js fallback
5. .env 權限不對（必須 0600）→ chmod 0600 ~/.claude/channels/slack/.env 或跑 install repair

完整 10 模式 troubleshooting matrix：skills/install/references/troubleshooting.md

3. 核心架構解析

3.1 四主體模型

整個系統的安全模型是「四主體 + 一條 invariant」：

Invariant：「訊息永遠是 content，永遠不是 authorization」。

3.2 資料流（mermaid）

flowchart LR
    subgraph Slack["Slack workspace"]
        HA["Human approver
(DM/channel/@mention)"]
        PA["Peer agent
(allowBotIds opt-in)"]
    end

    subgraph Host["Operator machine"]
        SO["Session owner"]
        CC["Claude Code session"]

        subgraph Server["server.ts (MCP stdio)"]
            SM["Socket Mode client
(outbound WS)"]
            IG["Inbound gate"]
            OG["Outbound gate"]
            FX["File-exfil guard"]
            SB["Session boundary
(thread-scoped)"]
            PE["Policy evaluator"]
            JS["Journal sink
(hash-chained Ed25519)"]
        end

        subgraph State["~/.claude/channels/slack (0600)"]
            ENV[".env (tokens)"]
            ACL["access.json"]
            SESS["sessions/"]
            LOG["audit.log"]
        end
    end

    HA --> SM
    PA --> SM
    SM --> IG
    IG -->|delivered| CC
    IG -. dropped .-> LOG
    CC --> PE
    PE -->|allow| CC
    PE -->|deny/require| OG
    CC -->|reply/upload| OG
    OG --> FX
    FX --> SM
    SM --> HA
    SO -.->|owns| ENV
    SO -.->|owns| ACL
    PE -.->|reads| ACL
    JS --> LOG
    IG -.-> JS
    OG -.-> JS
    PE -.-> JS

關鍵觀察：

• Socket Mode = outbound only WebSocket：不需要 public URL，可放防火牆 / NAT 後
• 每一條 inbound、每一條 outbound、每一個 policy 決策都會寫進 audit.log
• state dir 整個 0600：別的 user 完全讀不到

3.3 五層 prompt-injection 防禦

flowchart TB
    M["Inbound message"] --> L1{"L1: Inbound gate
(allowFrom / allowBotIds
/ permission regex)"}
    L1 -->|drop| D1["silently dropped
+ journal"]
    L1 -->|pass| L2{"L2: System prompt
hardening
(refuse pairing/access)"}
    L2 --> CC["Claude process"]
    CC -->|tool call| L3{"L3: Policy evaluator
(tier-aware, strictest wins)"}
    L3 -->|deny| D2["context-stripped
{behavior: 'deny'}"]
    L3 -->|allow| CC2["execute tool"]
    L3 -->|require| HITL["Slack approval
(2-person quorum)"]
    HITL --> CC2
    CC2 -->|reply| L4{"L4: Outbound gate
(only delivered channels)"}
    L4 --> L5{"L5: File-exfil guard
(denylist .env / access.json /
SSH / GPG / SLACK_SENDABLE_ROOTS)"}
    L5 -->|pass| OUT["Slack reply"]
    L5 -->|block| D3["throw + journal"]

3.4 Session 邊界（thread-scoped）

• Session = 一個 Slack thread 的 context（不是 channel）
• 兩個 parallel thread 在同一個 channel 看不到彼此的 context
• Supervisor 是 Armstrong-style：5-state FSM Nonexistent → Activating → Active → Quiescing → Deactivating，加 Quarantined 終止狀態（save/load 失敗）
• Crash recovery = reload-from-disk，不在 memory 重建
• Idle reaper：default 4 小時無活動 + 無 in-flight tool call → 自動 quiesce → deactivate
• Thread isolation：outbound gate key 是 (channel, thread_ts)，permission-pairing relay key 是 (thread_ts, requestId) — 兩層獨立執行，一層失效另一層不會默默放行

4. 主要模組詳細用法

4.1 Policy Engine（policy.ts，v0.6.0+）

宣告式規則，三種 effect：

 1{
 2  "policy": [
 3    {
 4      "id": "safe-reads-in-ops",
 5      "effect": "auto_approve",
 6      "match": { "tool": "Read", "channel": "C_OPS_DOCS" }
 7    },
 8    {
 9      "id": "no-shell",
10      "effect": "deny",
11      "match": { "tool": "Bash" },
12      "reason": "Shell execution is not permitted."
13    },
14    {
15      "id": "dangerous-writes",
16      "effect": "require_approval",
17      "match": { "tool": "Write", "channel": "C_DEPLOY" },
18      "approvers": 2,
19      "ttlMs": 300000
20    }
21  ]
22}

• auto_approve — 跳過 Block Kit prompt，直接跑，journal 寫 policy.allow
• deny — reason 回到原 thread，call 被拒，journal 寫 policy.deny，回傳給 Claude 的結果被 context-strip 成 bare { behavior: 'deny' }（不告訴 Claude rule id / reason，避免 rephrase-and-retry）
• require_approval — 路由到人工 approve，approvers: 2 要兩個不同的 Slack user_id（NIST two-person integrity；同一人按兩次不算），任一個 allowlist user deny 就立刻拒絕（不管 quorum）

Tier：admin → user → workspace → default，最嚴勝出（高 tier deny 不能被低 tier auto_approve 覆蓋）。

Parse error fatal at boot — policy 是 safety-critical，不接受靜默降級。空的 policy 沒問題（first-install）。

4.2 Access Control（access.json）

1/slack-channel:access policy allowlist       # 只允許預核 user
2/slack-channel:access add U12345678
3/slack-channel:access remove U12345678
4/slack-channel:access channel C12345678              # opt in channel
5/slack-channel:access channel C12345678 --mention    # 要 @mention 才回
6/slack-channel:access status

4.3 Multi-agent（allowBotIds）

讓多 bot 在同 channel 協調（例：ops-monitor agent + engineering agent 在 #incidents）：

1{
2  "channels": {
3    "C_INCIDENTS": {
4      "requireMention": false,
5      "allowFrom": ["U_OPS_BOT", "U_ENG_BOT", "U_HUMAN"],
6      "allowBotIds": ["U_OPS_BOT", "U_ENG_BOT"]
7    }
8  }
9}

• Self-echo 永遠被過濾（不管 allowBotIds）— bot_id / bot_profile.app_id / user === botUserId triple-check
• Peer bot 不能 approve permission prompt（permission relay gate on top-level allowFrom，不是 channel policy）
• Peer-bot rate limit：per-(channel, bot_id) sliding window，default 10 msg/60s，斷 A→B→A 無限 loop
• Operator 可以 !mute <@bot> / !unmute <@bot> 暫停亂叫的 peer

完整 multi-agent recipe：000-docs/multi-agent-channels.md

4.4 Audit Journal（journal.ts）

每個 gate 決策、每個 policy 決策、每個 outbound 都寫進 ~/.claude/channels/slack/audit.log：

• Hash-chained（前一筆的 hash 是這筆的 input → tamper-evident）
• Ed25519-signed（v0.10+）over RFC 8785 JCS canonical form → 第三方拿 public key 可以離線驗證整條 chain，不用信任 host

1# 端到端驗證
2bun server.ts --verify-audit-log ~/.claude/channels/slack/audit.log
3
4# Operator key 生命週期
5bun audit-key-cli.ts init       # 產 keypair、encrypt private 寫進 .env、印 public key
6bun audit-key-cli.ts rotate     # 換新 keypair、重簽 chain head、歸檔舊 public key
7bun audit-key-cli.ts verify     # 用 active + archived public key 驗 log
8bun audit-key-cli.ts show       # 印 active public key + key id

Key 從 SOPS+age 加密的 .env boot 時載入。要關簽章用 --no-audit-signing（只剩 hash chain）。

Redactor：journal 寫入前會 mask 已知 token shape（xoxb-*、xoxp-*、xapp-*、GitHub PAT 等）→ 即使 caller 不小心把 token 塞進 event 也不會落地。

4.5 Admin Commands（v0.10）

Operator verb（!clear / !restart etc.）走完整路徑：gate → policy → journal → execute，要 HMAC nonce + 另一條 channel 的第二人確認（解 EchoLeak / CVE-2025-32711 / threat T11）。Claude 自己無法呼叫 — 沒有 MCP tool name 開頭是 admin.。

關鍵：攻擊者注入 prompt 進 channel A 不能驅動 admin action，因為確認必須來自他控制不到的 channel B。

5. 應用場景

5.1 Deploy 審批（典型）

• #deploy channel + allowFrom: [CTO, lead-eng, lead-eng-2]
• Policy：Write / Bash 在 #deploy 都 require_approval，approvers: 2，ttlMs: 300000（5 分鐘 TTL）
• Claude 想跑 terraform apply → Slack 跳 Block Kit prompt → 兩個不同 lead 按 approve → 跑完
• 全程進 audit.log，事後可離線驗

5.2 Incident response 多 agent

• #incidents channel + allowBotIds: [pagerduty-bot, ops-monitor]
• PagerDuty 推 alert（peer bot）→ Claude 分析 → require_approval 跑 kubectl rollout undo
• Ops-monitor 監看 metrics（另一個 Claude session）
• 兩個 agent 在同 channel 協作，靠 mention addressing；rate limit 防 loop

5.3 Pair programming + 行動裝置 approval

• Session owner 桌機跑 Claude，但臨時離開 → 手機收 Slack 看到 require_approval prompt → 手機按 approve
• 適合需要長時間 supervised execution 的任務

5.4 合規 / 鑑識

• 半年後稽核員問「2026-03-15 那筆 production schema migration 誰 approve 的？」
• bun server.ts --verify-audit-log ... 跑出簽章驗證通過 + 兩個 approver Slack user_id + 時間戳
• 信任根：published public key

6. 資安掃描報告

掃描日期：2026-06-01；commit 023cab3；範圍：所有 *.ts + state-handling 邏輯

6.1 整體評估：🟢 低風險（其實是這類專案的標竿）

這是少數安全設計就是賣點的開源 repo。掃下來不只沒紅旗，反而是值得參考的範本。

6.2 Token / Secret 處理 🟢

6.3 Slack 認證 / 訊息流 🟢

6.4 Prompt-injection 防禦 🟢（行業標竿）

5 層 defense-in-depth + 1 條核心 invariant（訊息 = content ≠ authorization）。10 個 named threat T1–T11 + 6 個 code invariant 都有對應實作（000-docs/THREAT-MODEL.md）。

特別亮眼：

• Context-stripped deny：拒絕的 tool call 回給 Claude 的只有 { behavior: 'deny' }，不洩 rule id / reason → 阻斷 rephrase-and-retry loop
• Admin command cross-channel HITL：HMAC nonce 必須從第二條 channel 確認 → 解 CVE-2025-32711 echo-leak 等級威脅
• Policy isolation invariant：policy.ts / admin.ts 編譯期禁止 import manifest.ts（advertisements ≠ grants）

6.5 File exfiltration / Path traversal 🟢

6.6 child_process 使用 🟡 → 🟢

execFile 用於 admin.ts（tmux send-keys）+ audit-key-loader.ts（SOPS / age）。觀察：

• 全用 execFile（不是 exec / shell=true） → 無 shell injection
• admin.ts:424 強制 SLACK_TMUX_SESSION 不可空，空就拋錯（不會 default 到 user 的 session）
• ✅ 安全

6.7 依賴供應鏈 🟢

• 主要依賴 4 個都釘版（@modelcontextprotocol/sdk 1.29.0 / @slack/web-api 7.15.2 / @slack/socket-mode 2.0.6 / zod 3.25.76）
• bun audit --audit-level=high 是 CI required gate
• bun.lock 入庫
• CodeQL + gitleaks + Scorecard out-of-band
• axios / fast-uri 用 overrides 強制升級

6.8 殘留風險（README 明確列出）

• R1：Same-UID host compromise — 任何用 session owner 帳號跑的 process 都有同等權限（這是 OS 層問題，非本專案可解）
• 上游 SDK supply chain（4 個釘版 + lockfile 是 mitigation）
• Slack 平台漏洞（責任在 Slack）

6.9 給使用者的建議

1. .env 權限：第一次跑後 ls -la ~/.claude/channels/slack/.env 確認是 -rw-------
2. Audit key init：第一天就跑 bun audit-key-cli.ts init，把 public key 存在外部（git repo / 1Password）
3. Policy 從嚴開始：先 deny Bash / Write，再逐條 auto_approve 放行（一段時間後看 journal 統計）
4. Multi-bot 慎用 allowBotIds：每個 peer 都是新攻擊面，opt-in 要明確 review
5. Rotate audit key 季度節奏：bun audit-key-cli.ts rotate，舊 public key 自動歸檔仍可驗舊 log
6. 不要把 state dir 放共用 NFS：違反 same-UID 隔離前提

7. FAQ

Q1：必須要 Bun 嗎？Node.js 不行？ A：Node.js + npx tsx 可以（Option B），Docker 也可以（Option C）。但 Bun 是 maintainer 主推、CI 也是用 Bun 跑。

Q2：可以接到自架的 Slack-alike（Mattermost / Rocket.Chat）嗎？ A：本專案綁 Slack Socket Mode + Slack SDK，要換要重寫 transport 層。但架構（4 主體 / 5 層防禦 / policy engine / audit）值得參考。

Q3：為什麼不用 webhook 而用 Socket Mode？ A：Webhook 需要 public URL → NAT / firewall 後面要打洞、要 TLS 證書、要 IP allowlist → 攻擊面增加。Socket Mode = outbound WebSocket，從自家機器主動連，企業環境友善。

Q4：Audit log 會不會爆？ A：每筆事件 ~200-500 bytes，重 ops 場景一天 ~10MB 規模。Hash chain 不能 truncate（會破壞驗證），但可以 rotate（舊 log 歸檔、用 chain-head signature 證明完整性）。

Q5：Multi-approver 一定要 2 人嗎？ A：approvers 是 int，1 / 2 / 3+ 都可以。但本專案明確指出同一 user 按兩次不算（Epic 29-B / Issue 97），quorum 是 distinct Slack user_id 數量。

Q6：Claude session crash 了 context 會丟嗎？ A：不會。Session 寫到 ~/.claude/channels/slack/sessions/<channel>/<thread>.json，atomic write。Crash 後 reload 來源是磁碟，不是 memory。

Q7：policy.ts 有什麼測試？ A：986 tests / 6017 assertions（全 codebase），含 unit + property-based（fast-check）+ Gherkin acceptance。Mutation testing 用 Stryker，policy.ts 最新 mutation kill 率 89.78%。

Q8：可以給 Claude tool 嗎，例如自定義 MCP？ A：可以。本專案是 MCP server，會被 Claude Code 同時 load 進來；Claude 看得到本專案 expose 的 reply / upload_file / publish_manifest 等 tool。

8. 進階技巧

8.1 用 --verify-audit-log 做 CI 完整性檢查

每天定時跑：

1bun server.ts --verify-audit-log /backup/audit.log.$(date +%F)

驗證失敗 → 立刻警報（hash chain 斷 / 簽章不對 → 有人動過 log）。

8.2 用 static mode 凍結 access

1SLACK_ACCESS_MODE=static bun server.ts

Runtime 完全不能改 access.json。適合：生產環境 / 合規場景 / Demo。

8.3 用 mute store 做 fast cutoff

某個 peer bot 開始亂叫：

1!mute @ops-bot 30m

30 分鐘內 ops-bot 訊息全部進 mute store（journal peer.muted event），完全不到 Claude。事後解封：!unmute @ops-bot。

8.4 用 Gherkin 寫自己的 policy 驗收測試

features/policy_evaluation.feature 是 maintainer 的 acceptance suite，你可以複製格式寫自家 policy 的 Gherkin：

1Scenario: Bash in production must require 2 approvers
2  Given access.json policy includes deny rule for Bash in C_PROD
3  When Claude attempts to call Bash with command "rm -rf /tmp/cache"
4  Then the decision is "deny"
5  And the journal records "policy.deny" with rule id

跑 bun test features/runner.test.ts 驗。

8.5 整合 SOPS+age 做 audit key 自動發配

audit-key-cli.ts init 把 private key encrypt 到 .env。如果你已經有 SOPS / age workflow，加 .sops.yaml rule + direnv hook 就能團隊共享解密 → 多人都能驗 log，但 host 上 process 才能簽 log。

9. 整合進其他工作流

9.1 跟 GitHub Actions 整合

CI 跑完 → 走 webhook 進 #ci-bot → Claude（接這個 channel）→ 看到 fail → 跑 git bisect 找出問題 commit → 在 thread 回報。

整段過程審計：哪個 user/agent push 的 commit / 哪次 CI run / Claude 怎麼 bisect / 最後結論。

9.2 跟 PagerDuty 整合

PagerDuty 設 Slack incident channel → 本專案接 allowBotIds: [pd-bot] → alert 進來 Claude 自動分類 / 篩 noise → 重要的才標記 escalation。

9.3 跟內部 secret manager 整合

audit-key-loader.ts 支援自訂 loader path。寫一個 wrapper 從 Vault / AWS Secrets Manager 拉 key，不要存進 .env。

9.4 跟現有 ChatOps 工具串接

policy-dispatch.ts 是 side-effect-free dispatcher。可以注入自家的 RBAC 層 / approval workflow（例：require_approval 改路由到 PagerDuty incident commander，而不是 Slack Block Kit）。

10. Checklist：開始用之前

• Bun ≥ 1.0 / Claude Code ≥ v2.1.80 / claude login 已完成
• Slack App 建好，Socket Mode enabled，4 個 event subscribed，8 個 bot scope 設妥
• Bot token + App token 透過 /slack-channel:configure 配置完成
• .env 權限是 0600
• Bot 已加進每個要用的 channel（DM 不用，channel 要）
• /slack-channel:access pair <code> 完成配對
• @bot hello 驗證有回應
• bun audit-key-cli.ts init 跑過，public key 異地備份
• access.json.policy 先 deny 高風險 tool（Bash / Write）
• Audit log 路徑（SLACK_AUDIT_LOG）規劃好 rotate / backup
• 如果有 peer bot：allowBotIds 明確 review、bot_id 三重驗證 + rate limit + mute 都讀過
• THREAT-MODEL.md T1–T11 全讀過、SECURITY.md 殘留風險都接受
• CI 接 --verify-audit-log 每日驗證

11. 進一步閱讀

• README：README.md
• Architecture（4 主體 + 元件圖）：ARCHITECTURE.md
• Threat Model T1–T11：000-docs/THREAT-MODEL.md
• Security Policy：SECURITY.md
• Audit Journal Architecture：000-docs/audit-journal-architecture.md
• Policy Evaluation Flow：000-docs/policy-evaluation-flow.md
• Multi-Agent Channels：000-docs/multi-agent-channels.md
• Key Management：000-docs/key-management.md
• Mutation Report：000-docs/MUTATION_REPORT.md
• Install Skill（doctor / repair / verify / manifest）：skills/install/SKILL.md
• One-Pager Gist：https://gist.github.com/jeremylongshore/2bef9c630d4269d2858a666ae75fca53

教學文件生成於 2026-06-01，對應 repo commit 023cab3 (v0.10.0 release branch)。