diff --git a/docs/zh-CN/channels/broadcast-groups.md b/docs/zh-CN/channels/broadcast-groups.md index 12bb69a9f..744af3f9e 100644 --- a/docs/zh-CN/channels/broadcast-groups.md +++ b/docs/zh-CN/channels/broadcast-groups.md @@ -7,25 +7,25 @@ status: experimental summary: 向多个智能体广播一条 WhatsApp 消息 title: 广播组 x-i18n: - generated_at: "2026-04-28T11:44:56Z" + generated_at: "2026-05-03T22:49:29Z" model: gpt-5.5 provider: openai - source_hash: b0de4ccc85bf79e2ceb1dddd60db067309b15b7f876c92e7d591ff0b4b4315ec + source_hash: eab43d3c3ffddb360340469433d74a380fbab98e662b2463a54f62eafc375b55 source_path: channels/broadcast-groups.md workflow: 16 --- -**Status：** 实验性。已在 2026.1.9 中添加。 +**Status:** 实验性。已在 2026.1.9 中添加。 ## 概览 -广播组允许多个智能体同时处理并响应同一条消息。这让你可以创建专门的智能体团队，在单个 WhatsApp 群组或私信中协同工作，并且全部使用同一个电话号码。 +Broadcast Groups 允许多个智能体同时处理并回复同一条消息。这样你可以创建专门的智能体团队，让它们在同一个 WhatsApp 群组或私信中协作，且全部使用同一个电话号码。 当前范围：**仅 WhatsApp**（Web 渠道）。 -广播组会在渠道 allowlist 和群组激活规则之后评估。在 WhatsApp 群组中，这意味着广播会在 OpenClaw 通常会回复时发生（例如：被提及时，取决于你的群组设置）。 +Broadcast groups 会在渠道允许列表和群组激活规则之后评估。在 WhatsApp 群组中，这意味着当 OpenClaw 通常会回复时（例如：被提及时，取决于你的群组设置），就会进行广播。 ## 使用场景 @@ -42,7 +42,7 @@ x-i18n: - TestGenerator (suggests test cases) ``` - 每个智能体都会处理同一条消息，并提供其专门视角。 + 每个智能体都会处理同一条消息，并提供自己的专业视角。 @@ -77,9 +77,9 @@ x-i18n: ### 基本设置 -添加一个顶层 `broadcast` 区段（与 `bindings` 同级）。键是 WhatsApp peer id： +添加一个顶层 `broadcast` 部分（与 `bindings` 同级）。键是 WhatsApp 对端 ID： -- 群聊：群组 JID（例如 `120363403215116621@g.us`） +- 群组聊天：群组 JID（例如 `120363403215116621@g.us`） - 私信：E.164 电话号码（例如 `+15551234567`） ```json @@ -169,12 +169,12 @@ x-i18n: 收到一条 WhatsApp 群组或私信消息。 - 系统检查 peer ID 是否在 `broadcast` 中。 + 系统检查对端 ID 是否在 `broadcast` 中。 - 所有列出的智能体都会处理该消息。 - 每个智能体都有自己的会话键和隔离上下文。 - - 智能体会并行（默认）或按顺序处理。 + - 智能体并行（默认）或顺序处理。 @@ -183,26 +183,26 @@ x-i18n: -广播组不会绕过渠道 allowlist 或群组激活规则（提及/命令等）。它们只会在消息符合处理条件时更改_哪些智能体会运行_。 +Broadcast groups 不会绕过渠道允许列表或群组激活规则（提及/命令等）。它们只会在消息符合处理条件时改变_运行哪些智能体_。 ### 会话隔离 -广播组中的每个智能体都会维护完全独立的： +Broadcast group 中的每个智能体都会维护完全独立的： - **会话键**（`agent:alfred:whatsapp:group:120363...` 与 `agent:baerbel:whatsapp:group:120363...`） - **对话历史**（智能体看不到其他智能体的消息） - **工作区**（如果已配置，则使用独立沙箱） - **工具访问权限**（不同的允许/拒绝列表） -- **内存/上下文**（独立的 IDENTITY.md、SOUL.md 等） -- **群组上下文缓冲区**（用于上下文的最近群组消息）按 peer 共享，因此所有广播智能体在触发时都会看到相同上下文 +- **记忆/上下文**（独立的 IDENTITY.md、SOUL.md 等） +- **群组上下文缓冲区**（用于上下文的近期群组消息）按对端共享，因此所有广播智能体被触发时都会看到相同上下文 这让每个智能体可以拥有： -- 不同个性 -- 不同工具访问权限（例如只读与读写） -- 不同模型（例如 opus 与 sonnet） -- 安装不同 Skills +- 不同的性格 +- 不同的工具访问权限（例如，只读与读写） +- 不同的模型（例如，opus 与 sonnet） +- 安装不同的 Skills ### 示例：隔离会话 @@ -230,8 +230,8 @@ x-i18n: ## 最佳实践 - - 为每个智能体设计单一且明确的职责： + + 为每个智能体设计单一且清晰的职责： ```json { @@ -241,11 +241,11 @@ x-i18n: } ``` - ✅ **好：** 每个智能体只有一项工作。❌ **差：** 一个通用的 "dev-helper" 智能体。 + ✅ **好：** 每个智能体只有一项工作。❌ **不好：** 一个通用的 “dev-helper” 智能体。 - 明确说明每个智能体的作用： + 清楚说明每个智能体的作用： ```json { @@ -259,28 +259,30 @@ x-i18n: - 只为智能体授予它们需要的工具： + 只给智能体提供它们需要的工具： ```json { "agents": { "reviewer": { - "tools": { "allow": ["read", "exec"] } // Read-only + "tools": { "allow": ["read", "exec"] } }, "fixer": { - "tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write + "tools": { "allow": ["read", "write", "edit", "exec"] } } } } ``` + `reviewer` 是只读的。`fixer` 可以读取和写入。 + - 使用许多智能体时，请考虑： + 当有很多智能体时，请考虑： - - 使用 `"strategy": "parallel"`（默认）以提高速度 - - 将广播组限制为 5-10 个智能体 - - 为较简单的智能体使用更快的模型 + - 使用 `"strategy": "parallel"`（默认）以提升速度 + - 将 broadcast groups 限制为 5-10 个智能体 + - 为更简单的智能体使用更快的模型 @@ -298,7 +300,7 @@ x-i18n: ### 提供商 -广播组当前可用于： +Broadcast groups 目前适用于： - ✅ WhatsApp（已实现） - 🚧 Telegram（计划中） @@ -307,7 +309,7 @@ x-i18n: ### 路由 -广播组可与现有路由一起工作： +Broadcast groups 可与现有路由配合使用： ```json { @@ -323,8 +325,8 @@ x-i18n: } ``` -- `GROUP_A`：只有 alfred 响应（正常路由）。 -- `GROUP_B`：agent1 和 agent2 响应（广播）。 +- `GROUP_A`：只有 alfred 回复（正常路由）。 +- `GROUP_B`：agent1 和 agent2 都会回复（广播）。 **优先级：** `broadcast` 优先于 `bindings`。 @@ -333,11 +335,11 @@ x-i18n: ## 故障排除 - + **检查：** 1. 智能体 ID 存在于 `agents.list` 中。 - 2. Peer ID 格式正确（例如 `120363403215116621@g.us`）。 + 2. 对端 ID 格式正确（例如 `120363403215116621@g.us`）。 3. 智能体不在拒绝列表中。 **调试：** @@ -347,17 +349,17 @@ x-i18n: ``` - - **原因：** Peer ID 可能在 `bindings` 中，但不在 `broadcast` 中。 + + **原因：** 对端 ID 可能在 `bindings` 中，但不在 `broadcast` 中。 - **修复：** 添加到广播配置，或从绑定中移除。 + **修复：** 添加到 broadcast 配置，或从 bindings 中移除。 - 如果许多智能体导致速度变慢： + 如果多个智能体导致速度变慢： - 减少每个群组的智能体数量。 - - 使用更轻量的模型（sonnet 而不是 opus）。 + - 使用更轻量的模型（使用 sonnet 而不是 opus）。 - 检查沙箱启动时间。 @@ -403,12 +405,12 @@ x-i18n: **用户发送：** 代码片段。 - **响应：** + **回复：** - - code-formatter：“Fixed indentation and added type hints” - - security-scanner：“⚠️ SQL injection vulnerability in line 12” - - test-coverage：“Coverage is 45%, missing tests for error cases” - - docs-checker：“Missing docstring for function `process_data`” + - code-formatter：“已修复缩进并添加类型提示” + - security-scanner：“⚠️ 第 12 行存在 SQL 注入漏洞” + - test-coverage：“覆盖率为 45%，缺少错误情况测试” + - docs-checker：“函数 `process_data` 缺少文档字符串” @@ -432,7 +434,7 @@ x-i18n: ## API 参考 -### 配置架构 +### 配置模式 ```typescript interface OpenClawConfig { @@ -449,24 +451,24 @@ interface OpenClawConfig { 如何处理智能体。`parallel` 会同时运行所有智能体；`sequential` 会按数组顺序运行它们。 - WhatsApp 群组 JID、E.164 号码或其他 peer ID。值是应处理消息的智能体 ID 数组。 + WhatsApp 群组 JID、E.164 号码或其他对端 ID。值是应处理消息的智能体 ID 数组。 ## 限制 -1. **最大智能体数：** 没有硬性限制，但 10 个以上智能体可能较慢。 -2. **共享上下文：** 智能体看不到彼此的响应（有意设计）。 -3. **消息顺序：** 并行响应可能以任意顺序到达。 +1. **最大智能体数：** 没有硬性限制，但 10 个以上智能体可能会变慢。 +2. **共享上下文：** 智能体看不到彼此的回复（设计如此）。 +3. **消息顺序：** 并行回复可能以任意顺序到达。 4. **速率限制：** 所有智能体都会计入 WhatsApp 速率限制。 ## 未来增强 计划功能： -- [ ] 共享上下文模式（智能体会看到彼此的响应） -- [ ] 智能体协调（智能体可以互相发送信号） +- [ ] 共享上下文模式（智能体看到彼此的回复） +- [ ] 智能体协调（智能体可以互相发信号） - [ ] 动态智能体选择（根据消息内容选择智能体） -- [ ] 智能体优先级（部分智能体先于其他智能体响应） +- [ ] 智能体优先级（某些智能体先于其他智能体回复） ## 相关 diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index 374992f26..74a6eaf3a 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -1,18 +1,18 @@ --- read_when: - 设置 Slack 或调试 Slack 套接字/HTTP 模式 -summary: Slack 设置和运行时行为（Socket 模式 + HTTP 请求 URL） +summary: Slack 设置和运行时行为（Socket Mode + HTTP 请求 URL） title: Slack x-i18n: - generated_at: "2026-05-03T17:32:42Z" + generated_at: "2026-05-03T22:49:25Z" model: gpt-5.5 provider: openai - source_hash: d902fbbad23cee9b3f0ab7d240845b7b229e2d2507c5ea1d1a0fa3baa915d80a + source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b source_path: channels/slack.md workflow: 16 --- -已可通过 Slack 应用集成用于私信和渠道的生产环境。默认模式是 Socket Mode；也支持 HTTP Request URLs。 +可通过 Slack 应用集成在私信和频道中用于生产环境。默认模式是 Socket Mode；也支持 HTTP Request URLs。 @@ -21,8 +21,8 @@ x-i18n: 原生命令行为和命令目录。 - - 跨渠道诊断和修复手册。 + + 跨频道诊断和修复手册。 @@ -32,12 +32,12 @@ x-i18n: - 在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮： + 在 Slack 应用设置中按下 **[创建新应用](https://api.slack.com/apps/new)** 按钮： - 选择 **from a manifest**，并为你的应用选择一个工作区 - 粘贴下面的[示例清单](#manifest-and-scope-checklist)，然后继续创建 - 生成带有 `connections:write` 的 **App-Level Token**（`xapp-...`） - - 安装应用并复制显示的 **Bot Token**（`xoxb-...`） + - 安装应用，并复制显示的 **Bot Token**（`xoxb-...`） @@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run openclaw config patch --file ./slack.socket.patch.json5 ``` - 环境变量回退（仅默认账号）： + Env 回退方式（仅默认账号）： ```bash SLACK_APP_TOKEN=xapp-... @@ -87,12 +87,12 @@ openclaw gateway - 在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮： + 在 Slack 应用设置中按下 **[创建新应用](https://api.slack.com/apps/new)** 按钮： - 选择 **from a manifest**，并为你的应用选择一个工作区 - 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL - 保存用于请求验证的 **Signing Secret** - - 安装应用并复制显示的 **Bot Token**（`xoxb-...`） + - 安装应用，并复制显示的 **Bot Token**（`xoxb-...`） @@ -123,7 +123,7 @@ openclaw config patch --file ./slack.http.patch.json5 为多账号 HTTP 使用唯一的 webhook 路径 - 给每个账号分配不同的 `webhookPath`（默认 `/slack/events`），避免注册发生冲突。 + 给每个账号分配不同的 `webhookPath`（默认 `/slack/events`），避免注册冲突。 @@ -142,7 +142,7 @@ openclaw gateway ## Socket Mode 传输调优 -对于 Socket Mode，OpenClaw 默认将 Slack SDK 客户端 pong 超时设置为 15 秒。仅当你需要针对工作区或主机进行特定调优时，才覆盖传输设置： +默认情况下，OpenClaw 会将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 秒。仅当你需要针对工作区或主机进行特定调优时，才覆盖传输设置： ```json5 { @@ -159,11 +159,11 @@ openclaw gateway } ``` -仅在记录 Slack websocket pong/server-ping 超时，或运行在已知存在事件循环饥饿问题主机上的 Socket Mode 工作区中使用此设置。`clientPingTimeout` 是 SDK 发送客户端 ping 后等待 pong 的时间；`serverPingTimeout` 是等待 Slack 服务器 ping 的时间。应用消息和事件仍属于应用状态，而不是传输活性信号。 +仅对记录 Slack websocket pong/server-ping 超时，或运行在已知存在事件循环饥饿的主机上的 Socket Mode 工作区使用此项。`clientPingTimeout` 是 SDK 发送客户端 ping 后等待 pong 的时间；`serverPingTimeout` 是等待 Slack 服务器 ping 的时间。应用消息和事件仍是应用状态，不是传输活跃性信号。 -## 清单和 scope 检查清单 +## 清单和权限范围检查清单 -基础 Slack 应用清单对于 Socket Mode 和 HTTP Request URLs 相同。只有 `settings` 块（以及斜杠命令 `url`）不同。 +基础 Slack 应用清单对 Socket Mode 和 HTTP Request URLs 相同。只有 `settings` 块（以及斜杠命令的 `url`）不同。 基础清单（Socket Mode 默认）： @@ -240,7 +240,7 @@ openclaw gateway } ``` -对于 **HTTP Request URLs 模式**，将 `settings` 替换为 HTTP 变体，并向每个斜杠命令添加 `url`。需要公共 URL： +对于 **HTTP Request URLs 模式**，将 `settings` 替换为 HTTP 变体，并为每个斜杠命令添加 `url`。需要公开 URL： ```json { @@ -258,7 +258,19 @@ openclaw gateway "event_subscriptions": { "request_url": "https://gateway-host.example.com/slack/events", "bot_events": [ - /* same as Socket Mode */ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" ] }, "interactivity": { @@ -272,174 +284,179 @@ openclaw gateway ### 其他清单设置 -公开扩展上述默认值的不同功能。 +展示扩展上述默认设置的不同功能。 -默认清单启用 Slack App Home 的 **Home** 标签页，并订阅 `app_home_opened`。当工作区成员打开 Home 标签页时，OpenClaw 会通过 `views.publish` 发布一个安全的默认 Home 视图；其中不包含会话负载或私有配置。**Messages** 标签页仍为 Slack 私信启用。 +默认清单会启用 Slack App Home **Home** 标签，并订阅 `app_home_opened`。当工作区成员打开 Home 标签时，OpenClaw 会使用 `views.publish` 发布安全的默认 Home 视图；不会包含会话负载或私有配置。**Messages** 标签仍会为 Slack 私信启用。 - 可以使用多个[原生斜杠命令](#commands-and-slash-behavior)来替代单个已配置命令，并保留细微差异： + 可以使用多个[原生斜杠命令](#commands-and-slash-behavior)来替代单个已配置命令，但需注意： - 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已被保留。 - 一次最多只能提供 25 个斜杠命令。 - 将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)的子集： + 将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)的一个子集： ```json - "slash_commands": [ - { - "command": "/new", - "description": "Start a new session", - "usage_hint": "[model]" - }, - { - "command": "/reset", - "description": "Reset the current session" - }, - { - "command": "/compact", - "description": "Compact the session context", - "usage_hint": "[instructions]" - }, - { - "command": "/stop", - "description": "Stop the current run" - }, - { - "command": "/session", - "description": "Manage thread-binding expiry", - "usage_hint": "idle or max-age " - }, - { - "command": "/think", - "description": "Set the thinking level", - "usage_hint": "" - }, - { - "command": "/verbose", - "description": "Toggle verbose output", - "usage_hint": "on|off|full" - }, - { - "command": "/fast", - "description": "Show or set fast mode", - "usage_hint": "[status|on|off]" - }, - { - "command": "/reasoning", - "description": "Toggle reasoning visibility", - "usage_hint": "[on|off|stream]" - }, - { - "command": "/elevated", - "description": "Toggle elevated mode", - "usage_hint": "[on|off|ask|full]" - }, - { - "command": "/exec", - "description": "Show or set exec defaults", - "usage_hint": "host= security= ask= node=" - }, - { - "command": "/model", - "description": "Show or set the model", - "usage_hint": "[name|#|status]" - }, - { - "command": "/models", - "description": "List providers/models", - "usage_hint": "[provider] [page] [limit=|size=|all]" - }, - { - "command": "/help", - "description": "Show the short help summary" - }, - { - "command": "/commands", - "description": "Show the generated command catalog" - }, - { - "command": "/tools", - "description": "Show what the current agent can use right now", - "usage_hint": "[compact|verbose]" - }, - { - "command": "/agentstatus", - "description": "Show runtime status, including provider usage/quota when available" - }, - { - "command": "/tasks", - "description": "List active/recent background tasks for the current session" - }, - { - "command": "/context", - "description": "Explain how context is assembled", - "usage_hint": "[list|detail|json]" - }, - { - "command": "/whoami", - "description": "Show your sender identity" - }, - { - "command": "/skill", - "description": "Run a skill by name", - "usage_hint": " [input]" - }, - { - "command": "/btw", - "description": "Ask a side question without changing session context", - "usage_hint": "" - }, - { - "command": "/side", - "description": "Ask a side question without changing session context", - "usage_hint": "" - }, - { - "command": "/usage", - "description": "Control the usage footer or show cost summary", - "usage_hint": "off|tokens|full|cost" - } - ] +{ + "slash_commands": [ + { + "command": "/new", + "description": "Start a new session", + "usage_hint": "[model]" + }, + { + "command": "/reset", + "description": "Reset the current session" + }, + { + "command": "/compact", + "description": "Compact the session context", + "usage_hint": "[instructions]" + }, + { + "command": "/stop", + "description": "Stop the current run" + }, + { + "command": "/session", + "description": "Manage thread-binding expiry", + "usage_hint": "idle or max-age " + }, + { + "command": "/think", + "description": "Set the thinking level", + "usage_hint": "" + }, + { + "command": "/verbose", + "description": "Toggle verbose output", + "usage_hint": "on|off|full" + }, + { + "command": "/fast", + "description": "Show or set fast mode", + "usage_hint": "[status|on|off]" + }, + { + "command": "/reasoning", + "description": "Toggle reasoning visibility", + "usage_hint": "[on|off|stream]" + }, + { + "command": "/elevated", + "description": "Toggle elevated mode", + "usage_hint": "[on|off|ask|full]" + }, + { + "command": "/exec", + "description": "Show or set exec defaults", + "usage_hint": "host= security= ask= node=" + }, + { + "command": "/model", + "description": "Show or set the model", + "usage_hint": "[name|#|status]" + }, + { + "command": "/models", + "description": "List providers/models", + "usage_hint": "[provider] [page] [limit=|size=|all]" + }, + { + "command": "/help", + "description": "Show the short help summary" + }, + { + "command": "/commands", + "description": "Show the generated command catalog" + }, + { + "command": "/tools", + "description": "Show what the current agent can use right now", + "usage_hint": "[compact|verbose]" + }, + { + "command": "/agentstatus", + "description": "Show runtime status, including provider usage/quota when available" + }, + { + "command": "/tasks", + "description": "List active/recent background tasks for the current session" + }, + { + "command": "/context", + "description": "Explain how context is assembled", + "usage_hint": "[list|detail|json]" + }, + { + "command": "/whoami", + "description": "Show your sender identity" + }, + { + "command": "/skill", + "description": "Run a skill by name", + "usage_hint": " [input]" + }, + { + "command": "/btw", + "description": "Ask a side question without changing session context", + "usage_hint": "" + }, + { + "command": "/side", + "description": "Ask a side question without changing session context", + "usage_hint": "" + }, + { + "command": "/usage", + "description": "Control the usage footer or show cost summary", + "usage_hint": "off|tokens|full|cost" + } + ] +} ``` - 使用与上方 Socket Mode 相同的 `slash_commands` 列表，并为每个条目添加 `"url": "https://gateway-host.example.com/slack/events"`。示例： + 使用与上方 Socket Mode 相同的 `slash_commands` 列表，并向每个条目添加 `"url": "https://gateway-host.example.com/slack/events"`。示例： ```json - "slash_commands": [ - { - "command": "/new", - "description": "Start a new session", - "usage_hint": "[model]", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/help", - "description": "Show the short help summary", - "url": "https://gateway-host.example.com/slack/events" - } - // ...repeat for every command with the same `url` value - ] +{ + "slash_commands": [ + { + "command": "/new", + "description": "Start a new session", + "usage_hint": "[model]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/help", + "description": "Show the short help summary", + "url": "https://gateway-host.example.com/slack/events" + } + ] +} ``` + 在列表中的每个命令上重复该 `url` 值。 + - - 如果你希望出站消息使用当前智能体身份（自定义用户名和图标），而不是默认 Slack 应用身份，请添加 `chat:write.customize` 机器人作用域。 + + 如果你希望传出消息使用当前智能体身份（自定义用户名和图标），而不是默认 Slack 应用身份，请添加 `chat:write.customize` 机器人作用域。 - 如果你使用表情符号图标，Slack 期望使用 `:emoji_name:` 语法。 + 如果你使用表情图标，Slack 预期使用 `:emoji_name:` 语法。 - - 如果你配置了 `channels.slack.userToken`，典型读取作用域包括： + + 如果你配置了 `channels.slack.userToken`，典型的读取作用域包括： - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -458,23 +475,23 @@ openclaw gateway - HTTP 模式需要 `botToken` + `signingSecret`。 - `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 字符串或 SecretRef 对象。 -- 配置令牌会覆盖环境变量回退。 +- 配置令牌会覆盖环境变量回退值。 - `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账号。 -- `userToken`（`xoxp-...`）只能通过配置提供（无环境变量回退），并且默认采用只读行为（`userTokenReadOnly: true`）。 +- `userToken`（`xoxp-...`）仅能通过配置设置（没有环境变量回退），并且默认采用只读行为（`userTokenReadOnly: true`）。 Status 快照行为： -- Slack 账号检查会跟踪每个凭据的 `*Source` 和 `*Status` +- Slack 账号检查会按凭证跟踪 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。 - Status 为 `available`、`configured_unavailable` 或 `missing`。 -- `configured_unavailable` 表示该账号通过 SecretRef - 或其他非内联密钥来源进行了配置，但当前命令/运行时路径 +- `configured_unavailable` 表示账号已通过 SecretRef + 或其他非内联密钥来源配置，但当前命令/运行时路径 无法解析实际值。 -- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下， - 必需组合是 `botTokenStatus` + `appTokenStatus`。 +- 在 HTTP 模式下会包含 `signingSecretStatus`；在 Socket Mode 下， + 所需组合是 `botTokenStatus` + `appTokenStatus`。 -对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍优先使用机器人令牌；只有当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许用户令牌写入。 +对于操作/目录读取，配置用户令牌后可以优先使用用户令牌。对于写入，仍优先使用机器人令牌；仅当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许用户令牌写入。 ## 操作和门控 @@ -485,11 +502,11 @@ Slack 操作由 `channels.slack.actions.*` 控制。 | 组 | 默认值 | | ---------- | ------- | -| messages | 已启用 | -| reactions | 已启用 | -| pins | 已启用 | -| memberInfo | 已启用 | -| emojiList | 已启用 | +| messages | 启用 | +| reactions | 启用 | +| pins | 启用 | +| memberInfo | 启用 | +| emojiList | 启用 | 当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并为图片返回图片预览，或为其他文件类型返回本地文件元数据。 @@ -497,7 +514,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `channels.slack.dmPolicy` 控制私信访问。`channels.slack.allowFrom` 是规范私信允许列表。 + `channels.slack.dmPolicy` 控制私信访问。`channels.slack.allowFrom` 是规范的私信允许列表。 - `pairing`（默认） - `allowlist` @@ -515,10 +532,10 @@ Slack 操作由 `channels.slack.actions.*` 控制。 多账号优先级： - `channels.slack.accounts.default.allowFrom` 仅适用于 `default` 账号。 - - 具名账号在自身 `allowFrom` 未设置时继承 `channels.slack.allowFrom`。 + - 具名账号在自己的 `allowFrom` 未设置时继承 `channels.slack.allowFrom`。 - 具名账号不会继承 `channels.slack.accounts.default.allowFrom`。 - 旧版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的情况下，将它们迁移到 `dmPolicy` 和 `allowFrom`。 + 旧版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍会为兼容性读取。`openclaw doctor --fix` 会在不改变访问权限的前提下，将它们迁移到 `dmPolicy` 和 `allowFrom`。 私信中的配对使用 `openclaw pairing approve slack `。 @@ -531,20 +548,20 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `allowlist` - `disabled` - 渠道允许列表位于 `channels.slack.channels` 下，并且**必须使用稳定的 Slack 渠道 ID**（例如 `C12345678`）作为配置键。 + 渠道允许列表位于 `channels.slack.channels` 下，并且配置键**必须使用稳定的 Slack 渠道 ID**（例如 `C12345678`）。 - 运行时注意事项：如果完全缺少 `channels.slack`（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使设置了 `channels.defaults.groupPolicy`）。 + 运行时注意事项：如果 `channels.slack` 完全缺失（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使设置了 `channels.defaults.groupPolicy`）。 名称/ID 解析： - - 当令牌访问权限允许时，渠道允许列表条目和私信允许列表条目会在启动时解析 - - 未解析的渠道名称条目会按配置保留，但默认在路由中被忽略 - - 入站授权和渠道路由默认优先使用 ID；直接用户名/短名匹配需要 `channels.slack.dangerouslyAllowNameMatching: true` + - 渠道允许列表条目和私信允许列表条目会在启动时解析，前提是令牌访问允许 + - 未解析的渠道名称条目会保留为已配置状态，但默认在路由中忽略 + - 入站授权和渠道路由默认优先使用 ID；直接用户名/别名匹配需要 `channels.slack.dangerouslyAllowNameMatching: true` - 基于名称的键（`#channel-name` 或 `channel-name`）在 `groupPolicy: "allowlist"` 下**不会**匹配。渠道查找默认优先使用 ID，因此基于名称的键永远无法成功路由，并且该渠道中的所有消息都会被静默阻止。这不同于 `groupPolicy: "open"`；在该模式下，渠道键不是路由必需项，基于名称的键看起来可以工作。 + 基于名称的键（`#channel-name` 或 `channel-name`）在 `groupPolicy: "allowlist"` 下**不会**匹配。渠道查找默认优先使用 ID，因此基于名称的键永远无法成功路由，该渠道中的所有消息都会被静默阻止。这不同于 `groupPolicy: "open"`，后者不需要渠道键参与路由，因此基于名称的键看起来可以工作。 - 始终使用 Slack 渠道 ID 作为键。查找方法：在 Slack 中右键点击渠道 → **复制链接** — ID（`C...`）会出现在 URL 末尾。 + 始终使用 Slack 渠道 ID 作为键。查找方式：在 Slack 中右键点击渠道 → **Copy link** — ID（`C...`）会出现在 URL 末尾。 正确： @@ -580,16 +597,16 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 渠道消息默认受提及门控限制。 + 渠道消息默认受提及门控。 提及来源： - 显式应用提及（`<@botId>`） - - 当机器人用户是该用户组成员时，Slack 用户组提及（``）；需要 `usergroups:read` - - 提及正则表达式模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） + - 当机器人用户是 Slack 用户组成员时的 Slack 用户组提及（``）；需要 `usergroups:read` + - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） - 每渠道控制（`channels.slack.channels.`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 支持）： + 按渠道控制项（`channels.slack.channels.`；名称只能通过启动解析或 `dangerouslyAllowNameMatching` 使用）： - `requireMention` - `users`（允许列表） @@ -598,9 +615,9 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `systemPrompt` - `tools`, `toolsBySender` - `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符 - （旧版无前缀键仍仅映射到 `id:`） + （旧版无前缀键仍只映射到 `id:`） - `allowBots` 对渠道和私有渠道较为保守：仅当发送机器人的 ID 明确列在该房间的 `users` 允许列表中，或 `channels.slack.allowFrom` 中至少一个明确的 Slack 所有者 ID 当前是房间成员时，才接受机器人作者发送的房间消息。通配符和显示名称所有者条目不满足所有者存在条件。所有者存在检查使用 Slack `conversations.members`；请确保应用拥有与房间类型匹配的读取作用域（公共渠道为 `channels:read`，私有渠道为 `groups:read`）。如果成员查询失败，OpenClaw 会丢弃机器人作者发送的房间消息。 + 对渠道和私有渠道来说，`allowBots` 是保守的：只有当发送机器人被明确列在该房间的 `users` 允许列表中，或 `channels.slack.allowFrom` 中至少一个显式 Slack 所有者 ID 当前是房间成员时，才接受机器人发送的房间消息。通配符和显示名称所有者条目不满足所有者存在性要求。所有者存在性使用 Slack `conversations.members`；请确保应用具备对应房间类型的匹配读取作用域（公共渠道为 `channels:read`，私有渠道为 `groups:read`）。如果成员查询失败，OpenClaw 会丢弃机器人发送的房间消息。 @@ -608,18 +625,18 @@ Slack 操作由 `channels.slack.actions.*` 控制。 ## 线程、会话和回复标签 - 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。 -- Slack 路由绑定接受原始对等端 ID，以及 `channel:C12345678`、`user:U12345678` 和 `<@U12345678>` 等 Slack 目标形式。 +- Slack 路由绑定接受原始对等方 ID，以及 `channel:C12345678`、`user:U12345678` 和 `<@U12345678>` 等 Slack 目标形式。 - 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。 - 渠道会话：`agent::slack:channel:`。 -- 适用时，线程回复可以创建线程会话后缀（`:thread:`）。 +- 线程回复在适用时可以创建线程会话后缀（`:thread:`）。 - `channels.slack.thread.historyScope` 默认值为 `thread`；`thread.inheritParent` 默认值为 `false`。 -- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时获取多少条已有线程消息（默认 `20`；设为 `0` 可禁用）。 -- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，会抑制隐式线程提及，因此机器人只会响应线程内显式 `@bot` 提及，即使机器人已经参与该线程。没有此设置时，机器人已参与线程中的回复会绕过 `requireMention` 门控。 +- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时获取多少条现有线程消息（默认 `20`；设置为 `0` 可禁用）。 +- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，抑制隐式线程提及，使机器人只响应线程内的显式 `@bot` 提及，即使机器人已经参与过该线程。没有此设置时，在机器人已参与线程中的回复会绕过 `requireMention` 门控。 -回复线程控制： +回复线程控制项： - `channels.slack.replyToMode`: `off|first|all|batched`（默认 `off`） -- `channels.slack.replyToModeByChatType`: 按 `direct|group|channel` 分别设置 +- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 设置 - 直接聊天的旧版回退：`channels.slack.dm.replyToMode` 支持手动回复标签： @@ -628,23 +645,23 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `[[reply_to:]]` -`replyToMode="off"` 会禁用 Slack 中的**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这不同于 Telegram，在 Telegram 中，显式标签在 `"off"` 模式下仍会生效。Slack 线程会将消息从渠道中隐藏，而 Telegram 回复会保持内联可见。 +`replyToMode="off"` 会禁用 Slack 中的**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这不同于 Telegram，在 Telegram 中，显式标签在 `"off"` 模式下仍会被遵循。Slack 线程会在渠道中隐藏消息，而 Telegram 回复会以内联形式保持可见。 -## 确认反应 +## 确认回应 -`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 +`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情。 解析顺序： - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） +- 智能体身份表情回退（`agents.list[].identity.emoji`，否则为 "👀"） 注意事项： -- Slack 期望使用短代码（例如 `"eyes"`）。 +- Slack 预期使用短代码（例如 `"eyes"`）。 - 使用 `""` 可为 Slack 账号或全局禁用该反应。 ## 文本流式传输 @@ -654,16 +671,16 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `off`：禁用实时预览流式传输。 - `partial`（默认）：用最新的部分输出替换预览文本。 - `block`：追加分块预览更新。 -- `progress`：生成时显示进度 Status 文本，然后发送最终文本。 -- `streaming.preview.toolProgress`：当草稿预览处于活动状态时，将工具/进度更新路由到同一个已编辑的预览消息中（默认：`true`）。设为 `false` 可保留单独的工具/进度消息。 +- `progress`：生成时显示进度状态文本，然后发送最终文本。 +- `streaming.preview.toolProgress`：当草稿预览处于活动状态时，将工具/进度更新路由到同一个已编辑的预览消息中（默认值：`true`）。设置为 `false` 可保留单独的工具/进度消息。 -当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。 +当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认值：`true`）。 -- 必须有可用的回复线程，才会显示原生文本流式传输和 Slack 助手线程 Status。线程选择仍遵循 `replyToMode`。 -- 当原生流式传输不可用或没有回复线程时，渠道、群组聊天和顶级私信根仍可使用普通草稿预览。 -- 顶级 Slack 私信默认保持在线程外，因此不会显示 Slack 线程样式的原生流/Status 预览；OpenClaw 会改为在私信中发布并编辑草稿预览。 +- 必须有可用的回复线程，才能显示原生文本流式传输和 Slack 助手线程状态。线程选择仍遵循 `replyToMode`。 +- 当原生流式传输不可用或不存在回复线程时，渠道、群聊和顶层私信根仍可使用普通草稿预览。 +- 顶层 Slack 私信默认保持在线程之外，因此不会显示 Slack 的线程样式原生流/状态预览；OpenClaw 会改为在私信中发布并编辑草稿预览。 - 媒体和非文本载荷会回退到普通投递。 -- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息只有在可以就地编辑预览时才会刷新。 +- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/块最终消息只有在能够就地编辑预览时才会刷新。 - 如果流式传输在回复中途失败，OpenClaw 会对剩余载荷回退到普通投递。 使用草稿预览而不是 Slack 原生文本流式传输： @@ -687,9 +704,9 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。 - 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。 -## 输入反应回退 +## 输入状态反应回退 -`typingReaction` 会在 OpenClaw 处理回复时向入站 Slack 消息添加临时反应，然后在运行结束时移除它。这在线程回复之外最有用，因为线程回复会使用默认的“正在输入...”状态指示器。 +`typingReaction` 会在 OpenClaw 处理回复时，为入站 Slack 消息添加一个临时反应，并在运行完成后移除它。这在线程回复之外最有用，因为线程回复使用默认的 “is typing...” 状态指示器。 解析顺序： @@ -699,42 +716,42 @@ Slack 操作由 `channels.slack.actions.*` 控制。 注意事项： - Slack 需要短代码（例如 `"hourglass_flowing_sand"`）。 -- reaction 是尽力而为的，并会在回复或失败路径完成后自动尝试清理。 +- 反应是尽力而为的；在回复或失败路径完成后，会自动尝试清理。 ## 媒体、分块和投递 - Slack 文件附件会从 Slack 托管的私有 URL 下载（使用令牌认证的请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以使用 `download-file` 获取原始文件。 + Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在抓取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以用 `download-file` 获取原始文件。 - 下载使用有界的空闲和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息，并回退到文件占位符。 + 下载使用有界的空闲超时和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息，并回退到文件占位符。 运行时入站大小上限默认为 `20MB`，除非被 `channels.slack.mediaMaxMb` 覆盖。 - - 文本块使用 `channels.slack.textChunkLimit`（默认 4000） + - 文本分块使用 `channels.slack.textChunkLimit`（默认 4000） - `channels.slack.chunkMode="newline"` 启用段落优先拆分 - - 文件发送使用 Slack 上传 API，并可包含线程回复（`thread_ts`） - - 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则，渠道发送使用媒体流水线中的 MIME 类型默认值 + - 文件发送使用 Slack 上传 API，并且可以包含线程回复（`thread_ts`） + - 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则渠道发送会使用媒体管线中的 MIME 类型默认值 - 首选显式目标： + 首选的显式目标： - `user:` 用于私信 - `channel:` 用于渠道 - 仅文本/块的 Slack 私信可以直接发布到用户 ID；文件上传和线程发送会先通过 Slack conversation API 打开私信，因为这些路径需要具体的 conversation ID。 + 纯文本/分块的 Slack 私信可以直接发布到用户 ID；文件上传和线程发送会先通过 Slack 会话 API 打开私信，因为这些路径需要具体的会话 ID。 -## 命令和 slash 行为 +## 命令和斜杠行为 -Slash 命令在 Slack 中显示为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 以更改命令默认值： +斜杠命令在 Slack 中表现为单个配置命令或多个原生命令。配置 `channels.slack.slashCommand` 以更改命令默认值： - `enabled: false` - `name: "openclaw"` @@ -745,7 +762,7 @@ Slash 命令在 Slack 中显示为单个已配置命令或多个原生命令。 /openclaw /help ``` -原生命令需要在你的 Slack 应用中使用[其他清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 启用，或在全局配置中改用 `commands.native: true`。 +原生命令需要在你的 Slack 应用中配置[其他清单设置](#additional-manifest-settings)，并改用 `channels.slack.commands.native: true` 或全局配置中的 `commands.native: true` 启用。 - Slack 的原生命令自动模式为**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。 @@ -753,22 +770,22 @@ Slash 命令在 Slack 中显示为单个已配置命令或多个原生命令。 /help ``` -原生参数菜单使用自适应渲染策略，会在分派所选选项值之前显示确认模态框： +原生参数菜单使用自适应渲染策略，在分派所选选项值之前显示确认模态框： - 最多 5 个选项：按钮块 - 6-100 个选项：静态选择菜单 -- 超过 100 个选项：当交互选项处理程序可用时，使用带异步选项过滤的外部选择 +- 超过 100 个选项：当交互选项处理器可用时，使用带异步选项过滤的外部选择 - 超出 Slack 限制：编码后的选项值回退为按钮 ```txt /think ``` -Slash 会话使用类似 `agent::slack:slash:` 的隔离键，并且仍会使用 `CommandTargetSessionKey` 将命令执行路由到目标对话会话。 +斜杠会话使用 `agent::slack:slash:` 这样的隔离键，并且仍会使用 `CommandTargetSessionKey` 将命令执行路由到目标会话会话。 ## 交互式回复 -Slack 可以渲染智能体创作的交互式回复控件，但此功能默认禁用。 +Slack 可以渲染智能体编写的交互式回复控件，但此功能默认禁用。 全局启用： @@ -784,7 +801,7 @@ Slack 可以渲染智能体创作的交互式回复控件，但此功能默认 } ``` -或者只为一个 Slack 账户启用： +或仅为一个 Slack 账户启用： ```json5 { @@ -802,41 +819,43 @@ Slack 可以渲染智能体创作的交互式回复控件，但此功能默认 } ``` -启用后，智能体可以发出仅适用于 Slack 的回复指令： +启用后，智能体可以发出仅限 Slack 的回复指令： - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -这些指令会编译为 Slack Block Kit，并通过现有 Slack interaction 事件路径回传点击或选择。 +这些指令会编译为 Slack Block Kit，并通过现有 Slack 交互事件路径把点击或选择路由回来。 注意： -- 这是 Slack 专属 UI。其他渠道不会将 Slack Block Kit 指令转换为自己的按钮系统。 -- 交互式回调值是 OpenClaw 生成的不透明令牌，而不是智能体创作的原始值。 -- 如果生成的交互式块会超出 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的块载荷。 +- 这是 Slack 专用 UI。其他渠道不会把 Slack Block Kit 指令转换为自己的按钮系统。 +- 交互回调值是 OpenClaw 生成的不透明令牌，而不是智能体编写的原始值。 +- 如果生成的交互块会超过 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的 blocks 载荷。 -## Slack 中的 Exec 批准 +## Slack 中的 Exec 审批 -Slack 可以作为带有交互式按钮和交互的原生批准客户端，而不是回退到 Web UI 或终端。 +Slack 可以充当带有交互式按钮和交互的原生审批客户端，而不是回退到 Web UI 或终端。 -- Exec 批准使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 -- 当请求已经落到 Slack 中且批准 ID kind 为 `plugin:` 时，插件批准仍可通过同一个 Slack 原生按钮界面完成。 -- 仍会强制执行批准者授权：只有被识别为批准者的用户才能通过 Slack 批准或拒绝请求。 +- Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 +- 当请求已经到达 Slack 且审批 id 类型为 `plugin:` 时，插件审批仍可通过同一 Slack 原生按钮界面完成。 +- 审批者授权仍会强制执行：只有被识别为审批者的用户才能通过 Slack 批准或拒绝请求。 -这使用与其他渠道相同的共享批准按钮界面。当你的 Slack 应用设置中启用了 `interactivity` 时，批准提示会直接在对话中渲染为 Block Kit 按钮。 -当这些按钮存在时，它们是主要批准 UX；只有当工具结果表示聊天批准不可用，或手动批准是唯一路径时，OpenClaw 才应包含手动 `/approve` 命令。 +这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用 `interactivity` 后，审批提示会直接在会话中渲染为 Block Kit 按钮。 +当这些按钮存在时，它们就是主要审批体验；OpenClaw +只有在工具结果说明聊天审批不可用，或手动审批是唯一路径时， +才应包含手动 `/approve` 命令。 配置路径： - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers`（可选；可行时回退到 `commands.ownerAllowFrom`） +- `channels.slack.execApprovals.approvers`（可选；可能时回退到 `commands.ownerAllowFrom`） - `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter` -当 `enabled` 未设置或为 `"auto"`，且至少解析出一个批准者时，Slack 会自动启用原生 exec 批准。设置 `enabled: false` 可显式禁用 Slack 作为原生批准客户端。 -设置 `enabled: true` 可在解析出批准者时强制开启原生批准。 +当 `enabled` 未设置或为 `"auto"` 且至少能解析出一个审批者时，Slack 会自动启用原生 Exec 审批。设置 `enabled: false` 可显式禁用 Slack 作为原生审批客户端。 +当能够解析审批者时，设置 `enabled: true` 可强制开启原生审批。 -没有显式 Slack exec 批准配置时的默认行为： +没有显式 Slack Exec 审批配置时的默认行为： ```json5 { @@ -846,7 +865,8 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 } ``` -只有当你想覆盖批准者、添加过滤器或选择加入源聊天投递时，才需要显式 Slack 原生配置： +只有当你想覆盖审批者、添加过滤器，或 +选择启用来源聊天投递时，才需要显式 Slack 原生配置： ```json5 { @@ -862,22 +882,24 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 } ``` -共享的 `approvals.exec` 转发是独立的。只有当 exec 批准提示还必须路由到其他聊天或显式带外目标时才使用它。共享的 `approvals.plugin` 转发也是独立的；当这些请求已经落到 Slack 中时，Slack 原生按钮仍可完成插件批准。 +共享 `approvals.exec` 转发是独立的。只有当 Exec 审批提示也必须 +路由到其他聊天或显式的带外目标时才使用它。共享 `approvals.plugin` 转发也是 +独立的；当这些请求已经到达 Slack 时，Slack 原生按钮仍然可以完成插件审批。 -同聊天 `/approve` 也适用于已经支持命令的 Slack 渠道和私信。完整批准转发模型见 [Exec 批准](/zh-CN/tools/exec-approvals)。 +同一聊天中的 `/approve` 也适用于已经支持命令的 Slack 渠道和私信。完整的审批转发模型见 [Exec 审批](/zh-CN/tools/exec-approvals)。 ## 事件和运行行为 - 消息编辑/删除会映射为系统事件。 - 线程广播（“同时发送到渠道”的线程回复）会作为普通用户消息处理。 -- reaction 添加/移除事件会映射为系统事件。 -- 成员加入/离开、渠道创建/重命名以及 pin 添加/移除事件会映射为系统事件。 -- 启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。 -- 渠道 topic/purpose 元数据会被视为不可信上下文，并可注入路由上下文。 -- 适用时，线程起始消息和初始线程历史上下文播种会按配置的发送者 allowlist 过滤。 -- 块操作和模态框交互会发出结构化的 `Slack interaction: ...` 系统事件，并带有丰富的载荷字段： - - 块操作：所选值、标签、选择器值和 `workflow_*` 元数据 - - 模态框 `view_submission` 和 `view_closed` 事件，带有已路由的渠道元数据和表单输入 +- 反应添加/移除事件会映射为系统事件。 +- 成员加入/离开、渠道创建/重命名，以及置顶添加/移除事件会映射为系统事件。 +- 启用 `configWrites` 后，`channel_id_changed` 可以迁移渠道配置键。 +- 渠道主题/用途元数据会被视为不受信任的上下文，并且可以注入到路由上下文中。 +- 线程发起者和初始线程历史上下文种子会在适用时按已配置的发送者允许列表过滤。 +- 块操作和模态框交互会发出带有丰富载荷字段的结构化 `Slack interaction: ...` 系统事件： + - 块操作：选定值、标签、选择器值，以及 `workflow_*` 元数据 + - 模态框 `view_submission` 和 `view_closed` 事件，包含已路由的渠道元数据和表单输入 ## 配置参考 @@ -887,7 +909,7 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 - 模式/认证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*` - 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels` -- 兼容性开关：`dangerouslyAllowNameMatching`（应急开关；除非需要，否则保持关闭） +- 兼容性开关：`dangerouslyAllowNameMatching`（紧急破窗；除非需要，否则保持关闭） - 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention` - 线程/历史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` - 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress` @@ -902,11 +924,11 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 按顺序检查： - `groupPolicy` - - 渠道 allowlist（`channels.slack.channels`）— **键必须是渠道 ID**（`C12345678`），而不是名称（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，基于名称的键会静默失败，因为默认情况下渠道路由优先使用 ID。要查找 ID：在 Slack 中右键点击渠道 → **复制链接** — URL 末尾的 `C...` 值就是渠道 ID。 + - 渠道允许列表（`channels.slack.channels`）——**键必须是渠道 ID**（`C12345678`），而不是名称（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，基于名称的键会静默失败，因为默认情况下渠道路由以 ID 优先。查找 ID：在 Slack 中右键点击渠道 → **Copy link**——URL 末尾的 `C...` 值就是渠道 ID。 - `requireMention` - - 每渠道 `users` allowlist + - 每个渠道的 `users` 允许列表 - 有用命令： + 有用的命令： ```bash openclaw channels status --probe @@ -921,9 +943,9 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy`（或旧版 `channels.slack.dm.policy`） - - 配对批准 / allowlist 条目 + - 配对审批 / 允许列表条目 - Slack Assistant 私信事件：提到 `drop message_changed` 的详细日志 - 通常表示 Slack 发送了一个已编辑的 Assistant 线程事件，但消息元数据中没有 + 通常表示 Slack 发送了编辑后的 Assistant 线程事件，但消息元数据中没有 可恢复的人类发送者 ```bash @@ -933,50 +955,50 @@ openclaw pairing list slack - 在 Slack 应用设置中验证 bot + app 令牌以及 Socket Mode 启用状态。 + 在 Slack 应用设置中验证 bot + app 令牌和 Socket Mode 启用状态。 如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或 - `appTokenStatus: "configured_unavailable"`，则表示 Slack 账户已配置， - 但当前运行时无法解析 SecretRef 支持的值。 + `appTokenStatus: "configured_unavailable"`，说明 Slack 账户已配置， + 但当前运行时无法解析基于 SecretRef 的值。 - + 验证： - - signing secret - - webhook path + - 签名密钥 + - webhook 路径 - Slack Request URL（Events + Interactivity + Slash Commands） - - 每个 HTTP 账户的唯一 `webhookPath` + - 每个 HTTP 账户使用唯一的 `webhookPath` 如果账户快照中出现 `signingSecretStatus: "configured_unavailable"`， - 则表示 HTTP 账户已配置，但当前运行时无法解析 SecretRef 支持的 signing secret。 + 说明 HTTP 账户已配置，但当前运行时无法解析基于 SecretRef 的签名密钥。 - - 验证你的意图是： + + 确认你的意图是： - - 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册了匹配的 slash 命令 - - 或单个 slash 命令模式（`channels.slack.slashCommand.enabled: true`） + - 原生命令模式（`channels.slack.commands.native: true`），并且 Slack 中注册了匹配的斜杠命令 + - 或单个斜杠命令模式（`channels.slack.slashCommand.enabled: true`） - 还要检查 `commands.useAccessGroups` 和渠道/用户 allowlist。 + 也请检查 `commands.useAccessGroups` 和渠道/用户允许列表。 ## 附件视觉参考 -当 Slack 文件下载成功且大小限制允许时，Slack 可以将下载的媒体附加到智能体轮次。图像文件可以通过媒体理解路径传递，或直接传递给支持视觉的回复模型；其他文件会保留为可下载文件上下文，而不是作为图像输入处理。 +当 Slack 文件下载成功且大小限制允许时，Slack 可以将下载的媒体附加到智能体轮次中。图像文件可以通过媒体理解路径传递，或直接传递给具备视觉能力的回复模型；其他文件会保留为可下载的文件上下文，而不是作为图像输入处理。 ### 支持的媒体类型 -| 媒体类型 | 来源 | 当前行为 | 备注 | +| 媒体类型 | 来源 | 当前行为 | 备注 | | ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | JPEG / PNG / GIF / WebP 图像 | Slack 文件 URL | 下载并附加到该轮对话中，以便支持视觉的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） | | PDF 文件 | Slack 文件 URL | 下载并作为文件上下文暴露给 `download-file` 或 `pdf` 等工具 | Slack 入站不会自动将 PDF 转换为图像视觉输入 | -| 其他文件 | Slack 文件 URL | 在可能时下载并作为文件上下文暴露 | 二进制文件不会被视为图像输入 | -| 线程回复 | 线程起始文件 | 当回复没有直接媒体时，可以将根消息文件补水为上下文 | 仅文件的起始消息会使用附件占位符 | +| 其他文件 | Slack 文件 URL | 尽可能下载并作为文件上下文暴露 | 二进制文件不会被视为图像输入 | +| 线程回复 | 线程起始消息文件 | 当回复没有直接媒体时，根消息文件可以作为上下文补全 | 仅包含文件的起始消息会使用附件占位符 | | 多图像消息 | 多个 Slack 文件 | 每个文件都会独立评估 | Slack 处理限制为每条消息最多八个文件 | ### 入站流水线 @@ -985,17 +1007,17 @@ openclaw pairing list slack 1. OpenClaw 使用机器人令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。 2. 下载成功后，文件会写入媒体存储。 -3. 下载的媒体路径和内容类型会加入入站上下文。 +3. 下载的媒体路径和内容类型会添加到入站上下文中。 4. 支持图像的模型/工具路径可以使用该上下文中的图像附件。 -5. 非图像文件仍会作为文件元数据或媒体引用提供给能处理它们的工具。 +5. 非图像文件仍会作为文件元数据或媒体引用提供给能够处理它们的工具。 ### 线程根附件继承 -当消息在线程中到达时（有 `thread_ts` 父级）： +当消息到达某个线程中时（具有 `thread_ts` 父级）： -- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以将根文件补水为线程起始上下文。 +- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以将根文件补全为线程起始上下文。 - 直接回复附件优先于根消息附件。 -- 只有文件且没有文本的根消息会用附件占位符表示，这样回退仍可包含其文件。 +- 仅包含文件且没有文本的根消息会用附件占位符表示，这样后备逻辑仍可包含其文件。 ### 多附件处理 @@ -1003,52 +1025,52 @@ openclaw pairing list slack - 每个附件都会通过媒体流水线独立处理。 - 下载的媒体引用会聚合到消息上下文中。 -- 处理顺序遵循事件负载中的 Slack 文件顺序。 -- 某个附件下载失败不会阻塞其他附件。 +- 处理顺序遵循事件载荷中的 Slack 文件顺序。 +- 一个附件下载失败不会阻塞其他附件。 ### 大小、下载和模型限制 - **大小上限**：默认每个文件 20 MB。可通过 `channels.slack.mediaMaxMb` 配置。 - **下载失败**：Slack 无法提供的文件、过期 URL、不可访问文件、超大文件以及 Slack 认证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。 -- **视觉模型**：图像分析会在当前回复模型支持视觉时使用它，否则使用 `agents.defaults.imageModel` 中配置的图像模型。 +- **视觉模型**：图像分析会在当前回复模型支持视觉时使用它，否则使用 `agents.defaults.imageModel` 配置的图像模型。 ### 已知限制 | 场景 | 当前行为 | 解决方法 | | -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | 过期的 Slack 文件 URL | 文件被跳过；不显示错误 | 在 Slack 中重新上传文件 | -| 未配置视觉模型 | 图像附件会作为媒体引用存储，但不会作为图像分析 | 配置 `agents.defaults.imageModel` 或使用支持视觉的回复模型 | -| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，增大 `channels.slack.mediaMaxMb` | -| 转发/共享附件 | 文本和 Slack 托管的图像/文件媒体尽力处理 | 直接在 OpenClaw 线程中重新分享 | -| PDF 附件 | 作为文件/媒体上下文存储，不会自动路由到图像视觉 | 使用 `download-file` 获取文件元数据，或使用 `pdf` 工具进行 PDF 分析 | +| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel` 或使用支持视觉的回复模型 | +| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，可增大 `channels.slack.mediaMaxMb` | +| 转发/共享附件 | 文本以及 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新共享 | +| PDF 附件 | 存储为文件/媒体上下文，不会自动通过图像视觉路由 | 使用 `download-file` 获取文件元数据，或使用 `pdf` 工具进行 PDF 分析 | ### 相关文档 - [媒体理解流水线](/zh-CN/nodes/media-understanding) - [PDF 工具](/zh-CN/tools/pdf) -- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 附件视觉启用 -- 回归测试: [#51353](https://github.com/openclaw/openclaw/issues/51353) -- 实时验证: [#51354](https://github.com/openclaw/openclaw/issues/51354) +- 史诗任务：[#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 附件视觉启用 +- 回归测试：[#51353](https://github.com/openclaw/openclaw/issues/51353) +- 实时验证：[#51354](https://github.com/openclaw/openclaw/issues/51354) ## 相关 - - 将 Slack 用户配对到 Gateway 网关。 + + 将 Slack 用户与 Gateway 网关配对。 - + 渠道和群组私信行为。 - + 将入站消息路由到智能体。 - + 威胁模型和加固。 - + 配置布局和优先级。 - + 命令目录和行为。