From 8bd5a2a30b92aafee83e2c01c82f66db374a74df Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 3 May 2026 21:08:11 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/discord.md | 472 +++++++++++------------ docs/zh-CN/channels/telegram.md | 500 +++++++++++++------------ docs/zh-CN/concepts/progress-drafts.md | 254 +++++++++++++ docs/zh-CN/concepts/streaming.md | 138 +++---- docs/zh-CN/gateway/config-channels.md | 300 +++++++-------- 5 files changed, 968 insertions(+), 696 deletions(-) create mode 100644 docs/zh-CN/concepts/progress-drafts.md diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index 550cc3916..5a9b0597b 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -1,18 +1,18 @@ --- read_when: - 开发 Discord 渠道功能 -summary: Discord 机器人支持状态、能力和配置 +summary: Discord 机器人支持状态、功能和配置 title: Discord x-i18n: - generated_at: "2026-05-03T19:16:24Z" + generated_at: "2026-05-03T21:05:29Z" model: gpt-5.5 provider: openai - source_hash: 84582bdf79202e996bc1e5526acefa4954c5fedc62a904c733615a325870a3fd + source_hash: 3a38cb3c8e25c1f3d6b7ddfc35a0445dc264be74d74b08d0051528b462b743a3 source_path: channels/discord.md workflow: 16 --- -可通过官方 Discord 网关用于私信和服务器频道。 +已准备好通过官方 Discord gateway 支持私信和服务器频道。 @@ -28,18 +28,18 @@ 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**（推荐；角色允许列表和名称到 ID 匹配需要） @@ -48,25 +48,25 @@ x-i18n: - 在 **Bot** 页面上向上滚动并点击 **Reset Token**。 + 在 **Bot** 页面向上滚动，点击 **Reset Token**。 - 尽管名称如此，这会生成你的第一个令牌，并没有任何内容被“重置”。 + 尽管名称如此，这会生成你的第一个令牌，没有任何内容真的被“重置”。 - 复制该令牌并保存到某处。这是你的 **Bot Token**，稍后会用到。 + 复制令牌并保存到某处。这就是你的 **Bot Token**，稍后会用到。 - 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用于将机器人添加到你的服务器。 + 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用来把机器人添加到你的服务器。 向下滚动到 **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**。 - 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该能在 Discord 服务器中看到你的机器人。 + 这是普通文本频道的基线权限集合。如果你计划在 Discord 线程中发帖，包括会创建或继续线程的论坛或媒体频道工作流，也请启用 **Send Messages in Threads**。 + 复制底部生成的 URL，粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 连接。现在你应该能在 Discord 服务器中看到你的机器人。 - - 回到 Discord 应用，你需要启用 Developer Mode，以便复制内部 ID。 + + 回到 Discord 应用，你需要启用开发者模式，以便复制内部 ID。 - 1. 点击 **User Settings**（头像旁的齿轮图标）→ **Advanced** → 开启 **Developer Mode** - 2. 右键点击侧边栏中的 **服务器图标** → **Copy Server ID** - 3. 右键点击你的**个人头像** → **Copy User ID** + 1. 点击 **User Settings**（头像旁边的齿轮图标）→ **Advanced** → 打开 **Developer Mode** + 2. 右键点击侧边栏中的 **server icon** → **Copy Server ID** + 3. 右键点击你的 **own avatar** → **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 机器人令牌是机密（类似密码）。在给智能体发消息之前，在运行 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` 中，以便服务在重启后解析 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` 中，以便服务在重启后解析 env SecretRef。 + 如果你的主机被 Discord 的启动应用查询阻止或限速，请从 Developer Portal 设置 Discord application/client ID，这样启动时就能跳过该 REST 调用。默认账号使用 `channels.discord.applicationId`；运行多个 Discord 机器人时使用 `channels.discord.accounts..applicationId`。 @@ -135,7 +135,7 @@ openclaw gateway > “我已经在配置中设置了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” - 如果你偏好基于文件的配置，请设置： + 如果你更喜欢基于文件的配置，请设置： ```json5 { @@ -158,9 +158,9 @@ openclaw gateway 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 机器人，请将每个机器人令牌和应用 ID 放在其账号下。顶层 `channels.discord.applicationId` 会被账号继承，因此只有在每个账号都应使用同一个应用 ID 时才在那里设置它。 + 对于多个 Discord 机器人，请将每个机器人令牌和应用 ID 保存在它自己的账号下。顶层 `channels.discord.applicationId` 会被账号继承，因此只有在每个账号都应使用同一个应用 ID 时才在那里设置。 ```json5 { @@ -187,12 +187,12 @@ DISCORD_BOT_TOKEN=... - - 等待网关运行后，在 Discord 中给你的机器人发送私信。它会回复一个配对码。 + + 等到 Gateway 网关正在运行，然后在 Discord 中给你的机器人发私信。它会回复一个配对码。 - 将配对码通过现有渠道发送给你的智能体： + 通过现有渠道将配对码发送给你的智能体： > “批准这个 Discord 配对码：``” @@ -208,24 +208,24 @@ openclaw pairing approve discord 配对码会在 1 小时后过期。 - 现在你应该可以通过 Discord 私信与智能体聊天。 + 现在你应该可以通过 Discord 私信与你的智能体聊天。 -令牌解析支持账号感知。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 只用于默认账号。 -如果两个已启用的 Discord 账号解析到同一个机器人令牌，OpenClaw 只会为该令牌启动一个网关监视器。来自配置的令牌优先于默认环境变量回退；否则第一个启用的账号生效，重复账号会报告为已禁用。 -对于高级出站调用（message 工具/渠道操作），显式的按调用 `token` 会用于该调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账号策略/重试设置仍来自活动运行时快照中的所选账号。 +令牌解析支持账号感知。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账号。 +如果两个已启用的 Discord 账号解析到同一个机器人令牌，OpenClaw 只会为该令牌启动一个 Gateway 网关监视器。配置来源的令牌优先于默认环境变量回退；否则第一个启用的账号胜出，重复账号会被报告为已禁用。 +对于高级出站调用（消息工具/渠道操作），显式的逐调用 `token` 会用于该调用。这适用于发送和读取/探测类操作（例如读取/搜索/获取/线程/pins/权限）。账号策略/重试设置仍来自活动运行时快照中的选定账号。 ## 推荐：设置服务器工作区 -私信正常工作后，你可以将 Discord 服务器设置为完整工作区，让每个频道都有自己的智能体会话和上下文。对于只有你和机器人的私人服务器，推荐这样做。 +私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个频道都会获得自己的智能体会话和独立上下文。对于只有你和机器人的私人服务器，建议这样做。 - 这会让你的智能体在服务器上的任何频道中响应，而不只是私信。 + 这会让你的智能体在服务器上的任何频道中响应，而不仅仅是私信。 @@ -257,11 +257,11 @@ openclaw pairing approve discord 默认情况下，你的智能体只有在服务器频道中被 @mentioned 时才会响应。对于私人服务器，你可能希望它响应每条消息。 - 在服务器频道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须通过 `message` 工具显式发送，因此智能体默认可以静默旁观，并且只在它判断频道回复有用时发帖。 + 在服务器频道中，普通助手的最终回复默认保持私密。可见的 Discord 输出必须通过 `message` 工具显式发送，因此智能体可以默认旁听，只在判断频道回复有用时发帖。 - > “允许我的智能体在这个服务器上响应，而不需要被 @mentioned” + > “允许我的智能体在这个服务器上无需被 @mentioned 就能响应” 在你的服务器配置中设置 `requireMention: false`： @@ -295,32 +295,36 @@ openclaw pairing approve discord > “当我在 Discord 频道中提问时，如果你需要来自 MEMORY.md 的长期上下文，请使用 memory_search 或 memory_get。” - 如果你需要在每个频道中共享上下文，请将稳定指令放入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并在需要时通过记忆工具访问。 + 如果你需要在每个频道中共享上下文，请将稳定指令放入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并按需通过记忆工具访问它们。 -现在在你的 Discord 服务器上创建一些频道并开始聊天。你的智能体可以看到频道名称，并且每个频道都有自己的隔离会话，因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的频道。 +现在在你的 Discord 服务器上创建一些频道并开始聊天。你的智能体可以看到频道名称，并且每个频道都会获得自己的隔离会话，因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的频道。 ## 运行时模型 -- Gateway 网关负责 Discord 连接。 +- Gateway 网关拥有 Discord 连接。 - 回复路由是确定性的：Discord 入站回复会回到 Discord。 -- Discord 服务器/渠道元数据会作为不受信任的上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果模型把该封套复制回来，OpenClaw 会从出站回复和未来的重放上下文中剥离复制的元数据。 +- Discord 服务器/频道元数据会作为不受信任的上下文添加到模型提示中， + 而不是作为用户可见的回复前缀。如果模型把该封套复制回来， + OpenClaw 会从出站回复和未来的重放上下文中剥离复制的元数据。 - 默认情况下（`session.dmScope=main`），直接聊天共享智能体主会话（`agent:main:main`）。 -- 服务器渠道使用隔离的会话键（`agent::discord:channel:`）。 +- 服务器频道使用隔离的会话键（`agent::discord:channel:`）。 - 群组私信默认会被忽略（`channels.discord.dm.groupEnabled=false`）。 -- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 到路由后的对话会话。 -- 发送到 Discord 的纯文本定时任务/Heartbeat 公告只使用一次最终对助手可见的答案。当智能体发出多个可投递 payload 时，媒体和结构化组件 payload 仍会以多条消息发送。 +- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 到已路由的对话会话。 +- 只含文本的 cron/heartbeat 公告投递到 Discord 时，会使用最终的 + 助手可见答案一次。媒体和结构化组件载荷在智能体发出多个可投递载荷时， + 仍会作为多条消息发送。 -## 论坛渠道 +## 论坛频道 -Discord 论坛和媒体渠道只接受帖子线程。OpenClaw 支持两种创建方式： +Discord 论坛和媒体频道只接受线程帖子。OpenClaw 支持两种创建方式： -- 向论坛父级（`channel:`）发送消息以自动创建线程。线程标题使用你消息的第一行非空内容。 -- 使用 `openclaw message thread create` 直接创建线程。不要为论坛渠道传递 `--message-id`。 +- 向论坛父级（`channel:`）发送消息以自动创建线程。线程标题使用你的消息中第一行非空内容。 +- 使用 `openclaw message thread create` 直接创建线程。不要为论坛频道传入 `--message-id`。 示例：发送到论坛父级以创建线程 @@ -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 components v2 容器。使用带有 `components` payload 的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 +OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带有 `components` 载荷的消息工具。交互结果会作为正常入站消息路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 支持的块： @@ -350,15 +354,15 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 默认情况下，组件只能使用一次。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前多次使用。 -要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 +若要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉框，以及一个提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，只有调用用户可以使用它。 +`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单以及提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，且只有调用用户可以使用它。 文件附件： - `file` 块必须指向附件引用（`attachment://`） - 通过 `media`/`path`/`filePath` 提供附件（单个文件）；多个文件请使用 `media-gallery` -- 当上传名称需要匹配附件引用时，使用 `filename` 覆盖上传名称 +- 当上传名称应与附件引用匹配时，使用 `filename` 覆盖上传名称 模态表单： @@ -431,30 +435,30 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `open`（要求 `channels.discord.allowFrom` 包含 `"*"`） - `disabled` - 如果私信策略不是开放的，未知用户会被阻止（或在 `pairing` 模式下被提示配对）。 + 如果私信策略不是 open，未知用户会被阻止（或在 `pairing` 模式下被提示配对）。 - 多账户优先级： + 多账号优先级： - - `channels.discord.accounts.default.allowFrom` 仅适用于 `default` 账户。 - - 对于单个账户，`allowFrom` 优先于旧版 `dm.allowFrom`。 - - 当命名账户自身的 `allowFrom` 和旧版 `dm.allowFrom` 未设置时，会继承 `channels.discord.allowFrom`。 - - 命名账户不会继承 `channels.discord.accounts.default.allowFrom`。 + - `channels.discord.accounts.default.allowFrom` 仅适用于 `default` 账号。 + - 对于一个账号，`allowFrom` 优先于旧版 `dm.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:` 条目。 - 访问组名称会在消息渠道之间共享。对于静态组，请使用 `type: "message.senders"`，其成员以每个渠道的常规 `allowFrom` 语法表达；当 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 components v2 容器。使用带 } ``` - Discord 文本渠道没有单独的成员列表。`type: "discord.channelAudience"` 将成员资格建模为：私信发送者是已配置服务器的成员，并且在应用角色和渠道覆盖后，当前对已配置渠道拥有有效的 `ViewChannel` 权限。 + Discord 文本频道没有单独的成员列表。`type: "discord.channelAudience"` 将成员资格建模为：私信发送者是已配置服务器的成员，并且在应用角色和频道覆盖后，当前对已配置频道拥有有效的 `ViewChannel` 权限。 - 示例：允许任何可以看到 `#maintainers` 的人向机器人发送私信，同时对其他所有人保持私信关闭。 + 示例：允许任何能看到 `#maintainers` 的人向机器人发送私信，同时对其他所有人保持私信关闭。 ```json5 { @@ -500,7 +504,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 你可以混合动态和静态条目： + 你可以混合使用动态和静态条目： ```json5 { @@ -520,9 +524,9 @@ OpenClaw 支持用于智能体消息的 Discord components 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 components 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` + - 服务器必须匹配 `channels.discord.guilds`（首选 `id`，也接受 slug） + - 可选发送者允许列表：`users`（推荐稳定 ID）和 `roles`（仅角色 ID）；如果配置了任一项，则发送者匹配 `users` 或 `roles` 时会被允许 + - 默认禁用直接名称/标签匹配；仅将 `channels.discord.dangerouslyAllowNameMatching: true` 作为紧急兼容模式启用 - `users` 支持名称/标签，但 ID 更安全；使用名称/标签条目时，`openclaw security audit` 会发出警告 - - 如果服务器配置了 `channels`，未列出的渠道会被拒绝 - - 如果服务器没有 `channels` 块，该允许列表服务器中的所有渠道都会被允许 + - 如果服务器配置了 `channels`，未列出的频道会被拒绝 + - 如果服务器没有 `channels` 块，则该已加入允许列表的服务器中的所有频道都会被允许 示例： @@ -568,35 +572,35 @@ OpenClaw 支持用于智能体消息的 Discord components 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`） + - 在支持的情况下，隐式回复机器人行为 - 编写出站 Discord 消息时，请使用规范提及语法：用户用 `<@USER_ID>`，渠道用 `<#CHANNEL_ID>`，角色用 `<@&ROLE_ID>`。不要使用旧版 `<@!USER_ID>` 昵称提及形式。 + 编写出站 Discord 消息时，请使用规范提及语法：用户使用 `<@USER_ID>`，频道使用 `<#CHANNEL_ID>`，角色使用 `<@&ROLE_ID>`。不要使用旧版 `<@!USER_ID>` 昵称提及形式。 - `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 或 parent-peer 绑定之后、仅服务器绑定之前求值。如果绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 ```json5 { @@ -620,15 +624,15 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` -## 原生命令和命令授权 +## 原生命令和命令认证 -- `commands.native` 默认为 `"auto"`，并为 Discord 启用。 +- `commands.native` 默认为 `"auto"`，并对 Discord 启用。 - 按渠道覆盖：`channels.discord.commands.native`。 -- `commands.native=false` 会在启动期间跳过 Discord 斜杠命令注册和清理。先前注册的命令可能仍会在 Discord 中可见，直到你从 Discord 应用中移除它们。 -- 原生命令认证使用与普通消息处理相同的 Discord allowlist/策略。 -- 对未授权用户，命令可能仍会在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 认证并返回 “not authorized”。 +- `commands.native=false` 会在启动期间跳过 Discord 斜杠命令注册和清理。之前注册的命令可能仍会在 Discord 中可见，直到你从 Discord 应用中移除它们。 +- 原生命令鉴权使用与普通消息处理相同的 Discord allowlists/policies。 +- 对未授权用户，命令可能仍会在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 鉴权，并返回 "not authorized"。 -有关命令目录和行为，请参阅[斜杠命令](/zh-CN/tools/slash-commands)。 +请参阅[斜杠命令](/zh-CN/tools/slash-commands)了解命令目录和行为。 默认斜杠命令设置： @@ -638,7 +642,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - Discord 支持在智能体输出中使用回复标签： + Discord 支持 agent 输出中的回复标签： - `[[reply_to_current]]` - `[[reply_to:]]` @@ -650,18 +654,18 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `all` - `batched` - 注意：`off` 会禁用隐式回复串联。显式 `[[reply_to_*]]` 标签仍会生效。 - `first` 始终会把隐式原生回复引用附加到本轮的第一条出站 Discord 消息。 - `batched` 只会在入站轮次是由多条消息防抖合并成的批次时，才附加 Discord 的隐式原生回复引用。这个选项适用于你希望原生回复主要用于含义不明确的突发聊天，而不是每一个单消息轮次的场景。 + 注意：`off` 会禁用隐式回复串接。显式 `[[reply_to_*]]` 标签仍会被遵循。 + `first` 始终把隐式原生回复引用附加到该轮的第一条出站 Discord 消息。 + `batched` 仅当入站轮次是多条消息的防抖批次时，才附加 Discord 的隐式原生回复引用。这在你希望主要为含义不明确的突发聊天使用原生回复，而不是每个单消息轮次都使用时很有用。 - 消息 ID 会暴露在上下文/历史中，因此智能体可以定位特定消息。 + 消息 ID 会在上下文/历史中暴露，因此 agent 可以定位特定消息。 - OpenClaw 可以通过发送临时消息并在文本到达时编辑它来流式传输草稿回复。`channels.discord.streaming` 接受 `off`（默认）| `partial` | `block` | `progress`。在 Discord 上，`progress` 会映射到 `partial`；`streamMode` 是旧版别名，会自动迁移。 + OpenClaw 可以通过发送临时消息，并在文本到达时编辑它来流式传输回复草稿。`channels.discord.streaming` 接受 `off`（默认）| `partial` | `block` | `progress`。`progress` 会保留一个可编辑的 Status 草稿，并用工具进度更新它，直到最终投递；`streamMode` 是旧版别名，会自动迁移。 - 默认保持为 `off`，因为当多个机器人或 Gateway 网关共享一个账号时，Discord 预览编辑会很快触发速率限制。 + 默认值保持为 `off`，因为当多个机器人或 Gateway 网关共用一个账号时，Discord 预览编辑很快会触及速率限制。 ```json5 { @@ -679,19 +683,19 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 ``` - `partial` 会在 token 到达时编辑单条预览消息。 - - `block` 会发出草稿大小的分块（使用 `draftChunk` 调整大小和断点，并被限制在 `textChunkLimit` 内）。 + - `block` 会发出草稿大小的分块（使用 `draftChunk` 调整大小和断点，并限制在 `textChunkLimit` 内）。 - 媒体、错误和显式回复的最终消息会取消待处理的预览编辑。 - `streaming.preview.toolProgress`（默认 `true`）控制工具/进度更新是否复用预览消息。 - 预览流式传输仅支持文本；媒体回复会回退到普通投递。当显式启用 `block` streaming 时，OpenClaw 会跳过预览流，以避免双重流式传输。 + 预览流式传输仅支持文本；媒体回复会回退为普通投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 - - 服务器历史上下文： + + Guild 历史上下文： - - `channels.discord.historyLimit` 默认值 `20` - - 回退项：`messages.groupChat.historyLimit` + - `channels.discord.historyLimit` 默认 `20` + - fallback：`messages.groupChat.historyLimit` - `0` 禁用 私信历史控制： @@ -699,28 +703,28 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` - 线程行为： + 话题串行为： - - Discord 线程会路由为渠道会话，并继承父渠道配置，除非被覆盖。 - - 线程会话会继承父渠道的会话级 `/model` 选择，作为仅模型回退；线程本地 `/model` 选择仍然优先，且不会复制父转录历史，除非启用了转录继承。 - - `channels.discord.thread.inheritParent`（默认 `false`）会让新的自动线程从父转录初始化。按账号覆盖位于 `channels.discord.accounts..thread.inheritParent` 下。 + - Discord 话题串会作为渠道会话路由，并继承父渠道配置，除非被覆盖。 + - 话题串会话继承父渠道的会话级 `/model` 选择，作为仅模型 fallback；话题串本地的 `/model` 选择仍优先，并且除非启用 transcript 继承，否则不会复制父 transcript 历史。 + - `channels.discord.thread.inheritParent`（默认 `false`）让新的自动话题串选择从父 transcript 播种。按账号覆盖位于 `channels.discord.accounts..thread.inheritParent` 下。 - 消息工具反应可以解析 `user:` 私信目标。 - - `guilds..channels..requireMention: false` 会在回复阶段激活回退期间保留。 + - `guilds..channels..requireMention: false` 会在回复阶段激活 fallback 期间保留。 - 渠道主题会作为**不可信**上下文注入。allowlist 限制谁可以触发智能体，但并不是完整的补充上下文脱敏边界。 + 渠道主题会作为**不受信任**的上下文注入。Allowlists 限制谁可以触发 agent，而不是完整的补充上下文脱敏边界。 - - Discord 可以将线程绑定到会话目标，这样该线程中的后续消息会继续路由到同一会话（包括子智能体会话）。 + + Discord 可以将一个话题串绑定到一个会话目标，使该话题串中的后续消息继续路由到同一个会话（包括 subagent 会话）。 命令： - - `/focus ` 将当前/新线程绑定到子智能体/会话目标 - - `/unfocus` 移除当前线程绑定 + - `/focus ` 将当前/新话题串绑定到 subagent/会话目标 + - `/unfocus` 移除当前话题串绑定 - `/agents` 显示活跃运行和绑定状态 - - `/session idle ` 查看/更新已聚焦绑定的不活跃自动取消聚焦时间 - - `/session max-age ` 查看/更新已聚焦绑定的硬性最大时长 + - `/session idle ` 查看/更新聚焦绑定的不活跃自动取消聚焦时间 + - `/session max-age ` 查看/更新聚焦绑定的硬性最大年龄 配置： @@ -751,21 +755,21 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `session.threadBindings.*` 设置全局默认值。 - `channels.discord.threadBindings.*` 覆盖 Discord 行为。 - - `spawnSessions` 控制为 `sessions_spawn({ thread: true })` 和 ACP 线程生成自动创建/绑定线程。默认值：`true`。 - - `defaultSpawnContext` 控制线程绑定生成的原生子智能体上下文。默认值：`"fork"`。 + - `spawnSessions` 控制为 `sessions_spawn({ thread: true })` 和 ACP 话题串生成自动创建/绑定话题串。默认：`true`。 + - `defaultSpawnContext` 控制线程绑定生成的原生 subagent 上下文。默认：`"fork"`。 - 已弃用的 `spawnSubagentSessions`/`spawnAcpSessions` 键会由 `openclaw doctor --fix` 迁移。 - - 如果某个账号禁用了线程绑定，则 `/focus` 和相关线程绑定操作不可用。 + - 如果某个账号禁用了话题串绑定，则 `/focus` 和相关话题串绑定操作不可用。 - 请参阅[子智能体](/zh-CN/tools/subagents)、[ACP 智能体](/zh-CN/tools/acp-agents)和[配置参考](/zh-CN/gateway/configuration-reference)。 + 请参阅 [Sub-agents](/zh-CN/tools/subagents)、[ACP Agents](/zh-CN/tools/acp-agents) 和[配置参考](/zh-CN/gateway/configuration-reference)。 - 对于稳定的“always-on” ACP 工作区，请配置顶层类型化 ACP 绑定，目标指向 Discord 会话。 + 对于稳定的“始终在线” ACP 工作区，请配置顶层类型化 ACP 绑定，以定位 Discord 对话。 配置路径： - - `bindings[]`，其中 `type: "acp"` 且 `match.channel: "discord"` + - `bindings[]`，包含 `type: "acp"` 和 `match.channel: "discord"` 示例： @@ -817,47 +821,47 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 注意： - - `/acp spawn codex --bind here` 会就地绑定当前渠道或线程，并让未来消息保持在同一个 ACP 会话上。线程消息会继承父渠道绑定。 - - 在已绑定的渠道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时线程绑定在活跃时可以覆盖目标解析。 - - `spawnSessions` 通过 `--thread auto|here` 控制子线程创建/绑定。 + - `/acp spawn codex --bind here` 会在当前位置绑定当前渠道或话题串，并让未来消息继续使用同一个 ACP 会话。话题串消息继承父渠道绑定。 + - 在已绑定的渠道或话题串中，`/new` 和 `/reset` 会在原地重置同一个 ACP 会话。临时话题串绑定在活跃时可以覆盖目标解析。 + - `spawnSessions` 通过 `--thread auto|here` 控制子话题串创建/绑定。 - 有关绑定行为详情，请参阅 [ACP 智能体](/zh-CN/tools/acp-agents)。 + 请参阅 [ACP Agents](/zh-CN/tools/acp-agents) 了解绑定行为详情。 - 按服务器设置的反应通知模式： + 按 guild 设置反应通知模式： - `off` - `own`（默认） - `all` - `allowlist`（使用 `guilds..users`） - 反应事件会转换为系统事件，并附加到路由后的 Discord 会话。 + 反应事件会被转换为系统事件，并附加到路由到的 Discord 会话。 - `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 + `ackReaction` 会在 OpenClaw 处理入站消息时发送确认 emoji。 解析顺序： - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） + - agent 身份 emoji fallback（`agents.list[].identity.emoji`，否则为 "👀"） 注意： - - Discord 接受 Unicode 表情符号或自定义表情符号名称。 - - 使用 `""` 可为渠道或账号禁用该反应。 + - Discord 接受 Unicode emoji 或自定义 emoji 名称。 + - 使用 `""` 可禁用某个渠道或账号的反应。 默认启用由渠道发起的配置写入。 - 这会影响 `/config set|unset` 流程（启用命令功能时）。 + 这会影响 `/config set|unset` 流程（当命令功能启用时）。 禁用： @@ -922,15 +926,15 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 注意： - - allowlist 可以使用 `pk:` - - 只有当 `channels.discord.dangerouslyAllowNameMatching: true` 时，成员显示名称才会按名称/slug 匹配 - - 查询使用原始消息 ID，并受时间窗口约束 + - allowlists 可以使用 `pk:` + - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，成员显示名称才会按 name/slug 匹配 + - 查询使用原始消息 ID，并受时间窗口限制 - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非 `allowBots=true` - 当智能体需要对已知 Discord 用户进行确定性的出站提及时，使用 `mentionAliases`。键是不带前导 `@` 的 handle；值是 Discord 用户 ID。未知 handle、`@everyone`、`@here` 以及 Markdown 代码 span 中的提及会保持不变。 + 当 agent 需要对已知 Discord 用户进行确定性的出站提及时，使用 `mentionAliases`。键是不带前导 `@` 的 handle；值是 Discord 用户 ID。未知 handle、`@everyone`、`@here` 以及 Markdown 代码跨度中的提及会保持不变。 ```json5 { @@ -954,9 +958,9 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - 当你设置状态或活动字段，或启用自动在线状态时，会应用在线状态更新。 + 当你设置 Status 或活动字段，或启用自动在线状态时，会应用在线状态更新。 - 仅状态示例： + 仅 Status 示例： ```json5 { @@ -968,7 +972,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 活动示例（自定义状态是默认活动类型）： + 活动示例（自定义 Status 是默认活动类型）： ```json5 { @@ -997,12 +1001,12 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 活动类型映射： - - 0：正在玩 - - 1：正在直播（需要 `activityUrl`） - - 2：正在听 - - 3：正在看 - - 4：自定义（使用活动文本作为状态状态；表情符号可选） - - 5：正在竞赛 + - 0: Playing + - 1: Streaming（需要 `activityUrl`） + - 2: Listening + - 3: Watching + - 4: Custom（使用活动文本作为 Status 状态；emoji 可选） + - 5: Competing 自动在线状态示例（运行时健康信号）： @@ -1021,7 +1025,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 自动在线状态会将运行时可用性映射到 Discord 状态：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： + 自动在线状态会将运行时可用性映射到 Discord Status：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -1029,70 +1033,70 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - - Discord 支持在私信中通过按钮处理批准，并可选择在来源渠道中发布批准提示。 + + Discord 支持在私信中基于按钮处理审批，并可选择在来源渠道中发布审批提示。 配置路径： - `channels.discord.execApprovals.enabled` - `channels.discord.execApprovals.approvers`（可选；可行时回退到 `commands.ownerAllowFrom`） - - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认值：`dm`） + - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` - 当 `enabled` 未设置或为 `"auto"`，并且至少可以解析出一个审批者时，Discord 会自动启用原生执行审批；审批者可来自 `execApprovals.approvers` 或 `commands.ownerAllowFrom`。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或直接消息 `defaultTo` 推断执行审批者。设置 `enabled: false` 可明确禁用 Discord 作为原生审批客户端。 + 当 `enabled` 未设置或为 `"auto"`，且至少可以从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个批准者时，Discord 会自动启用原生 exec 批准。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或直接消息 `defaultTo` 推断 exec 批准者。设置 `enabled: false` 可明确禁用 Discord 作为原生批准客户端。 - 对于 `/diagnostics` 和 `/export-trajectory` 等敏感的仅 owner 群组命令，OpenClaw 会私下发送审批提示和最终结果。当发起调用的 owner 有 Discord owner 路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的 owner 路由，例如 Telegram。 + 对于 `/diagnostics` 和 `/export-trajectory` 等敏感的仅限所有者群组命令，OpenClaw 会私下发送批准提示和最终结果。当发起调用的所有者有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 - 当 `target` 为 `channel` 或 `both` 时，审批提示会在渠道中可见。只有已解析的审批者可以使用按钮；其他用户会收到一条临时拒绝消息。审批提示会包含命令文本，因此只应在受信任的渠道中启用渠道投递。如果无法从会话键中推导出渠道 ID，OpenClaw 会回退到私信投递。 + 当 `target` 为 `channel` 或 `both` 时，批准提示会在渠道中可见。只有已解析的批准者可以使用按钮；其他用户会收到一条临时拒绝消息。批准提示包含命令文本，因此只应在可信渠道中启用渠道投递。如果无法从会话键派生渠道 ID，OpenClaw 会回退到私信投递。 - Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要添加审批者私信路由和渠道扇出。 - 当这些按钮存在时，它们就是主要审批 UX；只有当工具结果表明 - 聊天审批不可用或手动审批是唯一路径时，OpenClaw + Discord 也会渲染其他聊天渠道使用的共享批准按钮。原生 Discord 适配器主要增加批准者私信路由和渠道扇出。 + 当这些按钮存在时，它们是主要批准 UX；只有当工具结果表明 + 聊天批准不可用，或手动批准是唯一路径时，OpenClaw 才应包含手动 `/approve` 命令。 - 如果 Discord 原生审批运行时未激活，OpenClaw 会保持 + 如果 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 分钟后过期。 - 参见 [执行审批](/zh-CN/tools/exec-approvals)。 + 参见 [Exec approvals](/zh-CN/tools/exec-approvals)。 -## 工具和操作闸门 +## 工具和操作门控 Discord 消息操作包括消息、渠道管理、审核、在线状态和元数据操作。 核心示例： - 消息：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` -- 反应：`react`、`reactions`、`emojiList` +- 表情回应：`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 | 已启用 | +| roles | 已禁用 | +| moderation | 已禁用 | +| presence | 已禁用 | ## Components v2 UI -OpenClaw 使用 Discord components v2 来处理执行审批和跨上下文标记。Discord 消息操作也可以接受 `components` 以实现自定义 UI（高级用法；需要通过 discord 工具构造组件载荷），而旧版 `embeds` 仍可使用，但不推荐。 +OpenClaw 使用 Discord components v2 处理 exec 批准和跨上下文标记。Discord 消息操作也可以接受 `components` 以提供自定义 UI（高级用法；需要通过 discord 工具构造组件载荷），旧版 `embeds` 仍然可用，但不推荐使用。 - `channels.discord.ui.components.accentColor` 设置 Discord 组件容器使用的强调色（十六进制）。 -- 使用 `channels.discord.accounts..ui.components.accentColor` 按账户设置。 -- 当 components v2 存在时，`embeds` 会被忽略。 +- 使用 `channels.discord.accounts..ui.components.accentColor` 为每个账号设置。 +- 当存在 components v2 时，`embeds` 会被忽略。 示例： @@ -1112,20 +1116,20 @@ OpenClaw 使用 Discord components v2 来处理执行审批和跨上下文标记 ## 语音 -Discord 有两种不同的语音表面：实时**语音频道**（连续对话）和**语音消息附件**（波形预览格式）。Gateway 网关两者都支持。 +Discord 有两个不同的语音表面：实时**语音频道**（连续对话）和**语音消息附件**（波形预览格式）。Gateway 网关同时支持两者。 ### 语音频道 -设置清单： +设置检查清单： 1. 在 Discord Developer Portal 中启用 Message Content Intent。 -2. 当使用角色/用户 allowlist 时，启用 Server Members Intent。 -3. 使用 `bot` 和 `applications.commands` scope 邀请 bot。 +2. 使用角色/用户 allowlist 时，启用 Server Members Intent。 +3. 使用 `bot` 和 `applications.commands` scope 邀请机器人。 4. 在目标语音频道中授予 Connect、Speak、Send Messages 和 Read Message History 权限。 5. 启用原生命令（`commands.native` 或 `channels.discord.commands.native`）。 6. 配置 `channels.discord.voice`。 -使用 `/vc join|leave|status` 控制会话。该命令使用账户默认智能体，并遵循与其他 Discord 命令相同的 allowlist 和群组策略规则。 +使用 `/vc join|leave|status` 控制会话。该命令使用账号默认智能体，并遵循与其他 Discord 命令相同的 allowlist 和群组策略规则。 ```bash /vc join channel: @@ -1164,36 +1168,36 @@ Discord 有两种不同的语音表面：实时**语音频道**（连续对话 说明： -- `voice.tts` 仅覆盖语音播放的 `messages.tts`。 -- `voice.model` 仅覆盖用于 Discord 语音频道响应的 LLM。保持未设置即可继承路由后的智能体模型。 -- STT 使用 `tools.media.audio`；`voice.model` 不影响转录。 -- 按渠道设置的 Discord `systemPrompt` 覆盖项会应用到该语音频道的语音转录轮次。 -- 语音转录轮次从 Discord `allowFrom`（或 `dm.allowFrom`）推导 owner 状态；非 owner 发言者无法访问仅 owner 工具（例如 `gateway` 和 `cron`）。 -- 对于纯文本配置，Discord 语音是选择启用的；设置 `channels.discord.voice.enabled=true`（或保留现有 `channels.discord.voice` 块）以启用 `/vc` 命令、语音运行时和 `GuildVoiceStates` Gateway 网关 intent。 +- `voice.tts` 仅覆盖语音播放使用的 `messages.tts`。 +- `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。 - `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 修复，该 PR 关闭了 discord.js issue #11419。 +- `voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试的初始 `@discordjs/voice` Ready 等待时间。默认：`30000`。 +- `voice.reconnectGraceMs` 控制 OpenClaw 在销毁已断开的语音会话前，等待其开始重新连接的时长。默认：`15000`。 +- OpenClaw 还会监控接收解密失败，并在短时间窗口内反复失败后，通过离开并重新加入语音频道来自动恢复。 +- 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 系列包含来自 discord.js PR #11449 的上游填充修复，该修复关闭了 discord.js issue #11419。 语音频道流水线： -- Discord PCM 捕获会转换为 WAV 临时文件。 +- Discord PCM 捕获会被转换为 WAV 临时文件。 - `tools.media.audio` 处理 STT，例如 `openai/gpt-4o-mini-transcribe`。 -- 转录文本会通过 Discord 入口和路由发送，同时响应 LLM 会以语音输出策略运行；该策略隐藏智能体 `tts` 工具并要求返回文本，因为 Discord 语音负责最终 TTS 播放。 -- 设置 `voice.model` 时，它仅覆盖此语音频道轮次的响应 LLM。 +- 转写文本会通过 Discord 入口和路由发送，同时响应 LLM 会以语音输出策略运行，该策略会隐藏智能体 `tts` 工具并要求返回文本，因为 Discord 语音负责最终 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 会被拒绝）。 -- 省略文本内容（Discord 拒绝在同一载荷中同时发送文本 + 语音消息）。 +- 省略文本内容（Discord 会拒绝同一载荷中的文本 + 语音消息）。 - 接受任何音频格式；OpenClaw 会按需转换为 OGG/Opus。 ```bash @@ -1203,7 +1207,7 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## 故障排除 - + - 启用 Message Content Intent - 当你依赖用户/成员解析时，启用 Server Members Intent @@ -1211,11 +1215,11 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a - + - 验证 `groupPolicy` - - 验证 `channels.discord.guilds` 下的服务器 allowlist - - 如果服务器 `channels` 映射存在，则只允许列出的渠道 + - 验证 `channels.discord.guilds` 下的 guild allowlist + - 如果存在 guild `channels` 映射，则只允许列出的渠道 - 验证 `requireMention` 行为和提及模式 有用的检查： @@ -1231,9 +1235,9 @@ openclaw logs --follow 常见原因： - - `groupPolicy="allowlist"` 但没有匹配的服务器/渠道 allowlist - - `requireMention` 配置在了错误的位置（必须位于 `channels.discord.guilds` 或渠道条目下） - - 发送者被服务器/渠道 `users` allowlist 阻止 + - `groupPolicy="allowlist"` 没有匹配的 guild/渠道 allowlist + - `requireMention` 配置在错误位置（必须位于 `channels.discord.guilds` 或渠道条目下） + - 发送者被 guild/渠道 `users` allowlist 阻止 @@ -1246,11 +1250,11 @@ openclaw logs --follow Discord Gateway 网关队列旋钮： - - 单账户：`channels.discord.eventQueue.listenerTimeout` - - 多账户：`channels.discord.accounts..eventQueue.listenerTimeout` + - 单账号：`channels.discord.eventQueue.listenerTimeout` + - 多账号：`channels.discord.accounts..eventQueue.listenerTimeout` - 这只控制 Discord Gateway 网关监听器工作，不控制智能体轮次生命周期 - Discord 不会对排队的智能体轮次应用渠道拥有的超时。消息监听器会立即交接，排队的 Discord 运行会保持每个会话的顺序，直到会话/工具/运行时生命周期完成或中止该工作。 + Discord 不会对排队的智能体轮次应用渠道拥有的超时。消息监听器会立即移交，排队的 Discord 运行会保持每个会话的顺序，直到会话/工具/运行时生命周期完成或中止该工作。 ```json5 { @@ -1271,28 +1275,28 @@ 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` + - 默认：`30000`（30 秒），最大值：`120000` - OpenClaw 会在启动期间以及运行时重新连接后等待 Discord 的网关 `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` @@ -1301,7 +1305,7 @@ openclaw logs --follow `channels status --probe` 权限检查仅适用于数字渠道 ID。 - 如果你使用 slug 键，运行时匹配仍然可以工作，但 probe 无法完整验证权限。 + 如果你使用 slug 键，运行时匹配仍然可以工作，但探测无法完整验证权限。 @@ -1313,11 +1317,11 @@ openclaw logs --follow - - 默认情况下，机器人发送的消息会被忽略。 + + 默认会忽略由 bot 发送的消息。 - 如果设置 `channels.discord.allowBots=true`，请使用严格的提及和允许列表规则来避免循环行为。 - 建议使用 `channels.discord.allowBots="mentions"`，只接受提及该机器人的机器人消息。 + 如果你设置了 `channels.discord.allowBots=true`，请使用严格的提及和允许名单规则，以避免循环行为。 + 优先使用 `channels.discord.allowBots="mentions"`，仅接受提及该 bot 的 bot 消息。 ```json5 { @@ -1346,13 +1350,13 @@ openclaw logs --follow - - 保持 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 接收历史进行对比 @@ -1369,11 +1373,11 @@ openclaw logs --follow - 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` - Gateway 网关：`gatewayInfoTimeoutMs`、`gatewayReadyTimeoutMs`、`gatewayRuntimeReadyTimeoutMs` - 回复/历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` -- 交付：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` +- 发送：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` - 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` -- 媒体/重试：`mediaMaxMb`（限制出站 Discord 上传，默认 `100MB`）、`retry` +- 媒体/重试：`mediaMaxMb`（限制发往 Discord 的上传，默认 `100MB`）、`retry` - 操作：`actions.*` -- 在线状态：`activity`、`status`、`activityType`、`activityUrl` +- Presence：`activity`、`status`、`activityType`、`activityUrl` - UI：`ui.components.accentColor` - 功能：`threadBindings`、顶层 `bindings[]`（`type: "acp"`）、`pluralkit`、`execApprovals`、`intents`、`agentComponents`、`heartbeat`、`responsePrefix` @@ -1381,9 +1385,9 @@ openclaw logs --follow ## 安全和运维 -- 将机器人 token 视为机密（在受监管环境中建议使用 `DISCORD_BOT_TOKEN`）。 -- 授予最小权限的 Discord 权限。 -- 如果命令部署/状态已过期，请重启 Gateway 网关并使用 `openclaw channels status --probe` 重新检查。 +- 将 bot 令牌视为机密（在受监督环境中优先使用 `DISCORD_BOT_TOKEN`）。 +- 授予最小权限 Discord 权限。 +- 如果命令部署/状态过期，请重启 Gateway 网关，并用 `openclaw channels status --probe` 重新检查。 ## 相关内容 @@ -1392,7 +1396,7 @@ openclaw logs --follow 将 Discord 用户配对到 Gateway 网关。 - 群聊和允许列表行为。 + 群聊和允许名单行为。 将入站消息路由到智能体。 @@ -1401,7 +1405,7 @@ openclaw logs --follow 威胁模型和加固。 - 将服务器和渠道映射到智能体。 + 将 guild 和渠道映射到智能体。 原生命令行为。 diff --git a/docs/zh-CN/channels/telegram.md b/docs/zh-CN/channels/telegram.md index e369cb656..77464e83e 100644 --- a/docs/zh-CN/channels/telegram.md +++ b/docs/zh-CN/channels/telegram.md @@ -1,42 +1,42 @@ --- read_when: - - 处理 Telegram 功能或网络钩子 + - 处理 Telegram 功能或 webhook summary: Telegram 机器人支持状态、能力和配置 title: Telegram x-i18n: - generated_at: "2026-05-03T19:29:14Z" + generated_at: "2026-05-03T21:05:28Z" model: gpt-5.5 provider: openai - source_hash: 06252b1540d5794aa5d8fe1066bf9d121e682a0df969a265d890445e97d5d647 + source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0 source_path: channels/telegram.md workflow: 16 --- -Production-ready for bot DMs and groups via grammY. Long polling is the default mode; webhook mode is optional. +可用于生产环境中的 bot 私信和群组，基于 grammY。长轮询是默认模式；webhook 模式是可选项。 - - Default DM policy for Telegram is pairing. + + Telegram 的默认私信策略是配对。 - - Cross-channel diagnostics and repair playbooks. + + 跨渠道诊断和修复手册。 - - Full channel config patterns and examples. + + 完整的渠道配置模式和示例。 -## Quick setup +## 快速设置 - - Open Telegram and chat with **@BotFather** (confirm the handle is exactly `@BotFather`). + + 打开 Telegram 并与 **@BotFather** 聊天（确认句柄完全是 `@BotFather`）。 - Run `/newbot`, follow prompts, and save the token. + 运行 `/newbot`，按提示操作，并保存 token。 - + ```json5 { @@ -51,12 +51,12 @@ Production-ready for bot DMs and groups via grammY. Long polling is the default } ``` - Env fallback: `TELEGRAM_BOT_TOKEN=...` (default account only). - Telegram does **not** use `openclaw channels login telegram`; configure token in config/env, then start gateway. + 环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。 + Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置 token，然后启动 Gateway 网关。 - + ```bash openclaw gateway @@ -64,119 +64,119 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Pairing codes expire after 1 hour. + 配对码将在 1 小时后过期。 - - Add the bot to your group, then set `channels.telegram.groups` and `groupPolicy` to match your access model. + + 将 bot 添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy`，以匹配你的访问模型。 -Token resolution order is account-aware. In practice, config values win over env fallback, and `TELEGRAM_BOT_TOKEN` only applies to the default account. +token 解析顺序感知账号。实践中，配置值优先于环境变量回退，且 `TELEGRAM_BOT_TOKEN` 只适用于默认账号。 -## Telegram side settings +## Telegram 侧设置 - - Telegram bots default to **Privacy Mode**, which limits what group messages they receive. + + Telegram bot 默认启用 **Privacy Mode**，这会限制它们能接收哪些群组消息。 - If the bot must see all group messages, either: + 如果 bot 必须看到所有群组消息，请执行以下任一操作： - - disable privacy mode via `/setprivacy`, or - - make the bot a group admin. + - 通过 `/setprivacy` 禁用隐私模式，或 + - 将 bot 设为群组管理员。 - When toggling privacy mode, remove + re-add the bot in each group so Telegram applies the change. + 切换隐私模式时，请在每个群组中移除并重新添加 bot，以便 Telegram 应用更改。 - - Admin status is controlled in Telegram group settings. + + 管理员状态在 Telegram 群组设置中控制。 - Admin bots receive all group messages, which is useful for always-on group behavior. + 管理员 bot 会接收所有群组消息，这对始终在线的群组行为很有用。 - + - - `/setjoingroups` to allow/deny group adds - - `/setprivacy` for group visibility behavior + - `/setjoingroups` 用于允许/拒绝添加到群组 + - `/setprivacy` 用于群组可见性行为 -## Access control and activation +## 访问控制和激活 - - `channels.telegram.dmPolicy` controls direct message access: + + `channels.telegram.dmPolicy` 控制直接消息访问： - - `pairing` (default) - - `allowlist` (requires at least one sender ID in `allowFrom`) - - `open` (requires `allowFrom` to include `"*"`) + - `pairing`（默认） + - `allowlist`（要求 `allowFrom` 中至少有一个发送者 ID） + - `open`（要求 `allowFrom` 包含 `"*"`） - `disabled` - `dmPolicy: "open"` with `allowFrom: ["*"]` lets any Telegram account that finds or guesses the bot username command the bot. Use it only for intentionally public bots with tightly restricted tools; one-owner bots should use `allowlist` with numeric user IDs. + `dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到 bot 用户名的 Telegram 账号都能命令该 bot。仅将其用于有意公开且工具受到严格限制的 bot；单所有者 bot 应使用 `allowlist` 并搭配数字用户 ID。 - `channels.telegram.allowFrom` accepts numeric Telegram user IDs. `telegram:` / `tg:` prefixes are accepted and normalized. - In multi-account configs, a restrictive top-level `channels.telegram.allowFrom` is treated as a safety boundary: account-level `allowFrom: ["*"]` entries do not make that account public unless the effective account allowlist still contains an explicit wildcard after merging. - `dmPolicy: "allowlist"` with empty `allowFrom` blocks all DMs and is rejected by config validation. - Setup asks for numeric user IDs only. - If you upgraded and your config contains `@username` allowlist entries, run `openclaw doctor --fix` to resolve them (best-effort; requires a Telegram bot token). - If you previously relied on pairing-store allowlist files, `openclaw doctor --fix` can recover entries into `channels.telegram.allowFrom` in allowlist flows (for example when `dmPolicy: "allowlist"` has no explicit IDs yet). + `channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。 + 在多账号配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账号级 `allowFrom: ["*"]` 条目不会让该账号公开，除非合并后的有效账号允许列表仍包含显式通配符。 + `dmPolicy: "allowlist"` 搭配空的 `allowFrom` 会阻止所有私信，并会被配置验证拒绝。 + 设置只会要求数字用户 ID。 + 如果你已升级且配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram bot token）。 + 如果你之前依赖配对存储的允许列表文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。 - For one-owner bots, prefer `dmPolicy: "allowlist"` with explicit numeric `allowFrom` IDs to keep access policy durable in config (instead of depending on previous pairing approvals). + 对于单所有者 bot，建议使用 `dmPolicy: "allowlist"` 并搭配显式数字 `allowFrom` ID，以便在配置中保持持久的访问策略（而不是依赖之前的配对批准）。 - Common confusion: DM pairing approval does not mean "this sender is authorized everywhere". - Pairing grants DM access. If no command owner exists yet, the first approved pairing also sets `commands.ownerAllowFrom` so owner-only commands and exec approvals have an explicit operator account. - Group sender authorization still comes from explicit config allowlists. - If you want "I am authorized once and both DMs and group commands work", put your numeric Telegram user ID in `channels.telegram.allowFrom`; for owner-only commands, make sure `commands.ownerAllowFrom` contains `telegram:`. + 常见误解：批准私信配对并不意味着“此发送者在所有地方都已获授权”。 + 配对授予私信访问权限。如果尚无命令所有者，第一次获批的配对还会设置 `commands.ownerAllowFrom`，使仅所有者命令和 exec 批准拥有显式操作员账号。 + 群组发送者授权仍来自显式配置允许列表。 + 如果你希望“我授权一次后，私信和群组命令都能使用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:`。 - ### Finding your Telegram user ID + ### 查找你的 Telegram 用户 ID - Safer (no third-party bot): + 更安全（无第三方 bot）： - 1. DM your bot. - 2. Run `openclaw logs --follow`. - 3. Read `from.id`. + 1. 私信你的 bot。 + 2. 运行 `openclaw logs --follow`。 + 3. 读取 `from.id`。 - Official Bot API method: + 官方 Bot API 方法： ```bash curl "https://api.telegram.org/bot/getUpdates" ``` - Third-party method (less private): `@userinfobot` or `@getidsbot`. + 第三方方法（隐私性较低）：`@userinfobot` 或 `@getidsbot`。 - - Two controls apply together: + + 两项控制共同生效： - 1. **Which groups are allowed** (`channels.telegram.groups`) - - no `groups` config: - - with `groupPolicy: "open"`: any group can pass group-ID checks - - with `groupPolicy: "allowlist"` (default): groups are blocked until you add `groups` entries (or `"*"`) - - `groups` configured: acts as allowlist (explicit IDs or `"*"`) + 1. **允许哪些群组**（`channels.telegram.groups`） + - 没有 `groups` 配置： + - 使用 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查 + - 使用 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`） + - 已配置 `groups`：作为允许列表（显式 ID 或 `"*"`） - 2. **Which senders are allowed in groups** (`channels.telegram.groupPolicy`) + 2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`） - `open` - - `allowlist` (default) + - `allowlist`（默认） - `disabled` - `groupAllowFrom` is used for group sender filtering. If not set, Telegram falls back to `allowFrom`. - `groupAllowFrom` entries should be numeric Telegram user IDs (`telegram:` / `tg:` prefixes are normalized). - Do not put Telegram group or supergroup chat IDs in `groupAllowFrom`. Negative chat IDs belong under `channels.telegram.groups`. - Non-numeric entries are ignored for sender authorization. - Security boundary (`2026.2.25+`): group sender auth does **not** inherit DM pairing-store approvals. - Pairing stays DM-only. For groups, set `groupAllowFrom` or per-group/per-topic `allowFrom`. - If `groupAllowFrom` is unset, Telegram falls back to config `allowFrom`, not the pairing store. - Practical pattern for one-owner bots: set your user ID in `channels.telegram.allowFrom`, leave `groupAllowFrom` unset, and allow the target groups under `channels.telegram.groups`. - Runtime note: if `channels.telegram` is completely missing, runtime defaults to fail-closed `groupPolicy="allowlist"` unless `channels.defaults.groupPolicy` is explicitly set. + `groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。 + `groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。 + 不要将 Telegram 群组或超级群组 chat ID 放入 `groupAllowFrom`。负数 chat ID 应放在 `channels.telegram.groups` 下。 + 非数字条目会在发送者授权中被忽略。 + 安全边界（`2026.2.25+`）：群组发送者认证**不会**继承私信配对存储批准。 + 配对仅限私信。对于群组，请设置 `groupAllowFrom` 或每群组/每 topic 的 `allowFrom`。 + 如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。 + 单所有者 bot 的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。 + 运行时说明：如果 `channels.telegram` 完全缺失，运行时会默认故障关闭为 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。 - Example: allow any member in one specific group: + 示例：允许一个特定群组中的任何成员： ```json5 { @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Example: allow only specific users inside one specific group: + 示例：只允许一个特定群组内的特定用户： ```json5 { @@ -211,34 +211,34 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - Common mistake: `groupAllowFrom` is not a Telegram group allowlist. + 常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。 - - Put negative Telegram group or supergroup chat IDs like `-1001234567890` under `channels.telegram.groups`. - - Put Telegram user IDs like `8734062810` under `groupAllowFrom` when you want to limit which people inside an allowed group can trigger the bot. - - Use `groupAllowFrom: ["*"]` only when you want any member of an allowed group to be able to talk to the bot. + - 将 `-1001234567890` 这样的负数 Telegram 群组或超级群组 chat ID 放在 `channels.telegram.groups` 下。 + - 当你想限制已允许群组内哪些人可以触发 bot 时，将 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 + - 仅当你希望已允许群组的任何成员都能与 bot 对话时，才使用 `groupAllowFrom: ["*"]`。 - - Group replies require mention by default. + + 群组回复默认要求提及。 - Mention can come from: + 提及可以来自： - - native `@botusername` mention, or - - mention patterns in: + - 原生 `@botusername` 提及，或 + - 以下位置中的提及模式： - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Session-level command toggles: + 会话级命令开关： - `/activation always` - `/activation mention` - These update session state only. Use config for persistence. + 这些只会更新会话状态。使用配置来持久化。 - Persistent config example: + 持久配置示例： ```json5 { @@ -252,44 +252,44 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Getting the group chat ID: + 获取群组 chat ID： - - forward a group message to `@userinfobot` / `@getidsbot` - - or read `chat.id` from `openclaw logs --follow` - - or inspect Bot API `getUpdates` + - 将群组消息转发给 `@userinfobot` / `@getidsbot` + - 或从 `openclaw logs --follow` 读取 `chat.id` + - 或检查 Bot API `getUpdates` -## Runtime behavior +## 运行时行为 -- Telegram is owned by the gateway process. -- Routing is deterministic: Telegram inbound replies back to Telegram (the model does not pick channels). -- Inbound messages normalize into the shared channel envelope with reply metadata and media placeholders. -- Group sessions are isolated by group ID. Forum topics append `:topic:` to keep topics isolated. -- DM messages can carry `message_thread_id`; OpenClaw preserves the thread ID for replies but keeps DMs on the flat session by default. Configure `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true`, or a matching topic config when you intentionally want DM topic session isolation. -- Long polling uses grammY runner with per-chat/per-thread sequencing. Overall runner sink concurrency uses `agents.defaults.maxConcurrent`. -- Long polling is guarded inside each gateway process so only one active poller can use a bot token at a time. If you still see `getUpdates` 409 conflicts, another OpenClaw gateway, script, or external poller is likely using the same token. -- Long-polling watchdog restarts trigger after 120 seconds without completed `getUpdates` liveness by default. Increase `channels.telegram.pollingStallThresholdMs` only if your deployment still sees false polling-stall restarts during long-running work. The value is in milliseconds and is allowed from `30000` to `600000`; per-account overrides are supported. -- Telegram Bot API has no read-receipt support (`sendReadReceipts` does not apply). +- Telegram 由 Gateway 网关进程拥有。 +- 路由是确定性的：Telegram 入站会回复到 Telegram（模型不会选择渠道）。 +- 入站消息会规范化为共享渠道信封，并带有回复元数据和媒体占位符。 +- 群组会话按群组 ID 隔离。论坛 topic 会追加 `:topic:` 以保持 topic 隔离。 +- 私信消息可以携带 `message_thread_id`；OpenClaw 会保留线程 ID 用于回复，但默认将私信保留在扁平会话中。当你有意希望进行私信 topic 会话隔离时，请配置 `channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct..threadReplies: "inbound"`、`requireTopic: true`，或匹配的 topic 配置。 +- 长轮询使用 grammY runner，并按每个 chat/每个 thread 排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。 +- 长轮询在每个 Gateway 网关进程内部受保护，因此同一时间只有一个活跃 poller 可以使用一个 bot token。如果你仍看到 `getUpdates` 409 冲突，很可能是另一个 OpenClaw Gateway 网关、脚本或外部 poller 正在使用同一个 token。 +- 默认情况下，长轮询 watchdog 会在 120 秒内没有完成的 `getUpdates` 活性后触发重启。仅当你的部署在长时间运行任务期间仍出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。 +- Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。 -## Feature reference +## 功能参考 - - OpenClaw can stream partial replies in real time: + + OpenClaw 可以实时流式传输部分回复： - - direct chats: preview message + `editMessageText` - - groups/topics: preview message + `editMessageText` + - 直接聊天：预览消息 + `editMessageText` + - 群组/topic：预览消息 + `editMessageText` - Requirement: + 要求： - - `channels.telegram.streaming` is `off | partial | block | progress` (default: `partial`) - - `progress` maps to `partial` on Telegram (compat with cross-channel naming) - - `streaming.preview.toolProgress` controls whether tool/progress updates reuse the same edited preview message (default: `true` when preview streaming is active) - - legacy `channels.telegram.streamMode` and boolean `streaming` values are detected; run `openclaw doctor --fix` to migrate them to `channels.telegram.streaming.mode` + - `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`） + - `progress` 会保留一个可编辑的状态草稿，并用工具进度更新它，直到最终交付 + - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（当预览流式传输处于活动状态时，默认：`true`） + - 旧版 `channels.telegram.streamMode` 和布尔 `streaming` 值会被检测到；运行 `openclaw doctor --fix` 将它们迁移到 `channels.telegram.streaming.mode` - Tool-progress preview updates are the short "Working..." lines shown while tools run, for example command execution, file reads, planning updates, or patch summaries. Telegram keeps these enabled by default to match released OpenClaw behavior from `v2026.4.22` and later. To keep the edited preview for answer text but hide tool-progress lines, set: + 工具进度预览更新是在工具运行时显示的短状态行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持这些更新启用，以匹配 `v2026.4.22` 及之后版本发布的 OpenClaw 行为。若要保留答案文本的已编辑预览，但隐藏工具进度行，请设置： ```json { @@ -306,30 +306,30 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 仅在你希望仅最终交付时使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立的 “Working...” 消息发送。审批提示、媒体载荷和错误仍会通过正常的最终交付路径路由。仅当你希望保留答案预览编辑，同时隐藏工具进度状态行时，使用 `streaming.preview.toolProgress: false`。 + Use `streaming.mode: "off"` 仅在你想要仅最终内容投递时使用：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立 Status 消息发送。审批提示、媒体载荷和错误仍会通过正常的最终投递路径发送。当你只想保留答案预览编辑，同时隐藏工具进度 Status 行时，请使用 `streaming.preview.toolProgress: false`。 - Telegram 选中引用回复是例外。当 `replyToMode` 为 `"first"`、`"all"` 或 `"batched"`，且入站消息包含选中的引用文本时，OpenClaw 会通过 Telegram 原生引用回复路径发送最终答案，而不是编辑答案预览，因此 `streaming.preview.toolProgress` 无法为该轮显示简短的 “Working...” 行。没有选中引用文本的当前消息回复仍会保留预览流式传输。当工具进度可见性比原生引用回复更重要时，设置 `replyToMode: "off"`；或者设置 `streaming.preview.toolProgress: false` 以确认这一权衡。 + Telegram 选中文本引用回复是例外。当 `replyToMode` 为 `"first"`、`"all"` 或 `"batched"`，且入站消息包含选中的引用文本时，OpenClaw 会通过 Telegram 的原生引用回复路径发送最终答案，而不是编辑答案预览，因此 `streaming.preview.toolProgress` 无法为该轮显示短 Status 行。没有选中引用文本的当前消息回复仍会保留预览流式传输。当工具进度可见性比原生引用回复更重要时，请设置 `replyToMode: "off"`；或者设置 `streaming.preview.toolProgress: false` 以确认这一取舍。 对于纯文本回复： - - 简短的私信/群组/topic 预览：OpenClaw 会保留同一条预览消息，并在原位置执行最终编辑，除非预览出现后发送过可见的非预览消息 - - 预览后跟随可见的非预览输出：OpenClaw 会将完成后的回复作为新的最终消息发送，并清理较旧的预览，因此最终答案会出现在中间输出之后 - - 超过约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳反映的是完成时间，而不是预览创建时间 + - 短私信/群组/topic 预览：OpenClaw 会保留同一条预览消息，并在原处执行最终编辑，除非预览出现后发送过可见的非预览消息 + - 预览后跟随可见的非预览输出：OpenClaw 会将完成后的回复作为新的最终消息发送，并清理旧预览，因此最终答案会出现在中间输出之后 + - 超过约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 可见时间戳会反映完成时间，而不是预览创建时间 - 对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终交付，然后清理预览消息。 + 对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终投递，然后清理预览消息。 - 预览流式传输独立于分块流式传输。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 + 预览流式传输与分块流式传输相互独立。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 仅限 Telegram 的推理流： - - `/reasoning stream` 会在生成过程中将推理发送到实时预览 + - `/reasoning stream` 会在生成时把推理发送到实时预览 - 最终答案发送时不包含推理文本 - + 出站文本使用 Telegram `parse_mode: "HTML"`。 - 类 Markdown 文本会渲染为 Telegram 安全的 HTML。 @@ -364,24 +364,24 @@ curl "https://api.telegram.org/bot/getUpdates" 规则： - - 名称会被规范化（去掉开头的 `/`，转为小写） + - 名称会被规范化（移除开头的 `/`，转为小写） - 有效模式：`a-z`、`0-9`、`_`，长度 `1..32` - 自定义命令不能覆盖原生命令 - 冲突/重复项会被跳过并记录日志 - 注意事项： + 注意： - 自定义命令只是菜单项；它们不会自动实现行为 - - plugin/skill 命令即使未显示在 Telegram 菜单中，输入时仍可生效 + - 插件/skill 命令即使未显示在 Telegram 菜单中，输入时仍可工作 - 如果原生命令被禁用，内置命令会被移除。自定义/plugin 命令在配置后仍可能注册。 + 如果禁用原生命令，内置项会被移除。自定义/插件命令在配置后仍可注册。 常见设置失败： - - `setMyCommands failed` 搭配 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然溢出；减少 plugin/skill/自定义命令，或禁用 `channels.telegram.commands.native`。 - - 当直接的 Bot API curl 命令可用，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 失败并显示 `404: Not Found` 时，可能表示 `channels.telegram.apiRoot` 被设置成了完整的 `/bot` 端点。`apiRoot` 必须只是 Bot API 根地址，并且 `openclaw doctor --fix` 会移除意外附加的尾部 `/bot`。 - - `getMe returned 401` 表示 Telegram 拒绝了配置的机器人 token。使用当前 BotFather token 更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。 - - `setMyCommands failed` 搭配网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻断。 + - `setMyCommands failed` 伴随 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然溢出；请减少插件/skill/自定义命令，或禁用 `channels.telegram.commands.native`。 + - 当直接 Bot API curl 命令可用，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 失败并显示 `404: Not Found` 时，可能表示 `channels.telegram.apiRoot` 被设置成了完整的 `/bot` 端点。`apiRoot` 必须只是 Bot API 根地址，并且 `openclaw doctor --fix` 会移除意外尾随的 `/bot`。 + - `getMe returned 401` 表示 Telegram 拒绝了配置的 bot 令牌。请使用当前 BotFather 令牌更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。 + - `setMyCommands failed` 伴随网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。 ### 设备配对命令（`device-pair` 插件） @@ -395,9 +395,9 @@ curl "https://api.telegram.org/bot/getUpdates" - 只有一个待处理请求时使用 `/pair approve` - `/pair approve latest` 用于最近的请求 - 设置代码携带一个短期有效的 bootstrap token。内置 bootstrap 交接会将主节点 token 保持在 `scopes: []`；任何被交接的 operator token 都限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap 作用域检查带有角色前缀，因此该 operator 允许列表只满足 operator 请求；非 operator 角色仍需要位于自身角色前缀下的作用域。 + 设置代码携带一个短期有效的 bootstrap 令牌。内置 bootstrap 交接会让主节点令牌保持在 `scopes: []`；任何交接出去的 operator 令牌都会被限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 范围内。Bootstrap 作用域检查带有角色前缀，因此该 operator 允许列表只满足 operator 请求；非 operator 角色仍需要其自身角色前缀下的作用域。 - 如果设备使用变更后的认证详情重试（例如角色/作用域/公钥），先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 + 如果设备使用变更后的认证详情（例如角色/作用域/公钥）重试，之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。 @@ -446,7 +446,7 @@ curl "https://api.telegram.org/bot/getUpdates" 旧版 `capabilities: ["inlineButtons"]` 会映射到 `inlineButtons: "all"`。 - 消息操作示例： + 消息动作示例： ```json5 { @@ -469,8 +469,8 @@ curl "https://api.telegram.org/bot/getUpdates" - - Telegram 工具操作包括： + + Telegram 工具动作包括： - `sendMessage`（`to`、`content`、可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`） - `react`（`chatId`、`messageId`、`emoji`） @@ -478,7 +478,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `editMessage`（`chatId`、`messageId`、`content`） - `createForumTopic`（`chatId`、`name`、可选 `iconColor`、`iconCustomEmojiId`） - 渠道消息操作提供易用别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。 + 渠道消息动作会暴露符合人体工程学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。 门控控制项： @@ -488,14 +488,14 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.sticker`（默认：禁用） 注意：`edit` 和 `topic-create` 目前默认启用，且没有单独的 `channels.telegram.actions.*` 开关。 - 运行时发送使用当前有效的配置/secret 快照（启动/重载），因此操作路径不会在每次发送时执行临时 SecretRef 重新解析。 + 运行时发送使用活动配置/密钥快照（启动/重载），因此动作路径不会在每次发送时执行临时 SecretRef 重新解析。 - 移除回应的语义：[/tools/reactions](/zh-CN/tools/reactions) + Reaction 移除语义：[/tools/reactions](/zh-CN/tools/reactions) - Telegram 支持在生成的输出中使用显式回复线程标签： + Telegram 支持在生成输出中使用显式回复线程标签： - `[[reply_to_current]]` 回复触发消息 - `[[reply_to:]]` 回复特定的 Telegram 消息 ID @@ -506,29 +506,29 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - 启用回复线程且原始 Telegram 文本或说明可用时，OpenClaw 会自动包含一段原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 代码单元，因此较长消息会从开头开始引用；如果 Telegram 拒绝该引用，则回退为普通回复。 + 当启用回复线程，且原始 Telegram 文本或标题可用时，OpenClaw 会自动包含一段原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 代码单元，因此更长的消息会从开头引用；如果 Telegram 拒绝该引用，则会回退为普通回复。 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。 - + 论坛超级群组： - topic 会话键追加 `:topic:` - - 回复和正在输入状态会指向 topic 线程 + - 回复和输入状态会面向 topic 线程 - topic 配置路径： `channels.telegram.groups..topics.` - 常规 topic（`threadId=1`）特殊情况： + General topic（`threadId=1`）特殊情况： - - 消息发送会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`） - - 正在输入操作仍会包含 `message_thread_id` + - 消息发送会省略 `message_thread_id`（Telegram 拒绝 `sendMessage(...thread_id=1)`） + - 输入状态动作仍会包含 `message_thread_id` Topic 继承：topic 条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 - `agentId` 仅限 topic，不会从群组默认值继承。 + `agentId` 仅属于 topic，不会从群组默认值继承。 - **按 topic 的智能体路由**：每个 topic 都可以通过在 topic 配置中设置 `agentId` 路由到不同智能体。这让每个 topic 都拥有自己的隔离工作区、记忆和会话。示例： + **按 topic 的智能体路由**：每个 topic 都可以通过在 topic 配置中设置 `agentId` 路由到不同的智能体。这让每个 topic 拥有自己隔离的工作区、记忆和会话。示例： ```json5 { @@ -548,26 +548,28 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 随后每个 topic 都会有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3` + 然后每个 topic 都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3` - **持久 ACP topic 绑定**：论坛 topic 可以通过顶层 typed ACP 绑定固定 ACP harness 会话（`bindings[]`，其中 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的 topic 限定 id）。目前作用域限于群组/超级群组中的论坛 topic。参见 [ACP Agents](/zh-CN/tools/acp-agents)。 + **持久 ACP topic 绑定**：论坛 topic 可以通过顶层类型化 ACP 绑定（`bindings[]`，其中 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的 topic 限定 ID）固定 ACP harness 会话。目前作用域限定为群组/超级群组中的论坛 topic。参见 [ACP Agents](/zh-CN/tools/acp-agents)。 - **从聊天派生线程绑定 ACP**：`/acp spawn --thread here|auto` 会将当前 topic 绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在 topic 内固定派生确认消息。需要保持启用 `channels.telegram.threadBindings.spawnSessions`（默认：`true`）。 + **从聊天生成线程绑定的 ACP**：`/acp spawn --thread here|auto` 会将当前 topic 绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在 topic 内固定生成确认。要求 `channels.telegram.threadBindings.spawnSessions` 保持启用（默认：`true`）。 - 模板上下文公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天默认保留私信路由，并在扁平会话上保留回复元数据；只有在配置了 `threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true` 或匹配的 topic 配置时，才会使用线程感知的会话键。使用顶层 `channels.telegram.dm.threadReplies` 作为账户默认值，或使用 `direct..threadReplies` 配置单个私信。 + 模板上下文会暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天默认会在扁平会话上保留私信路由和回复元数据；只有配置了 `threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true`，或匹配的 topic 配置时，才会使用线程感知会话键。使用顶层 `channels.telegram.dm.threadReplies` 作为账户默认值，或使用 `direct..threadReplies` 配置某个私信。 ### 音频消息 - Telegram 会区分语音消息和音频文件。 + Telegram 区分语音消息和音频文件。 - 默认：音频文件行为 - - 在智能体回复中使用标签 `[[audio_as_voice]]` 以强制作为语音消息发送 - - 入站语音消息转写会在智能体上下文中被框定为机器生成的、不受信任文本；提及检测仍使用原始转写，因此需要提及门控的语音消息会继续工作。 + - 在智能体回复中使用标签 `[[audio_as_voice]]` 以强制按语音消息发送 + - 入站语音消息转录会在智能体上下文中被框定为机器生成的、 + 不受信任文本；提及检测仍使用原始 + 转录，因此受提及门控的语音消息会继续工作。 - 消息操作示例： + 消息动作示例： ```json5 { @@ -581,9 +583,9 @@ curl "https://api.telegram.org/bot/getUpdates" ### 视频消息 - Telegram 区分视频文件和圆形视频消息。 + Telegram 会区分视频文件和视频便笺。 - 消息 action 示例： + 消息操作示例： ```json5 { @@ -595,14 +597,14 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 圆形视频消息不支持说明文字；提供的消息文本会单独发送。 + 视频便笺不支持字幕；提供的消息文本会单独发送。 ### 贴纸 入站贴纸处理： - 静态 WEBP：下载并处理（占位符 ``） - - 动态 TGS：跳过 + - 动画 TGS：跳过 - 视频 WEBM：跳过 贴纸上下文字段： @@ -617,9 +619,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - 贴纸会被描述一次（如果可能）并缓存，以减少重复的视觉调用。 + 贴纸会被描述一次（如果可行）并缓存，以减少重复的视觉调用。 - 启用贴纸 action： + 启用贴纸操作： ```json5 { @@ -633,7 +635,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 发送贴纸 action： + 发送贴纸操作： ```json5 { @@ -644,7 +646,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 搜索已缓存的贴纸： + 搜索缓存的贴纸： ```json5 { @@ -658,7 +660,7 @@ curl "https://api.telegram.org/bot/getUpdates" - Telegram 回应会作为 `message_reaction` 更新到达（与消息负载分离）。 + Telegram 回应会以 `message_reaction` 更新到达（独立于消息载荷）。 启用后，OpenClaw 会将如下系统事件加入队列： @@ -672,12 +674,12 @@ curl "https://api.telegram.org/bot/getUpdates" 注意： - `own` 表示仅用户对机器人发送消息的回应（通过已发送消息缓存尽力判断）。 - - 回应事件仍会遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。 - - Telegram 不会在回应更新中提供话题 ID。 + - 回应事件仍遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。 + - Telegram 不会在回应更新中提供线程 ID。 - 非论坛群组路由到群聊会话 - - 论坛群组路由到群组通用话题会话（`:topic:1`），而不是确切的原始话题 + - 论坛群组路由到群组通用主题会话（`:topic:1`），而不是确切的原始主题 - 用于轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。 + 轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。 @@ -689,19 +691,19 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - agent 身份 emoji 回退（`agents.list[].identity.emoji`，否则为 "👀"） + - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 “👀”） 注意： - - Telegram 需要 unicode emoji（例如 "👀"）。 - - 使用 `""` 可为某个 channel 或账户禁用该回应。 + - Telegram 需要 Unicode emoji（例如 “👀”）。 + - 使用 `""` 可禁用某个渠道或账号的回应。 - channel 配置写入默认启用（`configWrites !== false`）。 + 渠道配置写入默认启用（`configWrites !== false`）。 - 由 Telegram 触发的写入包括： + Telegram 触发的写入包括： - 群组迁移事件（`migrate_to_chat_id`），用于更新 `channels.telegram.groups` - `/config set` 和 `/config unset`（需要启用命令） @@ -721,29 +723,29 @@ curl "https://api.telegram.org/bot/getUpdates" - 默认使用长轮询。对于 webhook 模式，请设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选项包括 `webhookPath`、`webhookHost`、`webhookPort`（默认值为 `/telegram-webhook`、`127.0.0.1`、`8787`）。 + 默认是长轮询。对于 webhook 模式，设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选 `webhookPath`、`webhookHost`、`webhookPort`（默认值为 `/telegram-webhook`、`127.0.0.1`、`8787`）。 - 本地监听器绑定到 `127.0.0.1:8787`。对于公开入口，要么在本地端口前放置反向代理，要么有意设置 `webhookHost: "0.0.0.0"`。 + 本地监听器绑定到 `127.0.0.1:8787`。对于公共入口，可以在本地端口前放置反向代理，或有意设置 `webhookHost: "0.0.0.0"`。 - Webhook 模式会先验证请求防护、Telegram secret token 和 JSON 正文，然后再向 Telegram 返回 `200`。 - 随后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道异步处理更新，因此缓慢的 agent 回合不会阻塞 Telegram 的投递 ACK。 + Webhook 模式会先验证请求防护、Telegram 密钥令牌和 JSON 正文，然后再向 Telegram 返回 `200`。 + 随后 OpenClaw 会通过与长轮询相同的按聊天/按主题机器人通道异步处理该更新，因此缓慢的智能体轮次不会占用 Telegram 的投递 ACK。 - `channels.telegram.textChunkLimit` 默认值为 4000。 - - `channels.telegram.chunkMode="newline"` 在按长度拆分前优先使用段落边界（空行）。 + - `channels.telegram.chunkMode="newline"` 会在按长度拆分前优先使用段落边界（空行）。 - `channels.telegram.mediaMaxMb`（默认 100）限制入站和出站 Telegram 媒体大小。 - - `channels.telegram.mediaGroupFlushMs`（默认 500）控制在 OpenClaw 将 Telegram 相册/媒体组作为一条入站消息分发前缓冲多久。如果相册部分到达较晚，请增大该值；如果要降低相册回复延迟，请减小该值。 - - `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。机器人客户端会将配置值限制在 60 秒出站文本/正在输入请求防护以下，以便 grammY 不会在 OpenClaw 的传输防护和回退运行前中止可见回复投递。长轮询仍使用 45 秒 `getUpdates` 请求防护，因此空闲轮询不会被无限期放弃。 + - `channels.telegram.mediaGroupFlushMs`（默认 500）控制 Telegram 相册/媒体组在 OpenClaw 将其作为一条入站消息派发前的缓冲时长。如果相册部分到达较晚，可以增大该值；如果想降低相册回复延迟，可以减小该值。 + - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。机器人客户端会将低于 60 秒出站文本/正在输入请求防护的配置值进行限制，这样 grammY 就不会在 OpenClaw 的传输防护和回退运行前中止可见回复投递。长轮询仍使用 45 秒的 `getUpdates` 请求防护，因此空闲轮询不会被无限期放弃。 - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在误报轮询停滞重启时，在 `30000` 到 `600000` 之间调整。 - 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。 - - 回复/引用/转发的补充上下文目前按接收内容传递。 - - Telegram 允许列表主要控制谁可以触发 agent，而不是完整的补充上下文删减边界。 + - 回复/引用/转发补充上下文目前按接收到的内容传递。 + - Telegram 允许列表主要控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 - 私信历史控制： - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - `channels.telegram.retry` 配置适用于 Telegram 发送辅助方法（CLI/工具/action），用于可恢复的出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能导致可见消息重复的不明确发送后网络信封。 + - `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/操作）中可恢复的出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能重复可见消息的模糊发送后网络信封。 CLI 发送目标可以是数字聊天 ID 或用户名： @@ -752,7 +754,7 @@ openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Telegram 投票使用 `openclaw message poll`，并支持论坛话题： + Telegram 投票使用 `openclaw message poll`，并支持论坛主题： ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -762,57 +764,57 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - 仅 Telegram 支持的投票标志： + 仅 Telegram 投票标志： - `--poll-duration-seconds`（5-600） - `--poll-anonymous` - `--poll-public` - - 用于论坛话题的 `--thread-id`（或使用 `:topic:` 目标） + - `--thread-id` 用于论坛主题（或使用 `:topic:` 目标） Telegram 发送还支持： - - 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 来生成内联键盘 - - 当机器人可以在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递 - - 使用 `--force-document` 将出站图片和 GIF 作为文档发送，而不是作为压缩照片或动态媒体上传 + - 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 来实现内联键盘 + - `--pin` 或 `--delivery '{"pin":true}'`，在机器人可在该聊天中置顶时请求置顶投递 + - `--force-document`，将出站图片和 GIF 作为文档发送，而不是压缩照片或动画媒体上传 - Action 门控： + 操作门控： - - `channels.telegram.actions.sendMessage=false` 会禁用出站 Telegram 消息，包括投票 - - `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，但保留常规发送启用 + - `channels.telegram.actions.sendMessage=false` 禁用出站 Telegram 消息，包括投票 + - `channels.telegram.actions.poll=false` 禁用 Telegram 投票创建，同时保留常规发送启用 - - Telegram 支持在审批者私信中进行 exec 审批，并可选择在原始聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。 + + Telegram 支持在审批者私信中进行执行审批，也可以选择在原始聊天或主题中发布提示。审批者必须是数字 Telegram 用户 ID。 配置路径： - - `channels.telegram.execApprovals.enabled`（当至少一个审批者可解析时自动启用） + - `channels.telegram.execApprovals.enabled`（至少有一个审批者可解析时自动启用） - `channels.telegram.execApprovals.approvers`（回退到 `commands.ownerAllowFrom` 中的数字所有者 ID） - `channels.telegram.execApprovals.target`：`dm`（默认）| `channel` | `both` - `agentFilter`、`sessionFilter` - `channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人对话，以及机器人将普通回复发送到哪里。它们不会让某人成为 exec 审批者。当还没有命令所有者时，首次获批的私信配对会引导写入 `commands.ownerAllowFrom`，因此单所有者设置仍然无需在 `execApprovals.approvers` 下重复 ID 即可工作。 + `channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人交谈，以及它在哪里发送普通回复。它们不会让某人成为执行审批者。当尚无命令所有者时，第一次获批的私信配对会引导写入 `commands.ownerAllowFrom`，因此单所有者设置仍可工作，而无需在 `execApprovals.approvers` 下重复 ID。 - channel 投递会在聊天中显示命令文本；仅在可信群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。Exec 审批默认在 30 分钟后过期。 + 渠道投递会在聊天中显示命令文本；仅在可信群组/主题中启用 `channel` 或 `both`。当提示落在论坛主题中时，OpenClaw 会为审批提示和后续回复保留该主题。执行审批默认 30 分钟后过期。 - 内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过 exec 审批解析。 + 内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过执行审批解析。 - 参见 [Exec 审批](/zh-CN/tools/exec-approvals)。 + 参见 [执行审批](/zh-CN/tools/exec-approvals)。 ## 错误回复控制 -当 agent 遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以抑制该回复。两个配置键控制此行为： +当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以抑制它。两个配置键控制此行为： -| 键 | 值 | 默认值 | 描述 | -| ----------------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 向同一聊天发送错误回复之间的最短时间。防止故障期间产生错误刷屏。 | +| 键 | 值 | 默认值 | 描述 | +| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 对同一聊天的错误回复之间的最短时间。防止故障期间出现错误刷屏。 | -支持按账户、按群组和按话题覆盖（继承方式与其他 Telegram 配置键相同）。 +支持按账号、按群组和按主题覆盖（与其他 Telegram 配置键使用相同继承规则）。 ```json5 { @@ -835,20 +837,20 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - - 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。 + - 如果 `requireMention=false`，Telegram 隐私模式必须允许完全可见。 - BotFather：`/setprivacy` -> Disable - 然后将机器人从群组移除并重新添加 - - 当配置预期接收未提及的群组消息时，`openclaw channels status` 会发出警告。 - - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法进行成员身份探测。 + - 当配置期望未提及的群组消息时，`openclaw channels status` 会发出警告。 + - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法进行成员探测。 - 快速会话测试：`/activation always`。 - - 当存在 `channels.telegram.groups` 时，必须列出该群组（或包含 `"*"`） + - 当 `channels.telegram.groups` 存在时，群组必须列出（或包含 `"*"`） - 验证机器人在群组中的成员身份 - - 查看日志：`openclaw logs --follow` 以了解跳过原因 + - 查看日志：`openclaw logs --follow`，了解跳过原因 @@ -856,32 +858,32 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - 授权你的发送者身份（配对和/或数字 `allowFrom`） - 即使群组策略为 `open`，命令授权仍然适用 - - `setMyCommands failed` 并带有 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单 - - 启动时的 `deleteMyCommands` / `setMyCommands` 调用以及 `sendChatAction` 正在输入调用都是有界的，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性问题 + - `setMyCommands failed` 与 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单 + - `deleteMyCommands` / `setMyCommands` 启动调用和 `sendChatAction` 正在输入调用是有界的，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性问题 - + - - `getMe returned 401` 是配置的机器人令牌发生 Telegram 身份验证失败。 - - 在 BotFather 中重新复制或重新生成机器人令牌，然后为默认账户更新 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts..botToken` 或 `TELEGRAM_BOT_TOKEN`。 - - 启动期间的 `deleteWebhook 401 Unauthorized` 也是身份验证失败；把它当作“不存在 webhook”只会把同一个无效令牌失败推迟到后续 API 调用。 + - `getMe returned 401` 是已配置机器人令牌的 Telegram 身份验证失败。 + - 在 BotFather 中重新复制或重新生成机器人令牌，然后为默认账号更新 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts..botToken` 或 `TELEGRAM_BOT_TOKEN`。 + - 启动期间的 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“不存在网络钩子”只会把同一个无效令牌故障推迟到后续 API 调用。 - - Node 22+ + 自定义 fetch/proxy 可能会在 AbortSignal 类型不匹配时触发立即中止行为。 - - 某些主机会先把 `api.telegram.org` 解析到 IPv6；损坏的 IPv6 出站连接可能导致间歇性的 Telegram API 失败。 + - Node 22+ 加自定义 fetch/代理在 AbortSignal 类型不匹配时可能触发立即中止行为。 + - 某些主机会先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站连接可能导致间歇性的 Telegram API 失败。 - 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复的网络错误重试。 - - 在轮询启动期间，OpenClaw 会为 grammY 复用成功的启动 `getMe` 探测，因此运行器在第一次 `getUpdates` 之前不需要第二次 `getMe`。 - - 如果 `deleteWebhook` 在轮询启动期间因瞬时网络错误失败，OpenClaw 会继续进入长轮询，而不是再发起一次轮询前控制平面调用。仍处于活动状态的 webhook 会表现为 `getUpdates` 冲突；随后 OpenClaw 会重建 Telegram 传输并重试 webhook 清理。 - - 如果 Telegram 套接字按很短的固定周期回收，请检查是否有过低的 `channels.telegram.timeoutSeconds`；机器人客户端会将低于出站和 `getUpdates` 请求保护阈值的配置值钳制到保护阈值以上，但旧版本在该值设置低于这些保护阈值时，可能会中止每次轮询或回复。 - - 如果日志包含 `Polling stall detected`，默认情况下，OpenClaw 会在 120 秒内没有完成长轮询活性检查后重启轮询并重建 Telegram 传输。 - - 当正在运行的轮询账户在启动宽限期后尚未完成 `getUpdates`、正在运行的 webhook 账户在启动宽限期后尚未完成 `setWebhook`，或上一次成功的轮询传输活动已经陈旧时，`openclaw channels status --probe` 和 `openclaw doctor` 会发出警告。 - - 只有当长时间运行的 `getUpdates` 调用是健康的，但你的主机仍然报告误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出站问题。 - - Telegram 还会遵循进程代理环境变量用于 Bot API 传输，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 及其小写变体。`NO_PROXY` / `no_proxy` 仍可绕过 `api.telegram.org`。 - - 如果 OpenClaw 托管代理在服务环境中通过 `OPENCLAW_PROXY_URL` 配置，且不存在标准代理环境变量，Telegram 也会将该 URL 用于 Bot API 传输。 + - 在轮询启动期间，OpenClaw 会为 grammY 复用启动时成功的 `getMe` 探测，因此运行器在第一次 `getUpdates` 之前不需要第二次 `getMe`。 + - 如果轮询启动期间 `deleteWebhook` 因瞬时网络错误而失败，OpenClaw 会继续进入长轮询，而不是再发起一次轮询前控制平面调用。仍处于活动状态的网络钩子会表现为 `getUpdates` 冲突；随后 OpenClaw 会重建 Telegram 传输层并重试网络钩子清理。 + - 如果 Telegram 套接字按较短的固定周期回收，请检查 `channels.telegram.timeoutSeconds` 是否过低；机器人客户端会把低于出站请求和 `getUpdates` 请求保护下限的配置值提升到该下限，但旧版本在该值设为低于这些保护阈值时，可能会中止每一次轮询或回复。 + - 如果日志包含 `Polling stall detected`，默认情况下，OpenClaw 会在 120 秒内没有完成长轮询活性检查后重启轮询并重建 Telegram 传输层。 + - 当正在运行的轮询账号在启动宽限期后仍未完成 `getUpdates`、正在运行的网络钩子账号在启动宽限期后仍未完成 `setWebhook`，或上次成功的轮询传输活动已过期时，`openclaw channels status --probe` 和 `openclaw doctor` 会发出警告。 + - 仅当长时间运行的 `getUpdates` 调用是健康的，但你的主机仍报告误判的轮询停滞重启时，才增大 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出站问题。 + - Telegram 还会为 Bot API 传输遵循进程代理环境变量，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 及其小写变体。`NO_PROXY` / `no_proxy` 仍可绕过 `api.telegram.org`。 + - 如果服务环境通过 `OPENCLAW_PROXY_URL` 配置了 OpenClaw 托管代理，且不存在标准代理环境变量，Telegram 也会使用该 URL 进行 Bot API 传输。 - 在直接出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用： ```yaml @@ -890,8 +892,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）。Telegram DNS 结果顺序依次遵循 `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`、`channels.telegram.network.dnsResultOrder`，再到进程默认值，例如 `NODE_OPTIONS=--dns-result-order=ipv4first`；如果都不适用，Node 22+ 会回退到 `ipv4first`。 - - 如果你的主机是 WSL2，或明确更适合仅 IPv4 行为，请强制选择地址族： + - Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）。Telegram DNS 结果顺序会依次遵循 `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`、`channels.telegram.network.dnsResultOrder`，然后遵循进程默认值，例如 `NODE_OPTIONS=--dns-result-order=ipv4first`；如果都不适用，Node 22+ 会回退到 `ipv4first`。 + - 如果你的主机是 WSL2，或明确在仅 IPv4 行为下表现更好，请强制设置地址族选择： ```yaml channels: @@ -900,7 +902,10 @@ channels: autoSelectFamily: false ``` - - 默认情况下，Telegram 媒体下载已允许 RFC 2544 基准测试范围地址（`198.18.0.0/15`）。如果可信的 fake-IP 或透明代理在媒体下载期间把 `api.telegram.org` 重写为其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过： + - RFC 2544 基准测试范围响应（`198.18.0.0/15`）默认已允许 + 用于 Telegram 媒体下载。如果受信任的 fake-IP 或 + 透明代理在媒体下载期间把 `api.telegram.org` 重写为其他 + 私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过： ```yaml channels: @@ -909,20 +914,25 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - 同一个选择启用项也可按账户在 + - 同样的选择加入也可以按账号在 `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` 配置。 - - 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544 基准测试范围。 + - 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持 + 危险标志关闭。Telegram 媒体默认已允许 RFC 2544 + 基准测试范围。 `channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram - 媒体 SSRF 防护。仅在可信、由操作员控制的代理环境中使用它，例如 Clash、Mihomo 或 Surge fake-IP 路由，且它们会在 RFC 2544 基准测试范围之外合成私有或特殊用途答案。对于正常的公网 Telegram 访问，请保持关闭。 + 媒体 SSRF 防护。仅在受信任、由运维方控制的代理环境中使用它， + 例如 Clash、Mihomo 或 Surge fake-IP 路由，并且这些环境会合成 + RFC 2544 基准测试范围以外的私有或特殊用途响应。普通公共互联网 + Telegram 访问应保持关闭。 - 环境覆盖（临时）： - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - 验证 DNS 答案： + - 验证 DNS 响应： ```bash dig +short api.telegram.org A @@ -938,34 +948,34 @@ dig +short api.telegram.org AAAA 主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。 - + - 启动/身份验证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝） - 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、顶层 `bindings[]`（`type: "acp"`） -- 执行批准：`execApprovals`、`accounts.*.execApprovals` +- 执行审批：`execApprovals`、`accounts.*.execApprovals` - 命令/菜单：`commands.native`、`commands.nativeSkills`、`customCommands` - 线程/回复：`replyToMode`、`dm.threadReplies`、`direct.*.threadReplies` - 流式传输：`streaming`（预览）、`streaming.preview.toolProgress`、`blockStreaming` - 格式化/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix` - 媒体/网络：`mediaMaxMb`、`mediaGroupFlushMs`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy` -- 自定义 API 根：`apiRoot`（仅 Bot API 根；不要包含 `/bot`） -- webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost` +- 自定义 API 根地址：`apiRoot`（仅 Bot API 根地址；不要包含 `/bot`） +- 网络钩子：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost` - 操作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker` -- 表情回应：`reactionNotifications`、`reactionLevel` +- 回应：`reactionNotifications`、`reactionLevel` - 错误：`errorPolicy`、`errorCooldownMs` -- 写入/历史：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` +- 写入/历史记录：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` -多账户优先级：配置两个或更多账户 ID 时，请设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`）以明确默认路由。否则 OpenClaw 会回退到第一个规范化账户 ID，且 `openclaw doctor` 会发出警告。命名账户会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 值。 +多账号优先级：当配置了两个或更多账号 ID 时，设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`）以明确默认路由。否则 OpenClaw 会回退到第一个规范化后的账号 ID，并且 `openclaw doctor` 会发出警告。命名账号会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 值。 ## 相关内容 - 将 Telegram 用户配对到 Gateway 网关。 + 将 Telegram 用户与 Gateway 网关配对。 群组和话题允许列表行为。 diff --git a/docs/zh-CN/concepts/progress-drafts.md b/docs/zh-CN/concepts/progress-drafts.md new file mode 100644 index 000000000..6704134ed --- /dev/null +++ b/docs/zh-CN/concepts/progress-drafts.md @@ -0,0 +1,254 @@ +--- +read_when: + - 为长时间运行的聊天轮次配置可见的进度更新 + - 在部分、分块和进度流式传输模式之间选择 + - 解释 OpenClaw 如何在工作进行期间更新一条渠道消息 + - 进度草稿、独立进度消息或最终化回退的故障排除 +summary: 进度草稿：智能体运行时会更新的一条可见的进行中消息 +title: 进度草稿 +x-i18n: + generated_at: "2026-05-03T21:05:45Z" + model: gpt-5.5 + provider: openai + source_hash: 0fc0dff38232228b49872d66f4498f065675cdd3abf3a0f4003cb34fcbb7de8c + source_path: concepts/progress-drafts.md + workflow: 16 +--- + +进度草稿让长时间运行的智能体回合在聊天中显得仍然活跃，同时不会把对话变成一堆临时状态回复。 + +启用进度草稿后，OpenClaw 会创建一条可见的进行中消息，在智能体读取、规划、调用工具或等待批准时更新它，然后在渠道可以安全执行时，将该草稿转换为最终答案。 + +```text +Shelling +- reading recent channel context +- checking matching issues +- preparing reply +``` + +当你希望在工具密集型工作期间只显示一条整洁的状态消息，并在回合完成后显示最终答案时，请使用进度草稿。 + +## 快速开始 + +使用 `streaming.mode: "progress"` 按渠道启用进度草稿： + +```json5 +{ + channels: { + discord: { + streaming: { + mode: "progress", + }, + }, + }, +} +``` + +这通常就足够了。OpenClaw 会自动选择一个单词标签，在有用工作发生时添加紧凑的进度行，并在该回合中抑制重复的独立进度提示。 + +## 用户会看到什么 + +进度草稿包含两个部分： + +| 部分 | 用途 | +| -------------- | ----------------------------------------------------------------- | +| 标签 | 简短标题，例如 `Thinking` 或 `Shelling`。 | +| 进度行 | 紧凑的运行更新，例如工具调用、任务步骤或批准。 | + +标签会在智能体开始回复时立即显示。只有当智能体发出有用的工作更新时，才会添加进度行。在可能的情况下，最终答案会替换草稿；否则，OpenClaw 会正常发送最终答案，并根据渠道传输方式清理草稿或停止更新草稿。 + +## 选择模式 + +`channels..streaming.mode` 控制可见的进行中行为： + +| 模式 | 最适合 | 聊天中显示的内容 | +| ---------- | -------------------------------- | ------------------------------------------------- | +| `off` | 安静渠道 | 仅最终答案。 | +| `partial` | 观察答案文本逐步出现 | 一个草稿，编辑为最新答案文本。 | +| `block` | 更大的答案预览分块 | 一个预览，以更大分块更新或追加。 | +| `progress` | 工具密集型或长时间运行的回合 | 一条状态草稿，然后是最终答案。 | + +当用户更关心“正在发生什么”，而不是逐个 token 观看答案文本流式输出时，请选择 `progress`。 + +当答案本身就是进度信号时，请选择 `partial`。 + +当你想用更大的文本块更新草稿预览时，请选择 `block`。在 Discord 和 Telegram 上，`streaming.mode: "block"` 仍然是预览流式传输，而不是普通分块投递。当你想要普通分块回复时，请使用 `streaming.block.enabled` 或旧版 `blockStreaming`。 + +## 配置标签 + +进度标签位于 `channels..streaming.progress` 下。 + +默认标签是 `auto`，它会从 OpenClaw 的内置单词标签池中选择： + +```text +Thinking +Shelling +Scuttling +Clawing +Pinching +Molting +Bubbling +Tiding +Reefing +Cracking +Sifting +Brining +Nautiling +Krilling +Barnacling +Lobstering +Tidepooling +Pearling +Snapping +Surfacing +``` + +使用固定标签： + +```json5 +{ + channels: { + discord: { + streaming: { + mode: "progress", + progress: { + label: "Investigating", + }, + }, + }, + }, +} +``` + +使用你自己的自动标签池： + +```json5 +{ + channels: { + discord: { + streaming: { + mode: "progress", + progress: { + label: "auto", + labels: ["Checking", "Reading", "Testing", "Finishing"], + }, + }, + }, + }, +} +``` + +隐藏标签，只显示进度行： + +```json5 +{ + channels: { + discord: { + streaming: { + mode: "progress", + progress: { + label: false, + }, + }, + }, + }, +} +``` + +## 控制进度行 + +在进度模式下，进度行默认启用。它们来自真实的运行事件：工具启动、项目更新、任务计划、批准、命令输出、补丁摘要以及类似的智能体活动。 + +限制保持可见的行数： + +```json5 +{ + channels: { + discord: { + streaming: { + mode: "progress", + progress: { + maxLines: 4, + }, + }, + }, + }, +} +``` + +保留单条进度草稿，但隐藏工具和任务行： + +```json5 +{ + channels: { + discord: { + streaming: { + mode: "progress", + progress: { + toolProgress: false, + }, + }, + }, + }, +} +``` + +使用 `toolProgress: false` 时，OpenClaw 仍会抑制该回合中较旧的独立工具进度消息。除已配置的标签外，渠道会在视觉上保持安静，直到最终答案出现。 + +## 渠道行为 + +每个渠道都会使用其支持的最简洁传输方式： + +| 渠道 | 进度传输 | 说明 | +| --------------- | -------------------------------------- | --------------------------------------------------------------------- | +| Discord | 发送一条消息，然后编辑它。 | 当最终文本适合一条安全预览消息时，会就地编辑。 | +| Matrix | 发送一个事件，然后编辑它。 | 账号级流式传输配置控制账号级草稿。 | +| Microsoft Teams | 个人聊天中的原生 Teams 流。 | `streaming.mode: "block"` 映射到 Teams 分块投递。 | +| Slack | 原生流或可编辑草稿帖。 | 线程可用性会影响是否可以使用原生流式传输。 | +| Telegram | 发送一条消息，然后编辑它。 | 较旧的可见草稿可能会被替换，以保持最终时间戳有用。 | +| Mattermost | 可编辑草稿帖。 | 工具活动会折叠到同一个草稿样式帖子中。 | + +没有安全编辑支持的渠道通常会回退到输入指示器或仅最终答案投递。 + +## 最终化 + +当最终答案准备好时，OpenClaw 会尝试保持聊天整洁： + +- 如果草稿可以安全地成为最终答案，OpenClaw 会就地编辑它。 +- 如果渠道使用原生进度流式传输，OpenClaw 会在原生传输接受最终文本时最终化该流。 +- 如果最终答案包含媒体、批准提示、显式回复目标、过多分块，或者编辑/发送失败，OpenClaw 会通过正常渠道投递路径发送最终答案。 + +回退路径是有意设计的。发送新的最终答案，优于丢失文本、把回复串到错误线程，或用渠道无法安全表示的载荷覆盖草稿。 + +## 故障排除 + +**我只看到最终答案。** + +检查处理该消息的账号或渠道是否已将 `channels..streaming.mode` 设置为 `progress`。当渠道无法安全编辑正确消息时，一些群组或引用回复路径可能会禁用该回合的草稿预览。 + +**我看到标签，但没有工具行。** + +检查 `streaming.progress.toolProgress`。如果它是 `false`，OpenClaw 会保留单草稿行为，但隐藏工具和任务进度行。 + +**我看到一条新的最终消息，而不是编辑后的草稿。** + +这是安全回退。媒体回复、长答案、显式回复目标、旧 Telegram 草稿、缺失的 Slack 线程目标、已删除的预览消息，或原生流最终化失败，都可能导致这种情况。 + +**我仍然看到独立进度消息。** + +当草稿处于活动状态时，进度模式会抑制默认的独立工具进度消息。如果独立消息仍然出现，请确认该回合确实在使用进度模式，而不是 `streaming.mode: "off"`，也不是某个无法为该消息创建草稿的渠道路径。 + +**Teams 的行为与 Discord 或 Telegram 不同。** + +Microsoft Teams 在个人聊天中使用原生流，而不是通用的发送并编辑预览传输。Teams 还会将 `streaming.mode: "block"` 视为 Teams 分块投递，因为它没有 Discord 和 Telegram 使用的同一种草稿预览分块模式。 + +## 相关内容 + +- [流式传输和分块](/zh-CN/concepts/streaming) +- [消息](/zh-CN/concepts/messages) +- [频道配置](/zh-CN/gateway/config-channels) +- [Discord](/zh-CN/channels/discord) +- [Matrix](/zh-CN/channels/matrix) +- [Microsoft Teams](/zh-CN/channels/msteams) +- [Slack](/zh-CN/channels/slack) +- [Telegram](/zh-CN/channels/telegram) diff --git a/docs/zh-CN/concepts/streaming.md b/docs/zh-CN/concepts/streaming.md index 27db43a17..f45b2b91c 100644 --- a/docs/zh-CN/concepts/streaming.md +++ b/docs/zh-CN/concepts/streaming.md @@ -3,27 +3,27 @@ read_when: - 说明流式传输或分块在渠道上的工作方式 - 更改分块流式传输或渠道分块行为 - 调试重复/过早的分块回复或渠道预览流式传输 -summary: 流式传输 + 分块行为（块回复、渠道预览流式传输、模式映射） +summary: 流式传输 + 分块行为（分块回复、渠道预览流式传输、模式映射） title: 流式传输和分块 x-i18n: - generated_at: "2026-05-03T15:33:28Z" + generated_at: "2026-05-03T21:05:41Z" model: gpt-5.5 provider: openai - source_hash: 4a62b333123d317cad9a8063a68c5c026fb91b23731a6ccdb97d995d9bb8bdba + source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50 source_path: concepts/streaming.md workflow: 16 --- OpenClaw 有两个独立的流式传输层： -- **分块流式传输（渠道）：** 在 assistant 写入时发出已完成的 **blocks**。这些是普通渠道消息（不是 token 增量）。 +- **分块流式传输（渠道）：** 在助手写入时发出已完成的 **块**。这些是普通的渠道消息（不是 token 增量）。 - **预览流式传输（Telegram/Discord/Slack）：** 生成期间更新临时的 **预览消息**。 -目前渠道消息没有**真正的 token 增量流式传输**。预览流式传输基于消息（发送 + 编辑/追加）。 +目前没有面向渠道消息的 **真正 token 增量流式传输**。预览流式传输基于消息（发送 + 编辑/追加）。 ## 分块流式传输（渠道消息） -分块流式传输会在 assistant 输出可用时，以较粗粒度的分块发送输出。 +分块流式传输会在助手输出可用时，以较粗的分块发送输出。 ``` Model output @@ -38,74 +38,74 @@ Model output 图例： - `text_delta/events`：模型流事件（对于非流式模型可能较稀疏）。 -- `chunker`：`EmbeddedBlockChunker`，应用最小/最大边界 + 断点偏好。 +- `chunker`：`EmbeddedBlockChunker`，应用最小/最大边界 + 换行偏好。 - `channel send`：实际出站消息（分块回复）。 **控制项：** - `agents.defaults.blockStreamingDefault`：`"on"`/`"off"`（默认关闭）。 -- 渠道覆盖：`*.blockStreaming`（以及按账户变体）用于按渠道强制 `"on"`/`"off"`。 +- 渠道覆盖：`*.blockStreaming`（以及按账号的变体），用于按渠道强制 `"on"`/`"off"`。 - `agents.defaults.blockStreamingBreak`：`"text_end"` 或 `"message_end"`。 - `agents.defaults.blockStreamingChunk`：`{ minChars, maxChars, breakPreference? }`。 - `agents.defaults.blockStreamingCoalesce`：`{ minChars?, maxChars?, idleMs? }`（发送前合并流式块）。 - 渠道硬上限：`*.textChunkLimit`（例如 `channels.whatsapp.textChunkLimit`）。 -- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 会先按空行（段落边界）拆分，再按长度分块）。 -- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17）会拆分过高的回复，避免 UI 裁切。 +- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 会在按长度分块前按空行（段落边界）拆分）。 +- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17），拆分较高的回复以避免 UI 裁剪。 **边界语义：** -- `text_end`：chunker 一发出就流式发送块；在每个 `text_end` 时刷新。 -- `message_end`：等到 assistant 消息完成后，再刷新缓冲的输出。 +- `text_end`：只要 chunker 发出块就流式发送；每次 `text_end` 时刷新。 +- `message_end`：等待助手消息完成，然后刷新已缓冲的输出。 如果缓冲文本超过 `maxChars`，`message_end` 仍会使用 chunker，因此它可以在末尾发出多个分块。 -### 使用分块流式传输交付媒体 +### 使用分块流式传输传递媒体 -`MEDIA:` 指令是普通交付元数据。当分块流式传输提前发送媒体块时，OpenClaw 会记住该回合的交付。如果最终 assistant payload 重复同一媒体 URL，最终交付会移除重复媒体，而不是再次发送附件。 +`MEDIA:` 指令是普通的投递元数据。当分块流式传输提前发送媒体块时，OpenClaw 会记住该轮次的这次投递。如果最终助手载荷重复同一个媒体 URL，最终投递会去除重复媒体，而不是再次发送附件。 -完全重复的最终 payload 会被抑制。如果最终 payload 在已流式传输的媒体周围添加不同文本，OpenClaw 仍会发送新文本，同时保持媒体只交付一次。这可防止在 Telegram 等渠道上出现重复语音消息或文件，例如智能体在流式传输期间发出 `MEDIA:`，而提供商也在完成的回复中包含它时。 +完全重复的最终载荷会被抑制。如果最终载荷在已流式发送的媒体周围添加了不同文本，OpenClaw 仍会发送新文本，同时保持媒体只投递一次。这可以避免在 Telegram 等渠道上出现重复语音留言或文件，例如当智能体在流式传输期间发出 `MEDIA:`，而提供商也在完成回复中包含它时。 ## 分块算法（低/高边界） -分块由 `EmbeddedBlockChunker` 实现： +块分块由 `EmbeddedBlockChunker` 实现： -- **低边界：** 直到缓冲区 >= `minChars` 才发出（除非强制）。 -- **高边界：** 优先在 `maxChars` 前拆分；如果强制，则在 `maxChars` 处拆分。 +- **低边界：** 缓冲区 >= `minChars` 前不发出（除非强制）。 +- **高边界：** 优先在 `maxChars` 之前拆分；如果强制，则在 `maxChars` 处拆分。 - **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬断点。 -- **代码围栏：** 绝不在围栏内拆分；在 `maxChars` 处强制拆分时，会关闭 + 重新打开围栏，以保持 Markdown 有效。 +- **代码围栏：** 永不在围栏内部拆分；当在 `maxChars` 处强制拆分时，会关闭 + 重新打开围栏，以保持 Markdown 有效。 -`maxChars` 会被限制到渠道的 `textChunkLimit`，因此你不能超过每个渠道的上限。 +`maxChars` 会被限制到渠道的 `textChunkLimit`，所以你不能超过每个渠道的上限。 ## 合并（合并流式块） -启用分块流式传输时，OpenClaw 可以在发送前**合并连续的块分片**。这会减少“单行刷屏”，同时仍然提供渐进式输出。 +启用分块流式传输时，OpenClaw 可以在发送前 **合并连续的块分块**。这会减少“单行刷屏”，同时仍提供渐进式输出。 -- 合并会等待**空闲间隔**（`idleMs`）后再刷新。 +- 合并会等待 **空闲间隔**（`idleMs`）后再刷新。 - 缓冲区受 `maxChars` 限制，超过时会刷新。 -- `minChars` 会阻止过小片段发送，直到累积足够文本（最终刷新始终发送剩余文本）。 -- 连接符源自 `blockStreamingChunk.breakPreference`（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。 -- 可通过 `*.blockStreamingCoalesce` 设置渠道覆盖（包括按账户配置）。 -- 除非覆盖，Signal/Slack/Discord 的默认合并 `minChars` 会提升到 1500。 +- `minChars` 会防止过小片段发送，直到累积足够文本（最终刷新总会发送剩余文本）。 +- 连接符来自 `blockStreamingChunk.breakPreference`（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。 +- 可通过 `*.blockStreamingCoalesce` 使用渠道覆盖（包括按账号配置）。 +- 除非覆盖，否则 Signal/Slack/Discord 的默认合并 `minChars` 会提升到 1500。 ## 分块之间的拟人化节奏 -启用分块流式传输时，你可以在分块回复之间（第一个块之后）添加**随机暂停**。这会让多气泡回复感觉更自然。 +启用分块流式传输时，你可以在分块回复之间（第一个分块之后）添加 **随机化暂停**。这会让多气泡响应感觉更自然。 - 配置：`agents.defaults.humanDelay`（通过 `agents.list[].humanDelay` 按智能体覆盖）。 - 模式：`off`（默认）、`natural`（800–2500ms）、`custom`（`minMs`/`maxMs`）。 -- 仅适用于**分块回复**，不适用于最终回复或工具摘要。 +- 仅适用于 **分块回复**，不适用于最终回复或工具摘要。 ## “流式传输分块或全部内容” -这映射到： +这对应于： - **流式传输分块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发出）。非 Telegram 渠道还需要 `*.blockStreaming: true`。 -- **在末尾流式传输全部内容：** `blockStreamingBreak: "message_end"`（刷新一次，如果很长可能有多个分块）。 +- **在末尾流式传输全部内容：** `blockStreamingBreak: "message_end"`（刷新一次；如果很长，可能产生多个分块）。 - **无分块流式传输：** `blockStreamingDefault: "off"`（仅最终回复）。 -**渠道说明：** 除非显式将 `*.blockStreaming` 设置为 `true`，否则分块流式传输**关闭**。渠道可以流式传输实时预览（`channels..streaming`），而不发送分块回复。 +**渠道注意事项：** 除非明确将 `*.blockStreaming` 设置为 `true`，否则分块流式传输为 **关闭**。渠道可以流式传输实时预览（`channels..streaming`），而不发送分块回复。 -配置位置提醒：`blockStreaming*` 默认值位于 `agents.defaults` 下，而不是根配置。 +配置位置提醒：`blockStreaming*` 默认值位于 `agents.defaults` 下，而不是根配置中。 ## 预览流式传输模式 @@ -116,25 +116,28 @@ Model output - `off`：禁用预览流式传输。 - `partial`：单个预览，会被最新文本替换。 - `block`：以分块/追加步骤更新预览。 -- `progress`：生成期间显示进度/Status 预览，完成时给出最终答案。 +- `progress`：生成期间显示进度/状态预览，完成时给出最终答案。 + +`streaming.mode: "block"` 是适用于 Discord 和 Telegram 等可编辑渠道的预览流式传输模式。它不会在这些渠道启用渠道分块投递。需要普通分块回复时，请使用 `streaming.block.enabled` 或旧版 `blockStreaming` 渠道键。Microsoft Teams 是例外：它没有草稿预览分块传输，因此 `streaming.mode: "block"` 会映射到 Teams 分块投递，而不是原生 partial/progress 流式传输。 ### 渠道映射 -| 渠道 | `off` | `partial` | `block` | `progress` | -| ---------- | ----- | --------- | ------- | ----------------- | -| Telegram | ✅ | ✅ | ✅ | 映射到 `partial` | -| Discord | ✅ | ✅ | ✅ | 映射到 `partial` | -| Slack | ✅ | ✅ | ✅ | ✅ | -| Mattermost | ✅ | ✅ | ✅ | ✅ | +| 渠道 | `off` | `partial` | `block` | `progress` | +| ---------- | ----- | --------- | ------- | ----------------------- | +| Telegram | ✅ | ✅ | ✅ | 可编辑进度草稿 | +| Discord | ✅ | ✅ | ✅ | 可编辑进度草稿 | +| Slack | ✅ | ✅ | ✅ | ✅ | +| Mattermost | ✅ | ✅ | ✅ | ✅ | +| MS Teams | ✅ | ✅ | ✅ | 原生进度流 | 仅 Slack： - 当 `channels.slack.streaming.mode="partial"` 时，`channels.slack.streaming.nativeTransport` 会切换 Slack 原生流式传输 API 调用（默认：`true`）。 -- Slack 原生流式传输和 Slack assistant 线程 Status 需要回复线程目标。顶层私信不会显示这种线程样式预览，但它们仍可使用 Slack 草稿预览帖子和编辑。 +- Slack 原生流式传输和 Slack 助手线程状态需要一个回复线程目标。顶层私信不会显示那种线程样式预览，但仍可使用 Slack 草稿预览帖子和编辑。 -旧键迁移： +旧版键迁移： -- Telegram：旧版 `streamMode` 和标量/布尔 `streaming` 值会被 Doctor/配置兼容路径检测并迁移到 `streaming.mode`。 +- Telegram：旧版 `streamMode` 以及标量/布尔 `streaming` 值会被 Doctor/配置兼容路径检测并迁移到 `streaming.mode`。 - Discord：`streamMode` + 布尔 `streaming` 会自动迁移到 `streaming` 枚举。 - Slack：`streamMode` 会自动迁移到 `streaming.mode`；布尔 `streaming` 会自动迁移到 `streaming.mode` 加 `streaming.nativeTransport`；旧版 `nativeStreaming` 会自动迁移到 `streaming.nativeTransport`。 @@ -143,49 +146,49 @@ Model output Telegram： - 在私信和群组/话题中使用 `sendMessage` + `editMessageText` 预览更新。 -- 当预览已可见约一分钟时，会发送一条新的最终消息，而不是就地编辑，然后清理预览，使 Telegram 的时间戳反映回复完成时间。 -- 当 Telegram 分块流式传输被显式启用时，会跳过预览流式传输（避免双重流式传输）。 +- 当预览已可见约一分钟时，会发送新的最终消息，而不是就地编辑；随后清理预览，使 Telegram 的时间戳反映回复完成时间。 +- 当显式启用 Telegram 分块流式传输时，会跳过预览流式传输（避免双重流式传输）。 - `/reasoning stream` 可以将推理写入预览。 Discord： - 使用发送 + 编辑预览消息。 - `block` 模式使用草稿分块（`draftChunk`）。 -- 当 Discord 分块流式传输被显式启用时，会跳过预览流式传输。 -- 最终媒体、错误和显式回复 payload 会取消待处理预览，而不刷新新的草稿，然后使用正常交付。 +- 当显式启用 Discord 分块流式传输时，会跳过预览流式传输。 +- 最终媒体、错误和显式回复载荷会取消待处理预览，而不刷新新草稿，然后使用普通投递。 Slack： -- 可用时，`partial` 可以使用 Slack 原生流式传输（`chat.startStream`/`append`/`stop`）。 -- `block` 使用追加样式的草稿预览。 -- `progress` 使用 Status 预览文本，然后给出最终答案。 +- `partial` 可在可用时使用 Slack 原生流式传输（`chat.startStream`/`append`/`stop`）。 +- `block` 使用追加式草稿预览。 +- `progress` 使用状态预览文本，然后发送最终答案。 - 没有回复线程的顶层私信会使用草稿预览帖子和编辑，而不是 Slack 原生流式传输。 -- 原生和草稿预览流式传输会抑制该回合的分块回复，因此 Slack 回复只通过一条交付路径流式传输。 -- 最终媒体/错误 payload 和进度最终内容不会创建一次性草稿消息；只有能编辑预览的文本/块最终内容才会刷新待处理草稿文本。 +- 原生和草稿预览流式传输会抑制该轮次的分块回复，因此 Slack 回复只会通过一种投递路径流式传输。 +- 最终媒体/错误载荷和进度最终消息不会创建一次性草稿消息；只有可编辑预览的文本/块最终消息会刷新待处理草稿文本。 Mattermost： -- 将思考、工具活动和部分回复文本流式传输到单个草稿预览帖子中，并在最终答案可安全发送时就地完成。 -- 如果预览帖子在完成时已被删除或无法使用，则回退为发送新的最终帖子。 -- 最终媒体/错误 payload 会先取消待处理预览更新，再正常交付，而不是刷新临时预览帖子。 +- 将思考、工具活动和部分回复文本流式写入单个草稿预览帖子，并在最终答案可以安全发送时就地完成。 +- 如果预览帖子在完成时已被删除或不可用，则回退为发送新的最终帖子。 +- 最终媒体/错误载荷会在普通投递前取消待处理预览更新，而不是刷新临时预览帖子。 Matrix： - 当最终文本可以复用预览事件时，草稿预览会就地完成。 -- 仅媒体、错误和回复目标不匹配的最终内容会先取消待处理预览更新，再正常交付；已可见的过时预览会被撤回。 +- 仅媒体、错误和回复目标不匹配的最终消息会在普通投递前取消待处理预览更新；已可见的过期预览会被撤回。 ### 工具进度预览更新 -预览流式传输还可以包含**工具进度**更新，即“正在搜索网络”、“正在读取文件”或“正在调用工具”这类短 Status 行。工具运行时，它们会显示在同一条预览消息中，早于最终回复。这能让多步骤工具回合在第一个思考预览和最终答案之间保持视觉上的进行状态，而不是沉默。 +预览流式传输还可以包含 **工具进度** 更新，即类似“正在搜索网络”、“正在读取文件”或“正在调用工具”的短状态行。它们会在工具运行期间出现在同一条预览消息中，早于最终回复。这让多步骤工具轮次在第一个思考预览和最终答案之间保持视觉上的活跃，而不是静默。 -支持的表面： +支持的界面： -- **Discord**、**Slack**、**Telegram** 和 **Matrix** 在预览流式传输处于活动状态时，默认会将工具进度流式传输到实时预览编辑中。 -- Telegram 自 `v2026.4.22` 起已发布启用工具进度预览更新的行为；保持启用可保留该已发布行为。 -- **Mattermost** 已将工具活动合并到它的单个草稿预览帖子中（见上文）。 -- 工具进度编辑遵循活动的预览流式传输模式；当预览流式传输为 `off`，或分块流式传输已接管消息时会跳过。在 Telegram 上，`streaming.mode: "off"` 表示仅最终回复：通用进度闲聊也会被抑制，而不是作为独立的“Working...”消息交付；同时审批提示、媒体 payload 和错误仍会正常路由。 -- 要保留预览流式传输但隐藏工具进度行，请为该渠道将 `streaming.preview.toolProgress` 设置为 `false`。要完全禁用预览编辑，请将 `streaming.mode` 设置为 `off`。 -- Telegram 所选引用回复是一个例外：当 `replyToMode` 不是 `"off"` 且存在所选引用文本时，OpenClaw 会跳过该回合的答案预览流，因此工具进度预览行无法渲染。没有所选引用文本的当前消息回复仍会保留预览流式传输。详见 [Telegram 渠道文档](/zh-CN/channels/telegram)。 +- 默认情况下，当预览流式传输处于活动状态时，**Discord**、**Slack**、**Telegram** 和 **Matrix** 会将工具进度流式写入实时预览编辑。Microsoft Teams 在个人聊天中使用其原生进度流。 +- Telegram 自 `v2026.4.22` 起已发布并启用工具进度预览更新；保持启用可保留该已发布行为。 +- **Mattermost** 已经将工具活动折叠进其单个草稿预览帖子（见上文）。 +- 工具进度编辑会遵循活动的预览流式传输模式；当预览流式传输为 `off`，或分块流式传输已接管消息时，会跳过它们。在 Telegram 上，`streaming.mode: "off"` 表示仅最终消息：通用进度闲聊也会被抑制，而不是作为独立状态消息投递；审批提示、媒体载荷和错误仍会正常路由。 +- 若要保留预览流式传输但隐藏工具进度行，请将该渠道的 `streaming.preview.toolProgress` 设置为 `false`。若要完全禁用预览编辑，请将 `streaming.mode` 设置为 `off`。 +- Telegram 选定引用回复是例外：当 `replyToMode` 不是 `"off"` 且存在选定引用文本时，OpenClaw 会跳过该轮次的答案预览流，因此工具进度预览行无法渲染。没有选定引用文本的当前消息回复仍会保留预览流式传输。详情参见 [Telegram 渠道文档](/zh-CN/channels/telegram)。 示例： @@ -204,8 +207,9 @@ Matrix： } ``` -## 相关内容 +## 相关 -- [消息](/zh-CN/concepts/messages) — 消息生命周期和交付 -- [重试](/zh-CN/concepts/retry) — 交付失败时的重试行为 -- [渠道](/zh-CN/channels) — 各渠道流式传输支持 +- [进度草稿](/zh-CN/concepts/progress-drafts) — 长轮次期间会更新的可见进行中消息 +- [消息](/zh-CN/concepts/messages) — 消息生命周期和投递 +- [重试](/zh-CN/concepts/retry) — 投递失败时的重试行为 +- [渠道](/zh-CN/channels) — 按渠道列出的流式传输支持 diff --git a/docs/zh-CN/gateway/config-channels.md b/docs/zh-CN/gateway/config-channels.md index 58348a736..0d4bb3dc3 100644 --- a/docs/zh-CN/gateway/config-channels.md +++ b/docs/zh-CN/gateway/config-channels.md @@ -1,54 +1,54 @@ --- read_when: - - 配置渠道插件（身份验证、访问控制、多账号） - - 各渠道配置键名的故障排除 + - 配置渠道插件（认证、访问控制、多账号） + - 按渠道配置键的故障排除 - 审计私信策略、群组策略或提及门控 -summary: 渠道配置：跨 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等的访问控制、配对和按渠道密钥 +summary: 频道配置：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等渠道的访问控制、配对和每渠道密钥 title: 配置 — 渠道 x-i18n: - generated_at: "2026-05-03T18:19:09Z" + generated_at: "2026-05-03T21:05:42Z" model: gpt-5.5 provider: openai - source_hash: b92d7fe63a3d27c1740abb0986d6641d14d8d1017051f1744a02e1db77fda3c8 + source_hash: 366bcee632c649219bbf6cf44d64cc13d966ec813abc74d54088d89de640b47c source_path: gateway/config-channels.md workflow: 16 --- `channels.*` 下的每渠道配置键。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的每渠道键。 -对于智能体、工具、Gateway 网关运行时和其他顶层键，请参阅 +关于智能体、工具、Gateway 网关运行时和其他顶级键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。 ## 渠道 -每个渠道会在其配置段存在时自动启动（除非设置了 `enabled: false`）。 +每个渠道会在其配置部分存在时自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | +| 私信策略 | 行为 | | ------------------- | --------------------------------------------------------------- | -| `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`（故障关闭）并在启动时发出警告。 +当提供商的 `groupPolicy` 未设置时，`channels.defaults.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 { @@ -90,14 +90,14 @@ x-i18n: ``` - `channels.defaults.groupPolicy`：提供商级 `groupPolicy` 未设置时的回退群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/话题串/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与允许列表相同，但保留明确的引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在 Heartbeat 输出中包含健康的渠道 Status。 - `channels.defaults.heartbeat.showAlerts`：在 Heartbeat 输出中包含降级/错误 Status。 -- `channels.defaults.heartbeat.useIndicator`：渲染紧凑指示器样式的 Heartbeat 输出。 +- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器风格 Heartbeat 输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链接会话存在时，它会自动启动。 +WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已链接会话时，它会自动启动。 ```json5 { @@ -135,7 +135,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链 } ``` - + ```json5 { @@ -153,9 +153,9 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链 } ``` -- 出站命令默认使用 `default` 账号（如果存在）；否则使用第一个已配置账号 ID（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在匹配已配置账号 ID 时覆盖该回退默认账号选择。 -- 旧版单账号 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 如果存在 `default`，出站命令默认使用账号 `default`；否则使用第一个已配置的账号 ID（排序后）。 +- 可选的 `channels.whatsapp.defaultAccount` 在匹配已配置账号 ID 时，会覆盖该回退默认账号选择。 +- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 - 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -215,13 +215,13 @@ 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` 会发出警告。 +- 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` 会发出警告。 - `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 条目中带有 `type: "acp"` 的项会为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。 -- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于直接聊天和群组聊天）。 +- 带有 `type: "acp"` 的顶级 `bindings[]` 条目会为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群组聊天）。 - 重试策略：请参阅[重试策略](/zh-CN/concepts/retry)。 ### Discord @@ -277,7 +277,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链 historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) + streaming: "off", // off | partial | block | progress maxLinesPerMessage: 17, ui: { components: { @@ -327,41 +327,41 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链 } ``` -- 令牌：`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.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`：线程绑定会话功能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定投递/路由）的 Discord 覆盖项 - - `idleHours`：非活动自动取消聚焦的 Discord 覆盖项，单位为小时（`0` 表示禁用） - - `maxAgeHours`：硬性最大时长的 Discord 覆盖项，单位为小时（`0` 表示禁用） - - `spawnSessions`：`sessions_spawn({ thread: true })` 和 ACP 线程生成自动线程创建/绑定的开关（默认：`true`） + - `enabled`：线程绑定会话功能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由）的 Discord 覆盖 + - `idleHours`：按小时设置的不活动自动取消聚焦 Discord 覆盖（`0` 禁用） + - `maxAgeHours`：按小时设置的硬性最长时限 Discord 覆盖（`0` 禁用） + - `spawnSessions`：`sessions_spawn({ thread: true })` 和 ACP 线程生成自动创建/绑定线程的开关（默认：`true`） - `defaultSpawnContext`：线程绑定生成的原生子智能体上下文（默认 `"fork"`） -- 顶层 `bindings[]` 条目使用 `type: "acp"` 为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。 +- 带有 `type: "acp"` 的顶层 `bindings[]` 条目会为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。 - `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。 -- `channels.discord.voice` 启用 Discord 语音渠道对话，以及可选的自动加入 + LLM + TTS 覆盖项。仅文本的 Discord 配置默认关闭语音；设置 `channels.discord.voice.enabled=true` 以选择启用。 -- `channels.discord.voice.model` 可选地覆盖用于 Discord 语音渠道回复的 LLM 模型。 +- `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`）。 -- OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试恢复语音接收。 +- `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.execApprovals`：Discord 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析审批人时，exec 审批会激活。 +- `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 审批会激活。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - - `sessionFilter`：可选的会话键模式（子字符串或正则表达式）。 - - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到来源渠道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮只能由已解析的审批人使用。 + - `sessionFilter`：可选的会话键模式（子字符串或正则）。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批者私信，`"channel"` 发送到发起渠道，`"both"` 发送到两者。当 target 包含 `"channel"` 时，按钮仅可由已解析的审批者使用。 - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**回应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds..users`）。 +**反应通知模式：**`off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds..users`）。 ### Google Chat @@ -392,11 +392,11 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链 } ``` -- 服务账户 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 -- 也支持服务账户 SecretRef（`serviceAccountRef`）。 -- 环境变量后备：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 使用 `spaces/` 或 `users/` 作为投递目标。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（破窗兼容模式）。 +- 服务账号 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 也支持服务账号 SecretRef（`serviceAccountRef`）。 +- 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 +- 对投递目标使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（应急兼容模式）。 ### Slack @@ -468,27 +468,27 @@ 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 receiver API。仅在调查 ping/pong 超时或陈旧 websocket 行为时使用它。 +- **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 mode 下的 `signingSecretStatus`。`configured_unavailable` 表示账户通过 SecretRef 配置，但当前命令/运行时路径无法解析 secret 值。 +- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 配置，但当前命令/运行时路径无法解析密钥值。 - `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 在匹配已配置账户 ID 时会覆盖默认账户选择。 +- 可选的 `channels.slack.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 - `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔值 `streaming` 和 `nativeStreaming` 会自动迁移。 -- 使用 `user:`（私信）或 `channel:` 作为投递目标。 +- 对投递目标使用 `user:`（私信）或 `channel:`。 -**回应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**反应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 是每线程（默认）或跨渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。 +**线程会话隔离：**`thread.historyScope` 是按线程（默认）或跨渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。 -- Slack 原生流式传输以及 Slack assistant 风格的“正在输入...”线程状态需要回复线程目标。顶层私信默认保持在线程外，因此它们仍可通过 Slack 草稿发布并编辑预览来流式传输，而不是显示线程风格的原生流/状态预览。 -- `typingReaction` 会在回复运行期间向传入的 Slack 消息添加一个临时回应，然后在完成时移除它。使用 Slack emoji 短代码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。与 Discord 使用相同架构：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- Slack 原生流式传输以及 Slack 助手风格的 “is typing...” 线程状态需要回复线程目标。顶层私信默认保持在线程外，因此它们仍可通过 Slack 草稿发布并编辑预览进行流式传输，而不是显示线程风格的原生流/状态预览。 +- `typingReaction` 会在回复运行期间向传入的 Slack 消息添加临时反应，然后在完成时移除它。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批者授权。与 Discord 相同的 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认值 | 备注 | +| 操作组 | 默认值 | 说明 | | ------------ | ------- | ---------------------- | -| reactions | 已启用 | 回应 + 列出回应 | +| reactions | 已启用 | 反应 + 列出反应 | | messages | 已启用 | 读取/发送/编辑/删除 | | pins | 已启用 | 置顶/取消置顶/列出 | | memberInfo | 已启用 | 成员信息 | @@ -496,7 +496,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链 ### Mattermost -在当前 OpenClaw 版本中，Mattermost 作为内置插件提供。较旧或自定义构建可以使用 `openclaw plugins install @openclaw/mattermost` 安装当前 npm 包。固定版本前，请查看 [npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) 获取当前 dist-tags。 +Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧或自定义构建可以使用 `openclaw plugins install @openclaw/mattermost` 安装当前 npm 包。固定版本前，请查看 [npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) 了解当前 dist-tags。 ```json5 { @@ -526,18 +526,18 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链 } ``` -聊天模式：`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.` +- `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 时会覆盖默认账号选择。 +- `channels.mattermost.groups..requireMention`：逐渠道的提及门控覆盖（`"*"` 表示默认）。 +- 可选的 `channels.mattermost.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。 ### Signal @@ -558,11 +558,11 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当已链 } ``` -**回应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**表情回应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -- `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。 +- `channels.signal.account`：将渠道启动固定到特定 Signal 账户身份。 - `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 +- 可选的 `channels.signal.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。 ### BlueBubbles @@ -582,13 +582,13 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.blueb ``` - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 -- 顶层 `bindings[]` 条目如果带有 `type: "acp"`，可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings)。 -- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles)。 +- 可选的 `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#persistent-channel-bindings)。 +- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage -OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 +OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 ```json5 { @@ -612,15 +612,15 @@ OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。 -- 需要对 Messages DB 具备完全磁盘访问权限。 +- 需要对 Messages 数据库的完全磁盘访问权限。 - 优先使用 `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 发起的配置写入。 -- 顶层 `bindings[]` 条目如果带有 `type: "acp"`，可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或明确的聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings)。 +- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化句柄或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings)。 @@ -663,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"`。 - - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由到的对等方共享，而 `per-room` 会隔离每个私信房间。 +- 令牌身份验证使用 `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`，因此受邀房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配置 `autoJoinAllowlist`，或设置 `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)。 +- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams @@ -697,7 +697,7 @@ Microsoft Teams 由插件支持，并在 `channels.msteams` 下配置。 ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖项）记录在 [Microsoft Teams](/zh-CN/channels/msteams)。 +- 完整的 Teams 配置（凭证、webhook、私信/群组策略、逐 team/逐渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 ### IRC @@ -723,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 渠道配置（主机/端口/TLS/渠道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 -### 多账号（所有渠道） +### 多账户（所有渠道） -每个渠道运行多个账号（每个账号都有自己的 `accountId`）： +每个渠道运行多个账户（每个账户都有自己的 `accountId`）： ```json5 { @@ -749,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 + 路由）。 +- 环境变量令牌只应用于**默认**账户。 +- 基础渠道设置应用于所有账户，除非逐账户覆盖。 +- 使用 `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)。 +许多插件渠道配置为 `channels.`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +请参阅完整渠道索引：[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` 配置。只有在部署中禁用了文件监视或配置重载时才需要重启。 **提及类型：** -- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式中会被忽略。 +- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式中忽略。 - **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则表达式模式。无效模式和不安全的嵌套重复会被忽略。 -- 只有在可以检测时（原生提及或至少一个模式），才会强制执行提及门控。 +- 仅在可以检测时（原生提及或至少一个模式）强制执行提及门控。 ```json5 { @@ -793,9 +793,9 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可以用 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 +`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 可以提供自己的直接/源默认值；Codex harness 默认使用 `message_tool`。渠道允许列表和提及门控仍会决定是否处理某个轮次。 #### 私信历史限制 @@ -818,7 +818,7 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 #### 自聊模式 -在 `allowFrom` 中包含你自己的号码，以启用自聊模式（忽略原生 @ 提及，只响应文本模式）： +在 `allowFrom` 中包含你自己的号码以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -868,30 +868,30 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 -- 此区块配置命令界面。当前内置 + 捆绑命令目录见 [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 保持关闭。 +- `native: "auto"` 会为 Discord/Telegram 开启原生命令，并让 Slack 保持关闭。 +- `nativeSkills: "auto"` 会为 Discord/Telegram 开启原生 Skills 命令，并让 Slack 保持关闭。 - 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。对于 Discord，`false` 会在启动期间跳过原生命令注册和清理。 -- 用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 注册。 -- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 -- `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 客户端使用。 +- 使用 `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 服务器配置启用 `/mcp`。 - `plugins: true` 会为插件发现、安装以及启用/禁用控制启用 `/plugins`。 -- `channels..configWrites` 按渠道对配置变更进行门控（默认：true）。 -- 对于多账号渠道，`channels..accounts..configWrites` 也会对以该账号为目标的写入进行门控（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `channels..configWrites` 按渠道门控配置变更（默认值：true）。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会门控面向该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 - `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 -- `ownerAllowFrom` 是仅所有者命令/工具的显式所有者允许列表。它独立于 `allowFrom`。 +- `ownerAllowFrom` 是 owner-only 命令/工具的显式所有者允许列表。它独立于 `allowFrom`。 - `ownerDisplay: "hash"` 会在系统提示中哈希所有者 ID。设置 `ownerDisplaySecret` 可控制哈希。 -- `allowFrom` 按提供商配置。设置后，它就是**唯一**授权来源（会忽略渠道允许列表/配对以及 `useAccessGroups`）。 +- `allowFrom` 按提供商设置。设置后，它是**唯一**授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。 - 当未设置 `allowFrom` 时，`useAccessGroups: false` 允许命令绕过访问组策略。 - 命令文档映射： - 内置 + 捆绑目录：[Slash Commands](/zh-CN/tools/slash-commands) - - 渠道特定命令界面：[渠道](/zh-CN/channels) + - 渠道特定命令界面：[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) @@ -901,6 +901,6 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 ## 相关内容 -- [配置参考](/zh-CN/gateway/configuration-reference) — 顶级键 +- [配置参考](/zh-CN/gateway/configuration-reference) — 顶层键 - [配置 — 智能体](/zh-CN/gateway/config-agents) -- [渠道概览](/zh-CN/channels) +- [Channels 概览](/zh-CN/channels)