diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index df5931557..fd97c1800 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -4,17 +4,17 @@ read_when: summary: Discord 机器人支持状态、功能和配置 title: Discord x-i18n: - generated_at: "2026-04-22T09:51:15Z" + generated_at: "2026-04-22T17:02:15Z" model: gpt-5.4 provider: openai - source_hash: 758846d22457ff66e28736a2e4c67c930ad4cd4dd5493b32afcc1912758fd540 + source_hash: 2aa0a6d60984cf5cc41f86fdf16d1c409b94605ff36d59c265acadebb4240b45 source_path: channels/discord.md workflow: 15 --- # Discord（Bot API） -状态：已就绪，可通过官方 Discord Gateway 网关用于私信和服务器频道。 +状态：已就绪，可通过官方 Discord gateway 用于私信和服务器频道。 @@ -28,13 +28,13 @@ 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 智能体的称呼。 @@ -44,19 +44,19 @@ x-i18n: 仍然停留在 **Bot** 页面，向下滚动到 **Privileged Gateway Intents** 并启用： - **Message Content Intent**（必需） - - **Server Members Intent**（推荐；角色允许列表和名称到 ID 匹配需要它） + - **Server Members Intent**（推荐；角色 allowlist 和名称到 ID 匹配需要它） - **Presence Intent**（可选；仅在需要在线状态更新时使用） - 向上滚动回 **Bot** 页面顶部并点击 **Reset Token**。 + 向上滚动回到 **Bot** 页面，然后点击 **Reset Token**。 - 尽管名称如此，这会生成你的第一个令牌——并没有任何内容被“重置”。 + 尽管名称如此，这会生成你的第一个令牌——并没有任何东西被“重置”。 - 复制该令牌并将其保存在某处。这就是你的 **Bot Token**，你很快会用到它。 + 复制该令牌并保存到某个地方。这就是你的 **Bot Token**，你很快就会用到它。 @@ -68,7 +68,7 @@ x-i18n: - `bot` - `applications.commands` - 下方会出现一个 **Bot Permissions** 区域。至少启用： + 下方会出现 **Bot Permissions** 部分。至少启用： **General Permissions** - View Channels @@ -79,31 +79,31 @@ x-i18n: - Attach Files - Add Reactions（可选） - 这是普通文本频道所需的基础权限集。如果你计划在 Discord 线程中发帖，包括创建或继续线程的论坛或媒体频道工作流，还请启用 **Send Messages in Threads**。 - 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该可以在 Discord 服务器中看到你的机器人。 + 这是普通文本频道的基础权限集。如果你计划在 Discord 线程中发帖，包括会创建或继续线程的论坛或媒体频道工作流，也请启用 **Send Messages in Threads**。 + 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该能在 Discord 服务器中看到你的机器人。 - 回到 Discord 应用后，你需要启用开发者模式，这样你才能复制内部 ID。 + 回到 Discord 应用中，你需要启用开发者模式，这样你才能复制内部 ID。 1. 点击 **User Settings**（你头像旁边的齿轮图标）→ **Advanced** → 打开 **Developer Mode** - 2. 在侧边栏中右键点击你的**服务器图标** → **Copy Server ID** - 3. 右键点击你自己的**头像** → **Copy User ID** + 2. 在侧边栏中右键点击你的 **server icon** → **Copy Server ID** + 3. 右键点击你自己的 **avatar** → **Copy User ID** - 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存——你会在下一步将这三项都发送给 OpenClaw。 + 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存好——下一步你需要将这三者都提供给 OpenClaw。 - 为了让配对正常工作，Discord 需要允许你的机器人给你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。 + 为了让配对正常工作，Discord 需要允许你的机器人向你发送私信。右键点击你的 **server icon** → **Privacy Settings** → 打开 **Direct Messages**。 - 这会允许服务器成员（包括机器人）向你发送私信。如果你想将 Discord 私信与 OpenClaw 搭配使用，请保持启用。如果你只打算使用服务器频道，则可以在配对完成后关闭私信。 + 这样服务器成员（包括机器人）就可以向你发送私信。如果你想在 OpenClaw 中使用 Discord 私信，请保持启用。如果你只打算使用服务器频道，那么在配对完成后可以关闭私信。 - - 你的 Discord 机器人令牌是机密信息（类似密码）。在给你的智能体发消息之前，请先在运行 OpenClaw 的机器上设置它。 + + 你的 Discord 机器人令牌是一个机密信息（就像密码一样）。在向你的智能体发送消息之前，请先在运行 OpenClaw 的机器上设置它。 ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -113,7 +113,7 @@ openclaw config set channels.discord.enabled true --strict-json openclaw gateway ``` - 如果 OpenClaw 已经作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或者停止并重新启动 `openclaw gateway run` 进程。 + 如果 OpenClaw 已作为后台服务运行，请通过 OpenClaw Mac app 重启它，或者停止并重新启动 `openclaw gateway run` 进程。 @@ -121,9 +121,9 @@ openclaw gateway - 在任意现有渠道（例如 Telegram）上与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置标签页。 + 在任何现有渠道（例如 Telegram）中与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置标签页。 - > “我已经在配置中设置好了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” + > “我已经在配置中设置了我的 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” 如果你更喜欢基于文件的配置，请设置： @@ -157,11 +157,11 @@ DISCORD_BOT_TOKEN=... - 等待 Gateway 网关运行后，在 Discord 中给你的机器人发送私信。它会回复一个配对码。 + 等待 Gateway 网关运行后，在 Discord 中向你的机器人发送私信。它会回复一个配对码。 - 在你的现有渠道上将配对码发送给你的智能体： + 将配对码发送给你现有渠道中的智能体： > “批准这个 Discord 配对码：``” @@ -177,27 +177,27 @@ openclaw pairing approve discord 配对码会在 1 小时后过期。 - 现在你应该已经可以通过私信在 Discord 中与你的智能体聊天了。 + 现在你应该可以通过 Discord 私信与你的智能体聊天了。 -令牌解析按账户感知。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 -对于高级出站调用（消息工具/渠道操作），显式的每次调用 `token` 会用于该次调用。这适用于发送以及读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍来自活动运行时快照中选定的账户。 +令牌解析是账户感知的。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 +对于高级出站调用（消息工具/渠道操作），会对该次调用使用显式的每次调用 `token`。这适用于发送以及读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍然来自活动运行时快照中选定的账户。 ## 推荐：设置服务器工作区 -当私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个频道都会获得带有独立上下文的智能体会话。对于只有你和你的机器人的私人服务器，推荐这样做。 +当私信已经可用后，你可以将 Discord 服务器设置为一个完整工作区，其中每个频道都有自己的智能体会话和自己的上下文。对于只有你和你的机器人的私人服务器，这是推荐做法。 - - 这会让你的智能体能够在你服务器中的任意频道响应，而不仅仅是私信。 + + 这样你的智能体就能在服务器上的任何频道中回复，而不仅仅是私信。 - > “将我的 Discord Server ID `` 添加到服务器允许列表中” + > “把我的 Discord Server ID `` 添加到服务器 allowlist 中” @@ -222,15 +222,15 @@ openclaw pairing approve discord - - 默认情况下，你的智能体只会在被 @ 提及时在服务器频道中响应。对于私人服务器，你大概率希望它对每条消息都做出响应。 + + 默认情况下，你的智能体只会在被 @ 提及时在服务器频道中回复。对于私人服务器，你大概率希望它对每条消息都进行回复。 - > “允许我的智能体在这个服务器上无需被 @ 提及也能响应” + > “允许我的智能体在这个服务器中回复时不需要被 @ 提及” - 在你的服务器配置中设置 `requireMention: false`： + 在你的服务器配置中将 `requireMention: false` 设置为： ```json5 { @@ -252,36 +252,36 @@ openclaw pairing approve discord - 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。服务器频道不会自动加载 MEMORY.md。 + 默认情况下，长期记忆（MEMORY.md）仅在私信会话中加载。服务器频道不会自动加载 MEMORY.md。 > “当我在 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。 -- 默认情况下（`session.dmScope=main`），私聊共享智能体主会话（`agent:main:main`）。 +- 默认情况下（`session.dmScope=main`），私聊会共享智能体主会话（`agent:main:main`）。 - 服务器频道使用隔离的会话键（`agent::discord:channel:`）。 -- 群组私信默认被忽略（`channels.discord.dm.groupEnabled=false`）。 -- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍会将 `CommandTargetSessionKey` 传递到已路由的会话。 +- 默认忽略群组私信（`channels.discord.dm.groupEnabled=false`）。 +- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 指向被路由的对话会话。 ## 论坛频道 Discord 论坛和媒体频道只接受线程帖子。OpenClaw 支持两种创建方式： -- 向论坛父级（`channel:`）发送消息以自动创建线程。线程标题使用你消息中的第一行非空内容。 +- 向论坛父级（`channel:`）发送消息以自动创建线程。线程标题会使用你消息中的第一条非空行。 - 使用 `openclaw message thread create` 直接创建线程。对于论坛频道，不要传递 `--message-id`。 示例：发送到论坛父级以创建线程 @@ -298,35 +298,35 @@ openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -论坛父级不接受 Discord 组件。如果你需要组件，请发送到线程本身（`channel:`）。 +论坛父级不接受 Discord components。如果你需要 components，请发送到线程本身（`channel:`）。 ## 交互式组件 -OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `components` 负载的消息工具。交互结果会像普通入站消息一样路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 +OpenClaw 支持在智能体消息中使用 Discord components v2 容器。使用带有 `components` 负载的消息工具。交互结果会像普通入站消息一样路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 支持的块： - `text`、`section`、`separator`、`actions`、`media-gallery`、`file` -- 操作行最多允许 5 个按钮或单个选择菜单 +- 操作行最多允许 5 个按钮，或单个选择菜单 - 选择类型：`string`、`user`、`role`、`mentionable`、`channel` -默认情况下，组件为一次性使用。设置 `components.reusable=true` 可让按钮、选择器和表单在过期前可被多次使用。 +默认情况下，components 为一次性使用。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前被多次使用。 -若要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 +如果要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条 ephemeral 拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商和模型下拉菜单，以及一个提交步骤。选择器回复是临时的，且只有发起调用的用户可以使用它。 +`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商和模型下拉菜单以及一个提交步骤。`/models add` 还支持直接在聊天中添加新的提供商/模型条目，新添加的模型无需重启 Gateway 网关就会显示出来。选择器回复是 ephemeral 的，并且只有调用它的用户可以使用。 文件附件： - `file` 块必须指向一个附件引用（`attachment://`） -- 通过 `media`/`path`/`filePath` 提供附件（单文件）；多个文件请使用 `media-gallery` +- 通过 `media`/`path`/`filePath` 提供附件（单个文件）；多个文件请使用 `media-gallery` - 当上传名称应与附件引用匹配时，使用 `filename` 覆盖上传名称 模态表单： -- 添加 `components.modal`，最多可包含 5 个字段 +- 添加 `components.modal`，最多支持 5 个字段 - 字段类型：`text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` -- OpenClaw 会自动添加一个触发按钮 +- OpenClaw 会自动添加一个触发表单按钮 示例： @@ -335,45 +335,45 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c channel: "discord", action: "send", to: "channel:123456789012345678", - message: "可选的回退文本", + message: "Optional fallback text", components: { reusable: true, - text: "选择一条路径", + text: "Choose a path", blocks: [ { type: "actions", buttons: [ { - label: "批准", + label: "Approve", style: "success", allowedUsers: ["123456789012345678"], }, - { label: "拒绝", style: "danger" }, + { label: "Decline", style: "danger" }, ], }, { type: "actions", select: { type: "string", - placeholder: "选择一个选项", + placeholder: "Pick an option", options: [ - { label: "选项 A", value: "a" }, - { label: "选项 B", value: "b" }, + { label: "Option A", value: "a" }, + { label: "Option B", value: "b" }, ], }, }, ], modal: { - title: "详细信息", - triggerLabel: "打开表单", + title: "Details", + triggerLabel: "Open form", fields: [ - { type: "text", label: "请求者" }, + { type: "text", label: "Requester" }, { type: "select", - label: "优先级", + label: "Priority", options: [ - { label: "低", value: "low" }, - { label: "高", value: "high" }, + { label: "Low", value: "low" }, + { label: "High", value: "high" }, ], }, ], @@ -386,27 +386,27 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - `channels.discord.dmPolicy` 控制私信访问（旧版：`channels.discord.dm.policy`）： + `channels.discord.dmPolicy` 用于控制私信访问（旧版：`channels.discord.dm.policy`）： - `pairing`（默认） - `allowlist` - `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`。 用于投递的私信目标格式： - `user:` - - `<@id>` 提及 + - `<@id>` mention - 纯数字 ID 存在歧义，除非显式提供用户/频道目标类型，否则会被拒绝。 + 裸数字 ID 存在歧义，因此会被拒绝，除非明确提供 user/channel 目标类型。 @@ -422,11 +422,11 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c `allowlist` 行为： - 服务器必须匹配 `channels.discord.guilds`（优先使用 `id`，也接受 slug） - - 可选的发送者允许列表：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了其中任意一个，则当发送者匹配 `users` 或 `roles` 时即被允许 - - 直接名称/标签匹配默认禁用；仅在紧急兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true` - - `users` 支持名称/标签，但 ID 更安全；当使用名称/标签条目时，`openclaw security audit` 会发出警告 + - 可选的发送者 allowlist：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了其中任一项，则当发送者匹配 `users` 或 `roles` 时允许通过 + - 默认禁用直接名称/tag 匹配；仅在紧急兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true` + - `users` 支持名称/tag，但 ID 更安全；使用名称/tag 条目时，`openclaw security audit` 会发出警告 - 如果某个服务器配置了 `channels`，则未列出的频道会被拒绝 - - 如果某个服务器没有 `channels` 块，则该允许列表中的服务器内所有频道都被允许 + - 如果某个服务器没有 `channels` 块，则该 allowlist 服务器中的所有频道都被允许 示例： @@ -452,33 +452,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`。 - 服务器消息默认需要提及才会触发。 + 默认情况下，服务器消息需要 mention 才会触发。 - 提及检测包括： + mention 检测包括： - - 显式提及机器人 - - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 在支持场景中的隐式回复机器人行为 + - 明确 mention 机器人 + - 已配置的 mention 模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） + - 在支持场景中的隐式回复给机器人行为 `requireMention` 按服务器/频道配置（`channels.discord.guilds...`）。 - `ignoreOtherMentions` 可选择性丢弃提及了其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 + `ignoreOtherMentions` 可选地丢弃那些 mention 了其他用户/角色但没有 mention 机器人的消息（不包括 @everyone/@here）。 群组私信： - 默认：忽略（`dm.groupEnabled=false`） - - 可选允许列表：通过 `dm.groupChannels`（频道 ID 或 slug） + - 可选：通过 `dm.groupChannels`（频道 ID 或 slug）建立 allowlist ### 基于角色的智能体路由 -使用 `bindings[].match.roles` 可按角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并且会在 peer 或 parent-peer 绑定之后、仅服务器绑定之前进行评估。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 +使用 `bindings[].match.roles` 可按角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并且会在 peer 或 parent-peer 绑定之后、guild-only 绑定之前进行求值。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 ```json5 { @@ -519,16 +519,16 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - Message Content Intent - Server Members Intent（推荐） - Presence intent 是可选的，仅当你想接收在线状态更新时才需要。设置机器人在线状态（`setPresence`）不要求为成员启用在线状态更新。 + Presence intent 是可选的，仅在你希望接收在线状态更新时才需要。设置机器人在线状态（`setPresence`）不需要为成员启用在线状态更新。 - + OAuth URL 生成器： - scopes：`bot`、`applications.commands` - 常见的基础权限： + 典型的基础权限： **General Permissions** - View Channels @@ -539,7 +539,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - Attach Files - Add Reactions（可选） - 这是普通文本频道所需的基础权限集。如果你计划在 Discord 线程中发帖，包括创建或继续线程的论坛或媒体频道工作流，还请启用 **Send Messages in Threads**。 + 这是普通文本频道的基础权限集。如果你计划在 Discord 线程中发帖，包括会创建或继续线程的论坛或媒体频道工作流，也请启用 **Send Messages in Threads**。 除非明确需要，否则避免使用 `Administrator`。 @@ -551,20 +551,20 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - 频道 ID - 用户 ID - 在 OpenClaw 配置中优先使用数字 ID，以获得可靠的审计和探测结果。 + 在 OpenClaw 配置中优先使用数字 ID，以获得更可靠的审计和探测结果。 ## 原生命令和命令认证 -- `commands.native` 默认是 `"auto"`，并为 Discord 启用。 +- `commands.native` 默认为 `"auto"`，并且对 Discord 已启用。 - 按渠道覆盖：`channels.discord.commands.native`。 -- `commands.native=false` 会显式清除先前已注册的 Discord 原生命令。 -- 原生命令认证使用与普通消息处理相同的 Discord 允许列表/策略。 -- 对于未授权用户，命令仍可能在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 认证，并返回 “未授权”。 +- `commands.native=false` 会显式清除先前注册的 Discord 原生命令。 +- 原生命令认证使用与普通消息处理相同的 Discord allowlist/策略。 +- 即使用户未获授权，命令仍可能在 Discord UI 中可见；但执行时仍会强制执行 OpenClaw 认证，并返回“未授权”。 -有关命令目录和行为，参见[斜杠命令](/zh-CN/tools/slash-commands)。 +命令目录和行为请参见[斜杠命令](/zh-CN/tools/slash-commands)。 默认斜杠命令设置： @@ -586,25 +586,25 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - `all` - `batched` - 注意：`off` 会禁用隐式回复线程。显式的 `[[reply_to_*]]` 标签仍然会被遵循。 - `first` 总是将隐式原生回复引用附加到该轮次的第一条 Discord 出站消息。 - `batched` 仅在入站轮次是由多条消息去抖合并后的批次时，才附加 Discord 的隐式原生回复引用。这在你希望原生回复主要用于容易混淆的突发聊天，而不是每一条单独消息轮次时非常有用。 + 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。 + `first` 总是会将隐式原生回复引用附加到当前轮次发出的第一条 Discord 出站消息上。 + `batched` 仅在入站轮次是多个消息的去抖批处理时，才附加 Discord 的隐式原生回复引用。这适用于你主要希望在有歧义的突发聊天中使用原生回复，而不是对每个单消息轮次都使用。 - 消息 ID 会在上下文/历史中呈现，因此智能体可以定位到特定消息。 + 消息 ID 会在上下文/历史中公开，因此智能体可以定向回复特定消息。 - OpenClaw 可以通过发送一条临时消息并在文本到达时持续编辑它，来流式显示草稿回复。 + OpenClaw 可以通过发送临时消息并在文本到达时持续编辑它来流式传输草稿回复。 - `channels.discord.streaming` 控制预览流式传输（`off` | `partial` | `block` | `progress`，默认：`off`）。 - - 默认保持 `off`，因为 Discord 预览编辑很容易触发速率限制，尤其是在多个机器人或 Gateway 网关共享同一账户或服务器流量时。 - - `progress` 为了跨渠道一致性而被接受，并在 Discord 上映射为 `partial`。 + - 默认保持为 `off`，因为 Discord 预览编辑很容易触发速率限制，尤其是在多个机器人或 Gateway 网关共享同一账户或服务器流量时。 + - `progress` 为了跨渠道一致性而被接受，并会映射为 Discord 上的 `partial`。 - `channels.discord.streamMode` 是旧版别名，会被自动迁移。 - - `partial` 会在 token 到达时编辑同一条预览消息。 + - `partial` 会在 token 到达时编辑单条预览消息。 - `block` 会输出草稿大小的分块（使用 `draftChunk` 调整大小和断点）。 - 媒体、错误和显式回复的最终消息会取消待处理的预览编辑，而不会在正常投递前先刷新临时草稿。 - - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条草稿预览消息（默认：`true`）。设置为 `false` 可保留单独的工具/进度消息。 + - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条草稿预览消息（默认：`true`）。设置为 `false` 可保留独立的工具/进度消息。 示例： @@ -618,7 +618,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - `block` 模式的分块默认值（限制在 `channels.discord.textChunkLimit` 范围内）： + `block` 模式的默认分块设置（会被限制在 `channels.discord.textChunkLimit` 范围内）： ```json5 { @@ -635,13 +635,13 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - 预览流式传输仅支持文本；媒体回复会回退到正常投递。 + 预览流式传输仅支持文本；媒体回复会回退为普通投递。 - 注意：预览流式传输与分块流式传输是分开的。当明确为 Discord 启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 + 注意：预览流式传输与分块流式传输是分开的。当 Discord 明确启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 - + 服务器历史上下文： - `channels.discord.historyLimit` 默认值为 `20` @@ -656,25 +656,25 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 线程行为： - Discord 线程会作为频道会话进行路由 - - 父线程元数据可用于父会话链接 + - 父线程元数据可用于父会话关联 - 线程配置会继承父频道配置，除非存在线程专用条目 频道主题会作为**不受信任**的上下文注入（而不是作为系统提示词）。 - 回复和引用消息上下文当前会按接收到的内容保留。 - Discord 允许列表主要用于控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 + 当前回复和引用消息上下文会按接收时原样保留。 + Discord allowlist 主要用于控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 - Discord 可以将线程绑定到一个会话目标，这样该线程中的后续消息会持续路由到同一个会话（包括子智能体会话）。 + Discord 可以将一个线程绑定到某个会话目标，从而使该线程中的后续消息持续路由到同一会话（包括子智能体会话）。 命令： - - `/focus ` 将当前/新线程绑定到子智能体/会话目标 + - `/focus ` 将当前/新线程绑定到某个子智能体/会话目标 - `/unfocus` 移除当前线程绑定 - `/agents` 显示活动运行和绑定状态 - - `/session idle ` 检查/更新聚焦绑定的空闲自动取消聚焦设置 - - `/session max-age ` 检查/更新聚焦绑定的硬性最大时长设置 + - `/session idle ` 查看/更新聚焦绑定的非活动自动取消聚焦设置 + - `/session max-age ` 查看/更新聚焦绑定的硬性最大存续时间 配置： @@ -700,12 +700,12 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - 注意： + 说明： - `session.threadBindings.*` 设置全局默认值。 - - `channels.discord.threadBindings.*` 覆盖 Discord 行为。 + - `channels.discord.threadBindings.*` 会覆盖 Discord 行为。 - `spawnSubagentSessions` 必须为 true，才能为 `sessions_spawn({ thread: true })` 自动创建/绑定线程。 - - `spawnAcpSessions` 必须为 true，才能为 ACP 自动创建/绑定线程（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）。 + - `spawnAcpSessions` 必须为 true，才能为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建/绑定线程。 - 如果某个账户禁用了线程绑定，则 `/focus` 和相关线程绑定操作不可用。 参见 [Sub-agents](/zh-CN/tools/subagents)、[ACP Agents](/zh-CN/tools/acp-agents) 和 [Configuration Reference](/zh-CN/gateway/configuration-reference)。 @@ -713,11 +713,11 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - 对于稳定的“始终在线” ACP 工作区，可配置顶层类型化 ACP 绑定，将其目标指向 Discord 会话。 + 对于稳定的“始终在线” ACP 工作区，可配置顶层的类型化 ACP 绑定，以 Discord 对话为目标。 配置路径： - - `bindings[]`，并设置 `type: "acp"` 和 `match.channel: "discord"` + - `bindings[]`，其中 `type: "acp"` 且 `match.channel: "discord"` 示例： @@ -767,45 +767,45 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - 注意： + 说明： - - `/acp spawn codex --bind here` 会将当前 Discord 频道或线程就地绑定，并让后续消息持续路由到同一个 ACP 会话。 - - 这仍可能意味着“启动一个新的 Codex ACP 会话”，但它本身不会创建新的 Discord 线程。现有频道仍然是聊天界面。 - - Codex 仍可能在其自己的 `cwd` 或磁盘上的后端工作区中运行。该工作区属于运行时状态，而不是 Discord 线程。 - - 线程消息可以继承父频道 ACP 绑定。 + - `/acp spawn codex --bind here` 会就地绑定当前 Discord 频道或线程，并让后续消息持续路由到同一个 ACP 会话。 + - 这仍然可能意味着“启动一个全新的 Codex ACP 会话”，但它本身不会创建新的 Discord 线程。现有频道仍然是聊天界面。 + - Codex 仍然可以在其自己的 `cwd` 或磁盘上的 backend 工作区中运行。该工作区属于运行时状态，而不是 Discord 线程。 + - 线程消息可以继承父频道的 ACP 绑定。 - 在已绑定的频道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。 - - 临时线程绑定仍然有效，并且在激活期间可以覆盖目标解析。 - - 只有当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子线程时，才要求 `spawnAcpSessions`。对于当前频道中的 `/acp spawn ... --bind here` 则不需要。 + - 临时线程绑定仍然有效，并且在活动期间可以覆盖目标解析。 + - 仅当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子线程时，才要求 `spawnAcpSessions`。对于当前频道中的 `/acp spawn ... --bind here`，则不需要。 - 绑定行为详情参见 [ACP Agents](/zh-CN/tools/acp-agents)。 + 有关绑定行为的详细信息，参见 [ACP Agents](/zh-CN/tools/acp-agents)。 - 按服务器配置的反应通知模式： + 每个服务器的反应通知模式： - `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 名称。 - 使用 `""` 可为某个渠道或账户禁用该反应。 @@ -813,9 +813,9 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 默认启用由渠道发起的配置写入。 - 这会影响 `/config set|unset` 流程（当启用命令功能时）。 + 这会影响 `/config set|unset` 流程（启用命令功能时）。 - 禁用： + 禁用方式： ```json5 { @@ -830,7 +830,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - 通过 `channels.discord.proxy` 将 Discord Gateway 网关 WebSocket 流量和启动 REST 查询（应用 ID + 允许列表解析）路由到 HTTP(S) 代理。 + 使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord gateway WebSocket 流量和启动时的 REST 查询（应用 ID + allowlist 解析）。 ```json5 { @@ -876,17 +876,17 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - 注意： + 说明： - - 允许列表可以使用 `pk:` - - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名 + - allowlist 可以使用 `pk:` + - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会通过名称/slug 匹配成员显示名 - 查询使用原始消息 ID，并受时间窗口限制 - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非 `allowBots=true` - 当你设置状态或活动字段，或启用自动在线状态时，会应用在线状态更新。 + 当你设置状态或活动字段，或者启用自动在线状态时，会应用在线状态更新。 仅状态示例： @@ -906,7 +906,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c { channels: { discord: { - activity: "专注时间", + activity: "Focus time", activityType: 4, }, }, @@ -919,7 +919,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c { channels: { discord: { - activity: "实时编程", + activity: "Live coding", activityType: 1, activityUrl: "https://twitch.tv/openclaw", }, @@ -933,7 +933,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - 1：Streaming（需要 `activityUrl`） - 2：Listening - 3：Watching - - 4：Custom（使用活动文本作为状态内容；表情可选） + - 4：Custom（使用活动文本作为状态内容；emoji 可选） - 5：Competing 自动在线状态示例（运行时健康信号）： @@ -946,7 +946,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c enabled: true, intervalMs: 30000, minUpdateIntervalMs: 15000, - exhaustedText: "token 已耗尽", + exhaustedText: "token exhausted", }, }, }, @@ -962,36 +962,36 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - Discord 支持在私信中基于按钮处理审批，也可以选择在源频道中发布审批提示。 + Discord 支持在私信中基于按钮处理审批，并且可以选择在发起渠道中发布审批提示。 配置路径： - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers`（可选；在可能情况下回退到 `commands.ownerAllowFrom`） + - `channels.discord.execApprovals.approvers`（可选；在可能时回退到 `commands.ownerAllowFrom`） - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` - 当 `enabled` 未设置或为 `"auto"` 且至少有一个审批人可被解析时，Discord 会自动启用原生 exec 审批，这些审批人可来自 `execApprovals.approvers` 或 `commands.ownerAllowFrom`。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec 审批人。设置 `enabled: false` 可显式禁用 Discord 作为原生审批客户端。 + 当 `enabled` 未设置或为 `"auto"`，且至少有一个 approver 可被解析时，Discord 会自动启用原生 exec 审批；该 approver 可以来自 `execApprovals.approvers`，也可以来自 `commands.ownerAllowFrom`。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec approver。将 `enabled: false` 设置为 false 可显式禁用 Discord 作为原生审批客户端。 - 当 `target` 为 `channel` 或 `both` 时，审批提示会在频道中可见。只有已解析的审批人可以使用这些按钮；其他用户会收到临时拒绝消息。审批提示包含命令文本，因此仅应在受信任频道中启用频道投递。如果无法从会话键推导频道 ID，OpenClaw 会回退为私信投递。 + 当 `target` 为 `channel` 或 `both` 时，审批提示会在频道中可见。只有已解析的 approver 可以使用这些按钮；其他用户会收到一条 ephemeral 拒绝消息。审批提示包含命令文本，因此仅应在受信任的频道中启用渠道投递。如果无法从会话键推导出频道 ID，OpenClaw 会回退为私信投递。 - Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要增加了审批人私信路由和频道扇出。 - 当这些按钮存在时，它们就是主要的审批 UX；只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，OpenClaw 才应包含手动 `/approve` 命令。 + Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要增加 approver 私信路由和渠道扇出。 + 当这些按钮存在时，它们就是主要的审批 UX；仅当工具结果表明聊天审批不可用，或手动审批是唯一可行路径时，OpenClaw 才应包含手动 `/approve` 命令。 - 该处理器的 Gateway 网关认证使用与其他 Gateway 网关客户端相同的共享凭证解析契约： + 此处理器的 Gateway 网关认证使用与其他 Gateway 网关客户端相同的共享凭证解析契约： - env-first 本地认证（`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`，然后是 `gateway.auth.*`） - - 在本地模式下，仅当 `gateway.auth.*` 未设置时，`gateway.remote.*` 才可用作回退；已配置但未解析的本地 SecretRef 会以失败关闭 - - 在适用时，通过 `gateway.remote.*` 支持远程模式 - - URL 覆盖具备安全覆盖特性：CLI 覆盖不会复用隐式凭证，环境变量覆盖仅使用环境变量凭证 + - 在本地模式下，仅当 `gateway.auth.*` 未设置时，才可使用 `gateway.remote.*` 作为回退；已配置但未解析的本地 SecretRef 会以失败关闭方式处理 + - 适用时，通过 `gateway.remote.*` 支持远程模式 + - URL 覆盖是覆盖安全的：CLI 覆盖不会复用隐式凭证，环境变量覆盖仅使用环境变量凭证 审批解析行为： - - 以 `plugin:` 为前缀的 ID 通过 `plugin.approval.resolve` 解析。 - - 其他 ID 通过 `exec.approval.resolve` 解析。 - - Discord 不会在这里执行额外的 exec 到 plugin 回退跳转；ID 前缀决定它调用哪个 Gateway 网关方法。 + - 带有 `plugin:` 前缀的 ID 会通过 `plugin.approval.resolve` 解析。 + - 其他 ID 会通过 `exec.approval.resolve` 解析。 + - Discord 不会在这里执行额外的 exec 到 plugin 回退跳转；ID 前缀决定它调用哪个 gateway 方法。 - Exec 审批默认在 30 分钟后过期。如果审批因未知审批 ID 而失败，请检查审批人解析、功能启用状态，以及已投递的审批 ID 类型是否与待处理请求匹配。 + 默认情况下，exec 审批会在 30 分钟后过期。如果审批因未知审批 ID 而失败，请检查 approver 解析、功能启用状态，以及已投递的审批 ID 类型是否与待处理请求匹配。 相关文档：[Exec approvals](/zh-CN/tools/exec-approvals) @@ -1000,34 +1000,34 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c ## 工具和操作门控 -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 | 已启用 | +| roles | 已禁用 | +| moderation | 已禁用 | +| presence | 已禁用 | ## Components v2 UI -OpenClaw 对 exec 审批和跨上下文标记使用 Discord components v2。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.ui.components.accentColor` 用于设置 Discord 组件容器使用的强调色（十六进制）。 +- 可通过 `channels.discord.accounts..ui.components.accentColor` 按账户设置。 - 当存在 components v2 时，`embeds` 会被忽略。 示例： @@ -1054,9 +1054,9 @@ OpenClaw 可以加入 Discord 语音频道，以进行实时、连续的对话 - 启用原生命令（`commands.native` 或 `channels.discord.commands.native`）。 - 配置 `channels.discord.voice`。 -- 机器人在目标语音频道中需要具备 Connect 和 Speak 权限。 +- 机器人需要在目标语音频道中具备 Connect 和 Speak 权限。 -使用仅限 Discord 的原生命令 `/vc join|leave|status` 来控制会话。该命令使用账户默认智能体，并遵循与其他 Discord 命令相同的允许列表和服务器策略规则。 +使用仅限 Discord 的原生命令 `/vc join|leave|status` 来控制会话。该命令使用账户默认智能体，并遵循与其他 Discord 命令相同的 allowlist 和服务器策略规则。 自动加入示例： @@ -1084,25 +1084,25 @@ OpenClaw 可以加入 Discord 语音频道，以进行实时、连续的对话 } ``` -注意： +说明： -- `voice.tts` 仅对语音播放生效，并会覆盖 `messages.tts`。 -- 语音转录轮次会根据 Discord `allowFrom`（或 `dm.allowFrom`）推导所有者状态；非所有者说话者无法访问仅限所有者的工具（例如 `gateway` 和 `cron`）。 -- 语音默认启用；设置 `channels.discord.voice.enabled=false` 可禁用。 -- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` 加入选项。 +- `voice.tts` 仅对语音播放覆盖 `messages.tts`。 +- 语音转录轮次会从 Discord `allowFrom`（或 `dm.allowFrom`）派生 owner 状态；非 owner 发言者无法访问仅限 owner 的工具（例如 `gateway` 和 `cron`）。 +- 默认启用语音；设置 `channels.discord.voice.enabled=false` 可禁用。 +- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的加入选项。 - 如果未设置，`@discordjs/voice` 的默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 -- OpenClaw 还会监视接收端解密失败，并在短时间内重复失败后通过离开/重新加入语音频道来自动恢复。 -- 如果接收日志持续显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，这可能是上游 `@discordjs/voice` 接收问题，见 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)。 +- OpenClaw 还会监控接收解密失败，并在短时间内反复失败后通过离开/重新加入语音频道自动恢复。 +- 如果接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，这可能是上游 `@discordjs/voice` 接收 bug，见 [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 不允许在同一个负载中同时发送文本和语音消息）。 -- 接受任意音频格式；OpenClaw 会在需要时将其转换为 OGG/Opus。 +- 省略文本内容（Discord 不允许在同一负载中同时包含文本和语音消息）。 +- 接受任意音频格式；必要时 OpenClaw 会将其转换为 OGG/Opus。 示例： @@ -1113,22 +1113,22 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## 故障排除 - + - 启用 Message Content Intent - - 当你依赖用户/成员解析时，启用 Server Members Intent + - 当你依赖 user/member 解析时，启用 Server Members Intent - 修改 intents 后重启 Gateway 网关 - + - 验证 `groupPolicy` - - 验证 `channels.discord.guilds` 下的服务器允许列表 - - 如果存在服务器 `channels` 映射，则只允许列出的频道 - - 验证 `requireMention` 行为和提及模式 + - 验证 `channels.discord.guilds` 下的服务器 allowlist + - 如果存在服务器 `channels` 映射，则仅允许其中列出的频道 + - 验证 `requireMention` 行为和 mention 模式 - 有用的检查： + 有用的检查命令： ```bash openclaw doctor @@ -1138,16 +1138,16 @@ openclaw logs --follow - + 常见原因： - - `groupPolicy="allowlist"`，但没有匹配的服务器/频道允许列表 + - `groupPolicy="allowlist"`，但没有匹配的服务器/频道 allowlist - `requireMention` 配置在错误位置（必须位于 `channels.discord.guilds` 或频道条目下） - - 发送者被服务器/频道 `users` 允许列表阻止 + - 发送者被服务器/频道 `users` allowlist 拦截 - + 典型日志： @@ -1155,16 +1155,16 @@ openclaw logs --follow - `Slow listener detected ...` - `discord inbound worker timed out after ...` - 监听器预算旋钮： + 监听器预算调节项： - 单账户：`channels.discord.eventQueue.listenerTimeout` - 多账户：`channels.discord.accounts..eventQueue.listenerTimeout` - 工作器运行超时旋钮： + worker 运行超时调节项： - 单账户：`channels.discord.inboundWorker.runTimeoutMs` - 多账户：`channels.discord.accounts..inboundWorker.runTimeoutMs` - - 默认值：`1800000`（30 分钟）；设置为 `0` 可禁用 + - 默认：`1800000`（30 分钟）；设置为 `0` 可禁用 推荐基线： @@ -1187,14 +1187,14 @@ openclaw logs --follow } ``` - 对于较慢的监听器设置，使用 `eventQueue.listenerTimeout`；只有当你希望为排队的智能体轮次设置单独安全阀时，才使用 `inboundWorker.runTimeoutMs`。 + 对于监听器初始化较慢的情况，使用 `eventQueue.listenerTimeout`；仅当你希望为排队的智能体轮次设置单独的安全阀时，才使用 `inboundWorker.runTimeoutMs`。 - `channels status --probe` 的权限检查仅适用于数字频道 ID。 + `channels status --probe` 的权限检查仅对数字频道 ID 有效。 - 如果你使用 slug 键，运行时匹配仍然可能正常工作，但探测无法完整验证权限。 + 如果你使用 slug 键，运行时匹配仍然可以工作，但 probe 无法完整验证权限。 @@ -1202,32 +1202,32 @@ 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`，请使用严格的 mention 和 allowlist 规则以避免循环行为。 + 更推荐使用 `channels.discord.allowBots="mentions"`，只接受 mention 了该机器人的机器人消息。 - 保持 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) 对照 -## 配置参考指针 +## 配置参考指引 主要参考： @@ -1239,7 +1239,7 @@ openclaw logs --follow - 策略：`groupPolicy`、`dm.*`、`guilds.*`、`guilds.*.channels.*` - 命令：`commands.native`、`commands.useAccessGroups`、`configWrites`、`slashCommand.*` - 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` -- 入站工作器：`inboundWorker.runTimeoutMs` +- 入站 worker：`inboundWorker.runTimeoutMs` - 回复/历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` - 投递：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` - 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` @@ -1253,8 +1253,8 @@ openclaw logs --follow ## 安全和运维 - 将机器人令牌视为机密（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 -- 授予最小权限的 Discord 权限。 -- 如果命令部署/状态已过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。 +- 按最小权限原则授予 Discord 权限。 +- 如果命令部署/状态已过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 再次检查。 ## 相关内容 diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index 14073bd8d..07c9e325a 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -1,20 +1,20 @@ --- read_when: - - 设置 Slack 或调试 Slack socket/HTTP 模式 -summary: Slack 设置和运行时行为（Socket Mode + HTTP Request URLs） + - 设置 Slack 或调试 Slack Socket/HTTP 模式 +summary: Slack 设置与运行时行为（Socket Mode + HTTP 请求 URL） title: Slack x-i18n: - generated_at: "2026-04-22T01:34:40Z" + generated_at: "2026-04-22T17:02:14Z" model: gpt-5.4 provider: openai - source_hash: e80b1ff7dfe3124916f9a4334badc9a742a0d0843b37c77838ede9f830920ff7 + source_hash: a1609ab5570daac455005cb00cee578c8954e05b25c25bf5759ae032d2a12c2c source_path: channels/slack.md workflow: 15 --- # Slack -状态：已可用于生产环境，支持通过 Slack 应用集成实现私信和渠道。默认模式为 Socket Mode；也支持 HTTP Request URLs。 +状态：已可用于通过 Slack 应用集成实现私信 + 渠道，达到生产就绪。默认模式为 Socket Mode；也支持 HTTP 请求 URL。 @@ -28,7 +28,7 @@ x-i18n: -## 快速设置 +## 快速开始 @@ -37,9 +37,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-...`） @@ -57,7 +57,7 @@ x-i18n: } ``` - 环境变量回退方案（仅默认账户）： + 环境变量回退（仅默认账户）： ```bash SLACK_APP_TOKEN=xapp-... @@ -77,15 +77,15 @@ openclaw gateway - + 在 Slack 应用设置中，点击 **[Create New App](https://api.slack.com/apps/new)** 按钮： - 选择 **from a manifest**，并为你的应用选择一个工作区 - - 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新这些 URL + - 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL - 保存用于请求校验的 **Signing Secret** - - 安装应用并复制显示的 **Bot Token**（`xoxb-...`） + - 安装应用，并复制显示的 **Bot Token**（`xoxb-...`） @@ -106,9 +106,9 @@ openclaw gateway ``` - 为多账户 HTTP 使用唯一的 webhook 路径 + 对多账户 HTTP 使用唯一的 webhook 路径 - 为每个账户设置不同的 `webhookPath`（默认是 `/slack/events`），以避免注册冲突。 + 为每个账户提供不同的 `webhookPath`（默认为 `/slack/events`），以避免注册冲突。 @@ -125,7 +125,7 @@ openclaw gateway -## 清单和作用域检查清单 +## 清单与 scope 检查清单 @@ -134,7 +134,7 @@ openclaw gateway { "display_information": { "name": "OpenClaw", - "description": "OpenClaw 的 Slack 连接器" + "description": "用于 OpenClaw 的 Slack 连接器" }, "features": { "bot_user": { @@ -205,13 +205,13 @@ openclaw gateway - + ```json { "display_information": { "name": "OpenClaw", - "description": "OpenClaw 的 Slack 连接器" + "description": "用于 OpenClaw 的 Slack 连接器" }, "features": { "bot_user": { @@ -291,17 +291,17 @@ openclaw gateway ### 其他清单设置 -展示扩展上述默认设置的不同功能。 +显示可扩展上述默认值的不同功能。 - + 可以使用多个[原生斜杠命令](#commands-and-slash-behavior)来替代单个已配置命令，但有一些细节需要注意： - 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已被保留。 - 同时可用的斜杠命令不能超过 25 个。 - 用[可用命令](/zh-CN/tools/slash-commands#command-list)中的一个子集替换你现有的 `features.slash_commands` 部分： + 将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)中的一个子集： @@ -310,7 +310,7 @@ openclaw gateway "slash_commands": [ { "command": "/new", - "description": "开始新会话", + "description": "开始一个新会话", "usage_hint": "[model]" }, { @@ -329,7 +329,7 @@ openclaw gateway { "command": "/session", "description": "管理线程绑定过期时间", - "usage_hint": "idle or max-age " + "usage_hint": "idle 或 max-age " }, { "command": "/think", @@ -353,7 +353,7 @@ openclaw gateway }, { "command": "/elevated", - "description": "切换提升模式", + "description": "切换 elevated 模式", "usage_hint": "[on|off|ask|full]" }, { @@ -368,8 +368,8 @@ openclaw gateway }, { "command": "/models", - "description": "列出提供商，或列出某个提供商的模型", - "usage_hint": "[provider] [page] [limit=|size=|all]" + "description": "列出提供商/模型或添加模型", + "usage_hint": "[provider] [page] [limit=|size=|all] | add " }, { "command": "/help", @@ -381,16 +381,16 @@ openclaw gateway }, { "command": "/tools", - "description": "显示当前智能体此刻可用的内容", + "description": "显示当前智能体此刻可以使用什么", "usage_hint": "[compact|verbose]" }, { "command": "/agentstatus", - "description": "显示运行时状态，包括可用时的提供商使用情况/配额" + "description": "显示运行时状态，包括可用时的提供商使用量/配额" }, { "command": "/tasks", - "description": "列出当前会话的活跃/最近后台任务" + "description": "列出当前会话的活动/近期后台任务" }, { "command": "/context", @@ -403,30 +403,30 @@ openclaw gateway }, { "command": "/skill", - "description": "按名称运行一个技能", + "description": "按名称运行一个 skill", "usage_hint": " [input]" }, { "command": "/btw", - "description": "提出一个不改变会话上下文的旁支问题", + "description": "在不更改会话上下文的情况下提出一个旁支问题", "usage_hint": "" }, { "command": "/usage", - "description": "控制用量页脚或显示成本摘要", + "description": "控制 usage 页脚或显示成本摘要", "usage_hint": "off|tokens|full|cost" } ] ``` - + ```json "slash_commands": [ { "command": "/new", - "description": "开始新会话", + "description": "开始一个新会话", "usage_hint": "[model]", "url": "https://gateway-host.example.com/slack/events" }, @@ -449,7 +449,7 @@ openclaw gateway { "command": "/session", "description": "管理线程绑定过期时间", - "usage_hint": "idle or max-age ", + "usage_hint": "idle 或 max-age ", "url": "https://gateway-host.example.com/slack/events" }, { @@ -478,7 +478,7 @@ openclaw gateway }, { "command": "/elevated", - "description": "切换提升模式", + "description": "切换 elevated 模式", "usage_hint": "[on|off|ask|full]", "url": "https://gateway-host.example.com/slack/events" }, @@ -512,18 +512,18 @@ openclaw gateway }, { "command": "/tools", - "description": "显示当前智能体此刻可用的内容", + "description": "显示当前智能体此刻可以使用什么", "usage_hint": "[compact|verbose]", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/agentstatus", - "description": "显示运行时状态，包括可用时的提供商使用情况/配额", + "description": "显示运行时状态，包括可用时的提供商使用量/配额", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/tasks", - "description": "列出当前会话的活跃/最近后台任务", + "description": "列出当前会话的活动/近期后台任务", "url": "https://gateway-host.example.com/slack/events" }, { @@ -539,19 +539,19 @@ openclaw gateway }, { "command": "/skill", - "description": "按名称运行一个技能", + "description": "按名称运行一个 skill", "usage_hint": " [input]", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/btw", - "description": "提出一个不改变会话上下文的旁支问题", + "description": "在不更改会话上下文的情况下提出一个旁支问题", "usage_hint": "", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/usage", - "description": "控制用量页脚或显示成本摘要", + "description": "控制 usage 页脚或显示成本摘要", "usage_hint": "off|tokens|full|cost", "url": "https://gateway-host.example.com/slack/events" } @@ -562,17 +562,17 @@ openclaw gateway - - 如果你希望发出的消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。 + + 如果你希望发送消息时使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。 - 如果你使用 emoji 图标，Slack 期望采用 `:emoji_name:` 语法。 + 如果你使用 emoji 图标，Slack 要求采用 `:emoji_name:` 语法。 - - 如果你配置了 `channels.slack.userToken`，典型的读取作用域包括： + + 如果你配置了 `channels.slack.userToken`，典型的读取 scope 包括： - - `channels:history`、`groups:history`、`im:history`、`mpim:history` - - `channels:read`、`groups:read`、`im:read`、`mpim:read` + - `channels:history`, `groups:history`, `im:history`, `mpim:history` + - `channels:read`, `groups:read`, `im:read`, `mpim:read` - `users:read` - `reactions:read` - `pins:read` @@ -586,11 +586,11 @@ openclaw gateway - Socket Mode 需要 `botToken` + `appToken`。 - HTTP 模式需要 `botToken` + `signingSecret`。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 支持明文 字符串或 SecretRef 对象。 -- 配置中的令牌会覆盖环境变量回退值。 +- 配置中的令牌会覆盖环境变量回退。 - `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账户。 -- `userToken`（`xoxp-...`）仅支持通过配置提供（无环境变量回退），并默认采用只读行为（`userTokenReadOnly: true`）。 +- `userToken`（`xoxp-...`）仅支持配置方式（无环境变量回退），且默认是只读行为（`userTokenReadOnly: true`）。 状态快照行为： @@ -598,20 +598,20 @@ openclaw gateway 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。 - 状态可以是 `available`、`configured_unavailable` 或 `missing`。 - `configured_unavailable` 表示该账户通过 SecretRef - 或其他非内联密钥来源进行了配置，但当前命令/运行时路径 + 或其他非内联 secret 来源进行了配置，但当前命令/运行时路径 无法解析出实际值。 - 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下， - 所需的字段组合是 `botTokenStatus` + `appTokenStatus`。 + 必需的状态对是 `botTokenStatus` + `appTokenStatus`。 -对于 actions / 目录读取，配置了用户令牌时可以优先使用它。对于写入操作，仍然优先使用 bot 令牌；只有在 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。 +对于操作/目录读取，如果已配置，可以优先使用用户令牌。对于写入操作，仍然优先使用 bot 令牌；只有当 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。 -## Actions 和门控 +## 操作与门控 -Slack actions 由 `channels.slack.actions.*` 控制。 +Slack 操作由 `channels.slack.actions.*` 控制。 -当前 Slack 工具中可用的 action 分组： +当前 Slack 工具中的可用操作组： | Group | Default | | ---------- | ------- | @@ -621,9 +621,9 @@ Slack actions 由 `channels.slack.actions.*` 控制。 | memberInfo | enabled | | emojiList | enabled | -当前 Slack 消息 actions 包括 `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`。 -## 访问控制和路由 +## 访问控制与路由 @@ -636,17 +636,17 @@ Slack actions 由 `channels.slack.actions.*` 控制。 私信标志： - - `dm.enabled`（默认 true） + - `dm.enabled`（默认为 true） - `channels.slack.allowFrom`（推荐） - `dm.allowFrom`（旧版） - - `dm.groupEnabled`（群组私信默认 false） + - `dm.groupEnabled`（群组私信默认为 false） - `dm.groupChannels`（可选 MPIM allowlist） 多账户优先级： - `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 `。 @@ -659,56 +659,56 @@ 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 条目会在启动时解析 - - 无法解析的渠道名称条目会按原样保留，但默认会在路由中被忽略 - - 入站授权和渠道路由默认优先按 ID 处理；直接按用户名/slug 匹配需要设置 `channels.slack.dangerouslyAllowNameMatching: true` + - 当令牌访问权限允许时，渠道 allowlist 条目和私信 allowlist 条目会在启动时解析 + - 无法解析的渠道名称条目会按配置保留，但默认在路由中被忽略 + - 入站授权和渠道路由默认优先按 ID 处理；如果要直接匹配用户名/slug，需要设置 `channels.slack.dangerouslyAllowNameMatching: true` - - 渠道消息默认受提及门控保护。 + + 默认情况下，渠道消息受提及门控限制。 提及来源： - 显式应用提及（`<@botId>`） - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 隐式机器人线程回复行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） + - 隐式回复给 bot 的线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） - 每个渠道的控制项（`channels.slack.channels.`；名称仅通过启动时解析或 `dangerouslyAllowNameMatching` 支持）： + 每个渠道的控制项（`channels.slack.channels.`；仅能通过启动时解析或 `dangerouslyAllowNameMatching` 使用名称）： - `requireMention` - `users`（allowlist） - `allowBots` - `skills` - `systemPrompt` - - `tools`、`toolsBySender` + - `tools`, `toolsBySender` - `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符 （旧版无前缀键仍然只会映射到 `id:`） -## 线程、会话和回复标签 +## 线程、会话与回复标签 - 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。 -- 在默认 `session.dmScope=main` 下，Slack 私信会折叠到智能体主会话。 +- 使用默认 `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` 门控。 +- 在线程适用时，线程回复可以创建线程会话后缀（`:thread:`）。 +- `channels.slack.thread.historyScope` 默认为 `thread`；`thread.inheritParent` 默认为 `false`。 +- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时要抓取多少条现有线程消息（默认 `20`；设置为 `0` 可禁用）。 +- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当设为 `true` 时，会抑制隐式线程提及，因此 bot 仅会响应线程内显式的 `@bot` 提及，即使 bot 已经参与该线程也是如此。如果不这样设置，在 bot 已参与的线程中回复会绕过 `requireMention` 门控。 回复线程控制： - `channels.slack.replyToMode`：`off|first|all|batched`（默认 `off`） - `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 分别设置 -- 私信的旧版回退：`channels.slack.dm.replyToMode` +- 直聊的旧版回退：`channels.slack.dm.replyToMode` 支持手动回复标签： @@ -717,7 +717,7 @@ Slack actions 由 `channels.slack.actions.*` 控制。 注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程功能，包括显式的 `[[reply_to_*]]` 标签。这与 Telegram 不同，在 Telegram 中，显式标签在 `"off"` 模式下仍会生效。这种差异反映了平台的线程模型：Slack 线程会将消息隐藏在渠道之外，而 Telegram 回复仍会显示在主聊天流中。 -## 确认 reaction +## 确认反应 `ackReaction` 会在 OpenClaw 处理入站消息期间发送一个确认 emoji。 @@ -730,8 +730,8 @@ Slack actions 由 `channels.slack.actions.*` 控制。 说明： -- Slack 期望使用短代码（例如 `"eyes"`）。 -- 使用 `""` 可为 Slack 账户或全局禁用该 reaction。 +- Slack 要求使用短代码（例如 `"eyes"`）。 +- 使用 `""` 可为 Slack 账户或全局禁用该反应。 ## 文本流式传输 @@ -740,19 +740,19 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - `off`：禁用实时预览流式传输。 - `partial`（默认）：用最新的部分输出替换预览文本。 - `block`：追加分块的预览更新。 -- `progress`：生成期间显示进度状态文本，然后发送最终文本。 -- `streaming.preview.toolProgress`：当草稿预览处于启用状态时，将工具/进度更新路由到同一个被编辑的预览消息中（默认：`true`）。设为 `false` 可保留独立的工具/进度消息。 +- `progress`：在生成期间显示进度状态文本，然后发送最终文本。 +- `streaming.preview.toolProgress`：当草稿预览处于激活状态时，将工具/进度更新路由到同一条被编辑的预览消息中（默认：`true`）。设为 `false` 可保留单独的工具/进度消息。 当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。 -- 必须有一个回复线程可用，Slack 原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍然遵循 `replyToMode`。 +- 原生文本流式传输和 Slack assistant 线程状态显示都必须有可用的回复线程。线程选择仍然遵循 `replyToMode`。 - 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。 -- 顶层 Slack 私信默认保持无线程，因此不会显示线程式预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。 -- 媒体和非文本负载会回退到普通投递。 +- 顶层 Slack 私信默认保持在线程外，因此不会显示线程样式预览；如果你希望那里有可见进度，请使用线程回复或 `typingReaction`。 +- 媒体和非文本载荷会回退为常规投递。 - 媒体/错误最终消息会取消待处理的预览编辑，而不会刷新临时草稿；符合条件的文本/块最终消息仅会在能够原地编辑预览时刷新。 -- 如果流式传输在回复中途失败，OpenClaw 会对剩余负载回退到普通投递。 +- 如果流式传输在回复中途失败，OpenClaw 会对剩余载荷回退为常规投递。 -使用草稿预览而不是 Slack 原生文本流式传输： +使用草稿预览代替 Slack 原生文本流式传输： ```json5 { @@ -773,9 +773,9 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。 - 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。 -## 输入中 reaction 回退 +## 输入中反应回退 -`typingReaction` 会在 OpenClaw 处理回复期间，为入站 Slack 消息添加一个临时 reaction，并在运行结束后将其移除。这在非线程回复场景中最有用，因为线程回复会使用默认的 “is typing...” 状态指示器。 +`typingReaction` 会在 OpenClaw 处理回复期间，给入站 Slack 消息添加一个临时反应，并在运行结束后移除。它在线程回复之外最有用，因为线程回复默认使用 “is typing...” 状态指示器。 解析顺序： @@ -784,40 +784,40 @@ Slack actions 由 `channels.slack.actions.*` 控制。 说明： -- Slack 期望使用短代码（例如 `"hourglass_flowing_sand"`）。 -- 该 reaction 为尽力而为机制，并会在回复完成或失败路径结束后自动尝试清理。 +- Slack 要求使用短代码（例如 `"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"` 启用优先按段落拆分 - 文件发送使用 Slack 上传 API，并可包含线程回复（`thread_ts`） - - 如果配置了 `channels.slack.mediaMaxMb`，出站媒体上限遵循该设置；否则渠道发送使用媒体管道中的 MIME 类型默认值 + - 如果配置了 `channels.slack.mediaMaxMb`，出站媒体上限将遵循该值；否则渠道发送会使用媒体管道中的 MIME 类型默认值 - 推荐使用的显式目标： + 推荐的显式目标： - 私信使用 `user:` - 渠道使用 `channel:` - 向用户目标发送时，Slack 私信会通过 Slack 会话 API 打开。 + 发送到用户目标时，Slack 私信会通过 Slack 会话 API 打开。 -## 命令和斜杠行为 +## 命令与斜杠行为 -斜杠命令在 Slack 中可表现为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： +Slack 中的斜杠命令可以显示为单个已配置命令，或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： - `enabled: false` - `name: "openclaw"` @@ -828,30 +828,30 @@ 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，原生命令自动模式默认是 **off**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。 ```txt /help ``` -原生参数菜单使用自适应渲染策略，在派发所选选项值前会先显示一个确认模态框： +原生参数菜单使用自适应渲染策略，在分发所选选项值之前先显示确认模态框： - 最多 5 个选项：按钮块 -- 6-100 个选项：静态选择菜单 -- 超过 100 个选项：当可用 interactivity 选项处理器时，使用带异步选项过滤的外部选择 -- 超出 Slack 限制：编码后的选项值会回退为按钮 +- 6 - 100 个选项：静态选择菜单 +- 超过 100 个选项：当交互式选项处理器可用时，使用带异步选项过滤的外部选择 +- 超出 Slack 限制时：编码后的选项值会回退为按钮 ```txt /think ``` -斜杠会话使用类似 `agent::slack:slash:` 的隔离键，并仍通过 `CommandTargetSessionKey` 将命令执行路由到目标会话。 +斜杠会话使用类似 `agent::slack:slash:` 的隔离键，但仍会通过 `CommandTargetSessionKey` 将命令执行路由到目标会话。 ## 交互式回复 -Slack 可以渲染由智能体编写的交互式回复控件，但此功能默认禁用。 +Slack 可以渲染由智能体创作的交互式回复控件，但此功能默认禁用。 全局启用： @@ -867,7 +867,7 @@ Slack 可以渲染由智能体编写的交互式回复控件，但此功能默 } ``` -或者仅为某个 Slack 账户启用： +或者仅为一个 Slack 账户启用： ```json5 { @@ -885,41 +885,40 @@ 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 可以充当原生审批客户端，使用交互式按钮和交互，而不是回退到 Web UI 或终端。 +Slack 可以作为原生审批客户端，使用交互式按钮和交互，而不是回退到 Web UI 或终端。 - Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 -- 如果请求已经到达 Slack 且审批 ID 类型为 `plugin:`，插件审批仍可通过同一个 Slack 原生按钮界面处理。 -- 审批人授权仍会被强制执行：只有被识别为审批人的用户，才能通过 Slack 批准或拒绝请求。 +- 当请求已经落在 Slack 中且审批 ID 类型为 `plugin:` 时，插件审批也仍可通过同一套 Slack 原生按钮界面处理。 +- 审批人授权仍会被强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。 -这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用了 `interactivity` 时，审批提示会直接在会话中渲染为 Block Kit 按钮。 -当这些按钮存在时，它们就是主要审批 UX；OpenClaw -只应在工具结果表明聊天审批不可用，或手动审批是唯一途径时，包含手动 `/approve` 命令。 +这使用与其他渠道相同的共享审批按钮界面。当你在 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 审批配置时的默认行为： @@ -931,7 +930,7 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 } ``` -只有在你想覆盖审批人、添加过滤器或选择加入来源聊天投递时，才需要显式 Slack 原生配置： +只有当你想覆盖审批人、添加过滤器，或选择加入原始聊天投递时，才需要显式的 Slack 原生配置： ```json5 { @@ -947,23 +946,21 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 } ``` -共享 `approvals.exec` 转发是独立的。只有当 exec 审批提示也必须 -路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也 -是独立的；当这些请求已经到达 Slack 时，Slack 原生按钮仍可处理插件审批。 +共享的 `approvals.exec` 转发是独立的。只有当 exec 审批提示还必须路由到其他聊天或显式的带外目标时才使用它。共享的 `approvals.plugin` 转发也是独立的；当这些请求已经落在 Slack 中时，Slack 原生按钮仍可处理插件审批。 -同一聊天中的 `/approve` 在已经支持命令的 Slack 渠道和私信中也可使用。完整审批转发模型请参见[Exec 审批](/zh-CN/tools/exec-approvals)。 +同一聊天中的 `/approve` 在已经支持命令的 Slack 渠道和私信中也可使用。完整的审批转发模型见[Exec 审批](/zh-CN/tools/exec-approvals)。 -## 事件和运行行为 +## 事件与运行行为 - 消息编辑/删除/线程广播会映射为系统事件。 -- reaction 添加/移除事件会映射为系统事件。 -- 成员加入/离开、渠道创建/重命名以及 pin 添加/移除事件会映射为系统事件。 +- 添加/移除反应事件会映射为系统事件。 +- 成员加入/离开、渠道创建/重命名以及添加/移除 pin 事件会映射为系统事件。 - 当启用 `configWrites` 时，`channel_id_changed` 可迁移渠道配置键。 - 渠道 topic/purpose 元数据被视为不可信上下文，并可注入到路由上下文中。 -- 在线程起始消息和初始线程历史上下文植入时，如适用，会根据已配置的发送者 allowlist 进行过滤。 -- Block actions 和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并附带丰富的负载字段： - - block actions：所选值、标签、选择器值和 `workflow_*` 元数据 - - 模态 `view_submission` 和 `view_closed` 事件，包含路由后的渠道元数据和表单输入 +- 线程发起者和初始线程历史上下文播种在适用时会按已配置的发送者 allowlist 进行过滤。 +- 块操作和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并包含丰富的载荷字段： + - 块操作：所选值、标签、选择器值以及 `workflow_*` 元数据 + - 模态 `view_submission` 和 `view_closed` 事件，包含已路由的渠道元数据和表单输入 ## 配置参考指针 @@ -974,7 +971,7 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 高信号 Slack 字段： - 模式/认证：`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` @@ -989,7 +986,7 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 - `groupPolicy` - 渠道 allowlist（`channels.slack.channels`） - `requireMention` - - 每渠道 `users` allowlist + - 每个渠道的 `users` allowlist 有用的命令： @@ -1014,37 +1011,37 @@ openclaw pairing list slack - + 验证 bot + app 令牌，以及 Slack 应用设置中是否启用了 Socket Mode。 如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或 - `appTokenStatus: "configured_unavailable"`，则说明该 Slack 账户已 - 配置，但当前运行时无法解析由 SecretRef 支持的 + `appTokenStatus: "configured_unavailable"`，说明该 Slack 账户 + 已配置，但当前运行时无法解析由 SecretRef 支持的 实际值。 - + 验证： - signing secret - webhook 路径 - - Slack Request URLs（Events + Interactivity + Slash Commands） + - Slack 请求 URL（事件 + 交互 + 斜杠命令） - 每个 HTTP 账户使用唯一的 `webhookPath` 如果账户快照中出现 `signingSecretStatus: "configured_unavailable"`， - 则说明该 HTTP 账户已配置，但当前运行时无法 + 说明该 HTTP 账户已配置，但当前运行时无法 解析由 SecretRef 支持的 signing secret。 - - 请确认你是否本来想要： + + 验证你原本打算使用的是： - - 原生命令模式（`channels.slack.commands.native: true`），并且已在 Slack 中注册匹配的斜杠命令 + - 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册了匹配的斜杠命令 - 或单一斜杠命令模式（`channels.slack.slashCommand.enabled: true`） - 还要检查 `commands.useAccessGroups` 以及渠道/用户 allowlist。 + 另请检查 `commands.useAccessGroups` 以及渠道/用户 allowlist。 @@ -1053,7 +1050,7 @@ openclaw pairing list slack - [配对](/zh-CN/channels/pairing) - [群组](/zh-CN/channels/groups) -- [安全性](/zh-CN/gateway/security) +- [安全](/zh-CN/gateway/security) - [渠道路由](/zh-CN/channels/channel-routing) - [故障排除](/zh-CN/channels/troubleshooting) - [配置](/zh-CN/gateway/configuration) diff --git a/docs/zh-CN/concepts/models.md b/docs/zh-CN/concepts/models.md index 5b62ae1df..bf0c383f6 100644 --- a/docs/zh-CN/concepts/models.md +++ b/docs/zh-CN/concepts/models.md @@ -1,47 +1,47 @@ --- read_when: - 添加或修改模型 CLI（`models list`/`set`/`scan`/`aliases`/`fallbacks`） - - 更改模型回退行为或选择 UX + - 更改模型回退行为或选择体验 - 更新模型扫描探测（工具/图像） -summary: 模型 CLI：列表、设置、别名、回退、扫描、状态 +summary: 模型 CLI：列出、设置、别名、回退、扫描、状态 title: 模型 CLI x-i18n: - generated_at: "2026-04-22T03:53:27Z" + generated_at: "2026-04-22T17:02:15Z" model: gpt-5.4 provider: openai - source_hash: 0cf7a17a20bea66e5e8dce134ed08b483417bc70ed875e796609d850aa79280e + source_hash: 94fe5b6012f12ab469305bcae95b2b7e9482f2d6868fc8a71a8c9ac2bd0e8604 source_path: concepts/models.md workflow: 15 --- # 模型 CLI -关于凭证配置文件轮换、冷却时间，以及它们如何与回退机制交互，请参见 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 +有关凭证配置文件轮换、冷却时间以及它们如何与回退机制交互，请参见 [/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 密钥。 -- `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)）。 +- `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)）。 ## 快速模型策略 -- 将你的主模型设为你可用的、最新一代中能力最强的模型。 -- 对成本/延迟敏感的任务和风险较低的聊天，使用回退模型。 -- 对于启用工具的智能体或不可信输入，避免使用较旧/较弱的模型层级。 +- 将你的主模型设置为你可用的最强、最新一代模型。 +- 对成本/延迟敏感的任务和低风险聊天，使用回退模型。 +- 对启用了工具的智能体或不可信输入，避免使用较旧/较弱的模型层级。 ## 新手引导（推荐） @@ -51,9 +51,10 @@ OpenClaw 按以下顺序选择模型： openclaw onboard ``` -它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code（Codex）订阅**（OAuth）和 **Anthropic**（API 密钥或 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` @@ -63,23 +64,24 @@ openclaw onboard - `agents.defaults.models`（允许列表 + 别名 + 提供商参数） - `models.providers`（写入 `models.json` 的自定义提供商） -模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会规范化为 `zai/*`。 +模型引用会规范化为小写。像 `z.ai/*` 这样的提供商别名会规范化为 +`zai/*`。 -提供商配置示例（包括 OpenCode）位于 +提供商配置示例（包括 OpenCode）见 [/providers/opencode](/zh-CN/providers/opencode)。 ## “Model is not allowed”（以及为什么回复会停止） -如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择了不在该允许列表中的模型时，OpenClaw 会返回： +如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择的模型不在该允许列表中时，OpenClaw 会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` -这会发生在生成正常回复**之前**，所以消息看起来可能像是“没有响应”。解决方法是： +这会在生成正常回复**之前**发生，因此消息可能会让人感觉它“没有响应”。修复方法是： - 将该模型添加到 `agents.defaults.models`，或 -- 清除允许列表（移除 `agents.defaults.models`），或 +- 清空允许列表（移除 `agents.defaults.models`），或 - 从 `/model list` 中选择一个模型。 允许列表示例配置： @@ -98,7 +100,7 @@ Model "provider/model" is not allowed. Use /model to list available models. ## 在聊天中切换模型（`/model`） -你可以在不重启的情况下为当前会话切换模型： +你可以为当前会话切换模型，而无需重启： ``` /model @@ -112,21 +114,32 @@ Model "provider/model" is not allowed. Use /model to list available models. - `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。 - 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个提交步骤。 +- `/models add` 让你可以直接在聊天中添加一个提供商/模型条目，而无需手动编辑配置。 +- `/models add ` 是最快路径；仅输入 `/models add` 会在支持的情况下启动一个先选提供商的引导流程。 +- 执行 `/models add` 后，新模型会立即在 `/models` 和 `/model` 中可用，无需重启 Gateway 网关。 - `/model <#>` 会从该选择器中选择。 - `/model` 会立即持久化新的会话选择。 -- 如果智能体处于空闲状态，下一次运行会立即使用新模型。 -- 如果某次运行已处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在一个干净的重试点重启到新模型。 -- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续重试机会或下一个用户轮次。 -- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` + `api` 模式）。 -- 模型引用通过按**第一个** `/` 分割来解析。输入 `/model ` 时，请使用 `provider/model`。 -- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。 +- 如果智能体当前空闲，下一次运行会立刻使用新模型。 +- 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在一个干净的重试点重启到新模型。 +- 如果工具活动或回复输出已经开始，待处理切换可能会继续排队，直到后续某个重试机会或下一次用户轮次。 +- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` 和 `api` 模式）。 +- 模型引用通过按**第一个** `/` 分割来解析。输入 `/model ` 时请使用 `provider/model`。 +- 如果模型 ID 本身包含 `/`（OpenRouter 风格），则必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。 - 如果你省略提供商，OpenClaw 会按以下顺序解析输入： 1. 别名匹配 - 2. 该确切无前缀模型 ID 的唯一已配置提供商匹配 + 2. 对该精确无前缀模型 ID 的唯一已配置提供商匹配 3. 已弃用的回退：使用已配置的默认提供商 - 如果该提供商不再公开已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露过时的、已移除提供商默认值。 + 如果该提供商不再公开已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露陈旧、已移除提供商的默认值。 -完整命令行为/配置： [Slash commands](/zh-CN/tools/slash-commands)。 +完整命令行为/配置：[/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 +``` ## CLI 命令 @@ -155,7 +168,7 @@ openclaw models image-fallbacks clear ### `models list` -默认显示已配置的模型。常用标志： +默认显示已配置模型。常用标志： - `--all`：完整目录 - `--local`：仅本地提供商 @@ -163,18 +176,21 @@ openclaw models image-fallbacks clear - `--plain`：每行一个模型 - `--json`：机器可读输出 -`--all` 会在配置凭证之前包含内置的、由提供商拥有的静态目录条目，因此仅发现用途的视图也可以显示那些在你添加匹配提供商凭证之前不可用的模型。 +`--all` 会在配置凭证之前包含内置的、由提供商拥有的静态目录行，因此仅用于发现的视图也可以显示那些在你添加匹配提供商凭证之前不可用的模型。 ### `models status` -显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 过期状态（默认会在 24 小时内到期时发出警告）。`--plain` 仅打印已解析的主模型。 -OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置的提供商没有凭证，`models status` 会打印一个 **Missing auth** 部分。 -JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的生效凭证，包括基于环境变量的凭证）。`auth.oauth` 仅表示凭证存储中配置文件的健康状态；仅使用环境变量的提供商不会出现在其中。 -将 `--check` 用于自动化（缺失/已过期时退出码为 `1`，即将过期时为 `2`）。 -将 `--probe` 用于实时凭证检查；探测行可能来自凭证配置文件、环境变量凭证或 `models.json`。 -如果显式的 `auth.order.` 省略了某个已存储配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果凭证存在，但该提供商无法解析出可探测的模型，探测会报告 `status: no_model`。 +显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示凭证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内到期时警告）。`--plain` 仅打印已解析的主模型。 +OAuth 状态始终会显示（也包含在 `--json` 输出中）。如果某个已配置提供商没有凭证，`models status` 会打印一个**缺少凭证**部分。 +JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers` +（每个提供商的生效凭证，包括由环境变量支持的凭证）。`auth.oauth` +仅表示凭证存储配置文件的健康状态；仅使用环境变量的提供商不会出现在其中。 +自动化场景请使用 `--check`（缺少/已过期时退出码为 `1`，即将过期时为 `2`）。 +实时凭证检查请使用 `--probe`；探测行可以来自凭证配置文件、环境变量凭证或 `models.json`。 +如果显式的 `auth.order.` 省略了某个已存储配置文件，探测会报告 +`excluded_by_auth_order`，而不是尝试它。如果凭证存在但无法为该提供商解析出可探测模型，探测会报告 `status: no_model`。 -凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API 密钥通常是最可预测的；也支持复用 Claude CLI 和现有 Anthropic OAuth/令牌配置文件。 +凭证选择取决于提供商/账户。对于持续运行的 Gateway 网关主机，API 密钥通常最可预测；也支持重用 Claude CLI，以及现有的 Anthropic OAuth/token 配置文件。 示例（Claude CLI）： @@ -185,7 +201,7 @@ openclaw models status ## 扫描（OpenRouter 免费模型） -`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型是否支持工具和图像。 +`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型的工具和图像支持。 关键标志： @@ -194,49 +210,50 @@ openclaw models status - `--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 密钥（来自凭证配置文件或 `OPENROUTER_API_KEY`）。 -如果没有密钥，请使用 `--no-probe` 仅列出候选项。 +探测需要 OpenRouter API 密钥（来自凭证配置文件或 +`OPENROUTER_API_KEY`）。如果没有密钥，请使用 `--no-probe` 仅列出候选项。 扫描结果按以下顺序排序： 1. 图像支持 2. 工具延迟 3. 上下文大小 -4. 参数数量 +4. 参数量 输入 - OpenRouter `/models` 列表（筛选 `:free`） - 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/zh-CN/help/environment)） -- 可选筛选项：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` +- 可选筛选：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` - 探测控制：`--timeout`、`--concurrency` 在 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，合并模式优先级如下： - 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。 -- 智能体 `models.json` 中非空的 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中不是 SecretRef 管理时优先。 -- SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 -- SecretRef 管理的提供商请求头值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 +- 智能体 `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) — 回退链 -- [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/configuration-reference#agent-defaults) — 模型配置键名 +- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由与凭证 +- [模型回退](/zh-CN/concepts/model-failover) — 回退链 +- [图像生成](/zh-CN/tools/image-generation) — 图像模型配置 +- [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置 +- [视频生成](/zh-CN/tools/video-generation) — 视频模型配置 +- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键