From 027cdf6a1ca1910957187d49b554126a16650af5 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 29 Apr 2026 00:32:25 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/discord.md | 427 ++++++++++---------- docs/zh-CN/tools/exec-approvals-advanced.md | 178 ++++---- 2 files changed, 305 insertions(+), 300 deletions(-) diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index cab6d1b53..a4f5b2db3 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -1,18 +1,18 @@ --- read_when: - 开发 Discord 渠道功能 -summary: Discord 机器人支持状态、能力和配置 +summary: Discord 机器人支持状态、功能和配置 title: Discord x-i18n: - generated_at: "2026-04-28T19:12:26Z" + generated_at: "2026-04-29T00:30:33Z" model: gpt-5.5 provider: openai - source_hash: b552ae25d1f1edac7499af1ebb0a04b213f546b95aa93cd2bb4e292ce793bc40 + source_hash: 2fc2d3b26704ffa0f8e388cde48952ad2e205b9cd09c4873666d25db3a9bd94b source_path: channels/discord.md workflow: 16 --- -已支持通过官方 Discord Gateway 网关使用私信和 guild 渠道。 +已准备好通过官方 Discord Gateway 网关用于私信和服务器频道。 @@ -28,18 +28,18 @@ x-i18n: ## 快速设置 -你需要创建一个带机器人的新应用，将机器人添加到你的服务器，并将其配对到 OpenClaw。我们建议将你的机器人添加到你自己的私有服务器。如果你还没有服务器，请[先创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **Create My Own > For me and my friends**）。 +你需要创建一个带机器人的新应用，将机器人添加到你的服务器，并将其与 OpenClaw 配对。我们建议将你的机器人添加到你自己的私有服务器。如果你还没有服务器，请先[创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **Create My Own > For me and my friends**）。 - 前往 [Discord Developer Portal](https://discord.com/developers/applications)，点击 **New Application**。将它命名为类似 “OpenClaw” 的名称。 + 前往 [Discord Developer Portal](https://discord.com/developers/applications)，然后点击 **New Application**。将其命名为类似 “OpenClaw” 的名称。 点击侧边栏中的 **Bot**。将 **Username** 设置为你给 OpenClaw 智能体起的名称。 - - 仍在 **Bot** 页面上，向下滚动到 **Privileged Gateway Intents** 并启用： + + 仍在 **Bot** 页面，向下滚动到 **Privileged Gateway Intents** 并启用： - **Message Content Intent**（必需） - **Server Members Intent**（推荐；角色允许列表和名称到 ID 匹配需要） @@ -47,26 +47,26 @@ x-i18n: - - 回到 **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 threads 中发帖，包括创建或继续 thread 的论坛或媒体频道工作流，也请启用 **Send Messages in Threads**。 - 复制底部生成的 URL，粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 连接。现在你应该能在 Discord 服务器中看到你的机器人。 + 这是普通文本频道的基准权限集合。如果你计划在 Discord 话题中发帖，包括创建或继续话题的论坛或媒体频道工作流，也请启用 **Send Messages in Threads**。 + 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该能在 Discord 服务器中看到你的机器人。 - - 回到 Discord 应用中，你需要启用 Developer Mode，才能复制内部 ID。 + + 回到 Discord 应用，你需要启用开发者模式，以便复制内部 ID。 - 1. 点击 **User Settings**（头像旁的齿轮图标）→ **Advanced** → 开启 **Developer Mode** - 2. 右键点击侧边栏中的**服务器图标** → **Copy Server ID** - 3. 右键点击你**自己的头像** → **Copy User ID** + 1. 点击 **User Settings**（头像旁边的齿轮图标）→ **Advanced** → 开启 **Developer Mode** + 2. 右键点击侧边栏中的 **server icon** → **Copy Server ID** + 3. 右键点击你的 **own avatar** → **Copy User ID** - 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存，下一步你会把这三项都发送给 OpenClaw。 + 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存，你将在下一步把这三项发送给 OpenClaw。 - - 要让配对工作，Discord 需要允许你的机器人给你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 开启 **Direct Messages**。 + + 要让配对正常工作，Discord 需要允许你的机器人向你发送私信。右键点击你的 **server icon** → **Privacy Settings** → 开启 **Direct Messages**。 - 这允许服务器成员（包括机器人）给你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持此项启用。如果你只计划使用 guild 渠道，可以在配对后禁用私信。 + 这会允许服务器成员（包括机器人）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持此项启用。如果你只计划使用服务器频道，可以在配对后禁用私信。 - - 你的 Discord 机器人 token 是机密信息（类似密码）。在给你的智能体发消息之前，先在运行 OpenClaw 的机器上设置它。 + + 你的 Discord 机器人令牌是一个密钥（类似密码）。在向智能体发送消息之前，请在运行 OpenClaw 的机器上设置它。 ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -112,7 +112,7 @@ openclaw gateway ``` 如果 OpenClaw 已经作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或停止并重新启动 `openclaw gateway run` 进程。 - 对于托管服务安装，请在存在 `DISCORD_BOT_TOKEN` 的 shell 中运行 `openclaw gateway install`，或将该变量存储在 `~/.openclaw/.env` 中，以便服务在重启后解析 env SecretRef。 + 对于托管服务安装，请从存在 `DISCORD_BOT_TOKEN` 的 shell 中运行 `openclaw gateway install`，或将该变量存储在 `~/.openclaw/.env` 中，以便服务在重启后可以解析 env SecretRef。 @@ -120,9 +120,9 @@ openclaw gateway - 在任意现有渠道（例如 Telegram）与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置选项卡。 + 在任何现有渠道（例如 Telegram）与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置标签页。 - > “我已经在配置中设置了我的 Discord 机器人 token。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” + > “我已经在配置中设置了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” 如果你更喜欢基于文件的配置，请设置： @@ -148,7 +148,7 @@ openclaw gateway DISCORD_BOT_TOKEN=... ``` - 支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商的 SecretRef 值。参见[密钥管理](/zh-CN/gateway/secrets)。 + 支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商使用 SecretRef 值。请参阅[密钥管理](/zh-CN/gateway/secrets)。 @@ -156,13 +156,13 @@ DISCORD_BOT_TOKEN=... - 等待 Gateway 网关运行后，在 Discord 中给你的机器人发送私信。它会返回一个配对代码。 + 等待 Gateway 网关运行，然后在 Discord 中私信你的机器人。它会返回一个配对码。 - 在你的现有渠道上将配对代码发送给你的智能体： + 将配对码通过你现有的渠道发送给你的智能体： - > “批准这个 Discord 配对代码：``” + > “批准这个 Discord 配对码：``” @@ -174,7 +174,7 @@ openclaw pairing approve discord - 配对代码将在 1 小时后过期。 + 配对码将在 1 小时后过期。 现在你应该可以通过 Discord 私信与你的智能体聊天。 @@ -182,22 +182,22 @@ openclaw pairing approve discord -Token 解析是账户感知的。配置 token 值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 -如果两个已启用的 Discord 账户解析到同一个机器人 token，OpenClaw 只会为该 token 启动一个 Gateway 网关监视器。配置来源的 token 优先于默认环境变量回退；否则第一个已启用账户胜出，重复账户会报告为已禁用。 -对于高级出站调用（message 工具/渠道操作），显式的逐调用 `token` 将用于该调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍来自活动运行时快照中选定的账户。 +令牌解析是账户感知的。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 +如果两个已启用的 Discord 账户解析为同一个机器人令牌，OpenClaw 只会为该令牌启动一个 Gateway 网关监视器。配置来源的令牌优先于默认环境变量回退；否则第一个启用的账户胜出，重复账户会被报告为已禁用。 +对于高级出站调用（消息工具/渠道操作），显式的逐调用 `token` 会用于该调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍来自活动运行时快照中选定的账户。 -## 推荐：设置 guild 工作区 +## 推荐：设置服务器工作区 -私信可用后，你可以将 Discord 服务器设置为完整工作区，让每个频道都有自己的智能体会话和上下文。对于只有你和你的机器人的私有服务器，推荐这样做。 +私信正常工作后，你可以将 Discord 服务器设置为完整工作区，其中每个频道都有自己的智能体会话和上下文。对于只有你和你的机器人的私有服务器，建议这样做。 - - 这会让你的智能体可以在服务器上的任何频道中响应，而不只是私信。 + + 这会让你的智能体能够在服务器上的任何频道中响应，而不仅限于私信。 - > “将我的 Discord Server ID `` 添加到 guild 允许列表” + > “将我的 Discord Server ID `` 添加到服务器允许列表” @@ -222,17 +222,17 @@ Token 解析是账户感知的。配置 token 值优先于环境变量回退。` - - 默认情况下，你的智能体只会在 guild 渠道中被 @提及时响应。对于私有服务器，你可能希望它响应每条消息。 + + 默认情况下，你的智能体只有在服务器频道中被 @提及时才会响应。对于私有服务器，你可能希望它响应每条消息。 - 在 guild 渠道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须通过 `message` 工具显式发送，因此智能体默认可以潜伏，只在判断渠道回复有用时才发帖。 + 在服务器频道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须通过 `message` 工具显式发送，因此智能体默认可以旁观，并且只在它判断频道回复有用时才发帖。 - > “允许我的智能体在这个服务器上无需被 @提及也能响应” + > “允许我的智能体在这个服务器上响应，而不需要被 @提及” - 在你的 guild 配置中设置 `requireMention: false`： + 在你的服务器配置中设置 `requireMention: false`： ```json5 { @@ -248,67 +248,67 @@ Token 解析是账户感知的。配置 token 值优先于环境变量回退。` } ``` - 若要恢复群组/渠道房间的旧版自动最终回复，请设置 `messages.groupChat.visibleReplies: "automatic"`。 + 要为群组/频道房间恢复旧版自动最终回复，请设置 `messages.groupChat.visibleReplies: "automatic"`。 - - 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。Guild 渠道不会自动加载 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 guild/渠道元数据会作为不受信任的上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果模型复制了该包裹内容，OpenClaw 会从出站回复和未来重放上下文中剥离复制的元数据。 +- 回复路由是确定性的：Discord 入站回复会回到 Discord。 +- Discord 服务器/频道元数据会作为不受信任的上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果模型将该封套复制回来，OpenClaw 会从出站回复和未来重放上下文中移除复制的元数据。 - 默认情况下（`session.dmScope=main`），直接聊天共享智能体主会话（`agent:main:main`）。 -- Guild 渠道使用隔离的会话键（`agent::discord:channel:`）。 -- 群组私信默认被忽略（`channels.discord.dm.groupEnabled=false`）。 +- 服务器频道是隔离的会话键（`agent::discord:channel:`）。 +- 群组私信默认会被忽略（`channels.discord.dm.groupEnabled=false`）。 - 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 到路由后的对话会话。 -- 纯文本 cron/heartbeat 到 Discord 的公告投递会使用一次最终助手可见答案。媒体和结构化组件 payload 在智能体发出多个可投递 payload 时仍保持多消息形式。 +- 仅文本的 cron/heartbeat 公告投递到 Discord 时，会使用最终助手可见答案一次。媒体和结构化组件负载在智能体发出多个可投递负载时仍保持多消息形式。 ## 论坛频道 -Discord 论坛和媒体频道只接受 thread 帖文。OpenClaw 支持两种创建方式： +Discord 论坛和媒体频道只接受话题帖子。OpenClaw 支持两种创建方式： -- 向论坛父频道（`channel:`）发送消息以自动创建 thread。Thread 标题使用你消息的第一行非空内容。 -- 使用 `openclaw message thread create` 直接创建 thread。对于论坛频道，不要传递 `--message-id`。 +- 向论坛父频道（`channel:`）发送消息以自动创建话题。话题标题使用消息的第一行非空内容。 +- 使用 `openclaw message thread create` 直接创建话题。不要为论坛频道传递 `--message-id`。 -示例：发送到论坛父频道以创建 thread +示例：发送到论坛父频道以创建话题 ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -示例：显式创建论坛 thread +示例：显式创建论坛话题 ```bash openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -论坛父频道不接受 Discord 组件。如果你需要组件，请发送到 thread 本身（`channel:`）。 +论坛父频道不接受 Discord 组件。如果你需要组件，请发送到话题本身（`channel:`）。 ## 交互式组件 -OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带有 `components` 负载的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 +OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用带有 `components` 载荷的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有 Discord `replyToMode` 设置。 支持的块： @@ -316,23 +316,23 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - 操作行最多允许 5 个按钮或一个选择菜单 - 选择类型：`string`、`user`、`role`、`mentionable`、`channel` -默认情况下，组件只能使用一次。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前被多次使用。 +默认情况下，components 只能使用一次。设置 `components.reusable=true` 可允许按钮、选择菜单和表单被多次使用，直到它们过期。 要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开交互式模型选择器，包含提供商、模型和兼容运行时下拉菜单，以及提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，且只有调用用户可以使用。 +`/model` 和 `/models` 斜杠命令会打开交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，只有调用用户可以使用。 文件附件： - `file` 块必须指向附件引用（`attachment://`） -- 通过 `media`/`path`/`filePath` 提供附件（单个文件）；多个文件使用 `media-gallery` -- 当上传名称需要匹配附件引用时，使用 `filename` 覆盖上传名称 +- 通过 `media`/`path`/`filePath` 提供附件（单个文件）；多个文件请使用 `media-gallery` +- 当上传名称应匹配附件引用时，使用 `filename` 覆盖上传名称 模态表单： - 添加最多包含 5 个字段的 `components.modal` - 字段类型：`text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` -- OpenClaw 会自动添加一个触发按钮 +- OpenClaw 会自动添加触发按钮 示例： @@ -399,20 +399,20 @@ 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`。 - - 命名账户不会继承 `channels.discord.accounts.default.allowFrom`。 + - `channels.discord.accounts.default.allowFrom` 仅适用于 `default` 账号。 + - 具名账号在自身 `allowFrom` 未设置时继承 `channels.discord.allowFrom`。 + - 具名账号不会继承 `channels.discord.accounts.default.allowFrom`。 - 用于投递的私信目标格式： + 投递的私信目标格式： - `user:` - `<@id>` 提及 - 裸数字 ID 存在歧义，会被拒绝，除非提供了明确的用户/渠道目标类型。 + 裸数字 ID 存在歧义，除非提供了显式的用户/渠道目标类型，否则会被拒绝。 @@ -423,16 +423,16 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `allowlist` - `disabled` - 当存在 `channels.discord` 时，安全基线是 `allowlist`。 + 当 `channels.discord` 存在时，安全基线是 `allowlist`。 `allowlist` 行为： - - 服务器必须匹配 `channels.discord.guilds`（首选 `id`，也接受 slug） - - 可选发送者允许列表：`users`（建议使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了任一项，当发送者匹配 `users` 或 `roles` 时允许 - - 默认禁用直接名称/标签匹配；仅在应急兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true` + - 服务器必须匹配 `channels.discord.guilds`（优先使用 `id`，也接受 slug） + - 可选发送者允许列表：`users`（建议使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了任意一个，发送者匹配 `users` 或 `roles` 时即被允许 + - 默认禁用直接名称/标签匹配；仅在破窗兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true` - `users` 支持名称/标签，但 ID 更安全；使用名称/标签条目时，`openclaw security audit` 会发出警告 - - 如果服务器配置了 `channels`，未列出的渠道会被拒绝 - - 如果服务器没有 `channels` 块，则该允许列表服务器中的所有渠道都被允许 + - 如果某个服务器配置了 `channels`，未列出的渠道会被拒绝 + - 如果某个服务器没有 `channels` 块，该允许列表服务器中的所有渠道都会被允许 示例： @@ -458,18 +458,18 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 如果你只设置了 `DISCORD_BOT_TOKEN`，且没有创建 `channels.discord` 块，运行时回退为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open`。 + 如果你只设置 `DISCORD_BOT_TOKEN` 而未创建 `channels.discord` 块，运行时回退会是 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open`。 - 服务器消息默认由提及门控。 + 服务器消息默认受提及门控。 提及检测包括： - 显式机器人提及 - - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） - - 支持场景中的隐式回复机器人行为 + - 配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） + - 受支持情况下的隐式回复机器人行为 `requireMention` 按服务器/渠道配置（`channels.discord.guilds...`）。 `ignoreOtherMentions` 可选择丢弃提及其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 @@ -477,14 +477,14 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 群组私信： - 默认：忽略（`dm.groupEnabled=false`） - - 可选允许列表通过 `dm.groupChannels` 设置（渠道 ID 或 slug） + - 可通过 `dm.groupChannels` 设置可选允许列表（渠道 ID 或 slug） ### 基于角色的智能体路由 -使用 `bindings[].match.roles` 按角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并在对等或父对等绑定之后、仅服务器绑定之前求值。如果绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 +使用 `bindings[].match.roles` 按角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并在点对点或父点对点绑定之后、仅服务器绑定之前评估。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），所有配置字段都必须匹配。 ```json5 { @@ -514,9 +514,9 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - 按渠道覆盖：`channels.discord.commands.native`。 - `commands.native=false` 会显式清除先前注册的 Discord 原生命令。 - 原生命令认证使用与普通消息处理相同的 Discord 允许列表/策略。 -- 对于未授权的用户，命令仍可能在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 认证，并返回 “not authorized”。 +- 命令仍可能在 Discord UI 中对未授权用户可见；执行时仍会强制执行 OpenClaw 认证，并返回 “not authorized”。 -请参阅[斜杠命令](/zh-CN/tools/slash-commands)，了解命令目录和行为。 +请参阅[斜杠命令](/zh-CN/tools/slash-commands)了解命令目录和行为。 默认斜杠命令设置： @@ -538,18 +538,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` 是旧版别名，会自动迁移。 - 默认保持为 `off`，因为当多个机器人或 Gateway 网关共享一个账户时，Discord 预览编辑会很快触发速率限制。 + 默认保持 `off`，因为当多个机器人或 Gateway 网关共享账号时，Discord 预览编辑会很快触发速率限制。 ```json5 { @@ -566,8 +566,8 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - - `partial` 会在令牌到达时编辑单条预览消息。 - - `block` 会发出草稿大小的分块（使用 `draftChunk` 调整大小和断点，并受限于 `textChunkLimit`）。 + - `partial` 会在 token 到达时编辑单条预览消息。 + - `block` 会发出草稿大小的分块（使用 `draftChunk` 调整大小和断点，受限于 `textChunkLimit`）。 - 媒体、错误和显式回复最终消息会取消待处理的预览编辑。 - `streaming.preview.toolProgress`（默认 `true`）控制工具/进度更新是否复用预览消息。 @@ -575,7 +575,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - + 服务器历史上下文： - `channels.discord.historyLimit` 默认 `20` @@ -589,26 +589,26 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 线程行为： - - Discord 线程会作为渠道会话路由，并继承父渠道配置，除非被覆盖。 - - 线程会话继承父渠道的会话级 `/model` 选择，作为仅模型回退；线程本地 `/model` 选择仍然优先，且除非启用转录继承，否则不会复制父转录历史。 - - `channels.discord.thread.inheritParent`（默认 `false`）让新的自动线程选择从父转录中播种。按账户覆盖位于 `channels.discord.accounts..thread.inheritParent` 下。 + - Discord 线程按渠道会话路由，并继承父渠道配置，除非被覆盖。 + - 线程会话继承父渠道的会话级 `/model` 选择，作为仅模型回退；线程本地 `/model` 选择仍优先，且除非启用转录继承，否则不会复制父转录历史记录。 + - `channels.discord.thread.inheritParent`（默认 `false`）让新的自动线程选择从父转录播种。按账号覆盖位于 `channels.discord.accounts..thread.inheritParent` 下。 - 消息工具反应可以解析 `user:` 私信目标。 - `guilds..channels..requireMention: false` 会在回复阶段激活回退期间保留。 - 渠道主题会作为**不受信任**的上下文注入。允许列表门控谁可以触发智能体，而不是完整的补充上下文脱敏边界。 + 渠道主题会作为**不可信**上下文注入。允许列表控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 - + Discord 可以将线程绑定到会话目标，使该线程中的后续消息继续路由到同一会话（包括子智能体会话）。 命令： - `/focus ` 将当前/新线程绑定到子智能体/会话目标 - `/unfocus` 移除当前线程绑定 - - `/agents` 显示活动运行和绑定状态 + - `/agents` 显示活跃运行和绑定状态 - `/session idle ` 检查/更新聚焦绑定的不活跃自动取消聚焦 - - `/session max-age ` 检查/更新聚焦绑定的硬性最大期限 + - `/session max-age ` 检查/更新聚焦绑定的硬性最大时长 配置： @@ -634,20 +634,20 @@ 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` 和相关线程绑定操作将不可用。 + - 如果某个账号禁用了线程绑定，则 `/focus` 和相关线程绑定操作不可用。 请参阅 [子智能体](/zh-CN/tools/subagents)、[ACP 智能体](/zh-CN/tools/acp-agents) 和 [配置参考](/zh-CN/gateway/configuration-reference)。 - 对于稳定的“始终在线”ACP 工作区，请配置指向 Discord 对话的顶层带类型 ACP 绑定。 + 对于稳定的“始终在线”ACP 工作区，请配置面向 Discord 对话的顶层类型化 ACP 绑定。 配置路径： @@ -701,11 +701,11 @@ 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) 了解绑定行为详情。 @@ -724,7 +724,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `ackReaction` 会在 OpenClaw 处理入站消息时发送确认表情符号。 + `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 解析顺序： @@ -733,17 +733,17 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `messages.ackReaction` - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） - 注意： + 说明： - Discord 接受 Unicode 表情符号或自定义表情符号名称。 - - 使用 `""` 可为某个渠道或账号禁用该回应。 + - 使用 `""` 可为某个频道或账号禁用该回应。 默认启用由渠道发起的配置写入。 - 这会影响 `/config set|unset` 流程（当命令功能已启用时）。 + 这会影响 `/config set|unset` 流程（当命令功能启用时）。 禁用： @@ -760,7 +760,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - 通过带有 `channels.discord.proxy` 的 HTTP(S) 代理路由 Discord gateway WebSocket 流量和启动时的 REST 查询（应用 ID + allowlist 解析）。 + 使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord 网关 WebSocket 流量和启动时的 REST 查询（应用 ID + allowlist 解析）。 ```json5 { @@ -806,19 +806,19 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 注意： + 说明： - allowlist 可以使用 `pk:` - 只有当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名称 - 查询使用原始消息 ID，并受时间窗口限制 - - 如果查询失败，代理消息会被视为 bot 消息并丢弃，除非 `allowBots=true` + - 如果查询失败，代理消息会被视为机器人消息并被丢弃，除非 `allowBots=true` - 当你设置 Status 或活动字段，或者启用自动在线状态时，会应用在线状态更新。 + 当你设置状态或活动字段，或启用自动在线状态时，会应用在线状态更新。 - 仅 Status 示例： + 仅状态示例： ```json5 { @@ -843,7 +843,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 流式传输示例： + 直播示例： ```json5 { @@ -859,12 +859,12 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 活动类型映射： - - 0：正在玩 - - 1：正在流式传输（需要 `activityUrl`） - - 2：正在听 - - 3：正在观看 - - 4：自定义（使用活动文本作为状态状态；表情符号可选） - - 5：正在竞赛 + - 0: 正在玩 + - 1: 正在直播（需要 `activityUrl`） + - 2: 正在听 + - 3: 正在观看 + - 4: 自定义（使用活动文本作为状态内容；表情符号可选） + - 5: 正在竞赛 自动在线状态示例（运行时健康信号）： @@ -883,7 +883,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 自动在线状态会将运行时可用性映射到 Discord Status：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： + 自动在线状态会将运行时可用性映射到 Discord 状态：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -891,8 +891,8 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - - Discord 支持在私信中基于按钮处理批准，也可以选择在来源渠道中发布批准提示。 + + Discord 支持在私信中通过按钮处理审批，也可以选择在发起审批的频道中发布审批提示。 配置路径： @@ -901,25 +901,27 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` - 当 `enabled` 未设置或为 `"auto"`，并且至少可以从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个批准人时，Discord 会自动启用原生 exec 批准。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec 批准人。设置 `enabled: false` 可显式禁用 Discord 作为原生批准客户端。 + 当 `enabled` 未设置或为 `"auto"`，且可以从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出至少一个审批人时，Discord 会自动启用原生 exec 审批。Discord 不会从频道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec 审批人。设置 `enabled: false` 可明确禁用 Discord 作为原生审批客户端。 - 当 `target` 为 `channel` 或 `both` 时，批准提示会在渠道中可见。只有解析出的批准人可以使用按钮；其他用户会收到临时拒绝提示。批准提示包含命令文本，因此只应在受信任渠道中启用渠道投递。如果无法从会话键派生渠道 ID，OpenClaw 会回退到私信投递。 + 对于 `/diagnostics` 和 `/export-trajectory` 等敏感的仅所有者群组命令，OpenClaw 会私下发送审批提示和最终结果。当调用方所有者有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 - Discord 还会渲染其他聊天渠道使用的共享批准按钮。原生 Discord 适配器主要添加批准人私信路由和渠道扇出。 - 当这些按钮存在时，它们就是主要的批准 UX；OpenClaw - 只有在工具结果表明聊天批准不可用或手动批准是唯一路径时， + 当 `target` 为 `channel` 或 `both` 时，审批提示会在频道中可见。只有解析出的审批人可以使用按钮；其他用户会收到临时拒绝。审批提示包含命令文本，因此只应在可信频道中启用频道投递。如果无法从会话键派生频道 ID，OpenClaw 会回退到私信投递。 + + Discord 也会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要增加审批人私信路由和频道扇出。 + 当这些按钮存在时，它们是主要审批 UX；OpenClaw + 只有在工具结果说明聊天审批不可用，或手动审批是唯一路径时， 才应包含手动 `/approve` 命令。 - Gateway 网关身份验证和批准解析遵循共享 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。批准默认在 30 分钟后过期。 + Gateway 网关认证和审批解析遵循共享 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。审批默认在 30 分钟后过期。 - 请参阅 [Exec 批准](/zh-CN/tools/exec-approvals)。 + 请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)。 ## 工具和操作门控 -Discord 消息操作包括消息、渠道管理、审核、在线状态和元数据操作。 +Discord 消息操作包括消息、频道管理、审核、在线状态和元数据操作。 核心示例： @@ -928,26 +930,26 @@ Discord 消息操作包括消息、渠道管理、审核、在线状态和元数 - 审核：`timeout`、`kick`、`ban` - 在线状态：`setPresence` -`event-create` 操作接受可选的 `image` 参数（URL 或本地文件路径）来设置预定事件封面图。 +`event-create` 操作接受可选的 `image` 参数（URL 或本地文件路径），用于设置计划事件封面图。 操作门控位于 `channels.discord.actions.*` 下。 默认门控行为： -| 操作组 | 默认值 | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 已启用 | -| roles | 已禁用 | -| moderation | 已禁用 | -| presence | 已禁用 | +| 操作组 | 默认 | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 启用 | +| roles | 禁用 | +| moderation | 禁用 | +| presence | 禁用 | -## Components v2 UI +## 组件 v2 UI -OpenClaw 使用 Discord components v2 处理 exec 批准和跨上下文标记。Discord 消息操作也可以接受 `components` 作为自定义 UI（高级用法；需要通过 discord 工具构造组件载荷），而旧版 `embeds` 仍可用，但不推荐使用。 +OpenClaw 使用 Discord 组件 v2 处理 exec 审批和跨上下文标记。Discord 消息操作也可以接受用于自定义 UI 的 `components`（高级；需要通过 discord 工具构造组件载荷），而旧版 `embeds` 仍然可用，但不推荐。 - `channels.discord.ui.components.accentColor` 设置 Discord 组件容器使用的强调色（十六进制）。 - 使用 `channels.discord.accounts..ui.components.accentColor` 按账号设置。 -- 当存在 components v2 时，会忽略 `embeds`。 +- 当存在组件 v2 时，会忽略 `embeds`。 示例： @@ -967,20 +969,20 @@ OpenClaw 使用 Discord components v2 处理 exec 批准和跨上下文标记。 ## 语音 -Discord 有两个不同的语音表面：实时 **语音渠道**（连续对话）和 **语音消息附件**（波形预览格式）。Gateway 网关同时支持两者。 +Discord 有两个不同的语音表面：实时**语音频道**（连续对话）和**语音消息附件**（波形预览格式）。Gateway 网关同时支持两者。 -### 语音渠道 +### 语音频道 -设置清单： +设置检查清单： 1. 在 Discord Developer Portal 中启用 Message Content Intent。 -2. 使用角色/用户 allowlist 时，启用 Server Members Intent。 -3. 使用 `bot` 和 `applications.commands` scopes 邀请 bot。 -4. 在目标语音渠道中授予 Connect、Speak、Send Messages 和 Read Message History。 +2. 当使用角色/用户 allowlist 时，启用 Server Members Intent。 +3. 使用 `bot` 和 `applications.commands` 范围邀请机器人。 +4. 在目标语音频道中授予 Connect、Speak、Send Messages 和 Read Message History 权限。 5. 启用原生命令（`commands.native` 或 `channels.discord.commands.native`）。 6. 配置 `channels.discord.voice`。 -使用 `/vc join|leave|status` 控制会话。该命令使用账号默认智能体，并遵循与其他 Discord 命令相同的 allowlist 和组策略规则。 +使用 `/vc join|leave|status` 控制会话。该命令使用账号默认智能体，并遵循与其他 Discord 命令相同的 allowlist 和群组策略规则。 ```bash /vc join channel: @@ -1017,22 +1019,22 @@ Discord 有两个不同的语音表面：实时 **语音渠道**（连续对话 注意： -- `voice.tts` 仅为语音播放覆盖 `messages.tts`。 -- `voice.model` 仅为 Discord 语音渠道响应覆盖所用的 LLM。留空则继承路由后的智能体模型。 -- STT 使用 `tools.media.audio`；`voice.model` 不影响转录。 -- 语音转录轮次从 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者说话者无法访问仅限所有者的工具（例如 `gateway` 和 `cron`）。 +- `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`。 +- `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 的上游填充修复，该修复关闭了 discord.js issue #11419。 +- 如果未设置，`@discordjs/voice` 的默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 +- 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 入口和路由发送。 +- 转写文本会通过常规 Discord 入口和路由发送。 - 设置 `voice.model` 时，它仅覆盖此语音渠道轮次的响应 LLM。 - `voice.tts` 会合并覆盖 `messages.tts`；生成的音频会在已加入的渠道中播放。 @@ -1040,10 +1042,10 @@ Discord 有两个不同的语音表面：实时 **语音渠道**（连续对话 ### 语音消息 -Discord 语音消息会显示波形预览，并要求 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要 Gateway 网关主机上的 `ffmpeg` 和 `ffprobe` 来检查和转换。 +Discord 语音消息会显示波形预览，并且需要 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要 Gateway 网关主机上有 `ffmpeg` 和 `ffprobe` 来检查和转换。 - 提供一个**本地文件路径**（URL 会被拒绝）。 -- 省略文本内容（Discord 拒绝在同一 payload 中同时发送文本和语音消息）。 +- 省略文本内容（Discord 会拒绝同一 payload 中同时包含文本和语音消息）。 - 接受任意音频格式；OpenClaw 会按需转换为 OGG/Opus。 ```bash @@ -1053,22 +1055,22 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## 故障排除 - + - 启用 Message Content Intent - - 当你依赖用户/成员解析时，启用 Server Members Intent - - 更改 intent 后重启 Gateway 网关 + - 当你依赖用户/成员解析时启用 Server Members Intent + - 更改 intents 后重启 Gateway 网关 - + - 验证 `groupPolicy` - - 验证 `channels.discord.guilds` 下的服务器允许列表 - - 如果存在服务器 `channels` 映射，则仅允许列出的渠道 + - 验证 `channels.discord.guilds` 下的 guild allowlist + - 如果存在 guild `channels` 映射，则只允许列出的渠道 - 验证 `requireMention` 行为和提及模式 - 有用的检查： + 有用检查： ```bash openclaw doctor @@ -1078,16 +1080,16 @@ openclaw logs --follow - + 常见原因： - - `groupPolicy="allowlist"` 但没有匹配的服务器/渠道允许列表 - - `requireMention` 配置在了错误位置（必须位于 `channels.discord.guilds` 或渠道条目下） - - 发送者被服务器/渠道 `users` 允许列表阻止 + - `groupPolicy="allowlist"` 但没有匹配的 guild/channel allowlist + - `requireMention` 配置在错误位置（必须位于 `channels.discord.guilds` 或渠道条目下） + - 发送者被 guild/channel `users` allowlist 阻止 - + 典型日志： @@ -1127,13 +1129,12 @@ openclaw logs --follow } ``` - 对慢监听器设置使用 `eventQueue.listenerTimeout`，仅当你想为排队的智能体轮次设置单独的安全阀时， - 才使用 `inboundWorker.runTimeoutMs`。 + 使用 `eventQueue.listenerTimeout` 处理较慢的监听器设置；仅当你想为排队的智能体轮次设置单独安全阀时，才使用 `inboundWorker.runTimeoutMs`。 - - OpenClaw 会在连接前获取 Discord `/gateway/bot` 元数据。瞬时失败会回退到 Discord 默认 Gateway 网关 URL，并在日志中进行限速记录。 + + OpenClaw 会在连接前获取 Discord `/gateway/bot` 元数据。短暂失败会回退到 Discord 的默认 Gateway 网关 URL，并在日志中进行速率限制。 元数据超时旋钮： @@ -1144,14 +1145,14 @@ openclaw logs --follow - + `channels status --probe` 权限检查仅适用于数字渠道 ID。 - 如果你使用 slug 键，运行时匹配仍可工作，但 probe 无法完全验证权限。 + 如果你使用 slug 键，运行时匹配仍可工作，但 probe 无法完整验证权限。 - + - 私信已禁用：`channels.discord.dm.enabled=false` - 私信策略已禁用：`channels.discord.dmPolicy="disabled"`（旧版：`channels.discord.dm.policy`） @@ -1159,23 +1160,23 @@ openclaw logs --follow - - 默认情况下，bot 作者消息会被忽略。 + + 默认会忽略由机器人发出的消息。 - 如果你设置 `channels.discord.allowBots=true`，请使用严格的提及和允许列表规则以避免循环行为。 - 推荐使用 `channels.discord.allowBots="mentions"`，这样仅接受提及该 bot 的 bot 消息。 + 如果你设置 `channels.discord.allowBots=true`，请使用严格的提及和 allowlist 规则来避免循环行为。 + 建议使用 `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 接收历史进行对比 @@ -1184,48 +1185,48 @@ 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` -- 入站 Worker：`inboundWorker.runTimeoutMs` +- 入站 worker：`inboundWorker.runTimeoutMs` - 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.*` -- presence：`activity`、`status`、`activityType`、`activityUrl` +- 在线状态：`activity`、`status`、`activityType`、`activityUrl` - UI：`ui.components.accentColor` - 功能：`threadBindings`、顶层 `bindings[]`（`type: "acp"`）、`pluralkit`、`execApprovals`、`intents`、`agentComponents`、`heartbeat`、`responsePrefix` -## 安全和运维 +## 安全与运维 -- 将 bot token 视为密钥（在受监督环境中推荐使用 `DISCORD_BOT_TOKEN`）。 +- 将机器人 token 视为密钥（在受监管环境中首选 `DISCORD_BOT_TOKEN`）。 - 授予最小权限的 Discord 权限。 -- 如果命令部署/状态过期，请重启 Gateway 网关并使用 `openclaw channels status --probe` 重新检查。 +- 如果命令部署/状态过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。 -## 相关内容 +## 相关 - + 将 Discord 用户配对到 Gateway 网关。 - - 群聊和允许列表行为。 + + 群聊和 allowlist 行为。 - + 将入站消息路由到智能体。 - + 威胁模型和加固。 - - 将服务器和渠道映射到智能体。 + + 将 guild 和渠道映射到智能体。 原生命令行为。 diff --git a/docs/zh-CN/tools/exec-approvals-advanced.md b/docs/zh-CN/tools/exec-approvals-advanced.md index 271f6b4dc..955781ed0 100644 --- a/docs/zh-CN/tools/exec-approvals-advanced.md +++ b/docs/zh-CN/tools/exec-approvals-advanced.md @@ -1,27 +1,27 @@ --- read_when: - - 配置安全二进制目录或自定义安全二进制目录配置文件 + - 配置 safe bins 或自定义 safe-bin 配置文件 - 将审批转发到 Slack/Discord/Telegram 或其他聊天渠道 - 为渠道实现原生审批客户端 -summary: 高级 exec 审批：安全可执行文件、解释器绑定、审批转发、原生交付 +summary: 高级 exec 审批：安全二进制文件、解释器绑定、审批转发、原生交付 title: 执行审批 — 高级 x-i18n: - generated_at: "2026-04-28T23:40:22Z" + generated_at: "2026-04-29T00:30:47Z" model: gpt-5.5 provider: openai - source_hash: c134fbb417dab5b3642dc5a98d4076eef3825a2114b87f396e73271474882deb + source_hash: ad31e606eb8d0a5d99c59a53feee82212ee7d4fad7346c183315d6257a41cf43 source_path: tools/exec-approvals-advanced.md workflow: 16 --- -高级 exec 审批主题：`safeBins` 快速路径、解释器/运行时绑定，以及向聊天渠道转发审批（包括原生投递）。核心策略和审批流程见 [Exec 审批](/zh-CN/tools/exec-approvals)。 +高级 exec 批准主题：`safeBins` 快速路径、解释器/运行时绑定，以及将批准转发到聊天渠道（包括原生投递）。关于核心策略和批准流程，请参阅 [Exec 批准](/zh-CN/tools/exec-approvals)。 -## 安全二进制文件（仅限 stdin） +## 安全二进制文件（仅 stdin） -`tools.exec.safeBins` 定义了一小组**仅限 stdin** 的二进制文件（例如 `cut`），它们可以在允许列表模式下运行，**无需**显式允许列表条目。安全二进制文件会拒绝位置文件参数和类似路径的 token，因此只能处理传入的流。请将其视为流过滤器的窄范围快速路径，而不是通用信任列表。 +`tools.exec.safeBins` 定义了一小组**仅 stdin** 的二进制文件（例如 `cut`），它们可以在允许列表模式下运行，**无需**显式允许列表条目。安全二进制文件会拒绝位置文件参数和类似路径的 token，因此它们只能处理传入流。请将其视为流过滤器的窄范围快速路径，而不是通用信任列表。 -**不要**将解释器或运行时二进制文件（例如 `python3`、`node`、`ruby`、`bash`、`sh`、`zsh`）添加到 `safeBins`。如果某个命令按设计可以求值代码、执行子命令或读取文件，请优先使用显式允许列表条目，并保持审批提示启用。自定义安全二进制文件必须在 `tools.exec.safeBinProfiles.` 中定义显式 profile。 +**不要**将解释器或运行时二进制文件（例如 `python3`、`node`、`ruby`、`bash`、`sh`、`zsh`）添加到 `safeBins`。如果某个命令按设计可以求值代码、执行子命令或读取文件，请优先使用显式允许列表条目，并保持批准提示启用。自定义安全二进制文件必须在 `tools.exec.safeBinProfiles.` 中定义显式配置档案。 默认安全二进制文件： @@ -32,13 +32,13 @@ x-i18n: [//]: # "SAFE_BIN_DEFAULTS:END" -`grep` 和 `sort` 不在默认列表中。如果你选择启用，请为它们的非 stdin 工作流保留显式允许列表条目。对于安全二进制文件模式下的 `grep`，请用 `-e`/`--regexp` 提供 pattern；位置 pattern 形式会被拒绝，因此文件操作数无法伪装成有歧义的位置参数。 +`grep` 和 `sort` 不在默认列表中。如果你选择加入，请为它们的非 stdin 工作流保留显式允许列表条目。对于安全二进制文件模式下的 `grep`，请使用 `-e`/`--regexp` 提供模式；位置模式形式会被拒绝，因此文件操作数不能伪装成含糊的位置参数。 -### Argv 验证和被拒绝的 flag +### Argv 验证和被拒绝的标志 -验证只根据 argv 形状确定（不检查主机文件系统中是否存在），这可避免允许/拒绝差异产生文件存在性预言机行为。面向文件的选项会被默认安全二进制文件拒绝；长选项按失败关闭方式验证（未知 flag 和有歧义的缩写会被拒绝）。 +验证仅根据 argv 形状确定（不检查主机文件系统是否存在），这可以防止通过允许/拒绝差异产生文件存在性探测行为。面向文件的选项会被默认安全二进制文件拒绝；长选项以失败关闭方式验证（未知标志和含糊缩写会被拒绝）。 -按安全二进制文件 profile 列出的被拒绝 flag： +按安全二进制文件配置档案划分的被拒绝标志： [//]: # "SAFE_BIN_DENIED_FLAGS:START" @@ -49,144 +49,148 @@ x-i18n: [//]: # "SAFE_BIN_DENIED_FLAGS:END" -安全二进制文件还会在执行时强制将 argv token 当作**字面文本**处理（不进行 glob 展开，也不展开 `$VARS`），仅适用于 stdin-only segment，因此 `*` 或 `$HOME/...` 之类的 pattern 不能用于夹带文件读取。 +安全二进制文件还会强制 argv token 在执行时被视为**字面文本**（不进行 glob 展开，也不展开 `$VARS`），用于仅 stdin 的片段，因此不能用 `*` 或 `$HOME/...` 这类模式来夹带文件读取。 ### 受信任的二进制文件目录 -安全二进制文件必须从受信任的二进制文件目录解析（系统默认值加可选的 `tools.exec.safeBinTrustedDirs`）。`PATH` 条目绝不会自动受信任。默认受信任目录有意保持最小：`/bin`、`/usr/bin`。如果你的安全二进制可执行文件位于包管理器/用户路径中（例如 `/opt/homebrew/bin`、`/usr/local/bin`、`/opt/local/bin`、`/snap/bin`），请将它们显式添加到 `tools.exec.safeBinTrustedDirs`。 +安全二进制文件必须从受信任的二进制文件目录解析（系统默认值加上可选的 `tools.exec.safeBinTrustedDirs`）。`PATH` 条目绝不会被自动信任。默认受信任目录刻意保持最小：`/bin`、`/usr/bin`。如果你的安全二进制文件可执行文件位于包管理器/用户路径中（例如 `/opt/homebrew/bin`、`/usr/local/bin`、`/opt/local/bin`、`/snap/bin`），请将它们显式添加到 `tools.exec.safeBinTrustedDirs`。 ### Shell 链接、包装器和多路复用器 -当每个顶层 segment 都满足允许列表（包括安全二进制文件或 Skills 自动允许）时，允许 shell 链接（`&&`、`||`、`;`）。允许列表模式仍不支持重定向。命令替换（`$()` / 反引号）会在允许列表解析期间被拒绝，包括在双引号内部；如果需要字面 `$()` 文本，请使用单引号。 +当每个顶层片段都满足允许列表（包括安全二进制文件或 Skills 自动允许）时，允许 shell 链接（`&&`、`||`、`;`）。允许列表模式仍不支持重定向。命令替换（`$()` / 反引号）会在允许列表解析期间被拒绝，包括在双引号内部；如果你需要字面 `$()` 文本，请使用单引号。 -在 macOS 配套应用审批中，包含 shell 控制或展开语法（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、`)`）的原始 shell 文本会被视为允许列表未命中，除非 shell 二进制文件本身在允许列表中。 +在 macOS 配套应用批准中，包含 shell 控制或展开语法（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、`)`）的原始 shell 文本会被视为允许列表未命中，除非 shell 二进制文件本身已被加入允许列表。 -对于 shell 包装器（`bash|sh|zsh ... -c/-lc`），请求范围的 env 覆盖会缩减为一小组显式允许列表（`TERM`、`LANG`、`LC_*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`）。 +对于 shell 包装器（`bash|sh|zsh ... -c/-lc`），请求范围的环境覆盖会缩减为一小组显式允许列表（`TERM`、`LANG`、`LC_*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`）。 -在允许列表模式下，对于 `allow-always` 决策，已知分发包装器（`env`、`nice`、`nohup`、`stdbuf`、`timeout`）会持久化内部可执行文件路径，而不是包装器路径。Shell 多路复用器（`busybox`、`toybox`）会以相同方式对 shell applet（`sh`、`ash` 等）进行解包。如果包装器或多路复用器无法安全解包，则不会自动持久化允许列表条目。 +对于允许列表模式下的 `allow-always` 决策，已知分发包装器（`env`、`nice`、`nohup`、`stdbuf`、`timeout`）会持久化内部可执行文件路径，而不是包装器路径。Shell 多路复用器（`busybox`、`toybox`）会以相同方式对 shell applet（`sh`、`ash` 等）进行解包。如果无法安全解包包装器或多路复用器，则不会自动持久化允许列表条目。 -如果你将 `python3` 或 `node` 等解释器加入允许列表，建议使用 `tools.exec.strictInlineEval=true`，这样内联 eval 仍需要显式审批。在严格模式下，`allow-always` 仍可持久化良性的解释器/脚本调用，但内联 eval 载体不会自动持久化。 +如果你将 `python3` 或 `node` 这类解释器加入允许列表，请优先设置 `tools.exec.strictInlineEval=true`，这样内联求值仍需要显式批准。在严格模式下，`allow-always` 仍可持久化良性的解释器/脚本调用，但内联求值载体不会自动持久化。 ### 安全二进制文件与允许列表 -| 主题 | `tools.exec.safeBins` | 允许列表（`exec-approvals.json`） | +| 主题 | `tools.exec.safeBins` | 允许列表（`exec-approvals.json`） | | ---------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------- | -| 目标 | 自动允许窄范围 stdin 过滤器 | 显式信任特定可执行文件 | -| 匹配类型 | 可执行文件名称 + 安全二进制文件 argv 策略 | 已解析的可执行文件路径 glob，或通过 PATH 调用的命令使用裸命令名 glob | -| 参数范围 | 受安全二进制文件 profile 和字面 token 规则限制 | 仅匹配路径；参数除此之外由你负责 | -| 典型示例 | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, 自定义 CLI | -| 最佳用途 | 管道中的低风险文本转换 | 任何行为更广或有副作用的工具 | +| 目标 | 自动允许窄范围 stdin 过滤器 | 显式信任特定可执行文件 | +| 匹配类型 | 可执行文件名称 + 安全二进制文件 argv 策略 | 已解析可执行文件路径 glob，或 PATH 调用命令的裸命令名 glob | +| 参数范围 | 受安全二进制文件配置档案和字面 token 规则限制 | 仅路径匹配；参数在其他方面由你负责 | +| 典型示例 | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, 自定义 CLI | +| 最佳用途 | 管道中的低风险文本转换 | 任何具有更广行为或副作用的工具 | 配置位置： -- `safeBins` 来自配置（`tools.exec.safeBins` 或每智能体 `agents.list[].tools.exec.safeBins`）。 -- `safeBinTrustedDirs` 来自配置（`tools.exec.safeBinTrustedDirs` 或每智能体 `agents.list[].tools.exec.safeBinTrustedDirs`）。 -- `safeBinProfiles` 来自配置（`tools.exec.safeBinProfiles` 或每智能体 `agents.list[].tools.exec.safeBinProfiles`）。每智能体 profile 键会覆盖全局键。 +- `safeBins` 来自配置（`tools.exec.safeBins` 或按智能体设置的 `agents.list[].tools.exec.safeBins`）。 +- `safeBinTrustedDirs` 来自配置（`tools.exec.safeBinTrustedDirs` 或按智能体设置的 `agents.list[].tools.exec.safeBinTrustedDirs`）。 +- `safeBinProfiles` 来自配置（`tools.exec.safeBinProfiles` 或按智能体设置的 `agents.list[].tools.exec.safeBinProfiles`）。按智能体设置的配置档案键会覆盖全局键。 - 允许列表条目位于主机本地 `~/.openclaw/exec-approvals.json` 的 `agents..allowlist` 下（或通过 Control UI / `openclaw approvals allowlist ...`）。 -- 当解释器/运行时 bin 出现在 `safeBins` 中却没有显式 profile 时，`openclaw security audit` 会以 `tools.exec.safe_bins_interpreter_unprofiled` 发出警告。 -- `openclaw doctor --fix` 可以把缺失的自定义 `safeBinProfiles.` 条目搭建为 `{}`（之后请审查并收紧）。解释器/运行时 bin 不会自动搭建。 +- 当解释器/运行时二进制文件出现在 `safeBins` 中但没有显式配置档案时，`openclaw security audit` 会用 `tools.exec.safe_bins_interpreter_unprofiled` 发出警告。 +- `openclaw doctor --fix` 可以将缺失的自定义 `safeBinProfiles.` 条目脚手架生成为 `{}`（之后请审查并收紧）。解释器/运行时二进制文件不会被自动脚手架生成。 -自定义 profile 示例： +自定义配置档案示例： __OC_I18N_900000__ -如果你显式选择把 `jq` 加入 `safeBins`，OpenClaw 仍会在安全二进制文件模式下拒绝 `env` builtin，因此 `jq -n env` 无法在没有显式允许列表路径或审批提示的情况下转储主机进程环境。 +如果你显式将 `jq` 加入 `safeBins`，OpenClaw 仍会在安全二进制文件模式下拒绝 `env` 内建命令，因此 `jq -n env` 不能在没有显式允许列表路径或批准提示的情况下转储主机进程环境。 ## 解释器/运行时命令 -由审批支持的解释器/运行时运行有意保持保守： +由批准支持的解释器/运行时运行刻意保持保守： - 始终绑定精确的 argv/cwd/env 上下文。 - 直接 shell 脚本和直接运行时文件形式会尽力绑定到一个具体的本地文件快照。 - 仍解析到一个直接本地文件的常见包管理器包装器形式（例如 `pnpm exec`、`pnpm node`、`npm exec`、`npx`）会在绑定前解包。 -- 如果 OpenClaw 无法为某个解释器/运行时命令精确识别一个具体本地文件（例如包脚本、eval 形式、运行时特定 loader 链，或有歧义的多文件形式），由审批支持的执行会被拒绝，而不是声称具备它实际没有的语义覆盖。 -- 对于这些工作流，请优先使用沙箱隔离、独立的主机边界，或操作员接受更广泛运行时语义的显式受信任允许列表/完整工作流。 +- 如果 OpenClaw 无法为解释器/运行时命令准确识别一个具体的本地文件（例如包脚本、eval 形式、运行时特定加载器链，或含糊的多文件形式），由批准支持的执行会被拒绝，而不是声称拥有它并不具备的语义覆盖。 +- 对于这些工作流，请优先使用沙箱隔离、单独的主机边界，或显式受信任的允许列表/完整工作流，由操作者接受更宽泛的运行时语义。 -需要审批时，exec 工具会立即返回一个审批 ID。使用该 ID 关联后续系统事件（`Exec finished` / `Exec denied`）。如果在超时前没有收到决策，请求会被视为审批超时，并以拒绝原因呈现。 +需要批准时，exec 工具会立即返回一个批准 id。使用该 id 关联后续系统事件（`Exec finished` / `Exec denied`）。如果超时前没有决策到达，请求会被视为批准超时，并作为拒绝原因呈现。 ### 后续投递行为 -获批的 async exec 完成后，OpenClaw 会向同一会话发送一个后续 `agent` turn。 +批准的异步 exec 完成后，OpenClaw 会向同一会话发送一个后续 `agent` 轮次。 - 如果存在有效的外部投递目标（可投递渠道加目标 `to`），后续投递会使用该渠道。 -- 在没有外部目标的 webchat-only 或内部会话流程中，后续投递仅保留在会话内（`deliver: false`）。 -- 如果调用方显式要求严格外部投递，但没有可解析的外部渠道，请求会以 `INVALID_REQUEST` 失败。 -- 如果启用了 `bestEffortDeliver` 且无法解析外部渠道，投递会降级为仅会话内，而不是失败。 +- 在仅 webchat 或没有外部目标的内部会话流程中，后续投递会保持仅会话（`deliver: false`）。 +- 如果调用方显式请求严格外部投递，但没有可解析的外部渠道，请求会以 `INVALID_REQUEST` 失败。 +- 如果启用了 `bestEffortDeliver` 且无法解析外部渠道，投递会降级为仅会话，而不是失败。 -## 向聊天渠道转发审批 +## 将批准转发到聊天渠道 -你可以将 exec 审批提示转发到任意聊天渠道（包括插件渠道），并用 `/approve` 审批它们。这会使用普通的出站投递管线。 +你可以将 exec 批准提示转发到任何聊天渠道（包括插件渠道），并用 `/approve` 批准它们。这会使用正常的出站投递管道。 配置： __OC_I18N_900001__ 在聊天中回复： __OC_I18N_900002__ -`/approve` 命令同时处理 exec 审批和插件审批。如果 ID 与待处理的 exec 审批不匹配，它会自动改为检查插件审批。 +`/approve` 命令同时处理 exec 批准和插件批准。如果 ID 不匹配任何待处理的 exec 批准，它会自动改为检查插件批准。 -### 插件审批转发 +### 插件批准转发 -插件审批转发使用与 exec 审批相同的投递管线，但在 `approvals.plugin` 下有自己的独立配置。启用或禁用其中一个不会影响另一个。 +插件批准转发使用与 exec 批准相同的投递管道，但在 `approvals.plugin` 下拥有独立配置。启用或禁用其中一个不会影响另一个。 __OC_I18N_900003__ -配置形状与 `approvals.exec` 相同：`enabled`、`mode`、`agentFilter`、`sessionFilter` 和 `targets` 的工作方式一致。 +配置形状与 `approvals.exec` 相同：`enabled`、`mode`、`agentFilter`、`sessionFilter` 和 `targets` 的工作方式相同。 -支持共享交互式回复的渠道会为 exec 和插件审批渲染相同的审批按钮。没有共享交互式 UI 的渠道会回退到纯文本和 `/approve` 指令。 +支持共享交互式回复的渠道会为 exec 和插件批准呈现相同的批准按钮。没有共享交互式 UI 的渠道会回退为带 `/approve` 说明的纯文本。 -### 任意渠道中的同聊天审批 +### 任意渠道上的同聊天批准 -当 exec 或插件审批请求来自可投递的聊天界面时，同一个聊天现在默认可以用 `/approve` 审批它。除了现有 Web UI 和终端 UI 流程，这也适用于 Slack、Matrix 和 Microsoft Teams 等渠道。 +当 exec 或插件批准请求源自可投递聊天表面时，默认情况下，同一聊天现在可以用 `/approve` 批准它。除现有的 Web UI 和终端 UI 流程外，这也适用于 Slack、Matrix 和 Microsoft Teams 等渠道。 -这个共享文本命令路径使用该会话的普通渠道认证模型。如果发起聊天已经可以发送命令并接收回复，审批请求就不再需要单独的原生投递适配器来保持待处理状态。 +这个共享文本命令路径使用该会话的正常渠道认证模型。如果发起聊天已经可以发送命令并接收回复，批准请求就不再需要单独的原生投递适配器来保持待处理状态。 -Discord 和 Telegram 也支持同聊天 `/approve`，但即使禁用了原生审批投递，这些渠道仍会使用其解析出的审批者列表进行授权。 +Discord 和 Telegram 也支持同聊天 `/approve`，但即使原生批准投递已禁用，这些渠道仍会使用其已解析的批准者列表进行授权。 -对于 Telegram 和其他直接调用 Gateway 网关的原生审批客户端，此回退有意限制在“找不到审批”的失败场景。真实的 exec 审批拒绝/错误不会静默重试为插件审批。 +对于 Telegram 和其他直接调用 Gateway 网关的原生批准客户端，此回退刻意限定为“未找到批准”失败。真实的 exec 批准拒绝/错误不会静默重试为插件批准。 -### 原生审批投递 +### 原生批准投递 -某些渠道也可以充当原生审批客户端。原生客户端在共享同聊天 `/approve` 流程之上，增加审批者私信、来源聊天 fanout，以及渠道特定的交互式审批 UX。 +某些渠道也可以充当原生批准客户端。原生客户端会在共享的同聊天 `/approve` 流程之上，添加批准者私信、源聊天扇出和渠道特定的交互式批准 UX。 -当原生审批卡片/按钮可用时，该原生 UI 是主要的面向智能体路径。智能体不应再回显重复的普通聊天 `/approve` 命令，除非工具结果表明聊天审批不可用，或者手动审批是唯一剩余路径。 +当原生批准卡片/按钮可用时，该原生 UI 是面向智能体的主要路径。除非工具结果说明聊天批准不可用，或手动批准是唯一剩余路径，否则智能体不应再回显重复的纯聊天 +`/approve` 命令。 通用模型： -- 主机 exec 策略仍决定是否需要 exec 审批 -- `approvals.exec` 控制将审批提示转发到其他聊天目的地 -- `channels..execApprovals` 控制该渠道是否作为原生审批客户端 +- 主机 exec 策略仍决定是否需要 exec 批准 +- `approvals.exec` 控制将批准提示转发到其他聊天目标 +- `channels..execApprovals` 控制该渠道是否作为原生批准客户端 -当以下条件全部为真时，原生审批客户端会自动启用私信优先投递： +当以下条件全部为真时，原生批准客户端会自动启用私信优先投递： -- 该渠道支持原生审批投递 -- 可以从显式 `execApprovals.approvers` 或所有者身份（例如 `commands.ownerAllowFrom`）解析审批人 +- 该渠道支持原生批准投递 +- 可以从显式的 `execApprovals.approvers` 或所有者身份（例如 `commands.ownerAllowFrom`）解析批准者 - `channels..execApprovals.enabled` 未设置或为 `"auto"` -设置 `enabled: false` 可显式禁用原生审批客户端。当能解析审批人时，设置 `enabled: true` 可强制启用它。公开来源聊天投递仍通过 `channels..execApprovals.target` 显式配置。 +设置 `enabled: false` 可显式禁用原生批准客户端。设置 `enabled: true` 可在批准者可解析时强制启用它。公开的原始聊天投递仍通过 +`channels..execApprovals.target` 显式配置。 -常见问题：[为什么聊天审批有两套 exec 审批配置？](/help/faq-first-run#why-are-there-two-exec-approval-configs-for-chat-approvals) +常见问题：[为什么聊天批准有两个 exec 批准配置？](/help/faq-first-run#why-are-there-two-exec-approval-configs-for-chat-approvals) - Discord：`channels.discord.execApprovals.*` - Slack：`channels.slack.execApprovals.*` - Telegram：`channels.telegram.execApprovals.*` -这些原生审批客户端在共享的同聊天 `/approve` 流程和共享审批按钮之上，增加了私信路由和可选的渠道扇出。 +这些原生批准客户端在共享的同一聊天 `/approve` 流程和共享批准按钮之上，添加了私信路由和可选的渠道扇出。 共享行为： -- Slack、Matrix、Microsoft Teams 以及类似的可投递聊天使用常规渠道认证模型来处理同聊天 `/approve` -- 当原生审批客户端自动启用时，默认原生投递目标是审批人的私信 -- 对于 Discord 和 Telegram，只有解析出的审批人可以批准或拒绝 -- Discord 审批人可以显式指定（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断 -- Telegram 审批人可以显式指定（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断 -- Slack 审批人可以显式指定（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断 -- Slack 原生按钮会保留审批 ID 类型，因此 `plugin:` ID 可以解析插件审批，而不需要第二层 Slack 本地回退层 -- Matrix 原生私信/渠道路由和反应快捷操作同时处理 exec 与插件审批；插件授权仍来自 `channels.matrix.dm.allowFrom` -- Matrix 原生提示会在首个提示事件中包含 `com.openclaw.approval` 自定义事件内容，因此支持 OpenClaw 的 Matrix 客户端可以读取结构化审批状态，而普通客户端仍保留纯文本 `/approve` 回退 -- 请求者不需要是审批人 -- 当来源聊天已支持命令和回复时，可以直接用 `/approve` 审批 -- 原生 Discord 审批按钮按审批 ID 类型路由：`plugin:` ID 直接进入插件审批，其他所有 ID 进入 exec 审批 -- 原生 Telegram 审批按钮遵循与 `/approve` 相同的有界 exec 到插件回退 -- 当原生 `target` 启用来源聊天投递时，审批提示会包含命令文本 -- 待处理的 exec 审批默认在 30 分钟后过期 -- 如果没有操作员 UI 或已配置的审批客户端可以接受该请求，提示会回退到 `askFallback` +- Slack、Matrix、Microsoft Teams 以及类似的可投递聊天，会对同一聊天 `/approve` 使用普通渠道认证模型 +- 当原生批准客户端自动启用时，默认的原生投递目标是批准者私信 +- 对于 Discord 和 Telegram，只有已解析的批准者可以批准或拒绝 +- Discord 批准者可以是显式的（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断 +- Telegram 批准者可以是显式的（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断 +- Slack 批准者可以是显式的（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断 +- Slack 原生按钮会保留批准 ID 类型，因此 `plugin:` ID 可以解析插件批准，而无需第二层 Slack 本地回退 +- Matrix 原生私信/渠道路由和回应快捷方式同时处理 exec 和插件批准；插件授权仍来自 `channels.matrix.dm.allowFrom` +- Matrix 原生提示会在第一个提示事件中包含 `com.openclaw.approval` 自定义事件内容，因此支持 OpenClaw 的 Matrix 客户端可以读取结构化批准状态，而普通客户端仍保留纯文本 `/approve` 回退 +- 请求者不需要是批准者 +- 当发起聊天已经支持命令和回复时，可以直接用 `/approve` 批准 +- 原生 Discord 批准按钮会按批准 ID 类型路由：`plugin:` ID 直接进入插件批准，其他所有内容进入 exec 批准 +- 原生 Telegram 批准按钮遵循与 `/approve` 相同的有界 exec 到插件回退 +- 当原生 `target` 启用原始聊天投递时，批准提示会包含命令文本 +- 待处理的 exec 批准默认会在 30 分钟后过期 +- 如果没有任何操作员 UI 或已配置的批准客户端可以接收请求，提示会回退到 `askFallback` -Telegram 默认使用审批人私信（`target: "dm"`）。当你希望审批提示也出现在来源 Telegram 聊天/话题中时，可以切换为 `channel` 或 `both`。对于 Telegram 论坛话题，OpenClaw 会为审批提示和审批后的后续消息保留该话题。 +敏感的仅限所有者的群组命令（例如 `/diagnostics` 和 `/export-trajectory`）会对批准提示和最终结果使用私有所有者路由。OpenClaw 会先尝试在所有者运行命令的同一界面上使用私有路由。如果该界面没有私有所有者路由，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，因此当 Telegram 是已配置的主要私有界面时，Discord 群组命令仍可将批准和结果发送到所有者的 Telegram 私信。群聊只会收到一条简短确认。 + +Telegram 默认使用批准者私信（`target: "dm"`）。当你希望批准提示也显示在发起的 Telegram 聊天/话题中时，可以切换到 `channel` 或 `both`。对于 Telegram 论坛话题，OpenClaw 会为批准提示和批准后的后续消息保留该话题。 参见： @@ -197,13 +201,13 @@ Telegram 默认使用审批人私信（`target: "dm"`）。当你希望审批提 __OC_I18N_900004__ 安全说明： -- Unix socket 模式 `0600`，令牌存储在 `exec-approvals.json` 中。 -- 同 UID 对端检查。 -- 挑战/响应（nonce + HMAC token + request hash）+ 短 TTL。 +- Unix 套接字模式 `0600`，令牌存储在 `exec-approvals.json` 中。 +- 同一 UID 对端检查。 +- 质询/响应（nonce + HMAC 令牌 + 请求哈希）+ 短 TTL。 ## 相关内容 -- [Exec 审批](/zh-CN/tools/exec-approvals) — 核心策略和审批流程 +- [Exec 批准](/zh-CN/tools/exec-approvals) — 核心策略和批准流程 - [Exec 工具](/zh-CN/tools/exec) -- [提升模式](/zh-CN/tools/elevated) -- [Skills](/zh-CN/tools/skills) — 由技能支持的自动允许行为 +- [提权模式](/zh-CN/tools/elevated) +- [Skills](/zh-CN/tools/skills) — 由 Skills 支持的自动允许行为