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-10 20:36:33 +00:00
parent 094a6cdb4d
commit 085528131a
4 changed files with 1239 additions and 1172 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -5,127 +5,127 @@ read_when:
summary: 模型提供商概览，包含示例配置和 CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-04-10T20:23:47Z"
generated_at: "2026-04-10T20:28:58Z"
model: gpt-5.4
provider: openai
source_hash: f3d50795107077c7065773b5e545fae04b97f1d932a650d577b325d93bf25192
source_hash: fc970eacc8babdd43e3e83f164846b82d1289f8335732d2135dc9f41c560489e
source_path: concepts/model-providers.md
workflow: 15
---
# 模型提供商
本页介绍 **LLM / 模型提供商**（不是像 WhatsApp / Telegram 这样的聊天渠道）。
有关模型选择规则，请参见 [/concepts/models](/zh-CN/concepts/models)。
本页介绍 **LLM/模型提供商**（不是像 WhatsApp/Telegram 这样的聊天渠道）。
关于模型选择规则，请参阅 [/concepts/models](/zh-CN/concepts/models)。
## 快速规则
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
- 模型引用使用 `provider/model`（例如：`opencode/claude-opus-4-6`）。
- 如果你设置了 `agents.defaults.models`，它就会成为允许列表。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover)。
- `models.providers.*.models[].contextWindow` 是原生模型元数据；`models.providers.*.models[].contextTokens` 是实际运行时上限。
- 回退运行时规则、冷却探测以及会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover)。
- `models.providers.*.models[].contextWindow` 是原生模型元数据；`models.providers.*.models[].contextTokens` 是运行时生效的上限。
- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前将该输出合并到 `models.providers` 中。
- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样通用的基于环境变量的凭证探测和提供商变体就不需要加载插件运行时。剩余的核心环境变量映射现在仅用于非插件 / 核心提供商，以及少数通用优先级场景，例如 Anthropic API 密钥优先的新手引导。
- 提供商插件还可以通过以下能力拥有提供商运行时行为：`normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 和 `onModelSelected`。
- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录 / 工具怪癖、传输 / 缓存提示）。它不同于[公共能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么内容（文本推理、语音等）。
- 内置的 `codex` 提供商与内置的 Codex 智能体 harness 配对使用。当你需要 Codex 自有登录、模型发现、原生线程恢复和应用服务器执行时，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍会使用 OpenAI 提供商和标准的 OpenClaw 提供商传输。
- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样通用的基于环境变量的凭证探测和提供商变体就不需要加载插件运行时。剩余的核心环境变量映射现在仅用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic API 密钥优先的新手引导。
- 提供商插件还可以通过以下能力拥有提供商运行时行为：`normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 以及 `onModelSelected`。
- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录/工具特性差异、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么（文本推理、语音等）。
- 内置的 `codex` 提供商与内置 Codex 智能体 harness 配对使用。当你需要 Codex 自有的登录、模型发现、原生线程恢复和 app-server 执行时，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍将使用 OpenAI 提供商和常规的 OpenClaw 提供商传输。仅使用 Codex 的部署可以通过 `agents.defaults.embeddedHarness.fallback: "none"` 禁用自动 PI 回退；请参阅 [Agent Harness Plugins](/zh-CN/plugins/sdk-agent-harness#disable-pi-fallback)。
## 插件自有的提供商行为
提供商插件现在可以拥有大多数提供商特定逻辑，而 OpenClaw 保持通用推理循环。
提供商插件现在可以拥有大多数提供商特定逻辑，而 OpenClaw 保留通用推理循环。
典型分工：
典型拆分如下：
- `auth[].run` / `auth[].runNonInteractive`：提供商拥有用于 `openclaw onboard`、`openclaw models auth` 和无头设置的新手引导 / 登录流程
- `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
- `prepareDynamicModel`：提供商需要在重试动态解析前刷新元数据
- `normalizeResolvedModel`：提供商需要重写传输或基础 URL
- `contributeResolvedModelCompat`：即使其厂商模型通过另一种兼容传输到达，提供商也可以为其贡献兼容标志
- `capabilities`：提供商发布转录 / 工具 / 提供商家族怪癖
- `normalizeToolSchemas`：提供商会在嵌入式运行器看到工具 schema 之前对其进行清理
- `inspectToolSchemas`：提供商会在标准化之后暴露传输特定的 schema 警告
- `resolveReasoningOutputMode`：提供商选择原生或带标签的推理输出契约
- `prepareExtraParams`：提供商为按模型划分的请求参数提供默认值或进行标准化
- `createStreamFn`：提供商用完全自定义的传输替换正常流式路径
- `wrapStreamFn`：提供商应用请求头 / 请求体 / 模型兼容包装器
- `resolveTransportTurnState`：提供商提供每轮的原生传输头或元数据
- `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话头或会话冷却策略
- `createEmbeddingProvider`：当记忆嵌入行为应归属于提供商插件而不是核心嵌入切换板时，由提供商负责
- `formatApiKey`：提供商将存储的凭证配置格式化为传输所期望的运行时 `apiKey` 字符串
- `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`：提供商需要重写传输或 base URL
- `contributeResolvedModelCompat`：即使供应商模型通过另一个兼容传输到达，提供商也会为其贡献兼容标记
- `capabilities`：提供商发布转录/工具/提供商家族特性差异
- `normalizeToolSchemas`：提供商在嵌入式运行器看到工具 schema 之前先进行清理
- `inspectToolSchemas`：提供商在规范化后暴露特定于传输的 schema 警告
- `resolveReasoningOutputMode`：提供商选择原生还是带标签的推理输出契约
- `prepareExtraParams`：提供商为每个模型的请求参数提供默认值或进行规范化
- `createStreamFn`：提供商用完全自定义的传输替换正常的流式路径
- `wrapStreamFn`：提供商应用请求头/请求体/模型兼容性包装器
- `resolveTransportTurnState`：提供商提供每轮的原生传输请求头或元数据
- `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话请求头或会话冷却策略
- `createEmbeddingProvider`：当记忆嵌入行为更适合归属于提供商插件而不是核心嵌入切换板时，由提供商拥有该行为
- `formatApiKey`：提供商将已存储的凭证配置档格式化为传输所期望的运行时 `apiKey` 字符串
- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足时，由提供商负责 OAuth 刷新
- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商追加修复指导
- `matchesContextOverflowError`：提供商识别通用启发式方法可能漏掉的提供商特定上下文窗口溢出错误
- `classifyFailoverReason`：提供商将提供商特定的原始传输 / API 错误映射为回退原因，例如速率限制或过载
- `isCacheTtlEligible`：提供商决定哪些上游模型 ID 支持提示缓存 TTL
- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用凭证存储错误
- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以在直接解析失败时返回厂商自有错误
- `augmentModelCatalog`：提供商在发现和配置合并之后追加合成 / 最终目录条目
- `isBinaryThinking`：提供商拥有二元开 / 关思考 UX
- `supportsXHighThinking`：提供商让选定模型支持 `xhigh`
- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商附加修复指导
- `matchesContextOverflowError`：提供商识别通用启发式无法捕捉的提供商特定上下文窗口溢出错误
- `classifyFailoverReason`：提供商将特定于提供商的原始传输/API 错误映射为回退原因，例如速率限制或过载
- `isCacheTtlEligible`：提供商决定哪些上游模型 id 支持提示缓存 TTL
- `buildMissingAuthMessage`：提供商用特定于提供商的恢复提示替换通用凭证存储错误
- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以在直接解析失败时返回供应商自有错误
- `augmentModelCatalog`：提供商在发现和配置合并之后附加合成/最终目录条目
- `isBinaryThinking`：提供商拥有二元开/关 thinking UX
- `supportsXHighThinking`：提供商为选定模型启用 `xhigh`
- `resolveDefaultThinkingLevel`：提供商拥有某个模型家族的默认 `/think` 策略
- `applyConfigDefaults`：提供商在配置实体化期间根据凭证模式、环境或模型家族应用提供商特定的全局默认值
- `isModernModelRef`：提供商拥有 live / smoke 首选模型匹配
- `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 消息流量的仅限 Claude 的重放策略保护
- `openrouter`：透传模型 ID、请求包装器、提供商能力提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族进行代理推理注入、路由元数据转发，以及缓存 TTL 策略
- `github-copilot`：新手引导 / 设备登录、前向兼容模型回退、Claude-thinking 转录提示、运行时令牌交换，以及使用量端点获取
- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输标准化、支持 Codex 感知的缺失凭证提示、Spark 抑制、合成 OpenAI / Codex 目录条目、thinking / live-model 策略、使用量令牌别名标准化（`input` / `output` 和 `prompt` / `completion` 家族）、用于原生 OpenAI / Codex 包装器的共享 `openai-responses-defaults` 流家族、提供商家族元数据、为 `gpt-image-1` 内置的图像生成提供商注册，以及为 `sora-2` 内置的视频生成提供商注册
- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、bootstrap 重放清理、带标签的推理输出模式、现代模型匹配、为 Gemini image-preview 模型内置的图像生成提供商注册，以及为 Veo 模型内置的视频生成提供商注册；Gemini CLI OAuth 还拥有凭证配置令牌格式化、使用量令牌解析，以及用于使用量界面的配额端点获取
- `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 特有的工具 schema / 推理负载清理，以及为 `grok-imagine-video` 内置的视频生成提供商注册
- `mistral`：由插件自有的能力元数据
- `opencode` 和 `opencode-go`：由插件自有的能力元数据，外加代理 Gemini thought-signature 清理
- `alibaba`：由插件自有的直接 Wan 模型引用视频生成目录，例如 `alibaba/wan2.6-t2v`
- `byteplus`：由插件自有的目录，外加为 Seedance 文本转视频 / 图像转视频模型内置的视频生成提供商注册
- `fal`：为托管的第三方图像生成提供商内置的 FLUX 图像模型注册，外加为托管的第三方视频模型内置的视频生成提供商注册
- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅有由插件自有的目录
- `qwen`：文本模型由插件自有的目录，外加其多模态界面的共享 media-understanding 和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点以及内置的 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v`
- `runway`：为原生 Runway 基于任务的模型（例如 `gen4.5`）由插件自有的视频生成提供商注册
- `minimax`：由插件自有的目录、为 Hailuo 视频模型内置的视频生成提供商注册、为 `image-01` 内置的图像生成提供商注册、混合的 Anthropic / OpenAI 重放策略选择，以及使用量凭证 / 快照逻辑
- `together`：由插件自有的目录，外加为 Wan 视频模型内置的视频生成提供商注册
- `xiaomi`：由插件自有的目录，外加使用量凭证 / 快照逻辑
- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、用量端点获取、缓存 TTL/提供商家族元数据，以及具备凭证感知的全局配置默认值
- `amazon-bedrock`：提供商自有的上下文溢出匹配，以及针对 Bedrock 特有节流/未就绪错误的回退原因分类，另外还包括共享的 `anthropic-by-model` 重放家族，用于 Anthropic 流量上仅限 Claude 的重放策略保护
- `anthropic-vertex`：针对 Anthropic-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/Codex 包装器的共享 `openai-responses-defaults` 流家族、提供商家族元数据、为 `gpt-image-1` 注册的内置图像生成提供商，以及为 `sora-2` 注册的内置视频生成提供商
- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、引导重放清理、带标签的推理输出模式、现代模型匹配、为 Gemini image-preview 模型注册的内置图像生成提供商，以及为 Veo 模型注册的内置视频生成提供商；Gemini CLI OAuth 还拥有用于用量界面的凭证配置档令牌格式化、用量令牌解析和配额端点获取
- `moonshot`：共享传输、插件自有的 thinking 负载规范化
- `kilocode`：共享传输、插件自有的请求头、推理负载规范化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略
- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元 thinking/live-model 策略，以及用量凭证 + 配额获取；未知的 `glm-5*` id 会基于内置的 `glm-4.7` 模板合成
- `xai`：原生 Responses 传输规范化、针对 Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特有的工具 schema / 推理负载清理，以及为 `grok-imagine-video` 注册的内置视频生成提供商
- `mistral`：插件自有的能力元数据
- `opencode` 和 `opencode-go`：插件自有的能力元数据，以及代理 Gemini thought-signature 清理
- `alibaba`：针对直接 Wan 模型引用（如 `alibaba/wan2.6-t2v`）的插件自有视频生成目录
- `byteplus`：插件自有目录，以及为 Seedance 文本生成视频/图像生成视频模型注册的内置视频生成提供商
- `fal`：为托管的第三方图像生成模型注册的内置图像生成提供商，以及为托管的第三方视频模型注册的内置视频生成提供商
- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅有插件自有目录
- `qwen`：文本模型的插件自有目录，以及其多模态能力所使用的共享 media-understanding 和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点以及内置 Wan 模型，如 `wan2.6-t2v` 和 `wan2.7-r2v`
- `runway`：为原生 Runway 基于任务的模型（如 `gen4.5`）注册的插件自有视频生成提供商
- `minimax`：插件自有目录、为 Hailuo 视频模型注册的内置视频生成提供商、为 `image-01` 注册的内置图像生成提供商、混合 Anthropic/OpenAI 重放策略选择，以及用量凭证/快照逻辑
- `together`：插件自有目录，以及为 Wan 视频模型注册的内置视频生成提供商
- `xiaomi`：插件自有目录，以及用量凭证/快照逻辑
内置的 `openai` 插件现在同时拥有这两个提供商 ID：`openai` 和 `openai-codex`。
内置的 `openai` 插件现在拥有这两个提供商 id：`openai` 和 `openai-codex`。
以上涵盖了仍适配 OpenClaw 正常传输方式的提供商。需要完全自定义请求执行器的提供商，则属于另一个更深层的扩展接口。
以上涵盖了仍然适配 OpenClaw 常规传输的提供商。对于需要完全自定义请求执行器的提供商，则属于另一个更深入的扩展接口层。
## API 密钥轮换
- 支持为选定提供商进行通用提供商轮换。
- 通过以下方式配置多个密钥：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个 live 覆盖，优先级最高）
- 支持针对选定提供商的通用提供商轮换。
- 可通过以下方式配置多个密钥：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个 live 覆盖，最高优先级）
- `<PROVIDER>_API_KEYS`（逗号或分号分隔列表）
- `<PROVIDER>_API_KEY`（主密钥）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退项包含在内。
- 密钥选择顺序会保留优先级并对值去重。
- 只有在速率限制响应时才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、“Too many concurrent requests”、`ThrottlingException`、“concurrency limit reached”、`workers_ai ... quota limit exceeded` 或周期性的使用量限制消息）。
- 对于 Google 提供商，也会将 `GOOGLE_API_KEY` 作为回退项包含在内。
- 密钥选择顺序会保留优先级并去重数值。
- 仅在速率限制响应时，请求才会使用下一个密钥重试（例如 `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
@ -134,13 +134,13 @@ OpenClaw 附带 pi-ai 目录。这些提供商**不需要** `models.providers`
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
- 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-pro`
- CLI：`openclaw onboard --auth-choice openai-api-key`
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
- 默认传输是 `auto`（WebSocket 优先，SSE 回退）
- 可通过 `agents.defaults.models["openai/<model>"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup`（`true` / `false`）启用
- 可以通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先级处理
- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- 如果你想使用显式层级而不是共享的 `/fast` 开关，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用的 OpenAI 兼容代理
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup`（`true`/`false`）启用
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先处理
- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- 当你想显式指定层级而不是使用共享 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归属请求头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示以及 OpenAI 推理兼容负载整形；代理路由不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex
@ -157,9 +157,9 @@ OpenClaw 附带 pi-ai 目录。这些提供商**不需要** `models.providers`
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖）
- 示例模型：`anthropic/claude-opus-4-6`
- CLI：`openclaw onboard --auth-choice apiKey`
- 直接的公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 与 `standard_only`）
- Anthropic 说明：Anthropic 员工告诉我们，再次允许 OpenClaw 风格的 Claude CLI 用法，因此 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成的受认可方式，除非 Anthropic 发布新策略。
- Anthropic setup-token 仍可作为受支持的 OpenClaw 令牌路径使用，但 OpenClaw 现在在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。
- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成的受支持方式。
- Anthropic setup-token 仍然作为受支持的 OpenClaw 令牌路径可用，但 OpenClaw 现在在可用时更倾向于 Claude CLI 复用和 `claude -p`。
```json5
{
@ -173,14 +173,14 @@ OpenClaw 附带 pi-ai 目录。这些提供商**不需要** `models.providers`
- 凭证：OAuth（ChatGPT）
- 示例模型：`openai-codex/gpt-5.4`
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
- 默认传输是 `auto`（WebSocket 优先，SSE 回退）
- 可通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）中转发
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority`
- 当 Codex OAuth 目录暴露 `openai-codex/gpt-5.3-codex-spark` 时，它仍然可用；取决于授权资格
- `openai-codex/gpt-5.4` 保持原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- 策略说明：OpenAI Codex OAuth 明确支持用于像 OpenClaw 这样的外部工具 / 工作流。
- 隐藏的 OpenClaw 归属请求头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
- 与直接 `openai/*` 共用相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射到 `service_tier=priority`
- 当 Codex OAuth 目录暴露它时，`openai-codex/gpt-5.3-codex-spark` 仍然可用；是否可用取决于 entitlement
- `openai-codex/gpt-5.4` 保留原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- 策略说明：OpenAI Codex OAuth 被明确支持用于 OpenClaw 这类外部工具/工作流。
```json5
{
@ -226,15 +226,15 @@ OpenClaw 附带 pi-ai 目录。这些提供商**不需要** `models.providers`
- 凭证：`GEMINI_API_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-gemini-cli`
- 凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后遭遇了 Google 账号限制。请先查看 Google 条款，如果你选择继续，请使用非关键账号。
- 注意：OpenClaw 中的 Gemini CLI OAuth 属于非官方集成。一些用户报告称，在使用第三方客户端后，他们的 Google 账号受到了限制。请先查看 Google 条款，并且如果你决定继续，建议使用非关键账号。
- Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
- 先安装 Gemini CLI：
- `brew install gemini-cli`
@ -242,9 +242,9 @@ OpenClaw 附带 pi-ai 目录。这些提供商**不需要** `models.providers`
- 启用：`openclaw plugins enable google`
- 登录：`openclaw models auth login --provider google-gemini-cli --set-default`
- 默认模型：`google-gemini-cli/gemini-3-flash-preview`
- 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的凭证配置中。
- 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储到 Gateway 网关主机上的凭证配置档中。
- 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
- Gemini CLI JSON 回复会从 `response` 解析；使用量会回退到 `stats`，其中 `stats.cached` 会被标准化为 OpenClaw `cacheRead`。
- Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，并将 `stats.cached` 规范化为 OpenClaw `cacheRead`。
### Z.AI（GLM）
@ -252,8 +252,8 @@ OpenClaw 附带 pi-ai 目录。这些提供商**不需要** `models.providers`
- 凭证：`ZAI_API_KEY`
- 示例模型：`zai/glm-5.1`
- CLI：`openclaw onboard --auth-choice zai-api-key`
- 别名：`z.ai/*` 和 `z-ai/*` 会被标准化为 `zai/*`
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口
- 别名：`z.ai/*` 和 `z-ai/*` 会被规范化为 `zai/*`
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制指定某个特定接口
### Vercel AI Gateway
@ -268,27 +268,27 @@ OpenClaw 附带 pi-ai 目录。这些提供商**不需要** `models.providers`
- 凭证：`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` 发现机制可以进一步扩展运行时目录。
- Base URL：`https://api.kilo.ai/api/gateway/`
- 静态回退目录内置了 `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 重写不会启用
- 只有当请求实际发送到 `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 密钥）和 `minimax-portal`（OAuth）
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
- 示例模型：`minimax/MiniMax-M2.7` 或 `minimax-portal/MiniMax-M2.7`
- MiniMax 新手引导 / API 密钥设置会写入显式的 M2.7 模型定义，并带有 `input: ["text", "image"]`；在该提供商配置实体化之前，内置提供商目录会将聊天引用保持为仅文本
- MiniMax 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`）
@ -314,28 +314,29 @@ OpenClaw 附带 pi-ai 目录。这些提供商**不需要** `models.providers`
- 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` 可将其关闭
- `tool_stream` 默认开启；如需禁用，请将 `agents.defaults.models["xai/<model>"].params.tool_stream` 设置为 `false`
- Mistral：`mistral`（`MISTRAL_API_KEY`）
- 示例模型：`mistral/mistral-large-latest`
- CLI：`openclaw onboard --auth-choice mistral-api-key`
- Groq：`groq`（`GROQ_API_KEY`）
- Cerebras：`cerebras`（`CEREBRAS_API_KEY`）
- Cerebras 上的 GLM 模型使用 ID `zai-glm-4.7` 和 `zai-glm-4.6`。
- OpenAI 兼容基础 URL：`https://api.cerebras.ai/v1`。
- Cerebras 上的 GLM 模型使用 id `zai-glm-4.7` 和 `zai-glm-4.6`。
- OpenAI 兼容 base URL：`https://api.cerebras.ai/v1`。
- GitHub Copilot：`github-copilot`（`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`）
- Hugging Face Inference 示例模型：`huggingface/deepseek-ai/DeepSeek-R1`；CLI：`openclaw onboard --auth-choice huggingface-api-key`。请参见 [Hugging Face（Inference）](/zh-CN/providers/huggingface)。
- Hugging Face Inference 示例模型：`huggingface/deepseek-ai/DeepSeek-R1`；CLI：`openclaw onboard --auth-choice huggingface-api-key`。请参阅 [Hugging Face（Inference）](/zh-CN/providers/huggingface)。
## 通过 `models.providers` 配置的提供商（自定义 / 基础 URL）
## 通过 `models.providers` 配置的提供商（自定义/base URL）
使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或 OpenAI / Anthropic 兼容代理。
使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。
下面许多内置提供商插件已经发布了默认目录。只有当你想覆盖默认基础 URL、请求头或模型列表时，才使用显式的 `models.providers.<id>` 条目。
下面许多内置提供商插件已经发布了默认目录。
只有当你想覆盖默认 base URL、请求头或模型列表时，才需要使用显式的 `models.providers.<id>` 条目。
### Moonshot AI（Kimi）
Moonshot 作为内置提供商插件提供。默认请使用内置提供商，只有在你需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
Moonshot 作为内置提供商插件提供。默认请使用内置提供商，只有在你需要覆盖 base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
- 提供商：`moonshot`
- 凭证：`MOONSHOT_API_KEY`
@ -389,13 +390,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
}
```
旧版 `kimi/k2p5` 仍然作为兼容模型 ID 被接受。
旧版 `kimi/k2p5` 仍然被接受作为兼容模型 id。
### 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`
@ -408,9 +409,9 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
}
```
新手引导默认使用编程接口，但通用的 `volcengine/*` 目录也会同时注册。
新手引导默认使用编程接口，但通用 `volcengine/*` 目录也会同时注册。
在新手引导 / 配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商范围筛选的选择器。
在 onboarding/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商范围筛选的选择器。
可用模型：
@ -430,9 +431,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`
@ -445,9 +446,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。
}
```
新手引导默认使用编程接口，但通用的 `byteplus/*` 目录也会同时注册。
新手引导默认使用编程接口，但通用 `byteplus/*` 目录也会同时注册。
在新手引导 / 配置模型选择器中，BytePlus（国际版）凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商范围筛选的选择器。
在 onboarding/配置模型选择器中，BytePlus（国际版）凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商范围筛选的选择器。
可用模型：
@ -501,16 +502,16 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax API 密钥（CN）：`--auth-choice minimax-cn-api`
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
有关设置详情、模型选项和配置片段，请参见 [/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`
- Web 搜索保持使用提供商 ID `minimax`
- 图像理解在两条 MiniMax 凭证路径上都使用插件自有的 `MiniMax-VL-01`
- Web 搜索保持在提供商 id `minimax`
### Ollama
@ -534,23 +535,23 @@ ollama pull llama3.3
}
```
当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，并且内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。有关新手引导、云端 / 本地模式和自定义配置，请参见 [/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
vLLM 作为内置提供商插件提供，用于本地 / 自托管的 OpenAI 兼容服务器：
vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容服务器：
- 提供商：`vllm`
- 凭证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:8000/v1`
- 默认 base URL：`http://127.0.0.1:8000/v1`
要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）：
如需在本地选择启用自动发现（如果你的服务器不强制验证凭证，任意值都可以）：
```bash
export VLLM_API_KEY="vllm-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 id）：
```json5
{
@ -560,23 +561,23 @@ export VLLM_API_KEY="vllm-local"
}
```
详情请参见 [/providers/vllm](/zh-CN/providers/vllm)。
详情请参阅 [/providers/vllm](/zh-CN/providers/vllm)。
### SGLang
SGLang 作为内置提供商插件提供，用于快速的自托管 OpenAI 兼容服务器：
SGLang 作为内置提供商插件提供，用于高性能自托管的 OpenAI 兼容服务器：
- 提供商：`sglang`
- 凭证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:30000/v1`
- 默认 base URL：`http://127.0.0.1:30000/v1`
要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）：
如需在本地选择启用自动发现（如果你的服务器不强制验证凭证，任意值都可以）：
```bash
export SGLANG_API_KEY="sglang-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 id）：
```json5
{
@ -586,7 +587,7 @@ export SGLANG_API_KEY="sglang-local"
}
```
详情请参见 [/providers/sglang](/zh-CN/providers/sglang)。
详情请参阅 [/providers/sglang](/zh-CN/providers/sglang)。
### 本地代理（LM Studio、vLLM、LiteLLM 等）
@ -597,7 +598,7 @@ export SGLANG_API_KEY="sglang-local"
agents: {
defaults: {
model: { primary: "lmstudio/my-local-model" },
models: { "lmstudio/my-local-model": { alias: "Local" } },
models: { "lmstudio/my-local-model": { alias: "本地" } },
},
},
models: {
@ -609,7 +610,7 @@ export SGLANG_API_KEY="sglang-local"
models: [
{
id: "my-local-model",
name: "Local Model",
name: "本地模型",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
@ -632,10 +633,10 @@ export SGLANG_API_KEY="sglang-local"
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`
- 建议：设置与你的代理 / 模型限制匹配的显式值。
- 对于非原生端点上的 `api: "openai-completions"`（任何 host 不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
- 代理风格的 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求整形：没有 `service_tier`，没有 Responses `store`，没有提示缓存提示，没有 OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归因请求头。
- 如果 `baseUrl` 为空 / 被省略，OpenClaw 会保留默认的 OpenAI 行为（即解析到 `api.openai.com`）。
- 建议：设置与你的代理/模型限制匹配的显式值。
- 对于非原生端点上的 `api: "openai-completions"`（任何 host 不是 `api.openai.com` 的非空 `baseUrl`），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` 端点上仍会被覆盖。
## CLI 示例
@ -646,11 +647,11 @@ openclaw models set opencode/claude-opus-4-6
openclaw models list
```
另请参见：[/gateway/configuration](/zh-CN/gateway/configuration)，获取完整配置示例。
另请参阅：[/gateway/configuration](/zh-CN/gateway/configuration)，查看完整配置示例。
## 相关内容
- [Models](/zh-CN/concepts/models) — 模型配置和别名
- [模型](/zh-CN/concepts/models) — 模型配置和别名
- [Model Failover](/zh-CN/concepts/model-failover) — 回退链和重试行为
- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键
- [Providers](/zh-CN/providers) — 按提供商分类的设置指南

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

File diff suppressed because it is too large Load Diff

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

@ -3,13 +3,13 @@ read_when:
- 在本地或 CI 中运行测试
- 为模型 / 提供商缺陷添加回归测试
- 调试 Gateway 网关 + 智能体行为
summary: 测试工具包：单元 / e2e / 实时测试套件、Docker 运行器，以及每项测试所覆盖的内容
summary: 测试工具包：单元 / e2e / 实时测试套件、Docker 运行器，以及每类测试覆盖的内容
title: 测试
x-i18n:
generated_at: "2026-04-10T20:23:46Z"
generated_at: "2026-04-10T20:28:58Z"
model: gpt-5.4
provider: openai
source_hash: e24030b221699c7695ab5c87409a2646b7c5d014780a3482410c3375be8e3bd8
source_hash: e19cfbfcc708c0075d77364e2f20d8e8b8c4300cba97b0c525524882612b7cad
source_path: help/testing.md
workflow: 15
---
@ -20,24 +20,24 @@ OpenClaw 有三套 Vitest 测试套件（单元 / 集成、e2e、实时）以及
本文档是一份“我们如何测试”的指南：
- 每个测试套件覆盖什么（以及它刻意 _不_ 覆盖什么）
- 每个测试套件覆盖什么内容（以及它刻意 _不_ 覆盖什么）
- 常见工作流应运行哪些命令（本地、推送前、调试）
- 实时测试如何发现凭证并选择模型 / 提供商
- 实时测试如何发现凭证，以及如何选择模型 / 提供商
- 如何为真实世界中的模型 / 提供商问题添加回归测试
## 快速开始
大多数时候：
- 完整门禁（推送前的预期要求）：`pnpm build && pnpm check && pnpm test`
- 在配置充足的机器上更快地运行本地全量测试：`pnpm test:max`
- 完整门禁（推送前预期执行）：`pnpm build && pnpm check && pnpm test`
- 在配置较好的机器上更快地运行本地全套测试：`pnpm test:max`
- 直接进入 Vitest 监听循环：`pnpm test:watch`
- 直接按文件定位现在也会路由扩展 / 渠道路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
- 当你在迭代处理单个失败用例时，优先先运行定向测试。
- 当你正在迭代单个失败用例时，优先选择有针对性的运行。
- 基于 Docker 的 QA 站点：`pnpm qa:lab:up`
- 基于 Linux VM 的 QA 通道：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline`
- 基于 Linux VM 的 QA 测试通道：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline`
当你修改了测试，或想获得更多信心时：
当你改动了测试或想获得更高信心时：
- 覆盖率门禁：`pnpm test:coverage`
- E2E 测试套件：`pnpm test:e2e`
@ -47,245 +47,244 @@ OpenClaw 有三套 Vitest 测试套件（单元 / 集成、e2e、实时）以及
- 实时测试套件（模型 + Gateway 网关工具 / 图像探测）：`pnpm test:live`
- 安静地只运行一个实时测试文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts`
提示：当你只需要一个失败用例时，优先使用下面描述的 allowlist 环境变量来缩小实时测试范围。
提示：当你只需要一个失败用例时，优先使用下面介绍的 allowlist 环境变量来缩小实时测试范围。
## QA 专用运行器
当你需要 QA-lab 级别的真实环境时，这些命令与主测试套件并列使用：
当你需要 QA-lab 级别的真实环境时，这些命令与主测试套件配合使用：
- `pnpm openclaw qa suite`
- 直接在宿主机上运行基于仓库的 QA 场景。
- 默认会使用隔离的 Gateway 网关工作进程并行运行多个所选场景，最多 64 个工作进程或所选场景数。使用 `--concurrency <count>` 调整工作进程数量，或使用 `--concurrency 1` 回到旧的串行通道。
- 直接在主机上运行由仓库支持的 QA 场景。
- 默认并行运行多个选定场景，并使用隔离的 Gateway 网关工作进程，最多 64 个工作进程或所选场景数量。使用 `--concurrency <count>` 调整工作进程数，或使用 `--concurrency 1` 进入旧的串行通道。
- `pnpm openclaw qa suite --runner multipass`
- 在一次性的 Multipass Linux VM 中运行同一套 QA 测试。
- 保持与宿主机上 `qa suite` 相同的场景选择行为。
- 复用与 `qa suite` 相同的提供商 / 模型选择标志。
- 实时运行会转发对来宾环境实际可用的受支持 QA 认证输入：
- 与主机上的 `qa suite` 保持相同的场景选择行为。
- 复用 `qa suite` 相同的提供商 / 模型选择参数。
- 实时运行会转发适合来宾环境使用的受支持 QA 凭证输入：
基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。
- 输出目录必须保持在仓库根目录下，以便来宾可通过挂载的工作区回写。
- 会将常规 QA 报告 + 摘要以及 Multipass 日志写入
`.artifacts/qa-e2e/...`。
- 输出目录必须保持在仓库根目录下，以便来宾能通过挂载的工作区回写内容。
- 会在 `.artifacts/qa-e2e/...` 下写入常规 QA 报告 + 摘要以及 Multipass 日志。
- `pnpm qa:lab:up`
- 启动基于 Docker 的 QA 站点，供运维式 QA 工作使用。
- 启动基于 Docker 的 QA 站点，用于操作员风格的 QA 工作。
## 测试套件（各自在哪里运行）
## 测试套件（各自在哪里运行什么）
可以把这些套件理解为“真实度逐步提高”（同时不稳定性 / 成本也逐步增加）：
可以把这些测试套件理解为“真实度逐步增加”（同时不稳定性 / 成本也逐步增加）：
### 单元 / 集成（默认）
- 命令：`pnpm test`
- 配置：通过现有分域 Vitest 项目运行十个顺序分片（`vitest.full-*.config.ts`）
- 配置：在现有作用域化 Vitest 项目上执行十个顺序分片运行（`vitest.full-*.config.ts`）
- 文件：`src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 下的核心 / 单元测试清单，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` Node 测试
- 范围：
- 纯单元测试
- 进程内集成测试（Gateway 网关认证、路由、工具、解析、配置）
- 已知缺陷的确定性回归测试
- 进程内集成测试（Gateway 网关鉴权、路由、工具、解析、配置）
- 针对已知缺陷的确定性回归测试
- 预期：
- 在 CI 中运行
- 不需要真实密钥
- 应该快速且稳定
- 项目说明：
- 无目标的 `pnpm test` 现在会运行 11 个更小的分片配置（`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一个庞大的原生根项目进程。这样可以降低高负载机器上的 RSS 峰值，并避免 auto-reply / 扩展相关工作挤占无关套件资源。
- 不带目标的 `pnpm test` 现在会运行 11 个更小的分片配置（`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一个巨大的原生根项目进程。这样可以降低高负载机器上的峰值 RSS，并避免 auto-reply / 扩展工作拖慢无关测试套件。
- `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` 项目图，因为多分片监听循环并不现实。
- `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 现在会优先将显式文件 / 目录目标路由到分域通道，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 不需要承担整个根项目启动的成本。
- 当 diff 只涉及可路由的源码 / 测试文件时，`pnpm test:changed` 会将变更过的 git 路径扩展到相同的分域通道；配置 / setup 改动仍会回退到更广泛的根项目重跑。
- 一些选定的 `plugin-sdk` 和 `commands` 测试也会通过专用轻量通道运行，从而跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时较重的文件仍保留在现有通道上。
- 一些选定的 `plugin-sdk` 和 `commands` 辅助源码文件也会把 changed 模式运行映射到这些轻量通道中的显式同级测试，因此辅助文件改动不必为该目录重跑完整的重型套件。
- `auto-reply` 现在有三个专用桶：顶层核心辅助函数、顶层 `reply.*` 集成测试，以及 `src/auto-reply/reply/**` 子树。这样能让最重的 reply harness 工作不再压到廉价的 status / chunk / token 测试上。
- `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会先将显式文件 / 目录目标路由到作用域化通道，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 不必承担完整根项目启动开销。
- 当 diff 只涉及可路由的源文件 / 测试文件时，`pnpm test:changed` 会把 git 改动路径扩展到相同的作用域化通道；配置 / setup 编辑仍会回退到更广泛的根项目重新运行。
- 选定的 `plugin-sdk` 和 `commands` 测试也会通过专用轻量通道运行，以跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时较重的文件仍保留在现有通道中。
- 选定的 `plugin-sdk` 和 `commands` 辅助源文件也会在 changed 模式下将运行映射到这些轻量通道中的显式同级测试，因此辅助文件修改无需重新运行该目录下完整的重型测试套件。
- `auto-reply` 现在有三个专用分桶：顶层核心辅助函数、顶层 `reply.*` 集成测试，以及 `src/auto-reply/reply/**` 子树。这样可以让最重的 reply harness 工作不影响廉价的 status / chunk / token 测试。
- 嵌入式运行器说明：
- 当你修改消息工具发现输入或压缩运行时上下文时，
要同时保持两个层级的覆盖。
请同时保持两个层级的覆盖。
- 为纯路由 / 规范化边界添加聚焦的辅助函数回归测试。
- 同时也要保持嵌入式运行器集成测试套件健康：
`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` 路径；仅有辅助函数测试并不能充分替代这些集成路径。
- 进程池说明：
- 基础 Vitest 配置现在默认使用 `threads`。
- 共享 Vitest 配置还固定了 `isolate: false`，并在根项目、e2e 和实时配置中使用非隔离运行器。
- 根 UI 通道保留了它的 `jsdom` 设置和优化器，但现在也运行在共享的非隔离运行器上。
- 每个 `pnpm test` 分片都继承共享 Vitest 配置中相同的 `threads` + `isolate: false` 默认值。
- 共享的 `scripts/run-vitest.mjs` 启动器现在还会默认为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间 V8 编译抖动。如果你需要与原生 V8 行为比较，可设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1`。
- 根 UI 通道保留其 `jsdom` setup 和优化器，但现在也运行在共享的非隔离运行器上。
- 每个 `pnpm test` 分片都从共享 Vitest 配置继承相同的 `threads` + `isolate: false` 默认值。
- 共享的 `scripts/run-vitest.mjs` 启动器现在默认还会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。如果你需要对比原始 V8 行为，可设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1`。
- 本地快速迭代说明：
- 当变更路径能清晰映射到更小的套件时，`pnpm test:changed` 会通过分域通道运行。
- 当改动路径可以清晰映射到较小测试套件时，`pnpm test:changed` 会通过作用域化通道运行。
- `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的路由行为，只是使用更高的工作进程上限。
- 本地工作进程自动缩放现在刻意更保守，并且在宿主机平均负载已较高时也会回退，因此默认情况下多个并发 Vitest 运行的破坏性更小。
- 基础 Vitest 配置将这些项目 / 配置文件标记为 `forceRerunTriggers`，从而在测试接线发生变化时保证 changed 模式重跑仍然正确。
- 配置在受支持宿主机上保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你想为直接性能分析指定一个明确缓存位置，可设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。
- 本地工作进程自动缩放现在有意更保守，而且当主机负载平均值已经较高时也会回退，因此默认情况下多个并发 Vitest 运行造成的影响更小。
- 基础 Vitest 配置将项目 / 配置文件标记为 `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:changed:bench -- --ref <git-ref>` 会把路由后的 `test:changed` 与该已提交 diff 的原生根项目路径做对比，并输出总耗时以及 macOS 最大 RSS。
- `pnpm test:perf:changed:bench -- --worktree` 会通过将当前脏工作树中的变更文件列表路由到 `scripts/test-projects.mjs` 和根 Vitest 配置，对其进行基准测试。
- `pnpm test:perf:profile:main` 会为 Vitest / Vite 启动和转换开销写出主线程 CPU profile。
- `pnpm test:perf:profile:runner` 会在关闭文件并行的情况下，为单元测试套件写出运行器 CPU + 堆 profile。
- `pnpm test:perf:imports:changed` 会将同样的性能分析视图限定到自 `origin/main` 以来变更的文件。
- `pnpm test:perf:changed:bench -- --ref <git-ref>` 会针对该已提交 diff，比对已路由的 `test:changed` 与原生根项目路径，并打印总耗时和 macOS 最大 RSS。
- `pnpm test:perf:changed:bench -- --worktree` 会将当前未提交工作树中的变更文件列表通过 `scripts/test-projects.mjs` 和根 Vitest 配置进行路由，并执行基准测试。
- `pnpm test:perf:profile:main` 会为 Vitest / Vite 启动与转换开销写出主线程 CPU profile。
- `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为单元测试套件写出运行器 CPU + 堆 profile。
### E2E（Gateway 网关冒烟测试）
### E2E（Gateway 网关冒烟）
- 命令：`pnpm test:e2e`
- 配置：`vitest.e2e.config.ts`
- 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`
- 运行时默认值：
- 使用 Vitest `threads` 和 `isolate: false`，与仓库其余部分一致。
- 使用 Vitest `threads` 与 `isolate: false`，与仓库其余部分保持一致。
- 使用自适应工作进程（CI：最多 2 个，本地：默认 1 个）。
- 默认以静默模式运行，以减少控制台 I/O 开销。
- 常用覆盖项：
- `OPENCLAW_E2E_WORKERS=<n>` 强制指定工作进程数（上限为 16）。
- `OPENCLAW_E2E_WORKERS=<n>` 强制设置工作进程数（上限为 16）。
- `OPENCLAW_E2E_VERBOSE=1` 重新启用详细控制台输出。
- 范围：
- 多实例 Gateway 网关端到端行为
- WebSocket / HTTP 接口、节点配对和更重的网络行为
- WebSocket / HTTP 接口、节点配对和更重的网络交互
- 预期：
- 在 CI 中运行（当流水线启用时）
- 不需要真实密钥
- 比单元测试包含更多可变因素（可能更慢）
### E2E：OpenShell 后端冒烟测试
### E2E：OpenShell 后端冒烟
- 命令：`pnpm test:e2e:openshell`
- 文件：`test/openshell-sandbox.e2e.test.ts`
- 范围：
- 通过 Docker 在宿主机上启动一个隔离的 OpenShell Gateway 网关
- 从一个临时本地 Dockerfile 创建沙箱
- 通过真实的 `sandbox ssh-config` + SSH exec 运行 OpenClaw 的 OpenShell 后端
- 通过沙箱文件系统桥验证远程规范文件系统行为
- 通过 Docker 在主机上启动一个隔离的 OpenShell Gateway 网关
- 从临时本地 Dockerfile 创建一个沙箱
- 通过真实的 `sandbox ssh-config` + SSH 执行来验证 OpenClaw 的 OpenShell 后端
- 通过沙箱文件系统桥验证远端规范化文件系统行为
- 预期：
- 仅限选择加入；不属于默认的 `pnpm test:e2e` 运行范围
- 仅按需启用；不属于默认 `pnpm test:e2e` 运行的一部分
- 需要本地 `openshell` CLI 和可用的 Docker daemon
- 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 Gateway 网关和沙箱
- 常用覆盖项：
- `OPENCLAW_E2E_OPENSHELL=1` 在手动运行更广泛的 e2e 套件时启用该测试
- `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 指向非默认的 CLI 二进制文件或包装脚本
- `OPENCLAW_E2E_OPENSHELL=1` 在手动运行更广泛 e2e 测试套件时启用此测试
- `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 指向非默认 CLI 二进制文件或包装脚本
### 实时测试（真实提供商 + 真实模型）
### 实时（真实提供商 + 真实模型）
- 命令：`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` 为实时测试单独覆盖；测试会在遇到速率限制响应时重试。
- 优先运行缩小范围后的子集，而不是“全部”
- 实时运行会读取 `~/.profile` 来获取缺失的 API 密钥。
- 默认情况下，实时运行仍会隔离 `HOME`，并将配置 / 鉴权材料复制到临时测试 home 中，这样单元测试 fixture 就不会修改你真实的 `~/.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` 进行每次实时测试覆盖；测试会在收到速率限制响应时重试。
- 进度 / 心跳输出：
- 实时套件现在会将进度行输出到 stderr，因此即使 Vitest 控制台捕获处于安静模式，长时间的提供商调用也能明显显示为活跃状态。
- 实时测试套件现在会将进度行输出到 stderr，因此即使 Vitest 控制台捕获处于安静模式，长时间提供商调用期间也能看见它仍在活动。
- `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，因此提供商 / Gateway 网关进度行会在实时运行期间立即流式输出。
- 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型心跳。
- 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 Gateway 网关 / 探测心跳。
- 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型调用的心跳间隔。
- 使用 `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`
- 调试“我的机器人挂了” / 提供商特定故障 / 工具调用：运行缩小范围的 `pnpm test:live`
## 实时测试：Android 节点能力扫描
## 实时：Android 节点能力扫描
- 测试：`src/gateway/android-node.capabilities.live.test.ts`
- 脚本：`pnpm android:test:integration`
- 目标：调用已连接 Android 节点当前公布的**每一条命令**，并断言命令契约行为。
- 目标：调用已连接 Android 节点当前**宣告的每一个命令**，并断言命令契约行为。
- 范围：
- 带前置条件的 / 手动设置（该测试套件不会安装 / 运行 / 配对应用）。
- 针对所选 Android 节点逐条命令进行 Gateway 网关 `node.invoke` 校验。
- 依赖前置 / 手动设置（该测试套件不会安装 / 运行 / 配对应用）。
- 针对所选 Android 节点，逐命令验证 Gateway 网关 `node.invoke`。
- 必需的预先设置：
- Android 应用已连接并与 Gateway 网关完成配对。
- Android 应用已经连接并与 Gateway 网关配对。
- 应用保持在前台。
- 已为你期望通过的能力授予权限 / 捕获同意。
- 可选目标覆盖项：
- 你期望通过的能力所需权限 / 捕获授权已授予。
- 可选目标覆盖：
- `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 密钥）
## 实时：模型冒烟（profile 密钥）
实时测试分为两层，这样我们就能隔离故障：
实时测试分为两层，这样我们可以隔离故障：
- “直接模型”告诉我们，提供商 / 模型在给定密钥下是否至少能够响应。
- “Gateway 网关冒烟测试”告诉我们，完整的 Gateway 网关 + 智能体流水线是否对该模型正常工作（会话、历史记录、工具、沙箱策略等）。
- “直接模型”告诉我们，给定密钥下该提供商 / 模型是否至少能响应。
- “Gateway 网关冒烟”告诉我们，该模型的完整 Gateway 网关 + 智能体流水线是否正常工作（会话、历史、工具、沙箱策略等）。
### 第 1 层：直接模型补全（无 Gateway 网关）
- 测试：`src/agents/models.profiles.live.test.ts`
- 目标：
- 枚举发现到的模型
- 枚举已发现的模型
- 使用 `getApiKeyForModel` 选择你拥有凭证的模型
- 为每个模型运行一次小型补全（并在需要时运行定向回归测试）
- 启用方式：
- 对每个模型运行一个小型补全（以及需要时的定向回归测试）
- 如何启用：
- `pnpm test:live`（或直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`）
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）才会真正运行该测试套件；否则它会跳过，以便让 `pnpm test:live` 继续聚焦 Gateway 网关冒烟测试
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）才会实际运行此测试套件；否则它会跳过，以便让 `pnpm test:live` 继续聚焦于 Gateway 网关冒烟
- 如何选择模型：
- `OPENCLAW_LIVE_MODELS=modern` 运行 modern allowlist（Opus / Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_MODELS=all` 是 modern allowlist 的别名
- 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（逗号分隔的 allowlist）
- modern / all 扫描默认有一个精心挑选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可执行完整的 modern 扫描，或设置为正数以使用更小的上限。
- modern / all 扫描默认带有一个精心挑选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可执行穷尽式 modern 扫描，或设置正数以使用更小的上限。
- 如何选择提供商：
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔的 allowlist）
- 密钥来源：
- 密钥来自哪里：
- 默认：profile 存储和环境变量回退
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅使用 profile 存储**
- 为什么需要它：
- 将“提供商 API 出故障 / 密钥无效”和“Gateway 网关智能体流水线出故障”分离开来
- 容纳小型、隔离的回归测试（例如：OpenAI Responses / Codex Responses 推理重放 + 工具调用流程）
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**只使用 profile 存储**
- 存在原因：
- 将“提供商 API 坏了 / 密钥无效”与“Gateway 网关智能体流水线坏了”区分开
- 容纳小型、隔离的回归测试（例如：OpenAI Responses / Codex Responses 推理回放 + 工具调用流程）
### 第 2 层：Gateway 网关 + 开发智能体冒烟测试（也就是 “@openclaw” 实际做的事）
### 第 2 层：Gateway 网关 + 开发智能体冒烟（也就是 “@openclaw” 实际做的事）
- 测试：`src/gateway/gateway-models.profiles.live.test.ts`
- 目标：
- 启动一个进程内 Gateway 网关
- 创建 / 修补一个 `agent:dev:*` 会话（每次运行覆盖模型）
- 遍历带密钥的模型并断言：
- “有意义的”回复（不使用工具）
- 一次真实工具调用可正常工作（read 探测）
- “有意义”的响应（无工具）
- 一次真实工具调用可以成功（read 探测）
- 可选的额外工具探测（exec+read 探测）
- OpenAI 回归路径（仅工具调用 → 后续跟进）持续可用
- 探测细节（这样你可以快速解释失败）：
- `read` 探测：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 该文件并回显 nonce。
- OpenAI 回归路径（仅工具调用 → 后续跟进）仍然正常
- 探测细节（这样你可以快速解释故障）：
- `read` 探测：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 它并回显该 nonce。
- `exec+read` 探测：测试要求智能体通过 `exec` 将 nonce 写入一个临时文件，然后再 `read` 回来。
- 图像探测：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat <CODE>`。
- 图像探测：测试附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat <CODE>`。
- 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。
- 启用方式：
- 如何启用：
- `pnpm test:live`（或直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`）
- 如何选择模型：
- 默认：modern allowlist（Opus / Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是 modern allowlist 的别名
- 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）来缩小范围
- modern / all Gateway 网关扫描默认有一个精心挑选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可执行完整的 modern 扫描，或设置为正数以使用更小的上限。
- 如何选择提供商（避免“OpenRouter 全量”）：
- modern / all Gateway 网关扫描默认带有一个精心挑选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可执行穷尽式 modern 扫描，或设置正数以使用更小的上限。
- 如何选择提供商（避免“OpenRouter 全都测”）：
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔的 allowlist）
- 工具 + 图像探测在该实时测试中始终开启：
- 工具 + 图像探测在这个实时测试中始终开启：
- `read` 探测 + `exec+read` 探测（工具压力测试）
- 当模型声明支持图像输入时，会运行图像探测
- 流程（高层）：
- 当模型宣告支持图像输入时，会运行图像探测
- 流程（高层级）：
- 测试生成一个带有 “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`）
- 嵌入式智能体将多模态用户消息转发给模型
- 断言：回复包含 `cat` + 该代码（OCR 容错：允许轻微错误）
提示：如果你想查看你机器上可测试的内容（以及精确的 `provider/model` id），运行：
提示：如果你想查看本机可测试的内容（以及精确的 `provider/model` id），请运行：
```bash
openclaw models list
openclaw models list --json
```
## 实时测试：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI）
## 实时：CLI 后端冒烟（Claude、Codex、Gemini 或其他本地 CLI）
- 测试：`src/gateway/gateway-cli-backend.live.test.ts`
- 目标：在不触碰你的默认配置的前提下，使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线。
- 后端专属的冒烟测试默认值与所属扩展的 `cli-backend.ts` 定义一起维护。
- 目标：在不触碰默认配置的情况下，使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线。
- 后端特定的冒烟默认值位于所属扩展的 `cli-backend.ts` 定义中。
- 启用：
- `pnpm test:live`（或直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`）
- `OPENCLAW_LIVE_CLI_BACKEND=1`
@ -296,11 +295,11 @@ openclaw models list --json
- `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_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` 发送第二轮消息并验证恢复流程。
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` 禁用默认的 Claude Sonnet -> Opus 同会话连续性探测（当所选模型支持切换目标时，设置为 `1` 可强制启用）。
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` 禁用默认的 Claude Sonnet -> Opus 同会话连续性探测（当所选模型支持切换目标时，设置为 `1` 可强制开启）。
示例：
@ -328,27 +327,27 @@ pnpm test:docker:live-cli-backend:gemini
说明：
- Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。
- 它会在仓库 Docker 镜像中以非 root 的 `node` 用户身份运行实时 CLI 后端冒烟测试。
- 它会从所属扩展解析 CLI 冒烟测试元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到一个可写的缓存前缀 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 中（默认：`~/.cache/openclaw/docker-cli-tools`）。
- `pnpm test:docker:live-cli-backend:claude-subscription` 需要可移植的 Claude Code 订阅 OAuth，可通过带有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供。它会先在 Docker 中验证直接 `claude -p`，然后在不保留 Anthropic API 密钥环境变量的情况下运行两轮 Gateway 网关 CLI 后端测试。这个订阅通道默认会禁用 Claude MCP / 工具和图像探测，因为 Claude 当前会将第三方应用使用量路由到额外使用计费，而不是普通订阅套餐限制。
- 实时 CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮次、图像分类轮次，然后通过 Gateway 网关 CLI 验证 MCP `cron` 工具调用。
- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍记得之前的备注。
- 它会在仓库 Docker 镜像中以非 root 的 `node` 用户运行实时 CLI 后端冒烟测试。
- 它会从所属扩展解析 CLI 冒烟元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到可缓存、可写的前缀 `OPENCLAW_DOCKER_CLI_TOOLS_DIR`（默认：`~/.cache/openclaw/docker-cli-tools`）。
- `pnpm test:docker:live-cli-backend:claude-subscription` 要求通过以下任一方式提供可移植的 Claude Code 订阅 OAuth：带有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN`。它会先在 Docker 中验证直接 `claude -p`，然后在不保留 Anthropic API 密钥环境变量的情况下运行两轮 Gateway 网关 CLI 后端测试。这个订阅通道默认禁用 Claude MCP / 工具和图像探测，因为 Claude 目前会将第三方应用使用计入额外用量计费，而不是普通订阅套餐额度。
- 现在，实时 CLI 后端冒烟测试会对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮次、图像分类轮次，然后通过 Gateway 网关 CLI 验证 MCP `cron` 工具调用。
- Claude 的默认冒烟测试还会将会话从 Sonnet 修补到 Opus，并验证恢复后的会话仍记得先前记录的笔记。
## 实时测试：ACP 绑定冒烟测试（`/acp spawn ... --bind here`）
## 实时：ACP 绑定冒烟（`/acp spawn ... --bind here`）
- 测试：`src/gateway/gateway-acp-bind.live.test.ts`
- 目标：使用一个实时 ACP 智能体验证真实的 ACP 会话绑定流程：
- 目标：使用实时 ACP 智能体验证真实 ACP 会话绑定流程：
- 发送 `/acp spawn <agent> --bind here`
- 就地绑定一个合成的消息渠道会话
- 在同一会话上发送一条普通后续消息
- 验证后续消息落入已绑定的 ACP 会话转录中
- 验证该后续消息落入已绑定 ACP 会话的转录中
- 启用：
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
- `OPENCLAW_LIVE_ACP_BIND=1`
- 默认值：
- Docker 中的 ACP 智能体：`claude,codex,gemini`
- 直接 `pnpm test:live ...` 使用的 ACP 智能体：`claude`
- 合成渠道：Slack 私信风格会话上下文
- 合成渠道：Slack 私信风格的会话上下文
- ACP 后端：`acpx`
- 覆盖项：
- `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
@ -357,8 +356,8 @@ pnpm test:docker:live-cli-backend:gemini
- `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini`
- `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@<version>'`
- 说明：
- 该通道使用 Gateway 网关 `chat.send` 接口，并带有仅管理员可用的合成来源路由字段，这样测试就能附加消息渠道上下文，而无需假装真的对外投递。
- 当 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 未设置时，测试会使用内置 `acpx` 插件中针对所选 ACP harness 智能体的内建智能体注册表。
- 这个通道使用 Gateway 网关 `chat.send` 接口和仅管理员可用的合成来源路由字段，以便测试能附加消息渠道上下文，而无需假装进行外部投递。
- 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用内置 `acpx` 插件中针对所选 ACP harness 智能体的内建智能体注册表。
示例：
@ -387,24 +386,25 @@ Docker 说明：
- Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。
- 默认情况下，它会按顺序对所有受支持的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后 `gemini`。
- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 可缩小矩阵范围。
- 它会加载 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，把 `acpx` 安装到可写 npm 前缀中，然后在缺失时安装所请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。
- 在 Docker 内部，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，这样 acpx 就能让从 profile 加载到的提供商环境变量继续对其子 harness CLI 可用。
- 它会读取 `~/.profile`，将匹配的 CLI 鉴权材料暂存到容器中，把 `acpx` 安装到可写 npm 前缀中，然后在缺失时安装所请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。
- 在 Docker 内部，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，这样 acpx 就能让从 profile 读取的提供商环境变量继续对其子 harness CLI 可用。
## 实时测试：Codex app-server harness 冒烟测试
## 实时：Codex app-server harness 冒烟
- 目标：通过常规 Gateway 网关
`agent` 方法验证插件自有的 Codex harness：
- 加载内置 `codex` 插件
- 目标：通过正常的 Gateway 网关 `agent` 方法验证插件自有的 Codex harness：
- 加载内置的 `codex` 插件
- 选择 `OPENCLAW_AGENT_RUNTIME=codex`
- 向 `codex/gpt-5.4` 发送第一轮 Gateway 网关智能体消息
- 向同一个 OpenClaw 会话发送第二轮消息，并验证 app-server
线程能够恢复
线程可以恢复
- 测试：`src/gateway/gateway-codex-harness.live.test.ts`
- 启用：`OPENCLAW_LIVE_CODEX_HARNESS=1`
- 默认模型：`codex/gpt-5.4`
- 可选图像探测：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- 可选 MCP / 工具探测：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
- 认证：来自 shell / profile 的 `OPENAI_API_KEY`，以及可选复制的
- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，因此损坏的 Codex
harness 不能通过静默回退到 PI 而误判为通过。
- 鉴权：来自 shell / profile 的 `OPENAI_API_KEY`，以及可选复制的
`~/.codex/auth.json` 和 `~/.codex/config.toml`
本地配方：
@ -428,21 +428,20 @@ pnpm test:docker:live-codex-harness
Docker 说明：
- Docker 运行器位于 `scripts/test-live-codex-harness-docker.sh`。
- 它会加载挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI
认证文件，将 `@openai/codex` 安装到一个可写的挂载 npm
前缀中，暂存源代码树，然后仅运行 Codex harness 实时测试。
- Docker 默认启用图像和 MCP / 工具探测。若你需要更窄的调试运行，可设置
- 它会读取挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI
鉴权文件，将 `@openai/codex` 安装到可写的挂载 npm 前缀中，暂存源码树，然后只运行 Codex harness 实时测试。
- Docker 默认启用图像和 MCP / 工具探测。当你需要更窄范围的调试运行时，设置
`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或
`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`。
### 推荐的实时测试配方
范围收窄、显式的 allowlist 是最快且最不易出问题的：
范围明确、allowlist 收窄的运行方式最快，也最不容易出现不稳定问题：
- 单个模型，直接测试（无 Gateway 网关）：
- 单模型，直接运行（无 Gateway 网关）：
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts`
- 单个模型，Gateway 网关冒烟测试：
- 单模型，Gateway 网关冒烟：
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- 跨多个提供商的工具调用：
@ -455,29 +454,29 @@ Docker 说明：
说明：
- `google/...` 使用 Gemini API（API 密钥）。
- `google-antigravity/...` 使用 Antigravity OAuth bridge（Cloud Code Assist 风格的智能体端点）。
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（单独的认证 + 工具行为差异）。
- `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` 二进制文件；它有自己的认证方式，且行为可能不同（流式传输 / 工具支持 / 版本偏差）。
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / profile 鉴权）；这通常就是大多数用户所说的 “Gemini”。
- CLI：OpenClaw 会 shell out 到本地 `gemini` 二进制；它有自己的鉴权，并且行为可能不同（流式传输 / 工具支持 / 版本偏差）。
## 实时测试：模型矩阵（我们覆盖什么）
## 实时：模型矩阵（我们覆盖哪些内容）
没有固定的“CI 模型列表”（实时测试是可选启用的），但如果你在开发机上有可用密钥，下面这些是**推荐**定期覆盖的模型。
没有固定的“CI 模型列表”（实时测试是按需启用的），但这些是在带有密钥的开发机器上**建议**定期覆盖的模型。
### 现代冒烟测试集（工具调用 + 图像）
### 现代冒烟集（工具调用 + 图像）
这是我们期望持续可用的“常用模型”运行集：
这是我们预期应持续保持正常工作的“常用模型”运行集：
- OpenAI（非 Codex）：`openai/gpt-5.4`（可选：`openai/gpt-5.4-mini`）
- OpenAI Codex：`openai-codex/gpt-5.4`
- Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
- Google（Gemini API）：`google/gemini-3.1-pro-preview` 和 `google/gemini-3-flash-preview`（避免使用较旧的 Gemini 2.x 模型）
- Google（Gemini API）：`google/gemini-3.1-pro-preview` 和 `google/gemini-3-flash-preview`（避免较旧的 Gemini 2.x 模型）
- Google（Antigravity）：`google-antigravity/claude-opus-4-6-thinking` 和 `google-antigravity/gemini-3-flash`
- Z.AI（GLM）：`zai/glm-4.7`
- MiniMax：`minimax/MiniMax-M2.7`
运行带工具 + 图像的 Gateway 网关冒烟测试：
使用工具 + 图像运行 Gateway 网关冒烟：
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
### 基线：工具调用（Read + 可选 Exec）
@ -492,44 +491,44 @@ Docker 说明：
可选的额外覆盖（有则更好）：
- xAI：`xai/grok-4`（或当前最新可用模型）
- xAI：`xai/grok-4`（或最新可用版本）
- Mistral：`mistral/`…（选择一个你已启用、支持工具的模型）
- Cerebras：`cerebras/`…（如果你有权限）
- Cerebras：`cerebras/`…（如果你有访问权限）
- LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式）
### 视觉：图像发送（附件 → 多模态消息）
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude / Gemini / OpenAI 支持视觉的变体等），以执行图像探测。
至少在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中包含一个支持图像的模型（Claude / Gemini / OpenAI 支持视觉的变体等），以覆盖图像探测。
### 聚合器 / 其他 Gateway 网关
### 聚合器 / 替代 Gateway 网关
如果你启用了相应密钥，我们也支持通过以下方式测试：
如果你启用了相应密钥，我们也支持通过以下方式进行测试：
- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选模型）
- OpenCode：`opencode/...` 用于 Zen，`opencode-go/...` 用于 Go（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）
- OpenRouter：`openrouter/...`（数百种模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选模型）
- OpenCode：`opencode/...` 用于 Zen，`opencode-go/...` 用于 Go（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 鉴权）
你还可以在实时测试矩阵中加入更多提供商（如果你有凭证 / 配置）：
如果你有凭证 / 配置，也可以将更多提供商加入实时矩阵：
- 内置：`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 等）
提示：不要尝试在文档中硬编码“所有模型”。权威列表是你机器上的 `discoverModels(...)` 返回结果，以及当前可用的密钥。
提示：不要试图在文档里硬编码“所有模型”。权威列表应以你机器上 `discoverModels(...)` 返回的结果以及当前可用密钥为准。
## 凭证（绝不要提交）
## 凭证（切勿提交）
实时测试发现凭证的方式与 CLI 相同。实际含义如下：
- 如果 CLI 可用，实时测试通常也应该能找到相同的密钥。
- 如果某个实时测试提示 “no creds”，请像调试 `openclaw models list` / 模型选择那样调试它。
- 如果 CLI 可以工作，实时测试应能找到相同的密钥。
- 如果实时测试提示“无凭证”，请像调试 `openclaw models list` / 模型选择那样去调试。
- 每个智能体的认证 profile：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试里 “profile keys” 的含义）
- 按智能体划分的鉴权 profile：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试里 “profile keys” 的含义）
- 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时测试 home 中，但它不是主要的 profile-key 存储）
- 本地实时运行默认会将当前活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/`，以及受支持的外部 CLI 认证目录复制到临时测试 home 中；暂存的实时测试 home 会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖项，以确保探测不会落到你真实的宿主工作区上。
- 旧版状态目录：`~/.openclaw/credentials/`（如果存在，会复制到暂存的实时测试 home 中，但它不是主 profile 密钥存储）
- 默认情况下，本地实时运行会把活动配置、各智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 鉴权目录复制到临时测试 home 中；暂存的实时 home 会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，这样探测就不会落到你真实主机工作区上。
如果你想依赖环境变量中的密钥（例如在 `~/.profile` 中导出），请在本地测试前运行 `source ~/.profile`，或使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载进容器）。
如果你想依赖环境变量密钥（例如在你的 `~/.profile` 中导出的密钥），请在本地测试前运行 `source ~/.profile`，或使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。
## Deepgram 实时测试（音频转录）
## Deepgram 实时（音频转录）
- 测试：`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`
@ -547,7 +546,7 @@ Docker 说明：
- 范围：
- 覆盖内置 comfy 图像、视频和 `music_generate` 路径
- 除非配置了 `models.providers.comfy.<capability>`，否则会跳过各项能力
- 在修改 comfy 工作流提交、轮询、下载或插件注册后尤其有用
- 在修改 comfy 工作流提交、轮询、下载或插件注册后特别有用
## 图像生成实时测试
@ -555,10 +554,10 @@ Docker 说明：
- 命令：`pnpm test:live src/image-generation/runtime.live.test.ts`
- Harness：`pnpm test:live:media image`
- 范围：
- 枚举每个已注册的图像生成提供商插件
- 枚举每一个已注册的图像生成提供商插件
- 在探测前从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过时的测试密钥不会掩盖真实 shell 凭证
- 跳过没有可用认证 / profile / 模型的提供商
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的鉴权 profile，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
- 跳过没有可用鉴权 / profile / 模型的提供商
- 通过共享运行时能力运行标准图像生成变体：
- `google:flash-generate`
- `google:pro-generate`
@ -567,12 +566,12 @@ Docker 说明：
- 当前覆盖的内置提供商：
- `openai`
- `google`
- 可选范围收窄：
- 可选缩小范围：
- `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"`
- `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 存储鉴权，并忽略仅环境变量的覆盖
## 音乐生成实时测试
@ -583,20 +582,22 @@ Docker 说明：
- 覆盖共享的内置音乐生成提供商路径
- 当前覆盖 Google 和 MiniMax
- 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过时的测试密钥不会掩盖真实 shell 凭证
- 跳过没有可用认证 / profile / 模型的提供商
- 在可用时运行两种声明的运行时模式：
- `generate`：仅提示词输入
- `edit`：当提供商声明 `capabilities.edit.enabled` 时
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的鉴权 profile，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
- 跳过没有可用鉴权 / profile / 模型的提供商
- 在可用时运行两种已声明的运行时模式：
- `generate`，仅使用提示词输入
- 当提供商声明 `capabilities.edit.enabled` 时运行 `edit`
- 当前共享通道覆盖：
- `google`：`generate`、`edit`
- `minimax`：`generate`
- `comfy`：单独的 Comfy 实时测试文件，不在这个共享扫描中
- 可选范围收窄：
- `comfy`：单独的 Comfy 实时测试文件，不属于这个共享扫描
- 可选缩小范围：
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"`
- 可选认证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用 profile 存储认证，并忽略仅来自环境变量的覆盖
- 可选鉴权行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用 profile 存储鉴权，并忽略仅环境变量的覆盖
## 视频生成实时测试
## 视频生成实时测试
@ -606,36 +607,36 @@ Docker 说明：
- 范围：
- 覆盖共享的内置视频生成提供商路径
- 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过时的测试密钥不会掩盖真实 shell 凭证
- 跳过没有可用认证 / profile / 模型的提供商
- 在可用时运行两种声明的运行时模式：
- `generate`：仅提示词输入
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的鉴权 profile，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
- 跳过没有可用鉴权 / profile / 模型的提供商
- 在可用时运行两种已声明的运行时模式：
- `generate`，仅使用提示词输入
- 当提供商声明 `capabilities.imageToVideo.enabled`，且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地图像输入时，运行 `imageToVideo`
- 当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地视频输入时，运行 `videoToVideo`
- 当前在共享扫描中已声明但跳过的 `imageToVideo` 提供商：
- 当前在共享扫描中已声明但被跳过的 `imageToVideo` 提供商：
- `vydra`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL
- 提供商专属的 Vydra 覆盖：
- 提供商特定的 Vydra 覆盖：
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
- 该文件会运行 `veo3` 文本转视频，以及一个默认使用远程图像 URL 夹具的 `kling` 通道
- 当前 `videoToVideo` 实时测试覆盖：
- 仅 `runway`，且所选模型为 `runway/gen4_aleph` 时
- 当前在共享扫描中已声明但跳过的 `videoToVideo` 提供商：
- 该文件默认运行 `veo3` 文本转视频，以及一个使用远程图像 URL fixture 的 `kling` 通道
- 当前 `videoToVideo` 实时覆盖：
- 仅 `runway`，并且仅当所选模型是 `runway/gen4_aleph`
- 当前在共享扫描中已声明但被跳过的 `videoToVideo` 提供商：
- `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 参考 URL
- `google`，因为当前共享的 Gemini / Veo 通道使用基于本地 buffer 的输入，而该路径在共享扫描中不被接受
- `openai`，因为当前共享通道无法保证组织专属的视频修补 / remix 访问权限
- 可选范围收窄：
- `google`，因为当前共享 Gemini / Veo 通道使用基于本地 buffer 的输入，而该路径在共享扫描中不被接受
- `openai`，因为当前共享通道缺少组织特定的视频修补 / remix 访问保证
- 可选缩小范围：
- `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
- 可选认证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用 profile 存储认证，并忽略仅来自环境变量的覆盖
- 可选鉴权行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用 profile 存储鉴权，并忽略仅环境变量的覆盖
## 媒体实时测试 Harness
## 媒体实时 Harness
- 命令：`pnpm test:live:media`
- 目的：
- 通过一个仓库原生入口点运行共享的图像、音乐和视频实时测试套件
- 通过一个仓库原生入口运行共享的图像、音乐和视频实时测试套件
- 自动从 `~/.profile` 加载缺失的提供商环境变量
- 默认自动将每个测试套件范围收窄到当前拥有可用认证的提供商
- 默认自动将每个测试套件缩小到当前具有可用鉴权的提供商
- 复用 `scripts/test-live.mjs`，因此心跳和安静模式行为保持一致
- 示例：
- `pnpm test:live:media`
@ -645,120 +646,122 @@ Docker 说明：
## 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 扫描仍然可行：
- 实时模型运行器：`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 扫描仍然切实可行：
`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 通道中复用该镜像。
`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` 会启动一个或多个真实容器，并验证更高层级的集成路径。
这些实时模型 Docker 运行器还会仅 bind-mount 所需的 CLI 认证 home（或在未缩小范围时挂载所有受支持的认证 home），然后在运行前将其复制到容器 home 中，以便外部 CLI OAuth 能刷新令牌而不修改宿主认证存储：
实时模型 Docker 运行器还会只 bind-mount 必需的 CLI 鉴权 home（如果运行未缩小范围，则挂载所有受支持的鉴权 home），然后在运行前将其复制到容器 home 中，这样外部 CLI OAuth 就可以刷新令牌，而不会修改宿主机上的鉴权存储：
- 直接模型：`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`）
- Codex app-server harness 冒烟测试：`pnpm test:docker:live-codex-harness`（脚本：`scripts/test-live-codex-harness-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`）
- Codex app-server harness 冒烟：`pnpm test:docker:live-codex-harness`（脚本：`scripts/test-live-codex-harness-docker.sh`）
- Gateway 网关 + 开发智能体：`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 实时冒烟：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`）
- 新手引导向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`）
- Gateway 网关网络（两个容器，WS 认证 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`）
- MCP 渠道桥接（带种子数据的 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟测试）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`）
- 渠道插件（安装冒烟测试 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`）
- Gateway 网关网络（两个容器，WS 鉴权 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`）
- MCP 渠道桥接（带种子数据的 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟）：`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 当前 checkout，并将其暂存到容器内部的临时 workdir 中。这样既能保持运行时镜像精简，又仍然可以针对你精确的本地源码 / 配置运行 Vitest。
暂存步骤会跳过大型仅本地缓存和应用构建输出，例如
`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地的 `.build` 或
Gradle 输出目录，这样 Docker 实时运行就不会花上几分钟去复制
机器专属产物。
实时模型 Docker 运行器还会以只读方式 bind-mount 当前 checkout，
并把它暂存到容器内的临时工作目录中。这样可以保持运行时镜像精简，
同时仍然针对你精确的本地源码 / 配置运行 Vitest。
该暂存步骤会跳过大型本地专用缓存和应用构建输出，例如
`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地 `.build` 或
Gradle 输出目录，因此 Docker 实时运行不会花上几分钟复制
机器特定的产物。
它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 Gateway 网关实时探测就不会在容器内启动
真实的 Telegram / Discord / 等渠道工作进程。
`test:docker:live-models` 仍然运行 `pnpm test:live`，因此当你需要缩小范围或从该 Docker 通道中排除 Gateway 网关实时覆盖时，也请一并传入
`test:docker:live-models` 仍然运行 `pnpm test:live`，因此当你需要缩小范围或排除该 Docker 通道中的 Gateway 网关
实时覆盖时，也请一并传入
`OPENCLAW_LIVE_GATEWAY_*`。
`test:docker:openwebui` 是一个更高层级的兼容性冒烟测试：它会启动一个
启用了 OpenAI 兼容 HTTP 端点的 OpenClaw Gateway 网关容器，启动一个固定版本的 Open WebUI 容器并将其指向该 Gateway 网关，通过
Open WebUI 完成登录，验证 `/api/models` 暴露出 `openclaw/default`，然后通过
Open WebUI 的 `/api/chat/completions` 代理发送一条真实聊天请求。
首次运行可能会明显更慢，因为 Docker 可能需要拉取
Open WebUI 镜像，而 Open WebUI 也可能需要完成自身的冷启动设置。
该通道需要一个可用的实时模型密钥，而 `OPENCLAW_PROFILE_FILE`
（默认是 `~/.profile`）是在 Docker 化运行中提供它的主要方式。
`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 可能需要完成自身的冷启动设置。
这个通道需要可用的实时模型密钥，而 `OPENCLAW_PROFILE_FILE`
（默认 `~/.profile`）是在 Docker 化运行中提供它的主要方式。
成功运行会打印一个小型 JSON 载荷，例如 `{ "ok": true, "model":
"openclaw/default", ... }`。
`test:docker:mcp-channels` 刻意设计为确定性运行，不需要
`test:docker:mcp-channels` 是有意保持确定性的，不需要
真实的 Telegram、Discord 或 iMessage 账号。它会启动一个带种子数据的 Gateway 网关
容器，再启动第二个容器来运行 `openclaw mcp serve`，然后
容器，启动第二个容器来运行 `openclaw mcp serve`，然后
验证路由后的会话发现、转录读取、附件元数据、
实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 +
权限通知，这些都通过真实的 stdio MCP bridge 完成。通知检查
会直接检查原始 stdio MCP 帧，因此该冒烟测试验证的是 bridge 实际发出的内容，
而不仅仅是某个特定客户端 SDK 恰好暴露出来的内容。
实时事件队列行为、出站发送路由，以及通过真实 stdio MCP bridge 发送的 Claude 风格渠道 +
权限通知。该通知检查会直接检查原始 stdio MCP 帧，
因此这个冒烟测试验证的是 bridge 实际发出的内容，
而不仅仅是某个特定客户端 SDK 恰好暴露出的内容。
手动 ACP 平实语言线程冒烟测试（非 CI）：
手动 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 安装使用
- `$HOME` 下的外部 CLI 认证目录 / 文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...`
- `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 安装
- `$HOME` 下的外部 CLI 鉴权目录 / 文件会以只读方式挂载到 `/host-auth...`，然后在测试开始前复制到 `/home/node/...`
- 默认目录：`.minimax`
- 默认文件：`~/.codex/auth.json`、`~/.codex/config.toml`、`.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_SKIP_DOCKER_BUILD=1` 用于复用现有 `openclaw:local-live` 镜像，以便在无需重建时重新运行
- `OPENCLAW_SKIP_DOCKER_BUILD=1` 复用现有 `openclaw:local-live` 镜像，用于无需重新构建的重跑
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 确保凭证来自 profile 存储（而不是环境变量）
- `OPENCLAW_OPENWEBUI_MODEL=...` 选择 Gateway 网关为 Open WebUI 冒烟测试暴露的模型
- `OPENCLAW_OPENWEBUI_PROMPT=...` 覆盖 Open WebUI 冒烟测试中使用的 nonce 检查提示词
- `OPENWEBUI_IMAGE=...` 覆盖固定的 Open WebUI 镜像标签
- `OPENCLAW_OPENWEBUI_PROMPT=...` 覆盖 Open WebUI 冒烟测试使用的 nonce 校验提示词
- `OPENWEBUI_IMAGE=...` 覆盖固定版本的 Open WebUI 镜像标签
## 文档完整性检查
文档编辑后运行文档检查：`pnpm check:docs`。
当你还需要页内标题检查时，运行完整的 Mintlify anchor 校验：`pnpm docs:check-links:anchors`。
编辑文档后运行文档检查：`pnpm check:docs`。
如果你还需要完整的 Mintlify 锚点校验，包括页内标题检查，请运行：`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`，并强制写入配置 + 认证）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”）
- 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`，强制写入配置 + 鉴权）：`src/gateway/gateway.test.ts`（用例："runs wizard over ws and writes auth token config"）
## 智能体可靠性评估（Skills）
我们已经有一些可在 CI 中安全运行、行为类似“智能体可靠性评估”的测试：
我们已经有一些 CI 安全的测试，它们的行为类似“智能体可靠性评估”：
- 通过真实 Gateway 网关 + 智能体循环进行模拟工具调用（`src/gateway/gateway.test.ts`）。
- 通过真实 Gateway 网关 + 智能体循环执行模拟工具调用（`src/gateway/gateway.test.ts`）。
- 验证会话接线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。
对于 Skills（见 [Skills](/zh-CN/tools/skills)），目前仍缺少的是：
针对 Skills 仍然缺少的内容（见 [Skills](/zh-CN/tools/skills)）：
- **决策能力：** 当 Skills 被列在提示中时，智能体是否会选择正确的 Skills（或避开无关的 Skills）？
- **合规性：** 智能体是否会在使用前读取 `SKILL.md`，并遵循所要求的步骤 / 参数？
- **决策能力：** 当 Skills 列在提示词中时，智能体是否会选择正确的 Skill（或避免选择无关 Skill）？
- **遵循性：** 智能体在使用前是否会读取 `SKILL.md`，并遵循要求的步骤 / 参数？
- **工作流契约：** 断言工具顺序、会话历史延续和沙箱边界的多轮场景。
未来的评估应优先保持确定性：
未来的评估应首先保持确定性：
- 使用模拟提供商的场景运行器，用于断言工具调用 + 顺序、Skills 文件读取和会话接线。
- 一小套面向 Skills 的场景（使用 vs 避免、门禁、提示注入）。
- 仅在 CI 安全套件就位之后，才添加可选的实时评估（选择加入、由环境变量控制）。
- 一个使用模拟提供商的场景运行器，用于断言工具调用 + 顺序、Skill 文件读取和会话接线。
- 一小组聚焦 Skill 的场景（使用 vs 避免、门禁、提示注入）。
- 只有在 CI 安全测试套件就位之后，才加入可选的实时评估（按需启用、由环境变量控制）。
## 契约测试（插件和渠道形状）
契约测试会验证每个已注册的插件和渠道都符合其
接口契约。它们会遍历所有已发现的插件，并运行一组关于形状和行为的断言。默认的 `pnpm test` 单元测试通道会刻意
跳过这些共享接缝和冒烟测试文件；当你修改共享渠道或提供商表面时，
请显式运行这些契约命令。
契约测试会验证每个已注册插件和渠道都符合其接口契约。它们会遍历所有已发现的插件，并运行一组针对形状和行为的断言。默认的 `pnpm test` 单元测试通道会刻意跳过这些共享边界和冒烟文件；当你修改共享渠道或提供商接口时，请显式运行契约测试命令。
### 命令
@ -770,15 +773,15 @@ Open WebUI 镜像，而 Open WebUI 也可能需要完成自身的冷启动设置
位于 `src/channels/plugins/contracts/*.contract.test.ts`：
- **plugin** - 基本插件形状（id、名称、能力）
- **plugin** - 基础插件形状（id、名称、能力）
- **setup** - 设置向导契约
- **session-binding** - 会话绑定行为
- **outbound-payload** - 消息载荷结构
- **inbound** - 入站消息处理
- **actions** - 渠道操作处理器
- **actions** - 渠道动作处理器
- **threading** - 线程 ID 处理
- **directory** - 目录 / roster API
- **group-policy** - 群组策略强制执行
- **group-policy** - 群组策略执行
### 提供商状态契约测试
@ -791,8 +794,8 @@ Open WebUI 镜像，而 Open WebUI 也可能需要完成自身的冷启动设置
位于 `src/plugins/contracts/*.contract.test.ts`：
- **auth** - 认证流程契约
- **auth-choice** - 认证选项 / 选择
- **auth** - 鉴权流程契约
- **auth-choice** - 鉴权选择 / 选择逻辑
- **catalog** - 模型目录 API
- **discovery** - 插件发现
- **loader** - 插件加载
@ -802,21 +805,21 @@ Open WebUI 镜像，而 Open WebUI 也可能需要完成自身的冷启动设置
### 何时运行
- 修改 `plugin-sdk` 导出或子路径后
- 添加或修改渠道插件或提供商插件后
- 重构插件注册或发现逻辑后
- 修改 `plugin-sdk` 导出或子路径之后
- 添加或修改渠道插件或提供商插件之后
- 重构插件注册或发现逻辑之后
契约测试会在 CI 中运行，不需要真实 API 密钥。
## 添加回归测试（指导）
## 添加回归测试（指南）
当你修复了一个在实时测试中发现的提供商 / 模型问题时：
当你修复在实时测试中发现的提供商 / 模型问题时：
- 如果可能，添加一个 CI 安全的回归测试（模拟 / 存根提供商，或捕获精确的请求形状转换）
- 如果它天生只能通过实时测试复现（速率限制、认证策略），就让实时测试保持范围收窄，并通过环境变量选择加入
- 优先定位能捕获该缺陷的最小层级：
- 提供商请求转换 / 重放缺陷 → 直接模型测试
- 如果可能，添加一个 CI 安全的回归测试（模拟 / stub 提供商，或捕获精确的请求形状转换）
- 如果它本质上只能通过实时测试覆盖（速率限制、鉴权策略），请让实时测试保持范围狭窄，并通过环境变量按需启用
- 优先锁定能捕获该缺陷的最小层级：
- 提供商请求转换 / 回放缺陷 → 直接模型测试
- Gateway 网关会话 / 历史 / 工具流水线缺陷 → Gateway 网关实时冒烟测试或 CI 安全的 Gateway 网关模拟测试
- SecretRef 遍历防护约束：
- 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 时有意失败，这样新类别就无法被静默跳过。

129
docs/zh-CN/plugins/sdk-agent-harness.md
View File

@ -1,53 +1,53 @@
---
read_when:
- 你正在更改内嵌智能体运行时或 Harness 注册表
- 你正在从内置或受信任插件注册一个智能体 Harness
- 你正在更改嵌入式智能体运行时或 harness 注册表
- 你正在从内置或受信任的插件注册一个智能体 harness
- 你需要了解 Codex 插件与模型提供商之间的关系
sidebarTitle: Agent Harness
summary: 用于替换底层内嵌智能体执行器的插件实验性 SDK 接口层
summary: 用于替换底层嵌入式智能体执行器的实验性插件 SDK 接口
title: 智能体 Harness 插件
x-i18n:
generated_at: "2026-04-10T20:23:47Z"
generated_at: "2026-04-10T20:28:58Z"
model: gpt-5.4
provider: openai
source_hash: ba482dd6a2e4730c2d623b4739e2e6037cec8bb71bf7164b4e9d7ea8e43056d8
source_hash: 3afa7d81ca5a34f40da63e01bb9b42aa10ff8d6f92c2f78bf2588f1a71b5bc0e
source_path: plugins/sdk-agent-harness.md
workflow: 15
---
# 智能体 Harness 插件
**智能体 Harness** 是一个已准备好的 OpenClaw 智能体单次轮转的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。
**智能体 harness** 是一个已准备好的 OpenClaw 智能体单次轮次的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。
仅对内置或受信任的原生插件使用此接口层。该契约仍处于实验阶段，因为参数类型有意映射当前的内嵌运行器。
仅将此接口用于内置或受信任的原生插件。该契约仍处于实验阶段，因为其参数类型有意与当前的嵌入式运行器保持一致。
## 何时使用 Harness
## 何时使用 harness
当某个模型家族拥有自己的原生会话运行时，而常规 OpenClaw 提供商传输抽象并不适用时，请注册一个智能体 Harness。
当某个模型家族拥有自己的原生会话运行时，而常规的 OpenClaw 提供商传输层并不是合适抽象时，请注册一个智能体 harness。
示例：
- 拥有线程和上下文压缩能力的原生 coding-agent 服务器
- 必须流式传输原生计划/推理/工具事件的本地 CLI 或守护进程
- 除了 OpenClaw 会话转录之外，还需要自己的恢复 id 的模型运行时
- 拥有线程和压缩能力的原生编码智能体服务器
- 必须流式传输原生计划 / 推理 / 工具事件的本地 CLI 或守护进程
- 除 OpenClaw 会话转录之外，还需要自身 resume id 的模型运行时
不要仅为了添加一个新的 LLM API 而注册 Harness。对于普通的 HTTP 或 WebSocket 模型 API，请构建一个 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。
不要仅仅为了添加一个新的 LLM API 而注册 harness。对于常规的 HTTP 或 WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。
## 核心仍然负责的内容
## 核心仍负责的内容
在选择 Harness 之前，OpenClaw 已经解析了：
在选择 harness 之前，OpenClaw 已经解析了：
- 提供商和模型
- 运行时凭证状态
- 思考级别和上下文预算
- OpenClaw 转录/会话文件
- 运行时认证状态
- thinking level 和上下文预算
- OpenClaw transcript / session 文件
- 工作区、沙箱和工具策略
- 渠道回复回调和流式回调
- 模型回退和实时模型切换策略
这种拆分是有意设计的。Harness 负责运行一个已准备好的尝试；它不会选择提供商、替换渠道投递，也不会静默切换模型。
这种划分是有意设计的。harness 负责运行一个已准备好的尝试；它不负责选择提供商，不替代渠道投递，也不会静默切换模型。
## 注册 Harness
## 注册 harness
**导入：** `openclaw/plugin-sdk/agent-harness`
@ -85,38 +85,40 @@ export default definePluginEntry({
## 选择策略
OpenClaw 会在提供商/模型解析之后选择 Harness：
OpenClaw 会在提供商 / 模型解析之后选择一个 harness：
1. `OPENCLAW_AGENT_RUNTIME=<id>` 会强制使用具有该 id 的已注册 Harness。
2. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI Harness。
3. `OPENCLAW_AGENT_RUNTIME=auto` 会让已注册的 Harness 查询其是否支持已解析的提供商/模型。
4. 如果没有匹配的已注册 Harness，OpenClaw 会使用 PI。
1. `OPENCLAW_AGENT_RUNTIME=<id>` 会强制使用具有该 id 的已注册 harness。
2. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI harness。
3. `OPENCLAW_AGENT_RUNTIME=auto` 会让已注册的 harness 询问自己是否支持已解析的提供商 / 模型。
4. 如果没有匹配的已注册 harness，OpenClaw 会使用 PI，除非已禁用 PI 回退。
被强制指定的插件 Harness 如果失败，会作为运行失败呈现。在 `auto` 模式下，如果所选插件 Harness 在某次轮转产生副作用之前失败，OpenClaw 可能会回退到 PI。
强制使用插件 harness 时的失败会作为运行失败暴露出来。在 `auto` 模式下，如果所选插件 harness 在某一轮产生副作用之前失败，OpenClaw 可能会回退到 PI。将 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 或 `embeddedHarness.fallback: "none"` 设置为禁用回退，即可让该回退变成硬失败。
内置 Codex 插件将 `codex` 注册为其 Harness id。为兼容起见，当你手动设置 `OPENCLAW_AGENT_RUNTIME` 时，`codex-app-server` 和 `app-server` 也会解析到同一个 Harness。
内置 Codex 插件将 `codex` 注册为其 harness id。为保持兼容性，当你手动设置 `OPENCLAW_AGENT_RUNTIME` 时，`codex-app-server` 和 `app-server` 也会解析到同一个 harness。
## 提供商与 Harness 配对
## 提供商与 harness 配对
大多数 Harness 也应该注册一个提供商。提供商会让模型引用、凭证状态、模型元数据和 `/model` 选择对 OpenClaw 的其余部分可见。然后 Harness 在 `supports(...)` 中声明该提供商。
大多数 harness 也应注册一个提供商。该提供商会将模型引用、认证状态、模型元数据和 `/model` 选择暴露给 OpenClaw 的其余部分。随后，harness 会在 `supports(...)` 中声明该提供商。
内置 Codex 插件遵循这一模式：
- provider id: `codex`
- provider id：`codex`
- 用户模型引用：`codex/gpt-5.4`、`codex/gpt-5.2`，或 Codex app server 返回的其他模型
- harness id: `codex`
- 凭证：合成提供商可用性，因为 Codex Harness 拥有原生 Codex 登录/会话
- app-server 请求：OpenClaw 向 Codex 发送裸模型 id，并让 Harness 与原生 app-server 协议通信
- harness id：`codex`
- 认证：合成提供商可用性，因为 Codex harness 负责原生 Codex 登录 / 会话
- app-server 请求：OpenClaw 会将裸模型 id 发送给 Codex，并让 harness 与原生 app-server 协议通信
Codex 插件是增量性的。普通 `openai/gpt-*` 引用仍然是 OpenAI 提供商引用，并继续使用常规 OpenClaw 提供商路径。当你希望使用由 Codex 管理的凭证、Codex 模型发现、原生线程以及 Codex app-server 执行时，请选择 `codex/gpt-*`。`/model` 可以在 Codex app server 返回的 Codex 模型之间切换，而无需 OpenAI 提供商凭证。
Codex 插件是增量式的。普通的 `openai/gpt-*` 引用仍然是 OpenAI 提供商引用，并继续使用常规的 OpenClaw 提供商路径。当你需要 Codex 管理的认证、Codex 模型发现、原生线程和 Codex app-server 执行时，请选择 `codex/gpt-*`。`/model` 可以在 Codex app server 返回的 Codex 模型之间切换，而无需 OpenAI 提供商凭证。
OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会检查 app-server 初始化握手，并阻止较旧或未带版本信息的服务器，从而确保 OpenClaw 仅在它已测试过的协议接口层上运行。
OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会检查 app-server initialize 握手，并阻止较旧或未标明版本的服务器，以确保 OpenClaw 仅针对其已测试的协议接口运行。
## Harness 选择策略
## 禁用 PI 回退
默认情况下，OpenClaw 运行内嵌智能体时，`agents.defaults.embeddedHarness` 设置为 `{ runtime: "auto", fallback: "pi" }`。在 `auto` 模式下，已注册的插件 Harness 可以声明某个提供商/模型对。如果都不匹配，或者自动选中的插件 Harness 在产生输出之前失败，OpenClaw 会回退到 PI。
默认情况下，OpenClaw 运行嵌入式智能体时，`agents.defaults.embeddedHarness` 设置为 `{ runtime: "auto", fallback: "pi" }`。在 `auto` 模式下，已注册的插件 harness 可以声明某个提供商 / 模型对。如果没有任何匹配项，或者自动选择的插件 harness 在产生输出之前失败，OpenClaw 会回退到 PI。
当你需要证明某个插件 Harness 是唯一被执行的运行时时，请设置 `fallback: "none"`：
当你需要证明插件 harness 是唯一正在运行的运行时时，请设置 `fallback: "none"`。这会禁用自动 PI 回退；但不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。
对于仅使用 Codex 的嵌入式运行：
```json
{
@ -132,6 +134,21 @@ OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会
}
```
如果你希望任何已注册的插件 harness 都能声明匹配的模型，但又不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退：
```json
{
"agents": {
"defaults": {
"embeddedHarness": {
"runtime": "auto",
"fallback": "none"
}
}
}
}
```
按智能体覆盖使用相同的结构：
```json
@ -157,36 +174,46 @@ OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会
}
```
`OPENCLAW_AGENT_RUNTIME` 仍然会覆盖已配置的运行时。使用 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可通过环境变量禁用 PI 回退。
`OPENCLAW_AGENT_RUNTIME` 仍会覆盖已配置的运行时。使用 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可以从环境中禁用 PI 回退。
```bash
OPENCLAW_AGENT_RUNTIME=codex \
OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run
```
禁用回退后，如果所请求的 harness 未注册、不支持已解析的提供商 / 模型，或在产生该轮副作用之前失败，则会话会提前失败。这对于仅使用 Codex 的部署，以及必须证明 Codex app-server 路径确实在使用中的实时测试来说，是有意设计的行为。
此设置仅控制嵌入式智能体 harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商特定的模型路由。
## 原生会话与转录镜像
Harness 可以保留原生 session id、thread id 或守护进程侧恢复 token。请将这种绑定明确关联到 OpenClaw 会话，并继续将用户可见的助手/工具输出镜像到 OpenClaw 转录中。
harness 可以保留原生 session id、thread id 或守护进程侧的 resume token。请将该绑定明确与 OpenClaw 会话关联，并持续将用户可见的 assistant / tool 输出镜像到 OpenClaw transcript 中。
OpenClaw 转录仍然是以下能力的兼容层：
OpenClaw transcript 仍然是以下场景的兼容层：
- 渠道可见的会话历史
- 转录搜索和索引
- 在后续轮转中切换回内置 PI Harness
- 通用 `/new`、`/reset` 和会话删除行为
- transcript 搜索与索引
- 在后续轮次切换回内置 PI harness
- 通用的 `/new`、`/reset` 和会话删除行为
如果你的 Harness 存储了 sidecar 绑定，请实现 `reset(...)`，这样 OpenClaw 才能在所属 OpenClaw 会话重置时清除它。
如果你的 harness 存储了一个 sidecar 绑定，请实现 `reset(...)`，以便 OpenClaw 在所属的 OpenClaw 会话被重置时清除它。
## 工具和媒体结果
核心会构造 OpenClaw 工具列表并将其传入已准备好的尝试中。当 Harness 执行动态工具调用时，请通过 Harness 结果结构返回工具结果，而不是自行发送渠道媒体。
核心会构建 OpenClaw 工具列表，并将其传入已准备好的尝试。当 harness 执行一个动态工具调用时，请通过 harness 结果结构返回工具结果，而不是自行发送渠道媒体。
这样可以让文本、图像、视频、音乐、TTS、审批和消息工具输出与基于 PI 的运行共享同一条投递路径。
这样可以让文本、图像、视频、音乐、TTS、审批和消息工具输出与 PI 支持的运行保持在同一投递路径上。
## 当前限制
- 公共导入路径是通用的，但某些 attempt/result 类型别名仍然保留 `Pi` 名称以保持兼容性。
- 第三方 Harness 安装仍处于实验阶段。在你确实需要原生会话运行时之前，请优先使用提供商插件。
- 支持跨轮转切换 Harness。不要在某次轮转中途切换 Harness，尤其是在原生工具、审批、助手文本或消息发送已经开始之后。
- 公共导入路径是通用的，但某些 attempt / result 类型别名仍带有 `Pi` 命名，以保持兼容性。
- 第三方 harness 安装仍处于实验阶段。在你确实需要原生会话运行时之前，请优先使用提供商插件。
- 支持跨轮次切换 harness。不要在一轮中途、当原生工具、审批、assistant 文本或消息发送已经开始后切换 harness。
## 相关内容
- [SDK 概览](/zh-CN/plugins/sdk-overview)
- [运行时辅助工具](/zh-CN/plugins/sdk-runtime)
- [运行时辅助函数](/zh-CN/plugins/sdk-runtime)
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins)
- [模型提供商](/zh-CN/concepts/model-providers)