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

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-05 18:19:00 +00:00
parent 5a47bd28e6
commit 12bdc82edb
17 changed files with 3830 additions and 3848 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
docs/zh-CN/concepts/context.md
View File

@ -1,44 +1,44 @@
---
read_when:
- 你想了解 OpenClaw 中“上下文”的含义
- 你正在调试模型为什么“知道”某些内容（或为什么忘记了它）
- 你正在调试为什么模型“知道”某些内容（或忘记了它）
- 你想减少上下文开销（`/context`、`/status`、`/compact`）
summary: 上下文：模型能看到什么、它是如何构建的，以及如何检查它
summary: 上下文：模型会看到什么、它是如何构建的，以及如何检查它
title: 上下文
x-i18n:
generated_at: "2026-04-05T08:21:29Z"
generated_at: "2026-04-05T18:13:28Z"
model: gpt-5.4
provider: openai
source_hash: a75b4cd65bf6385d46265b9ce1643310bc99d220e35ec4b4924096bed3ca4aa0
source_hash: fe7dfe52cb1a64df229c8622feed1804df6c483a6243e0d2f309f6ff5c9fe521
source_path: concepts/context.md
workflow: 15
---
# 上下文
“上下文”是**OpenClaw 在一次运行中发送给模型的全部内容**。它受模型的**上下文窗口**（token 限制）约束。
“上下文”是 **OpenClaw 在一次运行中发送给模型的全部内容**。它受限于模型的 **上下文窗口**（token 限制）。
适合初学者的心智模型：
适合初学者的理解方式：
- **系统提示词**（由 OpenClaw 构建）：规则、工具、Skills 列表、时间 / 运行时信息，以及注入的工作区文件。
- **对话历史**：你在此会话中的消息 + 助手消息。
- **工具调用 / 结果 + 附件**：命令输出、文件读取、图像 / 音频等。
- **系统提示词**（由 OpenClaw 构建）：规则、工具、Skills 列表、时间/运行时信息，以及注入的工作区文件。
- **对话历史**：你在此会话中的消息，以及助手的消息。
- **工具调用/结果 + 附件**：命令输出、文件读取、图片/音频等。
上下文 _并不等同于_ “memory”：memory 可以存储到磁盘并在之后重新加载；上下文则是模型当前窗口中的内容。
上下文 _并不等同于_ “记忆”：记忆可以存储在磁盘上并在之后重新加载；上下文则是模型当前窗口中的内容。
## 快速开始（检查上下文）
- `/status` → 快速查看“我的窗口有多满？”以及会话设置。
- `/context list` → 查看注入了哪些内容 + 大致大小（每个文件 + 总计）。
- `/status` → 快速查看“我的窗口用了多少？”以及会话设置。
- `/context list` → 查看注入了什么 + 粗略大小（每个文件 + 总计）。
- `/context detail` → 更深入的细分：每个文件、每个工具 schema 的大小、每个 skill 条目的大小，以及系统提示词大小。
- `/usage tokens` → 在普通回复后附加每次回复的用量页脚。
- `/compact` → 将较早的历史总结为一条紧凑条目，以释放窗口空间。
另见：[Slash commands](/tools/slash-commands)、[Token use & costs](/reference/token-use)、[Compaction](/concepts/compaction)。
另见：[Slash commands](/zh-CN/tools/slash-commands)、[Token 用量与成本](/zh-CN/reference/token-use)、[压缩](/zh-CN/concepts/compaction)。
## 示例输出
具体值会因模型、提供商、工具策略以及你的工作区内容而异。
具体数值会因模型、提供商、工具策略以及你的工作区内容而异。
### `/context list`
@ -90,22 +90,22 @@ Top tools (schema size):
- 系统提示词（所有部分）。
- 对话历史。
- 工具调用 + 工具结果。
- 附件 / 转录内容（图像 / 音频 / 文件）。
- 压缩摘要和剪枝产物。
- 提供商“包装层”或隐藏头部（虽然不可见，仍会计入）。
- 附件/转录内容（图片/音频/文件）。
- 压缩摘要和裁剪产物。
- 提供商“包装层”或隐藏头信息（不可见，但仍会计入）。
## OpenClaw 如何构建系统提示词
系统提示词由 **OpenClaw 拥有**，并会在每次运行时重新构建。它包括：
系统提示词由 **OpenClaw 持有**，并会在每次运行时重新构建。它包括：
- 工具列表 + 简短说明。
- 工具列表 + 简短描述。
- Skills 列表（仅元数据；见下文）。
- 工作区位置。
- 时间（UTC + 如果已配置则包含换算后的用户时间）。
- 运行时元数据（主机 / OS / 模型 / thinking）。
- **Project Context** 下已注入的工作区 bootstrap 文件。
- 时间（UTC + 如果已配置则包含转换后的用户时区时间）。
- 运行时元数据（主机/OS/模型/思考设置）。
- 在 **Project Context** 下注入的工作区引导文件。
完整细分参见：[System Prompt](/concepts/system-prompt)。
完整细分请参见：[System Prompt](/zh-CN/concepts/system-prompt)。
## 注入的工作区文件（Project Context）
@ -119,62 +119,68 @@ Top tools (schema size):
- `HEARTBEAT.md`
- `BOOTSTRAP.md`（仅首次运行）
大文件会按文件使用 `agents.defaults.bootstrapMaxChars`（默认 `20000` 个字符）进行截断。OpenClaw 还会对所有文件的 bootstrap 注入总量施加上限 `agents.defaults.bootstrapTotalMaxChars`（默认 `150000` 个字符）。`/context` 会显示**原始大小与注入后大小**，以及是否发生了截断。
大型文件会按文件依据 `agents.defaults.bootstrapMaxChars`（默认 `20000` 个字符）进行截断。OpenClaw 还会通过 `agents.defaults.bootstrapTotalMaxChars`（默认 `150000` 个字符）对所有文件的总引导注入量施加上限。`/context` 会显示 **原始大小 vs 注入后大小**，以及是否发生了截断。
发生截断时，运行时可以在 Project Context 下方于提示词内注入一个警告块。可通过 `agents.defaults.bootstrapPromptTruncationWarning` 进行配置（`off`、`once`、`always`；默认 `once`）。
发生截断时，运行时可以在 Project Context 下方注入一个提示词内警告块。可通过 `agents.defaults.bootstrapPromptTruncationWarning` 进行配置（`off`、`once`、`always`；默认 `once`）。
## Skills：注入与按需加载
## Skills：默认注入与按需加载
系统提示词包含一个精简的 **Skills 列表**（名称 + 描述 + 位置）。这个列表会带来真实的开销。
系统提示词中包含一个紧凑的 **skills 列表**（名称 + 描述 + 位置）。这个列表会带来真实的上下文开销。
默认情况下不会包含 skill 指令本身。模型应当只在需要时 `read` 该 skill 的 `SKILL.md`。
Skill 指令默认 _不会_ 被包含进去。模型应当只在需要时才 `read` 该 skill 的 `SKILL.md`。
## Tools：有两类成本
## 工具：有两种成本
工具会通过两种方式影响上下文：
1. 系统提示词中的**工具列表文本**（你看到的 “Tooling”）。
2. **工具 schema**（JSON）。这些内容会发送给模型，以便它能够调用工具。即使你看不到它们的纯文本形式，它们仍会计入上下文。
1. 系统提示词中的 **工具列表文本**（也就是你看到的 “Tooling”）。
2. **工具 schemas**（JSON）。这些会发送给模型，以便它调用工具。即使你看不到它们的纯文本形式，它们也会计入上下文。
`/context detail` 会细分最大的工具 schema，以便你看到主要开销来自哪里。
`/context detail` 会拆分出最大的工具 schema，让你看清哪些部分占比最高。
## 命令、指令和“内联快捷方式”
## 命令、指令和“行内快捷方式”
Slash 命令由 Gateway 网关处理。这里有几种不同的行为：
Slash commands 由 Gateway 网关处理。这里有几种不同的行为：
- **独立命令**：如果一条消息只包含 `/...`，它会作为命令运行。
- **指令**：`/think`、`/verbose`、`/reasoning`、`/elevated`、`/model`、`/queue` 会在模型看到消息前被剥离。
- 只包含指令的消息会持久化会话设置。
- 普通消息中的内联指令会作为单条消息级提示生效。
- **内联快捷方式**（仅允许列表中的发件人）：普通消息中的某些 `/...` 标记可以立即执行（例如：“hey /status”），并会在模型看到剩余文本前被剥离。
- **独立命令**：一条只包含 `/...` 的消息会作为命令运行。
- **指令**：`/think`、`/verbose`、`/reasoning`、`/elevated`、`/model`、`/queue` 会在消息被模型看到之前被剥离。
- 仅包含指令的消息会持久化会话设置。
- 普通消息中的行内指令会作为单条消息级别的提示。
- **行内快捷方式**（仅限于白名单发送者）：普通消息中的某些 `/...` token 可以立即运行（例如：“hey /status”），并会在模型看到剩余文本之前被剥离。
详情参见：[Slash commands](/tools/slash-commands)。
详情请参见：[Slash commands](/zh-CN/tools/slash-commands)。
## 会话、压缩和剪枝（哪些内容会持久化）
## 会话、压缩和裁剪（哪些内容会持久化）
跨消息持久化的内容取决于所用机制：
跨消息持久化哪些内容，取决于所使用的机制：
- **普通历史** 会保留在会话转录中，直到按策略被压缩 / 剪枝。
- **普通历史** 会保留在会话转录中，直到根据策略被压缩/裁剪。
- **压缩** 会将摘要持久化到转录中，并保留最近的消息不变。
- **剪枝** 会从一次运行的**内存中**提示词移除旧的工具结果，但不会重写转录。
- **裁剪** 会从某次运行的 _内存中_ 提示词里移除旧的工具结果，但不会重写转录。
文档参见：[会话](/concepts/session)、[压缩](/concepts/compaction)、[会话剪枝](/concepts/session-pruning)。
文档：[Session](/zh-CN/concepts/session)、[压缩](/zh-CN/concepts/compaction)、[会话裁剪](/zh-CN/concepts/session-pruning)。
默认情况下，OpenClaw 使用内置的 `legacy` 上下文引擎进行组装和压缩。如果你安装了提供 `kind: "context-engine"` 的插件，并通过 `plugins.slots.contextEngine` 选择它，OpenClaw 就会将上下文组装、`/compact` 以及相关的子智能体上下文生命周期 hook 委托给该引擎。`ownsCompaction: false` 不会自动回退到 legacy 引擎；活动引擎仍必须正确实现 `compact()`。完整的可插拔接口、生命周期 hooks 和配置参见
[Context Engine](/concepts/context-engine)。
默认情况下，OpenClaw 使用内置的 `legacy` 上下文引擎进行组装和
压缩。如果你安装了一个提供 `kind: "context-engine"` 的插件，并通过
`plugins.slots.contextEngine` 选择它，OpenClaw 就会将上下文组装、
`/compact` 以及相关的子智能体上下文生命周期钩子委托给该
引擎处理。`ownsCompaction: false` 不会自动回退到 legacy
引擎；当前激活的引擎仍必须正确实现 `compact()`。完整的
可插拔接口、生命周期钩子和配置请参见
[Context Engine](/zh-CN/concepts/context-engine)。
## `/context` 实际报告了什么
## `/context` 实际报告的是什么
`/context` 在可用时会优先使用最新的**按运行构建**系统提示词报告：
在可用时，`/context` 会优先使用最新的 **按运行构建** 的系统提示词报告：
- `System prompt (run)` = 从上一次嵌入式（支持工具）运行中捕获，并持久化到会话存储中。
- `System prompt (estimate)` = 当不存在运行报告时按需即时计算（或者当通过不会生成该报告的 CLI 后端运行时计算）。
- `System prompt (run)` = 从最近一次嵌入式（支持工具）运行中捕获，并持久化到会话存储中的数据。
- `System prompt (estimate)` = 当还没有运行报告时，动态计算得出的估算值。
无论哪种方式，它都会报告大小和主要贡献项；它**不会**转储完整系统提示词或工具 schema。
无论哪种方式，它报告的都是大小和主要贡献项；它**不会**输出完整的系统提示词或工具 schema。
## 相关内容
- [Context Engine](/concepts/context-engine) — 通过插件进行自定义上下文注入
- [Compaction](/concepts/compaction) — 总结长对话
- [System Prompt](/concepts/system-prompt) — 系统提示词如何构建
- [Agent Loop](/concepts/agent-loop) — 完整的智能体执行循环
- [Context Engine](/zh-CN/concepts/context-engine) —— 通过插件实现自定义上下文注入
- [压缩](/zh-CN/concepts/compaction) —— 对长对话进行总结
- [System Prompt](/zh-CN/concepts/system-prompt) —— 系统提示词是如何构建的
- [Agent Loop](/zh-CN/concepts/agent-loop) —— 完整的智能体执行周期

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

@ -1,125 +1,125 @@
---
read_when:
- 你需要按提供商分类的模型设置参考
- 你想要模型提供商的示例配置或 CLI 新手引导命令
- 你需要按提供商区分的模型设置参考
- 你想查看模型提供商的示例配置或 CLI 新手引导命令
summary: 模型提供商概览，包含示例配置和 CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-04-05T17:48:13Z"
generated_at: "2026-04-05T18:14:49Z"
model: gpt-5.4
provider: openai
source_hash: bbe1b0cd1243804fcef3fc75ea1face72257d6e7c93ffb85c15766766193b490
source_hash: 24e6275b0bf137fa8143baa2a1d729439ecec6a0d7c0c14fed78c522f691476f
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`）。
- 如果你设置了 `agents.defaults.models`，它就会成为允许列表。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- CLI 助手：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover) 中。
- `models.providers.*.models[].contextWindow` 是模型原生元数据；`models.providers.*.models[].contextTokens` 是生效的运行时上限。
- `models.providers.*.models[].contextWindow` 是原生模型元数据；`models.providers.*.models[].contextTokens` 是生效的运行时上限。
- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前将该输出合并到 `models.providers` 中。
- 提供商清单可以声明 `providerAuthEnvVars`，这样通用的基于环境变量的凭证探测就不需要加载插件运行时。剩余的核心环境变量映射现在仅用于非插件/核心提供商，以及少数通用优先级场景，例如 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`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 和 `onModelSelected` 来管理提供商运行时行为。
- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录/工具行为差异、传输/缓存提示）。它与[公共能力模型](/zh-CN/plugins/architecture#public-capability-model)不同，后者描述的是插件注册了什么能力（文本推理、语音等）。
- 提供商清单可以声明 `providerAuthEnvVars`，这样基于通用环境变量的认证探测就不需要加载插件运行时。剩余的核心环境变量映射现在仅用于非插件/核心提供商，以及少数通用优先级场景，例如 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`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 以及 `onModelSelected` 来接管提供商运行时行为。
- 注意：提供商运行时 `capabilities` 是共享的运行器元数据（提供商家族、转录/工具差异、传输/缓存提示）。它与[公共能力模型](/zh-CN/plugins/architecture#public-capability-model)不同，后者描述的是插件注册了什么内容（文本推理、语音等）。
## 插件自有的提供商行为
现在，提供商插件可以拥有大多数提供商特定逻辑，而 OpenClaw 保持通用推理循环。
现在，提供商插件可以接管大多数提供商特定逻辑，而 OpenClaw 保留通用推理循环。
典型分工：
典型划分如下：
- `auth[].run` / `auth[].runNonInteractive`：提供商拥有用于 `openclaw onboard`、`openclaw models auth` 和无头设置的 onboarding/登录流程
- `wizard.setup` / `wizard.modelPicker`：提供商拥有认证选择标签、旧版别名、新手引导允许列表提示，以及新手引导/模型选择器中的设置项
- `auth[].run` / `auth[].runNonInteractive`：提供商负责 `openclaw onboard`、`openclaw models auth` 和无头设置的 onboarding/登录流程
- `wizard.setup` / `wizard.modelPicker`：提供商负责认证选项标签、旧别名、onboarding 允许列表提示，以及 onboarding/模型选择器中的设置项
- `catalog`：提供商会出现在 `models.providers` 中
- `normalizeModelId`：提供商会在查找或规范化之前标准化旧版/预览模型 id
- `normalizeTransport`：提供商会在通用模型组装之前标准化传输家族的 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后再检查其他具备 hook 能力的提供商插件，直到某个插件实际修改了传输
- `normalizeConfig`：提供商会在运行时使用前标准化 `models.providers.<id>` 配置；OpenClaw 会先检查匹配的提供商，然后再检查其他具备 hook 能力的提供商插件，直到某个插件实际修改了配置。如果没有提供商 hook 重写配置，内置的 Google 家族辅助逻辑仍会标准化受支持的 Google 提供商条目。
- `applyNativeStreamingUsageCompat`：提供商会对配置型提供商应用由端点驱动的原生流式使用量兼容性重写
- `resolveConfigApiKey`：提供商会为配置型提供商解析基于环境变量标记的认证，而无需强制加载完整运行时认证。`amazon-bedrock` 在这里也有内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时认证使用的是 AWS SDK 默认链。
- `resolveSyntheticAuth`：提供商可以在不持久化明文密钥的情况下暴露本地/自托管或其他基于配置的认证可用性
- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置文件占位符标记为低于环境变量/配置型认证的优先级
- `resolveDynamicModel`：提供商可以接受尚未出现在本地静态目录中的模型 id
- `normalizeModelId`：提供商会在查找或规范化之前规范旧版/预览模型 ID
- `normalizeTransport`：提供商会在通用模型组装之前规范传输族的 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，再检查其他支持此 Hook 的提供商插件，直到某个插件实际更改了传输
- `normalizeConfig`：提供商会在运行时使用前规范 `models.providers.<id>` 配置；OpenClaw 会先检查匹配的提供商，再检查其他支持此 Hook 的提供商插件，直到某个插件实际更改了配置。如果没有提供商 Hook 重写配置，内置的 Google 系列助手仍会规范受支持的 Google 提供商条目。
- `applyNativeStreamingUsageCompat`：提供商会对配置提供商应用由端点驱动的原生流式用量兼容重写
- `resolveConfigApiKey`：提供商会为配置提供商解析环境变量标记认证，而无需强制加载完整运行时认证。`amazon-bedrock` 在这里还内置了 AWS 环境变量标记解析器，尽管 Bedrock 运行时认证使用的是 AWS SDK 默认链。
- `resolveSyntheticAuth`：提供商可以暴露本地/自托管或其他基于配置的可用认证，而无需持久化明文密钥
- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置档占位符标记为优先级低于环境变量/配置支持的认证
- `resolveDynamicModel`：提供商可以接受尚未出现在本地静态目录中的模型 ID
- `prepareDynamicModel`：提供商在重试动态解析前需要刷新元数据
- `normalizeResolvedModel`：提供商需要进行传输或基础 URL 重写
- `contributeResolvedModelCompat`：即使模型通过其他兼容传输到达，提供商也可以为其厂商模型贡献兼容标记
- `capabilities`：提供商发布转录/工具/提供商家族的行为差异
- `normalizeToolSchemas`：提供商会在嵌入式运行器看到工具 schema 之前对其进行清理
- `inspectToolSchemas`：提供商会在标准化后暴露传输特定的 schema 警告
- `contributeResolvedModelCompat`：即使供应商模型是通过另一种兼容传输到达的，提供商也能为其贡献兼容标志
- `capabilities`：提供商发布转录/工具/提供商家族差异信息
- `normalizeToolSchemas`：提供商会在嵌入式运行器看到工具模式前对其进行清理
- `inspectToolSchemas`：提供商会在规范化后暴露特定于传输的模式警告
- `resolveReasoningOutputMode`：提供商选择原生或带标签的推理输出契约
- `prepareExtraParams`：提供商为每个模型的请求参数设置默认值或进行标准化
- `createStreamFn`：提供商用完全自定义的传输替换正常的流式路径
- `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`：提供商拥有二元开/关思考 UX
- `supportsXHighThinking`：提供商为选定模型启用 `xhigh`
- `resolveDefaultThinkingLevel`：提供商拥有某个模型家族的默认 `/think` 策略
- `applyConfigDefaults`：提供商在配置物化期间，根据认证模式、环境或模型家族应用提供商特定的全局默认值
- `isModernModelRef`：提供商拥有 live/smoke 首选模型匹配逻辑
- `resolveTransportTurnState`：提供商为每一轮提供原生传输请求头或元数据
- `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话请求头或会话冷却策略
- `createEmbeddingProvider`：当内存嵌入行为更适合归属提供商插件而不是核心嵌入分发器时，由提供商接管
- `formatApiKey`：提供商将已存储的认证配置档格式化为传输所期望的运行时 `apiKey` 字符串
- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足时，由提供商负责 OAuth 刷新
- `buildAuthDoctorHint`：当 OAuth 刷新失败时，由提供商追加修复指导
- `matchesContextOverflowError`：提供商识别通用启发式规则遗漏的、特定于提供商的上下文窗口溢出错误
- `classifyFailoverReason`：提供商将特定于提供商的原始传输/API 错误映射为回退原因，例如速率限制或过载
- `isCacheTtlEligible`：提供商决定哪些上游模型 ID 支持提示缓存 TTL
- `buildMissingAuthMessage`：提供商用特定于提供商的恢复提示替换通用认证存储错误
- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以在直接解析失败时返回供应商自有错误
- `augmentModelCatalog`：提供商在发现和配置合并之后追加合成/最终目录条目
- `isBinaryThinking`：提供商接管二元开/关 thinking 体验
- `supportsXHighThinking`：提供商让选定模型启用 `xhigh`
- `resolveDefaultThinkingLevel`：提供商接管某个模型家族的默认 `/think` 策略
- `applyConfigDefaults`：提供商根据认证模式、环境变量或模型家族，在配置具体化期间应用提供商特定的全局默认值
- `isModernModelRef`：提供商接管 live/smoke 首选模型匹配
- `prepareRuntimeAuth`：提供商将已配置凭证转换为短时效运行时令牌
- `resolveUsageAuth`：提供商为 `/usage` 及相关状态/报告界面解析使用量/配额凭证
- `fetchUsageSnapshot`：提供商拥有使用量端点的获取/解析逻辑，而核心仍拥有摘要外壳和格式化
- `onModelSelected`：提供商在选中模型后运行副作用，例如遥测或提供商自有的会话记账
- `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` 流家族进行代理推理注入、路由元数据转发和缓存 TTL 策略
- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude 思考转录提示、运行时令牌交换和使用量端点抓取
- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输标准化、支持 Codex 的缺失认证提示、Spark 抑制、合成 OpenAI/Codex 目录条目、思考/live-model 策略、使用量令牌别名标准化（`input` / `output` 以及 `prompt` / `completion` 家族）、用于原生 OpenAI/Codex 包装器的共享 `openai-responses-defaults` 流家族，以及提供商家族元数据
- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、bootstrap 重放清理、带标签的推理输出模式和现代模型匹配；Gemini CLI OAuth 还拥有认证配置文件令牌格式化、使用量令牌解析和用于使用量界面的配额端点抓取
- `moonshot`：共享传输、插件自有的思考载荷标准化
- `kilocode`：共享传输、插件自有请求头、推理载荷标准化、代理 Gemini thought-signature 清理和缓存 TTL 策略
- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元思考/live-model 策略，以及使用量认证 + 配额抓取；未知的 `glm-5*` id 会基于内置的 `glm-4.7` 模板进行合成
- `xai`：原生 Responses 传输标准化、针对 Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`，以及 xAI 特定的工具 schema / 推理载荷清理
- `mistral`：插件自有能力元数据
- `opencode` 和 `opencode-go`：插件自有能力元数据，外加代理 Gemini thought-signature 清理
- `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` 流家族注入代理推理、路由元数据转发，以及缓存 TTL 策略
- `github-copilot`：onboarding/设备登录、前向兼容模型回退、Claude-thinking 转录提示、运行时令牌交换，以及用量端点抓取
- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输规范化、具备 Codex 感知的缺失认证提示、Spark 抑制、合成 OpenAI/Codex 目录条目、thinking/live-model 策略、用量令牌别名规范化（`input` / `output` 和 `prompt` / `completion` 家族）、共享的 `openai-responses-defaults` 流家族用于原生 OpenAI/Codex 包装器，以及提供商家族元数据
- `google`：Gemini 3.1 前向兼容回退、原生 Gemini 重放验证、引导重放清理、带标签的推理输出模式，以及现代模型匹配
- `moonshot`：共享传输、插件自有的 thinking 负载规范化
- `kilocode`：共享传输、插件自有的请求头、推理负载规范化、代理 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 特有的工具模式 / 推理负载清理
- `mistral`：插件自有的能力元数据
- `opencode` 和 `opencode-go`：插件自有的能力元数据，外加代理 Gemini thought-signature 清理
- `byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅插件自有目录
- `qwen`：文本模型的插件自有目录，外加其多模态界面的共享 media-understanding 和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点以及内置的 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v`
- `minimax`：插件自有目录、混合 Anthropic/OpenAI 重放策略选择，以及使用量认证/快照逻辑
- `xiaomi`：插件自有目录以及使用量认证/快照逻辑
- `qwen`：文本模型的插件自有目录，以及用于其多模态界面的共享媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点和内置的 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v`
- `minimax`：插件自有目录、混合 Anthropic/OpenAI 重放策略选择，以及用量认证/快照逻辑
- `xiaomi`：插件自有目录，以及用量认证/快照逻辑
内置的 `openai` 插件现在同时拥有两个提供商 id：`openai` 和 `openai-codex`。
内置的 `openai` 插件现在同时拥有两个提供商 ID：`openai` 和 `openai-codex`。
以上涵盖了仍适用于 OpenClaw 正常传输方式的提供商。若提供商需要完全自定义的请求执行器，那就是另一个更深层的扩展接口了。
以上涵盖了仍适配 OpenClaw 常规传输方式的提供商。若某个提供商需要完全自定义的请求执行器，那就是另一层更深入的扩展接口了。
## API key 轮换
## API 密钥轮换
- 支持为选定提供商进行通用提供商轮换。
- 通过以下方式配置多个 key：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个 live 覆盖，优先级最高）
- 通过以下方式配置多个密钥：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个 live 覆盖，最高优先级）
- `<PROVIDER>_API_KEYS`（逗号或分号分隔列表）
- `<PROVIDER>_API_KEY`（主 key）
- `<PROVIDER>_API_KEY`（主密钥）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
- 对于 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 都失败时，返回最后一次尝试的最终错误。
- 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退值包含在内。
- 密钥选择顺序会保留优先级并对值去重。
- 仅在速率限制响应时，请求才会使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 或周期性用量限制消息）。
- 非速率限制失败会立即失败；不会尝试密钥轮换。
- 当所有候选密钥都失败时，会返回最后一次尝试的最终错误。
## 内置提供商（pi-ai 目录）
OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证并选择模型即可。
OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证并选择一个模型。
### OpenAI
@ -128,14 +128,14 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** `models.provide
- 可选轮换：`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）
- 可通过 `agents.defaults.models["openai/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- 默认传输是 `auto`（优先 WebSocket，回退到 SSE）
- 可通过 `agents.defaults.models["openai/<model>"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`）
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先级处理
- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射为 `api.openai.com` 上的 `service_tier=priority`
- 当你想显式指定层级，而不是使用共享 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用的 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示和 OpenAI 推理兼容载荷整形；代理路由则不会
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先处理
- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- 如果你想使用显式层级而不是共享的 `/fast` 开关，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归属请求头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用的 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示以及 OpenAI 推理兼容负载整形；代理路由则不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex
```json5
@ -151,9 +151,9 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** `models.provide
- 可选轮换：`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 key 和 OAuth 认证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 或 `standard_only`）
- 计费说明：对于 OpenClaw 中的 Anthropic，实际上的区分是**API key**或**带 Extra Usage 的 Claude 订阅**。Anthropic 于 **2026 年 4 月 4 日太平洋时间中午 12:00 / 英国夏令时晚上 8:00** 通知 OpenClaw 用户，**OpenClaw** 的 Claude 登录路径会被计为第三方 harness 使用，需要**单独于订阅计费**的 **Extra Usage**。我们的本地复现还表明，带有 OpenClaw 标识的提示字符串不会在 Anthropic SDK + API key 路径上复现。
- Anthropic setup-token 现已再次作为传统/手动 OpenClaw 路径提供。使用时请预期 Anthropic 已告知 OpenClaw 用户，该路径需要 **Extra Usage**。
- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 与 `standard_only`）
- 计费说明：对于 Anthropic 在 OpenClaw 中的使用，实际区分是 **API 密钥** 或 **带 Extra Usage 的 Claude 订阅**。Anthropic 在 **2026 年 4 月 4 日下午 12:00（PT）/ 晚上 8:00（BST）** 通知 OpenClaw 用户，**OpenClaw** 的 Claude 登录路径会被计为第三方工具链使用，因此需要单独于订阅计费的 **Extra Usage**。我们的本地复现还表明，Anthropic SDK + API 密钥路径不会复现 OpenClaw 标识提示字符串。
- Anthropic setup-token 现已再次作为旧版/手动 OpenClaw 路径提供。使用它时，请预期 Anthropic 已告知 OpenClaw 用户，此路径需要 **Extra Usage**。
```json5
{
@ -167,14 +167,14 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** `models.provide
- 认证：OAuth（ChatGPT）
- 示例模型：`openai-codex/gpt-5.4`
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
- 默认传输为 `auto`（优先 WebSocket，回退到 SSE）
- 可通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- 默认传输是 `auto`（优先 WebSocket，回退到 SSE）
- 可通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- `params.serviceTier` 也会转发到原生 Codex Responses 请求（`chatgpt.com/backend-api`）
- 隐藏的 OpenClaw 归因头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用的 OpenAI 兼容代理
- 隐藏的 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` 时，该模型仍然可用；是否可用取决于权益
- `openai-codex/gpt-5.4` 保持原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- 策略说明：OpenAI Codex OAuth 明确支持用于像 OpenClaw 这样的外部工具/工作流。
- 当 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 这类外部工具/工作流。
```json5
{
@ -197,7 +197,7 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** `models.provide
### 其他订阅式托管选项
- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商界面，以及 Alibaba DashScope 和 Coding Plan 端点映射
- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API key 访问
- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问
- [GLM Models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点
### OpenCode
@ -214,31 +214,21 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** `models.provide
}
```
### Google Gemini（API key）
### Google Gemini（API 密钥）
- 提供商：`google`
- 认证：`GEMINI_API_KEY`
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、后备 `GOOGLE_API_KEY`，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被标准化为 `google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范为 `google/gemini-3-flash-preview`
- CLI：`openclaw onboard --auth-choice gemini-api-key`
- 直接 Gemini 运行还接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会以 OpenClaw `cacheRead` 的形式显示
- 直接 Gemini 运行也接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会以 OpenClaw `cacheRead` 形式显示
### Google Vertex 和 Gemini CLI
### Google Vertex
- 提供商：`google-vertex`、`google-gemini-cli`
- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，使用第三方客户端后 Google 账号会受到限制。若你选择继续，请先查看 Google 条款并使用非关键账号。
- Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
- 先安装 Gemini CLI：
- `brew install gemini-cli`
- 或 `npm install -g @google/gemini-cli`
- 启用：`openclaw plugins enable google`
- 登录：`openclaw models auth login --provider google-gemini-cli --set-default`
- 默认模型：`google-gemini-cli/gemini-3.1-pro-preview`
- 注意：你**不需要**把 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的认证配置文件中。
- 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
- Gemini CLI JSON 回复会从 `response` 解析；使用量回退到 `stats`，其中 `stats.cached` 会被标准化为 OpenClaw `cacheRead`。
- 提供商：`google-vertex`
- 认证：gcloud ADC
- Gemini CLI JSON 回复从 `response` 解析；用量会回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
### Z.AI（GLM）
@ -246,43 +236,43 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** `models.provide
- 认证：`ZAI_API_KEY`
- 示例模型：`zai/glm-5`
- CLI：`openclaw onboard --auth-choice zai-api-key`
- 别名：`z.ai/*` 和 `z-ai/*` 会被标准化为 `zai/*`
- 别名：`z.ai/*` 和 `z-ai/*` 会被规范为 `zai/*`
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定界面
### Vercel AI Gateway
### Vercel AI Gateway 网关
- 提供商：`vercel-ai-gateway`
- 认证：`AI_GATEWAY_API_KEY`
- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6`
- CLI：`openclaw onboard --auth-choice ai-gateway-api-key`
### Kilo Gateway
### Kilo Gateway 网关
- 提供商：`kilocode`
- 认证：`KILOCODE_API_KEY`
- 示例模型：`kilocode/kilo/auto`
- CLI：`openclaw onboard --auth-choice kilocode-api-key`
- 基础 URL：`https://api.kilo.ai/api/gateway/`
- 静态后备目录内置 `kilocode/kilo/auto`；live `https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时目录。
- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 拥有，不是 OpenClaw 中硬编码的。
- 静态回退目录附带 `kilocode/kilo/auto`；live `https://api.kilo.ai/api/gateway/models` 发现可进一步扩展运行时目录。
- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 网关负责，不在 OpenClaw 中硬编码。
有关设置详情，请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。
设置详情请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。
### 其他内置提供商插件
- OpenRouter：`openrouter`（`OPENROUTER_API_KEY`）
- 示例模型：`openrouter/auto`
- 仅当请求实际指向 `openrouter.ai` 时，OpenClaw 才会应用 OpenRouter 文档中说明的应用归因头
- OpenRouter 特有的 Anthropic `cache_control` 标记同样仅对已验证的 OpenRouter 路由生效，不适用于任意代理 URL
- OpenRouter 仍然走代理式的 OpenAI 兼容路径，因此不会转发原生 OpenAI 专用的请求整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容载荷）
- 基于 Gemini 的 OpenRouter 引用仅保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和 bootstrap 重写仍然关闭
- Kilo Gateway：`kilocode`（`KILOCODE_API_KEY`）
- 仅当请求实际指向 `openrouter.ai` 时，OpenClaw 才会应用 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` 和其他不支持代理推理提示的模型会跳过代理推理注入
- MiniMax：`minimax`（API key）和 `minimax-portal`（OAuth）
- 认证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
- 基于 Gemini 的 Kilo 引用保留相同的代理 Gemini thought-signature 清理路径；`kilocode/kilo/auto` 及其他不支持代理推理提示的路径会跳过代理推理注入
- MiniMax：`minimax`（API 密钥）和 `minimax-portal`（OAuth）
- 认证：`MINIMAX_API_KEY` 用于 `minimax`；`MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` 用于 `minimax-portal`
- 示例模型：`minimax/MiniMax-M2.7` 或 `minimax-portal/MiniMax-M2.7`
- MiniMax onboarding/API key 设置会写入显式的 M2.7 模型定义，并包含 `input: ["text", "image"]`；在该提供商配置物化之前，内置提供商目录会将聊天引用保持为仅文本
- MiniMax onboarding/API 密钥设置会写入显式的 M2.7 模型定义，并带有 `input: ["text", "image"]`；在该提供商配置具体化之前，内置提供商目录会将聊天引用保持为仅文本
- Moonshot：`moonshot`（`MOONSHOT_API_KEY`）
- 示例模型：`moonshot/kimi-k2.5`
- Kimi Coding：`kimi`（`KIMI_API_KEY` 或 `KIMICODE_API_KEY`）
@ -300,15 +290,15 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** `models.provide
- Venice：`venice`（`VENICE_API_KEY`）
- Xiaomi：`xiaomi`（`XIAOMI_API_KEY`）
- 示例模型：`xiaomi/mimo-v2-flash`
- Vercel AI Gateway：`vercel-ai-gateway`（`AI_GATEWAY_API_KEY`）
- Vercel AI Gateway 网关：`vercel-ai-gateway`（`AI_GATEWAY_API_KEY`）
- Hugging Face Inference：`huggingface`（`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`）
- Cloudflare AI Gateway：`cloudflare-ai-gateway`（`CLOUDFLARE_AI_GATEWAY_API_KEY`）
- Cloudflare AI Gateway 网关：`cloudflare-ai-gateway`（`CLOUDFLARE_AI_GATEWAY_API_KEY`）
- Volcengine：`volcengine`（`VOLCANO_ENGINE_API_KEY`）
- 示例模型：`volcengine-plan/ark-code-latest`
- 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` 变体
- `tool_stream` 默认开启；将 `agents.defaults.models["xai/<model>"].params.tool_stream` 设为 `false` 可关闭
- Mistral：`mistral`（`MISTRAL_API_KEY`）
@ -316,28 +306,28 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** `models.provide
- 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 兼容基础 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)。
## 通过 `models.providers` 配置的提供商（自定义/基础 URL）
## 通过 `models.providers` 使用的提供商（自定义/基础 URL）
使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。
使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。
下方许多内置提供商插件已经发布了默认目录。
仅当你想覆盖默认基础 URL、请求头或模型列表时，才使用显式的 `models.providers.<id>` 条目。
下面许多内置提供商插件已经发布了默认目录。
仅当你想覆盖默认基础 URL、请求头或模型列表时，才使用显式 `models.providers.<id>` 条目。
### Moonshot AI（Kimi）
Moonshot 作为内置提供商插件提供。默认请使用内置提供商，只有在你需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
Moonshot 作为内置提供商插件提供。默认请使用内置提供商，仅当你需要覆盖基础 URL 或模型元数据时，才添加显式 `models.providers.moonshot` 条目：
- 提供商：`moonshot`
- 认证：`MOONSHOT_API_KEY`
- 示例模型：`moonshot/kimi-k2.5`
- CLI：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`
Kimi K2 模型 id：
Kimi K2 模型 ID：
[//]: # "moonshot-kimi-k2-model-refs:start"
@ -384,13 +374,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
}
```
旧版 `kimi/k2p5` 仍然接受，作为兼容模型 id。
旧版 `kimi/k2p5` 仍然作为兼容模型 ID 被接受。
### Volcano Engine（Doubao）
Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型访问。
Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型的访问。
- 提供商：`volcengine`（编码：`volcengine-plan`）
- 提供商：`volcengine`（编程：`volcengine-plan`）
- 认证：`VOLCANO_ENGINE_API_KEY`
- 示例模型：`volcengine-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice volcengine-api-key`
@ -403,9 +393,9 @@ Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型访
}
```
新手引导默认使用编码界面，但通用 `volcengine/*` 目录也会同时注册。
onboarding 默认使用编程界面，但同时也会注册通用 `volcengine/*` 目录。
在 onboarding/configure 模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤目录，而不是显示一个空的提供商范围选择器。
在 onboarding/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商范围选择器。
可用模型：
@ -415,7 +405,7 @@ Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型访
- `volcengine/glm-4-7-251222`（GLM 4.7）
- `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K）
编码模型（`volcengine-plan`）：
编程模型（`volcengine-plan`）：
- `volcengine-plan/ark-code-latest`
- `volcengine-plan/doubao-seed-code`
@ -425,9 +415,9 @@ Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型访
### BytePlus（国际版）
BytePlus ARK 为国际用户提供与 Volcano Engine 相同的模型访问。
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。
- 提供商：`byteplus`（编码：`byteplus-plan`）
- 提供商：`byteplus`（编程：`byteplus-plan`）
- 认证：`BYTEPLUS_API_KEY`
- 示例模型：`byteplus-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
@ -440,9 +430,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同的模型访问。
}
```
新手引导默认使用编码界面，但通用 `byteplus/*` 目录也会同时注册。
onboarding 默认使用编程界面，但同时也会注册通用 `byteplus/*` 目录。
在 onboarding/configure 模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤目录，而不是显示一个空的提供商范围选择器。
在 onboarding/配置模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商范围选择器。
可用模型：
@ -450,7 +440,7 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同的模型访问。
- `byteplus/kimi-k2-5-260127`（Kimi K2.5）
- `byteplus/glm-4-7-251222`（GLM 4.7）
编码模型（`byteplus-plan`）：
编程模型（`byteplus-plan`）：
- `byteplus-plan/ark-code-latest`
- `byteplus-plan/doubao-seed-code`
@ -490,22 +480,22 @@ Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型：
MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- 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`
- 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_API_KEY` 用于 `minimax`；`MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` 用于 `minimax-portal`
有关设置详情、模型选项和配置片段，请参见 [/providers/minimax](/zh-CN/providers/minimax)。
设置详情、模型选项和配置片段请参见 [/providers/minimax](/zh-CN/providers/minimax)。
在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认关闭 thinking，除非你显式设置它，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认禁用 thinking，除非你显式设置它；而 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
插件自有能力划分：
- 文本/聊天默认仍使用 `minimax/MiniMax-M2.7`
- 文本/聊天默认保持在 `minimax/MiniMax-M2.7`
- 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01`
- 图像理解在两条 MiniMax 认证路径上都使用插件自有的 `MiniMax-VL-01`
- 网页搜索保持在提供商 id `minimax`
- 图像理解在两个 MiniMax 认证路径上都使用插件自有的 `MiniMax-VL-01`
- Web 搜索保持在提供商 ID `minimax`
### Ollama
@ -529,7 +519,7 @@ ollama pull llama3.3
}
```
当你使用 `OLLAMA_API_KEY` 选择加入时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。有关 onboarding、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。
当你通过 `OLLAMA_API_KEY` 选择启用时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到，内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。关于 onboarding、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。
### vLLM
@ -539,13 +529,13 @@ vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容
- 认证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:8000/v1`
要在本地选择加入自动发现（如果你的服务器不强制认证，任意值都可以）：
要选择启用本地自动发现（如果你的服务器不强制认证，任意值都可以）：
```bash
export VLLM_API_KEY="vllm-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的其中一个 id）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -559,19 +549,19 @@ export VLLM_API_KEY="vllm-local"
### SGLang
SGLang 作为内置提供商插件提供，用于高性能自托管 OpenAI 兼容服务器：
SGLang 作为内置提供商插件提供，用于高速自托管的 OpenAI 兼容服务器：
- 提供商：`sglang`
- 认证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:30000/v1`
要在本地选择加入自动发现（如果你的服务器不强制认证，任意值都可以）：
要选择启用本地自动发现（如果你的服务器不强制认证，任意值都可以）：
```bash
export SGLANG_API_KEY="sglang-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的其中一个 id）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -620,18 +610,18 @@ 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"`（任何非空 `baseUrl` 且主机不是 `api.openai.com`），OpenClaw 会强制 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
- 代理式 OpenAI 兼容路由也会跳过原生 OpenAI 专用请求整形：没有 `service_tier`，没有 Responses `store`，没有提示缓存提示，没有 OpenAI 推理兼容载荷整形，也没有隐藏的 OpenClaw 归因头。
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（其会解析为 `api.openai.com`）。
- 出于安全考虑，即使显式设置 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。
- 建议：设置与你的代理/模型限制匹配的显式值。
- 对于非原生端点上的 `api: "openai-completions"`（任意非空 `baseUrl`，且其主机不是 `api.openai.com`），OpenClaw 会强制设定 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
- 代理式 OpenAI 兼容路由也会跳过原生 OpenAI 专属请求整形：没有 `service_tier`，没有 Responses `store`，没有提示缓存提示，没有 OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归属请求头。
- 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认 OpenAI 行为（解析到 `api.openai.com`）。
- 为了安全，在非原生 `openai-completions` 端点上，显式 `compat.supportsDeveloperRole: true` 仍会被覆盖。
## CLI 示例
@ -641,7 +631,7 @@ openclaw models set opencode/claude-opus-4-6
openclaw models list
```
另见：[/gateway/configuration](/zh-CN/gateway/configuration) 查看完整配置示例。
另请参见：[/gateway/configuration](/zh-CN/gateway/configuration) 了解完整配置示例。
## 相关内容

289
docs/zh-CN/gateway/cli-backends.md
View File

@ -1,289 +0,0 @@
---
read_when:
- 你希望在 API 提供商失败时有一个可靠的回退方案
- 你正在运行 Codex CLI 或其他本地 AI CLI，并希望复用它们
- 你想了解用于 CLI 后端工具访问的 MCP loopback 桥接
summary: CLI 后端：带可选 MCP 工具桥接的本地 AI CLI 回退方案
title: CLI 后端
x-i18n:
generated_at: "2026-04-05T17:47:31Z"
model: gpt-5.4
provider: openai
source_hash: fe30bb4d5f51adcda53bf69a4f88e27832e78630ed5bfd8a33a66b6412b66f2d
source_path: gateway/cli-backends.md
workflow: 15
---
# CLI 后端（回退运行时）
当 API 提供商宕机、受到速率限制或暂时行为异常时，OpenClaw 可以运行**本地 AI CLI** 作为**纯文本回退**。这是一个有意保守的设计：
- **OpenClaw 工具不会被直接注入**，但设置了 `bundleMcp: true` 的后端
可以通过 loopback MCP 桥接接收 Gateway 网关工具。
- 对支持该能力的 CLI 提供 **JSONL 分块流式传输**。
- **支持会话**（因此后续轮次能保持连贯）。
- 如果 CLI 接受图像路径，**图像可以透传**。
这被设计为一个**安全网**，而不是主要路径。当你希望在不依赖外部 API 的情况下获得“始终可用”的文本回复时，可以使用它。
如果你想要完整的封装运行时，包括 ACP 会话控制、后台任务、
线程 / 对话绑定以及持久化的外部编码会话，请改用
[ACP 智能体](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。
## 适合初学者的快速开始
你可以**无需任何配置**使用 Codex CLI（内置 OpenAI 插件
会注册一个默认后端）：
```bash
openclaw agent --message "hi" --model codex-cli/gpt-5.4
```
如果你的 Gateway 网关运行在 launchd / systemd 下，并且 PATH 很精简，只需添加
命令路径：
```json5
{
agents: {
defaults: {
cliBackends: {
"codex-cli": {
command: "/opt/homebrew/bin/codex",
},
},
},
},
}
```
就是这样。除了 CLI 本身之外，不需要密钥，也不需要额外的认证配置。
如果你在 Gateway 网关主机上将某个内置 CLI 后端作为**主要消息提供商**使用，OpenClaw 现在会在你的配置
明确在模型引用或
`agents.defaults.cliBackends` 下引用该后端时，自动加载其所属的内置插件。
## 作为回退使用
将 CLI 后端添加到你的回退列表中，这样它只会在主模型失败时运行：
```json5
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["codex-cli/gpt-5.4"],
},
models: {
"anthropic/claude-opus-4-6": { alias: "Opus" },
"codex-cli/gpt-5.4": {},
},
},
},
}
```
说明：
- 如果你使用 `agents.defaults.models`（允许列表），你也必须将 CLI 后端模型包含在其中。
- 如果主提供商失败（认证、速率限制、超时），OpenClaw 会
接着尝试 CLI 后端。
## 配置概览
所有 CLI 后端都位于：
```
agents.defaults.cliBackends
```
每个条目以**提供商 ID** 为键（例如 `codex-cli`、`my-cli`）。
该提供商 ID 会成为你的模型引用左侧部分：
```
<provider>/<model>
```
### 配置示例
```json5
{
agents: {
defaults: {
cliBackends: {
"codex-cli": {
command: "/opt/homebrew/bin/codex",
},
"my-cli": {
command: "my-cli",
args: ["--json"],
output: "json",
input: "arg",
modelArg: "--model",
modelAliases: {
"claude-opus-4-6": "opus",
"claude-sonnet-4-6": "sonnet",
},
sessionArg: "--session",
sessionMode: "existing",
sessionIdFields: ["session_id", "conversation_id"],
systemPromptArg: "--system",
systemPromptWhen: "first",
imageArg: "--image",
imageMode: "repeat",
serialize: true,
},
},
},
},
}
```
## 工作原理
1. 根据提供商前缀（`codex-cli/...`）**选择后端**。
2. 使用相同的 OpenClaw 提示词和工作区上下文**构建系统提示词**。
3. 如果支持，会使用会话 ID **执行 CLI**，以保持历史一致。
4. **解析输出**（JSON 或纯文本）并返回最终文本。
5. 按后端**持久化会话 ID**，以便后续轮次复用相同的 CLI 会话。
<Warning>
内置 Anthropic `claude-cli` 后端已被移除，因为 Anthropic 的
OpenClaw 计费边界发生了变化。OpenClaw 仍然支持通用 CLI
后端，但 Anthropic API 流量应直接使用 Anthropic 提供商，
而不是已移除的本地 Claude CLI 路径。
</Warning>
## 会话
- 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或
`sessionArgs`（占位符为 `{sessionId}`），用于需要将该 ID 插入
多个标志的情况。
- 如果 CLI 使用带有不同标志的**恢复子命令**，请设置
`resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput`
（用于非 JSON 恢复）。
- `sessionMode`：
- `always`：始终发送会话 ID（若未存储则生成新的 UUID）。
- `existing`：仅当之前已存储会话 ID 时才发送。
- `none`：从不发送会话 ID。
串行化说明：
- `serialize: true` 会保持同一通道中的运行按顺序执行。
- 大多数 CLI 会在一个提供商通道上串行执行。
- 当后端认证状态发生变化时，包括重新登录、令牌轮换或认证配置文件凭证变化，OpenClaw 会丢弃已存储的 CLI 会话复用状态。
## 图像（透传）
如果你的 CLI 接受图像路径，请设置 `imageArg`：
```json5
imageArg: "--image",
imageMode: "repeat"
```
OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，这些
路径会作为 CLI 参数传递。如果缺少 `imageArg`，OpenClaw 会将
文件路径附加到提示词中（路径注入）；这对于那些能从普通路径自动加载本地文件的 CLI 来说已经足够。
## 输入 / 输出
- `output: "json"`（默认）会尝试解析 JSON 并提取文本 + 会话 ID。
- 对于 Gemini CLI JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从
`stats` 读取用量。
- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及存在时的会话
标识符。
- `output: "text"` 会将 stdout 视为最终响应。
输入模式：
- `input: "arg"`（默认）会将提示词作为最后一个 CLI 参数传递。
- `input: "stdin"` 会通过 stdin 发送提示词。
- 如果提示词很长且设置了 `maxPromptArgChars`，则会改用 stdin。
## 默认值（插件所有）
内置 OpenAI 插件也会为 `codex-cli` 注册一个默认值：
- `command: "codex"`
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
- `resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
- `output: "jsonl"`
- `resumeOutput: "text"`
- `modelArg: "--model"`
- `imageArg: "--image"`
- `sessionMode: "existing"`
内置 Google 插件也会为 `google-gemini-cli` 注册一个默认值：
- `command: "gemini"`
- `args: ["--prompt", "--output-format", "json"]`
- `resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]`
- `modelArg: "--model"`
- `sessionMode: "existing"`
- `sessionIdFields: ["session_id", "sessionId"]`
前提条件：本地 Gemini CLI 必须已安装，并可在
`PATH` 中通过 `gemini` 使用（`brew install gemini-cli` 或
`npm install -g @google/gemini-cli`）。
Gemini CLI JSON 说明：
- 回复文本从 JSON `response` 字段读取。
- 当 `usage` 缺失或为空时，用量会回退到 `stats`。
- `stats.cached` 会被标准化为 OpenClaw `cacheRead`。
- 如果 `stats.input` 缺失，OpenClaw 会通过
`stats.input_tokens - stats.cached` 推导输入令牌数。
仅在需要时覆盖（常见情况：使用绝对 `command` 路径）。
## 插件所有的默认值
CLI 后端默认值现在是插件表面的一部分：
- 插件通过 `api.registerCliBackend(...)` 注册它们。
- 后端 `id` 会成为模型引用中的提供商前缀。
- `agents.defaults.cliBackends.<id>` 中的用户配置仍会覆盖插件默认值。
- 后端特定的配置清理仍通过可选的
`normalizeConfig` hook 由插件自身负责。
## 内置 MCP 叠加层
CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置
`bundleMcp: true` 选择接收自动生成的 MCP 配置叠加层。
当前内置行为：
- `codex-cli`：无内置 MCP 叠加层
- `google-gemini-cli`：无内置 MCP 叠加层
启用内置 MCP 时，OpenClaw 会：
- 启动一个 loopback HTTP MCP 服务器，将 Gateway 网关工具暴露给 CLI 进程
- 使用每会话令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行认证
- 将工具访问范围限定在当前会话、账户和渠道上下文内
- 为当前工作区加载已启用的内置 MCP 服务器
- 将它们与任何现有的后端 `--mcp-config` 合并
- 重写 CLI 参数以传递 `--strict-mcp-config --mcp-config <generated-file>`
如果没有启用任何 MCP 服务器，只要后端选择了内置 MCP，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。
## 限制
- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用直接注入
CLI 后端协议。只有当后端选择
`bundleMcp: true` 时，后端才能看到 Gateway 网关工具。
- **流式传输取决于后端。** 某些后端会流式输出 JSONL；另一些则会
缓冲到退出时再输出。
- **结构化输出**取决于 CLI 的 JSON 格式。
- **Codex CLI 会话**通过文本输出恢复（不是 JSONL），其结构性
不如初始的 `--json` 运行。OpenClaw 会话仍然可以
正常工作。
## 故障排除
- **找不到 CLI**：将 `command` 设置为完整路径。
- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。
- **没有会话连续性**：确保已设置 `sessionArg` 且 `sessionMode` 不是
`none`（Codex CLI 当前无法使用 JSON 输出进行恢复）。
- **图像被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。

1128
docs/zh-CN/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

359
docs/zh-CN/gateway/doctor.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 添加或修改 doctor 迁移时
- 引入破坏性配置变更时
- 添加或修改 Doctor 迁移
- 引入破坏性配置更改
summary: Doctor 命令：健康检查、配置迁移和修复步骤
title: Doctor
x-i18n:
generated_at: "2026-04-05T17:48:14Z"
generated_at: "2026-04-05T18:14:18Z"
model: gpt-5.4
provider: openai
source_hash: f20637d373c3b1be7c4a3d5424228908b5639cfded8ad5acb9c29f882d0f8d2b
source_hash: 6c0a15c522994552a1eef39206bed71fc5bf45746776372f24f31c101bfbd411
source_path: gateway/doctor.md
workflow: 15
---
@ -35,7 +35,7 @@ openclaw doctor --yes
openclaw doctor --repair
```
无需提示即可应用推荐修复（在安全情况下执行修复 + 重启）。
应用推荐的修复而不提示（在安全的情况下执行修复 + 重启）。
```bash
openclaw doctor --repair --force
@ -47,16 +47,16 @@ openclaw doctor --repair --force
openclaw doctor --non-interactive
```
无提示运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。会跳过需要人工确认的重启/服务/沙箱操作。
在无提示模式下运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。
检测到旧版状态迁移时会自动运行。
```bash
openclaw doctor --deep
```
扫描系统服务以查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。
扫描系统服务以查找额外的 Gateway 网关安装（`launchd`/`systemd`/`schtasks`）。
如果你想在写入前先检查变更，请先打开配置文件：
如果你想在写入前先查看更改，请先打开配置文件：
```bash
cat ~/.openclaw/openclaw.json
@ -64,67 +64,67 @@ cat ~/.openclaw/openclaw.json
## 它会做什么（摘要）
- 针对 git 安装的可选预检更新（仅交互模式）。
- 为 git 安装提供可选的预检更新（仅交互模式）。
- UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。
- 健康检查 + 重启提示。
- Skills 状态摘要（可用/缺失/被阻止）和插件状态。
- 旧版值的配置规范化。
- 将旧版扁平 `talk.*` 字段迁移为 `talk.provider` + `talk.providers.<provider>` 的 Talk 配置迁移。
- Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。
- 旧值的配置规范化。
- 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.<provider>` 的 Talk 配置迁移。
- 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪情况的浏览器迁移检查。
- OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。
- OpenAI Codex OAuth 配置档案的 OAuth TLS 前置条件检查。
- 旧版磁盘状态迁移（sessions/agent 目录/WhatsApp 凭证）。
- 旧版插件清单 contract 键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
- OpenAI Codex OAuth 配置的 OAuth TLS 前置条件检查。
- 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。
- 旧版插件清单契约键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook 回退任务）。
- 会话锁文件检查和过时锁清理。
- 状态完整性和权限检查（sessions、transcripts、state 目录）。
- 本地运行时的配置文件权限检查（chmod 600）。
- 模型凭证健康检查：检查 OAuth 过期情况，可刷新即将过期的 token，并报告 auth-profile 冷却/禁用状态。
- 检测额外的工作区目录（`~/openclaw`）。
- 启用沙箱隔离时的沙箱镜像修复。
- 会话锁文件检查和过期锁清理。
- 状态完整性和权限检查（会话、转录、状态目录）。
- 本地运行时的配置文件权限检查（`chmod 600`）。
- 模型认证健康状况：检查 OAuth 过期情况，可刷新即将过期的令牌，并报告 auth-profile 的冷却/禁用状态。
- 检测额外工作区目录（`~/openclaw`）。
- 在启用沙箱隔离时修复沙箱镜像。
- 旧版服务迁移和额外 Gateway 网关检测。
- Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。
- Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
- Gateway 网关运行时检查（服务已安装但未运行；缓存的 `launchd` 标签）。
- 渠道状态警告（从正在运行的 Gateway 网关探测）。
- Supervisor 配置审计（launchd/systemd/schtasks）及可选修复。
- Supervisor 配置审计（`launchd`/`systemd`/`schtasks`），并可选择修复。
- Gateway 网关运行时最佳实践检查（Node 与 Bun、版本管理器路径）。
- Gateway 网关端口冲突诊断（默认 `18789`）。
- 开放私信策略的安全警告。
- 本地 token 模式的 Gateway 网关认证检查（在没有 token 来源时提供生成 token；不会覆盖 token SecretRef 配置）。
- Linux 上的 systemd linger 检查。
- 工作区 bootstrap 文件大小检查（上下文文件的截断/接近限制警告）。
- 针对开放私信策略的安全警告。
- 本地令牌模式下的 Gateway 网关认证检查（当没有令牌来源时提供生成令牌；不会覆盖令牌 SecretRef 配置）。
- Linux 上的 `systemd linger` 检查。
- 工作区引导文件大小检查（上下文文件的截断/接近限制警告）。
- Shell 补全状态检查和自动安装/升级。
- 记忆搜索 embedding 提供商就绪情况检查（本地模型、远程 API 密钥或 QMD 二进制）。
- 源码安装检查（pnpm workspace 不匹配、缺失 UI 资源、缺失 tsx 二进制）。
- 记忆搜索嵌入提供商就绪检查（本地模型、远程 API 密钥或 `QMD` 二进制）。
- 源码安装检查（`pnpm` 工作区不匹配、缺失 UI 资源、缺失 `tsx` 二进制）。
- 写入更新后的配置 + 向导元数据。
## 详细行为与原理
## 详细行为和原因说明
### 0）可选更新（git 安装）
如果这是一个 git checkout，且 doctor 在交互模式下运行，它会先提供在运行 doctor 之前进行更新（fetch/rebase/build）的选项。
如果这是一个 git 检出副本，并且 doctor 以交互模式运行，它会在运行 doctor 之前提供更新选项（fetch/rebase/build）。
### 1）配置规范化
如果配置中包含旧版值形态（例如没有渠道特定覆盖的 `messages.ackReaction`），doctor 会将其规范化为当前 schema。
如果配置包含旧版值结构（例如 `messages.ackReaction` 没有特定于渠道的覆盖），doctor 会将其规范化为当前 schema。
这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置是
`talk.provider` + `talk.providers.<provider>`。Doctor 会将旧的
`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
`talk.apiKey` 形态重写到提供商映射中。
`talk.apiKey` 结构重写到提供商映射中。
### 2）旧版配置键迁移
当配置中包含已弃用键时，其他命令会拒绝运行，并要求你运行
当配置包含已弃用键时，其他命令会拒绝运行，并要求你执行
`openclaw doctor`。
Doctor 将会：
Doctor 会：
- 解释发现了哪些旧版键。
- 说明发现了哪些旧版键。
- 显示它应用的迁移。
- 用更新后的 schema 重写 `~/.openclaw/openclaw.json`。
- 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。
当 Gateway 网关在启动时检测到旧版配置格式，也会自动运行 doctor 迁移，因此无需手动干预即可修复过时配置。
当 Gateway 网关在启动时检测到旧版配置格式，它也会自动运行 doctor 迁移，因此过时配置无需手动干预即可修复。
Cron 任务存储迁移由 `openclaw doctor --fix` 处理。
当前迁移包括：
@ -149,275 +149,330 @@ Cron 任务存储迁移由 `openclaw doctor --fix` 处理。
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold`
→ `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- 对于具有命名 `accounts` 但仍保留单账户顶层渠道值的渠道，将这些账户范围的值移动到为该渠道选定的提升账户中（大多数渠道使用 `accounts.default`；Matrix 可以保留现有的匹配命名/默认目标）
- 对于具有命名 `accounts`、但仍保留单账户顶层渠道值的渠道，将这些账户范围的值移动到为该渠道选择的提升账户中（大多数渠道使用 `accounts.default`；Matrix 可以保留现有匹配的命名/默认目标）
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents）
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
→ `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- 移除 `browser.relayBindHost`（旧版扩展 relay 设置）
- 删除 `browser.relayBindHost`（旧版扩展 relay 设置）
Doctor 警告还包括多账户渠道的默认账户指导：
Doctor 警告还包括多账户渠道的默认账户指引：
- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有 `channels.<channel>.defaultAccount` 或 `accounts.default`，doctor 会警告回退路由可能选中意外的账户。
- 如果 `channels.<channel>.defaultAccount` 被设置为未知账户 ID，doctor 会发出警告并列出已配置的账户 ID。
- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有设置 `channels.<channel>.defaultAccount` 或 `accounts.default`，doctor 会警告回退路由可能会选中意外的账户。
- 如果 `channels.<channel>.defaultAccount` 设置为未知账户 ID，doctor 会发出警告并列出已配置的账户 ID。
### 2b）OpenCode 提供商覆盖
如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，
它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。
这可能会强制模型走错误的 API，或将成本归零。Doctor 会发出警告，以便你移除该覆盖并恢复按模型的 API 路由 + 成本。
这可能会把模型强制路由到错误的 API，或将成本清零。Doctor 会发出警告，以便你移除覆盖并恢复按模型进行的 API 路由 + 成本设置。
### 2c）浏览器迁移和 Chrome MCP 就绪情况
如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型：
如果你的浏览器配置仍然指向已移除的 Chrome 扩展路径，doctor
会将其规范化为当前基于主机本地的 Chrome MCP 附加模型：
- `browser.profiles.*.driver: "extension"` 会变为 `"existing-session"`
- `browser.profiles.*.driver: "extension"` 变为 `"existing-session"`
- `browser.relayBindHost` 会被移除
当你使用 `defaultProfile: "user"` 或已配置的 `existing-session` 配置档案时，doctor 还会审计主机本地 Chrome MCP 路径：
当你使用 `defaultProfile:
"user"` 或已配置的 `existing-session` 配置文件时，doctor 还会审计主机本地的 Chrome MCP 路径：
- 检查 Google Chrome 是否已安装在同一主机上，用于默认自动连接配置档案
- 检查检测到的 Chrome 版本，并在其低于 Chrome 144 时发出警告
- 检查默认自动连接配置文件所用的同一主机上是否安装了 Google Chrome
- 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告
- 提醒你在浏览器 inspect 页面中启用远程调试（例如
`chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging`，
或 `edge://inspect/#remote-debugging`）
Doctor 无法替你启用 Chrome 侧设置。主机本地 Chrome MCP 仍然需要：
Doctor 无法替你启用 Chrome 侧设置。主机本地 Chrome MCP
仍然要求：
- Gateway 网关/节点主机上安装 144+ 的 Chromium 内核浏览器
- Gateway 网关/节点主机上有一个 144+ 的 Chromium 内核浏览器
- 浏览器在本地运行
- 在该浏览器中启用远程调试
- 在浏览器中批准首次附加授权提示
- 在浏览器中批准首次附加的同意提示
这里的就绪情况仅涉及本地附加前置条件。Existing-session 会保留当前 Chrome MCP 的路由限制；像 `responsebody`、PDF 导出、下载拦截和批处理操作这样的高级路由，仍然需要受管浏览器或原始 CDP 配置档案。
这里的就绪情况仅涉及本地附加前提条件。`existing-session` 会保留
当前 Chrome MCP 路由限制；像 `responsebody`、PDF
导出、下载拦截和批量操作等高级路由，仍然需要受管浏览器
或原始 CDP 配置文件。
此检查**不**适用于 Docker、沙箱、remote-browser 或其他无头流程。这些流程将继续使用原始 CDP。
此检查**不**适用于 Docker、沙箱、remote-browser 或其他
无头流程。这些流程会继续使用原始 CDP。
### 2d）OAuth TLS 前置条件
当配置了 OpenAI Codex OAuth 配置档案时，doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈是否能够验证证书链。如果探测因证书错误失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），doctor 会输出特定平台的修复指导。在 macOS 上，如果使用的是 Homebrew Node，修复方式通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，该探测也会运行。
当配置了 OpenAI Codex OAuth 配置文件时，doctor 会探测 OpenAI
授权端点，以验证本地 Node/OpenSSL TLS 栈是否可以校验证书链。如果探测因证书错误失败（例如
`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），doctor 会打印特定于平台的修复指引。在使用 Homebrew Node 的 macOS 上，
修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，
即使 Gateway 网关健康，此探测也会运行。
### 3）旧版状态迁移（磁盘布局）
Doctor 可以将较旧的磁盘布局迁移到当前结构：
Doctor 可以将旧版磁盘布局迁移到当前结构：
- Sessions 存储 + transcripts：
- 会话存储 + 转录：
- 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents/<agentId>/sessions/`
- Agent 目录：
- 智能体目录：
- 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents/<agentId>/agent/`
- WhatsApp 凭证状态（Baileys）：
- 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）
- WhatsApp 认证状态（Baileys）：
- 从旧版 `~/.openclaw/credentials/*.json`（不包括 `oauth.json`）
- 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账户 ID：`default`）
这些迁移尽力而为且是幂等的；如果它保留了任何旧版文件夹作为备份，doctor 会发出警告。Gateway 网关/CLI 在启动时也会自动迁移旧版 sessions + agent 目录，因此历史记录/凭证/模型会落到按智能体划分的路径中，而无需手动运行 doctor。WhatsApp 凭证有意仅通过 `openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在会按结构相等性比较，因此仅键顺序差异不会再触发重复的无操作 `doctor --fix` 更改。
这些迁移是尽力而为且幂等的；doctor 会在留下任何旧版文件夹作为备份时发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话 + 智能体目录，因此历史记录/认证/模型会进入每个智能体路径，而无需手动运行 doctor。WhatsApp 认证则有意只通过 `openclaw doctor` 迁移。Talk provider/provider-map 规范化现在按结构相等进行比较，因此仅键顺序不同的差异不再触发重复的无操作 `doctor --fix` 更改。
### 3a）旧版插件清单迁移
Doctor 会扫描所有已安装插件清单中的已弃用顶层能力键
（`speechProviders`、`realtimeTranscriptionProviders`、
Doctor 会扫描所有已安装的插件清单，查找已弃用的顶层能力
键（`speechProviders`、`realtimeTranscriptionProviders`、
`realtimeVoiceProviders`、`mediaUnderstandingProviders`、
`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、
`webSearchProviders`）。发现后，它会提供将其移入 `contracts`
对象并原地重写清单文件的选项。该迁移是幂等的；
如果 `contracts` 键中已经有相同值，就会移除旧版键而不重复数据。
`webSearchProviders`）。找到后，它会提供将这些键移动到 `contracts`
对象中的选项，并原地重写清单文件。此迁移是幂等的；
如果 `contracts` 键中已存在相同值，则会移除旧版键，
而不会重复数据。
### 3b）旧版 cron 存储迁移
Doctor 还会检查 cron 任务存储（默认是 `~/.openclaw/cron/jobs.json`，
若被覆盖则使用 `cron.store`）中调度器仍为兼容性而接受的旧任务形态。
或在覆盖时使用 `cron.store`），查找调度器仍出于兼容性而接受的旧任务结构。
当前的 cron 清理包括：
当前 cron 清理包括：
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- 顶层 payload 字段（`message`、`model`、`thinking`、...）→ `payload`
- 顶层 delivery 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
- payload 中的 `provider` delivery 别名 → 显式 `delivery.channel`
- 简单的旧版 `notify: true` webhook 回退任务 → 显式 `delivery.mode="webhook"` 且 `delivery.to=cron.webhook`
- payload `provider` delivery 别名 → 显式 `delivery.channel`
- 简单的旧版 `notify: true` webhook 回退任务 → 显式 `delivery.mode="webhook"`，并配合 `delivery.to=cron.webhook`
Doctor 仅会在能够不改变行为的情况下自动迁移 `notify: true` 任务。
如果某个任务同时包含旧版 notify 回退和现有的非 webhook delivery 模式，doctor 会发出警告，并将该任务留待手动检查。
Doctor 仅在能够不改变行为的情况下自动迁移 `notify: true` 任务。
如果某个任务将旧版 notify 回退与现有
非 webhook delivery 模式结合使用，doctor 会发出警告，并将该任务留给人工审查。
### 3c）会话锁清理
Doctor 会扫描每个智能体会话目录中的过时写锁文件——这些文件是在会话异常退出时遗留的。对于找到的每个锁文件，它会报告：
路径、PID、该 PID 是否仍存活、锁的存在时间，以及它是否被视为过时（PID 已死或超过 30 分钟）。在 `--fix` / `--repair`
模式下，它会自动删除过时锁文件；否则会输出说明，并指示你使用 `--fix` 重新运行。
Doctor 会扫描每个智能体会话目录中是否存在过期写锁文件——即会话异常退出后遗留的文件。对于找到的每个锁文件，它会报告：
路径、PID、该 PID 是否仍然存活、锁文件存在时长，以及它是否
被视为过期（PID 已死或存在时间超过 30 分钟）。在 `--fix` / `--repair`
模式下，它会自动移除过期锁文件；否则它会打印说明，并指示你使用 `--fix` 重新运行。
### 4）状态完整性检查（会话持久化、路由和安全）
状态目录是运行系统的大脑中枢。如果它消失了，你将丢失
sessions、凭证、日志和配置（除非你在别处有备份）。
状态目录是运行中的中枢神经。如果它消失了，你会失去
会话、凭证、日志和配置（除非你在其他地方有备份）。
Doctor 会检查：
- **状态目录缺失**：警告灾难性的状态丢失，提示重新创建目录，并提醒你它无法恢复丢失的数据。
- **状态目录权限**：验证是否可写；提供修复权限的选项
- **状态目录缺失**：警告灾难性的状态丢失，提示重新创建
目录，并提醒你它无法恢复缺失数据。
- **状态目录权限**：验证可写性；提供修复权限选项
（并在检测到所有者/组不匹配时给出 `chown` 提示）。
- **macOS 云同步状态目录**：当状态解析到 iCloud Drive
（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或
`~/Library/CloudStorage/...` 下时发出警告，因为同步支持路径可能导致更慢的 I/O 以及锁/同步竞争。
`~/Library/CloudStorage/...` 下时发出警告，因为基于同步的路径可能导致更慢的 I/O
和锁/同步竞争。
- **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*`
挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入场景中可能更慢且磨损更快。
- **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史记录并避免 `ENOENT` 崩溃所必需的。
- **Transcript 不匹配**：当最近的会话条目缺少 transcript 文件时发出警告。
- **主会话“单行 JSONL”**：当主 transcript 只有一行时标记出来（历史记录没有持续累积）。
- **多个状态目录**：当多个主目录下存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在多个安装间分裂）。
- **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它（状态存储在那里）。
- **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对组/全局可读，则发出警告，并提供将权限收紧到 `600` 的选项。
挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入场景下可能更慢且磨损更快。
- **会话目录缺失**：`sessions/` 和会话存储目录是
持久化历史并避免 `ENOENT` 崩溃所必需的。
- **转录不匹配**：当最近的会话条目缺少
转录文件时发出警告。
- **主会话“单行 JSONL”**：当主转录只有一行时标记出来（历史未持续累积）。
- **多个状态目录**：当不同主目录下存在多个 `~/.openclaw` 文件夹，
或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在不同安装之间分裂）。
- **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它
（状态存储在那里）。
- **配置文件权限**：如果 `~/.openclaw/openclaw.json` 可被
组/所有用户读取，则会发出警告，并提供将权限收紧为 `600` 的选项。
### 5）模型凭证健康检查（OAuth 过期）
### 5）模型认证健康状况（OAuth 过期）
Doctor 会检查凭证存储中的 OAuth 配置档案，在 token 即将过期/已过期时发出警告，并可在安全时刷新它们。如果 Anthropic
OAuth/token 配置档案已过时，它会建议使用 Anthropic API 密钥或旧版 Anthropic setup-token 路径。
Doctor 会检查认证存储中的 OAuth 配置文件，在令牌
即将过期/已过期时发出警告，并可在安全的情况下刷新它们。如果 Anthropic
OAuth/令牌配置文件已过期，它会建议使用 Anthropic API 密钥或旧版
Anthropic setup-token 路径。
刷新提示仅在交互模式（TTY）下出现；`--non-interactive`
会跳过刷新尝试。
Doctor 还会检测已移除的 Anthropic Claude CLI 旧状态。如果旧的
Doctor 还会检测过期且已移除的 Anthropic Claude CLI 状态。如果旧的
`anthropic:claude-cli` 凭证字节仍存在于 `auth-profiles.json` 中，
doctor 会将其转换回 Anthropic token/OAuth 配置档案，并重写过时的
`claude-cli/...` 模型引用以及 `agents.defaults.cliBackends.claude-cli`。
如果这些字节已不存在，doctor 会移除过时配置并输出恢复命令。
doctor 会将其转换回 Anthropic 令牌/OAuth 配置文件，并重写
过期的 `claude-cli/...` 模型引用。
如果这些字节已不存在，doctor 会移除过期配置并打印恢复
命令。
Doctor 还会报告由于以下原因而暂时不可用的 auth profiles：
Doctor 还会报告由于以下原因而暂时不可用的 auth profile：
- 短期冷却（速率限制/超时/凭证失败）
- 较长时间禁用（计费/额度失败）
- 短期冷却（限流/超时/认证失败）
- 长期禁用（账单/余额失败）
### 6）Hooks 模型校验
### 6）Hooks 模型验证
如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证模型引用，并在其无法解析或不被允许时发出警告。
如果设置了 `hooks.gmail.model`，doctor 会根据目录和 allowlist 验证模型引用，并在它无法解析或不被允许时发出警告。
### 7）沙箱镜像修复
启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。
当启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。
### 7b）内置插件运行时依赖
Doctor 会验证内置插件运行时依赖（例如 Discord 插件运行时包）是否存在于 OpenClaw 安装根目录中。
Doctor 会验证内置插件运行时依赖（例如
Discord 插件运行时包）是否存在于 OpenClaw 安装根目录中。
如果缺失，doctor 会报告这些包，并在
`openclaw doctor --fix` / `openclaw doctor --repair` 模式下安装它们。
### 8）Gateway 网关服务迁移和清理提示
Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks），并提供移除它们以及使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类似 Gateway 网关服务并输出清理提示。
按配置档案命名的 OpenClaw Gateway 网关服务被视为一等公民，不会被标记为“额外”。
Doctor 会检测旧版 Gateway 网关服务（`launchd`/`systemd`/`schtasks`），并
提供移除它们及使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类 Gateway 网关服务并打印清理提示。
按 profile 命名的 OpenClaw Gateway 网关服务被视为一等公民，不会
被标记为“额外”服务。
### 8b）启动 Matrix 迁移
当 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时，
doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都不是致命的；错误会被记录，启动会继续。在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查会被完全跳过。
doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后
运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版
加密状态准备。这两个步骤都不是致命的；错误会被记录，启动会继续进行。在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查
会被完全跳过。
### 9）安全警告
当某个提供商对私信开放但没有允许列表，或某项策略以危险方式配置时，doctor 会发出警告。
当某个提供商对私信开放却没有 allowlist，或
某项策略以危险方式配置时，doctor 会发出警告。
### 10）systemd linger（Linux）
如果作为 systemd 用户服务运行，doctor 会确保已启用 lingering，以便 Gateway 网关在注销后仍保持运行。
如果作为 `systemd` 用户服务运行，doctor 会确保启用了 lingering，以便
Gateway 网关在注销后仍保持运行。
### 11）工作区状态（Skills、插件和旧版目录）
Doctor 会输出默认智能体的工作区状态摘要：
Doctor 会为默认智能体打印工作区状态摘要：
- **Skills 状态**：统计可用、缺少要求、和被允许列表阻止的 Skills 数量。
- **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区并存时发出警告。
- **插件状态**：统计已加载/已禁用/出错的插件数量；列出所有出错插件的插件 ID；报告内置插件能力。
- **Skills 状态**：统计符合条件、缺失要求和被 allowlist 阻止的 Skills 数量。
- **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录
与当前工作区并存时发出警告。
- **插件状态**：统计已加载/已禁用/出错的插件数量；列出出错插件的插件 ID；
报告 bundle 插件能力。
- **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。
- **插件诊断**：显示插件注册表在加载时发出的任何警告或错误。
- **插件诊断**：呈现插件注册表在加载时发出的任何警告或错误。
### 11b）Bootstrap 文件大小
### 11b）引导文件大小
Doctor 会检查工作区 bootstrap 文件（例如 `AGENTS.md`、
`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会报告每个文件的原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，doctor 会给出调优 `agents.defaults.bootstrapMaxChars`
和 `agents.defaults.bootstrapTotalMaxChars` 的建议。
Doctor 会检查工作区引导文件（例如 `AGENTS.md`、
`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过已配置的
字符预算。它会报告每个文件的原始字符数与注入字符数、截断
百分比、截断原因（`max/file` 或 `max/total`），以及总注入
字符数占总预算的比例。当文件被截断或接近
限制时，doctor 会打印有关调整 `agents.defaults.bootstrapMaxChars`
和 `agents.defaults.bootstrapTotalMaxChars` 的提示。
### 11c）Shell 补全
Doctor 会检查当前 shell 是否已安装 Tab 补全
（zsh、bash、fish 或 PowerShell）：
Doctor 会检查当前 shell
（zsh、bash、fish 或 PowerShell）是否已安装 tab 补全：
- 如果 shell 配置文件使用了较慢的动态补全模式
（`source <(openclaw completion ...)`），doctor 会将其升级为更快的缓存文件变体。
- 如果 shell 配置文件使用较慢的动态补全模式
（`source <(openclaw completion ...)`），doctor 会将其升级为更快的
缓存文件变体。
- 如果补全已在配置文件中配置，但缓存文件缺失，
doctor 会自动重新生成缓存。
- 如果完全未配置补全，它会提示你安装
- 如果完全未配置补全，它会提示进行安装
（仅交互模式；使用 `--non-interactive` 时跳过）。
运行 `openclaw completion --write-state` 可手动重新生成缓存。
### 12）Gateway 网关认证检查（本地 token）
### 12）Gateway 网关认证检查（本地令牌）
Doctor 会检查本地 Gateway 网关 token 认证的就绪情况。
Doctor 会检查本地 Gateway 网关令牌认证的就绪情况。
- 如果 token 模式需要 token 且没有 token 来源，doctor 会提供生成一个 token 的选项。
- 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，doctor 会发出警告，且不会用明文覆盖它。
- 仅当未配置 token SecretRef 时，`openclaw doctor --generate-gateway-token` 才会强制生成。
- 如果令牌模式需要令牌且没有令牌来源，doctor 会提供生成令牌的选项。
- 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，doctor 会发出警告，并且不会用明文覆盖它。
- `openclaw doctor --generate-gateway-token` 仅在未配置任何令牌 SecretRef 时强制生成。
### 12b）只读的 SecretRef 感知修复
### 12b）只读 SecretRef 感知修复
某些修复流程需要检查已配置的凭证，而不能削弱运行时快速失败行为。
某些修复流程需要检查已配置的凭证，同时又不能削弱运行时快速失败行为。
- `openclaw doctor --fix` 现在对目标配置修复使用与 status 系列命令相同的只读 SecretRef 摘要模型。
- `openclaw doctor --fix` 现在使用与状态类命令相同的只读 SecretRef 摘要模型，用于有针对性的配置修复。
- 示例：Telegram `allowFrom` / `groupAllowFrom` 的 `@username` 修复会在可用时尝试使用已配置的机器人凭证。
- 如果 Telegram bot token 通过 SecretRef 配置，但在当前命令路径中不可用，doctor 会报告该凭证已配置但不可用，并跳过自动解析，而不是崩溃或错误地将 token 报告为缺失。
- 如果 Telegram 机器人令牌是通过 SecretRef 配置的，但在当前命令路径中不可用，doctor 会报告该凭证“已配置但不可用”，并跳过自动解析，而不是崩溃或误报令牌缺失。
### 13）Gateway 网关健康检查 + 重启
Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。
Doctor 会运行健康检查，并在 Gateway 网关看起来
不健康时提供重启选项。
### 13b）记忆搜索就绪情况
Doctor 会检查为默认智能体配置的记忆搜索 embedding 提供商是否已就绪。其行为取决于已配置的后端和提供商：
Doctor 会检查为默认智能体配置的记忆搜索嵌入提供商是否已就绪。
具体行为取决于已配置的后端和提供商：
- **QMD 后端**：探测 `qmd` 二进制是否可用且可启动。
如果不能，则输出修复指导，包括 npm 包和手动二进制路径选项。
- **显式本地提供商**：检查本地模型文件或已识别的远程/可下载模型 URL。
如果缺失，则建议切换到远程提供商。
- **显式远程提供商**（`openai`、`voyage` 等）：验证环境中或凭证存储中是否存在 API 密钥。若缺失，则输出可执行的修复提示。
- **自动提供商**：先检查本地模型可用性，再按自动选择顺序尝试每个远程提供商。
如果不可用，会打印修复指引，包括 npm 包和手动二进制路径选项。
- **显式本地提供商**：检查本地模型文件或已识别的
远程/可下载模型 URL 是否存在。如果缺失，则建议切换到远程提供商。
- **显式远程提供商**（`openai`、`voyage` 等）：验证环境中或认证存储中是否存在 API 密钥。
如果缺失，会打印可执行的修复提示。
- **自动提供商**：先检查本地模型可用性，然后按自动选择顺序尝试每个远程
提供商。
当 Gateway 网关探测结果可用时（检查时 Gateway 网关是健康的），doctor 会将其结果与 CLI 可见配置交叉比对，并指出任何不一致之处。
当 Gateway 网关探测结果可用时（即检查时 Gateway 网关健康），doctor 会将其与 CLI 可见配置交叉对照，并指出
任何差异。
使用 `openclaw memory status --deep` 可在运行时验证 embedding 就绪情况。
使用 `openclaw memory status --deep` 在运行时验证嵌入就绪情况。
### 14）渠道状态警告
如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告带有建议修复方式的警告。
如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告
附带建议修复方法的警告。
### 15）Supervisor 配置审计 + 修复
Doctor 会检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少或落后于当前默认值（例如 systemd network-online 依赖项和重启延迟）。当发现不匹配时，它会建议更新，并可将服务文件/任务重写为当前默认值。
Doctor 会检查已安装的 supervisor 配置（`launchd`/`systemd`/`schtasks`），查看
是否缺少或过期了默认值（例如 `systemd` 的 `network-online` 依赖和
重启延迟）。当发现不匹配时，它会
建议更新，并可将服务文件/任务重写为当前默认值。
说明：
- `openclaw doctor` 会在重写 supervisor 配置前进行提示。
- `openclaw doctor` 会在重写 supervisor 配置前提示确认。
- `openclaw doctor --yes` 会接受默认修复提示。
- `openclaw doctor --repair` 会无提示应用推荐修复。
- `openclaw doctor --repair` 会在无提示的情况下应用推荐修复。
- `openclaw doctor --repair --force` 会覆盖自定义 supervisor 配置。
- 如果 token 认证需要 token，且 `gateway.auth.token` 由 SecretRef 管理，doctor 的服务安装/修复会验证 SecretRef，但不会将解析后的明文 token 值持久化到 supervisor 服务环境元数据中。
- 如果 token 认证需要 token，而已配置的 token SecretRef 未解析，doctor 会阻止安装/修复路径，并提供可执行的指导。
- 如果令牌认证需要令牌，而 `gateway.auth.token` 由 SecretRef 管理，doctor 在安装/修复服务时会验证 SecretRef，但不会将解析出的明文令牌值持久化到 supervisor 服务环境元数据中。
- 如果令牌认证需要令牌，而配置的令牌 SecretRef 无法解析，doctor 会阻止安装/修复路径，并提供可执行的指引。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，而 `gateway.auth.mode` 未设置，doctor 会阻止安装/修复，直到显式设置 mode。
- 对于 Linux user-systemd 单元，doctor 的 token 漂移检查现在在比较服务认证元数据时会同时包含 `Environment=` 和 `EnvironmentFile=` 来源。
- 你始终可以通过 `openclaw gateway install --force` 强制完整重写。
- 对于 Linux user-systemd 单元，doctor 的令牌漂移检查现在在比较服务认证元数据时会同时包含 `Environment=` 和 `EnvironmentFile=` 来源。
- 你始终可以通过 `openclaw gateway install --force` 强制执行完整重写。
### 16）Gateway 网关运行时 + 端口诊断
Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但实际未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。
Doctor 会检查服务运行时（PID、上次退出状态），并在
服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口
（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、
SSH 隧道）。
### 17）Gateway 网关运行时最佳实践
当 Gateway 网关服务运行在 Bun 上或运行在版本管理的 Node 路径
（`nvm`、`fnm`、`volta`、`asdf` 等）时，doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径在升级后可能失效，因为服务不会加载你的 shell 初始化。Doctor 会在系统 Node 可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。
当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径
（`nvm`、`fnm`、`volta`、`asdf` 等）上时，doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，
而版本管理器路径在升级后可能会失效，因为服务不会
加载你的 shell 初始化。Doctor 会在可用时提供迁移到系统 Node 安装（Homebrew/apt/choco）的选项。
### 18）配置写入 + 向导元数据
Doctor 会持久化任何配置变更，并写入向导元数据以记录本次 doctor 运行。
Doctor 会持久化所有配置更改，并写入向导元数据以记录
doctor 运行。
### 19）工作区提示（备份 + 记忆系统）
当工作区缺少记忆系统时，doctor 会提出建议；如果工作区尚未由 git 管理，它还会输出备份提示。
当工作区缺少记忆系统时，doctor 会给出建议；如果工作区尚未处于 git 管理下，它还会打印备份提示。
有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参见 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。
参见 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace) 了解有关
工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南。

1778
docs/zh-CN/help/faq.md
View File

File diff suppressed because it is too large Load Diff

517
docs/zh-CN/help/testing.md
View File

@ -1,28 +1,28 @@
---
read_when:
- 在本地或 CI 中运行测试时
- 为模型/提供商缺陷添加回归测试时
- 调试 Gateway 网关 + 智能体行为时
summary: 测试套件：单元/e2e/实时套件、Docker 运行器，以及各类测试覆盖的内容
- 在本地或 CI 中运行测试
- 为模型/提供商 Bug 添加回归测试
- 调试 Gateway 网关 + 智能体行为
summary: 测试工具包：unit/e2e/live 测试套件、Docker 运行器，以及各项测试覆盖的内容
title: 测试
x-i18n:
generated_at: "2026-04-05T17:49:14Z"
generated_at: "2026-04-05T18:14:58Z"
model: gpt-5.4
provider: openai
source_hash: 646f7bc92f15fc7c0270d6febee9f192ec1c8a6e9bb0cc8730bce73757521cac
source_hash: 65305c0de33287f48f182bb9f276e4f3ba9cc49c65a54e115e1d77ec89f56ab7
source_path: help/testing.md
workflow: 15
---
# 测试
OpenClaw 有三个 Vitest 测试套件（单元/集成、e2e、实时）以及一小组 Docker 运行器。
OpenClaw 有三个 Vitest 测试套件（unit/integration、e2e、live）以及一小组 Docker 运行器。
本文档是一份“我们如何测试”的指南：
- 每个套件覆盖什么（以及它刻意**不**覆盖什么）
- 每个测试套件覆盖什么内容（以及它刻意 _不_ 覆盖什么）
- 常见工作流应运行哪些命令（本地、推送前、调试）
- 实时测试如何发现凭证并选择模型/提供商
- live 测试如何发现凭证并选择模型/提供商
- 如何为真实世界中的模型/提供商问题添加回归测试
## 快速开始
@ -30,68 +30,70 @@ OpenClaw 有三个 Vitest 测试套件（单元/集成、e2e、实时）以及
大多数时候：
- 完整门禁（预期在推送前运行）：`pnpm build && pnpm check && pnpm test`
- 在资源充足的机器上更快地运行本地完整套件：`pnpm test:max`
- 直接运行 Vitest 监听循环（现代项目配置）：`pnpm test:watch`
- 直接指定文件现在也支持扩展/渠道路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
- 在配置充裕的机器上更快地运行本地完整测试套件：`pnpm test:max`
- 直接使用 Vitest 监视循环（现代 projects 配置）：`pnpm test:watch`
- 直接按文件定位现在也会路由扩展/渠道路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
当你修改测试或想要更高信心时：
当你改动了测试或想获得更高信心时：
- 覆盖率门禁：`pnpm test:coverage`
- E2E 套件：`pnpm test:e2e`
- E2E 测试套件：`pnpm test:e2e`
当你调试真实提供商/模型时（需要真实凭证）：
当你在调试真实提供商/模型时（需要真实凭证）：
- 实时套件（模型 + Gateway 网关工具/图像探针）：`pnpm test:live`
- 安静地只跑一个实时文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts`
- Live 测试套件（模型 + Gateway 网关工具/图像探测）：`pnpm test:live`
- 安静地只跑一个 live 文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts`
提示：如果你只需要一个失败用例，优先使用下面描述的允许名单环境变量来缩小实时测试范围。
提示：当你只需要一个失败用例时，优先使用下文描述的 allowlist 环境变量来缩小 live 测试范围。
## 测试套件（各自运行位置）
## 测试套件（各自在哪里运行）
可以把这些套件理解为“真实性逐步提升”（同时不稳定性/成本也逐步提高）：
可以把这些测试套件理解为“真实度逐步提升”（同时不稳定性/成本也逐步提升）：
### 单元 / 集成（默认）
### Unit / integration（默认）
- 命令：`pnpm test`
- 配置：通过 `vitest.config.ts` 使用原生 Vitest `projects`
- 文件：`src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 下的核心/单元测试清单，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` Node 测试
- 文件：`src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 下的 core/unit 测试清单，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` node 测试
- 范围：
- 纯单元测试
- 进程内集成测试（Gateway 网关认证、路由、工具、解析、配置）
- 已知缺陷的确定性回归测试
- 已知 Bug 的确定性回归测试
- 预期：
- 在 CI 中运行
- 不需要真实密钥
- 应该快速且稳定
- Projects 说明：
- `pnpm test`、`pnpm test:watch` 和 `pnpm test:changed` 现在都使用同一套原生 Vitest 根 `projects` 配置。
- 直接文件过滤现在会原生通过根项目图路由，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 无需自定义包装器即可工作。
- 嵌入式运行器说明：
- 当你更改消息工具发现输入或压缩运行时上下文时，
请同时保留这两个层级的覆盖。
- 为纯路由/归一化边界添加聚焦的辅助回归测试。
- 同时也要保持嵌入式运行器集成套件健康：
- `pnpm test`、`pnpm test:watch` 和 `pnpm test:changed` 现在都使用相同的原生 Vitest 根 `projects` 配置。
- 直接文件过滤现在会原生通过根项目图进行路由，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 无需自定义包装器即可运行。
- Embedded runner 说明：
- 当你修改消息工具发现输入或压缩运行时上下文时，
需要同时保留两个层级的覆盖。
- 为纯路由/规范化边界添加聚焦的辅助回归测试。
- 同时也要保持 embedded runner 集成测试套件健康：
`src/agents/pi-embedded-runner/compact.hooks.test.ts`、
`src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` 和
`src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。
- 这些套件会验证作用域 id 和压缩行为仍然会流经真实的 `run.ts` / `compact.ts` 路径；仅有辅助函数测试并不能充分替代这些集成路径。
- 线程池说明：
- 这些测试套件会验证带作用域的 id 和压缩行为仍然会通过真实的
`run.ts` / `compact.ts` 路径流转；仅有 helper 测试
不足以替代这些集成路径。
- Pool 说明：
- 基础 Vitest 配置现在默认使用 `threads`。
- 共享 Vitest 配置还固定设置了 `isolate: false`，并在根项目、e2e 和实时配置中使用非隔离运行器。
- 根 UI 测试通道保留其 `jsdom` 设置和优化器，但现在也运行在共享的非隔离运行器上。
- `pnpm test` 现在也从根 `vitest.config.ts` 的 projects 配置继承相同的 `threads` + `isolate: false` 默认值。
- 共享的 `scripts/run-vitest.mjs` 启动器现在默认还会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。如果你需要与原始 V8 行为进行对比，请设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1`。
- 快速本地迭代说明：
- `pnpm test:changed` 使用原生 projects 配置并附加 `--changed origin/main`。
- `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的原生 projects 配置，只是使用更高的 worker 上限。
- 本地 worker 自动扩缩现在有意更保守，而且当主机平均负载已经较高时也会退让，因此默认情况下多个并发 Vitest 运行造成的影响会更小。
- 基础 Vitest 配置会将 projects/config 文件标记为 `forceRerunTriggers`，这样当测试接线发生变化时，changed 模式重跑仍然正确。
- 在受支持的主机上，配置会保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你希望为直接性能分析指定一个明确缓存位置，请设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。
- 共享 Vitest 配置还固定了 `isolate: false`，并在根 projects、e2e 和 live 配置中使用非隔离运行器。
- 根 UI 通道仍保留其 `jsdom` 设置和优化器，但现在也在共享的非隔离运行器上运行。
- `pnpm test` 现在会从根 `vitest.config.ts` 的 projects 配置继承相同的 `threads` + `isolate: false` 默认值。
- 共享的 `scripts/run-vitest.mjs` 启动器现在也会默认为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。如果你需要与原始 V8 行为对比，可设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1`。
- 本地快速迭代说明：
- `pnpm test:changed` 会用 `--changed origin/main` 运行原生 projects 配置。
- `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的原生 projects 配置，只是提高了 worker 上限。
- 本地 worker 自动扩缩容现在有意更保守，并且当主机平均负载已经较高时也会回退，因此默认情况下多个并发 Vitest 运行造成的影响更小。
- 基础 Vitest 配置会将 projects/config 文件标记为 `forceRerunTriggers`，以便在测试接线发生变化时，changed 模式下的重跑仍然正确。
- 配置会在受支持主机上保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你想为直接性能分析指定一个显式缓存位置，可设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。
- 性能调试说明：
- `pnpm test:perf:imports` 会启用 Vitest 导入耗时报告以及导入细分输出。
- `pnpm test:perf:imports:changed` 会将相同的分析视图限定为自 `origin/main` 以来变更的文件。
- `pnpm test:perf:imports` 会启用 Vitest 导入耗时报告以及导入明细输出。
- `pnpm test:perf:imports:changed` 会将相同的分析视图限定到相对 `origin/main` 已变更的文件。
- `pnpm test:perf:profile:main` 会为 Vitest/Vite 启动和 transform 开销写出主线程 CPU profile。
- `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为单元测试套件写出运行器 CPU + 堆 profile。
- `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为 unit 测试套件写出 runner CPU + heap profile。
### E2E（Gateway 网关冒烟）
@ -99,219 +101,179 @@ OpenClaw 有三个 Vitest 测试套件（单元/集成、e2e、实时）以及
- 配置：`vitest.e2e.config.ts`
- 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`
- 运行时默认值：
- 使用带 `isolate: false` 的 Vitest `threads`，与仓库其余部分保持一致。
- 使用自适应 workers（CI：最多 2 个，本地：默认 1 个）。
- 使用 Vitest `threads` 且 `isolate: false`，与仓库其余部分保持一致。
- 使用自适应 worker（CI：最多 2 个，本地：默认 1 个）。
- 默认以静默模式运行，以减少控制台 I/O 开销。
- 常用覆盖项：
- `OPENCLAW_E2E_WORKERS=<n>` 强制指定 worker 数量（上限为 16）。
- `OPENCLAW_E2E_VERBOSE=1` 重新启用详细控制台输出。
- 范围：
- 多实例 Gateway 网关端到端行为
- WebSocket/HTTP 界面、节点配对及更重的网络场景
- WebSocket/HTTP 接口、节点配对以及更重的网络交互
- 预期：
- 在 CI 中运行（当流水线启用时）
- 不需要真实密钥
- 比单元测试包含更多活动部件（可能更慢）
- 比单元测试有更多活动部件（可能更慢）
### E2E：OpenShell 后端冒烟
- 命令：`pnpm test:e2e:openshell`
- 文件：`test/openshell-sandbox.e2e.test.ts`
- 范围：
- 通过 Docker 在主机上启动一个隔离的 OpenShell Gateway 网关
- 从临时本地 Dockerfile 创建一个沙箱
- 通过 Docker 在宿主机上启动一个隔离的 OpenShell Gateway 网关
- 从一个临时本地 Dockerfile 创建沙箱
- 通过真实的 `sandbox ssh-config` + SSH exec 运行 OpenClaw 的 OpenShell 后端
- 通过沙箱 fs bridge 验证远端规范文件系统行为
- 预期：
- 仅按需启用；不属于默认 `pnpm test:e2e` 运行的一部分
- 仅限选择性启用；不属于默认 `pnpm test:e2e` 运行的一部分
- 需要本地 `openshell` CLI 和可用的 Docker daemon
- 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 Gateway 网关和沙箱
- 常用覆盖项：
- `OPENCLAW_E2E_OPENSHELL=1`，在手动运行更广泛的 e2e 套件时启用该测试
- `OPENCLAW_E2E_OPENSHELL=1`，在手动运行更广泛的 e2e 测试套件时启用该测试
- `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`，指向非默认 CLI 二进制或包装脚本
### 实时（真实提供商 + 真实模型）
### Live（真实提供商 + 真实模型）
- 命令：`pnpm test:live`
- 配置：`vitest.live.config.ts`
- 文件：`src/**/*.live.test.ts`
- 默认：由 `pnpm test:live` **启用**（设置 `OPENCLAW_LIVE_TEST=1`）
- 范围：
- “这个提供商/模型今天在真实凭证下是否真的能工作？”
- 捕获提供商格式变化、工具调用怪癖、认证问题和速率限制行为
- “这个提供商/模型 _今天_ 在真实凭证下是否确实能工作？”
- 捕获提供商格式变化、工具调用怪癖、认证问题和限流行为
- 预期：
- 按设计不适合 CI 稳定运行（真实网络、真实提供商策略、配额、宕机）
- 会花钱 / 消耗速率限制
- 按设计不保证 CI 稳定（真实网络、真实提供商策略、配额、故障）
- 会花钱 / 消耗限流额度
- 优先运行缩小范围的子集，而不是“全部”
- 实时运行会读取 `~/.profile`，以获取缺失的 API 密钥。
- 默认情况下，实时运行仍会隔离 `HOME`，并将配置/认证材料复制到临时测试 home 中，这样单元测试夹具就不会修改你的真实 `~/.openclaw`。
- 只有在你明确需要让实时测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。
- `pnpm test:live` 现在默认采用更安静的模式：保留 `[live] ...` 进度输出，但抑制额外的 `~/.profile` 提示，并静默 Gateway 网关启动日志/Bonjour 噪声。如果你想恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。
- API 密钥轮换（提供商特定）：设置 `*_API_KEYS`（逗号/分号格式）或 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或者通过 `OPENCLAW_LIVE_*_KEY` 进行实时测试覆盖；测试在收到速率限制响应时会重试。
- Live 运行会读取 `~/.profile` 以获取缺失的 API 密钥。
- 默认情况下，live 运行仍会隔离 `HOME`，并把配置/认证材料复制到临时测试 home 中，这样 unit fixture 就不能修改你真实的 `~/.openclaw`。
- 只有当你明确需要 live 测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。
- `pnpm test:live` 现在默认更安静：它会保留 `[live] ...` 进度输出，但会抑制额外的 `~/.profile` 提示，并静音 Gateway 网关启动日志/Bonjour 噪声。如果你想恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。
- API 密钥轮换（提供商特定）：设置 `*_API_KEYS`（逗号/分号格式）或 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或者通过 `OPENCLAW_LIVE_*_KEY` 做每个 live 运行的单独覆盖；测试会在收到限流响应时重试。
- 进度/心跳输出：
- 实时套件现在会将进度行输出到 stderr，因此即使 Vitest 控制台捕获很安静，长时间的提供商调用也会明显显示为活跃状态。
- `vitest.live.config.ts` 禁用了 Vitest 控制台拦截，因此在实时运行期间，提供商/Gateway 网关进度行会立即流式输出。
- 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直连模型心跳。
- 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 Gateway 网关/探针心跳。
- Live 测试套件现在会向 stderr 输出进度行，因此即使 Vitest 控制台捕获较安静，长时间的提供商调用也能明显看出仍在活动。
- `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，以便提供商/Gateway 网关进度行在 live 运行期间立即流式输出。
- 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整 direct-model 心跳。
- 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 Gateway 网关/探测心跳。
## 我应该运行哪个套件？
## 我应该运行哪个测试套件？
使用这个决策表：
使用这张决策表：
- 编辑逻辑/测试：运行 `pnpm test`（如果你改动很多，也可运行 `pnpm test:coverage`）
- 修改 Gateway 网关网络 / WS 协议 / 配对：额外运行 `pnpm test:e2e`
- 调试“我的机器人挂了” / 提供商特定故障 / 工具调用：运行缩小范围的 `pnpm test:live`
- 编辑逻辑/测试：运行 `pnpm test`（如果改动较多，也运行 `pnpm test:coverage`）
- 触及 Gateway 网关网络 / WS 协议 / 配对：额外运行 `pnpm test:e2e`
- 调试“我的 bot 挂了” / 提供商特定故障 / 工具调用：运行缩小范围的 `pnpm test:live`
## 实时：Android 节点能力扫描
## Live：Android 节点能力扫查
- 测试：`src/gateway/android-node.capabilities.live.test.ts`
- 脚本：`pnpm android:test:integration`
- 目标：调用已连接 Android 节点当前**公开的每一条命令**，并断言命令契约行为。
- 目标：调用已连接 Android 节点当前**公布的每一条命令**，并断言命令契约行为。
- 范围：
- 有前置条件/手动设置（该套件不会安装/运行/配对应用）。
- 预置/手动设置（该测试套件不会安装/运行/配对 app）。
- 针对所选 Android 节点逐条执行 Gateway 网关 `node.invoke` 验证。
- 必需的预先设置：
- Android 应用已连接并与 Gateway 网关配对。
- 应用保持在前台。
- 你希望通过的能力所需权限/捕获同意已授予。
- 可选目标覆盖：
- 必需的预设置：
- Android app 已连接并已与 Gateway 网关配对。
- App 保持在前台。
- 已授予你期望通过的能力所需的权限/采集同意。
- 可选目标覆盖项：
- `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。
- 完整 Android 设置详情：[Android App](/zh-CN/platforms/android)
## 实时：模型冒烟（profile keys）
## Live：模型冒烟（profile keys）
实时测试分成两层，以便我们隔离故障：
Live 测试分成两层，以便我们隔离故障：
- “Direct model” 告诉我们：在给定密钥下，该提供商/模型是否至少能回答。
- “Gateway smoke” 告诉我们：该模型的完整 Gateway 网关 + 智能体流水线是否工作正常（会话、历史、工具、沙箱策略等）。
- “Direct model” 告诉我们，在给定密钥下，该提供商/模型是否至少能响应。
- “Gateway smoke” 告诉我们，该模型的完整 Gateway 网关 + 智能体流水线是否工作（会话、历史、工具、沙箱策略等）。
### 第 1 层：Direct model completion（无 Gateway 网关）
- 测试：`src/agents/models.profiles.live.test.ts`
- 目标：
- 枚举已发现的模型
- 使用 `getApiKeyForModel` 选择你已有凭证的模型
- 为每个模型运行一个小型 completion（必要时附带定向回归测试）
- 启用方式：
- `pnpm test:live`（如果直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，是 modern 的别名）后，该套件才会真正运行；否则它会跳过，以让 `pnpm test:live` 聚焦于 Gateway 网关冒烟
- 使用 `getApiKeyForModel` 选择你有凭证的模型
- 为每个模型运行一个小型 completion（必要时附带定向回归）
- 如何启用：
- `pnpm test:live`（或者如果你直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）才会实际运行该测试套件；否则会跳过，以便让 `pnpm test:live` 聚焦在 Gateway 网关冒烟
- 如何选择模型：
- `OPENCLAW_LIVE_MODELS=modern` 运行现代允许名单（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_MODELS=all` 是现代允许名单的别名
- 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（逗号分隔的允许名单）
- `OPENCLAW_LIVE_MODELS=modern` 运行现代 allowlist（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_MODELS=all` 是现代 allowlist 的别名
- 或者 `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（逗号分隔的 allowlist）
- 如何选择提供商：
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔的允许名单）
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity"`（逗号分隔的 allowlist）
- 密钥来源：
- 默认：profile 存储和环境变量回退
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅使用 profile 存储**
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅**使用 profile 存储
- 存在原因：
- 将“提供商 API 坏了 / 密钥无效”和“Gateway 网关智能体流水线坏了”区分开
- 包含小型、隔离的回归测试（例如：OpenAI Responses/Codex Responses 的推理回放 + 工具调用流程）
- 将“提供商 API 坏了 / 密钥无效”和“Gateway 网关智能体流水线坏了”分开
- 包含小型、隔离的回归测试（例如：OpenAI Responses/Codex Responses 推理重放 + 工具调用流）
### 第 2 层：Gateway 网关 + dev 智能体冒烟（也就是 “@openclaw” 实际做的事）
- 测试：`src/gateway/gateway-models.profiles.live.test.ts`
- 目标：
- 启动一个进程内 Gateway 网关
- 创建/修补一个 `agent:dev:*` 会话（每次运行可覆盖模型）
- 创建/修补一个 `agent:dev:*` 会话（每次运行按模型覆盖）
- 遍历带密钥的模型并断言：
- “有意义”的回复（无工具）
- 一次真实工具调用可用（read 探针）
- 可选的额外工具探针（exec+read 探针）
- OpenAI 回归路径（仅工具调用 → 后续跟进）持续有效
- 探针细节（便于你快速解释故障）：
- `read` 探针：测试会在工作区中写入一个 nonce 文件，并要求智能体 `read` 它并把 nonce 原样回显。
- `exec+read` 探针：测试会要求智能体通过 `exec` 将 nonce 写入临时文件，然后再 `read` 回来。
- 图像探针：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat <CODE>`。
- “有意义”的响应（无工具）
- 真实工具调用可用（read 探测）
- 可选的额外工具探测（exec+read 探测）
- OpenAI 回归路径（仅工具调用 → 后续跟进）继续可用
- 探测细节（这样你可以快速解释失败原因）：
- `read` 探测：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 该文件后回显 nonce。
- `exec+read` 探测：测试会要求智能体通过 `exec` 将 nonce 写入一个临时文件，然后再 `read` 回来。
- 图像探测：测试会附加一个生成的 PNG（cat + 随机代码），并期望模型返回 `cat <CODE>`。
- 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。
- 启用方式：
- `pnpm test:live`（如果直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
- 如何启用：
- `pnpm test:live`（或者如果你直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
- 如何选择模型：
- 默认：现代允许名单（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是现代允许名单的别名
- 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）来缩小范围
- 默认：现代 allowlist（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是现代 allowlist 的别名
- 或者设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）来缩小范围
- 如何选择提供商（避免“OpenRouter 全家桶”）：
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔的允许名单）
- 工具 + 图像探针在这个实时测试中始终开启：
- `read` 探针 + `exec+read` 探针（工具压力测试）
- 当模型宣告支持图像输入时，会运行图像探针
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,openai,anthropic,zai,minimax"`（逗号分隔的 allowlist）
- 在这个 live 测试中，工具 + 图像探测始终启用：
- `read` 探测 + `exec+read` 探测（工具压力测试）
- 当模型宣告支持图像输入时，会运行图像探测
- 流程（高层）：
- 测试生成一个带有 “CAT” + 随机代码的小 PNG（`src/gateway/live-image-probe.ts`）
- 测试生成一个带有 “CAT” + 随机代码的小型 PNG（`src/gateway/live-image-probe.ts`）
- 通过 `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]` 发送
- Gateway 网关将附件解析到 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
- 嵌入式智能体将多模态用户消息转发给模型
- Gateway 网关将附件解析为 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
- Embedded agent 将多模态用户消息转发给模型
- 断言：回复包含 `cat` + 该代码（OCR 容错：允许轻微错误）
提示：如果你想查看自己的机器上能测试哪些内容（以及精确的 `provider/model` id），请运行：
提示：如果你想查看在自己的机器上可以测试什么（以及精确的 `provider/model` id），请运行：
```bash
openclaw models list
openclaw models list --json
```
## 实时：CLI 后端冒烟（Codex CLI 或其他本地 CLI）
- 测试：`src/gateway/gateway-cli-backend.live.test.ts`
- 目标：在不触碰默认配置的前提下，使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线。
- 启用：
- `pnpm test:live`（如果直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
- `OPENCLAW_LIVE_CLI_BACKEND=1`
- 默认值：
- 模型：`codex-cli/gpt-5.4`
- 命令：`codex`
- 参数：`["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
- 覆盖项（可选）：
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"`
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径会注入到提示中）。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 将图像文件路径作为 CLI 参数传递，而不是注入到提示中。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）控制在设置 `IMAGE_ARG` 时如何传递图像参数。
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮并验证恢复流程。
示例：
```bash
OPENCLAW_LIVE_CLI_BACKEND=1 \
OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \
pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
```
Docker 配方：
```bash
pnpm test:docker:live-cli-backend
```
说明：
- Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。
- 它会在仓库 Docker 镜像中以非 root 的 `node` 用户运行实时 CLI 后端冒烟测试。
- 对于 `codex-cli`，它会将 Linux 版 `@openai/codex` 安装到可缓存的可写前缀 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 中（默认：`~/.cache/openclaw/docker-cli-tools`）。
## 实时：ACP 绑定冒烟（`/acp spawn ... --bind here`）
## Live：ACP 绑定冒烟（`/acp spawn ... --bind here`）
- 测试：`src/gateway/gateway-acp-bind.live.test.ts`
- 目标：使用实时 ACP 智能体验证真实 ACP 会话绑定流程：
- 目标：用一个 live ACP 智能体验证真实的 ACP 会话绑定流程：
- 发送 `/acp spawn <agent> --bind here`
- 就地绑定一个合成的消息渠道会话
- 在同一会话上发送普通后续消息
- 验证该后续消息落入已绑定 ACP 会话的转录中
- 原地绑定一个合成的 message-channel 会话
- 在同一会话上发送一条普通的后续消息
- 验证该后续消息会落入已绑定的 ACP 会话 transcript 中
- 启用：
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
- `OPENCLAW_LIVE_ACP_BIND=1`
- 默认值：
- ACP 智能体：`claude`
- 合成渠道：类似 Slack 私信风格的会话上下文
- 合成渠道：Slack 私信风格的会话上下文
- ACP 后端：`acpx`
- 覆盖项：
- `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
- `OPENCLAW_LIVE_ACP_BIND_AGENT=codex`
- `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@<version>'`
- 说明：
- 此测试通道使用 Gateway 网关 `chat.send` 界面，并带有仅管理员可用的合成 originating-route 字段，因此测试可以附加消息渠道上下文，而无需伪装为对外投递。
- 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会对所选 ACP harness 智能体使用内置 `acpx` 插件中的内建智能体注册表。
- 该通道使用 Gateway 网关 `chat.send` 接口，并附带仅限管理员使用的合成 originating-route 字段，因此测试可以附着消息渠道上下文，而无需假装真的对外投递。
- 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用内置 `acpx` 插件的内建智能体注册表来选择 ACP harness 智能体。
示例：
@ -330,14 +292,14 @@ pnpm test:docker:live-acp-bind
Docker 说明：
- Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。
- 它会读取 `~/.profile`，将匹配的 CLI 认证材料暂存到容器内，把 `acpx` 安装到可写 npm 前缀中，然后在缺失时安装请求的实时 CLI（`@anthropic-ai/claude-code` 或 `@openai/codex`）。
- 在 Docker 内，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，这样 `acpx` 能让从 profile 中读取到的提供商环境变量继续提供给子 harness CLI。
- 它会读取 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，把 `acpx` 安装到可写的 npm prefix 中，然后在缺失时安装所请求的 live CLI（`@anthropic-ai/claude-code` 或 `@openai/codex`）。
- 在 Docker 内，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，从而使 acpx 保留来自已读取 profile 的提供商环境变量，并传递给子 harness CLI。
### 推荐的实时配方
### 推荐的 live 配方
范围窄、明确的允许名单最快，也最不容易出问题：
缩小范围、显式的 allowlist 最快也最不容易不稳定：
- 单模型，直连（无 Gateway 网关）：
- 单模型，direct（无 Gateway 网关）：
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts`
- 单模型，Gateway 网关冒烟：
@ -353,19 +315,15 @@ Docker 说明：
说明：
- `google/...` 使用 Gemini API（API 密钥）。
- `google-antigravity/...` 使用 Antigravity OAuth bridge（Cloud Code Assist 风格的智能体端点）。
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立认证 + 工具行为差异）。
- Gemini API 与 Gemini CLI：
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / profile 认证）；这也是大多数用户说“Gemini”时的含义。
- CLI：OpenClaw 会调用本地 `gemini` 二进制；它有自己的认证方式，而且行为可能不同（流式传输/工具支持/版本偏差）。
- `google-antigravity/...` 使用 Antigravity OAuth bridge（类似 Cloud Code Assist 风格的智能体端点）。
## 实时：模型矩阵（我们覆盖什么）
## Live：模型矩阵（我们覆盖什么）
没有固定的“CI 模型列表”（实时测试是按需启用的），但以下是**推荐**在有密钥的开发机器上定期覆盖的模型。
没有固定的“CI 模型列表”（live 是可选启用的），但以下这些是**推荐**在带密钥的开发机器上定期覆盖的模型。
### 现代冒烟集（工具调用 + 图像）
这是我们预期应持续保持可用的“常用模型”运行集：
这是我们期望持续可用的“常见模型”运行集：
- OpenAI（非 Codex）：`openai/gpt-5.4`（可选：`openai/gpt-5.4-mini`）
- OpenAI Codex：`openai-codex/gpt-5.4`
@ -388,64 +346,64 @@ Docker 说明：
- Z.AI（GLM）：`zai/glm-4.7`
- MiniMax：`minimax/MiniMax-M2.7`
可选的额外覆盖（最好有）：
可选的额外覆盖（有的话更好）：
- xAI：`xai/grok-4`（或最新可用版本）
- Mistral：`mistral/`…（选择一个你已启用且支持工具的模型）
- Cerebras：`cerebras/`…（如果你有权限）
- Mistral：`mistral/`…（选择一个你已启用、支持 “tools” 的模型）
- Cerebras：`cerebras/`…（如果你有访问权限）
- LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式）
### Vision：图像发送（附件 → 多模态消息）
### Vision：发送图像（附件 → 多模态消息）
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude/Gemini/OpenAI 支持视觉的变体等），以触发图像探针。
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude/Gemini/OpenAI 的视觉变体等），以触发图像探测。
### 聚合器 / 替代 Gateway 网关
如果你已启用密钥，我们也支持通过以下方式测试：
如果你启用了相应密钥，我们也支持通过以下方式测试：
- OpenRouter：`openrouter/...`（数百种模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选）
- OpenCode：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）
- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 找出支持 tool+image 的候选项）
- OpenCode：`opencode/...` 用于 Zen，`opencode-go/...` 用于 Go（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）
你还可以在实时矩阵中加入更多提供商（如果你有凭证/配置）：
如果你有凭证/配置，还可以把更多提供商加入 live 矩阵：
- 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot`
- 通过 `models.providers`（自定义端点）：`minimax`（云/API），以及任意兼容 OpenAI/Anthropic 的代理（LM Studio、vLLM、LiteLLM 等）
- 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot`
- 通过 `models.providers`（自定义端点）：`minimax`（云/API），以及任何兼容 OpenAI/Anthropic 的代理（LM Studio、vLLM、LiteLLM 等）
提示：不要试图在文档里硬编码“所有模型”。权威列表始终是你机器上 `discoverModels(...)` 的返回结果 + 可用密钥。
提示：不要试图在文档里硬编码“所有模型”。权威列表始终是你机器上 `discoverModels(...)` 的返回结果 + 当前可用的密钥。
## 凭证（切勿提交）
## 凭证（绝不要提交）
实时测试发现凭证的方式与 CLI 相同。实际含义如下：
Live 测试发现凭证的方式与 CLI 相同。实际含义如下：
- 如果 CLI 可用，实时测试通常也应能找到相同密钥。
- 如果某个实时测试提示“没有凭证”，请按调试 `openclaw models list` / 模型选择的相同方式调试。
- 如果 CLI 可用，live 测试应该能找到相同的密钥。
- 如果 live 测试提示“无凭证”，请像调试 `openclaw models list` / 模型选择那样调试。
- 按智能体划分的认证 profile：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试中 “profile keys” 的含义）
- 每个智能体的认证 profile：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是 live 测试中 “profile keys” 的含义）
- 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- 旧版状态目录：`~/.openclaw/credentials/`（若存在，会复制到暂存的实时测试 home 中，但它不是主 profile-key 存储）
- 本地实时运行默认会复制当前有效配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录到临时测试 home；在这份暂存配置中，会去掉 `agents.*.workspace` / `agentDir` 路径覆盖，以保证探针不会落到你的真实主机工作区。
- 旧版状态目录：`~/.openclaw/credentials/`（若存在，会被复制到暂存的 live home 中，但这不是主 profile-key 存储）
- 本地 live 运行默认会把当前配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录复制到一个临时测试 home 中；在这个暂存配置里，`agents.*.workspace` / `agentDir` 路径覆盖会被移除，从而保证探测不会触及你真实宿主机工作区。
如果你想依赖环境变量密钥（例如导出在你的 `~/.profile` 中），请在 `source ~/.profile` 后运行本地测试，或者使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载进容器）。
如果你想依赖环境变量密钥（例如导出在你的 `~/.profile` 中），请在本地测试前运行 `source ~/.profile`，或者使用下面的 Docker 运行器（它们可以把 `~/.profile` 挂载进容器）。
## Deepgram 实时测试（音频转录）
## Deepgram live（音频转写）
- 测试：`src/media-understanding/providers/deepgram/audio.live.test.ts`
- 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts`
## BytePlus（国际版） 编码计划实时测试
## BytePlus 编码计划 live
- 测试：`src/agents/byteplus.live.test.ts`
- 启用：`BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts`
- 可选模型覆盖：`BYTEPLUS_CODING_MODEL=ark-code-latest`
## 图像生成实时测试
## 图像生成 live
- 测试：`src/image-generation/runtime.live.test.ts`
- 命令：`pnpm test:live src/image-generation/runtime.live.test.ts`
- 范围：
- 枚举每个已注册的图像生成提供商插件
- 在探测前从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量
- 默认优先使用实时/环境变量 API 密钥，而不是存储的认证 profile，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实 shell 凭证
- 默认优先使用 live/env API 密钥，而不是存储的 auth profile，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实 shell 凭证
- 跳过没有可用认证/profile/模型的提供商
- 通过共享运行时能力运行标准图像生成变体：
- `google:flash-generate`
@ -460,133 +418,156 @@ Docker 说明：
- `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"`
- 可选认证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用 profile 存储认证，忽略仅环境变量覆盖
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用 profile 存储认证，并忽略仅环境变量的覆盖
## Docker 运行器（可选的“在 Linux 中能工作”检查）
## Docker 运行器（可选的“在 Linux 中可运行”检查）
这些 Docker 运行器分成两类：
这些 Docker 运行器分为两类：
- 实时模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 仅在仓库 Docker 镜像中运行与其匹配的 profile-key 实时测试文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），并挂载你的本地配置目录和工作区（如果挂载了 `~/.profile`，也会读取它）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。
- Docker 实时运行器默认使用较小的冒烟上限，这样完整的 Docker 扫描仍然可行：
- Live-model 运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像中运行各自匹配的 profile-key live 文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），并挂载你的本地配置目录和工作区（如果已挂载，也会读取 `~/.profile`）。相应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。
- Docker live 运行器默认有更小的冒烟上限，以便完整的 Docker 扫查仍然实用：
`test:docker:live-models` 默认设置 `OPENCLAW_LIVE_MAX_MODELS=12`，并且
`test:docker:live-gateway` 默认设置 `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、
`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、
`OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` 和
`OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你明确想要更大范围的穷举扫描时，再覆盖这些环境变量。
- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次实时 Docker 镜像，然后在两个实时 Docker 通道中复用它。
- 容器冒烟运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels` 和 `test:docker:plugins` 会启动一个或多个真实容器，并验证更高层的集成路径。
`OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你
明确想进行更大范围的穷举扫描时，可覆盖这些环境变量。
- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次 live Docker 镜像，然后在两个 live Docker 通道中复用它。
- 容器冒烟运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels` 和 `test:docker:plugins` 会启动一个或多个真实容器，并验证更高层级的集成路径。
实时模型 Docker 运行器还会只 bind-mount 所需的 CLI 认证 home（如果运行未缩小范围，则会挂载所有支持的项），然后在运行前将它们复制到容器 home 中，以便外部 CLI OAuth 刷新令牌，而不会修改主机上的认证存储：
Live-model Docker 运行器还会只 bind-mount 所需的 CLI 认证 home（如果运行未缩小范围，则挂载所有受支持的），然后在运行前将它们复制到容器 home 中，这样外部 CLI OAuth 就可以刷新令牌，而不会修改宿主机认证存储：
- Direct model：`pnpm test:docker:live-models`（脚本：`scripts/test-live-models-docker.sh`）
- Direct models：`pnpm test:docker:live-models`（脚本：`scripts/test-live-models-docker.sh`）
- ACP 绑定冒烟：`pnpm test:docker:live-acp-bind`（脚本：`scripts/test-live-acp-bind-docker.sh`）
- CLI 后端冒烟：`pnpm test:docker:live-cli-backend`（脚本：`scripts/test-live-cli-backend-docker.sh`）
- Gateway 网关 + dev 智能体：`pnpm test:docker:live-gateway`（脚本：`scripts/test-live-gateway-models-docker.sh`）
- Open WebUI 实时冒烟：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`）
- Open WebUI live 冒烟：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`）
- 新手引导向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`）
- Gateway 网关网络（两个容器，WS 认证 + health）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`）
- Gateway 网关网络（两个容器，WS 认证 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`）
- MCP 渠道桥接（带预置数据的 Gateway 网关 + stdio bridge + 原始 Claude notification-frame 冒烟）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`）
- 插件（安装冒烟 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`）
实时模型 Docker 运行器还会以只读方式 bind-mount 当前检出，并将其暂存到容器内的临时工作目录中。这样既能保持运行时镜像精简，又能让 Vitest 针对你精确的本地源代码/配置运行。
它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 Gateway 网关实时探针就不会在容器内启动真实的 Telegram/Discord 等渠道 worker。
`test:docker:live-models` 仍然运行 `pnpm test:live`，因此当你需要缩小或排除该 Docker 通道中的 Gateway 网关实时覆盖时，也请一并传入 `OPENCLAW_LIVE_GATEWAY_*`。
`test:docker:openwebui` 是更高层级的兼容性冒烟：它会启动一个启用了 OpenAI 兼容 HTTP 端点的 OpenClaw Gateway 网关容器，针对该网关再启动一个固定版本的 Open WebUI 容器，通过 Open WebUI 登录，验证 `/api/models` 暴露 `openclaw/default`，然后通过 Open WebUI 的 `/api/chat/completions` 代理发送真实聊天请求。
第一次运行可能明显更慢，因为 Docker 可能需要拉取 Open WebUI 镜像，而 Open WebUI 也可能需要完成自身的冷启动设置。
这个测试通道需要可用的实时模型密钥，而 `OPENCLAW_PROFILE_FILE`（默认是 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。
成功运行会打印一小段 JSON 载荷，例如 `{ "ok": true, "model": "openclaw/default", ... }`。
`test:docker:mcp-channels` 是有意设计成确定性的，不需要真实的 Telegram、Discord 或 iMessage 账号。它会启动一个带预置数据的 Gateway 网关容器，启动第二个容器来运行 `openclaw mcp serve`，然后通过真实 stdio MCP bridge 验证路由会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。通知检查会直接检查原始 stdio MCP 帧，因此这个冒烟测试验证的是 bridge 实际发出了什么，而不仅仅是某个特定客户端 SDK 恰好暴露了什么。
Live-model Docker 运行器还会将当前 checkout 以只读方式 bind-mount，
并将其暂存到容器内的一个临时工作目录中。这样既能保持运行时
镜像精简，又仍然能针对你精确的本地源码/配置运行 Vitest。
它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 Gateway 网关 live 探测就不会在容器内
启动真实的 Telegram/Discord/等渠道 worker。
`test:docker:live-models` 仍然会运行 `pnpm test:live`，因此当你需要缩小范围或排除该 Docker 通道中的
Gateway 网关 live 覆盖时，也请同时传入
`OPENCLAW_LIVE_GATEWAY_*`。
`test:docker:openwebui` 是更高层级的兼容性冒烟：它会启动一个
启用了 OpenAI 兼容 HTTP 端点的 OpenClaw Gateway 网关容器，
再针对该 Gateway 网关启动一个固定版本的 Open WebUI 容器，通过
Open WebUI 完成登录，验证 `/api/models` 会暴露 `openclaw/default`，然后通过
Open WebUI 的 `/api/chat/completions` 代理发送一条真实聊天请求。
第一次运行可能会明显更慢，因为 Docker 可能需要拉取
Open WebUI 镜像，而 Open WebUI 也可能需要完成自己的冷启动设置。
这个通道需要可用的 live 模型密钥，而 `OPENCLAW_PROFILE_FILE`
（默认是 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。
成功运行会打印一小段 JSON 负载，例如 `{ "ok": true, "model":
"openclaw/default", ... }`。
`test:docker:mcp-channels` 是有意设计成确定性的，不需要
真实的 Telegram、Discord 或 iMessage 账号。它会启动一个带预置数据的 Gateway 网关
容器，再启动第二个容器来运行 `openclaw mcp serve`，然后
验证路由后的会话发现、transcript 读取、附件元数据、
实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 +
权限通知在真实 stdio MCP bridge 上的表现。通知检查
会直接检查原始 stdio MCP frame，因此这个冒烟测试验证的是 bridge
实际发出的内容，而不仅仅是某个特定客户端 SDK 恰好暴露出来的内容。
手动 ACP 自然语言线程冒烟（非 CI）：
- `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...`
- 请为回归/调试工作流保留此脚本。它未来可能还会再次用于 ACP 线程路由验证，因此不要删除。
- 保留此脚本用于回归/调试工作流。它未来仍可能用于 ACP 线程路由验证，因此不要删除它。
常用环境变量：
- `OPENCLAW_CONFIG_DIR=...`（默认：`~/.openclaw`）挂载到 `/home/node/.openclaw`
- `OPENCLAW_WORKSPACE_DIR=...`（默认：`~/.openclaw/workspace`）挂载到 `/home/node/.openclaw/workspace`
- `OPENCLAW_PROFILE_FILE=...`（默认：`~/.profile`）挂载到 `/home/node/.profile`，并在运行测试前读取
- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于 Docker 内缓存 CLI 安装
- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于缓存 Docker 内部的 CLI 安装
- `$HOME` 下的外部 CLI 认证目录/文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...`
- 默认目录：`.codex`、`.minimax`
- 默认文件：`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json`
- 缩小范围的提供商运行仅挂载由 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的所需目录/文件
- 可通过 `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none` 或逗号列表（如 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`）手动覆盖
- 已缩小提供商范围的运行只会挂载从 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的必需目录/文件
- 可通过 `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none` 或类似 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` 的逗号列表手动覆盖
- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用于缩小运行范围
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` 用于过滤容器内提供商
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 确保凭证来自 profile 存储（而非环境变量）
- `OPENCLAW_OPENWEBUI_MODEL=...` 选择在 Open WebUI 冒烟中由 Gateway 网关暴露的模型
- `OPENCLAW_OPENWEBUI_PROMPT=...` 覆盖 Open WebUI 冒烟中用于 nonce 检查的提示
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` 用于在容器内筛选提供商
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 确保凭证来自 profile 存储（而不是环境变量）
- `OPENCLAW_OPENWEBUI_MODEL=...` 选择 Gateway 网关为 Open WebUI 冒烟暴露的模型
- `OPENCLAW_OPENWEBUI_PROMPT=...` 覆盖 Open WebUI 冒烟使用的 nonce 检查提示词
- `OPENWEBUI_IMAGE=...` 覆盖固定的 Open WebUI 镜像标签
## 文档完整性检查
编辑文档后运行文档检查：`pnpm check:docs`。
如果还需要完整的 Mintlify 锚点校验（包括页内标题检查），运行：`pnpm docs:check-links:anchors`。
当你还需要进行页内标题检查时，运行完整的 Mintlify anchor 验证：`pnpm docs:check-links:anchors`。
## 离线回归（CI 安全）
这些是“不依赖真实提供商”的“真实流水线”回归：
这些是在没有真实提供商的情况下进行的“真实流水线”回归测试：
- Gateway 网关工具调用（模拟 OpenAI，真实 Gateway 网关 + 智能体循环）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”）
- Gateway 网关向导（WS `wizard.start`/`wizard.next`，强制写入配置 + auth）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”）
- Gateway 网关工具调用（mock OpenAI，真实 Gateway 网关 + 智能体循环）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”）
- Gateway 网关向导（WS `wizard.start`/`wizard.next`，强制写入配置 + 认证）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”）
## 智能体可靠性评估（Skills）
我们已经有一些 CI 安全的测试，它们的行为类似“智能体可靠性评估”：
我们已经有一些 CI 安全的测试，行为上类似“智能体可靠性评估”：
- 通过真实 Gateway 网关 + 智能体循环执行模拟工具调用（`src/gateway/gateway.test.ts`）。
- 验证会话接线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。
- 通过真实的 Gateway 网关 + 智能体循环进行 mock 工具调用（`src/gateway/gateway.test.ts`）。
- 验证会话接线与配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。
对于 Skills（参见 [Skills](/zh-CN/tools/skills)）目前仍缺少的是：
对于 Skills（见 [Skills](/zh-CN/tools/skills)），目前仍缺少：
- **决策能力：** 当提示中列出 Skills 时，智能体是否会选择正确的 Skill（或避免选择无关项）？
- **合规性：** 智能体是否会在使用前读取 `SKILL.md`，并遵循所需步骤/参数？
- **工作流契约：** 断言工具顺序、会话历史延续和沙箱边界的多轮场景。
- **决策能力：** 当提示词中列出了 skill 时，智能体是否会选择正确的 skill（或避开无关的 skill）？
- **合规性：** 智能体在使用前是否会读取 `SKILL.md`，并遵循要求的步骤/参数？
- **工作流契约：** 断言工具顺序、会话历史延续以及沙箱边界的多轮场景。
未来的评估应优先保持确定性：
- 一个使用模拟提供商的场景运行器，用于断言工具调用 + 顺序、Skill 文件读取和会话接线。
- 一小组聚焦 Skill 的场景（使用 vs 避免、门控、提示注入）。
- 只有在 CI 安全套件到位之后，才加入可选的实时评估（按需启用、由环境变量控制）。
- 一个使用 mock 提供商的场景运行器，用于断言工具调用 + 顺序、skill 文件读取以及会话接线。
- 一小组聚焦 skill 的场景（应使用 vs 应避免、门控、提示注入）。
- 可选的 live 评估（选择性启用、由环境变量控制）应在 CI 安全套件就位后再添加。
## 契约测试（插件和渠道形状）
## Contract 测试（插件和渠道形状）
契约测试会验证每个已注册插件和渠道都符合其接口契约。它们会遍历所有已发现的插件，并运行一套关于结构和行为的断言。默认的 `pnpm test` 单元测试通道会有意跳过这些共享接缝和冒烟文件；当你修改共享渠道或提供商表面时，请显式运行契约命令。
Contract 测试用于验证每个已注册插件和渠道都符合其
接口契约。它们会遍历所有已发现插件，并运行一组
形状和行为断言。默认的 `pnpm test` unit 通道会有意
跳过这些共享 seam 和 smoke 文件；当你修改共享渠道或提供商接口时，
请显式运行这些 contract 命令。
### 命令
- 所有契约：`pnpm test:contracts`
- 仅渠道契约：`pnpm test:contracts:channels`
- 仅提供商契约：`pnpm test:contracts:plugins`
- 所有 contract：`pnpm test:contracts`
- 仅渠道 contract：`pnpm test:contracts:channels`
- 仅提供商 contract：`pnpm test:contracts:plugins`
### 渠道契约
### 渠道 contract
位于 `src/channels/plugins/contracts/*.contract.test.ts`：
- **plugin** - 基本插件形状（id、name、capabilities）
- **setup** - 设置向导契约
- **session-binding** - 会话绑定行为
- **outbound-payload** - 消息载荷结构
- **outbound-payload** - 消息负载结构
- **inbound** - 入站消息处理
- **actions** - 渠道动作处理器
- **actions** - 渠道操作处理器
- **threading** - 线程 ID 处理
- **directory** - 目录/成员列表 API
- **group-policy** - 群组策略强制执行
### 提供商状态契约
### 提供商状态 contract
位于 `src/plugins/contracts/*.contract.test.ts`。
- **status** - 渠道状态探针
- **status** - 渠道状态探测
- **registry** - 插件注册表形状
### 提供商契约
### 提供商 contract
位于 `src/plugins/contracts/*.contract.test.ts`：
- **auth** - 认证流程契约
- **auth** - 认证流契约
- **auth-choice** - 认证选项/选择
- **catalog** - 模型目录 API
- **discovery** - 插件发现
@ -601,17 +582,17 @@ Docker 说明：
- 添加或修改渠道或提供商插件之后
- 重构插件注册或发现逻辑之后
契约测试会在 CI 中运行，不需要真实 API 密钥。
Contract 测试会在 CI 中运行，并且不需要真实 API 密钥。
## 添加回归测试（指南）
## 添加回归测试（指导）
当你修复一个在实时测试中发现的提供商/模型问题时：
当你修复了一个在 live 中发现的提供商/模型问题时：
- 如果可能，添加一个 CI 安全的回归测试（模拟/存根提供商，或捕获精确的请求形状转换）
- 如果问题本质上只能在实时环境中出现（速率限制、认证策略），请让实时测试保持范围窄，并通过环境变量按需启用
- 优先瞄准能捕获该缺陷的最小层级：
- 提供商请求转换/回放缺陷 → direct models test
- Gateway 网关会话/历史/工具流水线缺陷 → gateway 实时冒烟或 CI 安全的 gateway mock 测试
- SecretRef 遍历保护规则：
- 如果可能，添加一个 CI 安全的回归测试（mock/stub 提供商，或者捕获精确的请求形状转换）
- 如果它本质上只能在 live 中复现（限流、认证策略），请保持 live 测试足够窄，并通过环境变量选择性启用
- 优先定位到能捕获该 Bug 的最小层：
- 提供商请求转换/重放 Bug → direct models 测试
- Gateway 网关会话/历史/工具流水线 Bug → Gateway 网关 live 冒烟或 CI 安全的 Gateway 网关 mock 测试
- SecretRef 遍历防护：
- `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言遍历段 exec id 会被拒绝。
- 如果你在 `src/secrets/target-registry-data.ts` 中添加了新的 `includeInPlan` SecretRef 目标家族，请更新该测试中的 `classifyTargetClass`。该测试会有意在遇到未分类的目标 id 时失败，以防新的类别被悄悄跳过。
- 如果你在 `src/secrets/target-registry-data.ts` 中新增了一个 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。该测试会在出现未分类的目标 id 时故意失败，以防新的类别被悄悄跳过。

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

File diff suppressed because it is too large Load Diff

193
docs/zh-CN/plugins/building-plugins.md
View File

@ -4,59 +4,48 @@ read_when:
- 你需要一个用于插件开发的快速开始指南
- 你正在为 OpenClaw 添加新的渠道、提供商、工具或其他能力
sidebarTitle: Getting Started
summary: 在几分钟内创建你的第一个 OpenClaw 插件
summary: 几分钟内创建你的第一个 OpenClaw 插件
title: 构建插件
x-i18n:
generated_at: "2026-04-05T08:39:05Z"
generated_at: "2026-04-05T18:13:47Z"
model: gpt-5.4
provider: openai
source_hash: 26e780d3f04270b79d1d8f8076d6c3c5031915043e78fb8174be921c6bdd60c9
source_hash: 677da2cfba6706bd502fc055169072eb82d2d3baa5a78f28eb520f821caa3773
source_path: plugins/building-plugins.md
workflow: 15
---
# 构建插件
插件可为 OpenClaw 扩展新能力：渠道、模型提供商、
语音、实时转写、实时语音、媒体理解、图像生成、
视频生成、网页抓取、网页搜索、智能体工具，或任意
组合。
插件可通过新增能力来扩展 OpenClaw：渠道、模型提供商、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或以上任意组合。
你不需要将你的插件添加到 OpenClaw 仓库中。发布到
[ClawHub](/tools/clawhub) 或 npm，用户即可使用
`openclaw plugins install <package-name>` 进行安装。OpenClaw 会优先尝试 ClawHub，
并自动回退到 npm。
你不需要把你的插件添加到 OpenClaw 仓库中。发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm 后，用户可使用 `openclaw plugins install <package-name>` 安装。OpenClaw 会先尝试 ClawHub，并在需要时自动回退到 npm。
## 前提条件
## 前置条件
- Node >= 22 和一个包管理器（npm 或 pnpm）
- Node >= 22，以及一个包管理器（npm 或 pnpm）
- 熟悉 TypeScript（ESM）
- 对于仓库内插件：已克隆仓库并完成 `pnpm install`
## 什么类型的插件？
## 这是什么类型的插件？
<CardGroup cols={3}>
<Card title="渠道插件" icon="messages-square" href="/plugins/sdk-channel-plugins">
<Card title="渠道插件" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
将 OpenClaw 连接到消息平台（Discord、IRC 等）
</Card>
<Card title="提供商插件" icon="cpu" href="/plugins/sdk-provider-plugins">
添加一个模型提供商（LLM、代理或自定义端点）
<Card title="提供商插件" icon="cpu" href="/zh-CN/plugins/sdk-provider-plugins">
添加模型提供商（LLM、代理或自定义端点）
</Card>
<Card title="工具 / hook 插件" icon="wrench">
注册智能体工具、事件 hooks 或服务 —— 继续阅读下文
</Card>
</CardGroup>
如果某个渠道插件是可选的，并且在新手引导 / 设置运行时
可能尚未安装，请使用来自
`openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface(...)`。
它会生成一个设置适配器 + 向导组合，
用于声明安装要求，并在插件安装完成前对真实配置写入采取默认拒绝策略。
如果某个渠道插件是可选的，并且在新手引导 / 设置运行时可能尚未安装，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装完成前对实际配置写入采取失败关闭策略。
## 快速开始：工具插件
本演练将创建一个用于注册智能体工具的最小插件。渠道
和提供商插件有上方链接中的专门指南。
本演练将创建一个最小插件，用于注册一个智能体工具。渠道插件和提供商插件有上方链接的专用指南。
<Steps>
<Step title="创建包和清单">
@ -93,9 +82,7 @@ x-i18n:
```
</CodeGroup>
每个插件都需要一个清单，即使没有配置也是如此。完整 schema 请参见
[Manifest](/plugins/manifest)。规范的 ClawHub
发布片段位于 `docs/snippets/plugin-publish/` 中。
每个插件都需要一个清单，即使没有配置也一样。完整模式请参见 [Manifest](/zh-CN/plugins/manifest)。规范的 ClawHub 发布代码片段位于 `docs/snippets/plugin-publish/`。
</Step>
@ -123,9 +110,7 @@ x-i18n:
});
```
`definePluginEntry` 用于非渠道插件。对于渠道，请使用
`defineChannelPluginEntry` —— 参见 [渠道插件](/plugins/sdk-channel-plugins)。
有关完整的入口点选项，请参见 [入口点](/plugins/sdk-entrypoints)。
`definePluginEntry` 用于非渠道插件。对于渠道，请使用 `defineChannelPluginEntry` —— 参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。完整入口点选项请参见 [入口点](/zh-CN/plugins/sdk-entrypoints)。
</Step>
@ -139,8 +124,7 @@ x-i18n:
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
```
对于像
`@myorg/openclaw-my-plugin` 这样的裸包规范，OpenClaw 也会先检查 ClawHub，再检查 npm。
对于像 `@myorg/openclaw-my-plugin` 这样的裸包规范，OpenClaw 也会在 npm 之前先检查 ClawHub。
**仓库内插件：** 放在内置插件工作区树下 —— 会自动发现。
@ -153,60 +137,53 @@ x-i18n:
## 插件能力
单个插件可以通过 `api` 对象注册任意数量的能力：
单个插件可通过 `api` 对象注册任意数量的能力：
| 能力 | 注册方法 | 详细指南 |
| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------- |
| 文本推理（LLM） | `api.registerProvider(...)` | [提供商插件](/plugins/sdk-provider-plugins) |
| CLI 推理后端 | `api.registerCliBackend(...)` | [CLI 后端](/gateway/cli-backends) |
| 渠道 / 消息 | `api.registerChannel(...)` | [渠道插件](/plugins/sdk-channel-plugins) |
| 语音（TTS/STT） | `api.registerSpeechProvider(...)` | [提供商插件](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 实时转写 | `api.registerRealtimeTranscriptionProvider(...)` | [提供商插件](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | [提供商插件](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [提供商插件](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 图像生成 | `api.registerImageGenerationProvider(...)` | [提供商插件](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 视频生成 | `api.registerVideoGenerationProvider(...)` | [提供商插件](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 网页抓取 | `api.registerWebFetchProvider(...)` | [提供商插件](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 网页搜索 | `api.registerWebSearchProvider(...)` | [提供商插件](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 智能体工具 | `api.registerTool(...)` | 下文 |
| 自定义命令 | `api.registerCommand(...)` | [入口点](/plugins/sdk-entrypoints) |
| 事件 hooks | `api.registerHook(...)` | [入口点](/plugins/sdk-entrypoints) |
| HTTP 路由 | `api.registerHttpRoute(...)` | [内部机制](/plugins/architecture#gateway-http-routes) |
| CLI 子命令 | `api.registerCli(...)` | [入口点](/plugins/sdk-entrypoints) |
| 能力 | 注册方法 | 详细指南 |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| 文本推理（LLM） | `api.registerProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins) |
| 渠道 / 消息传递 | `api.registerChannel(...)` | [渠道插件](/zh-CN/plugins/sdk-channel-plugins) |
| 语音（TTS/STT） | `api.registerSpeechProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 图像生成 | `api.registerImageGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 视频生成 | `api.registerVideoGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 网页抓取 | `api.registerWebFetchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 网页搜索 | `api.registerWebSearchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 智能体工具 | `api.registerTool(...)` | 下文 |
| 自定义命令 | `api.registerCommand(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
| 事件 hooks | `api.registerHook(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
| HTTP 路由 | `api.registerHttpRoute(...)` | [内部机制](/zh-CN/plugins/architecture#gateway-http-routes) |
| CLI 子命令 | `api.registerCli(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
有关完整的注册 API，请参见 [SDK 概览](/plugins/sdk-overview#registration-api)。
完整注册 API 请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。
如果你的插件注册了自定义 gateway RPC 方法，请将它们保留在
插件专属前缀下。核心管理命名空间（`config.*`、
`exec.approvals.*`、`wizard.*`、`update.*`）保持保留状态，并且始终解析到
`operator.admin`，即使插件请求了更窄的作用域也是如此。
如果你的插件注册了自定义 Gateway RPC 方法，请将它们放在插件专属前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保留，并且总是解析到 `operator.admin`，即使插件请求了更窄的作用域也是如此。
需要注意的 hook 守卫语义：
需要注意的 hook 防护语义：
- `before_tool_call`：`{ block: true }` 是终止性结果，并会停止更低优先级的处理器。
- `before_tool_call`：`{ block: false }` 会被视为未作决定。
- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 批准浮层、Telegram 按钮、Discord 交互或任意渠道上的 `/approve` 命令提示用户批准。
- `before_install`：`{ block: true }` 是终止性结果，并会停止更低优先级的处理器。
- `before_install`：`{ block: false }` 会被视为未作决定。
- `message_sending`：`{ cancel: true }` 是终止性结果，并会停止更低优先级的处理器。
- `message_sending`：`{ cancel: false }` 会被视为未作决定。
- `before_tool_call`：`{ block: true }` 是终结结果，并会停止优先级更低的处理器。
- `before_tool_call`：`{ block: false }` 会被视为没有作出决定。
- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互，或任意渠道上的 `/approve` 命令提示用户审批。
- `before_install`：`{ block: true }` 是终结结果，并会停止优先级更低的处理器。
- `before_install`：`{ block: false }` 会被视为没有作出决定。
- `message_sending`：`{ cancel: true }` 是终结结果，并会停止优先级更低的处理器。
- `message_sending`：`{ cancel: false }` 会被视为没有作出决定。
`/approve` 命令会处理 exec 和插件批准，并带有有界回退：当找不到 exec approval id 时，OpenClaw 会使用同一 id 通过插件批准重试。插件批准转发可通过配置中的 `approvals.plugin` 独立设置。
`/approve` 命令会同时处理 exec 审批和插件审批，并带有有界回退机制：当找不到某个 exec 审批 id 时，OpenClaw 会使用同一个 id 重试插件审批。插件审批转发可以通过配置中的 `approvals.plugin` 独立配置。
如果自定义批准流程需要检测同样的有界回退场景，
请优先使用来自 `openclaw/plugin-sdk/error-runtime` 的 `isApprovalNotFoundError`，
而不是手动匹配 approval-expiry 字符串。
如果自定义审批流程需要检测这个相同的有界回退场景，优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不是手动匹配审批过期字符串。
详情请参见 [SDK 概览 hook 决策语义](/plugins/sdk-overview#hook-decision-semantics)。
详情请参见 [SDK 概览 hook 决策语义](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
## 注册智能体工具
工具是 LLM 可调用的类型化函数。它们可以是必需的（始终
可用），也可以是可选的（用户选择启用）：
工具是 LLM 可调用的类型化函数。它们可以是必需的（始终可用），也可以是可选的（用户主动选择启用）：
```typescript
register(api) {
// Required tool — always available
// 必需工具 —— 始终可用
api.registerTool({
name: "my_tool",
description: "Do a thing",
@ -216,7 +193,7 @@ register(api) {
},
});
// Optional tool — user must add to allowlist
// 可选工具 —— 用户必须添加到 allowlist
api.registerTool(
{
name: "workflow_tool",
@ -239,9 +216,9 @@ register(api) {
}
```
- 工具名称不得与核心工具冲突（冲突项会被跳过）
- 工具名称不能与核心工具冲突（冲突项会被跳过）
- 对于有副作用或需要额外二进制依赖的工具，请使用 `optional: true`
- 用户可以通过将插件 id 添加到 `tools.allow` 来启用某个插件中的全部工具
- 用户可通过将插件 id 添加到 `tools.allow` 来启用某个插件的所有工具
## 导入约定
@ -251,29 +228,23 @@ register(api) {
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
// Wrong: monolithic root (deprecated, will be removed)
// 错误：单体根路径（已弃用，将被移除）
import { ... } from "openclaw/plugin-sdk";
```
完整的子路径参考请参见 [SDK 概览](/plugins/sdk-overview)。
完整子路径参考请参见 [SDK 概览](/zh-CN/plugins/sdk-overview)。
在你的插件内部，请使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行
内部导入 —— 绝不要通过它自己的 SDK 路径导入你自己的插件。
在你的插件内部，请使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行内部导入 —— 绝不要通过其 SDK 路径导入你自己的插件。
对于提供商插件，请将提供商专属辅助函数保留在这些包根级
barrel 中，除非该边界确实是通用的。当前的内置示例包括：
对于提供商插件，除非该扩展点确实是通用的，否则应将提供商专属辅助函数保留在这些包根级 barrel 中。当前内置示例包括：
- Anthropic：Claude 流包装器以及 `service_tier` / beta 辅助函数
- Anthropic：Claude 流包装器，以及 `service_tier` / beta 辅助函数
- OpenAI：提供商构建器、默认模型辅助函数、实时提供商
- OpenRouter：提供商构建器以及新手引导 / 配置辅助函数
- OpenRouter：提供商构建器，以及新手引导 / 配置辅助函数
如果某个辅助函数只在一个内置提供商包内部有用，请将它保留在该
包根级边界上，而不要将其提升到 `openclaw/plugin-sdk/*` 中。
如果某个辅助函数只在一个内置提供商包内部有用，就应把它保留在该包根级扩展点上，而不是将其提升到 `openclaw/plugin-sdk/*` 中。
某些自动生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助边界仍然存在，
用于内置插件维护和兼容性，例如
`plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。请将这些视为保留
表面，而不是新第三方插件的默认模式。
某些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助扩展点仍然存在，用于内置插件维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。应将这些视为保留接口，而不是新第三方插件的默认模式。
## 提交前检查清单
@ -285,42 +256,42 @@ barrel 中，除非该边界确实是通用的。当前的内置示例包括：
<Check>测试通过（`pnpm test -- <bundled-plugin-root>/my-plugin/`）</Check>
<Check>`pnpm check` 通过（仓库内插件）</Check>
## Beta 发布测试
## Beta 版本测试
1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签看起来像 `v2026.3.N-beta.1`。你也可以为官方 OpenClaw X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以获取发布公告。
2. Beta 标签一出现，就尽快用它测试你的插件。稳定版发布前的窗口通常只有几个小时。
3. 测试后，在 Discord 频道 `plugin-forum` 中你插件对应的帖子里发送 `all good`，或者说明损坏了什么。如果你还没有帖子，请创建一个。
4. 如果出现问题，请创建或更新一个标题为 `Beta blocker: <plugin-name> - <summary>` 的 issue，并添加 `beta-blocker` 标签。将该 issue 链接贴到你的帖子中。
5. 向 `main` 提交一个标题为 `fix(<plugin-id>): beta blocker - <summary>` 的 PR，并在 PR 和你的 Discord 帖子中都链接该 issue。贡献者不能为 PR 添加标签，因此标题就是提供给维护者和自动化的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题仍可能随版本发布。维护者会在 Beta 测试期间关注这些帖子。
6. 沉默即表示绿色通过。如果你错过了这个窗口，你的修复很可能会进入下一个周期。
1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签形式类似 `v2026.3.N-beta.1`。你也可以为 OpenClaw 官方 X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以获取发布公告。
2. 在 beta 标签出现后尽快使用它测试你的插件。稳定版发布前的窗口通常只有几个小时。
3. 测试完成后，在 `plugin-forum` Discord 渠道中你的插件线程里发帖，说明是 `all good` 还是哪里出问题了。如果你还没有线程，请创建一个。
4. 如果出了问题，请创建或更新一个标题为 `Beta blocker: <plugin-name> - <summary>` 的 issue，并添加 `beta-blocker` 标签。把该 issue 链接发到你的线程中。
5. 向 `main` 提交一个标题为 `fix(<plugin-id>): beta blocker - <summary>` 的 PR，并在 PR 和你的 Discord 线程中都链接该 issue。贡献者无法给 PR 打标签，因此标题就是给维护者和自动化系统的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题则可能仍然随版本发布。维护者会在 beta 测试期间关注这些线程。
6. 没有消息就表示一切正常。如果你错过了窗口，你的修复很可能会在下一个周期落地。
## 后续步骤
<CardGroup cols={2}>
<Card title="渠道插件" icon="messages-square" href="/plugins/sdk-channel-plugins">
构建一个消息渠道插件
<Card title="渠道插件" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
构建消息渠道插件
</Card>
<Card title="提供商插件" icon="cpu" href="/plugins/sdk-provider-plugins">
构建一个模型提供商插件
<Card title="提供商插件" icon="cpu" href="/zh-CN/plugins/sdk-provider-plugins">
构建模型提供商插件
</Card>
<Card title="SDK 概览" icon="book-open" href="/plugins/sdk-overview">
导入映射和注册 API 参考
<Card title="SDK 概览" icon="book-open" href="/zh-CN/plugins/sdk-overview">
导入映射与注册 API 参考
</Card>
<Card title="运行时辅助函数" icon="settings" href="/plugins/sdk-runtime">
<Card title="运行时辅助函数" icon="settings" href="/zh-CN/plugins/sdk-runtime">
通过 api.runtime 使用 TTS、搜索、子智能体
</Card>
<Card title="测试" icon="test-tubes" href="/plugins/sdk-testing">
<Card title="测试" icon="test-tubes" href="/zh-CN/plugins/sdk-testing">
测试工具和模式
</Card>
<Card title="插件清单" icon="file-json" href="/plugins/manifest">
完整清单 schema 参考
<Card title="插件清单" icon="file-json" href="/zh-CN/plugins/manifest">
完整清单模式参考
</Card>
</CardGroup>
## 相关内容
- [插件架构](/plugins/architecture) — 内部架构深入解析
- [SDK 概览](/plugins/sdk-overview) — 插件 SDK 参考
- [Manifest](/plugins/manifest) — 插件清单格式
- [渠道插件](/plugins/sdk-channel-plugins) — 构建渠道插件
- [提供商插件](/plugins/sdk-provider-plugins) — 构建提供商插件
- [插件架构](/zh-CN/plugins/architecture) —— 内部架构深度解析
- [SDK 概览](/zh-CN/plugins/sdk-overview) —— 插件 SDK 参考
- [Manifest](/zh-CN/plugins/manifest) —— 插件清单格式
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) —— 构建渠道插件
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) —— 构建提供商插件

347
docs/zh-CN/plugins/manifest.md
View File

@ -1,62 +1,73 @@
---
read_when:
- 你正在构建一个 OpenClaw 插件
- 你需要发布插件配置 schema，或排查插件校验错误
- 你需要发布插件配置 schema，或调试插件校验错误
summary: 插件清单 + JSON schema 要求（严格配置校验）
title: Plugin Manifest
title: 插件清单
x-i18n:
generated_at: "2026-04-05T08:39:41Z"
generated_at: "2026-04-05T18:14:21Z"
model: gpt-5.4
provider: openai
source_hash: 702447ad39f295cfffd4214c3e389bee667d2f9850754f2e02e325dde8e4ac00
source_hash: 8781fcccef80de68036826833ef46d482e399cdad180bfd799dcc96cd1dfc845
source_path: plugins/manifest.md
workflow: 15
---
# Plugin Manifest（openclaw.plugin.json）
# 插件清单（`openclaw.plugin.json`）
本页仅适用于 **原生 OpenClaw 插件清单**。
有关兼容的 bundle 布局，请参见 [Plugin bundles](/plugins/bundles)。
关于兼容的 bundle 布局，请参见 [Plugin bundles](/zh-CN/plugins/bundles)。
兼容的 bundle 格式使用不同的清单文件：
- Codex bundle：`.codex-plugin/plugin.json`
- Claude bundle：`.claude-plugin/plugin.json` 或不带清单的默认 Claude 组件布局
- Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件
布局
- Cursor bundle：`.cursor-plugin/plugin.json`
OpenClaw 也会自动检测这些 bundle 布局，但它们不会按照此处描述的 `openclaw.plugin.json` schema 进行校验。
OpenClaw 也会自动检测这些 bundle 布局，但不会按照此处描述的
`openclaw.plugin.json` schema 对它们进行校验。
对于兼容 bundle，OpenClaw 当前会在布局符合 OpenClaw 运行时预期时，读取 bundle 元数据以及声明的 skill 根目录、Claude 命令根目录、Claude bundle `settings.json` 默认值、Claude bundle LSP 默认值，以及受支持的 hook 包。
对于兼容 bundle，OpenClaw 当前会在布局符合 OpenClaw 运行时预期时，
读取 bundle 元数据，以及声明的 skill 根目录、Claude 命令根目录、Claude bundle 的
`settings.json` 默认值、Claude bundle 的 LSP 默认值，以及受支持的 hook pack。
每个原生 OpenClaw 插件**必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用这个清单在**不执行插件代码**的情况下验证配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。
每个原生 OpenClaw 插件**必须**在 **插件根目录** 中提供一个 `openclaw.plugin.json`
文件。OpenClaw 使用该清单在**不执行插件代码的情况下**
校验配置。缺失或无效的清单会被视为
插件错误，并阻止配置校验。
完整插件系统指南请参见：[Plugins](/tools/plugin)。
有关原生能力模型和当前外部兼容性指南，请参见：
[Capability model](/plugins/architecture#public-capability-model)。
完整的插件系统指南请参见：[Plugins](/zh-CN/tools/plugin)。
关于原生能力模型和当前的外部兼容性指南，请参见：
[Capability model](/zh-CN/plugins/architecture#public-capability-model)。
## 这个文件的作用
`openclaw.plugin.json` 是 OpenClaw 在加载你的插件代码之前读取的元数据。
`openclaw.plugin.json` 是 OpenClaw 在加载你的
插件代码之前读取的元数据。
可用于：
它适用于：
- 插件身份
- 插件标识
- 配置校验
- 无需启动插件运行时即可获得的认证和新手引导元数据
- 应在插件运行时加载前解析的别名和自动启用元数据
- 应在运行时加载前自动激活插件的简写模型家族归属元数据
- 用于内置兼容接线和契约覆盖的静态能力归属快照
- 无需加载运行时即可合并到目录和校验界面的渠道专属配置元数据
- 无需启动插件运行时即可使用的认证和新手引导元数据
- 需要在插件运行时加载前解析的别名和自动启用元数据
- 需要在运行时加载前自动激活
插件的简写模型家族归属元数据
- 用于内置兼容性接线和
合同覆盖的静态能力归属快照
- 无需加载运行时即可合并到目录和校验
表面的渠道专用配置元数据
- 配置 UI 提示
不要用于：
不要将它用于：
- 注册运行时行为
- 声明代码入口点
- npm 安装元数据
这些内容属于你的插件代码和 `package.json`。
这些属于你的插件代码和 `package.json`。
## 最小示例
@ -83,7 +94,6 @@ OpenClaw 也会自动检测这些 bundle 布局，但它们不会按照此处描
"modelSupport": {
"modelPrefixes": ["router-"]
},
"cliBackends": ["openrouter-cli"],
"providerAuthEnvVars": {
"openrouter": ["OPENROUTER_API_KEY"]
},
@ -123,55 +133,54 @@ OpenClaw 也会自动检测这些 bundle 布局，但它们不会按照此处描
## 顶层字段参考
| 字段 | 必需 | 类型 | 含义 |
| ----------------------------------- | ---- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | 是 | `string` | 规范插件 id。这就是在 `plugins.entries.<id>` 中使用的 id。 |
| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 |
| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略它，或设置为任何非 `true` 的值，则插件默认保持禁用。 |
| `legacyPluginIds` | 否 | `string[]` | 会归一化到此规范插件 id 的旧版 id。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些 provider id 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明供 `plugins.slots.*` 使用的互斥插件类型。 |
| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于发现和配置校验。 |
| `providers` | 否 | `string[]` | 由此插件拥有的 provider id。 |
| `modelSupport` | 否 | `object` | 由清单拥有的简写模型家族元数据，用于在运行时加载前自动加载插件。 |
| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 |
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量 provider 认证环境变量元数据。 |
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选 provider 解析和简单 CLI 标志接线的轻量认证选项元数据。 |
| `contracts` | 否 | `object` | 用于 speech、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索及工具归属的静态内置能力快照。 |
| `channelConfigs` | 否 | `Record<string, object>` | 由清单拥有的渠道配置元数据，会在运行时加载前合并到发现和校验界面中。 |
| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 |
| `name` | 否 | `string` | 人类可读的插件名称。 |
| `description` | 否 | `string` | 显示在插件界面中的简短摘要。 |
| `version` | 否 | `string` | 仅供参考的插件版本。 |
| `uiHints` | 否 | `Record<string, object>` | 配置字段的 UI 标签、占位符和敏感性提示。 |
| 字段 | 必需 | 类型 | 含义 |
| ----------------------------------- | ---- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | 是 | `string` | 规范插件 id。这是 `plugins.entries.<id>` 中使用的 id。 |
| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 |
| `enabledByDefault` | 否 | `true` | 将某个内置插件标记为默认启用。省略它，或设置为任何非 `true` 的值，则该插件默认禁用。 |
| `legacyPluginIds` | 否 | `string[]` | 会规范化到这个规范插件 id 的旧版 id。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的互斥插件类型。 |
| `channels` | 否 | `string[]` | 此插件拥有的渠道 id。用于发现和配置校验。 |
| `providers` | 否 | `string[]` | 此插件拥有的提供商 id。 |
| `modelSupport` | 否 | `object` | 由清单持有的简写模型家族元数据，用于在运行时之前自动加载插件。 |
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量级提供商认证环境变量元数据。 |
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI flag 接线的轻量级认证选项元数据。 |
| `contracts` | 否 | `object` | 用于语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索和工具归属的静态内置能力快照。 |
| `channelConfigs` | 否 | `Record<string, object>` | 由清单持有的渠道配置元数据，在运行时加载前合并到发现和校验表面。 |
| `skills` | 否 | `string[]` | 要加载的 skill 目录，相对于插件根目录。 |
| `name` | 否 | `string` | 人类可读的插件名称。 |
| `description` | 否 | `string` | 显示在插件相关表面中的简短摘要。 |
| `version` | 否 | `string` | 仅供参考的插件版本。 |
| `uiHints` | 否 | `Record<string, object>` | 配置字段的 UI 标签、占位符和敏感性提示。 |
## providerAuthChoices 参考
## `providerAuthChoices` 参考
每个 `providerAuthChoices` 条目描述一个新手引导或认证选项。
OpenClaw 会在 provider 运行时加载前读取它。
OpenClaw 会在提供商运行时加载之前读取它。
| 字段 | 必需 | 类型 | 含义 |
| --------------------- | ---- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `provider` | 是 | `string` | 此选项所属的 provider id。 |
| `method` | 是 | `string` | 要分发到的认证方式 id。 |
| `choiceId` | 是 | `string` | 新手引导和 CLI 流程使用的稳定认证选项 id。 |
| `choiceLabel` | 否 | `string` | 面向用户的标签。如省略，OpenClaw 会回退到 `choiceId`。 |
| `choiceHint` | 否 | `string` | 选择器中的简短辅助文本。 |
| `assistantPriority` | 否 | `number` | 在由助手驱动的交互式选择器中，值越小排序越靠前。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，但仍允许手动 CLI 选择。 |
| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到该替代选项的旧 choice id。 |
| `groupId` | 否 | `string` | 用于对相关选项分组的可选组 id。 |
| `groupLabel` | 否 | `string` | 该分组的面向用户标签。 |
| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 |
| `optionKey` | 否 | `string` | 用于简单单标志认证流程的内部选项键。 |
| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 |
| `cliOption` | 否 | `string` | 完整 CLI 选项形式，例如 `--openrouter-api-key <key>`。 |
| `cliDescription` | 否 | `string` | CLI 帮助中使用的描述。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 该选项应显示在哪些新手引导界面中。如省略，默认值为 `["text-inference"]`。 |
| 字段 | 必需 | 类型 | 含义 |
| --------------------- | ---- | ----------------------------------------------- | ------------------------------------------------------------------ |
| `provider` | 是 | `string` | 此选项所属的提供商 id。 |
| `method` | 是 | `string` | 要分发到的认证方法 id。 |
| `choiceId` | 是 | `string` | 供新手引导和 CLI 流程使用的稳定认证选项 id。 |
| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 |
| `choiceHint` | 否 | `string` | 选择器中的简短辅助文本。 |
| `assistantPriority` | 否 | `number` | 数值越小，在由助手驱动的交互式选择器中排序越靠前。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，但仍允许通过手动 CLI 进行选择。 |
| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 id。 |
| `groupId` | 否 | `string` | 用于对相关选项分组的可选分组 id。 |
| `groupLabel` | 否 | `string` | 该分组的面向用户标签。 |
| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 |
| `optionKey` | 否 | `string` | 用于简单单 flag 认证流程的内部选项键。 |
| `cliFlag` | 否 | `string` | CLI flag 名称，例如 `--openrouter-api-key`。 |
| `cliOption` | 否 | `string` | 完整 CLI 选项形式，例如 `--openrouter-api-key <key>`。 |
| `cliDescription` | 否 | `string` | CLI 帮助中使用的描述。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 该选项应出现在哪些新手引导表面中。如果省略，默认值为 `["text-inference"]`。 |
## uiHints 参考
## `uiHints` 参考
`uiHints` 是一个从配置字段名映射到小型渲染提示的映射表。
`uiHints` 是从配置字段名映射到小型渲染提示的映射表。
```json
{
@ -186,20 +195,21 @@ OpenClaw 会在 provider 运行时加载前读取它。
}
```
每个字段提示可包含：
每个字段提示可以包括：
| 字段 | 类型 | 含义 |
| ------------- | ---------- | ------------------------ |
| `label` | `string` | 面向用户的字段标签。 |
| `help` | `string` | 简短辅助文本。 |
| `tags` | `string[]` | 可选 UI 标签。 |
| `advanced` | `boolean` | 将字段标记为高级选项。 |
| `sensitive` | `boolean` | 将字段标记为密钥或敏感项。 |
| `placeholder` | `string` | 表单输入的占位文本。 |
| 字段 | 类型 | 含义 |
| ------------- | ---------- | ---------------------------- |
| `label` | `string` | 面向用户的字段标签。 |
| `help` | `string` | 简短辅助文本。 |
| `tags` | `string[]` | 可选的 UI 标签。 |
| `advanced` | `boolean` | 将该字段标记为高级字段。 |
| `sensitive` | `boolean` | 将该字段标记为秘密或敏感项。 |
| `placeholder` | `string` | 表单输入的占位文本。 |
## contracts 参考
## `contracts` 参考
仅当 OpenClaw 需要在不导入插件运行时的情况下读取静态能力归属元数据时，才使用 `contracts`。
仅在 `contracts` 中放置 OpenClaw 可在不导入插件运行时的情况下
读取的静态能力归属元数据。
```json
{
@ -219,21 +229,21 @@ OpenClaw 会在 provider 运行时加载前读取它。
每个列表都是可选的：
| 字段 | 类型 | 含义 |
| -------------------------------- | ---------- | ------------------------------------------------ |
| `speechProviders` | `string[]` | 该插件拥有的 speech provider id。 |
| `realtimeTranscriptionProviders` | `string[]` | 该插件拥有的实时转录 provider id。 |
| `realtimeVoiceProviders` | `string[]` | 该插件拥有的实时语音 provider id。 |
| `mediaUnderstandingProviders` | `string[]` | 该插件拥有的媒体理解 provider id。 |
| `imageGenerationProviders` | `string[]` | 该插件拥有的图像生成 provider id。 |
| `videoGenerationProviders` | `string[]` | 该插件拥有的视频生成 provider id。 |
| `webFetchProviders` | `string[]` | 该插件拥有的网页抓取 provider id。 |
| `webSearchProviders` | `string[]` | 该插件拥有的网页搜索 provider id。 |
| `tools` | `string[]` | 该插件拥有的智能体工具名称，用于内置契约检查。 |
| 字段 | 类型 | 含义 |
| -------------------------------- | ---------- | -------------------------------------- |
| `speechProviders` | `string[]` | 此插件拥有的语音提供商 id。 |
| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录提供商 id。 |
| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 |
| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 |
| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 |
| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 |
| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取提供商 id。 |
| `webSearchProviders` | `string[]` | 此插件拥有的网页搜索提供商 id。 |
| `tools` | `string[]` | 此插件拥有的智能体工具名称，用于内置合同检查。 |
## channelConfigs 参考
## `channelConfigs` 参考
当渠道插件需要在运行时加载前提供轻量配置元数据时，请使用 `channelConfigs`。
当渠道插件需要在运行时加载前获得轻量级配置元数据时，请使用 `channelConfigs`。
```json
{
@ -260,19 +270,21 @@ OpenClaw 会在 provider 运行时加载前读取它。
}
```
每个渠道条目可包含：
每个渠道条目可以包括：
| 字段 | 类型 | 含义 |
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------- |
| `schema` | `object` | `channels.<id>` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 |
| `uiHints` | `Record<string, object>` | 该渠道配置区块可选的 UI 标签/占位符/敏感性提示。 |
| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面的渠道标签。 |
| `description` | `string` | 用于检查和目录界面的简短渠道描述。 |
| `preferOver` | `string[]` | 在选择界面中应优先于的旧版或较低优先级插件 id。 |
| 字段 | 类型 | 含义 |
| ------------- | ------------------------ | -------------------------------------------------------------------- |
| `schema` | `object` | `channels.<id>` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 |
| `uiHints` | `Record<string, object>` | 该渠道配置部分的可选 UI 标签/占位符/敏感性提示。 |
| `label` | `string` | 当运行时元数据尚未准备好时，合并到选择器和检查表面中的渠道标签。 |
| `description` | `string` | 用于检查和目录表面的简短渠道描述。 |
| `preferOver` | `string[]` | 在选择表面中，此渠道应优先于的旧版或较低优先级插件 id。 |
## modelSupport 参考
## `modelSupport` 参考
当 OpenClaw 需要在插件运行时加载前，根据 `gpt-5.4` 或 `claude-sonnet-4.6` 这样的简写模型 id 推断你的 provider 插件时，请使用 `modelSupport`。
当 OpenClaw 需要从诸如 `gpt-5.4` 或 `claude-sonnet-4.6` 之类的
简写模型 id 中推断你的提供商插件，并且这一过程发生在插件运行时
加载之前时，请使用 `modelSupport`。
```json
{
@ -283,97 +295,118 @@ OpenClaw 会在 provider 运行时加载前读取它。
}
```
OpenClaw 会按以下优先级应用：
OpenClaw 按以下优先级应用规则：
- 显式的 `provider/model` 引用会使用所属 `providers` 清单元数据
- 显式的 `provider/model` 引用使用拥有该提供商的 `providers` 清单元数据
- `modelPatterns` 优先于 `modelPrefixes`
- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出
- 如果仍有歧义，在用户或配置明确指定 provider 之前将忽略该歧义
- 如果一个非内置插件和一个内置插件都匹配，则非内置
插件胜出
- 对于剩余的歧义，在用户或配置明确指定提供商之前会被忽略
字段：
| 字段 | 类型 | 含义 |
| --------------- | ---------- | ------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | 对简写模型 id 使用 `startsWith` 匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除配置后缀后，对简写模型 id 进行匹配的正则表达式源码。 |
| 字段 | 类型 | 含义 |
| --------------- | ---------- | --------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | 对简写模型 id 使用 `startsWith` 进行匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除配置文件后缀后，对简写模型 id 进行匹配的正则表达式源码。 |
旧的顶层能力键已废弃。请使用 `openclaw doctor --fix` 将
旧版顶层能力键已弃用。使用 `openclaw doctor --fix` 将
`speechProviders`、`realtimeTranscriptionProviders`、
`realtimeVoiceProviders`、`mediaUnderstandingProviders`、
`imageGenerationProviders`、`videoGenerationProviders`、
`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；
常规清单加载已不再将这些顶层字段视为能力归属。
`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；普通
清单加载已不再将这些顶层字段视为能力归属。
## Manifest 与 package.json 的区别
## 清单与 `package.json` 的区别
这两个文件承担不同职责：
这两个文件承担的职责不同：
| 文件 | 用途 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | 发现、配置校验、认证选项元数据，以及必须在插件代码运行前就存在的 UI 提示 |
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 配置块 |
| 文件 | 用途 |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | 发现、配置校验、认证选项元数据，以及必须在插件代码运行前就存在的 UI 提示 |
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 配置块 |
如果你不确定某项元数据该放在哪里，请使用这条规则：
如果你不确定某段元数据该放在哪里，请使用这条规则：
- 如果 OpenClaw 必须在加载插件代码之前知道它，就把它放在 `openclaw.plugin.json`
- 如果它与打包、入口文件或 npm 安装行为有关，就把它放在 `package.json`
- 如果 OpenClaw 必须在加载插件代码之前知道它，就把它放进 `openclaw.plugin.json`
- 如果它与打包、入口文件或 npm 安装行为有关，就把它放进 `package.json`
### 影响发现流程的 package.json 字段
### 会影响发现的 `package.json` 字段
某些运行时前插件元数据会有意放在 `package.json` 的 `openclaw` 配置块下，而不是 `openclaw.plugin.json` 中。
某些运行前插件元数据有意放在 `package.json` 的
`openclaw` 配置块下，而不是 `openclaw.plugin.json` 中。
重要示例：
| 字段 | 含义 |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `openclaw.extensions` | 声明原生插件入口点。 |
| `openclaw.setupEntry` | 在新手引导和延迟渠道启动期间使用的轻量级仅设置入口点。 |
| `openclaw.channel` | 轻量渠道目录元数据，如标签、文档路径、别名和选择文案。 |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 用于内置和外部发布插件的安装/更新提示。 |
| `openclaw.install.defaultChoice` | 当存在多个安装来源时的首选安装路径。 |
| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用如 `>=2026.3.22` 这样的 semver 下限。 |
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许受限的内置插件重新安装恢复路径。 |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许仅设置的渠道界面在启动时于完整渠道插件之前加载。 |
| 字段 | 含义 |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `openclaw.extensions` | 声明原生插件入口点。 |
| `openclaw.setupEntry` | 轻量级、仅用于设置的入口点，用于新手引导和延迟的渠道启动。 |
| `openclaw.channel` | 轻量级渠道目录元数据，例如标签、文档路径、别名和选择文案。 |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 为内置插件和外部发布插件提供安装/更新提示。 |
| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 |
| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用类似 `>=2026.3.22` 的 semver 下限。 |
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许狭义的内置插件重装恢复路径。 |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许仅设置用的渠道表面在启动时于完整渠道插件之前加载。 |
`openclaw.install.minHostVersion` 会在安装期间和清单注册表加载时强制执行。无效值会被拒绝；对于较旧主机，较新但有效的值会跳过该插件。
`openclaw.install.minHostVersion` 会在安装期间和清单
注册表加载期间强制执行。无效值会被拒绝；有效但更高的值会在旧主机上
跳过该插件。
`openclaw.install.allowInvalidConfigRecovery` 的范围是有意收窄的。它不会让任意损坏的配置变得可安装。当前它仅允许安装流程从特定的旧版内置插件升级失败中恢复，例如缺失的内置插件路径，或该同一内置插件对应的旧 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并将操作员引导到 `openclaw doctor --fix`。
`openclaw.install.allowInvalidConfigRecovery` 的设计范围刻意很窄。它
不会让任意损坏的配置都变得可安装。目前它只允许安装
流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，
或同一内置插件的陈旧 `channels.<id>` 条目。无关的配置错误仍会阻止安装，
并将操作员引导到 `openclaw doctor --fix`。
## JSON Schema 要求
- **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。
- 可以使用空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。
- Schema 会在配置读写时校验，而不是在运行时校验。
- 空 schema 也是可以接受的（例如 `{ "type": "object", "additionalProperties": false }`）。
- Schema 会在配置读取/写入时校验，而不是在运行时校验。
## 校验行为
- 未知的 `channels.*` 键将被视为**错误**，除非该渠道 id 已由某个插件清单声明。
- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 已由
某个插件清单声明。
- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*`
必须引用**可发现的**插件 id。未知 id 将被视为**错误**。
- 如果插件已安装，但其清单或 schema 缺失或损坏，校验会失败，Doctor 会报告该插件错误。
- 如果插件配置存在，但插件已**禁用**，配置会被保留，并在 Doctor + 日志中显示**警告**。
必须引用**可发现的**插件 id。未知 id 会被视为**错误**。
- 如果插件已安装，但其清单或 schema 损坏或缺失，
校验将失败，Doctor 会报告该插件错误。
- 如果插件配置存在，但插件被**禁用**，配置会被保留，并且
Doctor + 日志中会显示一条**警告**。
完整 `plugins.*` schema 请参见 [Configuration reference](/gateway/configuration)。
完整的 `plugins.*` schema 请参见 [Configuration reference](/zh-CN/gateway/configuration)。
## 说明
- **原生 OpenClaw 插件必须提供该清单**，包括从本地文件系统加载的情况。
- 运行时仍会单独加载插件模块；清单仅用于发现 + 校验。
- 原生清单使用 JSON5 解析，因此注释、尾随逗号和未加引号的键都是允许的，只要最终值仍是一个对象。
- 清单加载器只会读取文档中说明的清单字段。避免在这里添加自定义顶层键。
- `providerAuthEnvVars` 是用于认证探测、环境变量标记校验以及类似 provider 认证界面的轻量元数据路径，这些场景不应仅为检查环境变量名而启动插件运行时。
- `providerAuthChoices` 是用于认证选项选择器、`--auth-choice` 解析、首选 provider 映射，以及在 provider 运行时加载前进行简单新手引导 CLI 标志注册的轻量元数据路径。对于需要 provider 代码的运行时向导元数据，请参见
[Provider runtime hooks](/plugins/architecture#provider-runtime-hooks)。
- 互斥插件类型通过 `plugins.slots.*` 选择。
- `kind: "memory"` 通过 `plugins.slots.memory` 选择。
- `kind: "context-engine"` 通过 `plugins.slots.contextEngine`
- 清单对于**原生 OpenClaw 插件**是**必需的**，包括本地文件系统加载。
- 运行时仍会单独加载插件模块；清单仅用于
发现 + 校验。
- 原生清单使用 JSON5 解析，因此只要最终值仍是对象，
注释、尾随逗号和未加引号的键都是允许的。
- 清单加载器只会读取文档中说明的清单字段。避免在这里添加
自定义顶层键。
- `providerAuthEnvVars` 是用于认证探测、环境变量标记
校验以及类似提供商认证表面的轻量级元数据路径，这些场景不应仅为检查环境变量名而启动插件
运行时。
- `providerAuthChoices` 是用于认证选项选择器、
`--auth-choice` 解析、首选提供商映射以及在提供商运行时加载前进行简单新手引导
CLI flag 注册的轻量级元数据路径。对于需要提供商代码的运行时向导
元数据，请参见
[Provider runtime hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
- 互斥插件类型通过 `plugins.slots.*` 进行选择。
- `kind: "memory"` 由 `plugins.slots.memory` 选择。
- `kind: "context-engine"` 由 `plugins.slots.contextEngine`
选择（默认：内置 `legacy`）。
- 当插件不需要时，`channels`、`providers`、`cliBackends` 和 `skills` 可以省略。
- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器允许列表要求（例如 pnpm `allow-build-scripts`
- 当插件不需要它们时，
`channels`、`providers` 和 `skills` 可以省略。
- 如果你的插件依赖原生模块，请记录构建步骤以及任何
包管理器允许列表要求（例如 pnpm `allow-build-scripts`
- `pnpm rebuild <package>`）。
## 相关内容
- [Building Plugins](/plugins/building-plugins) — 插件入门指南
- [Plugin Architecture](/plugins/architecture) — 内部架构
- [SDK Overview](/plugins/sdk-overview) — 插件 SDK 概览
- [Building Plugins](/zh-CN/plugins/building-plugins) —— 插件入门指南
- [Plugin Architecture](/zh-CN/plugins/architecture) —— 内部架构
- [SDK Overview](/zh-CN/plugins/sdk-overview) —— 插件 SDK 概览

336
docs/zh-CN/plugins/sdk-overview.md
View File

@ -1,53 +1,53 @@
---
read_when:
- 你需要知道应从哪个 SDK 子路径导入
- 你想查阅 OpenClawPluginApi 上所有注册方法的参考
- 你想查看 OpenClawPluginApi 上所有注册方法的参考
- 你正在查找某个特定的 SDK 导出
sidebarTitle: SDK Overview
summary: 导入映射、注册 API 参考和 SDK 架构
title: 插件 SDK 概览
x-i18n:
generated_at: "2026-04-05T17:48:58Z"
generated_at: "2026-04-05T18:15:07Z"
model: gpt-5.4
provider: openai
source_hash: f6e28e0e41430eba03a1cd11df15fd81bfaa1afb8c11d419554729d55c842b7d
source_hash: d70ea8cc1343b2dc1b4243b0562d19bebb1fdf7eb5065220b17e87cfd8aecc3e
source_path: plugins/sdk-overview.md
workflow: 15
---
# 插件 SDK 概览
插件 SDK 是插件与核心之间的类型化契约。本页是关于**该导入什么**以及**你可以注册什么**的参考。
插件 SDK 是插件与核心之间的类型化契约。本页是关于**导入什么**以及**你可以注册什么**的参考。
<Tip>
**在找操作指南吗？**
- 第一个插件？从 [入门指南](/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)
</Tip>
## 导入约定
始终从特定子路径导入：
始终从具体子路径导入：
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
每个子路径都是一个小型、自包含模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口 / 构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总入口表面和共享辅助函数，例如 `buildChannelConfigSchema`。
每个子路径都是一个小型、独立的模块。这样可以保持启动快速，并防止循环依赖问题。对于渠道专用的入口 / 构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总入口接口和共享辅助函数，例如 `buildChannelConfigSchema`。
不要添加或依赖以提供商命名的便捷接缝，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助接缝。内置插件应在其自己的 `api.ts` 或 `runtime-api.ts` barrel 中组合通用 SDK 子路径；而核心应使用这些插件本地 barrel，或者仅当需求确实跨渠道时再添加一个狭窄的通用 SDK 契约。
不要添加或依赖以提供商命名的便捷扩展点，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助扩展点。内置插件应在它们自己的 `api.ts` 或 `runtime-api.ts` barrel 中组合通用 SDK 子路径；而核心则应使用这些插件本地的 barrel，或者在需求确实跨渠道时新增一个窄而通用的 SDK 契约。
生成的导出映射仍包含一小组内置插件辅助接缝，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅为内置插件维护和兼容性而存在；它们在下方常用表中被有意省略，也不是新的第三方插件推荐使用的导入路径。
生成的导出映射仍包含少量内置插件辅助扩展点，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 以及 `plugin-sdk/matrix*`。这些子路径仅用于内置插件维护和兼容性；它们有意未出现在下方的常用表格中，也不是新第三方插件推荐使用的导入路径。
## 子路径参考
以下是最常用的子路径，按用途分组。完整的 200 多个子路径生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。
以下按用途分组列出了最常用的子路径。完整的 200+ 子路径生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。
保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其作为公开接口推荐，否则请将它们视为实现细节 / 兼容性表面。
保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其提升为公共接口，否则请将它们视为实现细节 / 兼容性接口。
### 插件入口点
### 插件入口
| 子路径 | 关键导出 |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
@ -63,40 +63,40 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | 共享的设置向导辅助函数、允许列表提示、设置状态构建器 |
| `plugin-sdk/setup` | 共享设置向导辅助函数、allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助函数、默认账户回退辅助函数 |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、账户 ID 标准化辅助函数 |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 |
| `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 |
| `plugin-sdk/account-helpers` | 狭义的账户列表 / 账户操作辅助函数 |
| `plugin-sdk/account-helpers` | 窄范围的账户列表 / 账户操作辅助函数 |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 |
| `plugin-sdk/telegram-command-config` | 带有内置契约回退的 Telegram 自定义命令标准化 / 校验辅助函数 |
| `plugin-sdk/telegram-command-config` | 带有内置契约回退的 Telegram 自定义命令规范化 / 校验辅助函数 |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建辅助函数 |
| `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助函数 |
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助函数 |
| `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助函数 |
| `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助函数 |
| `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助函数 |
| `plugin-sdk/outbound-media` | 共享出站媒体加载辅助函数 |
| `plugin-sdk/outbound-runtime` | 出站身份 / 发送委托辅助函数 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期与适配器辅助函数 |
| `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 |
| `plugin-sdk/agent-media-payload` | 旧版智能体媒体载荷构建器 |
| `plugin-sdk/conversation-runtime` | 会话 / 线程绑定、配对和已配置绑定辅助函数 |
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 |
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 |
| `plugin-sdk/channel-status` | 共享的渠道状态快照 / 摘要辅助函数 |
| `plugin-sdk/channel-config-primitives` | 狭义的渠道配置 schema 基元 |
| `plugin-sdk/channel-status` | 共享渠道状态快照 / 摘要辅助函数 |
| `plugin-sdk/channel-config-primitives` | 窄范围的渠道配置 schema 基元 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 |
| `plugin-sdk/channel-plugin-common` | 共享的渠道插件前导导出 |
| `plugin-sdk/allowlist-config-edit` | 允许列表配置编辑 / 读取辅助函数 |
| `plugin-sdk/group-access` | 共享的群组访问决策辅助函数 |
| `plugin-sdk/direct-dm` | 共享的直接私信认证 / 守卫辅助函数 |
| `plugin-sdk/interactive-runtime` | 交互式回复负载标准化 / 归约辅助函数 |
| `plugin-sdk/channel-inbound` | 去抖动、提及匹配、envelope 辅助函数 |
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前置导出 |
| `plugin-sdk/allowlist-config-edit` | Allowlist 配置编辑 / 读取辅助函数 |
| `plugin-sdk/group-access` | 共享群组访问决策辅助函数 |
| `plugin-sdk/direct-dm` | 共享直接私信认证 / 防护辅助函数 |
| `plugin-sdk/interactive-runtime` | 交互式回复载荷规范化 / 归约辅助函数 |
| `plugin-sdk/channel-inbound` | 去抖、提及匹配、envelope 辅助函数 |
| `plugin-sdk/channel-send-result` | 回复结果类型 |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
| `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 |
@ -108,100 +108,99 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | 经过筛选的本地 / 自托管提供商设置辅助函数 |
| `plugin-sdk/self-hosted-provider-setup` | 聚焦 OpenAI 兼容自托管提供商的设置辅助函数 |
| `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 |
| `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API key 解析辅助函数 |
| `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置文件写入辅助函数 |
| `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助函数 |
| `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容自托管提供商的设置辅助函数 |
| `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API 密钥解析辅助函数 |
| `plugin-sdk/provider-auth-api-key` | API 密钥新手引导 / profile 写入辅助函数 |
| `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 |
| `plugin-sdk/provider-auth-login` | 提供商插件共享的交互式登录辅助函数 |
| `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助函数 |
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的模型 ID 标准化辅助函数 |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、提供商端点辅助函数，以及如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助函数 |
| `plugin-sdk/provider-web-fetch` | Web 获取提供商注册 / 缓存辅助函数 |
| `plugin-sdk/provider-web-search` | Web 搜索提供商注册 / 缓存 / 配置辅助函数 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助函数 |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似导出 |
| `plugin-sdk/provider-http` | 通用提供商 HTTP / 端点能力辅助函数 |
| `plugin-sdk/provider-web-fetch` | 网页抓取提供商注册 / 缓存辅助函数 |
| `plugin-sdk/provider-web-search` | 网页搜索提供商注册 / 缓存 / 配置辅助函数 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助函数 |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似函数 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助函数 |
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 |
| `plugin-sdk/global-singleton` | 进程本地 singleton / map / 缓存辅助函数 |
| `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助函数 |
</Accordion>
<Accordion title="认证与安全子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 |
| `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天操作认证辅助函数 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件 / 过滤器辅助函数 |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助函数 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile / 过滤辅助函数 |
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 传递适配器 |
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 |
| `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复负载辅助函数 |
| `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复载荷辅助函数 |
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 |
| `plugin-sdk/command-detection` | 共享命令检测辅助函数 |
| `plugin-sdk/command-surface` | 命令体标准化和命令表面辅助函数 |
| `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助函数 |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和密钥收集辅助函数 |
| `plugin-sdk/ssrf-policy` | 主机允许列表和私有网络 SSRF 策略辅助函数 |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助函数 |
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 |
| `plugin-sdk/ssrf-runtime` | 固定调度器、受 SSRF 防护的抓取以及 SSRF 策略辅助函数 |
| `plugin-sdk/secret-input` | 密钥输入解析辅助函数 |
| `plugin-sdk/webhook-ingress` | webhook 请求 / 目标辅助函数 |
| `plugin-sdk/webhook-ingress` | Webhook 请求 / 目标辅助函数 |
| `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助函数 |
</Accordion>
<Accordion title="运行时与存储子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/runtime` | 广义的运行时 / 日志 / 备份 / 插件安装辅助函数 |
| `plugin-sdk/runtime-env` | 狭义的运行时环境、logger、超时、重试和退避辅助函数 |
| `plugin-sdk/runtime` | 广义运行时 / 日志 / 备份 / 插件安装辅助函数 |
| `plugin-sdk/runtime-env` | 窄范围运行时环境、logger、超时、重试和回退辅助函数 |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共享的插件命令 / hook / http / 交互式辅助函数 |
| `plugin-sdk/hook-runtime` | 共享的 webhook / 内部 hook 流水线辅助函数 |
| `plugin-sdk/lazy-runtime` | 延迟运行时导入 / 绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程 exec 辅助函数 |
| `plugin-sdk/plugin-runtime` | 共享插件命令 / hook / HTTP / 交互辅助函数 |
| `plugin-sdk/hook-runtime` | 共享 webhook / 内部 hook 管道辅助函数 |
| `plugin-sdk/lazy-runtime` | 惰性运行时导入 / 绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程执行辅助函数 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助函数 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助函数 |
| `plugin-sdk/gateway-runtime` | Gateway 客户端和渠道状态补丁辅助函数 |
| `plugin-sdk/config-runtime` | 配置加载 / 写入辅助函数 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名 / 描述标准化以及重复 / 冲突检查，即使内置 Telegram 契约表面不可用时也可使用 |
| `plugin-sdk/approval-runtime` | exec / 插件审批辅助函数、审批能力构建器、认证 / 配置文件辅助函数、原生路由 / 运行时辅助函数 |
| `plugin-sdk/reply-runtime` | 共享的入站 / 回复运行时辅助函数、分块、分发、心跳、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 狭义的回复分发 / 完成辅助函数 |
| `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/telegram-command-config` | Telegram 命令名 / 描述规范化以及重复 / 冲突检查，即使内置 Telegram 契约接口不可用也可使用 |
| `plugin-sdk/approval-runtime` | exec / 插件审批辅助函数、审批能力构建器、认证 / profile 辅助函数、原生路由 / 运行时辅助函数 |
| `plugin-sdk/reply-runtime` | 共享入站 / 回复运行时辅助函数、分块、分发、心跳、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发 / 完成辅助函数 |
| `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 狭义的文本 / markdown 分块辅助函数 |
| `plugin-sdk/reply-chunking` | 窄范围文本 / Markdown 分块辅助函数 |
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助函数 |
| `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助函数 |
| `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | 共享的渠道 / 账户状态摘要辅助函数、运行时状态默认值和问题元数据辅助函数 |
| `plugin-sdk/status-helpers` | 共享渠道 / 账户状态摘要辅助函数、运行时状态默认值和问题元数据辅助函数 |
| `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助函数 |
| `plugin-sdk/string-normalization-runtime` | slug / 字符串标准化辅助函数 |
| `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助函数 |
| `plugin-sdk/request-url` | 从 fetch / request 类输入中提取字符串 URL |
| `plugin-sdk/run-command` | 带超时的命令运行器，输出标准化的 stdout / stderr 结果 |
| `plugin-sdk/param-readers` | 常用工具 / CLI 参数读取器 |
| `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化 stdout / stderr 结果 |
| `plugin-sdk/param-readers` | 通用工具 / CLI 参数读取器 |
| `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 |
| `plugin-sdk/temp-path` | 共享临时下载路径辅助函数 |
| `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助函数 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助函数 |
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助函数 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助函数 |
| `plugin-sdk/persistent-dedupe` | 基于磁盘的去重缓存辅助函数 |
| `plugin-sdk/persistent-dedupe` | 磁盘后备去重缓存辅助函数 |
| `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助函数 |
| `plugin-sdk/agent-config-primitives` | 狭义的智能体运行时配置 schema 基元 |
| `plugin-sdk/agent-config-primitives` | 窄范围智能体运行时配置 schema 基元 |
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对 token 辅助函数 |
| `plugin-sdk/extension-shared` | 共享的被动渠道和状态辅助基元 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 |
| `plugin-sdk/extension-shared` | 共享被动渠道和状态辅助基元 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助函数 |
| `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助函数 |
| `plugin-sdk/native-command-registry` | 原生命令注册表构建 / 序列化辅助函数 |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助函数 |
| `plugin-sdk/native-command-registry` | 原生命令注册表 / 构建 / 序列化辅助函数 |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I 端点检测辅助函数 |
| `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助函数 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和固定查找辅助函数 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机标准化辅助函数 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 |
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 |
| `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助函数 |
| `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 |
@ -211,104 +210,103 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
<Accordion title="能力与测试子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/media-runtime` | 共享的媒体获取 / 转换 / 存储辅助函数，以及媒体负载构建器 |
| `plugin-sdk/media-runtime` | 共享媒体抓取 / 转换 / 存储辅助函数，以及媒体载荷构建器 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享的文本 / markdown / 日志辅助函数，例如对助手可见文本的剥离、markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 |
| `plugin-sdk/text-runtime` | 共享文本 / Markdown / 日志辅助函数，例如 assistant 可见文本剥离、Markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、指令标签辅助函数和安全文本工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助函数 |
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助函数 |
| `plugin-sdk/speech-core` | 共享的语音提供商类型、注册表、directive 和标准化辅助函数 |
| `plugin-sdk/realtime-transcription` | 实时转写提供商类型和注册表辅助函数 |
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的指令、注册表和校验辅助函数 |
| `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、指令和规范化辅助函数 |
| `plugin-sdk/realtime-transcription` | 实时转录提供商类型和注册表辅助函数 |
| `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 |
| `plugin-sdk/image-generation` | 图像生成提供商类型 |
| `plugin-sdk/image-generation-core` | 共享的图像生成类型、故障转移、认证和注册表辅助函数 |
| `plugin-sdk/image-generation-core` | 共享图像生成类型、故障切换、认证和注册表辅助函数 |
| `plugin-sdk/video-generation` | 视频生成提供商 / 请求 / 结果类型 |
| `plugin-sdk/video-generation-core` | 共享的视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 |
| `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助函数 |
| `plugin-sdk/webhook-path` | webhook 路径标准化辅助函数 |
| `plugin-sdk/video-generation-core` | 共享视频生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 |
| `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助函数 |
| `plugin-sdk/webhook-path` | Webhook 路径规范化辅助函数 |
| `plugin-sdk/web-media` | 共享远程 / 本地媒体加载辅助函数 |
| `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` |
| `plugin-sdk/zod` | 面向插件 SDK 使用者重新导出的 `zod` |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="记忆子路径">
<Accordion title="Memory 子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助表面，用于 manager / config / file / CLI 辅助函数 |
| `plugin-sdk/memory-core-engine-runtime` | 记忆索引 / 搜索运行时门面 |
| `plugin-sdk/memory-core-host-engine-foundation` | 记忆宿主基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | 记忆宿主嵌入引擎导出 |
| `plugin-sdk/memory-core-host-engine-qmd` | 记忆宿主 QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | 记忆宿主存储引擎导出 |
| `plugin-sdk/memory-core-host-multimodal` | 记忆宿主多模态辅助函数 |
| `plugin-sdk/memory-core-host-query` | 记忆宿主查询辅助函数 |
| `plugin-sdk/memory-core-host-secret` | 记忆宿主密钥辅助函数 |
| `plugin-sdk/memory-core-host-status` | 记忆宿主状态辅助函数 |
| `plugin-sdk/memory-core-host-runtime-cli` | 记忆宿主 CLI 运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-core` | 记忆宿主核心运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-files` | 记忆宿主文件 / 运行时辅助函数 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助表面 |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助接口，用于 manager / config / file / CLI 辅助函数 |
| `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时门面 |
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation 引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 引擎导出 |
| `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储引擎导出 |
| `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助函数 |
| `plugin-sdk/memory-core-host-query` | Memory host 查询辅助函数 |
| `plugin-sdk/memory-core-host-secret` | Memory host 密钥辅助函数 |
| `plugin-sdk/memory-core-host-status` | Memory host 状态辅助函数 |
| `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助函数 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 |
</Accordion>
<Accordion title="保留的内置辅助子路径">
| 家族 | 当前子路径 | 预期用途 |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-support` | 内置 browser 插件支持辅助函数 |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助 / 运行时表面 |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助 / 运行时表面 |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助表面 |
| 渠道特定辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性 / 辅助接缝 |
| 认证 / 插件特定辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能 / 插件辅助接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助函数 |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助 / 运行时接口 |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助 / 运行时接口 |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 |
| 渠道专用辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性 / 辅助扩展点 |
| 认证 / 插件专用辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能 / 插件辅助扩展点；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## 注册 API
`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，它具有以下方法：
`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，它包含以下方法：
### 能力注册
| 方法 | 注册内容 |
| 方法 | 它注册的内容 |
| ------------------------------------------------ | -------------------------------- |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
| `api.registerChannel(...)` | 消息渠道 |
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转写 |
| `api.registerSpeechProvider(...)` | 文字转语音 / STT 合成 |
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 |
| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 |
| `api.registerMediaUnderstandingProvider(...)` | 图像 / 音频 / 视频分析 |
| `api.registerImageGenerationProvider(...)` | 图像生成 |
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 |
| `api.registerWebSearchProvider(...)` | Web 搜索 |
| `api.registerWebFetchProvider(...)` | 网页抓取 / scrape 提供商 |
| `api.registerWebSearchProvider(...)` | 网页搜索 |
### 工具与命令
| 方法 | 注册内容 |
| 方法 | 它注册的内容 |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） |
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
### 基础设施
| 方法 | 注册内容 |
| 方法 | 它注册的内容 |
| ---------------------------------------------- | --------------------- |
| `api.registerHook(events, handler, opts?)` | 事件 hook |
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP endpoint |
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
| `api.registerHttpRoute(params)` | Gateway HTTP 端点 |
| `api.registerGatewayMethod(name, handler)` | Gateway RPC 方法 |
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
| `api.registerService(service)` | 后台服务 |
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件拥有的方法，请优先使用插件特定前缀。
保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试为某个 Gateway 方法指定更窄的作用域也是如此。对于插件自有方法，优先使用插件专属前缀。
### CLI 注册元数据
`api.registerCli(registrar, opts?)` 接受两种顶层元数据：
- `commands`：由注册器拥有的显式命令根
- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析时命令描述符
- `commands`：由 registrar 拥有的显式命令根
- `descriptors`：用于根 CLI 帮助、路由和惰性插件 CLI 注册的解析期命令描述符
如果你希望插件命令在正常根 CLI 路径中保持延迟加载，请提供 `descriptors`，覆盖该注册器公开的每个顶层命令根。
如果你希望插件命令在普通根 CLI 路径中保持惰性加载，请提供覆盖该 registrar 暴露的每个顶层命令根的 `descriptors`。
```typescript
api.registerCli(
@ -320,7 +318,7 @@ api.registerCli(
descriptors: [
{
name: "matrix",
description: "管理 Matrix 账户、验证、设备和资料状态",
description: "Manage Matrix accounts, verification, devices, and profile state",
hasSubcommands: true,
},
],
@ -328,68 +326,59 @@ api.registerCli(
);
```
仅使用 `commands` 适用于你不需要延迟根 CLI 注册的场景。该急切兼容路径仍受支持，但不会安装由 descriptor 支持的占位符来实现解析时延迟加载。
### CLI 后端注册
`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（如 `codex-cli`）的默认配置。
- 后端 `id` 会成为 `codex-cli/gpt-5` 这类 model ref 中的提供商前缀。
- 后端 `config` 使用与 `agents.defaults.cliBackends.<id>` 相同的结构。
- 用户配置仍然优先。OpenClaw 会在运行 CLI 前，将 `agents.defaults.cliBackends.<id>` 覆盖合并到插件默认值之上。
- 当后端在合并后需要兼容性重写时，请使用 `normalizeConfig`（例如标准化旧版 flag 结构）。
仅在你不需要惰性根 CLI 注册时，才单独使用 `commands`。这条急切兼容路径仍受支持，但它不会安装基于 descriptor 的占位符来实现解析期惰性加载。
### 独占槽位
| 方法 | 注册内容 |
| 方法 | 它注册的内容 |
| ------------------------------------------ | ------------------------------------- |
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个处于活动状态） |
| `api.registerMemoryPromptSection(builder)` | 记忆提示词区块构建器 |
| `api.registerMemoryFlushPlan(resolver)` | 记忆刷新计划解析器 |
| `api.registerMemoryRuntime(runtime)` | 记忆运行时适配器 |
| `api.registerContextEngine(id, factory)` | 上下文引擎（同一时间仅一个处于激活状态） |
| `api.registerMemoryPromptSection(builder)` | Memory 提示区段构建器 |
| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 |
| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 |
### 记忆嵌入适配器
### Memory embedding 适配器
| 方法 | 注册内容 |
| 方法 | 它注册的内容 |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的记忆嵌入适配器 |
| `api.registerMemoryEmbeddingProvider(adapter)` | 活跃插件的 Memory embedding 适配器 |
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是记忆插件专属的独占接口。
- `registerMemoryEmbeddingProvider` 允许活动记忆插件注册一个或多个嵌入适配器 ID（例如 `openai`、`gemini` 或插件自定义 ID）。
- 用户配置，如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`，会基于这些已注册适配器 ID 进行解析。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是 Memory 插件专属的独占接口。
- `registerMemoryEmbeddingProvider` 允许活跃的 Memory 插件注册一个或多个 embedding 适配器 id（例如 `openai`、`gemini` 或插件自定义 id）。
- 用户配置（如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会基于这些已注册的适配器 id 进行解析。
### 事件与生命周期
| 方法 | 作用 |
| 方法 | 它的作用 |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
| `api.onConversationBindingResolved(handler)` | 会话绑定解析回调 |
| `api.onConversationBindingResolved(handler)` | 会话绑定回调 |
### Hook 决策语义
### hook 决策语义
- `before_tool_call`：返回 `{ block: true }` 是终止性决定。一旦任一处理器设置它，较低优先级的处理器将被跳过。
- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（等同于省略 `block`），而不是覆盖。
- `before_install`：返回 `{ block: true }` 是终止性决定。一旦任一处理器设置它，较低优先级的处理器将被跳过。
- `before_install`：返回 `{ block: false }` 会被视为未作决定（等同于省略 `block`），而不是覆盖。
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性决定。一旦任一处理器声明已分发，较低优先级的处理器以及默认模型分发路径都会被跳过。
- `message_sending`：返回 `{ cancel: true }` 是终止性决定。一旦任一处理器设置它，较低优先级的处理器将被跳过。
- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（等同于省略 `cancel`），而不是覆盖。
- `before_tool_call`：返回 `{ block: true }` 是终结结果。一旦任何处理器设置了它，就会跳过优先级更低的处理器。
- `before_tool_call`：返回 `{ block: false }` 会被视为没有作出决定（等同于省略 `block`），而不是覆盖。
- `before_install`：返回 `{ block: true }` 是终结结果。一旦任何处理器设置了它，就会跳过优先级更低的处理器。
- `before_install`：返回 `{ block: false }` 会被视为没有作出决定（等同于省略 `block`），而不是覆盖。
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终结结果。一旦任何处理器声明已分发，就会跳过优先级更低的处理器以及默认模型分发路径。
- `message_sending`：返回 `{ cancel: true }` 是终结结果。一旦任何处理器设置了它，就会跳过优先级更低的处理器。
- `message_sending`：返回 `{ cancel: false }` 会被视为没有作出决定（等同于省略 `cancel`），而不是覆盖。
### API 对象字段
| 字段 | 类型 | 说明 |
| 字段 | 类型 | 描述 |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | 插件 ID |
| `api.id` | `string` | 插件 id |
| `api.name` | `string` | 显示名称 |
| `api.version` | `string?` | 插件版本（可选） |
| `api.description` | `string?` | 插件说明（可选） |
| `api.description` | `string?` | 插件描述（可选） |
| `api.source` | `string` | 插件源路径 |
| `api.rootDir` | `string?` | 插件根目录（可选） |
| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动内存运行时快照） |
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件特定配置 |
| `api.runtime` | `PluginRuntime` | [运行时](/zh-CN/plugins/sdk-runtime) |
| `api.config` | `OpenClawConfig` | 当前配置快照（如果可用，则为活动内存运行时快照） |
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属配置 |
| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口加载前的轻量启动 / 设置窗口 |
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口前的轻量启动 / 设置窗口 |
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
## 内部模块约定
@ -398,21 +387,19 @@ api.registerCli(
```
my-plugin/
api.ts # 面向外部使用者的公开导出
runtime-api.ts # 仅供内部使用的运行时导出
api.ts # 面向外部使用者的公共导出
runtime-api.ts # 仅内部使用的运行时导出
index.ts # 插件入口点
setup-entry.ts # 轻量级仅设置入口点（可选）
setup-entry.ts # 仅设置使用的轻量入口（可选）
```
<Warning>
不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>`
导入你自己的插件。内部导入应通过 `./api.ts` 或
`./runtime-api.ts`。SDK 路径仅是对外契约。
不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>` 导入你自己的插件。请通过 `./api.ts` 或 `./runtime-api.ts` 进行内部导入。SDK 路径仅是外部契约。
</Warning>
由门面加载的内置插件公开表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似公开入口文件）现在在 OpenClaw 已经运行时会优先使用活动运行时配置快照。如果运行时快照尚不存在，则会回退到磁盘上解析后的配置文件。
由门面加载的内置插件公共接口（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似公共入口文件）现在会在 OpenClaw 已运行时优先使用活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上解析出的配置文件。
提供商插件也可以公开一个狭义的插件本地契约 barrel，用于那些明确具有提供商特性、但暂时还不属于通用 SDK 子路径的辅助函数。当前的内置示例：Anthropic 提供商将其 Claude 流辅助函数保留在自己的公开 `api.ts` / `contract-api.ts` 接缝中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升到通用 `plugin-sdk/*` 契约中。
当某个辅助函数明确是提供商专用、且暂时不属于通用 SDK 子路径时，提供商插件也可以暴露一个窄范围的插件本地契约 barrel。当前内置示例：Anthropic 提供商将其 Claude 流辅助函数保留在自己的公共 `api.ts` / `contract-api.ts` 扩展点中，而不是把 Anthropic beta-header 和 `service_tier` 逻辑提升到通用 `plugin-sdk/*` 契约中。
其他当前内置示例：
@ -420,17 +407,14 @@ my-plugin/
- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导 / 配置辅助函数
<Warning>
扩展生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。
如果某个辅助函数确实需要共享，请将其提升到中立的 SDK 子路径，
例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，
或其他面向能力的表面，而不是让两个插件耦合在一起。
扩展生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。如果某个辅助函数确实需要共享，请将其提升到中立的 SDK 子路径，例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他面向能力的接口，而不是把两个插件耦合在一起。
</Warning>
## 相关内容
- [入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry` 选项
- [运行时](/zh-CN/plugins/sdk-runtime) — 完整 `api.runtime` 命名空间参考
- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、清单、配置 schema
- [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则
- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用表面迁移
- [插件内部机制](/zh-CN/plugins/architecture) — 深入架构和能力模型
- [入口点](/zh-CN/plugins/sdk-entrypoints) —— `definePluginEntry` 和 `defineChannelPluginEntry` 选项
- [运行时辅助函数](/zh-CN/plugins/sdk-runtime) —— 完整 `api.runtime` 命名空间参考
- [设置与配置](/zh-CN/plugins/sdk-setup) —— 打包、清单、配置 schema
- [测试](/zh-CN/plugins/sdk-testing) —— 测试工具和 lint 规则
- [SDK 迁移](/zh-CN/plugins/sdk-migration) —— 从已弃用接口迁移
- [插件内部机制](/zh-CN/plugins/architecture) —— 深入架构与能力模型

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

@ -1,30 +1,33 @@
---
read_when:
- 你正在构建一个新的模型提供商插件
- 你想为 OpenClaw 添加一个 OpenAI 兼容代理或自定义 LLM
- 你需要理解提供商认证、目录和运行时 hooks
- 你想为 OpenClaw 添加一个兼容 OpenAI 的代理或自定义 LLM
- 你需要了解提供商认证、目录和运行时 hooks
sidebarTitle: Provider Plugins
summary: 在 OpenClaw 中构建模型提供商插件的分步指南
summary: 为 OpenClaw 构建模型提供商插件的分步指南
title: 构建提供商插件
x-i18n:
generated_at: "2026-04-05T17:49:25Z"
generated_at: "2026-04-05T18:15:33Z"
model: gpt-5.4
provider: openai
source_hash: 9411ebf96c1eef0baecee9b743925440edc6714a8947da7712fed2b9ef1405cb
source_hash: 69500f46aa2cfdfe16e85b0ed9ee3c0032074be46f2d9c9d2940d18ae1095f47
source_path: plugins/sdk-provider-plugins.md
workflow: 15
---
# 构建提供商插件
本指南将带你构建一个提供商插件，用于向 OpenClaw 添加模型提供商（LLM）。完成后，你将拥有一个带有模型目录、API key 认证和动态模型解析的提供商。
本指南将带你构建一个向 OpenClaw 添加模型提供商
（LLM）的提供商插件。完成后，你将拥有一个带有模型目录、
API 密钥认证和动态模型解析能力的提供商。
<Info>
如果你之前没有构建过任何 OpenClaw 插件，请先阅读
[入门指南](/zh-CN/plugins/building-plugins) 了解基本的包结构和清单设置。
[入门指南](/zh-CN/plugins/building-plugins)，了解基本包
结构和清单设置。
</Info>
## 操作演练
## 演练
<Steps>
<a id="step-1-package-and-manifest"></a>
@ -83,7 +86,12 @@ x-i18n:
```
</CodeGroup>
清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测凭证。`modelSupport` 是可选的，它允许 OpenClaw 在运行时 hook 存在之前，通过像 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你在 ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段是必需的。
清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测
凭证。`modelSupport` 是可选的，
它让 OpenClaw 可以在运行时 hooks 存在之前，根据简写模型 ID
（如 `acme-large`）自动加载你的提供商插件。如果你在
ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段
是必需的。
</Step>
@ -159,11 +167,13 @@ x-i18n:
});
```
这就是一个可工作的提供商。用户现在可以执行
这就是一个可工作的提供商。用户现在可以
`openclaw onboard --acme-ai-api-key <key>`，并选择
`acme-ai/acme-large` 作为他们的模型。
对于只注册一个文本提供商、使用 API key 认证并带有单个目录支持运行时的内置提供商，优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数：
对于仅注册一个文本提供商、使用 API 密钥
认证并带有单个基于目录的运行时的内置提供商，优先使用更窄的
`defineSingleProviderPluginEntry(...)` 辅助函数：
```typescript
import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
@ -198,14 +208,27 @@ x-i18n:
});
```
如果你的认证流程还需要在 onboarding 期间修补 `models.providers.*`、别名和智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数是 `createDefaultModelPresetAppliers(...)`、`createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。
如果你的认证流程在新手引导期间还需要修补 `models.providers.*`、别名以及
智能体默认模型，请使用
`openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数包括
`createDefaultModelPresetAppliers(...)`、
`createDefaultModelsPresetAppliers(...)` 和
`createModelCatalogPresetAppliers(...)`。
当某个提供商的原生端点在正常的 `openai-completions` 传输上支持流式使用量块时，请优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不要硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和 `applyProviderNativeStreamingUsageCompat(...)` 会根据端点能力映射检测支持情况，因此即使插件使用的是自定义提供商 id，原生 Moonshot/DashScope 风格的端点也仍然可以启用此能力。
当某个提供商的原生端点在常规
`openai-completions` 传输上支持分块流式传输使用量块时，优先使用
`openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，
而不是硬编码提供商 ID 检查。
`supportsNativeStreamingUsageCompat(...)` 和
`applyProviderNativeStreamingUsageCompat(...)` 会根据端点能力映射检测支持情况，
因此即使插件使用的是自定义 provider ID，原生 Moonshot/DashScope 风格端点
也仍然可以选择启用。
</Step>
<Step title="添加动态模型解析">
如果你的提供商接受任意模型 ID（比如代理或路由器），请添加 `resolveDynamicModel`：
如果你的提供商接受任意模型 ID（例如代理或路由器），
请添加 `resolveDynamicModel`：
```typescript
api.registerProvider({
@ -226,14 +249,17 @@ x-i18n:
});
```
如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步预热 —— 在它完成后，会再次运行 `resolveDynamicModel`。
如果解析需要进行网络调用，请使用 `prepareDynamicModel` 进行异步
预热——完成后会再次运行 `resolveDynamicModel`。
</Step>
<Step title="按需添加运行时 hooks">
大多数提供商只需要 `catalog` + `resolveDynamicModel`。根据你的提供商需求逐步添加 hooks 即可。
<Step title="添加运行时 hooks（按需）">
大多数提供商只需要 `catalog` + `resolveDynamicModel`。当你的提供商有需要时，
再逐步添加 hooks。
共享辅助构建器现在已经覆盖了最常见的重放/工具兼容家族，因此插件通常不需要手动一个个接线每个 hook：
共享辅助构建器现在已经覆盖了最常见的 replay/tool-compat
系列，因此插件通常不需要手动逐个接线每个 hook：
```typescript
import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
@ -253,39 +279,39 @@ x-i18n:
});
```
当前可用的重放家族：
当前可用的 replay 系列：
| Family | 它会接入什么 |
| 系列 | 接入内容 |
| --- | --- |
| `openai-compatible` | 用于 OpenAI 兼容传输的共享 OpenAI 风格重放策略，包括 tool-call-id 清理、assistant-first 顺序修复，以及在传输需要时的通用 Gemini 轮次校验 |
| `anthropic-by-model` | 由 `modelId` 选择的 Claude 感知重放策略，因此 Anthropic-message 传输只有在解析出的模型实际是 Claude id 时，才会获得 Claude 特定的 thinking-block 清理 |
| `google-gemini` | 原生 Gemini 重放策略，以及 bootstrap 重放清理和带标签的推理输出模式 |
| `passthrough-gemini` | 用于通过 OpenAI 兼容代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini 重放校验或 bootstrap 重写 |
| `hybrid-anthropic-openai` | 用于在一个插件中混合 Anthropic-message 和 OpenAI 兼容模型界面的提供商的混合策略；可选的仅 Claude thinking-block 丢弃仍然限定在 Anthropic 一侧 |
| `openai-compatible` | 用于兼容 OpenAI 传输的共享 OpenAI 风格 replay 策略，包括 tool-call-id 清理、assistant-first 顺序修复，以及在传输需要时的通用 Gemini 轮次校验 |
| `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知 replay 策略，因此只有当解析后的模型实际是 Claude ID 时，Anthropic-message 传输才会获得 Claude 特有的 thinking block 清理 |
| `google-gemini` | 原生 Gemini replay 策略，加上 bootstrap replay 清理和带标签的 reasoning-output 模式 |
| `passthrough-gemini` | 适用于通过兼容 OpenAI 的代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini replay 校验或 bootstrap 重写 |
| `hybrid-anthropic-openai` | 适用于在同一个插件中混合 Anthropic-message 和兼容 OpenAI 模型面板的提供商的混合策略；可选的仅限 Claude 的 thinking block 丢弃仍然只作用于 Anthropic 一侧 |
真实的内置示例：
- `google` 和 `google-gemini-cli`：`google-gemini`
- `google`：`google-gemini`
- `openrouter`、`kilocode`、`opencode` 和 `opencode-go`：`passthrough-gemini`
- `amazon-bedrock` 和 `anthropic-vertex`：`anthropic-by-model`
- `minimax`：`hybrid-anthropic-openai`
- `moonshot`、`ollama`、`xai` 和 `zai`：`openai-compatible`
当前可用的流家族：
当前可用的 stream 系列：
| Family | 它会接入什么 |
| 系列 | 接入内容 |
| --- | --- |
| `google-thinking` | 共享流路径上的 Gemini thinking 载荷标准化 |
| `kilocode-thinking` | 共享代理流路径上的 Kilo 推理包装器，其中 `kilo/auto` 和不支持代理推理的 id 会跳过注入的 thinking |
| `moonshot-thinking` | 基于配置 + `/think` 级别的 Moonshot 二元原生 thinking 载荷映射 |
| `google-thinking` | 共享流路径上的 Gemini thinking 负载规范化 |
| `kilocode-thinking` | 共享代理流路径上的 Kilo reasoning 包装器，其中 `kilo/auto` 和不支持代理 reasoning 的 ID 会跳过注入的 thinking |
| `moonshot-thinking` | 基于配置 + `/think` 级别的 Moonshot 二进制 native-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` 包装器 |
| `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归属头、`/fast`/`serviceTier`、文本详细度、原生 Codex web 搜索、reasoning-compat 负载塑形，以及 Responses 上下文管理 |
| `openrouter-thinking` | 用于代理路由的 OpenRouter reasoning 包装器，集中处理不支持模型/`auto` 跳过逻辑 |
| `tool-stream-default-on` | 为像 Z.AI 这类希望默认启用工具流式传输的提供商提供默认开启的 `tool_stream` 包装器，除非显式禁用 |
真实的内置示例：
- `google` 和 `google-gemini-cli`：`google-thinking`
- `google`：`google-thinking`
- `kilocode`：`kilocode-thinking`
- `moonshot`：`moonshot-thinking`
- `minimax` 和 `minimax-portal`：`minimax-fast-mode`
@ -293,40 +319,76 @@ x-i18n:
- `openrouter`：`openrouter-thinking`
- `zai`：`tool-stream-default-on`
`openclaw/plugin-sdk/provider-model-shared` 还导出了 replay-family 枚举，以及这些家族所基于的共享辅助函数。常见公共导出包括：
`openclaw/plugin-sdk/provider-model-shared` 还导出了 replay-family
枚举，以及构建这些系列所用的共享辅助函数。常见公开导出包括：
- `ProviderReplayFamily`
- `buildProviderReplayFamilyHooks(...)`
- 共享重放构建器，例如 `buildOpenAICompatibleReplayPolicy(...)`、`buildAnthropicReplayPolicyForModel(...)`、`buildGoogleGeminiReplayPolicy(...)` 和 `buildHybridAnthropicOrOpenAIReplayPolicy(...)`
- Gemini 重放辅助函数，例如 `sanitizeGoogleGeminiReplayHistory(...)` 和 `resolveTaggedReasoningOutputMode()`
- 端点/模型辅助函数，例如 `resolveProviderEndpoint(...)`、`normalizeProviderId(...)`、`normalizeGooglePreviewModelId(...)` 和 `normalizeNativeXaiModelId(...)`
- 共享 replay 构建器，例如 `buildOpenAICompatibleReplayPolicy(...)`、
`buildAnthropicReplayPolicyForModel(...)`、
`buildGoogleGeminiReplayPolicy(...)` 和
`buildHybridAnthropicOrOpenAIReplayPolicy(...)`
- Gemini replay 辅助函数，例如 `sanitizeGoogleGeminiReplayHistory(...)`
和 `resolveTaggedReasoningOutputMode()`
- 端点/模型辅助函数，例如 `resolveProviderEndpoint(...)`、
`normalizeProviderId(...)`、`normalizeGooglePreviewModelId(...)` 和
`normalizeNativeXaiModelId(...)`
`openclaw/plugin-sdk/provider-stream` 同时暴露了家族构建器和这些家族复用的公共包装辅助函数。常见公共导出包括：
`openclaw/plugin-sdk/provider-stream` 同时公开了 family builder
以及这些 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` gating。
有些 stream 辅助函数会有意保持为提供商本地。当前的内置
示例：`@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 特定的推理载荷移除。
其他内置提供商在
行为无法在各 family 之间干净共享时，也会把特定传输的包装器保留在本地。当前示例：内置
xAI 插件将原生 xAI Responses 塑形保留在它自己的
`wrapStreamFn` 中，包括 `/fast` 别名重写、默认 `tool_stream`、
不支持的 strict-tool 清理以及 xAI 特有的 reasoning-payload
删除。
`openclaw/plugin-sdk/provider-tools` 当前暴露了一个共享工具 schema 家族，以及共享 schema/兼容辅助函数：
`openclaw/plugin-sdk/provider-tools` 当前公开了一个共享
tool schema 系列以及共享 schema/compat 辅助函数：
- `ProviderToolCompatFamily` 记录了当前共享家族清单。
- `buildProviderToolCompatFamilyHooks("gemini")` 会为需要 Gemini 安全工具 schema 的提供商接入 Gemini schema 清理 + 诊断。
- `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)` 是底层的公共 Gemini schema 辅助函数。
- `resolveXaiModelCompatPatch()` 返回内置 xAI 兼容补丁：`toolSchemaProfile: "xai"`、不受支持的 schema 关键字、原生 `web_search` 支持，以及 HTML 实体工具调用参数解码。
- `applyXaiModelCompat(model)` 会在模型到达运行器之前，将相同的 xAI 兼容补丁应用到解析后的模型上。
- `ProviderToolCompatFamily` 记录了当前共享的系列清单。
- `buildProviderToolCompatFamilyHooks("gemini")` 为需要 Gemini 安全工具 schema 的提供商接入 Gemini schema
清理 + 诊断。
- `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)`
是底层公开的 Gemini schema 辅助函数。
- `resolveXaiModelCompatPatch()` 返回内置 xAI compat patch：
`toolSchemaProfile: "xai"`、不支持的 schema 关键字、原生
`web_search` 支持，以及 HTML 实体形式的工具调用参数解码。
- `applyXaiModelCompat(model)` 会在解析后的模型到达 runner 之前
对其应用相同的 xAI compat patch。
真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 加上 `contributeResolvedModelCompat`，从而让兼容元数据继续由提供商拥有，而不是在核心中硬编码 xAI 规则。
真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 加
`contributeResolvedModelCompat`，以保持这些 compat 元数据归提供商所有，
而不是在 core 中硬编码 xAI 规则。
相同的包根模式也支撑着其他内置提供商：
相同的 package-root 模式也支撑着其他内置提供商：
- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助函数和 realtime 提供商构建器
- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及 onboarding/配置辅助函数
- `@openclaw/openai-provider`：`api.ts` 导出 provider builders、
默认模型辅助函数和 realtime provider builders
- `@openclaw/openrouter-provider`：`api.ts` 导出 provider builder
以及 onboarding/config 辅助函数
<Tabs>
<Tab title="令牌交换">
@ -347,7 +409,7 @@ x-i18n:
对于需要自定义请求头或请求体修改的提供商：
```typescript
// wrapStreamFn 返回一个从 ctx.streamFn 派生的 StreamFn
// wrapStreamFn 返回一个从 ctx.streamFn 派生出的 StreamFn
wrapStreamFn: (ctx) => {
if (!ctx.streamFn) return undefined;
const inner = ctx.streamFn;
@ -361,8 +423,8 @@ x-i18n:
},
```
</Tab>
<Tab title="原生传输身份">
对于在通用 HTTP 或 WebSocket 传输上需要原生请求/会话头或元数据的提供商：
<Tab title="原生传输标识">
对于需要在通用 HTTP 或 WebSocket 传输上附加原生请求/会话头或元数据的提供商：
```typescript
resolveTransportTurnState: (ctx) => ({
@ -382,8 +444,8 @@ x-i18n:
}),
```
</Tab>
<Tab title="使用量和计费">
对于暴露使用量/计费数据的提供商：
<Tab title="用量和计费">
对于公开用量/计费数据的提供商：
```typescript
resolveUsageAuth: async (ctx) => {
@ -398,72 +460,82 @@ x-i18n:
</Tabs>
<Accordion title="所有可用的提供商 hooks">
OpenClaw 会按以下顺序调用 hooks。大多数提供商只会用到 2-3 个：
OpenClaw 会按以下顺序调用 hooks。大多数提供商只会用到 2 到 3 个：
| # | Hook | 何时使用 |
| --- | --- | --- |
| 1 | `catalog` | 模型目录或基础 URL 默认值 |
| 2 | `applyConfigDefaults` | 配置物化期间由提供商拥有的全局默认值 |
| 3 | `normalizeModelId` | 在查找前清理旧版/预览模型 id 别名 |
| 4 | `normalizeTransport` | 在通用模型组装前清理提供商家族的 `api` / `baseUrl` |
| 5 | `normalizeConfig` | 标准化 `models.providers.<id>` 配置 |
| 6 | `applyNativeStreamingUsageCompat` | 配置型提供商的原生流式使用量兼容重写 |
| 7 | `resolveConfigApiKey` | 提供商自有的环境变量标记认证解析 |
| 8 | `resolveSyntheticAuth` | 本地/自托管或基于配置的合成认证 |
| 9 | `shouldDeferSyntheticProfileAuth` | 将合成存储配置文件占位符降到环境变量/配置认证之后 |
| 1 | `catalog` | 模型目录或基础 `base URL` 默认值 |
| 2 | `applyConfigDefaults` | 配置具体化期间由提供商拥有的全局默认值 |
| 3 | `normalizeModelId` | 查找前的旧版/预览模型 ID 别名清理 |
| 4 | `normalizeTransport` | 通用模型组装前，针对提供商系列的 `api` / `baseUrl` 清理 |
| 5 | `normalizeConfig` | 规范化 `models.providers.<id>` 配置 |
| 6 | `applyNativeStreamingUsageCompat` | 面向配置提供商的原生流式用量 compat 重写 |
| 7 | `resolveConfigApiKey` | 由提供商拥有的 env-marker 认证解析 |
| 8 | `resolveSyntheticAuth` | 本地/自托管或由配置支持的 synthetic auth |
| 9 | `shouldDeferSyntheticProfileAuth` | 将 synthetic 的已存储 profile 占位符置于 env/config auth 之后 |
| 10 | `resolveDynamicModel` | 接受任意上游模型 ID |
| 11 | `prepareDynamicModel` | 解析前进行异步元数据抓取 |
| 12 | `normalizeResolvedModel` | 在运行器之前进行传输重写 |
| 11 | `prepareDynamicModel` | 解析前的异步元数据获取 |
| 12 | `normalizeResolvedModel` | runner 之前的传输重写 |
运行时回退说明：
- `normalizeConfig` 会先检查匹配的提供商，再检查其他具备 hook 能力的提供商插件，直到其中一个实际修改了配置。如果没有提供商 hook 重写受支持的 Google 家族配置条目，内置的 Google 配置标准化器仍会生效。
- 当 `resolveConfigApiKey` 被暴露时，会使用该提供商 hook。内置的 `amazon-bedrock` 路径在这里也有 AWS 环境变量标记解析器，尽管 Bedrock 运行时认证本身仍使用 AWS SDK 默认链。
| 13 | `contributeResolvedModelCompat` | 为另一种兼容传输背后的厂商模型提供兼容标记 |
| 14 | `capabilities` | 旧版静态能力包；仅用于兼容 |
| 15 | `normalizeToolSchemas` | 在注册前由提供商拥有的工具 schema 清理 |
- `normalizeConfig` 会先检查匹配的提供商，然后再检查其他
具备 hook 能力的提供商插件，直到其中一个实际更改配置为止。
如果没有任何 provider hook 重写受支持的 Google 系列配置条目，
内置 Google 配置规范化器仍会应用。
- 如果公开了 provider hook，则 `resolveConfigApiKey` 会使用它。内置的
`amazon-bedrock` 路径在这里也有一个内建的 AWS env-marker 解析器，
即使 Bedrock 运行时认证本身仍然使用 AWS SDK 默认链。
| 13 | `contributeResolvedModelCompat` | 为运行在其他兼容传输之后的供应商模型提供 compat 标志 |
| 14 | `capabilities` | 旧版静态能力包；仅用于兼容性 |
| 15 | `normalizeToolSchemas` | 注册前由提供商拥有的工具 schema 清理 |
| 16 | `inspectToolSchemas` | 由提供商拥有的工具 schema 诊断 |
| 17 | `resolveReasoningOutputMode` | 带标签还是原生的推理输出契约 |
| 17 | `resolveReasoningOutputMode` | 带标签 vs 原生 reasoning-output 契约 |
| 18 | `prepareExtraParams` | 默认请求参数 |
| 19 | `createStreamFn` | 完全自定义的 StreamFn 传输 |
| 20 | `wrapStreamFn` | 正常流路径上的自定义请求头/请求体包装器 |
| 21 | `resolveTransportTurnState` | 原生每轮请求头/元数据 |
| 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话头/冷却 |
| 23 | `formatApiKey` | 自定义运行时令牌形状 |
| 20 | `wrapStreamFn` | 常规流路径上的自定义请求头/请求体包装器 |
| 21 | `resolveTransportTurnState` | 原生逐轮请求头/元数据 |
| 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话请求头/冷却时间 |
| 23 | `formatApiKey` | 自定义运行时令牌形态 |
| 24 | `refreshOAuth` | 自定义 OAuth 刷新 |
| 25 | `buildAuthDoctorHint` | 认证修复指导 |
| 26 | `matchesContextOverflowError` | 提供商自有的溢出检测 |
| 27 | `classifyFailoverReason` | 提供商自有的限流/过载分类 |
| 28 | `isCacheTtlEligible` | 提示缓存 TTL gating |
| 25 | `buildAuthDoctorHint` | 认证修复指引 |
| 26 | `matchesContextOverflowError` | 由提供商拥有的溢出检测 |
| 27 | `classifyFailoverReason` | 由提供商拥有的限流/过载分类 |
| 28 | `isCacheTtlEligible` | 提示词缓存 TTL 门控 |
| 29 | `buildMissingAuthMessage` | 自定义缺失认证提示 |
| 30 | `suppressBuiltInModel` | 隐藏陈旧的上游条目 |
| 31 | `augmentModelCatalog` | 合成的前向兼容目录条目 |
| 32 | `isBinaryThinking` | 二元 thinking 开/关 |
| 33 | `supportsXHighThinking` | `xhigh` 推理支持 |
| 31 | `augmentModelCatalog` | synthetic 向前兼容条目 |
| 32 | `isBinaryThinking` | 二进制 thinking 开/关 |
| 33 | `supportsXHighThinking` | `xhigh` reasoning 支持 |
| 34 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略 |
| 35 | `isModernModelRef` | live/smoke 模型匹配 |
| 36 | `prepareRuntimeAuth` | 推理前的令牌交换 |
| 37 | `resolveUsageAuth` | 自定义使用量凭证解析 |
| 38 | `fetchUsageSnapshot` | 自定义使用量端点 |
| 39 | `createEmbeddingProvider` | 用于 memory/search 的提供商自有 embedding 适配器 |
| 40 | `buildReplayPolicy` | 自定义转录重放/压缩策略 |
| 41 | `sanitizeReplayHistory` | 通用清理后由提供商特定执行的重放重写 |
| 42 | `validateReplayTurns` | 嵌入式运行器前的严格重放轮次校验 |
| 37 | `resolveUsageAuth` | 自定义用量凭证解析 |
| 38 | `fetchUsageSnapshot` | 自定义用量端点 |
| 39 | `createEmbeddingProvider` | 由提供商拥有的记忆/搜索 embedding 适配器 |
| 40 | `buildReplayPolicy` | 自定义转录 replay/压缩策略 |
| 41 | `sanitizeReplayHistory` | 通用清理后的提供商特定 replay 重写 |
| 42 | `validateReplayTurns` | 嵌入式 runner 之前的严格 replay turn 校验 |
| 43 | `onModelSelected` | 选择模型后的回调（例如遥测） |
提示词调优说明：
- `resolveSystemPromptContribution` 允许提供商为某个模型家族注入具备缓存感知的系统提示词指导。当行为属于单个提供商/模型家族且需要保留稳定/动态缓存拆分时，应优先使用它，而不是 `before_prompt_build`。
- `resolveSystemPromptContribution` 允许提供商为某个模型系列注入
具备缓存感知能力的 system-prompt 指引。当该行为属于某个提供商/模型
系列，且应保留稳定/动态缓存拆分时，优先使用它，而不是
`before_prompt_build`。
有关详细说明和真实示例，请参见
[内部机制：提供商运行时 hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
[内部机制：提供商运行时 Hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
</Accordion>
</Step>
<Step title="添加额外能力（可选）">
<a id="step-5-add-extra-capabilities"></a>
提供商插件除了文本推理外，还可以注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和网页搜索：
除文本推理外，提供商插件还可以注册语音、实时转录、实时
语音、媒体理解、图像生成、视频生成、web 抓取
和 web 搜索：
```typescript
register(api) {
@ -560,7 +632,8 @@ x-i18n:
}
```
OpenClaw 会将其归类为**混合能力**插件。这是公司级插件的推荐模式（每个厂商一个插件）。参见
OpenClaw 会将其归类为**混合能力**插件。这是
公司插件（每个供应商一个插件）的推荐模式。参见
[内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。
</Step>
@ -569,7 +642,7 @@ x-i18n:
<a id="step-6-test"></a>
```typescript src/provider.test.ts
import { describe, it, expect } from "vitest";
// 从 index.ts 或专用文件中导出你的提供商配置对象
// 从 index.ts 或专门的文件中导出你的 provider 配置对象
import { acmeProvider } from "./provider.js";
describe("acme-ai provider", () => {
@ -609,7 +682,7 @@ clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```
这里不要使用旧版的仅 Skills 发布别名；插件包应使用
这里不要使用旧版的仅限 skill 的发布别名；插件包应使用
`clawhub package publish`。
## 文件结构
@ -621,23 +694,24 @@ clawhub package publish your-org/your-plugin
├── index.ts # definePluginEntry + registerProvider
└── src/
├── provider.test.ts # 测试
└── usage.ts # 使用量端点（可选）
└── usage.ts # 用量端点（可选）
```
## 目录顺序参考
`catalog.order` 控制你的目录相对于内置提供商的合并时机：
`catalog.order` 控制你的目录相对于内置
提供商何时合并：
| Order | 时机 | 用例 |
| --------- | ------------- | ------------------------------------------- |
| `simple` | 第一轮 | 纯 API key 提供商 |
| `profile` | 在 simple 之后 | 受认证配置文件控制的提供商 |
| `paired` | 在 profile 之后 | 合成多个相关条目 |
| `late` | 最后一轮 | 覆盖现有提供商（冲突时胜出） |
| Order | 何时 | 使用场景 |
| --------- | ------------- | ----------------------------------------------- |
| `simple` | 第一阶段 | 纯 API 密钥提供商 |
| `profile` | 在 simple 之后 | 受 auth profile 控制的提供商 |
| `paired` | 在 profile 之后 | 合成多个相关条目 |
| `late` | 最后阶段 | 覆盖现有提供商（冲突时生效） |
## 下一步
## 后续步骤
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 如果你的插件也提供一个渠道
- [插件运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助函数（TTS、搜索、subagent）
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 如果你的插件还提供一个渠道
- [插件运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助函数（TTS、搜索、子智能体）
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考
- [插件内部机制](/zh-CN/plugins/architecture#provider-runtime-hooks) — hook 详情和内置示例
- [插件内部机制](/zh-CN/plugins/architecture#provider-runtime-hooks) — hook 细节和内置示例

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

@ -1,38 +1,43 @@
---
read_when:
- 你想在 OpenClaw 中使用 Anthropic 模型
summary: 在 OpenClaw 中通过 API 密钥使用 Anthropic Claude
summary: 在 OpenClaw 中通过 API key 使用 Anthropic Claude
title: Anthropic
x-i18n:
generated_at: "2026-04-05T17:48:50Z"
generated_at: "2026-04-05T18:14:50Z"
model: gpt-5.4
provider: openai
source_hash: 6af35571debf5889b63e3b4f6a05aa4e046f39740287e6e1c492916ca00df44b
source_hash: bbc6c4938674aedf20ff944bc04e742c9a7e77a5ff10ae4f95b5718504c57c2d
source_path: providers/anthropic.md
workflow: 15
---
# Anthropic (Claude)
# Anthropic（Claude）
Anthropic 构建了 **Claude** 模型家族，并通过 API 提供访问。
在 OpenClaw 中，新的 Anthropic 设置应使用 API 密钥。现有的旧版
Anthropic token 配置档案如果已经配置，运行时仍会继续生效。
在 OpenClaw 中，新的 Anthropic 设置应使用 API key。现有的旧版
Anthropic token 配置文件如果已经配置，运行时仍会继续支持。
<Warning>
对于 OpenClaw 中的 Anthropic，计费划分如下：
在 OpenClaw 中使用 Anthropic 时，计费方式分为：
- **Anthropic API 密钥**：普通的 Anthropic API 计费。
- **OpenClaw 内的 Claude 订阅认证**：Anthropic 已于
**2026 年 4 月 4 日太平洋时间中午 12:00 / 英国夏令时晚上 8:00**
告知 OpenClaw 用户，这被视为第三方 harness 使用，需要 **Extra Usage**（按量付费，与订阅分开计费）。
- **Anthropic API key**：标准 Anthropic API 计费。
- **OpenClaw 内的 Claude 订阅认证**：Anthropic 于
**2026 年 4 月 4 日太平洋时间中午 12:00 / 英国夏令时间晚上 8:00**
告知 OpenClaw 用户，这属于第三方 harness 使用，因此需要 **Extra Usage**（按量付费，
与订阅分开计费）。
我们的本地复现与这一划分一致：
我们的本地复现结果也符合这一划分：
- 直接 `claude -p` 可能仍然可用
- `claude -p --append-system-prompt ...` 在提示词标识为 OpenClaw 时，可能触发 Extra Usage 限制
- 相同的类 OpenClaw 系统提示词，在 Anthropic SDK + `ANTHROPIC_API_KEY` 路径上**不会**复现该拦截
- 直接使用 `claude -p` 可能仍然可用
- `claude -p --append-system-prompt ...` 在提示词表明 OpenClaw
身份时，可能会触发 Extra Usage 限制
- 相同的类 OpenClaw 系统提示词，在 Anthropic SDK + `ANTHROPIC_API_KEY`
路径上**不会**复现该拦截
因此，实际规则是：**Anthropic API 密钥，或启用了 Extra Usage 的 Claude 订阅**。如果你想要最清晰的生产路径，请使用 Anthropic API 密钥。
所以实际规则是：**Anthropic API key，或启用了
Extra Usage 的 Claude 订阅**。如果你想采用最明确的生产环境方案，请使用 Anthropic API
key。
Anthropic 当前的公开文档：
@ -42,17 +47,17 @@ Anthropic 当前的公开文档：
- [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
如果你想要最清晰的计费路径，请改用 Anthropic API 密钥。
OpenClaw 还支持其他订阅式选项，包括 [OpenAI
如果你希望采用最明确的计费路径，请改用 Anthropic API key。
OpenClaw 也支持其他订阅式选项，包括 [OpenAI
Codex](/zh-CN/providers/openai)、[Qwen Cloud Coding Plan](/zh-CN/providers/qwen)、
[MiniMax Coding Plan](/zh-CN/providers/minimax) 和 [Z.AI / GLM Coding
Plan](/zh-CN/providers/glm)。
</Warning>
## 选项 A：Anthropic API 密钥
## 选项 A：Anthropic API key
**最适合：** 标准 API 访问和按量计费。
请在 Anthropic Console 中创建你的 API 密钥。
请在 Anthropic Console 中创建你的 API key。
### CLI 设置
@ -84,7 +89,7 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
## 快速模式（Anthropic API）
OpenClaw 的共享 `/fast` 开关也支持直连公共 Anthropic 流量，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证请求。
OpenClaw 的共享 `/fast` 开关也支持直接面向公开 Anthropic 的流量，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 认证请求。
- `/fast on` 映射为 `service_tier: "auto"`
- `/fast off` 映射为 `service_tier: "standard_only"`
@ -106,23 +111,23 @@ OpenClaw 的共享 `/fast` 开关也支持直连公共 Anthropic 流量，包括
重要限制：
- OpenClaw 仅会为直连 `api.anthropic.com` 的请求注入 Anthropic service tiers。如果你通过代理或 Gateway 网关路由 `anthropic/*`，`/fast` 不会修改 `service_tier`。
- 如果同时设置了显式 Anthropic `serviceTier` 或 `service_tier` 模型参数，它们会覆盖 `/fast` 默认值。
- Anthropic 会在响应中的 `usage.service_tier` 下报告实际生效的层级。对于没有 Priority Tier 容量的账户，`service_tier: "auto"` 仍可能解析为 `standard`。
- OpenClaw 仅会为直接发往 `api.anthropic.com` 的请求注入 Anthropic service tier。如果你通过代理或 Gateway 网关路由 `anthropic/*`，`/fast` 不会修改 `service_tier`。
- 如果同时设置了显式 Anthropic `serviceTier` 或 `service_tier` 模型参数，则它们会覆盖 `/fast` 的默认值。
- Anthropic 会在响应中的 `usage.service_tier` 报告实际生效的 tier。对于没有 Priority Tier 容量的账户，`service_tier: "auto"` 仍可能解析为 `standard`。
## 提示词缓存（Anthropic API）
OpenClaw 支持 Anthropic 的提示词缓存功能。这是**仅限 API**的；旧版 Anthropic token 认证不会遵循缓存设置。
OpenClaw 支持 Anthropic 的提示词缓存功能。这**仅适用于 API**；旧版 Anthropic token 认证不会遵循缓存设置。
### 配置
在你的模型配置中使用 `cacheRetention` 参数：
| 值 | 缓存时长 | 说明 |
| ------- | -------- | ---------------- |
| `none` | 无缓存 | 禁用提示词缓存 |
| `short` | 5 分钟 | API 密钥认证默认 |
| `long` | 1 小时 | 扩展缓存 |
| 值 | 缓存时长 | 说明 |
| ------- | -------- | -------------------- |
| `none` | 不缓存 | 禁用提示词缓存 |
| `short` | 5 分钟 | API key 认证的默认值 |
| `long` | 1 小时 | 扩展缓存 |
```json5
{
@ -140,9 +145,9 @@ OpenClaw 支持 Anthropic 的提示词缓存功能。这是**仅限 API**的；
### 默认值
使用 Anthropic API 密钥认证时，OpenClaw 会自动为所有 Anthropic 模型应用 `cacheRetention: "short"`（5 分钟缓存）。你可以通过在配置中显式设置 `cacheRetention` 来覆盖这一行为。
使用 Anthropic API Key 认证时，OpenClaw 会自动对所有 Anthropic 模型应用 `cacheRetention: "short"`（5 分钟缓存）。你可以通过在配置中显式设置 `cacheRetention` 来覆盖它。
### 按智能体覆盖 cacheRetention
### 按智能体覆盖 `cacheRetention`
将模型级参数作为基线，然后通过 `agents.list[].params` 覆盖特定智能体。
@ -159,29 +164,30 @@ OpenClaw 支持 Anthropic 的提示词缓存功能。这是**仅限 API**的；
},
list: [
{ id: "research", default: true },
{ id: "alerts", params: { cacheRetention: "none" } }, // 仅为此智能体覆盖
{ id: "alerts", params: { cacheRetention: "none" } }, // 仅覆盖此智能体
],
},
}
```
与缓存相关参数的配置合并顺序：
与缓存相关的配置合并顺序：
1. `agents.defaults.models["provider/model"].params`
2. `agents.list[].params`（匹配 `id`，按键覆盖）
这使得一个智能体可以保持长期缓存，而另一个使用相同模型的智能体则可以禁用缓存，以避免突发/低复用流量的写入成本。
这样就可以让一个智能体保留长期缓存，而另一个使用同一模型的智能体禁用缓存，以避免突发性/低复用流量带来的写入成本。
### Bedrock Claude 说明
- Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）在配置时接受 `cacheRetention` 透传。
- Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）在配置后可透传 `cacheRetention`。
- 非 Anthropic 的 Bedrock 模型会在运行时被强制设为 `cacheRetention: "none"`。
- 当未设置显式值时，Anthropic API 密钥智能默认值也会为 Claude-on-Bedrock 模型引用填充 `cacheRetention: "short"`。
- 当未设置显式值时，Anthropic API key 的智能默认值也会为 Claude-on-Bedrock 模型引用填入 `cacheRetention: "short"`。
## 100 万上下文窗口（Anthropic beta）
Anthropic 的 100 万上下文窗口受 beta 权限控制。在 OpenClaw 中，
可对受支持的 Opus/Sonnet 模型按模型启用 `params.context1m: true`。
对受支持的 Opus/Sonnet 模型，可通过为每个模型设置
`params.context1m: true` 启用。
```json5
{
@ -197,61 +203,73 @@ Anthropic 的 100 万上下文窗口受 beta 权限控制。在 OpenClaw 中，
}
```
OpenClaw 会将其映射为 Anthropic 请求上的
OpenClaw 会将其映射为 Anthropic 请求中的
`anthropic-beta: context-1m-2025-08-07`。
只有在该模型明确设置 `params.context1m` 为 `true` 时，这一功能才会启用。
只有当该模型的 `params.context1m` 被显式设置为 `true` 时，
此功能才会启用。
要求：Anthropic 必须允许该凭证使用长上下文
（通常是 API 密钥计费，或 OpenClaw 的 Claude 登录路径 / 启用了 Extra Usage 的旧版 token 认证）。否则 Anthropic 会返回：
（通常是 API key 计费，或 OpenClaw 的 Claude 登录路径 / 启用了
Extra Usage 的旧版 token 认证）。否则 Anthropic 会返回：
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。
注意：Anthropic 当前会在使用旧版 Anthropic token 认证（`sk-ant-oat-*`）时拒绝 `context-1m-*` beta 请求。如果你在该旧版认证模式下配置了 `context1m: true`，OpenClaw 会记录一条警告，并通过跳过 context1m beta 标头而保留所需的 OAuth beta 标头，从而回退到标准上下文窗口。
注意：Anthropic 当前在使用
旧版 Anthropic token 认证（`sk-ant-oat-*`）时，会拒绝 `context-1m-*`
beta 请求。如果你在这种旧版认证模式下配置了
`context1m: true`，OpenClaw 会记录一条警告，并通过跳过 context1m beta
header 回退到标准上下文窗口，同时保留所需的 OAuth beta。
## 已移除：Claude CLI 后端
内置的 Anthropic `claude-cli` 后端已被移除。
- Anthropic 在 2026 年 4 月 4 日的通知中指出，由 OpenClaw 驱动的 Claude 登录流量属于第三方 harness 使用，需要 **Extra Usage**。
- 我们的本地复现还表明，直接
`claude -p --append-system-prompt ...` 在附加提示词标识为 OpenClaw 时，也可能触发相同限制。
- Anthropic 在 2026 年 4 月 4 日的通知中表示，由 OpenClaw 驱动的 Claude 登录流量属于
第三方 harness 使用，因此需要 **Extra Usage**。
- 我们的本地复现也显示，直接使用
`claude -p --append-system-prompt ...` 在附加提示词表明 OpenClaw
身份时，也可能触发同样的限制。
- 相同的类 OpenClaw 系统提示词，在
Anthropic SDK + `ANTHROPIC_API_KEY` 路径上不会触发该限制。
- 在 OpenClaw 中处理 Anthropic 流量时，请使用 Anthropic API 密钥。
- 如果你需要本地 CLI 回退运行时，请使用其他受支持的 CLI 后端，例如 Codex CLI。请参阅 [/gateway/cli-backends](/zh-CN/gateway/cli-backends)。
- 在 OpenClaw 中处理 Anthropic 流量时，请使用 Anthropic API key。
## 说明
- Anthropic 的公开 Claude Code 文档仍然记录了直接 CLI 用法，例如
`claude -p`，但 Anthropic 单独向 OpenClaw 用户发出的通知指出，
**OpenClaw** 的 Claude 登录路径属于第三方 harness 使用，需要
`claude -p`，但 Anthropic 面向 OpenClaw 用户的单独通知指出，
**OpenClaw** 的 Claude 登录路径属于第三方 harness 使用，因此需要
**Extra Usage**（按量付费，与订阅分开计费）。
我们的本地复现还表明，直接
`claude -p --append-system-prompt ...` 在附加提示词标识为 OpenClaw 时也可能触发相同限制，而相同的提示词形态在 Anthropic SDK + `ANTHROPIC_API_KEY` 路径上不会复现。对于生产用途，我们建议改用 Anthropic API 密钥。
- Anthropic setup-token 现已在 OpenClaw 中重新作为旧版/手动路径提供。Anthropic 针对 OpenClaw 的计费通知仍然适用，因此使用该路径时，请预期 Anthropic 会要求 **Extra Usage**。
- 凭证详情 + 复用规则见 [/concepts/oauth](/zh-CN/concepts/oauth)。
我们的本地复现也显示，直接使用
`claude -p --append-system-prompt ...` 在附加提示词表明 OpenClaw
身份时可能触发同样的限制，而相同形式的提示词在
Anthropic SDK + `ANTHROPIC_API_KEY` 路径上不会复现该问题。对于生产环境，我们
建议改用 Anthropic API key。
- Anthropic setup-token 已重新在 OpenClaw 中作为旧版/手动路径提供。Anthropic 针对 OpenClaw 的专用计费通知仍然适用，因此使用此路径时，应预期 Anthropic 会要求 **Extra Usage**。
- 认证细节和复用规则见 [/concepts/oauth](/zh-CN/concepts/oauth)。
## 故障排除
**401 错误 / token 突然失效**
- 旧版 Anthropic token 认证可能会过期或被撤销。
- 对于新的设置，请迁移到 Anthropic API 密钥。
- 旧版 Anthropic token 认证可能过期或被撤销。
- 对于新的设置，请迁移到 Anthropic API key。
**No API key found for provider "anthropic"**
**未找到 provider "anthropic" 的 API key**
- 凭证是**按智能体**隔离的。新智能体不会继承主智能体的密钥。
- 请为该智能体重新运行新手引导，或在 Gateway 网关主机上配置 API 密钥，然后使用 `openclaw models status` 验证。
- 认证是**按智能体**区分的。新智能体不会继承主智能体的 key。
- 重新为该智能体运行新手引导，或在 Gateway 网关
主机上配置 API key，然后使用 `openclaw models status` 验证。
**No credentials found for profile `anthropic:default`**
**未找到配置文件 `anthropic:default` 的凭证**
- 运行 `openclaw models status` 查看当前激活的是哪个凭证配置档案。
- 重新运行新手引导，或为该配置档案路径配置 API 密钥。
- 运行 `openclaw models status` 查看当前激活的是哪个认证配置文件。
- 重新运行新手引导，或为该配置文件路径配置 API key。
**No available auth profile (all in cooldown/unavailable)**
**没有可用的认证配置文件（全部处于冷却中/不可用）**
- 检查 `openclaw models status --json` 中的 `auth.unusableProfiles`。
- Anthropic 的限流冷却可能是按模型划分的，因此即使当前模型处于冷却中，同一 Anthropic 下的其他模型仍可能可用。
- 添加另一个 Anthropic 配置档案或等待冷却结束。
- Anthropic 的速率限制冷却可能是按模型区分的，因此即使当前模型处于冷却中，
同级的另一个 Anthropic 模型仍可能可用。
- 添加另一个 Anthropic 配置文件，或等待冷却结束。
更多信息：[/gateway/troubleshooting](/zh-CN/gateway/troubleshooting) 和 [/help/faq](/zh-CN/help/faq)。
更多内容：[/gateway/troubleshooting](/zh-CN/gateway/troubleshooting) 和 [/help/faq](/zh-CN/help/faq)。

58
docs/zh-CN/providers/google.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 你想在 OpenClaw 中使用 Google Gemini 模型
- 你需要 API 密钥或 OAuth 身份验证流程
summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、Web 搜索）
- 你需要 API 密钥认证流程
summary: Google Gemini 设置（API 密钥、图像生成、媒体理解、Web 搜索）
title: Google（Gemini）
x-i18n:
generated_at: "2026-04-05T08:42:18Z"
generated_at: "2026-04-05T18:14:58Z"
model: gpt-5.4
provider: openai
source_hash: fa3c4326e83fad277ae4c2cb9501b6e89457afcfa7e3e1d57ae01c9c0c6846e2
source_hash: 0df5bcbd98e2c1dafea3e9919e9793533ba785120b24f1db12e8e35b1ad23083
source_path: providers/google.md
workflow: 15
---
@ -18,9 +18,8 @@ x-i18n:
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及通过 Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）和 Web 搜索功能。
- 提供商：`google`
- 身份验证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
- 认证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
- API：Google Gemini API
- 替代提供商：`google-gemini-cli`（OAuth）
## 快速开始
@ -51,39 +50,6 @@ openclaw onboard --non-interactive \
--gemini-api-key "$GEMINI_API_KEY"
```
## OAuth（Gemini CLI）
另一个替代提供商 `google-gemini-cli` 使用 PKCE OAuth，而不是 API 密钥。这是一个非官方集成；一些用户报告了账户限制。请自行承担使用风险。
- 默认模型：`google-gemini-cli/gemini-3.1-pro-preview`
- 别名：`gemini-cli`
- 安装前提：本地可用的 Gemini CLI，命令名为 `gemini`
- Homebrew：`brew install gemini-cli`
- npm：`npm install -g @google/gemini-cli`
- 登录：
```bash
openclaw models auth login --provider google-gemini-cli --set-default
```
环境变量：
- `OPENCLAW_GEMINI_OAUTH_CLIENT_ID`
- `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET`
（或使用 `GEMINI_CLI_*` 变体。）
如果 Gemini CLI 的 OAuth 请求在登录后失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`，然后重试。
如果在浏览器流程开始之前登录就失败，请确认本地 `gemini` 命令已安装并位于 `PATH` 中。OpenClaw 同时支持 Homebrew 安装和全局 npm 安装，包括常见的 Windows/npm 布局。
Gemini CLI JSON 使用说明：
- 回复文本来自 CLI JSON 的 `response` 字段。
- 当 CLI 将 `usage` 留空时，用量会回退到 `stats`。
- `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
- 如果缺少 `stats.input`，OpenClaw 会根据 `stats.input_tokens - stats.cached` 推导输入 token 数。
## 功能
| 功能 | 支持情况 |
@ -94,16 +60,16 @@ Gemini CLI JSON 使用说明：
| 音频转录 | 是 |
| 视频理解 | 是 |
| Web 搜索（Grounding） | 是 |
| 思考/推理 | 是（Gemini 3.1+） |
| Thinking/推理 | 是（Gemini 3.1+） |
## 直接复用 Gemini 缓存
对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw 现在会将已配置的 `cachedContent` 句柄传递给 Gemini 请求。
对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw 现在会将已配置的 `cachedContent` 句柄透传到 Gemini 请求中。
- 可通过 `cachedContent` 或旧版 `cached_content` 为每个模型或全局参数进行配置
- 如果两者同时存在，则 `cachedContent` 优先
- 使用 `cachedContent` 或旧版 `cached_content` 为每个模型或全局参数进行配置
- 如果两者都存在，则 `cachedContent` 优先
- 示例值：`cachedContents/prebuilt-context`
- Gemini 缓存命中用量会根据上游 `cachedContentTokenCount` 规范化为 OpenClaw `cacheRead`
- Gemini 缓存命中的用量会从上游 `cachedContentTokenCount` 规范化为 OpenClaw `cacheRead`
示例：
@ -132,8 +98,8 @@ Gemini CLI JSON 使用说明：
- 编辑模式：已启用，最多支持 5 张输入图像
- 几何控制：`size`、`aspectRatio` 和 `resolution`
仅支持 OAuth 的 `google-gemini-cli` 提供商是一个独立的文本推理接口。图像生成、媒体理解和 Gemini Grounding 仍然使用 `google` 提供商 ID。
图像生成、媒体理解和 Gemini Grounding 都保持使用 `google` 提供商 ID。
## 环境说明
如果 Gateway 网关以守护进程（launchd/systemd）方式运行，请确保该进程可以访问 `GEMINI_API_KEY`（例如，在 `~/.openclaw/.env` 中，或通过 `env.shellEnv`）。
如果 Gateway 网关以守护进程（launchd/systemd）方式运行，请确保 `GEMINI_API_KEY` 对该进程可用（例如，在 `~/.openclaw/.env` 中，或通过 `env.shellEnv`）。

57
docs/zh-CN/providers/models.md
View File

@ -1,21 +1,22 @@
---
read_when:
- 你想选择一个模型提供商
- 你想要用于 LLM 认证和模型选择的快速设置示例
- 你想查看 LLM 认证和模型选择的快速设置示例
summary: OpenClaw 支持的模型提供商（LLM）
title: 模型提供商快速开始
x-i18n:
generated_at: "2026-04-05T08:42:47Z"
generated_at: "2026-04-05T18:14:57Z"
model: gpt-5.4
provider: openai
source_hash: 83e372193b476c7cee6eb9f5c443b03563d863043f47c633ac0096bca642cc6f
source_hash: bc98c65af5737b2c820f4da3304118c2b449d8f0cd363d73922f81087331e93d
source_path: providers/models.md
workflow: 15
---
# 模型提供商
OpenClaw 可以使用许多 LLM 提供商。选择一个，完成认证，然后将默认模型设置为 `provider/model`。
OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证，然后将默认
模型设置为 `provider/model`。
## 快速开始（两步）
@ -30,32 +31,32 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个，完成认证，然后
## 支持的提供商（入门集合）
- [Anthropic（API + Claude CLI）](/providers/anthropic)
- [Amazon Bedrock](/providers/bedrock)
- [BytePlus（国际版）](/concepts/model-providers#byteplus-international)
- [Chutes](/providers/chutes)
- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
- [Fireworks](/providers/fireworks)
- [GLM 模型](/providers/glm)
- [MiniMax](/providers/minimax)
- [Mistral](/providers/mistral)
- [Moonshot AI（Kimi + Kimi Coding）](/providers/moonshot)
- [OpenAI（API + Codex）](/providers/openai)
- [OpenCode（Zen + Go）](/providers/opencode)
- [OpenRouter](/providers/openrouter)
- [Qianfan](/providers/qianfan)
- [Qwen](/providers/qwen)
- [StepFun](/providers/stepfun)
- [Synthetic](/providers/synthetic)
- [Vercel AI Gateway](/providers/vercel-ai-gateway)
- [Venice（Venice AI）](/providers/venice)
- [xAI](/providers/xai)
- [Z.AI](/providers/zai)
- [Anthropic（API + Claude CLI）](/zh-CN/providers/anthropic)
- [Amazon Bedrock](/zh-CN/providers/bedrock)
- [BytePlus（国际版）](/zh-CN/concepts/model-providers#byteplus-international)
- [Chutes](/zh-CN/providers/chutes)
- [Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)
- [Fireworks](/zh-CN/providers/fireworks)
- [GLM 模型](/zh-CN/providers/glm)
- [MiniMax](/zh-CN/providers/minimax)
- [Mistral](/zh-CN/providers/mistral)
- [Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot)
- [OpenAI（API + Codex）](/zh-CN/providers/openai)
- [OpenCode（Zen + Go）](/zh-CN/providers/opencode)
- [OpenRouter](/zh-CN/providers/openrouter)
- [Qianfan](/zh-CN/providers/qianfan)
- [Qwen](/zh-CN/providers/qwen)
- [StepFun](/zh-CN/providers/stepfun)
- [Synthetic](/zh-CN/providers/synthetic)
- [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)
- [Venice（Venice AI）](/zh-CN/providers/venice)
- [xAI](/zh-CN/providers/xai)
- [Z.AI](/zh-CN/providers/zai)
## 其他内置变体
- `anthropic-vertex` - 当 Vertex 凭证可用时，隐式支持 Google Vertex 上的 Anthropic；无需单独的新手引导认证选项
- `anthropic-vertex` - 当 Vertex 凭证可用时，隐式启用 Google Vertex 上的 Anthropic 支持；无需单独的新手引导认证选项
- `copilot-proxy` - 本地 VS Code Copilot Proxy 桥接；使用 `openclaw onboard --auth-choice copilot-proxy`
- `google-gemini-cli` - 非官方 Gemini CLI OAuth 流程；需要本地安装 `gemini`（`brew install gemini-cli` 或 `npm install -g @google/gemini-cli`）；默认模型为 `google-gemini-cli/gemini-3.1-pro-preview`；使用 `openclaw onboard --auth-choice google-gemini-cli` 或 `openclaw models auth login --provider google-gemini-cli --set-default`
如需完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅[模型提供商](/concepts/model-providers)。
关于完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，
请参见 [模型提供商](/zh-CN/concepts/model-providers)。

215
docs/zh-CN/reference/session-management-compaction.md
View File

@ -1,15 +1,15 @@
---
read_when:
- 你需要调试会话 ID、转录 JSONL 或 sessions.json 字段
- 你正在更改自动压缩行为或添加“压缩前”整理逻辑
- 你想实现内存刷新或静默系统轮次
- 你需要调试会话 id、转录 JSONL 或 sessions.json 字段
- 你正在修改自动压缩行为，或添加“压缩前”维护逻辑
- 你想实现记忆刷新或静默系统轮次
summary: 深入解析：会话存储 + 转录、生命周期，以及（自动）压缩内部机制
title: 会话管理深入解析
x-i18n:
generated_at: "2026-04-05T10:08:28Z"
generated_at: "2026-04-05T18:15:37Z"
model: gpt-5.4
provider: openai
source_hash: e379d624dd7808d3af25ed011079268ce6a9da64bb3f301598884ad4c46ab091
source_hash: e0d8c2d30be773eac0424f7a4419ab055fdd50daac8bc654e7d250c891f2c3b8
source_path: reference/session-management-compaction.md
workflow: 15
---
@ -21,12 +21,12 @@ x-i18n:
- **会话路由**（入站消息如何映射到 `sessionKey`）
- **会话存储**（`sessions.json`）及其跟踪内容
- **转录持久化**（`*.jsonl`）及其结构
- **转录整理**（运行前的 provider 特定修正）
- **上下文限制**（上下文窗口与已跟踪 token 的区别）
- **压缩**（手动 + 自动压缩）以及压缩前工作的挂接位置
- **静默整理**（例如不应产生用户可见输出的内存写入）
- **转录清理**（运行前的提供商专用修正）
- **上下文限制**（上下文窗口 vs 已跟踪 token）
- **压缩**（手动 + 自动压缩）以及在何处挂接压缩前逻辑
- **静默维护**（例如不应产生用户可见输出的记忆写入）
如果你想先看一个更高层的概览，请先阅读：
如果你想先看更高层的概览，请从以下文档开始：
- [/concepts/session](/zh-CN/concepts/session)
- [/concepts/compaction](/zh-CN/concepts/compaction)
@ -39,26 +39,26 @@ x-i18n:
## 事实来源：Gateway 网关
OpenClaw 围绕一个拥有会话状态的单一 **Gateway 网关进程** 设计。
OpenClaw 的设计围绕一个拥有会话状态的单一 **Gateway 网关进程**。
- UI（macOS 应用、Web Control UI、TUI）应通过 Gateway 网关查询会话列表和 token 计数。
- UI（macOS 应用、web Control UI、TUI）应向 Gateway 网关查询会话列表和 token 计数。
- 在远程模式下，会话文件位于远程主机上；“检查你本地 Mac 上的文件”并不能反映 Gateway 网关实际使用的内容。
---
## 两层持久化
OpenClaw 通过两层来持久化会话：
OpenClaw 通过两层持久化保存会话：
1. **会话存储（`sessions.json`）**
- 键值映射：`sessionKey -> SessionEntry`
- 小巧、可变、可安全编辑（或删除条目）
- 跟踪会话元数据（当前会话 ID、最后活动时间、开关、token 计数器等）
- 体积小、可变、安全，可编辑（或删除条目）
- 跟踪会话元数据（当前会话 id、最近活动时间、开关、token 计数器等）
2. **转录（`<sessionId>.jsonl`）**
- 具有树结构的追加式转录（条目带有 `id` + `parentId`）
- 采用树结构的追加式转录（条目包含 `id` + `parentId`）
- 存储实际对话 + 工具调用 + 压缩摘要
- 用于为后续轮次重建模型上下文
- 用于为未来轮次重建模型上下文
---
@ -74,25 +74,25 @@ OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。
---
## 存储维护与磁盘控制
## 存储维护和磁盘控制
会话持久化为 `sessions.json` 和转录产物提供自动维护控制（`session.maintenance`）：
会话持久化为 `sessions.json` 和转录产物提供了自动维护控制（`session.maintenance`）：
- `mode`：`warn`（默认）或 `enforce`
- `pruneAfter`：陈旧条目的保留期限阈值（默认 `30d`）
- `maxEntries`：`sessions.json` 中条目数上限（默认 `500`）
- `rotateBytes`：`sessions.json` 过大时轮转（默认 `10mb`）
- `resetArchiveRetention`：`*.reset.<timestamp>` 转录归档的保留期（默认与 `pruneAfter` 相同；`false` 表示禁用清理）
- `pruneAfter`：过期条目的年龄阈值（默认 `30d`）
- `maxEntries`：`sessions.json` 中的条目上限（默认 `500`）
- `rotateBytes`：当 `sessions.json` 过大时轮转（默认 `10mb`）
- `resetArchiveRetention`：`*.reset.<timestamp>` 转录归档的保留期（默认：与 `pruneAfter` 相同；`false` 表示禁用清理）
- `maxDiskBytes`：可选的会话目录磁盘预算
- `highWaterBytes`：清理后的可选目标值（默认是 `maxDiskBytes` 的 `80%`）
磁盘预算清理的执行顺序（`mode: "enforce"`）：
1. 优先删除最旧的归档或孤立转录产物。
2. 如果仍高于目标值，则逐出最旧的会话条目及其转录文件。
3. 持续执行，直到使用量低于或等于 `highWaterBytes`。
2. 如果仍高于目标值，则驱逐最旧的会话条目及其转录文件。
3. 持续执行，直到使用量小于等于 `highWaterBytes`。
在 `mode: "warn"` 下，OpenClaw 会报告潜在逐出项，但不会修改存储或文件。
在 `mode: "warn"` 下，OpenClaw 会报告潜在驱逐项，但不会修改存储/文件。
按需运行维护：
@ -103,69 +103,69 @@ openclaw sessions cleanup --enforce
---
## Cron 会话与运行日志
## 定时任务会话和运行日志
隔离的 cron 运行也会创建会话条目/转录，并具有专用保留控制：
隔离的 cron 运行也会创建会话条目/转录，并且它们有专门的保留控制：
- `cron.sessionRetention`（默认 `24h`）会从会话存储中清理旧的隔离 cron 运行会话（`false` 表示禁用）。
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` 会清理 `~/.openclaw/cron/runs/<jobId>.jsonl` 文件（默认分别为 `2_000_000` 字节和 `2000` 行）。
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` 会清理 `~/.openclaw/cron/runs/<jobId>.jsonl` 文件（默认：`2_000_000` 字节和 `2000` 行）。
---
## 会话键（`sessionKey`）
`sessionKey` 用于标识你处于_哪个对话桶_中（路由 + 隔离）。
`sessionKey` 用于标识你当前处于 _哪个对话桶_ 中（路由 + 隔离）。
常见模式：
- 主/直接聊天（每个智能体）：`agent:<agentId>:<mainKey>`（默认 `main`）
- 群组：`agent:<agentId>:<channel>:group:<id>`
- 房间/频道（Discord/Slack）：`agent:<agentId>:<channel>:channel:<id>` 或 `...:room:<id>`
- 房间/渠道（Discord/Slack）：`agent:<agentId>:<channel>:channel:<id>` 或 `...:room:<id>`
- Cron：`cron:<job.id>`
- Webhook：`hook:<uuid>`（除非被覆盖）
规范规则记录在 [/concepts/session](/zh-CN/concepts/session) 中。
规范规则见 [/concepts/session](/zh-CN/concepts/session)。
---
## 会话 ID（`sessionId`）
## 会话 id（`sessionId`）
每个 `sessionKey` 都指向一个当前 `sessionId`（继续该对话的转录文件）。
每个 `sessionKey` 都指向当前的 `sessionId`（即继续该对话的转录文件）。
经验规则：
- **重置**（`/new`、`/reset`）会为该 `sessionKey` 创建新的 `sessionId`。
- **每日重置**（默认是 Gateway 网关主机本地时间凌晨 4:00）会在跨过重置边界后的下一条消息时创建新的 `sessionId`。
- **空闲过期**（`session.reset.idleMinutes` 或旧版 `session.idleMinutes`）会在消息于空闲窗口后到达时创建新的 `sessionId`。当每日重置和空闲过期同时配置时，以先到期者为准。
- **线程父级分叉保护**（`session.parentForkMaxTokens`，默认 `100000`）会在父会话已经过大时跳过父转录分叉；新线程将从头开始。设置为 `0` 可禁用。
- **每日重置**（默认是 Gateway 网关主机本地时间凌晨 4:00）会在越过重置边界后的下一条消息上创建新的 `sessionId`。
- **空闲过期**（`session.reset.idleMinutes` 或旧版 `session.idleMinutes`）会在消息于空闲窗口之后到达时创建新的 `sessionId`。当同时配置每日重置和空闲过期时，以先到者为准。
- **线程父级分叉保护**（`session.parentForkMaxTokens`，默认 `100000`）会在父会话已过大时跳过父转录分叉；新线程将从空白开始。设为 `0` 可禁用。
实现细节：该决策发生在 `src/auto-reply/reply/session.ts` 中的 `initSessionState()`。
实现细节：该决策发生在 `src/auto-reply/reply/session.ts` 的 `initSessionState()` 中。
---
## 会话存储模式（`sessions.json`）
## 会话存储 schema（`sessions.json`）
存储的值类型是 `src/config/sessions.ts` 中的 `SessionEntry`。
关键字段（非完整列表）：
- `sessionId`：当前转录 ID（除非设置了 `sessionFile`，否则文件名由此派生）
- `updatedAt`：最后活动时间戳
- `sessionId`：当前转录 id（除非设置了 `sessionFile`，否则文件名由它推导）
- `updatedAt`：最近活动时间戳
- `sessionFile`：可选的显式转录路径覆盖
- `chatType`：`direct | group | room`（帮助 UI 和发送策略）
- `provider`、`subject`、`room`、`space`、`displayName`：用于群组/频道标签的元数据
- `provider`、`subject`、`room`、`space`、`displayName`：用于群组/渠道标签的元数据
- 开关：
- `thinkingLevel`、`verboseLevel`、`reasoningLevel`、`elevatedLevel`
- `sendPolicy`（按会话覆盖）
- 模型选择：
- `providerOverride`、`modelOverride`、`authProfileOverride`
- token 计数器（尽力而为 / 依赖 provider）：
- token 计数器（尽力而为 / 依赖提供商）：
- `inputTokens`、`outputTokens`、`totalTokens`、`contextTokens`
- `compactionCount`：此会话键完成自动压缩的次数
- `memoryFlushAt`：上次压缩前内存刷新时间戳
- `memoryFlushCompactionCount`：上次刷新运行时的压缩计数
- `memoryFlushAt`：最近一次压缩前记忆刷新的时间戳
- `memoryFlushCompactionCount`：上一次刷新运行时的压缩计数
该存储可安全编辑，但 Gateway 网关才是权威：随着会话运行，它可能会重写或重新注入条目。
该存储可以安全编辑，但 Gateway 网关是权威来源：会话运行时它可能重写或重新填充条目。
---
@ -173,57 +173,60 @@ openclaw sessions cleanup --enforce
转录由 `@mariozechner/pi-coding-agent` 的 `SessionManager` 管理。
该文件为 JSONL：
该文件为 JSONL 格式：
- 第一行：会话头（`type: "session"`，包含 `id`、`cwd`、`timestamp` 和可选的 `parentSession`）
- 之后：带有 `id` + `parentId` 的会话条目（树结构）
- 第一行：会话头（`type: "session"`，包含 `id`、`cwd`、`timestamp`、可选的 `parentSession`）
- 后续：带有 `id` + `parentId` 的会话条目（树结构）
值得注意的条目类型：
- `message`：用户/助手/`toolResult` 消息
- `custom_message`：由扩展注入、_会_进入模型上下文的消息（可对 UI 隐藏）
- `custom`：_不会_进入模型上下文的扩展状态
- `custom_message`：由扩展注入、_会_ 进入模型上下文的消息（可对 UI 隐藏）
- `custom`：_不会_ 进入模型上下文的扩展状态
- `compaction`：持久化的压缩摘要，带有 `firstKeptEntryId` 和 `tokensBefore`
- `branch_summary`：导航树分支时的持久化摘要
- `branch_summary`：导航树分支时持久化的摘要
OpenClaw 有意**不会**“修正”转录；Gateway 网关使用 `SessionManager` 读取/写入它们。
OpenClaw 有意**不会**“修正”转录；Gateway 网关使用 `SessionManager` 读写它们。
---
## 上下文窗口与已跟踪 token
## 上下文窗口 vs 已跟踪 token
这里涉及两个不同概念：
这里有两个不同的概念：
1. **模型上下文窗口**：每个模型的硬上限（模型可见 token 数）
1. **模型上下文窗口**：每个模型的硬上限（模型可见的 token）
2. **会话存储计数器**：写入 `sessions.json` 的滚动统计（用于 `/status` 和仪表板）
如果你在调优限制：
如果你正在调整限制：
- 上下文窗口来自模型目录（并且可通过配置覆盖）。
- 存储中的 `contextTokens` 是运行时估算/报告值；不要将其视为严格保证。
- 上下文窗口来自模型目录（也可通过配置覆盖）。
- 存储中的 `contextTokens` 是运行时估算/报告值；不要把它当作严格保证。
更多信息请参阅 [/token-use](/zh-CN/reference/token-use)。
更多信息请参见 [/token-use](/zh-CN/reference/token-use)。
---
## 压缩：它是什么
压缩会将较早的对话总结为转录中持久化的 `compaction` 条目，并保留最近消息不变。
压缩会将较早的对话总结成转录中的持久化 `compaction` 条目，并保留最近消息不变。
压缩后，后续轮次将看到：
压缩后，未来轮次会看到：
- 压缩摘要
- `firstKeptEntryId` 之后的消息
压缩是**持久化的**（不同于会话修剪）。请参阅 [/concepts/session-pruning](/zh-CN/concepts/session-pruning)。
压缩是**持久的**（不同于会话裁剪）。参见 [/concepts/session-pruning](/zh-CN/concepts/session-pruning)。
## 压缩块边界与工具配对
## 压缩分块边界和工具配对
当 OpenClaw 将较长转录拆分为压缩块时，它会保持助手工具调用与其匹配的 `toolResult` 条目成对出现。
当 OpenClaw 将长转录拆分为压缩分块时，它会保持
助手工具调用与其对应 `toolResult` 条目配对。
- 如果 token 占比分割点落在工具调用和其结果之间，OpenClaw 会将边界移动到助手工具调用消息处，而不是拆开这一对。
- 如果尾部 `toolResult` 块原本会使压缩块超出目标大小，OpenClaw 会保留这个待处理工具块，并保持未摘要的尾部完整。
- 已中止/出错的工具调用块不会阻止待处理分割继续进行。
- 如果 token 占比分割点落在工具调用和其结果之间，OpenClaw
会将边界移动到助手工具调用消息处，而不是拆散这一对。
- 如果尾部的工具结果块原本会将分块推过目标大小，OpenClaw
会保留这段待处理工具块，并保持未总结的尾部完整。
- 已中止/报错的工具调用块不会让待处理分割持续保持打开状态。
---
@ -235,8 +238,8 @@ OpenClaw 有意**不会**“修正”转录；Gateway 网关使用 `SessionManag
（`request_too_large`、`context length exceeded`、`input exceeds the maximum
number of tokens`、`input token count exceeds the maximum number of input
tokens`、`input is too long for the model`、`ollama error: context length
exceeded`，以及类似的 provider 特定变体）→ 压缩 → 重试。
2. **阈值维护**：在成功完成一轮后，当：
exceeded`，以及类似的提供商形式变体）→ 压缩 → 重试。
2. **阈值维护**：在一次成功轮次之后，当：
`contextTokens > contextWindow - reserveTokens`
@ -245,7 +248,7 @@ exceeded`，以及类似的 provider 特定变体）→ 压缩 → 重试。
- `contextWindow` 是模型的上下文窗口
- `reserveTokens` 是为提示词 + 下一次模型输出预留的余量
这些是 Pi 运行时语义（OpenClaw 消费这些事件，但由 Pi 决定何时压缩）。
这些是 Pi 运行时语义（OpenClaw 会消费这些事件，但由 Pi 决定何时压缩）。
---
@ -263,21 +266,21 @@ Pi 的压缩设置位于 Pi settings 中：
}
```
OpenClaw 还会对嵌入式运行强制执行一个安全下限：
OpenClaw 还会为嵌入式运行施加一个安全下限：
- 如果 `compaction.reserveTokens < reserveTokensFloor`，OpenClaw 会将其提高。
- 默认下限为 `20000` token。
- 默认下限是 `20000` token。
- 设置 `agents.defaults.compaction.reserveTokensFloor: 0` 可禁用该下限。
- 如果它已经更高，OpenClaw 不会更改。
- 如果它本来就更高，OpenClaw 不会改动。
原因：在压缩不可避免之前，为多轮“整理”操作（例如内存写入）保留足够余量。
原因：在压缩变得不可避免之前，为多轮“维护”操作（例如记忆写入）预留足够余量。
实现：`src/agents/pi-settings.ts` 中的 `ensurePiCompactionReserveTokens()`
（由 `src/agents/pi-embedded-runner.ts` 调用）。
---
## 面向用户的可见接口
## 面向用户的可见表面
你可以通过以下方式观察压缩和会话状态：
@ -288,33 +291,37 @@ OpenClaw 还会对嵌入式运行强制执行一个安全下限：
---
## 静默整理（`NO_REPLY`）
## 静默维护（`NO_REPLY`）
OpenClaw 支持用于后台任务的“静默”轮次，在这种情况下用户不应看到中间输出。
OpenClaw 支持“静默”轮次，用于用户不应看到中间输出的后台任务。
约定如下：
约定：
- 助手以精确的静默标记 `NO_REPLY` / `no_reply` 开始输出，以表示“不要向用户发送回复”。
- OpenClaw 会在投递层剥离/抑制它。
- 对精确静默标记的抑制不区分大小写，因此当整个负载仅为该静默标记时，`NO_REPLY` 和
- 助手以精确的静默 token `NO_REPLY` /
`no_reply` 开头输出，以表示“不要向用户发送回复”。
- OpenClaw 会在交付层将其剥离/抑制。
- 对精确静默 token 的抑制不区分大小写，因此当整个负载仅为该静默 token 时，`NO_REPLY` 和
`no_reply` 都算有效。
- 这仅适用于真正的后台/不投递轮次；它并不是处理普通用户可执行请求的捷径。
- 这仅用于真正的后台/不交付轮次；它不是普通可执行用户请求的快捷方式。
从 `2026.1.10` 开始，OpenClaw 还会在部分分块以 `NO_REPLY` 开头时抑制**草稿/输入中流式传输**，这样静默操作就不会在轮次中途泄露部分输出。
自 `2026.1.10` 起，OpenClaw 还会在
部分分块以 `NO_REPLY` 开头时抑制**草稿/输入中流式传输**，这样静默操作就不会在轮次中途泄露部分输出。
---
## 压缩前“内存刷新”（已实现）
## 压缩前“记忆刷新”（已实现）
目标：在自动压缩发生之前，运行一个静默的智能体轮次，将持久状态写入磁盘（例如智能体工作区中的 `memory/YYYY-MM-DD.md`），以便压缩不会擦除关键上下文。
目标：在自动压缩发生之前，运行一个静默的智能体轮次，将持久
状态写入磁盘（例如智能体工作区中的 `memory/YYYY-MM-DD.md`），这样压缩就不会
擦除关键上下文。
OpenClaw 使用的是**阈值前刷新**方法：
OpenClaw 使用**预阈值刷新**方案：
1. 监控会话上下文使用情况。
2. 当其越过一个“软阈值”（低于 Pi 的压缩阈值）时，运行一个静默的
“立即写入内存”指令给智能体。
3. 使用精确静默标记 `NO_REPLY` / `no_reply`，使用户
完全看不到任何内容。
1. 监控会话上下文使用量。
2. 当它越过“软阈值”（低于 Pi 的压缩阈值）时，向智能体运行一个静默的
“现在写入记忆”指令。
3. 使用精确的静默 token `NO_REPLY` / `no_reply`，这样用户就看不到
任何内容。
配置（`agents.defaults.compaction.memoryFlush`）：
@ -325,22 +332,24 @@ OpenClaw 使用的是**阈值前刷新**方法：
说明：
- 默认的 prompt/system prompt 包含 `NO_REPLY` 提示，以抑制投递。
- 每个压缩周期仅运行一次刷新（在 `sessions.json` 中跟踪）。
- 刷新仅对嵌入式 Pi 会话运行（CLI 后端会跳过）。
- 默认的 prompt/system prompt 包含一个 `NO_REPLY` 提示，用于抑制
交付。
- 每个压缩周期只运行一次刷新（在 `sessions.json` 中跟踪）。
- 刷新仅对嵌入式 Pi 会话运行。
- 当会话工作区为只读（`workspaceAccess: "ro"` 或 `"none"`）时，会跳过刷新。
- 有关工作区文件布局和写入模式，请参阅 [Memory](/zh-CN/concepts/memory)。
- 关于工作区文件布局和写入模式，请参见 [Memory](/zh-CN/concepts/memory)。
Pi 也会在扩展 API 中公开 `session_before_compact` hook，但 OpenClaw 的刷新逻辑目前位于 Gateway 网关侧。
Pi 在扩展 API 中也暴露了一个 `session_before_compact` hook，但 OpenClaw 的
刷新逻辑目前位于 Gateway 网关侧。
---
## 故障排除清单
## 故障排除检查清单
- 会话键错误？从 [/concepts/session](/zh-CN/concepts/session) 开始，并在 `/status` 中确认 `sessionKey`。
- 存储与转录不匹配？确认 Gateway 网关主机和 `openclaw status` 给出的存储路径。
- 会话键不对？从 [/concepts/session](/zh-CN/concepts/session) 开始，并在 `/status` 中确认 `sessionKey`。
- 存储与转录不匹配？确认 Gateway 网关主机和 `openclaw status` 显示的存储路径。
- 压缩过于频繁？检查：
- 模型上下文窗口（是否过小）
- 压缩设置（对于模型窗口来说，`reserveTokens` 过高可能导致更早压缩）
- `toolResult` 膨胀：启用/调优会话修剪
- 静默轮次泄露？确认回复以 `NO_REPLY` 开头（大小写不敏感的精确标记），并且你使用的构建版本包含流式抑制修复。
- 压缩设置（对于模型窗口而言，`reserveTokens` 过高会导致更早压缩）
- 工具结果膨胀：启用/调整会话裁剪
- 静默轮次泄露了输出？确认回复以 `NO_REPLY` 开头（大小写不敏感的精确 token），并且你使用的是包含流式传输抑制修复的构建版本。

459
docs/zh-CN/tools/acp-agents.md
View File

@ -1,102 +1,99 @@
---
read_when:
- 通过 ACP 运行编码 harness
- 在消息渠道上设置对话绑定的 ACP 会话
- 将消息渠道对话绑定到持久化 ACP 会话
- 故障排除 ACP 后端和插件接线
- 在消息渠道上设置绑定到会话的 ACP 会话
- 将消息渠道会话绑定到持久化 ACP 会话
- 排查 ACP 后端和插件接线问题
- 从聊天中操作 /acp 命令
summary: 通过 ACP 后端插件，为 Codex、Claude Code、Cursor、Gemini CLI、OpenClaw ACP 及其他 harness 智能体使用 ACP 运行时会话
summary: 通过 ACP 运行时会话使用 Codex、Claude Code、Cursor、Gemini CLI、OpenClaw ACP 及其他 harness 智能体
title: ACP 智能体
x-i18n:
generated_at: "2026-04-05T17:51:09Z"
generated_at: "2026-04-05T18:16:39Z"
model: gpt-5.4
provider: openai
source_hash: fb651ab39b05e537398623ee06cb952a5a07730fc75d3f7e0de20dd3128e72c6
source_hash: 302f3fe25b1ffe0576592b6e0ad9e8a5781fa5702b31d508d9ba8908f7df33bd
source_path: tools/acp-agents.md
workflow: 15
---
# ACP 智能体
[Agent Client Protocol (ACP)](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI，以及其他受支持的 ACPX harness）。
[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI，以及其他受支持的 ACPX harness）。
如果你用自然语言告诉 OpenClaw “在 Codex 中运行这个”或“在线程里启动 Claude Code”，OpenClaw 应该将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。每次 ACP 会话生成都会作为一个[后台任务](/zh-CN/automation/tasks)进行跟踪。
如果你用自然语言要求 OpenClaw “在 Codex 中运行这个”或“在一个线程中启动 Claude Code”，OpenClaw 应该把该请求路由到 ACP 运行时（而不是原生子智能体运行时）。每次 ACP 会话生成都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。
如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接
到现有的 OpenClaw 渠道对话，请使用 [`openclaw mcp serve`](/cli/mcp)
而不是 ACP。
如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的 OpenClaw 渠道会话，请使用 [`openclaw mcp serve`](/cli/mcp)，而不是 ACP。
## 我该看哪个页面？
## 我需要哪个页面？
这里有三个相近的功能区域，很容易混淆：
这里有三个相近的功能面，很容易混淆：
| 你想要…… | 使用这个 | 说明 |
| ---------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| 通过 OpenClaw _运行_ Codex、Claude Code、Gemini CLI 或其他外部 harness | 本页：ACP 智能体 | 聊天绑定会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 |
| 将一个 OpenClaw Gateway 网关会话 _作为_ ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/cli/acp) | 桥接模式。IDE / 客户端通过 stdio / WebSocket 使用 ACP 与 OpenClaw 通信 |
| 将本地 AI CLI 复用为纯文本后备模型 | [CLI Backends](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有 harness 运行时 |
| 你想要... | 使用这个 | 说明 |
| ---------------------------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| 通过 OpenClaw 运行 Codex、Claude Code、Gemini CLI 或其他外部 harness | 本页：ACP 智能体 | 聊天绑定会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 |
| 将 OpenClaw Gateway 网关会话作为 ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/cli/acp) | 桥接模式。IDE/客户端 通过 stdio/WebSocket 与 OpenClaw 进行 ACP 通信 |
## 开箱即用吗？
## 这可以开箱即用吗？
通常可以。
- 全新安装现在默认启用内置的 `acpx` 运行时插件。
- 内置 `acpx` 插件会优先使用其插件本地固定版本的 `acpx` 二进制文件。
- 启动时，OpenClaw 会探测该二进制文件，并在需要时自行修复。
- 启动时，OpenClaw 会探测该二进制文件，并在需要时自我修复。
- 如果你想快速检查就绪状态，请先从 `/acp doctor` 开始。
首次使用时仍可能发生的情况：
首次使用时仍然可能发生的情况：
- 某个目标 harness 适配器可能会在你首次使用该 harness 时按需通过 `npx` 获取。
- 该 harness 对应的厂商认证仍然必须已经存在于主机上。
- 如果主机没有 npm / 网络访问能力，首次运行的适配器获取可能失败，直到缓存被预热或适配器通过其他方式安装。
- 第一次使用某个 harness 时，目标 harness 适配器可能会按需通过 `npx` 获取。
- 该 harness 的供应商认证仍然必须已存在于主机上。
- 如果主机没有 npm/网络访问权限，首次运行的适配器获取可能会失败，直到缓存被预热或适配器通过其他方式安装。
示例：
- `/acp spawn codex`：OpenClaw 应该已经可以引导 `acpx`，但 Codex ACP 适配器可能仍需要首次运行获取。
- `/acp spawn claude`：Claude ACP 适配器同理，另外还需要该主机上的 Claude 侧认证。
- `/acp spawn codex`：OpenClaw 应已准备好引导 `acpx`，但 Codex ACP 适配器仍可能需要首次运行获取。
- `/acp spawn claude`：Claude ACP 适配器也是同样情况，另外该主机上还需要 Claude 侧认证。
## 快速操作流程
## 面向操作员的快速流程
如果你想要一个实用的 `/acp` 操作手册，请使用这个流程：
当你想要一份实用的 `/acp` 操作手册时，请使用这个流程：
1. 生成一个会话：
- `/acp spawn codex --bind here`
- `/acp spawn codex --mode persistent --thread auto`
2. 在已绑定的对话或线程中工作（或显式指定该会话键）。
2. 在绑定的会话或线程中工作（或显式指定该会话键）。
3. 检查运行时状态：
- `/acp status`
4. 根据需要调整运行时选项：
4. 按需调整运行时选项：
- `/acp model <provider/model>`
- `/acp permissions <profile>`
- `/acp timeout <seconds>`
5. 在不替换上下文的情况下推动一个活动会话：
5. 在不替换上下文的情况下推动一个活跃会话：
- `/acp steer tighten logging and continue`
6. 停止工作：
- `/acp cancel`（停止当前回合），或
- `/acp cancel`（停止当前轮次），或
- `/acp close`（关闭会话 + 移除绑定）
## 面向人工操作的快速开始
## 面向人工用户的快速开始
自然请求示例：
自然语言请求示例：
- “把这个 Discord 渠道绑定到 Codex。”
- “在这里的线程里启动一个持久 Codex 会话并保持聚焦。”
- “把这个作为一次性 Claude Code ACP 会话运行，并总结结果。”
- “把这个 iMessage 聊天绑定到 Codex，并将后续消息保持在同一个工作区。”
- “为这个任务使用 Gemini CLI 在线程中运行，然后将后续消息保留在同一个线程中。”
- “将这个 Discord 渠道绑定到 Codex。”
- “在这里的一个线程中启动一个持久化 Codex 会话，并保持聚焦。”
- “将这个作为一次性 Claude Code ACP 会话运行，并总结结果。”
- “将这个 iMessage 聊天绑定到 Codex，并让后续消息保持在同一个工作区。”
- “在一个线程中用 Gemini CLI 处理这个任务，然后让后续消息继续留在同一个线程中。”
OpenClaw 应该执行的操作：
OpenClaw 应执行的操作：
1. 选择 `runtime: "acp"`。
2. 解析请求的 harness 目标（`agentId`，例如 `codex`）。
3. 如果请求了当前对话绑定，并且当前渠道支持，则将 ACP 会话绑定到该对话。
4. 否则，如果请求了线程绑定，并且当前渠道支持，则将 ACP 会话绑定到该线程。
5. 将后续已绑定消息路由到同一个 ACP 会话，直到取消聚焦 / 关闭 / 过期。
3. 如果请求绑定当前会话，并且当前活跃渠道支持此功能，则将 ACP 会话绑定到该会话。
4. 否则，如果请求线程绑定，并且当前渠道支持此功能，则将 ACP 会话绑定到该线程。
5. 将后续绑定消息继续路由到同一个 ACP 会话，直到失焦/关闭/过期。
## ACP 与子智能体
当你需要外部 harness 运行时时，请使用 ACP。当你需要 OpenClaw 原生的委派运行时，请使用子智能体。
如果你想要外部 harness 运行时，请使用 ACP。如果你想要 OpenClaw 原生委托运行，请使用子智能体。
| 区域 | ACP 会话 | 子智能体运行 |
| ------------- | ------------------------------------- | ---------------------------------- |
@ -105,121 +102,118 @@ OpenClaw 应该执行的操作：
| 主要命令 | `/acp ...` | `/subagents ...` |
| 生成工具 | `sessions_spawn` 搭配 `runtime:"acp"` | `sessions_spawn`（默认运行时） |
另请参阅 [Sub-agents](/zh-CN/tools/subagents)。
另请参见 [Sub-agents](/zh-CN/tools/subagents)。
## ACP 如何运行 Claude Code
通过 ACP 运行 Claude Code 时，堆栈如下：
对于通过 ACP 运行的 Claude Code，堆栈如下：
1. OpenClaw ACP 会话控制平面
2. 内置 `acpx` 运行时插件
3. Claude ACP 适配器
4. Claude 侧运行时 / 会话机制
4. Claude 侧运行时/会话机制
重要区别：
- ACP Claude 是一个 harness 会话，具有 ACP 控制、会话恢复、后台任务跟踪，以及可选的对话 / 线程绑定。
- CLI 后端是独立的纯文本本地后备运行时。参见 [CLI Backends](/zh-CN/gateway/cli-backends)。
- ACP Claude 是一个 harness 会话，具备 ACP 控制、会话恢复、后台任务跟踪，以及可选的会话/线程绑定。
对操作员来说，实用规则是：
对于操作员来说，实用规则是：
- 想要 `/acp spawn`、可绑定会话、运行时控制或持久化 harness 工作：请使用 ACP
- 如果你想要 `/acp spawn`、可绑定会话、运行时控制或持久化 harness 工作：使用 ACP
- 如果你想通过原始 CLI 获得简单的本地文本后备：使用 CLI 后端
## 绑定会话
## 已绑定会话
### 当前会话绑定
### 当前对话绑定
当你希望当前对话在不创建子线程的情况下变成持久的 ACP 工作区时，请使用 `/acp spawn <harness> --bind here`。
当你希望当前会话成为一个持久的 ACP 工作区，而不创建子线程时，请使用 `/acp spawn <harness> --bind here`。
行为：
- OpenClaw 继续负责渠道传输、认证、安全和投递。
- 当前对话会固定到新生成的 ACP 会话键。
- 该对话中的后续消息会路由到同一个 ACP 会话。
- `/new` 和 `/reset` 会原地重置同一个已绑定 ACP 会话。
- `/acp close` 会关闭会话并移除当前对话绑定。
- OpenClaw 继续拥有渠道传输、认证、安全和消息投递。
- 当前会话会被固定到已生成的 ACP 会话键。
- 该会话中的后续消息会被路由到同一个 ACP 会话。
- `/new` 和 `/reset` 会在原地重置同一个已绑定的 ACP 会话。
- `/acp close` 会关闭会话并移除当前会话绑定。
这在实践中的含义：
- `--bind here` 会保留同一个聊天界面。在 Discord 上，当前渠道仍然是当前渠道。
- 如果你是在生成新的工作，`--bind here` 仍然可以创建一个新的 ACP 会话。绑定会将该会话附加到当前对话。
- `--bind here` 会保持同一个聊天界面。在 Discord 上，当前渠道仍然是当前渠道。
- `--bind here` 在你生成全新工作时仍然可以创建一个新的 ACP 会话。该绑定会把该会话附加到当前会话。
- `--bind here` 本身不会创建子 Discord 线程或 Telegram 话题。
- ACP 运行时仍然可以拥有自己的工作目录（`cwd`）或由后端管理的磁盘工作区。该运行时工作区与聊天界面是分离的，并不意味着一定会创建新的消息线程。
- 如果你生成到另一个 ACP 智能体，且未传递 `--cwd`，OpenClaw 默认会继承**目标智能体的**工作区，而不是请求者的工作区。
- 如果该继承的工作区路径缺失（`ENOENT` / `ENOTDIR`），OpenClaw 会回退到后端默认 cwd，而不是悄悄复用错误的目录树。
- 如果该继承的工作区存在但无法访问（例如 `EACCES`），生成会返回真实的访问错误，而不是丢弃 `cwd`。
- ACP 运行时仍然可以拥有自己的工作目录（`cwd`）或后端管理的磁盘工作区。该运行时工作区与聊天界面是分离的，并不意味着会新建消息线程。
- 如果你生成到另一个 ACP 智能体且没有传入 `--cwd`，OpenClaw 默认会继承**目标智能体的**工作区，而不是请求方的工作区。
- 如果继承的工作区路径缺失（`ENOENT`/`ENOTDIR`），OpenClaw 会回退到后端默认 cwd，而不是默默复用错误的目录树。
- 如果继承的工作区存在但无法访问（例如 `EACCES`），生成操作会返回真实的访问错误，而不是丢弃 `cwd`。
心智模型：
- 聊天界面：人们继续交流的地方（`Discord channel`、`Telegram topic`、`iMessage chat`）
- ACP 会话：OpenClaw 路由到的持久 Codex / Claude / Gemini 运行时状态
- 子线程 / 话题：仅由 `--thread ...` 创建的可选额外消息界面
- 运行时工作区：harness 运行的文件系统位置（`cwd`、仓库检出、后端工作区）
- 聊天界面：人们继续交谈的地方（`Discord channel`、`Telegram topic`、`iMessage chat`）
- ACP 会话：OpenClaw 路由到的持久化 Codex/Claude/Gemini 运行时状态
- 子线程/话题：仅在 `--thread ...` 时创建的可选额外消息界面
- 运行时工作区：harness 运行所在的文件系统位置（`cwd`、仓库检出、后端工作区）
示例：
- `/acp spawn codex --bind here`：保留当前聊天，生成或附加一个 Codex ACP 会话，并将此后的消息路由到它
- `/acp spawn codex --thread auto`：OpenClaw 可能会创建一个子线程 / 话题，并在其中绑定 ACP 会话
- `/acp spawn codex --bind here`：保留当前聊天，生成或附加一个 Codex ACP 会话，并将此处后续消息路由到它
- `/acp spawn codex --thread auto`：OpenClaw 可能创建一个子线程/话题，并将 ACP 会话绑定到那里
- `/acp spawn codex --bind here --cwd /workspace/repo`：与上面相同的聊天绑定，但 Codex 在 `/workspace/repo` 中运行
当前对话绑定支持：
当前会话绑定支持：
- 声明支持当前对话绑定的聊天 / 消息渠道可以通过共享的对话绑定路径使用 `--bind here`。
- 具有自定义线程 / 话题语义的渠道仍可在同一共享接口后提供按渠道的规范化。
- `--bind here` 始终表示“原地绑定当前对话”。
- 通用的当前对话绑定使用共享的 OpenClaw 绑定存储，并可在正常 Gateway 网关重启后保留。
- 声明支持当前会话绑定的聊天/消息渠道可以通过共享会话绑定路径使用 `--bind here`。
- 具有自定义线程/话题语义的渠道仍可在相同共享接口之后提供渠道特定的规范化。
- `--bind here` 始终表示“原地绑定当前会话”。
- 通用当前会话绑定使用共享的 OpenClaw 绑定存储，并可在正常 Gateway 网关重启后保留。
说明：
- 在 `/acp spawn` 上，`--bind here` 和 `--thread ...` 互斥。
- 在 `/acp spawn` 中，`--bind here` 与 `--thread ...` 互斥。
- 在 Discord 上，`--bind here` 会原地绑定当前渠道或线程。只有当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions`。
- 如果活动渠道未暴露当前对话 ACP 绑定，OpenClaw 会返回明确的不支持消息。
- `resume` 和“新会话”问题是 ACP 会话问题，而不是渠道问题。你可以在不改变当前聊天界面的情况下复用或替换运行时状态。
- 如果活跃渠道不暴露当前会话 ACP 绑定，OpenClaw 会返回清晰的不支持消息。
- `resume` 和“新建会话”问题是 ACP 会话问题，不是渠道问题。你可以复用或替换运行时状态，而无需更改当前聊天界面。
### 线程绑定会话
当某个渠道适配器启用了线程绑定时，ACP 会话可以绑定到线程：
- OpenClaw 将一个线程绑定到目标 ACP 会话。
- 该线程中的后续消息会路由到已绑定的 ACP 会话。
- ACP 输出会回投到同一个线程。
- 取消聚焦 / 关闭 / 归档 / 空闲超时或最大时长到期都会移除该绑定。
- 该线程中的后续消息会被路由到已绑定的 ACP 会话。
- ACP 输出会回送到同一个线程。
- 失焦/关闭/归档/空闲超时或最长存活时间到期会移除绑定。
线程绑定支持取决于适配器。如果当前渠道适配器不支持线程绑定，OpenClaw 会返回明确的不支持 / 不可用消息。
线程绑定支持取决于适配器。如果当前活跃渠道适配器不支持线程绑定，OpenClaw 会返回清晰的不支持/不可用消息。
线程绑定 ACP 所需的功能标志：
线程绑定 ACP 所需功能开关：
- `acp.enabled=true`
- `acp.dispatch.enabled` 默认开启（设置为 `false` 以暂停 ACP 分发）
- 已启用渠道适配器的 ACP 线程生成标志（适配器特定）
- `acp.dispatch.enabled` 默认开启（设为 `false` 可暂停 ACP 分发）
- 渠道适配器 ACP 线程生成开关已启用（特定于适配器）
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true`
### 支持线程的渠道
- 任何暴露会话 / 线程绑定能力的渠道适配器。
- 任何暴露会话/线程绑定能力的渠道适配器。
- 当前内置支持：
- Discord 线程 / 渠道
- Telegram 话题（群组 / 超级群组中的论坛话题和私信话题）
- 插件渠道也可通过同一绑定接口添加支持。
- Discord 线程/渠道
- Telegram 话题（群组/超级群组中的论坛话题和私信话题）
- 插件渠道也可以通过相同绑定接口增加支持。
## 按渠道的特定设置
## 渠道特定设置
对于非临时性工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。
对于非临时工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。
### 绑定模型
- `bindings[].type="acp"` 用于标记一个持久化 ACP 对话绑定。
- `bindings[].match` 用于标识目标对话：
- `bindings[].type="acp"` 表示持久化 ACP 会话绑定。
- `bindings[].match` 标识目标会话：
- Discord 渠道或线程：`match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- Telegram 论坛话题：`match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- BlueBubbles 私信 / 群聊：`match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
- BlueBubbles 私信/群聊：`match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
对于稳定的群组绑定，优先使用 `chat_id:*` 或 `chat_identifier:*`。
- iMessage 私信 / 群聊：`match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
- iMessage 私信/群聊：`match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
对于稳定的群组绑定，优先使用 `chat_id:*`。
- `bindings[].agentId` 是所属的 OpenClaw 智能体 ID。
- 可选 ACP 覆盖项位于 `bindings[].acp` 下：
- 可选 ACP 覆盖位于 `bindings[].acp` 下：
- `mode`（`persistent` 或 `oneshot`）
- `label`
- `cwd`
@ -227,7 +221,7 @@ OpenClaw 应该执行的操作：
### 每个智能体的运行时默认值
使用 `agents.list[].runtime` 为每个智能体定义一次 ACP 默认值：
使用 `agents.list[].runtime` 为每个智能体一次性定义 ACP 默认值：
- `agents.list[].runtime.type="acp"`
- `agents.list[].runtime.acp.agent`（harness ID，例如 `codex` 或 `claude`）
@ -324,17 +318,17 @@ ACP 绑定会话的覆盖优先级：
行为：
- OpenClaw 会在使用前确保配置的 ACP 会话存在。
- 该渠道或话题中的消息会路由到配置的 ACP 会话。
- 在已绑定对话中，`/new` 和 `/reset` 会原地重置同一个 ACP 会话键。
- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍然适用。
- 对于未显式指定 `cwd` 的跨智能体 ACP 生成，OpenClaw 会从智能体配置中继承目标智能体工作区。
- 缺失的继承工作区路径会回退到后端默认 cwd；而非缺失导致的访问失败会作为生成错误直接返回。
- 该渠道或话题中的消息会被路由到已配置的 ACP 会话。
- 在已绑定会话中，`/new` 和 `/reset` 会原地重置同一个 ACP 会话键。
- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍会生效。
- 对于没有显式 `cwd` 的跨智能体 ACP 生成，OpenClaw 会从智能体配置继承目标智能体工作区。
- 缺失的继承工作区路径会回退到后端默认 cwd；非缺失的访问失败会作为生成错误暴露出来。
## 启动 ACP 会话（接口）
### 从 `sessions_spawn` 启动
使用 `runtime: "acp"` 从智能体回合或工具调用中启动 ACP 会话。
使用 `runtime: "acp"` 可从智能体轮次或工具调用中启动 ACP 会话。
```json
{
@ -348,29 +342,29 @@ ACP 绑定会话的覆盖优先级：
说明：
- `runtime` 默认是 `subagent`，因此对于 ACP 会话请显式设置 `runtime: "acp"`。
- 如果省略 `agentId`，在已配置时 OpenClaw 会使用 `acp.defaultAgent`。
- `mode: "session"` 需要 `thread: true` 才能保持一个持久化的绑定对话。
- `runtime` 默认为 `subagent`，因此对于 ACP 会话需要显式设置 `runtime: "acp"`。
- 如果省略 `agentId`，OpenClaw 会在配置了 `acp.defaultAgent` 时使用它。
- `mode: "session"` 需要 `thread: true` 才能保持一个持久化绑定会话。
接口详情：
- `task`（必需）：发送给 ACP 会话的初始提示。
- `runtime`（ACP 必需）：必须为 `"acp"`。
- `agentId`（可选）：ACP 目标 harness ID。若已设置，则回退到 `acp.defaultAgent`。
- `task`（必填）：发送到 ACP 会话的初始提示。
- `runtime`（ACP 必填）：必须为 `"acp"`。
- `agentId`（可选）：ACP 目标 harness ID。如果设置了 `acp.defaultAgent`，则回退到它。
- `thread`（可选，默认 `false`）：在支持时请求线程绑定流程。
- `mode`（可选）：`run`（一次性）或 `session`（持久化）。
- 默认值为 `run`
- 如果 `thread: true` 且省略 `mode`，OpenClaw 可根据运行时路径默认采用持久化行为
- 如果 `thread: true` 且省略 mode，OpenClaw 可能按运行时路径默认使用持久化行为
- `mode: "session"` 需要 `thread: true`
- `cwd`（可选）：请求的运行时工作目录（由后端 / 运行时策略校验）。如果省略，ACP 生成会在已配置时继承目标智能体工作区；缺失的继承路径会回退到后端默认值，而真实访问错误会直接返回。
- `label`（可选）：面向操作员的标签，用于会话 / 横幅文本。
- `resumeSessionId`（可选）：恢复现有 ACP 会话，而不是新建会话。智能体会通过 `session/load` 重放其对话历史。需要 `runtime: "acp"`。
- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式回传给请求方会话。
- 在可用时，接受的响应会包含 `streamLogPath`，指向一个按会话划分的 JSONL 日志（`<sessionId>.acp-stream.jsonl`），你可以对其执行 tail 以查看完整转发历史。
- `cwd`（可选）：请求的运行时工作目录（由后端/运行时策略验证）。如果省略，ACP 生成会在配置时继承目标智能体工作区；缺失的继承路径会回退到后端默认值，而真实访问错误会被返回。
- `label`（可选）：用于会话/横幅文本中的面向操作员标签。
- `resumeSessionId`（可选）：恢复一个现有 ACP 会话，而不是新建会话。该智能体会通过 `session/load` 重放其会话历史。需要 `runtime: "acp"`。
- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式返回给请求方会话。
- 可用时，接受的响应可包含 `streamLogPath`，指向一个作用域为该会话的 JSONL 日志（`<sessionId>.acp-stream.jsonl`），你可以对其执行 tail 以查看完整转发历史。
### 恢复现有会话
使用 `resumeSessionId` 来继续先前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其对话历史，因此它可以带着完整的前文继续工作。
使用 `resumeSessionId` 继续先前的 ACP 会话，而不是重新开始。该智能体会通过 `session/load` 重放其会话历史，因此它会带着之前的完整上下文继续。
```json
{
@ -383,41 +377,38 @@ ACP 绑定会话的覆盖优先级：
常见用例：
- 将一个 Codex 会话从你的笔记本交接到手机——告诉你的智能体从你上次停下的地方继续
- 继续你在 CLI 中以交互方式启动的编码会话，现在通过智能体以无头方式运行
- 接续因 Gateway 网关重启或空闲超时而中断的工作
- 将一个 Codex 会话从你的笔记本电脑切换到手机 —— 告诉你的智能体从你离开的地方继续
- 继续一个你先前在 CLI 中以交互方式启动、现在通过智能体以无头方式继续的编码会话
- 接着处理一个因 Gateway 网关重启或空闲超时而中断的工作
说明：
- `resumeSessionId` 需要 `runtime: "acp"`——如果与子智能体运行时一起使用，会返回错误。
- `resumeSessionId` 会恢复上游 ACP 对话历史；`thread` 和 `mode` 仍会正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然需要 `thread: true`。
- `resumeSessionId` 需要 `runtime: "acp"` —— 如果与子智能体运行时一起使用，会返回错误。
- `resumeSessionId` 会恢复上游 ACP 会话历史；`thread` 和 `mode` 仍会正常应用到你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然需要 `thread: true`。
- 目标智能体必须支持 `session/load`（Codex 和 Claude Code 支持）。
- 如果找不到会话 ID，生成会以明确错误失败——不会静默回退到新会话。
- 如果找不到该会话 ID，生成会以清晰错误失败 —— 不会静默回退为新会话。
### 操作员冒烟测试
### 面向操作员的 smoke 测试
在 Gateway 网关部署之后，如果你希望快速进行一次在线检查，确认 ACP 生成
确实端到端可用，而不仅仅是通过了单元测试，请使用这个方法。
当你在 Gateway 网关部署后想进行一次快速 live 检查，确认 ACP 生成确实在端到端工作，而不只是通过了单元测试时，请使用这个流程。
推荐门槛：
1. 验证目标主机上已部署的 Gateway 网关版本 / commit。
2. 确认已部署的源代码在
`src/gateway/sessions-patch.ts` 中包含 ACP 血缘接受逻辑（`subagent:* or acp:* sessions`）。
3. 打开一个临时 ACPX 桥接会话，连接到一个在线智能体（例如
`jpclawhq` 上的 `razor(main)`）。
4. 要求该智能体调用 `sessions_spawn`，参数如下：
1. 在目标主机上验证已部署的 Gateway 网关版本/提交。
2. 确认已部署源码在 `src/gateway/sessions-patch.ts` 中包含 ACP 血统接受逻辑（`subagent:* or acp:* sessions`）。
3. 打开一个到 live 智能体的临时 ACPX 桥接会话（例如 `jpclawhq` 上的 `razor(main)`）。
4. 要求该智能体调用 `sessions_spawn`，参数为：
- `runtime: "acp"`
- `agentId: "codex"`
- `mode: "run"`
- task：`Reply with exactly LIVE-ACP-SPAWN-OK`
5. 验证智能体报告：
5. 验证该智能体报告：
- `accepted=yes`
- 一个真实的 `childSessionKey`
- 没有校验器错误
6. 清理临时 ACPX 桥接会话。
6. 清理该临时 ACPX 桥接会话。
发给在线智能体的提示示例：
发送给 live 智能体的提示示例：
```text
Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
@ -427,29 +418,26 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
说明：
- 除非你有意测试
线程绑定的持久化 ACP 会话，否则请将此冒烟测试保持在 `mode: "run"`。
- 基础门槛无需要求 `streamTo: "parent"`。该路径依赖于
请求方 / 会话能力，是单独的集成检查。
- 将线程绑定的 `mode: "session"` 测试视为第二轮、更丰富的集成
检查，应从真实的 Discord 线程或 Telegram 话题中进行。
- 除非你有意测试线程绑定的持久化 ACP 会话，否则请将此 smoke 测试保持在 `mode: "run"`。
- 基础门槛不要要求 `streamTo: "parent"`。该路径依赖请求方/会话能力，是单独的集成检查。
- 将线程绑定的 `mode: "session"` 测试视为来自真实 Discord 线程或 Telegram 话题的第二阶段、更丰富的集成验证。
## 沙箱兼容性
ACP 会话当前运行在主机运行时上，而不是在 OpenClaw 沙箱中。
ACP 会话当前运行在主机运行时上，而不是 OpenClaw 沙箱内。
当前限制：
- 如果请求方会话已启用沙箱隔离，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 生成都会被阻止。
- 如果请求方会话处于沙箱隔离状态，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 生成都会被阻止。
- 错误：`Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.`
- 对于 `runtime: "acp"`，`sessions_spawn` 不支持 `sandbox: "require"`。
- `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。
- 错误：`sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`
当你需要由沙箱强制执行的运行时，请使用 `runtime: "subagent"`。
当你需要由沙箱强制执行时，请使用 `runtime: "subagent"`。
### 从 `/acp` 命令启动
在需要时，使用 `/acp spawn` 进行明确的聊天内操作控制。
当你需要从聊天中进行显式操作员控制时，请使用 `/acp spawn`。
```text
/acp spawn codex --mode persistent --thread auto
@ -466,24 +454,24 @@ ACP 会话当前运行在主机运行时上，而不是在 OpenClaw 沙箱中。
- `--cwd <absolute-path>`
- `--label <name>`
参见 [Slash Commands](/zh-CN/tools/slash-commands)。
请参见 [Slash Commands](/zh-CN/tools/slash-commands)。
## 会话目标解析
大多数 `/acp` 操作都接受一个可选会话目标（`session-key`、`session-id` 或 `session-label`）。
大多数 `/acp` 操作接受一个可选的会话目标（`session-key`、`session-id` 或 `session-label`）。
解析顺序：
1. 显式目标参数（或 `/acp steer` 的 `--session`）
- 先尝试键
- 再尝试 UUID 形状的会话 ID
- 然后尝试标签
2. 当前线程绑定（如果此对话 / 线程已绑定到 ACP 会话）
- 然后尝试 UUID 形状的会话 ID
- 再尝试标签
2. 当前线程绑定（如果此会话/线程已绑定到某个 ACP 会话）
3. 当前请求方会话回退
当前对话绑定和线程绑定都会参与步骤 2。
当前会话绑定和线程绑定都会参与第 2 步。
如果无法解析任何目标，OpenClaw 会返回明确错误（`Unable to resolve session target: ...`）。
如果无法解析任何目标，OpenClaw 会返回清晰错误（`Unable to resolve session target: ...`）。
## 生成绑定模式
@ -491,15 +479,15 @@ ACP 会话当前运行在主机运行时上，而不是在 OpenClaw 沙箱中。
| 模式 | 行为 |
| ------ | ---------------------------------------------------------------------- |
| `here` | 原地绑定当前活动对话；如果当前没有活动对话则失败。 |
| `off` | 不创建当前对话绑定。 |
| `here` | 原地绑定当前活跃会话；如果没有活跃会话则失败。 |
| `off` | 不创建当前会话绑定。 |
说明：
- `--bind here` 是“让这个渠道或聊天由 Codex 驱动”的最简单操作路径。
- `--bind here` 是“让这个渠道或聊天由 Codex 提供支持”的最简单操作员路径。
- `--bind here` 不会创建子线程。
- `--bind here` 仅在暴露当前对话绑定支持的渠道上可用。
- `--bind` 和 `--thread` 不能在同一次 `/acp spawn` 调用中组合使用。
- `--bind here` 仅适用于暴露当前会话绑定支持的渠道。
- `--bind` 与 `--thread` 不能在同一个 `/acp spawn` 调用中组合使用。
## 生成线程模式
@ -507,17 +495,17 @@ ACP 会话当前运行在主机运行时上，而不是在 OpenClaw 沙箱中。
| 模式 | 行为 |
| ------ | --------------------------------------------------------------------------------------------------- |
| `auto` | 在线程中：绑定该线程。在线程外：在支持时创建 / 绑定子线程。 |
| `here` | 要求当前必须处于活动线程中；否则失败。 |
| `off` | 不进行绑定。会话以未绑定状态启动。 |
| `auto` | 在活跃线程中：绑定该线程。在线程外：在支持时创建/绑定一个子线程。 |
| `here` | 要求当前处于活跃线程中；否则失败。 |
| `off` | 不绑定。会话以未绑定方式启动。 |
说明：
- 在非线程绑定界面上，默认行为实际上等同于 `off`。
- 在不支持线程绑定的界面上，默认行为实际上等同于 `off`。
- 线程绑定生成需要渠道策略支持：
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true`
- 当你希望固定当前对话而不创建子线程时，请使用 `--bind here`。
- 当你想固定当前会话而不创建子线程时，请使用 `--bind here`。
## ACP 控制
@ -539,45 +527,45 @@ ACP 会话当前运行在主机运行时上，而不是在 OpenClaw 沙箱中。
- `/acp doctor`
- `/acp install`
`/acp status` 会显示有效的运行时选项，并在可用时显示运行时级别和后端级别的会话标识符。
`/acp status` 会显示生效的运行时选项，并在可用时同时显示运行时级和后端级会话标识符。
某些控制取决于后端能力。如果某个后端不支持某项控制，OpenClaw 会返回明确的不支持控制错误。
某些控制依赖后端能力。如果后端不支持某个控制，OpenClaw 会返回清晰的“不支持该控制”错误。
## ACP 命令手册
| 命令 | 作用 | 示例 |
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
| `/acp spawn` | 创建 ACP 会话；可选当前绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | 取消目标会话的进行中回合。 | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | 向运行中的会话发送引导指令。 | `/acp steer --session support inbox prioritize failing tests` |
| `/acp cancel` | 取消目标会话的进行中轮次。 | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | 向正在运行的会话发送引导指令。 | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close` | 关闭会话并解除线程目标绑定。 | `/acp close` |
| `/acp status` | 显示后端、模式、状态、运行时选项、能力。 | `/acp status` |
| `/acp set-mode` | 设置目标会话的运行时模式。 | `/acp set-mode plan` |
| `/acp set` | 通用运行时配置选项写入。 | `/acp set model openai/gpt-5.4` |
| `/acp cwd` | 设置运行时工作目录覆盖。 | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | 设置审批策略配置文件。 | `/acp permissions strict` |
| `/acp set-mode` | 为目标会话设置运行时模式。 | `/acp set-mode plan` |
| `/acp set` | 写入通用运行时配置选项。 | `/acp set model openai/gpt-5.4` |
| `/acp cwd` | 设置运行时工作目录覆盖值。 | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | 设置审批策略配置档。 | `/acp permissions strict` |
| `/acp timeout` | 设置运行时超时（秒）。 | `/acp timeout 120` |
| `/acp model` | 设置运行时模型覆盖。 | `/acp model anthropic/claude-opus-4-6` |
| `/acp model` | 设置运行时模型覆盖值。 | `/acp model anthropic/claude-opus-4-6` |
| `/acp reset-options` | 移除会话运行时选项覆盖。 | `/acp reset-options` |
| `/acp sessions` | 从存储中列出最近的 ACP 会话。 | `/acp sessions` |
| `/acp doctor` | 后端健康状态、能力、可操作修复。 | `/acp doctor` |
| `/acp doctor` | 后端健康状态、能力、可执行修复。 | `/acp doctor` |
| `/acp install` | 打印确定性的安装和启用步骤。 | `/acp install` |
`/acp sessions` 会读取当前已绑定或请求方会话的存储。接受 `session-key`、`session-id` 或 `session-label` 标记的命令，会通过 Gateway 网关会话发现来解析目标，包括自定义的按智能体 `session.store` 根目录。
`/acp sessions` 会读取当前已绑定会话或请求方会话的存储。接受 `session-key`、`session-id` 或 `session-label` 标记的命令，会通过 Gateway 网关会话发现来解析目标，包括每个智能体自定义的 `session.store` 根目录。
## 运行时选项映射
`/acp` 提供便捷命令和通用设置器。
`/acp` 既有便捷命令，也有通用设置器。
等效操作：
等价操作：
- `/acp model <id>` 映射到运行时配置键 `model`。
- `/acp permissions <profile>` 映射到运行时配置键 `approval_policy`。
- `/acp timeout <seconds>` 映射到运行时配置键 `timeout`。
- `/acp cwd <path>` 会直接更新运行时 cwd 覆盖。
- `/acp cwd <path>` 会直接更新运行时 cwd 覆盖值。
- `/acp set <key> <value>` 是通用路径。
- 特殊情况：`key=cwd` 使用 cwd 覆盖路径。
- `/acp reset-options` 会清除目标会话的所有运行时覆盖项。
- `/acp reset-options` 会清除目标会话的所有运行时覆盖值。
## acpx harness 支持（当前）
@ -598,10 +586,10 @@ ACP 会话当前运行在主机运行时上，而不是在 OpenClaw 沙箱中。
- `pi`
- `qwen`
当 OpenClaw 使用 acpx 后端时，除非你的 acpx 配置定义了自定义智能体别名，否则 `agentId` 应优先使用这些值。
如果你的本地 Cursor 安装仍将 ACP 暴露为 `agent acp`，请在你的 acpx 配置中覆盖 `cursor` 智能体命令，而不是更改内置默认值。
当 OpenClaw 使用 acpx 后端时，除非你的 acpx 配置定义了自定义智能体别名，否则应优先将这些值用于 `agentId`。
如果你本地安装的 Cursor 仍将 ACP 暴露为 `agent acp`，请在你的 acpx 配置中覆盖 `cursor` 智能体命令，而不是更改内置默认值。
直接使用 acpx CLI 也可以通过 `--agent <command>` 指向任意适配器，但这个原始逃生口是 acpx CLI 的功能（不是常规的 OpenClaw `agentId` 路径）。
直接使用 acpx CLI 也可以通过 `--agent <command>` 定位任意适配器，但这个原始逃生口是 acpx CLI 功能（不是 OpenClaw 正常的 `agentId` 路径）。
## 必需配置
@ -611,7 +599,7 @@ ACP 会话当前运行在主机运行时上，而不是在 OpenClaw 沙箱中。
{
acp: {
enabled: true,
// 可选。默认值为 true；设置为 false 可在保留 /acp 控制的同时暂停 ACP 分发。
// 可选。默认是 true；设为 false 可暂停 ACP 分发，同时保留 /acp 控制。
dispatch: { enabled: true },
backend: "acpx",
defaultAgent: "codex",
@ -665,34 +653,32 @@ ACP 会话当前运行在主机运行时上，而不是在 OpenClaw 沙箱中。
}
```
如果线程绑定 ACP 生成不工作，请先验证适配器功能标志：
如果线程绑定的 ACP 生成无法工作，请先验证适配器功能开关：
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
当前对话绑定不需要创建子线程。它们需要一个活动对话上下文和一个暴露 ACP 对话绑定的渠道适配器。
当前会话绑定不需要创建子线程。它们需要一个活跃会话上下文，以及一个暴露 ACP 会话绑定的渠道适配器。
参见 [Configuration Reference](/zh-CN/gateway/configuration-reference)。
请参见 [Configuration Reference](/zh-CN/gateway/configuration-reference)。
## acpx 后端的插件设置
全新安装默认启用内置的 `acpx` 运行时插件，因此 ACP
通常无需手动安装插件即可工作。
全新安装默认启用内置 `acpx` 运行时插件，因此 ACP 通常无需手动安装插件即可工作。
先从这里开始：
请先执行：
```text
/acp doctor
```
如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或者希望
切换到本地开发检出，请使用显式插件路径：
如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或者想切换到本地开发检出，请使用显式插件路径：
```bash
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true
```
开发期间从本地工作区安装：
开发期间的本地工作区安装：
```bash
openclaw plugins install ./path/to/local/acpx-plugin
@ -708,14 +694,14 @@ openclaw plugins install ./path/to/local/acpx-plugin
默认情况下，内置 acpx 后端插件（`acpx`）使用插件本地固定版本的二进制文件：
1. 命令默认使用 ACPX 插件包内插件本地的 `node_modules/.bin/acpx`。
2. 预期版本默认使用扩展固定版本。
3. 启动时会立即将 ACP 后端注册为未就绪状态。
4. 一个后台确保任务会验证 `acpx --version`。
1. 命令默认指向 ACPX 插件包中的插件本地 `node_modules/.bin/acpx`。
2. 预期版本默认采用扩展固定版本。
3. 启动时立即将 ACP 后端注册为未就绪。
4. 一个后台 ensure 作业会验证 `acpx --version`。
5. 如果插件本地二进制文件缺失或版本不匹配，它会运行：
`npm install --omit=dev --no-save acpx@<pinned>`，然后重新验证。
你可以在插件配置中覆盖命令 / 版本：
你可以在插件配置中覆盖命令/版本：
```json
{
@ -738,52 +724,45 @@ openclaw plugins install ./path/to/local/acpx-plugin
- `command` 接受绝对路径、相对路径或命令名（`acpx`）。
- 相对路径从 OpenClaw 工作区目录解析。
- `expectedVersion: "any"` 会禁用严格版本匹配。
- 当 `command` 指向自定义二进制文件 / 路径时，会禁用插件本地自动安装。
- 当 `command` 指向自定义二进制文件/路径时，插件本地自动安装会被禁用。
- 在后端健康检查运行期间，OpenClaw 启动仍然是非阻塞的。
参见 [Plugins](/zh-CN/tools/plugin)。
请参见 [Plugins](/zh-CN/tools/plugin)。
### 自动依赖安装
当你使用 `npm install -g openclaw` 全局安装 OpenClaw 时，acpx
运行时依赖（特定平台的二进制文件）会通过 postinstall hook 自动安装。如果自动安装失败，Gateway 网关仍会正常启动，
并通过 `openclaw acp doctor` 报告缺失的依赖。
当你通过 `npm install -g openclaw` 全局安装 OpenClaw 时，acpx 运行时依赖（平台特定二进制文件）会通过 postinstall hook 自动安装。如果自动安装失败，Gateway 网关仍会正常启动，并通过 `openclaw acp doctor` 报告缺失依赖。
### 插件工具 MCP 桥接
默认情况下，ACPX 会话**不会**将 OpenClaw 插件已注册的工具暴露给
ACP harness。
默认情况下，ACPX 会话**不会**向 ACP harness 暴露 OpenClaw 插件注册的工具。
如果你希望 Codex 或 Claude Code 之类的 ACP 智能体调用已安装的
OpenClaw 插件工具，例如记忆 recall / store，请启用专用桥接：
如果你希望 Codex 或 Claude Code 之类的 ACP 智能体调用已安装的 OpenClaw 插件工具，例如 memory recall/store，请启用专用桥接：
```bash
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
```
这会执行以下操作：
其作用是：
- 在 ACPX 会话引导中注入一个名为 `openclaw-plugin-tools` 的内置 MCP 服务器。
- 暴露已安装且已启用的 OpenClaw
插件所注册的插件工具。
- 保持该功能为显式启用，默认关闭。
- 将一个名为 `openclaw-plugin-tools` 的内置 MCP 服务器注入到 ACPX 会话引导中。
- 暴露已安装并启用的 OpenClaw 插件已经注册的插件工具。
- 保持该功能显式启用，且默认关闭。
安全与信任说明：
- 这会扩展 ACP harness 的工具暴露面。
- ACP 智能体只能访问 Gateway 网关中已激活的插件工具。
- 应将其视为与允许这些插件在
OpenClaw 本身中执行相同的信任边界。
- 启用前请审查已安装插件。
- 这会扩展 ACP harness 的工具面。
- ACP 智能体只能访问 Gateway 网关中已经活跃的插件工具。
- 应将其视为与允许这些插件在 OpenClaw 本身中执行相同的信任边界。
- 启用前请检查已安装的插件。
自定义 `mcpServers` 仍与以前一样工作。内置插件工具桥接是一个
额外的选择启用便利功能，而不是通用 MCP 服务器配置的替代品。
自定义 `mcpServers` 仍和以前一样可用。内置插件工具桥接只是一个额外的可选便利功能，不是通用 MCP 服务器配置的替代品。
## 权限配置
ACP 会话以非交互模式运行——没有 TTY 可用于批准或拒绝文件写入和 shell 执行权限提示。acpx 插件提供了两个用于控制权限处理方式的配置键：
ACP 会话以非交互方式运行 —— 没有 TTY 可以批准或拒绝文件写入和 shell 执行权限提示。acpx 插件提供两个控制权限处理方式的配置键：
这些 ACPX harness 权限与 OpenClaw exec 审批是分开的，也与 CLI 后端的厂商绕过标志（例如 Claude CLI 的 `--permission-mode bypassPermissions`）分开。ACPX 的 `approve-all` 是 ACP 会话的 harness 级紧急放开开关。
这些 ACPX harness 权限与 OpenClaw exec 审批分离，也与 CLI 后端供应商绕过标志（例如 Claude CLI `--permission-mode bypassPermissions`）分离。ACPX `approve-all` 是 ACP 会话在 harness 层级的紧急开关。
### `permissionMode`
@ -797,12 +776,12 @@ ACP 会话以非交互模式运行——没有 TTY 可用于批准或拒绝文
### `nonInteractivePermissions`
控制本应显示权限提示但没有可交互 TTY 可用时的处理方式（ACP 会话始终如此）。
控制当本应显示权限提示但没有可用的交互式 TTY 时（ACP 会话始终如此）会发生什么。
| 值 | 行为 |
| ------ | ----------------------------------------------------------------- |
| `fail` | 以 `AcpRuntimeError` 中止会话。**（默认）** |
| `deny` | 静默拒绝该权限并继续运行（平稳降级）。 |
| `deny` | 静默拒绝该权限并继续（优雅降级）。 |
### 配置
@ -813,11 +792,11 @@ openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
```
修改这些值后请重启 Gateway 网关。
更改这些值后重启 Gateway 网关。
> **重要：** OpenClaw 当前默认使用 `permissionMode=approve-reads` 和 `nonInteractivePermissions=fail`。在非交互 ACP 会话中，任何会触发权限提示的写入或执行都可能失败，并报错 `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`。
> **重要：** OpenClaw 当前默认使用 `permissionMode=approve-reads` 和 `nonInteractivePermissions=fail`。在非交互式 ACP 会话中，任何触发权限提示的写入或执行操作都可能因 `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` 而失败。
>
> 如果你需要限制权限，请将 `nonInteractivePermissions` 设置为 `deny`，这样会话就会平稳降级，而不是崩溃。
> 如果你需要限制权限，请将 `nonInteractivePermissions` 设为 `deny`，这样会话会优雅降级，而不是崩溃。
## 故障排除
@ -825,17 +804,17 @@ openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACP runtime backend is not configured` | 后端插件缺失或已禁用。 | 安装并启用后端插件，然后运行 `/acp doctor`。 |
| `ACP is disabled by policy (acp.enabled=false)` | ACP 已被全局禁用。 | 设置 `acp.enabled=true`。 |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 普通线程消息的分发已禁用。 | 设置 `acp.dispatch.enabled=true`。 |
| `ACP agent "<id>" is not allowed by policy` | 智能体不在 allowlist 中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 |
| `Unable to resolve session target: ...` | 错误的键 / ID / 标签标记。 | 运行 `/acp sessions`，复制精确的键 / 标签后重试。 |
| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动可绑定对话的情况下使用了 `--bind here`。 | 切换到目标聊天 / 渠道后重试，或使用未绑定生成。 |
| `Conversation bindings are unavailable for <channel>.` | 适配器缺少当前对话 ACP 绑定能力。 | 在支持时使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或切换到受支持的渠道。 |
| `--thread here requires running /acp spawn inside an active ... thread` | 在非线程上下文中使用了 `--thread here`。 | 切换到目标线程，或使用 `--thread auto` / `off`。 |
| `Only <user-id> can rebind this channel/conversation/thread.` | 另一个用户拥有当前绑定目标。 | 由所有者重新绑定，或使用不同的对话或线程。 |
| `Thread bindings are unavailable for <channel>.` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或切换到受支持的适配器 / 渠道。 |
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时在主机侧；请求方会话已沙箱隔离。 | 从已沙箱隔离的会话中使用 `runtime="subagent"`，或从非沙箱隔离会话中运行 ACP 生成。 |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对需要沙箱隔离的情况使用 `runtime="subagent"`，或在非沙箱隔离会话中将 ACP 与 `sandbox="inherit"` 一起使用。 |
| 已绑定会话缺少 ACP 元数据 | ACP 会话元数据已过期 / 被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定 / 聚焦线程。 |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互 ACP 会话中阻止了写入 / 执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all`，然后重启 Gateway 网关。参见[权限配置](#permission-configuration)。 |
| ACP 会话很早失败且输出很少 | 权限提示被 `permissionMode` / `nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。如需完整权限，请设置 `permissionMode=approve-all`；如需平稳降级，请设置 `nonInteractivePermissions=deny`。 |
| ACP 会话在完成工作后无限期卡住 | harness 进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动杀掉陈旧进程。 |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 来自普通线程消息的分发已禁用。 | 设置 `acp.dispatch.enabled=true`。 |
| `ACP agent "<id>" is not allowed by policy` | 智能体不在允许列表中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 |
| `Unable to resolve session target: ...` | 错误的键/ID/标签标记。 | 运行 `/acp sessions`，复制精确的键/标签，然后重试。 |
| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活跃可绑定会话的情况下使用了 `--bind here`。 | 移动到目标聊天/渠道后重试，或使用未绑定生成。 |
| `Conversation bindings are unavailable for <channel>.` | 适配器缺少当前会话 ACP 绑定能力。 | 在支持时使用 `/acp spawn ... --thread ...`、配置顶层 `bindings[]`，或切换到受支持的渠道。 |
| `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文之外使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 |
| `Only <user-id> can rebind this channel/conversation/thread.` | 另一个用户拥有当前活跃绑定目标。 | 由所有者重新绑定，或使用其他会话或线程。 |
| `Thread bindings are unavailable for <channel>.` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或切换到受支持的适配器/渠道。 |
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于主机侧；请求方会话处于沙箱隔离状态。 | 在沙箱会话中使用 `runtime="subagent"`，或从非沙箱会话运行 ACP 生成。 |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 如需强制沙箱隔离，请使用 `runtime="subagent"`，或从非沙箱会话使用带 `sandbox="inherit"` 的 ACP。 |
| 绑定会话缺少 ACP 元数据 | ACP 会话元数据已过时/被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互式 ACP 会话中阻止了写入/执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设为 `approve-all` 并重启 Gateway 网关。请参见[权限配置](#permission-configuration)。 |
| ACP 会话在很早阶段失败且几乎没有输出 | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。如需完整权限，设置 `permissionMode=approve-all`；如需优雅降级，设置 `nonInteractivePermissions=deny`。 |
| ACP 会话在完成工作后无限期卡住 | harness 进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动终止陈旧进程。 |