From 8e60a4346834912a954f10a3f08cee01cc7bc25a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 03:00:43 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/discord.md | 480 ++++++++++++++------------ docs/zh-CN/channels/slack.md | 379 ++++++++++---------- docs/zh-CN/gateway/config-channels.md | 327 +++++++++--------- 3 files changed, 605 insertions(+), 581 deletions(-) diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index c6a98e751..29fc608cd 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -1,22 +1,22 @@ --- read_when: - 正在处理 Discord 渠道功能 -summary: Discord 机器人支持状态、功能和配置 +summary: Discord 机器人支持状态、能力和配置 title: Discord x-i18n: - generated_at: "2026-05-02T02:19:22Z" + generated_at: "2026-05-02T02:58:14Z" model: gpt-5.5 provider: openai - source_hash: 38dbdcf8fe6eb84c77ec7d0e88ecd839b6ecfa311194b2740a3a17a34f85823c + source_hash: 3f82966fd7c7f5ded09d72ea8bc8fe255316fe0178ee71c3f8a4e36410aead54 source_path: channels/discord.md workflow: 16 --- -可通过官方 Discord Gateway 网关使用私信和服务器频道。 +已可通过官方 Discord Gateway 网关用于私信和服务器频道。 - Discord 私信默认进入配对模式。 + Discord 私信默认使用配对模式。 原生命令行为和命令目录。 @@ -28,45 +28,45 @@ x-i18n: ## 快速设置 -你需要创建一个带机器人的新应用，将机器人添加到你的服务器，并将它配对到 OpenClaw。我们建议将你的机器人添加到你自己的私人服务器。如果你还没有服务器，请先[创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **Create My Own > For me and my friends**）。 +你需要创建一个带机器人的新应用，将机器人添加到你的服务器，并将它配对到 OpenClaw。我们建议将你的机器人添加到你自己的私人服务器。如果你还没有服务器，请[先创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **Create My Own > For me and my friends**）。 - 前往 [Discord Developer Portal](https://discord.com/developers/applications)，点击 **New Application**。将它命名为类似 “OpenClaw” 的名称。 + 前往 [Discord Developer Portal](https://discord.com/developers/applications)，然后点击 **New Application**。将它命名为类似 “OpenClaw” 的名称。 - 点击侧边栏中的 **Bot**。将 **Username** 设置为你给 OpenClaw 智能体起的名称。 + 点击侧边栏中的 **Bot**。将 **Username** 设置为你的 OpenClaw 智能体名称。 - 仍在 **Bot** 页面，向下滚动到 **Privileged Gateway Intents** 并启用： + 仍在 **Bot** 页面，向下滚动到 **Privileged Gateway Intents**，然后启用： - **Message Content Intent**（必需） - **Server Members Intent**（推荐；角色 allowlist 和名称到 ID 匹配需要） - - **Presence Intent**（可选；仅状态更新需要） + - **Presence Intent**（可选；仅在需要在线状态更新时需要） - - 在 **Bot** 页面向上滚动并点击 **Reset Token**。 + + 回到 **Bot** 页面顶部，点击 **Reset Token**。 - 尽管名称如此，这会生成你的第一个 token —— 并没有真正“重置”任何内容。 + 尽管名称如此，这会生成你的第一个令牌，并不会“重置”任何内容。 - 复制该 token 并保存到某处。这就是你的 **Bot Token**，稍后会用到。 + 复制令牌并保存在某处。这是你的 **Bot Token**，稍后会用到。 - 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用来将机器人添加到你的服务器。 + 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用于将机器人添加到你的服务器。 - 向下滚动到 **OAuth2 URL Generator** 并启用： + 向下滚动到 **OAuth2 URL Generator**，然后启用： - `bot` - `applications.commands` - 下方会出现 **Bot Permissions** 部分。至少启用： + 下方会出现 **Bot Permissions** 区块。至少启用： **General Permissions** - View Channels @@ -77,31 +77,31 @@ x-i18n: - Attach Files - Add Reactions（可选） - 这是普通文本频道的基线权限集。如果你计划在 Discord 帖子串中发帖，包括会创建或继续帖子串的论坛或媒体频道工作流，也请启用 **Send Messages in Threads**。 + 这是普通文本频道的基线设置。如果你计划在 Discord 线程中发帖，包括会创建或继续线程的论坛或媒体频道工作流，也请启用 **Send Messages in Threads**。 复制底部生成的 URL，粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该能在 Discord 服务器中看到你的机器人。 - 回到 Discord 应用，你需要启用开发者模式，以便复制内部 ID。 + 回到 Discord 应用，你需要启用开发者模式，才能复制内部 ID。 - 1. 点击 **User Settings**（头像旁的齿轮图标）→ **Advanced** → 开启 **Developer Mode** - 2. 右键点击侧边栏中的**服务器图标** → **Copy Server ID** + 1. 点击 **User Settings**（头像旁边的齿轮图标）→ **Advanced** → 开启 **Developer Mode** + 2. 在侧边栏右键点击你的 **server icon** → **Copy Server ID** 3. 右键点击你**自己的头像** → **Copy User ID** - 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存 —— 下一步你会把这三项发送给 OpenClaw。 + 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存，下一步你会把这三项发送给 OpenClaw。 - 为了让配对正常工作，Discord 需要允许你的机器人给你发私信。右键点击你的**服务器图标** → **Privacy Settings** → 开启 **Direct Messages**。 + 为了让配对生效，Discord 需要允许你的机器人给你发送私信。右键点击你的 **server icon** → **Privacy Settings** → 开启 **Direct Messages**。 - 这样服务器成员（包括机器人）就可以给你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持开启。如果你只计划使用服务器频道，可以在配对后关闭私信。 + 这会允许服务器成员（包括机器人）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持启用。如果你只计划使用服务器频道，可以在配对后禁用私信。 - - 你的 Discord 机器人 token 是机密信息（类似密码）。在给智能体发消息之前，请先在运行 OpenClaw 的机器上设置它。 + + 你的 Discord 机器人令牌是秘密信息（类似密码）。在给智能体发消息之前，请在运行 OpenClaw 的机器上设置它。 ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -120,9 +120,9 @@ openclaw config patch --file ./discord.patch.json5 openclaw gateway ``` - 如果 OpenClaw 已经作为后台服务运行，请通过 OpenClaw Mac 应用重启，或停止并重启 `openclaw gateway run` 进程。 - 对于托管服务安装，请在存在 `DISCORD_BOT_TOKEN` 的 shell 中运行 `openclaw gateway install`，或将该变量存储在 `~/.openclaw/.env` 中，以便服务在重启后解析环境变量 SecretRef。 - 如果你的主机被 Discord 启动时的应用查询阻止或限流，请从 Developer Portal 设置 Discord 应用/客户端 ID，这样启动就可以跳过该 REST 调用。默认账户使用 `channels.discord.applicationId`；运行多个 Discord 机器人时使用 `channels.discord.accounts..applicationId`。 + 如果 OpenClaw 已经作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或停止并重新启动 `openclaw gateway run` 进程。 + 对于托管服务安装，请在存在 `DISCORD_BOT_TOKEN` 的 shell 中运行 `openclaw gateway install`，或将变量存储到 `~/.openclaw/.env`，这样服务就能在重启后解析环境变量 SecretRef。 + 如果你的主机被 Discord 的启动应用查询阻止或限速，请从 Developer Portal 设置 Discord 应用/客户端 ID，这样启动时可以跳过该 REST 调用。默认账号使用 `channels.discord.applicationId`；运行多个 Discord 机器人时使用 `channels.discord.accounts..applicationId`。 @@ -132,7 +132,7 @@ openclaw gateway 在任意现有渠道（例如 Telegram）与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置标签页。 - > “我已经在配置中设置了我的 Discord 机器人 token。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” + > “我已经在配置中设置了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” 如果你更喜欢基于文件的配置，请设置： @@ -152,15 +152,15 @@ openclaw gateway } ``` - 默认账户的环境变量回退： + 默认账号的环境变量回退： ```bash DISCORD_BOT_TOKEN=... ``` - 对于脚本化或远程设置，请使用 `openclaw config patch --file ./discord.patch.json5 --dry-run` 写入同一个 JSON5 块，然后去掉 `--dry-run` 重新运行。支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商的 SecretRef 值。请参阅[密钥管理](/zh-CN/gateway/secrets)。 + 对于脚本化或远程设置，请使用 `openclaw config patch --file ./discord.patch.json5 --dry-run` 写入相同的 JSON5 区块，然后去掉 `--dry-run` 重新运行。支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商的 SecretRef 值。请参阅[密钥管理](/zh-CN/gateway/secrets)。 - 对于多个 Discord 机器人，请将每个机器人 token 和应用 ID 放在其账户下。顶层 `channels.discord.applicationId` 会被账户继承，所以只有在每个账户都应使用同一个应用 ID 时才在那里设置它。 + 对于多个 Discord 机器人，请将每个机器人令牌和应用 ID 保存在其账号下。顶层的 `channels.discord.applicationId` 会被账号继承，所以只有在每个账号都应使用同一个应用 ID 时才在那里设置。 ```json5 { @@ -188,11 +188,11 @@ DISCORD_BOT_TOKEN=... - 等到 Gateway 网关运行后，在 Discord 中给你的机器人发送私信。它会回复一个配对码。 + 等待 Gateway 网关运行后，在 Discord 中给你的机器人发送私信。它会回复一个配对码。 - 在你的现有渠道中将配对码发送给你的智能体： + 在你的现有渠道上将配对码发送给智能体： > “批准这个 Discord 配对码：``” @@ -206,26 +206,26 @@ openclaw pairing approve discord - 配对码会在 1 小时后过期。 + 配对码将在 1 小时后过期。 - 现在你应该可以在 Discord 中通过私信与你的智能体聊天。 + 现在你应该可以通过 Discord 私信与你的智能体聊天。 -Token 解析会感知账户。配置 token 值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 -如果两个已启用的 Discord 账户解析到同一个机器人 token，OpenClaw 只会为该 token 启动一个 Gateway 网关监控器。来自配置的 token 优先于默认环境变量回退；否则第一个启用的账户优先，并且重复账户会被报告为已禁用。 -对于高级出站调用（消息工具/渠道动作），显式的逐调用 `token` 会用于该调用。这适用于发送和读取/探测类动作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍来自活动运行时快照中选定的账户。 +令牌解析会感知账号。配置令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 只用于默认账号。 +如果两个已启用的 Discord 账号解析为同一个机器人令牌，OpenClaw 只会为该令牌启动一个 Gateway 网关监视器。配置来源的令牌优先于默认环境变量回退；否则第一个已启用的账号胜出，重复账号会被报告为已禁用。 +对于高级出站调用（消息工具/渠道操作），显式的逐调用 `token` 会用于该调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账号策略/重试设置仍来自活动运行时快照中的所选账号。 ## 推荐：设置服务器工作区 -私信可用后，你可以将你的 Discord 服务器设置为完整工作区，其中每个频道都会获得自己的智能体会话和上下文。对于只有你和机器人的私人服务器，推荐这样做。 +私信可用后，你可以将 Discord 服务器设置为完整工作区，让每个频道都有自己的智能体会话和自己的上下文。对于只有你和机器人使用的私人服务器，建议这样做。 - - 这会让你的智能体能够在你的服务器上的任意频道中响应，而不仅仅是私信。 + + 这会让你的智能体能够在服务器上的任意频道中响应，而不只是私信。 @@ -257,11 +257,11 @@ Token 解析会感知账户。配置 token 值优先于环境变量回退。`DIS 默认情况下，你的智能体只有在服务器频道中被 @提及时才会响应。对于私人服务器，你可能希望它响应每条消息。 - 在服务器频道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须通过 `message` 工具显式发送，因此智能体可以默认旁听，并且只在它判断频道回复有用时才发帖。 + 在服务器频道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须使用 `message` 工具显式发送，因此智能体可以默认旁观，并且仅在判断频道回复有用时发帖。 - > “允许我的智能体在这个服务器上响应，而不需要被 @提及” + > “允许我的智能体在此服务器上响应，而不必被 @提及” 在你的服务器配置中设置 `requireMention: false`： @@ -280,49 +280,53 @@ Token 解析会感知账户。配置 token 值优先于环境变量回退。`DIS } ``` - 要恢复群组/频道房间的旧版自动最终回复，请设置 `messages.groupChat.visibleReplies: "automatic"`。 + 要恢复旧版群组/频道房间的自动最终回复，请设置 `messages.groupChat.visibleReplies: "automatic"`。 - + 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。服务器频道不会自动加载 MEMORY.md。 - > “当我在 Discord 频道中提问时，如果你需要来自 MEMORY.md 的长期上下文，请使用 memory_search 或 memory_get。” + > “当我在 Discord 频道中提问时，如果你需要 MEMORY.md 中的长期上下文，请使用 memory_search 或 memory_get。” - 如果你需要在每个频道中共享上下文，请将稳定指令放入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并按需使用 memory 工具访问。 + 如果你需要每个频道中的共享上下文，请将稳定指令放入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话）。将长期笔记保存在 `MEMORY.md` 中，并按需使用记忆工具访问它们。 -现在在你的 Discord 服务器上创建一些频道并开始聊天。你的智能体可以看到频道名称，并且每个频道都会获得自己的隔离会话 —— 因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的频道。 +现在，在你的 Discord 服务器上创建一些频道并开始聊天。你的智能体可以看到频道名称，并且每个频道都会获得自己的隔离会话，所以你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的频道。 ## 运行时模型 -- Gateway 网关拥有 Discord 连接。 -- 回复路由是确定性的：Discord 入站回复会回到 Discord。 -- Discord 服务器/渠道元数据会作为不可信上下文加入模型提示，而不是作为用户可见的回复前缀。如果模型把该封套复制回来，OpenClaw 会从出站回复和未来回放上下文中移除复制的元数据。 +- Gateway 网关负责 Discord 连接。 +- 回复路由是确定性的：Discord 入站回复会回复到 Discord。 +- Discord 服务器/频道元数据会作为不受信任的上下文添加到模型提示中， + 而不是作为用户可见的回复前缀。如果模型把该信封复制回来， + OpenClaw 会从出站回复和未来的重放上下文中剥离复制的元数据。 - 默认情况下（`session.dmScope=main`），直接聊天共享智能体主会话（`agent:main:main`）。 -- 服务器渠道使用隔离的会话键（`agent::discord:channel:`）。 +- 服务器频道使用隔离的会话键（`agent::discord:channel:`）。 - 默认忽略群组私信（`channels.discord.dm.groupEnabled=false`）。 -- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 到路由后的对话会话。 -- 发送到 Discord 的纯文本 cron/Heartbeat 公告会使用最终的助手可见答案一次。媒体和结构化组件载荷在智能体发出多个可投递载荷时仍保持多消息形式。 +- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 到被路由的对话会话。 +- 发送到 Discord 的纯文本 cron/heartbeat 公告只使用一次最终的 + 助手可见回答。当智能体发出多个可投递 payload 时，媒体和结构化组件 payload + 仍会保持多消息形式。 -## 论坛渠道 +## 论坛频道 -Discord 论坛和媒体渠道只接受线程帖子。OpenClaw 支持两种创建方式： +Discord 论坛和媒体频道只接受线程帖子。OpenClaw 支持两种创建方式： -- 向论坛父级（`channel:`）发送消息以自动创建线程。线程标题使用你的消息中第一行非空内容。 -- 使用 `openclaw message thread create` 直接创建线程。对于论坛渠道，不要传入 `--message-id`。 +- 向论坛父频道（`channel:`）发送消息以自动创建线程。线程标题使用你的消息中第一行非空内容。 +- 使用 `openclaw message thread create` 直接创建线程。不要为论坛频道传入 `--message-id`。 -示例：发送到论坛父级以创建线程 +示例：发送到论坛父频道以创建线程 ```bash openclaw message send --channel discord --target channel: \ @@ -336,11 +340,11 @@ openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -论坛父级不接受 Discord 组件。如果需要组件，请发送到线程本身（`channel:`）。 +论坛父频道不接受 Discord 组件。如果你需要组件，请发送到线程本身（`channel:`）。 ## 交互式组件 -OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 `components` 载荷的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有 Discord `replyToMode` 设置。 +OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 `components` payload 的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 支持的块： @@ -348,11 +352,11 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - 操作行最多允许 5 个按钮或一个选择菜单 - 选择类型：`string`、`user`、`role`、`mentionable`、`channel` -默认情况下，组件为一次性使用。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前多次使用。 +默认情况下，组件只能使用一次。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前多次使用。 -要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到临时拒绝提示。 +要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及一个提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，且只有调用用户可以使用。 +`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及一个提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时消息，只有调用它的用户可以使用。 文件附件： @@ -420,7 +424,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` -## 访问控制与路由 +## 访问控制和路由 @@ -435,26 +439,26 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 多账户优先级： - - `channels.discord.accounts.default.allowFrom` 仅适用于 `default` 账户。 + - `channels.discord.accounts.default.allowFrom` 只应用于 `default` 账户。 - 对于一个账户，`allowFrom` 优先于旧版 `dm.allowFrom`。 - - 当命名账户自身的 `allowFrom` 和旧版 `dm.allowFrom` 均未设置时，会继承 `channels.discord.allowFrom`。 + - 当命名账户未设置自己的 `allowFrom` 和旧版 `dm.allowFrom` 时，会继承 `channels.discord.allowFrom`。 - 命名账户不会继承 `channels.discord.accounts.default.allowFrom`。 - 旧版 `channels.discord.dm.policy` 和 `channels.discord.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的情况下尽可能将它们迁移到 `dmPolicy` 和 `allowFrom`。 + 旧版 `channels.discord.dm.policy` 和 `channels.discord.dm.allowFrom` 仍会读取以保持兼容性。`openclaw doctor --fix` 会在不改变访问权限的前提下，将它们迁移到 `dmPolicy` 和 `allowFrom`。 - 用于投递的私信目标格式： + 投递用的私信目标格式： - `user:` - `<@id>` 提及 - 当渠道默认值处于活动状态时，裸数字 ID 通常会解析为渠道 ID，但账户有效私信 `allowFrom` 中列出的 ID 会为了兼容性被视为用户私信目标。 + 当频道默认值处于活动状态时，裸数字 ID 通常会解析为频道 ID，但为保持兼容性，账户有效私信 `allowFrom` 中列出的 ID 会被视为用户私信目标。 Discord 私信可以在 `channels.discord.allowFrom` 中使用动态 `accessGroup:` 条目。 - 访问组名称在消息渠道之间共享。对于成员以各渠道普通 `allowFrom` 语法表示的静态组，使用 `type: "message.senders"`；当 Discord 渠道当前的 `ViewChannel` 受众应动态定义成员资格时，使用 `type: "discord.channelAudience"`。共享访问组行为记录在这里：[访问组](/zh-CN/channels/access-groups)。 + 访问组名称在消息渠道之间共享。对于成员以每个渠道正常 `allowFrom` 语法表示的静态组，请使用 `type: "message.senders"`；当 Discord 频道当前的 `ViewChannel` 受众应动态定义成员资格时，请使用 `type: "discord.channelAudience"`。共享访问组行为记录在这里：[访问组](/zh-CN/channels/access-groups)。 ```json5 { @@ -477,9 +481,9 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - Discord 文本渠道没有单独的成员列表。`type: "discord.channelAudience"` 将成员资格建模为：私信发送者是已配置服务器的成员，并且在应用角色和渠道覆盖后，当前对已配置渠道拥有有效的 `ViewChannel` 权限。 + Discord 文本频道没有单独的成员列表。`type: "discord.channelAudience"` 将成员资格建模为：私信发送者是所配置服务器的成员，并且在应用角色和频道覆盖后，当前对所配置频道拥有有效的 `ViewChannel` 权限。 - 示例：允许任何能看到 `#maintainers` 的人向机器人发送私信，同时对其他所有人关闭私信。 + 示例：允许任何能看到 `#maintainers` 的人私信机器人，同时对其他所有人关闭私信。 ```json5 { @@ -520,9 +524,9 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 查询失败时默认拒绝。如果 Discord 返回 `Missing Access`、成员查询失败，或渠道属于不同服务器，则私信发送者会被视为未授权。 + 查找会失败关闭。如果 Discord 返回 `Missing Access`、成员查找失败，或频道属于其他服务器，则该私信发送者会被视为未授权。 - 使用渠道受众访问组时，请在 Discord Developer Portal 中为机器人启用 **Server Members Intent**。私信不包含服务器成员状态，因此 OpenClaw 会在授权时通过 Discord REST 解析成员。 + 使用频道受众访问组时，请在 Discord Developer Portal 中为机器人启用 **Server Members Intent**。私信不包含服务器成员状态，因此 OpenClaw 会在授权时通过 Discord REST 解析成员。 @@ -533,16 +537,16 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - `allowlist` - `disabled` - 当存在 `channels.discord` 时，安全基线是 `allowlist`。 + 当 `channels.discord` 存在时，安全基线是 `allowlist`。 `allowlist` 行为： - 服务器必须匹配 `channels.discord.guilds`（首选 `id`，也接受 slug） - - 可选发送者允许列表：`users`（建议使用稳定 ID）和 `roles`（仅角色 ID）；如果任一项已配置，发送者匹配 `users` 或 `roles` 时会被允许 - - 默认禁用直接名称/标签匹配；仅将 `channels.discord.dangerouslyAllowNameMatching: true` 作为应急兼容模式启用 + - 可选发送者允许列表：`users`（建议使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了任一项，发送者匹配 `users` 或 `roles` 即被允许 + - 默认禁用直接名称/标签匹配；仅在破窗兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true` - `users` 支持名称/标签，但 ID 更安全；使用名称/标签条目时，`openclaw security audit` 会发出警告 - - 如果服务器配置了 `channels`，未列出的渠道会被拒绝 - - 如果服务器没有 `channels` 块，则该允许列表服务器中的所有渠道都被允许 + - 如果某个服务器配置了 `channels`，未列出的频道会被拒绝 + - 如果某个服务器没有 `channels` 块，则该允许列表服务器中的所有频道都被允许 示例： @@ -568,33 +572,33 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 如果你只设置 `DISCORD_BOT_TOKEN`，但没有创建 `channels.discord` 块，则运行时回退为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open`。 + 如果你只设置了 `DISCORD_BOT_TOKEN`，并且没有创建 `channels.discord` 块，则运行时回退为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open`。 - 服务器消息默认需要提及。 + 服务器消息默认受提及门控。 提及检测包括： - 显式机器人提及 - - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 支持情况下的隐式回复机器人行为 + - 配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） + - 支持场景中的隐式回复机器人行为 - `requireMention` 按服务器/渠道配置（`channels.discord.guilds...`）。 + `requireMention` 按服务器/频道配置（`channels.discord.guilds...`）。 `ignoreOtherMentions` 可选择丢弃提及其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 群组私信： - 默认：忽略（`dm.groupEnabled=false`） - - 可选通过 `dm.groupChannels` 允许列表（渠道 ID 或 slug） + - 可选通过 `dm.groupChannels` 设置允许列表（频道 ID 或 slug） ### 基于角色的智能体路由 -使用 `bindings[].match.roles` 按角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并在 peer 或 parent-peer 绑定之后、仅服务器绑定之前求值。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 +使用 `bindings[].match.roles` 按角色 ID 将 Discord 服务器成员路由到不同的智能体。基于角色的绑定只接受角色 ID，并在对等或父对等绑定之后、仅服务器绑定之前求值。如果绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），所有已配置字段都必须匹配。 ```json5 { @@ -618,13 +622,13 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` -## 原生命令和命令鉴权 +## 原生命令和命令授权 - `commands.native` 默认为 `"auto"`，并为 Discord 启用。 - 单渠道覆盖：`channels.discord.commands.native`。 - `commands.native=false` 会显式清除先前注册的 Discord 原生命令。 -- 原生命令鉴权使用与普通消息处理相同的 Discord 允许列表/策略。 -- 对于未授权用户，命令可能仍会在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 鉴权并返回“未授权”。 +- 原生命令授权使用与普通消息处理相同的 Discord 允许列表/策略。 +- 对未授权用户，命令可能仍会显示在 Discord UI 中；执行时仍会强制执行 OpenClaw 授权并返回“未授权”。 有关命令目录和行为，请参阅[斜杠命令](/zh-CN/tools/slash-commands)。 @@ -648,18 +652,18 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - `all` - `batched` - 注意：`off` 会禁用隐式回复串联。显式 `[[reply_to_*]]` 标签仍会生效。 - `first` 始终会把隐式原生回复引用附加到本轮第一条传出的 Discord 消息。 - `batched` 仅在入站轮次是多条消息的防抖批次时，才会附加 Discord 的隐式原生回复引用。这在你希望原生回复主要用于含义不明确的突发聊天，而不是每个单消息轮次时很有用。 + 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。 + `first` 始终会把隐式原生回复引用附加到本轮第一条发出的 Discord 消息。 + `batched` 仅在入站轮次是由多条消息防抖合并成的批次时，才附加 Discord 的隐式原生回复引用。当你希望原生回复主要用于有歧义的密集聊天，而不是每个单消息轮次时，这很有用。 - 消息 ID 会在上下文/历史中暴露，因此智能体可以定位特定消息。 + 消息 ID 会在上下文/历史中暴露，因此智能体可以定向到特定消息。 OpenClaw 可以通过发送临时消息并在文本到达时编辑它来流式传输草稿回复。`channels.discord.streaming` 可取 `off`（默认）| `partial` | `block` | `progress`。在 Discord 上，`progress` 映射为 `partial`；`streamMode` 是旧版别名，会自动迁移。 - 默认保持为 `off`，因为当多个机器人或 Gateway 网关共享一个账号时，Discord 预览编辑很快会触发速率限制。 + 默认保持为 `off`，因为当多个机器人或 Gateway 网关共享一个账号时，Discord 预览编辑会很快触及速率限制。 ```json5 { @@ -676,12 +680,12 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - - `partial` 会在 token 到达时编辑单条预览消息。 + - `partial` 会在 token 到达时编辑同一条预览消息。 - `block` 会发出草稿大小的分块（使用 `draftChunk` 调整大小和断点，并限制在 `textChunkLimit` 内）。 - 媒体、错误和显式回复的最终消息会取消待处理的预览编辑。 - `streaming.preview.toolProgress`（默认 `true`）控制工具/进度更新是否复用预览消息。 - 预览流式传输仅支持文本；媒体回复会回退到普通投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。 + 预览流式传输仅支持文本；媒体回复会回退到正常投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 @@ -699,26 +703,26 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 线程行为： - - Discord 线程按渠道会话路由，并继承父渠道配置，除非被覆盖。 - - 线程会话会继承父渠道会话级 `/model` 选择，作为仅模型回退；线程本地的 `/model` 选择仍优先，并且除非启用转录继承，否则不会复制父转录历史。 - - `channels.discord.thread.inheritParent`（默认 `false`）会让新的自动线程从父转录播种。按账号覆盖项位于 `channels.discord.accounts..thread.inheritParent` 下。 + - Discord 线程会按渠道会话路由，并继承父渠道配置，除非被覆盖。 + - 线程会话会继承父渠道会话级 `/model` 选择，作为仅模型回退；线程本地的 `/model` 选择仍然优先，且除非启用转录继承，否则不会复制父级转录历史。 + - `channels.discord.thread.inheritParent`（默认 `false`）会让新的自动线程选择从父级转录中播种。按账号覆盖项位于 `channels.discord.accounts..thread.inheritParent` 下。 - 消息工具反应可以解析 `user:` 私信目标。 - `guilds..channels..requireMention: false` 会在回复阶段激活回退期间保留。 - 渠道主题会作为**不可信**上下文注入。允许列表会限制谁能触发智能体，但不是完整的补充上下文脱敏边界。 + 渠道主题会作为**不可信**上下文注入。允许列表控制谁能触发智能体，而不是完整的补充上下文脱敏边界。 - - Discord 可以将线程绑定到会话目标，这样该线程中的后续消息会继续路由到同一个会话（包括子智能体会话）。 + + Discord 可以把线程绑定到会话目标，这样该线程中的后续消息会继续路由到同一个会话（包括子智能体会话）。 命令： - `/focus ` 将当前/新线程绑定到子智能体/会话目标 - `/unfocus` 移除当前线程绑定 - - `/agents` 显示活动运行和绑定状态 - - `/session idle ` 查看/更新聚焦绑定的非活动自动取消聚焦 - - `/session max-age ` 查看/更新聚焦绑定的硬性最大存续时间 + - `/agents` 显示活跃运行和绑定状态 + - `/session idle ` 查看/更新聚焦绑定的不活跃自动取消聚焦时间 + - `/session max-age ` 查看/更新聚焦绑定的硬性最长存活时间 配置： @@ -744,24 +748,24 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 备注： + 说明： - `session.threadBindings.*` 设置全局默认值。 - `channels.discord.threadBindings.*` 覆盖 Discord 行为。 - - `spawnSubagentSessions` 必须为 true，才能为 `sessions_spawn({ thread: true })` 自动创建/绑定线程。 - - `spawnAcpSessions` 必须为 true，才能为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建/绑定线程。 - - 如果某个账号禁用了线程绑定，`/focus` 和相关线程绑定操作将不可用。 + - 必须将 `spawnSubagentSessions` 设为 true，才能为 `sessions_spawn({ thread: true })` 自动创建/绑定线程。 + - 必须将 `spawnAcpSessions` 设为 true，才能为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建/绑定线程。 + - 如果某个账号禁用了线程绑定，则 `/focus` 和相关线程绑定操作不可用。 参见[子智能体](/zh-CN/tools/subagents)、[ACP 智能体](/zh-CN/tools/acp-agents)和[配置参考](/zh-CN/gateway/configuration-reference)。 - 对于稳定的“始终在线”ACP 工作区，请配置顶层类型化 ACP 绑定，以定位 Discord 对话。 + 对于稳定的“always-on” ACP 工作区，请配置面向 Discord 对话的顶层类型化 ACP 绑定。 配置路径： - - `bindings[]`，其中包含 `type: "acp"` 和 `match.channel: "discord"` + - `bindings[]`，包含 `type: "acp"` 和 `match.channel: "discord"` 示例： @@ -811,10 +815,10 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 备注： + 说明： - - `/acp spawn codex --bind here` 会就地绑定当前渠道或线程，并让未来消息保持在同一个 ACP 会话上。线程消息会继承父渠道绑定。 - - 在已绑定的渠道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时线程绑定在活动期间可以覆盖目标解析。 + - `/acp spawn codex --bind here` 会就地绑定当前渠道或线程，并让后续消息保持在同一个 ACP 会话上。线程消息会继承父渠道绑定。 + - 在绑定的渠道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时线程绑定在活跃期间可以覆盖目标解析。 - 只有当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子线程时，才需要 `spawnAcpSessions`。 参见 [ACP 智能体](/zh-CN/tools/acp-agents)了解绑定行为详情。 @@ -843,17 +847,17 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - `messages.ackReaction` - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） - 备注： + 说明： - Discord 接受 Unicode 表情符号或自定义表情符号名称。 - - 使用 `""` 可禁用某个渠道或账号的反应。 + - 使用 `""` 可为某个渠道或账号禁用该反应。 默认启用由渠道发起的配置写入。 - 这会影响 `/config set|unset` 流程（当命令功能启用时）。 + 这会影响 `/config set|unset` 流程（当命令功能已启用时）。 禁用方式： @@ -870,7 +874,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - 通过 HTTP(S) 代理使用 `channels.discord.proxy` 路由 Discord gateway WebSocket 流量和启动 REST 查询（应用 ID + 允许列表解析）。 + 使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord gateway WebSocket 流量和启动时 REST 查询（应用程序 ID + 允许列表解析）。 ```json5 { @@ -916,19 +920,43 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 备注： + 说明： - 允许列表可以使用 `pk:` - - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名称 + - 只有当 `channels.discord.dangerouslyAllowNameMatching: true` 时，成员显示名称才会按名称/slug 匹配 - 查询使用原始消息 ID，并受时间窗口限制 - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非 `allowBots=true` - - 当你设置 Status 或活动字段，或启用自动 presence 时，会应用 presence 更新。 + + 当智能体需要对已知 Discord 用户进行确定性的出站提及时，使用 `mentionAliases`。键是不带前导 `@` 的 handle；值是 Discord 用户 ID。未知 handle、`@everyone`、`@here` 以及 Markdown 代码跨度中的提及会保持不变。 - 仅 Status 示例： +```json5 +{ + channels: { + discord: { + mentionAliases: { + Vladislava: "123456789012345678", + }, + accounts: { + ops: { + mentionAliases: { + OpsLead: "234567890123456789", + }, + }, + }, + }, + }, +} +``` + + + + + 当你设置状态或活动字段，或启用自动在线状态时，会应用在线状态更新。 + + 仅状态示例： ```json5 { @@ -940,7 +968,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 活动示例（自定义 Status 是默认活动类型）： + 活动示例（自定义状态是默认活动类型）： ```json5 { @@ -953,7 +981,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 流式示例： + 流式活动示例： ```json5 { @@ -969,14 +997,14 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 活动类型映射： - - 0：正在玩 - - 1：正在直播（需要 `activityUrl`） - - 2：正在听 - - 3：正在看 - - 4：自定义（使用活动文本作为 Status 状态；表情符号可选） - - 5：正在比赛 + - 0: 正在玩 + - 1: 正在直播（需要 `activityUrl`） + - 2: 正在听 + - 3: 正在看 + - 4: 自定义（使用活动文本作为状态 state；表情符号可选） + - 5: 正在竞赛 - 自动 presence 示例（运行时健康信号）： + 自动在线状态示例（运行时健康信号）： ```json5 { @@ -993,7 +1021,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 自动 presence 会将运行时可用性映射到 Discord Status：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖项： + 自动在线状态会把运行时可用性映射到 Discord 状态：健康 => 在线，降级或未知 => 空闲，耗尽或不可用 => 请勿打扰。可选文本覆盖项： - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -1002,7 +1030,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - Discord 支持在私信中进行基于按钮的审批处理，并且可以选择在原始渠道中发布审批提示。 + Discord 支持在私信中基于按钮处理审批，并可选择在来源渠道发布审批提示。 配置路径： @@ -1011,59 +1039,59 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` - 当 `enabled` 未设置或为 `"auto"`，并且至少能从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个审批人时，Discord 会自动启用原生 exec 审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或直接消息 `defaultTo` 推断 exec 审批人。设置 `enabled: false` 可显式禁用 Discord 作为原生审批客户端。 + 当 `enabled` 未设置或为 `"auto"`，并且至少可以解析出一个审批者时，Discord 会自动启用原生 exec 审批；审批者可以来自 `execApprovals.approvers` 或 `commands.ownerAllowFrom`。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或直接消息 `defaultTo` 推断 exec 审批者。设置 `enabled: false` 可明确禁用 Discord 作为原生审批客户端。 - 对于敏感的仅限所有者使用的群组命令，例如 `/diagnostics` 和 `/export-trajectory`，OpenClaw 会私下发送审批提示和最终结果。当调用的所有者拥有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 + 对于 `/diagnostics` 和 `/export-trajectory` 等敏感的仅所有者可用群组命令，OpenClaw 会私下发送审批提示和最终结果。当发起命令的所有者有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 - 当 `target` 为 `channel` 或 `both` 时，审批提示会显示在渠道中。只有解析出的审批者可以使用按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此只应在受信任的渠道中启用渠道投递。如果无法从会话键推导出渠道 ID，OpenClaw 会回退为私信投递。 + 当 `target` 是 `channel` 或 `both` 时，审批提示会在渠道中可见。只有解析出的审批者可以使用按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此仅在受信任的渠道中启用渠道投递。如果无法从会话键派生渠道 ID，OpenClaw 会回退到私信投递。 - Discord 也会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要增加审批者私信路由和渠道扇出。 - 当这些按钮存在时，它们就是主要审批用户体验；OpenClaw - 只应在工具结果表示聊天审批不可用，或手动审批是唯一路径时，才包含手动 `/approve` 命令。 - 如果 Discord 原生审批运行时未处于活动状态，OpenClaw 会保留 + Discord 也会呈现其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要添加审批者私信路由和渠道扇出。 + 当这些按钮存在时，它们是主要审批 UX；OpenClaw + 只有在工具结果表明聊天审批不可用，或手动审批是唯一路径时，才应包含手动 `/approve` 命令。 + 如果 Discord 原生审批运行时未激活，OpenClaw 会保留 本地确定性的 `/approve ` 提示可见。如果 - 运行时处于活动状态，但原生卡片无法投递到任何目标， - OpenClaw 会发送同一聊天回退通知，其中包含待处理审批里的精确 `/approve` + 运行时已激活但原生卡片无法投递到任何目标， + OpenClaw 会在同一聊天中发送回退通知，其中包含待审批项中的确切 `/approve` 命令。 - Gateway 网关认证和审批解析遵循共享 Gateway 网关客户端合约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。审批默认在 30 分钟后过期。 + Gateway 网关身份验证和审批解析遵循共享的 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。审批默认在 30 分钟后过期。 - 参见 [Exec 审批](/zh-CN/tools/exec-approvals)。 + 请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)。 -## 工具和操作门禁 +## 工具和操作门控 -Discord 消息操作包括消息收发、渠道管理、审核、在线状态和元数据操作。 +Discord 消息操作包括消息传递、渠道管理、审核、在线状态和元数据操作。 核心示例： -- 消息收发：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` +- 消息传递：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` - 表情回应：`react`、`reactions`、`emojiList` - 审核：`timeout`、`kick`、`ban` - 在线状态：`setPresence` -`event-create` 操作接受可选的 `image` 参数（URL 或本地文件路径），用于设置预定事件封面图。 +`event-create` 操作接受可选的 `image` 参数（URL 或本地文件路径），用于设置定时事件封面图片。 -操作门禁位于 `channels.discord.actions.*` 下。 +操作门控位于 `channels.discord.actions.*` 下。 -默认门禁行为： +默认门控行为： -| 操作组 | 默认值 | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 已启用 | -| roles | 已禁用 | -| moderation | 已禁用 | -| presence | 已禁用 | +| 操作组 | 默认值 | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | enabled | +| roles | disabled | +| moderation | disabled | +| presence | disabled | -## 组件 v2 界面 +## Components v2 UI -OpenClaw 使用 Discord 组件 v2 来处理 exec 审批和跨上下文标记。Discord 消息操作也可以接受 `components` 作为自定义界面（高级用法；需要通过 discord 工具构造组件载荷），而旧版 `embeds` 仍然可用，但不推荐。 +OpenClaw 使用 Discord components v2 处理 exec 审批和跨上下文标记。Discord 消息操作也可以接受 `components` 来实现自定义 UI（高级用法；需要通过 discord 工具构造组件载荷），而旧版 `embeds` 仍然可用，但不推荐使用。 - `channels.discord.ui.components.accentColor` 设置 Discord 组件容器使用的强调色（十六进制）。 -- 使用 `channels.discord.accounts..ui.components.accentColor` 按账户设置。 -- 当组件 v2 存在时，`embeds` 会被忽略。 +- 使用 `channels.discord.accounts..ui.components.accentColor` 为每个账号设置。 +- 当 components v2 存在时，`embeds` 会被忽略。 示例： @@ -1083,20 +1111,20 @@ OpenClaw 使用 Discord 组件 v2 来处理 exec 审批和跨上下文标记。D ## 语音 -Discord 有两个不同的语音表面：实时 **语音频道**（连续对话）和 **语音消息附件**（波形预览格式）。Gateway 网关同时支持两者。 +Discord 有两个不同的语音表面：实时**语音渠道**（持续对话）和**语音消息附件**（波形预览格式）。Gateway 网关同时支持两者。 -### 语音频道 +### 语音渠道 -设置检查清单： +设置清单： 1. 在 Discord Developer Portal 中启用 Message Content Intent。 2. 使用角色/用户允许列表时，启用 Server Members Intent。 -3. 使用 `bot` 和 `applications.commands` scopes 邀请机器人。 -4. 在目标语音频道中授予 Connect、Speak、Send Messages 和 Read Message History。 +3. 使用 `bot` 和 `applications.commands` 作用域邀请机器人。 +4. 在目标语音渠道中授予 Connect、Speak、Send Messages 和 Read Message History 权限。 5. 启用原生命令（`commands.native` 或 `channels.discord.commands.native`）。 6. 配置 `channels.discord.voice`。 -使用 `/vc join|leave|status` 控制会话。该命令使用账户默认智能体，并遵循与其他 Discord 命令相同的允许列表和组策略规则。 +使用 `/vc join|leave|status` 控制会话。该命令使用账号默认智能体，并遵循与其他 Discord 命令相同的允许列表和群组策略规则。 ```bash /vc join channel: @@ -1133,37 +1161,37 @@ Discord 有两个不同的语音表面：实时 **语音频道**（连续对话 } ``` -注意事项： +说明： - `voice.tts` 仅覆盖语音播放的 `messages.tts`。 -- `voice.model` 仅覆盖用于 Discord 语音频道响应的 LLM。保持未设置可继承路由后的智能体模型。 +- `voice.model` 仅覆盖用于 Discord 语音渠道响应的 LLM。保持未设置即可继承路由智能体模型。 - STT 使用 `tools.media.audio`；`voice.model` 不影响转写。 -- 按频道设置的 Discord `systemPrompt` 覆盖会应用于该语音频道的语音转写轮次。 -- 语音转写轮次从 Discord `allowFrom`（或 `dm.allowFrom`）推导所有者状态；非所有者说话者无法访问仅所有者工具（例如 `gateway` 和 `cron`）。 -- Discord 语音对于纯文本配置是选择启用的；设置 `channels.discord.voice.enabled=true`（或保留现有 `channels.discord.voice` 块）以启用 `/vc` 命令、语音运行时和 `GuildVoiceStates` gateway intent。 +- 每渠道的 Discord `systemPrompt` 覆盖会应用于该语音渠道的语音转写轮次。 +- 语音转写轮次从 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者说话者无法访问仅所有者可用工具（例如 `gateway` 和 `cron`）。 +- 对于纯文本配置，Discord 语音是选择加入；设置 `channels.discord.voice.enabled=true`（或保留现有的 `channels.discord.voice` 块）即可启用 `/vc` 命令、语音运行时以及 `GuildVoiceStates` Gateway 网关 intent。 - `channels.discord.intents.voiceStates` 可以显式覆盖语音状态 intent 订阅。保持未设置可让 intent 跟随有效的语音启用状态。 -- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` join options。 +- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` 加入选项。 - 如果未设置，`@discordjs/voice` 默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 - `voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试的初始 `@discordjs/voice` Ready 等待时间。默认值：`30000`。 -- `voice.reconnectGraceMs` 控制 OpenClaw 在销毁断开的语音会话之前，等待它开始重新连接的时长。默认值：`15000`。 -- OpenClaw 还会监控接收解密失败，并在短时间窗口内反复失败后，通过离开并重新加入语音频道自动恢复。 -- 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 版本线包含来自 discord.js PR #11449 的上游 padding 修复，该修复关闭了 discord.js issue #11419。 +- `voice.reconnectGraceMs` 控制 OpenClaw 在销毁已断开的语音会话之前，等待其开始重新连接的时长。默认值：`15000`。 +- OpenClaw 还会监视接收解密失败，并在短时间窗口内反复失败后通过离开/重新加入语音渠道自动恢复。 +- 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 系列包含来自 discord.js PR #11449 的上游 padding 修复，该修复关闭了 discord.js issue #11419。 -语音频道管线： +语音渠道流水线： - Discord PCM 捕获会转换为 WAV 临时文件。 - `tools.media.audio` 处理 STT，例如 `openai/gpt-4o-mini-transcribe`。 - 转写文本会通过 Discord 入口和路由发送，同时响应 LLM 使用语音输出策略运行，该策略会隐藏智能体 `tts` 工具并要求返回文本，因为 Discord 语音负责最终 TTS 播放。 -- 设置 `voice.model` 时，它仅覆盖此语音频道轮次的响应 LLM。 -- `voice.tts` 会合并覆盖 `messages.tts`；生成的音频会在已加入的频道中播放。 +- 设置 `voice.model` 时，它只覆盖此语音渠道轮次的响应 LLM。 +- `voice.tts` 会合并覆盖 `messages.tts`；生成的音频会在已加入的渠道中播放。 -凭证按组件解析：`voice.model` 的 LLM 路由认证、`tools.media.audio` 的 STT 认证，以及 `messages.tts`/`voice.tts` 的 TTS 认证。 +凭证按组件解析：`voice.model` 的 LLM 路由身份验证、`tools.media.audio` 的 STT 身份验证，以及 `messages.tts`/`voice.tts` 的 TTS 身份验证。 ### 语音消息 -Discord 语音消息会显示波形预览，并要求 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要 Gateway 网关主机上有 `ffmpeg` 和 `ffprobe` 来检查和转换。 +Discord 语音消息显示波形预览，并需要 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要 Gateway 网关主机上的 `ffmpeg` 和 `ffprobe` 来检查和转换。 -- 提供 **本地文件路径**（URL 会被拒绝）。 +- 提供**本地文件路径**（URL 会被拒绝）。 - 省略文本内容（Discord 会拒绝同一载荷中的文本 + 语音消息）。 - 接受任何音频格式；OpenClaw 会按需转换为 OGG/Opus。 @@ -1174,7 +1202,7 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## 故障排除 - + - 启用 Message Content Intent - 当你依赖用户/成员解析时，启用 Server Members Intent @@ -1182,12 +1210,12 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a - + - 验证 `groupPolicy` - - 验证 `channels.discord.guilds` 下的 guild 允许列表 - - 如果 guild `channels` 映射存在，则只允许列出的渠道 - - 验证 `requireMention` 行为和 mention 模式 + - 验证 `channels.discord.guilds` 下的服务器允许列表 + - 如果服务器 `channels` 映射存在，则只允许列出的渠道 + - 验证 `requireMention` 行为和提及模式 有用的检查： @@ -1199,12 +1227,12 @@ openclaw logs --follow - + 常见原因： - - `groupPolicy="allowlist"` 但没有匹配的 guild/渠道允许列表 - - `requireMention` 配置在了错误位置（必须位于 `channels.discord.guilds` 或渠道条目下） - - 发送者被 guild/渠道 `users` 允许列表阻止 + - `groupPolicy="allowlist"` 没有匹配的服务器/渠道允许列表 + - `requireMention` 配置在错误的位置（必须位于 `channels.discord.guilds` 或渠道条目下） + - 发送者被服务器/渠道 `users` 允许列表阻止 @@ -1217,11 +1245,11 @@ openclaw logs --follow Discord Gateway 网关队列调节项： - - 单账户：`channels.discord.eventQueue.listenerTimeout` - - 多账户：`channels.discord.accounts..eventQueue.listenerTimeout` - - 这只控制 Discord Gateway 网关监听器工作，而不是智能体轮次生命周期 + - 单账号：`channels.discord.eventQueue.listenerTimeout` + - 多账号：`channels.discord.accounts..eventQueue.listenerTimeout` + - 这只控制 Discord Gateway 网关监听器工作，不控制智能体轮次生命周期 - Discord 不会对已排队的智能体轮次应用渠道拥有的超时。消息监听器会立即移交，并且已排队的 Discord 运行会保留每会话排序，直到会话/工具/运行时生命周期完成或中止该工作。 + Discord 不会对排队的智能体轮次应用渠道拥有的超时。消息监听器会立即移交，排队的 Discord 运行会保留每会话顺序，直到会话/工具/运行时生命周期完成或中止该工作。 ```json5 { @@ -1242,37 +1270,37 @@ openclaw logs --follow - OpenClaw 会在连接前获取 Discord `/gateway/bot` 元数据。瞬时失败会回退到 Discord 的默认 Gateway 网关 URL，并在日志中受到速率限制。 + OpenClaw 在连接前获取 Discord `/gateway/bot` 元数据。临时失败会回退到 Discord 的默认 Gateway 网关 URL，并在日志中限速记录。 元数据超时调节项： - - 单账户：`channels.discord.gatewayInfoTimeoutMs` - - 多账户：`channels.discord.accounts..gatewayInfoTimeoutMs` + - 单账号：`channels.discord.gatewayInfoTimeoutMs` + - 多账号：`channels.discord.accounts..gatewayInfoTimeoutMs` - 配置未设置时的环境变量回退：`OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` - 默认值：`30000`（30 秒），最大值：`120000` - OpenClaw 会在启动期间和运行时重新连接后等待 Discord 的 gateway `READY` 事件。采用启动错峰的多账户设置可能需要比默认值更长的启动 READY 窗口。 + OpenClaw 会在启动期间以及运行时重新连接后等待 Discord 的 Gateway 网关 `READY` 事件。带有启动错峰的多账号设置可能需要比默认值更长的启动 READY 窗口。 READY 超时调节项： - - 启动单账户：`channels.discord.gatewayReadyTimeoutMs` - - 启动多账户：`channels.discord.accounts..gatewayReadyTimeoutMs` + - 启动单账号：`channels.discord.gatewayReadyTimeoutMs` + - 启动多账号：`channels.discord.accounts..gatewayReadyTimeoutMs` - 配置未设置时的启动环境变量回退：`OPENCLAW_DISCORD_READY_TIMEOUT_MS` - 启动默认值：`15000`（15 秒），最大值：`120000` - - 运行时单账户：`channels.discord.gatewayRuntimeReadyTimeoutMs` - - 运行时多账户：`channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` + - 运行时单账号：`channels.discord.gatewayRuntimeReadyTimeoutMs` + - 运行时多账号：`channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` - 配置未设置时的运行时环境变量回退：`OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` - 运行时默认值：`30000`（30 秒），最大值：`120000` - - `channels status --probe` 权限检查仅适用于数字渠道 ID。 + + `channels status --probe` 权限检查仅适用于数字型渠道 ID。 - 如果你使用 slug 键，运行时匹配仍然可以工作，但探测无法完全验证权限。 + 如果你使用 slug 键，运行时匹配仍然可以工作，但探测无法完整验证权限。 @@ -1284,23 +1312,23 @@ openclaw logs --follow - - 默认情况下会忽略机器人发送的消息。 + + 默认会忽略机器人发送的消息。 - 如果你设置了 `channels.discord.allowBots=true`，请使用严格的提及和允许列表规则来避免循环行为。 + 如果你设置 `channels.discord.allowBots=true`，请使用严格的提及和允许列表规则，以避免循环行为。 优先使用 `channels.discord.allowBots="mentions"`，仅接受提及该机器人的机器人消息。 - + - - 保持 OpenClaw 为最新版本（`openclaw update`），以确保 Discord 语音接收恢复逻辑可用 - - 确认 `channels.discord.voice.daveEncryption=true`（默认） + - 保持 OpenClaw 为最新版本（`openclaw update`），以确保包含 Discord 语音接收恢复逻辑 + - 确认 `channels.discord.voice.daveEncryption=true`（默认值） - 从 `channels.discord.voice.decryptionFailureTolerance=24`（上游默认值）开始，仅在需要时调整 - - 观察日志中的： + - 查看日志中是否出现： - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - 如果自动重新加入后故障仍然持续，请收集日志，并与 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) 和 [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) 中的上游 DAVE 接收历史进行比较 + - 如果自动重新加入后仍然失败，请收集日志，并与 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) 和 [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) 中的上游 DAVE 接收历史进行对比 @@ -1309,17 +1337,17 @@ openclaw logs --follow 主要参考：[配置参考 - Discord](/zh-CN/gateway/config-channels#discord)。 - + -- 启动/认证：`enabled`、`token`、`accounts.*`、`allowBots` +- 启动/身份验证：`enabled`、`token`、`accounts.*`、`allowBots` - 策略：`groupPolicy`、`dm.*`、`guilds.*`、`guilds.*.channels.*` - 命令：`commands.native`、`commands.useAccessGroups`、`configWrites`、`slashCommand.*` - 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` - Gateway 网关：`gatewayInfoTimeoutMs`、`gatewayReadyTimeoutMs`、`gatewayRuntimeReadyTimeoutMs` -- 回复/历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` -- 投递：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` +- 回复/历史记录：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` +- 递送：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` - 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` -- 媒体/重试：`mediaMaxMb`（限制 Discord 出站上传，默认 `100MB`）、`retry` +- 媒体/重试：`mediaMaxMb`（限制出站 Discord 上传，默认 `100MB`）、`retry` - 操作：`actions.*` - 在线状态：`activity`、`status`、`activityType`、`activityUrl` - UI：`ui.components.accentColor` @@ -1329,18 +1357,18 @@ openclaw logs --follow ## 安全和运维 -- 将机器人令牌视为密钥（受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 +- 将机器人令牌视为密钥（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 - 授予最小权限的 Discord 权限。 -- 如果命令部署/状态已过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。 +- 如果命令部署/状态已过期，请重启 Gateway 网关，并用 `openclaw channels status --probe` 重新检查。 -## 相关 +## 相关内容 将 Discord 用户配对到 Gateway 网关。 - 群聊和允许列表行为。 + 群组聊天和允许列表行为。 将入站消息路由到智能体。 diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index 95d0a3965..14e692a96 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -1,49 +1,49 @@ --- read_when: - - 设置 Slack 或调试 Slack 套接字/HTTP 模式 -summary: Slack 设置和运行时行为（Socket 模式 + HTTP 请求 URL） + - 设置 Slack 或调试 Slack socket/HTTP 模式 +summary: Slack 设置和运行时行为（Socket Mode + HTTP 请求 URL） title: Slack x-i18n: - generated_at: "2026-05-01T13:24:13Z" + generated_at: "2026-05-02T02:58:10Z" model: gpt-5.5 provider: openai - source_hash: d2b065eab0e80dc223d33d0e0c8210e1ff05ff24426f7a335885540c9eb42ae9 + source_hash: 82dbc27617415cb21e3c682d58c8a8a7f56c7471af0b43d5fcbb5df3fa872a49 source_path: channels/slack.md workflow: 16 --- -已可通过 Slack 应用集成用于生产环境中的私信和渠道。默认模式是 Socket Mode；也支持 HTTP Request URLs。 +Production-ready for DMs and channels via Slack app integrations. Default mode is Socket Mode; HTTP Request URLs are also supported. - Slack 私信默认使用配对模式。 + Slack DMs default to pairing mode. - 原生命令行为和命令目录。 + Native command behavior and command catalog. - 跨渠道诊断和修复手册。 + Cross-channel diagnostics and repair playbooks. -## 快速设置 +## Quick setup - 在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮： + In Slack app settings press the **[Create New App](https://api.slack.com/apps/new)** button: - - 选择 **from a manifest** 并为你的应用选择一个工作区 - - 粘贴下面的[示例清单](#manifest-and-scope-checklist)，然后继续创建 - - 生成一个具有 `connections:write` 权限的 **App-Level Token**（`xapp-...`） - - 安装应用并复制显示的 **Bot Token**（`xoxb-...`） + - choose **from a manifest** and select a workspace for your app + - paste the [example manifest](#manifest-and-scope-checklist) from below and continue to create + - generate an **App-Level Token** (`xapp-...`) with `connections:write` + - install app and copy the **Bot Token** (`xoxb-...`) shown - 推荐的 SecretRef 设置： + Recommended SecretRef setup: ```bash export SLACK_APP_TOKEN=xapp-... @@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run openclaw config patch --file ./slack.socket.patch.json5 ``` - 环境变量回退（仅默认账号）： + Env fallback (default account only): ```bash SLACK_APP_TOKEN=xapp-... @@ -87,18 +87,18 @@ openclaw gateway - 在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮： + In Slack app settings press the **[Create New App](https://api.slack.com/apps/new)** button: - - 选择 **from a manifest** 并为你的应用选择一个工作区 - - 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL - - 保存用于请求验证的 **Signing Secret** - - 安装应用并复制显示的 **Bot Token**（`xoxb-...`） + - choose **from a manifest** and select a workspace for your app + - paste the [example manifest](#manifest-and-scope-checklist) and update the URLs before create + - save the **Signing Secret** for request verification + - install app and copy the **Bot Token** (`xoxb-...`) shown - 推荐的 SecretRef 设置： + Recommended SecretRef setup: ```bash export SLACK_BOT_TOKEN=xoxb-... @@ -121,9 +121,9 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - 为多账号 HTTP 使用唯一的 webhook 路径 + Use unique webhook paths for multi-account HTTP - 为每个账号提供不同的 `webhookPath`（默认 `/slack/events`），这样注册不会冲突。 + Give each account a distinct `webhookPath` (default `/slack/events`) so registrations do not collide. @@ -140,9 +140,9 @@ openclaw gateway -## Socket Mode 传输调优 +## Socket Mode transport tuning -对于 Socket Mode，OpenClaw 默认将 Slack SDK 客户端 pong 超时设置为 15 秒。只有在需要针对工作区或主机进行特定调优时，才覆盖传输设置： +OpenClaw sets the Slack SDK client pong timeout to 15 seconds by default for Socket Mode. Override the transport settings only when you need workspace- or host-specific tuning: ```json5 { @@ -159,13 +159,13 @@ openclaw gateway } ``` -仅对记录 Slack websocket pong/server-ping 超时，或运行在已知存在事件循环饥饿问题主机上的 Socket Mode 工作区使用此配置。`clientPingTimeout` 是 SDK 发送客户端 ping 后等待 pong 的时间；`serverPingTimeout` 是等待 Slack 服务器 ping 的时间。应用消息和事件仍然是应用状态，而不是传输活跃性信号。 +Use this only for Socket Mode workspaces that log Slack websocket pong/server-ping timeouts or run on hosts with known event-loop starvation. `clientPingTimeout` is the pong wait after the SDK sends a client ping; `serverPingTimeout` is the wait for Slack server pings. App messages and events remain application state, not transport liveness signals. -## 清单和 scope 检查清单 +## Manifest and scope checklist -基础 Slack 应用清单对于 Socket Mode 和 HTTP Request URLs 相同。只有 `settings` 块（以及斜杠命令的 `url`）不同。 +The base Slack app manifest is the same for Socket Mode and HTTP Request URLs. Only the `settings` block (and the slash command `url`) differs. -基础清单（Socket Mode 默认）： +Base manifest (Socket Mode default): ```json { @@ -212,6 +212,7 @@ openclaw gateway "pins:write", "reactions:read", "reactions:write", + "usergroups:read", "users:read" ] } @@ -239,7 +240,7 @@ openclaw gateway } ``` -对于 **HTTP Request URLs 模式**，将 `settings` 替换为 HTTP 变体，并为每个斜杠命令添加 `url`。需要公开 URL： +For **HTTP Request URLs mode**, replace `settings` with the HTTP variant and add `url` to each slash command. Public URL required: ```json { @@ -269,21 +270,21 @@ openclaw gateway } ``` -### 其他清单设置 +### Additional manifest settings -公开不同功能，以扩展上述默认值。 +Surface different features that extend the above defaults. -默认清单启用 Slack App Home 的 **Home** 标签页，并订阅 `app_home_opened`。当工作区成员打开 Home 标签页时，OpenClaw 会通过 `views.publish` 发布一个安全的默认 Home 视图；其中不包含对话载荷或私有配置。**Messages** 标签页仍为 Slack 私信启用。 +The default manifest enables the Slack App Home **Home** tab and subscribes to `app_home_opened`. When a workspace member opens the Home tab, OpenClaw publishes a safe default Home view with `views.publish`; no conversation payload or private configuration is included. The **Messages** tab remains enabled for Slack DMs. - 可以使用多个[原生斜杠命令](#commands-and-slash-behavior)，而不是单个已配置命令，但有一些细节： + Multiple [native slash commands](#commands-and-slash-behavior) can be used instead of a single configured command with nuance: - - 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已保留。 - - 一次最多只能提供 25 个斜杠命令。 + - Use `/agentstatus` instead of `/status` because the `/status` command is reserved. + - No more than 25 slash commands can be made available at once. - 将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)的一个子集： + Replace your existing `features.slash_commands` section with a subset of [available commands](/zh-CN/tools/slash-commands#command-list): @@ -403,7 +404,7 @@ openclaw gateway - 使用与上方 Socket Mode 相同的 `slash_commands` 列表，并为每个条目添加 `"url": "https://gateway-host.example.com/slack/events"`。示例： + Use the same `slash_commands` list as Socket Mode above, and add `"url": "https://gateway-host.example.com/slack/events"` to every entry. Example: ```json "slash_commands": [ @@ -427,13 +428,13 @@ openclaw gateway - 如果你希望出站消息使用当前智能体身份（自定义用户名和图标），而不是默认 Slack 应用身份，请添加 `chat:write.customize` bot scope。 + Add the `chat:write.customize` bot scope if you want outgoing messages to use the active agent identity (custom username and icon) instead of the default Slack app identity. - 如果你使用 emoji 图标，Slack 要求使用 `:emoji_name:` 语法。 + If you use an emoji icon, Slack expects `:emoji_name:` syntax. - 如果你配置了 `channels.slack.userToken`，典型的读取 scope 包括： + 如果你配置了 `channels.slack.userToken`，典型的读取作用域为： - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -454,21 +455,21 @@ openclaw gateway 字符串或 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 或其他非内联密钥来源配置，但当前命令/运行时路径 无法解析实际值。 -- 在 HTTP 模式中，会包含 `signingSecretStatus`；在 Socket Mode 中， - 必需组合是 `botTokenStatus` + `appTokenStatus`。 +- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下， + 必需的组合是 `botTokenStatus` + `appTokenStatus`。 -对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍优先使用机器人令牌；只有当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许用户令牌写入。 +对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍优先使用机器人令牌；仅当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许用户令牌写入。 ## 操作和门控 @@ -479,19 +480,19 @@ 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，并为图片返回图片预览，或为其他文件类型返回本地文件元数据。 +当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并为图像返回图像预览，或为其他文件类型返回本地文件元数据。 ## 访问控制和路由 - `channels.slack.dmPolicy` 控制私信访问。`channels.slack.allowFrom` 是规范私信允许列表。 + `channels.slack.dmPolicy` 控制私信访问。`channels.slack.allowFrom` 是规范的私信允许列表。 - `pairing`（默认） - `allowlist` @@ -509,10 +510,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 `。 @@ -525,20 +526,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`）。 名称/ID 解析： - 当令牌访问允许时，渠道允许列表条目和私信允许列表条目会在启动时解析 - - 未解析的渠道名称条目会按配置保留，但默认在路由时忽略 - - 入站授权和渠道路由默认优先使用 ID；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true` + - 未解析的渠道名称条目会按配置保留，但默认会在路由中被忽略 + - 入站授权和渠道路由默认优先使用 ID；直接用户名/短标识匹配需要 `channels.slack.dangerouslyAllowNameMatching: true` - 基于名称的键（`#channel-name` 或 `channel-name`）在 `groupPolicy: "allowlist"` 下**不会**匹配。渠道查找默认优先使用 ID，因此基于名称的键永远无法成功路由，该渠道中的所有消息都会被静默阻止。这不同于 `groupPolicy: "open"`，后者不需要渠道键即可路由，基于名称的键看起来会生效。 + 在 `groupPolicy: "allowlist"` 下，基于名称的键（`#channel-name` 或 `channel-name`）**不会**匹配。渠道查找默认优先使用 ID，因此基于名称的键永远无法成功路由，并且该渠道中的所有消息都会被静默阻止。这与 `groupPolicy: "open"` 不同，在后者中，路由不需要渠道键，基于名称的键看起来可以工作。 - 始终使用 Slack 渠道 ID 作为键。查找方法：在 Slack 中右键点击渠道 → **Copy link** — ID（`C...`）会出现在 URL 末尾。 + 始终使用 Slack 渠道 ID 作为键。查找方法：在 Slack 中右键点击渠道 → **复制链接** — ID（`C...`）会出现在 URL 末尾。 正确： @@ -574,26 +575,27 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 渠道消息默认由提及门控。 + 渠道消息默认受提及门控控制。 提及来源： - 显式应用提及（`<@botId>`） - - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） - - 隐式回复到 bot 线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） + - Slack 用户组提及（``），当机器人用户是该用户组成员时；需要 `usergroups:read` + - 提及正则表达式模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） + - 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） - 单渠道控制（`channels.slack.channels.`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 使用）： + 按渠道控制项（`channels.slack.channels.`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 使用）： - `requireMention` - `users`（允许列表） - `allowBots` - `skills` - `systemPrompt` - - `tools`、`toolsBySender` - - `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:`，或 `"*"` 通配符 - （旧版无前缀键仍只映射到 `id:`） + - `tools`, `toolsBySender` + - `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符 + （旧版无前缀键仍然只映射到 `id:`） - `allowBots` 对渠道和私有渠道采取保守策略：只有当发送 bot 被明确列入该房间的 `users` 允许列表，或 `channels.slack.allowFrom` 中至少一个显式 Slack 所有者 ID 当前是房间成员时，才接受 bot 发出的房间消息。通配符和显示名称形式的所有者条目不满足所有者存在条件。所有者存在检查使用 Slack `conversations.members`；请确保应用拥有与房间类型匹配的读取 scope（公开渠道用 `channels:read`，私有渠道用 `groups:read`）。如果成员查询失败，OpenClaw 会丢弃 bot 发出的房间消息。 + 对于渠道和私有渠道，`allowBots` 采取保守策略：只有当发送消息的机器人被明确列入该房间的 `users` 允许列表，或 `channels.slack.allowFrom` 中至少一个显式 Slack 所有者 ID 当前是房间成员时，才会接受机器人发送的房间消息。通配符和显示名称所有者条目不满足所有者存在条件。所有者存在性使用 Slack `conversations.members`；确保应用拥有与房间类型匹配的读取作用域（公共渠道为 `channels:read`，私有渠道为 `groups:read`）。如果成员查找失败，OpenClaw 会丢弃机器人发送的房间消息。 @@ -603,16 +605,16 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 私信按 `direct` 路由；渠道按 `channel` 路由；MPIM 按 `group` 路由。 - 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。 - 渠道会话：`agent::slack:channel:`。 -- 适用时，线程回复可以创建线程会话后缀（`:thread:`）。 -- `channels.slack.thread.historyScope` 默认是 `thread`；`thread.inheritParent` 默认是 `false`。 +- 线程回复在适用时可以创建线程会话后缀（`:thread:`）。 +- `channels.slack.thread.historyScope` 默认为 `thread`；`thread.inheritParent` 默认为 `false`。 - `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时获取多少条现有线程消息（默认 `20`；设为 `0` 可禁用）。 -- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，抑制隐式线程提及，因此即使 bot 已参与该线程，bot 也只会响应线程内显式的 `@bot` 提及。否则，bot 已参与线程中的回复会绕过 `requireMention` 门控。 +- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，抑制隐式线程提及，因此机器人只会响应线程内显式的 `@bot` 提及，即使机器人已经参与了该线程。没有此设置时，机器人参与过的线程中的回复会绕过 `requireMention` 门控。 -回复线程控制： +回复线程控制项： - `channels.slack.replyToMode`：`off|first|all|batched`（默认 `off`） -- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 分别设置 -- 私聊的旧版回退：`channels.slack.dm.replyToMode` +- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 设置 +- 直接聊天的旧版回退：`channels.slack.dm.replyToMode` 支持手动回复标签： @@ -620,24 +622,24 @@ 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 账号或全局禁用该反应。 +- 使用 `""` 可为 Slack 账号或全局禁用该反应。 ## 文本流式传输 @@ -651,11 +653,11 @@ Slack 操作由 `channels.slack.actions.*` 控制。 当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。 -- 必须有可用的回复线程，才会显示原生文本流式传输和 Slack assistant 线程状态。线程选择仍遵循 `replyToMode`。 +- 必须有可用的回复线程，才会显示原生文本流式传输和 Slack 助手线程状态。线程选择仍遵循 `replyToMode`。 - 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。 -- 顶层 Slack 私信默认不在线程内，因此不会显示线程样式预览；如果你希望那里显示可见进度，请使用线程回复或 `typingReaction`。 +- 顶层 Slack 私信默认保持非线程模式，因此不会显示线程样式预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。 - 媒体和非文本载荷会回退到普通投递。 -- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息仅在可以原地编辑预览时才会 flush。 +- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息只有在可以原地编辑预览时才会刷新。 - 如果流式传输在回复中途失败，OpenClaw 会对剩余载荷回退到普通投递。 使用草稿预览而不是 Slack 原生文本流式传输： @@ -679,29 +681,29 @@ 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..." 状态指示器。 解析顺序： - `channels.slack.accounts..typingReaction` - `channels.slack.typingReaction` -注意： +说明： - Slack 需要短代码（例如 `"hourglass_flowing_sand"`）。 -- 该反应采用尽力而为方式，回复或失败路径完成后会自动尝试清理。 +- 该反应是尽力而为，并会在回复或失败路径完成后自动尝试清理。 ## 媒体、分块和投递 - - Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以用 `download-file` 获取原始文件。 + + Slack 文件附件会从 Slack 托管的私有 URL 下载（令牌认证的请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以使用 `download-file` 获取原始文件。 - 下载使用有界的空闲超时和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息，并回退到文件占位符。 + 下载使用有界空闲超时和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息，并回退到文件占位符。 - 运行时入站大小上限默认为 `20MB`，除非由 `channels.slack.mediaMaxMb` 覆盖。 + 运行时入站大小上限默认为 `20MB`，除非被 `channels.slack.mediaMaxMb` 覆盖。 @@ -709,24 +711,24 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 文本分块使用 `channels.slack.textChunkLimit`（默认 4000） - `channels.slack.chunkMode="newline"` 启用段落优先拆分 - 文件发送使用 Slack 上传 API，并且可以包含线程回复（`thread_ts`） - - 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则，渠道发送使用媒体流水线中的 MIME 类型默认值 + - 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则渠道发送会使用媒体流水线中的 MIME 类型默认值 - 首选的显式目标： + 首选显式目标： - `user:` 用于私信 - `channel:` 用于渠道 - 发送到用户目标时，会通过 Slack conversation API 打开 Slack 私信。 + 发送到用户目标时，会通过 Slack 会话 API 打开 Slack 私信。 -## 命令和 slash 行为 +## 命令和斜杠行为 -Slash 命令在 Slack 中显示为单个配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： +斜杠命令在 Slack 中显示为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： - `enabled: false` - `name: "openclaw"` @@ -737,7 +739,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 原生命令。 @@ -747,20 +749,20 @@ Slash 命令在 Slack 中显示为单个配置命令或多个原生命令。配 原生参数菜单使用自适应渲染策略，在分发所选选项值之前显示确认模态框： -- 最多 5 个选项：按钮区块 +- 最多 5 个选项：按钮块 - 6-100 个选项：静态选择菜单 -- 超过 100 个选项：当交互选项处理程序可用时，使用带异步选项过滤的外部选择 -- 超出 Slack 限制：编码后的选项值回退为按钮 +- 超过 100 个选项：当交互选项处理程序可用时，使用带异步选项筛选的外部选择 +- 超出 Slack 限制：编码后的选项值会回退为按钮 ```txt /think ``` -Slash 会话使用类似 `agent::slack:slash:` 的隔离键，并且仍会使用 `CommandTargetSessionKey` 将命令执行路由到目标对话会话。 +斜杠会话使用类似 `agent::slack:slash:` 的隔离键，并且仍会使用 `CommandTargetSessionKey` 将命令执行路由到目标对话会话。 ## 交互式回复 -Slack 可以渲染 agent 编写的交互式回复控件，但此功能默认禁用。 +Slack 可以渲染智能体编写的交互式回复控件，但此功能默认禁用。 全局启用： @@ -776,7 +778,7 @@ Slack 可以渲染 agent 编写的交互式回复控件，但此功能默认禁 } ``` -或仅为一个 Slack 账号启用： +或者仅为一个 Slack 账号启用： ```json5 { @@ -794,43 +796,43 @@ Slack 可以渲染 agent 编写的交互式回复控件，但此功能默认禁 } ``` -启用后，agent 可以发出仅限 Slack 的回复指令： +启用后，智能体可以发出仅适用于 Slack 的回复指令： - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -这些指令会编译为 Slack Block Kit，并通过现有 Slack 交互事件路径回传点击或选择。 +这些指令会编译为 Slack Block Kit，并通过现有 Slack 交互事件路径路由点击或选择。 -注意事项： +注意： - 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令转换为自己的按钮系统。 -- 交互式回调值是 OpenClaw 生成的不透明令牌，不是 agent 编写的原始值。 -- 如果生成的交互式区块会超过 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的 blocks 载荷。 +- 交互式回调值是 OpenClaw 生成的不透明令牌，而不是智能体编写的原始值。 +- 如果生成的交互式块会超出 Slack Block Kit 限制，OpenClaw 会回退到原始文本回复，而不是发送无效的块载荷。 -## Slack 中的执行批准 +## Slack 中的 Exec 审批 -Slack 可以作为带有交互式按钮和交互的原生批准客户端，而不是回退到 Web UI 或终端。 +Slack 可以作为带有交互式按钮和交互的原生审批客户端，而不是回退到 Web UI 或终端。 -- 执行批准使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 -- 当请求已经落在 Slack 中，并且批准 ID 类型为 `plugin:` 时，插件批准仍可通过同一 Slack 原生按钮界面完成。 -- 仍会强制执行批准者授权：只有被识别为批准者的用户才能通过 Slack 批准或拒绝请求。 +- Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 +- 当请求已落在 Slack 中且审批 ID 种类为 `plugin:` 时，插件审批仍可以通过同一个 Slack 原生按钮界面解析。 +- 审批人授权仍会强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。 -这会使用与其他渠道相同的共享批准按钮界面。当你的 Slack 应用设置中启用 `interactivity` 时，批准提示会在对话中直接渲染为 Block Kit 按钮。 -当这些按钮存在时，它们是主要批准 UX；OpenClaw -只应在工具结果表明聊天批准不可用或手动批准是唯一路径时 -包含手动 `/approve` 命令。 +这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用 `interactivity` 后，审批提示会直接在对话中渲染为 Block Kit 按钮。 +当这些按钮存在时，它们是主要审批 UX；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 会自动启用原生执行批准。设置 `enabled: false` 可显式禁用 Slack 作为原生批准客户端。 -设置 `enabled: true` 可在批准者解析成功时强制启用原生批准。 +当 `enabled` 未设置或为 `"auto"`，且至少能解析出一个审批人时，Slack 会自动启用原生 exec 审批。设置 `enabled: false` 可显式禁用 Slack 作为原生审批客户端。 +设置 `enabled: true` 可在能解析出审批人时强制启用原生审批。 -没有显式 Slack 执行批准配置时的默认行为： +没有显式 Slack exec 审批配置时的默认行为： ```json5 { @@ -840,7 +842,8 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 } ``` -只有在你想覆盖批准者、添加过滤器，或选择加入来源聊天投递时，才需要显式 Slack 原生配置： +仅当你想覆盖审批人、添加筛选器或 +选择加入源聊天投递时，才需要显式 Slack 原生配置： ```json5 { @@ -856,22 +859,24 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 } ``` -共享 `approvals.exec` 转发是独立的。仅当执行批准提示还必须路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是独立的；当这些请求已经落在 Slack 中时，Slack 原生按钮仍可完成插件批准。 +共享的 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须 +路由到其他聊天或显式带外目标时才使用它。共享的 `approvals.plugin` 转发也是 +独立的；当这些请求已落在 Slack 中时，Slack 原生按钮仍可以解析插件审批。 -同一聊天中的 `/approve` 也适用于已经支持命令的 Slack 渠道和私信。完整批准转发模型见[执行批准](/zh-CN/tools/exec-approvals)。 +同聊天 `/approve` 也适用于已支持命令的 Slack 渠道和私信。参阅 [Exec 审批](/zh-CN/tools/exec-approvals)了解完整审批转发模型。 -## 事件和运维行为 +## 事件和运行行为 - 消息编辑/删除会映射为系统事件。 -- 线程广播（“Also send to channel” 线程回复）会作为普通用户消息处理。 -- Reaction 添加/移除事件会映射为系统事件。 -- 成员加入/离开、渠道创建/重命名，以及 pin 添加/移除事件会映射为系统事件。 -- 启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。 -- 渠道 topic/purpose 元数据会被视为不受信任的上下文，并可能被注入路由上下文。 -- 适用时，线程起始消息和初始线程历史上下文注入会按配置的发送者允许列表过滤。 -- 区块操作和模态框交互会发出结构化的 `Slack interaction: ...` 系统事件，并带有丰富载荷字段： - - 区块操作：所选值、标签、选择器值和 `workflow_*` 元数据 - - 模态框 `view_submission` 和 `view_closed` 事件，包含路由的渠道元数据和表单输入 +- 线程广播（“同时发送到渠道”的线程回复）会作为普通用户消息处理。 +- 表情回应添加/移除事件会映射为系统事件。 +- 成员加入/离开、渠道创建/重命名以及置顶添加/移除事件会映射为系统事件。 +- 启用 `configWrites` 后，`channel_id_changed` 可以迁移渠道配置键。 +- 渠道主题/用途元数据会被视为不可信上下文，并可注入到路由上下文中。 +- 适用时，线程发起消息和初始线程历史上下文种子会按配置的发送者允许列表筛选。 +- 块操作和模态框交互会发出结构化 `Slack interaction: ...` 系统事件，并带有丰富的载荷字段： + - 块操作：所选值、标签、选择器值以及 `workflow_*` 元数据 + - 模态框 `view_submission` 和 `view_closed` 事件，带有路由后的渠道元数据和表单输入 ## 配置参考 @@ -879,9 +884,9 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 -- 模式/凭证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*` +- 模式/认证：`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` @@ -896,11 +901,11 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 按顺序检查： - `groupPolicy` - - 渠道允许列表（`channels.slack.channels`）— **键必须是渠道 ID**（`C12345678`），而不是名称（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，基于名称的键会静默失败，因为默认情况下渠道路由以 ID 优先。查找 ID 的方法：在 Slack 中右键点击渠道 → **Copy link** — URL 末尾的 `C...` 值就是渠道 ID。 + - 渠道允许列表（`channels.slack.channels`）— **键必须是渠道 ID**（`C12345678`），而不是名称（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，基于名称的键会静默失败，因为默认情况下渠道路由以 ID 优先。要查找 ID：在 Slack 中右键点击渠道 → **Copy link** — URL 末尾的 `C...` 值就是渠道 ID。 - `requireMention` - - 每个渠道的 `users` 允许列表 + - 每渠道 `users` 允许列表 - 有用命令： + 有用的命令： ```bash openclaw channels status --probe @@ -915,9 +920,9 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy`（或旧版 `channels.slack.dm.policy`） - - 配对批准 / 允许列表条目 + - 配对审批 / 允许列表条目 - Slack Assistant 私信事件：提到 `drop message_changed` 的详细日志 - 通常意味着 Slack 发送了一个已编辑的 Assistant 线程事件，但消息元数据中 + 通常意味着 Slack 发送了已编辑的 Assistant 线程事件，但消息元数据中 没有可恢复的人类发送者 ```bash @@ -927,12 +932,11 @@ 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 支持的值。 @@ -941,110 +945,109 @@ openclaw pairing list slack - 签名密钥 - webhook 路径 - - Slack Request URLs（Events + Interactivity + Slash Commands） + - Slack Request URLs（事件 + 交互 + 斜杠命令） - 每个 HTTP 账号唯一的 `webhookPath` 如果账号快照中出现 `signingSecretStatus: "configured_unavailable"`， - 表示 HTTP 账号已配置，但当前运行时无法 - 解析由 SecretRef 支持的签名密钥。 + 则 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` 以及渠道/用户允许列表。 + 还要检查 `commands.useAccessGroups` 和渠道/用户允许列表。 ## 附件视觉参考 -当 Slack 文件下载成功且大小限制允许时，Slack 可以将已下载媒体附加到 agent 轮次中。图片文件可以通过媒体理解路径传递，或直接传递给具备视觉能力的回复模型；其他文件会保留为可下载文件上下文，而不是被视为图片输入。 +当 Slack 文件下载成功且大小限制允许时，Slack 可以将下载的媒体附加到智能体轮次。图像文件可以通过媒体理解路径传递，也可以直接传递给具备视觉能力的回复模型；其他文件会保留为可下载文件上下文，而不是作为图像输入处理。 ### 支持的媒体类型 -| 媒体类型 | 来源 | 当前行为 | 备注 | +| 媒体类型 | 来源 | 当前行为 | 备注 | | ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| JPEG / PNG / GIF / WebP 图片 | Slack 文件 URL | 下载并附加到轮次中，以供具备视觉能力的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） | -| PDF 文件 | Slack 文件 URL | 下载并公开为文件上下文，供 `download-file` 或 `pdf` 等工具使用 | Slack 入站不会自动将 PDF 转换为图片视觉输入 | -| 其他文件 | Slack 文件 URL | 尽可能下载并公开为文件上下文 | 二进制文件不会被视为图片输入 | -| 线程回复 | 线程起始文件 | 当回复没有直接媒体时，可以将根消息文件水合为上下文 | 仅文件起始消息使用附件占位符 | -| 多图片消息 | 多个 Slack 文件 | 每个文件都会独立评估 | Slack 处理每条消息最多限制为八个文件 | +| JPEG / PNG / GIF / WebP 图片 | Slack 文件 URL | 下载并附加到该轮对话，以便支持视觉能力的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） | +| PDF 文件 | Slack 文件 URL | 下载并作为文件上下文暴露给 `download-file` 或 `pdf` 等工具 | Slack 入站不会自动将 PDF 转换为图像视觉输入 | +| 其他文件 | Slack 文件 URL | 在可能时下载并作为文件上下文暴露 | 二进制文件不会被视为图像输入 | +| 线程回复 | 线程起始消息文件 | 当回复没有直接媒体时，根消息文件可以作为上下文补充 | 仅包含文件的起始消息会使用附件占位符 | +| 多图像消息 | 多个 Slack 文件 | 每个文件都会独立评估 | Slack 处理限制为每条消息最多八个文件 | ### 入站流水线 当带有文件附件的 Slack 消息到达时： -1. OpenClaw 使用 bot 令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。 -2. 成功后，文件会写入媒体存储。 +1. OpenClaw 使用机器人令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。 +2. 下载成功后，文件会写入媒体存储。 3. 下载的媒体路径和内容类型会添加到入站上下文。 4. 支持图像的模型/工具路径可以使用该上下文中的图像附件。 -5. 非图像文件仍会作为文件元数据或媒体引用提供给能处理它们的工具。 +5. 非图像文件仍会作为文件元数据或媒体引用提供给能够处理它们的工具。 ### 线程根附件继承 -当消息在线程中到达（有一个 `thread_ts` 父级）时： +当消息在线程中到达时（具有 `thread_ts` 父级）： -- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以将根文件注入为线程起始上下文。 +- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以将根文件作为线程起始上下文补充。 - 直接回复附件优先于根消息附件。 -- 只有文件而没有文本的根消息会以附件占位符表示，因此回退仍可包含其文件。 +- 仅包含文件且没有文本的根消息会用附件占位符表示，以便回退仍可包含其文件。 ### 多附件处理 当单条 Slack 消息包含多个文件附件时： -- 每个附件都会通过媒体管线独立处理。 +- 每个附件都会通过媒体流水线独立处理。 - 下载的媒体引用会聚合到消息上下文中。 -- 处理顺序遵循事件载荷中 Slack 的文件顺序。 -- 一个附件下载失败不会阻塞其他附件。 +- 处理顺序遵循事件载荷中的 Slack 文件顺序。 +- 一个附件下载失败不会阻止其他附件。 ### 大小、下载和模型限制 - **大小上限**：默认每个文件 20 MB。可通过 `channels.slack.mediaMaxMb` 配置。 -- **下载失败**：Slack 无法提供的文件、过期 URL、无法访问的文件、超大文件，以及 Slack 认证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。 -- **视觉模型**：图像分析会使用支持视觉的当前回复模型，或使用在 `agents.defaults.imageModel` 配置的图像模型。 +- **下载失败**：Slack 无法提供的文件、过期 URL、无法访问的文件、超大文件以及 Slack 身份验证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。 +- **视觉模型**：图像分析会在活动回复模型支持视觉时使用该模型，或使用 `agents.defaults.imageModel` 配置的图像模型。 ### 已知限制 -| 场景 | 当前行为 | 解决方法 | +| 场景 | 当前行为 | 解决方法 | | -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| 过期的 Slack 文件 URL | 文件被跳过；不显示错误 | 在 Slack 中重新上传文件 | -| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用支持视觉的回复模型 | -| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，增加 `channels.slack.mediaMaxMb` | -| 转发/共享的附件 | 文本和 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新分享 | -| PDF 附件 | 存储为文件/媒体上下文，不会自动通过图像视觉路由 | 对文件元数据使用 `download-file`，或使用 `pdf` 工具进行 PDF 分析 | +| 过期的 Slack 文件 URL | 文件被跳过；不显示错误 | 在 Slack 中重新上传文件 | +| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用支持视觉的回复模型 | +| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，请提高 `channels.slack.mediaMaxMb` | +| 转发/共享的附件 | 文本和 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新共享 | +| PDF 附件 | 存储为文件/媒体上下文，不会自动通过图像视觉路由 | 使用 `download-file` 获取文件元数据，或使用 `pdf` 工具进行 PDF 分析 | ### 相关文档 -- [媒体理解管线](/zh-CN/nodes/media-understanding) +- [媒体理解流水线](/zh-CN/nodes/media-understanding) - [PDF 工具](/zh-CN/tools/pdf) -- 长篇任务：[#51349](https://github.com/openclaw/openclaw/issues/51349) — 启用 Slack 附件视觉 +- 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) -## 相关内容 +## 相关 - - 将 Slack 用户与 Gateway 网关配对。 + + 将 Slack 用户配对到 Gateway 网关。 - + 渠道和群组私信行为。 - + 将入站消息路由到智能体。 - + 威胁模型和加固。 - + 配置布局和优先级。 - + 命令目录和行为。 diff --git a/docs/zh-CN/gateway/config-channels.md b/docs/zh-CN/gateway/config-channels.md index 3e5e1f320..7db1a92d4 100644 --- a/docs/zh-CN/gateway/config-channels.md +++ b/docs/zh-CN/gateway/config-channels.md @@ -1,22 +1,22 @@ --- read_when: - - 配置渠道插件（身份验证、访问控制、多账号） - - 每个渠道的配置键名故障排除 + - 配置渠道插件（身份验证、访问控制、多账户） + - 按渠道配置键名的故障排除 - 审计私信策略、群组策略或提及门控 -summary: 渠道配置：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等渠道的访问控制、配对和按渠道配置的密钥 +summary: 渠道配置：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等渠道的访问控制、配对和按渠道设置的密钥 title: 配置 — 渠道 x-i18n: - generated_at: "2026-05-01T18:34:53Z" + generated_at: "2026-05-02T02:58:28Z" model: gpt-5.5 provider: openai - source_hash: bca1314b67f8d2dd4699888a728af28a75b973b001901581536df31c2d0e8ce8 + source_hash: bc790f19aed583b4c52988c170c8883bf56282cfbf3eae26f655f7a4660bd4ed source_path: gateway/config-channels.md workflow: 16 --- -按 `channels.*` 划分的各渠道配置键。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的各渠道键。 +每个渠道配置键位于 `channels.*` 下。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的各渠道键。 -关于智能体、工具、Gateway 网关运行时和其他顶层键，请参阅 +对于智能体、工具、Gateway 网关运行时和其他顶级键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。 ## 渠道 @@ -27,28 +27,28 @@ x-i18n: 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | --------------------------------------------------------------- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | -| `allowlist` | 仅允许 `allowFrom`（或已配对允许存储）中的发送者 | -| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| 私信策略 | 行为 | +| ------------------- | ----------------------------------------------------------- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 仅允许 `allowFrom`（或已配对允许存储）中的发送者 | +| `open` | 允许所有入站私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有入站私信 | -| 群组策略 | 行为 | -| --------------------- | ------------------------------------------------------ | -| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | -| `open` | 绕过群组允许列表（提及门控仍然适用） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| --------------------- | -------------------------------------------------- | +| `allowlist`（默认） | 仅允许匹配已配置允许名单的群组 | +| `open` | 绕过群组允许名单（提及门控仍然适用） | +| `disabled` | 阻止所有群组/房间消息 | -`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设为默认值。 -配对码会在 1 小时后过期。待处理的私信配对请求限制为**每个渠道 3 个**。 -如果提供商块完全缺失（不存在 `channels.`），运行时群组策略会回退到 `allowlist`（故障关闭），并在启动时发出警告。 +`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设置默认值。 +配对码会在 1 小时后过期。待处理的私信配对请求上限为 **每个渠道 3 个**。 +如果提供商块完全缺失（不存在 `channels.`），运行时群组策略会回退到 `allowlist`（失败关闭），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话尚未有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。 +使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话还没有模型覆盖时（例如通过 `/model` 设置），会应用渠道映射。 ```json5 { @@ -71,7 +71,7 @@ x-i18n: ### 渠道默认值和 Heartbeat -使用 `channels.defaults` 为各提供商设置共享的群组策略和 Heartbeat 行为： +使用 `channels.defaults` 设置跨提供商共享的群组策略和 Heartbeat 行为： ```json5 { @@ -89,15 +89,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时的回退群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/话题串/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与允许列表相同，但保留显式引用/回复上下文）。各渠道覆盖：`channels..contextVisibility`。 -- `channels.defaults.heartbeat.showOk`：在 Heartbeat 输出中包含健康的渠道状态。 +- `channels.defaults.groupPolicy`：提供商级 `groupPolicy` 未设置时的回退群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许名单发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留明确引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.heartbeat.showOk`：在 Heartbeat 输出中包含健康渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在 Heartbeat 输出中包含降级/错误状态。 - `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器样式 Heartbeat 输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已链接会话时，它会自动启动。 +WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已链接会话时会自动启动。 ```json5 { @@ -155,10 +155,10 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- 外发命令默认使用账号 `default`（如果存在）；否则使用第一个已配置账号 ID（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配已配置账号 ID 时覆盖该回退默认账号选择。 -- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 -- 各账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 +- 出站命令默认使用账号 `default`（如果存在）；否则使用第一个已配置账号 ID（排序后）。 +- 可选的 `channels.whatsapp.defaultAccount` 会在匹配已配置账号 ID 时覆盖该回退默认账号选择。 +- 旧版单账号 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 按账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -217,14 +217,14 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅限普通文件；拒绝符号链接），默认账号会以 `TELEGRAM_BOT_TOKEN` 作为回退。 -- `apiRoot` 仅是 Telegram Bot API 根地址。使用 `https://api.telegram.org` 或你的自托管/代理根地址，而不是 `https://api.telegram.org/bot`；`openclaw doctor --fix` 会移除意外尾随的 `/bot` 后缀。 -- 可选的 `channels.telegram.defaultAccount` 会在其匹配已配置账号 ID 时覆盖默认账号选择。 -- 在多账号设置（2 个以上账号 ID）中，设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；当其缺失或无效时，`openclaw doctor` 会发出警告。 +- 机器人令牌：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅普通文件；符号链接会被拒绝），默认账号的回退值为 `TELEGRAM_BOT_TOKEN`。 +- `apiRoot` 仅是 Telegram Bot API 根地址。使用 `https://api.telegram.org` 或你的自托管/代理根地址，不要使用 `https://api.telegram.org/bot`；`openclaw doctor --fix` 会移除意外尾随的 `/bot` 后缀。 +- 可选的 `channels.telegram.defaultAccount` 会在匹配已配置账号 ID 时覆盖默认账号选择。 +- 在多账号设置（2 个以上账号 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；当缺失或无效时，`openclaw doctor` 会发出警告。 - `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 条目使用 `type: "acp"` 为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 +- 带有 `type: "acp"` 的顶级 `bindings[]` 条目会为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 - Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群聊）。 -- 重试策略：参阅[重试策略](/zh-CN/concepts/retry)。 +- 重试策略：请参阅[重试策略](/zh-CN/concepts/retry)。 ### Discord @@ -328,39 +328,40 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- Token：`channels.discord.token`，默认账号的回退值为 `DISCORD_BOT_TOKEN`。 -- 提供显式 Discord `token` 的直接出站调用会使用该 token 执行调用；账号重试/策略设置仍来自活动运行时快照中选定的账号。 -- 可选的 `channels.discord.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 -- 使用 `user:`（私信）或 `channel:`（服务器渠道）作为投递目标；裸数字 ID 会被拒绝。 -- 服务器 slug 为小写并将空格替换为 `-`；渠道键使用 slug 化后的名称（不带 `#`）。优先使用服务器 ID。 -- 默认忽略机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及机器人的机器人消息（仍会过滤自己发送的消息）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及渠道覆盖项）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）即使在低于 2000 个字符时也会拆分过高的消息。 +- 令牌：`channels.discord.token`，默认账户回退使用 `DISCORD_BOT_TOKEN`。 +- 提供显式 Discord `token` 的直接出站调用会为该调用使用该令牌；账户重试/策略设置仍来自活动运行时快照中的所选账户。 +- 可选的 `channels.discord.defaultAccount` 在匹配已配置账户 ID 时会覆盖默认账户选择。 +- 使用 `user:`（私信）或 `channel:`（公会渠道）作为投递目标；裸数字 ID 会被拒绝。 +- 公会 slug 为小写，并将空格替换为 `-`；渠道键使用 slug 化名称（不含 `#`）。优先使用公会 ID。 +- 默认忽略机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及机器人的机器人消息（仍会过滤自身消息）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及渠道覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 +- `channels.discord.mentionAliases` 会在发送前将稳定的出站 `@handle` 文本映射到 Discord 用户 ID，因此即使瞬时目录缓存为空，也能确定性地提及已知队友。按账户覆盖位于 `channels.discord.accounts..mentionAliases` 下。 +- `maxLinesPerMessage`（默认 17）即使在 2000 字符以内，也会拆分很高的消息。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：线程绑定会话功能的 Discord 覆盖项（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） - - `idleHours`：不活动自动取消聚焦的 Discord 覆盖项，单位为小时（`0` 表示禁用） - - `maxAgeHours`：硬性最大时长的 Discord 覆盖项，单位为小时（`0` 表示禁用） - - `spawnSubagentSessions`：用于 `sessions_spawn({ thread: true })` 自动创建/绑定线程的选择加入开关 -- 带有 `type: "acp"` 的顶层 `bindings[]` 条目为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 + - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） + - `idleHours`：按小时设置非活动自动取消聚焦的 Discord 覆盖（`0` 表示禁用） + - `maxAgeHours`：按小时设置硬性最大时长的 Discord 覆盖（`0` 表示禁用） + - `spawnSubagentSessions`：用于 `sessions_spawn({ thread: true })` 自动创建/绑定线程的选择启用开关 +- 顶层 `bindings[]` 条目配合 `type: "acp"` 为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 - `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。 -- `channels.discord.voice` 启用 Discord 语音渠道对话以及可选的自动加入 + LLM + TTS 覆盖项。纯文本 Discord 配置默认关闭语音；设置 `channels.discord.voice.enabled=true` 以选择加入。 +- `channels.discord.voice` 启用 Discord 语音渠道对话，以及可选的自动加入 + LLM + TTS 覆盖。纯文本 Discord 配置默认关闭语音；设置 `channels.discord.voice.enabled=true` 以选择启用。 - `channels.discord.voice.model` 可选地覆盖用于 Discord 语音渠道响应的 LLM 模型。 -- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会传递给 `@discordjs/voice` DAVE 选项（默认分别为 `true` 和 `24`）。 -- `channels.discord.voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试时初始 `@discordjs/voice` Ready 等待时间（默认为 `30000`）。 -- `channels.discord.voice.reconnectGraceMs` 控制已断开的语音会话在 OpenClaw 销毁它之前可进入重连信令的时长（默认为 `15000`）。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` DAVE 选项（默认分别为 `true` 和 `24`）。 +- `channels.discord.voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试的初始 `@discordjs/voice` Ready 等待时间（默认 `30000`）。 +- `channels.discord.voice.reconnectGraceMs` 控制已断开的语音会话可在 OpenClaw 销毁它之前进入重连信令的时长（默认 `15000`）。 - OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试语音接收恢复。 -- `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔值 `streaming` 会自动迁移。 -- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online、degraded => idle、exhausted => dnd），并允许可选的状态文本覆盖项。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（破窗兼容模式）。 +- `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 +- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选状态文本覆盖。 +- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（应急兼容模式）。 - `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析审批人时，exec 审批会激活。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析审批人时，会激活 exec 审批。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - - `sessionFilter`：可选的会话键模式（子字符串或正则）。 - - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到来源渠道，`"both"` 发送到两者。当目标包含 `"channel"` 时，按钮仅可由已解析的审批人使用。 - - `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除审批私信。 + - `agentFilter`：可选智能体 ID 允许列表。省略则转发所有智能体的审批。 + - `sessionFilter`：可选会话键模式（子字符串或正则表达式）。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到来源渠道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮只能由已解析的审批人使用。 + - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**回应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds..users`）。 +**反应通知模式：**`off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds..users`）。 ### Google Chat @@ -391,11 +392,11 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- 服务账号 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 -- 也支持服务账号 SecretRef（`serviceAccountRef`）。 -- 环境变量回退值：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 +- 服务账户 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 也支持服务账户 SecretRef（`serviceAccountRef`）。 +- 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 - 使用 `spaces/` 或 `users/` 作为投递目标。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（破窗兼容模式）。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（应急兼容模式）。 ### Slack @@ -467,43 +468,35 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级或每个账号中）。 -- `socketMode` 会将 Slack SDK Socket Mode 传输调优透传到公共 Bolt 接收器 API。仅在调查 ping/pong 超时或陈旧 websocket 行为时使用它。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 - 字符串或 SecretRef 对象。 -- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 - `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 中的 - `signingSecretStatus`。`configured_unavailable` 表示账号通过 - SecretRef 配置，但当前命令/运行时路径无法解析密钥值。 -- `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 -- `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输协议。旧版 `streamMode`、布尔值 `streaming` 和 `nativeStreaming` 会自动迁移。 +- **Socket 模式**需要同时提供 `botToken` 和 `appToken`（默认账户环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP 模式**需要 `botToken` 加 `signingSecret`（在根级或按账户配置）。 +- `socketMode` 会将 Slack SDK Socket Mode 传输调优透传到公共 Bolt 接收器 API。仅在调查 ping/pong 超时或过期 websocket 行为时使用。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 +- Slack 账户快照会暴露按凭据的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示账户通过 SecretRef 配置，但当前命令/运行时路径无法解析密钥值。 +- `configWrites: false` 会阻止 Slack 发起的配置写入。 +- 可选的 `channels.slack.defaultAccount` 在匹配已配置账户 ID 时会覆盖默认账户选择。 +- `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输协议。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会自动迁移。 - 使用 `user:`（私信）或 `channel:` 作为投递目标。 -**回应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**反应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 为按线程（默认）或跨渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。 +**线程会话隔离：**`thread.historyScope` 为按线程（默认）或跨渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。 -- Slack 原生流式传输加 Slack assistant 风格的 “is typing...” 线程状态需要回复线程目标。顶层私信默认保持非线程模式，因此它们会使用 `typingReaction` 或普通投递，而不是线程风格预览。 -- `typingReaction` 会在回复运行时向入站 Slack 消息添加临时回应，然后在完成时移除。使用 Slack emoji shortcode，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。与 Discord 相同的 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- Slack 原生流式传输加 Slack assistant 风格的“正在输入...”线程状态需要回复线程目标。顶层私信默认保持在线程外，因此它们会使用 `typingReaction` 或常规投递，而不是线程风格预览。 +- `typingReaction` 会在回复运行期间向入站 Slack 消息添加临时反应，然后在完成时移除。使用 Slack 表情短代码，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。架构与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 | 操作组 | 默认值 | 备注 | | ------------ | ------- | ---------------------- | -| reactions | enabled | 回应 + 列出回应 | -| messages | enabled | 读取/发送/编辑/删除 | -| pins | enabled | 置顶/取消置顶/列出 | -| memberInfo | enabled | 成员信息 | -| emojiList | enabled | 自定义 emoji 列表 | +| reactions | 已启用 | 反应 + 列出反应 | +| messages | 已启用 | 读取/发送/编辑/删除 | +| pins | 已启用 | 置顶/取消置顶/列表 | +| memberInfo | 已启用 | 成员信息 | +| emojiList | 已启用 | 自定义表情列表 | ### Mattermost -Mattermost 在当前 OpenClaw 版本中作为内置插件发布。较旧或 -自定义构建可以使用 -`openclaw plugins install @openclaw/mattermost` 安装当前 npm 包；如果 npm 报告 -OpenClaw 所有的包已弃用，请使用内置插件或本地检出， -直到发布更新的 npm 包。 +Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧或自定义构建可以使用 `openclaw plugins install @openclaw/mattermost` 安装当前 npm 包；如果 npm 报告 OpenClaw 拥有的包已弃用，请使用内置插件或本地检出，直到发布更新的 npm 包。 ```json5 { @@ -533,18 +526,18 @@ OpenClaw 所有的包已弃用，请使用内置插件或本地检出， } ``` -聊天模式：`oncall`（在 @-提及时响应，默认）、`onmessage`（每条消息）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（响应 @ 提及，默认）、`onmessage`（每条消息）、`onchar`（以触发前缀开头的消息）。 启用 Mattermost 原生命令时： -- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），而不是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。 -- 原生斜杠回调使用 Mattermost 在注册斜杠命令时返回的每命令令牌进行认证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调并返回 `Unauthorized: invalid command token.` -- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。使用主机/域名值，而不是完整 URL。 -- `channels.mattermost.configWrites`：允许或拒绝 Mattermost 发起的配置写入。 -- `channels.mattermost.requireMention`：要求在渠道中回复前先 `@mention`。 -- `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（`"*"` 表示默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 +- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器必须可以访问。 +- 原生斜杠回调使用每个命令的 token 进行身份验证，这些 token 由 Mattermost 在斜杠命令注册期间返回。如果注册失败或没有命令被激活，OpenClaw 会拒绝回调并返回 `Unauthorized: invalid command token.` +- 对于私有、tailnet 或内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。使用主机/域名值，而不是完整 URL。 +- `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 +- `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。 +- `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（`"*"` 表示默认）。 +- 可选的 `channels.mattermost.defaultAccount` 会在匹配已配置的账号 ID 时覆盖默认账号选择。 ### Signal @@ -565,11 +558,11 @@ OpenClaw 所有的包已弃用，请使用内置插件或本地检出， } ``` -**反应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**回应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -- `channels.signal.account`：将渠道启动固定到特定 Signal 账号身份。 -- `channels.signal.configWrites`：允许或拒绝 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 +- `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。 +- `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 +- 可选的 `channels.signal.defaultAccount` 会在匹配已配置的账号 ID 时覆盖默认账号选择。 ### BlueBubbles @@ -589,13 +582,13 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.blueb ``` - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 -- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles 句柄或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 -- 完整 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 +- 可选的 `channels.bluebubbles.defaultAccount` 会在匹配已配置的账号 ID 时覆盖默认账号选择。 +- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage -OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 +OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 ```json5 { @@ -619,15 +612,15 @@ OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 会在匹配已配置的账号 ID 时覆盖默认账号选择。 -- 需要对 Messages DB 拥有完全磁盘访问权限。 +- 需要对 Messages DB 拥有完整磁盘访问权限。 - 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以便通过 SCP 获取附件。 +- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 - `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 - SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 -- `channels.imessage.configWrites`：允许或拒绝 iMessage 发起的配置写入。 -- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化句柄或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 +- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 @@ -670,21 +663,21 @@ Matrix 由插件支持，并在 `channels.matrix` 下配置。 } ``` -- 令牌认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。具名账号可以用 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和此网络选择加入是彼此独立的控制项。 -- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 -- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信风格邀请会被忽略，直到你设置带有 `autoJoinAllowlist` 的 `autoJoin: "allowlist"` 或 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生执行批准投递和批准者授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析批准者时，执行批准会激活。 - - `approvers`：允许批准执行请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选智能体 ID 允许列表。省略时会转发所有智能体的批准。 - - `sessionFilter`：可选会话键模式（子字符串或正则表达式）。 - - `target`：发送批准提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 +- token 身份验证使用 `accessToken`；密码身份验证使用 `userId` + `password`。 +- `channels.matrix.proxy` 通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可以使用 `channels.matrix.accounts..proxy` 覆盖它。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和这个网络选择加入项是相互独立的控制项。 +- `channels.matrix.defaultAccount` 会在多账号设置中选择首选账号。 +- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置带有 `autoJoinAllowlist` 的 `autoJoin: "allowlist"` 或 `autoJoin: "always"`。 +- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批者授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析审批者时，会激活 exec 审批。 + - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。 + - `sessionFilter`：可选的会话键模式（子字符串或正则表达式）。 + - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组成会话：`per-user`（默认）按路由后的对等方共享，而 `per-room` 会隔离每个私信房间。 -- Matrix Status 探测和实时目录查找使用与运行时流量相同的代理策略。 -- 完整 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由后的对端共享，而 `per-room` 会隔离每个私信房间。 +- Matrix 状态探测和实时目录查询使用与运行时流量相同的代理策略。 +- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams @@ -704,7 +697,7 @@ Microsoft Teams 由插件支持，并在 `channels.msteams` 下配置。 ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 +- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 ### IRC @@ -730,12 +723,12 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 -- 完整 IRC 渠道配置（主机/端口/TLS/渠道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 +- 可选的 `channels.irc.defaultAccount` 会在匹配已配置的账号 ID 时覆盖默认账号选择。 +- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/mention gating）记录在 [IRC](/zh-CN/channels/irc) 中。 ### 多账号（所有渠道） -每个渠道运行多个账号（每个都有自己的 `accountId`）： +每个渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -756,34 +749,34 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 } ``` -- 省略 `accountId` 时会使用 `default`（CLI + 路由）。 -- 环境变量令牌只适用于**默认**账号。 -- 基础渠道设置适用于所有账号，除非按账号覆盖。 -- 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。 -- 如果在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将账号范围的顶层单账号值提升到该渠道的账号映射中，从而让原始账号继续工作。大多数渠道会将它们移入 `channels..accounts.default`；Matrix 可以改为保留现有匹配的具名/默认目标。 -- 现有的仅渠道绑定（没有 `accountId`）会继续匹配默认账号；账号范围绑定仍然是可选的。 -- `openclaw doctor --fix` 也会通过将账号范围的顶层单账号值移动到为该渠道选择的已提升账号，来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 可以改为保留现有匹配的具名/默认目标。 +- 省略 `accountId` 时使用 `default`（CLI + 路由）。 +- 环境变量 token 只适用于**默认**账号。 +- 基础渠道设置会应用到所有账号，除非按账号覆盖。 +- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。 +- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，而当前仍使用单账号顶层渠道配置，OpenClaw 会先将账号作用域的顶层单账号值提升到渠道账号映射中，以便原始账号继续工作。大多数渠道会将它们移入 `channels..accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 +- 现有的仅渠道绑定（没有 `accountId`）会继续匹配默认账号；账号作用域绑定仍然是可选的。 +- `openclaw doctor --fix` 也会通过将账号作用域的顶层单账号值移动到为该渠道选择的已提升账号来修复混合形状。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 ### 其他插件渠道 许多插件渠道配置为 `channels.`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -查看完整渠道索引：[Channels](/zh-CN/channels)。 +请参阅完整渠道索引：[渠道](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认**要求提及**（元数据提及或安全正则表达式模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 -可见回复由单独的配置控制。群组/渠道房间默认为 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理该轮对话，但普通最终回复保持私密，可见房间输出需要 `message(action=send)`。只有在你想要旧版行为，即普通回复会发回房间时，才设置为 `"automatic"`。若要把相同的仅工具可见回复行为也应用于直接聊天，请设置 `messages.visibleReplies: "message_tool"`；Codex harness 也将该仅工具行为用作未设置时的直接聊天默认值。 +可见回复会单独控制。群组/渠道房间默认为 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理该轮对话，但普通最终回复保持私密，可见的房间输出需要 `message(action=send)`。仅当你想要普通回复被发回房间的旧版行为时，才设置 `"automatic"`。要将相同的仅工具可见回复行为也应用到直接聊天，请设置 `messages.visibleReplies: "message_tool"`；Codex harness 也将这种仅工具行为用作未设置的直接聊天默认值。 -如果在活动工具策略下消息工具不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。`openclaw doctor` 会警告这种不匹配。 +如果消息工具在当前工具策略下不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。`openclaw doctor` 会对此不匹配发出警告。 -Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中禁用了文件监听或配置重载时才需要重启。 +文件保存后，Gateway 网关会热重载 `messages` 配置。仅当部署中禁用了文件监视或配置重载时才需要重启。 **提及类型：** -- **元数据提及**：原生平台 @-mentions。在 WhatsApp 自聊模式中会被忽略。 -- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则表达式模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅当可以检测时（原生提及或至少一个模式），才会强制执行提及门控。 +- **元数据提及**：原生平台 @-提及。在 WhatsApp 自聊模式中会被忽略。 +- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 +- 只有在可以检测时（原生提及或至少一个模式），才会执行提及门控。 ```json5 { @@ -802,7 +795,7 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中 `messages.groupChat.historyLimit` 设置全局默认值。渠道可以用 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 -`messages.visibleReplies` 是全局源回合默认值；`messages.groupChat.visibleReplies` 会针对群组/渠道源回合覆盖它。当 `messages.visibleReplies` 未设置时，harness 可以提供自己的直接/源默认值；Codex harness 默认使用 `message_tool`。渠道允许列表和提及门控仍会决定是否处理某个回合。 +`messages.visibleReplies` 是全局源回合默认值；`messages.groupChat.visibleReplies` 会为群组/渠道源回合覆盖它。当 `messages.visibleReplies` 未设置时，harness 可以提供自己的 direct/source 默认值；Codex harness 默认使用 `message_tool`。渠道允许列表和提及门控仍会决定是否处理某个回合。 #### 私信历史限制 @@ -875,30 +868,30 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中 -- 此块配置命令表面。当前内置 + 内置插件命令目录请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。 -- 此页面是**配置键参考**，不是完整命令目录。渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、记忆 `/dreaming`、手机控制 `/phone` 和 Talk `/voice`，记录在其渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 +- 此块配置命令表面。当前内置 + 捆绑命令目录请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。 +- 此页面是**配置键参考**，不是完整命令目录。渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、记忆 `/dreaming`、电话控制 `/phone` 和 Talk `/voice`，记录在各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 - 文本命令必须是带前导 `/` 的**独立**消息。 - `native: "auto"` 会为 Discord/Telegram 开启原生命令，并让 Slack 保持关闭。 - `nativeSkills: "auto"` 会为 Discord/Telegram 开启原生 Skills 命令，并让 Slack 保持关闭。 -- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除之前注册的命令。 +- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前注册的命令。 - 使用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 注册。 - `channels.telegram.customCommands` 会添加额外的 Telegram bot 菜单项。 -- `bash: true` 会为主机 shell 启用 `! `。需要 `tools.elevated.enabled`，且发送者在 `tools.elevated.allowFrom.` 中。 -- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还需要 `operator.admin`；只读 `/config show` 仍可供普通写作用域的 operator 客户端使用。 -- `mcp: true` 会为 `mcp.servers` 下由 OpenClaw 管理的 MCP server 配置启用 `/mcp`。 -- `plugins: true` 会为插件发现、安装以及启用/禁用控制启用 `/plugins`。 -- `channels..configWrites` 按渠道限制配置变更（默认：true）。 -- 对于多账号渠道，`channels..accounts..configWrites` 还会限制面向该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 -- `ownerAllowFrom` 是仅限所有者命令/工具的显式所有者允许列表。它独立于 `allowFrom`。 -- `ownerDisplay: "hash"` 会在系统提示词中哈希所有者 ID。设置 `ownerDisplaySecret` 可控制哈希。 -- `allowFrom` 按提供商设置。设置后，它是**唯一**授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。 +- `bash: true` 启用用于主机 shell 的 `! `。需要 `tools.elevated.enabled`，且发送者在 `tools.elevated.allowFrom.` 中。 +- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还需要 `operator.admin`；只读 `/config show` 仍可供普通写入作用域的 operator 客户端使用。 +- `mcp: true` 为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 +- `plugins: true` 为插件发现、安装以及启用/禁用控制启用 `/plugins`。 +- `channels..configWrites` 按渠道限制配置变更（默认值：true）。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会限制以该账号为目标的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `restart: false` 禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 +- `ownerAllowFrom` 是仅限 owner 命令/工具的显式 owner 允许列表。它独立于 `allowFrom`。 +- `ownerDisplay: "hash"` 会在系统提示中哈希 owner id。设置 `ownerDisplaySecret` 以控制哈希。 +- `allowFrom` 按提供商设置。设置后，它是**唯一**授权来源（渠道允许列表/配对和 `useAccessGroups` 会被忽略）。 - 当未设置 `allowFrom` 时，`useAccessGroups: false` 允许命令绕过访问组策略。 - 命令文档映射： - - 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands) - - 渠道专属命令表面：[渠道](/zh-CN/channels) + - 内置 + 捆绑目录：[Slash Commands](/zh-CN/tools/slash-commands) + - 渠道特定命令表面：[Channels](/zh-CN/channels) - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) - - 配对命令：[配对](/zh-CN/channels/pairing) + - 配对命令：[Pairing](/zh-CN/channels/pairing) - LINE 卡片命令：[LINE](/zh-CN/channels/line) - 记忆 Dreaming：[Dreaming](/zh-CN/concepts/dreaming) @@ -908,6 +901,6 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中 ## 相关内容 -- [配置参考](/zh-CN/gateway/configuration-reference) — 顶层键 +- [配置参考](/zh-CN/gateway/configuration-reference) — 顶级键 - [配置 — 智能体](/zh-CN/gateway/config-agents) - [渠道概览](/zh-CN/channels)