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-21 08:28:19 +00:00
parent 6299024ded
commit 7fadfc729c
7 changed files with 1048 additions and 1183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

261
docs/zh-CN/channels/slack.md
View File

@ -1,20 +1,20 @@
---
read_when:
- 设置 Slack 或调试 Slack socket/HTTP 模式
- 设置 Slack 或排查 Slack socket/HTTP 模式问题
summary: Slack 设置和运行时行为（Socket Mode + HTTP Request URLs）
title: Slack
x-i18n:
generated_at: "2026-04-12T06:50:10Z"
generated_at: "2026-04-21T08:24:18Z"
model: gpt-5.4
provider: openai
source_hash: 4b80c1a612b8815c46c675b688639c207a481f367075996dde3858a83637313b
source_hash: 2fe3c3c344e1c20c09b29773f4f68d2790751e76d8bbaa3c6157e3ff75978acf
source_path: channels/slack.md
workflow: 15
---
# Slack
状态：已可用于生产环境，支持通过 Slack 应用集成进行私信和渠道。默认模式为 Socket Mode；也支持 HTTP Request URLs。
状态：通过 Slack 应用集成实现了可用于私信和渠道的生产就绪支持。默认模式为 Socket Mode；也支持 HTTP Request URLs。
<CardGroup cols={3}>
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
@ -28,17 +28,17 @@ x-i18n:
</Card>
</CardGroup>
## 快速设置
## 快速开始
<Tabs>
<Tab title="Socket Mode（默认）">
<Steps>
<Step title="创建一个新的 Slack 应用">
<Step title="创建新的 Slack 应用">
在 Slack 应用设置中，点击 **[Create New App](https://api.slack.com/apps/new)** 按钮：
- 选择 **from a manifest**，并为你的应用选择一个工作区
- 粘贴下面的[示例清单](#manifest-and-scope-checklist)，然后继续创建
- 生成一个具有 `connections:write` 权限的 **App-Level Token**（`xapp-...`）
- 生成一个带有 `connections:write` 权限的 **App-Level Token**（`xapp-...`）
- 安装应用，并复制显示的 **Bot Token**（`xoxb-...`）
</Step>
@ -79,12 +79,12 @@ openclaw gateway
<Tab title="HTTP Request URLs">
<Steps>
<Step title="创建一个新的 Slack 应用">
<Step title="创建新的 Slack 应用">
在 Slack 应用设置中，点击 **[Create New App](https://api.slack.com/apps/new)** 按钮：
- 选择 **from a manifest**，并为你的应用选择一个工作区
- 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL
- 保存用于请求校验的 **Signing Secret**
- 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新其中的 URL
- 保存用于请求验证的 **Signing Secret**
- 安装应用，并复制显示的 **Bot Token**（`xoxb-...`）
</Step>
@ -106,9 +106,9 @@ openclaw gateway
```
<Note>
对多账户 HTTP 使用唯一的 webhook 路径
为多账户 HTTP 使用唯一的 webhook 路径
为每个账户指定不同的 `webhookPath`（默认为 `/slack/events`），以避免注册冲突。
为每个账户指定不同的 `webhookPath`（默认是 `/slack/events`），以避免注册冲突。
</Note>
</Step>
@ -134,7 +134,7 @@ openclaw gateway
{
"display_information": {
"name": "OpenClaw",
"description": "OpenClaw 的 Slack 连接器"
"description": "用于 OpenClaw 的 Slack 连接器"
},
"features": {
"bot_user": {
@ -211,7 +211,7 @@ openclaw gateway
{
"display_information": {
"name": "OpenClaw",
"description": "OpenClaw 的 Slack 连接器"
"description": "用于 OpenClaw 的 Slack 连接器"
},
"features": {
"bot_user": {
@ -291,12 +291,12 @@ openclaw gateway
### 其他清单设置
展示扩展上述默认配置的不同功能。
展示可扩展上述默认设置的不同功能。
<AccordionGroup>
<Accordion title="可选原生斜杠命令">
可以使用多个[原生斜杠命令](#commands-and-slash-behavior)来替代单个已配置命令，但需要注意一些细节：
可以使用多个[原生斜杠命令](#commands-and-slash-behavior)来替代单个已配置命令，但有一些细节需要注意：
- 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已被保留。
- 同时最多只能提供 25 个斜杠命令。
@ -310,7 +310,7 @@ openclaw gateway
"slash_commands": [
{
"command": "/new",
"description": "开始一个新会话",
"description": "开始新的会话",
"usage_hint": "[model]"
},
{
@ -329,12 +329,12 @@ openclaw gateway
{
"command": "/session",
"description": "管理线程绑定过期时间",
"usage_hint": "idle <duration|off> 或 max-age <duration|off>"
"usage_hint": "idle <duration|off> or max-age <duration|off>"
},
{
"command": "/think",
"description": "设置思考级别",
"usage_hint": "<off|minimal|low|medium|high|xhigh>"
"usage_hint": "<level>"
},
{
"command": "/verbose",
@ -381,16 +381,16 @@ openclaw gateway
},
{
"command": "/tools",
"description": "显示当前智能体此刻可以使用的内容",
"description": "显示当前智能体现在可以使用什么",
"usage_hint": "[compact|verbose]"
},
{
"command": "/agentstatus",
"description": "显示运行时状态，包括可用时的提供商使用情况/配额"
"description": "显示运行时状态，包括可用时的提供商用量/配额"
},
{
"command": "/tasks",
"description": "列出当前会话中活跃/最近的后台任务"
"description": "列出当前会话的活动/最近后台任务"
},
{
"command": "/context",
@ -403,17 +403,17 @@ openclaw gateway
},
{
"command": "/skill",
"description": "按名称运行一个 Skill",
"description": "按名称运行一个 skill",
"usage_hint": "<name> [input]"
},
{
"command": "/btw",
"description": "提出一个旁支问题而不改变会话上下文",
"description": "在不更改会话上下文的情况下提出附带问题",
"usage_hint": "<question>"
},
{
"command": "/usage",
"description": "控制 usage 页脚或显示成本摘要",
"description": "控制用量页脚或显示成本摘要",
"usage_hint": "off|tokens|full|cost"
}
]
@ -426,7 +426,7 @@ openclaw gateway
"slash_commands": [
{
"command": "/new",
"description": "开始一个新会话",
"description": "开始新的会话",
"usage_hint": "[model]",
"url": "https://gateway-host.example.com/slack/events"
},
@ -449,13 +449,13 @@ openclaw gateway
{
"command": "/session",
"description": "管理线程绑定过期时间",
"usage_hint": "idle <duration|off> 或 max-age <duration|off>",
"usage_hint": "idle <duration|off> or max-age <duration|off>",
"url": "https://gateway-host.example.com/slack/events"
},
{
"command": "/think",
"description": "设置思考级别",
"usage_hint": "<off|minimal|low|medium|high|xhigh>",
"usage_hint": "<level>",
"url": "https://gateway-host.example.com/slack/events"
},
{
@ -512,18 +512,18 @@ openclaw gateway
},
{
"command": "/tools",
"description": "显示当前智能体此刻可以使用的内容",
"description": "显示当前智能体现在可以使用什么",
"usage_hint": "[compact|verbose]",
"url": "https://gateway-host.example.com/slack/events"
},
{
"command": "/agentstatus",
"description": "显示运行时状态，包括可用时的提供商使用情况/配额",
"description": "显示运行时状态，包括可用时的提供商用量/配额",
"url": "https://gateway-host.example.com/slack/events"
},
{
"command": "/tasks",
"description": "列出当前会话中活跃/最近的后台任务",
"description": "列出当前会话的活动/最近后台任务",
"url": "https://gateway-host.example.com/slack/events"
},
{
@ -539,19 +539,19 @@ openclaw gateway
},
{
"command": "/skill",
"description": "按名称运行一个 Skill",
"description": "按名称运行一个 skill",
"usage_hint": "<name> [input]",
"url": "https://gateway-host.example.com/slack/events"
},
{
"command": "/btw",
"description": "提出一个旁支问题而不改变会话上下文",
"description": "在不更改会话上下文的情况下提出附带问题",
"usage_hint": "<question>",
"url": "https://gateway-host.example.com/slack/events"
},
{
"command": "/usage",
"description": "控制 usage 页脚或显示成本摘要",
"description": "控制用量页脚或显示成本摘要",
"usage_hint": "off|tokens|full|cost",
"url": "https://gateway-host.example.com/slack/events"
}
@ -563,12 +563,12 @@ openclaw gateway
</Accordion>
<Accordion title="可选作者身份作用域（写入操作）">
如果你希望发出的消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。
如果你希望出站消息使用当前智能体身份（自定义用户名和图标），而不是默认 Slack 应用身份，请添加 `chat:write.customize` bot scope。
如果你使用 emoji 图标，Slack 需要 `:emoji_name:` 语法。
如果你使用 emoji 图标，Slack 要求采用 `:emoji_name:` 语法。
</Accordion>
<Accordion title="可选用户令牌作用域（读取操作）">
<Accordion title="可选 user-token 作用域（读取操作）">
如果你配置了 `channels.slack.userToken`，典型的读取作用域包括：
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
@ -587,19 +587,19 @@ openclaw gateway
- Socket Mode 需要 `botToken` + `appToken`。
- HTTP 模式需要 `botToken` + `signingSecret`。
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。
- 配置中的令牌会覆盖环境变量回退。
- 配置中的令牌会覆盖环境变量回退值。
- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账户。
- `userToken`（`xoxp-...`）仅支持通过配置设置（无环境变量回退），并且默认是只读行为（`userTokenReadOnly: true`）。
- `userToken`（`xoxp-...`）仅支持在配置中设置（没有环境变量回退），并且默认是只读行为（`userTokenReadOnly: true`）。
状态快照行为：
- Slack 账户检查会跟踪每个凭证对应的 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。
- 状态值可以是 `available`、`configured_unavailable` 或 `missing`。
- `configured_unavailable` 表示该账户通过 SecretRef 或其他非内联密钥源完成了配置，但当前命令/运行时路径无法解析出实际值。
- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，所需配对是 `botTokenStatus` + `appTokenStatus`。
- 状态值为 `available`、`configured_unavailable` 或 `missing`。
- `configured_unavailable` 表示该账户通过 SecretRef 或其他非内联密钥源进行了配置，但当前命令/运行时路径无法解析出实际值。
- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，所需的配对是 `botTokenStatus` + `appTokenStatus`。
<Tip>
对于 actions/目录读取，如果已配置，可以优先使用用户令牌。对于写入，仍优先使用 bot 令牌；只有在 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。
对于 actions/目录读取，如果已配置 user token，则可以优先使用它。对于写入，仍优先使用 bot token；只有在 `userTokenReadOnly: false` 且 bot token 不可用时，才允许使用 user-token 写入。
</Tip>
## Actions 和门控
@ -608,13 +608,13 @@ Slack actions 由 `channels.slack.actions.*` 控制。
当前 Slack 工具中的可用 action 分组：
| 分组 | 默认值 |
| --------- | ------ |
| messages | enabled |
| reactions | enabled |
| pins | enabled |
| Group | Default |
| ---------- | ------- |
| messages | enabled |
| reactions | enabled |
| pins | enabled |
| memberInfo | enabled |
| emojiList | enabled |
| emojiList | enabled |
当前 Slack 消息 actions 包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。
@ -631,19 +631,19 @@ Slack actions 由 `channels.slack.actions.*` 控制。
私信标志：
- `dm.enabled`（默认 true）
- `dm.enabled`（默认为 true）
- `channels.slack.allowFrom`（推荐）
- `dm.allowFrom`（旧版）
- `dm.groupEnabled`（群组私信默认为 false）
- `dm.groupChannels`（可选的 MPIM allowlist）
- `dm.groupChannels`（可选 MPIM allowlist）
多账户优先级：
- `channels.slack.accounts.default.allowFrom` 仅适用于 `default` 账户。
- 如果命名账户自身未设置 `allowFrom`，则会继承 `channels.slack.allowFrom`。
- 命名账户在自身 `allowFrom` 未设置时，会继承 `channels.slack.allowFrom`。
- 命名账户不会继承 `channels.slack.accounts.default.allowFrom`。
在私信中进行配对时，使用 `openclaw pairing approve slack <code>`。
在私信中配对时，使用 `openclaw pairing approve slack <code>`。
</Tab>
@ -656,26 +656,26 @@ Slack actions 由 `channels.slack.actions.*` 控制。
渠道 allowlist 位于 `channels.slack.channels` 下，并且应使用稳定的渠道 ID。
运行时说明：如果 `channels.slack` 完全缺失（仅使用环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使设置了 `channels.defaults.groupPolicy` 也是如此）。
运行时说明：如果 `channels.slack` 完全缺失（仅环境变量设置），运行时会回退为 `groupPolicy="allowlist"` 并记录警告（即使设置了 `channels.defaults.groupPolicy` 也是如此）。
名称/ID 解析：
- 渠道 allowlist 条目和私信 allowlist 条目会在启动时、令牌访问允许的情况下进行解析
- 无法解析的渠道名称条目会按配置保留，但默认不会用于路由
- 入站授权和渠道路由默认优先使用 ID；直接按用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true`
- 渠道 allowlist 条目和私信 allowlist 条目会在启动时解析，前提是令牌访问允许
- 无法解析的渠道名称条目会按原样保留配置，但默认不会用于路由
- 入站授权和渠道路由默认优先基于 ID；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true`
</Tab>
<Tab title="提及和渠道用户">
默认情况下，渠道消息会受到提及门控。
默认情况下，渠道消息受提及门控限制。
提及来源：
- 显式应用提及（`<@botId>`）
- 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`）
- 隐式回复到 bot 的线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用）
- 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`）
- 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用）
每个渠道的控制项（`channels.slack.channels.<id>`；仅能通过启动时解析或 `dangerouslyAllowNameMatching` 使用名称）：
每个渠道的控制项（`channels.slack.channels.<id>`；仅能通过启动解析名称，或使用 `dangerouslyAllowNameMatching`）：
- `requireMention`
- `users`（allowlist）
@ -683,26 +683,26 @@ Slack actions 由 `channels.slack.actions.*` 控制。
- `skills`
- `systemPrompt`
- `tools`, `toolsBySender`
- `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:`，或 `"*"` 通配符
（旧版未加前缀的键仍然只映射到 `id:`）
- `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符
（旧版无前缀键仍仅映射到 `id:`）
</Tab>
</Tabs>
## 线程、会话和回复标签
- 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。
- 使用默认的 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。
- 私信路由为 `direct`；渠道为 `channel`；MPIM 为 `group`。
- 在默认 `session.dmScope=main` 下，Slack 私信会收敛到智能体主会话。
- 渠道会话：`agent:<agentId>:slack:channel:<channelId>`。
- 在线程回复适用时，可以创建线程会话后缀（`:thread:<threadTs>`）。
- 在线程回复适用时，可以创建带有线程会话后缀（`:thread:<threadTs>`）的会话。
- `channels.slack.thread.historyScope` 默认为 `thread`；`thread.inheritParent` 默认为 `false`。
- `channels.slack.thread.initialHistoryLimit` 控制新线程会话开始时会抓取多少条已有线程消息（默认 `20`；设为 `0` 可禁用）。
- `channels.slack.thread.requireExplicitMention`（默认 `false`）：设为 `true` 时，会抑制隐式线程提及，因此 bot 即使已经参与了某个线程，也只会响应该线程内显式的 `@bot` 提及。否则，在 bot 已参与的线程中回复会绕过 `requireMention` 门控。
- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时会抓取多少条现有线程消息（默认 `20`；设为 `0` 可禁用）。
- `channels.slack.thread.requireExplicitMention`（默认 `false`）：设为 `true` 时，会抑制隐式线程提及，因此机器人即使已经参与了线程，也只会响应线程中的显式 `@bot` 提及。否则，在机器人已参与的线程中进行回复会绕过 `requireMention` 门控。
回复线程控制：
- `channels.slack.replyToMode`: `off|first|all|batched`（默认 `off`）
- `channels.slack.replyToModeByChatType`: 按 `direct|group|channel` 分别设置
- `channels.slack.replyToMode`：`off|first|all|batched`（默认 `off`）
- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 分别设置
- 私聊的旧版回退：`channels.slack.dm.replyToMode`
支持手动回复标签：
@ -710,11 +710,11 @@ Slack actions 由 `channels.slack.actions.*` 控制。
- `[[reply_to_current]]`
- `[[reply_to:<id>]]`
注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程功能，包括显式的 `[[reply_to_*]]` 标签。这一点不同于 Telegram，在 Telegram 中显式标签在 `"off"` 模式下仍会生效。这个差异反映了平台的线程模型：Slack 线程会将消息隐藏在渠道之外，而 Telegram 回复仍会保留在主聊天流中可见。
注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程功能，包括显式 `[[reply_to_*]]` 标签。这与 Telegram 不同，在 Telegram 中，即使是 `"off"` 模式，显式标签仍会被遵循。这种差异反映了平台线程模型的不同：Slack 线程会将消息隐藏在渠道之外，而 Telegram 回复仍会显示在主聊天流中。
## 确认反应
`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认 emoji。
`ackReaction` 会在 OpenClaw 处理入站消息期间发送一个确认 emoji。
解析顺序：
@ -725,8 +725,8 @@ Slack actions 由 `channels.slack.actions.*` 控制。
说明：
- Slack 需要使用 shortcode（例如 `"eyes"`）。
- 使用 `""` 可以为某个 Slack 账户或全局禁用该反应。
- Slack 需要使用短代码（例如 `"eyes"`）。
- 使用 `""` 可为某个 Slack 账户或全局禁用该反应。
## 文本流式传输
@ -735,15 +735,15 @@ Slack actions 由 `channels.slack.actions.*` 控制。
- `off`：禁用实时预览流式传输。
- `partial`（默认）：用最新的部分输出替换预览文本。
- `block`：追加分块预览更新。
- `progress`：在生成期间显示进度状态文本，然后发送最终文本。
- `progress`：生成期间显示进度状态文本，然后发送最终文本。
当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。
- 必须有可用的回复线程，原生文本流式传输和 Slack 助手线程状态才会显示。线程选择仍然遵循 `replyToMode`。
- 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。
- 顶层 Slack 私信默认保持非线程状态，因此不会显示线程样式的预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。
- 媒体和非文本负载会回退为普通投递。
- 如果流式传输在回复中途失败，OpenClaw 会对剩余负载回退为普通投递。
- 必须有可用的回复线程，Slack 原生文本流式传输和 Slack 助手线程状态才会显示。线程选择仍遵循 `replyToMode`。
- 当原生流式传输不可用时，渠道和群聊根消息仍可使用常规草稿预览。
- 顶层 Slack 私信默认保持非线程形式，因此不会显示线程样式预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。
- 媒体和非文本负载会回退到常规投递方式。
- 如果流式传输在回复中途失败，OpenClaw 会对剩余负载回退到常规投递方式。
使用草稿预览而不是 Slack 原生文本流式传输：
@ -766,9 +766,9 @@ Slack actions 由 `channels.slack.actions.*` 控制。
- 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。
- 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。
## 输入中反应回退
## typingReaction 回退
`typingReaction` 会在 OpenClaw 处理回复期间，向入站 Slack 消息临时添加一个反应，并在运行结束时将其移除。这在非线程回复场景中特别有用，因为线程回复会使用默认的“正在输入...”状态指示器。
`typingReaction` 会在 OpenClaw 处理回复期间，为入站 Slack 消息添加一个临时反应，并在运行结束时将其移除。这在线程回复之外尤其有用，因为线程回复会使用默认的“正在输入...”状态指示器。
解析顺序：
@ -777,24 +777,24 @@ Slack actions 由 `channels.slack.actions.*` 控制。
说明：
- Slack 需要使用 shortcode（例如 `"hourglass_flowing_sand"`）。
- 该反应采用尽力而为方式，回复完成或失败路径结束后会自动尝试清理。
- Slack 需要使用短代码（例如 `"hourglass_flowing_sand"`）。
- 该反应为尽力而为，回复完成或失败路径结束后会自动尝试清理。
## 媒体、分块和投递
<AccordionGroup>
<Accordion title="入站附件">
Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在抓取成功且大小限制允许时写入媒体存储。
Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在获取成功且大小限制允许时写入媒体存储。
运行时入站大小上限默认为 `20MB`，除非通过 `channels.slack.mediaMaxMb` 覆盖。
运行时入站大小上限默认是 `20MB`，除非通过 `channels.slack.mediaMaxMb` 覆盖。
</Accordion>
<Accordion title="出站文本和文件">
- 文本分块使用 `channels.slack.textChunkLimit`（默认 4000）
- `channels.slack.chunkMode="newline"` 启用优先按段落拆分
- `channels.slack.chunkMode="newline"` 启用按段落优先拆分
- 文件发送使用 Slack 上传 API，并且可以包含线程回复（`thread_ts`）
- 如果已配置，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则渠道发送使用媒体管道中的 MIME 类型默认值
- 配置了 `channels.slack.mediaMaxMb` 时，出站媒体上限遵循该值；否则，渠道发送会使用媒体管道中按 MIME 类型划分的默认值
</Accordion>
<Accordion title="投递目标">
@ -810,7 +810,7 @@ Slack actions 由 `channels.slack.actions.*` 控制。
## 命令和斜杠行为
斜杠命令在 Slack 中可以显示为单个已配置命令，或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值：
斜杠命令在 Slack 中可以显示为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值：
- `enabled: false`
- `name: "openclaw"`
@ -821,30 +821,30 @@ Slack actions 由 `channels.slack.actions.*` 控制。
/openclaw /help
```
原生命令需要你在 Slack 应用中配置[其他清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 或全局配置中的 `commands.native: true` 启用。
原生命令需要你在 Slack 应用中配置[额外清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 或全局配置中的 `commands.native: true` 启用。
- 对于 Slack，原生命令自动模式默认是 **关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。
- 对于 Slack，原生命令自动模式默认是**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。
```txt
/help
```
原生参数菜单使用一种自适应渲染策略，在分发所选选项值之前会先显示一个确认模态框：
原生参数菜单使用自适应渲染策略，在分发所选选项值之前会先显示确认模态框：
- 最多 5 个选项：按钮块
- 6-100 个选项：静态选择菜单
- 超过 100 个选项：当交互式选项处理器可用时，使用带异步选项过滤的外部选择
- 超出 Slack 限制时：经过编码的选项值会回退为按钮
- 超过 100 个选项：当可用交互式选项处理器时，使用带异步选项过滤的外部选择
- 超出 Slack 限制时：编码后的选项值会回退为按钮
```txt
/think
```
斜杠会话使用隔离键，例如 `agent:<agentId>:slack:slash:<userId>`，并仍会通过 `CommandTargetSessionKey` 将命令执行路由到目标会话。
斜杠会话使用隔离键，例如 `agent:<agentId>:slack:slash:<userId>`，但仍会通过 `CommandTargetSessionKey` 将命令执行路由到目标会话。
## 交互式回复
Slack 可以渲染由智能体生成的交互式回复控件，但该功能默认禁用。
Slack 可以渲染由智能体生成的交互式回复控件，但此功能默认禁用。
全局启用：
@ -860,7 +860,7 @@ Slack 可以渲染由智能体生成的交互式回复控件，但该功能默
}
```
或者仅为一个 Slack 账户启用：
或仅为某一个 Slack 账户启用：
```json5
{
@ -878,7 +878,7 @@ Slack 可以渲染由智能体生成的交互式回复控件，但该功能默
}
```
启用后，智能体可以发出仅适用于 Slack 的回复指令：
启用后，智能体可以输出仅适用于 Slack 的回复指令：
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
@ -887,32 +887,32 @@ Slack 可以渲染由智能体生成的交互式回复控件，但该功能默
说明：
- 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令翻译成它们自己的按钮系统。
- 交互回调值是 OpenClaw 生成的不透明令牌，而不是智能体原始编写的值。
- 这是 Slack 专属 UI。其他渠道不会将 Slack Block Kit 指令转换为自己的按钮系统。
- 交互式回调值是 OpenClaw 生成的不透明令牌，而不是智能体原始编写的值。
- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的 blocks 负载。
## Slack 中的 Exec 审批
Slack 可以充当原生审批客户端，使用交互按钮和交互流程，而不是回退到 Web UI 或终端。
Slack 可以充当原生审批客户端，使用交互式按钮和交互，而不是回退到 Web UI 或终端。
- Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。
- 当请求已经落在 Slack 中，且审批 ID 类型为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面进行处理。
- 如果请求已经到达 Slack 且审批 ID 类型为 `plugin:`，插件审批仍可通过同一个 Slack 原生按钮界面完成。
- 审批人授权仍会被强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。
这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用了 `interactivity` 时，审批提示会直接在会话中渲染为 Block Kit 按钮。
当这些按钮存在时，它们就是主要的审批 UX；只有当工具结果表明聊天审批不可用，或手动审批是唯一可行路径时，OpenClaw
这使用与其他渠道相同的共享审批按钮界面。当你在 Slack 应用设置中启用 `interactivity` 时，审批提示会直接在会话中渲染为 Block Kit 按钮。
当这些按钮存在时，它们就是主要的审批 UX；只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，OpenClaw
才应包含手动 `/approve` 命令。
配置路径：
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers`（可选；尽可能回退到 `commands.ownerAllowFrom`）
- `channels.slack.execApprovals.approvers`（可选；可能时回退为 `commands.ownerAllowFrom`）
- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`）
- `agentFilter`、`sessionFilter`
当 `enabled` 未设置或为 `"auto"`，且至少解析出一个
审批人时，Slack 会自动启用原生 exec 审批。将 `enabled: false` 设为显式禁用 Slack 作为原生审批客户端。
将 `enabled: true` 设为在审批人可解析时强制启用原生审批。
当 `enabled` 未设置或为 `"auto"` 且至少解析出一个
审批人时，Slack 会自动启用原生 exec 审批。设置 `enabled: false` 可显式禁用 Slack 作为原生审批客户端。
设置 `enabled: true` 可在审批人可解析时强制启用原生审批。
在没有显式 Slack exec 审批配置时的默认行为：
@ -925,7 +925,7 @@ Slack 可以充当原生审批客户端，使用交互按钮和交互流程，
```
只有当你想覆盖审批人、添加过滤器，或
启用投递到来源聊天时，才需要显式的 Slack 原生配置：
选择加入来源聊天投递时，才需要显式 Slack 原生配置：
```json5
{
@ -943,24 +943,23 @@ Slack 可以充当原生审批客户端，使用交互按钮和交互流程，
共享的 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须
路由到其他聊天或显式带外目标时才使用它。共享的 `approvals.plugin` 转发也
是独立的；当这些请求已经落在
Slack 中时，Slack 原生按钮仍然可以处理插件审批。
是独立的；当这些请求已经到达 Slack 时，Slack 原生按钮仍可处理插件审批。
同聊天中的 `/approve` 在已经支持命令的 Slack 渠道和私信中也可使用。完整的审批转发模型请参见[Exec approvals](/zh-CN/tools/exec-approvals)。
同一聊天中的 `/approve` 也适用于已经支持命令的 Slack 渠道和私信。完整审批转发模型请参见 [Exec approvals](/zh-CN/tools/exec-approvals)。
## 事件和运行行为
- 消息编辑/删除/线程广播会映射为系统事件。
- 反应添加/移除事件会映射为系统事件。
- 成员加入/离开、渠道创建/重命名，以及 pin 添加/移除事件会映射为系统事件。
- 当 `configWrites` 启用时，`channel_id_changed` 可以迁移渠道配置键。
- 渠道 topic/purpose 元数据被视为不受信任的上下文，并且可注入到路由上下文中。
- 在线程发起者和初始线程历史上下文植入过程中，会在适用时按已配置的发送者 allowlist 进行过滤。
- 添加/移除反应事件会映射为系统事件。
- 成员加入/离开、渠道创建/重命名以及 pin 添加/移除事件会映射为系统事件。
- 当启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。
- 渠道 topic/purpose 元数据会被视为不可信上下文，并可注入到路由上下文中。
- 线程发起者和初始线程历史上下文填充会在适用时按已配置的发送者 allowlist 进行过滤。
- Block actions 和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并带有丰富的负载字段：
- block actions：所选值、标签、选择器值和 `workflow_*` 元数据
- 模态 `view_submission` 和 `view_closed` 事件，带有已路由的渠道元数据和表单输入
- block actions：所选值、标签、选择器值以及 `workflow_*` 元数据
- 模态 `view_submission` 和 `view_closed` 事件，包含已路由的渠道元数据和表单输入
## 配置参考指针
## 配置参考指引
主要参考：
@ -969,7 +968,7 @@ Slack 中时，Slack 原生按钮仍然可以处理插件审批。
高信号 Slack 字段：
- 模式/认证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*`
- 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels`
- 兼容性开关：`dangerouslyAllowNameMatching`（紧急兜底开关；除非确有需要，否则保持关闭）
- 兼容性开关：`dangerouslyAllowNameMatching`（紧急开关；除非确有需要，否则保持关闭）
- 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention`
- 线程/历史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
- 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`
@ -984,9 +983,9 @@ Slack 中时，Slack 原生按钮仍然可以处理插件审批。
- `groupPolicy`
- 渠道 allowlist（`channels.slack.channels`）
- `requireMention`
- 每个渠道的 `users` allowlist
- 每渠道 `users` allowlist
有用的命令：
常用命令：
```bash
openclaw channels status --probe
@ -1001,7 +1000,7 @@ openclaw doctor
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy`（或旧版 `channels.slack.dm.policy`）
- 配对批准 / allowlist 条目
- 配对审批 / allowlist 条目
```bash
openclaw pairing list slack
@ -1010,7 +1009,7 @@ openclaw pairing list slack
</Accordion>
<Accordion title="Socket mode 未连接">
验证 bot 和 app 令牌，以及 Slack 应用设置中的 Socket Mode 是否已启用。
验证 bot + app 令牌，以及 Slack 应用设置中是否启用了 Socket Mode。
如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或
`appTokenStatus: "configured_unavailable"`，说明 Slack 账户
@ -1019,7 +1018,7 @@ openclaw pairing list slack
</Accordion>
<Accordion title="HTTP mode 未接收到事件">
<Accordion title="HTTP 模式未接收到事件">
验证：
- signing secret
@ -1029,17 +1028,17 @@ openclaw pairing list slack
如果账户快照中出现 `signingSecretStatus: "configured_unavailable"`，
说明 HTTP 账户已完成配置，但当前运行时无法
解析由 SecretRef 支持的 signing secret。
解析由 SecretRef 支持的 signing secret 实际值。
</Accordion>
<Accordion title="原生命令/斜杠命令未触发">
请确认你的预期是：
确认你想要的是：
- 原生命令模式（`channels.slack.commands.native: true`），并且已在 Slack 中注册了匹配的斜杠命令
- 或单个斜杠命令模式（`channels.slack.slashCommand.enabled: true`）
- 原生命令模式（`channels.slack.commands.native: true`），并且已在 Slack 中注册匹配的斜杠命令
- 或单斜杠命令模式（`channels.slack.slashCommand.enabled: true`）
还要检查 `commands.useAccessGroups` 以及渠道/用户 allowlist。
同时检查 `commands.useAccessGroups` 以及渠道/用户 allowlist。
</Accordion>
</AccordionGroup>

529
docs/zh-CN/concepts/model-providers.md
View File

@ -2,265 +2,149 @@
read_when:
- 你需要一份按提供商分别说明的模型设置参考文档
- 你想要模型提供商的示例配置或 CLI 新手引导命令
summary: 模型提供商概览，附示例配置 + CLI 流程
summary: 模型提供商概览，包含示例配置和 CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-04-21T06:04:35Z"
generated_at: "2026-04-21T08:24:19Z"
model: gpt-5.4
provider: openai
source_hash: e433dfd51d1721832480089cb35ab1243e5c873a587f9968e14744840cb912cf
source_hash: 6732ab672757579c09395583a0f7d110348c909d4e4ab1d2accad68ad054c636
source_path: concepts/model-providers.md
workflow: 15
---
# 模型提供商
本页介绍的是 **LLM / 模型提供商**（不是像 WhatsApp / Telegram 这样的聊天渠道）。
本页介绍的是 **LLM/模型提供商**（而不是像 WhatsApp/Telegram 这样的聊天渠道）。
关于模型选择规则，请参见 [/concepts/models](/zh-CN/concepts/models)。
## 快速规则
- 模型引用使用 `provider/model`（例如：`opencode/claude-opus-4-6`）。
- 模型引用使用 `provider/model` 格式（示例：`opencode/claude-opus-4-6`）。
- 如果你设置了 `agents.defaults.models`，它就会成为允许列表。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- 回退运行时规则、冷却探测以及会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover) 中。
- `models.providers.*.models[].contextWindow` 是原生模型元数据；
`models.providers.*.models[].contextTokens` 是运行时生效的上限。
- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；
OpenClaw 会在写入 `models.json` 之前将该输出合并到 `models.providers` 中。
- 提供商清单可以声明 `providerAuthEnvVars` 和
`providerAuthAliases`，这样通用的基于环境变量的凭证探测以及提供商变体
就不需要加载插件运行时。核心中剩余的环境变量映射现在只用于非插件 / 核心提供商，
以及少数通用优先级场景，例如 Anthropic API 密钥优先的新手引导。
- 提供商插件还可以通过以下方式拥有提供商运行时行为：
`normalizeModelId`、`normalizeTransport`、`normalizeConfig`、
`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、
`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、
`resolveDynamicModel`、`prepareDynamicModel`、
`normalizeResolvedModel`、`contributeResolvedModelCompat`、
`capabilities`、`normalizeToolSchemas`、
`inspectToolSchemas`、`resolveReasoningOutputMode`、
`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、
`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、
`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、
`buildAuthDoctorHint`、
`matchesContextOverflowError`、`classifyFailoverReason`、
`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、
`augmentModelCatalog`、`isBinaryThinking`、`supportsXHighThinking`、
`supportsAdaptiveThinking`、`supportsMaxThinking`、
`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、
`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 以及
`onModelSelected`。
- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商
家族、转录 / 工具特性、传输 / 缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，
后者描述的是插件注册了什么能力（文本推理、语音等）。
- 内置的 `codex` 提供商与内置的 Codex 智能体 harness 配套使用。
当你希望使用由 Codex 管理的登录、模型发现、原生线程恢复和应用服务器执行时，
请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍会使用 OpenAI 提供商
和常规的 OpenClaw 提供商传输。仅使用 Codex 的部署可以通过
`agents.defaults.embeddedHarness.fallback: "none"` 禁用自动 PI 回退；请参见
[Codex Harness](/zh-CN/plugins/codex-harness)。
- CLI 助手：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover)。
- `models.providers.*.models[].contextWindow` 是原生模型元数据；`models.providers.*.models[].contextTokens` 是运行时生效的上限。
- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前将该输出合并到 `models.providers` 中。
- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样基于通用环境变量的凭证探测和提供商变体就不需要加载插件运行时。当前核心中的其余环境变量映射现在只用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic 以 API key 优先的新手引导。
- 提供商插件还可以通过 `normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`resolveThinkingProfile`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 和 `onModelSelected` 来拥有提供商运行时行为。
- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录/工具行为特性、传输/缓存提示）。它不同于[公开 capability 模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。
- 内置的 `codex` 提供商与内置 Codex 智能体 harness 配对使用。当你需要 Codex 自有登录、模型发现、原生线程恢复和 app-server 执行时，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍然会使用 OpenAI 提供商和标准 OpenClaw 提供商传输。仅使用 Codex 的部署可以通过设置 `agents.defaults.embeddedHarness.fallback: "none"` 来禁用自动 PI 回退；参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
## 插件拥有的提供商行为
## 插件自有的提供商行为
现在，提供商插件可以拥有大多数提供商特定逻辑，而 OpenClaw 保留
通用推理循环。
提供商插件现在可以拥有大部分提供商特定逻辑，而 OpenClaw 则保留通用推理循环。
典型划分：
典型划分如下：
- `auth[].run` / `auth[].runNonInteractive`：提供商拥有用于 `openclaw onboard`、`openclaw models auth` 和无头设置的
新手引导 / 登录流程
- `wizard.setup` / `wizard.modelPicker`：提供商拥有凭证选择标签、
旧别名、用于新手引导的允许列表提示，以及新手引导 / 模型选择器中的设置项
- `catalog`：提供商会出现在 `models.providers` 中
- `normalizeModelId`：提供商会在查找或规范化之前，
规范化旧版 / 预览模型 id
- `normalizeTransport`：提供商会在通用模型组装之前，
规范化传输家族的 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，
然后再检查其他支持该钩子的提供商插件，直到某个插件实际更改了
传输
- `normalizeConfig`：提供商会在运行时使用之前，
规范化 `models.providers.<id>` 配置；OpenClaw 会先检查匹配的提供商，
然后再检查其他支持该钩子的提供商插件，直到某个插件实际更改了配置。如果没有
提供商钩子重写该配置，内置的 Google 家族辅助逻辑仍会
规范化受支持的 Google 提供商条目。
- `applyNativeStreamingUsageCompat`：提供商会为配置型提供商应用由端点驱动的原生流式用量兼容性重写
- `resolveConfigApiKey`：提供商会为配置型提供商解析环境变量标记凭证，
而无需强制加载完整运行时凭证。`amazon-bedrock` 在这里也有一个
内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是
AWS SDK 默认链。
- `resolveSyntheticAuth`：提供商可以暴露本地 / 自托管或其他
基于配置的凭证可用性，而不持久化明文密钥
- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置文件
占位符标记为低于基于环境变量 / 配置的凭证优先级
- `resolveDynamicModel`：提供商可以接受尚未存在于本地
静态目录中的模型 id
- `prepareDynamicModel`：提供商在重试
动态解析之前需要刷新元数据
- `normalizeResolvedModel`：提供商需要进行传输或 base URL 重写
- `contributeResolvedModelCompat`：提供商可以为其
供应商模型贡献兼容标记，即使这些模型是通过另一种兼容传输到达的
- `capabilities`：提供商会发布转录 / 工具 / 提供商家族特性
- `normalizeToolSchemas`：提供商会在嵌入式
运行器看到工具 schema 之前对其进行清理
- `inspectToolSchemas`：提供商会在规范化之后暴露传输特定的 schema 警告
- `resolveReasoningOutputMode`：提供商会选择原生或带标签的
reasoning 输出契约
- `prepareExtraParams`：提供商会为每个模型请求参数设置默认值或进行规范化
- `createStreamFn`：提供商会用完全自定义的传输
替换常规流路径
- `wrapStreamFn`：提供商会应用请求头 / 请求体 / 模型兼容包装器
- `resolveTransportTurnState`：提供商会提供每轮原生传输的
请求头或元数据
- `resolveWebSocketSessionPolicy`：提供商会提供原生 WebSocket 会话
请求头或会话冷却策略
- `createEmbeddingProvider`：当内存嵌入行为应归属于提供商插件而不是核心嵌入切换器时，
由提供商拥有该行为
- `formatApiKey`：提供商会将已存储的认证配置文件格式化为
传输所期望的运行时 `apiKey` 字符串
- `refreshOAuth`：当共享的 `pi-ai`
刷新器不够用时，由提供商负责 OAuth 刷新
- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商会追加修复指导
- `matchesContextOverflowError`：提供商会识别提供商特定的
上下文窗口溢出错误，而通用启发式规则可能会漏掉这些错误
- `classifyFailoverReason`：提供商会将提供商特定的原始传输 / API
错误映射为回退原因，例如速率限制或过载
- `isCacheTtlEligible`：提供商会决定哪些上游模型 id 支持提示缓存 TTL
- `buildMissingAuthMessage`：提供商会用提供商特定的恢复提示
替换通用的凭证存储错误
- `suppressBuiltInModel`：提供商会隐藏过时的上游条目，并且可以对直接解析失败
返回供应商自有错误
- `augmentModelCatalog`：提供商会在发现和配置合并之后
追加合成 / 最终目录条目
- `isBinaryThinking`：提供商拥有二元开 / 关 thinking UX
- `supportsXHighThinking`：提供商为选定模型启用 `xhigh`
- `supportsAdaptiveThinking`：提供商为选定模型启用 `adaptive`
- `supportsMaxThinking`：提供商为选定模型启用 `max`
- `resolveDefaultThinkingLevel`：提供商拥有某个
模型家族的默认 `/think` 策略
- `applyConfigDefaults`：提供商会在配置具体化期间，
根据凭证模式、环境或模型家族应用提供商特定的全局默认值
- `isModernModelRef`：提供商拥有 live / smoke 首选模型匹配
- `prepareRuntimeAuth`：提供商会将配置好的凭证转换为短期有效的运行时令牌
- `resolveUsageAuth`：提供商会为 `/usage`
及相关状态 / 报告界面解析用量 / 配额凭证
- `fetchUsageSnapshot`：提供商拥有用量端点的获取 / 解析逻辑，
而核心仍拥有摘要外壳和格式化
- `onModelSelected`：提供商会在选择模型后执行副作用，例如
遥测或提供商自有的会话记账
- `auth[].run` / `auth[].runNonInteractive`：提供商拥有 `openclaw onboard`、`openclaw models auth` 和无头设置的引导/登录流程
- `wizard.setup` / `wizard.modelPicker`：提供商拥有凭证选择标签、旧版别名、新手引导允许列表提示，以及新手引导/模型选择器中的设置项
- `catalog`：提供商显示在 `models.providers` 中
- `normalizeModelId`：提供商在查找或规范化之前标准化旧版/预览模型 ID
- `normalizeTransport`：提供商在通用模型组装之前标准化传输家族 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后再检查其他支持该 hook 的提供商插件，直到其中一个实际更改了传输
- `normalizeConfig`：提供商在运行时使用前标准化 `models.providers.<id>` 配置；OpenClaw 会先检查匹配的提供商，然后再检查其他支持该 hook 的提供商插件，直到其中一个实际更改了配置。如果没有提供商 hook 重写配置，内置的 Google 家族助手仍会标准化受支持的 Google 提供商条目。
- `applyNativeStreamingUsageCompat`：提供商对配置提供商应用由端点驱动的原生流式用量兼容性重写
- `resolveConfigApiKey`：提供商为配置提供商解析环境变量标记凭证，而不强制加载完整运行时凭证。`amazon-bedrock` 这里也有一个内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是 AWS SDK 默认链。
- `resolveSyntheticAuth`：提供商可以在不持久化明文密钥的情况下公开本地/自托管或其他基于配置的凭证可用性
- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置占位凭证标记为低于环境变量/配置支持凭证的优先级
- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 ID
- `prepareDynamicModel`：提供商在重试动态解析之前需要刷新元数据
- `normalizeResolvedModel`：提供商需要重写传输或基础 URL
- `contributeResolvedModelCompat`：即使其供应商模型通过另一个兼容传输到达，提供商也会为其贡献兼容性标志
- `capabilities`：提供商发布转录/工具/提供商家族行为特性
- `normalizeToolSchemas`：提供商在内置运行器看到工具 schema 之前对其进行清理
- `inspectToolSchemas`：提供商在标准化之后暴露传输特定的 schema 警告
- `resolveReasoningOutputMode`：提供商选择原生或带标签的推理输出契约
- `prepareExtraParams`：提供商为每个模型的请求参数设置默认值或进行标准化
- `createStreamFn`：提供商用完全自定义的传输替换正常的流路径
- `wrapStreamFn`：提供商应用请求头/请求体/模型兼容性包装器
- `resolveTransportTurnState`：提供商提供逐轮原生传输头或元数据
- `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话头或会话冷却策略
- `createEmbeddingProvider`：当内存嵌入行为应属于提供商插件而不是核心嵌入切换板时，由提供商拥有该行为
- `formatApiKey`：提供商将已存储的凭证配置格式化为传输所期望的运行时 `apiKey` 字符串
- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足时，由提供商拥有 OAuth 刷新
- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商追加修复指导
- `matchesContextOverflowError`：提供商识别通用启发式规则会漏掉的、提供商特定的上下文窗口溢出错误
- `classifyFailoverReason`：提供商将提供商特定的原始传输/API 错误映射为回退原因，例如速率限制或过载
- `isCacheTtlEligible`：提供商决定哪些上游模型 ID 支持提示词缓存 TTL
- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用凭证存储错误
- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并可在直接解析失败时返回供应商自有错误
- `augmentModelCatalog`：提供商在发现和配置合并之后追加合成/最终目录条目
- `resolveThinkingProfile`：提供商拥有所选模型的精确 `/think` 级别集合、可选显示标签和默认级别
- `isBinaryThinking`：用于二元开/关思考 UX 的兼容性 hook
- `supportsXHighThinking`：用于选定 `xhigh` 模型的兼容性 hook
- `resolveDefaultThinkingLevel`：用于默认 `/think` 策略的兼容性 hook
- `applyConfigDefaults`：提供商在基于凭证模式、环境变量或模型家族进行配置具体化时应用提供商特定的全局默认值
- `isModernModelRef`：提供商拥有实时/冒烟测试首选模型匹配逻辑
- `prepareRuntimeAuth`：提供商将已配置的凭证转换为短期有效的运行时令牌
- `resolveUsageAuth`：提供商为 `/usage` 以及相关状态/报告界面解析用量/配额凭证
- `fetchUsageSnapshot`：提供商拥有用量端点的抓取/解析逻辑，而核心仍拥有摘要外壳和格式化
- `onModelSelected`：提供商在模型被选中后运行副作用，例如遥测或提供商自有的会话记账
当前内置示例：
- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、用量
端点获取、缓存 TTL / 提供商家族元数据，以及具备凭证感知能力的全局
配置默认值
- `amazon-bedrock`：由提供商拥有的上下文溢出匹配，以及针对 Bedrock 特定限流 / 未就绪错误的回退
原因分类，外加共享的 `anthropic-by-model` 重放家族，用于对 Anthropic 流量上的
仅 Claude 重放策略守卫
- `anthropic-vertex`：针对 Anthropic-message
流量的仅 Claude 重放策略守卫
- `openrouter`：透传模型 id、请求包装器、提供商能力
提示、代理 Gemini 流量上的 Gemini thought-signature 清理、
通过 `openrouter-thinking` 流家族注入代理 reasoning、
路由元数据转发，以及缓存 TTL 策略
- `github-copilot`：新手引导 / 设备登录、前向兼容模型回退、
Claude-thinking 转录提示、运行时令牌交换，以及用量端点
获取
- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输
规范化、具备 Codex 感知能力的缺失凭证提示、Spark 抑制、合成的
OpenAI / Codex 目录条目、thinking / live-model 策略、用量令牌别名
规范化（`input` / `output` 和 `prompt` / `completion` 家族）、共享的
`openai-responses-defaults` 流家族，用于原生 OpenAI / Codex 包装器、
提供商家族元数据、为 `gpt-image-1` 内置注册的图像生成提供商，
以及为 `sora-2` 内置注册的视频生成提供商
- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、
原生 Gemini 重放校验、bootstrap 重放清理、带标签的
reasoning 输出模式、现代模型匹配、为 Gemini image-preview 模型内置注册的图像生成
提供商，以及为 Veo 模型内置注册的
视频生成提供商；Gemini CLI OAuth 还拥有认证配置文件令牌格式化、
用量令牌解析，以及用于用量界面的配额端点获取
- `moonshot`：共享传输，由插件拥有的 thinking 载荷规范化
- `kilocode`：共享传输，由插件拥有的请求头、reasoning 载荷
规范化、代理 Gemini thought-signature 清理，以及缓存 TTL
策略
- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL
策略、二元 thinking / live-model 策略，以及用量凭证 + 配额获取；
未知的 `glm-5*` id 会基于内置的 `glm-4.7` 模板进行合成
- `xai`：原生 Responses 传输规范化、针对
Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特定的工具 schema /
reasoning 载荷清理，以及为 `grok-imagine-video` 内置注册的视频生成提供商
- `mistral`：由插件拥有的能力元数据
- `opencode` 和 `opencode-go`：由插件拥有的能力元数据，外加
代理 Gemini thought-signature 清理
- `alibaba`：由插件拥有的视频生成目录，用于直接 Wan 模型引用，
例如 `alibaba/wan2.6-t2v`
- `byteplus`：由插件拥有的目录，外加为 Seedance 文生视频 / 图生视频模型内置注册的
视频生成提供商
- `fal`：为托管的第三方
图像生成模型 FLUX 内置注册的图像生成提供商，外加为托管的第三方视频模型内置注册的
视频生成提供商
- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、
`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：
仅由插件拥有目录
- `qwen`：文本模型的插件自有目录，外加其
多模态界面的共享媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频
端点，并配套内置的 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v`
- `runway`：由插件拥有的视频生成提供商注册，用于原生
Runway 基于任务的模型，例如 `gen4.5`
- `minimax`：由插件拥有的目录、为 Hailuo 视频模型内置注册的
视频生成提供商、为 `image-01` 内置注册的图像生成提供商、
混合 Anthropic / OpenAI 重放策略选择，以及用量凭证 / 快照逻辑
- `together`：由插件拥有的目录，外加为 Wan 视频模型内置注册的
视频生成提供商
- `xiaomi`：由插件拥有的目录，外加用量凭证 / 快照逻辑
- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、用量端点抓取、缓存 TTL/提供商家族元数据，以及具备凭证感知能力的全局配置默认值
- `amazon-bedrock`：由提供商自有的上下文溢出匹配，以及针对 Bedrock 特有节流/未就绪错误的回退原因分类，外加共享的 `anthropic-by-model` 重放家族，用于 Anthropic 流量上仅限 Claude 的重放策略保护
- `anthropic-vertex`：针对 Anthropic 消息流量的仅限 Claude 的重放策略保护
- `openrouter`：直通模型 ID、请求包装器、提供商 capability 提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族进行代理推理注入、路由元数据转发，以及缓存 TTL 策略
- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude thinking 转录提示、运行时令牌交换，以及用量端点抓取
- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输标准化、具备 Codex 感知能力的缺失凭证提示、Spark 抑制、合成 OpenAI/Codex 目录条目、thinking/实时模型策略、用量令牌别名标准化（`input` / `output` 和 `prompt` / `completion` 家族）、共享的 `openai-responses-defaults` 流家族（用于原生 OpenAI/Codex 包装器）、提供商家族元数据、为 `gpt-image-1` 内置的图像生成提供商注册，以及为 `sora-2` 内置的视频生成提供商注册
- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、引导重放清理、带标签的推理输出模式、现代模型匹配、为 Gemini image-preview 模型内置的图像生成提供商注册，以及为 Veo 模型内置的视频生成提供商注册；此外，Gemini CLI OAuth 还拥有凭证配置令牌格式化、用量令牌解析，以及面向用量界面的配额端点抓取
- `moonshot`：共享传输、插件自有的 thinking 负载标准化
- `kilocode`：共享传输、插件自有的请求头、推理负载标准化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略
- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元 thinking/实时模型策略，以及用量凭证 + 配额抓取；未知的 `glm-5*` ID 会基于内置的 `glm-4.7` 模板合成
- `xai`：原生 Responses 传输标准化、针对 Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特有的工具 schema / 推理负载清理，以及为 `grok-imagine-video` 内置的视频生成提供商注册
- `mistral`：插件自有的 capability 元数据
- `opencode` 和 `opencode-go`：插件自有的 capability 元数据，以及代理 Gemini thought-signature 清理
- `alibaba`：针对直接 Wan 模型引用（如 `alibaba/wan2.6-t2v`）的插件自有视频生成目录
- `byteplus`：插件自有目录，以及为 Seedance 文生视频/图生视频模型内置的视频生成提供商注册
- `fal`：为托管第三方图像生成 FLUX 图像模型内置的图像生成提供商注册，以及为托管第三方视频模型内置的视频生成提供商注册
- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅有插件自有目录
- `qwen`：文本模型的插件自有目录，以及其多模态界面的共享媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点，并配套内置 Wan 模型，如 `wan2.6-t2v` 和 `wan2.7-r2v`
- `runway`：为原生 Runway 基于任务的模型（如 `gen4.5`）提供插件自有的视频生成提供商注册
- `minimax`：插件自有目录、为 Hailuo 视频模型内置的视频生成提供商注册、为 `image-01` 内置的图像生成提供商注册、Anthropic/OpenAI 混合重放策略选择，以及用量凭证/快照逻辑
- `together`：插件自有目录，以及为 Wan 视频模型内置的视频生成提供商注册
- `xiaomi`：插件自有目录，以及用量凭证/快照逻辑
内置的 `openai` 插件现在同时拥有两个提供商 id：`openai` 和
`openai-codex`。
内置的 `openai` 插件现在同时拥有两个提供商 ID：`openai` 和 `openai-codex`。
以上涵盖了仍然适配 OpenClaw 常规传输的提供商。一个提供商
如果需要完全自定义的请求执行器，那就是另一个更深层的扩展接口。
以上涵盖了仍适配 OpenClaw 常规传输的提供商。若某个提供商需要完全自定义的请求执行器，那就是另一类、更深层的扩展接口。
## API 密钥轮换
## API key 轮换
- 支持为选定提供商进行通用提供商轮换。
- 通过以下方式配置多个密钥：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个 live 覆盖项，优先级最高）
- 通过以下方式配置多个 key：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
- `<PROVIDER>_API_KEYS`（逗号或分号分隔列表）
- `<PROVIDER>_API_KEY`（主密钥）
- `<PROVIDER>_API_KEY`（主 key）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
- 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退项包含在内。
- 密钥选择顺序会保留优先级并对值去重。
- 仅当响应为速率限制时，才会使用下一个密钥重试请求（例如
`429`、`rate_limit`、`quota`、`resource exhausted`、`Too many
concurrent requests`、`ThrottlingException`、`concurrency limit reached`、
`workers_ai ... quota limit exceeded`，或周期性的用量上限消息）。
- 非速率限制失败会立即失败；不会尝试密钥轮换。
- 当所有候选密钥都失败时，将返回最后一次尝试的最终错误。
- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退项包含在内。
- key 选择顺序会保留优先级并去重数值。
- 仅在收到速率限制响应时，才会使用下一个 key 重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性的用量限制消息）。
- 非速率限制失败会立即失败；不会尝试 key 轮换。
- 当所有候选 key 都失败时，返回最后一次尝试的最终错误。
## 内置提供商（pi-ai 目录）
OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
`models.providers` 配置；只需设置凭证并选择一个模型。
OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
`models.providers` 配置；只需设置凭证并选择模型。
### OpenAI
- 提供商：`openai`
- 凭证：`OPENAI_API_KEY`
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖项）
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
- 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-pro`
- CLI：`openclaw onboard --auth-choice openai-api-key`
- 默认传输为 `auto`（优先 WebSocket，回退到 SSE）
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
- 可通过 `agents.defaults.models["openai/<model>"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true` / `false`）
- 可以通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先级处理
- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- 当你想使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、
`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于
通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示，以及
OpenAI reasoning 兼容载荷整形；代理路由则不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`）
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先级处理
- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- 当你希望使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）只适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示词缓存提示，以及 OpenAI 推理兼容负载整形；代理路由则不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 会拒绝它；Spark 被视为仅限 Codex
```json5
{
@ -272,12 +156,12 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
- 提供商：`anthropic`
- 凭证：`ANTHROPIC_API_KEY`
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖项）
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖）
- 示例模型：`anthropic/claude-opus-4-6`
- CLI：`openclaw onboard --auth-choice apiKey`
- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- Anthropic 说明：Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成的受认可方式，除非 Anthropic 发布新的政策。
- Anthropic setup-token 仍然可作为受支持的 OpenClaw 令牌路径使用，但 OpenClaw 现在在可用时优先选择 Claude CLI 复用和 `claude -p`。
- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 凭证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为该集成已获许可。
- Anthropic setup-token 仍可作为受支持的 OpenClaw 令牌路径使用，但 OpenClaw 现在在可用时更倾向于 Claude CLI 复用和 `claude -p`。
```json5
{
@ -291,16 +175,14 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
- 凭证：OAuth（ChatGPT）
- 示例模型：`openai-codex/gpt-5.4`
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
- 默认传输为 `auto`（优先 WebSocket，回退到 SSE）
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
- 可通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）上传递
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、
`User-Agent`）仅附加在发往
`chatgpt.com/backend-api` 的原生 Codex 流量上，不适用于通用 OpenAI 兼容代理
- 与直接的 `openai/*` 共享同一个 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority`
- 当 Codex OAuth 目录暴露 `openai-codex/gpt-5.3-codex-spark` 时，它仍然可用；是否可用取决于授权资格
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
- 与直接 `openai/*` 共用相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority`
- 当 Codex OAuth 目录暴露 `openai-codex/gpt-5.3-codex-spark` 时，该模型仍可用；是否可用取决于 entitlement
- `openai-codex/gpt-5.4` 保持原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- 策略说明：OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部工具 / 工作流。
- 策略说明：OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部工具/工作流。
```json5
{
@ -322,8 +204,8 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
### 其他订阅式托管选项
- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射
- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问
- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商界面，以及 Alibaba DashScope 和 Coding Plan 端点映射
- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API key 访问
- [GLM Models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点
### OpenCode
@ -340,23 +222,23 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
}
```
### Google Gemini（API 密钥）
### Google Gemini（API key）
- 提供商：`google`
- 凭证：`GEMINI_API_KEY`
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖项）
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被标准化为 `google/gemini-3-flash-preview`
- CLI：`openclaw onboard --auth-choice gemini-api-key`
- 直接 Gemini 运行还接受 `agents.defaults.models["google/<model>"].params.cachedContent`
（或旧版 `cached_content`），用于转发提供商原生的
- 直接 Gemini 运行也接受 `agents.defaults.models["google/<model>"].params.cachedContent`
（或旧版 `cached_content`），以转发提供商原生的
`cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
### Google Vertex 和 Gemini CLI
- 提供商：`google-vertex`、`google-gemini-cli`
- 凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后其 Google 账号受到了限制。请先查看 Google 条款，并且如果你决定继续，请使用非关键账号。
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后遭遇了 Google 账号限制。如果你选择继续，请先查看 Google 条款，并使用非关键账号。
- Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
- 先安装 Gemini CLI：
- `brew install gemini-cli`
@ -364,11 +246,10 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
- 启用：`openclaw plugins enable google`
- 登录：`openclaw models auth login --provider google-gemini-cli --set-default`
- 默认模型：`google-gemini-cli/gemini-3-flash-preview`
- 注意：你**不需要**把 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将
令牌存储在 Gateway 网关主机上的认证配置文件中。
- 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的凭证配置中。
- 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
- Gemini CLI JSON 回复会从 `response` 中解析；用量会回退到
`stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
- Gemini CLI JSON 回复会从 `response` 解析；用量会回退到
`stats`，其中 `stats.cached` 会被标准化为 OpenClaw `cacheRead`。
### Z.AI（GLM）
@ -376,8 +257,8 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
- 凭证：`ZAI_API_KEY`
- 示例模型：`zai/glm-5.1`
- CLI：`openclaw onboard --auth-choice zai-api-key`
- 别名：`z.ai/*` 和 `z-ai/*` 会被规范化为 `zai/*`
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口
- 别名：`z.ai/*` 和 `z-ai/*` 会被标准化为 `zai/*`
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定界面
### Vercel AI Gateway
@ -393,11 +274,11 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
- 示例模型：`kilocode/kilo/auto`
- CLI：`openclaw onboard --auth-choice kilocode-api-key`
- Base URL：`https://api.kilo.ai/api/gateway/`
- 静态回退目录内置了 `kilocode/kilo/auto`；实时的
`https://api.kilo.ai/api/gateway/models` 发现机制可以进一步扩展运行时
- 静态回退目录内置 `kilocode/kilo/auto`；实时
`https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时
目录。
- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 决定，
并不是在 OpenClaw 中硬编码的。
- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 自行管理，
并非在 OpenClaw 中硬编码。
设置详情请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。
@ -405,25 +286,19 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
- OpenRouter：`openrouter`（`OPENROUTER_API_KEY`）
- 示例模型：`openrouter/auto`
- 只有当请求实际发往 `openrouter.ai` 时，OpenClaw 才会应用 OpenRouter 文档中说明的应用归因请求头
- OpenRouter 特有的 Anthropic `cache_control` 标记同样只会在
已验证的 OpenRouter 路由上启用，而不会用于任意代理 URL
- OpenRouter 仍然走代理风格的 OpenAI 兼容路径，因此仅原生
OpenAI 支持的请求整形（`serviceTier`、Responses `store`、
提示缓存提示、OpenAI reasoning 兼容载荷）不会被转发
- 由 Gemini 驱动的 OpenRouter 引用仅保留代理 Gemini thought-signature 清理；
原生 Gemini 重放校验和 bootstrap 重写保持关闭
- OpenClaw 仅在请求实际发往 `openrouter.ai` 时才会应用 OpenRouter 文档中说明的应用归因请求头
- OpenRouter 特有的 Anthropic `cache_control` 标记同样只会作用于经过验证的 OpenRouter 路由，而不是任意代理 URL
- OpenRouter 仍走代理风格的 OpenAI 兼容路径，因此仅适用于原生 OpenAI 的请求整形（`serviceTier`、Responses `store`、提示词缓存提示、OpenAI 推理兼容负载）不会被转发
- 基于 Gemini 的 OpenRouter 引用只保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和引导重写保持关闭
- Kilo Gateway：`kilocode`（`KILOCODE_API_KEY`）
- 示例模型：`kilocode/kilo/auto`
- 由 Gemini 驱动的 Kilo 引用保留相同的代理 Gemini thought-signature
清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的
提示会跳过代理 reasoning 注入
- MiniMax：`minimax`（API 密钥）和 `minimax-portal`（OAuth）
- 基于 Gemini 的 Kilo 引用保留相同的代理 Gemini thought-signature
清理路径；`kilocode/kilo/auto` 以及其他不支持代理推理的提示会跳过代理推理注入
- MiniMax：`minimax`（API key）和 `minimax-portal`（OAuth）
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
- 示例模型：`minimax/MiniMax-M2.7` 或 `minimax-portal/MiniMax-M2.7`
- MiniMax 新手引导 / API 密钥设置会写入显式的 M2.7 模型定义，
其中包含 `input: ["text", "image"]`；内置提供商目录会将聊天引用
保持为纯文本，直到该提供商配置被具体化
- MiniMax 新手引导/API key 设置会写入显式的 M2.7 模型定义，并带有
`input: ["text", "image"]`；内置提供商目录会在该提供商配置具体化之前，将聊天引用保持为仅文本
- Moonshot：`moonshot`（`MOONSHOT_API_KEY`）
- 示例模型：`moonshot/kimi-k2.6`
- Kimi Coding：`kimi`（`KIMI_API_KEY` 或 `KIMICODE_API_KEY`）
@ -449,35 +324,36 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
- BytePlus：`byteplus`（`BYTEPLUS_API_KEY`）
- 示例模型：`byteplus-plan/ark-code-latest`
- xAI：`xai`（`XAI_API_KEY`）
- 原生内置的 xAI 请求使用 xAI Responses 路径
- 原生内置 xAI 请求使用 xAI Responses 路径
- `/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、
`grok-4` 和 `grok-4-0709` 重写为它们对应的 `*-fast` 变体
`grok-4` 和 `grok-4-0709` 重写为其 `*-fast` 变体
- `tool_stream` 默认开启；设置
`agents.defaults.models["xai/<model>"].params.tool_stream` 为 `false` 可
禁用它
关闭
- Mistral：`mistral`（`MISTRAL_API_KEY`）
- 示例模型：`mistral/mistral-large-latest`
- CLI：`openclaw onboard --auth-choice mistral-api-key`
- Groq：`groq`（`GROQ_API_KEY`）
- Cerebras：`cerebras`（`CEREBRAS_API_KEY`）
- Cerebras 上的 GLM 模型使用 id `zai-glm-4.7` 和 `zai-glm-4.6`。
- Cerebras 上的 GLM 模型使用 ID `zai-glm-4.7` 和 `zai-glm-4.6`。
- OpenAI 兼容 Base URL：`https://api.cerebras.ai/v1`。
- GitHub Copilot：`github-copilot`（`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`）
- Hugging Face Inference 示例模型：`huggingface/deepseek-ai/DeepSeek-R1`；CLI：`openclaw onboard --auth-choice huggingface-api-key`。请参见 [Hugging Face（Inference）](/zh-CN/providers/huggingface)。
- Hugging Face Inference 示例模型：`huggingface/deepseek-ai/DeepSeek-R1`；CLI：`openclaw onboard --auth-choice huggingface-api-key`。参见 [Hugging Face（Inference）](/zh-CN/providers/huggingface)。
## 通过 `models.providers` 使用的提供商（自定义 / Base URL）
## 通过 `models.providers` 使用提供商（自定义/Base URL）
使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或
OpenAI / Anthropic 兼容代理。
使用 `models.providers`（或 `models.json`）添加**自定义**提供商或
OpenAI/Anthropic 兼容代理。
下方许多内置提供商插件已经发布了默认目录。
只有当你想覆盖默认的 base URL、请求头或模型列表时，才需要使用显式的
只有在你想覆盖默认 Base URL、请求头或模型列表时，才需要显式使用
`models.providers.<id>` 条目。
### Moonshot AI（Kimi）
Moonshot 作为内置提供商插件提供。默认请使用内置提供商，
只有在你需要覆盖 base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在你
需要覆盖 Base URL 或模型元数据时，才添加显式的 `models.providers.moonshot`
条目：
- 提供商：`moonshot`
- 凭证：`MOONSHOT_API_KEY`
@ -532,13 +408,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
}
```
旧版 `kimi/k2p5` 仍然作为兼容模型 id 被接受。
旧版 `kimi/k2p5` 仍然作为兼容模型 ID 被接受。
### Volcano Engine（Doubao）
Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。
- 提供商：`volcengine`（编程版：`volcengine-plan`）
- 提供商：`volcengine`（coding：`volcengine-plan`）
- 凭证：`VOLCANO_ENGINE_API_KEY`
- 示例模型：`volcengine-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice volcengine-api-key`
@ -551,13 +427,12 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
}
```
新手引导默认使用编程接口，但通用的 `volcengine/*`
新手引导默认使用 coding 界面，但通用 `volcengine/*`
目录会同时注册。
在新手引导 / 配置模型选择器中，Volcengine 凭证选项会优先显示
`volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，
OpenClaw 会回退到未过滤目录，而不是显示一个空的
提供商范围选择器。
在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示
`volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未加载，
OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范围选择器。
可用模型：
@ -567,7 +442,7 @@ OpenClaw 会回退到未过滤目录，而不是显示一个空的
- `volcengine/glm-4-7-251222`（GLM 4.7）
- `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K）
编程模型（`volcengine-plan`）：
Coding 模型（`volcengine-plan`）：
- `volcengine-plan/ark-code-latest`
- `volcengine-plan/doubao-seed-code`
@ -577,9 +452,9 @@ OpenClaw 会回退到未过滤目录，而不是显示一个空的
### BytePlus（国际版）
BytePlus ARK 为国际用户提供与 Volcano Engine 相同的模型访问能力。
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。
- 提供商：`byteplus`（编程版：`byteplus-plan`）
- 提供商：`byteplus`（coding：`byteplus-plan`）
- 凭证：`BYTEPLUS_API_KEY`
- 示例模型：`byteplus-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
@ -592,13 +467,12 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同的模型访问能力
}
```
新手引导默认使用编程接口，但通用的 `byteplus/*`
新手引导默认使用 coding 界面，但通用 `byteplus/*`
目录会同时注册。
在新手引导 / 配置模型选择器中，BytePlus 凭证选项会优先显示
`byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，
OpenClaw 会回退到未过滤目录，而不是显示一个空的
提供商范围选择器。
在新手引导/配置模型选择器中，BytePlus（国际版）凭证选项会优先显示
`byteplus/*` 和 `byteplus-plan/*` 条目。如果这些模型尚未加载，
OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范围选择器。
可用模型：
@ -606,7 +480,7 @@ OpenClaw 会回退到未过滤目录，而不是显示一个空的
- `byteplus/kimi-k2-5-260127`（Kimi K2.5）
- `byteplus/glm-4-7-251222`（GLM 4.7）
编程模型（`byteplus-plan`）：
Coding 模型（`byteplus-plan`）：
- `byteplus-plan/ark-code-latest`
- `byteplus-plan/doubao-seed-code`
@ -646,35 +520,35 @@ Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型：
MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax OAuth（全球）：`--auth-choice minimax-global-oauth`
- MiniMax OAuth（中国）：`--auth-choice minimax-cn-oauth`
- MiniMax API 密钥（全球）：`--auth-choice minimax-global-api`
- MiniMax API 密钥（中国）：`--auth-choice minimax-cn-api`
- MiniMax OAuth（Global）：`--auth-choice minimax-global-oauth`
- MiniMax OAuth（CN）：`--auth-choice minimax-cn-oauth`
- MiniMax API key（Global）：`--auth-choice minimax-global-api`
- MiniMax API key（CN）：`--auth-choice minimax-cn-api`
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或
`MINIMAX_API_KEY`
设置详情、模型选项和配置片段请参见 [/providers/minimax](/zh-CN/providers/minimax)。
在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认禁用 thinking，
除非你显式设置它，而 `/fast on` 会将
除非你显式设置它，并且 `/fast on` 会将
`MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
插件拥有的能力划分：
插件自有 capability 划分：
- 文本 / 聊天默认仍使用 `minimax/MiniMax-M2.7`
- 文本/聊天默认保持在 `minimax/MiniMax-M2.7`
- 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01`
- 图像理解在两个 MiniMax 认证路径上都由插件自有的 `MiniMax-VL-01` 提供
- Web 搜索仍使用提供商 id `minimax`
- 图像理解在两种 MiniMax 凭证路径上都使用插件自有的 `MiniMax-VL-01`
- Web 搜索保持使用提供商 ID `minimax`
### LM Studio
LM Studio 作为一个使用原生 API 的内置提供商插件提供：
LM Studio 作为内置提供商插件提供，并使用原生 API：
- 提供商：`lmstudio`
- 凭证：`LM_API_TOKEN`
- 默认推理 Base URL：`http://localhost:1234/v1`
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
然后设置一个模型（请替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
```json5
{
@ -686,7 +560,7 @@ LM Studio 作为一个使用原生 API 的内置提供商插件提供：
OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load`
进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。
设置与故障排除请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
设置和故障排除请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
### Ollama
@ -698,7 +572,7 @@ Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API：
- 安装：[https://ollama.com/download](https://ollama.com/download)
```bash
# 安装 Ollama，然后拉取一个模型：
# Install Ollama, then pull a model:
ollama pull llama3.3
```
@ -710,26 +584,26 @@ ollama pull llama3.3
}
```
当你通过 `OLLAMA_API_KEY` 选择启用时，OpenClaw 会在本地 `http://127.0.0.1:11434` 检测 Ollama，
当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，
并且内置提供商插件会将 Ollama 直接添加到
`openclaw onboard` 和模型选择器中。新手引导、云端 / 本地模式以及自定义配置请参见 [/providers/ollama](/zh-CN/providers/ollama)。
`openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。
### vLLM
vLLM 作为内置提供商插件提供，用于本地 / 自托管的 OpenAI 兼容
vLLM 作为内置提供商插件提供，适用于本地/自托管的 OpenAI 兼容
服务器：
- 提供商：`vllm`
- 凭证：可选（取决于你的服务器）
- 默认 base URL：`http://127.0.0.1:8000/v1`
- 默认 Base URL：`http://127.0.0.1:8000/v1`
要在本地启用自动发现（如果你的服务器不强制认证，任意值都可以）：
要在本地选择启用自动发现（如果你的服务器不强制凭证，任意值都可以）：
```bash
export VLLM_API_KEY="vllm-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
然后设置一个模型（请替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -743,21 +617,21 @@ export VLLM_API_KEY="vllm-local"
### SGLang
SGLang 作为内置提供商插件提供，用于快速自托管的
SGLang 作为内置提供商插件提供，适用于快速自托管的
OpenAI 兼容服务器：
- 提供商：`sglang`
- 凭证：可选（取决于你的服务器）
- 默认 base URL：`http://127.0.0.1:30000/v1`
- 默认 Base URL：`http://127.0.0.1:30000/v1`
要在本地启用自动发现（如果你的服务器不
强制认证，任意值都可以）：
要在本地选择启用自动发现（如果你的服务器不强制
凭证，任意值都可以）：
```bash
export SGLANG_API_KEY="sglang-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
然后设置一个模型（请替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -806,21 +680,20 @@ export SGLANG_API_KEY="sglang-local"
说明：
- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。
省略时，OpenClaw 默认使用：
- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选项。
如果省略，OpenClaw 默认使用：
- `reasoning: false`
- `input: ["text"]`
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`
- 建议：设置与你的代理 / 模型限制相匹配的显式值。
- 建议：设置与你的代理/模型限制相匹配的显式值。
- 对于非原生端点上的 `api: "openai-completions"`（任何 host 不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
- 代理风格的 OpenAI 兼容路由也会跳过仅原生 OpenAI 支持的请求
整形：没有 `service_tier`，没有 Responses `store`，没有提示缓存提示，没有
OpenAI reasoning 兼容载荷整形，也没有隐藏的 OpenClaw 归因
请求头。
- 如果 `baseUrl` 为空 / 省略，OpenClaw 会保留默认 OpenAI 行为（解析到 `api.openai.com`）。
- 为了安全起见，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。
- 代理风格的 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求
整形：没有 `service_tier`、没有 Responses `store`、没有提示词缓存提示、没有
OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归因请求头。
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认的 OpenAI 行为（即解析到 `api.openai.com`）。
- 为了安全起见，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。
## CLI 示例
@ -830,11 +703,11 @@ openclaw models set opencode/claude-opus-4-6
openclaw models list
```
另请参见：[/gateway/configuration](/zh-CN/gateway/configuration)，获取完整配置示例。
另请参见：[/gateway/configuration](/zh-CN/gateway/configuration) 了解完整配置示例。
## 相关内容
- [Models](/zh-CN/concepts/models) —— 模型配置与别名
- [Model Failover](/zh-CN/concepts/model-failover) —— 回退链与重试行为
- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) —— 模型配置键
- [Providers](/zh-CN/providers) —— 按提供商分类的设置指南
- [Models](/zh-CN/concepts/models) — 模型配置和别名
- [Model Failover](/zh-CN/concepts/model-failover) — 回退链和重试行为
- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键
- [Providers](/zh-CN/providers) — 按提供商分别说明的设置指南

785
docs/zh-CN/plugins/architecture.md
View File

File diff suppressed because it is too large Load Diff

232
docs/zh-CN/plugins/sdk-provider-plugins.md
View File

@ -1,37 +1,37 @@
---
read_when:
- 你正在构建一个新的模型提供商插件
- 你想将一个与 OpenAI 兼容的代理或自定义 LLM 添加到 OpenClaw 中
- 你想为 OpenClaw 添加一个兼容 OpenAI 的代理或自定义 LLM
- 你需要了解提供商认证、目录和运行时钩子
sidebarTitle: Provider Plugins
summary: 为 OpenClaw 构建模型提供商插件的分步指南
title: 构建提供商插件
x-i18n:
generated_at: "2026-04-21T06:04:34Z"
generated_at: "2026-04-21T08:24:18Z"
model: gpt-5.4
provider: openai
source_hash: 459761118c7394c1643c170edfec97c87e1c6323b436183b53ad7a2fed783b04
source_hash: 08494658def4a003a1e5752f68d9232bfbbbf76348cf6f319ea1a6855c2ae439
source_path: plugins/sdk-provider-plugins.md
workflow: 15
---
# 构建提供商插件
本指南将带你构建一个提供商插件，把模型提供商（LLM）添加到 OpenClaw 中。完成后，你将拥有一个带有模型目录、API 密钥认证和动态模型解析的提供商。
本指南将带你构建一个提供商插件，为 OpenClaw 添加一个模型提供商（LLM）。完成后，你将拥有一个带有模型目录、API 密钥认证和动态模型解析的提供商。
<Info>
如果你之前没有构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基础包结构和清单设置。
如果你之前没有构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基本的软件包结构和清单设置。
</Info>
<Tip>
提供商插件会把模型添加到 OpenClaw 的标准推理循环中。如果模型必须通过一个拥有线程、压缩或工具事件的原生智能体守护进程运行，请将该提供商与 [agent harness](/zh-CN/plugins/sdk-agent-harness) 配合使用，而不是把守护进程协议细节放进核心中。
提供商插件会将模型添加到 OpenClaw 的常规推理循环中。如果该模型必须通过一个原生智能体守护进程来运行，并由它负责线程、压缩或工具事件，请将该提供商与一个 [智能体 harness](/zh-CN/plugins/sdk-agent-harness) 搭配使用，而不是把守护进程协议细节放进核心中。
</Tip>
## 演练
<Steps>
<a id="step-1-package-and-manifest"></a>
<Step title="包和清单">
<Step title="软件包和清单">
<CodeGroup>
```json package.json
{
@ -57,7 +57,7 @@ x-i18n:
{
"id": "acme-ai",
"name": "Acme AI",
"description": "Acme AI model provider",
"description": "Acme AI 模型提供商",
"providers": ["acme-ai"],
"modelSupport": {
"modelPrefixes": ["acme-"]
@ -73,12 +73,12 @@ x-i18n:
"provider": "acme-ai",
"method": "api-key",
"choiceId": "acme-ai-api-key",
"choiceLabel": "Acme AI API key",
"choiceLabel": "Acme AI API 密钥",
"groupId": "acme-ai",
"groupLabel": "Acme AI",
"cliFlag": "--acme-ai-api-key",
"cliOption": "--acme-ai-api-key <key>",
"cliDescription": "Acme AI API key"
"cliDescription": "Acme AI API 密钥"
}
],
"configSchema": {
@ -89,12 +89,12 @@ x-i18n:
```
</CodeGroup>
该清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就能在不加载你的插件运行时的情况下检测凭证。当某个提供商变体应复用另一个提供商 id 的认证时，请添加 `providerAuthAliases`。`modelSupport` 是可选的，它让 OpenClaw 能在运行时钩子存在之前，根据像 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你要在 ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段是必填的。
清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测凭证。当某个提供商变体应复用另一个提供商 id 的认证时，添加 `providerAuthAliases`。`modelSupport` 是可选的，它允许 OpenClaw 在运行时钩子存在之前，就通过像 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你要在 ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段是必需的。
</Step>
<Step title="注册提供商">
一个最小可用的提供商需要 `id`、`label`、`auth` 和 `catalog`：
一个最小化的提供商需要 `id`、`label`、`auth` 和 `catalog`：
```typescript index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -103,7 +103,7 @@ x-i18n:
export default definePluginEntry({
id: "acme-ai",
name: "Acme AI",
description: "Acme AI model provider",
description: "Acme AI 模型提供商",
register(api) {
api.registerProvider({
id: "acme-ai",
@ -115,12 +115,12 @@ x-i18n:
createProviderApiKeyAuthMethod({
providerId: "acme-ai",
methodId: "api-key",
label: "Acme AI API key",
hint: "API key from your Acme AI dashboard",
label: "Acme AI API 密钥",
hint: "来自你的 Acme AI 控制台的 API 密钥",
optionKey: "acmeAiApiKey",
flagName: "--acme-ai-api-key",
envVar: "ACME_AI_API_KEY",
promptMessage: "Enter your Acme AI API key",
promptMessage: "输入你的 Acme AI API 密钥",
defaultModel: "acme-ai/acme-large",
}),
],
@ -167,7 +167,7 @@ x-i18n:
这就是一个可工作的提供商。用户现在可以运行 `openclaw onboard --acme-ai-api-key <key>`，并选择 `acme-ai/acme-large` 作为他们的模型。
如果上游提供商使用的控制令牌与 OpenClaw 不同，请添加一个小型双向文本转换，而不是替换流路径：
如果上游提供商使用的控制令牌与 OpenClaw 不同，请添加一个小型的双向文本转换，而不是替换流路径：
```typescript
api.registerTextTransforms({
@ -184,9 +184,9 @@ x-i18n:
});
```
`input` 会在传输前重写最终系统提示词和文本消息内容。`output` 会在 OpenClaw 解析其自身控制标记或进行渠道投递之前，重写助手文本增量和最终文本。
`input` 会在传输之前重写最终系统提示和文本消息内容。`output` 会在 OpenClaw 解析其自身控制标记或进行渠道投递之前，重写助手文本增量和最终文本。
对于仅注册一个带有 API 密钥认证并附带单个基于目录的运行时的文本提供商的内置提供商，优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数：
对于那些只注册一个带 API 密钥认证且附带单个目录支持运行时的文本提供商的内置提供商，优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数：
```typescript
import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
@ -194,19 +194,19 @@ x-i18n:
export default defineSingleProviderPluginEntry({
id: "acme-ai",
name: "Acme AI",
description: "Acme AI model provider",
description: "Acme AI 模型提供商",
provider: {
label: "Acme AI",
docsPath: "/providers/acme-ai",
auth: [
{
methodId: "api-key",
label: "Acme AI API key",
hint: "API key from your Acme AI dashboard",
label: "Acme AI API 密钥",
hint: "来自你的 Acme AI 控制台的 API 密钥",
optionKey: "acmeAiApiKey",
flagName: "--acme-ai-api-key",
envVar: "ACME_AI_API_KEY",
promptMessage: "Enter your Acme AI API key",
promptMessage: "输入你的 Acme AI API 密钥",
defaultModel: "acme-ai/acme-large",
},
],
@ -221,18 +221,18 @@ x-i18n:
});
```
如果你的认证流程还需要在新手引导期间修补 `models.providers.*`、别名以及智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数包括 `createDefaultModelPresetAppliers(...)`、`createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。
如果你的认证流程在新手引导期间还需要修补 `models.providers.*`、别名以及智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数包括 `createDefaultModelPresetAppliers(...)`、`createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。
当某个提供商的原生端点在标准 `openai-completions` 传输上支持流式 usage 块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和 `applyProviderNativeStreamingUsageCompat(...)` 会根据端点能力映射检测支持情况，因此原生 Moonshot/DashScope 风格端点即使使用自定义提供商 id 的插件，也仍然可以选择启用。
当某个提供商的原生端点在常规 `openai-completions` 传输上支持流式 usage 块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和 `applyProviderNativeStreamingUsageCompat(...)` 会根据端点能力映射检测支持情况，因此原生 Moonshot/DashScope 风格的端点即使插件使用的是自定义提供商 id，也仍然可以选择启用。
</Step>
<Step title="添加动态模型解析">
如果你的提供商接受任意模型 id（例如代理或路由器），请添加 `resolveDynamicModel`：
如果你的提供商接受任意模型 id（比如代理或路由器），请添加 `resolveDynamicModel`：
```typescript
api.registerProvider({
// ... id, label, auth, catalog from above
// ... 上面的 id、label、auth、catalog
resolveDynamicModel: (ctx) => ({
id: ctx.modelId,
@ -249,14 +249,14 @@ x-i18n:
});
```
如果解析需要进行网络调用，请使用 `prepareDynamicModel` 做异步预热——它完成后会再次运行 `resolveDynamicModel`。
如果解析需要进行网络调用，请使用 `prepareDynamicModel` 来进行异步预热——在它完成后，`resolveDynamicModel` 会再次运行。
</Step>
<Step title="按需添加运行时钩子">
<Step title="添加运行时钩子（按需）">
大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着你的提供商需求增加，再逐步添加钩子。
共享辅助构建器现在已经覆盖了最常见的 replay/tool-compat 系列，因此插件通常不需要逐个手动接线每个钩子：
共享辅助构建器现在已经覆盖了最常见的重放/工具兼容性家族，因此插件通常不需要再逐个手动连接每个钩子：
```typescript
import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
@ -276,17 +276,17 @@ x-i18n:
});
```
当前可用的 replay 系列：
当前可用的重放家族：
| 系列 | 会接入的内容 |
| 家族 | 会接入的内容 |
| --- | --- |
| `openai-compatible` | OpenAI 兼容传输的共享 OpenAI 风格 replay 策略，包括工具调用 id 清理、assistant-first 顺序修复，以及在传输需要时的通用 Gemini 轮次校验 |
| `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知 replay 策略，因此 Anthropic message 传输只有在解析后的模型实际是 Claude id 时，才会获得 Claude 专属的 thinking block 清理 |
| `google-gemini` | 原生 Gemini replay 策略，外加 bootstrap replay 清理和带标签的推理输出模式 |
| `passthrough-gemini` | 针对通过 OpenAI 兼容代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini replay 校验或 bootstrap 重写 |
| `hybrid-anthropic-openai` | 用于在同一个插件中混合 Anthropic message 和 OpenAI 兼容模型面向层的提供商的混合策略；可选的仅限 Claude 的 thinking block 丢弃仍然只作用于 Anthropic 一侧 |
| `openai-compatible` | 面向兼容 OpenAI 的传输的共享 OpenAI 风格重放策略，包括工具调用 id 清理、assistant 优先顺序修复，以及传输所需的通用 Gemini 轮次校验 |
| `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知重放策略，因此基于 Anthropic 消息的传输只有在解析后的模型确实是 Claude id 时，才会获得 Claude 专用的思维块清理 |
| `google-gemini` | 原生 Gemini 重放策略，加上 bootstrap 重放清理和带标签的推理输出模式 |
| `passthrough-gemini` | 面向通过兼容 OpenAI 的代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini 重放校验或 bootstrap 重写 |
| `hybrid-anthropic-openai` | 用于在一个插件中混合 Anthropic 消息和兼容 OpenAI 模型表面的提供商的混合策略；可选的仅 Claude 思维块丢弃仍然限定在 Anthropic 一侧 |
实际内置示例：
真实的内置示例：
- `google` 和 `google-gemini-cli`：`google-gemini`
- `openrouter`、`kilocode`、`opencode` 和 `opencode-go`：`passthrough-gemini`
@ -294,19 +294,19 @@ x-i18n:
- `minimax`：`hybrid-anthropic-openai`
- `moonshot`、`ollama`、`xai` 和 `zai`：`openai-compatible`
当前可用的流系列：
当前可用的流家族：
| 系列 | 会接入的内容 |
| 家族 | 会接入的内容 |
| --- | --- |
| `google-thinking` | 共享流路径上的 Gemini thinking 负载规范化 |
| `kilocode-thinking` | 共享代理流路径上的 Kilo 推理包装器，其中 `kilo/auto` 和不受支持的代理推理 id 会跳过注入的 thinking |
| `moonshot-thinking` | 根据配置和 `/think` 级别进行的 Moonshot 二进制 native-thinking 负载映射 |
| `minimax-fast-mode` | 共享流路径上的 MiniMax fast-mode 模型重写 |
| `openai-responses-defaults` | 共享原生 OpenAI/Codex Responses 包装器：归因头、`/fast`/`serviceTier`、文本详细程度、原生 Codex web search、reasoning-compat 负载整形，以及 Responses 上下文管理 |
| `openrouter-thinking` | 面向代理路由的 OpenRouter 推理包装器，且对不受支持模型和 `auto` 的跳过由中心统一处理 |
| `tool-stream-default-on` | 针对像 Z.AI 这类希望默认启用工具流式传输、除非被明确禁用的提供商的默认开启 `tool_stream` 包装器 |
| `google-thinking` | 在共享流路径上进行 Gemini thinking 负载规范化 |
| `kilocode-thinking` | 在共享代理流路径上为 Kilo 推理提供包装器，并且会为 `kilo/auto` 和不支持的代理推理 id 跳过注入的 thinking |
| `moonshot-thinking` | 根据配置和 `/think` 级别，对 Moonshot 二进制原生 thinking 负载进行映射 |
| `minimax-fast-mode` | 在共享流路径上进行 MiniMax fast-mode 模型重写 |
| `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归因头、`/fast`/`serviceTier`、文本详细程度、原生 Codex web 搜索、推理兼容负载整形，以及 Responses 上下文管理 |
| `openrouter-thinking` | 面向代理路由的 OpenRouter 推理包装器，并集中处理不支持模型/`auto` 跳过 |
| `tool-stream-default-on` | 面向像 Z.AI 这样希望默认启用工具流式传输、除非显式禁用的提供商的默认开启 `tool_stream` 包装器 |
实际内置示例：
真实的内置示例：
- `google` 和 `google-gemini-cli`：`google-thinking`
- `kilocode`：`kilocode-thinking`
@ -316,7 +316,7 @@ x-i18n:
- `openrouter`：`openrouter-thinking`
- `zai`：`tool-stream-default-on`
`openclaw/plugin-sdk/provider-model-shared` 还导出了 replay 系列枚举，以及这些系列所基于的共享辅助函数。常见公开导出包括：
`openclaw/plugin-sdk/provider-model-shared` 还导出了 replay family 枚举，以及这些家族所基于的共享辅助函数。常见的公共导出包括：
- `ProviderReplayFamily`
- `buildProviderReplayFamilyHooks(...)`
@ -324,36 +324,36 @@ x-i18n:
- Gemini replay 辅助函数，例如 `sanitizeGoogleGeminiReplayHistory(...)` 和 `resolveTaggedReasoningOutputMode()`
- 端点/模型辅助函数，例如 `resolveProviderEndpoint(...)`、`normalizeProviderId(...)`、`normalizeGooglePreviewModelId(...)` 和 `normalizeNativeXaiModelId(...)`
`openclaw/plugin-sdk/provider-stream` 同时公开了系列构建器以及这些系列复用的公共包装器辅助函数。常见公开导出包括：
`openclaw/plugin-sdk/provider-stream` 同时公开了 family 构建器，以及这些家族复用的公共包装器辅助函数。常见的公共导出包括：
- `ProviderStreamFamily`
- `buildProviderStreamFamilyHooks(...)`
- `composeProviderStreamWrappers(...)`
- 共享 OpenAI/Codex 包装器，例如 `createOpenAIAttributionHeadersWrapper(...)`、`createOpenAIFastModeWrapper(...)`、`createOpenAIServiceTierWrapper(...)`、`createOpenAIResponsesContextManagementWrapper(...)` 和 `createCodexNativeWebSearchWrapper(...)`
- 共享代理/提供商包装器，例如 `createOpenRouterWrapper(...)`、`createToolStreamWrapper(...)` 和 `createMinimaxFastModeWrapper(...)`
- 共享的 OpenAI/Codex 包装器，例如 `createOpenAIAttributionHeadersWrapper(...)`、`createOpenAIFastModeWrapper(...)`、`createOpenAIServiceTierWrapper(...)`、`createOpenAIResponsesContextManagementWrapper(...)` 和 `createCodexNativeWebSearchWrapper(...)`
- 共享的代理/提供商包装器，例如 `createOpenRouterWrapper(...)`、`createToolStreamWrapper(...)` 和 `createMinimaxFastModeWrapper(...)`
某些流辅助函数会有意保留为提供商本地实现。当前内置示例：`@openclaw/anthropic-provider` 从其公共 `api.ts` / `contract-api.ts` 接缝导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 Anthropic 包装器构建器。这些辅助函数仍然保持 Anthropic 专属，因为它们还编码了 Claude OAuth beta 处理和 `context1m` 门控。
一些流辅助函数会有意保持为提供商本地。当前的内置示例：`@openclaw/anthropic-provider` 通过其公共 `api.ts` / `contract-api.ts` 接缝导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及更底层的 Anthropic 包装器构建器。这些辅助函数仍然保持 Anthropic 专属，因为它们还编码了 Claude OAuth beta 处理和 `context1m` 门控。
其他内置提供商也会在行为无法在各个系列间干净共享时，将传输专属包装器保留为本地实现。当前示例：内置 xAI 插件将原生 xAI Responses 整形保留在它自己的 `wrapStreamFn` 中，包括 `/fast` 别名重写、默认 `tool_stream`、不受支持的 strict-tool 清理，以及 xAI 专属的 reasoning 负载移除。
其他内置提供商也会在行为无法在各家族之间清晰共享时，将传输专用包装器保留在本地。当前示例：内置 xAI 插件将原生 xAI Responses 整形保留在自己的 `wrapStreamFn` 中，包括 `/fast` 别名重写、默认 `tool_stream`、不支持的严格工具清理，以及 xAI 专属的推理负载移除。
`openclaw/plugin-sdk/provider-tools` 目前公开了一个共享工具 schema 系列，以及共享 schema/兼容性辅助函数：
`openclaw/plugin-sdk/provider-tools` 当前公开了一个共享工具模式家族，以及共享的 schema/兼容性辅助函数：
- `ProviderToolCompatFamily` 记录了当前共享系列清单。
- `ProviderToolCompatFamily` 记录了当前的共享 family 清单。
- `buildProviderToolCompatFamilyHooks("gemini")` 会为需要 Gemini 安全工具 schema 的提供商接入 Gemini schema 清理 + 诊断。
- `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)` 是底层公开的 Gemini schema 辅助函数。
- `resolveXaiModelCompatPatch()` 返回内置 xAI 兼容性补丁：`toolSchemaProfile: "xai"`、不受支持的 schema 关键字、原生 `web_search` 支持，以及 HTML 实体工具调用参数解码。
- `applyXaiModelCompat(model)` 会在解析后的模型进入运行器之前，对其应用同一个 xAI 兼容性补丁。
- `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)` 是底层的公共 Gemini schema 辅助函数。
- `resolveXaiModelCompatPatch()` 返回内置的 xAI compat patch：`toolSchemaProfile: "xai"`、不支持的 schema 关键字、原生 `web_search` 支持，以及 HTML 实体工具调用参数解码。
- `applyXaiModelCompat(model)` 会在解析后的模型到达运行器之前，对其应用同一个 xAI compat patch。
实际内置示例：xAI 插件使用 `normalizeResolvedModel` 加上 `contributeResolvedModelCompat`，以保持这些兼容性元数据由提供商自己管理，而不是在核心中硬编码 xAI 规则。
真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 加上 `contributeResolvedModelCompat`，以便让这份兼容性元数据由提供商自己维护，而不是在核心中硬编码 xAI 规则。
同样的包根模式也支持其他内置提供商：
同样的软件包根模式也支撑着其他内置提供商：
- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助函数和 realtime 提供商构建器
- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助函数以及实时提供商构建器
- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导/配置辅助函数
<Tabs>
<Tab title="令牌交换">
对于需要在每次推理调用前执行令牌交换的提供商：
对于那些需要在每次推理调用之前进行令牌交换的提供商：
```typescript
prepareRuntimeAuth: async (ctx) => {
@ -367,7 +367,7 @@ x-i18n:
```
</Tab>
<Tab title="自定义请求头">
对于需要自定义请求头或请求体修改的提供商：
对于那些需要自定义请求头或请求体修改的提供商：
```typescript
// wrapStreamFn returns a StreamFn derived from ctx.streamFn
@ -384,8 +384,8 @@ x-i18n:
},
```
</Tab>
<Tab title="原生传输标识">
对于需要在通用 HTTP 或 WebSocket 传输上附加原生请求/会话请求头或元数据的提供商：
<Tab title="原生传输身份">
对于那些需要在通用 HTTP 或 WebSocket 传输上添加原生请求/会话头或元数据的提供商：
```typescript
resolveTransportTurnState: (ctx) => ({
@ -406,7 +406,7 @@ x-i18n:
```
</Tab>
<Tab title="用量和计费">
对于公开用量/计费数据的提供商：
对于那些暴露用量/计费数据的提供商：
```typescript
resolveUsageAuth: async (ctx) => {
@ -421,73 +421,73 @@ x-i18n:
</Tabs>
<Accordion title="所有可用的提供商钩子">
OpenClaw 会按以下顺序调用这些钩子。大多数提供商只会用到 2–3 个：
OpenClaw 会按这个顺序调用钩子。大多数提供商只会用到 2–3 个：
| # | 钩子 | 何时使用 |
| --- | --- | --- |
| 1 | `catalog` | 模型目录或 base URL 默认值 |
| 2 | `applyConfigDefaults` | 在配置具体化期间应用由提供商管理的全局默认值 |
| 1 | `catalog` | 模型目录或默认 `baseUrl` |
| 2 | `applyConfigDefaults` | 在配置实体化期间应用由提供商拥有的全局默认值 |
| 3 | `normalizeModelId` | 在查找前清理旧版/预览版模型 id 别名 |
| 4 | `normalizeTransport` | 在通用模型组装前清理提供商系列的 `api` / `baseUrl` |
| 4 | `normalizeTransport` | 在通用模型组装前清理 provider-family `api` / `baseUrl` |
| 5 | `normalizeConfig` | 规范化 `models.providers.<id>` 配置 |
| 6 | `applyNativeStreamingUsageCompat` | 针对配置提供商的原生流式 usage 兼容性重写 |
| 7 | `resolveConfigApiKey` | 由提供商管理的 env-marker 认证解析 |
| 8 | `resolveSyntheticAuth` | 本地/自托管或基于配置的 synthetic 认证 |
| 9 | `shouldDeferSyntheticProfileAuth` | 将 synthetic 存储配置文件占位符优先级降到 env/config 认证之后 |
| 6 | `applyNativeStreamingUsageCompat` | 针对配置提供商的原生流式 usage compat 重写 |
| 7 | `resolveConfigApiKey` | 由提供商拥有的 env-marker 认证解析 |
| 8 | `resolveSyntheticAuth` | 本地/自托管或基于配置的合成认证 |
| 9 | `shouldDeferSyntheticProfileAuth` | 让 env/config 认证优先于较低级别的合成已存储配置文件占位符 |
| 10 | `resolveDynamicModel` | 接受任意上游模型 id |
| 11 | `prepareDynamicModel` | 在解析前进行异步元数据获取 |
| 12 | `normalizeResolvedModel` | 在运行器之前进行传输重写 |
| 11 | `prepareDynamicModel` | 解析前异步获取元数据 |
| 12 | `normalizeResolvedModel` | 在进入运行器之前进行传输重写 |
运行时回退说明：
- `normalizeConfig` 会先检查匹配的提供商，然后再检查其他具备钩子能力的提供商插件，直到其中一个实际修改配置为止。如果没有任何提供商钩子重写受支持的 Google 系列配置条目，内置 Google 配置规范化器仍会生效。
- `resolveConfigApiKey` 在公开该钩子时会使用提供商钩子。内置 `amazon-bedrock` 路径在这里也有一个内建的 AWS env-marker 解析器，尽管 Bedrock 运行时认证本身仍使用 AWS SDK 默认链。
| 13 | `contributeResolvedModelCompat` | 用于兼容传输后面的供应商模型的兼容性标志 |
- `normalizeConfig` 会先检查匹配的提供商，然后检查其他支持钩子的提供商插件，直到有一个实际更改了配置。
如果没有任何提供商钩子重写受支持的 Google family 配置项，内置的 Google 配置规范化器仍会生效。
- `resolveConfigApiKey` 在提供商暴露该钩子时会使用提供商钩子。内置的 `amazon-bedrock` 路径在这里也有一个内建的 AWS env-marker 解析器，尽管 Bedrock 运行时认证本身仍然使用 AWS SDK 默认链。
| 13 | `contributeResolvedModelCompat` | 为通过其他兼容传输提供的厂商模型提供 compat 标志 |
| 14 | `capabilities` | 旧版静态能力包；仅用于兼容性 |
| 15 | `normalizeToolSchemas` | 在注册前由提供商管理的工具 schema 清理 |
| 16 | `inspectToolSchemas` | 由提供商管理的工具 schema 诊断 |
| 17 | `resolveReasoningOutputMode` | 标记式与原生推理输出契约 |
| 15 | `normalizeToolSchemas` | 在注册前进行由提供商拥有的工具 schema 清理 |
| 16 | `inspectToolSchemas` | 由提供商拥有的工具 schema 诊断 |
| 17 | `resolveReasoningOutputMode` | 带标签与原生推理输出契约 |
| 18 | `prepareExtraParams` | 默认请求参数 |
| 19 | `createStreamFn` | 完全自定义的 StreamFn 传输 |
| 20 | `wrapStreamFn` | 标准流路径上的自定义请求头/请求体包装器 |
| 20 | `wrapStreamFn` | 常规流路径上的自定义头/请求体包装器 |
| 21 | `resolveTransportTurnState` | 原生逐轮请求头/元数据 |
| 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话请求头/冷却时间 |
| 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话头/冷却时间 |
| 23 | `formatApiKey` | 自定义运行时令牌形态 |
| 24 | `refreshOAuth` | 自定义 OAuth 刷新 |
| 25 | `buildAuthDoctorHint` | 认证修复指引 |
| 26 | `matchesContextOverflowError` | 由提供商管理的上下文溢出检测 |
| 27 | `classifyFailoverReason` | 由提供商管理的限流/过载分类 |
| 28 | `isCacheTtlEligible` | 提示词缓存 TTL 门控 |
| 26 | `matchesContextOverflowError` | 由提供商拥有的溢出检测 |
| 27 | `classifyFailoverReason` | 由提供商拥有的限流/过载分类 |
| 28 | `isCacheTtlEligible` | 提示缓存 TTL 门控 |
| 29 | `buildMissingAuthMessage` | 自定义缺失认证提示 |
| 30 | `suppressBuiltInModel` | 隐藏过时的上游条目 |
| 31 | `augmentModelCatalog` | synthetic 前向兼容条目 |
| 32 | `isBinaryThinking` | 二进制 thinking 开/关 |
| 33 | `supportsXHighThinking` | `xhigh` 推理支持 |
| 34 | `supportsAdaptiveThinking` | 自适应 thinking 支持 |
| 35 | `supportsMaxThinking` | `max` 推理支持 |
| 36 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略 |
| 37 | `isModernModelRef` | live/smoke 模型匹配 |
| 38 | `prepareRuntimeAuth` | 推理前令牌交换 |
| 39 | `resolveUsageAuth` | 自定义用量凭证解析 |
| 40 | `fetchUsageSnapshot` | 自定义用量端点 |
| 41 | `createEmbeddingProvider` | 用于 memory/search 的由提供商管理的嵌入适配器 |
| 42 | `buildReplayPolicy` | 自定义转录回放/压缩策略 |
| 43 | `sanitizeReplayHistory` | 在通用清理后执行的提供商专属 replay 重写 |
| 44 | `validateReplayTurns` | 在嵌入式运行器之前执行严格的 replay 轮次校验 |
| 45 | `onModelSelected` | 选择后的回调（例如遥测） |
| 31 | `augmentModelCatalog` | 合成的前向兼容条目 |
| 32 | `resolveThinkingProfile` | 模型专属 `/think` 选项集 |
| 33 | `isBinaryThinking` | 二进制 thinking 开/关兼容性 |
| 34 | `supportsXHighThinking` | `xhigh` 推理支持兼容性 |
| 35 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略兼容性 |
| 36 | `isModernModelRef` | 实时/smoke 模型匹配 |
| 37 | `prepareRuntimeAuth` | 推理前进行令牌交换 |
| 38 | `resolveUsageAuth` | 自定义用量凭证解析 |
| 39 | `fetchUsageSnapshot` | 自定义用量端点 |
| 40 | `createEmbeddingProvider` | 用于 memory/search 的提供商自有嵌入适配器 |
| 41 | `buildReplayPolicy` | 自定义转录重放/压缩策略 |
| 42 | `sanitizeReplayHistory` | 在通用清理之后进行提供商专属 replay 重写 |
| 43 | `validateReplayTurns` | 在嵌入式运行器之前进行严格的 replay-turn 校验 |
| 44 | `onModelSelected` | 选择模型后的回调（例如遥测） |
提示词调优说明：
提示调优说明：
- `resolveSystemPromptContribution` 允许提供商为某个模型系列注入具备缓存感知的系统提示词指导。当行为属于某个提供商/模型系列，并且应保留稳定/动态缓存拆分时，优先使用它，而不是 `before_prompt_build`。
- `resolveSystemPromptContribution` 允许提供商为某个模型 family 注入具备缓存感知能力的系统提示指引。如果该行为属于某个单独的提供商/模型 family，并且应保留稳定/动态缓存拆分，优先使用它，而不是 `before_prompt_build`。
有关详细说明和真实示例，请参阅 [Internals: Provider Runtime Hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
如需详细说明和真实示例，请参阅 [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture#provider-runtime-hooks)。
</Accordion>
</Step>
<Step title="添加额外能力（可选）">
<a id="step-5-add-extra-capabilities"></a>
提供商插件除了文本推理之外，还可以注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和 web search：
提供商插件除了文本推理之外，还可以注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和 web 搜索：
```typescript
register(api) {
@ -570,7 +570,7 @@ x-i18n:
api.registerWebFetchProvider({
id: "acme-ai-fetch",
label: "Acme Fetch",
hint: "Fetch pages through Acme's rendering backend.",
hint: "通过 Acme 的渲染后端抓取页面。",
envVars: ["ACME_FETCH_API_KEY"],
placeholder: "acme-...",
signupUrl: "https://acme.example.com/fetch",
@ -581,7 +581,7 @@ x-i18n:
acme.apiKey = value;
},
createTool: () => ({
description: "Fetch a page through Acme Fetch.",
description: "通过 Acme Fetch 抓取页面。",
parameters: {},
execute: async (args) => ({ content: [] }),
}),
@ -595,11 +595,11 @@ x-i18n:
}
```
OpenClaw 会将其归类为 **hybrid-capability** 插件。这是公司插件（每个供应商一个插件）的推荐模式。请参见 [Internals: Capability Ownership](/zh-CN/plugins/architecture#capability-ownership-model)。
OpenClaw 将这类插件归类为 **hybrid-capability** 插件。这是公司级插件（每个厂商一个插件）的推荐模式。参见 [内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。
对于视频生成，优先使用上面所示的模式感知能力结构：`generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages`、`maxInputVideos` 和 `maxDurationSeconds` 这样的扁平聚合字段，不足以干净地声明转换模式支持或已禁用模式。
对于视频生成，优先使用上面展示的按模式区分的能力结构：`generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages`、`maxInputVideos` 和 `maxDurationSeconds` 这样的扁平聚合字段不足以清晰地声明变换模式支持或已禁用模式。
音乐生成提供商也应遵循同样的模式：`generate` 用于仅基于提示词的生成，`edit` 用于基于参考图像的生成。像 `maxInputImages`、`supportsLyrics` 和 `supportsFormat` 这样的扁平聚合字段，不足以声明 edit 支持；显式的 `generate` / `edit` 块才是预期契约。
音乐生成提供商也应遵循相同模式：`generate` 用于仅基于提示词的生成，`edit` 用于基于参考图像的生成。像 `maxInputImages`、`supportsLyrics` 和 `supportsFormat` 这样的扁平聚合字段不足以声明 edit 支持；显式的 `generate` / `edit` 块才是预期契约。
</Step>
@ -654,7 +654,7 @@ clawhub package publish your-org/your-plugin
```
<bundled-plugin-root>/acme-ai/
├── package.json # openclaw.providers 元数据
├── openclaw.plugin.json # 带有提供商认证元数据的清单
├── openclaw.plugin.json # 带提供商认证元数据的清单
├── index.ts # definePluginEntry + registerProvider
└── src/
├── provider.test.ts # 测试
@ -670,11 +670,11 @@ clawhub package publish your-org/your-plugin
| `simple` | 第一轮 | 纯 API 密钥提供商 |
| `profile` | 在 simple 之后 | 受认证配置文件控制的提供商 |
| `paired` | 在 profile 之后 | 合成多个相关条目 |
| `late` | 最后一轮 | 覆盖现有提供商（冲突时生效） |
| `late` | 最后一轮 | 覆盖现有提供商（冲突时胜出） |
## 后续步骤
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 如果你的插件也提供一个渠道
- [SDK 运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助函数（TTS、搜索、subagent）
- [SDK 概览](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助函数（TTS、搜索、子智能体）
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考
- [Plugin Internals](/zh-CN/plugins/architecture#provider-runtime-hooks) — 钩子细节和内置示例
- [插件内部机制](/zh-CN/plugins/architecture#provider-runtime-hooks) — 钩子细节和内置示例

70
docs/zh-CN/tools/agent-send.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 你想从脚本或命令行触发智能体运行
- 你需要以编程方式将智能体回复投递到聊天渠道
summary: 从 CLI 运行智能体回合，并可选择将回复投递到渠道
- 你想要从脚本或命令行触发智能体运行
- 你需要以编程方式将智能体回复发送到聊天渠道
summary: 从 CLI 运行智能体轮次，并可选择将回复发送到渠道
title: 智能体发送
x-i18n:
generated_at: "2026-04-05T10:10:06Z"
generated_at: "2026-04-21T08:24:19Z"
model: gpt-5.4
provider: openai
source_hash: 42ea2977e89fb28d2afd07e5f6b1560ad627aea8b72fde36d8e324215c710afc
source_hash: 0550ad38efb2711f267a62b905fd150987a98801247de780ed3df97f27245704
source_path: tools/agent-send.md
workflow: 15
---
# 智能体发送
`openclaw agent` 可从命令行运行单个智能体回合，而无需入站聊天消息。你可以将它用于脚本化工作流、测试和程序化投递。
`openclaw agent` 可在无需入站聊天消息的情况下，从命令行运行单个智能体轮次。可将其用于脚本化工作流、测试以及以编程方式进行发送。
## 快速开始
<Steps>
<Step title="运行一个简单的智能体回合">
<Step title="运行一个简单的智能体轮次">
```bash
openclaw agent --message "What is the weather today?"
```
@ -31,24 +31,24 @@ x-i18n:
<Step title="指定特定智能体或会话">
```bash
# Target a specific agent
# 指定特定智能体
openclaw agent --agent ops --message "Summarize logs"
# Target a phone number (derives session key)
# 指定电话号码（派生会话键）
openclaw agent --to +15555550123 --message "Status update"
# Reuse an existing session
# 复用现有会话
openclaw agent --session-id abc123 --message "Continue the task"
```
</Step>
<Step title="将回复投递到某个渠道">
<Step title="将回复发送到渠道">
```bash
# Deliver to WhatsApp (default channel)
# 发送到 WhatsApp（默认渠道）
openclaw agent --to +15555550123 --message "Report ready" --deliver
# Deliver to Slack
# 发送到 Slack
openclaw agent --agent ops --message "Generate report" \
--deliver --reply-channel slack --reply-to "#reports"
```
@ -58,41 +58,41 @@ x-i18n:
## 标志
| 标志 | 说明 |
| 标志 | 说明 |
| ----------------------------- | ----------------------------------------------------------- |
| `--message \<text\>` | 要发送的消息（必需） |
| `--to \<dest\>` | 从目标派生会话键（电话号码、聊天 id） |
| `--agent \<id\>` | 指定已配置的智能体（使用其 `main` 会话） |
| `--session-id \<id\>` | 通过 id 复用现有会话 |
| `--local` | 强制使用本地嵌入式运行时（跳过 Gateway 网关） |
| `--deliver` | 将回复发送到聊天渠道 |
| `--channel \<name\>` | 投递渠道（whatsapp、telegram、discord、slack 等） |
| `--reply-to \<target\>` | 覆盖投递目标 |
| `--reply-channel \<name\>` | 覆盖投递渠道 |
| `--reply-account \<id\>` | 覆盖投递账号 id |
| `--thinking \<level\>` | 设置 thinking 级别（off、minimal、low、medium、high、xhigh） |
| `--verbose \<on\|full\|off\>` | 设置 verbose 级别 |
| `--timeout \<seconds\>` | 覆盖智能体超时时间 |
| `--json` | 输出结构化 JSON |
| `--message \<text\>` | 要发送的消息（必需） |
| `--to \<dest\>` | 从目标（电话、聊天 id）派生会话键 |
| `--agent \<id\>` | 指定已配置的智能体（使用其 `main` 会话） |
| `--session-id \<id\>` | 按 id 复用现有会话 |
| `--local` | 强制使用本地嵌入式运行时（跳过 Gateway 网关） |
| `--deliver` | 将回复发送到聊天渠道 |
| `--channel \<name\>` | 发送渠道（whatsapp、telegram、discord、slack 等） |
| `--reply-to \<target\>` | 覆盖发送目标 |
| `--reply-channel \<name\>` | 覆盖发送渠道 |
| `--reply-account \<id\>` | 覆盖发送账户 id |
| `--thinking \<level\>` | 为所选模型配置设置思考级别 |
| `--verbose \<on\|full\|off\>` | 设置详细级别 |
| `--timeout \<seconds\>` | 覆盖智能体超时时间 |
| `--json` | 输出结构化 JSON |
## 行为
- 默认情况下，CLI 会 **通过 Gateway 网关** 运行。添加 `--local` 可强制使用当前机器上的嵌入式运行时。
- 如果 Gateway 网关不可达，CLI 会 **回退** 到本地嵌入式运行。
- 会话选择：`--to` 会派生会话键（群组/渠道目标会保留隔离；私聊会折叠为 `main`）。
- Thinking 和 verbose 标志会持久化到会话存储中。
- 默认情况下，CLI 会**通过 Gateway 网关**运行。添加 `--local` 可强制在当前机器上使用嵌入式本地运行时。
- 如果 Gateway 网关不可达，CLI 会**回退**到本地嵌入式运行。
- 会话选择：`--to` 会派生会话键（群组/渠道目标会保持隔离；私聊会折叠到 `main`）。
- thinking 和 verbose 标志会持久保存到会话存储中。
- 输出：默认是纯文本，或使用 `--json` 输出结构化负载 + 元数据。
## 示例
```bash
# Simple turn with JSON output
# 带 JSON 输出的简单轮次
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
# Turn with thinking level
# 带 thinking 级别的轮次
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
# Deliver to a different channel than the session
# 发送到与会话不同的渠道
openclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin"
```

232
docs/zh-CN/tools/slash-commands.md
View File

@ -2,35 +2,34 @@
read_when:
- 使用或配置聊天命令
- 调试命令路由或权限
summary: 斜杠命令：文本与原生、配置，以及支持的命令
summary: 斜杠命令：文本与原生、配置以及支持的命令
title: 斜杠命令
x-i18n:
generated_at: "2026-04-12T18:22:04Z"
generated_at: "2026-04-21T08:24:16Z"
model: gpt-5.4
provider: openai
source_hash: 9ef6f54500fa2ce3b873a8398d6179a0882b8bf6fba38f61146c64671055505e
source_hash: d90ddee54af7c05b7fdf486590561084581d750e42cd14674d43bbdc0984df5d
source_path: tools/slash-commands.md
workflow: 15
---
# 斜杠命令
命令由 Gateway 网关处理。大多数命令必须作为**独立**消息发送，并且以 `/` 开头。
仅主机可用的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是它的别名）。
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。
仅主机可用的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是别名）。
这里有两个相关系统：
- **命令**：独立的 `/...` 消息。
- **指令**：`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
- 在模型看到消息之前，指令会从消息中剥离。
- 在普通聊天消息中（不是纯指令消息），它们会被当作“内联提示”，并且**不会**持久化为会话设置。
- 在纯指令消息中（消息只包含指令），它们会持久化到会话，并回复一条确认信息。
- 指令仅对**已授权的发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的
允许列表；否则，授权来源于渠道允许列表/配对以及 `commands.useAccessGroups`。
未授权的发送者会看到这些指令被当作普通文本处理。
- 在模型看到消息之前，指令会从消息中移除。
- 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。
- 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话中，并回复一条确认信息。
- 指令只会对**已授权发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。
未授权发送者看到的指令会被当作普通文本处理。
还有一些**内联快捷命令**（仅限已列入允许列表/已授权的发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
它们会立即运行，在模型看到消息之前被剥离，其余文本则继续按正常流程处理。
还有一些**内联快捷方式**（仅限已列入允许列表/已授权的发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
它们会立即运行，在模型看到消息前被移除，剩余文本继续按正常流程处理。
## 配置
@ -60,26 +59,25 @@ x-i18n:
```
- `commands.text`（默认 `true`）启用在聊天消息中解析 `/...`。
- 在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设为 `false`，文本命令仍然可用。
- 在不支持原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设为 `false`，文本命令仍然可用。
- `commands.native`（默认 `"auto"`）注册原生命令。
- 自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对于不支持原生命令的提供商则忽略。
- Auto：在 Discord/Telegram 上开启；在 Slack 上关闭（直到你添加斜杠命令）；对不支持原生命令的提供商会忽略。
- 设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。
- `false` 会在启动时清除之前在 Discord/Telegram 上注册的命令。Slack 命令由 Slack 应用管理，不会自动移除。
- `false` 会在启动时清除之前在 Discord/Telegram 上注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
- `commands.nativeSkills`（默认 `"auto"`）在支持时以原生方式注册 **skill** 命令。
- 自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。
- Auto：在 Discord/Telegram 上开启；在 Slack 上关闭（Slack 要求为每个 skill 单独创建一个斜杠命令）。
- 设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
- `commands.bash`（默认 `false`）启用 `! <cmd>` 以运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
- `commands.bash`（默认 `false`）启用 `! <cmd>` 来运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
- `commands.bashForegroundMs`（默认 `2000`）控制 bash 在切换到后台模式前等待多久（`0` 表示立即转入后台）。
- `commands.config`（默认 `false`）启用 `/config`（读取/写入 `openclaw.json`）。
- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入 OpenClaw 管理的 `mcp.servers` 下的 MCP 配置）。
- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。
- `commands.plugins`（默认 `false`）启用 `/plugins`（插件发现/状态，以及安装 + 启用/禁用控制）。
- `commands.debug`（默认 `false`）启用 `/debug`（仅运行时覆盖）。
- `commands.restart`（默认 `true`）启用 `/restart` 以及 Gateway 网关重启工具操作。
- `commands.ownerAllowFrom`（可选）为仅限所有者的命令/工具界面设置显式所有者允许列表。这与 `commands.allowFrom` 分开。
- `commands.ownerDisplay` 控制系统提示中所有者 id 的显示方式：`raw` 或 `hash`。
- `commands.ownerDisplaySecret` 可选地设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
- `commands.allowFrom`（可选）为命令授权设置按提供商划分的允许列表。配置后，它将成为命令和指令的
唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商专用键会覆盖它。
- `commands.ownerAllowFrom`（可选）为仅所有者可用的命令/工具界面设置显式所有者允许列表。这与 `commands.allowFrom` 分开。
- `commands.ownerDisplay` 控制所有者 id 在系统提示中的显示方式：`raw` 或 `hash`。
- `commands.ownerDisplaySecret` 可选设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
- `commands.allowFrom`（可选）为命令授权设置按提供商区分的允许列表。配置后，它会成为命令和指令的唯一授权来源（渠道允许列表/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商专属键会覆盖它。
- `commands.useAccessGroups`（默认 `true`）在未设置 `commands.allowFrom` 时，对命令强制执行允许列表/策略。
## 命令列表
@ -89,52 +87,52 @@ x-i18n:
- 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts`
- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts`
- 插件命令来自插件的 `registerCommand()` 调用
- 你的 Gateway 网关上实际可用的命令仍取决于配置标志、渠道界面，以及已安装/已启用的插件
- 你的 Gateway 网关上实际可用的命令仍取决于配置标志、渠道界面以及已安装/已启用的插件
### 核心内置命令
当前可用的内置命令：
- `/new [model]` 启动新会话；`/reset` 是重置别名。
- `/new [model]` 启动一个新会话；`/reset` 是重置别名。
- `/compact [instructions]` 压缩会话上下文。参见 [/concepts/compaction](/zh-CN/concepts/compaction)。
- `/stop` 中止当前运行。
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期时间。
- `/think <off|minimal|low|medium|high|xhigh>` 设置思考级别。别名：`/thinking`、`/t`。
- `/think <level>` 设置思考级别。可选项来自当前模型的提供商配置文件；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，也支持某些自定义级别，如 `xhigh`、`adaptive`、`max`，或仅在支持时可用的二元 `on`。别名：`/thinking`、`/t`。
- `/verbose on|off|full` 切换详细输出。别名：`/v`。
- `/trace on|off` 为当前会话切换插件追踪输出。
- `/trace on|off` 为当前会话切换插件跟踪输出。
- `/fast [status|on|off]` 显示或设置快速模式。
- `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。
- `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 显示或设置 exec 默认值。
- `/model [name|#|status]` 显示或设置模型。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商，或列出某个提供商的模型。
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及 `debounce:2s cap:25 drop:summarize` 之类的选项。
- `/help` 显示简要帮助摘要。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商或某个提供商的模型。
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及如 `debounce:2s cap:25 drop:summarize` 之类的选项。
- `/help` 显示简短帮助摘要。
- `/commands` 显示生成的命令目录。
- `/tools [compact|verbose]` 显示当前智能体此刻可以使用的内容。
- `/tools [compact|verbose]` 显示当前智能体此刻可以使用什么。
- `/status` 显示运行时状态，包括可用时的提供商使用量/配额。
- `/tasks` 列出当前会话中活跃/最近的后台任务。
- `/tasks` 列出当前会话的活动/最近后台任务。
- `/context [list|detail|json]` 说明上下文是如何组装的。
- `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。
- `/whoami` 显示你的发送者 id。别名：`/id`。
- `/skill <name> [input]` 按名称运行一个 skill。
- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。
- `/approve <id> <decision>` 处理 exec 审批提示。
- `/btw <question>` 在不改变未来会话上下文的情况下提出一个旁支问题。参见 [/tools/btw](/zh-CN/tools/btw)。
- `/btw <question>` 在不改变未来会话上下文的情况下提出旁支问题。参见 [/tools/btw](/zh-CN/tools/btw)。
- `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。
- `/focus <target>` 将当前 Discord 线程或 Telegram 话题/会话绑定到一个会话目标。
- `/unfocus` 移除当前绑定。
- `/agents` 列出当前会话中绑定到线程的智能体。
- `/kill <id|#|all>` 中止一个或所有正在运行的子智能体。
- `/steer <id|#> <message>` 向正在运行的子智能体发送引导。别名：`/tell`。
- `/agents` 列出当前会话中线程绑定的智能体。
- `/kill <id|#|all>` 中止一个或全部正在运行的子智能体。
- `/steer <id|#> <message>` 向正在运行的子智能体发送引导信息。别名：`/tell`。
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅所有者。需要 `commands.config: true`。
- `/mcp show|get|set|unset` 读取或写入 OpenClaw 管理的 `mcp.servers` 下的 MCP 服务器配置。仅所有者。需要 `commands.mcp: true`。
- `/plugins list|inspect|show|get|install|enable|disable` 检查或修改插件状态。`/plugin` 是别名。写操作仅限所有者。需要 `commands.plugins: true`。
- `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅所有者。需要 `commands.mcp: true`。
- `/plugins list|inspect|show|get|install|enable|disable` 检查或修改插件状态。`/plugin` 是别名。写操作仅所有者可用。需要 `commands.plugins: true`。
- `/debug show|set|unset|reset` 管理仅运行时配置覆盖。仅所有者。需要 `commands.debug: true`。
- `/usage off|tokens|full|cost` 控制每次响应的使用量页脚，或输出本地成本摘要。
- `/usage off|tokens|full|cost` 控制每次响应的使用量页脚，或打印本地成本摘要。
- `/tts on|off|status|provider|limit|summary|audio|help` 控制 TTS。参见 [/tools/tts](/zh-CN/tools/tts)。
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用它。
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用。
- `/activation mention|always` 设置群组激活模式。
- `/send on|off|inherit` 设置发送策略。仅所有者。
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。
@ -154,12 +152,12 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
内置插件可以添加更多斜杠命令。此仓库中当前的内置命令：
- `/dreaming [on|off|status|help]` 切换 memory dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [Pairing](/zh-CN/channels/pairing)。
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时启用高风险手机节点命令。
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。
- `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置的 Codex 应用服务器 harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置的 Codex app-server harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
- 仅 QQ Bot 命令：
- `/bot-ping`
- `/bot-version`
@ -172,67 +170,63 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
用户可调用的 Skills 也会作为斜杠命令公开：
- `/skill <name> [input]` 始终可作为通用入口点使用。
- 当 skill/插件注册它们时，skills 也可能显示为直接命令，例如 `/prose`。
- 当 skill/插件注册了它们时，Skills 也可能显示为直接命令，例如 `/prose`。
- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
注意：
- 命令支持在命令与参数之间可选使用 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。
- 要查看完整的提供商使用量细分，请使用 `openclaw status --usage`。
- 命令支持在命令与参数之间可选添加 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
- `/new <model>` 接受模型别名、`provider/model`，或提供商名称（模糊匹配）；如果没有匹配项，则该文本会被视为消息正文。
- 如需完整的提供商用量明细，请使用 `openclaw status --usage`。
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道的 `configWrites`。
- 在多账号渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账号的 `configWrites`。
- `/usage` 控制每次响应的使用量页脚；`/usage cost` 会根据 OpenClaw 会话日志输出本地成本摘要。
- `/usage` 控制每次响应的使用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地成本摘要。
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包或 `clawhub:<pkg>`。
- `/plugins enable|disable` 会更新插件配置，并且可能提示你重启。
- 仅 Discord 原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包，或 `clawhub:<pkg>`。
- `/plugins enable|disable` 会更新插件配置，并可能提示你重启。
- 仅 Discord 原生命令：`/vc join|leave|status` 控制语音频道（需要 `channels.discord.voice` 和原生命令；文本形式不可用）。
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求有效启用线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
- ACP 命令参考和运行时行为： [ACP Agents](/zh-CN/tools/acp-agents)。
- `/verbose` 主要用于调试和额外可见性；正常使用时请保持**关闭**。
- `/trace` 比 `/verbose` 更窄：它只显示插件自有的追踪/调试行，并保持普通的详细工具输出关闭。
- `/fast on|off` 会持久化一个会话覆盖。使用 Sessions UI 的 `inherit` 选项可清除它，并回退到配置默认值。
- `/fast` 是提供商相关的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射为 `service_tier=priority`，而直接发送到 `api.anthropic.com` 的公开 Anthropic 请求（包括通过 OAuth 认证的流量）会将其映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
- 相关时仍会显示工具失败摘要，但详细失败文本仅在 `/verbose` 为 `on` 或 `full` 时包含。
- `/reasoning`、`/verbose` 和 `/trace` 在群组环境中存在风险：它们可能暴露你原本无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。
- `/verbose` 用于调试和额外可见性；正常使用时请保持**关闭**。
- `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通详细工具输出关闭。
- `/fast on|off` 会持久化一个会话覆盖。使用会话 UI 中的 `inherit` 选项可清除它并回退到配置默认值。
- `/fast` 是提供商相关的：OpenAI/OpenAI Codex 在原生 Responses 端点上会将其映射到 `service_tier=priority`，而直接发往 `api.anthropic.com` 的公开 Anthropic 请求（包括使用 OAuth 身份验证的流量）会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
- 当相关时，工具失败摘要仍会显示，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。
- `/reasoning`、`/verbose` 和 `/trace` 在群组场景中有风险：它们可能暴露你本无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。
- `/model` 会立即持久化新的会话模型。
- 如果智能体空闲，下一次运行会立即使用它。
- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在一个干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队到之后的重试机会，或直到用户下一轮输入。
- **快速路径：** 来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。
- **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。
- **内联快捷命令（仅限允许列表发送者）：** 某些命令嵌入普通消息中时也可生效，并且会在模型看到其余文本之前被剥离。
- 示例：`hey /status` 会触发一条状态回复，其余文本则继续按正常流程处理。
- 如果智能体处于空闲状态，下一次运行会立即使用它。
- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在一个干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队到后续某个重试机会，或下一个用户回合。
- **快速路径：** 来自允许列表发送者的仅命令消息会立即处理（绕过队列 + 模型）。
- **群组提及门控：** 来自允许列表发送者的仅命令消息会绕过提及要求。
- **内联快捷方式（仅允许列表发送者）：** 某些命令在嵌入普通消息时也能工作，并会在模型看到剩余文本前被移除。
- 示例：`hey /status` 会触发一条状态回复，剩余文本继续按正常流程处理。
- 当前包括：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
- 未授权的纯命令消息会被静默忽略，而内联 `/...` 标记会被当作普通文本处理。
- **skill 命令：** `user-invocable` Skills 会公开为斜杠命令。名称会被规范化为 `a-z0-9_`（最长 32 个字符）；冲突时会附加数字后缀（例如 `_2`）。
- `/skill <name> [input]` 按名称运行一个 skill（当原生命令限制阻止按 skill 单独创建命令时，这很有用）。
- 未授权的仅命令消息会被静默忽略，内联 `/...` 标记会被视为普通文本。
- **skill 命令：** `user-invocable` 的 Skills 也会作为斜杠命令公开。名称会被清理为 `a-z0-9_`（最多 32 个字符）；冲突项会附加数字后缀（例如 `_2`）。
- `/skill <name> [input]` 按名称运行一个 skill（当原生命令限制阻止按 skill 单独生成命令时，这很有用）。
- 默认情况下，skill 命令会作为普通请求转发给模型。
- Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到某个工具（确定性、无模型）。
- Skills 可选择声明 `command-dispatch: tool`，将命令直接路由到某个工具（确定性、无模型）。
- 示例：`/prose`（OpenProse 插件）——参见 [OpenProse](/zh-CN/prose)。
- **原生命令参数：** Discord 对动态选项使用自动补全（省略必填参数时也会显示按钮菜单）。Telegram 和 Slack 在某个命令支持选项且你省略该参数时，会显示按钮菜单。
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时，也会使用按钮菜单）。Telegram 和 Slack 则会在某个命令支持可选项且你省略参数时显示按钮菜单。
## `/tools`
`/tools` 回答的是一个运行时问题，而不是配置问题：**这个智能体现在在
这个会话中能使用什么**。
`/tools` 回答的是一个运行时问题，而不是配置问题：**这个智能体现在在这段对话中可以使用什么**。
- 默认的 `/tools` 是紧凑模式，针对快速浏览进行了优化。
- `/tools verbose` 会添加简短说明。
- 支持参数的原生命令界面会公开相同的模式切换，即 `compact|verbose`。
- 结果是按会话范围限定的，因此更换智能体、渠道、线程、发送者授权或模型都可能
改变输出。
- `/tools` 包含在运行时实际可达的工具，包括核心工具、已连接的
插件工具，以及渠道自有工具。
- `/tools verbose` 会添加简短描述。
- 支持参数的原生命令界面会以 `compact|verbose` 提供相同的模式切换。
- 结果是会话作用域的，因此更改智能体、渠道、线程、发送者授权或模型，都可能改变输出。
- `/tools` 包含在运行时真正可达的工具，包括核心工具、已连接的插件工具以及渠道自有工具。
如需编辑 profile 和覆盖项，请使用 Control UI Tools 面板或配置/目录界面，而不要
将 `/tools` 视为静态目录。
对于配置文件和覆盖编辑，请使用控制 UI 的工具面板或配置/目录界面，而不要将 `/tools` 当作静态目录。
## 使用量界面（各处显示内容）
## 使用量界面（哪些内容显示在哪里）
- **提供商使用量/配额**（例如：“Claude 剩余 80%”）会在启用使用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一规范为“剩余 %”；对于 MiniMax，仅剩余百分比字段会在显示前反转，而 `model_remains` 响应会优先使用聊天模型条目以及带模型标签的套餐标签。
- `/status` 中的**令牌/缓存行**在实时会话快照信息不足时，可以回退到最近的转录使用量条目。现有的非零实时值仍然优先，转录回退还可以在已存储总量缺失或更小时，恢复当前活动运行时模型标签以及一个更偏向提示词的更大总量。
- **每次响应的令牌/成本** 由 `/usage off|tokens|full` 控制（附加在普通回复后）。
- **提供商用量/配额**（例如：“Claude 还剩 80%”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一规范为“剩余百分比”；对于 MiniMax，仅返回剩余百分比字段时会在显示前反转，而 `model_remains` 响应会优先采用聊天模型条目，并附带一个带模型标签的套餐标签。
- 当实时会话快照较稀疏时，`/status` 中的**token/缓存行**可以回退到最新转录使用量条目。现有的非零实时值仍然优先，转录回退还可以在存储总量缺失或更小时恢复当前活动运行时模型标签以及一个更偏向提示词的更大总量。
- **每次响应的 token/成本** 由 `/usage off|tokens|full` 控制（附加在正常回复后）。
- `/model status` 关注的是**模型/凭证/端点**，而不是使用量。
## 模型选择（`/model`）
@ -250,16 +244,16 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/model status
```
说明：
注意：
- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型系列 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单以及提交步骤。
- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型家族 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及提交步骤。
- `/model <#>` 会从该选择器中进行选择（并在可能时优先当前提供商）。
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）以及 API 模式（`api`，如果可用）。
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用的话。
## 调试覆盖
`/debug` 让你设置**仅运行时**配置覆盖（内存中，不写磁盘）。仅所有者。默认禁用；通过 `commands.debug: true` 启用。
`/debug` 让你设置**仅运行时**配置覆盖（内存中，不写磁盘）。仅所有者可用。默认禁用；通过 `commands.debug: true` 启用。
示例：
@ -271,14 +265,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/debug reset
```
说明：
注意：
- 覆盖会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。
- 使用 `/debug reset` 可清除所有覆盖，并返回到磁盘上的配置。
- 覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。
- 使用 `/debug reset` 清除所有覆盖并返回磁盘上的配置。
## 插件追踪输出
## 插件 trace 输出
`/trace` 让你在不开启完整详细模式的情况下切换**会话范围的插件追踪/调试行**。
`/trace` 让你在不开启完整详细模式的情况下切换**会话作用域的插件 trace/debug 行**。
示例：
@ -288,18 +282,18 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/trace off
```
说明：
注意：
- 不带参数的 `/trace` 会显示当前会话的追踪状态。
- `/trace on` 会为当前会话启用插件追踪行。
- `/trace off` 会再次将其关闭。
- 插件追踪行可能会出现在 `/status` 中，也可能作为普通 assistant 回复之后的附加诊断消息出现。
- 不带参数的 `/trace` 会显示当前会话的 trace 状态。
- `/trace on` 会为当前会话启用插件 trace 行。
- `/trace off` 会再次禁用它们。
- 插件 trace 行可能出现在 `/status` 中，也可能作为普通助手回复后的后续诊断消息出现。
- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时配置覆盖。
- `/trace` 也不能替代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。
- `/trace` 不能替代 `/verbose`；普通详细工具/状态输出仍属于 `/verbose`。
## 配置更新
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅所有者。默认禁用；通过 `commands.config: true` 启用。
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅所有者可用。默认禁用；通过 `commands.config: true` 启用。
示例：
@ -311,14 +305,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/config unset messages.responsePrefix
```
说明：
注意：
- 写入前会验证配置；无效更改会被拒绝。
- 配置会在写入前进行校验；无效更改会被拒绝。
- `/config` 更新会在重启后保留。
## MCP 更新
`/mcp` 会把 OpenClaw 管理的 MCP 服务器定义写入 `mcp.servers` 下。仅所有者。默认禁用；通过 `commands.mcp: true` 启用。
`/mcp` 会将 OpenClaw 管理的 MCP 服务器定义写入 `mcp.servers`。仅所有者可用。默认禁用；通过 `commands.mcp: true` 启用。
示例：
@ -329,10 +323,10 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/mcp unset context7
```
说明：
注意：
- `/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 自有的项目设置中。
- 运行时适配器决定哪些传输实际上可以执行。
- `/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。
- 运行时适配器决定哪些传输实际上可执行。
## 插件更新
@ -348,11 +342,11 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/plugins disable context7
```
说明：
注意：
- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实的插件发现。
- `/plugins enable|disable` 只会更新插件配置；不会安装或卸载插件。
- 启用/禁用变更后，请重启 Gateway 网关以应用它们。
- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实插件发现。
- `/plugins enable|disable` 只更新插件配置；不会安装或卸载插件。
- 启用/禁用变更后，重启 Gateway 网关以应用它们。
## 界面说明
@ -360,10 +354,10 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
- **原生命令** 使用隔离会话：
- Discord：`agent:<agentId>:discord:slash:<userId>`
- Slack：`agent:<agentId>:slack:slash:<userId>`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定位到聊天会话）
- **`/stop`** 以当前活动聊天会话为目标，因此它可以中止当前运行。
- **Slack：** `channels.slack.slashCommand` 仍然支持单个 `/openclaw` 风格命令。如果你启用了 `commands.native`，则必须为每个内置命令在 Slack 中创建一个斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式传递。
- Slack 原生例外：请注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定向到聊天会话）
- **`/stop`** 作用于当前活动聊天会话，因此它可以中止当前运行。
- **Slack：** `channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 等相同）。Slack 的命令参数菜单通过临时 Block Kit 按钮传递。
- Slack 原生命令例外：请注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。
## BTW 旁支问题
@ -371,13 +365,13 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
与普通聊天不同：
- 它会使用当前会话作为背景上下文，
- 它会作为一次独立的**无工具**单次调用运行，
- 它使用当前会话作为背景上下文，
- 它以单独的**无工具**一次性调用运行，
- 它不会改变未来的会话上下文，
- 它不会写入转录历史，
- 它会作为实时旁支结果交付，而不是普通 assistant 消息。
- 它会作为实时旁支结果传递，而不是普通助手消息。
这使得 `/btw` 在你希望主任务继续进行的同时，临时获取一个澄清时非常有用。
这使得 `/btw` 在你希望获得临时澄清、同时主任务继续推进时非常有用。
示例：
@ -385,4 +379,4 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/btw what are we doing right now?
```
有关完整行为和客户端 UX 细节，请参见 [BTW Side Questions](/zh-CN/tools/btw)。
完整行为和客户端 UX 细节，请参见 [BTW Side Questions](/zh-CN/tools/btw)。

122
docs/zh-CN/tools/thinking.md
View File

@ -1,13 +1,13 @@
---
read_when:
- 调整思考、快速模式或详细模式的指令解析或默认值
summary: '`/think`、`/fast`、`/verbose`、`/trace` 的指令语法，以及推理可见性'
summary: '`/think`、`/fast`、`/verbose`、`/trace` 和推理可见性的指令语法'
title: 思考级别
x-i18n:
generated_at: "2026-04-21T06:04:33Z"
generated_at: "2026-04-21T08:24:15Z"
model: gpt-5.4
provider: openai
source_hash: edee9420e1cc3eccfa18d87061c4a4d6873e70cb51fff85305fafbcd6a5d6a7d
source_hash: 1b0217f6e5a5cb3400090f31ad5271ca61848a40f77d3f942851e7c2f2352886
source_path: tools/thinking.md
workflow: 15
---
@ -16,42 +16,43 @@ x-i18n:
## 它的作用
- 任何传入消息正文中都可以使用内联指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
- 可在任何入站消息正文中使用内联指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
- 级别（别名）：`off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → “思考”
- low → “深入思考”
- medium → “更深入思考”
- high → “超级思考”（最大预算）
- xhigh → “超级思考+”（GPT-5.2 + Codex 模型以及 Anthropic Claude Opus 4.7 努力度）
- adaptive → 由提供商管理的自适应思考（适用于 Anthropic/Bedrock 上的 Claude 4.6 和 Anthropic Claude Opus 4.7）
- high → “超深度思考”（最大预算）
- xhigh → “超深度思考 +”（GPT-5.2 + Codex 模型，以及 Anthropic Claude Opus 4.7 的 effort）
- adaptive → 由提供商管理的自适应思考（Anthropic/Bedrock 上的 Claude 4.6，以及 Anthropic Claude Opus 4.7 支持）
- max → 提供商最大推理（当前为 Anthropic Claude Opus 4.7）
- `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 都映射为 `xhigh`。
- `highest` 映射为 `high`。
- `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 都映射到 `xhigh`。
- `highest` 映射到 `high`。
- 提供商说明：
- 只有在提供商/模型声明支持自适应思考时，`adaptive` 才会在原生命令菜单和选择器中显示。为兼容现有配置和别名，它仍然接受手动输入的指令。
- 只有在提供商/模型声明支持最大思考时，`max` 才会在原生命令菜单和选择器中显示。当模型不支持 `max` 时，现有已保存的 `max` 设置会重映射为所选模型支持的最高级别。
- 如果没有显式设置思考级别，Anthropic Claude 4.6 模型默认使用 `adaptive`。
- Anthropic Claude Opus 4.7 默认不使用自适应思考。它的 API 努力度默认值仍由提供商决定，除非你显式设置思考级别。
- 对于 Anthropic Claude Opus 4.7，`/think xhigh` 会映射为自适应思考加上 `output_config.effort: "xhigh"`，因为 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的努力度设置。
- Anthropic Claude Opus 4.7 还支持 `/think max`；它会映射到同一条由提供商管理的最大努力度路径。
- OpenAI GPT 模型会根据各模型对 Responses API 努力度的支持情况来映射 `/think`。只有当目标模型支持时，`/think off` 才会发送 `reasoning.effort: "none"`；否则 OpenClaw 会省略禁用推理的载荷，而不是发送不受支持的值。
- 在 Anthropic 兼容流式路径上的 MiniMax（`minimax/*`）默认使用 `thinking: { type: "disabled" }`，除非你在模型参数或请求参数中显式设置思考。这样可以避免 MiniMax 非原生 Anthropic 流格式泄露 `reasoning_content` 增量。
- Z.AI（`zai/*`）只支持二元思考模式（`on`/`off`）。任何非 `off` 级别都视为 `on`（映射为 `low`）。
- Moonshot（`moonshot/*`）会将 `/think off` 映射为 `thinking: { type: "disabled" }`，将任何非 `off` 级别映射为 `thinking: { type: "enabled" }`。启用思考时，Moonshot 只接受 `tool_choice` 为 `auto|none`；OpenClaw 会将不兼容的值规范化为 `auto`。
- 思考菜单和选择器由 provider profile 驱动。提供商插件会为所选模型声明确切支持的级别集合，包括如二元 `on` 这样的标签。
- `adaptive`、`xhigh` 和 `max` 只会针对支持它们的 provider/model profile 进行展示。若输入了不受支持的级别指令，将拒绝该指令，并返回该模型的有效选项。
- 现有已存储但不受支持的级别，包括切换模型后旧的 `max` 值，会被重新映射为所选模型支持的最高级别。
- 当未显式设置思考级别时，Anthropic Claude 4.6 模型默认使用 `adaptive`。
- Anthropic Claude Opus 4.7 不默认使用自适应思考。其 API effort 默认值仍由提供商控制，除非你显式设置思考级别。
- 对于 Anthropic Claude Opus 4.7，`/think xhigh` 会映射为自适应思考加上 `output_config.effort: "xhigh"`，因为 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的 effort 设置。
- Anthropic Claude Opus 4.7 也支持 `/think max`；它会映射到同一个由提供商控制的最大 effort 路径。
- OpenAI GPT 模型会根据具体模型对 Responses API effort 的支持来映射 `/think`。只有当目标模型支持时，`/think off` 才会发送 `reasoning.effort: "none"`；否则 OpenClaw 会省略已禁用推理的 payload，而不会发送不受支持的值。
- 走 Anthropic 兼容流式路径的 MiniMax（`minimax/*`）默认使用 `thinking: { type: "disabled" }`，除非你在模型参数或请求参数中显式设置 thinking。这样可避免 MiniMax 非原生 Anthropic 流格式泄露 `reasoning_content` 增量。
- Z.AI（`zai/*`）只支持二元思考（`on`/`off`）。任何非 `off` 级别都会被视为 `on`（映射为 `low`）。
- Moonshot（`moonshot/*`）会将 `/think off` 映射为 `thinking: { type: "disabled" }`，并将任何非 `off` 级别映射为 `thinking: { type: "enabled" }`。启用 thinking 时，Moonshot 只接受 `tool_choice` 为 `auto|none`；OpenClaw 会将不兼容的值规范化为 `auto`。
## 解析顺序
1. 消息中的内联指令（仅对该条消息生效）。
2. 会话覆盖项（通过发送只包含指令的消息设置）。
2. 会话覆盖项（通过发送仅包含指令的消息来设置）。
3. 每个智能体的默认值（配置中的 `agents.list[].thinkingDefault`）。
4. 全局默认值（配置中的 `agents.defaults.thinkingDefault`）。
5. 回退值：Anthropic Claude 4.6 模型为 `adaptive`，Anthropic Claude Opus 4.7 在未显式配置时为 `off`，其他支持推理的模型为 `low`，否则为 `off`。
5. 回退：若可用，则使用提供商声明的默认值；对于其他被标记为支持推理的 catalog 模型，使用 `low`；否则为 `off`。
## 设置会话默认值
- 发送一条**只包含该指令**的消息（允许空白字符），例如 `/think:medium` 或 `/t high`。
- 该设置会固定在当前会话中（默认按发送者区分）；可通过 `/think:off` 或会话空闲重置来清除。
- 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），命令会被拒绝并给出提示，同时不会更改会话状态。
- 发送一条**仅包含指令**的消息（允许空白字符），例如 `/think:medium` 或 `/t high`。
- 该设置会在当前会话中保持生效（默认按发送者区分）；可通过 `/think:off` 或会话空闲重置来清除。
- 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），命令会被拒绝，并给出提示，同时保持会话状态不变。
- 发送不带参数的 `/think`（或 `/think:`）可查看当前思考级别。
## 按智能体应用
@ -61,67 +62,70 @@ x-i18n:
## 快速模式（`/fast`）
- 级别：`on|off`。
- 只含指令的消息会切换会话快速模式覆盖项，并回复 `Fast mode enabled.` / `Fast mode disabled.`。
- 仅包含指令的消息会切换会话快速模式覆盖项，并回复 `Fast mode enabled.` / `Fast mode disabled.`。
- 发送不带模式的 `/fast`（或 `/fast status`）可查看当前生效的快速模式状态。
- OpenClaw 按以下顺序解析快速模式：
1. 内联/只含指令的 `/fast on|off`
1. 内联/仅指令 `/fast on|off`
2. 会话覆盖项
3. 每个智能体的默认值（`agents.list[].fastModeDefault`）
4. 每个模型的配置：`agents.defaults.models["<provider>/<model>"].params.fastMode`
5. 回退值：`off`
- 对于 `openai/*`，快速模式会通过在受支持的 Responses 请求中发送 `service_tier=priority`，映射为 OpenAI 优先处理。
- 对于 `openai-codex/*`，快速模式会在 Codex Responses 上发送相同的 `service_tier=priority` 标志。OpenClaw 在这两种认证路径之间共用同一个 `/fast` 开关。
- 对于直接发送到公共 `anthropic/*` 的请求，包括发往 `api.anthropic.com` 的 OAuth 认证流量，快速模式会映射到 Anthropic 服务层级：`/fast on` 设置 `service_tier=auto`，`/fast off` 设置 `service_tier=standard_only`。
- 对于 Anthropic 兼容路径上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
- 当同时设置了显式 Anthropic `serviceTier` / `service_tier` 模型参数和快速模式默认值时，前者会覆盖后者。对于非 Anthropic 代理 base URL，OpenClaw 仍会跳过 Anthropic 服务层级注入。
5. 回退：`off`
- 对于 `openai/*`，快速模式通过在受支持的 Responses 请求中发送 `service_tier=priority`，映射到 OpenAI 优先处理。
- 对于 `openai-codex/*`，快速模式会在 Codex Responses 上发送同样的 `service_tier=priority` 标志。OpenClaw 在这两种认证路径之间共享同一个 `/fast` 开关。
- 对于直接发往公共 `anthropic/*` 的请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，快速模式会映射到 Anthropic 服务层级：`/fast on` 设置 `service_tier=auto`，`/fast off` 设置 `service_tier=standard_only`。
- 对于走 Anthropic 兼容路径的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
- 当二者同时设置时，显式的 Anthropic `serviceTier` / `service_tier` 模型参数会覆盖快速模式默认值。对于非 Anthropic 代理 base URL，OpenClaw 仍会跳过 Anthropic service-tier 注入。
## 详细模式指令（`/verbose` 或 `/v`）
- 级别：`on`（最简）| `full` | `off`（默认）。
- 只含指令的消息会切换会话详细模式，并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示，且不会更改状态。
- `/verbose off` 会存储一个显式的会话覆盖项；可在 Sessions UI 中选择 `inherit` 来清除它。
- 内联指令仅对当前消息生效；否则使用会话/全局默认值。
- 仅包含指令的消息会切换会话详细模式，并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示，但不会更改状态。
- `/verbose off` 会存储为显式会话覆盖项；可在 Sessions UI 中选择 `inherit` 来清除。
- 内联指令仅影响该条消息；否则使用会话/全局默认值。
- 发送不带参数的 `/verbose`（或 `/verbose:`）可查看当前详细级别。
- 当详细模式开启时，会输出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为独立的仅元数据消息发回；如果可用，则前缀为 `<emoji> <tool-name>: <arg>`（路径/命令）。这些工具摘要会在每个工具启动时立即发送（独立气泡），而不是作为流式增量发送。
- 工具失败摘要在普通模式下仍然可见，但原始错误详情后缀只有在详细模式为 `on` 或 `full` 时才会显示。
- 当详细级别为 `full` 时，工具输出也会在完成后转发（独立气泡，并截断到安全长度）。如果你在运行过程中切换 `/verbose on|full|off`，后续工具气泡会遵循新的设置。
- 当详细模式开启时，会输出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为独立的仅元数据消息发回；若可用，会以前缀 `<emoji> <tool-name>: <arg>` 的形式显示（路径/命令）。这些工具摘要会在每个工具启动时立即发送（单独气泡），而不是作为流式增量发送。
- 工具失败摘要在普通模式下仍然可见，但原始错误详情后缀会被隐藏，除非详细级别为 `on` 或 `full`。
- 当详细级别为 `full` 时，工具输出也会在完成后转发（单独气泡，并截断到安全长度）。如果你在运行进行中切换 `/verbose on|full|off`，后续工具气泡会遵循新的设置。
## 插件跟踪指令（`/trace`）
## 插件追踪指令（`/trace`）
- 级别：`on` | `off`（默认）。
- 只含指令的消息会切换会话插件跟踪输出，并回复 `Plugin trace enabled.` / `Plugin trace disabled.`。
- 内联指令仅对该条消息生效；否则使用会话/全局默认值。
- 发送不带参数的 `/trace`（或 `/trace:`）可查看当前跟踪级别。
- `/trace` 比 `/verbose` 更窄：它只暴露插件自有的跟踪/调试行，例如 Active Memory 调试摘要。
- 跟踪行可能出现在 `/status` 中，也可能作为普通助手回复后的跟进诊断消息出现。
- 仅包含指令的消息会切换会话插件追踪输出，并回复 `Plugin trace enabled.` / `Plugin trace disabled.`。
- 内联指令仅影响该条消息；否则使用会话/全局默认值。
- 发送不带参数的 `/trace`（或 `/trace:`）可查看当前追踪级别。
- `/trace` 比 `/verbose` 更窄：它只暴露插件拥有的追踪/调试行，例如 Active Memory 调试摘要。
- 追踪行可出现在 `/status` 中，也可作为普通助手回复后的后续诊断消息出现。
## 推理可见性（`/reasoning`）
- 级别：`on|off|stream`。
- 只含指令的消息会切换是否在回复中显示思考块。
- 启用后，推理会作为**单独一条消息**发送，并带有前缀 `Reasoning:`。
- `stream`（仅 Telegram）：在生成回复时将推理流式写入 Telegram 草稿气泡，然后发送不含推理的最终答案。
- 仅包含指令的消息会切换是否在回复中显示 thinking 块。
- 启用后，推理会作为**单独一条消息**发送，并以 `Reasoning:` 为前缀。
- `stream`（仅 Telegram）：在回复生成过程中，将推理流式写入 Telegram 草稿气泡，最终发送的正式答案不包含推理。
- 别名：`/reason`。
- 发送不带参数的 `/reasoning`（或 `/reasoning:`）可查看当前推理级别。
- 解析顺序：内联指令，然后会话覆盖项，然后每个智能体的默认值（`agents.list[].reasoningDefault`），最后是回退值（`off`）。
- 解析顺序：内联指令，然后是会话覆盖项，然后是每个智能体的默认值（`agents.list[].reasoningDefault`），最后回退为 `off`。
## 相关内容
- 提权模式文档见 [Elevated mode](/zh-CN/tools/elevated)。
- Elevated mode 文档位于 [Elevated mode](/zh-CN/tools/elevated)。
## 心跳
- 心跳探测消息正文是已配置的心跳提示词（默认值：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。心跳消息中的内联指令照常生效（但应避免通过心跳更改会话默认值）。
- 心跳投递默认只发送最终载荷。如需同时发送单独的 `Reasoning:` 消息（如有），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或每个智能体级别的 `agents.list[].heartbeat.includeReasoning: true`。
- 心跳探测正文为已配置的心跳提示词（默认值：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。心跳消息中的内联指令仍照常生效（但应避免通过心跳更改会话默认值）。
- 心跳传递默认只发送最终 payload。若还要发送单独的 `Reasoning:` 消息（若可用），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或每个智能体的 `agents.list[].heartbeat.includeReasoning: true`。
## Web 聊天 UI
- Web 聊天中的思考选择器会在页面加载时，镜像会话从传入会话存储/config 中保存的级别。
- Web 聊天中的思考选择器会在页面加载时，从入站会话存储/config 中镜像该会话已存储的级别。
- 选择其他级别会立即通过 `sessions.patch` 写入会话覆盖项；它不会等到下一次发送，也不是一次性的 `thinkingOnce` 覆盖。
- 第一个选项始终是 `Default (<resolved level>)`，其中解析出的默认值来自当前会话模型：Anthropic 上的 Claude 4.6 为 `adaptive`，Anthropic Claude Opus 4.7 在未配置时为 `off`，其他支持推理的模型为 `low`，否则为 `off`。
- 该选择器会保持提供商感知：
- 大多数提供商显示 `off | minimal | low | medium | high`
- Anthropic/Bedrock Claude 4.6 显示 `off | minimal | low | medium | high | adaptive`
- Anthropic Claude Opus 4.7 显示 `off | minimal | low | medium | high | xhigh | adaptive | max`
- Z.AI 显示二元 `off | on`
- `/think:<level>` 仍然可用，并会更新同一个已存储的会话级别，因此聊天指令和选择器会保持同步。
- 第一个选项始终是 `Default (<resolved level>)`，其中解析后的默认值来自当前活动会话模型的 provider thinking profile。
- 选择器使用 Gateway 网关会话行返回的 `thinkingOptions`。浏览器 UI 不会维护自己的 provider 正则列表；模型特定级别集合由插件负责。
- `/think:<level>` 仍然有效，并会更新同一个已存储的会话级别，因此聊天指令与选择器保持同步。
## Provider profiles
- 提供商插件可暴露 `resolveThinkingProfile(ctx)` 来定义模型支持的级别及默认值。
- 每个 profile 级别都有一个已存储的规范 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），并且可包含一个显示用 `label`。二元提供商使用 `{ id: "low", label: "on" }`。
- 已发布的旧版 hook（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）仍保留作为兼容适配器，但新的自定义级别集合应使用 `resolveThinkingProfile`。
- Gateway 网关行会暴露 `thinkingOptions` 和 `thinkingDefault`，以便 ACP/聊天客户端渲染与运行时校验相同的 profile。