openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-26 03:28:53 +00:00
parent 5183903081
commit b1844d4c7a
5 changed files with 497 additions and 514 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

412
docs/zh-CN/channels/discord.md
View File

@ -4,10 +4,10 @@ read_when:
summary: Discord 机器人支持状态、功能和配置
title: Discord
x-i18n:
generated_at: "2026-04-25T11:52:07Z"
generated_at: "2026-04-26T03:26:32Z"
model: gpt-5.4
provider: openai
source_hash: 685dd2dce8a299233b14e7bdd5f502ee92f740b7dbb3104e86e0c2f36aabcfe1
source_hash: 68f4e1885aab2438c38ef3735b752968b7e1ed70795d1c3903fad20ff183d3ca
source_path: channels/discord.md
workflow: 15
---
@ -22,13 +22,13 @@ x-i18n:
原生命令行为和命令目录。
</Card>
<Card title="渠道故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
跨渠道诊断和修复流程。
跨渠道诊断与修复流程。
</Card>
</CardGroup>
## 快速设置
## 快速开始
你需要创建一个带机器人的新应用，将机器人添加到你的服务器，并将其与 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**）。
<Steps>
<Step title="创建 Discord 应用和机器人">
@ -39,19 +39,19 @@ x-i18n:
</Step>
<Step title="启用特权 intents">
仍然在 **Bot** 页面，向下滚动到 **Privileged Gateway Intents** 并启用：
仍然停留在 **Bot** 页面，向下滚动到 **Privileged Gateway Intents**，然后启用：
- **Message Content Intent**（必需）
- **Server Members Intent**（推荐；角色 allowlist 和名称到 ID 匹配时必需）
- **Presence Intent**（可选；仅在需要在线状态更新时才需要）
- **Server Members Intent**（推荐；角色 allowlist 和名称到 ID 匹配必需）
- **Presence Intent**（可选；仅在需要在线状态更新时使用）
</Step>
<Step title="复制你的机器人令牌">
向上滚回 **Bot** 页面顶部，然后点击 **Reset Token**。
向上滚动回到 **Bot** 页面顶部，然后点击 **Reset Token**。
<Note>
尽管名字如此，这是在生成你的第一个令牌——并没有任何内容被“重置”。
尽管名称如此，这会生成你的第一个令牌——并没有任何内容被“重置”。
</Note>
复制该令牌并将其保存到某处。这就是你的 **Bot Token**，你很快就会用到它。
@ -59,14 +59,14 @@ x-i18n:
</Step>
<Step title="生成邀请 URL 并将机器人添加到你的服务器">
点击侧边栏中的 **OAuth2**。你将生成一个具有正确权限的邀请 URL，以便将机器人添加到你的服务器。
点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用于将机器人添加到你的服务器。
向下滚动到 **OAuth2 URL Generator** 并启用：
向下滚动到 **OAuth2 URL Generator**，并启用：
- `bot`
- `applications.commands`
下方会出现一个 **Bot Permissions** 部分。至少启用：
下方会出现一个 **Bot Permissions** 区域。至少启用：
**General Permissions**
- View Channels
@ -77,7 +77,7 @@ x-i18n:
- Attach Files
- Add Reactions（可选）
这是普通文本频道的基础权限集。如果你计划在 Discord 主题帖中发帖，包括会创建或继续主题帖的论坛或媒体频道工作流，还要启用 **Send Messages in Threads**。
这是普通文本频道的基础权限集。如果你计划在 Discord 线程中发帖，包括会创建或继续线程的论坛或媒体频道工作流，还需要启用 **Send Messages in Threads**。
复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该能在 Discord 服务器中看到你的机器人。
</Step>
@ -85,23 +85,23 @@ x-i18n:
<Step title="启用开发者模式并收集你的 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。
</Step>
<Step title="允许来自服务器成员的私信">
为了让配对正常工作，Discord 需要允许你的机器人向你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。
为了让配对正常工作，Discord 需要允许你的机器人给你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。
这允许服务器成员（包括机器人）向你发送私信。如果你想在 OpenClaw 中使用 Discord 私信，请保持开启。如果你只打算使用服务器频道，则可以在配对完成后禁用私信。
这样服务器成员（包括机器人）就可以向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持此项开启。如果你只打算使用服务器频道，则可以在完成配对后关闭私信。
</Step>
<Step title="安全设置你的机器人令牌（不要在聊天中发送）">
你的 Discord 机器人令牌是一个密钥（就像密码一样）。在给你的智能体发消息之前，请先在运行 OpenClaw 的机器上设置它。
<Step title="安全设置你的机器人令牌（不要在聊天中发送它）">
你的 Discord 机器人令牌是一个秘密信息（类似密码）。在给你的智能体发消息之前，请先在运行 OpenClaw 的机器上进行设置。
```bash
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
@ -111,7 +111,7 @@ openclaw config set channels.discord.enabled true --strict-json
openclaw gateway
```
如果 OpenClaw 已经作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或者停止并重新启动 `openclaw gateway run` 进程。
如果 OpenClaw 已经作为后台服务在运行，请通过 OpenClaw Mac 应用重启它，或停止并重新启动 `openclaw gateway run` 进程。
</Step>
@ -119,9 +119,9 @@ openclaw gateway
<Tabs>
<Tab title="询问你的智能体">
在任何现有渠道（例如 Telegram）中与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置选项卡。
在任何现有渠道（例如 Telegram）上与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置标签页。
> “我已经在配置中设置了我的 Discord bot token。请使用 User ID `<user_id>` 和 Server ID `<server_id>` 完成 Discord 设置。”
> “我已经在配置中设置了 Discord 机器人令牌。请使用 User ID `<user_id>` 和 Server ID `<server_id>` 完成 Discord 设置。”
</Tab>
<Tab title="CLI / 配置">
如果你更喜欢基于文件的配置，请设置：
@ -141,7 +141,7 @@ openclaw gateway
}
```
默认账户的环境变量回退值：
默认账户的环境变量回退：
```bash
DISCORD_BOT_TOKEN=...
@ -155,13 +155,13 @@ DISCORD_BOT_TOKEN=...
</Step>
<Step title="批准首次私信配对">
等待 Gateway 网关运行后，在 Discord 中向你的机器人发送私信。它会回复一个配对码。
等待 Gateway 网关运行后，在 Discord 中给你的机器人发送私信。它会回复一个配对代码。
<Tabs>
<Tab title="询问你的智能体">
将配对码发送给你现有渠道中的智能体：
在你现有的渠道上把配对代码发送给你的智能体：
> “批准这个 Discord 配对码：`<CODE>`”
> “批准这个 Discord 配对代码：`<CODE>`”
</Tab>
<Tab title="CLI">
@ -173,29 +173,29 @@ openclaw pairing approve discord <CODE>
</Tab>
</Tabs>
配对码会在 1 小时后过期。
配对代码将在 1 小时后过期。
现在你应该可以通过 Discord 私信与你的智能体聊天了。
现在你应该已经可以通过 Discord 私信与你的智能体聊天了。
</Step>
</Steps>
<Note>
令牌解析是账户感知的。配置中的令牌值优先于环境变量回退值。`DISCORD_BOT_TOKEN` 仅用于默认账户。
对于高级出站调用（消息工具/渠道操作），显式的每次调用 `token` 会用于该次调用。这适用于发送以及读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍来自活动运行时快照中所选的账户。
令牌解析具有账户感知能力。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 只用于默认账户。
对于高级出站调用（消息工具 / 渠道操作），每次调用中显式提供的 `token` 会用于该次调用。这适用于发送以及读取 / 探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略 / 重试设置仍然来自活动运行时快照中所选的账户。
</Note>
## 推荐：设置一个服务器工作区
## 推荐：设置服务器工作区
当私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个频道都有自己的智能体会话和独立上下文。对于只有你和机器人参与的私人服务器，这种方式是推荐的。
当私信可以正常工作后，你可以将你的 Discord 服务器设置为一个完整工作区，其中每个频道都会获得自己的智能体会话和独立上下文。对于只有你和你的机器人的私人服务器，我们推荐这样做。
<Steps>
<Step title="将你的服务器添加到服务器 allowlist">
这样你的智能体就可以在服务器中的任何频道响应，而不只是私信。
<Step title="将你的服务器添加到 guild allowlist">
这样你的智能体就可以在你的服务器中的任意频道回复，而不仅仅是私信。
<Tabs>
<Tab title="询问你的智能体">
> “将我的 Discord Server ID `<server_id>` 添加到服务器 allowlist”
> “把我的 Discord Server ID `<server_id>` 添加到 guild allowlist”
</Tab>
<Tab title="配置">
@ -220,15 +220,15 @@ openclaw pairing approve discord <CODE>
</Step>
<Step title="允许无需 @mention 的回复">
默认情况下，你的智能体只有在被 @mention 时才会在服务器频道中响应。对于私人服务器，你大概会希望它响应每一条消息。
<Step title="允许在不 @ 提及的情况下回复">
默认情况下，你的智能体只会在被 @ 提及时才会在服务器频道中回复。对于私人服务器，你可能更希望它对每条消息都进行回复。
<Tabs>
<Tab title="询问你的智能体">
> “允许我的智能体在这个服务器中无需被 @mention 也能回复”
> “允许我的智能体在这个服务器中无需被 @ 提及也能回复”
</Tab>
<Tab title="配置">
在你的服务器配置中设置 `requireMention: false`：
在你的 guild 配置中设置 `requireMention: false`：
```json5
{
@ -249,7 +249,7 @@ openclaw pairing approve discord <CODE>
</Step>
<Step title="规划服务器频道中的记忆使用">
<Step title="为服务器频道中的记忆使用做好规划">
默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。服务器频道不会自动加载 MEMORY.md。
<Tabs>
@ -257,70 +257,70 @@ openclaw pairing approve discord <CODE>
> “当我在 Discord 频道中提问时，如果你需要来自 MEMORY.md 的长期上下文，请使用 memory_search 或 memory_get。”
</Tab>
<Tab title="手动">
如果你需要每个频道都共享上下文，请将稳定的指令放在 `AGENTS.md` 或 `USER.md` 中（它们会注入到每个会话）。将长期笔记保存在 `MEMORY.md` 中，并按需通过记忆工具访问。
如果你需要在每个频道中共享上下文，请将稳定指令放入 `AGENTS.md` 或 `USER.md`（它们会被注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并在需要时使用记忆工具按需访问。
</Tab>
</Tabs>
</Step>
</Steps>
现在，在你的 Discord 服务器上创建一些频道并开始聊天。你的智能体可以看到频道名称，并且每个频道都会获得自己隔离的会话——因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的频道。
现在，在你的 Discord 服务器中创建一些频道并开始聊天。你的智能体可以看到频道名称，并且每个频道都会获得各自隔离的会话——因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的频道。
## 运行时模型
- Gateway 网关拥有 Discord 连接。
- 回复路由是确定性的：从 Discord 收到的入站消息会回复回 Discord。
- 默认情况下（`session.dmScope=main`），直接聊天共享智能体主会话（`agent:main:main`）。
- 回复路由是确定性的：来自 Discord 的入站回复会返回到 Discord。
- Discord guild / channel 元数据会作为不受信任的上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果某个模型把该封装内容复制回来了，OpenClaw 会从出站回复和后续重放上下文中剥离这些复制的元数据。
- 默认情况下（`session.dmScope=main`），私聊共享智能体主会话（`agent:main:main`）。
- 服务器频道使用隔离的会话键（`agent:<agentId>:discord:channel:<channelId>`）。
- 默认忽略群组私信（`channels.discord.dm.groupEnabled=false`）。
- 原生斜杠命令在隔离的命令会话中运行（`agent:<agentId>:discord:slash:<userId>`），同时仍会将 `CommandTargetSessionKey` 传递给已路由的对话会话。
- 发送到 Discord 的纯文本 cron/heartbeat 通知默认只使用一次最终的、智能体可见的答案。
当智能体发出多个可投递负载时，媒体和结构化组件负载仍会以多条消息形式发送。
- 原生斜杠命令在隔离的命令会话中运行（`agent:<agentId>:discord:slash:<userId>`），同时仍会将 `CommandTargetSessionKey` 传递给路由后的对话会话。
- 将纯文本 cron / heartbeat 公告投递到 Discord 时，只会使用最终对智能体可见的答案发送一次。若智能体发出了多个可投递载荷，媒体和结构化组件载荷仍会以多消息形式发送。
## 论坛频道
Discord 论坛和媒体频道只接受主题帖。OpenClaw 支持两种创建方式：
Discord 论坛和媒体频道只接受线程帖子。OpenClaw 支持两种创建方式：
- 向论坛父频道（`channel:<forumId>`）发送消息以自动创建主题帖。主题标题会使用你消息中的第一行非空文本。
- 使用 `openclaw message thread create` 直接创建主题帖。不要为论坛频道传递 `--message-id`。
- 向论坛父频道（`channel:<forumId>`）发送消息以自动创建线程。线程标题会使用你消息中的第一行非空内容。
- 使用 `openclaw message thread create` 直接创建线程。对于论坛频道，不要传递 `--message-id`。
示例：发送到论坛父频道以创建主题帖
示例：发送到论坛父频道以创建线程
```bash
openclaw message send --channel discord --target channel:<forumId> \
--message "Topic title\nBody of the post"
```
示例：显式创建论坛主题帖
示例：显式创建论坛线程
```bash
openclaw message thread create --channel discord --target channel:<forumId> \
--thread-name "Topic title" --message "Body of the post"
```
论坛父频道不接受 Discord 组件。如果你需要组件，请发送到主题帖本身（`channel:<threadId>`）。
论坛父频道不接受 Discord 组件。如果你需要组件，请发送到线程本身（`channel:<threadId>`）。
## 交互式组件
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.reusable=true` 可允许按钮、选择器和表单在过期之前被多次使用。
若要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。
要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。
`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及一个提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是通过聊天注册模型。选择器回复是临时的，且只有调用它的用户可以使用。
`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及一个提交步骤。`/models add` 已弃用，现在会返回弃用提示消息，而不是通过聊天注册模型。选择器回复是临时可见的，且只有调用它的用户可以使用。
文件附件：
- `file` 块必须指向一个附件引用（`attachment://<filename>`）
- 通过 `media`/`path`/`filePath` 提供附件（单个文件）；多个文件请使用 `media-gallery`
- 当上传名称应与附件引用匹配时，使用 `filename` 覆盖上传名称
- `file` 区块必须指向一个附件引用（`attachment://<filename>`）
- 通过 `media` / `path` / `filePath` 提供附件（单个文件）；多个文件请使用 `media-gallery`
- 当上传名称需要与附件引用匹配时，使用 `filename` 覆盖上传名称
模态表单：
@ -386,27 +386,27 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
<Tabs>
<Tab title="私信策略">
`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`。
- 命名账户不会继承 `channels.discord.accounts.default.allowFrom`。
- 已命名账户在其自身 `allowFrom` 未设置时，会继承 `channels.discord.allowFrom`。
- 已命名账户不会继承 `channels.discord.accounts.default.allowFrom`。
用于投递的私信目标格式：
- `user:<id>`
- `<@id>` mention
- `<@id>` 提及
纯数字 ID 有歧义，除非提供了显式的用户/频道目标类型，否则会被拒绝。
裸数字 ID 存在歧义，除非显式提供用户 / 频道目标类型，否则会被拒绝。
</Tab>
@ -417,16 +417,16 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
- `allowlist`
- `disabled`
当存在 `channels.discord` 时，安全的基线值是 `allowlist`。
当存在 `channels.discord` 时，安全基线为 `allowlist`。
`allowlist` 行为：
- 服务器必须匹配 `channels.discord.guilds`（优先使用 `id`，也接受 slug）
- 可选的发送者 allowlist：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了其中任一项，则当发送者匹配 `users` 或 `roles` 时允许发送
- 直接名称/标签匹配默认禁用；仅在紧急兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true`
- `users` 支持名称/标签，但 ID 更安全；当使用名称/标签条目时，`openclaw security audit` 会发出警告
- 可选发送者 allowlist：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了任一项，则当发送者匹配 `users` 或 `roles` 时被允许
- 默认禁用直接名称 / 标签匹配；仅在紧急兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true`
- `users` 支持名称 / 标签，但 ID 更安全；使用名称 / 标签条目时，`openclaw security audit` 会发出警告
- 如果某个服务器配置了 `channels`，则未列出的频道会被拒绝
- 如果某个服务器没有 `channels` 块，则该 allowlist 服务器中的所有频道都允许
- 如果某个服务器没有 `channels` 区块，则该 allowlist 服务器中的所有频道都被允许
示例：
@ -452,21 +452,21 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
}
```
如果你只设置了 `DISCORD_BOT_TOKEN` 而未创建 `channels.discord` 块，则运行时回退值为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open` 也是如此。
如果你只设置了 `DISCORD_BOT_TOKEN` 而没有创建 `channels.discord` 区块，则运行时回退为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open` 也是如此。
</Tab>
<Tab title="提及和群组私信">
默认情况下，服务器消息受 mention 限制。
默认情况下，服务器消息受提及限制。
mention 检测包括：
提及检测包括：
- 显式提及机器人
- 已配置的 mention 模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`）
- 在受支持场景中的隐式回复机器人行为
- 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`）
- 在支持场景下的隐式回复机器人行为
`requireMention` 按服务器/频道配置（`channels.discord.guilds...`）。
`ignoreOtherMentions` 可选地丢弃提及了其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。
`requireMention` 按服务器 / 频道配置（`channels.discord.guilds...`）。
`ignoreOtherMentions` 可选丢弃提及了其他用户 / 角色但未提及机器人的消息（不包括 @everyone / @here）。
群组私信：
@ -478,7 +478,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
### 基于角色的智能体路由
使用 `bindings[].match.roles` 可按角色 ID 将 Discord 服务器成员路由到不同的智能体。基于角色的绑定仅接受角色 ID，并且会在 peer 或 parent-peer 绑定之后、仅服务器绑定之前进行评估。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。
使用 `bindings[].match.roles` 可根据角色 ID 将 Discord 服务器成员路由到不同的智能体。基于角色的绑定仅接受角色 ID，并在 peer 或 parent-peer 绑定之后、仅服务器绑定之前进行评估。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。
```json5
{
@ -504,13 +504,13 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
## 原生命令和命令鉴权
- `commands.native` 默认为 `"auto"`，并且在 Discord 上启用。
- `commands.native` 默认为 `"auto"`，并且对 Discord 已启用。
- 按渠道覆盖：`channels.discord.commands.native`。
- `commands.native=false` 会显式清除先前已注册的 Discord 原生命令。
- 原生命令鉴权使用与普通消息处理相同的 Discord allowlist/策略。
- 即使用户未获授权，命令仍可能在 Discord UI 中可见；执行时仍会强制 OpenClaw 鉴权，并返回“未授权”。
- 原生命令鉴权使用与普通消息处理相同的 Discord allowlist / 策略。
- 即使未授权用户仍可能在 Discord UI 中看到命令，执行时仍会强制执行 OpenClaw 鉴权，并返回“未授权”。
命令目录和行为请参见[斜杠命令](/zh-CN/tools/slash-commands)。
有关命令目录和行为，请参见 [Slash commands](/zh-CN/tools/slash-commands)。
默认斜杠命令设置：
@ -532,18 +532,18 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
- `all`
- `batched`
注意：`off` 会禁用隐式回复线程。显式的 `[[reply_to_*]]` 标签仍然有效。
`first` 总是将隐式原生回复引用附加到该轮的第一条发往 Discord 的出站消息。
`batched` 仅在入站轮次是多个消息的去抖批处理时，才附加 Discord 的隐式原生回复引用。当你只想在含糊的高频聊天场景中主要使用原生回复，而不是每个单消息轮次都使用时，这很有帮助。
注意：`off` 会禁用隐式回复线程。显式的 `[[reply_to_*]]` 标签仍会被遵循。
`first` 总是将隐式原生回复引用附加到本轮的第一条出站 Discord 消息。
`batched` 仅在入站轮次是多个消息的去抖批处理时，才附加 Discord 的隐式原生回复引用。当你主要希望在含糊不清的突发聊天中使用原生回复，而不是每个单消息轮次都使用时，这很有用。
消息 ID 会在上下文/历史中显示，以便智能体定位特定消息。
消息 ID 会在上下文 / 历史中呈现，以便智能体可以定位特定消息。
</Accordion>
<Accordion title="实时流式预览">
OpenClaw 可以通过发送一条临时消息并在文本到达时对其进行编辑，来流式显示草稿回复。`channels.discord.streaming` 接受 `off`（默认）| `partial` | `block` | `progress`。`progress` 在 Discord 上会映射为 `partial`；`streamMode` 是旧版别名，会被自动迁移。
OpenClaw 可以通过发送临时消息并在文本到达时编辑它来流式传输草稿回复。`channels.discord.streaming` 取值为 `off`（默认）| `partial` | `block` | `progress`。在 Discord 上，`progress` 会映射到 `partial`；`streamMode` 是旧版别名，会被自动迁移。
默认值保持为 `off`，因为当多个机器人或 Gateway 网关共享一个账户时，Discord 预览编辑很容易触发速率限制。
默认保持为 `off`，因为当多个机器人或 Gateway 网关共享同一账户时，Discord 预览编辑很容易触发速率限制。
```json5
{
@ -560,20 +560,20 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
}
```
- `partial` 会在 token 到达时编辑单条预览消息。
- `block` 会输出草稿大小的分块（使用 `draftChunk` 调整大小和断点，并限制在 `textChunkLimit` 内）。
- `partial` 会在 token 到达时编辑一条预览消息。
- `block` 会输出草稿大小的分块（使用 `draftChunk` 调整大小和断点，并限制在 `textChunkLimit` 范围内）。
- 媒体、错误和显式回复的最终消息会取消待处理的预览编辑。
- `streaming.preview.toolProgress`（默认 `true`）控制工具/进度更新是否复用预览消息。
- `streaming.preview.toolProgress`（默认 `true`）控制工具 / 进度更新是否复用预览消息。
预览流式传输仅支持文本；媒体回复会回退到普通投递。当显式启用 `block` 分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
预览流式传输仅支持文本；媒体回复会回退为普通投递。当显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
</Accordion>
<Accordion title="历史、上下文和主题帖行为">
<Accordion title="历史、上下文和线程行为">
服务器历史上下文：
- `channels.discord.historyLimit` 默认值为 `20`
- 回退值：`messages.groupChat.historyLimit`
- `channels.discord.historyLimit` 默认 `20`
- 回退：`messages.groupChat.historyLimit`
- `0` 表示禁用
私信历史控制：
@ -581,27 +581,27 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
- `channels.discord.dmHistoryLimit`
- `channels.discord.dms["<user_id>"].historyLimit`
主题帖行为：
线程行为：
- Discord 主题帖按频道会话进行路由，并继承父频道配置，除非被覆盖。
- `channels.discord.thread.inheritParent`（默认 `false`）可让新自动主题帖选择从父级对话记录中播种。按账户覆盖位于 `channels.discord.accounts.<id>.thread.inheritParent`。
- 消息工具的 reactions 可以解析 `user:<id>` 私信目标。
- Discord 线程会作为频道会话进行路由，并继承父频道配置，除非被覆盖。
- `channels.discord.thread.inheritParent`（默认 `false`）可选择让新自动线程从父级转录中播种。按账户覆盖位于 `channels.discord.accounts.<id>.thread.inheritParent`。
- 消息工具反应可以解析 `user:<id>` 私信目标。
- `guilds.<guild>.channels.<channel>.requireMention: false` 会在回复阶段激活回退期间保留。
频道主题会作为**不受信任的**上下文注入。allowlist 只控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
频道主题会作为**不受信任**的上下文注入。allowlist 控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
</Accordion>
<Accordion title="子智能体的线程绑定会话">
Discord 可以将一个主题帖绑定到某个会话目标，这样该主题帖中的后续消息会持续路由到同一个会话（包括子智能体会话）。
Discord 可以将一个线程绑定到某个会话目标，这样该线程中的后续消息会持续路由到同一会话（包括子智能体会话）。
命令：
- `/focus <target>` 将当前/新主题帖绑定到某个子智能体/会话目标
- `/unfocus` 移除当前主题帖绑定
- `/agents` 显示活跃运行和绑定状态
- `/session idle <duration|off>` 查看/更新聚焦绑定的不活动自动取消聚焦设置
- `/session max-age <duration|off>` 查看/更新聚焦绑定的硬性最长存活时间
- `/focus <target>` 将当前 / 新线程绑定到某个子智能体 / 会话目标
- `/unfocus` 移除当前线程绑定
- `/agents` 显示活动运行和绑定状态
- `/session idle <duration|off>` 检查 / 更新已聚焦绑定的空闲自动取消聚焦
- `/session max-age <duration|off>` 检查 / 更新已聚焦绑定的硬性最大存续时间
配置：
@ -620,7 +620,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
enabled: true,
idleHours: 24,
maxAgeHours: 0,
spawnSubagentSessions: false, // opt-in
spawnSubagentSessions: false, // 选择启用
},
},
},
@ -631,20 +631,20 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
- `session.threadBindings.*` 设置全局默认值。
- `channels.discord.threadBindings.*` 覆盖 Discord 行为。
- `spawnSubagentSessions` 必须为 true，才能为 `sessions_spawn({ thread: true })` 自动创建/绑定主题帖。
- `spawnAcpSessions` 必须为 true，才能为 ACP 自动创建/绑定主题帖（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）。
- 如果某个账户禁用了线程绑定，`/focus` 和相关线程绑定操作将不可用。
- `spawnSubagentSessions` 必须为 true，才能为 `sessions_spawn({ thread: true })` 自动创建 / 绑定线程。
- `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)。
请参见 [Sub-agents](/zh-CN/tools/subagents)、[ACP Agents](/zh-CN/tools/acp-agents) 和 [Configuration Reference](/zh-CN/gateway/configuration-reference)。
</Accordion>
<Accordion title="持久化 ACP 渠道绑定">
对于稳定的“始终在线” ACP 工作区，可配置顶层类型化 ACP 绑定，使其指向 Discord 对话。
<Accordion title="持久化 ACP 频道绑定">
对于稳定的“始终在线” ACP 工作区，可配置以 Discord 对话为目标的顶层类型化 ACP 绑定。
配置路径：
- `bindings[]`，其中 `type: "acp"` 且 `match.channel: "discord"`
- `bindings[]`，并设置 `type: "acp"` 和 `match.channel: "discord"`
示例：
@ -696,23 +696,23 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
说明：
- `/acp spawn codex --bind here` 会就地绑定当前频道或主题帖，并让后续消息持续使用同一个 ACP 会话。主题帖消息会继承父频道绑定。
- 在已绑定的频道或主题帖中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时线程绑定在激活期间可以覆盖目标解析。
- 仅当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子主题帖时，才需要 `spawnAcpSessions`。
- `/acp spawn codex --bind here` 会就地绑定当前频道或线程，并让后续消息持续停留在同一个 ACP 会话上。线程消息会继承父频道绑定。
- 在已绑定的频道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时线程绑定在激活期间可以覆盖目标解析。
- 只有当 OpenClaw 需要通过 `--thread auto|here` 创建 / 绑定子线程时，才需要 `spawnAcpSessions`。
有关绑定行为的详细信息，请参见 [ACP Agents](/zh-CN/tools/acp-agents)。
有关绑定行为详情，请参见 [ACP Agents](/zh-CN/tools/acp-agents)。
</Accordion>
<Accordion title="反应通知">
按服务器配置的反应通知模式：
按服务器设置的反应通知模式：
- `off`
- `own`（默认）
- `all`
- `allowlist`（使用 `guilds.<id>.users`）
反应事件会转换为系统事件，并附加到已路由的 Discord 会话中。
反应事件会被转换为系统事件，并附加到已路由的 Discord 会话中。
</Accordion>
@ -724,7 +724,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
- `channels.discord.accounts.<accountId>.ackReaction`
- `channels.discord.ackReaction`
- `messages.ackReaction`
- 智能体身份 emoji 回退值（`agents.list[].identity.emoji`，否则为 “👀”）
- 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 “👀”）
说明：
@ -734,11 +734,11 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
</Accordion>
<Accordion title="配置写入">
默认启用由渠道发起的配置写入。
默认启用从渠道发起的配置写入。
这会影响 `/config set|unset` 流程（在启用命令功能时）。
这会影响 `/config set|unset` 流程（当命令功能启用时）。
禁用方式：
禁用：
```json5
{
@ -753,7 +753,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
</Accordion>
<Accordion title="Gateway 网关代理">
使用 `channels.discord.proxy` 通过 HTTP(S) 代理来路由 Discord Gateway 网关 WebSocket 流量和启动 REST 查找（应用 ID + allowlist 解析）。
使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord Gateway 网关 WebSocket 流量和启动 REST 查询（应用 ID + allowlist 解析）。
```json5
{
@ -792,7 +792,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
discord: {
pluralkit: {
enabled: true,
token: "pk_live_...", // optional; needed for private systems
token: "pk_live_...", // 可选；私有系统需要
},
},
},
@ -802,14 +802,14 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
说明：
- allowlist 可以使用 `pk:<memberId>`
- 只有在 `channels.discord.dangerouslyAllowNameMatching: true` 时，成员显示名称才会按名称/slug 匹配
- 查找使用原始消息 ID，并受时间窗口限制
- 如果查找失败，代理消息会被视为机器人消息并丢弃，除非 `allowBots=true`
- 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，成员显示名称才会按名称 / slug 匹配
- 查询使用原始消息 ID，并受时间窗口限制
- 如果查询失败，代理消息会被视为机器人消息并被丢弃，除非 `allowBots=true`
</Accordion>
<Accordion title="在线状态配置">
当你设置状态或活动字段，或启用自动在线状态时，将应用在线状态更新。
当你设置状态或活动字段，或启用自动在线状态时，会应用在线状态更新。
仅状态示例：
@ -842,7 +842,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
{
channels: {
discord: {
activity: "直播编程",
activity: "实时编程",
activityType: 1,
activityUrl: "https://twitch.tv/openclaw",
},
@ -856,7 +856,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
- 1：Streaming（需要 `activityUrl`）
- 2：Listening
- 3：Watching
- 4：Custom（使用活动文本作为状态文本；emoji 可选）
- 4：Custom（使用活动文本作为状态内容；emoji 可选）
- 5：Competing
自动在线状态示例（运行时健康信号）：
@ -876,7 +876,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
}
```
自动在线状态会将运行时可用性映射为 Discord 状态：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖项：
自动在线状态会将运行时可用性映射为 Discord 状态：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖：
- `autoPresence.healthyText`
- `autoPresence.degradedText`
@ -885,7 +885,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
</Accordion>
<Accordion title="Discord 中的审批">
Discord 支持在私信中通过按钮处理审批，并可选择在发起来源频道中发布审批提示。
Discord 支持在私信中使用基于按钮的审批处理，并且可以选择在源频道中发布审批提示。
配置路径：
@ -894,50 +894,50 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带
- `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`）
- `agentFilter`、`sessionFilter`、`cleanupAfterResolve`
当 `enabled` 未设置或为 `"auto"`，且至少可解析出一个 approver（来自 `execApprovals.approvers` 或 `commands.ownerAllowFrom`）时，Discord 会自动启用原生 exec 审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec approver。若要显式禁用 Discord 作为原生审批客户端，请设置 `enabled: false`。
当 `enabled` 未设置或为 `"auto"`，且至少可以从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个审批人时，Discord 会自动启用原生 exec 审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec 审批人。设置 `enabled: false` 可显式禁用 Discord 作为原生审批客户端。
当 `target` 为 `channel` 或 `both` 时，审批提示会显示在频道中。只有已解析的 approver 可以使用这些按钮；其他用户会收到临时拒绝消息。审批提示包含命令文本，因此仅应在受信任频道中启用频道投递。如果无法从会话键中推导出频道 ID，OpenClaw 会回退到私信投递。
当 `target` 为 `channel` 或 `both` 时，审批提示会显示在频道中。只有已解析的审批人可以使用这些按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此只应在受信任的频道中启用频道投递。如果无法从会话键推导出频道 ID，OpenClaw 会回退为私信投递。
Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要增加了 approver 私信路由和频道扇出。
当这些按钮存在时，它们是主要的审批 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)。
</Accordion>
</AccordionGroup>
## 工具和操作门控
Discord 消息操作包括消息发送、频道管理、审核、在线状态和元数据操作。
Discord 消息操作包括消息处理、频道管理、内容审核、在线状态和元数据操作。
核心示例：
- 消息：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply`
- 消息处理：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply`
- 反应：`react`、`reactions`、`emojiList`
- 审核：`timeout`、`kick`、`ban`
- 内容审核：`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 消息操作也可以接受用于自定义 UI 的 `components`（高级用法；需要通过 discord 工具构造组件负载），而旧版 `embeds` 仍可使用，但不推荐。
OpenClaw 对 exec 审批和跨上下文标记使用 Discord components v2。Discord 消息操作也可以接受用于自定义 UI 的 `components`（高级用法；需要通过 discord 工具构造组件载荷），而旧版 `embeds` 仍然可用，但不推荐。
- `channels.discord.ui.components.accentColor` 设置 Discord 组件容器使用的强调色（十六进制）。
- 可通过 `channels.discord.accounts.<id>.ui.components.accentColor` 按账户设置。
- 可按账户通过 `channels.discord.accounts.<id>.ui.components.accentColor` 设置。
- 当存在 components v2 时，`embeds` 会被忽略。
示例：
@ -958,15 +958,15 @@ OpenClaw 对 exec 审批和跨上下文标记使用 Discord components v2。Disc
## 语音
Discord 有两种不同的语音界面：实时**语音频道**（持续对话）和**语音消息附件**（波形预览格式）。Gateway 网关同时支持这两种方式。
Discord 有两种不同的语音界面：实时**语音频道**（连续对话）和**语音消息附件**（波形预览格式）。Gateway 网关同时支持两者。
### 语音频道
设置检查清单：
1. 在 Discord Developer Portal 中启用 Message Content Intent。
2. 当使用角色/用户 allowlist 时，启用 Server Members Intent。
3. 使用 `bot` 和 `applications.commands` scopes 邀请机器人。
2. 当使用角色 / 用户 allowlist 时，启用 Server Members Intent。
3. 使用 `bot` 和 `applications.commands` 范围邀请机器人。
4. 在目标语音频道中授予 Connect、Speak、Send Messages 和 Read Message History 权限。
5. 启用原生命令（`commands.native` 或 `channels.discord.commands.native`）。
6. 配置 `channels.discord.voice`。
@ -1009,32 +1009,32 @@ Discord 有两种不同的语音界面：实时**语音频道**（持续对话
说明：
- `voice.tts` 仅对语音播放覆盖 `messages.tts`。
- `voice.model` 仅覆盖用于 Discord 语音频道回复的 LLM。留空则继承已路由智能体的模型。
- `voice.model` 仅覆盖 Discord 语音频道响应所使用的 LLM。不设置时会继承已路由智能体模型。
- STT 使用 `tools.media.audio`；`voice.model` 不影响转录。
- 语音转录轮次会从 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者说话者无法访问仅限所有者的工具（例如 `gateway` 和 `cron`）。
- 语音默认启用；设置 `channels.discord.voice.enabled=false` 可将其禁用。
- 语音转录轮次会根据 Discord `allowFrom`（或 `dm.allowFrom`）推导所有者状态；非所有者发言者无法访问仅限所有者的工具（例如 `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 PR #11449 的上游 padding 修复，该修复关闭了 discord.js issue #11419。
- 如果未设置，`@discordjs/voice` 默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。
- OpenClaw 还会监视接收解密失败，并在短时间内重复失败后通过离开 / 重新加入语音频道自动恢复。
- 如果更新后接收日志持续显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 版本线包含了 discord.js PR #11449 的上游填充修复，该修复关闭了 discord.js issue #11419。
语音频道处理流水线：
语音频道流水线：
- Discord PCM 捕获会转换为一个 WAV 临时文件。
- Discord PCM 捕获会转换为一个临时 WAV 文件。
- `tools.media.audio` 负责 STT，例如 `openai/gpt-4o-mini-transcribe`。
- 转录文本会通过普通 Discord 入站和路由流程发送。
- 设置后，`voice.model` 仅覆盖该语音频道轮次的响应 LLM。
- `voice.tts` 会叠加到 `messages.tts` 之上；生成的音频会在已加入的频道中播放。
- 转录文本会通过普通的 Discord 入站和路由流程发送。
- 设置后，`voice.model` 仅覆盖这一轮语音频道的响应 LLM。
- `voice.tts` 会合并到 `messages.tts` 之上；生成的音频会在已加入的频道中播放。
凭证按组件分别解析：`voice.model` 使用 LLM 路由鉴权，`tools.media.audio` 使用 STT 鉴权，`messages.tts`/`voice.tts` 使用 TTS 鉴权。
凭证按组件分别解析：`voice.model` 使用 LLM 路由鉴权，`tools.media.audio` 使用 STT 鉴权，`messages.tts` / `voice.tts` 使用 TTS 鉴权。
### 语音消息
Discord 语音消息会显示波形预览，并要求使用 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要在 Gateway 网关主机上安装 `ffmpeg` 和 `ffprobe` 以进行检查和转换。
Discord 语音消息会显示波形预览，并且要求使用 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要在 Gateway 网关主机上安装 `ffmpeg` 和 `ffprobe` 才能进行检测和转换。
- 提供一个**本地文件路径**（不接受 URL）。
- 省略文本内容（Discord 会拒绝同时包含文本和语音消息的负载）。
- 接受任意音频格式；OpenClaw 会在需要时将其转换为 OGG/Opus。
- 提供**本地文件路径**（不接受 URL）。
- 省略文本内容（Discord 会拒绝同一载荷中的文本 + 语音消息）。
- 接受任意音频格式；OpenClaw 会在需要时转换为 OGG/Opus。
```bash
message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)
@ -1043,20 +1043,20 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a
## 故障排除
<AccordionGroup>
<Accordion title="使用了不允许的 intents，或机器人看不到任何服务器消息">
<Accordion title="使用了不允许的 intents，或机器人看不到服务器消息">
- 启用 Message Content Intent
- 当你依赖用户/成员解析时，启用 Server Members Intent
- 当你依赖用户 / 成员解析时，启用 Server Members Intent
- 更改 intents 后重启 Gateway 网关
</Accordion>
<Accordion title="服务器消息被意外阻止">
- 检查 `groupPolicy`
- 检查 `channels.discord.guilds` 下的服务器 allowlist
- 验证 `groupPolicy`
- 验证 `channels.discord.guilds` 下的服务器 allowlist
- 如果存在服务器 `channels` 映射，则只允许列出的频道
- 检查 `requireMention` 行为和 mention 模式
- 验证 `requireMention` 行为和提及模式
有用的检查命令：
@ -1068,16 +1068,16 @@ openclaw logs --follow
</Accordion>
<Accordion title="已将 require mention 设为 false，但仍被阻止">
<Accordion title="requireMention 为 false 但仍然被阻止">
常见原因：
- `groupPolicy="allowlist"`，但没有匹配的服务器/频道 allowlist
- `groupPolicy="allowlist"`，但没有匹配的服务器 / 频道 allowlist
- `requireMention` 配置在错误位置（必须位于 `channels.discord.guilds` 或频道条目下）
- 发送者被服务器/频道 `users` allowlist 阻止
- 发送者被服务器 / 频道 `users` allowlist 阻止
</Accordion>
<Accordion title="长时间运行的处理器超时或出现重复回复">
<Accordion title="长时间运行的处理程序超时或出现重复回复">
典型日志：
@ -1085,16 +1085,16 @@ openclaw logs --follow
- `Slow listener detected ...`
- `discord inbound worker timed out after ...`
监听器预算调节项：
监听器预算旋钮：
- 单账户：`channels.discord.eventQueue.listenerTimeout`
- 多账户：`channels.discord.accounts.<accountId>.eventQueue.listenerTimeout`
Worker 运行超时调节项：
Worker 运行超时旋钮：
- 单账户：`channels.discord.inboundWorker.runTimeoutMs`
- 多账户：`channels.discord.accounts.<accountId>.inboundWorker.runTimeoutMs`
- 默认值：`1800000`（30 分钟）；设置为 `0` 表示禁用
- 默认：`1800000`（30 分钟）；设置为 `0` 可禁用
推荐基线：
@ -1117,14 +1117,14 @@ openclaw logs --follow
}
```
对于较慢的监听器设置，请使用 `eventQueue.listenerTimeout`；仅当你希望为排队的智能体轮次设置单独的安全阀时，才使用 `inboundWorker.runTimeoutMs`。
对于较慢的监听器设置，请使用 `eventQueue.listenerTimeout`；仅当你想为排队的智能体轮次设置单独的安全阀时，才使用 `inboundWorker.runTimeoutMs`。
</Accordion>
<Accordion title="权限审计不匹配">
`channels status --probe` 的权限检查仅适用于数字频道 ID。
`channels status --probe` 权限检查仅适用于数字频道 ID。
如果你使用 slug 键，运行时匹配仍然可能有效，但 probe 无法完整验证权限。
如果你使用 slug 键，运行时匹配仍然可能有效，但探测无法完整验证权限。
</Accordion>
@ -1136,42 +1136,42 @@ openclaw logs --follow
</Accordion>
<Accordion title="机器人到机器人的循环">
默认情况下会忽略由机器人发送的消息。
<Accordion title="机器人到机器人循环">
默认情况下，会忽略由机器人发送的消息。
如果你设置了 `channels.discord.allowBots=true`，请使用严格的 mention 和 allowlist 规则以避免循环行为。
更推荐使用 `channels.discord.allowBots="mentions"`，只接受提及该机器人的机器人消息。
如果你设置了 `channels.discord.allowBots=true`，请使用严格的提及和 allowlist 规则来避免循环行为。
优先使用 `channels.discord.allowBots="mentions"`，以便只接受提及该机器人的机器人消息。
</Accordion>
<Accordion title="语音 STT 因 DecryptionFailed(...) 而丢失">
<Accordion title="语音 STT 因 DecryptionFailed(...) 丢失">
- 保持 OpenClaw 为最新版本（`openclaw update`），以确保包含 Discord 语音接收恢复逻辑
- 确认 `channels.discord.voice.daveEncryption=true`（默认值）
- 从 `channels.discord.voice.decryptionFailureTolerance=24`（上游默认值）开始，仅在必要时再调优
- 确认 `channels.discord.voice.daveEncryption=true`（默认）
- 从 `channels.discord.voice.decryptionFailureTolerance=24`（上游默认值）开始，仅在需要时调整
- 观察日志中是否出现：
- `discord voice: DAVE decrypt failures detected`
- `discord voice: repeated decrypt failures; attempting rejoin`
- 如果自动重新加入后仍然失败，请收集日志，并与上游 DAVE 接收历史进行对比：[discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) 和 [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449)
- 如果自动重新加入后故障仍持续，请收集日志，并与上游 DAVE 接收历史进行对比：[discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) 和 [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449)
</Accordion>
</AccordionGroup>
## 配置参考
主要参考文档：[配置参考 - Discord](/zh-CN/gateway/config-channels#discord)。
主要参考： [Configuration reference - Discord](/zh-CN/gateway/config-channels#discord)。
<Accordion title="高信号 Discord 字段">
- 启动/鉴权：`enabled`、`token`、`accounts.*`、`allowBots`
- 启动 / 鉴权：`enabled`、`token`、`accounts.*`、`allowBots`
- 策略：`groupPolicy`、`dm.*`、`guilds.*`、`guilds.*.channels.*`
- 命令：`commands.native`、`commands.useAccessGroups`、`configWrites`、`slashCommand.*`
- 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency`
- 入站 worker：`inboundWorker.runTimeoutMs`
- 回复/历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
- 回复 / 历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
- 投递：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage`
- 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`、`draftChunk`、`block streaming`、`blockStreamingCoalesce`
- 媒体/重试：`mediaMaxMb`（限制发往 Discord 的上传，默认 `100MB`）、`retry`
- 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`、`draftChunk`、分块流式传输、`blockStreamingCoalesce`
- 媒体 / 重试：`mediaMaxMb`（限制出站 Discord 上传，默认 `100MB`）、`retry`
- 操作：`actions.*`
- 在线状态：`activity`、`status`、`activityType`、`activityUrl`
- UI：`ui.components.accentColor`
@ -1181,15 +1181,15 @@ openclaw logs --follow
## 安全和运维
- 将机器人令牌视为密钥（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。
- 将机器人令牌视为秘密信息（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。
- 授予最小权限的 Discord 权限。
- 如果命令部署/状态已过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。
- 如果命令部署 / 状态已过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。
## 相关内容
<CardGroup cols={2}>
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
将 Discord 用户与网关配对。
将 Discord 用户与 Gateway 网关配对。
</Card>
<Card title="群组" icon="users" href="/zh-CN/channels/groups">
群聊和 allowlist 行为。

118
docs/zh-CN/cli/infer.md
View File

@ -2,20 +2,20 @@
read_when:
- 添加或修改 `openclaw infer` 命令
- 设计稳定的无头能力自动化
summary: 面向 provider 支持的模型、图像、音频、TTS、视频、网页和嵌入工作流的 infer-first CLI
summary: 面向由提供商支持的模型、图像、音频、TTS、视频、Web 和嵌入工作流的推理优先 CLI
title: 推理 CLI
x-i18n:
generated_at: "2026-04-25T19:34:26Z"
generated_at: "2026-04-26T03:26:37Z"
model: gpt-5.4
provider: openai
source_hash: bd5b98b70fd959cdcdf80131cebf99cb7131b220c5757acb380ce405b85998a1
source_hash: bf07b306d80535b58d811aa33c0bbe2ecac57b22c3ab27f6f2ae6518ceb21e49
source_path: cli/infer.md
workflow: 15
---
`openclaw infer` 是 provider 支持的推理工作流的规范无头入口。
`openclaw infer` 是面向由提供商支持的推理工作流的规范无头入口。
它有意暴露的是能力家族，而不是原始 Gateway 网关 RPC 名称，也不是原始智能体工具 id。
它有意公开的是能力族，而不是原始 Gateway 网关 RPC 名称，也不是原始智能体工具 id。
## 将 infer 变成一个 Skills
@ -26,14 +26,14 @@ Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my comm
Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings.
```
一个好的基于 infer 的 Skills 应该：
一个优秀的基于 infer 的 Skills 应该：
- 将常见用户意图映射到正确的 infer 子命令
- 包含它所覆盖工作流的一些规范 infer 示例
- 包含其所覆盖工作流的几个规范 infer 示例
- 在示例和建议中优先使用 `openclaw infer ...`
- 避免在 Skills 正文中重新记录整个 infer 入口
- 避免在 Skills 正文中重新记录整个 infer 功能面
典型的 infer 聚焦型 Skills 覆盖范围：
典型的 infer 导向 Skills 覆盖范围：
- `openclaw infer model run`
- `openclaw infer image generate`
@ -44,20 +44,17 @@ Focus on model runs, image generation, video generation, audio transcription, TT
## 为什么使用 infer
`openclaw infer` 为 OpenClaw 中由 provider 支持的推理任务提供了一个统一的 CLI。
`openclaw infer` 为 OpenClaw 内由提供商支持的推理任务提供了一个统一的 CLI。
优势：
- 使用 OpenClaw 中已经配置好的 providers 和模型，而不是为每个后端单独接入一次性封装。
- 将模型、图像、音频转写、TTS、视频、网页和嵌入工作流统一到同一棵命令树下。
- 为脚本、自动化和智能体驱动工作流使用稳定的 `--json` 输出结构。
- 使用已在 OpenClaw 中配置好的提供商和模型，而不是为每个后端单独接入一次性包装器。
- 将模型、图像、音频转录、TTS、视频、Web 和嵌入工作流统一放在同一棵命令树下。
- 为脚本、自动化和智能体驱动的工作流提供稳定的 `--json` 输出结构。
- 当任务本质上是“运行推理”时，优先使用 OpenClaw 的第一方入口。
- 对于大多数 infer 命令，使用常规本地路径而不需要 Gateway 网关。
- 对大多数 infer 命令，使用常规本地路径而不需要运行 Gateway 网关。
对于端到端的 provider 检查，在更底层的
provider 测试通过后，优先使用 `openclaw infer ...`。它会在发出 provider 请求之前，覆盖已发布的 CLI、配置加载、
默认智能体解析、内置插件激活、运行时依赖修复
以及共享能力运行时。
对于端到端提供商检查，在底层提供商测试通过后，优先使用 `openclaw infer ...`。它会在发起提供商请求之前，覆盖已发布的 CLI、配置加载、默认智能体解析、内置插件激活、运行时依赖修复以及共享能力运行时。
## 命令树
@ -117,31 +114,31 @@ provider 测试通过后，优先使用 `openclaw infer ...`。它会在发出 p
| 任务 | 命令 | 说明 |
| ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
| 运行文本/模型提示词 | `openclaw infer model run --prompt "..." --json` | 默认使用常规本地路径 |
| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 从现有文件开始时，使用 `image edit` |
| 描述图像文件 | `openclaw infer image describe --file ./image.png --json` | `--model` 必须是图像能力的 `<provider/model>` |
| 转写音频 | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` 必须是 `<provider/model>` |
| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 从现有文件开始时使用 `image edit` |
| 描述图像文件 | `openclaw infer image describe --file ./image.png --json` | `--model` 必须是支持图像的 `<provider/model>` |
| 转录音频 | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` 必须是 `<provider/model>` |
| 合成语音 | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` 面向 Gateway 网关 |
| 生成视频 | `openclaw infer video generate --prompt "..." --json` | 支持 `--resolution` 等 provider 提示参数 |
| 生成视频 | `openclaw infer video generate --prompt "..." --json` | 支持如 `--resolution` 之类的提供商提示参数 |
| 描述视频文件 | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` 必须是 `<provider/model>` |
| 搜索网页 | `openclaw infer web search --query "..." --json` | |
| 搜索 Web | `openclaw infer web search --query "..." --json` | |
| 抓取网页 | `openclaw infer web fetch --url https://example.com --json` | |
| 创建嵌入 | `openclaw infer embedding create --text "..." --json` | |
## 行为
- `openclaw infer ...` 是这些工作流的主要 CLI 入口。
- 当输出将被其他命令或脚本消费时，使用 `--json`。
- 当输出会被其他命令或脚本消费时，使用 `--json`。
- 当需要特定后端时，使用 `--provider` 或 `--model provider/model`。
- 对于 `image describe`、`audio transcribe` 和 `video describe`，`--model` 必须使用 `<provider/model>` 形式。
- 对于 `image describe`，显式提供 `--model` 会直接运行该 provider/model。该模型必须在模型目录或 provider 配置中具备图像能力。`codex/<model>` 会运行一个受限的 Codex app-server 图像理解轮次；`openai-codex/<model>` 则使用 OpenAI Codex OAuth provider 路径。
- 对于 `image describe`，显式传入 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。`codex/<model>` 会运行一次受限的 Codex app-server 图像理解轮次；`openai-codex/<model>` 则使用 OpenAI Codex OAuth 提供商路径。
- 无状态执行命令默认走本地。
- 由 Gateway 网关管理状态的命令默认走 gateway。
- 常规本地路径不要求 Gateway 网关正在运行。
- `model run` 是单次执行。对于本地和 `--gateway` 执行，该命令通过智能体运行时打开的 MCP 服务器都会在回复后退役，因此重复的脚本调用不会持续保留 stdio MCP 子进程。
- 常规本地路径不要求 Gateway 网关处于运行状态。
- `model run` 是一次性执行。通过该命令的智能体运行时打开的 MCP 服务器，在本地和 `--gateway` 执行模式下都会在回复完成后被回收，因此重复的脚本调用不会让 stdio MCP 子进程持续存活。
## 模型
## Model
对由 provider 支持的文本推理以及模型/provider 检查，使用 `model`。
对由提供商支持的文本推理，以及模型/提供商检查，使用 `model`。
```bash
openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
@ -152,13 +149,13 @@ openclaw infer model inspect --name gpt-5.5 --json
说明：
- `model run` 会复用智能体运行时，因此 provider/模型覆盖的行为与常规智能体执行一致。
- 因为 `model run` 面向无头自动化，所以命令结束后不会保留按会话维度的内置 MCP 运行时。
- `model auth login`、`model auth logout` 和 `model auth status` 用于管理已保存的 provider 认证状态。
- `model run` 会复用智能体运行时，因此提供商/模型覆盖的行为与常规智能体执行一致。
- 因为 `model run` 面向无头自动化，所以命令结束后不会保留该次会话的内置 MCP 运行时。
- `model auth login`、`model auth logout` 和 `model auth status` 用于管理已保存的提供商认证状态。
## 图像
## Image
对生成、编辑和描述，使用 `image`。
对生成、编辑和描述图像，使用 `image`。
```bash
openclaw infer image generate --prompt "friendly lobster illustration" --json
@ -166,6 +163,7 @@ openclaw infer image generate --prompt "cinematic product photo of headphones" -
openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "simple red circle sticker on a transparent background" --json
openclaw infer image generate --prompt "slow image backend" --timeout-ms 180000 --json
openclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "keep the logo, remove the background" --json
openclaw infer image edit --file ./poster.png --prompt "make this a vertical story ad" --size 2160x3840 --aspect-ratio 9:16 --resolution 4K --json
openclaw infer image describe --file ./photo.jpg --json
openclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-4.1-mini --json
openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --json
@ -174,16 +172,10 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j
说明：
- 从现有输入文件开始时，使用 `image edit`。
- 当使用
`--model openai/gpt-image-1.5` 时，配合 `--output-format png --background transparent`
可获得透明背景的 OpenAI PNG 输出；
`--openai-background` 仍可作为 OpenAI 专用别名使用。不声明背景支持的 providers
会将该提示报告为被忽略的覆盖项。
- 使用 `image providers --json` 可验证哪些内置图像 providers
可被发现、已配置、已选中，以及每个 provider 暴露了哪些
生成/编辑能力。
- 将 `image generate --model <provider/model> --json` 用作图像生成变更的
最窄范围在线 CLI 冒烟检查。示例：
- 对于支持在参考图像编辑时提供几何提示的提供商/模型，可在 `image edit` 中使用 `--size`、`--aspect-ratio` 或 `--resolution`。
- 对于带透明背景的 OpenAI PNG 输出，使用 `--model openai/gpt-image-1.5` 配合 `--output-format png --background transparent`；`--openai-background` 仍可作为 OpenAI 专用别名使用。未声明支持背景控制的提供商会将该提示报告为被忽略的覆盖项。
- 使用 `image providers --json` 可验证哪些内置图像提供商可被发现、已配置、已选中，以及每个提供商公开了哪些生成/编辑能力。
- 使用 `image generate --model <provider/model> --json` 作为图像生成变更的最小化在线 CLI 冒烟检查。示例：
```bash
openclaw infer image providers --json
@ -194,16 +186,14 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j
--json
```
JSON 响应会报告 `ok`、`provider`、`model`、`attempts` 和已写入的
输出路径。设置了 `--output` 时，最终扩展名可能会跟随
provider 返回的 MIME 类型。
JSON 响应会报告 `ok`、`provider`、`model`、`attempts` 和已写入的输出路径。设置 `--output` 时，最终扩展名可能会跟随提供商返回的 MIME type。
- 对于 `image describe`，`--model` 必须是具备图像能力的 `<provider/model>`。
- 对于本地 Ollama 视觉模型，先拉取模型，并将 `OLLAMA_API_KEY` 设置为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。
- 对于 `image describe`，`--model` 必须是支持图像的 `<provider/model>`。
- 对于本地 Ollama 视觉模型，请先拉取模型，并将 `OLLAMA_API_KEY` 设为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。
## 音频
## Audio
对文件转写，使用 `audio`。
对文件转录，使用 `audio`。
```bash
openclaw infer audio transcribe --file ./memo.m4a --json
@ -213,12 +203,12 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso
说明：
- `audio transcribe` 用于文件转写，不用于实时会话管理。
- `audio transcribe` 用于文件转录，而不是实时会话管理。
- `--model` 必须是 `<provider/model>`。
## TTS
对语音合成和 TTS provider 状态，使用 `tts`。
对语音合成和 TTS 提供商状态，使用 `tts`。
```bash
openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json
@ -232,9 +222,9 @@ openclaw infer tts status --json
- `tts status` 默认走 gateway，因为它反映的是由 Gateway 网关管理的 TTS 状态。
- 使用 `tts providers`、`tts voices` 和 `tts set-provider` 来检查和配置 TTS 行为。
## 视频
## Video
对生成和描述，使用 `video`。
对视频生成和描述，使用 `video`。
```bash
openclaw infer video generate --prompt "cinematic sunset over the ocean" --json
@ -245,10 +235,10 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js
说明：
- `video generate` 接受 `--size`、`--aspect-ratio`、`--resolution`、`--duration`、`--audio`、`--watermark` 和 `--timeout-ms`，并将它们转发给视频生成运行时。
- `video generate` 接受 `--size`、`--aspect-ratio`、`--resolution`、`--duration`、`--audio`、`--watermark` 和 `--timeout-ms`，并将其转发给视频生成运行时。
- 对于 `video describe`，`--model` 必须是 `<provider/model>`。
## 网页
## Web
对搜索和抓取工作流，使用 `web`。
@ -261,11 +251,11 @@ openclaw infer web providers --json
说明：
- 使用 `web providers` 来检查可用、已配置和已选中的 providers。
- 使用 `web providers` 来检查可用、已配置和已选中的提供商。
## 嵌入
## Embedding
对向量创建和嵌入 provider 检查，使用 `embedding`。
对向量创建和嵌入提供商检查，使用 `embedding`。
```bash
openclaw infer embedding create --text "friendly lobster" --json
@ -275,7 +265,7 @@ openclaw infer embedding providers --json
## JSON 输出
Infer 命令会在共享封装下规范化 JSON 输出：
Infer 命令会在统一封装下标准化 JSON 输出：
```json
{
@ -300,9 +290,7 @@ Infer 命令会在共享封装下规范化 JSON 输出：
- `outputs`
- `error`
对于生成媒体的命令，`outputs` 包含由 OpenClaw 写入的文件。对于自动化，请使用
该数组中的 `path`、`mimeType`、`size` 以及任何媒体特定尺寸信息，
而不是去解析面向人的 stdout。
对于生成媒体的命令，`outputs` 包含由 OpenClaw 写入的文件。对于自动化，请使用该数组中的 `path`、`mimeType`、`size` 以及任何媒体特定尺寸信息，而不是解析人类可读的 stdout。
## 常见陷阱
@ -326,7 +314,7 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso
- `openclaw capability ...` 是 `openclaw infer ...` 的别名。
## 相关
## 相关内容
- [CLI 参考](/zh-CN/cli)
- [Models](/zh-CN/concepts/models)

129
docs/zh-CN/cli/plugins.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 你想要安装或管理 Gateway 网关插件或兼容的捆绑包。
- 你想要调试插件加载失败问题。
- 你想安装或管理 Gateway 网关插件或兼容的捆绑包。
- 你想调试插件加载失败问题。
summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）'
title: 插件
x-i18n:
generated_at: "2026-04-26T00:28:48Z"
generated_at: "2026-04-26T03:26:30Z"
model: gpt-5.4
provider: openai
source_hash: 52183e4465154afd32d321c7a7a040c0a3c246e334cb81cded5745abebc78e1b
source_hash: 6dec5a7f48d8daaa5230280250642885cb355d1a5f83bacd78d81ba45fa6a7d8
source_path: cli/plugins.md
workflow: 15
---
@ -48,9 +48,9 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
内置插件随 OpenClaw 一起发布。其中一些默认启用（例如内置模型提供商、内置语音提供商，以及内置浏览器插件）；另一些则需要运行 `plugins enable`。
内置插件会随 OpenClaw 一起发布。其中有些默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）；另一些则需要运行 `plugins enable`。
原生 OpenClaw 插件必须提供 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空也必须提供）。兼容捆绑包则使用它们自己的 bundle manifest。
原生 OpenClaw 插件必须提供 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空也需要）。兼容捆绑包则改用它们自己的 bundle 清单。
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细的 list/info 输出还会显示 bundle 子类型（`codex`、`claude` 或 `cursor`）以及检测到的 bundle 能力。
@ -58,7 +58,7 @@ openclaw plugins marketplace list <marketplace> --json
```bash
openclaw plugins install <package> # 先查 ClawHub，再查 npm
openclaw plugins install clawhub:<package> # 仅使用 ClawHub
openclaw plugins install clawhub:<package> # 仅 ClawHub
openclaw plugins install <package> --force # 覆盖现有安装
openclaw plugins install <package> --pin # 固定版本
openclaw plugins install <package> --dangerously-force-unsafe-install
@ -68,31 +68,32 @@ openclaw plugins install <plugin> --marketplace <name> # marketplace（显式
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
裸包名会先在 ClawHub 中检查，然后再查 npm。安全提示：请将插件安装视为运行代码。优先选择固定版本。
裸包名会先在 ClawHub 中检查，然后再检查 npm。安全提示：安装插件应视同运行代码。优先选择固定版本。
如果你的 `plugins` 部分由单文件 `$include` 提供支持，那么 `plugins install/update/enable/disable/uninstall` 会直接写入该被包含文件，并保持 `openclaw.json` 不变。根级 include、include 数组，以及带同级覆盖项的 include 都会以失败关闭的方式处理，而不会被展平。支持的形状请参见 [配置 include](/zh-CN/gateway/configuration)。
如果你的 `plugins` 部分由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会直接写入这个被包含的文件，而不会修改 `openclaw.json`。根级 include、include 数组，以及带有同级覆盖项的 include 都会以失败关闭的方式处理，而不是被展平。支持的形式见 [配置 includes](/zh-CN/gateway/configuration)。
如果配置无效，`plugins install` 通常会以失败关闭的方式终止，并提示你先运行 `openclaw doctor --fix`。唯一有文档说明的例外是一个受限的内置插件恢复路径，仅适用于明确选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。
如果配置无效，`plugins install` 通常会以失败关闭的方式终止，并提示你先运行 `openclaw doctor --fix`。唯一有文档说明的例外是一个范围很窄的内置插件恢复路径，仅适用于明确选择启用 `openclaw.install.allowInvalidConfigRecovery` 的插件。
`--force` 会复用现有安装目标，并原地覆盖已安装的插件或 hook 包。当你有意从新的本地路径、归档、ClawHub 包或 npm 制品重新安装同一 id 时，请使用它。对于已跟踪 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
`--force` 会复用现有安装目标，并直接覆盖已安装的插件或 hook 包。当你有意从新的本地路径、归档文件、ClawHub 包或 npm 制品重新安装同一个 id 时，可以使用它。对于已跟踪的 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
如果你对一个已经安装的插件 id 运行 `plugins install`，OpenClaw 会停止，并引导你在正常升级时使用 `plugins update <id-or-npm-spec>`，或者在你确实想从不同来源覆盖当前安装时使用 `plugins install <package> --force`。
如果你为一个已经安装的插件 id 运行 `plugins install`，OpenClaw 会停止并提示你：常规升级请使用 `plugins update <id-or-npm-spec>`，如果你确实想从其他来源覆盖当前安装，则使用 `plugins install <package> --force`。
`--pin` 仅适用于 npm 安装。不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
`--dangerously-force-unsafe-install` 是一个紧急破窗选项，用于处理内置危险代码扫描器的误报。即使内置扫描器报告了 `critical` 级别发现，它也允许安装继续进行，但它**不会**绕过插件 `before_install` hook 策略拦截，也**不会**绕过扫描失败。
`--dangerously-force-unsafe-install` 是一个仅供紧急情况使用的选项，用于处理内置危险代码扫描器的误报。即使内置扫描器报告了 `critical` 级别发现，它也允许安装继续，但它**不会**绕过插件 `before_install` hook 策略拦截，也**不会**绕过扫描失败。
这个 CLI 标志适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。
这个 CLI 标志适用于插件 install/update 流程。由 Gateway 网关支持的 Skills 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍然是一个单独的 ClawHub Skills 下载/安装流程。
`plugins install` 也是暴露 `openclaw.hooks` 于 `package.json` 中的 hook 包的安装入口。请使用 `openclaw hooks` 来查看经过过滤的 hook 可见性和按 hook 启用设置，而不是用于包安装。
`plugins install` 也是暴露了 `openclaw.hooks` 的 hook 包在 `package.json` 中的安装入口。请使用 `openclaw hooks` 查看筛选后的 hook 可见性和按 hook 启用控制，而不是用它进行包安装。
npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为了安全，依赖安装会在项目本地以 `--ignore-scripts` 运行，即使你的 shell 配置了全局 npm 安装设置也是如此。
Npm spec **仅支持 registry**（包名 + 可选的**精确版本**或**dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为保证安全，依赖安装会在项目本地以 `--ignore-scripts` 运行，即使你的 shell 配置了全局 npm 安装设置也是如此。
裸 spec 和 `@latest` 会保持在稳定轨道上。如果 npm 将其中任一项解析为预发布版本，OpenClaw 会停止，并要求你显式选择加入，例如使用 `@beta`/`@rc` 这样的预发布标签，或像 `@1.2.3-beta.4` 这样的精确预发布版本。
裸 spec 和 `@latest` 会保持在稳定轨道上。如果 npm 将这两者之一解析为预发布版本，OpenClaw 会停止，并要求你使用预发布标签（如 `@beta`/`@rc`）或精确预发布版本（如 `@1.2.3-beta.4`）来显式选择加入。
如果裸安装 spec 与某个内置插件 id 匹配（例如 `diffs`），OpenClaw 会直接安装该内置插件。若要安装同名的 npm 包，请使用显式的带作用域 spec（例如 `@scope/diffs`）。
如果一个裸安装 spec 与某个内置插件 id 匹配（例如 `diffs`），OpenClaw 会直接安装该内置插件。要安装同名的 npm 包，请使用显式作用域 spec（例如 `@scope/diffs`）。
支持的归档格式：`.zip`、`.tgz`、`.tar.gz`、`.tar`。
支持的归档格式：`.zip`、`.tgz`、`.tar.gz`、`.tar`。
原生 OpenClaw 插件归档必须在解压后的插件根目录中包含有效的 `openclaw.plugin.json`；仅包含 `package.json` 的归档会在 OpenClaw 写入安装记录之前被拒绝。
也支持 Claude marketplace 安装。
@ -103,22 +104,22 @@ openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
现在，对于符合 npm 安全规范的裸插件 spec，OpenClaw 也会优先使用 ClawHub。只有当 ClawHub 没有该包或版本时，它才会回退到 npm：
OpenClaw 现在也会优先为符合 npm 安全要求的裸插件 spec 使用 ClawHub。只有当 ClawHub 没有该包或该版本时，才会回退到 npm：
```bash
openclaw plugins install openclaw-codex-app-server
```
OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低网关兼容性，然后通过常规归档路径完成安装。记录下来的安装会保留其 ClawHub 来源元数据，以便后续更新。
OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低 gateway 兼容性，然后通过常规归档路径进行安装。记录下来的安装会保留其 ClawHub 来源元数据，以便后续更新。
当 marketplace 名称存在于 Claude 的本地注册表缓存 `~/.claude/plugins/known_marketplaces.json` 中时，可使用 `plugin@marketplace` 简写：
当 marketplace 名称存在于 Claude 的本地 registry 缓存 `~/.claude/plugins/known_marketplaces.json` 中时，可使用 `plugin@marketplace` 简写：
```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
当你想显式传递 marketplace 来源时，请使用 `--marketplace`：
如果你想显式传入 marketplace 来源，请使用 `--marketplace`：
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
@ -129,22 +130,22 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
Marketplace 来源可以是：
- `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称
- 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称
- 本地 marketplace 根目录或 `marketplace.json` 路径
- 例如 `owner/repo` 这样的 GitHub 仓库简写
- 例如 `https://github.com/owner/repo` 这样的 GitHub 仓库 URL
- `owner/repo` 这样的 GitHub 仓库简写
- `https://github.com/owner/repo` 这样的 GitHub 仓库 URL
- git URL
对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆后的 marketplace 仓库内部。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程 manifest 中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径类插件来源。
对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆后的 marketplace 仓库内部。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件来源。
对于本地路径和归档，OpenClaw 会自动检测：
对于本地路径和归档文件，OpenClaw 会自动检测：
- 原生 OpenClaw 插件（`openclaw.plugin.json`）
- Codex 兼容捆绑包（`.codex-plugin/plugin.json`）
- Claude 兼容捆绑包（`.claude-plugin/plugin.json` 或默认的 Claude 组件布局）
- Cursor 兼容捆绑包（`.cursor-plugin/plugin.json`）
- 与 Codex 兼容的捆绑包（`.codex-plugin/plugin.json`）
- 与 Claude 兼容的捆绑包（`.claude-plugin/plugin.json` 或默认 Claude 组件布局）
- 与 Cursor 兼容的捆绑包（`.cursor-plugin/plugin.json`）
兼容捆绑包会安装到常规插件根目录中，并参与同样的 list/info/enable/disable 流程。当前已支持 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / manifest 声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录；其他检测到的 bundle 能力会显示在诊断/info 中，但尚未接入运行时执行。
兼容捆绑包会安装到常规插件根目录中，并参与同样的 list/info/enable/disable 流程。目前已支持 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录；其他检测到的 bundle 能力会显示在 diagnostics/info 中，但尚未接入运行时执行。
### 列表
@ -155,15 +156,15 @@ openclaw plugins list --verbose
openclaw plugins list --json
```
使用 `--enabled` 仅显示已启用插件。使用 `--verbose` 可从表格视图切换到按插件显示详情行，其中包含 source/origin/version/activation 元数据。使用 `--json` 可获取适用于机器读取的清单以及注册表诊断信息。
使用 `--enabled` 仅显示已启用的插件。使用 `--verbose` 可从表格视图切换为每个插件一行详情，显示来源/起源/版本/激活元数据。使用 `--json` 可获取机器可读的清单以及 registry 诊断信息。
`plugins list` 会先读取持久化的本地插件注册表；如果注册表缺失或无效，则回退为仅基于 manifest 推导的结果。它适合用于检查某个插件是否已安装、已启用，以及在冷启动规划中是否可见，但它不是针对已运行 Gateway 网关进程的实时运行时探针。修改插件代码、启用状态、hook 策略或 `plugins.load.paths` 后，在期待新的 `register(api)` 代码或 hook 生效之前，请重启为该渠道提供服务的 Gateway 网关。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不仅仅是包装进程。
`plugins list` 会先读取持久化的本地插件 registry；如果 registry 缺失或无效，则回退为仅基于清单派生的结果。它适合用于检查某个插件是否已安装、已启用，以及在冷启动规划中是否可见，但它不是对已经运行中的 Gateway 网关进程的实时运行时探测。修改插件代码、启用状态、hook 策略或 `plugins.load.paths` 后，在期待新的 `register(api)` 代码或 hook 开始运行之前，请重启为该渠道提供服务的 Gateway 网关。对于远程/容器部署，请确认你重启的是真正的 `openclaw gateway run` 子进程，而不只是包装进程。
对于运行时 hook 调试：
用于运行时 hook 调试：
- `openclaw plugins inspect <id> --json` 会显示已注册的 hook，以及来自模块加载检查过程的诊断信息
- `openclaw plugins inspect <id> --json` 会显示已注册的 hook，以及模块加载式检查过程中产生的诊断信息
- `openclaw gateway status --deep --require-rpc` 会确认可访问的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态
- 非内置的对话 hook（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）要求设置 `plugins.entries.<id>.hooks.allowConversationAccess=true`
- 非内置的会话 hook（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要设置 `plugins.entries.<id>.hooks.allowConversationAccess=true`
使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）：
@ -171,13 +172,14 @@ openclaw plugins list --json
openclaw plugins install -l ./my-plugin
```
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制到受管安装目标。
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是覆盖受管安装目标。
在 npm 安装时使用 `--pin`，可以将解析后的精确 spec（`name@version`）保存到受管插件索引中，同时保持默认行为为未固定版本。
在 npm 安装时使用 `--pin`，可将解析后的精确 spec（`name@version`）保存到受管插件索引中，同时保持默认行为为非固定版本。
### 插件索引
插件安装元数据是机器管理状态，不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其中顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件 manifest 的记录。`plugins` 数组是基于 manifest 推导的冷注册表缓存。该文件包含“请勿手动编辑”警告，并被 `openclaw plugins update`、卸载、诊断以及冷插件注册表使用。
插件安装元数据是机器管理的状态，而不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其中顶层的 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组则是从清单派生的冷注册表缓存。该文件包含“请勿编辑”的警告，并被 `openclaw plugins update`、卸载、诊断和冷插件 registry 使用。
当 OpenClaw 看到配置中存在已发布的旧版 `plugins.installs` 记录时，会将它们迁移到插件索引中并移除该配置键；如果任一写入失败，则会保留配置记录，以避免安装元数据丢失。
### 卸载
@ -187,13 +189,9 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` 会从 `plugins.entries`、持久化插件索引、插件 allowlist，以及在适用情况下的已链接 `plugins.load.paths` 条目中移除插件记录。
对于活动的内存插件，memory 槽位会重置为 `memory-core`。
`uninstall` 会从 `plugins.entries`、持久化插件索引、插件 allowlist，以及适用时的已链接 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，否则卸载还会删除受跟踪的受管安装目录，但前提是该目录位于 OpenClaw 的插件扩展根目录中。对于活动的内存插件，memory 槽位会重置为 `memory-core`。
默认情况下，卸载还会移除活动 state-dir 插件根目录下的插件安装目录。使用
`--keep-files` 可保留磁盘上的文件。
`--keep-config` 作为 `--keep-files` 的已弃用别名仍受支持。
`--keep-config` 作为 `--keep-files` 的已弃用别名仍然受支持。
### 更新
@ -205,19 +203,19 @@ openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
更新适用于受管插件索引中已跟踪的插件安装，以及 `hooks.internal.installs` 中已跟踪的 hook 包安装。
更新会应用到受管插件索引中已跟踪的插件安装，以及 `hooks.internal.installs` 中已跟踪的 hook 包安装。
当你传入插件 id 时，OpenClaw 会复用该插件记录下来的安装 spec。这意味着之前保存的 dist-tag（例如 `@beta`）和精确固定版本，在之后运行 `update <id>` 时会继续使用。
当你传入插件 id 时，OpenClaw 会复用该插件记录下来的安装 spec。这意味着先前保存的 dist-tag（如 `@beta`）和精确固定版本，在后续运行 `update <id>` 时会继续使用。
对于 npm 安装，你也可以传入带 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回已跟踪的插件记录，更新该已安装插件，并为今后基于 id 的更新记录新的 npm spec。
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回已跟踪的插件记录，更新那个已安装的插件，并记录新的 npm spec，以供将来基于 id 的更新使用。
仅传入 npm 包名而不带版本或标签，也会解析回已跟踪的插件记录。当某个插件被固定到精确版本，而你希望将它切回 registry 的默认发布线时，可使用这种方式。
传入不带版本或标签的 npm 包名也会解析回已跟踪的插件记录。当某个插件之前被固定到精确版本，而你想让它回到 registry 的默认发布线时，可使用这种方式。
在执行实时 npm 更新之前，OpenClaw 会将已安装的包版本与 npm registry 元数据进行比对。如果已安装版本和已记录的制品身份已经与解析出的目标一致，则会跳过更新，不会下载、重新安装，也不会重写 `openclaw.json`。
在执行实际的 npm 更新前，OpenClaw 会将已安装的包版本与 npm registry 元数据进行比对。如果已安装版本和记录下来的制品身份已经与解析出的目标一致，则会跳过更新，不会下载、重新安装，也不会改写 `openclaw.json`。
当存在已存储的完整性哈希，而获取到的制品哈希发生变化时，OpenClaw 会将其视为 npm 制品漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续之前请求确认。非交互式更新辅助工具会以失败关闭的方式终止，除非调用方提供显式的继续策略。
当存在已存储的完整性哈希，而拉取到的制品哈希发生变化时，OpenClaw 会将其视为 npm 制品漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助流程会以失败关闭方式终止，除非调用方提供显式的继续策略。
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为在插件更新期间应对内置危险代码扫描误报的紧急破窗覆盖项。它仍然不会绕过插件 `before_install` 策略拦截或扫描失败拦截，而且它仅适用于插件更新，不适用于 hook 包更新。
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报时的紧急覆盖选项。它仍然不会绕过插件 `before_install` 策略拦截，也不会绕过扫描失败拦截，并且它只适用于插件更新，不适用于 hook 包更新。
### 检查
@ -226,20 +224,20 @@ openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
```
针对单个插件的深度检查。会显示身份、加载状态、来源、已注册能力、hook、工具、命令、服务、网关方法、HTTP 路由、策略标志、诊断信息、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持。
对单个插件进行深度检查。会显示身份、加载状态、来源、已注册能力、hooks、工具、命令、服务、gateway 方法、HTTP 路由、策略标志、诊断信息、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持。
每个插件都会根据其在运行时实际注册的内容进行分类：
- **plain-capability** — 单一能力类型（例如仅提供商插件）
- **plain-capability** — 一种能力类型（例如仅 provider 插件）
- **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像）
- **hook-only** — 只有 hook，没有能力或表面
- **hook-only** — 只有 hooks，没有能力或其他表面
- **non-capability** — 有工具/命令/服务，但没有能力
有关能力模型的更多信息，请参见 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
有关能力模型的更多信息，请参阅 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
`--json` 标志会输出适合脚本和审计使用的机器可读报告。
`inspect --all` 会渲染整个插件集范围的表格，其中包含形态、能力种类、兼容性提示、bundle 能力和 hook 摘要列。
`inspect --all` 会渲染一个覆盖全量插件的表格，其中包含 shape、capability kinds、兼容性提示、bundle 能力和 hook 摘要列。
`info` 是 `inspect` 的别名。
@ -249,11 +247,11 @@ openclaw plugins inspect <id> --json
openclaw plugins doctor
```
`doctor` 会报告插件加载错误、manifest/设备发现 诊断信息以及兼容性提示。当一切正常时，它会打印 `No plugin issues detected.`。
`doctor` 会报告插件加载错误、清单/发现诊断信息以及兼容性提示。当一切正常时，它会打印 `No plugin issues detected.`。
对于缺少 `register`/`activate` 导出之类的模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以便在诊断输出中包含紧凑的导出形态摘要。
对于缺少 `register`/`activate` 导出之类的模块形态失败，可使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以便在诊断输出中包含简洁的导出形态摘要。
### 注册表
### Registry
```bash
openclaw plugins registry
@ -261,12 +259,11 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
本地插件注册表是 OpenClaw 持久化的冷读模型，用于存储已安装插件的身份、启用状态、来源元数据和贡献归属关系。
正常启动、提供商所有者查找、渠道设置分类以及插件清单都可以在不导入插件运行时模块的情况下读取它。
本地插件 registry 是 OpenClaw 持久化的冷读模型，用于记录已安装插件的身份、启用状态、来源元数据和贡献归属。常规启动、provider 所有者查找、渠道设置分类和插件清单都可以在不导入插件运行时模块的情况下读取它。
使用 `plugins registry` 可检查持久化注册表是否存在、是否为最新或是否已过时。使用 `--refresh` 可根据持久化插件索引、配置策略以及 manifest/package 元数据重建它。这是一条修复路径，而不是运行时激活路径。
使用 `plugins registry` 可检查持久化 registry 是否存在、是否最新或是否已过期。使用 `--refresh` 可根据持久化插件索引、配置策略以及清单/package 元数据重建它。这是一条修复路径，而不是运行时激活路径。
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的紧急破窗兼容开关，用于处理注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；该环境变量回退仅用于迁移推出期间的紧急启动恢复。
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的紧急兼容性开关，用于处理 registry 读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；这个环境变量回退仅用于迁移推出期间的紧急启动恢复。
### Marketplace
@ -275,7 +272,7 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Marketplace list 接受本地 marketplace 路径、`marketplace.json` 路径、如 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的来源标签，以及已解析的 marketplace manifest 和插件条目。
Marketplace list 接受本地 marketplace 路径、`marketplace.json` 路径、如 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的来源标签，以及已解析的 marketplace 清单和插件条目。
## 相关内容

91
docs/zh-CN/providers/anthropic.md
View File

@ -1,24 +1,24 @@
---
read_when:
- 你想在 OpenClaw 中使用 Anthropic 模型
summary: 在 OpenClaw 中通过 API 密钥或 Claude CLI 使用 Anthropic Claude
summary: 在 OpenClaw 中通过 API 密钥或 Claude CLI 使用 Anthropic（API + Claude CLI）
title: Anthropic
x-i18n:
generated_at: "2026-04-24T18:10:01Z"
generated_at: "2026-04-26T03:26:30Z"
model: gpt-5.4
provider: openai
source_hash: daba524d9917321d2aec55222d0df7b850ddf7f5c1c13123b62807eebd1a7a1b
source_hash: cf1ecd7846b8dd86cd7a722654042cd78e6c28fc2ae5aca43d967d19df337744
source_path: providers/anthropic.md
workflow: 15
---
Anthropic 构建了 **Claude** 模型家族。OpenClaw 支持两种认证方式：
Anthropic 构建了 **Claude** 模型系列。OpenClaw 支持两种认证方式：
- **API 密钥** — 直接访问 Anthropic API，按用量计费（`anthropic/*` 模型）
- **Claude CLI** — 复用同一主机上现有的 Claude CLI 登录
- **API 密钥** — 直接访问 Anthropic API，并按用量计费（`anthropic/*` 模型）
- **Claude CLI** — 在同一主机上复用现有的 Claude CLI 登录
<Warning>
Anthropic 工作人员告诉我们，OpenClaw 这种 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新的政策，否则 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为被认可。
Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为已获认可。
对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是最清晰、最可预测的生产路径。
@ -26,8 +26,8 @@ Anthropic 当前的公开文档：
- [Claude Code CLI 参考](https://code.claude.com/docs/en/cli-reference)
- [Claude Agent SDK 概览](https://platform.claude.com/docs/en/agent-sdk/overview)
- [在你的 Pro 或 Max 套餐中使用 Claude Code](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- [在你的 Team 或 Enterprise 套餐中使用 Claude Code](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
- [在你的 Pro 或 Max 计划中使用 Claude Code](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- [在你的 Team 或 Enterprise 计划中使用 Claude Code](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
</Warning>
@ -75,8 +75,8 @@ Anthropic 当前的公开文档：
**最适合：** 复用现有的 Claude CLI 登录，而无需单独的 API 密钥。
<Steps>
<Step title="确保已安装并登录 Claude CLI">
验证方式：
<Step title="确保已安装 Claude CLI 并完成登录">
使用以下命令验证：
```bash
claude --version
@ -102,7 +102,7 @@ Anthropic 当前的公开文档：
</Note>
<Tip>
如果你想要最清晰的计费路径，请改用 Anthropic API 密钥。OpenClaw 也支持来自 [OpenAI Codex](/zh-CN/providers/openai)、[Qwen Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [Z.AI / GLM](/zh-CN/providers/glm) 的订阅式选项。
如果你希望获得最清晰的计费路径，请改用 Anthropic API 密钥。OpenClaw 还支持来自 [OpenAI Codex](/zh-CN/providers/openai)、[Qwen Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [Z.AI / GLM](/zh-CN/providers/glm) 的订阅式选项。
</Tip>
</Tab>
@ -112,7 +112,7 @@ Anthropic 当前的公开文档：
当未设置显式 thinking 级别时，Claude 4.6 模型在 OpenClaw 中默认使用 `adaptive` thinking。
可通过 `/think:<level>` 按消息覆盖，或在模型参数中配置：
可通过 `/think:<level>` 按消息覆盖，或在模型参数中设置：
```json5
{
@ -134,15 +134,15 @@ Anthropic 当前的公开文档：
- [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
</Note>
## 提示词缓存
## 提示缓存
OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
OpenClaw 支持 Anthropic 的提示缓存功能，适用于 API 密钥认证。
| 值 | 缓存时长 | 说明 |
| 值 | 缓存时长 | 描述 |
| ------------------- | -------------- | -------------------------------------- |
| `"short"`（默认） | 5 分钟 | 会为 API 密钥认证自动应用 |
| `"short"`（默认） | 5 分钟 | 对 API 密钥认证自动应用 |
| `"long"` | 1 小时 | 扩展缓存 |
| `"none"` | 不缓存 | 禁用提示词缓存 |
| `"none"` | 不缓存 | 禁用提示缓存 |
```json5
{
@ -160,7 +160,7 @@ OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
<AccordionGroup>
<Accordion title="按智能体覆盖缓存">
使用模型级参数作为基线，然后通过 `agents.list[].params` 覆盖特定智能体：
使用模型级 `params` 作为基线，然后通过 `agents.list[].params` 覆盖特定智能体：
```json5
{
@ -186,14 +186,14 @@ OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
1. `agents.defaults.models["provider/model"].params`
2. `agents.list[].params`（匹配 `id`，按键覆盖）
这让一个智能体可以保持长生命周期缓存，而同一模型上的另一个智能体则可为突发性/低复用流量禁用缓存。
这样，你可以让一个智能体保留长期缓存，同时让同一模型上的另一个智能体为突发性或低复用流量禁用缓存。
</Accordion>
<Accordion title="Bedrock Claude 说明">
- Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）在配置时接受 `cacheRetention` 透传。
- Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）在配置后接受 `cacheRetention` 透传。
- 非 Anthropic 的 Bedrock 模型会在运行时被强制设为 `cacheRetention: "none"`。
- 当未设置显式值时，API 密钥智能默认值也会为 Bedrock 上的 Claude 引用注入 `cacheRetention: "short"`。
- 当未设置显式值时，API 密钥的智能默认值也会为 Bedrock 上的 Claude 引用预设 `cacheRetention: "short"`。
</Accordion>
</AccordionGroup>
@ -201,7 +201,7 @@ OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
<AccordionGroup>
<Accordion title="快速模式">
OpenClaw 的共享 `/fast` 开关支持直连 Anthropic 流量（使用 API 密钥和 OAuth 访问 `api.anthropic.com`）。
OpenClaw 的共享 `/fast` 开关支持直连 Anthropic 流量（API 密钥和面向 `api.anthropic.com` 的 OAuth）。
| 命令 | 映射到 |
|---------|---------|
@ -224,28 +224,29 @@ OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
<Note>
- 仅对直连 `api.anthropic.com` 的请求注入。代理路由会保持 `service_tier` 不变。
- 当 `/fast` 和显式的 `serviceTier` 或 `service_tier` 参数同时设置时，后者优先。
- 对于没有 Priority Tier 容量的账户，`service_tier: "auto"` 可能解析为 `standard`。
- 当同时设置时，显式的 `serviceTier` 或 `service_tier` 参数会覆盖 `/fast`。
- 在没有 Priority Tier 容量的账户上，`service_tier: "auto"` 可能会解析为 `standard`。
</Note>
</Accordion>
<Accordion title="媒体理解（图像和 PDF）">
内置的 Anthropic 插件注册了图像和 PDF 理解能力。OpenClaw
会从已配置的 Anthropic 认证中自动解析媒体能力——无需额外配置。
会根据已配置的 Anthropic 认证自动解析媒体能力——无需
额外配置。
| 属性 | 值 |
| -------------- | -------------------- |
| 默认模型 | `claude-opus-4-6` |
| 支持的输入 | 图像、PDF 文档 |
当图像或 PDF 被附加到对话中时，OpenClaw 会自动
通过 Anthropic 媒体理解提供商进行路由。
当图像或 PDF 附加到对话中时，OpenClaw 会自动
通过 Anthropic 媒体理解提供商进行处理。
</Accordion>
<Accordion title="1M 上下文窗口（测试版）">
Anthropic 的 1M 上下文窗口受测试版门控。可按模型启用：
Anthropic 的 1M 上下文窗口受测试版门控限制。请按模型启用：
```json5
{
@ -263,15 +264,19 @@ OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
OpenClaw 会将其映射为请求中的 `anthropic-beta: context-1m-2025-08-07`。
`params.context1m: true` 也适用于 Claude CLI 后端
（`claude-cli/*`）中符合条件的 Opus 和 Sonnet 模型，从而扩展这些 CLI 会话的运行时
上下文窗口，使其与直连 API 的行为保持一致。
<Warning>
需要你的 Anthropic 凭证具备长上下文访问权限。旧版令牌认证（`sk-ant-oat-*`）会被拒绝用于 1M 上下文请求——OpenClaw 会记录警告并回退到标准上下文窗口。
需要你的 Anthropic 凭证具备长上下文访问权限。旧版令牌认证（`sk-ant-oat-*`）会被 1M 上下文请求拒绝——OpenClaw 会记录警告，并回退到标准上下文窗口。
</Warning>
</Accordion>
<Accordion title="Claude Opus 4.7 1M 上下文">
`anthropic/claude-opus-4.7` 及其 `claude-cli` 变体默认具有 1M 上下文
窗口——不需要 `params.context1m: true`。
窗口——无需设置 `params.context1m: true`。
</Accordion>
</AccordionGroup>
@ -279,37 +284,37 @@ OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
<AccordionGroup>
<Accordion title="401 错误 / 令牌突然失效">
Anthropic 令牌认证会过期，也可能被撤销。对于新的设置，请改用 Anthropic API 密钥。
Anthropic 令牌认证会过期，也可能被撤销。对于新的配置，建议改用 Anthropic API 密钥。
</Accordion>
<Accordion title='No API key found for provider "anthropic"'>
Anthropic 认证是**按智能体**生效的——新智能体不会继承主智能体的密钥。请为该智能体重新运行新手引导（或在 Gateway 网关主机上配置 API 密钥），然后使用 `openclaw models status` 验证。
<Accordion title='未找到提供商 "anthropic" 的 API 密钥'>
Anthropic 认证是**按智能体**配置的——新智能体不会继承主智能体的密钥。请为该智能体重新运行新手引导（或在 Gateway 网关主机上配置 API 密钥），然后使用 `openclaw models status` 验证。
</Accordion>
<Accordion title='No credentials found for profile "anthropic:default"'>
运行 `openclaw models status` 查看当前激活的是哪个认证配置文件。重新运行新手引导，或为该配置文件路径配置 API 密钥。
<Accordion title='未找到配置文件 "anthropic:default" 的凭证'>
运行 `openclaw models status` 以查看当前启用的是哪个认证配置文件。重新运行新手引导，或为该配置文件路径配置 API 密钥。
</Accordion>
<Accordion title="No available auth profile (all in cooldown)">
检查 `openclaw models status --json` 中的 `auth.unusableProfiles`。Anthropic 的速率限制冷却可能是按模型范围生效的，因此同级的其他 Anthropic 模型仍可能可用。添加另一个 Anthropic 配置文件，或等待冷却结束。
<Accordion title="没有可用的认证配置文件（全部处于冷却中）">
检查 `openclaw models status --json` 中的 `auth.unusableProfiles`。Anthropic 的速率限制冷却可能按模型范围生效，因此同级的其他 Anthropic 模型可能仍可使用。添加另一个 Anthropic 配置文件，或等待冷却结束。
</Accordion>
</AccordionGroup>
<Note>
更多帮助： [故障排除](/zh-CN/help/troubleshooting) 和 [常见问题](/zh-CN/help/faq)。
更多帮助：[故障排除](/zh-CN/help/troubleshooting) 和 [常见问题](/zh-CN/help/faq)。
</Note>
## 相关
## 相关内容
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="CLI 后端" href="/zh-CN/gateway/cli-backends" icon="terminal">
Claude CLI 后端设置和运行时细节。
</Card>
<Card title="提示词缓存" href="/zh-CN/reference/prompt-caching" icon="database">
提示词缓存在各提供商间的工作方式。
<Card title="提示缓存" href="/zh-CN/reference/prompt-caching" icon="database">
提示缓存如何在不同提供商之间工作。
</Card>
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
认证细节和凭证复用规则。

261
docs/zh-CN/tools/tts.md
View File

@ -3,19 +3,19 @@ read_when:
- 为回复启用文本转语音
- 配置 TTS 提供商或限制
- 使用 `/tts` 命令
summary: 用于发出回复的文本转语音（TTS）
summary: 用于出站回复的文本转语音（TTS）
title: 文本转语音
x-i18n:
generated_at: "2026-04-26T03:13:10Z"
generated_at: "2026-04-26T03:26:32Z"
model: gpt-5.4
provider: openai
source_hash: c1c0d338e146f62398be2d0157b5c8bb641ebd9624b5f527556f0938d2e6ce29
source_hash: 56df1e6193e07224fca9252f5f21d6feaee016b26216be63c27b35defba84444
source_path: tools/tts.md
workflow: 15
---
OpenClaw 可以使用 Azure Speech、ElevenLabs、Google Gemini、Gradium、Inworld、Local CLI、Microsoft、MiniMax、OpenAI、Volcengine、Vydra、xAI 或 Xiaomi MiMo，将发出的回复转换为音频。
它适用于 OpenClaw 能发送音频的任何地方。
OpenClaw 可以使用 Azure Speech、ElevenLabs、Google Gemini、Gradium、Inworld、Local CLI、Microsoft、MiniMax、OpenAI、Volcengine、Vydra、xAI 或 Xiaomi MiMo 将出站回复转换为音频。
它适用于 OpenClaw 可以发送音频的任何地方。
## 支持的服务
@ -29,16 +29,16 @@ OpenClaw 可以使用 Azure Speech、ElevenLabs、Google Gemini、Gradium、Inwo
- **MiniMax**（主提供商或回退提供商；使用 T2A v2 API）
- **OpenAI**（主提供商或回退提供商；也用于摘要）
- **Volcengine**（主提供商或回退提供商；使用 BytePlus Seed Speech HTTP API）
- **Vydra**（主提供商或回退提供商；共享的图像、视频和语音提供商）
- **Vydra**（主提供商或回退提供商；共享图像、视频和语音提供商）
- **xAI**（主提供商或回退提供商；使用 xAI TTS API）
- **Xiaomi MiMo**（主提供商或回退提供商；通过 Xiaomi chat completions 使用 MiMo TTS）
### Microsoft 语音说明
当前内置的 Microsoft 语音提供商通过 `node-edge-tts` 库使用 Microsoft Edge 的在线神经网络 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 端点，并且不需要 API key。
`node-edge-tts` 提供了语音配置选项和输出格式，但并非所有选项都受该服务支持。使用 `edge` 的旧版配置和指令输入仍然有效，并会被规范化为 `microsoft`。
当前内置的 Microsoft 语音提供商通过 `node-edge-tts` 库使用 Microsoft Edge 的在线神经 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 端点，并且不需要 API key。
`node-edge-tts` 提供语音配置选项和输出格式，但并非所有选项都受该服务支持。使用 `edge` 的旧版配置和指令输入仍然可用，并会被标准化为 `microsoft`。
由于这一路径属于公共 Web 服务，且没有公开发布的 SLA 或配额，请将其视为“尽力而为”的服务。如果你需要有保障的限额和支持，请使用 OpenAI 或 ElevenLabs。
由于这一路径是没有公开 SLA 或配额说明的公共网络服务，请将其视为尽力而为的服务。如果你需要有保障的限制和支持，请使用 OpenAI 或 ElevenLabs。
## 可选键
@ -49,44 +49,44 @@ OpenClaw 可以使用 Azure Speech、ElevenLabs、Google Gemini、Gradium、Inwo
- `GEMINI_API_KEY`（或 `GOOGLE_API_KEY`）
- `GRADIUM_API_KEY`
- `INWORLD_API_KEY`
- `MINIMAX_API_KEY`；MiniMax TTS 还接受通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY` 提供的 Token Plan 身份验证
- `MINIMAX_API_KEY`；MiniMax TTS 也接受通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY` 提供的 Token Plan 认证
- `OPENAI_API_KEY`
- `VOLCENGINE_TTS_API_KEY`（或 `BYTEPLUS_SEED_SPEECH_API_KEY`）；旧版 AppID/token 身份验证也接受 `VOLCENGINE_TTS_APPID` 和 `VOLCENGINE_TTS_TOKEN`
- `VOLCENGINE_TTS_API_KEY`（或 `BYTEPLUS_SEED_SPEECH_API_KEY`）；旧版 AppID/token 认证也接受 `VOLCENGINE_TTS_APPID` 和 `VOLCENGINE_TTS_TOKEN`
- `VYDRA_API_KEY`
- `XAI_API_KEY`
- `XIAOMI_API_KEY`
Local CLI 和 Microsoft 语音**不**需要 API key。
Local CLI 和 Microsoft 语音 **不** 需要 API key。
如果配置了多个提供商，则会先使用选定的提供商，其他提供商作为回退选项。
自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用了摘要，对应提供商也必须完成身份验证。
如果配置了多个提供商，会先使用所选提供商，其他提供商则作为回退选项。
自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用了摘要，对应提供商也必须完成认证。
## 服务链接
- [OpenAI Text-to-Speech guide](https://platform.openai.com/docs/guides/text-to-speech)
- [OpenAI Audio API reference](https://platform.openai.com/docs/api-reference/audio)
- [Azure Speech REST text-to-speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech)
- [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech)
- [OpenAI Audio API 参考](https://platform.openai.com/docs/api-reference/audio)
- [Azure Speech REST 文本转语音](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech)
- [Azure Speech provider](/zh-CN/providers/azure-speech)
- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech)
- [ElevenLabs Authentication](https://elevenlabs.io/docs/api-reference/authentication)
- [ElevenLabs 文本转语音](https://elevenlabs.io/docs/api-reference/text-to-speech)
- [ElevenLabs 认证](https://elevenlabs.io/docs/api-reference/authentication)
- [Gradium](/zh-CN/providers/gradium)
- [Inworld TTS API](https://docs.inworld.ai/tts/tts)
- [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2)
- [Volcengine TTS HTTP API](/zh-CN/providers/volcengine#text-to-speech)
- [Xiaomi MiMo speech synthesis](/zh-CN/providers/xiaomi#text-to-speech)
- [Xiaomi MiMo 语音合成](/zh-CN/providers/xiaomi#text-to-speech)
- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)
- [Microsoft Speech output formats](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
- [xAI Text to Speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest)
- [Microsoft Speech 输出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
- [xAI 文本转语音](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest)
## 默认启用吗？
不是。自动 TTS 默认**关闭**。可通过配置中的 `messages.tts.auto` 或本地的 `/tts on` 启用。
不是。自动 TTS 默认 **关闭**。请在配置中使用 `messages.tts.auto` 启用，或在本地使用 `/tts on` 启用。
当未设置 `messages.tts.provider` 时，OpenClaw 会按照注册表自动选择顺序，选取第一个已配置的语音提供商。
当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序挑选第一个已配置的语音提供商。
## 配置
TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
完整 schema 见 [Gateway 网关配置](/zh-CN/gateway/configuration)。
### 最小配置（启用 + 提供商）
@ -102,9 +102,9 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
}
```
### 按智能体覆盖语音配置
### 按智能体覆盖语音设置
当某个智能体需要使用不同的提供商、语音、模型、风格或自动 TTS 模式时，请使用 `agents.list[].tts`。该智能体配置块会在 `messages.tts` 之上执行深度合并，因此提供商凭证可以保留在全局提供商配置中。
当某个智能体需要使用不同的提供商、语音、模型、风格或自动 TTS 模式时，请使用 `agents.list[].tts`。智能体配置块会在 `messages.tts` 之上执行深度合并，因此提供商凭证可以保留在全局提供商配置中。
```json5
{
@ -137,14 +137,14 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
}
```
自动回复、`/tts audio`、`/tts status` 和 `tts` 智能体工具的优先级如下：
自动回复、`/tts audio`、`/tts status` 以及 `tts` 智能体工具的优先级顺序为：
1. `messages.tts`
2. 当前激活的 `agents.list[].tts`
3. 此主机的本地 `/tts` 偏好设置
3. 当前主机的本地 `/tts` 偏好设置
4. 启用模型覆盖时的内联 `[[tts:...]]` 指令
### 使用 OpenAI 作为主提供商，ElevenLabs 作为回退
### OpenAI 主提供商 + ElevenLabs 回退
```json5
{
@ -185,7 +185,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
}
```
### Azure Speech 作为主提供商
### Azure Speech 主提供商
```json5
{
@ -208,9 +208,9 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
}
```
Azure Speech 使用的是 Speech 资源 key，而不是 Azure OpenAI key。解析顺序为 `messages.tts.providers.azure-speech.apiKey` -> `AZURE_SPEECH_KEY` -> `AZURE_SPEECH_API_KEY` -> `SPEECH_KEY`，地区则为 `messages.tts.providers.azure-speech.region` -> `AZURE_SPEECH_REGION` -> `SPEECH_REGION`。新配置应使用 `azure-speech`；`azure` 可作为提供商别名。
Azure Speech 使用的是 Speech 资源 key，而不是 Azure OpenAI key。解析顺序为 `messages.tts.providers.azure-speech.apiKey` -> `AZURE_SPEECH_KEY` -> `AZURE_SPEECH_API_KEY` -> `SPEECH_KEY`，区域则是 `messages.tts.providers.azure-speech.region` -> `AZURE_SPEECH_REGION` -> `SPEECH_REGION`。新配置应使用 `azure-speech`；`azure` 可作为提供商别名接受。
### Microsoft 作为主提供商（无 API key）
### Microsoft 主提供商（无需 API key）
```json5
{
@ -233,7 +233,7 @@ Azure Speech 使用的是 Speech 资源 key，而不是 Azure OpenAI key。解
}
```
### MiniMax 作为主提供商
### MiniMax 主提供商
```json5
{
@ -257,9 +257,9 @@ Azure Speech 使用的是 Speech 资源 key，而不是 Azure OpenAI key。解
}
```
MiniMax TTS 的身份验证解析顺序是 `messages.tts.providers.minimax.apiKey`，然后是已存储的 `minimax-portal` OAuth/token 配置文件，然后是 Token Plan 环境变量键（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。当未显式设置 TTS 的 `baseUrl` 时，OpenClaw 可以复用已配置的 `minimax-portal` OAuth 主机用于 Token Plan 语音。
MiniMax TTS 的认证解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是已存储的 `minimax-portal` OAuth/token 配置文件，再然后是 Token Plan 环境变量键（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。如果没有显式设置 TTS `baseUrl`，OpenClaw 可以复用已配置的 `minimax-portal` OAuth 主机用于 Token Plan 语音。
### Google Gemini 作为主提供商
### Google Gemini 主提供商
```json5
{
@ -279,9 +279,9 @@ MiniMax TTS 的身份验证解析顺序是 `messages.tts.providers.minimax.apiKe
}
```
Google Gemini TTS 使用 Gemini API key 路径。限制为 Gemini API 的 Google Cloud Console API key 在这里也有效，并且它与内置 Google 图像生成提供商使用的是同一种 key。解析顺序为 `messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`。
Google Gemini TTS 使用 Gemini API key 路径。限制为 Gemini API 的 Google Cloud Console API key 在这里可用，并且它与内置的 Google 图像生成提供商使用的是同一类 key。解析顺序为 `messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`。
### Inworld 作为主提供商
### Inworld 主提供商
```json5
{
@ -303,9 +303,9 @@ Google Gemini TTS 使用 Gemini API key 路径。限制为 Gemini API 的 Google
}
```
`apiKey` 的值必须是从 Inworld 控制台逐字复制的 Base64 编码凭证字符串（Workspace > API Keys）。提供商会直接将其作为 `Authorization: Basic <apiKey>` 发送，而不会进行任何额外编码，因此不要传入原始 bearer token，也不要自行再次进行 Base64 编码。该 key 会回退到 `INWORLD_API_KEY` 环境变量。完整设置见 [Inworld provider](/zh-CN/providers/inworld)。
`apiKey` 的值必须是从 Inworld 控制台原样复制的 Base64 编码凭证字符串（Workspace > API Keys）。提供商会将其作为 `Authorization: Basic <apiKey>` 发送，不会做任何额外编码，因此不要传入原始 bearer token，也不要自行再次进行 Base64 编码。该 key 会回退到 `INWORLD_API_KEY` 环境变量。完整设置请参见 [Inworld provider](/zh-CN/providers/inworld)。
### Volcengine 作为主提供商
### Volcengine 主提供商
```json5
{
@ -326,9 +326,9 @@ Google Gemini TTS 使用 Gemini API key 路径。限制为 Gemini API 的 Google
}
```
Volcengine TTS 使用的是来自 Speech Console 的 BytePlus Seed Speech API key，而不是 Doubao 模型提供商使用的 OpenAI 兼容 `VOLCANO_ENGINE_API_KEY`。解析顺序为 `messages.tts.providers.volcengine.apiKey` -> `VOLCENGINE_TTS_API_KEY` -> `BYTEPLUS_SEED_SPEECH_API_KEY`。旧版 AppID/token 身份验证仍可通过 `messages.tts.providers.volcengine.appId` / `token` 或 `VOLCENGINE_TTS_APPID` / `VOLCENGINE_TTS_TOKEN` 使用。语音便笺目标会请求提供商原生的 `ogg_opus`；普通音频文件目标会请求 `mp3`。
Volcengine TTS 使用的是来自 Speech Console 的 BytePlus Seed Speech API key，而不是 Doubao 模型提供商所用的 OpenAI 兼容 `VOLCANO_ENGINE_API_KEY`。解析顺序为 `messages.tts.providers.volcengine.apiKey` -> `VOLCENGINE_TTS_API_KEY` -> `BYTEPLUS_SEED_SPEECH_API_KEY`。旧版 AppID/token 认证仍可通过 `messages.tts.providers.volcengine.appId` / `token` 或 `VOLCENGINE_TTS_APPID` / `VOLCENGINE_TTS_TOKEN` 使用。语音便笺目标会请求提供商原生的 `ogg_opus`；普通音频文件目标会请求 `mp3`。
### xAI 作为主提供商
### xAI 主提供商
```json5
{
@ -350,9 +350,9 @@ Volcengine TTS 使用的是来自 Speech Console 的 BytePlus Seed Speech API ke
}
```
xAI TTS 与内置的 Grok 模型提供商共用同一个 `XAI_API_KEY` 路径。解析顺序为 `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`。当前可用的实时语音有 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认值为 `eve`。`language` 接受 BCP-47 标签或 `auto`。
xAI TTS 与内置的 Grok 模型提供商共用同一条 `XAI_API_KEY` 路径。解析顺序为 `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`。当前可用的语音包括 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认值为 `eve`。`language` 接受 BCP-47 标签或 `auto`。
### Xiaomi MiMo 作为主提供商
### Xiaomi MiMo 主提供商
```json5
{
@ -367,7 +367,7 @@ xAI TTS 与内置的 Grok 模型提供商共用同一个 `XAI_API_KEY` 路径。
model: "mimo-v2.5-tts",
voice: "mimo_default",
format: "mp3",
style: "明亮、自然、对话式的语气。",
style: "Bright, natural, conversational tone.",
},
},
},
@ -375,9 +375,9 @@ xAI TTS 与内置的 Grok 模型提供商共用同一个 `XAI_API_KEY` 路径。
}
```
Xiaomi MiMo TTS 与内置 Xiaomi 模型提供商共用同一个 `XIAOMI_API_KEY` 路径。语音提供商 id 是 `xiaomi`；`mimo` 也可作为别名。目标文本会作为 assistant 消息发送，以匹配 Xiaomi 的 TTS 协议。可选的 `style` 会作为用户指令发送，不会被朗读出来。
Xiaomi MiMo TTS 与内置的 Xiaomi 模型提供商共用同一条 `XIAOMI_API_KEY` 路径。语音提供商 id 是 `xiaomi`；`mimo` 也可作为别名使用。目标文本会作为 assistant 消息发送，以匹配 Xiaomi 的 TTS 契约。可选的 `style` 会作为用户指令发送，不会被朗读出来。
### OpenRouter 作为主提供商
### OpenRouter 主提供商
```json5
{
@ -398,9 +398,9 @@ Xiaomi MiMo TTS 与内置 Xiaomi 模型提供商共用同一个 `XIAOMI_API_KEY`
}
```
OpenRouter TTS 与内置的 OpenRouter 模型提供商共用同一个 `OPENROUTER_API_KEY` 路径。解析顺序为 `messages.tts.providers.openrouter.apiKey` -> `models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。
OpenRouter TTS 与内置的 OpenRouter 模型提供商共用同一条 `OPENROUTER_API_KEY` 路径。解析顺序为 `messages.tts.providers.openrouter.apiKey` -> `models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。
### Local CLI 作为主提供商
### Local CLI 主提供商
```json5
{
@ -421,9 +421,9 @@ OpenRouter TTS 与内置的 OpenRouter 模型提供商共用同一个 `OPENROUTE
}
```
Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符会在 `args` 中展开；如果不存在 `{{Text}}` 占位符，OpenClaw 会将要朗读的文本写入 stdin。`outputFormat` 接受 `mp3`、`opus` 或 `wav`。语音便笺目标会被转码为 Ogg/Opus，电话输出会使用 `ffmpeg` 转码为原始 16 kHz 单声道 PCM。旧版提供商别名 `cli` 仍然可用，但新配置应使用 `tts-local-cli`。
Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符会在 `args` 中展开；如果不存在 `{{Text}}` 占位符，OpenClaw 会将要朗读的文本写入 stdin。`outputFormat` 接受 `mp3`、`opus` 或 `wav`。语音便笺目标会被转码为 Ogg/Opus，电话输出会使用 `ffmpeg` 转码为原始的 16 kHz 单声道 PCM。旧版提供商别名 `cli` 仍然可用，但新配置应使用 `tts-local-cli`。
### Gradium 作为主提供商
### Gradium 主提供商
```json5
{
@ -459,7 +459,7 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}}
}
```
### 自定义限制 + 偏好设置路径
### 自定义限制 + 偏好路径
```json5
{
@ -474,7 +474,7 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}}
}
```
### 仅在收到语音消息后用音频回复
### 仅在收到入站语音消息后用音频回复
```json5
{
@ -507,31 +507,31 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}}
### 字段说明
- `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。
- `inbound` 仅在收到语音消息后发送音频。
- `inbound` 仅在收到入站语音消息后发送音频。
- `tagged` 仅在回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。
- `enabled`：旧版开关（Doctor 会将其迁移到 `auto`）。
- `mode`：`"final"`（默认）或 `"all"`（包括工具/分块回复）。
- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"inworld"`、`"microsoft"`、`"minimax"`、`"openai"`、`"volcengine"`、`"vydra"`、`"xai"` 或 `"xiaomi"`（会自动回退）。
- 如果 `provider` **未设置**，OpenClaw 会按照注册表自动选择顺序，使用第一个已配置的语音提供商。
- `enabled`：旧版开关（`doctor` 会将其迁移到 `auto`）。
- `mode`：`"final"`（默认）或 `"all"`（包含工具/分块回复）。
- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"inworld"`、`"microsoft"`、`"minimax"`、`"openai"`、`"volcengine"`、`"vydra"`、`"xai"` 或 `"xiaomi"`（回退会自动处理）。
- 如果 `provider` **未设置**，OpenClaw 会按注册表自动选择顺序使用第一个已配置的语音提供商。
- 旧版 `provider: "edge"` 配置可由 `openclaw doctor --fix` 修复，并重写为 `provider: "microsoft"`。
- `summaryModel`：用于自动摘要的可选低成本模型；默认值为 `agents.defaults.model.primary`。
- 接受 `provider/model` 或已配置的模型别名。
- `modelOverrides`：允许模型输出 TTS 指令（默认开启）。
- `allowProvider` 默认为 `false`（切换提供商需要显式启用）。
- `providers.<id>`：按语音提供商 id 键控的、由提供商拥有的设置。
- 旧版直接提供商块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）可由 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.<id>`。
- 旧版 `messages.tts.providers.edge` 也可由 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.microsoft`。
- `maxTextLength`：TTS 输入的硬性上限（字符数）。超过时，`/tts audio` 会失败。
- `providers.<id>`：由提供商自行拥有的设置，以语音提供商 id 为键。
- 旧版直接提供商块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）可由 `openclaw doctor --fix` 修复；提交到仓库的配置应使用 `messages.tts.providers.<id>`。
- 旧版 `messages.tts.providers.edge` 也可由 `openclaw doctor --fix` 修复；提交到仓库的配置应使用 `messages.tts.providers.microsoft`。
- `maxTextLength`：TTS 输入的硬上限（字符数）。超过时，`/tts audio` 会失败。
- `timeoutMs`：请求超时（毫秒）。
- `prefsPath`：覆盖本地偏好设置 JSON 路径（提供商/限制/摘要）。
- `apiKey` 值会回退到环境变量（`AZURE_SPEECH_KEY`/`AZURE_SPEECH_API_KEY`/`SPEECH_KEY`、`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`INWORLD_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`、`XIAOMI_API_KEY`）。Volcengine 则使用 `appId`/`token`。
- `prefsPath`：覆盖本地偏好 JSON 路径（提供商/限制/摘要）。
- `apiKey` 值会回退到环境变量（`AZURE_SPEECH_KEY` / `AZURE_SPEECH_API_KEY` / `SPEECH_KEY`、`ELEVENLABS_API_KEY` / `XI_API_KEY`、`GEMINI_API_KEY` / `GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`INWORLD_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`、`XIAOMI_API_KEY`）。Volcengine 改用 `appId` / `token`。
- `providers.azure-speech.apiKey`：Azure Speech 资源 key（环境变量：`AZURE_SPEECH_KEY`、`AZURE_SPEECH_API_KEY` 或 `SPEECH_KEY`）。
- `providers.azure-speech.region`：Azure Speech 区域，例如 `eastus`（环境变量：`AZURE_SPEECH_REGION` 或 `SPEECH_REGION`）。
- `providers.azure-speech.endpoint` / `providers.azure-speech.baseUrl`：可选的 Azure Speech endpoint/base URL 覆盖值。
- `providers.azure-speech.endpoint` / `providers.azure-speech.baseUrl`：可选的 Azure Speech endpoint/base URL 覆盖。
- `providers.azure-speech.voice`：Azure 语音 ShortName（默认 `en-US-JennyNeural`）。
- `providers.azure-speech.lang`：SSML 语言代码（默认 `en-US`）。
- `providers.azure-speech.outputFormat`：用于标准音频输出的 Azure `X-Microsoft-OutputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。
- `providers.azure-speech.voiceNoteOutputFormat`：用于语音便笺输出的 Azure `X-Microsoft-OutputFormat`（默认 `ogg-24khz-16bit-mono-opus`）。
- `providers.azure-speech.outputFormat`：标准音频输出的 Azure `X-Microsoft-OutputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。
- `providers.azure-speech.voiceNoteOutputFormat`：语音便笺输出的 Azure `X-Microsoft-OutputFormat`（默认 `ogg-24khz-16bit-mono-opus`）。
- `providers.elevenlabs.baseUrl`：覆盖 ElevenLabs API base URL。
- `providers.openai.baseUrl`：覆盖 OpenAI TTS endpoint。
- 解析顺序：`messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1`
@ -548,38 +548,38 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}}
- `providers.minimax.voiceId`：语音标识符（默认 `English_expressive_narrator`，环境变量：`MINIMAX_TTS_VOICE_ID`）。
- `providers.minimax.speed`：播放速度 `0.5..2.0`（默认 1.0）。
- `providers.minimax.vol`：音量 `(0, 10]`（默认 1.0；必须大于 0）。
- `providers.minimax.pitch`：整数音高偏移 `-12..12`（默认 0）。在调用 MiniMax T2A 之前，小数值会被截断，因为 API 会拒绝非整数音高值。
- `providers.minimax.pitch`：整数音高偏移 `-12..12`（默认 0）。在调用 MiniMax T2A 之前，小数值会被截断，因为 API 拒绝非整数的音高值。
- `providers.tts-local-cli.command`：用于 CLI TTS 的本地可执行文件或命令字符串。
- `providers.tts-local-cli.args`：命令参数；支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符。
- `providers.tts-local-cli.outputFormat`：预期的 CLI 输出格式（`mp3`、`opus` 或 `wav`；音频附件默认 `mp3`）。
- `providers.tts-local-cli.timeoutMs`：命令超时，单位毫秒（默认 `120000`）。
- `providers.tts-local-cli.outputFormat`：预期的 CLI 输出格式（`mp3`、`opus` 或 `wav`；音频附件默认值为 `mp3`）。
- `providers.tts-local-cli.timeoutMs`：命令超时时间（毫秒，默认 `120000`）。
- `providers.tts-local-cli.cwd`：可选的命令工作目录。
- `providers.tts-local-cli.env`：命令的可选字符串环境变量覆盖值。
- `providers.tts-local-cli.env`：命令的可选字符串环境变量覆盖。
- `providers.inworld.baseUrl`：覆盖 Inworld API base URL（默认 `https://api.inworld.ai`）。
- `providers.inworld.voiceId`：Inworld 语音标识符（默认 `Sarah`）。
- `providers.inworld.modelId`：Inworld TTS 模型（默认 `inworld-tts-1.5-max`；也支持 `inworld-tts-1.5-mini`、`inworld-tts-1-max`、`inworld-tts-1`）。
- `providers.inworld.temperature`：采样温度 `0..2`（可选）。
- `providers.google.model`：Gemini TTS 模型（默认 `gemini-3.1-flash-tts-preview`）。
- `providers.google.voiceName`：Gemini 预置语音名称（默认 `Kore`；也接受 `voice`）。
- `providers.google.audioProfile`：会添加在朗读文本前的自然语言风格提示。
- `providers.google.speakerName`：可选说话人标签；当你的 TTS 提示使用具名说话人时，会添加在朗读文本前。
- `providers.google.audioProfile`：在朗读文本前添加的自然语言风格提示。
- `providers.google.speakerName`：当你的 TTS 提示使用命名说话人时，在朗读文本前添加的可选说话人标签。
- `providers.google.baseUrl`：覆盖 Gemini API base URL。仅接受 `https://generativelanguage.googleapis.com`。
- 如果省略 `messages.tts.providers.google.apiKey`，TTS 可在回退到环境变量之前复用 `models.providers.google.apiKey`。
- 如果省略 `messages.tts.providers.google.apiKey`，TTS 可以先复用 `models.providers.google.apiKey`，再回退到环境变量。
- `providers.gradium.baseUrl`：覆盖 Gradium API base URL（默认 `https://api.gradium.ai`）。
- `providers.gradium.voiceId`：Gradium 语音标识符（默认 Emma，`YTpq7expH9539ERJ`）。
- `providers.volcengine.apiKey`：BytePlus Seed Speech API key（环境变量：`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`）。
- `providers.volcengine.resourceId`：BytePlus Seed Speech resource id（默认 `seed-tts-1.0`，环境变量：`VOLCENGINE_TTS_RESOURCE_ID`；当你的 BytePlus 项目具有 TTS 2.0 权限时，请使用 `seed-tts-2.0`）。
- `providers.volcengine.resourceId`：BytePlus Seed Speech 资源 id（默认 `seed-tts-1.0`，环境变量：`VOLCENGINE_TTS_RESOURCE_ID`；如果你的 BytePlus 项目具备 TTS 2.0 权限，请使用 `seed-tts-2.0`）。
- `providers.volcengine.appKey`：BytePlus Seed Speech app key 请求头（默认 `aGjiRDfUWi`，环境变量：`VOLCENGINE_TTS_APP_KEY`）。
- `providers.volcengine.baseUrl`：覆盖 Seed Speech TTS HTTP endpoint（环境变量：`VOLCENGINE_TTS_BASE_URL`）。
- `providers.volcengine.appId`：旧版 Volcengine Speech Console application id（环境变量：`VOLCENGINE_TTS_APPID`）。
- `providers.volcengine.token`：旧版 Volcengine Speech Console access token（环境变量：`VOLCENGINE_TTS_TOKEN`）。
- `providers.volcengine.cluster`：旧版 Volcengine TTS cluster（默认 `volcano_tts`，环境变量：`VOLCENGINE_TTS_CLUSTER`）。
- `providers.volcengine.appId`：旧版 Volcengine Speech Console 应用 id（环境变量：`VOLCENGINE_TTS_APPID`）。
- `providers.volcengine.token`：旧版 Volcengine Speech Console 访问令牌（环境变量：`VOLCENGINE_TTS_TOKEN`）。
- `providers.volcengine.cluster`：旧版 Volcengine TTS 集群（默认 `volcano_tts`，环境变量：`VOLCENGINE_TTS_CLUSTER`）。
- `providers.volcengine.voice`：语音类型（默认 `en_female_anna_mars_bigtts`，环境变量：`VOLCENGINE_TTS_VOICE`）。
- `providers.volcengine.speedRatio`：提供商原生速度比率。
- `providers.volcengine.speedRatio`：提供商原生速度比例。
- `providers.volcengine.emotion`：提供商原生情感标签。
- `providers.xai.apiKey`：xAI TTS API key（环境变量：`XAI_API_KEY`）。
- `providers.xai.baseUrl`：覆盖 xAI TTS base URL（默认 `https://api.x.ai/v1`，环境变量：`XAI_BASE_URL`）。
- `providers.xai.voiceId`：xAI 语音 id（默认 `eve`；当前可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。
- `providers.xai.voiceId`：xAI 语音 id（默认 `eve`；当前在线语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。
- `providers.xai.language`：BCP-47 语言代码或 `auto`（默认 `en`）。
- `providers.xai.responseFormat`：`mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`（默认 `mp3`）。
- `providers.xai.speed`：提供商原生速度覆盖值。
@ -588,36 +588,37 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}}
- `providers.xiaomi.model`：TTS 模型（默认 `mimo-v2.5-tts`，环境变量：`XIAOMI_TTS_MODEL`；也支持 `mimo-v2-tts`）。
- `providers.xiaomi.voice`：MiMo 语音 id（默认 `mimo_default`，环境变量：`XIAOMI_TTS_VOICE`）。
- `providers.xiaomi.format`：`mp3` 或 `wav`（默认 `mp3`，环境变量：`XIAOMI_TTS_FORMAT`）。
- `providers.xiaomi.style`：可选的自然语言风格指令，会作为用户消息发送；不会被朗读。
- `providers.openrouter.apiKey`：OpenRouter API key（环境变量：`OPENROUTER_API_KEY`；可复用 `models.providers.openrouter.apiKey`）。
- `providers.openrouter.baseUrl`：覆盖 OpenRouter TTS base URL（默认 `https://openrouter.ai/api/v1`；旧版 `https://openrouter.ai/v1` 会被规范化）。
- `providers.xiaomi.style`：可选的自然语言风格指令，会作为 user 消息发送；不会被朗读。
- `providers.openrouter.apiKey`：OpenRouter API key（环境变量：`OPENROUTER_API_KEY`；也可复用 `models.providers.openrouter.apiKey`）。
- `providers.openrouter.baseUrl`：覆盖 OpenRouter TTS base URL（默认 `https://openrouter.ai/api/v1`；旧版 `https://openrouter.ai/v1` 会被标准化）。
- `providers.openrouter.model`：OpenRouter TTS 模型 id（默认 `hexgrad/kokoro-82m`；也接受 `modelId`）。
- `providers.openrouter.voice`：提供商特定的语音 id（默认 `af_alloy`；也接受 `voiceId`）。
- `providers.openrouter.voice`：提供商专用语音 id（默认 `af_alloy`；也接受 `voiceId`）。
- `providers.openrouter.responseFormat`：`mp3` 或 `pcm`（默认 `mp3`）。
- `providers.openrouter.speed`：提供商原生速度覆盖值。
- `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；不需要 API key）。
- `providers.microsoft.voice`：Microsoft 神经网络语音名称（例如 `en-US-MichelleNeural`）。
- `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；无需 API key）。
- `providers.microsoft.voice`：Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。
- `providers.microsoft.lang`：语言代码（例如 `en-US`）。
- `providers.microsoft.outputFormat`：Microsoft 输出格式（例如 `audio-24khz-48kbitrate-mono-mp3`）。
- 有效值请参见 Microsoft Speech output formats；并非所有格式都受内置的基于 Edge 的传输支持。
- 有效值请参见 Microsoft Speech 输出格式；并非所有格式都受内置的 Edge 后端传输支持。
- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`：百分比字符串（例如 `+10%`、`-5%`）。
- `providers.microsoft.saveSubtitles`：在音频文件旁写入 JSON 字幕。
- `providers.microsoft.saveSubtitles`：在音频文件旁边写入 JSON 字幕。
- `providers.microsoft.proxy`：Microsoft 语音请求的代理 URL。
- `providers.microsoft.timeoutMs`：请求超时覆盖值（毫秒）。
- `edge.*`：同一组 Microsoft 设置的旧版别名。运行 `openclaw doctor --fix` 可将持久化配置重写为 `providers.microsoft`。
## 模型驱动的覆盖（默认开启）
默认情况下，模型**可以**为单条回复输出 TTS 指令。
当 `messages.tts.auto` 为 `tagged` 时，必须有这些指令才会触发音频。
默认情况下，模型**可以**为单条回复输出 TTS 指令。
当 `messages.tts.auto` 为 `tagged` 时，这些指令是触发音频所必需的。
启用后，模型可以输出 `[[tts:...]]` 指令来覆盖单条回复的语音设置，还可以选择输出 `[[tts:text]]...[[/tts:text]]` 块，以提供只应出现在音频中的表现性标签（笑声、歌唱提示等）。
启用后，模型可以输出 `[[tts:...]]` 指令来为单条回复覆盖语音设置，还可以选择使用 `[[tts:text]]...[[/tts:text]]` 块提供仅应出现在音频中的表现性标签（笑声、歌唱提示等）。
分块流式传输在把内容交给渠道之前，会从可见文本中剥离这些指令，即使某条指令被拆分在相邻分块之间也是如此。最终模式仍会解析累计的原始回复以进行 TTS 合成。
分块流式传输会在渠道看到文本之前，从可见文本中移除这些指令，即使某条指令被拆分到相邻的多个块中也是如此。最终模式仍会解析累积后的原始回复，以进行 TTS 合成。
除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。
除非设置 `modelOverrides.allowProvider: true`，否则会忽略 `provider=...` 指令。
当回复声明 `provider=...` 时，该指令中的其他键只会由该提供商解析。不受支持的键会从可见文本中移除，并作为 TTS 指令警告报告，而不会被路由到其他提供商。
示例回复载荷：
回复负载示例：
```
Here you go.
@ -630,10 +631,10 @@ Here you go.
- `provider`（已注册的语音提供商 id，例如 `openai`、`elevenlabs`、`google`、`gradium`、`minimax`、`microsoft`、`volcengine`、`vydra`、`xai` 或 `xiaomi`；需要 `allowProvider: true`）
- `voice`（OpenAI、Gradium、Volcengine 或 Xiaomi 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音），或 `voiceId`（ElevenLabs / Gradium / MiniMax / xAI）
- `model`（OpenAI TTS 模型、ElevenLabs model id、MiniMax 模型或 Xiaomi MiMo TTS 模型）或 `google_model`（Google TTS 模型）
- `model`（OpenAI TTS 模型、ElevenLabs 模型 id、MiniMax 模型或 Xiaomi MiMo TTS 模型）或 `google_model`（Google TTS 模型）
- `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost`
- `vol` / `volume`（MiniMax 音量，0-10）
- `pitch`（MiniMax 整数音高，-12 到 12；小数值会在发起 MiniMax 请求前被截断）
- `pitch`（MiniMax 整数音高，-12 到 12；在发起 MiniMax 请求前，小数值会被截断）
- `emotion`（Volcengine 情感标签）
- `applyTextNormalization`（`auto|on|off`）
- `languageCode`（ISO 639-1）
@ -653,7 +654,7 @@ Here you go.
}
```
可选允许列表（启用提供商切换，同时保持其他参数仍可配置）：
可选允许列表（启用提供商切换，同时保留其他参数可配置）：
```json5
{
@ -671,9 +672,7 @@ Here you go.
## 按用户的偏好设置
斜杠命令会将本地覆盖写入 `prefsPath`（默认：
`~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或
`messages.tts.prefsPath` 覆盖）。
斜杠命令会将本地覆盖写入 `prefsPath`（默认：`~/.openclaw/settings/tts.json`，可用 `OPENCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。
存储字段：
@ -682,31 +681,27 @@ Here you go.
- `maxLength`（摘要阈值；默认 1500 个字符）
- `summarize`（默认 `true`）
这些字段会覆盖该主机上由 `messages.tts` 加上当前激活的
`agents.list[].tts` 配置块得出的最终配置。
这些字段会覆盖该主机上 `messages.tts` 加上当前激活的 `agents.list[].tts` 配置块形成的最终配置。
## 输出格式（固定）
- **Feishu / Matrix / Telegram / WhatsApp**：语音便笺回复优先使用 Opus（ElevenLabs 使用 `opus_48000_64`，OpenAI 使用 `opus`）。
- 48 kHz / 64 kbps 是语音消息较好的平衡方案。
- **Feishu / WhatsApp**：当语音便笺回复生成为 MP3/WebM/WAV/M4A
或其他常见音频文件时，渠道插件会在发送原生语音消息前，使用 `ffmpeg` 将其转码为 48 kHz
Ogg/Opus。WhatsApp 会通过 Baileys 的 `audio` 载荷并设置 `ptt: true` 和
`audio/ogg; codecs=opus` 发送结果。如果转换失败，Feishu 会收到原始文件作为附件；WhatsApp 发送会失败，而不是发布不兼容的 PTT 载荷。
- 48 kHz / 64 kbps 是语音消息中较好的折中方案。
- **Feishu / WhatsApp**：当语音便笺回复被生成为 MP3/WebM/WAV/M4A 或其他可能的音频文件时，渠道插件会在发送原生语音消息前，使用 `ffmpeg` 将其转码为 48 kHz 的 Ogg/Opus。WhatsApp 通过 Baileys 的 `audio` 负载，配合 `ptt: true` 和 `audio/ogg; codecs=opus` 发送结果。如果转换失败，Feishu 会收到原始文件作为附件；WhatsApp 发送会失败，而不是发布不兼容的 PTT 负载。
- **其他渠道**：MP3（ElevenLabs 使用 `mp3_44100_128`，OpenAI 使用 `mp3`）。
- 44.1 kHz / 128 kbps 是语音清晰度的默认平衡。
- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu、Telegram 和 WhatsApp 等语音便笺目标，OpenClaw 会在交付前使用 `ffmpeg` 将 MiniMax 的 MP3 转码为 48 kHz Opus。
- **Xiaomi MiMo**：默认使用 MP3，配置后也可使用 WAV。对于 Feishu、Telegram 和 WhatsApp 等语音便笺目标，OpenClaw 会在交付前使用 `ffmpeg` 将 Xiaomi 输出转码为 48 kHz Opus。
- 44.1 kHz / 128 kbps 是语音清晰度的默认平衡点。
- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu、Telegram 和 WhatsApp 等语音便笺目标，OpenClaw 会在投递前使用 `ffmpeg` 将 MiniMax MP3 转码为 48 kHz Opus。
- **Xiaomi MiMo**：默认使用 MP3，配置时也可使用 WAV。对于 Feishu、Telegram 和 WhatsApp 等语音便笺目标，OpenClaw 会在投递前使用 `ffmpeg` 将 Xiaomi 输出转码为 48 kHz Opus。
- **Local CLI**：使用配置的 `outputFormat`。语音便笺目标会被转换为 Ogg/Opus，电话输出会使用 `ffmpeg` 转换为原始 16 kHz 单声道 PCM。
- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于音频附件，为语音便笺目标转码为 48 kHz Opus，并直接为 Talk/电话返回 PCM。
- **Gradium**：音频附件使用 WAV，语音便笺目标使用 Opus，电话使用 8 kHz 的 `ulaw_8000`。
- **Inworld**：普通音频附件使用 MP3，语音便笺目标使用原生 `OGG_OPUS`，Talk/电话使用 22050 Hz 的原始 `PCM`。
- **xAI**：默认使用 MP3；`responseFormat` 可设为 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批处理 REST TTS endpoint，并返回完整音频附件；此提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便笺格式。
- **xAI**：默认使用 MP3；`responseFormat` 可以是 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批量 REST TTS endpoint，并返回完整音频附件；该提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便笺格式。
- **Microsoft**：使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。
- 内置传输支持 `outputFormat`，但服务并不提供所有格式。
- 输出格式值遵循 Microsoft Speech output formats（包括 Ogg/WebM Opus）。
- 内置传输接受 `outputFormat`，但并非所有格式都能从该服务获得。
- 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。
- Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保障的 Opus 语音消息，请使用 OpenAI/ElevenLabs。
- 如果配置的 Microsoft 输出格式失败，OpenClaw 会回退重试 MP3。
- 如果配置的 Microsoft 输出格式失败，OpenClaw 会回退并重试为 MP3。
OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。
@ -714,12 +709,12 @@ OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。
启用后，OpenClaw 会：
- 如果回复已经包含媒体或 `MEDIA:` 指令，则跳过 TTS。
- 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。
- 跳过过短的回复（少于 10 个字符）。
- 启用时，使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复进行摘要。
- 当启用时，使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复生成摘要。
- 将生成的音频附加到回复中。
如果回复超过 `maxLength`，且摘要已关闭（或摘要模型没有 API key），则会跳过音频，仅发送普通文本回复。
如果回复超过 `maxLength` 且摘要功能关闭（或摘要模型没有 API key），则会跳过音频，仅发送普通文本回复。
## 流程图
@ -738,11 +733,10 @@ Reply -> TTS enabled?
## 斜杠命令用法
只有一个命令：`/tts`。
启用详情见 [斜杠命令](/zh-CN/tools/slash-commands)。
只有一个命令：`/tts`。
启用细节请参见 [斜杠命令](/zh-CN/tools/slash-commands)。
Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那里注册
`/voice` 作为原生命令。不过文本形式的 `/tts ...` 仍然可用。
Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那里注册 `/voice` 作为原生命令。文本形式的 `/tts ...` 仍然可用。
```
/tts off
@ -760,29 +754,28 @@ Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那
说明：
- 命令需要已授权的发送者（仍适用 allowlist/owner 规则）。
- 命令需要已授权的发送者（仍然适用 allowlist/owner 规则）。
- 必须启用 `commands.text` 或原生命令注册。
- 配置 `messages.tts.auto` 接受 `off|always|inbound|tagged`。
- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会写为 `off`。
- `/tts chat on|off|default` 会为当前聊天写入会话范围的自动 TTS 覆盖。
- 当你想要 `inbound` 或 `tagged` 作为默认值时，请使用配置。
- `limit` 和 `summary` 存储在本地偏好设置中，而不是主配置中。
- `/tts audio` 会生成一次性的音频回复（不会开启 TTS）。
- `/tts latest` 会从当前会话记录中读取最新的 assistant 回复，并将其作为音频发送一次。它只会在会话条目上存储该回复的哈希，以防止重复发送语音。
- `/tts status` 会包含最近一次尝试的回退可见性：
- 如果你想使用 `inbound` 或 `tagged` 作为默认值，请使用配置。
- `limit` 和 `summary` 存储在本地偏好中，而不是主配置中。
- `/tts audio` 会生成一次性音频回复（不会切换 TTS 开关为开启）。
- `/tts latest` 会从当前会话记录中读取最新的 assistant 回复，并将其作为音频发送一次。它只会在会话条目上存储该回复的哈希值，以抑制重复发送语音。
- `/tts status` 包含最近一次尝试的回退可见性：
- 成功回退：`Fallback: <primary> -> <used>` 加上 `Attempts: ...`
- 失败：`Error: ...` 加上 `Attempts: ...`
- 详细诊断：`Attempt details: provider:outcome(reasonCode) latency`
- 当启用 TTS 时，`/status` 会显示当前 TTS 模式，以及已配置的提供商、模型、语音和已脱敏的自定义 endpoint 元数据。
- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（如果提供商返回），并会在 TTS 错误/日志中显示。
- 当启用 TTS 时，`/status` 会显示当前激活的 TTS 模式，以及已配置的提供商、模型、语音和已脱敏的自定义 endpoint 元数据。
- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误细节和请求 id（当提供商返回时），并会在 TTS 错误/日志中显示。
## 智能体工具
`tts` 工具会将文本转换为语音，并返回用于回复交付的音频附件。当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会作为语音消息而不是文件附件发送。
当 `ffmpeg` 可用时，Feishu 和 WhatsApp 在此路径上可以对非 Opus 的 TTS 输出进行转码。
WhatsApp 通过 Baileys 以 PTT 语音便笺形式发送音频（`audio` 配合
`ptt: true`），并将可见文本与 PTT 音频分开发送，因为客户端并不总能正确显示语音便笺的说明文字。
它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是单次调用的提供商请求超时，单位为毫秒。
`tts` 工具会将文本转换为语音，并返回用于回复投递的音频附件。当渠道是 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会作为语音消息而不是文件附件投递。
在这一路径中，如果可用 `ffmpeg`，Feishu 和 WhatsApp 可以对非 Opus 的 TTS 输出进行转码。
WhatsApp 通过 Baileys 以 PTT 语音便笺形式发送音频（带有 `ptt: true` 的 `audio`），并将可见文本与 PTT 音频分开发送，因为客户端对语音便笺标题的显示并不总是一致。
它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是按调用设置的提供商请求超时时间，单位为毫秒。
## Gateway 网关 RPC