diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index 87787e559..dc9a9c2bb 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -1,20 +1,20 @@ --- read_when: - - 设置 Slack 或调试 Slack socket/HTTP 模式 + - 设置 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。 @@ -28,17 +28,17 @@ x-i18n: -## 快速设置 +## 快速开始 - + 在 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-...`） @@ -79,12 +79,12 @@ openclaw gateway - + 在 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-...`） @@ -106,9 +106,9 @@ openclaw gateway ``` - 对多账户 HTTP 使用唯一的 webhook 路径 + 为多账户 HTTP 使用唯一的 webhook 路径 - 为每个账户指定不同的 `webhookPath`（默认为 `/slack/events`），以避免注册冲突。 + 为每个账户指定不同的 `webhookPath`（默认是 `/slack/events`），以避免注册冲突。 @@ -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 ### 其他清单设置 -展示扩展上述默认配置的不同功能。 +展示可扩展上述默认设置的不同功能。 - 可以使用多个[原生斜杠命令](#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 或 max-age " + "usage_hint": "idle or max-age " }, { "command": "/think", "description": "设置思考级别", - "usage_hint": "" + "usage_hint": "" }, { "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": " [input]" }, { "command": "/btw", - "description": "提出一个旁支问题而不改变会话上下文", + "description": "在不更改会话上下文的情况下提出附带问题", "usage_hint": "" }, { "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 或 max-age ", + "usage_hint": "idle or max-age ", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/think", "description": "设置思考级别", - "usage_hint": "", + "usage_hint": "", "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": " [input]", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/btw", - "description": "提出一个旁支问题而不改变会话上下文", + "description": "在不更改会话上下文的情况下提出附带问题", "usage_hint": "", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/usage", - "description": "控制 usage 页脚或显示成本摘要", + "description": "控制用量页脚或显示成本摘要", "usage_hint": "off|tokens|full|cost", "url": "https://gateway-host.example.com/slack/events" } @@ -563,12 +563,12 @@ openclaw gateway - 如果你希望发出的消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。 + 如果你希望出站消息使用当前智能体身份（自定义用户名和图标），而不是默认 Slack 应用身份，请添加 `chat:write.customize` bot scope。 - 如果你使用 emoji 图标，Slack 需要 `:emoji_name:` 语法。 + 如果你使用 emoji 图标，Slack 要求采用 `:emoji_name:` 语法。 - + 如果你配置了 `channels.slack.userToken`，典型的读取作用域包括： - `channels: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`。 -对于 actions/目录读取，如果已配置，可以优先使用用户令牌。对于写入，仍优先使用 bot 令牌；只有在 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。 +对于 actions/目录读取，如果已配置 user token，则可以优先使用它。对于写入，仍优先使用 bot token；只有在 `userTokenReadOnly: false` 且 bot token 不可用时，才允许使用 user-token 写入。 ## 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 `。 + 在私信中配对时，使用 `openclaw pairing approve slack `。 @@ -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` - 默认情况下，渠道消息会受到提及门控。 + 默认情况下，渠道消息受提及门控限制。 提及来源： - 显式应用提及（`<@botId>`） - - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 隐式回复到 bot 的线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） + - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） + - 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） - 每个渠道的控制项（`channels.slack.channels.`；仅能通过启动时解析或 `dangerouslyAllowNameMatching` 使用名称）： + 每个渠道的控制项（`channels.slack.channels.`；仅能通过启动解析名称，或使用 `dangerouslyAllowNameMatching`）： - `requireMention` - `users`（allowlist） @@ -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:`） ## 线程、会话和回复标签 -- 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。 -- 使用默认的 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。 +- 私信路由为 `direct`；渠道为 `channel`；MPIM 为 `group`。 +- 在默认 `session.dmScope=main` 下，Slack 私信会收敛到智能体主会话。 - 渠道会话：`agent::slack:channel:`。 -- 在线程回复适用时，可以创建线程会话后缀（`:thread:`）。 +- 在线程回复适用时，可以创建带有线程会话后缀（`:thread:`）的会话。 - `channels.slack.thread.historyScope` 默认为 `thread`；`thread.inheritParent` 默认为 `false`。 -- `channels.slack.thread.initialHistoryLimit` 控制新线程会话开始时会抓取多少条已有线程消息（默认 `20`；设为 `0` 可禁用）。 -- `channels.slack.thread.requireExplicitMention`（默认 `false`）：设为 `true` 时，会抑制隐式线程提及，因此 bot 即使已经参与了某个线程，也只会响应该线程内显式的 `@bot` 提及。否则，在 bot 已参与的线程中回复会绕过 `requireMention` 门控。 +- `channels.slack.thread.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:]]` -注意：`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"`）。 +- 该反应为尽力而为，回复完成或失败路径结束后会自动尝试清理。 ## 媒体、分块和投递 - Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在抓取成功且大小限制允许时写入媒体存储。 + Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在获取成功且大小限制允许时写入媒体存储。 - 运行时入站大小上限默认为 `20MB`，除非通过 `channels.slack.mediaMaxMb` 覆盖。 + 运行时入站大小上限默认是 `20MB`，除非通过 `channels.slack.mediaMaxMb` 覆盖。 - 文本分块使用 `channels.slack.textChunkLimit`（默认 4000） - - `channels.slack.chunkMode="newline"` 启用优先按段落拆分 + - `channels.slack.chunkMode="newline"` 启用按段落优先拆分 - 文件发送使用 Slack 上传 API，并且可以包含线程回复（`thread_ts`） - - 如果已配置，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则渠道发送使用媒体管道中的 MIME 类型默认值 + - 配置了 `channels.slack.mediaMaxMb` 时，出站媒体上限遵循该值；否则，渠道发送会使用媒体管道中按 MIME 类型划分的默认值 @@ -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::slack:slash:`，并仍会通过 `CommandTargetSessionKey` 将命令执行路由到目标会话。 +斜杠会话使用隔离键，例如 `agent::slack:slash:`，但仍会通过 `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 - 验证 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 - + 验证： - signing secret @@ -1029,17 +1028,17 @@ openclaw pairing list slack 如果账户快照中出现 `signingSecretStatus: "configured_unavailable"`， 说明 HTTP 账户已完成配置，但当前运行时无法 - 解析由 SecretRef 支持的 signing secret。 + 解析由 SecretRef 支持的 signing secret 实际值。 - 请确认你的预期是： + 确认你想要的是： - - 原生命令模式（`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。 diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index a193c5a96..481b3d6b4 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -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 `。 -- 回退运行时规则、冷却探测以及会话覆盖持久化记录在 [/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 `。 +- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/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.` 配置；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.` 配置；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__KEY`（单个 live 覆盖项，优先级最高） +- 通过以下方式配置多个 key： + - `OPENCLAW_LIVE__KEY`（单个实时覆盖，最高优先级） - `_API_KEYS`（逗号或分号分隔列表） - - `_API_KEY`（主密钥） + - `_API_KEY`（主 key） - `_API_KEY_*`（编号列表，例如 `_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/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true` / `false`） -- 可以通过 `agents.defaults.models["openai/"].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/"].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/"].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/"].params.cachedContent` - （或旧版 `cached_content`），用于转发提供商原生的 +- 直接 Gemini 运行也接受 `agents.defaults.models["google/"].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/"].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.` 条目。 ### 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) — 按提供商分别说明的设置指南 diff --git a/docs/zh-CN/plugins/architecture.md b/docs/zh-CN/plugins/architecture.md index c2c4293b8..a92e15587 100644 --- a/docs/zh-CN/plugins/architecture.md +++ b/docs/zh-CN/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - 构建或调试原生 OpenClaw 插件 - - 理解插件能力模型或所有权边界 - - 处理插件加载流水线或注册表 + - 理解插件能力模型或归属边界 + - 处理插件加载流程或注册表 - 实现提供商运行时钩子或渠道插件 sidebarTitle: Internals -summary: 插件内部机制：能力模型、所有权、契约、加载流水线和运行时辅助工具 +summary: 插件内部机制：能力模型、归属、契约、加载流程和运行时辅助工具 title: 插件内部机制 x-i18n: - generated_at: "2026-04-21T06:04:37Z" + generated_at: "2026-04-21T08:24:18Z" model: gpt-5.4 provider: openai - source_hash: 05b612f75189ba32f8c92e5a261241abdf9ad8d4a685c1d8da0cf9605d7158b7 + source_hash: 4b1fb42e659d4419033b317e88563a59b3ddbfad0523f32225c868c8e828fd16 source_path: plugins/architecture.md workflow: 15 --- @@ -19,11 +19,11 @@ x-i18n: # 插件内部机制 - 这是**深度架构参考**。如需实用指南，请参阅： + 这是**深度架构参考**。如需实用指南，请参见： - [安装和使用插件](/zh-CN/tools/plugin) — 用户指南 - [入门指南](/zh-CN/plugins/building-plugins) — 第一个插件教程 - - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建消息渠道 - - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建模型提供商 + - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建一个消息渠道 + - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建一个模型提供商 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 导入映射和注册 API @@ -31,14 +31,14 @@ x-i18n: ## 公共能力模型 -能力是 OpenClaw 内部公开的**原生插件**模型。每个原生 OpenClaw 插件都会针对一种或多种能力类型进行注册： +能力是 OpenClaw 内部公共的**原生插件**模型。每个原生 OpenClaw 插件都会针对一种或多种能力类型进行注册： | 能力 | 注册方式 | 示例插件 | | ---------------------- | ------------------------------------------------ | ------------------------------------ | | 文本推理 | `api.registerProvider(...)` | `openai`, `anthropic` | | CLI 推理后端 | `api.registerCliBackend(...)` | `openai`, `anthropic` | | 语音 | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| 实时转写 | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | | 实时语音 | `api.registerRealtimeVoiceProvider(...)` | `openai` | | 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | | 图像生成 | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | @@ -46,48 +46,48 @@ x-i18n: | 视频生成 | `api.registerVideoGenerationProvider(...)` | `qwen` | | 网页抓取 | `api.registerWebFetchProvider(...)` | `firecrawl` | | 网页搜索 | `api.registerWebSearchProvider(...)` | `google` | -| 渠道 / 消息 | `api.registerChannel(...)` | `msteams`, `matrix` | +| 渠道 / 消息传递 | `api.registerChannel(...)` | `msteams`, `matrix` | -如果一个插件没有注册任何能力，但提供了钩子、工具或服务，它就是一个**仅钩子的旧版**插件。该模式仍然受到完全支持。 +如果一个插件注册了零个能力，但提供了钩子、工具或服务，它就是一个**仅钩子的旧版**插件。该模式目前仍然被完全支持。 ### 外部兼容性立场 -能力模型已经在核心中落地，并且当前已被内置/原生插件使用，但外部插件兼容性仍需要比“它已导出，因此它被冻结”更严格的标准。 +能力模型已经在核心中落地，并且今天已被内置 / 原生插件使用，但外部插件的兼容性仍需要比“它已导出，因此它已冻结”更严格的标准。 -当前指导原则： +当前指引： -- **现有外部插件：** 保持基于钩子的集成可用；将其视为兼容性的基准 -- **新的内置/原生插件：** 优先使用显式能力注册，而不是特定厂商的深入访问方式或新的仅钩子设计 -- **采用能力注册的外部插件：** 允许这样做，但除非文档明确将某个契约标记为稳定，否则应将特定能力的辅助接口视为仍在演进中 +- **现有外部插件：** 保持基于钩子的集成继续工作；将此视为兼容性的基线 +- **新的内置 / 原生插件：** 优先使用显式能力注册，而不是面向供应商的特殊访问或新的仅钩子设计 +- **采用能力注册的外部插件：** 允许这样做，但除非文档明确将某个契约标记为稳定，否则应将能力相关的辅助接口视为仍在演进中 -实用规则： +实践规则： - 能力注册 API 是预期的发展方向 -- 在过渡期间，旧版钩子仍是外部插件最安全、最不容易破坏的路径 -- 导出的辅助子路径并不完全等价；优先使用文档化的精简契约，而不是附带暴露的辅助导出 +- 在过渡期间，旧版钩子仍然是对外部插件来说最安全、最不容易破坏兼容性的路径 +- 导出的辅助子路径并不完全等价；优先使用文档化的狭义契约，而不是偶然暴露出的辅助导出 ### 插件形态 -OpenClaw 会根据每个已加载插件的实际注册行为，而不是仅根据静态元数据，将其归类为一种形态： +OpenClaw 会根据每个已加载插件的实际注册行为对其进行形态分类，而不只是依据静态元数据： -- **plain-capability** —— 只注册一种能力类型（例如仅提供商插件，如 `mistral`） +- **plain-capability** —— 只注册一种能力类型（例如仅提供商插件 `mistral`） - **hybrid-capability** —— 注册多种能力类型（例如 `openai` 同时拥有文本推理、语音、媒体理解和图像生成） - **hook-only** —— 只注册钩子（类型化或自定义），不注册能力、工具、命令或服务 - **non-capability** —— 注册工具、命令、服务或路由，但不注册能力 -使用 `openclaw plugins inspect ` 可查看插件的形态及能力拆分。详情请参阅 [CLI 参考](/cli/plugins#inspect)。 +使用 `openclaw plugins inspect ` 可查看插件的形态和能力拆分。详情参见 [CLI 参考](/cli/plugins#inspect)。 ### 旧版钩子 -`before_agent_start` 钩子仍然作为仅钩子插件的兼容路径受到支持。旧版真实插件仍依赖它。 +`before_agent_start` 钩子仍作为仅钩子插件的兼容路径被支持。现实中的旧版插件仍然依赖它。 方向如下： -- 保持其可用 -- 将其文档化为旧版 -- 对于模型/提供商覆盖工作，优先使用 `before_model_resolve` -- 对于提示词变更工作，优先使用 `before_prompt_build` -- 只有在真实使用量下降且夹具覆盖证明迁移安全后才移除 +- 保持其继续工作 +- 在文档中将其标注为旧版 +- 对模型 / 提供商覆盖工作，优先使用 `before_model_resolve` +- 对提示词变更工作，优先使用 `before_prompt_build` +- 只有在真实使用下降且 fixture 覆盖证明迁移安全后才移除 ### 兼容性信号 @@ -95,57 +95,57 @@ OpenClaw 会根据每个已加载插件的实际注册行为，而不是仅根 | 信号 | 含义 | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | 配置可正常解析，插件也能正常解析 | -| **compatibility advisory** | 插件使用受支持但较旧的模式（例如 `hook-only`） | -| **legacy warning** | 插件使用 `before_agent_start`，该功能已弃用 | -| **hard error** | 配置无效或插件加载失败 | +| **配置有效** | 配置解析正常，且插件可解析 | +| **兼容性提示** | 插件使用了受支持但较旧的模式（例如 `hook-only`） | +| **旧版警告** | 插件使用了 `before_agent_start`，该接口已弃用 | +| **硬错误** | 配置无效，或插件加载失败 | -`hook-only` 和 `before_agent_start` 当前都不会导致你的插件失效——`hook-only` 只是提示，而 `before_agent_start` 只会触发警告。这些信号也会出现在 `openclaw status --all` 和 `openclaw plugins doctor` 中。 +`hook-only` 和 `before_agent_start` 目前都不会导致你的插件损坏——`hook-only` 只是提示，而 `before_agent_start` 只会触发警告。这些信号也会出现在 `openclaw status --all` 和 `openclaw plugins doctor` 中。 ## 架构概览 -OpenClaw 的插件系统分为四层： +OpenClaw 的插件系统有四层： -1. **清单 + 发现** - OpenClaw 会从已配置路径、工作区根目录、全局扩展根目录以及内置扩展中查找候选插件。发现阶段会优先读取原生 `openclaw.plugin.json` 清单以及受支持的 bundle 清单。 -2. **启用 + 校验** - 核心决定某个已发现插件是启用、禁用、阻止，还是被选用于某个独占槽位，例如 memory。 -3. **运行时加载** - 原生 OpenClaw 插件通过 jiti 在进程内加载，并将能力注册到中央注册表中。兼容的 bundle 会被规范化为注册表记录，而不会导入运行时代码。 -4. **能力面消费** +1. **清单 + 设备发现** + OpenClaw 会从配置路径、工作区根目录、全局扩展根目录和内置扩展中查找候选插件。设备发现会先读取原生的 `openclaw.plugin.json` 清单以及受支持的 bundle 清单。 +2. **启用 + 校验** + 核心决定已发现的插件是启用、禁用、阻止，还是被选中用于某个排他性槽位，例如 memory。 +3. **运行时加载** + 原生 OpenClaw 插件通过 `jiti` 在进程内加载，并将能力注册到中央注册表中。兼容的 bundle 会被标准化为注册表记录，而无需导入运行时代码。 +4. **表面消费** OpenClaw 的其余部分会读取注册表，以暴露工具、渠道、提供商设置、钩子、HTTP 路由、CLI 命令和服务。 -对于插件 CLI，根命令发现专门分为两个阶段： +对于插件 CLI，根命令发现被拆分为两个阶段： -- 解析期元数据来自 `registerCli(..., { descriptors: [...] })` +- 解析时元数据来自 `registerCli(..., { descriptors: [...] })` - 真正的插件 CLI 模块可以保持惰性，并在首次调用时再注册 -这样既能让插件拥有自己的 CLI 代码，又能让 OpenClaw 在解析之前预留根命令名称。 +这样可以让插件拥有的 CLI 代码保留在插件内部，同时仍允许 OpenClaw 在解析前预留根命令名称。 -重要的设计边界： +重要的设计边界是： -- 发现 + 配置校验应当能够仅依赖**清单/模式元数据**完成，而无需执行插件代码 +- 设备发现 + 配置校验应当能够仅通过**清单 / schema 元数据**工作，而不执行插件代码 - 原生运行时行为来自插件模块的 `register(api)` 路径 -这种拆分使 OpenClaw 能在完整运行时尚未激活之前，就完成配置校验、解释缺失/禁用插件的原因，并构建 UI/模式提示。 +这种拆分使 OpenClaw 能够在完整运行时激活之前，就校验配置、解释缺失 / 已禁用的插件，并构建 UI / schema 提示。 -### 渠道插件和共享 message 工具 +### 渠道插件与共享消息工具 -对于常规聊天操作，渠道插件无需单独注册发送/编辑/回应工具。OpenClaw 在核心中保留了一个共享的 `message` 工具，而渠道插件则负责其背后的渠道特定发现和执行。 +对于常规聊天操作，渠道插件不需要单独注册发送 / 编辑 / 反应工具。OpenClaw 在核心中保留了一个共享的 `message` 工具，而渠道插件负责其背后的渠道特定发现和执行。 当前边界如下： -- 核心拥有共享 `message` 工具宿主、提示词接线、会话/线程记录，以及执行分发 -- 渠道插件拥有作用域动作发现、能力发现，以及任何渠道特定的模式片段 -- 渠道插件拥有提供商特定的会话会话语法，例如对话 id 如何编码线程 id，或如何从父对话继承 +- 核心拥有共享 `message` 工具宿主、提示词接线、会话 / 线程簿记和执行分发 +- 渠道插件拥有作用域化的动作发现、能力发现以及任何渠道特定的 schema 片段 +- 渠道插件拥有提供商特定的会话对话语法，例如对话 id 如何编码线程 id 或从父对话继承 - 渠道插件通过其动作适配器执行最终动作 -对于渠道插件，SDK 接口为 `ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一的发现调用使插件可以一起返回其可见动作、能力和模式贡献，从而避免这些部分彼此漂移。 +对于渠道插件，SDK 接口是 `ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一的发现调用让插件可以一起返回其可见动作、能力和 schema 贡献，从而避免这些部分彼此漂移。 -当某个渠道特定的 message-tool 参数携带媒体来源，例如本地路径或远程媒体 URL 时，插件还应从 `describeMessageTool(...)` 返回 `mediaSourceParams`。核心会使用这个显式列表来应用沙箱路径规范化和出站媒体访问提示，而不是硬编码插件自有参数名。 -这里应优先使用按动作划分的映射，而不是整个渠道范围的扁平列表，这样仅用于资料的媒体参数就不会在 `send` 这类无关动作中被规范化。 +当某个渠道特定的消息工具参数携带媒体来源，例如本地路径或远程媒体 URL 时，插件还应当从 `describeMessageTool(...)` 返回 `mediaSourceParams`。核心使用这份显式列表来应用沙箱路径规范化和出站媒体访问提示，而无需对插件拥有的参数名进行硬编码。 +这里优先使用按动作划分的映射，而不是整个渠道共用的扁平列表，这样仅用于 profile 的媒体参数就不会在 `send` 之类的不相关动作上被规范化。 -核心会将运行时作用域传入这一步发现。重要字段包括： +核心会将运行时作用域传入该发现步骤。重要字段包括： - `accountId` - `currentChannelId` @@ -156,32 +156,31 @@ OpenClaw 的插件系统分为四层： - `agentId` - 受信任的入站 `requesterSenderId` -这对于依赖上下文的插件很重要。渠道可以根据活动账户、当前房间/线程/消息，或受信任的请求者身份来隐藏或暴露消息动作，而无需在核心 `message` 工具中硬编码渠道特定分支。 +这对于上下文敏感的插件很重要。渠道可以根据活动账户、当前房间 / 线程 / 消息或受信任的请求者身份来隐藏或暴露消息动作，而不需要在核心 `message` 工具中硬编码渠道特定分支。 -这也是为什么嵌入式运行器路由变更仍属于插件工作：运行器负责将当前聊天/会话身份转发到插件发现边界，以便共享 `message` 工具能为当前轮次暴露正确的渠道自有能力面。 +这也是为什么嵌入式运行器路由变更仍然属于插件工作：运行器负责将当前聊天 / 会话身份转发到插件发现边界，以便共享 `message` 工具在当前轮次暴露正确的渠道自有表面。 -对于渠道自有的执行辅助工具，内置插件应将执行运行时保留在各自的扩展模块中。核心不再拥有位于 `src/agents/tools` 下的 Discord、Slack、Telegram 或 WhatsApp 消息动作运行时。 -我们不会发布单独的 `plugin-sdk/*-action-runtime` 子路径，内置插件应直接从其扩展自有模块导入本地运行时代码。 +对于渠道自有的执行辅助工具，内置插件应将执行运行时保留在它们自己的扩展模块中。核心不再拥有位于 `src/agents/tools` 下的 Discord、Slack、Telegram 或 WhatsApp 消息动作运行时。我们不会发布单独的 `plugin-sdk/*-action-runtime` 子路径，内置插件应直接从其扩展自有模块导入自己的本地运行时代码。 -同样的边界也适用于一般意义上的、带提供商名称的 SDK 接缝：核心不应导入 Slack、Discord、Signal、WhatsApp 或类似扩展的渠道特定便捷 barrel。如果核心需要某种行为，应当消费该内置插件自己的 `api.ts` / `runtime-api.ts` barrel，或者将这一需求提升为共享 SDK 中一个精简的通用能力。 +同样的边界也适用于一般情况下以提供商命名的 SDK 接缝：核心不应导入面向 Slack、Discord、Signal、WhatsApp 或类似扩展的渠道特定便利 barrel。如果核心需要某种行为，要么消费内置插件自己的 `api.ts` / `runtime-api.ts` barrel，要么将该需求提升为共享 SDK 中一个狭义的通用能力。 对于投票，当前有两条执行路径： -- `outbound.sendPoll` 是适用于符合通用投票模型的渠道的共享基线 -- `actions.handleAction("poll")` 是适用于渠道特定投票语义或额外投票参数的首选路径 +- `outbound.sendPoll` 是适用于符合通用投票模型渠道的共享基线 +- `actions.handleAction("poll")` 是针对渠道特定投票语义或额外投票参数的首选路径 -现在，核心会在插件投票分发拒绝该动作之后，才回退到共享投票解析，因此插件自有的投票处理器可以接受渠道特定的投票字段，而不会先被通用投票解析器拦住。 +现在，核心会在插件投票分发拒绝该动作之后，才回退到共享投票解析，因此插件自有的投票处理器可以接受渠道特定的投票字段，而不会先被通用投票解析器阻挡。 -完整启动顺序请参阅[加载流水线](#load-pipeline)。 +完整启动顺序请参见[加载流程](#load-pipeline)。 -## 能力所有权模型 +## 能力归属模型 -OpenClaw 将原生插件视为一个**公司**或一个**功能**的所有权边界，而不是无关集成的杂项集合。 +OpenClaw 将原生插件视为**公司**或**功能**的归属边界，而不是一堆无关集成的杂物袋。 这意味着： -- 一个公司插件通常应拥有该公司的全部 OpenClaw 对外能力面 -- 一个功能插件通常应拥有它引入的完整功能能力面 +- 一个公司插件通常应拥有该公司的所有 OpenClaw 对外表面 +- 一个功能插件通常应拥有其引入的完整功能表面 - 渠道应消费共享的核心能力，而不是临时重新实现提供商行为 示例： @@ -193,49 +192,49 @@ OpenClaw 将原生插件视为一个**公司**或一个**功能**的所有权边 - 内置的 `firecrawl` 插件拥有 Firecrawl 网页抓取行为 - 内置的 `minimax`、`mistral`、`moonshot` 和 `zai` 插件拥有它们各自的媒体理解后端 - 内置的 `qwen` 插件拥有 Qwen 文本提供商行为，以及媒体理解和视频生成行为 -- `voice-call` 插件是一个功能插件：它拥有通话传输、工具、CLI、路由和 Twilio 媒体流桥接，但它消费共享的语音以及实时转写和实时语音能力，而不是直接导入厂商插件 +- `voice-call` 插件是一个功能插件：它拥有通话传输、工具、CLI、路由和 Twilio 媒体流桥接，但它会消费共享的语音以及实时转录和实时语音能力，而不是直接导入供应商插件 预期的最终状态是： -- 即使 OpenAI 横跨文本模型、语音、图像和未来的视频能力，它仍然存在于一个插件中 -- 另一个厂商也可以用同样方式管理其自己的全部能力面 -- 渠道并不关心哪个厂商插件拥有该提供商；它们只消费由核心暴露的共享能力契约 +- 即使 OpenAI 同时涵盖文本模型、语音、图像以及未来的视频，它也应存在于同一个插件中 +- 其他供应商也可以对其自身的表面区域采用同样方式 +- 渠道并不关心哪个供应商插件拥有该提供商；它们消费的是由核心暴露的共享能力契约 这是关键区别： -- **plugin** = 所有权边界 -- **capability** = 多个插件都可以实现或消费的核心契约 +- **plugin** = 归属边界 +- **capability** = 多个插件可实现或消费的核心契约 -因此，如果 OpenClaw 增加一个新领域，例如视频，第一个问题不应该是“哪个提供商应该硬编码视频处理？”第一个问题应该是“核心的视频能力契约是什么？”一旦该契约存在，厂商插件就可以针对它进行注册，而渠道/功能插件也可以消费它。 +因此，如果 OpenClaw 添加了视频这样的新领域，首要问题不是“哪个提供商应该硬编码视频处理？”首要问题是“核心的视频能力契约是什么？”一旦该契约存在，供应商插件就可以针对它进行注册，而渠道 / 功能插件也可以消费它。 如果该能力尚不存在，通常正确的做法是： 1. 在核心中定义缺失的能力 -2. 通过插件 API/运行时以类型化方式暴露它 -3. 让渠道/功能围绕该能力进行接线 -4. 让厂商插件注册实现 +2. 通过插件 API / 运行时以类型化方式暴露它 +3. 让渠道 / 功能对接这个能力 +4. 让供应商插件注册实现 -这样可以保持所有权明确，同时避免核心行为依赖单一厂商或某条一次性的插件特定代码路径。 +这样可以在保持归属明确的同时，避免核心行为依赖单一供应商或某条一次性的插件特定代码路径。 ### 能力分层 -在决定代码应该放在哪里时，可使用以下心智模型： +在决定代码应放在哪里时，使用以下思维模型： - **核心能力层**：共享编排、策略、回退、配置合并规则、交付语义和类型化契约 -- **厂商插件层**：厂商特定 API、认证、模型目录、语音合成、图像生成、未来视频后端、用量端点 -- **渠道/功能插件层**：Slack/Discord/voice-call 等集成，它们消费核心能力并在某个能力面上呈现出来 +- **供应商插件层**：供应商特定 API、认证、模型目录、语音合成、图像生成、未来的视频后端、用量端点 +- **渠道 / 功能插件层**：Slack / Discord / voice-call / 等集成，它们消费核心能力并将其呈现在某个表面上 -例如，TTS 遵循这种结构： +例如，TTS 遵循如下结构： - 核心拥有回复时 TTS 策略、回退顺序、偏好和渠道交付 -- `openai`、`elevenlabs` 和 `microsoft` 拥有合成实现 +- `openai`、`elevenlabs` 和 `microsoft` 拥有各自的合成实现 - `voice-call` 消费电话 TTS 运行时辅助工具 -对于未来能力，也应优先采用同样的模式。 +未来的能力也应优先采用同样的模式。 ### 多能力公司插件示例 -从外部看，一个公司插件应该具有一致性。如果 OpenClaw 对模型、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取和网页搜索都有共享契约，那么一个厂商就可以在一个地方拥有它的全部能力面： +从外部看，一个公司插件应当体现出内聚性。如果 OpenClaw 拥有针对模型、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和网页搜索的共享契约，那么一个供应商就可以在一个地方拥有其全部表面： ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -289,163 +288,163 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -关键不在于辅助函数的确切名称，而在于这种结构： +重要的不是确切的辅助函数名称，而是这种结构： -- 一个插件拥有该厂商的能力面 +- 一个插件拥有该供应商表面 - 核心仍然拥有能力契约 -- 渠道和功能插件消费 `api.runtime.*` 辅助工具，而不是厂商代码 -- 契约测试可以断言该插件确实注册了它声称拥有的能力 +- 渠道和功能插件消费 `api.runtime.*` 辅助工具，而不是供应商代码 +- 契约测试可以断言该插件已注册它声称拥有的能力 ### 能力示例：视频理解 -OpenClaw 已经将图像/音频/视频理解视为一种共享能力。同样的所有权模型也适用于这里： +OpenClaw 已经将图像 / 音频 / 视频理解视为一个共享能力。在这里同样适用相同的归属模型： 1. 核心定义媒体理解契约 -2. 厂商插件按需注册 `describeImage`、`transcribeAudio` 和 `describeVideo` -3. 渠道和功能插件消费共享的核心行为，而不是直接接线到厂商代码 +2. 供应商插件按适用情况注册 `describeImage`、`transcribeAudio` 和 `describeVideo` +3. 渠道和功能插件消费共享的核心行为，而不是直接连接到供应商代码 -这样可以避免将某个提供商对视频的假设固化进核心。插件拥有厂商能力面；核心拥有能力契约和回退行为。 +这样可以避免将某个提供商的视频假设固化进核心。插件拥有供应商表面；核心拥有能力契约和回退行为。 -视频生成也已经采用了同样的顺序：核心拥有类型化能力契约和运行时辅助工具，而厂商插件则针对它注册 `api.registerVideoGenerationProvider(...)` 实现。 +视频生成已经使用同样的顺序：核心拥有类型化能力契约和运行时辅助工具，而供应商插件针对它注册 `api.registerVideoGenerationProvider(...)` 实现。 -需要一个具体的发布检查清单吗？请参阅[能力扩展手册](/zh-CN/plugins/architecture)。 +需要一个具体的发布检查清单？参见 [能力扩展手册](/zh-CN/plugins/architecture)。 -## 契约和约束 +## 契约与强制执行 -插件 API 接口被有意设计为类型化，并集中在 `OpenClawPluginApi` 中。该契约定义了受支持的注册点，以及插件可依赖的运行时辅助工具。 +插件 API 表面在 `OpenClawPluginApi` 中被有意设计为类型化且集中化。该契约定义了受支持的注册点，以及插件可以依赖的运行时辅助工具。 -这很重要，因为： +其重要性在于： - 插件作者获得一个稳定的内部标准 -- 核心可以拒绝重复所有权，例如两个插件注册相同的提供商 id -- 启动时可以为格式错误的注册提供可执行的诊断信息 -- 契约测试可以强制执行内置插件的所有权，并防止静默漂移 +- 核心可以拒绝重复归属，例如两个插件注册相同的 provider id +- 启动时可以为格式错误的注册暴露可操作的诊断信息 +- 契约测试可以强制内置插件归属并防止无声漂移 -约束分为两层： +有两层强制机制： -1. **运行时注册约束** - 插件注册表会在插件加载时校验注册。例如：重复的提供商 id、重复的语音提供商 id，以及格式错误的注册，都会产出插件诊断信息，而不是导致未定义行为。 +1. **运行时注册强制** + 插件加载时，插件注册表会校验注册内容。示例：重复的 provider id、重复的 speech provider id 以及格式错误的注册，不会导致未定义行为，而是生成插件诊断信息。 2. **契约测试** - 内置插件会在测试运行期间被捕获到契约注册表中，以便 OpenClaw 能显式断言所有权。当前这用于模型提供商、语音提供商、网页搜索提供商以及内置注册所有权。 + 在测试运行期间，内置插件会被捕获到契约注册表中，以便 OpenClaw 可以明确断言归属。如今这被用于模型提供商、语音提供商、网页搜索提供商和内置注册归属。 -实际效果是，OpenClaw 能够预先知道哪个插件拥有哪个能力面。这样一来，核心和渠道就可以无缝组合，因为所有权是声明式、类型化且可测试的，而不是隐式的。 +实际效果是，OpenClaw 会预先知道哪个插件拥有哪个表面。这让核心和渠道能够无缝组合，因为归属是声明出来的、类型化的并且可测试，而不是隐含的。 -### 什么内容应属于契约 +### 什么应该属于契约 好的插件契约应当是： -- 类型化 -- 小而精 -- 能力特定 +- 类型化的 +- 小而精的 +- 能力特定的 - 由核心拥有 - 可被多个插件复用 -- 可被渠道/功能消费，而无需了解厂商细节 +- 能被渠道 / 功能消费，而无需了解供应商细节 不好的插件契约包括： -- 隐藏在核心中的厂商特定策略 -- 绕过注册表的一次性插件逃逸口 -- 渠道代码直接深入到厂商实现 +- 隐藏在核心中的供应商特定策略 +- 绕过注册表的一次性插件逃生口 +- 渠道代码直接深入供应商实现 - 不属于 `OpenClawPluginApi` 或 `api.runtime` 的临时运行时对象 -拿不准时，就提高抽象层级：先定义能力，再让插件接入它。 +如果拿不准，就提升抽象层级：先定义能力，再让插件接入它。 ## 执行模型 -原生 OpenClaw 插件会**在进程内**与 Gateway 网关一起运行。它们不是沙箱隔离的。已加载的原生插件与核心代码处于相同的进程级信任边界内。 +原生 OpenClaw 插件会与 Gateway 网关**在同一进程内**运行。它们不是沙箱隔离的。一个已加载的原生插件与核心代码具有相同的进程级信任边界。 -这意味着： +其影响包括： - 原生插件可以注册工具、网络处理器、钩子和服务 -- 原生插件中的 bug 可能导致 Gateway 网关崩溃或不稳定 -- 恶意原生插件等同于在 OpenClaw 进程内执行任意代码 +- 原生插件中的 bug 可能导致 gateway 崩溃或不稳定 +- 恶意原生插件等同于在 OpenClaw 进程内部执行任意代码 -兼容 bundle 默认更安全，因为 OpenClaw 当前将它们视为元数据/内容包。在当前版本中，这主要指内置 Skills。 +兼容 bundle 默认更安全，因为 OpenClaw 当前将它们视为元数据 / 内容包。在当前版本中，这主要指内置 Skills。 -对于非内置插件，请使用 allowlist 和显式安装/加载路径。应将工作区插件视为开发期代码，而不是生产默认项。 +对于非内置插件，请使用 allowlist 和显式的安装 / 加载路径。将工作区插件视为开发时代码，而不是生产环境默认值。 -对于内置工作区包名，默认应让插件 id 锚定在 npm 名称中：`@openclaw/`，或者使用经批准的类型化后缀，例如 `-provider`、`-plugin`、`-speech`、`-sandbox` 或 `-media-understanding`，前提是该包有意暴露更窄的插件角色。 +对于内置工作区包名，默认应让插件 id 以 npm 名称中的 `@openclaw/` 为锚点，或者使用批准的类型化后缀，例如 `-provider`、`-plugin`、`-speech`、`-sandbox` 或 `-media-understanding`，当该包有意暴露更狭义的插件角色时可这样命名。 重要的信任说明： - `plugins.allow` 信任的是**插件 id**，而不是来源出处。 -- 如果某个工作区插件与某个内置插件具有相同 id，那么当该工作区插件被启用/加入 allowlist 时，它会有意遮蔽内置副本。 -- 这属于正常且有用的行为，适用于本地开发、补丁测试和热修复。 +- 与内置插件具有相同 id 的工作区插件，在启用 / 加入 allowlist 后，会有意遮蔽该内置副本。 +- 这是一种正常且有用的行为，适用于本地开发、补丁测试和热修复。 ## 导出边界 -OpenClaw 导出的是能力，而不是实现便利性。 +OpenClaw 导出的是能力，而不是实现层面的便利工具。 -应保持能力注册为公开能力面。应精简非契约辅助导出： +保持能力注册为公共接口。收紧非契约辅助导出： - 内置插件特定的辅助子路径 -- 不打算作为公共 API 的运行时接线子路径 -- 厂商特定的便捷辅助函数 -- 属于实现细节的设置/新手引导辅助工具 +- 不打算作为公共 API 的运行时管线子路径 +- 供应商特定的便利辅助函数 +- 属于实现细节的设置 / 新手引导辅助工具 -出于兼容性和内置插件维护的需要，一些内置插件辅助子路径仍保留在生成的 SDK 导出映射中。当前示例包括 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup`，以及若干 `plugin-sdk/matrix*` 接缝。应将这些视为保留的实现细节导出，而不是为新的第三方插件推荐的 SDK 模式。 +出于兼容性和内置插件维护的需要，一些内置插件辅助子路径仍保留在生成的 SDK 导出映射中。当前示例包括 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 以及若干 `plugin-sdk/matrix*` 接缝。应将它们视为保留的实现细节导出，而不是新第三方插件推荐采用的 SDK 模式。 -## 加载流水线 +## 加载流程 在启动时，OpenClaw 大致会执行以下步骤： 1. 发现候选插件根目录 -2. 读取原生或兼容 bundle 的清单及包元数据 +2. 读取原生或兼容 bundle 的清单与包元数据 3. 拒绝不安全的候选项 4. 规范化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、`slots`、`load.paths`） -5. 为每个候选项决定是否启用 -6. 通过 jiti 加载已启用的原生模块 -7. 调用原生 `register(api)`（或 `activate(api)`——旧版别名）钩子，并将注册收集到插件注册表中 -8. 将注册表暴露给命令/运行时能力面 +5. 决定每个候选项的启用状态 +6. 通过 `jiti` 加载已启用的原生模块 +7. 调用原生 `register(api)`（或 `activate(api)`——旧版别名）钩子，并将注册内容收集到插件注册表中 +8. 将注册表暴露给命令 / 运行时表面 -`activate` 是 `register` 的旧版别名——加载器会解析其中存在的那个（`def.register ?? def.activate`），并在相同时间点调用。所有内置插件都使用 `register`；新插件请优先使用 `register`。 +`activate` 是 `register` 的旧版别名——加载器会解析存在的那个（`def.register ?? def.activate`），并在相同时间点调用它。所有内置插件都使用 `register`；新插件优先使用 `register`。 -安全门控发生在**运行时代码执行之前**。当入口逃逸出插件根目录、路径可被所有人写入，或者对于非内置插件来说路径所有权看起来可疑时，候选项会被阻止。 +安全闸门发生在**运行时执行之前**。当入口逃离插件根目录、路径对所有人可写，或者对于非内置插件而言路径归属看起来可疑时，候选项会被阻止。 ### Manifest-first 行为 -manifest 是控制面的事实来源。OpenClaw 用它来： +清单是控制平面的事实来源。OpenClaw 用它来： - 标识插件 -- 发现已声明的渠道/Skills/配置模式或 bundle 能力 +- 发现声明的渠道 / Skills / 配置 schema 或 bundle 能力 - 校验 `plugins.entries..config` -- 增强 Control UI 标签/占位符 -- 显示安装/目录元数据 -- 在不加载插件运行时的前提下，保留轻量激活和设置描述符 +- 增强 Control UI 标签 / 占位符 +- 显示安装 / 目录元数据 +- 在不加载插件运行时的情况下保留轻量激活和设置描述符 -对于原生插件，运行时模块是数据面部分。它会注册实际行为，例如钩子、工具、命令或提供商流程。 +对于原生插件，运行时模块是数据平面部分。它会注册实际行为，例如钩子、工具、命令或提供商流程。 -可选的 manifest `activation` 和 `setup` 块仍属于控制面。它们只是用于激活规划和设置发现的纯元数据描述符；它们并不能替代运行时注册、`register(...)` 或 `setupEntry`。 -第一批在线激活消费者现在会使用 manifest 中的命令、渠道和提供商提示，在更广泛的注册表物化之前先缩小插件加载范围： +可选的清单 `activation` 和 `setup` 区块仍属于控制平面。它们是仅元数据的描述符，用于激活规划和设置发现；它们不会替代运行时注册、`register(...)` 或 `setupEntry`。 +首批实时激活消费者现在会使用清单中的命令、渠道和提供商提示，在更广泛的注册表实体化之前缩小插件加载范围： - CLI 加载会缩小到拥有所请求主命令的插件 -- 渠道设置/插件解析会缩小到拥有所请求渠道 id 的插件 -- 显式提供商设置/运行时解析会缩小到拥有所请求提供商 id 的插件 +- 渠道设置 / 插件解析会缩小到拥有所请求 channel id 的插件 +- 显式提供商设置 / 运行时解析会缩小到拥有所请求 provider id 的插件 -设置发现现在会优先使用描述符自有的 id，例如 `setup.providers` 和 `setup.cliBackends`，以便在回退到 `setup-api` 之前先缩小候选插件范围；而 `setup-api` 仅用于那些仍然需要设置期运行时钩子的插件。如果多个已发现插件声称拥有同一个规范化后的设置提供商或 CLI 后端 id，那么设置查找会拒绝这个存在歧义的所有者，而不是依赖发现顺序。 +设置发现现在会优先使用由描述符拥有的 id，例如 `setup.providers` 和 `setup.cliBackends`，以便在回退到 `setup-api` 之前先缩小候选插件范围；而 `setup-api` 则用于那些仍然需要设置时运行时钩子的插件。如果多个已发现插件声明了相同的规范化 setup provider 或 CLI backend id，设置查找会拒绝这个存在歧义的归属者，而不是依赖发现顺序。 ### 加载器会缓存什么 -OpenClaw 会为以下内容保留短生命周期的进程内缓存： +OpenClaw 会在进程内维护短生命周期缓存，用于： - 发现结果 -- manifest 注册表数据 +- 清单注册表数据 - 已加载的插件注册表 -这些缓存可减少突发式启动和重复命令带来的开销。可以安全地将它们理解为短期性能缓存，而不是持久化机制。 +这些缓存可以减少突发式启动和重复命令的开销。可以将它们安全地理解为短生命周期的性能缓存，而不是持久化存储。 性能说明： - 设置 `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` 或 `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` 可禁用这些缓存。 -- 可通过 `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` 和 `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` 调整缓存窗口。 +- 使用 `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` 和 `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` 调整缓存窗口。 ## 注册表模型 -已加载的插件不会直接修改任意核心全局对象。它们会注册到一个中央插件注册表中。 +已加载的插件不会直接修改任意核心全局状态。它们会注册到一个中央插件注册表中。 -该注册表会跟踪： +注册表会跟踪： - 插件记录（身份、来源、出处、状态、诊断） - 工具 @@ -458,16 +457,16 @@ OpenClaw 会为以下内容保留短生命周期的进程内缓存： - 后台服务 - 插件自有命令 -随后，核心功能会从该注册表中读取，而不是直接与插件模块交互。这使加载方向保持单向： +然后，核心功能从这个注册表中读取，而不是直接与插件模块通信。这使加载保持单向： -- 插件模块 -> 注册到注册表 -- 核心运行时 -> 消费注册表 +- 插件模块 -> 注册表注册 +- 核心运行时 -> 注册表消费 -这种分离对于可维护性非常重要。这意味着大多数核心能力面只需要一个集成点：“读取注册表”，而不是“为每个插件模块编写特例”。 +这种分离对于可维护性很重要。这意味着大多数核心表面只需要一个集成点：“读取注册表”，而不是“为每个插件模块做特殊处理”。 ## 对话绑定回调 -绑定对话的插件可以在审批结果确定时作出响应。 +绑定对话的插件可以在审批结果确定后作出响应。 使用 `api.onConversationBindingResolved(...)` 可在绑定请求被批准或拒绝后接收回调： @@ -489,87 +488,85 @@ export default { }; ``` -回调负载字段： +回调负载字段包括： - `status`：`"approved"` 或 `"denied"` - `decision`：`"allow-once"`、`"allow-always"` 或 `"deny"` -- `binding`：用于已批准请求的已解析绑定 -- `request`：原始请求摘要、分离提示、发送者 id，以及对话元数据 +- `binding`：已批准请求对应的已解析绑定 +- `request`：原始请求摘要、detach 提示、sender id 和对话元数据 -此回调仅用于通知。它不会改变谁被允许绑定对话，并且会在核心审批处理完成之后才运行。 +这个回调仅用于通知。它不会改变谁被允许绑定对话，并且会在核心审批处理完成后运行。 ## 提供商运行时钩子 -提供商插件现在分为两层： +提供商插件现在有两层： -- manifest 元数据：`providerAuthEnvVars` 用于在运行时加载前进行轻量的提供商环境变量认证查找，`providerAuthAliases` 用于共享认证的提供商变体，`channelEnvVars` 用于在运行时加载前进行轻量的渠道环境变量/设置查找，另有 `providerAuthChoices` 用于在运行时加载前为新手引导/认证选项标签和 CLI 标志元数据提供轻量支持 -- 配置期钩子：`catalog` / 旧版 `discovery` 以及 `applyConfigDefaults` -- 运行时钩子：`normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`resolveExternalAuthProfiles`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`isBinaryThinking`、`supportsXHighThinking`、`supportsAdaptiveThinking`、`supportsMaxThinking`、`resolveDefaultThinkingLevel`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot`、`createEmbeddingProvider`、`buildReplayPolicy`、`sanitizeReplayHistory`、`validateReplayTurns`、`onModelSelected` +- 清单元数据：`providerAuthEnvVars` 用于在运行时加载前进行轻量级提供商环境变量认证查找，`providerAuthAliases` 用于共享认证的提供商变体，`channelEnvVars` 用于在运行时加载前进行轻量级渠道环境变量 / 设置查找，以及 `providerAuthChoices` 用于在运行时加载前提供轻量级新手引导 / 认证选项标签和 CLI 标志元数据 +- 配置时钩子：`catalog` / 旧版 `discovery` 以及 `applyConfigDefaults` +- 运行时钩子：`normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`resolveExternalAuthProfiles`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`resolveThinkingProfile`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot`、`createEmbeddingProvider`、`buildReplayPolicy`、`sanitizeReplayHistory`、`validateReplayTurns`、`onModelSelected` -OpenClaw 仍然拥有通用智能体循环、故障切换、转录处理和工具策略。这些钩子是面向提供商特定行为的扩展能力面，而无需实现整套自定义推理传输。 +OpenClaw 仍然拥有通用智能体循环、故障切换、转录处理和工具策略。这些钩子是在无需整套自定义推理传输的情况下，为提供商特定行为提供扩展表面的方式。 -当某个提供商拥有基于环境变量的凭证，并且希望通用认证/状态/模型选择器路径在不加载插件运行时的情况下也能感知它时，请使用 manifest `providerAuthEnvVars`。如果某个提供商 id 应复用另一个提供商 id 的环境变量、认证配置文件、配置支持的认证和 API 密钥新手引导选项，请使用 manifest `providerAuthAliases`。如果希望新手引导/认证选项 CLI 能在不加载提供商运行时的情况下知道提供商的选项 id、分组标签和简单的单标志认证接线，请使用 manifest `providerAuthChoices`。而提供商运行时中的 `envVars` 则应保留用于面向操作员的提示，例如新手引导标签或 OAuth client-id/client-secret 设置变量。 +当提供商具有基于环境变量的凭证，并且通用认证 / 状态 / 模型选择器路径需要在不加载插件运行时的情况下看到它们时，请使用清单中的 `providerAuthEnvVars`。当一个 provider id 应复用另一个 provider id 的环境变量、认证配置文件、基于配置的认证以及 API 密钥新手引导选项时，请使用清单中的 `providerAuthAliases`。当新手引导 / 认证选项 CLI 表面需要在不加载提供商运行时的情况下知道该提供商的 choice id、分组标签和简单的单标志认证接线时，请使用清单中的 `providerAuthChoices`。将提供商运行时 `envVars` 保留用于面向操作人员的提示，例如新手引导标签或 OAuth client-id / client-secret 设置变量。 -当某个渠道具有由环境变量驱动的认证或设置，并且希望通用 shell 环境变量回退、配置/状态检查或设置提示在不加载渠道运行时的情况下也能感知它时，请使用 manifest `channelEnvVars`。 +当某个渠道具有基于环境变量驱动的认证或设置，并且通用 shell 环境变量回退、配置 / 状态检查或设置提示需要在不加载渠道运行时的情况下看到它时，请使用清单中的 `channelEnvVars`。 -### 钩子顺序和用法 +### 钩子顺序与使用方式 -对于模型/提供商插件，OpenClaw 会按大致如下顺序调用这些钩子。 -“何时使用”这一列就是快速决策指南。 +对于模型 / 提供商插件，OpenClaw 大致按如下顺序调用钩子。“何时使用”这一列是快速决策指南。 -| # | 钩子 | 作用 | 何时使用 | +| # | 钩子 | 作用 | 何时使用 | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | 在生成 `models.json` 期间将提供商配置发布到 `models.providers` 中 | 提供商拥有目录或基础 URL 默认值 | -| 2 | `applyConfigDefaults` | 在配置物化期间应用由提供商拥有的全局配置默认值 | 默认值依赖于认证模式、环境变量或提供商模型族语义 | -| -- | _(built-in model lookup)_ | OpenClaw 会先尝试正常的注册表/目录路径 | _(不是插件钩子)_ | -| 3 | `normalizeModelId` | 在查找前规范化旧版或预览版模型 id 别名 | 提供商在规范模型解析前拥有别名清理逻辑 | -| 4 | `normalizeTransport` | 在通用模型组装之前规范化提供商族的 `api` / `baseUrl` | 提供商在同一传输族中拥有针对自定义提供商 id 的传输清理逻辑 | -| 5 | `normalizeConfig` | 在运行时/提供商解析之前规范化 `models.providers.` | 提供商需要将配置清理逻辑与插件放在一起；内置的 Google 族辅助工具也会为受支持的 Google 配置项提供兜底 | -| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式用量兼容性重写 | 提供商需要基于端点修正原生流式用量元数据 | -| 7 | `resolveConfigApiKey` | 在加载运行时认证之前，为配置提供商解析环境变量标记认证 | 提供商拥有自己的环境变量标记 API 密钥解析逻辑；`amazon-bedrock` 也在此处内置了 AWS 环境变量标记解析器 | -| 8 | `resolveSyntheticAuth` | 在不持久化明文的情况下暴露本地/自托管或配置支持的认证 | 提供商可以使用合成/本地凭证标记运行 | -| 9 | `resolveExternalAuthProfiles` | 叠加由提供商拥有的外部认证配置文件；默认 `persistence` 为 `runtime-only`，适用于 CLI/应用自有凭证 | 提供商会复用外部认证凭证，而不持久化复制的刷新令牌 | -| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的合成配置文件占位符降级到环境变量/配置支持认证之后 | 提供商存储了不应具有更高优先级的合成占位配置文件 | -| 11 | `resolveDynamicModel` | 为本地注册表中尚不存在的提供商自有模型 id 提供同步回退解析 | 提供商接受任意上游模型 id | -| 12 | `prepareDynamicModel` | 进行异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 id 之前需要网络元数据 | -| 13 | `normalizeResolvedModel` | 在嵌入式运行器使用已解析模型之前执行最终重写 | 提供商需要传输重写，但仍使用核心传输 | -| 14 | `contributeResolvedModelCompat` | 为另一个兼容传输背后的厂商模型提供兼容性标志 | 提供商能够在代理传输上识别自己的模型，而无需接管该提供商 | -| 15 | `capabilities` | 由提供商拥有、供共享核心逻辑使用的转录/工具元数据 | 提供商需要处理转录或提供商族特有差异 | -| 16 | `normalizeToolSchemas` | 在嵌入式运行器看到工具模式之前先进行规范化 | 提供商需要进行传输族级别的模式清理 | -| 17 | `inspectToolSchemas` | 在规范化之后暴露由提供商拥有的模式诊断信息 | 提供商希望给出关键字警告，而不必让核心理解提供商特定规则 | -| 18 | `resolveReasoningOutputMode` | 选择原生推理输出契约还是带标签的推理输出契约 | 提供商需要使用带标签的推理/最终输出，而不是原生字段 | -| 19 | `prepareExtraParams` | 在通用流式选项包装器之前规范化请求参数 | 提供商需要默认请求参数或按提供商划分的参数清理 | -| 20 | `createStreamFn` | 用自定义传输完全替换正常的流式路径 | 提供商需要自定义线协议，而不只是包装器 | -| 21 | `wrapStreamFn` | 在应用通用包装器之后再包装流式函数 | 提供商需要请求头/请求体/模型兼容性包装器，而无需自定义传输 | -| 22 | `resolveTransportTurnState` | 附加原生的逐轮传输头或元数据 | 提供商希望通用传输发送提供商原生的轮次身份信息 | -| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或会话冷却策略 | 提供商希望通用 WS 传输调整会话头或回退策略 | -| 24 | `formatApiKey` | 认证配置文件格式化器：已存储配置文件会变成运行时 `apiKey` 字符串 | 提供商存储了额外认证元数据，并需要自定义运行时令牌格式 | -| 25 | `refreshOAuth` | 为自定义刷新端点或刷新失败策略覆盖 OAuth 刷新逻辑 | 提供商不适配共享的 `pi-ai` 刷新器 | -| 26 | `buildAuthDoctorHint` | 当 OAuth 刷新失败时附加修复提示 | 提供商在刷新失败后需要由提供商自有的认证修复指导 | -| 27 | `matchesContextOverflowError` | 由提供商拥有的上下文窗口溢出匹配器 | 提供商存在通用启发式方法无法识别的原始溢出错误 | -| 28 | `classifyFailoverReason` | 由提供商拥有的故障切换原因分类 | 提供商能够将原始 API/传输错误映射为限流/过载等类型 | -| 29 | `isCacheTtlEligible` | 面向代理/回传提供商的提示词缓存策略 | 提供商需要代理特定的缓存 TTL 门控 | -| 30 | `buildMissingAuthMessage` | 替代通用缺失认证恢复消息 | 提供商需要提供商特定的缺失认证恢复提示 | -| 31 | `suppressBuiltInModel` | 过期上游模型抑制，并可附带面向用户的错误提示 | 提供商需要隐藏过期的上游条目，或用厂商提示替换它们 | -| 32 | `augmentModelCatalog` | 在发现后追加合成/最终目录条目 | 提供商需要在 `models list` 和选择器中添加用于前向兼容的合成条目 | -| 33 | `isBinaryThinking` | 面向二元思考提供商的开/关推理切换 | 提供商只暴露二元的思考开/关 | -| 34 | `supportsXHighThinking` | 为选定模型提供 `xhigh` 推理支持 | 提供商希望仅在部分模型上显示 `xhigh` | -| 35 | `supportsAdaptiveThinking` | 为选定模型提供 `adaptive` 思考支持 | 提供商希望仅在由提供商管理自适应思考的模型上显示 `adaptive` | -| 36 | `supportsMaxThinking` | 为选定模型提供 `max` 推理支持 | 提供商希望仅在具有提供商最大思考能力的模型上显示 `max` | -| 37 | `resolveDefaultThinkingLevel` | 为特定模型族解析默认 `/think` 级别 | 提供商拥有某个模型族的默认 `/think` 策略 | -| 38 | `isModernModelRef` | 用于实时配置文件过滤和冒烟选择的现代模型匹配器 | 提供商拥有实时/冒烟首选模型匹配逻辑 | -| 39 | `prepareRuntimeAuth` | 在推理前将已配置凭证交换为实际运行时令牌/密钥 | 提供商需要令牌交换或短生命周期的请求凭证 | -| 40 | `resolveUsageAuth` | 为 `/usage` 及相关状态能力面解析用量/计费凭证 | 提供商需要自定义用量/配额令牌解析，或需要不同的用量凭证 | -| 41 | `fetchUsageSnapshot` | 在认证解析完成后获取并规范化提供商特定的用量/配额快照 | 提供商需要提供商特定的用量端点或负载解析器 | -| 42 | `createEmbeddingProvider` | 为 memory/search 构建由提供商拥有的嵌入适配器 | Memory 嵌入行为应归属于提供商插件 | -| 43 | `buildReplayPolicy` | 返回一个用于控制该提供商转录处理的重放策略 | 提供商需要自定义转录策略（例如移除思考块） | -| 44 | `sanitizeReplayHistory` | 在通用转录清理之后重写重放历史 | 提供商需要在共享压缩辅助工具之外，执行提供商特定的重放重写 | -| 45 | `validateReplayTurns` | 在嵌入式运行器之前对重放轮次进行最终校验或重塑 | 提供商传输在通用清洗之后需要更严格的轮次校验 | -| 46 | `onModelSelected` | 在模型被选中后运行由提供商拥有的副作用 | 当某个模型变为活动状态时，提供商需要遥测或提供商自有状态 | +| 1 | `catalog` | 在生成 `models.json` 期间将提供商配置发布到 `models.providers` 中 | 提供商拥有目录或基础 URL 默认值 | +| 2 | `applyConfigDefaults` | 在配置实体化期间应用提供商自有的全局配置默认值 | 默认值依赖认证模式、环境变量或提供商模型家族语义 | +| -- | _(内置模型查找)_ | OpenClaw 会先尝试常规注册表 / 目录路径 | _(不是插件钩子)_ | +| 3 | `normalizeModelId` | 在查找前规范化旧版或预览版 model-id 别名 | 提供商拥有在规范模型解析前进行的别名清理 | +| 4 | `normalizeTransport` | 在通用模型组装前规范化提供商家族的 `api` / `baseUrl` | 提供商拥有同一传输家族中自定义 provider id 的传输清理逻辑 | +| 5 | `normalizeConfig` | 在运行时 / 提供商解析前规范化 `models.providers.` | 提供商需要将配置清理逻辑与插件放在一起；内置的 Google 家族辅助工具也会为受支持的 Google 配置项提供兜底 | +| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生分块流式传输用量兼容性重写 | 提供商需要基于端点驱动的原生分块流式传输用量元数据修复 | +| 7 | `resolveConfigApiKey` | 在运行时认证加载前，为配置提供商解析环境变量标记认证 | 提供商拥有自己的环境变量标记 API 密钥解析逻辑；`amazon-bedrock` 这里也有一个内置的 AWS 环境变量标记解析器 | +| 8 | `resolveSyntheticAuth` | 在不持久化明文的情况下暴露本地 / 自托管或基于配置的认证 | 提供商可使用合成 / 本地凭证标记运行 | +| 9 | `resolveExternalAuthProfiles` | 叠加提供商自有的外部认证配置文件；默认 `persistence` 为面向 CLI / 应用自有凭证的 `runtime-only` | 提供商会复用外部认证凭证，而不持久化复制出来的 refresh token | +| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的合成配置文件占位符优先级下调到环境变量 / 基于配置的认证之后 | 提供商存储了不应优先生效的合成占位配置文件 | +| 11 | `resolveDynamicModel` | 为尚未存在于本地注册表中的提供商自有 model id 提供同步回退 | 提供商接受任意上游 model id | +| 12 | `prepareDynamicModel` | 进行异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 id 前需要网络元数据 | +| 13 | `normalizeResolvedModel` | 在嵌入式运行器使用已解析模型前进行最终重写 | 提供商需要进行传输重写，但仍使用核心传输 | +| 14 | `contributeResolvedModelCompat` | 为位于另一个兼容传输后的供应商模型提供兼容性标志 | 提供商能在代理传输上识别自己的模型，而不接管该提供商 | +| 15 | `capabilities` | 由共享核心逻辑使用的提供商自有转录 / 工具元数据 | 提供商需要处理转录 / 提供商家族特有行为 | +| 16 | `normalizeToolSchemas` | 在嵌入式运行器看到工具 schema 之前对其进行规范化 | 提供商需要处理传输家族 schema 清理 | +| 17 | `inspectToolSchemas` | 在规范化后暴露提供商自有的 schema 诊断信息 | 提供商希望给出关键字警告，而不需要教核心了解提供商特定规则 | +| 18 | `resolveReasoningOutputMode` | 选择原生还是带标签的推理输出契约 | 提供商需要使用带标签的推理 / 最终输出，而不是原生字段 | +| 19 | `prepareExtraParams` | 在通用流包装器之前对请求参数进行规范化 | 提供商需要默认请求参数或按提供商清理参数 | +| 20 | `createStreamFn` | 用自定义传输完全替换常规流路径 | 提供商需要自定义线路协议，而不只是包装器 | +| 21 | `wrapStreamFn` | 在应用通用包装器之后再包裹流 | 提供商需要请求头 / 请求体 / 模型兼容性包装器，但不需要自定义传输 | +| 22 | `resolveTransportTurnState` | 附加原生的逐轮传输头或元数据 | 提供商希望通用传输发送提供商原生的轮次身份 | +| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或会话冷却策略 | 提供商希望通用 WS 传输可调整会话头或回退策略 | +| 24 | `formatApiKey` | 认证配置文件格式化器：已存储配置文件会变为运行时 `apiKey` 字符串 | 提供商存储了额外认证元数据，并需要自定义运行时 token 形态 | +| 25 | `refreshOAuth` | 用于自定义刷新端点或刷新失败策略的 OAuth 刷新覆盖 | 提供商不适配共享的 `pi-ai` 刷新器 | +| 26 | `buildAuthDoctorHint` | 在 OAuth 刷新失败时追加修复提示 | 提供商需要在刷新失败后提供自有的认证修复指引 | +| 27 | `matchesContextOverflowError` | 提供商自有的上下文窗口溢出匹配器 | 提供商存在通用启发式无法识别的原始溢出错误 | +| 28 | `classifyFailoverReason` | 提供商自有的故障切换原因分类 | 提供商可将原始 API / 传输错误映射为限流 / 过载等原因 | +| 29 | `isCacheTtlEligible` | 面向代理 / 回程提供商的提示词缓存策略 | 提供商需要代理特定的缓存 TTL 限制逻辑 | +| 30 | `buildMissingAuthMessage` | 替代通用缺失认证恢复消息 | 提供商需要提供商特定的缺失认证恢复提示 | +| 31 | `suppressBuiltInModel` | 过时上游模型抑制，并可附带面向用户的错误提示 | 提供商需要隐藏过时的上游条目，或用供应商提示替换它们 | +| 32 | `augmentModelCatalog` | 在发现后追加合成 / 最终目录条目 | 提供商需要在 `models list` 和选择器中添加合成的前向兼容条目 | +| 33 | `resolveThinkingProfile` | 为特定模型设置 `/think` 级别、显示标签和默认值 | 提供商为选定模型提供自定义思考层级或二元标签 | +| 34 | `isBinaryThinking` | 开 / 关推理切换兼容性钩子 | 提供商只暴露二元的思考开 / 关 | +| 35 | `supportsXHighThinking` | `xhigh` 推理支持兼容性钩子 | 提供商希望仅在部分模型上支持 `xhigh` | +| 36 | `resolveDefaultThinkingLevel` | 默认 `/think` 级别兼容性钩子 | 提供商拥有某个模型家族的默认 `/think` 策略 | +| 37 | `isModernModelRef` | 用于实时配置文件筛选和 smoke 选择的现代模型匹配器 | 提供商拥有实时 / smoke 首选模型匹配逻辑 | +| 38 | `prepareRuntimeAuth` | 在推理前最后时刻将已配置凭证交换为实际运行时 token / key | 提供商需要进行 token 交换或使用短生命周期请求凭证 | +| 39 | `resolveUsageAuth` | 为 `/usage` 及相关状态表面解析用量 / 计费凭证 | 提供商需要自定义用量 / 配额 token 解析，或使用不同的用量凭证 | +| 40 | `fetchUsageSnapshot` | 在认证解析完成后获取并规范化提供商特定的用量 / 配额快照 | 提供商需要提供商特定的用量端点或负载解析器 | +| 41 | `createEmbeddingProvider` | 为 memory / 搜索构建提供商自有的 embedding 适配器 | memory embedding 行为应归属于提供商插件 | +| 42 | `buildReplayPolicy` | 返回一个控制该提供商转录处理方式的重放策略 | 提供商需要自定义转录策略（例如剥离 thinking 块） | +| 43 | `sanitizeReplayHistory` | 在通用转录清理后重写重放历史 | 提供商需要在共享压缩辅助工具之外执行提供商特定的重放重写 | +| 44 | `validateReplayTurns` | 在嵌入式运行器之前对重放轮次进行最终校验或重塑 | 提供商传输在通用清理后需要更严格的轮次校验 | +| 45 | `onModelSelected` | 在模型被选中后运行提供商自有的副作用 | 当模型变为活动状态时，提供商需要遥测或提供商自有状态 | -`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配到的提供商插件，然后再依次回退到其他具备相应钩子能力的提供商插件，直到其中某个插件实际修改了模型 id 或传输/配置。这样可以让别名/兼容性提供商 shim 继续工作，而无需调用方知道哪个内置插件拥有该重写逻辑。如果没有任何提供商钩子重写受支持的 Google 族配置项，内置的 Google 配置规范化器仍会执行该兼容性清理。 +`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配到的提供商插件，然后再继续落到其他支持钩子的提供商插件，直到其中某个插件实际修改了 model id 或 transport / config。这样可以让别名 / 兼容性提供商 shim 正常工作，而不要求调用方知道哪个内置插件拥有这次重写。如果没有任何提供商钩子重写受支持的 Google 家族配置项，内置的 Google 配置规范化器仍会应用这类兼容性清理。 -如果提供商需要完全自定义的线协议或自定义请求执行器，那就是另一类扩展。这些钩子适用于仍然运行在 OpenClaw 标准推理循环上的提供商行为。 +如果提供商需要完全自定义的线路协议或自定义请求执行器，那是另一类扩展。这些钩子适用于仍运行在 OpenClaw 常规推理循环上的提供商行为。 ### 提供商示例 @@ -627,29 +624,29 @@ api.registerProvider({ ### 内置示例 -- Anthropic 使用 `resolveDynamicModel`、`capabilities`、`buildAuthDoctorHint`、`resolveUsageAuth`、`fetchUsageSnapshot`、`isCacheTtlEligible`、`supportsAdaptiveThinking`、`supportsMaxThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef` 和 `wrapStreamFn`，因为它拥有 Claude 4.6 前向兼容、提供商族提示、认证修复指导、用量端点集成、提示词缓存资格、感知认证的配置默认值、Claude 默认/自适应思考策略，以及面向 beta headers、`/fast` / `serviceTier` 和 `context1m` 的 Anthropic 特定流式整形。 -- Anthropic 的 Claude 特定流式辅助工具目前仍保留在该内置插件自有的公共 `api.ts` / `contract-api.ts` 接缝中。该包能力面会导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及更底层的 Anthropic 包装器构建器，而不是围绕某个提供商的 beta-header 规则去扩展通用 SDK。 -- OpenAI 使用 `resolveDynamicModel`、`normalizeResolvedModel` 和 `capabilities`，以及 `buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`supportsXHighThinking` 和 `isModernModelRef`，因为它拥有 GPT-5.4 前向兼容、直接 OpenAI `openai-completions` -> `openai-responses` 规范化、感知 Codex 的认证提示、Spark 抑制、合成 OpenAI 列表条目，以及 GPT-5 思考 / 实时模型策略；`openai-responses-defaults` 流式家族则拥有共享的原生 OpenAI Responses 包装器，用于 attribution headers、`/fast`/`serviceTier`、文本详细度、原生 Codex 网页搜索、reasoning-compat 负载整形，以及 Responses 上下文管理。 -- OpenRouter 使用 `catalog` 以及 `resolveDynamicModel` 和 `prepareDynamicModel`，因为该提供商是透传型的，可能在 OpenClaw 静态目录更新之前就暴露新的模型 id；它还使用 `capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，以避免将提供商特定的请求头、路由元数据、推理补丁和提示词缓存策略放进核心。它的重放策略来自 `passthrough-gemini` 家族，而 `openrouter-thinking` 流式家族则拥有代理推理注入以及对不受支持模型 / `auto` 的跳过逻辑。 -- GitHub Copilot 使用 `catalog`、`auth`、`resolveDynamicModel` 和 `capabilities`，以及 `prepareRuntimeAuth` 和 `fetchUsageSnapshot`，因为它需要提供商自有的设备登录、模型回退行为、Claude 转录差异、GitHub token -> Copilot token 交换，以及提供商自有的用量端点。 -- OpenAI Codex 使用 `catalog`、`resolveDynamicModel`、`normalizeResolvedModel`、`refreshOAuth` 和 `augmentModelCatalog`，以及 `prepareExtraParams`、`resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它仍运行在核心 OpenAI 传输之上，但拥有自己的传输/base URL 规范化、OAuth 刷新回退策略、默认传输选择、合成 Codex 目录条目，以及 ChatGPT 用量端点集成；它与直接 OpenAI 共享同一个 `openai-responses-defaults` 流式家族。 -- Google AI Studio 和 Gemini CLI OAuth 使用 `resolveDynamicModel`、`buildReplayPolicy`、`sanitizeReplayHistory`、`resolveReasoningOutputMode`、`wrapStreamFn` 和 `isModernModelRef`，因为 `google-gemini` 重放家族拥有 Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、bootstrap 重放清洗、带标签的推理输出模式，以及现代模型匹配；而 `google-thinking` 流式家族则拥有 Gemini 思考负载规范化。Gemini CLI OAuth 还使用 `formatApiKey`、`resolveUsageAuth` 和 `fetchUsageSnapshot` 来处理令牌格式化、令牌解析和配额端点接线。 -- Anthropic Vertex 通过 `anthropic-by-model` 重放家族使用 `buildReplayPolicy`，这样 Claude 特定的重放清理就能只限定在 Claude id 上，而不会作用于每一个 `anthropic-messages` 传输。 -- Amazon Bedrock 使用 `buildReplayPolicy`、`matchesContextOverflowError`、`classifyFailoverReason` 和 `resolveDefaultThinkingLevel`，因为它拥有面向 Anthropic-on-Bedrock 流量的 Bedrock 特定限流/未就绪/上下文溢出错误分类；其重放策略仍共享同一个仅限 Claude 的 `anthropic-by-model` 保护。 -- OpenRouter、Kilocode、Opencode 和 Opencode Go 通过 `passthrough-gemini` 重放家族使用 `buildReplayPolicy`，因为它们通过 OpenAI 兼容传输代理 Gemini 模型，并且需要 Gemini thought-signature 清洗，而不需要原生 Gemini 重放校验或 bootstrap 重写。 -- MiniMax 通过 `hybrid-anthropic-openai` 重放家族使用 `buildReplayPolicy`，因为一个提供商同时拥有 Anthropic-message 和 OpenAI 兼容语义；它在 Anthropic 侧保留仅限 Claude 的思考块丢弃，同时将推理输出模式覆盖回原生，而 `minimax-fast-mode` 流式家族则在共享流式路径上拥有 fast-mode 模型重写。 -- Moonshot 使用 `catalog` 和 `wrapStreamFn`，因为它仍使用共享 OpenAI 传输，但需要提供商自有的思考负载规范化；`moonshot-thinking` 流式家族会将配置加 `/think` 状态映射到其原生二元思考负载。 -- Kilocode 使用 `catalog`、`capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，因为它需要提供商自有的请求头、推理负载规范化、Gemini 转录提示和 Anthropic 缓存 TTL 门控；`kilocode-thinking` 流式家族则在共享代理流式路径上保留 Kilo 思考注入，同时跳过 `kilo/auto` 和其他不支持显式推理负载的代理模型 id。 -- Z.AI 使用 `resolveDynamicModel`、`prepareExtraParams`、`wrapStreamFn`、`isCacheTtlEligible`、`isBinaryThinking`、`isModernModelRef`、`resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它拥有 GLM-5 回退、`tool_stream` 默认值、二元思考 UX、现代模型匹配，以及用量认证和配额获取；`tool-stream-default-on` 流式家族则将默认开启的 `tool_stream` 包装器保留在每个提供商手写胶水逻辑之外。 -- xAI 使用 `normalizeResolvedModel`、`normalizeTransport`、`contributeResolvedModelCompat`、`prepareExtraParams`、`wrapStreamFn`、`resolveSyntheticAuth`、`resolveDynamicModel` 和 `isModernModelRef`，因为它拥有原生 xAI Responses 传输规范化、Grok fast-mode 别名重写、默认 `tool_stream`、strict-tool / reasoning-payload 清理、供插件自有工具使用的回退认证复用、前向兼容的 Grok 模型解析，以及由提供商拥有的兼容性补丁，例如 xAI 工具模式配置、受支持模式关键字、原生 `web_search` 和 HTML 实体工具调用参数解码。 -- Mistral、OpenCode Zen 和 OpenCode Go 仅使用 `capabilities`，以将转录/工具差异保留在核心之外。 -- 仅目录型的内置提供商，例如 `byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi-coding`、`nvidia`、`qianfan`、`synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine`，仅使用 `catalog`。 -- Qwen 为其文本提供商使用 `catalog`，并为其多模态能力面使用共享的媒体理解和视频生成注册。 -- MiniMax 和 Xiaomi 使用 `catalog` 加用量钩子，因为尽管推理仍通过共享传输运行，但它们的 `/usage` 行为属于插件自有逻辑。 +- Anthropic 使用 `resolveDynamicModel`、`capabilities`、`buildAuthDoctorHint`、`resolveUsageAuth`、`fetchUsageSnapshot`、`isCacheTtlEligible`、`resolveThinkingProfile`、`applyConfigDefaults`、`isModernModelRef` 和 `wrapStreamFn`，因为它拥有 Claude 4.6 前向兼容、提供商家族提示、认证修复指引、用量端点集成、提示词缓存资格、认证感知的配置默认值、Claude 默认 / 自适应思考策略，以及针对 beta 头、`/fast` / `serviceTier` 和 `context1m` 的 Anthropic 特定流整形。 +- Anthropic 的 Claude 特定流辅助工具目前保留在内置插件自身公开的 `api.ts` / `contract-api.ts` 接缝中。该包表面导出的是 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 Anthropic 包装器构建工具，而不是围绕某个提供商的 beta 头规则去扩展通用 SDK。 +- OpenAI 使用 `resolveDynamicModel`、`normalizeResolvedModel` 和 `capabilities`，以及 `buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`resolveThinkingProfile` 和 `isModernModelRef`，因为它拥有 GPT-5.4 前向兼容、直接的 OpenAI `openai-completions` -> `openai-responses` 规范化、面向 Codex 的认证提示、Spark 抑制、合成 OpenAI 列表行，以及 GPT-5 思考 / 实时模型策略；`openai-responses-defaults` 流家族拥有共享的原生 OpenAI Responses 包装器，用于 attribution 头、`/fast` / `serviceTier`、文本详细度、原生 Codex Web 搜索、推理兼容负载整形和 Responses 上下文管理。 +- OpenRouter 使用 `catalog`，以及 `resolveDynamicModel` 和 `prepareDynamicModel`，因为该提供商是透传式的，并且可能会在 OpenClaw 的静态目录更新之前暴露新的 model id；它还使用 `capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，以便将提供商特定请求头、路由元数据、推理补丁和提示词缓存策略保留在核心之外。它的重放策略来自 `passthrough-gemini` 家族，而 `openrouter-thinking` 流家族拥有代理推理注入以及对不受支持模型 / `auto` 的跳过逻辑。 +- GitHub Copilot 使用 `catalog`、`auth`、`resolveDynamicModel` 和 `capabilities`，以及 `prepareRuntimeAuth` 和 `fetchUsageSnapshot`，因为它需要提供商自有的设备登录、模型回退行为、Claude 转录特性、GitHub token -> Copilot token 交换以及提供商自有的用量端点。 +- OpenAI Codex 使用 `catalog`、`resolveDynamicModel`、`normalizeResolvedModel`、`refreshOAuth` 和 `augmentModelCatalog`，以及 `prepareExtraParams`、`resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它仍运行在核心 OpenAI 传输之上，但拥有其 transport / base URL 规范化、OAuth 刷新回退策略、默认传输选择、合成 Codex 目录条目和 ChatGPT 用量端点集成；它与直接 OpenAI 共享同一个 `openai-responses-defaults` 流家族。 +- Google AI Studio 和 Gemini CLI OAuth 使用 `resolveDynamicModel`、`buildReplayPolicy`、`sanitizeReplayHistory`、`resolveReasoningOutputMode`、`wrapStreamFn` 和 `isModernModelRef`，因为 `google-gemini` 重放家族拥有 Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、bootstrap 重放清理、带标签的推理输出模式和现代模型匹配，而 `google-thinking` 流家族拥有 Gemini thinking 负载规范化；Gemini CLI OAuth 还使用 `formatApiKey`、`resolveUsageAuth` 和 `fetchUsageSnapshot` 来处理 token 格式化、token 解析和 quota 端点接线。 +- Anthropic Vertex 通过 `anthropic-by-model` 重放家族使用 `buildReplayPolicy`，这样 Claude 特定的重放清理就能只限定在 Claude id 范围内，而不是作用于每个 `anthropic-messages` 传输。 +- Amazon Bedrock 使用 `buildReplayPolicy`、`matchesContextOverflowError`、`classifyFailoverReason` 和 `resolveThinkingProfile`，因为它拥有针对 Anthropic-on-Bedrock 流量的 Bedrock 特定限流 / 未就绪 / 上下文溢出错误分类；其重放策略仍与同一个仅限 Claude 的 `anthropic-by-model` 防护共享。 +- OpenRouter、Kilocode、Opencode 和 Opencode Go 通过 `passthrough-gemini` 重放家族使用 `buildReplayPolicy`，因为它们通过 OpenAI 兼容传输代理 Gemini 模型，并且需要 Gemini thought-signature 清理，而不需要原生 Gemini 重放校验或 bootstrap 重写。 +- MiniMax 通过 `hybrid-anthropic-openai` 重放家族使用 `buildReplayPolicy`，因为一个提供商同时拥有 Anthropic-message 和 OpenAI 兼容语义；它会在 Anthropic 侧保留仅限 Claude 的 thinking 块丢弃逻辑，同时将推理输出模式覆盖回原生，而 `minimax-fast-mode` 流家族拥有共享流路径上的 fast-mode 模型重写。 +- Moonshot 使用 `catalog`、`resolveThinkingProfile` 和 `wrapStreamFn`，因为它仍使用共享 OpenAI 传输，但需要提供商自有的 thinking 负载规范化；`moonshot-thinking` 流家族将配置加 `/think` 状态映射到其原生的二元 thinking 负载。 +- Kilocode 使用 `catalog`、`capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，因为它需要提供商自有请求头、推理负载规范化、Gemini 转录提示和 Anthropic 缓存 TTL 限制；`kilocode-thinking` 流家族会在共享代理流路径上保留 Kilo thinking 注入，同时跳过 `kilo/auto` 和其他不支持显式推理负载的代理 model id。 +- Z.AI 使用 `resolveDynamicModel`、`prepareExtraParams`、`wrapStreamFn`、`isCacheTtlEligible`、`resolveThinkingProfile`、`isModernModelRef`、`resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它拥有 GLM-5 回退、`tool_stream` 默认值、二元 thinking UX、现代模型匹配，以及用量认证和 quota 获取；`tool-stream-default-on` 流家族会把默认开启的 `tool_stream` 包装器保留在逐提供商手写胶水代码之外。 +- xAI 使用 `normalizeResolvedModel`、`normalizeTransport`、`contributeResolvedModelCompat`、`prepareExtraParams`、`wrapStreamFn`、`resolveSyntheticAuth`、`resolveDynamicModel` 和 `isModernModelRef`，因为它拥有原生 xAI Responses 传输规范化、Grok fast-mode 别名重写、默认 `tool_stream`、严格工具 / 推理负载清理、面向插件自有工具的回退认证复用、前向兼容的 Grok 模型解析，以及提供商自有兼容性补丁，例如 xAI 工具 schema 配置、受支持 schema 关键字、原生 `web_search` 和 HTML 实体工具调用参数解码。 +- Mistral、OpenCode Zen 和 OpenCode Go 只使用 `capabilities`，以便将转录 / 工具特性保留在核心之外。 +- 仅目录型内置提供商，例如 `byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi-coding`、`nvidia`、`qianfan`、`synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine`，只使用 `catalog`。 +- Qwen 为其文本提供商使用 `catalog`，并为其多模态表面共享媒体理解和视频生成注册。 +- MiniMax 和 Xiaomi 使用 `catalog` 加上用量钩子，因为它们的 `/usage` 行为归插件拥有，尽管推理仍通过共享传输运行。 ## 运行时辅助工具 -插件可以通过 `api.runtime` 访问部分选定的核心辅助工具。以 TTS 为例： +插件可以通过 `api.runtime` 访问部分核心辅助工具。以 TTS 为例： ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -670,12 +667,12 @@ const voices = await api.runtime.tts.listVoices({ 说明： -- `textToSpeech` 返回用于文件/语音便笺能力面的标准核心 TTS 输出负载。 -- 使用核心 `messages.tts` 配置和提供商选择逻辑。 -- 返回 PCM 音频缓冲区 + 采样率。插件必须为各提供商自行完成重采样/编码。 -- `listVoices` 对每个提供商来说是可选项。可将其用于厂商自有的语音选择器或设置流程。 -- 语音列表可以包含更丰富的元数据，例如语言区域、性别和人格标签，以支持感知提供商的选择器。 -- 当前 OpenAI 和 ElevenLabs 支持电话场景。Microsoft 不支持。 +- `textToSpeech` 返回适用于文件 / 语音便签表面的常规核心 TTS 输出负载。 +- 使用核心 `messages.tts` 配置和提供商选择。 +- 返回 PCM 音频缓冲区 + 采样率。插件必须为提供商重新采样 / 编码。 +- `listVoices` 对每个提供商来说是可选的。可将其用于供应商自有的语音选择器或设置流程。 +- 语音列表可以包含更丰富的元数据，例如区域设置、性别和个性标签，以供具备提供商感知能力的选择器使用。 +- 目前 OpenAI 和 ElevenLabs 支持电话场景。Microsoft 不支持。 插件也可以通过 `api.registerSpeechProvider(...)` 注册语音提供商。 @@ -698,11 +695,11 @@ api.registerSpeechProvider({ 说明： - 将 TTS 策略、回退和回复交付保留在核心中。 -- 使用语音提供商承载厂商自有的合成行为。 -- 旧版 Microsoft `edge` 输入会被规范化为 `microsoft` 提供商 id。 -- 首选的所有权模型是面向公司的：随着 OpenClaw 增加这些能力契约，一个厂商插件可以同时拥有文本、语音、图像和未来媒体提供商。 +- 对供应商自有的合成行为使用语音提供商。 +- 旧版 Microsoft `edge` 输入会被规范化为 `microsoft` provider id。 +- 首选的归属模型是面向公司的：随着 OpenClaw 增加这些能力契约，一个供应商插件可以同时拥有文本、语音、图像和未来的媒体提供商。 -对于图像/音频/视频理解，插件会注册一个类型化的媒体理解提供商，而不是通用的键值包： +对于图像 / 音频 / 视频理解，插件会注册一个类型化的媒体理解提供商，而不是通用的键 / 值包： ```ts api.registerMediaUnderstandingProvider({ @@ -717,14 +714,14 @@ api.registerMediaUnderstandingProvider({ 说明： - 将编排、回退、配置和渠道接线保留在核心中。 -- 将厂商行为保留在提供商插件中。 -- 增量扩展应保持类型化：新增可选方法、新增可选结果字段、新增可选能力。 +- 将供应商行为保留在提供商插件中。 +- 增量扩展应保持类型化：新的可选方法、新的可选结果字段、新的可选能力。 - 视频生成已经遵循同样的模式： - 核心拥有能力契约和运行时辅助工具 - - 厂商插件注册 `api.registerVideoGenerationProvider(...)` - - 功能/渠道插件消费 `api.runtime.videoGeneration.*` + - 供应商插件注册 `api.registerVideoGenerationProvider(...)` + - 功能 / 渠道插件消费 `api.runtime.videoGeneration.*` -对于 media-understanding 运行时辅助工具，插件可以调用： +对于媒体理解运行时辅助工具，插件可以调用： ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -739,7 +736,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -对于音频转写，插件既可以使用 media-understanding 运行时，也可以使用旧版 STT 别名： +对于音频转录，插件既可以使用媒体理解运行时，也可以使用旧版 STT 别名： ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -752,9 +749,9 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ 说明： -- `api.runtime.mediaUnderstanding.*` 是图像/音频/视频理解的首选共享能力面。 +- `api.runtime.mediaUnderstanding.*` 是图像 / 音频 / 视频理解的首选共享表面。 - 使用核心媒体理解音频配置（`tools.media.audio`）和提供商回退顺序。 -- 当未产生转写输出时返回 `{ text: undefined }`（例如输入被跳过或不受支持）。 +- 当未产生转录输出时返回 `{ text: undefined }`（例如输入被跳过 / 不受支持）。 - `api.runtime.stt.transcribeAudioFile(...)` 仍保留为兼容性别名。 插件也可以通过 `api.runtime.subagent` 启动后台子智能体运行： @@ -771,13 +768,13 @@ const result = await api.runtime.subagent.run({ 说明： -- `provider` 和 `model` 是单次运行可选覆盖项，不会持久化为会话变更。 -- OpenClaw 仅对受信任调用方接受这些覆盖字段。 -- 对于插件自有的回退运行，操作员必须通过 `plugins.entries..subagent.allowModelOverride: true` 显式启用。 -- 使用 `plugins.entries..subagent.allowedModels` 可将受信任插件限制为特定规范 `provider/model` 目标，或使用 `"*"` 显式允许任意目标。 -- 不受信任的插件子智能体运行仍然可用，但覆盖请求会被拒绝，而不是静默回退。 +- `provider` 和 `model` 是每次运行可选的覆盖项，不是持久性的会话更改。 +- OpenClaw 只会为受信任调用方启用这些覆盖字段。 +- 对于插件自有的回退运行，操作员必须通过 `plugins.entries..subagent.allowModelOverride: true` 显式选择启用。 +- 使用 `plugins.entries..subagent.allowedModels` 将受信任插件限制为特定的规范 `provider/model` 目标，或者设为 `"*"` 以显式允许任意目标。 +- 不受信任插件的子智能体运行仍然可用，但覆盖请求会被拒绝，而不是静默回退。 -对于网页搜索，插件可以消费共享运行时辅助工具，而不是深入到智能体工具接线中： +对于网页搜索，插件可以消费共享运行时辅助工具，而不必深入到智能体工具接线中： ```ts const providers = api.runtime.webSearch.listProviders({ @@ -798,8 +795,8 @@ const result = await api.runtime.webSearch.search({ 说明： - 将提供商选择、凭证解析和共享请求语义保留在核心中。 -- 对厂商特定搜索传输使用网页搜索提供商。 -- `api.runtime.webSearch.*` 是功能/渠道插件需要搜索行为但又不依赖智能体工具包装器时的首选共享能力面。 +- 对供应商特定的搜索传输使用网页搜索提供商。 +- 对于需要搜索行为但不依赖智能体工具包装器的功能 / 渠道插件，`api.runtime.webSearch.*` 是首选共享表面。 ### `api.runtime.imageGeneration` @@ -819,7 +816,7 @@ const providers = api.runtime.imageGeneration.listProviders({ ## Gateway 网关 HTTP 路由 -插件可以使用 `api.registerHttpRoute(...)` 暴露 HTTP 端点。 +插件可以通过 `api.registerHttpRoute(...)` 暴露 HTTP 端点。 ```ts api.registerHttpRoute({ @@ -837,155 +834,153 @@ api.registerHttpRoute({ 路由字段： - `path`：Gateway 网关 HTTP 服务器下的路由路径。 -- `auth`：必填。使用 `"gateway"` 表示要求正常 Gateway 网关认证，或使用 `"plugin"` 表示由插件管理认证/webhook 校验。 +- `auth`：必填。使用 `"gateway"` 表示要求常规 Gateway 网关认证，或使用 `"plugin"` 表示由插件管理认证 / webhook 验证。 - `match`：可选。`"exact"`（默认）或 `"prefix"`。 -- `replaceExisting`：可选。允许同一插件替换其自身现有的路由注册。 +- `replaceExisting`：可选。允许同一插件替换自己已有的路由注册。 - `handler`：当路由处理了请求时返回 `true`。 说明： - `api.registerHttpHandler(...)` 已被移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。 - 插件路由必须显式声明 `auth`。 -- 精确的 `path + match` 冲突会被拒绝，除非设置 `replaceExisting: true`，并且一个插件不能替换另一个插件的路由。 -- 带有不同 `auth` 级别的重叠路由会被拒绝。`exact`/`prefix` 的贯穿链只能保留在相同 auth 级别上。 -- `auth: "plugin"` 路由**不会**自动接收操作员运行时作用域。它们用于插件管理的 webhook/签名校验，而不是特权 Gateway 网关辅助调用。 -- `auth: "gateway"` 路由会在 Gateway 网关请求运行时作用域内运行，但该作用域是有意保守的： +- 若 `path + match` 完全冲突，则除非设置 `replaceExisting: true`，否则会被拒绝；并且一个插件不能替换另一个插件的路由。 +- 不同 `auth` 级别的重叠路由会被拒绝。仅在相同认证级别内保留 `exact` / `prefix` 贯穿链。 +- `auth: "plugin"` 路由**不会**自动接收操作员运行时作用域。它们用于插件管理的 webhook / 签名校验，而不是特权 Gateway 网关辅助调用。 +- `auth: "gateway"` 路由会在 Gateway 网关请求运行时作用域内运行，但该作用域被有意设计得较为保守： - 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes` - - 受信任的、带身份信息的 HTTP 模式（例如 `trusted-proxy`，或私有入口上的 `gateway.auth.mode = "none"`）只有在显式提供该头时才会接受 `x-openclaw-scopes` - - 如果这些带身份信息的插件路由请求中缺少 `x-openclaw-scopes`，运行时作用域会回退为 `operator.write` -- 实用规则：不要假设一个 gateway-auth 插件路由天然就是管理员能力面。如果你的路由需要仅管理员可用的行为，请要求使用带身份信息的认证模式，并记录清楚显式 `x-openclaw-scopes` 请求头契约。 + - 带有受信任身份的 HTTP 模式（例如 `trusted-proxy` 或私有入口上的 `gateway.auth.mode = "none"`）只会在该头显式存在时才采纳 `x-openclaw-scopes` + - 如果这些带身份的插件路由请求中缺少 `x-openclaw-scopes`，运行时作用域会回退为 `operator.write` +- 实际规则：不要假设一个使用 gateway 认证的插件路由天然就是管理员表面。如果你的路由需要仅管理员可用的行为，请要求使用带身份的认证模式，并文档化显式的 `x-openclaw-scopes` 请求头契约。 ## 插件 SDK 导入路径 -在编写插件时，应使用 SDK 子路径，而不是整体式的 `openclaw/plugin-sdk` 导入： +在编写插件时，请使用 SDK 子路径，而不是单体式的 `openclaw/plugin-sdk` 导入： -- `openclaw/plugin-sdk/plugin-entry`：用于插件注册原语。 -- `openclaw/plugin-sdk/core`：用于通用共享的面向插件契约。 -- `openclaw/plugin-sdk/config-schema`：用于根 `openclaw.json` Zod 模式导出（`OpenClawSchema`）。 -- 稳定的渠道原语，例如 `openclaw/plugin-sdk/channel-setup`、`openclaw/plugin-sdk/setup-runtime`、`openclaw/plugin-sdk/setup-adapter-runtime`、`openclaw/plugin-sdk/setup-tools`、`openclaw/plugin-sdk/channel-pairing`、`openclaw/plugin-sdk/channel-contract`、`openclaw/plugin-sdk/channel-feedback`、`openclaw/plugin-sdk/channel-inbound`、`openclaw/plugin-sdk/channel-lifecycle`、`openclaw/plugin-sdk/channel-reply-pipeline`、`openclaw/plugin-sdk/command-auth`、`openclaw/plugin-sdk/secret-input` 和 `openclaw/plugin-sdk/webhook-ingress`，用于共享设置/认证/回复/webhook 接线。`channel-inbound` 是防抖、提及匹配、入站提及策略辅助工具、信封格式化以及入站信封上下文辅助工具的共享归属地。`channel-setup` 是精简的可选安装设置接缝。`setup-runtime` 是 `setupEntry` / 延迟启动使用的运行时安全设置能力面，其中包括导入安全的设置补丁适配器。`setup-adapter-runtime` 是感知环境变量的账户设置适配器接缝。`setup-tools` 是精简的 CLI/归档/文档辅助工具接缝（`formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR`）。 -- 领域子路径，例如 `openclaw/plugin-sdk/channel-config-helpers`、`openclaw/plugin-sdk/allow-from`、`openclaw/plugin-sdk/channel-config-schema`、`openclaw/plugin-sdk/telegram-command-config`、`openclaw/plugin-sdk/channel-policy`、`openclaw/plugin-sdk/approval-gateway-runtime`、`openclaw/plugin-sdk/approval-handler-adapter-runtime`、`openclaw/plugin-sdk/approval-handler-runtime`、`openclaw/plugin-sdk/approval-runtime`、`openclaw/plugin-sdk/config-runtime`、`openclaw/plugin-sdk/infra-runtime`、`openclaw/plugin-sdk/agent-runtime`、`openclaw/plugin-sdk/lazy-runtime`、`openclaw/plugin-sdk/reply-history`、`openclaw/plugin-sdk/routing`、`openclaw/plugin-sdk/status-helpers`、`openclaw/plugin-sdk/text-runtime`、`openclaw/plugin-sdk/runtime-store` 和 `openclaw/plugin-sdk/directory-runtime`，用于共享运行时/配置辅助工具。`telegram-command-config` 是 Telegram 自定义命令规范化/校验的精简公共接缝，即使内置 Telegram 契约能力面暂时不可用，它也仍然可用。`text-runtime` 是共享文本/Markdown/日志接缝，其中包括去除对助手可见文本的辅助工具、Markdown 渲染/分块辅助工具、脱敏辅助工具、directive-tag 辅助工具以及安全文本工具。 -- 针对审批的渠道接缝应优先在插件上使用一个 `approvalCapability` 契约。然后核心会通过这一能力统一读取审批认证、交付、渲染、原生路由和惰性原生处理器行为，而不是将审批行为混入无关的插件字段中。 -- `openclaw/plugin-sdk/channel-runtime` 已弃用，目前仅作为旧插件的兼容性 shim 保留。新代码应改为导入更精简的通用原语，仓库代码也不应新增对该 shim 的导入。 -- 内置扩展内部实现仍然是私有的。外部插件应只使用 `openclaw/plugin-sdk/*` 子路径。OpenClaw 核心/测试代码可以使用插件包根目录下仓库公开的入口点，例如 `index.js`、`api.js`、`runtime-api.js`、`setup-entry.js`，以及作用域精确的文件，如 `login-qr-api.js`。绝不要从核心代码或另一个扩展中导入某个插件包的 `src/*`。 +- `openclaw/plugin-sdk/plugin-entry` 用于插件注册原语。 +- `openclaw/plugin-sdk/core` 用于通用共享的面向插件契约。 +- `openclaw/plugin-sdk/config-schema` 用于根 `openclaw.json` 的 Zod schema 导出（`OpenClawSchema`）。 +- 稳定的渠道原语，例如 `openclaw/plugin-sdk/channel-setup`、`openclaw/plugin-sdk/setup-runtime`、`openclaw/plugin-sdk/setup-adapter-runtime`、`openclaw/plugin-sdk/setup-tools`、`openclaw/plugin-sdk/channel-pairing`、`openclaw/plugin-sdk/channel-contract`、`openclaw/plugin-sdk/channel-feedback`、`openclaw/plugin-sdk/channel-inbound`、`openclaw/plugin-sdk/channel-lifecycle`、`openclaw/plugin-sdk/channel-reply-pipeline`、`openclaw/plugin-sdk/command-auth`、`openclaw/plugin-sdk/secret-input` 和 `openclaw/plugin-sdk/webhook-ingress`，用于共享设置 / 认证 / 回复 / webhook 接线。`channel-inbound` 是防抖、提及匹配、入站提及策略辅助工具、信封格式化和入站信封上下文辅助工具的共享归属位置。`channel-setup` 是狭义的可选安装设置接缝。`setup-runtime` 是 `setupEntry` / 延迟启动使用的运行时安全设置表面，其中包括可安全导入的设置补丁适配器。`setup-adapter-runtime` 是具备环境变量感知能力的账户设置适配器接缝。`setup-tools` 是小型 CLI / 归档 / 文档辅助工具接缝（`formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR`）。 +- 领域子路径，例如 `openclaw/plugin-sdk/channel-config-helpers`、`openclaw/plugin-sdk/allow-from`、`openclaw/plugin-sdk/channel-config-schema`、`openclaw/plugin-sdk/telegram-command-config`、`openclaw/plugin-sdk/channel-policy`、`openclaw/plugin-sdk/approval-gateway-runtime`、`openclaw/plugin-sdk/approval-handler-adapter-runtime`、`openclaw/plugin-sdk/approval-handler-runtime`、`openclaw/plugin-sdk/approval-runtime`、`openclaw/plugin-sdk/config-runtime`、`openclaw/plugin-sdk/infra-runtime`、`openclaw/plugin-sdk/agent-runtime`、`openclaw/plugin-sdk/lazy-runtime`、`openclaw/plugin-sdk/reply-history`、`openclaw/plugin-sdk/routing`、`openclaw/plugin-sdk/status-helpers`、`openclaw/plugin-sdk/text-runtime`、`openclaw/plugin-sdk/runtime-store` 和 `openclaw/plugin-sdk/directory-runtime`，用于共享运行时 / 配置辅助工具。`telegram-command-config` 是 Telegram 自定义命令规范化 / 校验的狭义公共接缝，即使内置 Telegram 契约表面暂时不可用，它也仍然可用。`text-runtime` 是共享的文本 / Markdown / 日志接缝，包括对智能体可见文本的剥离、Markdown 渲染 / 分块辅助工具、脱敏辅助工具、指令标签辅助工具和安全文本工具。 +- 面向审批的渠道接缝应优先使用插件上的单一 `approvalCapability` 契约。然后核心通过这一项能力来读取审批认证、交付、渲染、原生路由和惰性原生处理器行为，而不是将审批行为混杂到无关的插件字段中。 +- `openclaw/plugin-sdk/channel-runtime` 已弃用，当前仅作为旧版插件的兼容性 shim 保留。新代码应改为导入更狭义的通用原语，仓库代码也不应再新增对该 shim 的导入。 +- 内置扩展内部实现仍然是私有的。外部插件应仅使用 `openclaw/plugin-sdk/*` 子路径。OpenClaw 核心 / 测试代码可以使用插件包根目录下仓库内公开的入口点，例如 `index.js`、`api.js`、`runtime-api.js`、`setup-entry.js`，以及诸如 `login-qr-api.js` 这类范围狭窄的文件。绝不要从核心或另一个扩展中导入某个插件包的 `src/*`。 - 仓库入口点拆分： - `/api.js` 是辅助工具/类型 barrel， + `/api.js` 是辅助工具 / 类型 barrel， `/runtime-api.js` 是仅运行时 barrel， `/index.js` 是内置插件入口， `/setup-entry.js` 是设置插件入口。 - 当前内置提供商示例： - - Anthropic 使用 `api.js` / `contract-api.js` 提供 Claude 流式辅助工具，例如 `wrapAnthropicProviderStream`、beta-header 辅助工具和 `service_tier` 解析。 + - Anthropic 使用 `api.js` / `contract-api.js` 提供 Claude 流辅助工具，例如 `wrapAnthropicProviderStream`、beta 头辅助工具和 `service_tier` 解析。 - OpenAI 使用 `api.js` 提供提供商构建器、默认模型辅助工具和实时提供商构建器。 - - OpenRouter 使用 `api.js` 提供其提供商构建器以及新手引导/配置辅助工具，而 `register.runtime.js` 仍可为仓库本地使用重新导出通用 `plugin-sdk/provider-stream` 辅助工具。 -- 通过 facade 加载的公共入口点会在存在活动运行时配置快照时优先使用它；如果 OpenClaw 尚未提供运行时快照，则回退到磁盘上已解析的配置文件。 -- 通用共享原语仍然是首选的公共插件 SDK 契约。仍保留一小部分带渠道品牌的内置辅助接缝以兼容旧逻辑。应将它们视为内置维护/兼容性接缝，而不是新的第三方导入目标；新的跨渠道契约仍应落在通用 `plugin-sdk/*` 子路径或插件本地 `api.js` / `runtime-api.js` barrel 上。 + - OpenRouter 使用 `api.js` 提供其提供商构建器以及新手引导 / 配置辅助工具，而 `register.runtime.js` 仍可为仓库内部使用重新导出通用 `plugin-sdk/provider-stream` 辅助工具。 +- 由 facade 加载的公共入口点会在存在活动运行时配置快照时优先使用它；如果 OpenClaw 尚未提供运行时快照，则回退到磁盘上的已解析配置文件。 +- 通用共享原语仍是首选的公共插件 SDK 契约。仍然存在一小组保留的、带内置渠道品牌的辅助工具接缝用于兼容性。应将这些视为内置维护 / 兼容性接缝，而不是新的第三方导入目标；新的跨渠道契约仍应落在通用 `plugin-sdk/*` 子路径或插件本地 `api.js` / `runtime-api.js` barrel 上。 兼容性说明： -- 新代码应避免使用根 `openclaw/plugin-sdk` barrel。 -- 优先使用精简且稳定的原语。较新的 setup/pairing/reply/feedback/contract/inbound/threading/command/secret-input/webhook/infra/allowlist/status/message-tool 子路径，是新的内置和外部插件工作的预期契约。 - 目标解析/匹配应放在 `openclaw/plugin-sdk/channel-targets`。 - 消息动作门控和 reaction message-id 辅助工具应放在 `openclaw/plugin-sdk/channel-actions`。 -- 内置扩展特定的辅助 barrel 默认并不稳定。如果某个辅助工具只被某个内置扩展使用，应将它保留在该扩展本地的 `api.js` 或 `runtime-api.js` 接缝之后，而不是提升到 `openclaw/plugin-sdk/`。 -- 新的共享辅助接缝应当是通用的，而不是带渠道品牌的。共享目标解析应放在 `openclaw/plugin-sdk/channel-targets`；渠道特定内部实现则保留在所属插件本地的 `api.js` 或 `runtime-api.js` 接缝之后。 -- 像 `image-generation`、`media-understanding` 和 `speech` 这样的能力特定子路径之所以存在，是因为内置/原生插件今天就在使用它们。它们的存在本身并不意味着每个导出辅助工具都是长期冻结的外部契约。 +- 新代码应避免使用根级 `openclaw/plugin-sdk` barrel。 +- 优先使用狭义且稳定的原语。较新的 setup / pairing / reply / feedback / contract / inbound / threading / command / secret-input / webhook / infra / allowlist / status / message-tool 子路径，是新内置插件和外部插件工作的预期契约。目标解析 / 匹配应放在 `openclaw/plugin-sdk/channel-targets`。消息动作闸门和 reaction message-id 辅助工具应放在 `openclaw/plugin-sdk/channel-actions`。 +- 默认情况下，内置扩展特定的辅助工具 barrel 不是稳定接口。如果某个辅助工具仅被某个内置扩展需要，应将其保留在该扩展本地的 `api.js` 或 `runtime-api.js` 接缝后面，而不是提升到 `openclaw/plugin-sdk/` 中。 +- 新的共享辅助工具接缝应当是通用的，而不是带渠道品牌的。共享目标解析应放在 `openclaw/plugin-sdk/channel-targets`；渠道特定内部实现则保留在归属插件本地的 `api.js` 或 `runtime-api.js` 接缝后面。 +- `image-generation`、`media-understanding` 和 `speech` 这类能力特定子路径之所以存在，是因为今天的内置 / 原生插件正在使用它们。但这并不自动意味着每个导出的辅助工具都是长期冻结的外部契约。 -## message 工具模式 +## 消息工具 schema -插件应拥有渠道特定的 `describeMessageTool(...)` 模式贡献。将提供商特定字段保留在插件中，而不是放进共享核心。 +插件应拥有渠道特定的 `describeMessageTool(...)` schema 贡献。将提供商特定字段保留在插件中，而不是放入共享核心。 -对于共享的可移植模式片段，可复用通过 `openclaw/plugin-sdk/channel-actions` 导出的通用辅助工具： +对于可移植的共享 schema 片段，请复用通过 `openclaw/plugin-sdk/channel-actions` 导出的通用辅助工具： -- `createMessageToolButtonsSchema()`：用于按钮网格风格的负载 -- `createMessageToolCardSchema()`：用于结构化卡片负载 +- `createMessageToolButtonsSchema()` 用于按钮网格样式负载 +- `createMessageToolCardSchema()` 用于结构化卡片负载 -如果某个模式形状只对某一个提供商有意义，就应在该插件自己的源码中定义它，而不是将其提升到共享 SDK 中。 +如果某个 schema 形状只对一个提供商有意义，请在该插件自己的源码中定义它，而不是将其提升到共享 SDK 中。 ## 渠道目标解析 -渠道插件应拥有渠道特定的目标语义。保持共享出站宿主为通用能力，并使用消息适配器能力面处理提供商规则： +渠道插件应拥有渠道特定的目标语义。保持共享出站宿主通用，并使用消息适配器表面承载提供商规则： -- `messaging.inferTargetChatType({ to })` 用于在目录查找前判断规范化目标应被视为 `direct`、`group` 还是 `channel` -- `messaging.targetResolver.looksLikeId(raw, normalized)` 用于告诉核心某个输入是否应跳过目录搜索，直接进入类 id 解析 -- `messaging.targetResolver.resolveTarget(...)` 是插件回退路径，当核心在规范化之后或目录未命中后需要最终的提供商自有解析时使用 -- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后拥有提供商特定的会话路由构造逻辑 +- `messaging.inferTargetChatType({ to })` 用于在目录查找之前决定一个规范化目标应被视为 `direct`、`group` 还是 `channel` +- `messaging.targetResolver.looksLikeId(raw, normalized)` 用于告诉核心某个输入是否应跳过目录搜索，直接进入类似 id 的解析 +- `messaging.targetResolver.resolveTarget(...)` 是在规范化后或目录未命中后，核心需要最终由提供商拥有的解析结果时，插件的回退路径 +- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后，拥有提供商特定的会话路由构建 推荐拆分方式： -- 对于应在搜索 peers/groups 之前发生的分类决策，使用 `inferTargetChatType` -- 对于“将其视为显式/原生目标 id”的判断，使用 `looksLikeId` -- 对于提供商特定的规范化回退，使用 `resolveTarget`，而不是用它执行广泛的目录搜索 -- 将 chat id、thread id、JID、handle 和 room id 这类提供商原生 id 保留在 `target` 值或提供商特定参数中，而不是放进通用 SDK 字段 +- 对于应在搜索 peers / groups 之前发生的类别决策，使用 `inferTargetChatType` +- 对于“将其视为显式 / 原生目标 id”的检查，使用 `looksLikeId` +- 对于提供商特定的规范化回退，使用 `resolveTarget`，而不是把它用于广义目录搜索 +- 将 chat id、thread id、JID、handle 和 room id 这类提供商原生 id 保留在 `target` 值或提供商特定参数中，而不是放在通用 SDK 字段中 -## 配置支持的目录 +## 基于配置的目录 -如果插件从配置中派生目录项，应将该逻辑保留在插件内部，并复用 `openclaw/plugin-sdk/directory-runtime` 中的共享辅助工具。 +如果插件会从配置派生目录条目，应将该逻辑保留在插件内部，并复用 `openclaw/plugin-sdk/directory-runtime` 中的共享辅助工具。 -适用场景包括某个渠道需要由配置支持的 peers/groups，例如： +当某个渠道需要基于配置的 peers / groups 时，请使用这种方式，例如： -- 由 allowlist 驱动的私信 peers -- 已配置的渠道/群组映射 -- 按账户划分的静态目录回退 +- 基于 allowlist 的私信 peers +- 已配置的渠道 / 分组映射 +- 账户作用域的静态目录回退 `directory-runtime` 中的共享辅助工具只处理通用操作： - 查询过滤 - 限制应用 -- 去重/规范化辅助工具 +- 去重 / 规范化辅助工具 - 构建 `ChannelDirectoryEntry[]` 渠道特定的账户检查和 id 规范化应保留在插件实现中。 ## 提供商目录 -提供商插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })` 定义用于推理的模型目录。 +提供商插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })` 为推理定义模型目录。 `catalog.run(...)` 返回与 OpenClaw 写入 `models.providers` 相同的结构： -- `{ provider }`：用于单个提供商条目 -- `{ providers }`：用于多个提供商条目 +- `{ provider }` 表示一个提供商条目 +- `{ providers }` 表示多个提供商条目 -当插件拥有提供商特定的模型 id、base URL 默认值或受认证控制的模型元数据时，请使用 `catalog`。 +当插件拥有提供商特定 model id、base URL 默认值或受认证控制的模型元数据时，请使用 `catalog`。 `catalog.order` 控制插件目录相对于 OpenClaw 内置隐式提供商的合并时机： - `simple`：普通 API 密钥或环境变量驱动的提供商 -- `profile`：存在认证配置文件时出现的提供商 +- `profile`：当认证配置文件存在时出现的提供商 - `paired`：合成多个相关提供商条目的提供商 - `late`：最后一轮，在其他隐式提供商之后 -后合并的提供商会在键冲突时胜出，因此插件可以有意覆盖拥有相同提供商 id 的内置提供商条目。 +后出现的提供商会在键冲突时胜出，因此插件可以有意覆盖具有相同 provider id 的内置提供商条目。 兼容性： -- `discovery` 仍作为旧版别名可用 +- `discovery` 仍可作为旧版别名使用 - 如果同时注册了 `catalog` 和 `discovery`，OpenClaw 会使用 `catalog` ## 只读渠道检查 -如果你的插件注册了一个渠道，除了 `resolveAccount(...)` 外，也建议实现 `plugin.config.inspectAccount(cfg, accountId)`。 +如果你的插件注册了一个渠道，除 `resolveAccount(...)` 外，优先同时实现 `plugin.config.inspectAccount(cfg, accountId)`。 原因： -- `resolveAccount(...)` 是运行时路径。它可以假定凭证已经完全物化，并在缺少必要密钥时快速失败。 -- 只读命令路径，例如 `openclaw status`、`openclaw status --all`、`openclaw channels status`、`openclaw channels resolve`，以及 doctor/config 修复流程，不应为了描述配置而必须物化运行时凭证。 +- `resolveAccount(...)` 是运行时路径。它可以假设凭证已被完整实体化，并且在缺少必需 secret 时快速失败。 +- 只读命令路径，例如 `openclaw status`、`openclaw status --all`、`openclaw channels status`、`openclaw channels resolve`，以及 doctor / 配置修复流程，不应为了描述配置而必须实体化运行时凭证。 推荐的 `inspectAccount(...)` 行为： - 只返回描述性的账户状态。 - 保留 `enabled` 和 `configured`。 -- 在相关时包含凭证来源/状态字段，例如： +- 在相关时包含凭证来源 / 状态字段，例如： - `tokenSource`、`tokenStatus` - `botTokenSource`、`botTokenStatus` - `appTokenSource`、`appTokenStatus` - `signingSecretSource`、`signingSecretStatus` -- 为了报告只读可用性，你不需要返回原始令牌值。返回 `tokenStatus: "available"`（以及匹配的来源字段）就足够供状态类命令使用。 -- 当凭证通过 SecretRef 配置，但在当前命令路径中不可用时，请使用 `configured_unavailable`。 +- 你不需要为了报告只读可用性而返回原始 token 值。返回 `tokenStatus: "available"`（以及匹配的来源字段）就足以满足状态类命令。 +- 当凭证通过 SecretRef 配置但在当前命令路径中不可用时，使用 `configured_unavailable`。 -这样只读命令就能报告“已配置，但在当前命令路径中不可用”，而不是崩溃或错误地将账户报告为未配置。 +这样只读命令就可以报告“已配置，但在当前命令路径中不可用”，而不是崩溃或错误地报告该账户未配置。 -## 包集合 +## 包 pack -一个插件目录可以包含带有 `openclaw.extensions` 的 `package.json`： +插件目录可以包含带有 `openclaw.extensions` 的 `package.json`： ```json { @@ -997,37 +992,37 @@ api.registerHttpRoute({ } ``` -每个条目都会变成一个插件。如果该 pack 列出了多个扩展，插件 id 就会变成 `name/`。 +每个条目都会成为一个插件。如果 pack 列出了多个扩展，插件 id 将变为 `name/`。 -如果你的插件导入了 npm 依赖，请在该目录中安装它们，以便 `node_modules` 可用（`npm install` / `pnpm install`）。 +如果你的插件导入了 npm 依赖，请在该目录中安装它们，以确保 `node_modules` 可用（`npm install` / `pnpm install`）。 -安全护栏：每个 `openclaw.extensions` 条目在解析符号链接后都必须保留在插件目录内。任何逃逸出包目录的条目都会被拒绝。 +安全护栏：每个 `openclaw.extensions` 条目在解析符号链接后都必须保留在插件目录内。任何逃离包目录的条目都会被拒绝。 -安全说明：`openclaw plugins install` 会使用 `npm install --omit=dev --ignore-scripts` 安装插件依赖（无生命周期脚本，运行时也不安装开发依赖）。请保持插件依赖树为“纯 JS/TS”，并避免需要 `postinstall` 构建的包。 +安全说明：`openclaw plugins install` 会使用 `npm install --omit=dev --ignore-scripts` 安装插件依赖（不运行生命周期脚本，运行时不安装开发依赖）。请保持插件依赖树为“纯 JS / TS”，并避免需要 `postinstall` 构建的包。 -可选项：`openclaw.setupEntry` 可以指向一个轻量级的仅设置模块。当 OpenClaw 需要为某个已禁用的渠道插件提供设置能力面，或者某个渠道插件已启用但尚未配置时，它会加载 `setupEntry` 而不是完整插件入口。这样在你的主插件入口还会接入工具、钩子或其他仅运行时代码时，可让启动和设置过程更轻量。 +可选项：`openclaw.setupEntry` 可以指向一个轻量级、仅用于设置的模块。当 OpenClaw 需要为一个已禁用的渠道插件提供设置表面，或者某个渠道插件已启用但尚未配置时，它会加载 `setupEntry` 而不是完整插件入口。这样在你的主插件入口还会接线工具、钩子或其他仅运行时代码时，可以让启动和设置更轻量。 -可选项：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` 可以让渠道插件在 Gateway 网关预监听启动阶段也选择同一个 `setupEntry` 路径，即使该渠道已经配置完成。 +可选项：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` 可以让一个渠道插件在 Gateway 网关的 pre-listen 启动阶段，即使渠道已经配置完成，也选择加入同一个 `setupEntry` 路径。 -仅当 `setupEntry` 能完全覆盖 Gateway 网关开始监听之前必须存在的启动能力面时，才应使用此项。实际上，这意味着设置入口必须注册启动所依赖的所有渠道自有能力，例如： +只有在 `setupEntry` 完全覆盖 Gateway 网关开始监听之前必须存在的启动表面时，才使用此项。实际来说，这意味着设置入口必须注册启动所依赖的每个渠道自有能力，例如： - 渠道注册本身 -- 所有必须在 Gateway 网关开始监听之前就可用的 HTTP 路由 -- 在同一时间窗口内必须存在的任何 Gateway 网关方法、工具或服务 +- 任何必须在 Gateway 网关开始监听前可用的 HTTP 路由 +- 任何必须在同一时间窗口内存在的 gateway 方法、工具或服务 -如果完整入口仍然拥有任何必需的启动能力，请不要启用此标志。保持插件使用默认行为，让 OpenClaw 在启动期间加载完整入口。 +如果你的完整入口仍然拥有任何必需的启动能力，请不要启用此标志。保持插件采用默认行为，并让 OpenClaw 在启动期间加载完整入口。 -内置渠道也可以发布仅设置的契约能力面辅助工具，供核心在完整渠道运行时加载之前查询。当前的设置提升能力面包括： +内置渠道也可以发布仅设置用的契约表面辅助工具，供核心在完整渠道运行时加载前查询。当前的设置提升表面包括： - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -当核心需要在不加载完整插件入口的前提下，将旧版单账户渠道配置提升到 `channels..accounts.*` 中时，就会使用这组能力面。Matrix 是当前的内置示例：当命名账户已存在时，它只会将认证/bootstrap 键移动到已命名的提升账户中，并且它可以保留一个已配置但非规范的默认账户键，而不是总是创建 `accounts.default`。 +当核心需要在不加载完整插件入口的情况下，将旧版单账户渠道配置提升到 `channels..accounts.*` 时，会使用该表面。Matrix 是当前的内置示例：当命名账户已存在时，它只会将 auth / bootstrap 键移动到一个已命名的提升账户中，并且可以保留一个已配置的非规范默认账户键，而不是总是创建 `accounts.default`。 -这些设置补丁适配器会让内置契约能力面发现保持惰性。导入时保持轻量；提升能力面只会在首次使用时加载，而不会在模块导入时重新进入内置渠道启动流程。 +这些设置补丁适配器让内置契约表面发现保持惰性。导入时间保持轻量；提升表面只会在首次使用时加载，而不是在模块导入时重新进入内置渠道启动。 -当这些启动能力面包含 Gateway 网关 RPC 方法时，请为它们保留插件特定前缀。核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍然是保留的，并且始终解析为 `operator.admin`，即使某个插件请求了更窄的作用域。 +当这些启动表面包含 gateway RPC 方法时，请将它们保留在插件特定前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍然保留，并且始终解析为 `operator.admin`，即使某个插件请求了更窄的作用域也是如此。 示例： @@ -1046,7 +1041,7 @@ api.registerHttpRoute({ ### 渠道目录元数据 -渠道插件可以通过 `openclaw.channel` 宣告设置/发现元数据，并通过 `openclaw.install` 宣告安装提示。这样可以让核心目录保持无数据状态。 +渠道插件可以通过 `openclaw.channel` 声明 setup / 发现元数据，并通过 `openclaw.install` 声明安装提示。这样可以让核心目录保持无数据状态。 示例： @@ -1074,34 +1069,34 @@ api.registerHttpRoute({ } ``` -除最小示例外，还有一些有用的 `openclaw.channel` 字段： +除了最小示例之外，其他有用的 `openclaw.channel` 字段还包括： -- `detailLabel`：用于更丰富目录/状态能力面的次级标签 +- `detailLabel`：用于更丰富目录 / 状态表面的次级标签 - `docsLabel`：覆盖文档链接的链接文本 -- `preferOver`：该目录条目应优先于的低优先级插件/渠道 id -- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：用于选择能力面的文案控制 -- `markdownCapable`：将渠道标记为支持 Markdown，以便出站格式化决策 -- `exposure.configured`：当设为 `false` 时，在已配置渠道列表能力面中隐藏该渠道 -- `exposure.setup`：当设为 `false` 时，在交互式设置/配置选择器中隐藏该渠道 -- `exposure.docs`：将渠道标记为内部/私有，以用于文档导航能力面 -- `showConfigured` / `showInSetup`：旧版别名，出于兼容性仍可接受；优先使用 `exposure` -- `quickstartAllowFrom`：让该渠道接入标准快速开始 `allowFrom` 流程 -- `forceAccountBinding`：即使只存在一个账户，也要求显式账户绑定 -- `preferSessionLookupForAnnounceTarget`：在解析公告目标时优先使用会话查找 +- `preferOver`：此目录条目应优先于的低优先级插件 / 渠道 id +- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择表面文案控制 +- `markdownCapable`：将该渠道标记为支持 Markdown，以便进行出站格式决策 +- `exposure.configured`：设为 `false` 时，在已配置渠道列表表面中隐藏该渠道 +- `exposure.setup`：设为 `false` 时，在交互式设置 / 配置选择器中隐藏该渠道 +- `exposure.docs`：将该渠道标记为内部 / 私有，用于文档导航表面 +- `showConfigured` / `showInSetup`：出于兼容性仍接受的旧版别名；优先使用 `exposure` +- `quickstartAllowFrom`：让该渠道选择加入标准快速开始 `allowFrom` 流程 +- `forceAccountBinding`：即使只有一个账户存在，也要求显式账户绑定 +- `preferSessionLookupForAnnounceTarget`：在解析 announce 目标时优先使用会话查找 -OpenClaw 还可以合并**外部渠道目录**（例如 MPM 注册表导出）。将一个 JSON 文件放到以下任一路径： +OpenClaw 还可以合并**外部渠道目录**（例如 MPM 注册表导出）。将 JSON 文件放到以下任一位置即可： - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（使用逗号/分号/`PATH` 分隔）。每个文件都应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧版别名。 +或者，将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（以逗号 / 分号 / `PATH` 分隔）。每个文件应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧版别名。 ## 上下文引擎插件 -上下文引擎插件拥有会话上下文的编排能力，包括摄取、组装和压缩。你可以通过 `api.registerContextEngine(id, factory)` 在插件中注册它们，然后通过 `plugins.slots.contextEngine` 选择活动引擎。 +上下文引擎插件拥有会话上下文编排，负责摄取、组装和压缩。通过 `api.registerContextEngine(id, factory)` 在你的插件中注册它们，然后使用 `plugins.slots.contextEngine` 选择活动引擎。 -当你的插件需要替换或扩展默认上下文流水线，而不只是添加 memory 搜索或钩子时，请使用此功能。 +当你的插件需要替换或扩展默认上下文管线，而不仅仅是添加 memory 搜索或钩子时，请使用这种方式。 ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1129,7 +1124,7 @@ export default function (api) { } ``` -如果你的引擎**不**拥有压缩算法，请保持 `compact()` 已实现，并显式委托它： +如果你的引擎**不**拥有压缩算法，请仍然实现 `compact()`，并显式委托它： ```ts import { @@ -1166,37 +1161,37 @@ export default function (api) { ## 添加新能力 -当插件需要当前 API 无法容纳的行为时，不要通过私有深入访问绕过插件系统。应添加缺失的能力。 +当插件需要当前 API 无法容纳的行为时，不要通过私有深入访问绕过插件系统。请添加缺失的能力。 推荐顺序： 1. 定义核心契约 - 明确哪些共享行为应由核心拥有：策略、回退、配置合并、生命周期、面向渠道的语义，以及运行时辅助工具形态。 -2. 添加类型化的插件注册/运行时能力面 - 使用最小但有用的类型化能力面来扩展 `OpenClawPluginApi` 和/或 `api.runtime`。 -3. 连接核心 + 渠道/功能消费者 - 渠道和功能插件应通过核心消费新能力，而不是直接导入某个厂商实现。 -4. 注册厂商实现 - 然后由厂商插件将其后端注册到该能力上。 + 决定哪些共享行为应由核心拥有：策略、回退、配置合并、生命周期、面向渠道的语义以及运行时辅助工具形态。 +2. 添加类型化的插件注册 / 运行时表面 + 以最小但有用的类型化能力表面扩展 `OpenClawPluginApi` 和 / 或 `api.runtime`。 +3. 接线核心 + 渠道 / 功能消费者 + 渠道和功能插件应通过核心消费这一新能力，而不是直接导入某个供应商实现。 +4. 注册供应商实现 + 然后由供应商插件针对该能力注册其后端。 5. 添加契约覆盖 - 添加测试，以便随着时间推移，所有权和注册形态仍保持明确。 + 添加测试，使归属和注册形态能长期保持明确。 -这就是 OpenClaw 如何在保持鲜明架构立场的同时，不会被硬编码到某一个提供商的世界观中。具体文件清单和完整示例请参阅[能力扩展手册](/zh-CN/plugins/architecture)。 +这就是 OpenClaw 如何在保持明确立场的同时，不会被硬编码进某个提供商的世界观。具体的文件检查清单和完整示例，请参见[能力扩展手册](/zh-CN/plugins/architecture)。 ### 能力检查清单 -当你添加一个新能力时，实现通常应同时覆盖这些能力面： +当你添加一个新能力时，实现通常应同时涉及以下表面： - `src//types.ts` 中的核心契约类型 -- `src//runtime.ts` 中的核心运行器/运行时辅助工具 -- `src/plugins/types.ts` 中的插件 API 注册能力面 +- `src//runtime.ts` 中的核心运行器 / 运行时辅助工具 +- `src/plugins/types.ts` 中的插件 API 注册表面 - `src/plugins/registry.ts` 中的插件注册表接线 -- 当功能/渠道插件需要消费它时，`src/plugins/runtime/*` 中的插件运行时暴露 -- `src/test-utils/plugin-registration.ts` 中的捕获/测试辅助工具 -- `src/plugins/contracts/registry.ts` 中的所有权/契约断言 -- `docs/` 中面向操作员/插件的文档 +- 当功能 / 渠道插件需要消费该能力时，位于 `src/plugins/runtime/*` 中的插件运行时暴露层 +- `src/test-utils/plugin-registration.ts` 中的捕获 / 测试辅助工具 +- `src/plugins/contracts/registry.ts` 中的归属 / 契约断言 +- `docs/` 中面向操作员 / 插件的文档 -如果其中某个能力面缺失，通常意味着该能力还没有被完全集成。 +如果这些表面中缺了某一个，通常说明这个能力还没有被完整集成。 ### 能力模板 @@ -1235,6 +1230,6 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); 这样规则就保持简单： - 核心拥有能力契约 + 编排 -- 厂商插件拥有厂商实现 -- 功能/渠道插件消费运行时辅助工具 -- 契约测试让所有权保持明确 +- 供应商插件拥有供应商实现 +- 功能 / 渠道插件消费运行时辅助工具 +- 契约测试让归属保持明确 diff --git a/docs/zh-CN/plugins/sdk-provider-plugins.md b/docs/zh-CN/plugins/sdk-provider-plugins.md index 253567026..d0f8afcc1 100644 --- a/docs/zh-CN/plugins/sdk-provider-plugins.md +++ b/docs/zh-CN/plugins/sdk-provider-plugins.md @@ -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 密钥认证和动态模型解析的提供商。 - 如果你之前没有构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基础包结构和清单设置。 + 如果你之前没有构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基本的软件包结构和清单设置。 - 提供商插件会把模型添加到 OpenClaw 的标准推理循环中。如果模型必须通过一个拥有线程、压缩或工具事件的原生智能体守护进程运行，请将该提供商与 [agent harness](/zh-CN/plugins/sdk-agent-harness) 配合使用，而不是把守护进程协议细节放进核心中。 + 提供商插件会将模型添加到 OpenClaw 的常规推理循环中。如果该模型必须通过一个原生智能体守护进程来运行，并由它负责线程、压缩或工具事件，请将该提供商与一个 [智能体 harness](/zh-CN/plugins/sdk-agent-harness) 搭配使用，而不是把守护进程协议细节放进核心中。 ## 演练 - + ```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 ", - "cliDescription": "Acme AI API key" + "cliDescription": "Acme AI API 密钥" } ], "configSchema": { @@ -89,12 +89,12 @@ x-i18n: ``` - 该清单声明了 `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` 字段是必需的。 - 一个最小可用的提供商需要 `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 `，并选择 `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，也仍然可以选择启用。 - 如果你的提供商接受任意模型 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` 会再次运行。 - + 大多数提供商只需要 `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` 导出提供商构建器以及新手引导/配置辅助函数 - 对于需要在每次推理调用前执行令牌交换的提供商： + 对于那些需要在每次推理调用之前进行令牌交换的提供商： ```typescript prepareRuntimeAuth: async (ctx) => { @@ -367,7 +367,7 @@ x-i18n: ``` - 对于需要自定义请求头或请求体修改的提供商： + 对于那些需要自定义请求头或请求体修改的提供商： ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -384,8 +384,8 @@ x-i18n: }, ``` - - 对于需要在通用 HTTP 或 WebSocket 传输上附加原生请求/会话请求头或元数据的提供商： + + 对于那些需要在通用 HTTP 或 WebSocket 传输上添加原生请求/会话头或元数据的提供商： ```typescript resolveTransportTurnState: (ctx) => ({ @@ -406,7 +406,7 @@ x-i18n: ``` - 对于公开用量/计费数据的提供商： + 对于那些暴露用量/计费数据的提供商： ```typescript resolveUsageAuth: async (ctx) => { @@ -421,73 +421,73 @@ x-i18n: - 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.` 配置 | - | 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)。 - 提供商插件除了文本推理之外，还可以注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和 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` 块才是预期契约。 @@ -654,7 +654,7 @@ clawhub package publish your-org/your-plugin ``` /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) — 钩子细节和内置示例 diff --git a/docs/zh-CN/tools/agent-send.md b/docs/zh-CN/tools/agent-send.md index 2191bf8d3..08cb94b51 100644 --- a/docs/zh-CN/tools/agent-send.md +++ b/docs/zh-CN/tools/agent-send.md @@ -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` 可在无需入站聊天消息的情况下，从命令行运行单个智能体轮次。可将其用于脚本化工作流、测试以及以编程方式进行发送。 ## 快速开始 - + ```bash openclaw agent --message "What is the weather today?" ``` @@ -31,24 +31,24 @@ x-i18n: ```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" ``` - + ```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 \` | 要发送的消息（必需） | -| `--to \` | 从目标派生会话键（电话号码、聊天 id） | -| `--agent \` | 指定已配置的智能体（使用其 `main` 会话） | -| `--session-id \` | 通过 id 复用现有会话 | -| `--local` | 强制使用本地嵌入式运行时（跳过 Gateway 网关） | -| `--deliver` | 将回复发送到聊天渠道 | -| `--channel \` | 投递渠道（whatsapp、telegram、discord、slack 等） | -| `--reply-to \` | 覆盖投递目标 | -| `--reply-channel \` | 覆盖投递渠道 | -| `--reply-account \` | 覆盖投递账号 id | -| `--thinking \` | 设置 thinking 级别（off、minimal、low、medium、high、xhigh） | -| `--verbose \` | 设置 verbose 级别 | -| `--timeout \` | 覆盖智能体超时时间 | -| `--json` | 输出结构化 JSON | +| `--message \` | 要发送的消息（必需） | +| `--to \` | 从目标（电话、聊天 id）派生会话键 | +| `--agent \` | 指定已配置的智能体（使用其 `main` 会话） | +| `--session-id \` | 按 id 复用现有会话 | +| `--local` | 强制使用本地嵌入式运行时（跳过 Gateway 网关） | +| `--deliver` | 将回复发送到聊天渠道 | +| `--channel \` | 发送渠道（whatsapp、telegram、discord、slack 等） | +| `--reply-to \` | 覆盖发送目标 | +| `--reply-channel \` | 覆盖发送渠道 | +| `--reply-account \` | 覆盖发送账户 id | +| `--thinking \` | 为所选模型配置设置思考级别 | +| `--verbose \` | 设置详细级别 | +| `--timeout \` | 覆盖智能体超时时间 | +| `--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" ``` diff --git a/docs/zh-CN/tools/slash-commands.md b/docs/zh-CN/tools/slash-commands.md index b508257a7..5d59e4608 100644 --- a/docs/zh-CN/tools/slash-commands.md +++ b/docs/zh-CN/tools/slash-commands.md @@ -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 聊天命令使用 `! `（`/bash ` 是它的别名）。 +命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。 +仅主机可用的 bash 聊天命令使用 `! `（`/bash ` 是别名）。 这里有两个相关系统： - **命令**：独立的 `/...` 消息。 - **指令**：`/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`）启用 `! ` 以运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` 允许列表）。 +- `commands.bash`（默认 `false`）启用 `! ` 来运行主机 shell 命令（`/bash ` 是别名；需要 `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 ` 和 `/session max-age ` 管理线程绑定过期时间。 -- `/think ` 设置思考级别。别名：`/thinking`、`/t`。 +- `/think ` 设置思考级别。可选项来自当前模型的提供商配置文件；常见级别有 `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= security= ask= node=` 显示或设置 exec 默认值。 - `/model [name|#|status]` 显示或设置模型。 -- `/models [provider] [page] [limit=|size=|all]` 列出提供商，或列出某个提供商的模型。 -- `/queue ` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及 `debounce:2s cap:25 drop:summarize` 之类的选项。 -- `/help` 显示简要帮助摘要。 +- `/models [provider] [page] [limit=|size=|all]` 列出提供商或某个提供商的模型。 +- `/queue ` 管理队列行为（`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 [input]` 按名称运行一个 skill。 - `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。 - `/approve ` 处理 exec 审批提示。 -- `/btw ` 在不改变未来会话上下文的情况下提出一个旁支问题。参见 [/tools/btw](/zh-CN/tools/btw)。 +- `/btw ` 在不改变未来会话上下文的情况下提出旁支问题。参见 [/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 ` 将当前 Discord 线程或 Telegram 话题/会话绑定到一个会话目标。 - `/unfocus` 移除当前绑定。 -- `/agents` 列出当前会话中绑定到线程的智能体。 -- `/kill ` 中止一个或所有正在运行的子智能体。 -- `/steer ` 向正在运行的子智能体发送引导。别名：`/tell`。 +- `/agents` 列出当前会话中线程绑定的智能体。 +- `/kill ` 中止一个或全部正在运行的子智能体。 +- `/steer ` 向正在运行的子智能体发送引导信息。别名：`/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 ` 运行主机 shell 命令。仅文本。别名：`! `。需要 `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 [duration]|disarm` 临时启用高风险手机节点命令。 - `/voice status|list [limit]|set ` 管理 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 [input]` 始终可作为通用入口点使用。 -- 当 skill/插件注册它们时，skills 也可能显示为直接命令，例如 `/prose`。 +- 当 skill/插件注册了它们时，Skills 也可能显示为直接命令，例如 `/prose`。 - 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 注意： -- 命令支持在命令与参数之间可选使用 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 -- `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。 -- 要查看完整的提供商使用量细分，请使用 `openclaw status --usage`。 +- 命令支持在命令与参数之间可选添加 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 +- `/new ` 接受模型别名、`provider/model`，或提供商名称（模糊匹配）；如果没有匹配项，则该文本会被视为消息正文。 +- 如需完整的提供商用量明细，请使用 `openclaw status --usage`。 - `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道的 `configWrites`。 - 在多账号渠道中，面向配置目标的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账号的 `configWrites`。 -- `/usage` 控制每次响应的使用量页脚；`/usage cost` 会根据 OpenClaw 会话日志输出本地成本摘要。 +- `/usage` 控制每次响应的使用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地成本摘要。 - `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。 -- `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包或 `clawhub:`。 -- `/plugins enable|disable` 会更新插件配置，并且可能提示你重启。 -- 仅 Discord 原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。 +- `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包，或 `clawhub:`。 +- `/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 [input]` 按名称运行一个 skill（当原生命令限制阻止按 skill 单独创建命令时，这很有用）。 +- 未授权的仅命令消息会被静默忽略，内联 `/...` 标记会被视为普通文本。 +- **skill 命令：** `user-invocable` 的 Skills 也会作为斜杠命令公开。名称会被清理为 `a-z0-9_`（最多 32 个字符）；冲突项会附加数字后缀（例如 `_2`）。 + - `/skill [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::discord:slash:` - Slack：`agent::slack:slash:`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置） - - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位到聊天会话） -- **`/stop`** 以当前活动聊天会话为目标，因此它可以中止当前运行。 -- **Slack：** `channels.slack.slashCommand` 仍然支持单个 `/openclaw` 风格命令。如果你启用了 `commands.native`，则必须为每个内置命令在 Slack 中创建一个斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式传递。 - - Slack 原生例外：请注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。 + - Telegram：`telegram:slash:`（通过 `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)。 diff --git a/docs/zh-CN/tools/thinking.md b/docs/zh-CN/tools/thinking.md index 49cf361e1..72c3a6e4d 100644 --- a/docs/zh-CN/tools/thinking.md +++ b/docs/zh-CN/tools/thinking.md @@ -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 `、`/think:` 或 `/thinking `。 +- 可在任何入站消息正文中使用内联指令：`/t `、`/think:` 或 `/thinking `。 - 级别（别名）：`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["/"].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 智能体）会将每次工具调用作为独立的仅元数据消息发回；如果可用，则前缀为 ` : `（路径/命令）。这些工具摘要会在每个工具启动时立即发送（独立气泡），而不是作为流式增量发送。 -- 工具失败摘要在普通模式下仍然可见，但原始错误详情后缀只有在详细模式为 `on` 或 `full` 时才会显示。 -- 当详细级别为 `full` 时，工具输出也会在完成后转发（独立气泡，并截断到安全长度）。如果你在运行过程中切换 `/verbose on|full|off`，后续工具气泡会遵循新的设置。 +- 当详细模式开启时，会输出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为独立的仅元数据消息发回；若可用，会以前缀 ` : ` 的形式显示（路径/命令）。这些工具摘要会在每个工具启动时立即发送（单独气泡），而不是作为流式增量发送。 +- 工具失败摘要在普通模式下仍然可见，但原始错误详情后缀会被隐藏，除非详细级别为 `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 ()`，其中解析出的默认值来自当前会话模型：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:` 仍然可用，并会更新同一个已存储的会话级别，因此聊天指令和选择器会保持同步。 +- 第一个选项始终是 `Default ()`，其中解析后的默认值来自当前活动会话模型的 provider thinking profile。 +- 选择器使用 Gateway 网关会话行返回的 `thinkingOptions`。浏览器 UI 不会维护自己的 provider 正则列表；模型特定级别集合由插件负责。 +- `/think:` 仍然有效，并会更新同一个已存储的会话级别，因此聊天指令与选择器保持同步。 + +## 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。