jeremylongshore/claude-code-slack-channel

# claude-code-slack-channel v0.7.0 双向 Slack ↔ Claude Code 桥接。在 Slack 私信和频道中与 Claude 聊天，就像在终端中聊天一样。每个线程会话隔离，带有可选每频道 Slack 投影的哈希链防篡改审计日志，策略门控工具，五层提示注入防御。 [](https://github.com/jeremylongshore/claude-code-slack-channel/actions/workflows/ci.yml) [](LICENSE) [](https://scorecard.dev/viewer/?uri=github.com/jeremylongshore/claude-code-slack-channel) **链接：** [Gist One-Pager](https://gist.github.com/jeremylongshore/2bef9c630d4269d2858a666ae75fca53) · [GitHub Pages](https://jeremylongshore.github.io/claude-code-slack-channel/) · [Release Notes](https://github.com/jeremylongshore/claude-code-slack-channel/releases/tag/v0.7.0) ## 工作原理 ``` Slack workspace (cloud) ↕ WebSocket (Socket Mode — outbound only, no public URL) server.ts (local MCP server, spawned by Claude Code) ↕ stdio (MCP transport) Claude Code session ``` Socket 模式意味着 **无需公开 URL** —— 可以在防火墙后、NAT 环境下任何位置使用。 ## 快速开始 ### 1. 创建 Slack 应用 1. 访问 [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → From scratch 2. **Socket Mode**：Settings → Socket Mode → 启用 → 生成应用级令牌 (`xapp-...`)，并赋予 `connections:write` 权限 3. **Event Subscriptions**：启用 → 订阅机器人事件： - `message.im` — 私信 - `message.channels` — 公开频道 - `message.groups` — 私有频道 - `app_mention` — @提及 4. **Bot Token Scopes**（OAuth 与权限）： - `chat:write` — 发送消息 - `channels:history` — 读取公开频道 - `groups:history` — 读取私有频道 - `im:history` — 读取私信 - `reactions:write` — 添加表情反应 - `files:read` — 下载共享文件 - `files:write` — 上传文件 - `users:read` — 解析显示名称 5. **Install to Workspace** → 复制机器人令牌 (`xoxb-...`) ### 2. 配置令牌 ``` /slack-channel:configure xoxb-your-bot-token xapp-your-app-token ``` ### 3. 运行 选择运行时： #### 选项 A：Bun（推荐） ``` bun install # 当前（claude-code-plugins 市场）： claude --channels plugin:slack-channel@claude-code-plugins # 未来（上游批准后）： # claude --channels plugin:slack-channel@claude-plugins-official ``` #### 选项 B：Node.js / npx ``` npm install # 在 .mcp.json 中，将命令更改为："npx"，参数：["tsx", "server.ts"] claude --channels plugin:slack-channel@claude-code-plugins ``` #### 选项 C：Docker ``` docker build -t claude-slack-channel . # 在 .mcp.json 中，将命令更改为："docker"，参数：["run", "--rm", "-i", "-v", "~/.claude/channels/slack:/state", "claude-slack-channel"] claude --channels plugin:slack-channel@claude-code-plugins ``` ### 4. 配对账户 1. 在 Slack 中私信机器人 —— 你会收到一个 6 位配对码 2. 在终端中运行：`/slack-channel:access pair ` 3. 已连接。可以开始聊天了。 ## 策略引擎（v0.6.0+） 在 `access.json.policy` 中编写规则，以自动化 Claude Code 工具调用的权限决策。三种规则效果，按首次匹配顺序执行： ``` { "policy": [ { "id": "safe-reads-in-ops", "effect": "auto_approve", "match": { "tool": "Read", "channel": "C_OPS_DOCS" } }, { "id": "no-shell", "effect": "deny", "match": { "tool": "Bash" }, "reason": "Shell execution is not permitted." }, { "id": "dangerous-writes", "effect": "require_approval", "match": { "tool": "Write", "channel": "C_DEPLOY" }, "approvers": 2, "ttlMs": 300000 } ] } ``` - **`auto_approve`** — 跳过 Block Kit 提示；工具调用立即执行，并记录 `policy.allow` 事件。 - **`deny`** — 将原因回传到原始线程并拒绝调用。记录 `policy.deny`。 - **`require_approval`** — 路由到人工审批者。`approvers: 2` 需要两个 **不同** 的 Slack `user_id`（NIST 双人完整性；同一用户不能通过两次点击满足配额）。任何允许列表用户的拒绝都会立即拒绝请求，无论配额计数如何。 - 成功的审批会授予一个作用域为 `(规则, 频道, 线程)` 的 TTL 窗口，因此一系列相似调用不会重复提示。 - `access.json.policy` 中的解析错误在 **启动时致命** —— 策略是安全关键，不提供静默降级。缺少或空的 `policy` 是可以的（首次安装路径）。 完整模式参考：[`ACCESS.md`](ACCESS.md#policy-rules)。决策流程：[`000-docs/policy-evaluation-flow.md`](000-docs/policy-evaluation-flow.md)。发布范围与有意推迟的内容：[`000-docs/v0.6.0-release-plan.md`](000-docs/v0.6.0-release-plan.md)。 ## 访问控制 参见 [ACCESS.md](ACCESS.md) 获取完整模式。 ``` /slack-channel:access policy allowlist # Only pre-approved users /slack-channel:access add U12345678 # Add a user /slack-channel:access remove U12345678 # Remove a user /slack-channel:access channel C12345678 # Opt in a channel /slack-channel:access channel C12345678 --mention # Require @mention /slack-channel:access status # Show current config ``` ### 多代理协调 频道可以加入跨机器人消息传递，方法是在 `allowBotIds` 中列出受信任的机器人用户 ID。当多个 Claude Code 实例（或你运营的其他机器人）需要在共享频道中协调时非常有用 —— 例如，运维监控代理和工程代理在 `#incidents` 中。默认不进行跨机器人传递：每个机器人消息在入口处被丢弃。完整模式和安全性权衡请参见 [ACCESS.md](ACCESS.md)。 `access.json` 示例条目： ``` { "channels": { "C_INCIDENTS": { "requireMention": false, "allowFrom": ["U_OPS_BOT", "U_ENG_BOT", "U_HUMAN"], "allowBotIds": ["U_OPS_BOT", "U_ENG_BOT"] } } } ``` 来自本机器人的自回声始终被过滤，无论 `allowBotIds` 如何。对等机器人无法审批权限提示 —— 权限中继取决于顶层 `allowFrom`，而非频道策略。 ## 安全 - **发送者门控**：每条入站消息都会经过门控。未经过门控的消息在到达 Claude 前被静默丢弃。 - **出站门控**：回复仅能发送到已通过入站门控的频道。 - **文件外泄防护**：无法通过回复工具发送 `.env`、`access.json` 或其他状态文件。 - **提示注入防御**：系统指令明确指示 Claude 拒绝来自 Slack 消息的配对/访问请求。 - **机器人过滤**：`bot_id` 消息默认被丢弃。允许加入特定对等机器人的频道可通过 `allowBotIds` 配置；自回声通过 `bot_id` / `bot_profile.app_id` / `user` 三重检查进行过滤。 - **链接预解析禁用**：所有出站消息设置 `unfurl_links: false, unfurl_media: false`。 - **令牌安全**：`.env` 权限为 `chmod 0o600`，从不记录，永不出现在工具结果中。 - **静态模式**：设置 `SLACK_ACCESS_MODE=static` 以在启动时冻结访问（无运行时变更）。 ## 开发 ``` # 开发模式（绕过插件允许列表）： claude --dangerously-load-development-channels server:slack ``` ## 一页纸与系统分析 [完整项目一页纸及操作级系统分析](https://gist.github.com/jeremylongshore/2bef9c630d4269d2858a666ae75fca53) ## 贡献者 - [@jeremylongshore](https://github.com/jeremylongshore) — 作者、维护者 - [@maui-99](https://github.com/maui-99) — 安全加固评审（v0.3.0） - [@jinsung-kang](https://github.com/jinsung-kang) — 客户端断开时干净关闭（v0.3.1） - [@CaseyMargell](https://github.com/CaseyMargell) — 事件去重修复（v0.3.1）、通过 `allowBotIds` 的跨机器人传递（v0.4.0） ## 许可证 MIT