From bdb5d0e24f43de561c3e668d36a90c2ae9e00a99 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 1 May 2026 23:05:10 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/access-groups.md | 189 +++++++++++ docs/zh-CN/channels/discord.md | 476 +++++++++++++-------------- docs/zh-CN/channels/groups.md | 161 ++++----- docs/zh-CN/channels/pairing.md | 103 +++--- 4 files changed, 561 insertions(+), 368 deletions(-) create mode 100644 docs/zh-CN/channels/access-groups.md diff --git a/docs/zh-CN/channels/access-groups.md b/docs/zh-CN/channels/access-groups.md new file mode 100644 index 000000000..45495f2b0 --- /dev/null +++ b/docs/zh-CN/channels/access-groups.md @@ -0,0 +1,189 @@ +--- +read_when: + - 在多个消息渠道中配置相同的允许列表 + - 共享私信和群组发送者访问规则 + - 审查消息渠道访问控制 +summary: 用于消息渠道的可复用发送者允许名单 +title: 访问组 +x-i18n: + generated_at: "2026-05-01T23:03:17Z" + model: gpt-5.5 + provider: openai + source_hash: fc7bc1d4fb80e5c5d4e72b190d49821aa93ced575eafcf89864ac800e8558f94 + source_path: channels/access-groups.md + workflow: 16 +--- + +访问组是你定义一次、并通过 `accessGroup:` 从渠道允许列表引用的具名发送者列表。 + +当同一批人应被允许使用多个消息渠道，或一个受信任集合应同时应用于私信和群组发送者授权时，请使用它们。 + +访问组本身不会授予访问权限。只有当允许列表字段引用某个组时，该组才有意义。 + +## 静态消息发送者组 + +静态发送者组使用 `type: "message.senders"`。 + +```json5 +{ + accessGroups: { + operators: { + type: "message.senders", + members: { + "*": ["global-owner-id"], + discord: ["discord:123456789012345678"], + telegram: ["987654321"], + whatsapp: ["+15551234567"], + }, + }, + }, +} +``` + +成员列表按消息渠道 ID 作为键： + +| 键 | 含义 | +| ---------- | ----------------------------------------------------------------------- | +| `"*"` | 对引用该组的每个消息渠道检查的共享条目。 | +| `discord` | 仅用于 Discord 允许列表匹配时检查的条目。 | +| `telegram` | 仅用于 Telegram 允许列表匹配时检查的条目。 | +| `whatsapp` | 仅用于 WhatsApp 允许列表匹配时检查的条目。 | + +条目会使用目标渠道的常规 `allowFrom` 规则进行匹配。OpenClaw 不会在渠道之间转换发送者 ID。如果 Alice 同时有 Telegram ID 和 Discord ID，请将两个 ID 都列在相应的键下。 + +## 从允许列表引用组 + +在消息渠道路径支持发送者允许列表的任何位置，都可以使用 `accessGroup:` 引用组。 + +私信允许列表示例： + +```json5 +{ + accessGroups: { + operators: { + type: "message.senders", + members: { + discord: ["discord:123456789012345678"], + telegram: ["987654321"], + }, + }, + }, + channels: { + discord: { + dmPolicy: "allowlist", + allowFrom: ["accessGroup:operators"], + }, + telegram: { + dmPolicy: "allowlist", + allowFrom: ["accessGroup:operators"], + }, + }, +} +``` + +群组发送者允许列表示例： + +```json5 +{ + accessGroups: { + oncall: { + type: "message.senders", + members: { + whatsapp: ["+15551234567"], + googlechat: ["users/1234567890"], + }, + }, + }, + channels: { + whatsapp: { + groupPolicy: "allowlist", + groupAllowFrom: ["accessGroup:oncall"], + }, + googlechat: { + spaces: { + "spaces/AAA": { + users: ["accessGroup:oncall"], + }, + }, + }, + }, +} +``` + +你可以混合使用组和直接条目： + +```json5 +{ + channels: { + discord: { + dmPolicy: "allowlist", + allowFrom: ["accessGroup:operators", "discord:123456789012345678"], + }, + }, +} +``` + +## 支持的消息渠道路径 + +访问组可用于共享的消息渠道授权路径，包括： + +- 私信发送者允许列表，例如 `channels..allowFrom` +- 群组发送者允许列表，例如 `channels..groupAllowFrom` +- 使用相同发送者匹配规则的渠道特定按房间发送者允许列表 +- 复用消息渠道发送者允许列表的命令授权路径 + +渠道支持取决于该渠道是否通过共享的 OpenClaw 发送者授权辅助工具接入。当前内置支持包括 Discord、Google Chat、Nostr、WhatsApp、Zalo 和 Zalo Personal。静态 `message.senders` 组设计为与渠道无关，因此新的消息渠道应通过使用共享的插件 SDK 辅助工具来支持它们，而不是自定义允许列表展开。 + +## Discord 渠道受众 + +Discord 还支持动态访问组类型： + +```json5 +{ + accessGroups: { + maintainers: { + type: "discord.channelAudience", + guildId: "1456350064065904867", + channelId: "1456744319972282449", + membership: "canViewChannel", + }, + }, + channels: { + discord: { + dmPolicy: "allowlist", + allowFrom: ["accessGroup:maintainers"], + }, + }, +} +``` + +`discord.channelAudience` 表示“允许当前可以查看此服务器渠道的 Discord 私信发送者”。OpenClaw 会在授权时通过 Discord 解析发送者，并应用 Discord `ViewChannel` 权限规则。 + +当某个 Discord 渠道已经是某个团队的事实来源时使用此功能，例如 `#maintainers` 或 `#on-call`。 + +要求和失败行为： + +- 机器人需要能访问该服务器和渠道。 +- 机器人需要 Discord 开发者门户中的 **Server Members Intent**。 +- 当 Discord 返回 `Missing Access`、无法将发送者解析为服务器成员，或渠道属于另一个服务器时，访问组会失败关闭。 + +更多 Discord 特定示例：[Discord 访问控制](/zh-CN/channels/discord#access-control-and-routing) + +## 安全说明 + +- 访问组是允许列表别名，不是角色。它们本身不会创建所有者、批准配对请求或授予工具权限。 +- `dmPolicy: "open"` 仍然要求有效的私信允许列表中包含 `"*"`。引用访问组不等同于公共访问。 +- 缺失的组名会失败关闭。如果 `allowFrom` 包含 `accessGroup:operators` 而 `accessGroups.operators` 不存在，则该条目不会授权任何人。 +- 保持渠道 ID 稳定。当渠道同时支持数字/用户 ID 和显示名称时，优先使用数字/用户 ID。 + +## 故障排除 + +如果某个发送者本应匹配但被阻止： + +1. 确认允许列表字段包含精确的 `accessGroup:` 引用。 +2. 确认 `accessGroups..type` 正确。 +3. 确认发送者 ID 列在匹配的渠道键下，或列在 `"*"` 下。 +4. 确认该条目使用该渠道的常规允许列表语法。 +5. 对于 Discord 渠道受众，确认机器人可以看到服务器渠道，并且已启用 Server Members Intent。 + +编辑访问控制配置后运行 `openclaw doctor`。它会在运行时之前捕获许多无效的允许列表和策略组合。 diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index fbf1732c8..f9217be2f 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -1,22 +1,22 @@ --- read_when: - 开发 Discord 渠道功能 -summary: Discord 机器人支持 Status、功能和配置 +summary: Discord 机器人支持状态、能力和配置 title: Discord x-i18n: - generated_at: "2026-05-01T22:59:37Z" + generated_at: "2026-05-01T23:03:03Z" model: gpt-5.5 provider: openai - source_hash: 6bd33cbe350f4cee90e63334797675d29d2d62efdce9a3eecc29666e04d9dedb + source_hash: 0d87dfc4cbebb2cbf89d92dc2eb55903ada60a390f92c1e1817d67baada87669 source_path: channels/discord.md workflow: 16 --- -可通过官方 Discord Gateway 网关用于私信和服务器渠道。 +可通过官方 Discord Gateway 网关使用私信和服务器频道。 - Discord 私信默认进入配对模式。 + Discord 私信默认使用配对模式。 原生命令行为和命令目录。 @@ -28,45 +28,45 @@ x-i18n: ## 快速设置 -你需要创建一个带 bot 的新应用，将 bot 添加到你的服务器，并将它配对到 OpenClaw。我们建议将你的 bot 添加到你自己的私有服务器。如果你还没有服务器，请[先创建一个](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** 页面上，向下滚动到 **Privileged Gateway Intents** 并启用： - **Message Content Intent**（必需） - - **Server Members Intent**（推荐；角色允许列表和名称到 ID 匹配需要） - - **Presence Intent**（可选；仅在需要在线状态更新时才需要） + - **Server Members Intent**（推荐；角色允许列表和名称到 ID 匹配需要它） + - **Presence Intent**（可选；仅在需要在线状态更新时需要） - - 在 **Bot** 页面上向上滚动并点击 **Reset Token**。 + + 在 **Bot** 页面向上滚动并点击 **Reset Token**。 - 虽然名称如此，但这会生成你的第一个 token，并没有任何内容被“重置”。 + 尽管名称如此，这会生成你的第一个令牌，并没有真正“重置”任何内容。 - 复制 token 并保存到某处。这是你的 **Bot Token**，稍后会用到。 + 复制令牌并保存到某处。这是你的 **Bot Token**，稍后会用到。 - - 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用来将 bot 添加到你的服务器。 + + 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用于将机器人添加到你的服务器。 向下滚动到 **OAuth2 URL Generator** 并启用： - `bot` - `applications.commands` - 下方会出现 **Bot Permissions** 区域。至少启用： + 下方会出现 **Bot Permissions** 区块。至少启用： **General Permissions** - View Channels @@ -77,15 +77,15 @@ x-i18n: - Attach Files - Add Reactions（可选） - 这是普通文本频道的基线权限集。如果你计划在 Discord 线程中发帖，包括会创建或继续线程的论坛或媒体频道工作流，也要启用 **Send Messages in Threads**。 - 复制底部生成的 URL，粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该能在 Discord 服务器中看到你的 bot。 + 这是普通文本频道的基准权限集合。如果你计划在 Discord 线程中发帖，包括会创建或继续线程的论坛或媒体频道工作流，还要启用 **Send Messages in Threads**。 + 复制底部生成的 URL，粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该能在 Discord 服务器中看到你的机器人。 - 回到 Discord 应用中，你需要启用 Developer Mode，才能复制内部 ID。 + 回到 Discord 应用，你需要启用 Developer Mode，才能复制内部 ID。 - 1. 点击 **User Settings**（头像旁的齿轮图标）→ **Advanced** → 打开 **Developer Mode** + 1. 点击 **User Settings**（头像旁边的齿轮图标）→ **Advanced** → 打开 **Developer Mode** 2. 右键点击侧边栏中的**服务器图标** → **Copy Server ID** 3. 右键点击你**自己的头像** → **Copy User ID** @@ -94,14 +94,14 @@ x-i18n: - 为了让配对正常工作，Discord 需要允许你的 bot 给你发私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。 + 要让配对正常工作，Discord 需要允许你的机器人向你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。 - 这会让服务器成员（包括 bot）能够向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持启用。如果你只计划使用服务器渠道，可以在配对后禁用私信。 + 这允许服务器成员（包括机器人）向你发送私信。如果你想通过 OpenClaw 使用 Discord 私信，请保持此项启用。如果你只计划使用服务器频道，可以在配对后禁用私信。 - - 你的 Discord bot token 是密钥（类似密码）。在给智能体发消息之前，在运行 OpenClaw 的机器上设置它。 + + 你的 Discord 机器人令牌是机密信息（类似密码）。在给智能体发消息之前，先在运行 OpenClaw 的机器上设置它。 ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -120,9 +120,9 @@ openclaw config patch --file ./discord.patch.json5 openclaw gateway ``` - 如果 OpenClaw 已经作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或停止并重新启动 `openclaw gateway run` 进程。 - 对于托管服务安装，请在存在 `DISCORD_BOT_TOKEN` 的 shell 中运行 `openclaw gateway install`，或将该变量存储在 `~/.openclaw/.env` 中，以便服务重启后能够解析 env SecretRef。 - 如果你的主机被 Discord 的启动应用查询阻止或限速，请从 Developer Portal 设置 Discord 应用/客户端 ID，这样启动时可以跳过该 REST 调用。默认账号使用 `channels.discord.applicationId`；运行多个 Discord bot 时使用 `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`。 @@ -130,12 +130,12 @@ openclaw gateway - 在任何现有渠道（例如 Telegram）中与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / config 标签页。 + 在任何现有渠道（例如 Telegram）与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置标签页。 - > “我已经在配置中设置了 Discord bot token。请用 User ID `` 和 Server ID `` 完成 Discord 设置。” + > “我已经在配置中设置了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” - - 如果你更喜欢基于文件的配置，请设置： + + 如果你偏好基于文件的配置，请设置： ```json5 { @@ -152,15 +152,15 @@ openclaw gateway } ``` - 默认账号的 env 回退： + 默认账户的 env 回退： ```bash DISCORD_BOT_TOKEN=... ``` - 对于脚本化或远程设置，请使用 `openclaw config patch --file ./discord.patch.json5 --dry-run` 写入相同的 JSON5 块，然后去掉 `--dry-run` 重新运行。支持明文 `token` 值。对于 `channels.discord.token`，也支持跨 env/file/exec 提供商的 SecretRef 值。参见[密钥管理](/zh-CN/gateway/secrets)。 + 对于脚本化或远程设置，请使用 `openclaw config patch --file ./discord.patch.json5 --dry-run` 写入同一个 JSON5 区块，然后去掉 `--dry-run` 重新运行。支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商的 SecretRef 值。请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 - 对于多个 Discord bot，请将每个 bot token 和应用 ID 放在各自账号下。顶层 `channels.discord.applicationId` 会被账号继承，因此只有在每个账号都应使用同一个应用 ID 时，才在那里设置它。 + 对于多个 Discord 机器人，请将每个机器人令牌和 application ID 保存在它自己的账户下。顶层 `channels.discord.applicationId` 会被账户继承，因此只有在每个账户都应使用同一个 application ID 时，才在那里设置它。 ```json5 { @@ -188,13 +188,13 @@ DISCORD_BOT_TOKEN=... - 等待 Gateway 网关运行，然后在 Discord 中给你的 bot 发送私信。它会回复一个配对代码。 + 等到 Gateway 网关运行后，在 Discord 中给你的机器人发送私信。它会返回一个配对码。 - 将配对代码通过现有渠道发送给你的智能体： + 在你的现有渠道中将配对码发送给智能体： - > “批准这个 Discord 配对代码：``” + > “批准此 Discord 配对码：``” @@ -206,26 +206,26 @@ openclaw pairing approve discord - 配对代码会在 1 小时后过期。 + 配对码会在 1 小时后过期。 - 现在你应该可以通过 Discord 私信与你的智能体聊天。 + 现在你应该可以通过私信在 Discord 中与你的智能体聊天。 -Token 解析是账号感知的。配置中的 token 值优先于 env 回退。`DISCORD_BOT_TOKEN` 仅用于默认账号。 -如果两个已启用的 Discord 账号解析到同一个 bot token，OpenClaw 只会为该 token 启动一个 Gateway 网关监控器。来自配置的 token 优先于默认 env 回退；否则第一个已启用账号胜出，重复账号会报告为已禁用。 -对于高级出站调用（消息工具/渠道操作），显式的逐调用 `token` 会用于该调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账号策略/重试设置仍来自活动运行时快照中选定的账号。 +令牌解析会感知账户。配置令牌值优先于 env 回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 +如果两个已启用的 Discord 账户解析到同一个机器人令牌，OpenClaw 只会为该令牌启动一个 Gateway 网关监视器。来自配置的令牌优先于默认 env 回退；否则第一个已启用的账户获胜，重复账户会被报告为已禁用。 +对于高级出站调用（消息工具/渠道操作），显式的每次调用 `token` 会用于该调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍来自活动运行时快照中选定的账户。 ## 推荐：设置服务器工作区 -私信正常工作后，你可以将 Discord 服务器设置为完整工作区，其中每个渠道都有自己的智能体会话和上下文。对于只有你和你的 bot 的私有服务器，建议这样做。 +私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个频道都有自己的智能体会话和上下文。对于只有你和你的机器人的私有服务器，建议这样做。 - 这会让你的智能体能够在你服务器上的任何渠道中响应，而不仅是私信。 + 这会允许你的智能体在服务器上的任何频道中响应，而不仅是私信。 @@ -254,14 +254,14 @@ Token 解析是账号感知的。配置中的 token 值优先于 env 回退。`D - - 默认情况下，你的智能体只会在服务器渠道中被 @mentioned 时响应。对于私有服务器，你可能希望它响应每条消息。 + + 默认情况下，只有在服务器频道中被 @mentioned 时，你的智能体才会响应。对于私有服务器，你可能希望它响应每条消息。 - 在服务器渠道中，普通助手最终回复默认保持私有。可见的 Discord 输出必须使用 `message` 工具显式发送，因此智能体可以默认旁听，只在判断渠道回复有用时才发帖。 + 在服务器频道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须用 `message` 工具显式发送，因此智能体默认可以潜伏，只在判断频道回复有用时才发帖。 - > “允许我的智能体在这个服务器上响应，而不必被 @mentioned” + > “允许我的智能体在这个服务器上响应，而无需被 @mentioned” 在你的服务器配置中设置 `requireMention: false`： @@ -280,47 +280,47 @@ Token 解析是账号感知的。配置中的 token 值优先于 env 回退。`D } ``` - 要为群组/渠道房间恢复旧版自动最终回复，请设置 `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` 中，并按需使用记忆工具访问。 + 如果你需要在每个频道中共享上下文，请将稳定指令放入 `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:`）。 +- 公会渠道会隔离为会话键（`agent::discord:channel:`）。 - 群组私信默认会被忽略（`channels.discord.dm.groupEnabled=false`）。 -- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 到路由后的对话会话。 -- 面向 Discord 的纯文本 cron/heartbeat 公告投递会使用一次最终的、智能体可见的回答。媒体和结构化组件载荷在智能体发出多个可投递载荷时仍会保持多消息。 +- 原生命令斜杠命令会在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 指向路由后的对话会话。 +- 面向 Discord 的纯文本 cron/heartbeat 公告投递只使用一次最终的助手可见答案。当智能体发出多个可投递 payload 时，媒体和结构化组件 payload 仍会以多消息形式发送。 -## 论坛频道 +## 论坛渠道 -Discord 论坛和媒体频道只接受线程帖子。OpenClaw 支持两种创建方式： +Discord 论坛和媒体渠道只接受帖子线程。OpenClaw 支持两种创建方式： -- 向论坛父级（`channel:`）发送消息以自动创建线程。线程标题使用你的消息中第一行非空内容。 -- 使用 `openclaw message thread create` 直接创建线程。不要为论坛频道传入 `--message-id`。 +- 向论坛父级（`channel:`）发送消息以自动创建线程。线程标题使用你消息中的第一行非空内容。 +- 使用 `openclaw message thread create` 直接创建线程。不要为论坛渠道传入 `--message-id`。 示例：发送到论坛父级以创建线程 @@ -336,11 +336,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` 载荷的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 +OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 `components` payload 的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有 Discord `replyToMode` 设置。 支持的块： @@ -348,11 +348,11 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - 操作行最多允许 5 个按钮或一个选择菜单 - 选择类型：`string`、`user`、`role`、`mentionable`、`channel` -默认情况下，组件只能使用一次。设置 `components.reusable=true` 可允许按钮、选择控件和表单在过期前被多次使用。 +默认情况下，组件只能使用一次。设置 `components.reusable=true` 可允许按钮、选择菜单和表单在过期前多次使用。 -要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 +若要限制谁能点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及一个提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，且只有调用用户可以使用它。 +`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型、兼容运行时下拉菜单以及提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，且只有调用用户可以使用。 文件附件： @@ -362,7 +362,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 模态表单： -- 添加最多包含 5 个字段的 `components.modal` +- 添加 `components.modal`，最多包含 5 个字段 - 字段类型：`text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` - OpenClaw 会自动添加触发按钮 @@ -420,41 +420,41 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` -## 访问控制和路由 +## 访问控制与路由 - `channels.discord.dmPolicy` 控制私信访问。`channels.discord.allowFrom` 是规范私信允许列表。 + `channels.discord.dmPolicy` 控制私信访问。`channels.discord.allowFrom` 是规范的私信允许列表。 - `pairing`（默认） - `allowlist` - `open`（要求 `channels.discord.allowFrom` 包含 `"*"`） - `disabled` - 如果私信策略不是开放的，未知用户会被阻止（或在 `pairing` 模式下被提示配对）。 + 如果私信策略不是开放的，未知用户会被阻止（或在 `pairing` 模式下提示配对）。 多账号优先级： - `channels.discord.accounts.default.allowFrom` 仅适用于 `default` 账号。 - 对于单个账号，`allowFrom` 优先于旧版 `dm.allowFrom`。 - - 当命名账号自己的 `allowFrom` 和旧版 `dm.allowFrom` 未设置时，它们会继承 `channels.discord.allowFrom`。 + - 当命名账号自己的 `allowFrom` 和旧版 `dm.allowFrom` 未设置时，会继承 `channels.discord.allowFrom`。 - 命名账号不会继承 `channels.discord.accounts.default.allowFrom`。 - 旧版 `channels.discord.dm.policy` 和 `channels.discord.dm.allowFrom` 仍会为兼容性读取。`openclaw doctor --fix` 会在不改变访问权限的情况下将它们迁移到 `dmPolicy` 和 `allowFrom`。 + 旧版 `channels.discord.dm.policy` 和 `channels.discord.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的前提下，将它们迁移到 `dmPolicy` 和 `allowFrom`。 用于投递的私信目标格式： - `user:` - `<@id>` 提及 - 当频道默认值处于活动状态时，裸数字 ID 通常会解析为频道 ID，但为兼容性起见，账号有效私信 `allowFrom` 中列出的 ID 会被视为用户私信目标。 + 当渠道默认值处于活动状态时，裸数字 ID 通常会解析为渠道 ID，但账号有效私信 `allowFrom` 中列出的 ID 会被视为用户私信目标以保持兼容。 Discord 私信可以在 `channels.discord.allowFrom` 中使用动态 `accessGroup:` 条目。 - 访问组名称在各消息渠道之间共享。对于成员以每个渠道正常 `allowFrom` 语法表示的静态组，请使用 `type: "message.senders"`；当 Discord 频道当前的 `ViewChannel` 受众应动态定义成员资格时，请使用 `type: "discord.channelAudience"`。 + 访问组名称在消息渠道之间共享。对于成员以每个渠道正常 `allowFrom` 语法表示的静态组，请使用 `type: "message.senders"`；当 Discord 渠道当前的 `ViewChannel` 受众应动态定义成员资格时，请使用 `type: "discord.channelAudience"`。共享访问组行为记录在这里：[访问组](/zh-CN/channels/access-groups)。 ```json5 { @@ -477,9 +477,9 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - Discord 文本频道没有单独的成员列表。`type: "discord.channelAudience"` 将成员资格建模为：私信发送者是已配置服务器的成员，并且在应用角色和频道覆盖后，当前对已配置频道具有有效的 `ViewChannel` 权限。 + Discord 文本渠道没有单独的成员列表。`type: "discord.channelAudience"` 将成员资格建模为：私信发送者是已配置公会的成员，并且在应用角色和渠道覆盖后，当前对已配置渠道拥有有效的 `ViewChannel` 权限。 - 示例：允许任何能看到 `#maintainers` 的人向 bot 发送私信，同时对其他所有人关闭私信。 + 示例：允许任何能看到 `#maintainers` 的人向机器人发送私信，同时对其他所有人关闭私信。 ```json5 { @@ -520,29 +520,29 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 查询失败时默认关闭。如果 Discord 返回 `Missing Access`、成员查询失败，或频道属于不同服务器，则私信发送者会被视为未授权。 + 查询失败时默认关闭。如果 Discord 返回 `Missing Access`、成员查询失败，或渠道属于不同公会，则私信发送者会被视为未授权。 - 使用频道受众访问组时，请在 Discord Developer Portal 中为 bot 启用 **Server Members Intent**。私信不包含服务器成员状态，因此 OpenClaw 会在授权时通过 Discord REST 解析成员。 + 使用渠道受众访问组时，请在 Discord Developer Portal 中为机器人启用 **Server Members Intent**。私信不包含公会成员状态，因此 OpenClaw 会在授权时通过 Discord REST 解析成员。 - 服务器处理由 `channels.discord.groupPolicy` 控制： + 公会处理由 `channels.discord.groupPolicy` 控制： - `open` - `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,33 +568,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`。 - 服务器消息默认受提及门控控制。 + 公会消息默认由提及门控。 提及检测包括： - - 显式 bot 提及 - - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 支持场景中的隐式回复 bot 行为 + - 显式提及机器人 + - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） + - 支持场景中的隐式回复机器人行为 - `requireMention` 按服务器/频道配置（`channels.discord.guilds...`）。 - `ignoreOtherMentions` 可选地丢弃提及其他用户/角色但未提及 bot 的消息（不包括 @everyone/@here）。 + `requireMention` 按公会/渠道配置（`channels.discord.guilds...`）。 + `ignoreOtherMentions` 可选择丢弃提及其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 群组私信： - 默认：忽略（`dm.groupEnabled=false`） - - 可通过 `dm.groupChannels`（频道 ID 或 slug）配置可选允许列表 + - 可选通过 `dm.groupChannels` 使用允许列表（渠道 ID 或 slug） ### 基于角色的智能体路由 -使用 `bindings[].match.roles` 根据角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并在 peer 或 parent-peer 绑定之后、仅服务器绑定之前求值。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 +使用 `bindings[].match.roles` 按角色 ID 将 Discord 公会成员路由到不同智能体。基于角色的绑定只接受角色 ID，并在对等或父对等绑定之后、公会限定绑定之前求值。如果绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），所有已配置字段都必须匹配。 ```json5 { @@ -618,15 +618,15 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` -## 原生命令和命令认证 +## 原生命令与命令认证 -- `commands.native` 默认值为 `"auto"`，并且对 Discord 启用。 +- `commands.native` 默认为 `"auto"`，并对 Discord 启用。 - 按渠道覆盖：`channels.discord.commands.native`。 -- `commands.native=false` 会显式清除之前注册的 Discord 原生命令。 +- `commands.native=false` 会显式清除先前注册的 Discord 原生命令。 - 原生命令认证使用与普通消息处理相同的 Discord 允许列表/策略。 -- 命令可能仍会在 Discord UI 中对未授权用户可见；执行时仍会强制应用 OpenClaw 认证，并返回“未授权”。 +- 对于未授权用户，命令可能仍会在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 认证并返回“未授权”。 -请参阅[斜杠命令](/zh-CN/tools/slash-commands)了解命令目录和行为。 +请参阅[斜杠命令](/zh-CN/tools/slash-commands)，了解命令目录和行为。 默认斜杠命令设置： @@ -648,20 +648,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 { @@ -678,20 +676,20 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - - `partial` 会在令牌到达时编辑单条预览消息。 + - `partial` 会随着令牌到达编辑单条预览消息。 - `block` 会发出草稿大小的分块（使用 `draftChunk` 调整大小和断点，并限制在 `textChunkLimit` 内）。 - 媒体、错误和显式回复的最终消息会取消待处理的预览编辑。 - `streaming.preview.toolProgress`（默认 `true`）控制工具/进度更新是否复用预览消息。 - 预览流式传输仅支持文本；媒体回复会回退到正常投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 + 预览流式传输仅支持文本；媒体回复会回退到常规投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。 - + 服务器历史上下文： - - `channels.discord.historyLimit` 默认值为 `20` - - 回退项：`messages.groupChat.historyLimit` + - `channels.discord.historyLimit` 默认 `20` + - 回退：`messages.groupChat.historyLimit` - `0` 会禁用 私信历史控制： @@ -699,28 +697,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` 选择作为仅模型回退；话题本地的 `/model` 选择仍优先，并且不会复制父转录历史，除非启用了转录继承。 + - `channels.discord.thread.inheritParent`（默认 `false`）让新的自动话题选择从父转录播种。按账号的覆盖位于 `channels.discord.accounts..thread.inheritParent` 下。 - 消息工具反应可以解析 `user:` 私信目标。 - `guilds..channels..requireMention: false` 会在回复阶段激活回退期间保留。 - 渠道主题会作为**不受信任**的上下文注入。允许列表用于限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 + 渠道主题会作为**不受信任**的上下文注入。允许列表限制谁可以触发智能体，而不是完整的补充上下文删减边界。 - - Discord 可以把线程绑定到会话目标，使该线程中的后续消息继续路由到同一个会话（包括子智能体会话）。 + + Discord 可以将一个话题绑定到会话目标，让该话题中的后续消息继续路由到同一个会话（包括子智能体会话）。 命令： - - `/focus ` 将当前/新线程绑定到子智能体/会话目标 - - `/unfocus` 移除当前线程绑定 + - `/focus ` 将当前/新话题绑定到子智能体/会话目标 + - `/unfocus` 移除当前话题绑定 - `/agents` 显示活动运行和绑定状态 - - `/session idle ` 查看/更新已聚焦绑定的不活动自动取消聚焦 - - `/session max-age ` 查看/更新已聚焦绑定的硬性最大年龄 + - `/session idle ` 查看/更新焦点绑定的不活动自动取消焦点时间 + - `/session max-age ` 查看/更新焦点绑定的硬性最长寿命 配置： @@ -746,24 +744,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 工作区，请配置面向 Discord 对话的顶级类型化 ACP 绑定。 + 对于稳定的“始终在线”ACP 工作区，请配置面向 Discord 对话的顶层类型化 ACP 绑定。 配置路径： - - `bindings[]`，包含 `type: "acp"` 和 `match.channel: "discord"` + - `bindings[]`，带有 `type: "acp"` 和 `match.channel: "discord"` 示例： @@ -813,18 +811,18 @@ 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`（默认） @@ -845,15 +843,15 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `messages.ackReaction` - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） - 备注： + 说明： - Discord 接受 Unicode 表情符号或自定义表情符号名称。 - - 使用 `""` 可为某个渠道或账号禁用该反应。 + - 使用 `""` 可对某个渠道或账号禁用该反应。 - 默认启用由渠道发起的配置写入。 + 渠道发起的配置写入默认启用。 这会影响 `/config set|unset` 流程（当命令功能启用时）。 @@ -872,7 +870,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - 通过 HTTP(S) 代理和 `channels.discord.proxy` 路由 Discord 网关 WebSocket 流量以及启动时 REST 查找（应用 ID + 允许列表解析）。 + 通过 HTTP(S) 代理使用 `channels.discord.proxy` 路由 Discord 网关 WebSocket 流量和启动 REST 查询（应用 ID + 允许列表解析）。 ```json5 { @@ -903,7 +901,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - 启用 PluralKit 解析，将代理消息映射到系统成员身份： + 启用 PluralKit 解析，以将代理消息映射到系统成员身份： ```json5 { @@ -918,19 +916,19 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 备注： + 说明： - 允许列表可以使用 `pk:` - - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名称 - - 查找使用原始消息 ID，并受时间窗口约束 - - 如果查找失败，代理消息会被视为机器人消息并丢弃，除非 `allowBots=true` + - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，成员显示名称才会按名称/slug 匹配 + - 查询使用原始消息 ID，并受时间窗口限制 + - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非 `allowBots=true` - 当你设置 Status 或活动字段，或启用自动在线状态时，会应用在线状态更新。 + 当你设置状态或活动字段，或启用自动在线状态时，会应用在线状态更新。 - 仅 Status 示例： + 仅状态示例： ```json5 { @@ -955,7 +953,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 流式传输示例： + 流式活动示例： ```json5 { @@ -972,10 +970,10 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 活动类型映射： - 0：正在玩 - - 1：流式传输（需要 `activityUrl`） + - 1：正在直播（需要 `activityUrl`） - 2：正在听 - 3：正在观看 - - 4：自定义（使用活动文本作为状态状态；表情符号可选） + - 4：自定义（使用活动文本作为状态；表情符号可选） - 5：正在竞赛 自动在线状态示例（运行时健康信号）： @@ -995,7 +993,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 自动在线状态会将运行时可用性映射到 Discord Status：healthy => 在线，degraded 或 unknown => 空闲，exhausted 或 unavailable => 请勿打扰。可选文本覆盖项： + 自动在线状态会将运行时可用性映射到 Discord 状态：健康 => 在线，降级或未知 => 空闲，耗尽或不可用 => 请勿打扰。可选文本覆盖： - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -1003,8 +1001,8 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - - Discord 支持在私信中基于按钮处理批准，并且可以选择在来源渠道中发布批准提示。 + + Discord 支持在私信中进行基于按钮的审批处理，也可以选择在发起渠道中发布审批提示。 配置路径： @@ -1013,23 +1011,23 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` - 当 `enabled` 未设置或为 `"auto"`，且至少能从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个批准者时，Discord 会自动启用原生执行批准。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或直接消息 `defaultTo` 推断执行批准者。设置 `enabled: false` 可明确禁用 Discord 作为原生批准客户端。 + 当 `enabled` 未设置或为 `"auto"`，并且至少能从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个审批人时，Discord 会自动启用原生执行审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或直接消息 `defaultTo` 推断执行审批人。设置 `enabled: false` 可显式禁用 Discord 作为原生审批客户端。 - 对于敏感的仅所有者群组命令，例如 `/diagnostics` 和 `/export-trajectory`，OpenClaw 会私下发送批准提示和最终结果。当调用的所有者有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 + 对于敏感的仅所有者群组命令，例如 `/diagnostics` 和 `/export-trajectory`，OpenClaw 会私下发送审批提示和最终结果。当发起调用的所有者有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 - 当 `target` 为 `channel` 或 `both` 时，批准提示会在渠道中可见。只有已解析的批准者可以使用按钮；其他用户会收到临时拒绝。批准提示会包含命令文本，因此只应在可信渠道中启用渠道投递。如果无法从会话键派生渠道 ID，OpenClaw 会回退到私信投递。 + 当 `target` 为 `channel` 或 `both` 时，审批提示会在渠道中可见。只有解析出的审批人可以使用按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此只应在可信渠道中启用渠道投递。如果无法从会话键推导出渠道 ID，OpenClaw 会回退到私信投递。 - Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要增加审批人私信路由和渠道扇出。 + Discord 也会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要增加审批人私信路由和渠道扇出。 当这些按钮存在时，它们就是主要审批 UX；OpenClaw - 只有在工具结果说明聊天审批不可用，或手动审批是唯一路径时， + 只有在工具结果表明聊天审批不可用或手动审批是唯一路径时， 才应包含手动 `/approve` 命令。 如果 Discord 原生审批运行时未激活，OpenClaw 会保持 本地确定性的 `/approve ` 提示可见。如果 - 运行时已激活但原生卡片无法送达任何目标， - OpenClaw 会在同一聊天中发送回退通知，其中包含待处理审批里的精确 `/approve` + 运行时已激活但原生卡片无法投递到任何目标， + OpenClaw 会在同一聊天中发送回退通知，其中包含待审批项的准确 `/approve` 命令。 - Gateway 网关认证和审批解析遵循共享的 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。审批默认在 30 分钟后过期。 + Gateway 网关认证和审批解析遵循共享 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。审批默认在 30 分钟后过期。 参见 [Exec 审批](/zh-CN/tools/exec-approvals)。 @@ -1038,13 +1036,13 @@ 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 或本地文件路径），用于设置定时事件封面图。 @@ -1053,20 +1051,20 @@ Discord 消息操作包括消息、渠道管理、内容管理、在线状态和 默认门控行为： -| 操作组 | 默认 | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -| 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 处理 exec 审批和跨上下文标记。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` 会被忽略。 示例： @@ -1086,20 +1084,20 @@ OpenClaw 使用 Discord components v2 处理 exec 审批和跨上下文标记。 ## 语音 -Discord 有两个不同的语音界面：实时**语音渠道**（连续对话）和**语音消息附件**（波形预览格式）。Gateway 网关两者都支持。 +Discord 有两个不同的语音表面：实时 **语音频道**（连续对话）和 **语音消息附件**（波形预览格式）。Gateway 网关同时支持二者。 -### 语音渠道 +### 语音频道 设置检查清单： 1. 在 Discord Developer Portal 中启用 Message Content Intent。 -2. 使用角色/用户允许列表时启用 Server Members Intent。 -3. 使用 `bot` 和 `applications.commands` 作用域邀请机器人。 -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 命令相同的允许列表和群组策略规则。 +使用 `/vc join|leave|status` 控制会话。该命令使用账号默认智能体，并遵循与其他 Discord 命令相同的允许列表和组策略规则。 ```bash /vc join channel: @@ -1136,39 +1134,39 @@ Discord 有两个不同的语音界面：实时**语音渠道**（连续对话 } ``` -注意： +说明： -- `voice.tts` 仅为语音播放覆盖 `messages.tts`。 -- `voice.model` 仅覆盖用于 Discord 语音渠道回复的 LLM。留空则继承已路由的智能体模型。 +- `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` 可以显式覆盖 voice-state intent 订阅。留空则该 intent 跟随实际语音启用状态。 -- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 加入选项。 +- 单渠道 Discord `systemPrompt` 覆盖会应用于该语音频道的语音转录轮次。 +- 语音转录轮次从 Discord `allowFrom`（或 `dm.allowFrom`）派生 owner 状态；非 owner 说话者无法访问仅 owner 可用的工具（例如 `gateway` 和 `cron`）。 +- 对于纯文本配置，Discord 语音是可选启用的；设置 `channels.discord.voice.enabled=true`（或保留现有的 `channels.discord.voice` 块）即可启用 `/vc` 命令、语音运行时和 `GuildVoiceStates` Gateway 网关 intent。 +- `channels.discord.intents.voiceStates` 可以显式覆盖 voice-state intent 订阅。保持未设置时，该 intent 会跟随有效的语音启用状态。 +- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` join 选项。 - 如果未设置，`@discordjs/voice` 默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 -- `voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试时初始等待 `@discordjs/voice` Ready 的时间。默认值：`30000`。 -- `voice.reconnectGraceMs` 控制 OpenClaw 在销毁已断开的语音会话前，等待其开始重连的时长。默认值：`15000`。 -- OpenClaw 还会监视接收端解密失败，并在短时间窗口内重复失败后，通过离开并重新加入语音渠道来自动恢复。 +- `voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试时初始 `@discordjs/voice` Ready 等待时间。默认值：`30000`。 +- `voice.reconnectGraceMs` 控制 OpenClaw 在销毁已断开的语音会话前，等待其开始重新连接的时长。默认值：`15000`。 +- OpenClaw 还会监视接收解密失败，并在短时间窗口内重复失败后，通过离开并重新加入语音频道自动恢复。 - 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 版本线包含来自 discord.js PR #11449 的上游 padding 修复，该修复关闭了 discord.js issue #11419。 -语音渠道流水线： +语音频道流水线： - Discord PCM 捕获会转换为 WAV 临时文件。 - `tools.media.audio` 处理 STT，例如 `openai/gpt-4o-mini-transcribe`。 -- 转录文本会通过 Discord 入口和路由发送，同时响应 LLM 以语音输出策略运行：隐藏智能体 `tts` 工具并要求返回文本，因为 Discord 语音拥有最终 TTS 播放。 -- 设置后，`voice.model` 仅覆盖此语音渠道轮次的响应 LLM。 -- `voice.tts` 会覆盖合并到 `messages.tts` 上；生成的音频会在已加入的渠道中播放。 +- 转录文本通过 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 会拒绝同一载荷中的文本 + 语音消息）。 -- 接受任意音频格式；OpenClaw 会按需转换为 OGG/Opus。 +- 提供一个 **本地文件路径**（URL 会被拒绝）。 +- 省略文本内容（Discord 会拒绝在同一载荷中同时包含文本和语音消息）。 +- 接受任何音频格式；OpenClaw 会按需转换为 OGG/Opus。 ```bash message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) @@ -1177,10 +1175,10 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## 故障排除 - + - 启用 Message Content Intent - - 当你依赖用户/成员解析时，启用 Server Members Intent + - 依赖用户/成员解析时，启用 Server Members Intent - 更改 intent 后重启 Gateway 网关 @@ -1189,7 +1187,7 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a - 验证 `groupPolicy` - 验证 `channels.discord.guilds` 下的服务器允许列表 - - 如果服务器 `channels` 映射存在，则只允许列出的渠道 + - 如果存在服务器 `channels` 映射，则只允许列出的渠道 - 验证 `requireMention` 行为和提及模式 有用的检查： @@ -1202,10 +1200,10 @@ openclaw logs --follow - + 常见原因： - - `groupPolicy="allowlist"` 没有匹配的服务器/渠道允许列表 + - `groupPolicy="allowlist"` 但没有匹配的服务器/渠道允许列表 - `requireMention` 配置在错误位置（必须位于 `channels.discord.guilds` 或渠道条目下） - 发送者被服务器/渠道 `users` 允许列表阻止 @@ -1218,13 +1216,13 @@ openclaw logs --follow - `Slow listener detected ...` - `stuck session: sessionKey=agent:...:discord:... state=processing ...` - Discord Gateway 网关队列调节项： + 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 { @@ -1245,21 +1243,21 @@ 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` - `channels status --probe` 权限检查只适用于数字渠道 ID。 + `channels status --probe` 权限检查仅适用于数字渠道 ID。 - 如果使用 slug 键，运行时匹配仍可工作，但 probe 无法完整验证权限。 + 如果你使用 slug 键，运行时匹配仍可工作，但 probe 无法完整验证权限。 @@ -1271,23 +1269,23 @@ openclaw logs --follow - + 默认情况下，机器人发送的消息会被忽略。 - 如果设置 `channels.discord.allowBots=true`，请使用严格的提及和允许列表规则以避免循环行为。 - 建议使用 `channels.discord.allowBots="mentions"`，只接受提及该机器人的机器人消息。 + 如果你设置 `channels.discord.allowBots=true`，请使用严格的提及和允许列表规则以避免循环行为。 + 推荐使用 `channels.discord.allowBots="mentions"`，只接受提及该机器人的机器人消息。 - - 保持 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 接收历史进行对比 @@ -1296,15 +1294,15 @@ openclaw logs --follow 主要参考：[配置参考 - Discord](/zh-CN/gateway/config-channels#discord)。 - + - 启动/认证：`enabled`、`token`、`accounts.*`、`allowBots` - 策略：`groupPolicy`、`dm.*`、`guilds.*`、`guilds.*.channels.*` - 命令：`commands.native`、`commands.useAccessGroups`、`configWrites`、`slashCommand.*` - 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` - Gateway 网关元数据：`gatewayInfoTimeoutMs` -- 回复/历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` -- 交付：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` +- 回复/历史记录：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` +- 发送：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` - 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` - 媒体/重试：`mediaMaxMb`（限制出站 Discord 上传，默认 `100MB`）、`retry` - 操作：`actions.*` @@ -1318,27 +1316,27 @@ openclaw logs --follow - 将机器人令牌视为机密（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 - 授予最小权限的 Discord 权限。 -- 如果命令部署/状态过期，请重启 Gateway 网关并使用 `openclaw channels status --probe` 重新检查。 +- 如果命令部署/状态过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。 -## 相关 +## 相关内容 - - 将 Discord 用户配对到 Gateway 网关。 + + 将 Discord 用户与 Gateway 网关配对。 - + 群聊和允许列表行为。 - + 将入站消息路由到智能体。 - + 威胁模型和加固。 - + 将服务器和渠道映射到智能体。 - + 原生命令行为。 diff --git a/docs/zh-CN/channels/groups.md b/docs/zh-CN/channels/groups.md index b1389236e..fcb1c9141 100644 --- a/docs/zh-CN/channels/groups.md +++ b/docs/zh-CN/channels/groups.md @@ -2,36 +2,36 @@ read_when: - 更改群聊行为或提及门控 sidebarTitle: Groups -summary: 跨各个界面的群聊行为（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo） +summary: 跨各界面的群聊行为（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo） title: 群组 x-i18n: - generated_at: "2026-05-01T18:34:39Z" + generated_at: "2026-05-01T23:03:10Z" model: gpt-5.5 provider: openai - source_hash: 1a75fe41f3a214c9b7d59db19c1622321d43bc16340ea70a43f1547b45c79cf0 + source_hash: 5cc33dbbcf5504cae5caa003b7427d99f5c1a2d7c850dedd5d1f58a2fe44fa04 source_path: channels/groups.md workflow: 16 --- -OpenClaw 在不同表面上一致处理群聊：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。 +OpenClaw 在各个入口上一致地处理群聊：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。 ## 新手简介（2 分钟） -OpenClaw “存在于”你自己的消息账号中。没有单独的 WhatsApp bot 用户。如果**你**在某个群组中，OpenClaw 就能看到该群组并在那里响应。 +OpenClaw “驻留”在你自己的消息账号中。没有单独的 WhatsApp bot 用户。如果**你**在某个群组中，OpenClaw 就能看到该群组并在那里回复。 默认行为： -- 群组受到限制（`groupPolicy: "allowlist"`）。 -- 回复需要提及，除非你明确禁用提及门控。 -- 群组/渠道中的普通最终回复默认是私密的。可见房间输出使用 `message` 工具。 +- 群组受限制（`groupPolicy: "allowlist"`）。 +- 回复需要提及，除非你显式禁用提及门控。 +- 群组/渠道中的普通最终回复默认是私密的。可见的房间输出使用 `message` 工具。 -换句话说：允许列表中的发送者可以通过提及 OpenClaw 来触发它。 +也就是说：允许列表中的发送者可以通过提及 OpenClaw 来触发它。 -**简而言之** +**摘要** -- **私信访问权限**由 `*.allowFrom` 控制。 -- **群组访问权限**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。 +- **私信访问**由 `*.allowFrom` 控制。 +- **群组访问**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。 - **回复触发**由提及门控（`requireMention`、`/activation`）控制。 @@ -48,18 +48,18 @@ otherwise -> reply ## 可见回复 对于群组/渠道房间，OpenClaw 默认使用 `messages.groupChat.visibleReplies: "message_tool"`。 -这意味着智能体仍会处理该轮对话，并可以更新记忆/会话状态，但它的普通最终回答不会自动发回房间。若要可见地发言，智能体会使用 `message(action=send)`。 +这意味着智能体仍会处理该轮对话，并可以更新记忆/会话状态，但它的普通最终回答不会自动发回房间。要可见地发言，智能体会使用 `message(action=send)`。 -如果在当前工具策略下消息工具不可用，OpenClaw 会回退为自动可见回复，而不是静默抑制响应。 -`openclaw doctor` 会警告这种不匹配。 +如果当前工具策略下消息工具不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。 +`openclaw doctor` 会对此不匹配发出警告。 -对于直接聊天和任何其他来源轮次，使用 `messages.visibleReplies: "message_tool"` 可在全局应用相同的仅工具可见回复行为。Harness 也可以选择它作为未设置时的默认值；Codex harness 会为 Codex 模式直接聊天这样做。`messages.groupChat.visibleReplies` 仍然是针对群组/渠道房间的更具体覆盖项。 +对于直接聊天和任何其他来源轮次，使用 `messages.visibleReplies: "message_tool"` 可以全局应用相同的仅工具可见回复行为。Harness 也可以选择将其作为未设置时的默认值；Codex harness 会对 Codex 模式的直接聊天这样做。`messages.groupChat.visibleReplies` 仍然是针对群组/渠道房间的更具体覆盖项。 -这取代了旧模式：强制模型在大多数潜伏模式轮次中回答 `NO_REPLY`。在仅工具模式中，什么都不显示仅仅意味着不调用消息工具。 +这取代了旧模式，即强制模型在大多数潜伏模式轮次中回答 `NO_REPLY`。在仅工具模式中，不做任何可见操作只意味着不调用消息工具。 -在智能体以仅工具模式工作时，仍会发送输入中指示器。这些轮次的默认群组输入模式会从 “message” 升级为 “instant”，因为在智能体决定是否调用消息工具之前，可能永远不会有普通的 assistant 消息文本。显式输入模式配置仍然优先。 +在智能体以仅工具模式工作时，仍会发送正在输入指示器。对于这些轮次，默认群组输入模式会从 “message” 升级为 “instant”，因为在智能体决定是否调用消息工具之前，可能永远不会出现普通助手消息文本。显式输入模式配置仍然优先。 -要恢复群组/渠道房间的旧版自动最终回复： +要为群组/渠道房间恢复旧版自动最终回复： ```json5 { @@ -83,29 +83,29 @@ otherwise -> reply } ``` -原生命令斜杠命令（Discord、Telegram，以及其他支持原生命令的表面）会绕过 `visibleReplies: "message_tool"`，并始终可见地回复，以便渠道原生命令 UI 获得它预期的响应。这仅适用于已验证的原生命令轮次；以文本输入的 `/...` 命令和普通聊天轮次仍遵循配置的群组默认值。 +原生命令（Discord、Telegram 以及其他支持原生命令的入口）会绕过 `visibleReplies: "message_tool"`，并始终可见地回复，以便渠道原生命令 UI 获得它预期的响应。这仅适用于经过验证的原生命令轮次；文本输入的 `/...` 命令和普通聊天轮次仍遵循配置的群组默认值。 ## 上下文可见性和允许列表 -群组安全涉及两种不同的控制： +群组安全涉及两种不同控制： - **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道特定允许列表）。 -- **上下文可见性**：哪些补充上下文会注入模型（回复文本、引用、线程历史、转发元数据）。 +- **上下文可见性**：哪些补充上下文会注入模型（回复文本、引用、话题历史、转发元数据）。 -默认情况下，OpenClaw 优先考虑普通聊天行为，并基本按接收时的样子保留上下文。这意味着允许列表主要决定谁可以触发动作，而不是为每段引用或历史片段提供通用脱敏边界。 +默认情况下，OpenClaw 优先保持普通聊天行为，并让上下文基本按接收状态保留。这意味着允许列表主要决定谁可以触发操作，而不是每段引用或历史片段的通用脱敏边界。 - - 一些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 线程种子填充、Matrix 回复/线程查找）。 - - 其他渠道仍会按接收时的样子传递引用/回复/转发上下文。 + - 一些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 话题种子填充、Matrix 回复/话题查找）。 + - 其他渠道仍会按接收状态传递引用/回复/转发上下文。 - - `contextVisibility: "all"`（默认）保留当前按接收时处理的行为。 + - `contextVisibility: "all"`（默认）保留当前按接收状态处理的行为。 - `contextVisibility: "allowlist"` 将补充上下文过滤为允许列表中的发送者。 - `contextVisibility: "allowlist_quote"` 是 `allowlist` 加上一个显式引用/回复例外。 - 在此加固模型在各渠道中一致实现之前，预期不同表面会存在差异。 + 在此加固模型在各渠道中一致实现之前，预期不同入口会有差异。 @@ -114,27 +114,30 @@ otherwise -> reply 如果你想要…… -| 目标 | 要设置的内容 | +| 目标 | 要设置的内容 | | -------------------------------------------- | ---------------------------------------------------------- | | 允许所有群组，但只在 @提及时回复 | `groups: { "*": { requireMention: true } }` | -| 禁用所有群组回复 | `groupPolicy: "disabled"` | -| 仅特定群组 | `groups: { "": { ... } }`（没有 `"*"` 键） | -| 只有你可以在群组中触发 | `groupPolicy: "allowlist"`，`groupAllowFrom: ["+1555..."]` | +| 禁用所有群组回复 | `groupPolicy: "disabled"` | +| 仅允许特定群组 | `groups: { "": { ... } }`（没有 `"*"` 键） | +| 只有你可以在群组中触发 | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | +| 在多个渠道间复用一组受信发送者 | `groupAllowFrom: ["accessGroup:operators"]` | + +关于可复用的发送者允许列表，请参阅 [访问组](/zh-CN/channels/access-groups)。 ## 会话键 - 群组会话使用 `agent:::group:` 会话键（房间/渠道使用 `agent:::channel:`）。 -- Telegram 论坛主题会在群组 ID 后添加 `:topic:`，因此每个主题都有自己的会话。 -- 直接聊天使用主会话（如果已配置，也可以按发送者分会话）。 +- Telegram 论坛主题会向群组 id 添加 `:topic:`，因此每个主题都有自己的会话。 +- 直接聊天使用主会话（如果已配置，则按发送者分别使用）。 - 群组会话会跳过 Heartbeat。 -## 模式：个人私信 + 公共群组（单个智能体） +## 模式：个人私信 + 公开群组（单智能体） -可以，这种方式很适合“个人”流量是**私信**、“公共”流量是**群组**的情况。 +可以。如果你的“个人”流量是**私信**，而你的“公开”流量是**群组**，这种方式效果很好。 -原因：在单智能体模式中，私信通常会落到**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main::group:`）。如果你使用 `mode: "non-main"` 启用沙箱隔离，这些群组会话会在配置的沙箱后端中运行，而你的主私信会话仍留在主机上。如果你不选择后端，Docker 是默认后端。 +原因：在单智能体模式中，私信通常落入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main::group:`）。如果你启用沙箱隔离并设置 `mode: "non-main"`，这些群组会话会在配置的沙箱后端中运行，而你的主私信会话仍留在主机上。如果你没有选择后端，Docker 是默认后端。 这会给你一个智能体“大脑”（共享工作区 + 记忆），但有两种执行姿态： @@ -142,7 +145,7 @@ otherwise -> reply - **群组**：沙箱 + 受限工具 -如果你需要真正分离的工作区/人格（“个人”和“公共”绝不能混合），请使用第二个智能体 + 绑定。参见[多智能体路由](/zh-CN/concepts/multi-agent)。 +如果你需要真正独立的工作区/人格（“个人”和“公开”绝不能混用），请使用第二个智能体 + 绑定。参阅 [多智能体路由](/zh-CN/concepts/multi-agent)。 @@ -170,8 +173,8 @@ otherwise -> reply } ``` - - 想要“群组只能看到文件夹 X”，而不是“没有主机访问权限”？保留 `workspaceAccess: "none"`，并只把允许列表中的路径挂载到沙箱中： + + 想要“群组只能看到文件夹 X”，而不是“无主机访问权限”？保留 `workspaceAccess: "none"`，并只将允许列表中的路径挂载进沙箱： ```json5 { @@ -196,20 +199,20 @@ otherwise -> reply -相关： +相关内容： - 配置键和默认值：[Gateway 网关配置](/zh-CN/gateway/config-agents#agentsdefaultssandbox) -- 调试工具为何被阻止：[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) +- 调试工具为什么被阻止：[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) - 绑定挂载详情：[沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) ## 显示标签 - UI 标签在可用时使用 `displayName`，格式为 `:`。 -- `#room` 保留用于房间/渠道；群聊使用 `g-`（小写，空格 -> `-`，保留 `#@+._-`）。 +- `#room` 保留给房间/渠道；群聊使用 `g-`（小写，空格 -> `-`，保留 `#@+._-`）。 ## 群组策略 -按渠道控制如何处理群组/房间消息： +控制每个渠道如何处理群组/房间消息： ```json5 { @@ -256,25 +259,25 @@ otherwise -> reply } ``` -| 策略 | 行为 | +| 策略 | 行为 | | ------------- | ------------------------------------------------------------ | -| `"open"` | 群组绕过允许列表；提及门控仍然适用。 | -| `"disabled"` | 完全阻止所有群组消息。 | +| `"open"` | 群组绕过允许列表；提及门控仍然适用。 | +| `"disabled"` | 完全阻止所有群组消息。 | | `"allowlist"` | 仅允许匹配已配置允许列表的群组/房间。 | - - - `groupPolicy` 独立于提及门控（后者需要 @提及）。 + + - `groupPolicy` 独立于提及门控（后者要求 @提及）。 - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（回退：显式 `allowFrom`）。 - - Signal：`groupAllowFrom` 可以匹配入站 Signal 群组 ID 或发送者电话/UUID。 - - 私信配对批准（`*-allowFrom` 存储条目）仅适用于私信访问；群组发送者授权仍显式属于群组允许列表。 + - Signal：`groupAllowFrom` 可以匹配入站 Signal 群组 id，也可以匹配发送者电话/UUID。 + - 私信配对审批（`*-allowFrom` 存储条目）仅适用于私信访问；群组发送者授权仍显式使用群组允许列表。 - Discord：允许列表使用 `channels.discord.guilds..channels`。 - Slack：允许列表使用 `channels.slack.channels`。 - - Matrix：允许列表使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查找是尽力而为，运行时会忽略未解析的名称。使用 `channels.matrix.groupAllowFrom` 限制发送者；也支持按房间的 `users` 允许列表。 + - Matrix：允许列表使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查找是尽力而为，未解析的名称会在运行时被忽略。使用 `channels.matrix.groupAllowFrom` 来限制发送者；也支持按房间设置的 `users` 允许列表。 - 群组私信会单独控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。 - Telegram 允许列表可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀不区分大小写。 - - 默认值是 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息会被阻止。 - - 运行时安全：当提供商块完全缺失（不存在 `channels.`）时，群组策略会回退到故障关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。 + - 默认是 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息会被阻止。 + - 运行时安全：当某个提供商块完全缺失（缺少 `channels.`）时，群组策略会回退到失败关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。 @@ -282,11 +285,11 @@ otherwise -> reply 快速心智模型（群组消息的评估顺序）： - + `groupPolicy`（open/disabled/allowlist）。 - 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道专用允许列表）。 + 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道特定允许列表）。 提及门控（`requireMention`、`/activation`）。 @@ -295,9 +298,9 @@ otherwise -> reply ## 提及门控（默认） -群组消息需要提及，除非按群组覆盖。默认值位于各子系统下的 `*.groups."*"`。 +群组消息需要提及，除非按群组覆盖。默认值按子系统存放在 `*.groups."*"` 下。 -当渠道支持回复元数据时，回复 bot 消息会计为隐式提及。在暴露引用元数据的渠道中，引用 bot 消息也可以计为隐式提及。当前内置场景包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。 +当渠道支持回复元数据时，回复机器人消息会算作隐式提及。在暴露引用元数据的渠道上，引用机器人消息也可以算作隐式提及。当前内置情况包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。 ```json5 { @@ -337,15 +340,15 @@ otherwise -> reply - - `mentionPatterns` 是大小写不敏感的安全正则表达式模式；无效模式和不安全的嵌套重复形式会被忽略。 - - 提供显式提及的界面仍会通过；模式是回退方案。 + - `mentionPatterns` 是不区分大小写的安全正则表达式模式；无效模式和不安全的嵌套重复形式会被忽略。 + - 提供显式提及的表面仍会通过；模式是兜底机制。 - 按智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享一个群组时很有用）。 - 只有在可以进行提及检测时（配置了原生提及或 `mentionPatterns`），才会强制执行提及门控。 - - 将某个群组或发送者加入允许列表不会禁用提及门控；如果所有消息都应触发，请将该群组的 `requireMention` 设为 `false`。 - - 群聊提示上下文会在每一轮携带解析后的静默回复指令；工作区文件不应重复 `NO_REPLY` 机制。 - - 允许静默回复的群组会把干净的空模型轮次或仅推理轮次视为静默，等同于 `NO_REPLY`。直接聊天仅在明确允许直接静默回复时才会这样处理；否则空回复仍会作为失败的智能体轮次。 + - 将群组或发送者加入允许列表不会禁用提及门控；当所有消息都应触发时，将该群组的 `requireMention` 设为 `false`。 + - 群聊提示词上下文在每轮都会携带已解析的静默回复指令；工作区文件不应重复 `NO_REPLY` 机制。 + - 允许静默回复的群组会把干净的空模型轮次或仅推理轮次视为静默，等同于 `NO_REPLY`。只有在明确允许直接静默回复时，直接聊天才会这样处理；否则空回复仍会被视为失败的智能体轮次。 - Discord 默认值位于 `channels.discord.guilds."*"`（可按服务器/渠道覆盖）。 - - 群组历史上下文在各渠道中统一包装，并且**仅限待处理**（因提及门控而跳过的消息）；使用 `messages.groupChat.historyLimit` 设置全局默认值，使用 `channels..historyLimit`（或 `channels..accounts.*.historyLimit`）进行覆盖。设为 `0` 可禁用。 + - 群组历史上下文在各渠道中统一包装，并且是**仅待处理**的（因提及门控而跳过的消息）；使用 `messages.groupChat.historyLimit` 设置全局默认值，并使用 `channels..historyLimit`（或 `channels..accounts.*.historyLimit`）进行覆盖。设为 `0` 可禁用。 @@ -354,19 +357,19 @@ otherwise -> reply 某些渠道配置支持限制**特定群组/房间/渠道内**可用的工具。 -- `tools`：为整个群组允许/拒绝工具。 -- `toolsBySender`：群组内按发送者覆盖。使用显式键前缀：`id:`、`e164:`、`username:`、`name:` 和 `"*"` 通配符。旧版无前缀键仍被接受，并且仅按 `id:` 匹配。 +- `tools`：允许/拒绝整个群组的工具。 +- `toolsBySender`：群组内的按发送者覆盖。使用显式键前缀：`id:`、`e164:`、`username:`、`name:` 和 `"*"` 通配符。旧版无前缀键仍会被接受，并且只按 `id:` 匹配。 -解析顺序（最具体的优先）： +解析顺序（最具体者优先）： - + 群组/渠道 `toolsBySender` 匹配。 群组/渠道 `tools`。 - + 默认（`"*"`）`toolsBySender` 匹配。 @@ -395,15 +398,15 @@ otherwise -> reply ``` -群组/渠道工具限制会在全局/智能体工具策略之外额外应用（拒绝仍然优先）。某些渠道对房间/渠道使用不同的嵌套方式（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。 +群组/渠道工具限制会叠加在全局/智能体工具策略之上（拒绝仍然优先）。某些渠道对房间/渠道使用不同的嵌套方式（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。 ## 群组允许列表 -配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会作为群组允许列表。使用 `"*"` 可允许所有群组，同时仍然设置默认提及行为。 +配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，键会作为群组允许列表。使用 `"*"` 可允许所有群组，同时仍设置默认提及行为。 -常见混淆：私信配对审批不等同于群组授权。对于支持私信配对的渠道，配对存储只解锁私信。群组命令仍需要来自配置允许列表的显式群组发送者授权，例如 `groupAllowFrom` 或该渠道记录的配置回退。 +常见混淆：私信配对批准不等同于群组授权。对于支持私信配对的渠道，配对存储只解锁私信。群组命令仍需要来自配置允许列表的显式群组发送者授权，例如 `groupAllowFrom` 或该渠道记录的配置兜底项。 常见意图（复制/粘贴）： @@ -463,7 +466,7 @@ otherwise -> reply - `/activation mention` - `/activation always` -所有者由 `channels.whatsapp.allowFrom` 决定（未设置时使用 bot 自身的 E.164）。请将命令作为独立消息发送。其他界面目前会忽略 `/activation`。 +所有者由 `channels.whatsapp.allowFrom` 决定（未设置时则为机器人的自身 E.164）。将命令作为独立消息发送。其他表面目前会忽略 `/activation`。 ## 上下文字段 @@ -475,25 +478,25 @@ otherwise -> reply - `WasMentioned`（提及门控结果） - Telegram 论坛话题还包括 `MessageThreadId` 和 `IsForum`。 -渠道专用说明： +渠道特定说明： -- BlueBubbles 可以在填充 `GroupMembers` 之前，从本地 Contacts 数据库可选地补充未命名的 macOS 群组参与者信息。此功能默认关闭，并且仅在常规群组门控通过后运行。 +- BlueBubbles 可以选择在填充 `GroupMembers` 之前，从本地 Contacts 数据库补充未命名的 macOS 群组参与者。此功能默认关闭，并且只会在正常群组门控通过后运行。 -智能体系统提示会在新群组会话的第一轮包含群组介绍。它会提醒模型像人一样回复，避免使用 Markdown 表格，尽量减少空行并遵循正常聊天间距，且避免输入字面量 `\n` 序列。来自渠道的群组名称和参与者标签会呈现为围栏代码块中的不受信任元数据，而不是内联系统指令。 +智能体系统提示词会在新群组会话的第一轮包含群组介绍。它会提醒模型像人一样回应、避免使用 Markdown 表格、尽量减少空行并遵循正常聊天间距，以及避免输入字面量 `\n` 序列。来自渠道的群组名称和参与者标签会渲染为受围栏保护的不可信元数据，而不是内联系统指令。 ## iMessage 细节 - 路由或加入允许列表时，优先使用 `chat_id:`。 - 列出聊天：`imsg chats --limit 20`。 -- 群组回复始终回到同一个 `chat_id`。 +- 群组回复始终返回到同一个 `chat_id`。 -## WhatsApp 系统提示 +## WhatsApp 系统提示词 -请参阅 [WhatsApp](/zh-CN/channels/whatsapp#system-prompts)，了解规范的 WhatsApp 系统提示规则，包括群组和直接提示解析、通配符行为以及账号覆盖语义。 +请参阅 [WhatsApp](/zh-CN/channels/whatsapp#system-prompts)，了解规范的 WhatsApp 系统提示词规则，包括群组和直接提示词解析、通配符行为以及账号覆盖语义。 ## WhatsApp 细节 -请参阅 [群组消息](/zh-CN/channels/group-messages)，了解仅限 WhatsApp 的行为（历史注入、提及处理细节）。 +请参阅[群组消息](/zh-CN/channels/group-messages)，了解仅限 WhatsApp 的行为（历史注入、提及处理细节）。 ## 相关 diff --git a/docs/zh-CN/channels/pairing.md b/docs/zh-CN/channels/pairing.md index 24a0b4876..637944bc3 100644 --- a/docs/zh-CN/channels/pairing.md +++ b/docs/zh-CN/channels/pairing.md @@ -2,14 +2,14 @@ read_when: - 设置私信访问控制 - 配对新的 iOS/Android 节点 - - 审查 OpenClaw 安全态势 -summary: 配对概览：批准谁可以给你发私信 + 哪些节点可以加入 + - 审查 OpenClaw 的安全态势 +summary: 配对概览：批准谁可以私信你 + 哪些节点可以加入 title: 配对 x-i18n: - generated_at: "2026-05-01T22:59:39Z" + generated_at: "2026-05-01T23:03:13Z" model: gpt-5.5 provider: openai - source_hash: b11f4b538b9100e14c3dfe13c7a64995e5cebfc1c459839c6fa7a397f4cfb9ec + source_hash: bb68d87c0e1dfe7c9a6a6d9415f4c63625755fb43a2e22a1d1374ff0a63e49c4 source_path: channels/pairing.md workflow: 16 --- @@ -17,27 +17,27 @@ x-i18n: “配对”是 OpenClaw 的显式访问批准步骤。 它用于两个地方： -1. **私信配对**（谁被允许与机器人交谈） +1. **私信配对**（谁被允许与机器人对话） 2. **节点配对**（哪些设备/节点被允许加入 Gateway 网关网络） 安全上下文：[安全](/zh-CN/gateway/security) ## 1) 私信配对（入站聊天访问） -当某个渠道配置了私信策略 `pairing` 时，未知发送者会收到一个短代码，并且在你批准之前，其消息**不会被处理**。 +当某个渠道配置了私信策略 `pairing` 时，未知发送者会收到一个短代码，并且在你批准之前，他们的消息**不会被处理**。 默认私信策略记录在：[安全](/zh-CN/gateway/security) -`dmPolicy: "open"` 只有在生效的私信允许列表包含 `"*"` 时才是公开的。 +只有当有效的私信允许列表包含 `"*"` 时，`dmPolicy: "open"` 才是公开的。 设置和验证要求公开开放配置使用该通配符。如果现有 -状态包含带有具体 `allowFrom` 条目的 `open`，运行时仍然只准入 -这些发送者，并且配对存储中的批准不会扩大 `open` 访问范围。 +状态包含 `open` 和具体的 `allowFrom` 条目，运行时仍然只接纳 +这些发送者，并且配对存储中的批准不会扩大 `open` 访问权限。 配对代码： - 8 个字符，大写，不含易混淆字符（`0O1I`）。 - **1 小时后过期**。机器人只会在创建新请求时发送配对消息（大约每个发送者每小时一次）。 -- 待处理的私信配对请求默认每个渠道最多 **3 个**；额外请求会被忽略，直到其中一个过期或被批准。 +- 默认情况下，待处理的私信配对请求上限为**每个渠道 3 个**；更多请求会被忽略，直到其中一个过期或获批。 ### 批准发送者 @@ -47,16 +47,20 @@ openclaw pairing approve telegram ``` 如果尚未配置命令所有者，批准私信配对代码也会将 -`commands.ownerAllowFrom` 初始化为已批准的发送者，例如 `telegram:123456789`。 -这会为首次设置提供一个显式所有者，用于特权命令和执行审批 -提示。所有者存在后，之后的配对批准只授予私信 +`commands.ownerAllowFrom` 引导设置为已批准的发送者，例如 `telegram:123456789`。 +这会为首次设置提供一个用于特权命令和 exec +批准提示的显式所有者。已有所有者之后，后续配对批准只授予私信 访问权限；它们不会添加更多所有者。 支持的渠道：`bluebubbles`、`discord`、`feishu`、`googlechat`、`imessage`、`irc`、`line`、`matrix`、`mattermost`、`msteams`、`nextcloud-talk`、`nostr`、`openclaw-weixin`、`signal`、`slack`、`synology-chat`、`telegram`、`twitch`、`whatsapp`、`zalo`、`zalouser`。 -### 可复用发送者组 +### 可复用的发送者组 -当同一组可信发送者需要应用到多个消息渠道，或同时应用到私信和群组允许列表时，请使用顶层 `accessGroups`。静态发送者组使用 `type: "message.senders"`，并按每个渠道的常规 `allowFrom` 语法列出成员。 +当同一组受信任发送者需要应用于多个消息渠道，或同时应用于私信和群组允许列表时， +请使用顶层 `accessGroups`。 + +静态组使用 `type: "message.senders"`，并在渠道允许列表中通过 +`accessGroup:` 引用： ```json5 { @@ -64,7 +68,6 @@ openclaw pairing approve telegram operators: { type: "message.senders", members: { - "*": ["global-owner-id"], discord: ["discord:123456789012345678"], telegram: ["987654321"], whatsapp: ["+15551234567"], @@ -78,31 +81,31 @@ openclaw pairing approve telegram } ``` -`"*"` 成员列表由所有消息渠道共享。渠道特定列表会使用该渠道自己的发送者匹配规则进行检查。 +访问组的详细文档在这里：[访问组](/zh-CN/channels/access-groups) -### 状态存储位置 +### 状态的存储位置 存储在 `~/.openclaw/credentials/` 下： - 待处理请求：`-pairing.json` - 已批准允许列表存储： - - 默认账号：`-allowFrom.json` - - 非默认账号：`--allowFrom.json` + - 默认账户：`-allowFrom.json` + - 非默认账户：`--allowFrom.json` -账号作用域行为： +账户作用域行为： -- 非默认账号只读取/写入其作用域内的允许列表文件。 -- 默认账号使用渠道作用域的非作用域允许列表文件。 +- 非默认账户只读写其作用域内的允许列表文件。 +- 默认账户使用渠道作用域的无作用域允许列表文件。 -请将这些视为敏感内容（它们控制对你的助手的访问）。 +请将这些文件视为敏感信息（它们控制对你的助手的访问）。 配对允许列表存储用于私信访问。群组授权是独立的。 批准私信配对代码不会自动允许该发送者运行群组 -命令或在群组中控制机器人。首次所有者初始化是 `commands.ownerAllowFrom` -中的独立配置状态，而群组聊天投递仍遵循该 -渠道的群组允许列表（例如 `groupAllowFrom`、`groups`，或视渠道而定的按群组 -或按主题覆盖）。 +命令或在群组中控制机器人。首次所有者引导是 +`commands.ownerAllowFrom` 中的独立配置状态，群聊投递仍然遵循该 +渠道的群组允许列表（例如 `groupAllowFrom`、`groups`，或取决于渠道的按群组 +或按话题覆盖）。 ## 2) 节点设备配对（iOS/Android/macOS/无头节点） @@ -112,31 +115,31 @@ openclaw pairing approve telegram ### 通过 Telegram 配对（推荐用于 iOS） -如果你使用 `device-pair` 插件，可以完全从 Telegram 完成首次设备配对： +如果你使用 `device-pair` 插件，可以完全通过 Telegram 完成首次设备配对： -1. 在 Telegram 中，向你的机器人发送消息：`/pair` -2. 机器人会回复两条消息：一条说明消息，以及一条单独的**设置代码**消息（在 Telegram 中易于复制/粘贴）。 -3. 在你的手机上，打开 OpenClaw iOS 应用 → 设置 → Gateway 网关。 +1. 在 Telegram 中，给你的机器人发送消息：`/pair` +2. 机器人会回复两条消息：一条说明消息，以及一条单独的**设置代码**消息（便于在 Telegram 中复制/粘贴）。 +3. 在手机上，打开 OpenClaw iOS 应用 → 设置 → Gateway 网关。 4. 粘贴设置代码并连接。 5. 回到 Telegram：`/pair pending`（查看请求 ID、角色和作用域），然后批准。 -设置代码是一个 base64 编码的 JSON 载荷，包含： +设置代码是一个 base64 编码的 JSON 载荷，其中包含： - `url`：Gateway 网关 WebSocket URL（`ws://...` 或 `wss://...`） - `bootstrapToken`：用于初始配对握手的短期单设备引导令牌 -该引导令牌携带内置配对引导配置文件： +该引导令牌携带内置的配对引导配置文件： -- 主要移交的 `node` 令牌保持 `scopes: []` -- 任何移交的 `operator` 令牌都限制在引导允许列表内： +- 主要移交的 `node` 令牌保持为 `scopes: []` +- 任何移交的 `operator` 令牌都保持受限于引导允许列表： `operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write` -- 引导作用域检查按角色前缀区分，而不是一个扁平的作用域池： +- 引导作用域检查按角色加前缀，而不是一个扁平的作用域池： operator 作用域条目只满足 operator 请求，非 operator 角色 - 仍必须请求其自身角色前缀下的作用域 -- 后续令牌轮换/撤销仍同时受设备已批准 - 角色契约和调用方会话 operator 作用域的限制 + 仍必须在自己的角色前缀下请求作用域 +- 后续令牌轮换/吊销仍然同时受设备已批准的 + 角色契约和调用方会话的 operator 作用域限制 -请在设置代码有效期间像对待密码一样对待它。 +设置代码有效期间，请像对待密码一样对待它。 ### 批准节点设备 @@ -151,13 +154,13 @@ openclaw devices reject `requestId`。 -已配对的设备不会静默获得更广泛的访问权限。如果它重新连接并请求更多作用域或更广泛的角色，OpenClaw 会保持现有批准不变，并创建一个新的待处理升级请求。批准前，请使用 `openclaw devices list` 比较当前已批准的访问权限和新请求的访问权限。 +已配对的设备不会静默获得更广泛的访问权限。如果它重新连接并请求更多作用域或更宽泛的角色，OpenClaw 会保持现有批准不变，并创建新的待处理升级请求。在批准前，请使用 `openclaw devices list` 比较当前已批准的访问权限与新请求的访问权限。 -### 可选的可信 CIDR 节点自动批准 +### 可选的受信任 CIDR 节点自动批准 -设备配对默认仍为手动。对于严格受控的节点网络， -你可以选择使用显式 CIDR 或精确 IP 来对首次节点自动批准： +设备配对默认保持手动。对于严格控制的节点网络， +你可以通过显式 CIDR 或精确 IP 选择加入首次节点自动批准： ```json5 { @@ -172,8 +175,8 @@ openclaw devices reject ``` 这只适用于没有请求 -作用域的新 `role: node` 配对请求。Operator、浏览器、Control UI 和 WebChat 客户端仍需要手动 -批准。角色、作用域、元数据和公钥变更仍需要手动 +作用域的全新 `role: node` 配对请求。Operator、浏览器、Control UI 和 WebChat 客户端仍然需要手动 +批准。角色、作用域、元数据和公钥变更仍然需要手动 批准。 ### 节点配对状态存储 @@ -186,9 +189,9 @@ openclaw devices reject ### 备注 - 旧版 `node.pair.*` API（CLI：`openclaw nodes pending|approve|reject|remove|rename`）是一个 - 独立的 Gateway 网关拥有的配对存储。WS 节点仍需要设备配对。 -- 配对记录是已批准角色的持久事实来源。活跃 - 设备令牌仍受该已批准角色集限制；已批准角色之外的杂散令牌条目 + 独立的 Gateway 网关所有的配对存储。WS 节点仍然需要设备配对。 +- 配对记录是已批准角色的持久事实来源。活动 + 设备令牌保持受限于该已批准角色集；已批准角色之外的零散令牌条目 不会创建新的访问权限。 ## 相关文档