diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index 36abfb2f9..f8b2afeaa 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -1,72 +1,72 @@ --- read_when: - 正在开发 Discord 渠道功能 -summary: Discord 机器人支持状态、能力和配置 +summary: Discord 机器人支持状态、功能和配置 title: Discord x-i18n: - generated_at: "2026-04-29T05:38:00Z" + generated_at: "2026-04-29T12:05:10Z" model: gpt-5.5 provider: openai - source_hash: f25e1e1ed36d9f6f943cdf155d8cab08f031fcaab67477acf04ea7f18f694ec7 + source_hash: 8ae0b2fc79f266bc830c8c8725cb7a1bb1b33d89566c63a80362c7ecb2c863fb source_path: channels/discord.md workflow: 16 --- -已准备好通过官方 Discord Gateway 网关用于私信和公会频道。 +可通过官方 Discord Gateway 网关用于私信和公会渠道。 - - Discord 私信默认使用配对模式。 + + Discord 私信默认进入配对模式。 - + 原生命令行为和命令目录。 - + 跨渠道诊断和修复流程。 ## 快速设置 -你需要创建一个带有机器人的新应用，将机器人添加到你的服务器，并将它与 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** 并启用： - **Message Content Intent**（必需） - - **Server Members Intent**（推荐；角色 allowlist 和名称到 ID 匹配需要） - - **Presence Intent**（可选；仅在需要在线状态更新时需要） + - **Server Members Intent**（推荐；角色允许列表和名称到 ID 匹配需要） + - **Presence Intent**（可选；仅状态更新需要） - - 回到 **Bot** 页面顶部并点击 **Reset Token**。 + + 在 **Bot** 页面向上滚动，然后点击 **Reset Token**。 - 尽管名称如此，这会生成你的第一个 token，并没有真正“重置”任何内容。 + 尽管名称如此，这会生成你的第一个令牌——并没有任何内容被“重置”。 - 复制该 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 应用，你需要启用开发者模式，这样才能复制内部 ID。 + + 回到 Discord 应用，你需要启用开发者模式，以便复制内部 ID。 1. 点击 **User Settings**（头像旁边的齿轮图标）→ **Advanced** → 打开 **Developer Mode** - 2. 在侧边栏中右键点击你的 **server icon** → **Copy Server ID** - 3. 右键点击你自己的 **own avatar** → **Copy User ID** + 2. 右键点击侧边栏中的 **服务器图标** → **Copy Server ID** + 3. 右键点击你**自己的头像** → **Copy User ID** - 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存，下一步你会把这三项都发送给 OpenClaw。 + 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存——下一步你会把这三项都发送给 OpenClaw。 - - 为了让配对正常工作，Discord 需要允许你的机器人给你发送私信。右键点击你的 **server icon** → **Privacy Settings** → 打开 **Direct Messages**。 + + 为了让配对正常工作，Discord 需要允许你的机器人给你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。 - 这会允许服务器成员（包括机器人）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持此项启用。如果你只计划使用公会频道，可以在配对后禁用私信。 + 这允许服务器成员（包括机器人）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持此项启用。如果你只计划使用公会渠道，可以在配对后禁用私信。 - - 你的 Discord 机器人 token 是机密信息（类似密码）。在给智能体发消息之前，先在运行 OpenClaw 的机器上设置它。 + + 你的 Discord 机器人令牌是机密信息（类似密码）。在向你的智能体发送消息前，先在运行 OpenClaw 的机器上设置它。 ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -111,21 +111,21 @@ openclaw config set channels.discord.enabled true --strict-json openclaw gateway ``` - 如果 OpenClaw 已经作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或停止并重新启动 `openclaw gateway run` 进程。 - 对于托管服务安装，请从存在 `DISCORD_BOT_TOKEN` 的 shell 中运行 `openclaw gateway install`，或将该变量存储在 `~/.openclaw/.env` 中，这样服务在重启后就能解析 env SecretRef。 + 如果 OpenClaw 已作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或停止并重新启动 `openclaw gateway run` 进程。 + 对于托管服务安装，请在存在 `DISCORD_BOT_TOKEN` 的 shell 中运行 `openclaw gateway install`，或将变量存储在 `~/.openclaw/.env` 中，这样服务重启后就能解析 env SecretRef。 - + - - 在任何现有渠道（例如 Telegram）与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / config 标签页。 + + 在任何现有渠道（例如 Telegram）与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置标签页。 - > “我已经在配置中设置了 Discord 机器人 token。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” + > “我已经在配置中设置了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” - - 如果你更喜欢基于文件的配置，请设置： + + 如果你偏好基于文件的配置，请设置： ```json5 { @@ -142,25 +142,25 @@ openclaw gateway } ``` - 默认账户的 env 回退： + 默认账号的 env 回退： ```bash DISCORD_BOT_TOKEN=... ``` - 支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商的 SecretRef 值。参见 [Secrets Management](/zh-CN/gateway/secrets)。 + 支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商的 SecretRef 值。参见[密钥管理](/zh-CN/gateway/secrets)。 - - 等到 Gateway 网关运行后，在 Discord 中私信你的机器人。它会返回一个配对码。 + + 等待 Gateway 网关运行后，在 Discord 中给你的机器人发送私信。它会回复一个配对码。 - - 在现有渠道上把配对码发送给你的智能体： + + 在你的现有渠道中将配对码发送给你的智能体： > “批准这个 Discord 配对码：``” @@ -174,32 +174,32 @@ openclaw pairing approve discord - 配对码将在 1 小时后过期。 + 配对码会在 1 小时后过期。 - 现在你应该可以通过 Discord 私信与你的智能体聊天。 + 现在你应该可以通过私信在 Discord 中与你的智能体聊天。 -Token 解析是账户感知的。配置 token 值优先于 env 回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 -如果两个已启用的 Discord 账户解析到同一个机器人 token，OpenClaw 只会为该 token 启动一个 Gateway 网关监视器。来自配置的 token 优先于默认 env 回退；否则第一个启用的账户胜出，重复账户会被报告为已禁用。 -对于高级出站调用（message 工具/渠道操作），显式的逐调用 `token` 会用于该调用。这适用于发送和读取/探测风格的操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍来自活动运行时快照中的所选账户。 +令牌解析感知账号。配置中的令牌值优先于 env 回退。`DISCORD_BOT_TOKEN` 仅用于默认账号。 +如果两个已启用的 Discord 账号解析到同一个机器人令牌，OpenClaw 只会为该令牌启动一个 Gateway 网关监视器。来自配置的令牌优先于默认 env 回退；否则第一个已启用账号获胜，并且重复账号会被报告为已禁用。 +对于高级出站调用（消息工具/渠道操作），显式的每次调用 `token` 会用于该调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账号策略/重试设置仍来自活动运行时快照中选定的账号。 ## 推荐：设置公会工作区 -私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个频道都有自己的智能体会话和上下文。对于只有你和机器人的私人服务器，推荐这样做。 +私信正常工作后，你可以将 Discord 服务器设置为完整工作区，其中每个渠道都有自己的智能体会话及其上下文。对于只有你和你的机器人的私有服务器，建议这样做。 - - 这会让你的智能体可以在服务器上的任意频道中响应，而不只是私信。 + + 这会让你的智能体可以在服务器上的任何渠道中回复，而不只是私信。 - - > “将我的 Discord Server ID `` 添加到公会 allowlist” + + > “将我的 Discord Server ID `` 添加到公会允许列表” - + ```json5 { @@ -222,16 +222,16 @@ Token 解析是账户感知的。配置 token 值优先于 env 回退。`DISCORD - - 默认情况下，你的智能体只有在公会频道中被 @提及时才会响应。对于私人服务器，你可能希望它响应每条消息。 + + 默认情况下，你的智能体只有在公会渠道中被 @提及时才会回复。对于私有服务器，你可能希望它回复每条消息。 - 在公会频道中，普通 assistant 最终回复默认保持私有。可见的 Discord 输出必须通过 `message` 工具显式发送，因此智能体可以默认旁观，只在认为频道回复有用时发帖。 + 在公会渠道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须通过 `message` 工具显式发送，因此智能体默认可以静默观察，并且只在判断渠道回复有用时才发帖。 - - > “允许我的智能体在此服务器上无需 @提及也能响应” + + > “允许我的智能体在这个服务器上回复，而不必被 @提及” - + 在你的公会配置中设置 `requireMention: false`： ```json5 @@ -248,85 +248,85 @@ Token 解析是账户感知的。配置 token 值优先于 env 回退。`DISCORD } ``` - 要为群组/频道房间恢复旧版自动最终回复，请设置 `messages.groupChat.visibleReplies: "automatic"`。 + 要为群组/渠道房间恢复旧版自动最终回复，请设置 `messages.groupChat.visibleReplies: "automatic"`。 - - 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。公会频道不会自动加载 MEMORY.md。 + + 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。公会渠道不会自动加载 MEMORY.md。 - - > “当我在 Discord 频道中提问时，如果你需要 MEMORY.md 中的长期上下文，请使用 memory_search 或 memory_get。” + + > “当我在 Discord 渠道中提问时，如果你需要来自 MEMORY.md 的长期上下文，请使用 memory_search 或 memory_get。” - - 如果你需要在每个频道中共享上下文，请将稳定指令放入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话）。将长期笔记保存在 `MEMORY.md` 中，并按需使用 memory 工具访问它们。 + + 如果你需要在每个渠道中共享上下文，请将稳定指令放入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并按需使用记忆工具访问它们。 -现在在你的 Discord 服务器上创建一些频道并开始聊天。你的智能体可以看到频道名称，并且每个频道都有自己的隔离会话，所以你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的频道。 +现在在你的 Discord 服务器上创建一些渠道并开始聊天。你的智能体可以看到渠道名称，并且每个渠道都会获得自己的隔离会话——因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的渠道。 ## 运行时模型 - Gateway 网关拥有 Discord 连接。 - 回复路由是确定性的：Discord 入站会回复到 Discord。 -- Discord 公会/频道元数据会作为不受信任的上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果模型把该包络复制回来，OpenClaw 会从出站回复和未来的重放上下文中剥离复制的元数据。 +- Discord 公会/渠道元数据会作为不可信上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果模型复制了该信封，OpenClaw 会从出站回复和未来的重放上下文中剥离复制的元数据。 - 默认情况下（`session.dmScope=main`），直接聊天共享智能体主会话（`agent:main:main`）。 -- 公会频道是隔离的会话键（`agent::discord:channel:`）。 -- 群组私信默认会被忽略（`channels.discord.dm.groupEnabled=false`）。 -- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 到被路由的对话会话。 -- 仅文本的 cron/heartbeat 到 Discord 的公告投递会使用一次最终的 assistant 可见答案。媒体和结构化组件载荷在智能体发出多个可投递载荷时仍保持多消息。 +- 公会渠道使用隔离的会话键（`agent::discord:channel:`）。 +- 群组私信默认被忽略（`channels.discord.dm.groupEnabled=false`）。 +- 原生斜杠命令在隔离的命令会话中运行（`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`。 -示例：发送到论坛父频道以创建线程 +示例：发送到论坛父级以创建帖子串 ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -示例：显式创建论坛线程 +示例：显式创建论坛帖子串 ```bash 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` 负载的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有 Discord `replyToMode` 设置。 +OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带有 `components` 载荷的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 -支持的区块： +支持的块： - `text`、`section`、`separator`、`actions`、`media-gallery`、`file` - 操作行最多允许 5 个按钮或一个选择菜单 - 选择类型：`string`、`user`、`role`、`mentionable`、`channel` -默认情况下，组件只能使用一次。设置 `components.reusable=true` 可允许按钮、选择菜单和表单被多次使用，直到它们过期。 +默认情况下，组件为一次性使用。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前被多次使用。 -要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 +要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到仅自己可见的拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及一个提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，且只有调用用户可以使用它。 +`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及一个提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复为仅自己可见，并且只有调用用户可以使用它。 文件附件： -- `file` 区块必须指向附件引用（`attachment://`） +- `file` 块必须指向附件引用（`attachment://`） - 通过 `media`/`path`/`filePath` 提供附件（单个文件）；多个文件请使用 `media-gallery` -- 当上传名称应与附件引用匹配时，使用 `filename` 覆盖上传名称 +- 当上传名称应匹配附件引用时，使用 `filename` 覆盖上传名称 模态表单： @@ -399,12 +399,13 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 - `open`（要求 `channels.discord.allowFrom` 包含 `"*"`；旧版：`channels.discord.dm.allowFrom`） - `disabled` - 如果私信策略不是开放的，未知用户会被阻止（或在 `pairing` 模式下被提示配对）。 + 如果私信策略不是开放的，未知用户会被阻止（或在 `pairing` 模式下收到配对提示）。 多账号优先级： - `channels.discord.accounts.default.allowFrom` 仅适用于 `default` 账号。 - - 命名账号在自身未设置 `allowFrom` 时继承 `channels.discord.allowFrom`。 + - 对于单个账号，`allowFrom` 优先于旧版 `dm.allowFrom`。 + - 当命名账号未设置自己的 `allowFrom` 和旧版 `dm.allowFrom` 时，会继承 `channels.discord.allowFrom`。 - 命名账号不会继承 `channels.discord.accounts.default.allowFrom`。 用于投递的私信目标格式： @@ -412,12 +413,12 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 - `user:` - `<@id>` 提及 - 纯数字 ID 存在歧义，会被拒绝，除非提供了明确的用户/渠道目标类型。 + 当渠道默认值处于活动状态时，纯数字 ID 通常会解析为渠道 ID，但为了兼容性，列在账号有效私信 `allowFrom` 中的 ID 会被视为用户私信目标。 - Guild 处理由 `channels.discord.groupPolicy` 控制： + 服务器处理由 `channels.discord.groupPolicy` 控制： - `open` - `allowlist` @@ -427,12 +428,12 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 `allowlist` 行为： - - guild 必须匹配 `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` 会发出警告 - - 如果 guild 配置了 `channels`，未列出的渠道会被拒绝 - - 如果 guild 没有 `channels` 区块，则该允许列表 guild 中的所有渠道都被允许 + - 如果服务器配置了 `channels`，未列出的渠道会被拒绝 + - 如果服务器没有 `channels` 块，则该允许列表服务器中的所有渠道都被允许 示例： @@ -458,33 +459,33 @@ 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`。 - Guild 消息默认受提及门控。 + 默认情况下，服务器消息受提及门控。 提及检测包括： - - 显式机器人提及 + - 明确提及机器人 - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） - - 受支持情况下的隐式回复机器人行为 + - 支持场景中的隐式回复机器人行为 - `requireMention` 按 guild/渠道配置（`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 guild 成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并在对等或父对等绑定之后、仅 guild 绑定之前求值。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），所有已配置字段都必须匹配。 +使用 `bindings[].match.roles` 按角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并在对等或父对等绑定之后、仅服务器绑定之前求值。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 ```json5 { @@ -508,13 +509,13 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 } ``` -## 原生命令和命令身份验证 +## 原生命令和命令认证 - `commands.native` 默认为 `"auto"`，并为 Discord 启用。 - 按渠道覆盖：`channels.discord.commands.native`。 -- `commands.native=false` 会显式清除之前注册的 Discord 原生命令。 -- 原生命令身份验证使用与普通消息处理相同的 Discord 允许列表/策略。 -- 对未授权用户，命令仍可能在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 身份验证，并返回“未授权”。 +- `commands.native=false` 会显式清除先前注册的 Discord 原生命令。 +- 原生命令认证使用与普通消息处理相同的 Discord 允许列表/策略。 +- 对于未获授权的用户，命令可能仍会显示在 Discord UI 中；执行时仍会强制执行 OpenClaw 认证并返回 “not authorized”。 请参阅[斜杠命令](/zh-CN/tools/slash-commands)了解命令目录和行为。 @@ -526,7 +527,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 - Discord 在智能体输出中支持回复标签： + Discord 支持智能体输出中的回复标签： - `[[reply_to_current]]` - `[[reply_to:]]` @@ -538,18 +539,18 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 - `all` - `batched` - 注意：`off` 会禁用隐式回复线程化。显式 `[[reply_to_*]]` 标签仍会被遵循。 - `first` 始终将隐式原生回复引用附加到本轮的第一条出站 Discord 消息。 - `batched` 仅当入站轮次是多条消息的防抖批次时，才附加 Discord 的隐式原生回复引用。这在你主要希望为含糊的突发聊天提供原生回复，而不是为每个单消息轮次都提供原生回复时很有用。 + 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会生效。 + `first` 始终将隐式原生回复引用附加到该轮的第一条出站 Discord 消息。 + `batched` 仅在入站轮次是一批经过防抖的多条消息时，才会附加 Discord 的隐式原生回复引用。当你主要希望在有歧义的突发聊天中使用原生回复，而不是每个单消息轮次都使用时，这很有用。 - 消息 ID 会暴露在上下文/历史记录中，因此智能体可以定位特定消息。 + 消息 ID 会显示在上下文/历史记录中，以便智能体可以定位特定消息。 - OpenClaw 可以通过发送临时消息并在文本到达时编辑该消息来流式传输草稿回复。`channels.discord.streaming` 接受 `off`（默认）| `partial` | `block` | `progress`。`progress` 在 Discord 上映射到 `partial`；`streamMode` 是旧版别名，会自动迁移。 + OpenClaw 可以通过发送临时消息并在文本到达时编辑它来流式传输回复草稿。`channels.discord.streaming` 接受 `off`（默认）| `partial` | `block` | `progress`。在 Discord 上，`progress` 映射到 `partial`；`streamMode` 是旧版别名，会自动迁移。 - 默认保持 `off`，因为当多个机器人或 Gateway 网关共享一个账号时，Discord 预览编辑会很快触发速率限制。 + 默认保持为 `off`，因为当多个机器人或 Gateway 网关共享一个账号时，Discord 预览编辑很快会触发速率限制。 ```json5 { @@ -566,21 +567,21 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 } ``` - - `partial` 会在令牌到达时编辑一条预览消息。 - - `block` 会发出草稿大小的分块（使用 `draftChunk` 调整大小和断点，并被限制到 `textChunkLimit`）。 - - 媒体、错误和显式回复的最终消息会取消待处理的预览编辑。 + - `partial` 会在令牌到达时编辑单条预览消息。 + - `block` 会发出草稿大小的分块（使用 `draftChunk` 调整大小和断点，并钳制到 `textChunkLimit`）。 + - 媒体、错误和显式回复最终消息会取消待处理的预览编辑。 - `streaming.preview.toolProgress`（默认 `true`）控制工具/进度更新是否复用预览消息。 - 预览流式传输仅支持文本；媒体回复会回退到普通投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。 + 预览流式传输仅支持文本；媒体回复会回退到普通投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 - Guild 历史上下文： + 服务器历史上下文： - - `channels.discord.historyLimit` 默认值 `20` + - `channels.discord.historyLimit` 默认值为 `20` - 回退：`messages.groupChat.historyLimit` - - `0` 禁用 + - `0` 表示禁用 私信历史控制： @@ -590,17 +591,17 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 线程行为： - Discord 线程会作为渠道会话路由，并继承父渠道配置，除非被覆盖。 - - 线程会话会将父渠道的会话级 `/model` 选择作为仅模型回退继承；线程本地 `/model` 选择仍优先，并且不会复制父会话记录历史，除非已启用会话记录继承。 - - `channels.discord.thread.inheritParent`（默认 `false`）会让新的自动线程选择从父会话记录播种。按账号覆盖位于 `channels.discord.accounts..thread.inheritParent` 下。 + - 线程会话会继承父渠道的会话级 `/model` 选择，作为仅模型回退；线程本地 `/model` 选择仍然优先，并且除非启用转录继承，否则不会复制父转录历史。 + - `channels.discord.thread.inheritParent`（默认 `false`）会让新的自动线程选择从父转录播种。按账号覆盖位于 `channels.discord.accounts..thread.inheritParent` 下。 - 消息工具反应可以解析 `user:` 私信目标。 - `guilds..channels..requireMention: false` 会在回复阶段激活回退期间保留。 - 渠道主题会作为**不受信任**的上下文注入。允许列表会限制谁可以触发智能体，但不是完整的补充上下文脱敏边界。 + 渠道主题会作为**不受信任**的上下文注入。允许列表用于控制谁可以触发智能体，而不是完整的补充上下文删改边界。 - Discord 可以将线程绑定到会话目标，因此该线程中的后续消息会继续路由到同一会话（包括子智能体会话）。 + Discord 可以将一个线程绑定到会话目标，使该线程中的后续消息继续路由到同一会话（包括子智能体会话）。 命令： @@ -634,24 +635,24 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 } ``` - 备注： + 注意事项： - `session.threadBindings.*` 设置全局默认值。 - `channels.discord.threadBindings.*` 覆盖 Discord 行为。 - - `spawnSubagentSessions` 必须为 true，才能为 `sessions_spawn({ thread: true })` 自动创建/绑定话题。 - - `spawnAcpSessions` 必须为 true，才能为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建/绑定话题。 - - 如果某个账号禁用了话题绑定，`/focus` 和相关的话题绑定操作将不可用。 + - `spawnSubagentSessions` 必须为 true，才能为 `sessions_spawn({ thread: true })` 自动创建/绑定线程。 + - `spawnAcpSessions` 必须为 true，才能为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建/绑定线程。 + - 如果某个账号禁用了线程绑定，则 `/focus` 和相关线程绑定操作不可用。 - 参见[子智能体](/zh-CN/tools/subagents)、[ACP 智能体](/zh-CN/tools/acp-agents)和[配置参考](/zh-CN/gateway/configuration-reference)。 + 参见 [子智能体](/zh-CN/tools/subagents)、[ACP 智能体](/zh-CN/tools/acp-agents) 和 [配置参考](/zh-CN/gateway/configuration-reference)。 - 对于稳定的“始终在线”ACP 工作区，请配置顶层类型化 ACP 绑定，并将其指向 Discord 对话。 + 对于稳定的“常驻” ACP 工作区，配置指向 Discord 对话的顶层带类型 ACP 绑定。 配置路径： - - `bindings[]`，其中包含 `type: "acp"` 和 `match.channel: "discord"` + - `bindings[]`，带有 `type: "acp"` 和 `match.channel: "discord"` 示例： @@ -701,49 +702,49 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 } ``` - 注意： + 注意事项： - - `/acp spawn codex --bind here` 会就地绑定当前频道或话题，并让未来消息保持在同一个 ACP 会话中。话题消息会继承父频道绑定。 - - 在已绑定的频道或话题中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时话题绑定在激活期间可以覆盖目标解析。 - - 仅当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子话题时，才需要 `spawnAcpSessions`。 + - `/acp spawn codex --bind here` 会就地绑定当前频道或线程，并让之后的消息保持在同一个 ACP 会话上。线程消息会继承父频道绑定。 + - 在已绑定的频道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时线程绑定在活跃期间可以覆盖目标解析。 + - 只有当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子线程时，才需要 `spawnAcpSessions`。 - 有关绑定行为详情，请参见 [ACP 智能体](/zh-CN/tools/acp-agents)。 + 绑定行为详情参见 [ACP 智能体](/zh-CN/tools/acp-agents)。 - - 按服务器设置反应通知模式： + + 按服务器配置回应通知模式： - `off` - `own`（默认） - `all` - `allowlist`（使用 `guilds..users`） - 反应事件会被转换为系统事件，并附加到已路由的 Discord 会话。 + 回应事件会转换为系统事件，并附加到路由后的 Discord 会话。 - - `ackReaction` 会在 OpenClaw 处理传入消息时发送一个确认表情符号。 + + `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 解析顺序： - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - 智能体身份表情符号回退值（`agents.list[].identity.emoji`，否则为 "👀"） + - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 “👀”） - 注意： + 注意事项： - - Discord 接受 Unicode 表情符号或自定义表情名称。 - - 使用 `""` 可禁用某个渠道或账号的反应。 + - Discord 接受 Unicode 表情符号或自定义表情符号名称。 + - 使用 `""` 为某个频道或账号禁用回应。 - 默认启用由渠道发起的配置写入。 + 由渠道发起的配置写入默认已启用。 - 这会影响 `/config set|unset` 流程（当命令功能已启用时）。 + 这会影响 `/config set|unset` 流程（启用命令功能时）。 禁用： @@ -760,7 +761,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 - 使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord Gateway 网关 WebSocket 流量和启动时的 REST 查询（应用 ID + allowlist 解析）。 + 通过 HTTP(S) 代理路由 Discord 网关 WebSocket 流量和启动时 REST 查询（应用 ID + 允许列表解析），配置为 `channels.discord.proxy`。 ```json5 { @@ -806,17 +807,17 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 } ``` - 注意： + 注意事项： - - allowlist 可以使用 `pk:` - - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名称 + - 允许列表可以使用 `pk:` + - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按 name/slug 匹配成员显示名称 - 查询使用原始消息 ID，并受时间窗口限制 - - 如果查询失败，代理消息会被视为 bot 消息并丢弃，除非 `allowBots=true` + - 如果查询失败，代理消息会被视为机器人消息并被丢弃，除非 `allowBots=true` - 当你设置 Status 或活动字段，或启用自动在线状态时，会应用在线状态更新。 + 当你设置状态或活动字段，或启用自动在线状态时，会应用在线状态更新。 仅 Status 示例： @@ -830,7 +831,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 } ``` - 活动示例（自定义 Status 是默认活动类型）： + 活动示例（自定义状态是默认活动类型）： ```json5 { @@ -843,7 +844,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 } ``` - 流式传输示例： + 直播示例： ```json5 { @@ -860,11 +861,11 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 活动类型映射： - 0：正在玩 - - 1：正在流式传输（需要 `activityUrl`） + - 1：直播（需要 `activityUrl`） - 2：正在听 - 3：正在观看 - - 4：自定义（使用活动文本作为 Status 状态；表情符号可选） - - 5：正在竞赛 + - 4：自定义（使用活动文本作为状态内容；表情符号可选） + - 5：竞赛中 自动在线状态示例（运行时健康信号）： @@ -883,7 +884,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 } ``` - 自动在线状态会将运行时可用性映射到 Discord Status：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： + 自动在线状态会将运行时可用性映射到 Discord 状态：健康 => online，降级或未知 => idle，用尽或不可用 => dnd。可选文本覆盖项： - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -892,27 +893,29 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 - Discord 支持在私信中基于按钮处理审批，并且可以选择在发起渠道中发布审批提示。 + Discord 支持在私信中基于按钮处理审批，并且可以选择在发起审批的频道中发布审批提示。 配置路径： - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers`（可选；可行时回退到 `commands.ownerAllowFrom`） + - `channels.discord.execApprovals.approvers`（可选；可用时回退到 `commands.ownerAllowFrom`） - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` - 当 `enabled` 未设置或为 `"auto"`，并且至少能从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个审批人时，Discord 会自动启用原生 exec 审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec 审批人。设置 `enabled: false` 可明确禁用 Discord 作为原生审批客户端。 + 当 `enabled` 未设置或为 `"auto"`，且至少能从 `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 适配器主要添加审批人私信路由和频道扇出发送。 + 当这些按钮存在时，它们就是主要审批体验；只有当工具结果表明 + 聊天审批不可用，或手动审批是唯一路径时，OpenClaw 才应包含手动 `/approve` 命令。 - 如果 Discord 原生审批运行时未激活，OpenClaw 会保持本地确定性的 `/approve ` 提示可见。如果 - 运行时已激活，但原生卡片无法投递到任何目标，OpenClaw 会发送同一聊天回退通知，其中包含待处理审批中的确切 `/approve` - 命令。 + 如果 Discord 原生审批运行时未激活，OpenClaw 会保持本地确定性的 + `/approve ` 提示可见。如果运行时已激活，但原生卡片 + 无法投递到任何目标，OpenClaw 会在同一聊天中发送回退通知， + 其中包含来自待处理审批的精确 `/approve` 命令。 Gateway 网关身份验证和审批解析遵循共享 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。审批默认在 30 分钟后过期。 @@ -921,37 +924,37 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用 -## 工具和操作门禁 +## 工具和动作门控 -Discord 消息操作包括消息传递、频道管理、审核、在线状态和元数据操作。 +Discord 消息动作包括消息发送、频道管理、内容管理、在线状态和元数据动作。 核心示例： -- 消息传递：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` -- 反应：`react`、`reactions`、`emojiList` -- 审核：`timeout`、`kick`、`ban` +- 消息：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` +- 回应：`react`、`reactions`、`emojiList` +- 内容管理：`timeout`、`kick`、`ban` - 在线状态：`setPresence` -`event-create` 操作接受可选的 `image` 参数（URL 或本地文件路径），用于设置预定事件封面图。 +`event-create` 动作接受可选的 `image` 参数（URL 或本地文件路径），用于设置计划事件的封面图片。 -操作门禁位于 `channels.discord.actions.*` 下。 +动作门控位于 `channels.discord.actions.*` 下。 -默认门禁行为： +默认门控行为： -| 操作组 | 默认值 | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 已启用 | -| roles | 已禁用 | -| moderation | 已禁用 | -| presence | 已禁用 | +| 动作组 | 默认值 | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 已启用 | +| roles | 已禁用 | +| moderation | 已禁用 | +| presence | 已禁用 | -## 组件 v2 UI +## 组件 v2 界面 -OpenClaw 使用 Discord 组件 v2 处理 exec 审批和跨上下文标记。Discord 消息操作也可以接受 `components` 来实现自定义 UI（高级；需要通过 discord 工具构造组件载荷），而旧版 `embeds` 仍然可用，但不推荐使用。 +OpenClaw 使用 Discord 组件 v2 处理 exec 审批和跨上下文标记。Discord 消息动作也可以接受 `components` 来提供自定义界面（高级用法；需要通过 discord 工具构造组件载荷），而旧版 `embeds` 仍然可用，但不推荐使用。 - `channels.discord.ui.components.accentColor` 设置 Discord 组件容器使用的强调色（十六进制）。 - 使用 `channels.discord.accounts..ui.components.accentColor` 按账号设置。 -- 当存在组件 v2 时，会忽略 `embeds`。 +- 存在组件 v2 时，`embeds` 会被忽略。 示例： @@ -971,20 +974,20 @@ OpenClaw 使用 Discord 组件 v2 处理 exec 审批和跨上下文标记。Disc ## 语音 -Discord 有两个不同的语音表面：实时**语音频道**（连续对话）和**语音消息附件**（波形预览格式）。Gateway 网关同时支持两者。 +Discord 有两个不同的语音界面：实时 **语音频道**（连续对话）和 **语音消息附件**（波形预览格式）。Gateway 网关同时支持两者。 ### 语音频道 -设置清单： +设置检查清单： 1. 在 Discord Developer Portal 中启用 Message Content Intent。 -2. 使用角色/用户 allowlist 时，启用 Server Members Intent。 -3. 使用 `bot` 和 `applications.commands` 作用域邀请 bot。 -4. 在目标语音频道中授予 Connect、Speak、Send Messages 和 Read Message History。 +2. 使用角色/用户允许列表时，启用 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 命令相同的允许列表和组策略规则。 ```bash /vc join channel: @@ -1021,33 +1024,33 @@ Discord 有两个不同的语音表面：实时**语音频道**（连续对话 说明： -- `voice.tts` 仅覆盖语音播放的 `messages.tts`。 -- `voice.model` 仅覆盖用于 Discord 语音渠道响应的 LLM。保持未设置即可继承路由后的智能体模型。 -- STT 使用 `tools.media.audio`；`voice.model` 不影响转录。 -- 语音转录轮次从 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者发言者不能访问仅限所有者的工具（例如 `gateway` 和 `cron`）。 -- 语音默认启用；设置 `channels.discord.voice.enabled=false` 可禁用语音运行时和 `GuildVoiceStates` Gateway 网关意图。 -- `channels.discord.intents.voiceStates` 可以显式覆盖语音状态意图订阅。保持未设置可让该意图跟随 `voice.enabled`。 -- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 加入选项。 -- 如果未设置，`@discordjs/voice` 的默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 -- OpenClaw 还会监视接收解密失败，并在短时间窗口内重复失败后通过离开并重新加入语音渠道来自动恢复。 -- 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 版本线包含来自 discord.js PR #11449 的上游填充修复，该修复关闭了 discord.js issue #11419。 +- `voice.tts` 仅针对语音播放覆盖 `messages.tts`。 +- `voice.model` 仅针对 Discord 语音频道响应覆盖所用的 LLM。保持未设置可继承路由后的智能体模型。 +- STT 使用 `tools.media.audio`；`voice.model` 不影响转写。 +- 语音转写轮次会从 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者说话人无法访问仅限所有者的工具（例如 `gateway` 和 `cron`）。 +- 默认启用语音；设置 `channels.discord.voice.enabled=false` 可停用语音运行时和 `GuildVoiceStates` Gateway 网关 intent。 +- `channels.discord.intents.voiceStates` 可以显式覆盖语音状态 intent 订阅。保持未设置可让 intent 跟随 `voice.enabled`。 +- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` 加入选项。 +- 如果未设置，`@discordjs/voice` 默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 +- OpenClaw 也会监控接收解密失败，并在短时间窗口内重复失败后通过离开并重新加入语音频道自动恢复。 +- 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 版本线包含来自 discord.js PR #11449 的上游 padding 修复，该修复关闭了 discord.js issue #11419。 -语音渠道流水线： +语音频道流水线： -- Discord PCM 捕获会转换为 WAV 临时文件。 +- Discord PCM 捕获会转换为一个 WAV 临时文件。 - `tools.media.audio` 处理 STT，例如 `openai/gpt-4o-mini-transcribe`。 -- 转录文本会通过常规 Discord 入口和路由发送。 -- 设置 `voice.model` 后，它仅覆盖此语音渠道轮次的响应 LLM。 -- `voice.tts` 会合并到 `messages.tts` 之上；生成的音频会在已加入的渠道中播放。 +- 转写文本会通过常规 Discord 入口和路由发送。 +- 设置 `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 会拒绝在同一 payload 中同时包含文本和语音消息）。 +- 提供一个**本地文件路径**（URL 会被拒绝）。 +- 省略文本内容（Discord 会拒绝同一个 payload 中的文本 + 语音消息）。 - 接受任何音频格式；OpenClaw 会按需转换为 OGG/Opus。 ```bash @@ -1057,19 +1060,19 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## 故障排除 - + - 启用 Message Content Intent - 当你依赖用户/成员解析时，启用 Server Members Intent - - 更改意图后重启 Gateway 网关 + - 更改 intent 后重启 Gateway 网关 - + - 验证 `groupPolicy` - - 验证 `channels.discord.guilds` 下的服务器允许列表 - - 如果存在服务器 `channels` 映射，则只允许列出的渠道 + - 验证 `channels.discord.guilds` 下的 guild allowlist + - 如果存在 guild `channels` map，则只允许列出的频道 - 验证 `requireMention` 行为和提及模式 有用的检查： @@ -1082,12 +1085,12 @@ openclaw logs --follow - + 常见原因： - - `groupPolicy="allowlist"` 但没有匹配的服务器/渠道允许列表 - - `requireMention` 配置在了错误位置（必须位于 `channels.discord.guilds` 或渠道条目下） - - 发送者被服务器/渠道 `users` 允许列表阻止 + - `groupPolicy="allowlist"`，但没有匹配的 guild/channel allowlist + - `requireMention` 配置在了错误位置（必须位于 `channels.discord.guilds` 或 channel 条目下） + - 发送者被 guild/channel `users` allowlist 阻止 @@ -1098,13 +1101,13 @@ openclaw logs --follow - `Slow listener detected ...` - `stuck session: sessionKey=agent:...:discord:... state=processing ...` - Carbon Gateway 网关队列旋钮： + Carbon Gateway 网关队列调节项： - 单账号：`channels.discord.eventQueue.listenerTimeout` - 多账号：`channels.discord.accounts..eventQueue.listenerTimeout` - - 这只控制 Carbon Gateway 网关监听器工作，而不是智能体轮次生命周期 + - 这只控制 Carbon Gateway 网关监听器工作，不控制智能体轮次生命周期 - Discord 不会对排队的智能体轮次应用渠道拥有的超时。消息监听器会立即移交，排队的 Discord 运行会保持每个会话的顺序，直到会话/工具/运行时生命周期完成或中止工作。 + Discord 不会对排队的智能体轮次应用频道自有的超时。消息监听器会立即移交，排队的 Discord 运行会保持每个会话的顺序，直到 session/tool/runtime 生命周期完成或中止工作。 ```json5 { @@ -1125,9 +1128,9 @@ openclaw logs --follow - OpenClaw 会在连接前获取 Discord `/gateway/bot` 元数据。临时失败会回退到 Discord 的默认 Gateway 网关 URL，并在日志中进行速率限制。 + OpenClaw 会在连接前获取 Discord `/gateway/bot` 元数据。暂时性失败会回退到 Discord 的默认 Gateway 网关 URL，并在日志中进行速率限制。 - 元数据超时旋钮： + 元数据超时调节项： - 单账号：`channels.discord.gatewayInfoTimeoutMs` - 多账号：`channels.discord.accounts..gatewayInfoTimeoutMs` @@ -1137,37 +1140,37 @@ openclaw logs --follow - `channels status --probe` 权限检查仅适用于数字渠道 ID。 + `channels status --probe` 权限检查仅适用于数字频道 ID。 - 如果你使用 slug 键，运行时匹配仍可工作，但 probe 无法完全验证权限。 + 如果你使用 slug 键，运行时匹配仍可正常工作，但 probe 无法完整验证权限。 - - 私信已禁用：`channels.discord.dm.enabled=false` - - 私信策略已禁用：`channels.discord.dmPolicy="disabled"`（旧版：`channels.discord.dm.policy`） - - 在 `pairing` 模式中等待配对批准 + - 私信已停用：`channels.discord.dm.enabled=false` + - 私信策略已停用：`channels.discord.dmPolicy="disabled"`（旧版：`channels.discord.dm.policy`） + - 在 `pairing` 模式下等待配对批准 - - 默认情况下，会忽略机器人编写的消息。 + + 默认情况下会忽略 bot 编写的消息。 - 如果你设置了 `channels.discord.allowBots=true`，请使用严格的提及和允许列表规则来避免循环行为。 - 优先使用 `channels.discord.allowBots="mentions"`，仅接受提及该机器人的机器人消息。 + 如果你设置 `channels.discord.allowBots=true`，请使用严格的提及和 allowlist 规则来避免循环行为。 + 优先使用 `channels.discord.allowBots="mentions"`，只接受提及该 bot 的 bot 消息。 - + - - 保持 OpenClaw 为当前版本（`openclaw update`），以便具备 Discord 语音接收恢复逻辑 - - 确认 `channels.discord.voice.daveEncryption=true`（默认） - - 从 `channels.discord.voice.decryptionFailureTolerance=24`（上游默认值）开始，仅在需要时调整 - - 查看日志中的： + - 保持 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 接收历史进行比较 @@ -1184,21 +1187,21 @@ openclaw logs --follow - 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` - Gateway 网关元数据：`gatewayInfoTimeoutMs` - 回复/历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` -- 投递：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` +- 交付：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` - 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` - 媒体/重试：`mediaMaxMb`（限制出站 Discord 上传，默认 `100MB`）、`retry` -- 操作：`actions.*` +- 动作：`actions.*` - 在线状态：`activity`、`status`、`activityType`、`activityUrl` - UI：`ui.components.accentColor` - 功能：`threadBindings`、顶层 `bindings[]`（`type: "acp"`）、`pluralkit`、`execApprovals`、`intents`、`agentComponents`、`heartbeat`、`responsePrefix` -## 安全与运维 +## 安全和运维 -- 将机器人令牌视为机密（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 +- 将 bot token 视为密钥（在受监督环境中优先使用 `DISCORD_BOT_TOKEN`）。 - 授予最小权限的 Discord 权限。 -- 如果命令部署/状态已过期，请重启 Gateway 网关并使用 `openclaw channels status --probe` 重新检查。 +- 如果命令部署/状态陈旧，请重启 Gateway 网关，并用 `openclaw channels status --probe` 重新检查。 ## 相关 @@ -1207,7 +1210,7 @@ openclaw logs --follow 将 Discord 用户配对到 Gateway 网关。 - 群聊和允许列表行为。 + 群聊和 allowlist 行为。 将入站消息路由到智能体。 @@ -1216,9 +1219,9 @@ openclaw logs --follow 威胁模型和加固。 - 将服务器和渠道映射到智能体。 + 将 guild 和频道映射到智能体。 - + 原生命令行为。 diff --git a/docs/zh-CN/channels/telegram.md b/docs/zh-CN/channels/telegram.md index 8d9a6a4ad..120a00f7e 100644 --- a/docs/zh-CN/channels/telegram.md +++ b/docs/zh-CN/channels/telegram.md @@ -4,22 +4,22 @@ read_when: summary: Telegram 机器人支持状态、能力和配置 title: Telegram x-i18n: - generated_at: "2026-04-29T11:47:17Z" + generated_at: "2026-04-29T12:05:10Z" model: gpt-5.5 provider: openai - source_hash: 8bae9845e95669fe21d75694d81172bfb4fc6329b67ef232e7fe4cbf67b87958 + source_hash: 8db902132bd9b93deda2f951353dadc6ea2d4d76a59919cf1fb90f7e75615556 source_path: channels/telegram.md workflow: 16 --- -可用于生产环境，通过 grammY 支持机器人私信和群组。默认模式是长轮询；Webhook 模式可选。 +可用于生产环境的机器人私信和群组，基于 grammY。默认模式是长轮询；webhook 模式可选。 Telegram 的默认私信策略是配对。 - 跨渠道诊断和修复手册。 + 跨渠道诊断和修复操作手册。 完整的渠道配置模式和示例。 @@ -30,9 +30,9 @@ x-i18n: - 打开 Telegram 并与 **@BotFather** 聊天（确认账号名正好是 `@BotFather`）。 + 打开 Telegram 并与 **@BotFather** 聊天（确认账号名正是 `@BotFather`）。 - 运行 `/newbot`，按照提示操作，并保存令牌。 + 运行 `/newbot`，按提示操作，并保存令牌。 @@ -51,12 +51,12 @@ x-i18n: } ``` - 环境回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。 - Telegram **不** 使用 `openclaw channels login telegram`；请在配置/环境中配置令牌，然后启动 Gateway 网关。 + 环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。 + Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置令牌，然后启动 Gateway 网关。 - + ```bash openclaw gateway @@ -74,21 +74,21 @@ openclaw pairing approve telegram -令牌解析顺序支持按账号区分。实际上，配置值优先于环境回退，且 `TELEGRAM_BOT_TOKEN` 只适用于默认账号。 +令牌解析顺序会识别账户。实践中，配置值优先于环境变量回退，并且 `TELEGRAM_BOT_TOKEN` 只适用于默认账户。 ## Telegram 端设置 - Telegram 机器人默认使用**隐私模式**，这会限制它们能接收哪些群组消息。 + Telegram 机器人默认使用**隐私模式**，这会限制它们接收的群组消息。 如果机器人必须看到所有群组消息，可以： - 通过 `/setprivacy` 禁用隐私模式，或 - 将机器人设为群组管理员。 - 切换隐私模式时，请在每个群组中移除并重新添加机器人，这样 Telegram 才会应用变更。 + 切换隐私模式后，请在每个群组中移除并重新添加机器人，以便 Telegram 应用该变更。 @@ -102,7 +102,7 @@ openclaw pairing approve telegram - `/setjoingroups` 用于允许/拒绝添加到群组 - - `/setprivacy` 用于控制群组可见性行为 + - `/setprivacy` 用于群组可见性行为 @@ -118,27 +118,27 @@ openclaw pairing approve telegram - `open`（要求 `allowFrom` 包含 `"*"`） - `disabled` - `dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到机器人用户名的 Telegram 账号都能命令该机器人。仅应将它用于有意公开且工具受到严格限制的机器人；单所有者机器人应使用带数字用户 ID 的 `allowlist`。 + `dmPolicy: "open"` 配合 `allowFrom: ["*"]` 会允许任何找到或猜到机器人用户名的 Telegram 账户向机器人发出命令。仅应将它用于有意公开且工具严格受限的机器人；单一所有者机器人应使用带数字用户 ID 的 `allowlist`。 - `channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。接受 `telegram:` / `tg:` 前缀，并会规范化。 - 在多账号配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账号级 `allowFrom: ["*"]` 条目不会使该账号公开，除非合并后的有效账号允许列表仍包含显式通配符。 - `dmPolicy: "allowlist"` 搭配空 `allowFrom` 会阻止所有私信，并会被配置校验拒绝。 - 设置只要求填写数字用户 ID。 - 如果你已升级且配置包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。 - 如果你之前依赖配对存储允许列表文件，`openclaw doctor --fix` 可以在允许列表流程中将条目恢复到 `channels.telegram.allowFrom`（例如 `dmPolicy: "allowlist"` 尚无显式 ID 时）。 + `channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。 + 在多账户配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账户级 `allowFrom: ["*"]` 条目不会让该账户公开，除非合并后的有效账户允许列表中仍包含显式通配符。 + `dmPolicy: "allowlist"` 配合空的 `allowFrom` 会阻止所有私信，并会被配置校验拒绝。 + 设置只会询问数字用户 ID。 + 如果你已升级且配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。 + 如果你之前依赖配对存储的允许列表文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。 - 对于单所有者机器人，建议使用 `dmPolicy: "allowlist"` 并设置显式数字 `allowFrom` ID，使访问策略在配置中保持持久（而不是依赖之前的配对批准）。 + 对于单一所有者机器人，建议使用 `dmPolicy: "allowlist"` 并配置显式数字 `allowFrom` ID，以便将访问策略持久保存在配置中（而不是依赖之前的配对批准）。 - 常见混淆：私信配对批准并不意味着“此发送者在所有地方都已授权”。 - 配对授予私信访问权限。如果还没有命令所有者，首次获批配对还会设置 `commands.ownerAllowFrom`，从而为仅所有者命令和执行批准提供显式操作员账号。 + 常见混淆：私信配对批准并不表示“此发送者在所有地方都已授权”。 + 配对授予私信访问权限。如果尚无命令所有者，第一次批准的配对还会设置 `commands.ownerAllowFrom`，使仅所有者命令和 exec 批准拥有显式操作员账户。 群组发送者授权仍来自显式配置允许列表。 - 如果你想要“一次授权后私信和群组命令都能工作”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:`。 + 如果你希望“我授权一次后，私信和群组命令都能工作”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:`。 ### 查找你的 Telegram 用户 ID 更安全（无需第三方机器人）： - 1. 向你的机器人发送私信。 + 1. 私信你的机器人。 2. 运行 `openclaw logs --follow`。 3. 读取 `from.id`。 @@ -153,12 +153,12 @@ curl "https://api.telegram.org/bot/getUpdates" - 两个控制项会同时生效： + 两项控制会共同生效： 1. **允许哪些群组**（`channels.telegram.groups`） - 没有 `groups` 配置： - - 搭配 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查 - - 搭配 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`） + - 配合 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查 + - 配合 `groupPolicy: "allowlist"`（默认）：在你添加 `groups` 条目（或 `"*"`）之前，群组会被阻止 - 已配置 `groups`：作为允许列表（显式 ID 或 `"*"`） 2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`） @@ -167,16 +167,16 @@ curl "https://api.telegram.org/bot/getUpdates" - `disabled` `groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。 - `groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会规范化）。 + `groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。 不要将 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 应放在 `channels.telegram.groups` 下。 非数字条目会在发送者授权中被忽略。 - 安全边界（`2026.2.25+`）：群组发送者认证**不会**继承私信配对存储批准。 - 配对仅用于私信。对于群组，请设置 `groupAllowFrom` 或按群组/按话题设置 `allowFrom`。 - 如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。 - 单所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。 - 运行时注意事项：如果完全缺少 `channels.telegram`，除非显式设置了 `channels.defaults.groupPolicy`，否则运行时默认会以失败关闭方式使用 `groupPolicy="allowlist"`。 + 安全边界（`2026.2.25+`）：群组发送者身份验证**不会**继承私信配对存储批准。 + 配对仅限私信。对于群组，请设置 `groupAllowFrom` 或每群组/每话题的 `allowFrom`。 + 如果未设置 `groupAllowFrom`，Telegram 会回退到配置 `allowFrom`，而不是配对存储。 + 单一所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。 + 运行时注意：如果完全缺少 `channels.telegram`，运行时会默认故障关闭为 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。 - 示例：允许某个特定群组中的任何成员： + 示例：允许一个特定群组中的任何成员： ```json5 { @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 示例：仅允许某个特定群组内的特定用户： + 示例：只允许一个特定群组中的特定用户： ```json5 { @@ -213,21 +213,21 @@ curl "https://api.telegram.org/bot/getUpdates" 常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。 - - 将 `-1001234567890` 这样的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。 - - 当你想限制已允许群组内哪些人可以触发机器人时，将 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 - - 仅在你希望已允许群组中的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。 + - 将类似 `-1001234567890` 的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。 + - 当你想限制已允许群组中哪些人可以触发机器人时，将类似 `8734062810` 的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 + - 只有在你希望已允许群组中的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。 - 群组回复默认需要提及。 + 群组回复默认要求提及。 提及可以来自： - 原生 `@botusername` 提及，或 - - 以下位置的提及模式： + - 以下位置中的提及模式： - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` @@ -236,7 +236,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - 这些只会更新会话状态。使用配置实现持久化。 + 这些只会更新会话状态。使用配置来持久化。 持久化配置示例： @@ -255,7 +255,7 @@ curl "https://api.telegram.org/bot/getUpdates" 获取群组聊天 ID： - 将群组消息转发给 `@userinfobot` / `@getidsbot` - - 或从 `openclaw logs --follow` 中读取 `chat.id` + - 或从 `openclaw logs --follow` 读取 `chat.id` - 或检查 Bot API `getUpdates` @@ -265,18 +265,18 @@ curl "https://api.telegram.org/bot/getUpdates" - Telegram 由 Gateway 网关进程拥有。 - 路由是确定性的：Telegram 入站会回复到 Telegram（模型不会选择渠道）。 -- 入站消息会规范化为共享渠道信封，并包含回复元数据和媒体占位符。 +- 入站消息会规范化为共享渠道信封，包含回复元数据和媒体占位符。 - 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:` 以保持话题隔离。 -- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用线程感知的会话键路由它们，并为回复保留线程 ID。 -- 长轮询使用 grammY runner，并按每个聊天/每个线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。 -- 每个 Gateway 网关进程内部都会保护长轮询，因此同一时间只有一个活动轮询器可以使用一个机器人令牌。如果你仍然看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一令牌。 -- 默认情况下，长轮询看门狗会在 120 秒内没有完成的 `getUpdates` 活跃性后触发重启。仅当你的部署在长时间运行工作期间仍出现误报轮询停滞重启时，才提高 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。 +- 私信消息可以携带 `message_thread_id`；OpenClaw 会用支持线程的会话键对其进行路由，并为回复保留线程 ID。 +- 长轮询使用 grammY runner，并按聊天/线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。 +- 每个 Gateway 网关进程内都会保护长轮询，确保同一时间只有一个活动 poller 可以使用一个机器人令牌。如果你仍看到 `getUpdates` 409 冲突，可能有另一个 OpenClaw Gateway 网关、脚本或外部 poller 正在使用同一个令牌。 +- 默认情况下，如果 120 秒内没有完成的 `getUpdates` 存活信号，长轮询 watchdog 会触发重启。仅当你的部署在长时间运行工作期间仍看到误判的轮询停滞重启时，才增大 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账户覆盖。 - Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。 ## 功能参考 - + OpenClaw 可以实时流式传输部分回复： - 直接聊天：预览消息 + `editMessageText` @@ -285,11 +285,11 @@ curl "https://api.telegram.org/bot/getUpdates" 要求： - `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`） - - 在 Telegram 上，`progress` 会映射到 `partial`（与跨渠道命名兼容） - - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（默认：预览流式传输启用时为 `true`） - - 会检测旧版 `channels.telegram.streamMode` 和布尔 `streaming` 值；运行 `openclaw doctor --fix` 可将它们迁移到 `channels.telegram.streaming.mode` + - `progress` 在 Telegram 上映射到 `partial`（兼容跨渠道命名） + - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（默认：预览流式传输处于活动状态时为 `true`） + - 会检测旧版 `channels.telegram.streamMode` 和布尔值 `streaming`；运行 `openclaw doctor --fix` 可将它们迁移到 `channels.telegram.streaming.mode` - 工具进度预览更新是在工具运行时显示的简短“正在工作...”行，例如命令执行、文件读取、计划更新或补丁摘要。Telegram 默认保持启用这些内容，以匹配 `v2026.4.22` 及更高版本已发布的 OpenClaw 行为。若要保留答案文本的已编辑预览，但隐藏工具进度行，请设置： + 工具进度预览更新是在工具运行时显示的简短 “Working...” 行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持这些更新启用，以匹配 `v2026.4.22` 及更高版本发布的 OpenClaw 行为。若要保留回答文本的已编辑预览，但隐藏工具进度行，请设置： ```json { @@ -306,34 +306,34 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 仅当你需要只交付最终消息时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立“正在工作...”消息发送。批准提示、媒体负载和错误仍会通过正常最终交付路由。若你只想保留答案预览编辑，同时隐藏工具进度状态行，请使用 `streaming.preview.toolProgress: false`。 + 仅当你希望只交付最终消息时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，并且通用工具/进度闲聊会被抑制，而不是作为独立的 “Working...” 消息发送。批准提示、媒体载荷和错误仍会通过正常最终交付路由。仅当你只想保留回答预览编辑，同时隐藏工具进度状态行时，才使用 `streaming.preview.toolProgress: false`。 对于纯文本回复： - - 短私信/群组/话题预览：OpenClaw 保留同一条预览消息，并在原处执行最终编辑 - - 早于约一分钟的预览：OpenClaw 将完成的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间 + - 简短的私信/群组/topic 预览：OpenClaw 保留同一条预览消息，并在原处执行最终编辑 + - 超过约一分钟的预览：OpenClaw 将完成的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间 - 对于复杂回复（例如媒体载荷），OpenClaw 会回退到常规最终投递，然后清理预览消息。 + 对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终投递，然后清理预览消息。 - 预览流式传输独立于分块流式传输。为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 + 预览流式传输独立于分块流式传输。当 Telegram 明确启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 - 如果原生草稿传输不可用或被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。 + 如果原生草稿传输不可用/被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。 - 仅限 Telegram 的推理流： + 仅 Telegram 推理流： - - `/reasoning stream` 在生成期间将推理发送到实时预览 + - `/reasoning stream` 会在生成时将推理发送到实时预览 - 最终答案发送时不包含推理文本 - + 出站文本使用 Telegram `parse_mode: "HTML"`。 - 类 Markdown 文本会渲染为 Telegram 安全的 HTML。 - 原始模型 HTML 会被转义，以减少 Telegram 解析失败。 - - 如果 Telegram 拒绝解析后的 HTML，OpenClaw 会以纯文本重试。 + - 如果 Telegram 拒绝已解析的 HTML，OpenClaw 会重试为纯文本。 - 链接预览默认启用，可以用 `channels.telegram.linkPreview: false` 禁用。 + 链接预览默认启用，可通过 `channels.telegram.linkPreview: false` 禁用。 @@ -342,7 +342,7 @@ curl "https://api.telegram.org/bot/getUpdates" 原生命令默认值： - - `commands.native: "auto"` 为 Telegram 启用原生命令 + - `commands.native: "auto"` 会为 Telegram 启用原生命令 添加自定义命令菜单项： @@ -361,40 +361,40 @@ curl "https://api.telegram.org/bot/getUpdates" 规则： - - 名称会被规范化（去掉前导 `/`，转换为小写） + - 名称会被规范化（去掉开头的 `/`，转换为小写） - 有效模式：`a-z`、`0-9`、`_`，长度 `1..32` - 自定义命令不能覆盖原生命令 - 冲突/重复项会被跳过并记录日志 - 注意： + 说明： - 自定义命令只是菜单项；它们不会自动实现行为 - - 即使插件/skill 命令未显示在 Telegram 菜单中，键入时仍可工作 + - 插件/Skill 命令即使未显示在 Telegram 菜单中，输入时仍可生效 - 如果禁用原生命令，内置命令会被移除。自定义/插件命令在配置后仍可注册。 + 如果禁用原生命令，内置命令会被移除。自定义/插件命令在已配置时仍可能注册。 常见设置失败： - - `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 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 拒绝了已配置的机器人令牌。请用当前 BotFather 令牌更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。 + - `setMyCommands failed` 带有网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。 ### 设备配对命令（`device-pair` 插件） 安装 `device-pair` 插件后： 1. `/pair` 生成设置代码 - 2. 在 iOS 应用中粘贴代码 + 2. 将代码粘贴到 iOS 应用中 3. `/pair pending` 列出待处理请求（包括角色/作用域） 4. 批准请求： - `/pair approve ` 用于显式批准 - 只有一个待处理请求时使用 `/pair approve` - `/pair approve latest` 用于最近的请求 - 设置代码携带一个短期有效的引导 token。内置引导交接会让主节点 token 保持在 `scopes: []`；任何被交接的 operator token 都限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 范围内。引导作用域检查带有角色前缀，因此该 operator 允许列表只满足 operator 请求；非 operator 角色仍需要在其自身角色前缀下的作用域。 + 设置代码携带短期有效的引导令牌。内置引导交接会将主节点令牌保持在 `scopes: []`；任何交接的操作员令牌都限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 范围内。引导作用域检查带有角色前缀，因此该操作员允许列表只满足操作员请求；非操作员角色仍需要其自身角色前缀下的作用域。 - 如果设备用变更后的认证详情重试（例如角色/作用域/公钥），先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 + 如果设备使用已更改的认证详情（例如角色/作用域/公钥）重试，则之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。 @@ -443,7 +443,7 @@ curl "https://api.telegram.org/bot/getUpdates" 旧版 `capabilities: ["inlineButtons"]` 映射到 `inlineButtons: "all"`。 - 消息动作示例： + 消息操作示例： ```json5 { @@ -466,8 +466,8 @@ curl "https://api.telegram.org/bot/getUpdates" - - Telegram 工具动作包括： + + Telegram 工具操作包括： - `sendMessage`（`to`、`content`，可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`） - `react`（`chatId`、`messageId`、`emoji`） @@ -475,7 +475,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`）。 门控控制： @@ -485,17 +485,17 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.sticker`（默认：禁用） 注意：`edit` 和 `topic-create` 目前默认启用，且没有单独的 `channels.telegram.actions.*` 开关。 - 运行时发送使用活动的配置/secret 快照（启动/重载），因此动作路径不会在每次发送时临时重新解析 SecretRef。 + 运行时发送使用活动的配置/密钥快照（启动/重载），因此操作路径不会在每次发送时执行临时 SecretRef 重新解析。 - reaction 移除语义：[/tools/reactions](/zh-CN/tools/reactions) + 移除回应的语义：[/tools/reactions](/zh-CN/tools/reactions) - Telegram 支持在生成输出中使用显式回复线程标签： + Telegram 支持在生成的输出中使用显式回复线程标签： - `[[reply_to_current]]` 回复触发消息 - - `[[reply_to:]]` 回复指定的 Telegram 消息 ID + - `[[reply_to:]]` 回复特定 Telegram 消息 ID `channels.telegram.replyToMode` 控制处理方式： @@ -503,29 +503,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_*]]` 标签仍会被遵守。 + 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。 - + 论坛超级群组： - - 话题会话键会追加 `:topic:` - - 回复和正在输入状态以话题线程为目标 - - 话题配置路径： + - topic 会话键会追加 `:topic:` + - 回复和输入状态会指向 topic 线程 + - topic 配置路径： `channels.telegram.groups..topics.` - 常规话题（`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` - 话题继承：话题条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 - `agentId` 仅属于话题，不会从群组默认值继承。 + topic 继承：topic 条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 + `agentId` 仅限 topic，不会从群组默认值继承。 - **按话题路由智能体**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同智能体。这让每个话题拥有自己的隔离工作区、记忆和会话。示例： + **按 topic 的智能体路由**：每个 topic 都可以通过在 topic 配置中设置 `agentId` 路由到不同的智能体。这会为每个 topic 提供独立的工作区、记忆和会话。示例： ```json5 { @@ -545,28 +545,28 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 然后每个话题都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3` + 随后每个 topic 都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3` - **持久 ACP 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定（`bindings[]`，其中 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的话题限定 id）固定 ACP harness 会话。目前作用域限于群组/超级群组中的论坛话题。参见 [ACP Agents](/zh-CN/tools/acp-agents)。 + **持久 ACP topic 绑定**：论坛 topic 可以通过顶层类型化 ACP 绑定固定 ACP harness 会话（`bindings[]`，其中 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，以及像 `-1001234567890:topic:42` 这样的 topic 限定 id）。目前范围限定于群组/超级群组中的论坛 topic。参见 [ACP 智能体](/zh-CN/tools/acp-agents)。 - **从聊天中生成线程绑定 ACP**：`/acp spawn --thread here|auto` 将当前话题绑定到新的 ACP 会话；后续消息会直接路由到该处。OpenClaw 会将生成确认固定在话题内。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。 + **从聊天生成线程绑定的 ACP**：`/acp spawn --thread here|auto` 会将当前 topic 绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在 topic 内固定生成确认。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。 - 模板上下文公开 `MessageThreadId` 和 `IsForum`。带 `message_thread_id` 的私信聊天会保留私信路由，但使用感知线程的会话键。 + 模板上下文暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保持私信路由，但使用线程感知的会话键。 ### 音频消息 - Telegram 区分语音便笺和音频文件。 + Telegram 会区分语音便条与音频文件。 - 默认：音频文件行为 - - 在智能体回复中使用标签 `[[audio_as_voice]]` 强制作为语音便笺发送 - - 入站语音便笺转写会在智能体上下文中被框定为机器生成的、 + - 在智能体回复中使用标签 `[[audio_as_voice]]` 强制发送为语音便条 + - 入站语音便条转录会在智能体上下文中被框定为机器生成的、 不受信任文本；提及检测仍使用原始 - 转写，因此提及门控的语音消息会继续工作。 + 转录，因此受提及门控的语音消息会继续工作。 - 消息动作示例： + 消息操作示例： ```json5 { @@ -580,9 +580,9 @@ curl "https://api.telegram.org/bot/getUpdates" ### 视频消息 - Telegram 区分视频文件和视频便笺。 + Telegram 会区分视频文件与视频便条。 - 消息动作示例： + 消息操作示例： ```json5 { @@ -594,7 +594,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 视频便笺不支持标题；提供的消息文本会单独发送。 + 视频便条不支持说明；提供的消息文本会单独发送。 ### 贴纸 @@ -616,9 +616,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - 贴纸会被描述一次（在可能时）并缓存，以减少重复视觉调用。 + 贴纸会被描述一次（在可能时），并缓存以减少重复视觉调用。 - 启用贴纸动作： + 启用贴纸操作： ```json5 { @@ -632,7 +632,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 发送贴纸动作： + 发送贴纸操作： ```json5 { @@ -643,7 +643,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 搜索缓存的贴纸： + 搜索已缓存贴纸： ```json5 { @@ -656,44 +656,44 @@ curl "https://api.telegram.org/bot/getUpdates" - - Telegram reactions 作为 `message_reaction` 更新到达（独立于消息载荷）。 + + Telegram 回应会作为 `message_reaction` 更新到达（与消息载荷分开）。 - 启用后，OpenClaw 会将如下系统事件加入队列： + 启用后，OpenClaw 会将系统事件加入队列，例如： - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` 配置： - - `channels.telegram.reactionNotifications`：`off | own | all`（默认值：`own`） - - `channels.telegram.reactionLevel`：`off | ack | minimal | extensive`（默认值：`minimal`） + - `channels.telegram.reactionNotifications`: `off | own | all`（默认：`own`） + - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive`（默认：`minimal`） - 注意事项： + 备注： - - `own` 表示仅用户对机器人发送消息的反应（通过已发送消息缓存尽力实现）。 - - 反应事件仍遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。 - - Telegram 不会在反应更新中提供话题 ID。 - - 非论坛群组路由到群聊会话 - - 论坛群组路由到群组通用话题会话（`:topic:1`），而不是确切的来源话题 + - `own` 表示仅处理用户对机器人已发送消息的回应（通过已发送消息缓存尽力而为）。 + - 回应事件仍会遵循 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。 + - Telegram 不会在回应更新中提供话题 ID。 + - 非论坛群组会路由到群聊会话 + - 论坛群组会路由到群组通用话题会话（`:topic:1`），而不是确切的原始话题 轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。 - - `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 + + `ackReaction` 会在 OpenClaw 处理传入消息时发送一个确认 emoji。 解析顺序： - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） + - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 "👀"） - 注意事项： + 备注： - - Telegram 需要 unicode 表情符号（例如 "👀"）。 - - 使用 `""` 可为某个渠道或账号禁用反应。 + - Telegram 需要 unicode emoji（例如 "👀"）。 + - 使用 `""` 可为某个渠道或账号禁用回应。 @@ -720,28 +720,28 @@ 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"`。 - Webhook 模式会在向 Telegram 返回 `200` 之前验证请求防护、Telegram 密钥令牌和 JSON 正文。 - 然后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道路异步处理该更新，因此缓慢的智能体轮次不会阻塞 Telegram 的投递 ACK。 + Webhook 模式会在向 Telegram 返回 `200` 之前验证请求防护、Telegram secret token 和 JSON body。 + 随后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道路异步处理更新，因此较慢的智能体轮次不会阻塞 Telegram 的投递 ACK。 - - `channels.telegram.textChunkLimit` 默认值为 4000。 - - `channels.telegram.chunkMode="newline"` 会在按长度拆分前优先使用段落边界（空行）。 - - `channels.telegram.mediaMaxMb`（默认 100）限制入站和出站 Telegram 媒体大小。 - - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（如未设置，则使用 grammY 默认值）。 - - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在轮询停滞重启误报时，在 `30000` 到 `600000` 之间调整。 + - `channels.telegram.textChunkLimit` 默认是 4000。 + - `channels.telegram.chunkMode="newline"` 在按长度拆分前优先使用段落边界（空行）。 + - `channels.telegram.mediaMaxMb`（默认 100）限制传入和传出的 Telegram 媒体大小。 + - `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时（如未设置，则使用 grammY 默认值）。 + - `channels.telegram.pollingStallThresholdMs` 默认为 `120000`；仅在轮询停滞重启出现误报时，在 `30000` 到 `600000` 之间调整。 - 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。 - - 回复/引用/转发补充上下文目前会按接收内容传递。 - - Telegram 允许列表主要限制谁可以触发智能体，而不是完整的补充上下文编辑边界。 + - 回复/引用/转发的补充上下文目前会按收到的内容传递。 + - Telegram allowlist 主要限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 - 私信历史控制： - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - `channels.telegram.retry` 配置适用于可恢复出站 API 错误的 Telegram 发送辅助函数（CLI/工具/动作）。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能导致可见消息重复的模糊发送后网络封包。 + - `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/actions）中的可恢复出站 API 错误。传入最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能导致可见消息重复的含糊发送后网络信封。 CLI 发送目标可以是数字聊天 ID 或用户名： @@ -765,52 +765,52 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - `--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 支持在审批者私信中进行执行审批，并且可以选择在来源聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。 + + Telegram 支持在审批人私信中进行 exec 审批，也可以选择在原始聊天或话题中发布提示。审批人必须是数字 Telegram 用户 ID。 配置路径： - - `channels.telegram.execApprovals.enabled`（当至少一个审批者可解析时自动启用） - - `channels.telegram.execApprovals.approvers`（回退到 `commands.ownerAllowFrom` 中的数字所有者 ID） - - `channels.telegram.execApprovals.target`：`dm`（默认）| `channel` | `both` + - `channels.telegram.execApprovals.enabled`（至少有一个审批人可解析时自动启用） + - `channels.telegram.execApprovals.approvers`（回退到 `commands.ownerAllowFrom` 中的数字 owner ID） + - `channels.telegram.execApprovals.target`: `dm`（默认）| `channel` | `both` - `agentFilter`、`sessionFilter` - `channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人对话以及机器人向何处发送普通回复。它们不会让某人成为执行审批者。当还没有命令所有者时，第一个已批准的私信配对会引导创建 `commands.ownerAllowFrom`，因此单所有者设置仍可工作，无需在 `execApprovals.approvers` 下重复 ID。 + `channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人对话，以及它在哪里发送常规回复。它们不会让某人成为 exec 审批人。当还没有命令 owner 时，第一个获批的私信配对会引导写入 `commands.ownerAllowFrom`，因此单 owner 设置仍可工作，无需在 `execApprovals.approvers` 下重复 ID。 - 渠道投递会在聊天中显示命令文本；仅在受信任的群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。执行审批默认在 30 分钟后过期。 + 渠道投递会在聊天中显示命令文本；仅在受信任的群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。Exec 审批默认会在 30 分钟后过期。 - 内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 通过插件审批解析；其他 ID 会先通过执行审批解析。 + 内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过 exec 审批解析。 - 参见 [执行审批](/zh-CN/tools/exec-approvals)。 + 请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)。 ## 错误回复控制 -当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以抑制该错误。两个配置键控制此行为： +当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以将其抑制。此行为由两个配置键控制： -| 键 | 值 | 默认值 | 描述 | -| ----------------------------------- | ----------------- | ------- | --------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 | -| `channels.telegram.errorCooldownMs` | 数字（ms） | `60000` | 向同一聊天发送错误回复的最小间隔。防止故障期间出现错误刷屏。 | +| 键 | 值 | 默认值 | 描述 | +| ----------------------------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 | +| `channels.telegram.errorCooldownMs` | 数字（ms） | `60000` | 对同一聊天发送错误回复的最短间隔。可防止故障期间出现错误刷屏。 | -支持按账号、按群组和按话题覆盖（与其他 Telegram 配置键的继承方式相同）。 +支持按账号、按群组和按话题覆盖（继承方式与其他 Telegram 配置键相同）。 ```json5 { @@ -831,52 +831,53 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## 故障排除 - + - - 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。 - - BotFather：`/setprivacy` -> 禁用 - - 然后从群组中移除机器人并重新添加 - - 当配置期望未提及的群组消息时，`openclaw channels status` 会发出警告。 - - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法进行成员探测。 + - 如果 `requireMention=false`，Telegram 隐私模式必须允许完全可见。 + - BotFather：`/setprivacy` -> Disable + - 然后将机器人从群组移除并重新添加 + - 当配置预期接收未提及机器人的群组消息时，`openclaw channels status` 会发出警告。 + - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法探测成员资格。 - 快速会话测试：`/activation always`。 - - 当 `channels.telegram.groups` 存在时，群组必须列出（或包含 `"*"`） - - 验证机器人在群组中的成员身份 - - 查看日志：`openclaw logs --follow` 以了解跳过原因 + - 当 `channels.telegram.groups` 存在时，群组必须被列出（或包含 `"*"`） + - 验证机器人在群组中的成员资格 + - 查看日志：使用 `openclaw logs --follow` 查看跳过原因 - 授权你的发送者身份（配对和/或数字 `allowFrom`） - - 即使群组策略为 `open`，命令授权仍然适用 - - 带有 `BOT_COMMANDS_TOO_MUCH` 的 `setMyCommands failed` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单 - - 带有网络/fetch 错误的 `setMyCommands failed` 通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性问题 + - 即使群组策略是 `open`，命令授权仍然适用 + - `setMyCommands failed` 携带 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单 + - `setMyCommands failed` 携带网络/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 调用。 - - 如果轮询启动期间 `deleteWebhook` 因临时网络错误失败，OpenClaw 会检查 `getWebhookInfo`；当 Telegram 报告空 webhook URL 时，轮询会继续，因为清理已经满足。 + - `getMe returned 401` 是配置的机器人 token 的 Telegram 身份验证失败。 + - 在 BotFather 中重新复制或重新生成机器人 token，然后为默认账号更新 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts..botToken` 或 `TELEGRAM_BOT_TOKEN`。 + - 启动期间的 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“没有 webhook 存在”只会把同一个错误 token 失败延后到后续 API 调用。 + - 如果 `deleteWebhook` 在轮询启动期间因临时网络错误而失败，OpenClaw 会检查 `getWebhookInfo`；当 Telegram 报告 webhook URL 为空时，轮询会继续，因为清理已满足。 - - 如果 AbortSignal 类型不匹配，Node 22+ 加自定义 fetch/代理可能会触发立即中止行为。 - - 某些主机会先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站可能导致间歇性 Telegram API 故障。 - - 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复网络错误进行重试。 - - 如果日志包含 `Polling stall detected`，默认情况下，OpenClaw 会在 120 秒内没有完成长轮询活性检查后重启轮询并重建 Telegram 传输。 - - 仅当长时间运行的 `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 传输。 + - Node 22+ 与自定义 fetch/proxy 组合时，如果 AbortSignal 类型不匹配，可能触发立即中止行为。 + - 某些主机会优先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站可能导致 Telegram API 间歇性失败。 + - 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复网络错误重试。 + - 如果日志包含 `Polling stall detected`，默认情况下，在 120 秒没有完成长轮询活性后，OpenClaw 会重启轮询并重建 Telegram 传输。 + - 当正在运行的轮询账号在启动宽限期后尚未完成 `getUpdates`，或其最近一次成功的轮询传输活动已陈旧时，`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 传输。 - 在直接出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用： ```yaml @@ -886,7 +887,7 @@ channels: ``` - Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）和 `dnsResultOrder=ipv4first`。 - - 如果你的主机是 WSL2，或明确在仅 IPv4 行为下工作得更好，请强制选择地址族： + - 如果你的主机是 WSL2，或者明确更适合仅 IPv4 的行为，请强制选择地址族： ```yaml channels: @@ -895,7 +896,7 @@ 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: @@ -904,21 +905,20 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - 每个账户也可以在 - `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` 单独启用同一选项。 - - 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544 - 基准测试范围。 + - 同一选择也可按账号在 + `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` 配置。 + - 如果你的代理将 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 @@ -934,15 +934,15 @@ dig +short api.telegram.org AAAA 主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。 - + -- 启动/凭证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝） +- 启动/认证：`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` - 流式传输：`streaming`（预览）、`streaming.preview.toolProgress`、`blockStreaming` -- 格式化/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix` +- 格式/交付：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix` - 媒体/网络：`mediaMaxMb`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy` - 自定义 API 根地址：`apiRoot`（仅 Bot API 根地址；不要包含 `/bot`） - webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost` @@ -954,14 +954,14 @@ dig +short api.telegram.org AAAA -多账户优先级：配置了两个或更多账户 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 网关配对。 群组和话题允许列表行为。