From ed9c831b6299c42b440ca8a8bab8a6079d88bb55 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 17:26:39 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/discord.md | 386 ++++++++++++++++----------------- docs/zh-CN/channels/slack.md | 269 +++++++++++------------ docs/zh-CN/concepts/models.md | 194 +++++++++-------- 3 files changed, 422 insertions(+), 427 deletions(-) diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index 182ecb3f8..4b2b62f9f 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -1,22 +1,22 @@ --- read_when: - - 开发 Discord 渠道功能 + - 正在开发 Discord 渠道功能 summary: Discord 机器人支持状态、功能和配置 title: Discord x-i18n: - generated_at: "2026-04-24T03:37:11Z" + generated_at: "2026-04-24T17:24:33Z" model: gpt-5.4 provider: openai - source_hash: ce73e0e6995702f3b2453b2e5ab4e55b02190e64fdf5805f53b4002be63140a2 + source_hash: df5d215c6a6c43e1b3f60837752f60eafc6e34c1ffd4aaceb2f60d4dd3c130be source_path: channels/discord.md workflow: 15 --- -已准备好通过官方 Discord Gateway 网关支持私信和服务器频道。 +已通过官方 Discord Gateway 网关支持私信和 guild 渠道。 - Discord 私信默认使用配对模式。 + Discord 私信默认处于配对模式。 原生命令行为和命令目录。 @@ -26,40 +26,40 @@ x-i18n: -## 快速开始 +## 快速设置 -你需要创建一个带机器人的新应用，将机器人添加到你的服务器，并将其与 OpenClaw 配对。我们建议将你的机器人添加到你自己的私有服务器。如果你还没有服务器，请先[创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **Create My Own > For me and my friends**）。 +你需要创建一个带机器人的新应用，将机器人添加到你的服务器，并将其与 OpenClaw 配对。我们建议你将机器人添加到你自己的私有服务器。如果你还没有，请先[创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **Create My Own > For me and my friends**）。 - 前往 [Discord Developer Portal](https://discord.com/developers/applications)，然后点击 **New Application**。给它起一个类似 “OpenClaw” 的名字。 + 前往 [Discord Developer Portal](https://discord.com/developers/applications)，点击 **New Application**。给它起一个类似 “OpenClaw” 的名字。 点击侧边栏中的 **Bot**。将 **Username** 设置为你对 OpenClaw 智能体的称呼。 - 仍然停留在 **Bot** 页面，向下滚动到 **Privileged Gateway Intents** 并启用： + 仍然在 **Bot** 页面，向下滚动到 **Privileged Gateway Intents** 并启用： - **Message Content Intent**（必需） - - **Server Members Intent**（推荐；角色 allowlist 和名称到 ID 匹配所必需） - - **Presence Intent**（可选；仅在需要在线状态更新时才需要） + - **Server Members Intent**（推荐；角色白名单和名称到 ID 匹配需要它） + - **Presence Intent**（可选；仅在需要状态更新时使用） - 回到 **Bot** 页面顶部，然后点击 **Reset Token**。 + 向上滚动回 **Bot** 页面顶部，点击 **Reset Token**。 - 尽管名字叫这样，但这里生成的是你的第一个令牌——并没有任何内容被“重置”。 + 尽管名字如此，这会生成你的第一个令牌——并没有任何内容被“重置”。 - 复制该令牌并保存到某个地方。这就是你的 **Bot Token**，你很快就会用到它。 + 复制该令牌并保存到某个地方。这就是你的 **Bot Token**，你很快会用到它。 - 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，以便将机器人添加到你的服务器。 + 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用于将机器人添加到你的服务器。 向下滚动到 **OAuth2 URL Generator** 并启用： @@ -68,40 +68,40 @@ x-i18n: 下方会出现一个 **Bot Permissions** 部分。至少启用： - **常规权限** - - 查看频道 - **文本权限** - - 发送消息 - - 读取消息历史 - - 嵌入链接 - - 附加文件 - - 添加表情回应（可选） + **General Permissions** + - View Channels + **Text Permissions** + - Send Messages + - Read Message History + - Embed Links + - Attach Files + - Add Reactions（可选） - 这是普通文本频道的基础权限集合。如果你计划在 Discord 线程中发帖，包括会创建或继续线程的论坛或媒体频道工作流，还需要启用 **Send Messages in Threads**。 + 这是普通文本渠道的基础权限集。如果你计划在 Discord 主题帖中发帖，包括会创建或继续主题帖的 forum 或 media 渠道工作流，还需要启用 **Send Messages in Threads**。 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 完成连接。现在你应该可以在 Discord 服务器中看到你的机器人。 - 回到 Discord 应用中，你需要启用开发者模式，这样才能复制内部 ID。 + 回到 Discord 应用中，你需要启用开发者模式，以便复制内部 ID。 - 1. 点击 **User Settings**（你头像旁边的齿轮图标）→ **Advanced** → 打开 **Developer Mode** + 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 需要允许你的机器人向你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。 + 为了让配对生效，Discord 需要允许你的机器人向你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。 - 这样服务器成员（包括机器人）就可以向你发送私信。如果你想在 OpenClaw 中使用 Discord 私信，请保持此项开启。如果你只打算使用服务器频道，则可以在配对完成后关闭私信。 + 这会允许服务器成员（包括机器人）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持此项开启。如果你只打算使用 guild 渠道，则可以在配对完成后关闭私信。 - - 你的 Discord 机器人令牌是一个机密信息（类似密码）。在向你的智能体发送消息之前，请先在运行 OpenClaw 的机器上设置它。 + + 你的 Discord 机器人令牌是一个密钥（类似密码）。在给智能体发消息之前，请先在运行 OpenClaw 的机器上设置它。 ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -111,17 +111,17 @@ openclaw config set channels.discord.enabled true --strict-json openclaw gateway ``` - 如果 OpenClaw 已经作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或停止并重新启动 `openclaw gateway run` 进程。 + 如果 OpenClaw 已经作为后台服务在运行，请通过 OpenClaw Mac 应用重启它，或停止后重新启动 `openclaw gateway run` 进程。 - + - - 在任何现有渠道（例如 Telegram）上与你的 OpenClaw 智能体聊天，并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置标签页。 + + 在任何现有渠道（例如 Telegram）中与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置选项卡。 - > “我已经在配置中设置好了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” + > “我已经在配置中设置了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” 如果你更喜欢基于文件的配置，请设置： @@ -147,7 +147,7 @@ openclaw gateway DISCORD_BOT_TOKEN=... ``` - 支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商的 SecretRef 值。请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 + 支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商的 SecretRef 值。参见 [Secrets Management](/zh-CN/gateway/secrets)。 @@ -155,11 +155,11 @@ DISCORD_BOT_TOKEN=... - 等待 Gateway 网关运行后，在 Discord 中给你的机器人发送私信。它会回复一个配对码。 + 等待 Gateway 网关运行后，在 Discord 中向你的机器人发送私信。它会回复一个配对码。 - - 将配对码发送给你现有渠道上的智能体： + + 在你现有的渠道中将配对码发送给智能体： > “批准这个 Discord 配对码：``” @@ -175,27 +175,27 @@ openclaw pairing approve discord 配对码会在 1 小时后过期。 - 现在你应该可以通过私信在 Discord 中与你的智能体聊天了。 + 现在你应该已经可以通过 Discord 私信与你的智能体聊天了。 令牌解析是账户感知的。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 -对于高级出站调用（消息工具/渠道操作），显式的每次调用 `token` 会用于该次调用。这适用于发送以及读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍然来自活动运行时快照中选定的账户。 +对于高级出站调用（消息工具/渠道操作），显式的每次调用 `token` 会用于该次调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍然来自活动运行时快照中所选的账户。 -## 推荐：设置服务器工作区 +## 推荐：设置一个 guild 工作区 -一旦私信可用，你就可以将 Discord 服务器设置为完整工作区，其中每个频道都有自己的智能体会话和独立上下文。这对于只有你和你的机器人的私有服务器来说尤其推荐。 +一旦私信可用，你就可以将 Discord 服务器设置为完整工作区，其中每个渠道都有自己独立的智能体会话和上下文。对于只有你和机器人使用的私有服务器，我们推荐这样做。 - - 这样你的智能体就可以在你的服务器的任何频道中回复，而不仅限于私信。 + + 这会让你的智能体能够在服务器中的任意渠道中响应，而不仅仅是在私信中。 - - > “把我的 Discord Server ID `` 添加到 guild allowlist” + + > “将我的 Discord Server ID `` 添加到 guild 允许列表” @@ -220,12 +220,12 @@ openclaw pairing approve discord - - 默认情况下，你的智能体只有在被 @ 提及时才会在服务器频道中回复。对于私有服务器，你很可能希望它对每条消息都进行回复。 + + 默认情况下，你的智能体只会在被 @mentioned 时才在 guild 渠道中回复。对于私有服务器，你可能更希望它对每条消息都作出响应。 - - > “允许我的智能体在这个服务器中无需被 @ 提及也能回复” + + > “允许我的智能体在这个服务器中无需被 @mentioned 就能回复” 在你的 guild 配置中设置 `requireMention: false`： @@ -249,82 +249,82 @@ openclaw pairing approve discord - - 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。服务器频道不会自动加载 MEMORY.md。 + + 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。guild 渠道不会自动加载 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` 中，并在需要时通过 memory 工具访问。 -现在，在你的 Discord 服务器中创建一些频道并开始聊天吧。你的智能体可以看到频道名称，并且每个频道都有自己隔离的会话——因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的频道。 +现在，在你的 Discord 服务器上创建一些渠道并开始聊天。你的智能体可以看到渠道名称，并且每个渠道都会获得各自独立隔离的会话——因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的名称。 ## 运行时模型 -- Gateway 网关持有 Discord 连接。 +- Gateway 网关拥有 Discord 连接。 - 回复路由是确定性的：来自 Discord 的入站回复会返回到 Discord。 - 默认情况下（`session.dmScope=main`），私聊共享智能体主会话（`agent:main:main`）。 -- 服务器频道使用隔离的会话键（`agent::discord:channel:`）。 -- 群组私信默认会被忽略（`channels.discord.dm.groupEnabled=false`）。 -- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍会携带 `CommandTargetSessionKey` 到被路由的对话会话。 +- Guild 渠道使用隔离的会话键（`agent::discord:channel:`）。 +- 默认忽略群组私信（`channels.discord.dm.groupEnabled=false`）。 +- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍会将 `CommandTargetSessionKey` 传递到路由后的对话会话。 -## 论坛频道 +## Forum 渠道 -Discord 论坛和媒体频道只接受线程帖子。OpenClaw 支持两种创建方式： +Discord 的 forum 和 media 渠道只接受主题帖形式的发帖。OpenClaw 支持两种创建方式： -- 向论坛父频道（`channel:`）发送消息以自动创建线程。线程标题会使用你消息中的第一行非空内容。 -- 使用 `openclaw message thread create` 直接创建线程。对于论坛频道，不要传递 `--message-id`。 +- 向 forum 父级渠道（`channel:`）发送消息以自动创建主题帖。主题标题使用消息中第一行非空内容。 +- 使用 `openclaw message thread create` 直接创建主题帖。对于 forum 渠道，不要传递 `--message-id`。 -示例：发送到论坛父频道以创建线程 +示例：发送到 forum 父级渠道以创建主题帖 ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -示例：显式创建论坛线程 +示例：显式创建 forum 主题帖 ```bash openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -论坛父频道不接受 Discord 组件。如果你需要组件，请发送到线程本身（`channel:`）。 +Forum 父级渠道不接受 Discord 组件。如果你需要组件，请发送到主题帖本身（`channel:`）。 ## 交互式组件 -OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `components` 负载的消息工具。交互结果会像普通入站消息一样路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 +OpenClaw 支持在智能体消息中使用 Discord components v2 容器。使用带有 `components` 负载的消息工具。交互结果会像普通入站消息一样路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 支持的块： - `text`、`section`、`separator`、`actions`、`media-gallery`、`file` -- 操作行最多允许 5 个按钮或 1 个单选菜单 +- 操作行最多允许 5 个按钮或 1 个选择菜单 - 选择类型：`string`、`user`、`role`、`mentionable`、`channel` -默认情况下，组件是单次使用的。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前被多次使用。 +默认情况下，组件是一次性使用的。设置 `components.reusable=true` 可让按钮、选择器和表单在过期前被多次使用。 -若要限制谁可以点击某个按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到临时拒绝提示。 +要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商和模型下拉菜单以及一个提交步骤。除非 `commands.modelsWrite=false`，否则 `/models add` 也支持通过聊天添加新的提供商/模型条目，且新添加的模型无需重启 Gateway 网关就会显示出来。选择器回复是临时的，并且只有调用它的用户可以使用。 +`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商和模型下拉菜单以及一个提交步骤。`/models add` 已弃用，现在会返回弃用提示消息，而不是通过聊天注册模型。选择器回复是临时的，且只有调用该命令的用户可以使用。 文件附件： - `file` 块必须指向一个附件引用（`attachment://`） -- 通过 `media` / `path` / `filePath` 提供附件（单个文件）；多个文件请使用 `media-gallery` -- 当上传名称应与附件引用匹配时，使用 `filename` 覆盖上传名称 +- 通过 `media`/`path`/`filePath` 提供附件（单个文件）；多个文件请使用 `media-gallery` +- 当上传名称需要与附件引用匹配时，使用 `filename` 覆盖上传文件名 模态表单： - 添加 `components.modal`，最多支持 5 个字段 - 字段类型：`text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` -- OpenClaw 会自动添加一个触发按钮 +- OpenClaw 会自动添加一个触发表单按钮 示例： @@ -391,12 +391,12 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - `open`（要求 `channels.discord.allowFrom` 包含 `"*"`；旧版：`channels.discord.dm.allowFrom`） - `disabled` - 如果私信策略不是 open，未知用户会被阻止（或在 `pairing` 模式下被提示进行配对）。 + 如果私信策略不是 open，未知用户将被阻止（或在 `pairing` 模式下提示配对）。 多账户优先级： - `channels.discord.accounts.default.allowFrom` 仅适用于 `default` 账户。 - - 当命名账户自己的 `allowFrom` 未设置时，它们会继承 `channels.discord.allowFrom`。 + - 当命名账户自身未设置 `allowFrom` 时，会继承 `channels.discord.allowFrom`。 - 命名账户不会继承 `channels.discord.accounts.default.allowFrom`。 用于投递的私信目标格式： @@ -404,12 +404,12 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - `user:` - `<@id>` 提及 - 纯数字 ID 存在歧义，除非明确提供 user/channel 目标类型，否则会被拒绝。 + 纯数字 ID 存在歧义，除非显式提供 user/channel 目标类型，否则会被拒绝。 - - 服务器处理由 `channels.discord.groupPolicy` 控制： + + Guild 处理由 `channels.discord.groupPolicy` 控制： - `open` - `allowlist` @@ -419,12 +419,12 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c `allowlist` 行为： - - 服务器必须匹配 `channels.discord.guilds`（优先使用 `id`，也接受 slug） - - 可选的发送者 allowlist：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了其中任一项，当发送者匹配 `users` 或 `roles` 时即可被允许 + - guild 必须匹配 `channels.discord.guilds`（优先使用 `id`，也接受 slug） + - 可选的发送者允许列表：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了其中任一项，则当发送者匹配 `users` 或 `roles` 时允许通过 - 默认禁用直接名称/标签匹配；仅在紧急兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true` - `users` 支持名称/标签，但 ID 更安全；当使用名称/标签条目时，`openclaw security audit` 会发出警告 - - 如果某个服务器配置了 `channels`，则未列出的频道会被拒绝 - - 如果某个服务器没有 `channels` 块，则该 allowlist 服务器中的所有频道都被允许 + - 如果某个 guild 配置了 `channels`，则未列出的渠道会被拒绝 + - 如果某个 guild 没有 `channels` 块，则该允许列表 guild 中的所有渠道都允许 示例： @@ -450,33 +450,33 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - 如果你只设置了 `DISCORD_BOT_TOKEN`，但没有创建 `channels.discord` 块，则运行时回退为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open`。 + 如果你只设置了 `DISCORD_BOT_TOKEN` 而没有创建 `channels.discord` 块，则运行时回退为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open` 也是如此。 - 服务器消息默认受提及门控。 + 默认情况下，guild 消息需要提及才会触发。 提及检测包括： - 显式提及机器人 - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） - - 在支持场景下的隐式回复机器人行为 + - 在受支持情况下的隐式回复机器人行为 - `requireMention` 按服务器/频道配置（`channels.discord.guilds...`）。 + `requireMention` 按 guild/渠道配置（`channels.discord.guilds...`）。 `ignoreOtherMentions` 可选择性丢弃那些提及了其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 群组私信： - 默认：忽略（`dm.groupEnabled=false`） - - 可选 allowlist：通过 `dm.groupChannels`（频道 ID 或 slug） + - 可选允许列表：通过 `dm.groupChannels`（渠道 ID 或 slug） ### 基于角色的智能体路由 -使用 `bindings[].match.roles`，按角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并且会在 peer 或 parent-peer 绑定之后、guild-only 绑定之前进行评估。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 +使用 `bindings[].match.roles` 按角色 ID 将 Discord guild 成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并且会在 peer 或 parent-peer 绑定之后、guild-only 绑定之前进行评估。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 ```json5 { @@ -503,12 +503,12 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c ## 原生命令和命令认证 - `commands.native` 默认为 `"auto"`，并且对 Discord 启用。 -- 每个渠道的覆盖项：`channels.discord.commands.native`。 -- `commands.native=false` 会显式清除先前已注册的 Discord 原生命令。 -- 原生命令认证使用与普通消息处理相同的 Discord allowlist / 策略。 -- 即使对于未获授权的用户，这些命令仍可能在 Discord UI 中可见；但执行时仍会强制 OpenClaw 认证，并返回“not authorized”。 +- 按渠道覆盖：`channels.discord.commands.native`。 +- `commands.native=false` 会显式清除之前已注册的 Discord 原生命令。 +- 原生命令认证使用与普通消息处理相同的 Discord 允许列表/策略。 +- 对于未获授权的用户，命令仍可能在 Discord UI 中可见；但执行时仍会强制执行 OpenClaw 认证，并返回“未授权”。 -有关命令目录和行为，请参阅[斜杠命令](/zh-CN/tools/slash-commands)。 +命令目录和行为请参见[斜杠命令](/zh-CN/tools/slash-commands)。 默认斜杠命令设置： @@ -530,18 +530,18 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - `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`。在 Discord 上，`progress` 会映射为 `partial`；`streamMode` 是旧版别名，会被自动迁移。 - 默认仍为 `off`，因为当多个机器人或 Gateway 网关共享同一账户时，Discord 预览编辑很容易触发速率限制。 + 默认仍为 `off`，因为当多个机器人或 Gateway 网关共享同一个账户时，Discord 预览编辑很快会触及速率限制。 ```json5 { @@ -558,17 +558,17 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - - `partial` 会在 token 到达时编辑同一条预览消息。 - - `block` 会输出草稿大小的分块（使用 `draftChunk` 调整大小和断点，并受 `textChunkLimit` 限制）。 + - `partial` 会在 token 到达时编辑单条预览消息。 + - `block` 会输出按草稿大小切分的块（使用 `draftChunk` 调整大小和断点，受限于 `textChunkLimit`）。 - 媒体、错误和显式回复的最终消息会取消待处理的预览编辑。 - - `streaming.preview.toolProgress`（默认 `true`）控制工具/进度更新是否复用预览消息。 + - `streaming.preview.toolProgress`（默认 `true`）控制工具/进度更新是否复用该预览消息。 - 预览流式传输仅支持文本；媒体回复会回退为普通投递。当显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 + 预览流式传输仅支持文本；媒体回复会回退到正常投递。当显式启用 `block` 分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 - - 服务器历史上下文： + + Guild 历史上下文： - `channels.discord.historyLimit` 默认 `20` - 回退：`messages.groupChat.historyLimit` @@ -581,25 +581,25 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 线程行为： - - Discord 线程按频道会话路由，并继承父频道配置，除非被覆盖。 - - `channels.discord.thread.inheritParent`（默认 `false`）允许新自动线程从父级对话记录播种。每账户覆盖项位于 `channels.discord.accounts..thread.inheritParent`。 - - 消息工具的回应可以解析 `user:` 私信目标。 - - `guilds..channels..requireMention: false` 会在回复阶段激活回退期间被保留。 + - Discord 线程按渠道会话进行路由，并继承父渠道配置，除非被覆盖。 + - `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 ` 查看/更新聚焦绑定的硬性最大存活时间 配置： @@ -630,15 +630,15 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - `session.threadBindings.*` 设置全局默认值。 - `channels.discord.threadBindings.*` 覆盖 Discord 行为。 - `spawnSubagentSessions` 必须为 true，才能为 `sessions_spawn({ thread: true })` 自动创建/绑定线程。 - - `spawnAcpSessions` 必须为 true，才能为 ACP 自动创建/绑定线程（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）。 - - 如果某个账户禁用了线程绑定，则 `/focus` 和相关线程绑定操作不可用。 + - `spawnAcpSessions` 必须为 true，才能为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建/绑定线程。 + - 如果某个账户禁用了线程绑定，则 `/focus` 及相关线程绑定操作不可用。 - 请参阅[子智能体](/zh-CN/tools/subagents)、[ACP Agents](/zh-CN/tools/acp-agents) 和[配置参考](/zh-CN/gateway/configuration-reference)。 + 参见[子智能体](/zh-CN/tools/subagents)、[ACP Agents](/zh-CN/tools/acp-agents) 和[配置参考](/zh-CN/gateway/configuration-reference)。 - - 对于稳定的“始终在线” ACP 工作区，请配置面向 Discord 对话的顶层类型化 ACP 绑定。 + + 对于稳定的“始终在线” ACP 工作区，可配置以 Discord 对话为目标的顶层类型化 ACP 绑定。 配置路径： @@ -694,39 +694,39 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 说明： - - `/acp spawn codex --bind here` 会就地绑定当前频道或线程，并让后续消息持续停留在同一个 ACP 会话中。线程消息会继承父频道绑定。 - - 在已绑定的频道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时线程绑定在生效期间可以覆盖目标解析。 + - `/acp spawn codex --bind here` 会就地绑定当前渠道或线程，并让后续消息持续使用同一个 ACP 会话。线程消息会继承父渠道绑定。 + - 在已绑定的渠道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时线程绑定在激活时可以覆盖目标解析。 - 只有当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子线程时，才需要 `spawnAcpSessions`。 - 有关绑定行为的详细信息，请参阅 [ACP Agents](/zh-CN/tools/acp-agents)。 + 绑定行为详情请参见 [ACP Agents](/zh-CN/tools/acp-agents)。 - 每个服务器的反应通知模式： + 按 guild 配置的反应通知模式： - `off` - `own`（默认） - `all` - `allowlist`（使用 `guilds..users`） - 反应事件会转换为系统事件，并附加到已路由的 Discord 会话中。 + 反应事件会被转换为系统事件，并附加到路由后的 Discord 会话中。 - `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情。 + `ackReaction` 会在 OpenClaw 处理入站消息期间发送一个确认 emoji。 解析顺序： - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - 智能体身份表情回退（`agents.list[].identity.emoji`，否则为 “👀”） + - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 "👀"） 说明： - - Discord 接受 unicode 表情或自定义表情名称。 + - Discord 接受 unicode emoji 或自定义 emoji 名称。 - 使用 `""` 可为某个渠道或账户禁用该反应。 @@ -751,7 +751,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - 使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord Gateway 网关 WebSocket 流量以及启动时的 REST 查询（应用 ID + allowlist 解析）。 + 使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord Gateway 网关 WebSocket 流量和启动时的 REST 查询（应用 ID + allowlist 解析）。 ```json5 { @@ -763,7 +763,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - 每账户覆盖： + 按账户覆盖： ```json5 { @@ -799,10 +799,10 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 说明： - - allowlist 可使用 `pk:` - - 只有在 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名称 + - allowlist 可以使用 `pk:` + - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名 - 查询使用原始消息 ID，并受时间窗口限制 - - 如果查询失败，代理消息会被视为机器人消息并被丢弃，除非 `allowBots=true` + - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非 `allowBots=true` @@ -827,20 +827,20 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c { channels: { discord: { - activity: "Focus time", + activity: "专注时间", activityType: 4, }, }, } ``` - 直播示例： + Streaming 示例： ```json5 { channels: { discord: { - activity: "Live coding", + activity: "直播编程", activityType: 1, activityUrl: "https://twitch.tv/openclaw", }, @@ -854,7 +854,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - 1：Streaming（需要 `activityUrl`） - 2：Listening - 3：Watching - - 4：Custom（使用活动文本作为状态内容；表情可选） + - 4：Custom（使用活动文本作为状态内容；emoji 可选） - 5：Competing 自动在线状态示例（运行时健康信号）： @@ -874,7 +874,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - 自动在线状态会将运行时可用性映射到 Discord 状态：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖项： + 自动在线状态会将运行时可用性映射到 Discord 状态：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -892,50 +892,50 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` - 当 `enabled` 未设置或为 `"auto"`，并且至少可以从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个审批人时，Discord 会自动启用原生 exec 审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec 审批人。设置 `enabled: false` 可显式禁用 Discord 作为原生审批客户端。 + 当 `enabled` 未设置或为 `"auto"`，且至少能从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个审批人时，Discord 会自动启用原生 exec 审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec 审批人。设置 `enabled: false` 可显式禁用 Discord 作为原生审批客户端。 - 当 `target` 为 `channel` 或 `both` 时，审批提示会显示在该频道中。只有已解析的审批人可以使用这些按钮；其他用户会收到临时拒绝提示。审批提示包含命令文本，因此只应在受信任的频道中启用渠道投递。如果无法从会话键推导出频道 ID，OpenClaw 会回退为私信投递。 + 当 `target` 为 `channel` 或 `both` 时，审批提示会显示在渠道中。只有已解析的审批人可以使用这些按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此仅应在受信任渠道中启用渠道投递。如果无法从会话键推导出渠道 ID，OpenClaw 会回退到私信投递。 - Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要增加了审批人私信路由和渠道扇出。 - 当这些按钮存在时，它们就是主要的审批 UX；只有当工具结果显示聊天审批不可用，或者手动审批是唯一可行路径时，OpenClaw 才应包含手动 `/approve` 命令。 + Discord 还会渲染其他聊天渠道共用的审批按钮。原生 Discord 适配器主要增加了审批人私信路由和渠道扇出。 + 当这些按钮存在时，它们就是主要的审批 UX；只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，OpenClaw 才应包含手动 `/approve` 命令。 - Gateway 网关认证和审批解析遵循共享的 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。审批默认会在 30 分钟后过期。 + Gateway 网关认证和审批解析遵循共享的 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。默认情况下，审批会在 30 分钟后过期。 - 请参阅 [Exec approvals](/zh-CN/tools/exec-approvals)。 + 参见 [Exec approvals](/zh-CN/tools/exec-approvals)。 ## 工具和操作门控 -Discord 消息操作包括消息收发、频道管理、审核、在线状态和元数据操作。 +Discord 消息操作包括消息发送、渠道管理、审核、在线状态和元数据操作。 核心示例： -- 消息收发：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` +- 消息：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` - 反应：`react`、`reactions`、`emojiList` - 审核：`timeout`、`kick`、`ban` - 在线状态：`setPresence` -`event-create` 操作接受一个可选的 `image` 参数（URL 或本地文件路径），用于设置计划事件封面图。 +`event-create` 操作接受一个可选的 `image` 参数（URL 或本地文件路径），用于设置计划事件封面图片。 操作门控位于 `channels.discord.actions.*` 下。 默认门控行为： -| 操作组 | 默认值 | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 启用 | -| roles | 禁用 | -| moderation | 禁用 | -| presence | 禁用 | +| 操作组 | 默认值 | +| --- | --- | +| reactions、messages、threads、pins、polls、search、memberInfo、roleInfo、channelInfo、channels、voiceStatus、events、stickers、emojiUploads、stickerUploads、permissions | enabled | +| roles | disabled | +| moderation | disabled | +| presence | disabled | ## Components v2 UI -OpenClaw 使用 Discord components v2 来实现 exec 审批和跨上下文标记。Discord 消息操作也可以接受 `components` 来构建自定义 UI（高级用法；需要通过 discord 工具构造组件负载），而旧版 `embeds` 仍然可用，但不推荐。 +OpenClaw 对 exec 审批和跨上下文标记使用 Discord components v2。Discord 消息操作也可以接受 `components` 以构建自定义 UI（高级用法；需要通过 discord 工具构造组件负载），而旧版 `embeds` 仍可用，但不推荐。 - `channels.discord.ui.components.accentColor` 设置 Discord 组件容器使用的强调色（十六进制）。 -- 可通过 `channels.discord.accounts..ui.components.accentColor` 按账户设置。 +- 按账户设置请使用 `channels.discord.accounts..ui.components.accentColor`。 - 当存在 components v2 时，`embeds` 会被忽略。 示例： @@ -956,17 +956,17 @@ OpenClaw 使用 Discord components v2 来实现 exec 审批和跨上下文标记 ## 语音 -Discord 有两种不同的语音表面：实时**语音频道**（持续对话）和**语音消息附件**（波形预览格式）。Gateway 网关同时支持这两种形式。 +Discord 有两个不同的语音表面：实时**语音渠道**（连续对话）和**语音消息附件**（波形预览格式）。Gateway 网关同时支持这两种。 -### 语音频道 +### 语音渠道 要求： - 启用原生命令（`commands.native` 或 `channels.discord.commands.native`）。 - 配置 `channels.discord.voice`。 -- 机器人在目标语音频道中需要 Connect 和 Speak 权限。 +- 机器人需要在目标语音渠道中具备 Connect 和 Speak 权限。 -使用 `/vc join|leave|status` 控制会话。该命令使用账户默认智能体，并遵循与其他 Discord 命令相同的 allowlist 和服务器策略规则。 +使用 `/vc join|leave|status` 控制会话。该命令使用账户默认智能体，并遵循与其他 Discord 命令相同的 allowlist 和群组策略规则。 自动加入示例： @@ -997,19 +997,19 @@ Discord 有两种不同的语音表面：实时**语音频道**（持续对话 说明： - `voice.tts` 仅覆盖语音播放的 `messages.tts`。 -- 语音转录轮次会根据 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者说话者不能访问仅限所有者的工具（例如 `gateway` 和 `cron`）。 +- 语音转写轮次从 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者说话者不能访问仅限所有者的工具（例如 `gateway` 和 `cron`）。 - 语音默认启用；设置 `channels.discord.voice.enabled=false` 可禁用。 - `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的加入选项。 -- 如果未设置，`@discordjs/voice` 的默认值是 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 -- OpenClaw 还会监测接收解密失败，并在短时间内重复失败后通过离开/重新加入语音频道自动恢复。 +- 如果未设置，`@discordjs/voice` 默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 +- OpenClaw 还会监视接收解密失败，并在短时间内重复失败后通过离开/重新加入语音渠道自动恢复。 - 如果接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，这可能是上游 `@discordjs/voice` 接收缺陷，见 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)。 ### 语音消息 -Discord 语音消息会显示波形预览，并要求使用 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要在 Gateway 网关主机上提供 `ffmpeg` 和 `ffprobe` 来进行检测和转换。 +Discord 语音消息会显示波形预览，并需要 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要在 Gateway 网关主机上安装 `ffmpeg` 和 `ffprobe` 来检测和转换音频。 - 提供**本地文件路径**（不接受 URL）。 -- 省略文本内容（Discord 会拒绝同一负载中的文本 + 语音消息）。 +- 不要附带文本内容（Discord 会拒绝同时包含文本和语音消息的负载）。 - 接受任意音频格式；OpenClaw 会在需要时将其转换为 OGG/Opus。 ```bash @@ -1019,22 +1019,22 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## 故障排除 - + - 启用 Message Content Intent - - 如果你依赖用户/成员解析，则启用 Server Members Intent - - 更改 intents 后重启 Gateway 网关 + - 当你依赖用户/成员解析时，启用 Server Members Intent + - 修改 intents 后重启 Gateway 网关 - + - - 检查 `groupPolicy` - - 检查 `channels.discord.guilds` 下的服务器 allowlist - - 如果存在服务器 `channels` 映射，则只允许列出的频道 - - 检查 `requireMention` 行为和提及模式 + - 验证 `groupPolicy` + - 验证 `channels.discord.guilds` 下的 guild allowlist + - 如果存在 guild `channels` 映射，则仅允许已列出的渠道 + - 验证 `requireMention` 行为和提及模式 - 有用的检查命令： + 常用检查： ```bash openclaw doctor @@ -1044,16 +1044,16 @@ openclaw logs --follow - + 常见原因： - - `groupPolicy="allowlist"`，但没有匹配的服务器/频道 allowlist - - `requireMention` 配置在了错误的位置（必须位于 `channels.discord.guilds` 下或频道条目下） - - 发送者被服务器/频道 `users` allowlist 阻止 + - `groupPolicy="allowlist"` 但没有匹配的 guild/渠道 allowlist + - `requireMention` 配置在错误位置（必须位于 `channels.discord.guilds` 或渠道条目下） + - 发送者被 guild/渠道 `users` allowlist 阻止 - + 典型日志： @@ -1061,12 +1061,12 @@ openclaw logs --follow - `Slow listener detected ...` - `discord inbound worker timed out after ...` - 监听器预算调节项： + 监听器预算旋钮： - 单账户：`channels.discord.eventQueue.listenerTimeout` - 多账户：`channels.discord.accounts..eventQueue.listenerTimeout` - worker 运行超时调节项： + Worker 运行超时旋钮： - 单账户：`channels.discord.inboundWorker.runTimeoutMs` - 多账户：`channels.discord.accounts..inboundWorker.runTimeoutMs` @@ -1093,12 +1093,12 @@ openclaw logs --follow } ``` - 对于缓慢的监听器初始化，请使用 `eventQueue.listenerTimeout`；仅当你希望为排队中的智能体轮次设置单独的安全阀时，才使用 `inboundWorker.runTimeoutMs`。 + 对于慢速监听器设置，请使用 `eventQueue.listenerTimeout`；仅当你希望为排队的智能体轮次设置单独的安全阀时，才使用 `inboundWorker.runTimeoutMs`。 - `channels status --probe` 权限检查仅适用于数字频道 ID。 + `channels status --probe` 权限检查仅适用于数字渠道 ID。 如果你使用 slug 键，运行时匹配仍然可以工作，但 probe 无法完整验证权限。 @@ -1113,29 +1113,29 @@ openclaw logs --follow - 默认情况下，由机器人发送的消息会被忽略。 + 默认情况下，会忽略由机器人发送的消息。 如果你设置了 `channels.discord.allowBots=true`，请使用严格的提及和 allowlist 规则以避免循环行为。 - 建议使用 `channels.discord.allowBots="mentions"`，这样只接受提及该机器人的机器人消息。 + 更推荐使用 `channels.discord.allowBots="mentions"`，仅接受提及该机器人的机器人消息。 - 保持 OpenClaw 为最新版本（`openclaw update`），以确保包含 Discord 语音接收恢复逻辑 - - 确认 `channels.discord.voice.daveEncryption=true`（默认） + - 确认 `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 #11419](https://github.com/discordjs/discord.js/issues/11419) 对比 ## 配置参考 -主要参考： [配置参考 - Discord](/zh-CN/gateway/config-channels#discord)。 +主要参考：[配置参考 - Discord](/zh-CN/gateway/config-channels#discord)。 @@ -1157,7 +1157,7 @@ openclaw logs --follow ## 安全和运维 -- 将机器人令牌视为机密（在受监管环境中推荐使用 `DISCORD_BOT_TOKEN`）。 +- 将机器人令牌视为密钥（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 - 授予最小权限的 Discord 权限。 - 如果命令部署/状态已过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。 @@ -1177,7 +1177,7 @@ openclaw logs --follow 威胁模型和加固。 - 将服务器和频道映射到智能体。 + 将 guild 和渠道映射到智能体。 原生命令行为。 diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index a40f7dd6b..fd1970caa 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -1,18 +1,18 @@ --- read_when: - 设置 Slack 或调试 Slack socket/HTTP 模式 -summary: Slack 设置和运行时行为（Socket Mode + HTTP 请求 URL） +summary: Slack 设置与运行时行为（Socket Mode + HTTP 请求 URL） title: Slack x-i18n: - generated_at: "2026-04-24T03:37:12Z" + generated_at: "2026-04-24T17:24:32Z" model: gpt-5.4 provider: openai - source_hash: 906a4fcf00a51f4a9b8410f982abe1f068687b5aa9847a4894f489e57fa9e4dd + source_hash: 830fe844f1f278062de3c186f2b7865684962c10dfb2740a42bf7b47e342b534 source_path: channels/slack.md workflow: 15 --- -通过 Slack 应用集成即可为私信和渠道提供生产可用支持。默认模式为 Socket Mode；同时也支持 HTTP 请求 URL。 +适用于通过 Slack 应用集成在私信和渠道中进行生产环境使用。默认模式为 Socket Mode；也支持 HTTP 请求 URL。 @@ -26,7 +26,7 @@ x-i18n: -## 快速开始 +## 快速设置 @@ -35,9 +35,9 @@ x-i18n: 在 Slack 应用设置中，点击 **[Create New App](https://api.slack.com/apps/new)** 按钮： - 选择 **from a manifest**，并为你的应用选择一个工作区 - - 粘贴下方的[示例清单](#manifest-and-scope-checklist)，然后继续创建 + - 粘贴下面的[示例清单](#manifest-and-scope-checklist)，然后继续创建 - 生成一个带有 `connections:write` 权限的 **App-Level Token**（`xapp-...`） - - 安装应用并复制显示出的 **Bot Token**（`xoxb-...`） + - 安装应用，并复制显示的 **Bot Token**（`xoxb-...`） @@ -82,8 +82,8 @@ openclaw gateway - 选择 **from a manifest**，并为你的应用选择一个工作区 - 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL - - 保存用于请求校验的 **Signing Secret** - - 安装应用并复制显示出的 **Bot Token**（`xoxb-...`） + - 保存用于请求验证的 **Signing Secret** + - 安装应用，并复制显示的 **Bot Token**（`xoxb-...`） @@ -104,9 +104,9 @@ openclaw gateway ``` - 为多账户 HTTP 使用唯一的 webhook 路径 + 对多账户 HTTP 使用唯一的 webhook 路径 - 为每个账户提供不同的 `webhookPath`（默认是 `/slack/events`），这样注册时就不会发生冲突。 + 为每个账户指定不同的 `webhookPath`（默认是 `/slack/events`），这样注册就不会发生冲突。 @@ -123,9 +123,9 @@ openclaw gateway -## 清单和 scope 检查清单 +## 清单和作用域检查清单 -Socket Mode 和 HTTP 请求 URL 使用相同的基础 Slack 应用清单。只有 `settings` 代码块（以及斜杠命令的 `url`）不同。 +Socket Mode 和 HTTP 请求 URL 使用相同的基础 Slack 应用清单。只有 `settings` 块（以及斜杠命令的 `url`）不同。 基础清单（Socket Mode 默认）： @@ -199,7 +199,7 @@ Socket Mode 和 HTTP 请求 URL 使用相同的基础 Slack 应用清单。只 } ``` -对于**HTTP 请求 URL 模式**，请将 `settings` 替换为 HTTP 变体，并为每个斜杠命令添加 `url`。需要公开 URL： +对于 **HTTP 请求 URL 模式**，请将 `settings` 替换为 HTTP 变体，并为每个斜杠命令添加 `url`。需要公共 URL： ```json { @@ -217,7 +217,7 @@ Socket Mode 和 HTTP 请求 URL 使用相同的基础 Slack 应用清单。只 "event_subscriptions": { "request_url": "https://gateway-host.example.com/slack/events", "bot_events": [ - /* same as Socket Mode */ + /* 与 Socket Mode 相同 */ ] }, "interactivity": { @@ -231,17 +231,17 @@ Socket Mode 和 HTTP 请求 URL 使用相同的基础 Slack 应用清单。只 ### 其他清单设置 -呈现可扩展上述默认值的不同功能。 +展示扩展上述默认值的不同功能。 - 可以使用多个[原生斜杠命令](#commands-and-slash-behavior)来替代单个已配置命令，但有一些细节需要注意： + 可以使用多个[原生斜杠命令](#commands-and-slash-behavior)来代替单个已配置命令，但有一些细微差别： - 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已被保留。 - - 同时可用的斜杠命令不能超过 25 个。 + - 同时最多只能提供 25 个斜杠命令。 - 将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)中的一个子集： + 用[可用命令](/zh-CN/tools/slash-commands#command-list)的一个子集替换你现有的 `features.slash_commands` 部分： @@ -308,8 +308,8 @@ Socket Mode 和 HTTP 请求 URL 使用相同的基础 Slack 应用清单。只 }, { "command": "/models", - "description": "List providers/models or add a model", - "usage_hint": "[provider] [page] [limit=|size=|all] | add " + "description": "List providers/models", + "usage_hint": "[provider] [page] [limit=|size=|all]" }, { "command": "/help", @@ -376,7 +376,7 @@ Socket Mode 和 HTTP 请求 URL 使用相同的基础 Slack 应用清单。只 "description": "Show the short help summary", "url": "https://gateway-host.example.com/slack/events" } - // ...repeat for every command with the same `url` value + // ...为每个命令重复添加相同的 `url` 值 ] ``` @@ -384,14 +384,14 @@ Socket Mode 和 HTTP 请求 URL 使用相同的基础 Slack 应用清单。只 - - 如果你希望发出的消息使用当前智能体身份（自定义用户名和图标）而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。 + + 如果你希望发出的消息使用当前智能体身份（自定义用户名和图标）而不是默认 Slack 应用身份，请添加 `chat:write.customize` bot scope。 - 如果你使用 emoji 图标，Slack 期望采用 `:emoji_name:` 语法。 + 如果你使用表情符号图标，Slack 需要 `:emoji_name:` 语法。 - - 如果你配置了 `channels.slack.userToken`，常见读取 scope 包括： + + 如果你配置了 `channels.slack.userToken`，典型的读取作用域包括： - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -408,42 +408,37 @@ Socket Mode 和 HTTP 请求 URL 使用相同的基础 Slack 应用清单。只 - Socket Mode 需要 `botToken` + `appToken`。 - HTTP 模式需要 `botToken` + `signingSecret`。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受纯文本 - 字符串或 SecretRef 对象。 -- 配置中的令牌会覆盖环境变量回退值。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 +- 配置中的令牌会覆盖环境变量回退。 - `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账户。 -- `userToken`（`xoxp-...`）仅支持通过配置提供（没有环境变量回退），并默认采用只读行为（`userTokenReadOnly: true`）。 +- `userToken`（`xoxp-...`）仅支持通过配置设置（没有环境变量回退），并且默认是只读行为（`userTokenReadOnly: true`）。 状态快照行为： -- Slack 账户检查会跟踪每个凭证的 `*Source` 和 `*Status` - 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。 +- Slack 账户检查会跟踪每个凭证的 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。 - 状态可以是 `available`、`configured_unavailable` 或 `missing`。 -- `configured_unavailable` 表示该账户通过 SecretRef - 或其他非内联密钥来源进行了配置，但当前命令/运行时路径 - 无法解析出实际值。 -- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下， - 必需的组合是 `botTokenStatus` + `appTokenStatus`。 +- `configured_unavailable` 表示账户是通过 SecretRef 或其他非内联密钥来源配置的，但当前命令/运行时路径无法解析出实际值。 +- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，所需的字段对是 `botTokenStatus` + `appTokenStatus`。 -对于 actions/目录读取，如果已配置 user token，则可以优先使用它。对于写入，仍然优先使用 bot token；只有当 `userTokenReadOnly: false` 且 bot token 不可用时，才允许使用 user-token 写入。 +对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍然优先使用 bot 令牌；只有在 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。 -## Actions 和门控 +## 操作和门控 -Slack actions 由 `channels.slack.actions.*` 控制。 +Slack 操作由 `channels.slack.actions.*` 控制。 -当前 Slack 工具中可用的 action 分组： +当前 Slack 工具中可用的操作组： -| 分组 | 默认值 | +| 组 | 默认值 | | ---------- | ------- | -| messages | 已启用 | -| reactions | 已启用 | -| pins | 已启用 | -| memberInfo | 已启用 | -| emojiList | 已启用 | +| messages | 启用 | +| reactions | 吂用 | +| pins | 启用 | +| memberInfo | 启用 | +| emojiList | 启用 | -当前 Slack 消息 action 包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。 +当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。 ## 访问控制和路由 @@ -467,10 +462,10 @@ Slack actions 由 `channels.slack.actions.*` 控制。 多账户优先级： - `channels.slack.accounts.default.allowFrom` 仅适用于 `default` 账户。 - - 当具名账户自己的 `allowFrom` 未设置时，会继承 `channels.slack.allowFrom`。 - - 具名账户不会继承 `channels.slack.accounts.default.allowFrom`。 + - 已命名账户在自身 `allowFrom` 未设置时，会继承 `channels.slack.allowFrom`。 + - 已命名账户不会继承 `channels.slack.accounts.default.allowFrom`。 - 在私信中进行配对时，使用 `openclaw pairing approve slack `。 + 私信中的配对使用 `openclaw pairing approve slack `。 @@ -481,15 +476,15 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - `allowlist` - `disabled` - 渠道 allowlist 位于 `channels.slack.channels` 下，并应使用稳定的渠道 ID。 + 渠道 allowlist 位于 `channels.slack.channels` 下，并且应使用稳定的渠道 ID。 - 运行时说明：如果完全缺少 `channels.slack`（仅环境变量设置），运行时会回退为 `groupPolicy="allowlist"` 并记录一条警告（即使已设置 `channels.defaults.groupPolicy` 也是如此）。 + 运行时说明：如果完全缺少 `channels.slack`（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录一条警告（即使设置了 `channels.defaults.groupPolicy` 也是如此）。 名称/ID 解析： - - 当令牌访问允许时，渠道 allowlist 条目和私信 allowlist 条目会在启动时解析 + - 在令牌访问允许的情况下，渠道 allowlist 条目和私信 allowlist 条目会在启动时解析 - 无法解析的渠道名称条目会按配置保留，但默认不会用于路由 - - 入站授权和渠道路由默认优先使用 ID；只有设置 `channels.slack.dangerouslyAllowNameMatching: true` 时，才会直接进行用户名/slug 匹配 + - 入站授权和渠道路由默认优先基于 ID；直接匹配用户名/slug 需要 `channels.slack.dangerouslyAllowNameMatching: true` @@ -499,10 +494,10 @@ Slack actions 由 `channels.slack.actions.*` 控制。 提及来源： - 显式应用提及（`<@botId>`） - - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 隐式 bot 线程回复行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） + - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） + - 隐式机器人线程回复行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） - 每渠道控制（`channels.slack.channels.`；名称仅通过启动时解析或 `dangerouslyAllowNameMatching` 支持）： + 每个渠道的控制项（`channels.slack.channels.`；名称仅通过启动时解析或 `dangerouslyAllowNameMatching` 支持）： - `requireMention` - `users`（allowlist） @@ -511,35 +506,35 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - `systemPrompt` - `tools`, `toolsBySender` - `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符 - （旧版无前缀键仍仅映射为 `id:`） + （旧版无前缀键仍然只会映射到 `id:`） ## 线程、会话和回复标签 -- 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。 +- 私信路由为 `direct`；渠道为 `channel`；MPIM 为 `group`。 - 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。 - 渠道会话：`agent::slack:channel:`。 - 在线程回复适用时，可以创建带线程会话后缀的回复（`:thread:`）。 -- `channels.slack.thread.historyScope` 默认是 `thread`；`thread.inheritParent` 默认是 `false`。 -- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时抓取多少条现有线程消息（默认 `20`；设为 `0` 可禁用）。 -- `channels.slack.thread.requireExplicitMention`（默认 `false`）：设为 `true` 时，会抑制隐式线程提及，因此 bot 即使已经参与线程，也只会响应线程内显式的 `@bot` 提及。如果不这样设置，在 bot 已参与的线程中进行回复会绕过 `requireMention` 门控。 +- `channels.slack.thread.historyScope` 默认为 `thread`；`thread.inheritParent` 默认为 `false`。 +- `channels.slack.thread.initialHistoryLimit` 控制新线程会话开始时会抓取多少现有线程消息（默认 `20`；设为 `0` 可禁用）。 +- `channels.slack.thread.requireExplicitMention`（默认 `false`）：为 `true` 时，会抑制隐式线程提及，因此机器人只会响应线程内显式的 `@bot` 提及，即使机器人之前已经参与了该线程。若不启用此项，在机器人已参与线程时，该线程中的回复会绕过 `requireMention` 门控。 回复线程控制： - `channels.slack.replyToMode`：`off|first|all|batched`（默认 `off`） - `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 分别设置 -- 旧版 direct 聊天回退：`channels.slack.dm.replyToMode` +- 旧版私信回退：`channels.slack.dm.replyToMode` 支持手动回复标签： - `[[reply_to_current]]` - `[[reply_to:]]` -注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程功能，包括显式 `[[reply_to_*]]` 标签。这一点与 Telegram 不同，在 Telegram 中，即使在 `"off"` 模式下也仍会遵循显式标签 —— Slack 线程会把消息隐藏在线程里，而 Telegram 回复仍以内联形式可见。 +注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程功能，包括显式 `[[reply_to_*]]` 标签。这与 Telegram 不同，在 Telegram 中，即使在 `"off"` 模式下也仍然会遵循显式标签——Slack 线程会把消息隐藏在渠道之外，而 Telegram 回复则仍以内联方式可见。 -## 确认 reaction +## 确认反应 `ackReaction` 会在 OpenClaw 处理入站消息期间发送一个确认 emoji。 @@ -548,12 +543,12 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 “👀”） +- 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 `"👀"`） 说明： -- Slack 期望使用 shortcode（例如 `"eyes"`）。 -- 使用 `""` 可为某个 Slack 账户或全局禁用该 reaction。 +- Slack 需要 shortcode（例如 `"eyes"`）。 +- 使用 `""` 可为 Slack 账户或全局禁用该反应。 ## 文本流式传输 @@ -561,20 +556,20 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - `off`：禁用实时预览流式传输。 - `partial`（默认）：用最新的部分输出替换预览文本。 -- `block`：追加分块流式传输的预览更新。 -- `progress`：在生成时显示进度状态文本，然后发送最终文本。 -- `streaming.preview.toolProgress`：当草稿预览启用时，将工具/进度更新路由到同一个被编辑的预览消息中（默认：`true`）。设为 `false` 可保留单独的工具/进度消息。 +- `block`：追加分块预览更新。 +- `progress`：生成期间显示进度状态文本，然后发送最终文本。 +- `streaming.preview.toolProgress`：当草稿预览处于活动状态时，将工具/进度更新路由到同一条被编辑的预览消息中（默认：`true`）。设为 `false` 可保留单独的工具/进度消息。 -`channels.slack.streaming.nativeTransport` 控制当 `channels.slack.streaming.mode` 为 `partial` 时的 Slack 原生文本流式传输（默认：`true`）。 +当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。 -- 必须有一个回复线程可用，Slack 原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍然遵循 `replyToMode`。 +- 必须有可用的回复线程，原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍然遵循 `replyToMode`。 - 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。 -- 顶层 Slack 私信默认保持非线程状态，因此不会显示线程样式预览；如果你希望在这些场景中显示可见进度，请使用线程回复或 `typingReaction`。 -- 媒体和非文本载荷会回退为普通投递。 -- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/块最终消息只有在能够原地编辑预览时才会刷新。 -- 如果流式传输在回复过程中失败，OpenClaw 会对剩余载荷回退为普通投递。 +- 顶层 Slack 私信默认保持在线程之外，因此不会显示线程样式预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。 +- 媒体和非文本负载会回退为普通投递。 +- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/块最终消息仅会在能够原地编辑预览时才刷新。 +- 如果流式传输在回复中途失败，OpenClaw 会对剩余负载回退为普通投递。 -使用草稿预览而不是 Slack 原生文本流式传输： +使用草稿预览代替 Slack 原生文本流式传输： ```json5 { @@ -591,13 +586,13 @@ Slack actions 由 `channels.slack.actions.*` 控制。 旧版键： -- `channels.slack.streamMode`（`replace | status_final | append`）会自动迁移到 `channels.slack.streaming.mode`。 -- 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。 -- 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。 +- `channels.slack.streamMode`（`replace | status_final | append`）会自动迁移为 `channels.slack.streaming.mode`。 +- 布尔值 `channels.slack.streaming` 会自动迁移为 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。 +- 旧版 `channels.slack.nativeStreaming` 会自动迁移为 `channels.slack.streaming.nativeTransport`。 -## 输入中 reaction 回退 +## 输入中反应回退 -`typingReaction` 会在 OpenClaw 处理回复期间，为入站 Slack 消息添加一个临时 reaction，并在运行结束后将其移除。这在非线程回复场景中特别有用，因为线程回复会使用默认的“正在输入...”状态指示器。 +`typingReaction` 会在 OpenClaw 处理回复期间，给入站 Slack 消息添加一个临时反应，并在运行结束时将其移除。这在非线程回复场景中特别有用，因为线程回复会使用默认的“正在输入...”状态指示器。 解析顺序： @@ -606,40 +601,40 @@ Slack actions 由 `channels.slack.actions.*` 控制。 说明： -- Slack 期望使用 shortcode（例如 `"hourglass_flowing_sand"`）。 -- 该 reaction 采用尽力而为策略，回复完成或失败路径结束后会自动尝试清理。 +- Slack 需要 shortcode（例如 `"hourglass_flowing_sand"`）。 +- 该反应是尽力而为的，回复完成或失败路径结束后会自动尝试清理。 ## 媒体、分块和投递 - Slack 文件附件通过 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在抓取成功且大小限制允许时写入媒体存储。 + Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在抓取成功且大小限制允许时写入媒体存储。 - 运行时入站大小上限默认是 `20MB`，除非通过 `channels.slack.mediaMaxMb` 覆盖。 + 运行时入站大小上限默认是 `20MB`，除非被 `channels.slack.mediaMaxMb` 覆盖。 - 文本分块使用 `channels.slack.textChunkLimit`（默认 4000） - - `channels.slack.chunkMode="newline"` 启用优先按段落拆分 + - `channels.slack.chunkMode="newline"` 启用按段落优先拆分 - 文件发送使用 Slack 上传 API，并可包含线程回复（`thread_ts`） - - 配置了 `channels.slack.mediaMaxMb` 时，出站媒体上限遵循该值；否则渠道发送会使用媒体管线中的 MIME 类型默认值 + - 配置了 `channels.slack.mediaMaxMb` 时，出站媒体上限遵循该值；否则渠道发送使用媒体管线中的 MIME 类型默认值 - 推荐使用显式目标： + 推荐的显式目标： - 私信使用 `user:` - 渠道使用 `channel:` - 发送到用户目标时，Slack 私信会通过 Slack conversation API 打开。 + 发送到用户目标时，Slack 私信会通过 Slack 会话 API 打开。 ## 命令和斜杠行为 -斜杠命令在 Slack 中可以显示为单个已配置命令，或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： +斜杠命令在 Slack 中会显示为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： - `enabled: false` - `name: "openclaw"` @@ -650,26 +645,26 @@ Slack actions 由 `channels.slack.actions.*` 控制。 /openclaw /help ``` -原生命令需要在你的 Slack 应用中进行[额外清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 或全局配置中的 `commands.native: true` 来启用。 +原生命令要求你在 Slack 应用中设置[其他清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 或全局配置中的 `commands.native: true` 启用。 -- 对于 Slack，原生命令自动模式默认**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。 +- Slack 的原生命令自动模式默认为**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。 ```txt /help ``` -原生参数菜单使用一种自适应渲染策略，会在分发所选选项值前先显示确认模态框： +原生参数菜单使用自适应渲染策略，在分发所选选项值前会先显示确认模态框： - 最多 5 个选项：按钮块 - 6-100 个选项：静态选择菜单 -- 超过 100 个选项：当交互选项处理器可用时，使用带异步选项过滤的外部选择 -- 超出 Slack 限制：经过编码的选项值会回退为按钮 +- 超过 100 个选项：当可用 interactivity 选项处理器时，使用带异步选项过滤的外部选择 +- 超出 Slack 限制：编码后的选项值会回退为按钮 ```txt /think ``` -斜杠会话使用像 `agent::slack:slash:` 这样的隔离键，但仍会通过 `CommandTargetSessionKey` 将命令执行路由到目标对话会话。 +斜杠会话使用类似 `agent::slack:slash:` 的隔离键，并且仍会使用 `CommandTargetSessionKey` 将命令执行路由到目标会话。 ## 交互式回复 @@ -689,7 +684,7 @@ Slack 可以渲染由智能体编写的交互式回复控件，但该功能默 } ``` -或仅为一个 Slack 账户启用： +或者仅为某一个 Slack 账户启用： ```json5 { @@ -707,43 +702,42 @@ Slack 可以渲染由智能体编写的交互式回复控件，但该功能默 } ``` -启用后，智能体可以输出仅适用于 Slack 的回复指令： +启用后，智能体可以发出仅限 Slack 的回复指令： - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -这些指令会编译为 Slack Block Kit，并将点击或选择通过现有的 Slack 交互事件路径路由回来。 +这些指令会编译为 Slack Block Kit，并将点击或选择通过现有 Slack 交互事件路径路由回来。 说明： -- 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令翻译为各自的按钮系统。 -- 交互回调值是 OpenClaw 生成的不透明令牌，不是智能体原始编写的值。 -- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的 blocks 载荷。 +- 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令转换为它们自己的按钮系统。 +- 交互回调值是 OpenClaw 生成的不透明令牌，而不是智能体原始编写的值。 +- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的 blocks 负载。 -## Slack 中的 Exec 审批 +## Slack 中的 exec 审批 Slack 可以充当原生审批客户端，使用交互式按钮和交互，而不是回退到 Web UI 或终端。 - Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 -- 当请求已落在 Slack 中且审批 id 类型为 `plugin:` 时，插件审批仍可通过相同的 Slack 原生按钮界面进行处理。 -- 审批人授权仍会强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。 +- 当请求已经落在 Slack 中且审批 ID 类型为 `plugin:` 时，插件审批仍然可以通过相同的 Slack 原生按钮界面处理。 +- 审批人授权仍然会被强制执行：只有被识别为审批人的用户，才能通过 Slack 批准或拒绝请求。 -这使用与其他渠道相同的共享审批按钮界面。当你在 Slack 应用设置中启用 `interactivity` 时，审批提示会直接在会话中渲染为 Block Kit 按钮。 -当这些按钮存在时，它们就是主要的审批 UX；只有在工具结果表明聊天审批不可用或手动审批是唯一途径时，OpenClaw +这使用与其他渠道相同的共享审批按钮界面。当你在 Slack 应用设置中启用 `interactivity` 后，审批提示会直接在会话中渲染为 Block Kit 按钮。 +当这些按钮存在时，它们就是主要的审批 UX；只有当工具结果表明聊天审批不可用，或手动审批是唯一可行路径时，OpenClaw 才应包含手动 `/approve` 命令。 配置路径： - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers`（可选；在可能的情况下回退到 `commands.ownerAllowFrom`） +- `channels.slack.execApprovals.approvers`（可选；在可能的情况下会回退到 `commands.ownerAllowFrom`） - `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter` -当 `enabled` 未设置或为 `"auto"`，并且至少解析出一个 -审批人时，Slack 会自动启用原生 exec 审批。设置 `enabled: false` 可显式禁用 Slack 作为原生审批客户端。 -设置 `enabled: true` 可在审批人可解析时强制启用原生审批。 +当 `enabled` 未设置或为 `"auto"`，并且至少解析出一位审批人时，Slack 会自动启用原生 exec 审批。将 `enabled: false` 设为显式禁用 Slack 作为原生审批客户端。 +将 `enabled: true` 设为在审批人可解析时强制启用原生审批。 -没有显式 Slack exec 审批配置时的默认行为： +在没有显式 Slack exec 审批配置时的默认行为： ```json5 { @@ -753,8 +747,7 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 } ``` -只有在你想覆盖审批人、添加过滤器，或 -选择启用源聊天投递时，才需要显式 Slack 原生配置： +只有当你想覆盖审批人、添加过滤器，或选择启用源聊天投递时，才需要显式的 Slack 原生配置： ```json5 { @@ -770,23 +763,21 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 } ``` -共享 `approvals.exec` 转发是独立的。只有当 exec 审批提示还必须 -路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也 -是独立的；当这些请求已经落在 Slack 中时，Slack 原生按钮仍可解析插件审批。 +共享 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须路由到其他聊天或明确的带外目标时才使用它。共享 `approvals.plugin` 转发也是独立的；当这些请求已经落在 Slack 中时，Slack 原生按钮仍然可以处理插件审批。 -同一聊天中的 `/approve` 也适用于已经支持命令的 Slack 渠道和私信。完整的审批转发模型请参见 [Exec approvals](/zh-CN/tools/exec-approvals)。 +同一聊天中的 `/approve` 也可在已支持命令的 Slack 渠道和私信中使用。完整的审批转发模型请参阅 [Exec approvals](/zh-CN/tools/exec-approvals)。 ## 事件和运行行为 - 消息编辑/删除/线程广播会映射为系统事件。 -- reaction 添加/移除事件会映射为系统事件。 -- 成员加入/离开、渠道创建/重命名以及 pin 添加/移除事件会映射为系统事件。 +- 反应添加/移除事件会映射为系统事件。 +- 成员加入/离开、渠道创建/重命名，以及固定消息添加/移除事件会映射为系统事件。 - 当启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。 - 渠道 topic/purpose 元数据会被视为不可信上下文，并可注入到路由上下文中。 -- 线程发起者和初始线程历史上下文播种会在适用时根据已配置的发送者 allowlist 进行过滤。 -- Block action 和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并带有丰富的载荷字段： - - block action：所选值、标签、选择器值以及 `workflow_*` 元数据 - - 模态 `view_submission` 和 `view_closed` 事件，包含路由后的渠道元数据和表单输入 +- 在线程起始消息和初始线程历史上下文播种时，会在适用情况下按已配置的发送者 allowlist 进行过滤。 +- Block 操作和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并带有丰富的负载字段： + - block 操作：选中值、标签、选择器值以及 `workflow_*` 元数据 + - 模态 `view_submission` 和 `view_closed` 事件，包含已路由的渠道元数据和表单输入 ## 配置参考 @@ -794,9 +785,9 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 -- mode/auth：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*` +- 模式/认证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*` - 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels` -- 兼容性开关：`dangerouslyAllowNameMatching`（紧急开关；除非必要请保持关闭） +- 兼容性开关：`dangerouslyAllowNameMatching`（紧急开关；除非确有需要，否则保持关闭） - 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention` - 线程/历史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` - 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress` @@ -808,12 +799,12 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 - 按顺序检查： + 按以下顺序检查： - `groupPolicy` - 渠道 allowlist（`channels.slack.channels`） - `requireMention` - - 每渠道 `users` allowlist + - 每个渠道的 `users` allowlist 有用的命令： @@ -839,16 +830,16 @@ openclaw pairing list slack - 验证 bot 和 app token，以及 Slack 应用设置中的 Socket Mode 是否已启用。 + 验证 bot 和 app 令牌，以及 Slack 应用设置中的 Socket Mode 是否已启用。 如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或 - `appTokenStatus: "configured_unavailable"`，说明 Slack 账户 - 已配置，但当前运行时无法解析由 SecretRef 支持的 + `appTokenStatus: "configured_unavailable"`，则表示 Slack 账户已 + 配置，但当前运行时无法解析由 SecretRef 支持的 值。 - + 验证： - signing secret @@ -857,13 +848,13 @@ openclaw pairing list slack - 每个 HTTP 账户使用唯一的 `webhookPath` 如果账户快照中出现 `signingSecretStatus: "configured_unavailable"`， - 说明该 HTTP 账户已配置，但当前运行时无法 + 则表示 HTTP 账户已配置，但当前运行时无法 解析由 SecretRef 支持的 signing secret。 - 验证你本来打算使用的是： + 验证你期望的是： - 原生命令模式（`channels.slack.commands.native: true`），并且在 Slack 中注册了匹配的斜杠命令 - 或单一斜杠命令模式（`channels.slack.slashCommand.enabled: true`） @@ -886,7 +877,7 @@ openclaw pairing list slack 将入站消息路由到智能体。 - 威胁模型和加固。 + 威胁模型与加固。 配置布局和优先级。 diff --git a/docs/zh-CN/concepts/models.md b/docs/zh-CN/concepts/models.md index d0f4fa3e0..67e95d826 100644 --- a/docs/zh-CN/concepts/models.md +++ b/docs/zh-CN/concepts/models.md @@ -1,45 +1,45 @@ --- read_when: - - 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks） - - 更改模型回退行为或选择体验 + - 添加或修改模型 CLI（`models list`/`set`/`scan`/`aliases`/`fallbacks`） + - 更改模型回退行为或选择 UX - 更新模型扫描探测（工具/图像） -summary: 模型 CLI：list、set、aliases、fallbacks、scan、status +summary: 模型 CLI：列表、设置、别名、回退、扫描、状态 title: 模型 CLI x-i18n: - generated_at: "2026-04-24T03:39:12Z" + generated_at: "2026-04-24T17:24:37Z" model: gpt-5.4 provider: openai - source_hash: 12f784984c87b33e645ec296f7f93ec3acc2a91efa3b63d3a912a6b09b90e048 + source_hash: 5c036097a5093f0ce304fd08b7ae22ccf5102eb6f511a9a2018a8d4712e43648 source_path: concepts/models.md workflow: 15 --- -有关凭证配置轮换、冷却时间以及它们如何与回退配合，请参见 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 -快速了解提供商概览和示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。 +有关凭证配置轮换、冷却时间，以及这些机制如何与回退交互，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 +快速了解提供商概览与示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。 -## 模型选择如何工作 +## 模型选择的工作方式 OpenClaw 按以下顺序选择模型： -1. **主**模型（`agents.defaults.model.primary` 或 `agents.defaults.model`）。 +1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。 2. `agents.defaults.model.fallbacks` 中的**回退模型**（按顺序）。 -3. **提供商凭证故障转移**会先在同一个提供商内部发生，然后才会切换到下一个模型。 +3. **提供商凭证故障切换**会先在单个提供商内部进行，然后才会切换到下一个模型。 相关内容： -- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（也包含别名）。 -- `agents.defaults.imageModel` **仅在**主模型无法接收图像时使用。 -- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，工具会依次回退到 `agents.defaults.imageModel`，然后回退到已解析的会话/默认模型。 -- `agents.defaults.imageGenerationModel` 用于共享图像生成能力。如果省略，`image_generate` 仍可推断出一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请同时配置该提供商的凭证/API key。 -- `agents.defaults.musicGenerationModel` 用于共享音乐生成能力。如果省略，`music_generate` 仍可推断出一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也请同时配置该提供商的凭证/API key。 -- `agents.defaults.videoGenerationModel` 用于共享视频生成能力。如果省略，`video_generate` 仍可推断出一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请同时配置该提供商的凭证/API key。 -- 每个智能体的默认值可通过 `agents.list[].model` 和绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。 +- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（还包括别名）。 +- `agents.defaults.imageModel` **仅在**主模型无法接受图像时使用。 +- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会依次回退到 `agents.defaults.imageModel`，然后是解析后的会话/默认模型。 +- `agents.defaults.imageGenerationModel` 用于共享的图像生成能力。如果省略，`image_generate` 仍然可以推断出一个带凭证的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- `agents.defaults.musicGenerationModel` 用于共享的音乐生成能力。如果省略，`music_generate` 仍然可以推断出一个带凭证的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- `agents.defaults.videoGenerationModel` 用于共享的视频生成能力。如果省略，`video_generate` 仍然可以推断出一个带凭证的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- 每个智能体的默认设置可以通过 `agents.list[].model` 加上绑定来覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。 ## 快速模型策略 - 将你的主模型设置为你可用的最新一代中能力最强的模型。 -- 对于成本/延迟敏感的任务和风险较低的聊天，使用回退模型。 -- 对于启用了工具的智能体或不可信输入，避免使用较旧/较弱的模型层级。 +- 对于对成本/延迟敏感的任务和风险较低的聊天，可使用回退模型。 +- 对于启用了工具的智能体或不受信任的输入，避免使用较旧/较弱档位的模型。 ## 新手引导（推荐） @@ -49,10 +49,10 @@ OpenClaw 按以下顺序选择模型： openclaw onboard ``` -它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code (Codex) -subscription**（OAuth）和 **Anthropic**（API key 或 Claude CLI）。 +它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code（Codex）订阅** +（OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。 -## 配置键（概览） +## 配置键名（概览） - `agents.defaults.model.primary` 和 `agents.defaults.model.fallbacks` - `agents.defaults.imageModel.primary` 和 `agents.defaults.imageModel.fallbacks` @@ -62,7 +62,7 @@ subscription**（OAuth）和 **Anthropic**（API key 或 Claude CLI）。 - `agents.defaults.models`（允许列表 + 别名 + 提供商参数） - `models.providers`（写入 `models.json` 的自定义提供商） -模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会被规范化为 +模型引用会统一规范为小写。像 `z.ai/*` 这样的提供商别名会规范为 `zai/*`。 提供商配置示例（包括 OpenCode）位于 @@ -70,31 +70,36 @@ subscription**（OAuth）和 **Anthropic**（API key 或 Claude CLI）。 ### 安全地编辑允许列表 -手动更新 `agents.defaults.models` 时，请使用追加式写入： +手动更新 `agents.defaults.models` 时，使用追加式写入： ```bash openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge ``` -`openclaw config set` 会保护模型/提供商映射，防止被意外覆盖。对 `agents.defaults.models`、`models.providers` 或 -`models.providers..models` 进行普通对象赋值时，如果会移除现有条目，则会被拒绝。追加式变更请使用 `--merge`；仅当你希望提供的值成为完整目标值时，才使用 `--replace`。 +`openclaw config set` 会保护模型/提供商映射，防止被意外覆盖。对 +`agents.defaults.models`、`models.providers` 或 +`models.providers..models` 进行普通对象赋值时，如果会移除现有条目， +则会被拒绝。追加式更改请使用 `--merge`；只有在提供的值应成为完整目标值时， +才使用 `--replace`。 -交互式提供商设置和 `openclaw configure --section model` 也会将按提供商划分的选择合并到现有允许列表中，因此添加 Codex、 +交互式提供商设置和 `openclaw configure --section model` 也会将按提供商范围选择的内容合并到现有允许列表中，因此添加 Codex、 Ollama 或其他提供商时，不会丢弃无关的模型条目。 ## “Model is not allowed”（以及为什么回复会停止） -如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择了不在允许列表中的模型时， +如果设置了 `agents.defaults.models`，它就会成为 `/model` 以及 +会话覆盖的**允许列表**。当用户选择的模型不在该允许列表中时， OpenClaw 会返回： -```text +``` Model "provider/model" is not allowed. Use /model to list available models. ``` -这会发生在正常回复生成**之前**，因此这条消息可能会让人感觉像是“没有回应”。解决方法是： +这会发生在正常回复生成**之前**，因此这条消息会让人感觉它 +“没有响应”。修复方法是： - 将该模型添加到 `agents.defaults.models`，或 -- 清空允许列表（移除 `agents.defaults.models`），或 +- 清除允许列表（移除 `agents.defaults.models`），或 - 从 `/model list` 中选择一个模型。 允许列表示例配置： @@ -113,9 +118,9 @@ Model "provider/model" is not allowed. Use /model to list available models. ## 在聊天中切换模型（`/model`） -你可以为当前会话切换模型，而无需重启： +你可以在不重启的情况下为当前会话切换模型： -```text +``` /model /model list /model 3 @@ -126,35 +131,25 @@ Model "provider/model" is not allowed. Use /model to list available models. 说明： - `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。 -- 在 Discord 上，`/model` 和 `/models` 会打开交互式选择器，其中包含提供商和模型下拉菜单，以及一个 Submit 步骤。 -- `/models add` 默认可用，可通过 `commands.modelsWrite=false` 禁用。 -- 启用后，`/models add ` 是最快路径；仅输入 `/models add` 时，在支持的情况下会启动一个按提供商优先的引导流程。 -- 执行 `/models add` 后，新模型无需重启 Gateway 网关，就会在 `/models` 和 `/model` 中可用。 -- `/model <#>` 会从该选择器中选中模型。 +- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个提交步骤。 +- `/models add` 已弃用，现在会返回弃用提示，而不是在聊天中注册模型。 +- `/model <#>` 会从该选择器中进行选择。 - `/model` 会立即持久化新的会话选择。 -- 如果智能体当前空闲，下一次运行会立刻使用新模型。 -- 如果已有运行中的任务，OpenClaw 会将实时切换标记为待处理，并仅在合适的重试点重启到新模型。 -- 如果工具活动或回复输出已经开始，这个待处理切换可能会一直排队到之后的某个重试机会，或到下一轮用户输入时才生效。 -- `/model status` 是详细视图（凭证候选，以及在已配置时的提供商端点 `baseUrl` + `api` 模式）。 -- 模型引用会通过**第一个** `/` 进行拆分。输入 `/model ` 时，请使用 `provider/model`。 -- 如果模型 id 本身包含 `/`（如 OpenRouter 风格），你必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。 -- 如果你省略了提供商，OpenClaw 会按以下顺序解析输入： +- 如果智能体处于空闲状态，下次运行会立即使用新模型。 +- 如果某次运行已在进行中，OpenClaw 会将实时切换标记为待处理，并且只会在一个干净的重试点重启到新模型。 +- 如果工具活动或回复输出已经开始，待处理的切换可能会保持排队，直到后续出现重试机会，或等到下一个用户轮次。 +- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` + `api` 模式）。 +- 模型引用通过按**第一个** `/` 拆分来解析。输入 `/model ` 时请使用 `provider/model`。 +- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。 +- 如果你省略提供商，OpenClaw 会按以下顺序解析输入： 1. 别名匹配 - 2. 与该无前缀模型 id 精确匹配的唯一已配置提供商 - 3. 已弃用的回退方式：使用已配置的默认提供商 - 如果该提供商已不再提供已配置的默认模型，OpenClaw - 会改为回退到第一个已配置的提供商/模型，以避免 - 暴露一个已过时、已移除提供商的默认值。 + 2. 对该精确无前缀模型 ID 的唯一已配置提供商匹配 + 3. 已弃用的回退：回退到已配置的默认提供商 + 如果该提供商不再暴露已配置的默认模型，OpenClaw + 则会回退到第一个已配置的提供商/模型，以避免 + 暴露一个陈旧的、已移除提供商的默认项。 -完整命令行为/配置：[/tools/slash-commands](/zh-CN/tools/slash-commands)。 - -示例： - -```text -/models add -/models add ollama glm-5.1:cloud -/models add lmstudio qwen/qwen3.5-9b -``` +完整命令行为/配置： [Slash commands](/zh-CN/tools/slash-commands)。 ## CLI 命令 @@ -179,33 +174,39 @@ openclaw models image-fallbacks remove openclaw models image-fallbacks clear ``` -`openclaw models`（不带子命令）是 `models status` 的快捷方式。 +`openclaw models`（无子命令）是 `models status` 的快捷方式。 ### `models list` -默认显示已配置的模型。常用标志： +默认显示已配置模型。实用标志： - `--all`：完整目录 - `--local`：仅本地提供商 -- `--provider `：按提供商 id 过滤，例如 `moonshot`；不接受交互式选择器中的显示标签 +- `--provider `：按提供商 ID 过滤，例如 `moonshot`；不接受交互式选择器中的显示标签 - `--plain`：每行一个模型 - `--json`：机器可读输出 -`--all` 会在配置凭证之前包含内置的、由提供商拥有的静态目录条目，因此仅用于发现的视图可能会显示那些在你添加匹配提供商凭证之前不可用的模型。 +`--all` 会在配置凭证之前，先包含内置的、由提供商拥有的静态目录条目， +因此仅做发现用途的视图也可以显示那些在你添加匹配提供商凭证之前不可用的模型。 ### `models status` -显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中发现的配置文件的 OAuth 过期状态（默认在 24 小时内发出警告）。`--plain` 只打印已解析的主模型。 -OAuth 状态始终会显示（也包含在 `--json` 输出中）。如果某个已配置提供商没有凭证，`models status` 会打印一个 **Missing auth** 部分。 +显示解析后的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 过期状态（默认会在 24 小时内到期时发出警告）。`--plain` 仅打印解析后的主模型。 +OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置的 +提供商没有凭证，`models status` 会打印一个 **Missing auth** 部分。 JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers` -（每个提供商的生效凭证，包括来自环境变量的凭证）。`auth.oauth` -仅表示凭证存储中的配置文件健康状态；仅依赖环境变量的提供商不会出现在其中。 -自动化使用时请用 `--check`（缺失/过期时退出码为 `1`，即将过期时为 `2`）。 -实时凭证检查请用 `--probe`；探测行可能来自凭证配置文件、环境变量凭证，或 `models.json`。 +（每个提供商的生效凭证，包括由环境变量提供的凭证）。`auth.oauth` +仅表示凭证存储中配置文件的健康状态；仅依赖环境变量的提供商不会出现在其中。 +自动化场景请使用 `--check`（缺失/已过期时退出码为 `1`，即将过期时为 `2`）。 +实时凭证检查请使用 `--probe`；探测结果行可能来自凭证配置文件、环境变量 +凭证，或 `models.json`。 如果显式 `auth.order.` 省略了某个已存储配置文件，探测会报告 -`excluded_by_auth_order`，而不是尝试使用它。如果有凭证但无法为该提供商解析出可探测的模型，则探测会报告 `status: no_model`。 +`excluded_by_auth_order`，而不是尝试它。如果凭证存在，但该提供商无法解析出可探测的 +模型，探测会报告 `status: no_model`。 -凭证选择取决于提供商/账号。对于始终在线的 Gateway 网关主机，API key 通常是最可预测的；也支持复用 Claude CLI 以及现有 Anthropic OAuth/token 配置文件。 +凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API +密钥通常是最可预测的；也支持复用 Claude CLI 以及现有的 Anthropic +OAuth/令牌配置文件。 示例（Claude CLI）： @@ -216,22 +217,23 @@ openclaw models status ## 扫描（OpenRouter 免费模型） -`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并且可以选择探测模型对工具和图像的支持情况。 +`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并且可以 +选择性地探测模型是否支持工具和图像。 关键标志： - `--no-probe`：跳过实时探测（仅元数据） - `--min-params `：最小参数规模（十亿） -- `--max-age-days `：跳过较旧的模型 +- `--max-age-days `：跳过较旧模型 - `--provider `：提供商前缀过滤 - `--max-candidates `：回退列表大小 -- `--set-default`：将 `agents.defaults.model.primary` 设置为首个选中项 -- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为首个图像选中项 +- `--set-default`：将 `agents.defaults.model.primary` 设为第一个选择结果 +- `--set-image`：将 `agents.defaults.imageModel.primary` 设为第一个图像选择结果 -探测需要 OpenRouter API key（来自凭证配置文件或 -`OPENROUTER_API_KEY`）。没有 key 时，请使用 `--no-probe` 仅列出候选项。 +探测需要 OpenRouter API 密钥（来自凭证配置文件或 +`OPENROUTER_API_KEY`）。如果没有密钥，请使用 `--no-probe` 仅列出候选项。 -扫描结果排序依据： +扫描结果按以下顺序排序： 1. 图像支持 2. 工具延迟 @@ -240,34 +242,36 @@ openclaw models status 输入 -- OpenRouter `/models` 列表（筛选 `:free`） -- 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API key（参见 [/environment](/zh-CN/help/environment)） -- 可选过滤项：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` +- OpenRouter `/models` 列表（过滤 `:free`） +- 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/zh-CN/help/environment)） +- 可选过滤器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` - 探测控制：`--timeout`、`--concurrency` -在 TTY 中运行时，你可以交互式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。 +在 TTY 中运行时，你可以交互式选择回退模型。在非交互模式下， +传入 `--yes` 以接受默认值。 ## 模型注册表（`models.json`） -`models.providers` 中的自定义提供商会被写入智能体目录下的 `models.json`（默认路径为 `~/.openclaw/agents//agent/models.json`）。除非 `models.mode` 设置为 `replace`，否则该文件默认会以合并方式处理。 +`models.providers` 中的自定义提供商会被写入智能体目录下的 `models.json` +（默认路径为 `~/.openclaw/agents//agent/models.json`）。默认情况下会合并此文件，除非 `models.mode` 被设置为 `replace`。 -匹配提供商 id 时的合并模式优先级： +匹配提供商 ID 时，合并模式的优先级如下： - 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。 -- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中**不是** SecretRef 托管时优先。 -- 对于由 SecretRef 托管的提供商，`apiKey` 值会根据源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不会持久化已解析出的密钥。 -- 对于由 SecretRef 托管的提供商，header 值也会根据源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 -- 智能体中的 `apiKey`/`baseUrl` 为空或缺失时，会回退到配置中的 `models.providers`。 -- 其他提供商字段会根据配置和规范化后的目录数据刷新。 +- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中不是 SecretRef 管理时才优先。 +- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记中刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 +- 由 SecretRef 管理的提供商请求头值会从源标记中刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 +- 智能体中为空或缺失的 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 +- 其他提供商字段会从配置和规范化后的目录数据中刷新。 -标记持久化以源配置为准：OpenClaw 会根据当前源配置快照（解析前）写入标记，而不是根据运行时已解析出的密钥值写入。 -这适用于 OpenClaw 重新生成 `models.json` 的所有情况，包括像 `openclaw agent` 这样的命令驱动路径。 +标记持久化以源配置为准：OpenClaw 会从当前激活的源配置快照（解析前）写入标记，而不是从运行时已解析的密钥值写入。 +只要 OpenClaw 重新生成 `models.json`，这一规则都会生效，包括像 `openclaw agent` 这样的命令驱动路径。 ## 相关内容 - [Model Providers](/zh-CN/concepts/model-providers) — 提供商路由与凭证 - [Model Failover](/zh-CN/concepts/model-failover) — 回退链 -- [图像生成](/zh-CN/tools/image-generation) — 图像模型配置 -- [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置 -- [视频生成](/zh-CN/tools/video-generation) — 视频模型配置 -- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键 +- [Image Generation](/zh-CN/tools/image-generation) — 图像模型配置 +- [Music Generation](/zh-CN/tools/music-generation) — 音乐模型配置 +- [Video Generation](/zh-CN/tools/video-generation) — 视频模型配置 +- [Configuration Reference](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键名