From a0408fe705db06bbcdf7d719003e1480e1becff3 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 3 May 2026 18:13:08 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/discord.md | 510 +++++++++++++------------- docs/zh-CN/gateway/config-channels.md | 313 ++++++++-------- docs/zh-CN/tools/slash-commands.md | 293 ++++++++------- 3 files changed, 563 insertions(+), 553 deletions(-) diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index 8c894a61c..a69802521 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -4,15 +4,15 @@ read_when: summary: Discord 机器人支持状态、能力和配置 title: Discord x-i18n: - generated_at: "2026-05-02T09:29:19Z" + generated_at: "2026-05-03T18:10:25Z" model: gpt-5.5 provider: openai - source_hash: 42223982a8bfd288d29a1f402b37141557718a407537011956b878b91b894e62 + source_hash: 7a323cd9035265d43aaf60252503a4712264e316b7da175a063bff4ec51f777d source_path: channels/discord.md workflow: 16 --- -已可通过官方 Discord gateway 处理私信和服务器渠道。 +可通过官方 Discord 网关使用私信和服务器频道。 @@ -28,13 +28,13 @@ 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**。将 **Username** 设为你给 OpenClaw 智能体起的名字。 @@ -43,23 +43,23 @@ x-i18n: - **Message Content Intent**（必需） - **Server Members Intent**（推荐；角色允许列表和名称到 ID 匹配需要） - - **Presence Intent**（可选；仅在需要在线状态更新时使用） + - **Presence Intent**（可选；仅在需要状态更新时需要） - - 回到 **Bot** 页面上方并点击 **Reset Token**。 + + 回到 **Bot** 页面顶部，点击 **Reset Token**。 - 尽管名称如此，这会生成你的第一个 token，而不是在“重置”任何内容。 + 尽管名称如此，这会生成你的第一个令牌，并没有任何内容被“重置”。 - 复制该 token 并保存到某处。这是你的 **Bot Token**，你很快会用到它。 + 复制令牌并将其保存在某处。这是你的 **Bot Token**，稍后会用到。 - - 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用于将 bot 添加到你的服务器。 + + 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用于将机器人添加到你的服务器。 向下滚动到 **OAuth2 URL Generator** 并启用： @@ -77,31 +77,31 @@ x-i18n: - Attach Files - Add Reactions（可选） - 这是普通文本渠道的基线权限集。如果你计划在 Discord thread 中发帖，包括会创建或继续 thread 的论坛或媒体渠道工作流，也要启用 **Send Messages in Threads**。 - 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该能在 Discord 服务器中看到你的 bot。 + 这是普通文本频道的基线权限集。如果你计划在 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** - 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存，下一步你会将这三项都发送给 OpenClaw。 + 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存，下一步会将这三项发送给 OpenClaw。 - 为了让配对正常工作，Discord 需要允许你的 bot 给你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。 + 为了让配对正常工作，Discord 需要允许你的机器人向你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。 - 这会允许服务器成员（包括 bot）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持开启。如果你只计划使用服务器渠道，可以在配对后禁用私信。 + 这允许服务器成员（包括机器人）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持启用。如果你只计划使用服务器频道，可以在配对后禁用私信。 - - 你的 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 application/client 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 / 配置标签页。 + 在任何现有渠道（例如 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 值。参见[密钥管理](/zh-CN/gateway/secrets)。 - 对于多个 Discord bot，将每个 bot token 和 application ID 保存在对应账户下。顶层 `channels.discord.applicationId` 会由账户继承，因此只有在每个账户都应使用相同 application ID 时，才在此处设置。 + 对于多个 Discord 机器人，请将每个机器人令牌和应用 ID 放在其账户下。顶层 `channels.discord.applicationId` 会被账户继承，因此只有在每个账户都应使用同一个应用 ID 时才在那里设置。 ```json5 { @@ -187,14 +187,14 @@ 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 后备；否则第一个已启用账户获胜，重复账户会被报告为已禁用。 -对于高级出站调用（message 工具/渠道操作），显式的每次调用 `token` 会用于该调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍来自活动运行时快照中选定的账户。 +令牌解析会感知账户。配置中的令牌值优先于 env 回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 +如果两个已启用的 Discord 账户解析到同一个机器人令牌，OpenClaw 只会为该令牌启动一个网关监视器。来自配置的令牌优先于默认 env 回退；否则第一个启用的账户获胜，重复账户会被报告为已禁用。 +对于高级出站调用（消息工具/渠道操作），显式的逐调用 `token` 会用于该调用。这适用于发送以及读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍来自活动运行时快照中选定的账户。 ## 推荐：设置服务器工作区 -私信正常工作后，你可以将 Discord 服务器设置为完整工作区，其中每个渠道都有自己的智能体会话和上下文。建议在只有你和你的 bot 的私有服务器中使用这种方式。 +私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个频道都有自己的智能体会话和独立上下文。对于只有你和你的机器人的私有服务器，推荐这样做。 - 这会让你的智能体能够在服务器上的任何渠道中响应，而不仅限于私信。 + 这会让你的智能体能够在服务器上的任何频道中响应，而不仅限于私信。 @@ -254,14 +254,14 @@ Token 解析会识别账户。配置中的 token 值优先于 env 后备。`DISC - - 默认情况下，你的智能体只有在服务器渠道中被 @mentioned 时才会响应。对于私有服务器，你可能希望它响应每条消息。 + + 默认情况下，你的智能体只有在服务器频道中被 @mentioned 时才会响应。对于私有服务器，你可能希望它响应每条消息。 - 在服务器渠道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须通过 `message` 工具显式发送，因此智能体默认可以旁观，并且只在判断渠道回复有用时才发帖。 + 在服务器频道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须使用 `message` 工具显式发送，因此智能体默认可以旁听，并且只在它判断频道回复有用时发帖。 - > “允许我的智能体在此服务器上无需被 @mentioned 即可响应” + > “允许我的智能体在这个服务器上无需被 @mentioned 就能响应” 在你的服务器配置中设置 `requireMention: false`： @@ -280,49 +280,53 @@ Token 解析会识别账户。配置中的 token 值优先于 env 后备。`DISC } ``` - 要恢复群组/渠道房间的旧版自动最终回复，请设置 `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:`）。 - 群组私信默认会被忽略（`channels.discord.dm.groupEnabled=false`）。 -- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍会携带 `CommandTargetSessionKey` 到被路由的对话会话。 -- 仅文本的 cron/heartbeat 公告投递到 Discord 时，会使用最终对助手可见的答案一次。媒体和结构化组件载荷在智能体发出多个可投递载荷时仍保持多消息形式。 +- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 指向已路由的对话会话。 +- 面向 Discord 的纯文本 cron/heartbeat 公告投递会使用最终的 + 智能体可见答案一次。媒体和结构化组件载荷在智能体发出多个可投递载荷时， + 仍会保持多消息形式。 ## 论坛渠道 Discord 论坛和媒体渠道只接受线程帖子。OpenClaw 支持两种创建方式： -- 向论坛父级（`channel:`）发送消息以自动创建线程。线程标题使用你的消息中第一行非空内容。 -- 使用 `openclaw message thread create` 直接创建线程。不要为论坛渠道传递 `--message-id`。 +- 向论坛父渠道（`channel:`）发送消息以自动创建线程。线程标题使用你消息中的第一行非空文本。 +- 使用 `openclaw message thread create` 直接创建线程。不要为论坛渠道传入 `--message-id`。 -示例：发送到论坛父级以创建线程 +示例：发送到论坛父渠道以创建线程 ```bash openclaw message send --channel discord --target channel: \ @@ -336,11 +340,11 @@ openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -论坛父级不接受 Discord 组件。如果你需要组件，请发送到线程本身（`channel:`）。 +论坛父渠道不接受 Discord 组件。如果你需要组件，请发送到线程本身（`channel:`）。 ## 交互式组件 -OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 `components` 载荷的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有 Discord `replyToMode` 设置。 +OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带有 `components` 载荷的 message 工具。交互结果会作为普通入站消息路由回智能体，并遵循现有 Discord `replyToMode` 设置。 支持的块： @@ -348,11 +352,11 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - 操作行最多允许 5 个按钮或一个选择菜单 - 选择类型：`string`、`user`、`role`、`mentionable`、`channel` -默认情况下，组件只能使用一次。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前被多次使用。 +默认情况下，组件是单次使用的。设置 `components.reusable=true` 可允许按钮、选择菜单和表单在过期前多次使用。 要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，并且只有调用它的用户可以使用。 +`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及一个提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时消息，只有调用它的用户可以使用。 文件附件： @@ -362,7 +366,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 模态表单： -- 添加包含最多 5 个字段的 `components.modal` +- 添加 `components.modal`，最多包含 5 个字段 - 字段类型：`text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` - OpenClaw 会自动添加触发按钮 @@ -423,7 +427,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 ## 访问控制和路由 - + `channels.discord.dmPolicy` 控制私信访问。`channels.discord.allowFrom` 是规范的私信允许列表。 - `pairing`（默认） @@ -431,30 +435,30 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - `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"`。共享访问组行为见此处文档：[访问组](/zh-CN/channels/access-groups)。 + 访问组名称在消息渠道之间共享。对于成员以各渠道常规 `allowFrom` 语法表示的静态组，使用 `type: "message.senders"`；当 Discord 渠道当前的 `ViewChannel` 受众应动态定义成员关系时，使用 `type: "discord.channelAudience"`。共享访问组行为记录在这里：[访问组](/zh-CN/channels/access-groups)。 ```json5 { @@ -477,9 +481,9 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - Discord 文本渠道没有单独的成员列表。`type: "discord.channelAudience"` 将成员资格建模为：私信发送者是已配置服务器的成员，并且在应用角色和渠道覆盖后，当前对已配置渠道拥有有效的 `ViewChannel` 权限。 + Discord 文本渠道没有单独的成员列表。`type: "discord.channelAudience"` 将成员关系建模为：私信发送者是已配置服务器的成员，并且在应用角色和渠道覆盖后，当前对已配置渠道具有有效的 `ViewChannel` 权限。 - 示例：允许任何能看到 `#maintainers` 的人给机器人发私信，同时对其他所有人保持私信关闭。 + 示例：允许任何能看到 `#maintainers` 的人给机器人发送私信，同时保持对其他所有人关闭私信。 ```json5 { @@ -500,7 +504,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 你可以混合动态和静态条目： + 你可以混合使用动态和静态条目： ```json5 { @@ -520,29 +524,29 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 查找失败时默认关闭。如果 Discord 返回 `Missing Access`，成员查找失败，或渠道属于不同服务器，私信发送者会被视为未授权。 + 查询失败时默认拒绝访问。如果 Discord 返回 `Missing Access`、成员查询失败，或该渠道属于不同的服务器，则将私信发送者视为未授权。 - 使用渠道受众访问组时，请在 Discord Developer Portal 中为机器人启用 **Server Members Intent**。私信不包含服务器成员状态，因此 OpenClaw 会在授权时通过 Discord REST 解析成员。 + 使用渠道受众访问组时，请在 Discord Developer Portal 中为机器人启用 **Server Members Intent**。私信不包含服务器成员状态，所以 OpenClaw 会在授权时通过 Discord REST 解析成员。 - + 服务器处理由 `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` 块，则该允许列表服务器中的所有渠道都被允许 示例： @@ -568,35 +572,35 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 如果你只设置了 `DISCORD_BOT_TOKEN`，且未创建 `channels.discord` 块，则运行时回退为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open`。 + 如果你只设置了 `DISCORD_BOT_TOKEN` 且没有创建 `channels.discord` 块，运行时回退为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open`。 - - 服务器消息默认受提及门控。 + + 服务器消息默认需要提及才会触发。 提及检测包括： - - 显式机器人提及 - - 配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 受支持情况下的隐式回复机器人行为 + - 显式提及机器人 + - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） + - 在支持情况下的隐式回复机器人行为 - 编写出站 Discord 消息时，请使用规范提及语法：用户使用 `<@USER_ID>`，渠道使用 `<#CHANNEL_ID>`，角色使用 `<@&ROLE_ID>`。不要使用旧版 `<@!USER_ID>` 昵称提及形式。 + 编写出站 Discord 消息时，请使用规范提及语法：`<@USER_ID>` 表示用户，`<#CHANNEL_ID>` 表示渠道，`<@&ROLE_ID>` 表示角色。不要使用旧版 `<@!USER_ID>` 昵称提及形式。 `requireMention` 按服务器/渠道配置（`channels.discord.guilds...`）。 - `ignoreOtherMentions` 可选地丢弃提及其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 + `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 { @@ -620,15 +624,15 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` -## 原生命令和命令认证 +## 原生命令和命令鉴权 -- `commands.native` 默认为 `"auto"`，并为 Discord 启用。 -- 按渠道覆盖：`channels.discord.commands.native`。 -- `commands.native=false` 会显式清除之前注册的 Discord 原生命令。 -- 原生命令认证使用与普通消息处理相同的 Discord allowlists/策略。 -- 对未获授权的用户，命令可能仍会显示在 Discord UI 中；执行时仍会强制执行 OpenClaw 认证并返回“未获授权”。 +- `commands.native` 默认为 `"auto"`，并且已为 Discord 启用。 +- 每渠道覆盖项：`channels.discord.commands.native`。 +- `commands.native=false` 会在启动期间跳过 Discord 斜杠命令注册和清理。之前注册的命令可能仍会在 Discord 中可见，直到你从 Discord 应用中移除它们。 +- 原生命令认证使用与普通消息处理相同的 Discord 允许列表/策略。 +- 对未授权用户，命令可能仍会在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 认证，并返回“未授权”。 -请参阅 [斜杠命令](/zh-CN/tools/slash-commands)，了解命令目录和行为。 +请参阅[斜杠命令](/zh-CN/tools/slash-commands)，了解命令目录和行为。 默认斜杠命令设置： @@ -637,8 +641,8 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 ## 功能详情 - - Discord 支持智能体输出中的回复标签： + + Discord 支持在智能体输出中使用回复标签： - `[[reply_to_current]]` - `[[reply_to:]]` @@ -650,21 +654,18 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - `all` - `batched` - 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。 - `first` 始终会将隐式原生回复引用附加到该轮次的第一条出站 Discord 消息。 - `batched` 仅当入站轮次是多条消息组成的防抖批次时， - 才会附加 Discord 的隐式原生回复引用。这个选项适合 - 你希望主要在模糊的突发聊天中使用原生回复， - 而不是每个单消息轮次都使用时。 + 注意：`off` 会禁用隐式回复串联。显式 `[[reply_to_*]]` 标签仍会生效。 + `first` 始终会把隐式原生回复引用附加到本轮的第一条出站 Discord 消息。 + `batched` 仅在入站轮次是多条消息的防抖批次时，才会附加 Discord 的隐式原生回复引用。这个选项适合你主要想在含义不明确的突发聊天中使用原生回复，而不是每个单消息轮次都使用。 - 消息 ID 会显示在上下文/历史中，因此智能体可以定位特定消息。 + 消息 ID 会在上下文/历史中公开，这样智能体可以定位特定消息。 - - OpenClaw 可以通过发送临时消息并在文本到达时编辑它来流式传输草稿回复。`channels.discord.streaming` 接受 `off`（默认）| `partial` | `block` | `progress`。在 Discord 上，`progress` 映射到 `partial`；`streamMode` 是旧版别名，会自动迁移。 + + OpenClaw 可以通过发送临时消息并在文本到达时编辑它，来流式传输草稿回复。`channels.discord.streaming` 接受 `off`（默认）| `partial` | `block` | `progress`。`progress` 在 Discord 上会映射为 `partial`；`streamMode` 是旧版别名，会自动迁移。 - 默认保持为 `off`，因为当多个 Bot 或 Gateway 网关共享同一账号时，Discord 预览编辑会很快触发速率限制。 + 默认保持为 `off`，因为当多个机器人或 Gateway 网关共享一个账号时，Discord 预览编辑很快会触发速率限制。 ```json5 { @@ -681,23 +682,23 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - - `partial` 会在 token 到达时编辑单条预览消息。 + - `partial` 会在令牌到达时编辑单条预览消息。 - `block` 会发出草稿大小的分块（使用 `draftChunk` 调整大小和断点，并受 `textChunkLimit` 限制）。 - 媒体、错误和显式回复最终消息会取消待处理的预览编辑。 - `streaming.preview.toolProgress`（默认 `true`）控制工具/进度更新是否复用预览消息。 - 预览流式传输仅支持文本；媒体回复会回退到普通投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 + 预览流式传输仅支持文本；媒体回复会回退到普通投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。 - - Guild 历史上下文： + + 公会历史上下文： - - `channels.discord.historyLimit` 默认值 `20` - - 回退：`messages.groupChat.historyLimit` - - `0` 禁用 + - `channels.discord.historyLimit` 默认值为 `20` + - 回退项：`messages.groupChat.historyLimit` + - `0` 会禁用 - 私信历史控制： + 私信历史控制项： - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` @@ -705,25 +706,25 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 线程行为： - Discord 线程会作为渠道会话路由，并继承父渠道配置，除非被覆盖。 - - 线程会话会继承父渠道的会话级 `/model` 选择，作为仅模型回退；线程本地 `/model` 选择仍优先，并且除非启用 transcript 继承，否则不会复制父 transcript 历史。 - - `channels.discord.thread.inheritParent`（默认 `false`）会让新的自动线程选择从父 transcript 播种。按账号覆盖位于 `channels.discord.accounts..thread.inheritParent`。 - - 消息工具 reactions 可以解析 `user:` 私信目标。 + - 线程会话会继承父渠道会话级 `/model` 选择，作为仅模型回退；线程本地 `/model` 选择仍优先，并且除非启用转录继承，否则不会复制父转录历史。 + - `channels.discord.thread.inheritParent`（默认 `false`）会让新的自动线程选择从父转录播种。每账号覆盖项位于 `channels.discord.accounts..thread.inheritParent` 下。 + - 消息工具反应可以解析 `user:` 私信目标。 - `guilds..channels..requireMention: false` 会在回复阶段激活回退期间保留。 - 渠道主题会作为**不可信**上下文注入。Allowlists 控制谁可以触发智能体，而不是完整的补充上下文遮蔽边界。 + 渠道主题会作为**不受信任**的上下文注入。允许列表限制谁可以触发智能体，而不是完整的补充上下文删减边界。 - - Discord 可以将线程绑定到会话目标，让该线程中的后续消息继续路由到同一会话（包括子智能体会话）。 + + Discord 可以将线程绑定到会话目标，使该线程中的后续消息继续路由到同一个会话（包括子智能体会话）。 命令： - `/focus ` 将当前/新线程绑定到子智能体/会话目标 - `/unfocus` 移除当前线程绑定 - `/agents` 显示活跃运行和绑定状态 - - `/session idle ` 查看/更新已聚焦绑定的非活跃自动取消聚焦时间 - - `/session max-age ` 查看/更新已聚焦绑定的硬性最大存活时间 + - `/session idle ` 检查/更新已聚焦绑定的不活跃自动取消聚焦 + - `/session max-age ` 检查/更新已聚焦绑定的硬性最大年龄 配置： @@ -754,17 +755,17 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - `session.threadBindings.*` 设置全局默认值。 - `channels.discord.threadBindings.*` 覆盖 Discord 行为。 - - `spawnSessions` 控制为 `sessions_spawn({ thread: true })` 和 ACP 线程生成自动创建/绑定线程。默认值：`true`。 - - `defaultSpawnContext` 控制线程绑定生成的原生子智能体上下文。默认值：`"fork"`。 + - `spawnSessions` 控制是否为 `sessions_spawn({ thread: true })` 和 ACP 线程生成自动创建/绑定线程。默认：`true`。 + - `defaultSpawnContext` 控制线程绑定生成的原生子智能体上下文。默认：`"fork"`。 - 已弃用的 `spawnSubagentSessions`/`spawnAcpSessions` 键会由 `openclaw doctor --fix` 迁移。 - 如果某个账号禁用了线程绑定，`/focus` 和相关线程绑定操作将不可用。 - 请参阅 [子智能体](/zh-CN/tools/subagents)、[ACP 智能体](/zh-CN/tools/acp-agents) 和 [配置参考](/zh-CN/gateway/configuration-reference)。 + 请参阅[子智能体](/zh-CN/tools/subagents)、[ACP 智能体](/zh-CN/tools/acp-agents)和[配置参考](/zh-CN/gateway/configuration-reference)。 - - 对于稳定的“始终在线”ACP 工作区，请配置顶层类型化 ACP 绑定，目标指向 Discord 对话。 + + 对于稳定的“始终在线”ACP 工作区，请配置顶层带类型 ACP 绑定，目标指向 Discord 对话。 配置路径： @@ -820,47 +821,47 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 说明： - - `/acp spawn codex --bind here` 会就地绑定当前渠道或线程，并让未来消息保留在同一 ACP 会话上。线程消息会继承父渠道绑定。 - - 在已绑定的渠道或线程中，`/new` 和 `/reset` 会就地重置同一 ACP 会话。临时线程绑定在活跃时可以覆盖目标解析。 - - `spawnSessions` 通过 `--thread auto|here` 门控子线程创建/绑定。 + - `/acp spawn codex --bind here` 会就地绑定当前渠道或线程，并让未来消息保持在同一个 ACP 会话上。线程消息会继承父渠道绑定。 + - 在已绑定的渠道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时线程绑定在活跃时可以覆盖目标解析。 + - `spawnSessions` 通过 `--thread auto|here` 控制子线程创建/绑定。 请参阅 [ACP 智能体](/zh-CN/tools/acp-agents)，了解绑定行为详情。 - - 按 Guild 设置的 reaction 通知模式： + + 每公会反应通知模式： - `off` - `own`（默认） - `all` - `allowlist`（使用 `guilds..users`） - Reaction 事件会转换为系统事件并附加到已路由的 Discord 会话。 + 反应事件会转换为系统事件，并附加到已路由的 Discord 会话。 - - `ackReaction` 会在 OpenClaw 处理入站消息时发送确认 emoji。 + + `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 解析顺序： - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 "👀"） + - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） 说明： - - Discord 接受 unicode emoji 或自定义 emoji 名称。 - - 使用 `""` 可为某个渠道或账号禁用该 reaction。 + - Discord 接受 Unicode 表情符号或自定义表情符号名称。 + - 使用 `""` 可为渠道或账号禁用该反应。 - - 默认启用由渠道发起的配置写入。 + + 渠道发起的配置写入默认启用。 - 这会影响 `/config set|unset` 流程（启用命令功能时）。 + 这会影响 `/config set|unset` 流程（当命令功能启用时）。 禁用： @@ -876,8 +877,8 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - - 通过 `channels.discord.proxy` 将 Discord Gateway 网关 WebSocket 流量和启动 REST 查询（应用 ID + allowlist 解析）路由到 HTTP(S) 代理。 + + 使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord Gateway 网关 WebSocket 流量和启动时 REST 查询（应用 ID + 允许列表解析）。 ```json5 { @@ -889,7 +890,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 按账号覆盖： + 每账号覆盖项： ```json5 { @@ -907,8 +908,8 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - - 启用 PluralKit 解析，将代理消息映射到系统成员身份： + + 启用 PluralKit 解析，以将代理消息映射到系统成员身份： ```json5 { @@ -925,15 +926,15 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 说明： - - allowlists 可以使用 `pk:` - - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，成员显示名称才会按 name/slug 匹配 - - 查询使用原始消息 ID，并受时间窗口限制 - - 如果查询失败，代理消息会被视为 Bot 消息并丢弃，除非 `allowBots=true` + - 允许列表可以使用 `pk:` + - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名称 + - 查询使用原始消息 ID，并受时间窗口约束 + - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非 `allowBots=true` - - 当智能体需要对已知 Discord 用户进行确定性的出站提及时，请使用 `mentionAliases`。键是不带前导 `@` 的 handle；值是 Discord 用户 ID。未知 handle、`@everyone`、`@here` 以及 Markdown 代码 span 内的提及会保持不变。 + + 当智能体需要为已知 Discord 用户生成确定性的出站提及时，请使用 `mentionAliases`。键是不带前导 `@` 的句柄；值是 Discord 用户 ID。未知句柄、`@everyone`、`@here` 以及 Markdown 代码跨度内的提及会保持不变。 ```json5 { @@ -956,10 +957,10 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - - 当你设置 status 或 activity 字段，或者启用自动 presence 时，会应用 presence 更新。 + + 当你设置状态或活动字段，或启用自动存在状态时，会应用存在状态更新。 - 仅 status 示例： + 仅状态示例： ```json5 { @@ -971,7 +972,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - Activity 示例（自定义 status 是默认 activity 类型）： + 活动示例（自定义状态是默认活动类型）： ```json5 { @@ -984,7 +985,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - Streaming 示例： + 流式传输示例： ```json5 { @@ -998,16 +999,16 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - Activity 类型映射： + 活动类型映射： - 0：正在玩 - - 1：Streaming（需要 `activityUrl`） + - 1：正在流式传输（需要 `activityUrl`） - 2：正在听 - 3：正在观看 - - 4：自定义（使用 activity 文本作为 status 状态；emoji 可选） - - 5：正在竞赛 + - 4：自定义（使用活动文本作为状态状态；表情符号可选） + - 5：正在比赛 - 自动 presence 示例（运行时健康信号）： + 自动存在状态示例（运行时健康信号）： ```json5 { @@ -1024,7 +1025,7 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 } ``` - 自动 presence 会将运行时可用性映射到 Discord status：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： + 自动存在状态会将运行时可用性映射到 Discord 状态：健康 => 在线，降级或未知 => 空闲，耗尽或不可用 => 请勿打扰。可选文本覆盖项： - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -1032,69 +1033,70 @@ OpenClaw 支持用于智能体消息的 Discord 组件 v2 容器。使用带有 - - Discord 支持在私信中基于按钮处理批准，也可以选择在来源渠道中发布批准提示。 + + Discord 支持在私信中通过按钮处理批准，并且可选地在原始渠道中发布批准提示。 配置路径： - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers`（可选；可能时回退到 `commands.ownerAllowFrom`） - - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认值：`dm`） + - `channels.discord.execApprovals.approvers`（可选；可行时回退到 `commands.ownerAllowFrom`） + - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` - 当 `enabled` 未设置或为 `"auto"`，且至少能解析出一个审批者时，Discord 会自动启用原生执行审批；审批者可以来自 `execApprovals.approvers`，也可以来自 `commands.ownerAllowFrom`。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断执行审批者。设置 `enabled: false` 可明确禁用 Discord 作为原生审批客户端。 + 当 `enabled` 未设置或为 `"auto"`，并且至少能从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个审批人时，Discord 会自动启用原生 exec 审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或直接消息 `defaultTo` 推断 exec 审批人。设置 `enabled: false` 可明确禁用 Discord 作为原生审批客户端。 - 对于敏感的仅限所有者群组命令，例如 `/diagnostics` 和 `/export-trajectory`，OpenClaw 会私下发送审批提示和最终结果。当发起命令的所有者有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 + 对于 `/diagnostics` 和 `/export-trajectory` 等敏感的仅所有者可用群组命令，OpenClaw 会私下发送审批提示和最终结果。当发起调用的所有者有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 - 当 `target` 为 `channel` 或 `both` 时，审批提示会在渠道中可见。只有已解析的审批者可以使用按钮；其他用户会收到一条临时拒绝消息。审批提示会包含命令文本，因此只应在可信渠道中启用渠道投递。如果无法从会话键派生渠道 ID，OpenClaw 会回退到私信投递。 + 当 `target` 为 `channel` 或 `both` 时，审批提示会在渠道中可见。只有已解析的审批人可以使用按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此只应在受信任的渠道中启用渠道投递。如果无法从会话键推导出渠道 ID，OpenClaw 会回退到私信投递。 - Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要增加审批者私信路由和渠道扇出。 - 当这些按钮存在时，它们就是主要审批体验；OpenClaw - 只应在工具结果表明聊天审批不可用，或手动审批是唯一路径时包含手动 `/approve` 命令。 + Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 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 分钟后过期。 - 参见[执行审批](/zh-CN/tools/exec-approvals)。 + 请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)。 -## 工具和操作门控 +## 工具和动作门控 -Discord 消息操作包括消息、渠道管理、审核、在线状态和元数据操作。 +Discord 消息动作包括消息、渠道管理、审核、在线状态和元数据动作。 核心示例： - 消息：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` -- 表态：`react`、`reactions`、`emojiList` +- 反应：`react`、`reactions`、`emojiList` - 审核：`timeout`、`kick`、`ban` - 在线状态：`setPresence` -`event-create` 操作接受可选的 `image` 参数（URL 或本地文件路径），用于设置预定事件封面图。 +`event-create` 动作接受可选的 `image` 参数（URL 或本地文件路径），用于设置预定事件封面图。 -操作门控位于 `channels.discord.actions.*` 下。 +动作门控位于 `channels.discord.actions.*` 下。 默认门控行为： -| 操作组 | 默认值 | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 已启用 | -| roles | 已禁用 | -| moderation | 已禁用 | -| presence | 已禁用 | +| 动作组 | 默认 | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 启用 | +| roles | 禁用 | +| moderation | 禁用 | +| presence | 禁用 | ## Components v2 UI -OpenClaw 使用 Discord components v2 处理执行审批和跨上下文标记。Discord 消息操作也可以接受用于自定义 UI 的 `components`（高级；需要通过 discord 工具构造组件负载），旧版 `embeds` 仍可用，但不推荐。 +OpenClaw 使用 Discord components v2 处理 exec 审批和跨上下文标记。Discord 消息动作也可以接受用于自定义 UI 的 `components`（高级；需要通过 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` 会被忽略。 示例： @@ -1114,7 +1116,7 @@ OpenClaw 使用 Discord components v2 处理执行审批和跨上下文标记。 ## 语音 -Discord 有两个不同的语音表面：实时**语音频道**（连续对话）和**语音消息附件**（波形预览格式）。Gateway 网关同时支持两者。 +Discord 有两个不同的语音表面：实时 **语音频道**（持续对话）和 **语音消息附件**（波形预览格式）。Gateway 网关同时支持二者。 ### 语音频道 @@ -1122,8 +1124,8 @@ Discord 有两个不同的语音表面：实时**语音频道**（连续对话 1. 在 Discord Developer Portal 中启用 Message Content Intent。 2. 使用角色/用户允许列表时，启用 Server Members Intent。 -3. 使用 `bot` 和 `applications.commands` 作用域邀请机器人。 -4. 在目标语音频道中授予 Connect、Speak、Send Messages 和 Read Message History。 +3. 使用 `bot` 和 `applications.commands` scope 邀请机器人。 +4. 在目标语音频道中授予 Connect、Speak、Send Messages 和 Read Message History 权限。 5. 启用原生命令（`commands.native` 或 `channels.discord.commands.native`）。 6. 配置 `channels.discord.voice`。 @@ -1164,38 +1166,38 @@ Discord 有两个不同的语音表面：实时**语音频道**（连续对话 } ``` -注意事项： +注意： -- `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 网关意图。 -- `channels.discord.intents.voiceStates` 可以明确覆盖语音状态意图订阅。保持未设置时，该意图会跟随有效的语音启用状态。 -- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` 加入选项。 +- `voice.tts` 仅为语音播放覆盖 `messages.tts`。 +- `voice.model` 仅覆盖用于 Discord 语音频道响应的 LLM。保留未设置可继承路由后的智能体模型。 +- STT 使用 `tools.media.audio`；`voice.model` 不影响转写。 +- 每渠道 Discord `systemPrompt` 覆盖会应用于该语音频道的语音转写轮次。 +- 语音转写轮次会从 Discord `allowFrom`（或 `dm.allowFrom`）推导所有者状态；非所有者发言人无法访问仅所有者可用工具（例如 `gateway` 和 `cron`）。 +- Discord 语音对纯文本配置是选择加入；设置 `channels.discord.voice.enabled=true`（或保留现有 `channels.discord.voice` 块）可启用 `/vc` 命令、语音运行时和 `GuildVoiceStates` gateway intent。 +- `channels.discord.intents.voiceStates` 可以明确覆盖语音状态 intent 订阅。保留未设置时，该 intent 会跟随有效的语音启用状态。 +- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会传递给 `@discordjs/voice` 加入选项。 - 如果未设置，`@discordjs/voice` 默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 -- `voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试的初始 `@discordjs/voice` Ready 等待时间。默认值：`30000`。 -- `voice.reconnectGraceMs` 控制 OpenClaw 在销毁已断开语音会话前，等待其开始重新连接的时长。默认值：`15000`。 -- OpenClaw 还会监视接收解密失败，并在短时间窗口内重复失败后，通过离开/重新加入语音频道自动恢复。 -- 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 系列包含来自 discord.js PR #11449 的上游填充修复，该修复关闭了 discord.js issue #11419。 +- `voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试时初始 `@discordjs/voice` Ready 等待。默认值：`30000`。 +- `voice.reconnectGraceMs` 控制 OpenClaw 在销毁断开的语音会话前，等待其开始重连的时长。默认值：`15000`。 +- OpenClaw 还会监视接收解密失败，并在短时间窗口内反复失败后，通过离开并重新加入语音频道自动恢复。 +- 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置 `@discordjs/voice` 版本线包含来自 discord.js PR #11449 的上游填充修复，该修复关闭了 discord.js issue #11419。 语音频道流水线： - Discord PCM 捕获会转换为 WAV 临时文件。 - `tools.media.audio` 处理 STT，例如 `openai/gpt-4o-mini-transcribe`。 -- 转录文本会通过 Discord 入口和路由发送，同时响应 LLM 会以语音输出策略运行，该策略隐藏智能体 `tts` 工具并要求返回文本，因为 Discord 语音负责最终 TTS 播放。 +- 转写内容会通过 Discord 入口和路由发送，同时响应 LLM 会以语音输出策略运行，该策略隐藏智能体 `tts` 工具并要求返回文本，因为 Discord 语音拥有最终 TTS 播放。 - 设置 `voice.model` 时，它只会覆盖此语音频道轮次的响应 LLM。 -- `voice.tts` 会合并到 `messages.tts` 之上；生成的音频会在已加入的频道中播放。 +- `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 会拒绝同一负载中的文本 + 语音消息）。 +- 提供 **本地文件路径**（URL 会被拒绝）。 +- 省略文本内容（Discord 会拒绝在同一载荷中同时发送文本和语音消息）。 - 接受任何音频格式；OpenClaw 会按需转换为 OGG/Opus。 ```bash @@ -1205,22 +1207,22 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## 故障排除 - + - 启用 Message Content Intent - 当你依赖用户/成员解析时，启用 Server Members Intent - - 更改意图后重启 Gateway 网关 + - 更改 intent 后重启 Gateway 网关 - + - 验证 `groupPolicy` - - 验证 `channels.discord.guilds` 下的服务器允许列表 - - 如果存在服务器 `channels` 映射，则只允许列出的渠道 + - 验证 `channels.discord.guilds` 下的 guild 允许列表 + - 如果存在 guild `channels` 映射，则只允许列出的渠道 - 验证 `requireMention` 行为和提及模式 - 有用的检查： + 有用检查： ```bash openclaw doctor @@ -1233,9 +1235,9 @@ openclaw logs --follow 常见原因： - - `groupPolicy="allowlist"` 且没有匹配的服务器/渠道允许列表 + - `groupPolicy="allowlist"` 且没有匹配的 guild/渠道允许列表 - `requireMention` 配置在错误位置（必须位于 `channels.discord.guilds` 或渠道条目下） - - 发送者被服务器/渠道 `users` 允许列表阻止 + - 发送者被 guild/渠道 `users` 允许列表阻止 @@ -1252,7 +1254,7 @@ openclaw logs --follow - 多账号：`channels.discord.accounts..eventQueue.listenerTimeout` - 这只控制 Discord Gateway 网关监听器工作，不控制智能体轮次生命周期 - Discord 不会对排队的智能体轮次应用渠道自有超时。消息监听器会立即移交，排队的 Discord 运行会保留按会话排序，直到会话/工具/运行时生命周期完成或中止工作。 + Discord 不会对已排队的智能体轮次应用渠道拥有的超时。消息监听器会立即移交，已排队的 Discord 运行会保留每个会话的顺序，直到会话/工具/运行时生命周期完成或中止工作。 ```json5 { @@ -1273,7 +1275,7 @@ openclaw logs --follow - OpenClaw 会在连接前获取 Discord `/gateway/bot` 元数据。瞬时失败会回退到 Discord 的默认 Gateway 网关 URL，并在日志中做速率限制。 + OpenClaw 会在连接前获取 Discord `/gateway/bot` 元数据。瞬时失败会回退到 Discord 的默认 Gateway 网关 URL，并在日志中进行限速。 元数据超时旋钮： @@ -1285,25 +1287,25 @@ openclaw logs --follow - OpenClaw 在启动期间以及运行时重新连接后会等待 Discord 的 Gateway 网关 `READY` 事件。带启动错峰的多账户设置可能需要比默认值更长的启动 READY 窗口。 + OpenClaw 在启动期间以及运行时重连后会等待 Discord 的 gateway `READY` 事件。带启动错峰的多账号设置可能需要比默认值更长的启动 READY 窗口。 - READY 超时调节项： + READY 超时旋钮： - - 启动单账户：`channels.discord.gatewayReadyTimeoutMs` - - 启动多账户：`channels.discord.accounts..gatewayReadyTimeoutMs` + - 启动单账号：`channels.discord.gatewayReadyTimeoutMs` + - 启动多账号：`channels.discord.accounts..gatewayReadyTimeoutMs` - 配置未设置时的启动环境变量回退：`OPENCLAW_DISCORD_READY_TIMEOUT_MS` - 启动默认值：`15000`（15 秒），最大值：`120000` - - 运行时单账户：`channels.discord.gatewayRuntimeReadyTimeoutMs` - - 运行时多账户：`channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` + - 运行时单账号：`channels.discord.gatewayRuntimeReadyTimeoutMs` + - 运行时多账号：`channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` - 配置未设置时的运行时环境变量回退：`OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` - 运行时默认值：`30000`（30 秒），最大值：`120000` - `channels status --probe` 权限检查仅适用于数字渠道 ID。 + `channels status --probe` 权限检查只适用于数字渠道 ID。 - 如果你使用 slug 键，运行时匹配仍然可以工作，但探测无法完全验证权限。 + 如果你使用 slug 键，运行时匹配仍然可以工作，但探测无法完整验证权限。 @@ -1311,27 +1313,27 @@ openclaw logs --follow - 私信已禁用：`channels.discord.dm.enabled=false` - 私信策略已禁用：`channels.discord.dmPolicy="disabled"`（旧版：`channels.discord.dm.policy`） - - 在 `pairing` 模式中等待配对批准 + - 在 `pairing` 模式下等待配对批准 - 默认情况下会忽略机器人发送的消息。 + 默认会忽略机器人发出的消息。 - 如果你设置 `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`（默认值） + - 让 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 接收历史进行对比 @@ -1346,11 +1348,11 @@ openclaw logs --follow - 策略：`groupPolicy`、`dm.*`、`guilds.*`、`guilds.*.channels.*` - 命令：`commands.native`、`commands.useAccessGroups`、`configWrites`、`slashCommand.*` - 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` -- Gateway 网关：`gatewayInfoTimeoutMs`、`gatewayReadyTimeoutMs`、`gatewayRuntimeReadyTimeoutMs` +- gateway：`gatewayInfoTimeoutMs`、`gatewayReadyTimeoutMs`、`gatewayRuntimeReadyTimeoutMs` - 回复/历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` - 投递：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` - 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` -- 媒体/重试：`mediaMaxMb`（限制发往 Discord 的上传，默认 `100MB`）、`retry` +- 媒体/重试：`mediaMaxMb`（限制 Discord 出站上传，默认 `100MB`）、`retry` - 操作：`actions.*` - 在线状态：`activity`、`status`、`activityType`、`activityUrl` - UI：`ui.components.accentColor` @@ -1360,27 +1362,27 @@ openclaw logs --follow ## 安全与运维 -- 将机器人令牌视为机密（在受监督环境中优先使用 `DISCORD_BOT_TOKEN`）。 +- 将机器人 token 视为机密（在受监管环境中首选 `DISCORD_BOT_TOKEN`）。 - 授予最小权限的 Discord 权限。 -- 如果命令部署/状态已过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。 +- 如果命令部署/状态已过期，请重启 Gateway 网关，并用 `openclaw channels status --probe` 重新检查。 -## 相关内容 +## 相关 - 将 Discord 用户与 Gateway 网关配对。 + 将 Discord 用户配对到 gateway。 群聊和允许列表行为。 - 将传入消息路由到智能体。 + 将入站消息路由到智能体。 - 威胁模型与加固。 + 威胁模型和加固。 - 将服务器和渠道映射到智能体。 + 将 guild 和渠道映射到智能体。 原生命令行为。 diff --git a/docs/zh-CN/gateway/config-channels.md b/docs/zh-CN/gateway/config-channels.md index 846bd4b88..ba195e8ed 100644 --- a/docs/zh-CN/gateway/config-channels.md +++ b/docs/zh-CN/gateway/config-channels.md @@ -1,54 +1,54 @@ --- read_when: - - 配置渠道插件（身份验证、访问控制、多账号） - - 每个渠道配置键的故障排除 + - 配置渠道插件（认证、访问控制、多账号） + - 按渠道配置键名的故障排除 - 审计私信策略、群组策略或提及门控 -summary: 渠道配置：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等的访问控制、配对和每渠道密钥 +summary: 渠道配置：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等渠道的访问控制、配对和各渠道密钥 title: 配置 — 渠道 x-i18n: - generated_at: "2026-05-03T01:34:53Z" + generated_at: "2026-05-03T18:10:37Z" model: gpt-5.5 provider: openai - source_hash: 5ec4aad94a844f6e2f936b2e0d208343ea264c9a4c74f7fc610c516e0353b53b + source_hash: 7deb5358980d58a917eb564d8f65a43d6b61b8bc53b80349f404353db50bbb98 source_path: gateway/config-channels.md workflow: 16 --- -`channels.*` 下的每渠道配置键。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的每渠道键。 +每个渠道的配置键位于 `channels.*` 下。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的各渠道键。 -对于智能体、工具、Gateway 网关运行时和其他顶级键，请参阅 +对于智能体、工具、Gateway 网关运行时和其他顶层键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。 ## 渠道 -每个渠道会在其配置部分存在时自动启动（除非 `enabled: false`）。 +当配置段存在时，每个渠道都会自动启动（除非 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： | 私信策略 | 行为 | -| ------------------- | --------------------------------------------------------------- | -| `pairing`（默认） | 未知发送者会获得一次性配对码；所有者必须批准 | -| `allowlist` | 仅允许 `allowFrom`（或已配对允许存储）中的发送者 | -| `open` | 允许所有入站私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有入站私信 | +| ------------------- | ----------------------------------------------------------- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 仅允许 `allowFrom`（或已配对允许存储）中的发送者 | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | +| 群组策略 | 行为 | | --------------------- | ------------------------------------------------------ | -| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | -| `open` | 绕过群组允许列表（提及门控仍然适用） | -| `disabled` | 阻止所有群组/房间消息 | +| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | +| `open` | 绕过群组允许列表（提及门控仍会生效） | +| `disabled` | 阻止所有群组/房间消息 | -`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设置默认值。 -配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。 -如果提供商块完全缺失（不存在 `channels.`），运行时群组策略会回退到 `allowlist`（以关闭方式失败），并在启动时发出警告。 +`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设定默认值。 +配对码在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。 +如果提供商块完全缺失（不存在 `channels.`），运行时群组策略会回退到 `allowlist`（失败关闭），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话尚未有模型覆盖（例如通过 `/model` 设置）时，会应用渠道映射。 +使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话尚未设置模型覆盖时（例如通过 `/model` 设置），会应用渠道映射。 ```json5 { @@ -89,15 +89,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：提供商级 `groupPolicy` 未设置时的回退群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与允许列表相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 -- `channels.defaults.heartbeat.showOk`：在 Heartbeat 输出中包含健康的渠道状态。 -- `channels.defaults.heartbeat.showAlerts`：在 Heartbeat 输出中包含降级/错误状态。 -- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器样式 Heartbeat 输出。 +- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时使用的回退群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含允许列表发送者的上下文）、`allowlist_quote`（与允许列表相同，但保留显式引用/回复上下文）。各渠道覆盖项：`channels..contextVisibility`。 +- `channels.defaults.heartbeat.showOk`：在 Heartbeat 输出中包含健康的渠道 Status。 +- `channels.defaults.heartbeat.showAlerts`：在 Heartbeat 输出中包含降级/错误 Status。 +- `channels.defaults.heartbeat.useIndicator`：渲染紧凑指示器样式的 Heartbeat 输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已关联会话时，它会自动启动。 +WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已链接会话时，它会自动启动。 ```json5 { @@ -156,9 +156,9 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 ``` - 出站命令默认使用账号 `default`（如果存在）；否则使用第一个已配置账号 ID（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在匹配已配置账号 ID 时覆盖该回退默认账号选择。 -- 旧版单账号 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 -- 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 +- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配已配置账号 ID 时覆盖该回退默认账号选择。 +- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 按账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -217,14 +217,14 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- Bot 令牌：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅限普通文件；拒绝符号链接），默认账号的回退值为 `TELEGRAM_BOT_TOKEN`。 -- `apiRoot` 仅是 Telegram Bot API 根地址。使用 `https://api.telegram.org` 或你的自托管/代理根地址，不要使用 `https://api.telegram.org/bot`；`openclaw doctor --fix` 会移除意外尾随的 `/bot` 后缀。 -- 可选的 `channels.telegram.defaultAccount` 会在匹配已配置账号 ID 时覆盖默认账号选择。 +- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅限普通文件；符号链接会被拒绝），默认账号会以 `TELEGRAM_BOT_TOKEN` 作为回退。 +- `apiRoot` 仅是 Telegram Bot API 根地址。使用 `https://api.telegram.org` 或你的自托管/代理根地址，而不是 `https://api.telegram.org/bot`；`openclaw doctor --fix` 会移除意外追加的 `/bot` 后缀。 +- 可选的 `channels.telegram.defaultAccount` 会在其匹配已配置账号 ID 时覆盖默认账号选择。 - 在多账号设置（2 个以上账号 ID）中，设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；当它缺失或无效时，`openclaw doctor` 会发出警告。 -- `configWrites: false` 会阻止 Telegram 发起的配置写入（超级群 ID 迁移、`/config set|unset`）。 -- 顶级 `bindings[]` 条目配合 `type: "acp"` 可为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。 +- `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。 +- 带有 `type: "acp"` 的顶层 `bindings[]` 条目会为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。 - Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群聊）。 -- 重试策略：请参阅[重试策略](/zh-CN/concepts/retry)。 +- 重试策略：参阅[重试策略](/zh-CN/concepts/retry)。 ### Discord @@ -329,41 +329,41 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- 令牌：`channels.discord.token`，默认账户使用 `DISCORD_BOT_TOKEN` 作为回退。 -- 提供显式 Discord `token` 的直接出站调用会使用该令牌发起调用；账户重试/策略设置仍来自活动运行时快照中的所选账户。 -- 可选的 `channels.discord.defaultAccount` 在匹配已配置账户 ID 时会覆盖默认账户选择。 +- 令牌：`channels.discord.token`，默认账号以 `DISCORD_BOT_TOKEN` 作为回退。 +- 提供显式 Discord `token` 的直接出站调用会使用该令牌进行调用；账号重试/策略设置仍来自活动运行时快照中选定的账号。 +- 可选的 `channels.discord.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 - 使用 `user:`（私信）或 `channel:`（公会渠道）作为投递目标；裸数字 ID 会被拒绝。 -- 公会 slug 为小写，并将空格替换为 `-`；渠道键使用 slug 化名称（不含 `#`）。优先使用公会 ID。 -- 默认忽略机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及该机器人的机器人消息（仍会过滤自己的消息）。 +- 公会 slug 为小写，空格替换为 `-`；渠道键使用 slug 化后的名称（无 `#`）。优先使用公会 ID。 +- 默认忽略机器人作者的消息。`allowBots: true` 会启用这些消息；使用 `allowBots: "mentions"` 只接受提及该机器人的机器人消息（仍会过滤自己发送的消息）。 - `channels.discord.guilds..ignoreOtherMentions`（以及渠道覆盖项）会丢弃提及其他用户或角色但未提及该机器人的消息（不包括 @everyone/@here）。 -- `channels.discord.mentionAliases` 会在发送前将稳定的出站 `@handle` 文本映射到 Discord 用户 ID，因此即使临时目录缓存为空，也能确定性地提及已知队友。每账户覆盖项位于 `channels.discord.accounts..mentionAliases` 下。 -- `maxLinesPerMessage`（默认 17）即使在 2000 个字符以内也会拆分过高的消息。 +- `channels.discord.mentionAliases` 会在发送前把稳定的出站 `@handle` 文本映射到 Discord 用户 ID，因此即使临时目录缓存为空，也能确定性地提及已知队友。按账号覆盖项位于 `channels.discord.accounts..mentionAliases` 下。 +- `maxLinesPerMessage`（默认 17）即使在低于 2000 个字符时也会拆分过高的消息。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：线程绑定会话功能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由）的 Discord 覆盖项 - - `idleHours`：非活动自动取消聚焦的 Discord 覆盖项，单位为小时（`0` 禁用） - - `maxAgeHours`：硬性最长时限的 Discord 覆盖项，单位为小时（`0` 禁用） + - `enabled`：线程绑定会话功能的 Discord 覆盖项（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） + - `idleHours`：非活动自动取消聚焦的 Discord 覆盖项，单位为小时（`0` 表示禁用） + - `maxAgeHours`：硬性最大时长的 Discord 覆盖项，单位为小时（`0` 表示禁用） - `spawnSessions`：用于 `sessions_spawn({ thread: true })` 和 ACP 线程生成自动创建/绑定线程的开关（默认：`true`） - - `defaultSpawnContext`：线程绑定生成的原生子智能体上下文（默认为 `"fork"`） + - `defaultSpawnContext`：线程绑定生成的原生子智能体上下文（默认 `"fork"`） - 顶层 `bindings[]` 条目配合 `type: "acp"` 可为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。 - `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。 -- `channels.discord.voice` 启用 Discord 语音渠道对话，以及可选的自动加入 + LLM + TTS 覆盖项。纯文本 Discord 配置默认关闭语音；设置 `channels.discord.voice.enabled=true` 以选择启用。 -- `channels.discord.voice.model` 可选地覆盖用于 Discord 语音渠道响应的 LLM 模型。 +- `channels.discord.voice` 启用 Discord 语音渠道对话，以及可选的自动加入 + LLM + TTS 覆盖项。纯文本 Discord 配置默认关闭语音；设置 `channels.discord.voice.enabled=true` 可选择启用。 +- `channels.discord.voice.model` 可选地覆盖用于 Discord 语音渠道回复的 LLM 模型。 - `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` DAVE 选项（默认分别为 `true` 和 `24`）。 -- `channels.discord.voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试的初始 `@discordjs/voice` Ready 等待时间（默认为 `30000`）。 -- `channels.discord.voice.reconnectGraceMs` 控制断开的语音会话在 OpenClaw 销毁前可进入重连信令的时长（默认为 `15000`）。 -- OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试语音接收恢复。 -- `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔 `streaming` 值会自动迁移。 -- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online、degraded => idle、exhausted => dnd），并允许可选的状态文本覆盖项。 +- `channels.discord.voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试的初始 `@discordjs/voice` Ready 等待时间（默认 `30000`）。 +- `channels.discord.voice.reconnectGraceMs` 控制断开的语音会话可进入重连信令的最长时间，超过后 OpenClaw 会销毁它（默认 `15000`）。 +- OpenClaw 还会在反复解密失败后，通过离开/重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.streaming` 是规范流模式键。旧版 `streamMode` 和布尔值 `streaming` 会自动迁移。 +- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖项。 - `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（应急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批者授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，如果可以从 `approvers` 或 `commands.ownerAllowFrom` 解析审批者，exec 审批会激活。 - - `approvers`：允许审批 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 +- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析审批人时，会激活 exec 审批。 + - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - `sessionFilter`：可选的会话键模式（子字符串或正则表达式）。 - - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批者私信，`"channel"` 发送到来源渠道，`"both"` 同时发送到两者。当 target 包含 `"channel"` 时，按钮仅可由已解析的审批者使用。 + - `target`：审批提示发送位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到来源渠道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮只能由已解析的审批人使用。 - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds..users`）。 +**反应通知模式：**`off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds..users`）。 ### Google Chat @@ -394,8 +394,8 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- 服务账户 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 -- 也支持服务账户 SecretRef（`serviceAccountRef`）。 +- 服务账号 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 - 使用 `spaces/` 或 `users/` 作为投递目标。 - `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（应急兼容模式）。 @@ -470,35 +470,44 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账户环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级别或每账户）。 -- `socketMode` 会将 Slack SDK Socket Mode 传输调优透传给公开的 Bolt 接收器 API。仅在调查 ping/pong 超时或陈旧 websocket 行为时使用它。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 -- Slack 账户快照会公开每个凭证的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及 HTTP mode 中的 `signingSecretStatus`。`configured_unavailable` 表示账户已通过 SecretRef 配置，但当前命令/运行时路径无法解析密钥值。 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级或按账号配置）。 +- `socketMode` 会把 Slack SDK Socket Mode 传输调优透传到公共 Bolt receiver API。仅在调查 ping/pong 超时或过期 websocket 行为时使用。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 + 字符串或 SecretRef 对象。 +- Slack 账号快照会暴露按凭据划分的来源/状态字段，例如 + `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 + `signingSecretStatus`。`configured_unavailable` 表示账号已 + 通过 SecretRef 配置，但当前命令/运行时路径无法 + 解析密钥值。 - `configWrites: false` 会阻止 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 在匹配已配置账户 ID 时会覆盖默认账户选择。 -- `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输协议。旧版 `streamMode`、布尔 `streaming` 和 `nativeStreaming` 值会自动迁移。 +- 可选的 `channels.slack.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 +- `channels.slack.streaming.mode` 是规范 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流传输。旧版 `streamMode`、布尔值 `streaming` 和 `nativeStreaming` 会自动迁移。 - 使用 `user:`（私信）或 `channel:` 作为投递目标。 -**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**反应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 为每线程（默认）或跨渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。 +**线程会话隔离：**`thread.historyScope` 是按线程（默认）或在渠道内共享。`thread.inheritParent` 会把父渠道转录复制到新线程。 -- Slack 原生流式传输加上 Slack assistant 风格的“正在输入...”线程状态需要回复线程目标。顶层私信默认保持在线程外，因此它们仍可通过 Slack 草稿发布并编辑预览进行流式传输，而不是显示线程风格的原生流/状态预览。 -- `typingReaction` 会在回复运行时向入站 Slack 消息添加一个临时反应，然后在完成时移除。使用 Slack emoji 短代码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批者授权。与 Discord 相同的 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- Slack 原生流式传输加 Slack 助手风格的 “is typing...” 线程状态需要回复线程目标。顶层私信默认保持在线程外，因此仍可通过 Slack 草稿发布并编辑预览来流式传输，而不是显示线程风格的原生流/状态预览。 +- `typingReaction` 会在回复运行时向传入的 Slack 消息添加临时反应，并在完成时移除它。使用 Slack emoji shortcode，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。架构与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认值 | 说明 | -| ------------ | ------ | ------------------ | -| reactions | 已启用 | 添加反应 + 列出反应 | -| messages | 已启用 | 读取/发送/编辑/删除 | -| pins | 已启用 | 置顶/取消置顶/列出 | -| memberInfo | 已启用 | 成员信息 | -| emojiList | 已启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 备注 | +| ------------ | ------- | ---------------------- | +| reactions | enabled | 添加反应 + 列出反应 | +| messages | enabled | 读取/发送/编辑/删除 | +| pins | enabled | 固定/取消固定/列出 | +| memberInfo | enabled | 成员信息 | +| emojiList | enabled | 自定义 emoji 列表 | ### Mattermost -Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧版本或自定义构建可以使用 `openclaw plugins install @openclaw/mattermost` 安装当前 npm 包。固定版本前，请查看 [npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) 获取当前 dist-tags。 +Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧或 +自定义构建可以使用 +`openclaw plugins install @openclaw/mattermost` 安装当前 npm 包。固定版本前，请查看 +[npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) +了解当前 dist-tags。 ```json5 { @@ -528,18 +537,18 @@ Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧版本 } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @-mention 时回复，默认）、`onmessage`（每条消息）、`onchar`（以触发前缀开头的消息）。 启用 Mattermost 原生命令时： - `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可以访问。 -- 原生斜杠回调使用 Mattermost 在斜杠命令注册期间返回的每命令令牌进行身份验证。如果注册失败或没有命令被激活，OpenClaw 会以 `Unauthorized: invalid command token.` 拒绝回调。 -- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。使用主机/域名值，不要使用完整 URL。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。 +- 原生斜杠回调使用 Mattermost 在斜杠命令注册期间返回的每命令令牌进行认证。如果注册失败或没有激活任何命令，OpenClaw 会使用 `Unauthorized: invalid command token.` 拒绝回调。 +- 对于私有、tailnet 或内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。使用主机/域名值，而不是完整 URL。 - `channels.mattermost.configWrites`：允许或拒绝 Mattermost 发起的配置写入。 -- `channels.mattermost.requireMention`：要求在渠道中回复前先 `@mention`。 -- `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（`"*"` 表示默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 会在匹配已配置的账号 id 时覆盖默认账号选择。 +- `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。 +- `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（`"*"` 表示默认）。 +- 可选的 `channels.mattermost.defaultAccount` 在匹配已配置账号 ID 时覆盖默认账号选择。 ### Signal @@ -560,11 +569,11 @@ Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧版本 } ``` -**表情反应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**表情回应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 - `channels.signal.account`：将渠道启动固定到特定 Signal 账号身份。 - `channels.signal.configWrites`：允许或拒绝 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 会在匹配已配置的账号 id 时覆盖默认账号选择。 +- 可选的 `channels.signal.defaultAccount` 在匹配已配置账号 ID 时覆盖默认账号选择。 ### BlueBubbles @@ -583,14 +592,14 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.blueb } ``` -- 这里覆盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 会在匹配已配置的账号 id 时覆盖默认账号选择。 -- 顶层 `bindings[]` 条目配合 `type: "acp"` 可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles 句柄或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP Agents](/zh-CN/tools/acp-agents#persistent-channel-bindings)。 -- 完整 BlueBubbles 渠道配置见 [BlueBubbles](/zh-CN/channels/bluebubbles)。 +- 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 +- 可选的 `channels.bluebubbles.defaultAccount` 在匹配已配置账号 ID 时覆盖默认账号选择。 +- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles 句柄或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings)。 +- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage -OpenClaw 会启动 `imsg rpc`（通过 stdio 运行 JSON-RPC）。不需要守护进程或端口。 +OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 ```json5 { @@ -614,15 +623,15 @@ OpenClaw 会启动 `imsg rpc`（通过 stdio 运行 JSON-RPC）。不需要守 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在匹配已配置的账号 id 时覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 在匹配已配置账号 ID 时覆盖默认账号选择。 -- 需要对 Messages DB 授予完整磁盘访问权限。 +- 需要 Messages 数据库的完整磁盘访问权限。 - 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）用于通过 SCP 获取附件。 -- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 +- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）用于 SCP 附件获取。 +- `attachmentRoots` 和 `remoteAttachmentRoots` 限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 - SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 - `channels.imessage.configWrites`：允许或拒绝 iMessage 发起的配置写入。 -- 顶层 `bindings[]` 条目配合 `type: "acp"` 可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化句柄或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP Agents](/zh-CN/tools/acp-agents#persistent-channel-bindings)。 +- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化句柄或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings)。 @@ -665,21 +674,21 @@ Matrix 由插件支持，并在 `channels.matrix` 下配置。 } ``` -- 令牌身份验证使用 `accessToken`；密码身份验证使用 `userId` + `password`。 +- 令牌认证使用 `accessToken`；密码认证使用 `userId` + `password`。 - `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可以用 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 与此网络选择加入是相互独立的控制项。 -- `channels.matrix.defaultAccount` 会在多账号设置中选择首选账号。 -- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置带有 `autoJoinAllowlist` 的 `autoJoin: "allowlist"` 或 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析审批人时，exec 审批会激活。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和这个网络选择加入是独立控制项。 +- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 +- `channels.matrix.autoJoin` 默认为 `off`，因此被邀请的房间和新的私信样式邀请会被忽略，直到你设置带有 `autoJoinAllowlist` 的 `autoJoin: "allowlist"` 或 `autoJoin: "always"`。 +- `channels.matrix.execApprovals`：Matrix 原生 exec 批准投递和批准者授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析批准者时，exec 批准会激活。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。 - - `sessionFilter`：可选的会话键模式（子字符串或正则表达式）。 - - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 + - `agentFilter`：可选智能体 ID 允许列表。省略则转发所有智能体的批准。 + - `sessionFilter`：可选会话键模式（子字符串或正则表达式）。 + - `target`：发送批准提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组为会话：`per-user`（默认）按路由后的对端共享，而 `per-room` 会隔离每个私信房间。 -- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 -- 完整 Matrix 配置、定向规则和设置示例见 [Matrix](/zh-CN/channels/matrix)。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组为会话：`per-user`（默认）按路由后的对等方共享，而 `per-room` 会隔离每个私信房间。 +- Matrix Status 探测和实时目录查找使用与运行时流量相同的代理策略。 +- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams @@ -698,8 +707,8 @@ Microsoft Teams 由插件支持，并在 `channels.msteams` 下配置。 } ``` -- 这里覆盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖）见 [Microsoft Teams](/zh-CN/channels/msteams)。 +- 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 +- 完整 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 ### IRC @@ -724,13 +733,13 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 } ``` -- 这里覆盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 会在匹配已配置的账号 id 时覆盖默认账号选择。 -- 完整 IRC 渠道配置（主机/端口/TLS/渠道/允许列表/提及门控）见 [IRC](/zh-CN/channels/irc)。 +- 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 +- 可选的 `channels.irc.defaultAccount` 在匹配已配置账号 ID 时覆盖默认账号选择。 +- 完整的 IRC 渠道配置（主机/端口/TLS/渠道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 ### 多账号（所有渠道） -每个渠道运行多个账号（每个账号都有自己的 `accountId`）： +每个渠道运行多个账号（每个都有自己的 `accountId`）： ```json5 { @@ -754,31 +763,31 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 - 省略 `accountId` 时使用 `default`（CLI + 路由）。 - 环境变量令牌仅适用于**默认**账号。 - 基础渠道设置会应用于所有账号，除非按账号覆盖。 -- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。 -- 如果你在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将账号作用域的顶层单账号值提升到渠道账号映射中，以便原账号继续工作。大多数渠道会将它们移入 `channels..accounts.default`；Matrix 则可以改为保留现有匹配的命名/默认目标。 -- 现有仅渠道绑定（没有 `accountId`）会继续匹配默认账号；账号作用域绑定仍然是可选的。 -- `openclaw doctor --fix` 也会通过将账号作用域的顶层单账号值移入为该渠道选择的已提升账号来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以改为保留现有匹配的命名/默认目标。 +- 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。 +- 如果你在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将账号范围的顶层单账号值提升到渠道账号映射中，以便原始账号继续工作。大多数渠道会将它们移入 `channels..accounts.default`；Matrix 可以改为保留现有匹配的命名/默认目标。 +- 现有仅渠道绑定（无 `accountId`）继续匹配默认账号；账号范围绑定仍为可选。 +- `openclaw doctor --fix` 还会通过将账号范围的顶层单账号值移入为该渠道选择的已提升账号来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 可以改为保留现有匹配的命名/默认目标。 ### 其他插件渠道 -许多插件渠道配置为 `channels.`，并在各自专用的渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -查看完整渠道索引：[Channels](/zh-CN/channels)。 +许多插件渠道配置为 `channels.`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +查看完整渠道索引：[渠道](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认**要求提及**（元数据提及或安全正则表达式模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 -可见回复单独控制。群组/渠道房间默认为 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理该轮对话，但普通最终回复保持私密，可见房间输出需要 `message(action=send)`。仅当你需要旧版行为，即普通回复也发回房间时，才设置为 `"automatic"`。若要将相同的仅工具可见回复行为也应用到直接聊天，请设置 `messages.visibleReplies: "message_tool"`；Codex harness 也将这种仅工具行为作为未设置的直接聊天默认值。 +可见回复单独控制。群组/渠道房间默认为 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理本轮，但普通最终回复保持私密，可见房间输出需要 `message(action=send)`。仅当你想要旧版行为，即普通回复发布回房间时，才设置 `"automatic"`。要把相同的仅工具可见回复行为也应用到直接聊天，请设置 `messages.visibleReplies: "message_tool"`；Codex harness 也使用该仅工具行为作为其未设置直接聊天默认值。 -如果消息工具在当前工具策略下不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。`openclaw doctor` 会对这种不匹配发出警告。 +如果在当前工具策略下消息工具不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。`openclaw doctor` 会对此不匹配发出警告。 -Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中禁用了文件监听或配置重载时才需要重启。 +Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中禁用文件监视或配置重载时才重启。 **提及类型：** -- **元数据提及**：原生平台 @-提及。在 WhatsApp 自聊模式下会被忽略。 -- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅当可以检测时（原生提及或至少一个模式），才会强制执行提及门控。 +- **元数据提及**：原生平台 @-提及。在 WhatsApp 自聊模式中会被忽略。 +- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则表达式模式。无效模式和不安全的嵌套重复会被忽略。 +- 仅在可检测时（原生提及或至少一个模式）强制执行提及门控。 ```json5 { @@ -797,7 +806,7 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中 `messages.groupChat.historyLimit` 设置全局默认值。渠道可以用 `channels..historyLimit`（或按账号）覆盖。设为 `0` 可禁用。 -`messages.visibleReplies` 是全局源回合默认值；`messages.groupChat.visibleReplies` 会为群组/渠道源回合覆盖它。当 `messages.visibleReplies` 未设置时，harness 可以提供自己的直接/源默认值；Codex harness 默认为 `message_tool`。渠道允许列表和提及门控仍会决定是否处理某个回合。 +`messages.visibleReplies` 是全局来源轮次默认值；`messages.groupChat.visibleReplies` 会为群组/渠道来源轮次覆盖它。当 `messages.visibleReplies` 未设置时，harness 可以提供自己的直接/来源默认值；Codex harness 默认使用 `message_tool`。渠道 allowlist 和提及门控仍会决定是否处理某个轮次。 #### 私信历史限制 @@ -870,28 +879,28 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中 -- 此块配置命令界面。有关当前内置 + 内置打包命令目录，请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。 -- 此页面是**配置键参考**，不是完整命令目录。渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、记忆 `/dreaming`、手机控制 `/phone` 和 Talk `/voice`，记录在其渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 -- 文本命令必须是以 `/` 开头的**独立**消息。 -- `native: "auto"` 会为 Discord/Telegram 启用原生命令，保持 Slack 关闭。 -- `nativeSkills: "auto"` 会为 Discord/Telegram 启用原生 Skills 命令，保持 Slack 关闭。 -- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除此前注册的命令。 +- 此块配置命令界面。要查看当前内置 + 捆绑的命令目录，请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。 +- 本页是**配置键参考**，不是完整命令目录。渠道/插件拥有的命令（例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、记忆 `/dreaming`、手机控制 `/phone` 和 Talk `/voice`）记录在各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 +- 文本命令必须是带前导 `/` 的**独立**消息。 +- `native: "auto"` 会为 Discord/Telegram 开启原生命令，Slack 保持关闭。 +- `nativeSkills: "auto"` 会为 Discord/Telegram 开启原生 Skills 命令，Slack 保持关闭。 +- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。对于 Discord，`false` 会在启动期间跳过原生命令注册和清理。 - 使用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 注册。 -- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单条目。 -- `bash: true` 为主机 shell 启用 `! `。需要 `tools.elevated.enabled`，且发送者在 `tools.elevated.allowFrom.` 中。 -- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还需要 `operator.admin`；只读 `/config show` 仍可供普通写入作用域的 operator 客户端使用。 -- `mcp: true` 为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 -- `plugins: true` 为插件发现、安装以及启用/禁用控制启用 `/plugins`。 -- `channels..configWrites` 按渠道控制配置变更（默认值：true）。 -- 对于多账号渠道，`channels..accounts..configWrites` 也会控制面向该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `restart: false` 禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 -- `ownerAllowFrom` 是仅限所有者命令/工具的显式所有者允许列表。它与 `allowFrom` 分开。 -- `ownerDisplay: "hash"` 会在系统提示中哈希所有者 ID。设置 `ownerDisplaySecret` 可控制哈希。 -- `allowFrom` 按提供商设置。设置后，它是**唯一**授权来源（渠道允许列表/配对和 `useAccessGroups` 会被忽略）。 +- `channels.telegram.customCommands` 会添加额外的 Telegram Bot 菜单条目。 +- `bash: true` 启用面向宿主 shell 的 `! `。需要 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.` 中。 +- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久性 `/config set|unset` 写入还需要 `operator.admin`；只读 `/config show` 仍可供普通写入范围的 operator 客户端使用。 +- `mcp: true` 启用 `/mcp`，用于 `mcp.servers` 下由 OpenClaw 管理的 MCP server 配置。 +- `plugins: true` 启用 `/plugins`，用于插件发现、安装和启用/禁用控制。 +- `channels..configWrites` 按渠道门控配置变更（默认值：true）。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会门控以该账号为目标的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 +- `ownerAllowFrom` 是仅限 owner 命令/工具的显式 owner allowlist。它独立于 `allowFrom`。 +- `ownerDisplay: "hash"` 会在系统提示中哈希 owner id。设置 `ownerDisplaySecret` 可控制哈希。 +- `allowFrom` 按提供商设置。设置后，它就是**唯一**授权来源（渠道 allowlist/配对和 `useAccessGroups` 会被忽略）。 - 当未设置 `allowFrom` 时，`useAccessGroups: false` 允许命令绕过访问组策略。 - 命令文档映射： - - 内置 + 内置打包目录：[Slash Commands](/zh-CN/tools/slash-commands) - - 渠道特定命令界面：[Channels](/zh-CN/channels) + - 内置 + 捆绑目录：[Slash Commands](/zh-CN/tools/slash-commands) + - 渠道特定命令界面：[渠道](/zh-CN/channels) - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) - 配对命令：[Pairing](/zh-CN/channels/pairing) - LINE 卡片命令：[LINE](/zh-CN/channels/line) @@ -903,6 +912,6 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中 ## 相关内容 -- [配置参考](/zh-CN/gateway/configuration-reference) — 顶层键 +- [配置参考](/zh-CN/gateway/configuration-reference) — 顶级键 - [配置 — 智能体](/zh-CN/gateway/config-agents) - [渠道概览](/zh-CN/channels) diff --git a/docs/zh-CN/tools/slash-commands.md b/docs/zh-CN/tools/slash-commands.md index 3051c85aa..08b8590e0 100644 --- a/docs/zh-CN/tools/slash-commands.md +++ b/docs/zh-CN/tools/slash-commands.md @@ -3,20 +3,20 @@ read_when: - 使用或配置聊天命令 - 调试命令路由或权限 sidebarTitle: Slash commands -summary: 斜杠命令：文本与原生、配置和支持的命令 +summary: 斜杠命令：文本与原生命令、配置和支持的命令 title: 斜杠命令 x-i18n: - generated_at: "2026-05-03T17:32:48Z" + generated_at: "2026-05-03T18:10:24Z" model: gpt-5.5 provider: openai - source_hash: 02b7c1f3daa9598515085fd94570172f82779ce61a2af34edac02a36ccc87543 + source_hash: 9fbdd76ccd43159cabfbc3f15f7bddd2a7ada07fcd6eea2e169d2d88df18f28c source_path: tools/slash-commands.md workflow: 16 --- -命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! `（`/bash ` 是别名）。 +命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! `（`/bash ` 作为别名）。 -当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍保留在本地：`/acp ...` 始终到达 OpenClaw ACP 命令处理器；只要该表面启用了命令处理，`/status` 和 `/unfocus` 也会保留在本地。 +当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍保持本地处理：`/acp ...` 始终会到达 OpenClaw ACP 命令处理程序，并且只要该表面启用了命令处理，`/status` 和 `/unfocus` 就会保持本地处理。 有两个相关系统： @@ -27,16 +27,16 @@ x-i18n: `/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。 - - 指令会在模型看到消息之前从消息中移除。 - - 在普通聊天消息中（不是仅指令消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 + - 指令会在模型看到消息之前从消息中剥离。 + - 在普通聊天消息中（非仅指令消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 - 在仅指令消息中（消息只包含指令），它们会持久化到会话，并回复确认。 - - 指令只会应用于**已授权的发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对，以及 `commands.useAccessGroups`。未授权发送者的指令会被当作纯文本处理。 + - 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则，授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被当作纯文本处理。 - - 仅限允许列表中/已授权的发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 + + 仅允许列表内/已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - 它们会立即运行，并在模型看到消息之前被移除，剩余文本继续走普通流程。 + 它们会立即运行，在模型看到消息之前被剥离，剩余文本会继续按正常流程处理。 @@ -72,17 +72,17 @@ x-i18n: 启用在聊天消息中解析 `/...`。在没有原生命令的表面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将它设置为 `false`，文本命令仍然可用。 - 注册原生命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对于没有原生支持的提供商会被忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。 + 注册原生命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对没有原生支持的提供商忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。在 Discord 上，`false` 会跳过启动期间的斜杠命令注册和清理；之前注册的命令可能会保持可见，直到你从 Discord 应用中移除它们。Slack 命令在 Slack 应用中管理，不会自动移除。 -在 Discord 上，原生命令规格可以包含 `descriptionLocalizations`，OpenClaw 会将其发布为 Discord `description_localizations`，并纳入调和比较。 +在 Discord 上，原生命令规范可以包含 `descriptionLocalizations`，OpenClaw 会将其发布为 Discord `description_localizations`，并纳入对账比较。 - 在支持时原生注册 **skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 + 在支持时以原生方式注册 **skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 要求为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 - 启用 `! ` 来运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` 允许列表）。 + 启用 `! ` 以运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` 允许列表）。 - 控制 bash 在切换到后台模式前等待多久（`0` 表示立即转入后台）。 + 控制 bash 在切换到后台模式前等待的时长（`0` 表示立即进入后台）。 启用 `/config`（读取/写入 `openclaw.json`）。 @@ -91,87 +91,87 @@ x-i18n: 启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。 - 启用 `/plugins`（插件发现/Status，以及安装 + 启用/禁用控制）。 + 启用 `/plugins`（插件发现/Status，以及安装和启用/禁用控制）。 启用 `/debug`（仅运行时覆盖）。 - 启用 `/restart` 以及 Gateway 网关重启工具动作。 + 启用 `/restart` 以及 Gateway 网关重启工具操作。 - 为仅所有者命令/工具表面设置显式所有者允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom`，也独立于私信配对访问。 + 为仅所有者命令/工具表面设置显式所有者允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账户。它独立于 `commands.allowFrom`，也独立于私信配对访问。 - 按渠道设置：让仅所有者命令要求**所有者身份**才能在该表面运行。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或在内部消息渠道上持有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求——仅所有者命令会在该渠道上失败关闭。如果你希望仅所有者命令只由 `ownerAllowFrom` 和标准命令允许列表控制，请保持关闭。 + 按渠道：让仅所有者命令在该表面运行时要求**所有者身份**。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` scope。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求——仅所有者命令会在该渠道上默认关闭失败。如果你希望仅所有者命令只受 `ownerAllowFrom` 和标准命令允许列表控制，请保持关闭。 - 控制所有者 id 在系统提示中如何显示。 + 控制所有者 ID 在系统提示中的显示方式。 - 可选地设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。 + 可选设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC secret。 - 用于命令授权的按提供商允许列表。配置后，它就是命令和指令的唯一授权来源（会忽略渠道允许列表/配对和 `commands.useAccessGroups`）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。 + 用于命令授权的按提供商允许列表。配置后，它就是命令和指令的唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。 - 当未设置 `commands.allowFrom` 时，对命令强制执行允许列表/策略。 + 当未设置 `commands.allowFrom` 时，为命令强制执行允许列表/策略。 ## 命令列表 -当前权威来源： +当前事实来源： - 核心内置项来自 `src/auto-reply/commands-registry.shared.ts` -- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts` +- 生成的停靠命令来自 `src/auto-reply/commands-registry.data.ts` - 插件命令来自插件 `registerCommand()` 调用 -- 你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道表面，以及已安装/已启用的插件 +- 在你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道表面以及已安装/已启用的插件 ### 核心内置命令 - `/new [model]` 启动新会话；`/reset` 是重置别名。 - - Control UI 会拦截输入的 `/new`，创建并切换到新的仪表盘会话；输入的 `/reset` 仍运行 Gateway 网关的原地重置。 - - `/reset soft [message]` 保留当前转录，丢弃复用的 CLI 后端会话 id，并在原地重新运行启动/系统提示加载。 - - `/compact [instructions]` 压缩会话上下文。参见 [压缩](/zh-CN/concepts/compaction)。 + - Control UI 会拦截键入的 `/new`，以创建并切换到新的仪表板会话；键入的 `/reset` 仍会运行 Gateway 网关的原地重置。 + - `/reset soft [message]` 保留当前转录，丢弃已复用的 CLI 后端会话 ID，并原地重新运行启动/系统提示加载。 + - `/compact [instructions]` 压缩会话上下文。参见[压缩](/zh-CN/concepts/compaction)。 - `/stop` 中止当前运行。 - - `/session idle ` 和 `/session max-age ` 管理线程绑定过期。 + - `/session idle ` 和 `/session max-age ` 管理线程绑定过期时间。 - `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。 - - `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [trajectory bundle](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。 + - `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。 - - `/think ` 设置 thinking 级别。选项来自当前模型的提供商配置；常见级别为 `off`、`minimal`、`low`、`medium` 和 `high`，自定义级别（如 `xhigh`、`adaptive`、`max`）或二进制 `on` 仅在受支持处可用。别名：`/thinking`、`/t`。 + - `/think ` 设置思考级别。选项来自活动模型的提供商配置文件；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，而 `xhigh`、`adaptive`、`max` 或二进制 `on` 等自定义级别仅在支持的位置可用。别名：`/thinking`、`/t`。 - `/verbose on|off|full` 切换详细输出。别名：`/v`。 - - `/trace on|off` 切换当前会话的插件 trace 输出。 + - `/trace on|off` 为当前会话切换插件 trace 输出。 - `/fast [status|on|off]` 显示或设置快速模式。 - - `/reasoning [on|off|stream]` 切换 reasoning 可见性。别名：`/reason`。 - - `/elevated [on|off|ask|full]` 切换 elevated 模式。别名：`/elev`。 + - `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。 + - `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。 - `/exec host= security= ask= node=` 显示或设置 exec 默认值。 - `/model [name|#|status]` 显示或设置模型。 - - `/models [provider] [page] [limit=|size=|all]` 列出已配置/认证可用的提供商，或某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。 - - `/queue ` 管理队列行为（`steer`、旧版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`）以及类似 `debounce:0.5s cap:25 drop:summarize` 的选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见 [命令队列](/zh-CN/concepts/queue) 和 [Steering queue](/zh-CN/concepts/queue-steering)。 + - `/models [provider] [page] [limit=|size=|all]` 列出已配置/可用认证的提供商，或某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。 + - `/queue ` 管理队列行为（`steer`、旧版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见[命令队列](/zh-CN/concepts/queue)和 [Steering queue](/zh-CN/concepts/queue-steering)。 - + - `/help` 显示简短帮助摘要。 - `/commands` 显示生成的命令目录。 - `/tools [compact|verbose]` 显示当前智能体现在可以使用什么。 - - `/status` 显示执行/运行时状态，包括 `Execution`/`Runtime` 标签，以及在可用时显示提供商用量/配额。 - - `/diagnostics [note]` 是用于 Gateway 网关 bug 和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 前请求显式 exec 批准；不要用允许全部规则批准 diagnostics。批准后，它会发送一份可粘贴的报告，包含本地 bundle 路径、清单摘要、隐私说明和相关会话 id。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一次批准也会将相关 Codex feedback 发送到 OpenAI 服务器，完成后的回复会列出 OpenClaw 会话 id、Codex 线程 id 和 `codex resume ` 命令。参见 [Diagnostics Export](/zh-CN/gateway/diagnostics)。 + - `/status` 显示执行/运行时 Status，包括 `Execution`/`Runtime` 标签，以及可用时的提供商用量/配额。 + - `/diagnostics [note]` 是用于 Gateway 网关 bug 和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 前请求显式 exec 批准；不要使用 allow-all 规则批准诊断。批准后，它会发送一份可粘贴报告，其中包含本地包路径、清单摘要、隐私说明和相关会话 ID。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一批准还会将相关 Codex 反馈发送到 OpenAI 服务器，完成后的回复会列出 OpenClaw 会话 ID、Codex 线程 ID 和 `codex resume ` 命令。参见[诊断导出](/zh-CN/gateway/diagnostics)。 - `/crestodian ` 从所有者私信运行 Crestodian 设置和修复助手。 - `/tasks` 列出当前会话的活动/最近后台任务。 - `/context [list|detail|json]` 解释上下文如何组装。 - - `/whoami` 显示你的发送者 id。别名：`/id`。 - - `/usage off|tokens|full|cost` 控制每条响应的用量页脚，或打印本地成本摘要。 + - `/whoami` 显示你的发送者 ID。别名：`/id`。 + - `/usage off|tokens|full|cost` 控制每条回复的用量页脚，或打印本地成本摘要。 - + - `/skill [input]` 按名称运行一个 skill。 - `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。 - `/approve ` 解决 exec 批准提示。 - - `/btw ` 询问一个旁支问题，而不改变未来会话上下文。别名：`/side`。参见 [BTW](/zh-CN/tools/btw)。 + - `/btw ` 提出一个旁支问题，而不改变未来会话上下文。别名：`/side`。参见 [BTW](/zh-CN/tools/btw)。 @@ -179,34 +179,33 @@ x-i18n: - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。 - `/focus ` 将当前 Discord 线程或 Telegram 话题/对话绑定到一个会话目标。 - `/unfocus` 移除当前绑定。 - - `/agents` 列出当前会话的线程绑定智能体。 + - `/agents` 列出当前会话中绑定到线程的智能体。 - `/kill ` 中止一个或所有正在运行的子智能体。 - `/steer ` 向正在运行的子智能体发送引导。别名：`/tell`。 - - - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。 - - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。 - - `/plugins list|inspect|show|get|install|enable|disable` 检查或变更插件状态。`/plugin` 是别名。写入仅限所有者。需要 `commands.plugins: true`。 - - `/debug show|set|unset|reset` 管理仅运行时生效的配置覆盖。仅限所有者。需要 `commands.debug: true`。 + + - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅所有者。需要 `commands.config: true`。 + - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅所有者。需要 `commands.mcp: true`。 + - `/plugins list|inspect|show|get|install|enable|disable` 检查或修改插件状态。`/plugin` 是别名。写入仅限所有者。需要 `commands.plugins: true`。 + - `/debug show|set|unset|reset` 管理仅运行时生效的配置覆盖项。仅所有者。需要 `commands.debug: true`。 - `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用它。 - - `/send on|off|inherit` 设置发送策略。仅限所有者。 + - `/send on|off|inherit` 设置发送策略。仅所有者。 - + - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。参见 [TTS](/zh-CN/tools/tts)。 - `/activation mention|always` 设置群组激活模式。 - - `/bash ` 运行主机 shell 命令。仅文本。别名：`! `。需要 `commands.bash: true` 加 `tools.elevated` 允许列表。 - - `!poll [sessionId]` 检查后台 bash 作业。 - - `!stop [sessionId]` 停止后台 bash 作业。 + - `/bash ` 运行主机 shell 命令。仅文本。别名：`! `。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。 + - `!poll [sessionId]` 检查后台 bash 任务。 + - `!stop [sessionId]` 停止后台 bash 任务。 ### 生成的停靠命令 -停靠命令会将当前会话的回复路由切换到另一个已关联的 -渠道。设置、示例和故障排除见[渠道停靠](/zh-CN/concepts/channel-docking)。 +停靠命令会将当前会话的回复路由切换到另一个已链接的渠道。有关设置、示例和故障排除，请参见[渠道停靠](/zh-CN/concepts/channel-docking)。 停靠命令由支持原生命令的渠道插件生成。当前内置集合： @@ -215,15 +214,15 @@ x-i18n: - `/dock-slack`（别名：`/dock_slack`） - `/dock-telegram`（别名：`/dock_telegram`） -在直接聊天中使用停靠命令，将当前会话的回复路由切换到另一个已关联的渠道。智能体会保留同一个会话上下文，但该会话后续回复会发送到所选的渠道对端。 +在直接聊天中使用停靠命令，可将当前会话的回复路由切换到另一个已链接的渠道。智能体会保留相同的会话上下文，但该会话之后的回复会发送到所选渠道对端。 -停靠命令需要 `session.identityLinks`。源发送者和目标对端必须位于同一个身份组中，例如 `["telegram:123", "discord:456"]`。如果 id 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活跃会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未关联到 Discord 对端，该命令会回复一条设置提示，而不是落入普通聊天流程。 +停靠命令需要 `session.identityLinks`。源发送者和目标对端必须位于同一身份组，例如 `["telegram:123", "discord:456"]`。如果 ID 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活跃会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未链接到 Discord 对端，该命令会回复设置提示，而不会落入普通聊天流程。 -停靠只会改变活跃会话路由。它不会创建渠道账户、授予访问权限、绕过渠道允许列表，或将转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的停靠命令再次切换路由。 +停靠只会更改活跃会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，也不会将对话历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的停靠命令可再次切换路由。 ### 内置插件命令 -内置插件可以添加更多斜杠命令。此仓库中的当前内置命令： +内置插件可以添加更多斜杠命令。此仓库中当前的内置命令： - `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。 - `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见[配对](/zh-CN/channels/pairing)。 @@ -238,90 +237,90 @@ x-i18n: - `/bot-upgrade` - `/bot-logs` -### 动态 Skills 命令 +### 动态 Skill 命令 -用户可调用的 Skills 也会公开为斜杠命令： +用户可调用的 Skills 也会作为斜杠命令公开： -- `/skill [input]` 始终作为通用入口点可用。 -- 当 skill/插件注册时，Skills 也可能以 `/prose` 这样的直接命令出现。 -- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 -- 命令规格可以为支持本地化描述的原生表面提供 `descriptionLocalizations`，包括 Discord。 +- `/skill [input]` 始终可作为通用入口点使用。 +- 当 Skill/插件注册直接命令时，Skills 也可能以 `/prose` 这样的直接命令出现。 +- 原生 Skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 +- 命令规格可以为支持本地化描述的原生界面提供 `descriptionLocalizations`，包括 Discord。 - - 命令在命令和参数之间接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 - - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。 - - 要查看完整的提供商使用情况明细，请使用 `openclaw status --usage`。 + - 命令允许在命令和参数之间使用可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 + - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，文本会被视为消息正文。 + - 如需完整的提供商用量细分，请使用 `openclaw status --usage`。 - `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。 - - 在多账户渠道中，面向配置目标的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账户的 `configWrites`。 - - `/usage` 控制每条回复的用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地成本摘要。 + - 在多账号渠道中，面向配置的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账号的 `configWrites`。 + - `/usage` 控制每条回复的用量页脚；`/usage cost` 会根据 OpenClaw 会话日志打印本地费用汇总。 - `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。 - - `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包、`git:` 或 `clawhub:`，然后请求重启 Gateway 网关，因为插件源模块已更改。 - - `/plugins enable|disable` 更新插件配置，并为新的智能体轮次触发 Gateway 网关插件重载。 + - `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包、`git:` 或 `clawhub:`，然后由于插件源码模块已更改而请求重启 Gateway 网关。 + - `/plugins enable|disable` 更新插件配置，并为新的智能体轮次触发 Gateway 网关插件重新加载。 - - - 仅 Discord 的原生命令：`/vc join|leave|status` 控制语音频道（不能作为文本使用）。`join` 需要一个 guild 和选定的语音/舞台频道。需要 `channels.discord.voice` 和原生命令。 - - Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效的线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 + + - 仅 Discord 原生命令：`/vc join|leave|status` 控制语音渠道（不能作为文本使用）。`join` 需要一个服务器和所选的语音/舞台渠道。需要 `channels.discord.voice` 和原生命令。 + - Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 - ACP 命令参考和运行时行为：[ACP 智能体](/zh-CN/tools/acp-agents)。 - - - `/verbose` 用于调试和提供额外可见性；正常使用时请保持**关闭**。 - - `/trace` 比 `/verbose` 范围更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具噪声关闭。 - - `/fast on|off` 会持久化一个会话覆盖。使用会话 UI 的 `inherit` 选项清除它，并回退到配置默认值。 - - `/fast` 与提供商相关：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公开 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 - - 相关时仍会显示工具失败摘要，但详细失败文本仅在 `/verbose` 为 `on` 或 `full` 时包含。 - - `/reasoning`、`/verbose` 和 `/trace` 在群组场景中有风险：它们可能暴露你无意公开的内部推理、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。 + + - `/verbose` 用于调试和额外可见性；日常使用时保持**关闭**。 + - `/trace` 比 `/verbose` 范围更窄：它只显示插件拥有的跟踪/调试行，并保持常规详细工具输出关闭。 + - `/fast on|off` 会持久保存一个会话覆盖项。使用会话 UI 的 `inherit` 选项可清除它，并回退到配置默认值。 + - `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射为 `service_tier=priority`，而直接的公共 Anthropic 请求（包括发送到 `api.anthropic.com` 的 OAuth 认证流量）会将其映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 + - 相关时仍会显示工具失败摘要，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。 + - `/reasoning`、`/verbose` 和 `/trace` 在群组环境中有风险：它们可能暴露你不想公开的内部推理、工具输出或插件诊断信息。最好保持关闭，尤其是在群聊中。 - - `/model` 会立即持久化新的会话模型。 - - 如果智能体空闲，下一次运行会立刻使用它。 + - `/model` 会立即持久保存新的会话模型。 + - 如果智能体处于空闲状态，下一次运行会立刻使用它。 - 如果已有运行处于活跃状态，OpenClaw 会将实时切换标记为待处理，并且只会在干净的重试点重启到新模型。 - - 如果工具活动或回复输出已经开始，待处理切换可能会继续排队，直到后续重试机会或下一轮用户输入。 - - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这与消息渠道救援模式分开，也不会授予远程配置权限。 + - 如果工具活动或回复输出已经开始，待处理的切换可能会一直排队到之后的重试机会或下一个用户轮次。 + - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这独立于消息渠道救援模式，也不会授予远程配置权限。 - - - **快速路径：**来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。 - - **群组提及门控：**来自允许列表发送者的纯命令消息会绕过提及要求。 - - **内联快捷方式（仅允许列表发送者）：**某些命令嵌入普通消息时也可工作，并会在模型看到剩余文本之前被剥离。 - - 示例：`hey /status` 会触发状态回复，剩余文本继续走普通流程。 + + - **快速路径：** 来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。 + - **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。 + - **行内快捷方式（仅允许列表发送者）：** 某些命令嵌入普通消息时也可工作，并会在模型看到剩余文本前被移除。 + - 示例：`hey /status` 触发状态回复，剩余文本继续进入普通流程。 - 当前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - - 未授权的纯命令消息会被静默忽略，内联 `/...` 标记会被视为纯文本。 + - 未授权的纯命令消息会被静默忽略，行内 `/...` 片段会被视为普通文本。 - - **Skill 命令：**`user-invocable` Skills 会公开为斜杠命令。名称会被清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。 - - `/skill [input]` 按名称运行一个 skill（当原生命令限制阻止按 skill 提供命令时很有用）。 - - 默认情况下，skill 命令会作为普通请求转发给模型。 - - Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，不经过模型）。 - - 示例：`/prose`（OpenProse 插件）- 参见 [OpenProse](/zh-CN/prose)。 - - **原生命令参数：**Discord 对动态选项使用自动补全（省略必需参数时使用按钮菜单）。Telegram 和 Slack 在命令支持选择项且你省略参数时显示按钮菜单。动态选择项会基于目标会话模型解析，因此 `/think` 级别等特定模型选项会遵循该会话的 `/model` 覆盖。 + - **Skill 命令：** `user-invocable` Skills 会作为斜杠命令公开。名称会清理为 `a-z0-9_`（最多 32 个字符）；冲突时会添加数字后缀（例如 `_2`）。 + - `/skill [input]` 按名称运行一个 Skill（当原生命令限制无法为每个 Skill 创建命令时很有用）。 + - 默认情况下，Skill 命令会作为普通请求转发给模型。 + - Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性、无模型）。 + - 示例：`/prose`（OpenProse 插件）— 参见 [OpenProse](/zh-CN/prose)。 + - **原生命令参数：** Discord 对动态选项使用自动补全（缺少必需参数时使用按钮菜单）。当命令支持选项且你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选项会根据目标会话模型解析，因此 `/think` 级别等模型特定选项会遵循该会话的 `/model` 覆盖项。 ## `/tools` -`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体现在在此对话中可以使用什么**。 +`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体在当前对话中现在可以使用什么**。 -- 默认 `/tools` 很紧凑，并针对快速浏览优化。 -- `/tools verbose` 添加简短描述。 -- 支持参数的原生命令表面会公开同样的模式切换：`compact|verbose`。 -- 结果按会话限定范围，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。 -- `/tools` 包含运行时实际可访问的工具，包括核心工具、已连接的插件工具以及渠道拥有的工具。 +- 默认的 `/tools` 简洁，并针对快速扫描优化。 +- `/tools verbose` 会添加简短描述。 +- 支持参数的原生命令界面会公开相同的模式切换，即 `compact|verbose`。 +- 结果按会话限定，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。 +- `/tools` 包括运行时实际可达的工具，包括核心工具、已连接的插件工具以及渠道拥有的工具。 -要编辑配置文件和覆盖，请使用 Control UI 工具面板或配置/目录表面，而不是将 `/tools` 视为静态目录。 +如需编辑配置文件和覆盖项，请使用 Control UI Tools 面板或配置/目录界面，而不要把 `/tools` 当作静态目录。 -## 使用情况表面（哪里显示什么） +## 用量界面（哪里显示什么） -- **提供商使用量/配额**（示例：“Claude 剩余 80%”）会在启用使用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余 %”；对于 MiniMax，仅剩余百分比字段会在显示前取反，并且 `model_remains` 响应会优先使用聊天模型条目以及带模型标记的套餐标签。 -- `/status` 中的 **token/cache 行** 可以在实时会话快照稀疏时回退到最新的转录使用量条目。已有的非零实时值仍然优先，转录回退还可以恢复活动运行时模型标签，以及在存储总量缺失或更小时恢复更大的面向提示词的总量。 -- **执行与运行时：** `/status` 会为有效沙箱路径报告 `Execution`，并为实际运行会话的一方报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。 -- **每次响应的 token/成本** 由 `/usage off|tokens|full` 控制（追加到普通回复中）。 -- `/model status` 关注的是**模型/身份验证/端点**，不是使用量。 +- **提供商用量/配额**（示例：“Claude 剩余 80%”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余百分比”；对于 MiniMax，仅表示剩余的百分比字段会在显示前取反，并且 `model_remains` 响应会优先使用聊天模型条目以及带模型标记的套餐标签。 +- **Token/缓存行** 在 `/status` 中可以在实时会话快照信息稀疏时回退到最新的转录用量条目。已有的非零实时值仍然优先，并且在已存总量缺失或更小时，转录回退还可以恢复当前运行时模型标签以及更大的、面向提示词的总量。 +- **执行与运行时：** `/status` 会为有效的沙箱路径报告 `Execution`，并为实际运行会话的对象报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。 +- **每次响应的 token/成本** 由 `/usage off|tokens|full` 控制（附加到普通回复中）。 +- `/model status` 关注的是 **模型/凭证/端点**，而不是用量。 ## 模型选择（`/model`） @@ -338,16 +337,16 @@ x-i18n: /model status ``` -说明： +注意： -- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型系列 + 可用提供商）。 -- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉框以及 Submit 步骤。 +- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型家族 + 可用提供商）。 +- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单以及提交步骤。 - `/model <#>` 会从该选择器中选择（并在可能时优先使用当前提供商）。 -- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`，如可用）。 +- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用。 ## 调试覆盖 -`/debug` 允许你设置**仅运行时**的配置覆盖（内存中，不写入磁盘）。仅所有者可用。默认禁用；使用 `commands.debug: true` 启用。 +`/debug` 让你设置**仅运行时**配置覆盖（内存中，而不是磁盘）。仅限所有者。默认禁用；使用 `commands.debug: true` 启用。 示例： @@ -360,12 +359,12 @@ x-i18n: ``` -覆盖会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并返回磁盘上的配置。 +覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并返回磁盘上的配置。 -## 插件 trace 输出 +## 插件跟踪输出 -`/trace` 允许你在不打开完整详细模式的情况下，切换**会话范围的插件 trace/debug 行**。 +`/trace` 让你切换**会话范围内的插件跟踪/调试行**，无需开启完整详细模式。 示例： @@ -375,18 +374,18 @@ x-i18n: /trace off ``` -说明： +注意： -- 不带参数的 `/trace` 会显示当前会话 trace 状态。 -- `/trace on` 会为当前会话启用插件 trace 行。 +- 不带参数的 `/trace` 会显示当前会话跟踪状态。 +- `/trace on` 会为当前会话启用插件跟踪行。 - `/trace off` 会再次禁用它们。 -- 插件 trace 行可以出现在 `/status` 中，也可以在普通助手回复之后作为后续诊断消息出现。 +- 插件跟踪行可能出现在 `/status` 中，也可能在普通助手回复之后作为后续诊断消息出现。 - `/trace` 不会替代 `/debug`；`/debug` 仍然管理仅运行时配置覆盖。 -- `/trace` 不会替代 `/verbose`；普通的详细工具/Status 输出仍属于 `/verbose`。 +- `/trace` 不会替代 `/verbose`；普通的详细工具/Status 输出仍然属于 `/verbose`。 ## 配置更新 -`/config` 会写入你磁盘上的配置（`openclaw.json`）。仅所有者可用。默认禁用；使用 `commands.config: true` 启用。 +`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者。默认禁用；使用 `commands.config: true` 启用。 示例： @@ -399,12 +398,12 @@ x-i18n: ``` -写入前会验证配置；无效更改会被拒绝。`/config` 更新会在重启后保留。 +配置会在写入前进行验证；无效更改会被拒绝。`/config` 更新会在重启后保留。 ## MCP 更新 -`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅所有者可用。默认禁用；使用 `commands.mcp: true` 启用。 +`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者。默认禁用；使用 `commands.mcp: true` 启用。 示例： @@ -416,12 +415,12 @@ x-i18n: ``` -`/mcp` 会将配置存储在 OpenClaw 配置中，而不是 Pi 所有的项目设置中。运行时适配器会决定哪些传输协议实际可执行。 +`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定哪些传输协议实际可执行。 ## 插件更新 -`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以将 `/plugin` 用作别名。默认禁用；使用 `commands.plugins: true` 启用。 +`/plugins` 让操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。 示例： @@ -436,8 +435,8 @@ x-i18n: - `/plugins list` 和 `/plugins show` 会基于当前工作区以及磁盘上的配置执行真实插件发现。 - `/plugins install` 会从 ClawHub、npm、git、本地目录和归档安装。 -- `/plugins enable|disable` 只会更新插件配置；它不会安装或卸载插件。 -- 启用和禁用更改会为新的智能体轮次热重载 Gateway 网关插件运行时表面；安装会请求 Gateway 网关重启，因为插件源模块已更改。 +- `/plugins enable|disable` 仅更新插件配置；它不会安装或卸载插件。 +- 启用和禁用更改会为新的智能体轮次热重载 Gateway 网关插件运行时表面；安装会请求 Gateway 网关重启，因为插件源模块发生了变化。 @@ -445,35 +444,35 @@ x-i18n: - - **文本命令**在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。 - - **原生命令**使用隔离会话： + - **文本命令** 在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。 + - **原生命令** 使用隔离会话： - Discord：`agent::discord:slash:` - Slack：`agent::slack:slash:`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置） - - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位到聊天会话） - - **`/stop`** 会定位到活动聊天会话，因此它可以中止当前运行。 + - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位聊天会话） + - **`/stop`** 定位当前聊天会话，因此它可以中止当前运行。 - `channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格的命令。如果你启用 `commands.native`，必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式发送。 + `channels.slack.slashCommand` 仍然支持单个 `/openclaw` 风格的命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack slash command（名称与 `/help` 相同）。Slack 的命令参数菜单会作为临时的 Block Kit 按钮发送。 - Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。 + Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 仍可在 Slack 消息中使用。 -## BTW 旁支问题 +## BTW 附带问题 -`/btw` 是关于当前会话的快速**旁支问题**。`/side` 是别名。 +`/btw` 是关于当前会话的快速**附带问题**。`/side` 是别名。 与普通聊天不同： - 它使用当前会话作为背景上下文， -- 它以单独的**无工具**一次性调用运行， -- 它不会更改未来的会话上下文， +- 它作为单独的**无工具**一次性调用运行， +- 它不会改变未来的会话上下文， - 它不会写入转录历史， -- 它会作为实时旁支结果发送，而不是普通助手消息。 +- 它作为实时附带结果发送，而不是普通助手消息。 -这使得 `/btw` 适合在主任务继续推进时获取临时澄清。 +这使得 `/btw` 在你希望主任务继续进行时获得临时说明很有用。 示例： @@ -482,7 +481,7 @@ x-i18n: /side what changed while the main run continued? ``` -完整行为和客户端 UX 详情请参阅 [BTW 旁支问题](/zh-CN/tools/btw)。 +查看 [BTW 附带问题](/zh-CN/tools/btw)，了解完整行为和客户端 UX 细节。 ## 相关