From 6ba4e6f8a72cf55f39cfcfd16723af863cc31050 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 10 Apr 2026 21:07:13 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/model-providers.md | 314 ++++++++++++------------ docs/zh-CN/plugins/codex-harness.md | 267 ++++++++++++++++++++ docs/zh-CN/plugins/sdk-agent-harness.md | 111 +++++---- 3 files changed, 481 insertions(+), 211 deletions(-) create mode 100644 docs/zh-CN/plugins/codex-harness.md diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index 57ecdd319..15e09e2bc 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -1,14 +1,14 @@ --- read_when: - - 你需要一份按提供商分类的模型设置参考。 + - 你需要一份按提供商分别说明的模型设置参考。 - 你想要模型提供商的示例配置或 CLI 新手引导命令。 -summary: 模型提供商概览，包含示例配置和 CLI 流程 +summary: 模型提供商概览，附带示例配置 + CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-04-10T20:28:58Z" + generated_at: "2026-04-10T21:05:12Z" model: gpt-5.4 provider: openai - source_hash: fc970eacc8babdd43e3e83f164846b82d1289f8335732d2135dc9f41c560489e + source_hash: 910ea7895e74c03910757d9d3e02825754b779b204eca7275b28422647ed0151 source_path: concepts/model-providers.md workflow: 15 --- @@ -16,116 +16,116 @@ x-i18n: # 模型提供商 本页介绍 **LLM/模型提供商**（不是像 WhatsApp/Telegram 这样的聊天渠道）。 -关于模型选择规则，请参阅 [/concepts/models](/zh-CN/concepts/models)。 +有关模型选择规则，请参见 [/concepts/models](/zh-CN/concepts/models)。 ## 快速规则 -- 模型引用使用 `provider/model`（例如：`opencode/claude-opus-4-6`）。 +- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。 - 如果你设置了 `agents.defaults.models`，它就会成为允许列表。 -- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 -- 回退运行时规则、冷却探测以及会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 -- `models.providers.*.models[].contextWindow` 是原生模型元数据；`models.providers.*.models[].contextTokens` 是运行时生效的上限。 +- CLI 帮助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 +- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover) 中。 +- `models.providers.*.models[].contextWindow` 是原生模型元数据；`models.providers.*.models[].contextTokens` 是实际运行时上限。 - 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前将该输出合并到 `models.providers` 中。 -- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样通用的基于环境变量的凭证探测和提供商变体就不需要加载插件运行时。剩余的核心环境变量映射现在仅用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic API 密钥优先的新手引导。 -- 提供商插件还可以通过以下能力拥有提供商运行时行为：`normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`isBinaryThinking`、`supportsXHighThinking`、`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)。 +- 提供商清单可以声明 `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 智能体运行器配套使用。当你需要 Codex 自有的登录、模型发现、原生线程恢复和应用服务器执行时，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍会使用 OpenAI 提供商和正常的 OpenClaw 提供商传输。纯 Codex 部署可以通过 `agents.defaults.embeddedHarness.fallback: "none"` 禁用自动 PI 回退；参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 -## 插件自有的提供商行为 +## 插件自主管理的提供商行为 -提供商插件现在可以拥有大多数提供商特定逻辑，而 OpenClaw 保留通用推理循环。 +提供商插件现在可以管理大多数提供商特定逻辑，而 OpenClaw 保留通用推理循环。 -典型拆分如下： +典型分工： -- `auth[].run` / `auth[].runNonInteractive`：提供商拥有 `openclaw onboard`、`openclaw models auth` 和无头设置的 onboarding/登录流程 -- `wizard.setup` / `wizard.modelPicker`：提供商拥有凭证选择标签、旧版别名、onboarding 允许列表提示，以及 onboarding/模型选择器中的设置项 -- `catalog`：提供商会出现在 `models.providers` 中 -- `normalizeModelId`：提供商在查找或规范化之前规范旧版/预览模型 id -- `normalizeTransport`：提供商在通用模型组装之前规范传输家族的 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后再检查其他支持 hook 的提供商插件，直到其中一个实际更改了传输 -- `normalizeConfig`：提供商在运行时使用前规范 `models.providers.` 配置；OpenClaw 会先检查匹配的提供商，然后再检查其他支持 hook 的提供商插件，直到其中一个实际更改了配置。如果没有任何提供商 hook 重写配置，内置的 Google 家族辅助逻辑仍会规范受支持的 Google 提供商条目。 -- `applyNativeStreamingUsageCompat`：提供商为配置型提供商应用由端点驱动的原生流式用量兼容性重写 -- `resolveConfigApiKey`：提供商为配置型提供商解析环境变量标记的凭证，而无需强制加载完整运行时凭证。`amazon-bedrock` 在这里也有内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是 AWS SDK 默认链。 +- `auth[].run` / `auth[].runNonInteractive`：提供商管理 `openclaw onboard`、`openclaw models auth` 和无头设置的引导/登录流程 +- `wizard.setup` / `wizard.modelPicker`：提供商管理凭证选择标签、旧版别名、引导允许列表提示，以及新手引导/模型选择器中的设置条目 +- `catalog`：提供商会显示在 `models.providers` 中 +- `normalizeModelId`：提供商在查找或规范化之前标准化旧版/预览模型 ID +- `normalizeTransport`：提供商在通用模型组装之前标准化传输家族 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后再检查其他支持该钩子的提供商插件，直到其中一个实际更改了传输 +- `normalizeConfig`：提供商在运行时使用前标准化 `models.providers.` 配置；OpenClaw 会先检查匹配的提供商，然后再检查其他支持该钩子的提供商插件，直到其中一个实际更改了配置。如果没有提供商钩子重写配置，内置的 Google 家族帮助器仍会标准化受支持的 Google 提供商条目。 +- `applyNativeStreamingUsageCompat`：提供商为配置型提供商应用由端点驱动的原生流式使用量兼容性重写 +- `resolveConfigApiKey`：提供商为配置型提供商解析环境变量标记凭证，而无需强制加载完整运行时凭证。`amazon-bedrock` 在这里也有一个内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是 AWS SDK 默认链。 - `resolveSyntheticAuth`：提供商可以暴露本地/自托管或其他基于配置的凭证可用性，而无需持久化明文密钥 -- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置档占位符标记为低于环境变量/配置凭证的优先级 -- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 id -- `prepareDynamicModel`：提供商在重试动态解析前需要刷新元数据 -- `normalizeResolvedModel`：提供商需要重写传输或 base URL -- `contributeResolvedModelCompat`：即使供应商模型通过另一个兼容传输到达，提供商也会为其贡献兼容标记 -- `capabilities`：提供商发布转录/工具/提供商家族特性差异 -- `normalizeToolSchemas`：提供商在嵌入式运行器看到工具 schema 之前先进行清理 -- `inspectToolSchemas`：提供商在规范化后暴露特定于传输的 schema 警告 -- `resolveReasoningOutputMode`：提供商选择原生还是带标签的推理输出契约 -- `prepareExtraParams`：提供商为每个模型的请求参数提供默认值或进行规范化 -- `createStreamFn`：提供商用完全自定义的传输替换正常的流式路径 +- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置文件占位符标记为低于环境变量/配置型凭证的优先级 +- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 ID +- `prepareDynamicModel`：提供商在重试动态解析之前需要刷新元数据 +- `normalizeResolvedModel`：提供商需要重写传输或基础 URL +- `contributeResolvedModelCompat`：即使其供应商模型通过另一种兼容传输到达，提供商仍会为其贡献兼容性标记 +- `capabilities`：提供商发布转录/工具/提供商家族特殊行为 +- `normalizeToolSchemas`：提供商在内置运行器看到工具 schema 之前对其进行清理 +- `inspectToolSchemas`：提供商在标准化后暴露传输特定的 schema 警告 +- `resolveReasoningOutputMode`：提供商选择原生或带标签的推理输出协议 +- `prepareExtraParams`：提供商为每个模型请求参数设置默认值或进行标准化 +- `createStreamFn`：提供商用完全自定义的传输替换正常流式路径 - `wrapStreamFn`：提供商应用请求头/请求体/模型兼容性包装器 -- `resolveTransportTurnState`：提供商提供每轮的原生传输请求头或元数据 +- `resolveTransportTurnState`：提供商为每一轮提供原生传输请求头或元数据 - `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话请求头或会话冷却策略 -- `createEmbeddingProvider`：当记忆嵌入行为更适合归属于提供商插件而不是核心嵌入切换板时，由提供商拥有该行为 -- `formatApiKey`：提供商将已存储的凭证配置档格式化为传输所期望的运行时 `apiKey` 字符串 -- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足时，由提供商负责 OAuth 刷新 -- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商附加修复指导 -- `matchesContextOverflowError`：提供商识别通用启发式无法捕捉的提供商特定上下文窗口溢出错误 -- `classifyFailoverReason`：提供商将特定于提供商的原始传输/API 错误映射为回退原因，例如速率限制或过载 -- `isCacheTtlEligible`：提供商决定哪些上游模型 id 支持提示缓存 TTL -- `buildMissingAuthMessage`：提供商用特定于提供商的恢复提示替换通用凭证存储错误 -- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以在直接解析失败时返回供应商自有错误 -- `augmentModelCatalog`：提供商在发现和配置合并之后附加合成/最终目录条目 -- `isBinaryThinking`：提供商拥有二元开/关 thinking UX +- `createEmbeddingProvider`：当内存嵌入行为更适合放在提供商插件中而不是核心嵌入调度器中时，由提供商负责管理 +- `formatApiKey`：提供商将已存储的凭证配置文件格式化为传输所需的运行时 `apiKey` 字符串 +- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足以满足需求时，由提供商管理 OAuth 刷新 +- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商追加修复指导 +- `matchesContextOverflowError`：提供商识别通用启发式方法可能漏掉的提供商特定上下文窗口溢出错误 +- `classifyFailoverReason`：提供商将原始的提供商特定传输/API 错误映射为回退原因，例如速率限制或过载 +- `isCacheTtlEligible`：提供商决定哪些上游模型 ID 支持提示缓存 TTL +- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用凭证存储错误 +- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以在直接解析失败时返回供应商自主管理的错误 +- `augmentModelCatalog`：在发现和配置合并之后，提供商追加合成/最终目录条目 +- `isBinaryThinking`：提供商管理二元开/关思考体验 - `supportsXHighThinking`：提供商为选定模型启用 `xhigh` -- `resolveDefaultThinkingLevel`：提供商拥有某个模型家族的默认 `/think` 策略 -- `applyConfigDefaults`：提供商基于凭证模式、环境或模型家族，在配置具体化期间应用提供商特定的全局默认值 -- `isModernModelRef`：提供商拥有 live/smoke 首选模型匹配 -- `prepareRuntimeAuth`：提供商将已配置的凭证转换为短时有效的运行时令牌 +- `resolveDefaultThinkingLevel`：提供商管理某个模型家族的默认 `/think` 策略 +- `applyConfigDefaults`：提供商根据凭证模式、环境或模型家族，在配置具体化期间应用提供商特定的全局默认值 +- `isModernModelRef`：提供商管理 live/smoke 首选模型匹配 +- `prepareRuntimeAuth`：提供商将已配置的凭证转换为短期运行时令牌 - `resolveUsageAuth`：提供商为 `/usage` 及相关状态/报告界面解析用量/配额凭证 -- `fetchUsageSnapshot`：提供商拥有用量端点的获取/解析逻辑，而核心仍拥有摘要外壳和格式化 -- `onModelSelected`：提供商在模型选定后运行副作用，例如遥测或提供商自有的会话簿记 +- `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`：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`：插件自有目录，以及用量凭证/快照逻辑 +- `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-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 图像预览模型内置图像生成提供商注册，以及为 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`：文本模型目录由插件自主管理，另外其多模态界面使用共享的媒体理解和视频生成提供商注册；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__KEY`（单个 live 覆盖，最高优先级） +- 支持为选定提供商进行通用提供商轮换。 +- 通过以下方式配置多个密钥： + - `OPENCLAW_LIVE__KEY`（单个 live 覆盖，优先级最高） - `_API_KEYS`（逗号或分号分隔列表） - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） -- 对于 Google 提供商，也会将 `GOOGLE_API_KEY` 作为回退项包含在内。 -- 密钥选择顺序会保留优先级并去重数值。 -- 仅在速率限制响应时，请求才会使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 或周期性用量限制消息）。 +- 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。 +- 密钥选择顺序会保留优先级并去重。 +- 仅在速率限制响应时，请求才会使用下一个密钥重试（例如 `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,15 +134,15 @@ 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 回退） -- 可通过 `agents.defaults.models["openai/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup`（`true`/`false`）启用 +- 默认传输为 `auto`（WebSocket 优先，SSE 回退） +- 可通过 `agents.defaults.models["openai/"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） +- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`） - 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先处理 - `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority` -- 当你想显式指定层级而不是使用共享 `/fast` 开关时，请使用 `params.serviceTier` -- 隐藏的 OpenClaw 归属请求头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理 -- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示以及 OpenAI 推理兼容负载整形；代理路由不会 -- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex +- 如果你想要显式层级而不是共享的 `/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 { @@ -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 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成的受支持方式。 -- 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 用法再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成的许可方式，除非 Anthropic 发布新的策略。 +- 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 回退） -- 可通过 `agents.defaults.models["openai-codex/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） +- 默认传输为 `auto`（WebSocket 优先，SSE 回退） +- 可通过 `agents.defaults.models["openai-codex/"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） - `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）中转发 -- 隐藏的 OpenClaw 归属请求头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理 -- 与直接 `openai/*` 共用相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射到 `service_tier=priority` -- 当 Codex OAuth 目录暴露它时，`openai-codex/gpt-5.3-codex-spark` 仍然可用；是否可用取决于 entitlement +- 隐藏的 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 这类外部工具/工作流。 +- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这样的外部工具/工作流。 ```json5 { @@ -224,17 +224,17 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** `models.providers - 提供商：`google` - 凭证：`GEMINI_API_KEY` -- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） +- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） - 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview` -- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview` +- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被标准化为 `google/gemini-3-flash-preview` - CLI：`openclaw onboard --auth-choice gemini-api-key` -- 直接 Gemini 运行也接受 `agents.defaults.models["google/"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` +- 直接 Gemini 运行还接受 `agents.defaults.models["google/"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` ### Google Vertex 和 Gemini CLI - 提供商：`google-vertex`、`google-gemini-cli` - 凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程 -- 注意：OpenClaw 中的 Gemini CLI OAuth 属于非官方集成。一些用户报告称，在使用第三方客户端后，他们的 Google 账号受到了限制。请先查看 Google 条款，并且如果你决定继续，建议使用非关键账号。 +- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后，Google 账号受到了限制。如果你选择继续，请先查看 Google 条款，并使用非关键账号。 - Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 - 先安装 Gemini CLI： - `brew install gemini-cli` @@ -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` -- 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 中硬编码的。 +- 基础 URL：`https://api.kilo.ai/api/gateway/` +- 静态回退目录内置了 `kilocode/kilo/auto`；实时 `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 重放校验和引导重写仍然关闭 +- 只有当请求实际目标为 `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` 以及其他不支持代理推理的提示会跳过代理推理注入 +- 基于 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 onboarding/API 密钥设置会写入显式的 M2.7 模型定义，并带有 `input: ["text", "image"]`；在该提供商配置具体化之前，内置提供商目录会让这些聊天引用保持仅文本模式 +- MiniMax 新手引导/API 密钥设置会写入显式的 M2.7 模型定义，并带有 `input: ["text", "image"]`；在该提供商配置具体化之前，内置提供商目录会将聊天引用保持为仅文本 - Moonshot：`moonshot`（`MOONSHOT_API_KEY`） - 示例模型：`moonshot/kimi-k2.5` - Kimi Coding：`kimi`（`KIMI_API_KEY` 或 `KIMICODE_API_KEY`） @@ -315,28 +315,28 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** `models.providers - 示例模型：`byteplus-plan/ark-code-latest` - xAI：`xai`（`XAI_API_KEY`） - 原生内置 xAI 请求使用 xAI Responses 路径 - - `/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为它们的 `*-fast` 变体 + - `/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为各自的 `*-fast` 变体 - `tool_stream` 默认开启；如需禁用，请将 `agents.defaults.models["xai/"].params.tool_stream` 设置为 `false` - Mistral：`mistral`（`MISTRAL_API_KEY`） - 示例模型：`mistral/mistral-large-latest` - CLI：`openclaw onboard --auth-choice mistral-api-key` - Groq：`groq`（`GROQ_API_KEY`） - Cerebras：`cerebras`（`CEREBRAS_API_KEY`） - - Cerebras 上的 GLM 模型使用 id `zai-glm-4.7` 和 `zai-glm-4.6`。 - - OpenAI 兼容 base URL：`https://api.cerebras.ai/v1`。 + - 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)。 +- Hugging Face Inference 示例模型：`huggingface/deepseek-ai/DeepSeek-R1`；CLI：`openclaw onboard --auth-choice huggingface-api-key`。参见 [Hugging Face（Inference）](/zh-CN/providers/huggingface)。 -## 通过 `models.providers` 配置的提供商（自定义/base URL） +## 通过 `models.providers` 配置的提供商（自定义/基础 URL） 使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。 下面许多内置提供商插件已经发布了默认目录。 -只有当你想覆盖默认 base URL、请求头或模型列表时，才需要使用显式的 `models.providers.` 条目。 +只有当你想覆盖默认基础 URL、请求头或模型列表时，才使用显式的 `models.providers.` 条目。 ### Moonshot AI（Kimi） -Moonshot 作为内置提供商插件提供。默认请使用内置提供商，只有在你需要覆盖 base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： +Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在你需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： - 提供商：`moonshot` - 凭证：`MOONSHOT_API_KEY` @@ -390,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` @@ -409,9 +409,9 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访 } ``` -新手引导默认使用编程接口，但通用 `volcengine/*` 目录也会同时注册。 +新手引导默认使用编程接口，但同时也会注册通用的 `volcengine/*` 目录。 -在 onboarding/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商范围筛选的选择器。 +在新手引导/配置模型选择器中，Volcengine 的凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示一个空的按提供商范围筛选的选择器。 可用模型： @@ -431,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` @@ -446,9 +446,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力 } ``` -新手引导默认使用编程接口，但通用 `byteplus/*` 目录也会同时注册。 +新手引导默认使用编程接口，但同时也会注册通用的 `byteplus/*` 目录。 -在 onboarding/配置模型选择器中，BytePlus（国际版）凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商范围筛选的选择器。 +在新手引导/配置模型选择器中，BytePlus（国际版）的凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示一个空的按提供商范围筛选的选择器。 可用模型： @@ -502,20 +502,20 @@ 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 -Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API： +Ollama 作为内置提供商插件提供，并使用 Ollama 原生 API： - 提供商：`ollama` - 凭证：无需（本地服务器） @@ -535,7 +535,7 @@ ollama pull llama3.3 } ``` -当你通过 `OLLAMA_API_KEY` 选择启用时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到，并且内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。有关 onboarding、云端/本地模式和自定义配置，请参阅 [/providers/ollama](/zh-CN/providers/ollama)。 +当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，并且内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。 ### vLLM @@ -543,15 +543,15 @@ vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容 - 提供商：`vllm` - 凭证：可选（取决于你的服务器） -- 默认 base URL：`http://127.0.0.1:8000/v1` +- 默认基础 URL：`http://127.0.0.1:8000/v1` -如需在本地选择启用自动发现（如果你的服务器不强制验证凭证，任意值都可以）： +要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）： ```bash export VLLM_API_KEY="vllm-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 id）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： ```json5 { @@ -561,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` - 凭证：可选（取决于你的服务器） -- 默认 base URL：`http://127.0.0.1:30000/v1` +- 默认基础 URL：`http://127.0.0.1:30000/v1` -如需在本地选择启用自动发现（如果你的服务器不强制验证凭证，任意值都可以）： +要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）： ```bash export SGLANG_API_KEY="sglang-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 id）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： ```json5 { @@ -587,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 等） @@ -633,11 +633,11 @@ 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`）。 -- 出于安全考虑，即使显式设置了 `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 示例 @@ -647,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)，查看完整配置示例。 ## 相关内容 -- [模型](/zh-CN/concepts/models) — 模型配置和别名 +- [Models](/zh-CN/concepts/models) — 模型配置和别名 - [Model Failover](/zh-CN/concepts/model-failover) — 回退链和重试行为 - [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键 - [Providers](/zh-CN/providers) — 按提供商分类的设置指南 diff --git a/docs/zh-CN/plugins/codex-harness.md b/docs/zh-CN/plugins/codex-harness.md new file mode 100644 index 000000000..97d23a041 --- /dev/null +++ b/docs/zh-CN/plugins/codex-harness.md @@ -0,0 +1,267 @@ +--- +read_when: + - 你想使用内置的 Codex app-server 测试工具 + - 你需要 Codex 模型引用和配置示例 + - 你想为仅使用 Codex 的部署禁用 PI 回退机制 +summary: 通过内置的 Codex app-server 测试工具运行 OpenClaw 嵌入式智能体轮次 +title: Codex 测试工具 +x-i18n: + generated_at: "2026-04-10T21:05:27Z" + model: gpt-5.4 + provider: openai + source_hash: b1babe5b3498eb2a963f3e66a46975bd261886398499453d0d240e1fbc309bf4 + source_path: plugins/codex-harness.md + workflow: 15 +--- + +# Codex 测试工具 + +内置的 `codex` 插件让 OpenClaw 通过 Codex app-server 运行嵌入式智能体轮次，而不是使用内置的 PI 测试工具。 + +当你希望由 Codex 接管底层智能体会话时使用此功能：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传输，以及可见的对话记录镜像。 + +该测试工具默认关闭。只有在启用 `codex` 插件且解析后的模型是 `codex/*` 模型时，或者你显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex` 时，才会选用它。如果你从不配置 `codex/*`，现有的 PI、OpenAI、Anthropic、Gemini、本地和自定义提供商运行方式都会保持当前行为。 + +## 选择正确的模型前缀 + +OpenClaw 为 OpenAI 和 Codex 风格的访问提供了不同的路由： + +| 模型引用 | 运行时路径 | 适用场景 | +| ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | +| `openai/gpt-5.4` | 通过 OpenClaw/PI 管道的 OpenAI 提供商路径 | 你希望使用 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 | +| `openai-codex/gpt-5.4` | 通过 PI 的 OpenAI Codex OAuth 提供商路径 | 你希望使用 ChatGPT/Codex OAuth，但不使用 Codex app-server 测试工具。 | +| `codex/gpt-5.4` | 内置 Codex 提供商 + Codex 测试工具 | 你希望在嵌入式智能体轮次中使用原生 Codex app-server 执行。 | + +Codex 测试工具只接管 `codex/*` 模型引用。现有的 `openai/*`、`openai-codex/*`、Anthropic、Gemini、xAI、本地和自定义提供商引用都会继续走各自的正常路径。 + +## 要求 + +- OpenClaw，且内置的 `codex` 插件可用。 +- Codex app-server `0.118.0` 或更高版本。 +- app-server 进程可用的 Codex 认证信息。 + +该插件会阻止较旧版本或未带版本信息的 app-server 握手。这可确保 OpenClaw 始终运行在它已测试过的协议接口上。 + +对于实时测试和 Docker 冒烟测试，认证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的认证材料。 + +## 最小配置 + +使用 `codex/gpt-5.4`，启用内置插件，并强制使用 `codex` 测试工具： + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + }, + }, + }, + agents: { + defaults: { + model: "codex/gpt-5.4", + embeddedHarness: { + runtime: "codex", + fallback: "none", + }, + }, + }, +} +``` + +如果你的配置使用了 `plugins.allow`，也请将 `codex` 包含进去： + +```json5 +{ + plugins: { + allow: ["codex"], + entries: { + codex: { + enabled: true, + }, + }, + }, +} +``` + +将 `agents.defaults.model` 或某个智能体模型设置为 `codex/` 也会自动启用内置的 `codex` 插件。显式添加插件条目在共享配置中仍然很有用，因为它能让部署意图更清晰。 + +## 在不替换其他模型的情况下添加 Codex + +如果你希望 `codex/*` 模型使用 Codex，而其他所有模型仍使用 PI，请保持 `runtime: "auto"`： + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + }, + }, + }, + agents: { + defaults: { + model: { + primary: "codex/gpt-5.4", + fallbacks: ["openai/gpt-5.4", "anthropic/claude-opus-4-6"], + }, + models: { + "codex/gpt-5.4": { alias: "codex" }, + "codex/gpt-5.4-mini": { alias: "codex-mini" }, + "openai/gpt-5.4": { alias: "gpt" }, + "anthropic/claude-opus-4-6": { alias: "opus" }, + }, + embeddedHarness: { + runtime: "auto", + fallback: "pi", + }, + }, + }, +} +``` + +采用这种配置后： + +- `/model codex` 或 `/model codex/gpt-5.4` 会使用 Codex app-server 测试工具。 +- `/model gpt` 或 `/model openai/gpt-5.4` 会使用 OpenAI 提供商路径。 +- `/model opus` 会使用 Anthropic 提供商路径。 +- 如果选择的是非 Codex 模型，PI 仍然是兼容性测试工具。 + +## 仅使用 Codex 的部署 + +如果你需要证明每个嵌入式智能体轮次都使用 Codex 测试工具，请禁用 PI 回退： + +```json5 +{ + agents: { + defaults: { + model: "codex/gpt-5.4", + embeddedHarness: { + runtime: "codex", + fallback: "none", + }, + }, + }, +} +``` + +环境变量覆盖： + +```bash +OPENCLAW_AGENT_RUNTIME=codex \ +OPENCLAW_AGENT_HARNESS_FALLBACK=none \ +openclaw gateway run +``` + +禁用回退后，如果 Codex 插件被禁用、请求的模型不是 `codex/*` 引用、app-server 版本过旧，或者 app-server 无法启动，OpenClaw 都会尽早失败。 + +## 按智能体使用 Codex + +你可以让某一个智能体仅使用 Codex，而默认智能体继续保持正常的自动选择： + +```json5 +{ + agents: { + defaults: { + embeddedHarness: { + runtime: "auto", + fallback: "pi", + }, + }, + list: [ + { + id: "main", + default: true, + model: "anthropic/claude-opus-4-6", + }, + { + id: "codex", + name: "Codex", + model: "codex/gpt-5.4", + embeddedHarness: { + runtime: "codex", + fallback: "none", + }, + }, + ], + }, +} +``` + +使用常规会话命令切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，而 Codex 测试工具会按需创建或恢复它对应的 sidecar app-server 线程。`/reset` 会清除该线程的 OpenClaw 会话绑定。 + +## 模型发现 + +默认情况下，Codex 插件会向 app-server 请求可用模型。如果发现失败或超时，它会使用内置的回退目录： + +- `codex/gpt-5.4` +- `codex/gpt-5.4-mini` +- `codex/gpt-5.2` + +你可以在 `plugins.entries.codex.config.discovery` 下调整发现行为： + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + discovery: { + enabled: true, + timeoutMs: 2500, + }, + }, + }, + }, + }, +} +``` + +如果你希望启动时避免探测 Codex，并始终使用回退目录，可以禁用发现： + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + discovery: { + enabled: false, + }, + }, + }, + }, + }, +} +``` + +## 工具、媒体和压缩 + +Codex 测试工具只会改变底层嵌入式智能体执行器。 + +OpenClaw 仍然会构建工具列表，并从测试工具接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出，都会继续通过正常的 OpenClaw 传输路径处理。 + +当所选模型使用 Codex 测试工具时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一份对话记录镜像，用于渠道历史、搜索、`/new`、`/reset`，以及未来的模型或测试工具切换。 + +媒体生成不依赖 PI。图像、视频、音乐、PDF、TTS 和媒体理解仍会继续使用匹配的提供商/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 + +## 故障排除 + +**Codex 没有出现在 `/model` 中：** 启用 `plugins.entries.codex.enabled`，设置一个 `codex/*` 模型引用，或检查 `plugins.allow` 是否排除了 `codex`。 + +**OpenClaw 回退到 PI：** 在测试时设置 `embeddedHarness.fallback: "none"` 或 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`。 + +**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告的版本为 `0.118.0` 或更高。 + +**模型发现速度很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs`，或禁用发现。 + +**某个非 Codex 模型使用了 PI：** 这是预期行为。Codex 测试工具只接管 `codex/*` 模型引用。 + +## 相关内容 + +- [智能体测试工具插件](/zh-CN/plugins/sdk-agent-harness) +- [模型提供商](/zh-CN/concepts/model-providers) +- [配置参考](/zh-CN/gateway/configuration-reference) +- [测试](/zh-CN/help/testing#live-codex-app-server-harness-smoke) diff --git a/docs/zh-CN/plugins/sdk-agent-harness.md b/docs/zh-CN/plugins/sdk-agent-harness.md index 8ada35be8..618470685 100644 --- a/docs/zh-CN/plugins/sdk-agent-harness.md +++ b/docs/zh-CN/plugins/sdk-agent-harness.md @@ -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:28:58Z" + generated_at: "2026-04-10T21:05:13Z" model: gpt-5.4 provider: openai - source_hash: 3afa7d81ca5a34f40da63e01bb9b42aa10ff8d6f92c2f78bf2588f1a71b5bc0e + source_hash: 3abada0b89609c80edf3b66dfbd5951e812523c31d758643edb92e01f86e6dae source_path: plugins/sdk-agent-harness.md workflow: 15 --- # 智能体 Harness 插件 -**智能体 harness** 是一个已准备好的 OpenClaw 智能体单次轮次的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。 +**智能体 Harness** 是一个已准备好的 OpenClaw 智能体单轮请求的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。 -仅将此接口用于内置或受信任的原生插件。该契约仍处于实验阶段，因为其参数类型有意与当前的嵌入式运行器保持一致。 +仅对内置或受信任的原生插件使用此接口。该契约目前仍是实验性的，因为其参数类型有意映射当前的嵌入式运行器。 -## 何时使用 harness +## 何时使用 Harness -当某个模型家族拥有自己的原生会话运行时，而常规的 OpenClaw 提供商传输层并不是合适抽象时，请注册一个智能体 harness。 +当某个模型家族拥有自己的原生会话运行时，而常规的 OpenClaw 提供商传输层抽象并不适用时，请注册一个智能体 Harness。 示例： -- 拥有线程和压缩能力的原生编码智能体服务器 -- 必须流式传输原生计划 / 推理 / 工具事件的本地 CLI 或守护进程 -- 除 OpenClaw 会话转录之外，还需要自身 resume id 的模型运行时 +- 一个拥有线程和压缩机制的原生编码智能体服务器 +- 一个必须流式传输原生计划 / 推理 / 工具事件的本地 CLI 或守护进程 +- 一个除了 OpenClaw 会话转录之外，还需要自己恢复 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 已经解析了： - 提供商和模型 -- 运行时认证状态 -- thinking level 和上下文预算 -- OpenClaw transcript / session 文件 +- 运行时凭证状态 +- 思考级别和上下文预算 +- OpenClaw 转录 / 会话文件 - 工作区、沙箱和工具策略 -- 渠道回复回调和流式回调 +- 渠道回复回调和流式传输回调 - 模型回退和实时模型切换策略 -这种划分是有意设计的。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 的已注册 harness。 -2. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI harness。 -3. `OPENCLAW_AGENT_RUNTIME=auto` 会让已注册的 harness 询问自己是否支持已解析的提供商 / 模型。 -4. 如果没有匹配的已注册 harness，OpenClaw 会使用 PI，除非已禁用 PI 回退。 +1. `OPENCLAW_AGENT_RUNTIME=` 会强制使用具有该 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。将 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 或 `embeddedHarness.fallback: "none"` 设置为禁用回退，即可让该回退变成硬失败。 +强制使用插件 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 插件遵循这一模式： +内置的 Codex 插件遵循这种模式： -- provider id：`codex` +- 提供商 id：`codex` - 用户模型引用：`codex/gpt-5.4`、`codex/gpt-5.2`，或 Codex app server 返回的其他模型 -- harness id：`codex` -- 认证：合成提供商可用性，因为 Codex harness 负责原生 Codex 登录 / 会话 -- app-server 请求：OpenClaw 会将裸模型 id 发送给 Codex，并让 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 initialize 握手，并阻止较旧或未标明版本的服务器，以确保 OpenClaw 仅针对其已测试的协议接口运行。 +有关操作员设置、模型前缀示例和仅限 Codex 的配置，请参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 + +OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会检查 app-server 初始化握手，并阻止较旧或未标明版本的服务器，以确保 OpenClaw 仅运行在它已测试过的协议接口之上。 ## 禁用 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"`。这会禁用自动 PI 回退；但不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。 +当你需要证明插件 Harness 是唯一正在被使用的运行时时，请设置 `fallback: "none"`。这会禁用自动 PI 回退；但不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。 对于仅使用 Codex 的嵌入式运行： @@ -134,7 +136,7 @@ OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会 } ``` -如果你希望任何已注册的插件 harness 都能声明匹配的模型，但又不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退： +如果你希望任何已注册的插件 Harness 都可以声明匹配的模型，但又不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退： ```json { @@ -174,7 +176,7 @@ 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 \ @@ -182,38 +184,39 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -禁用回退后，如果所请求的 harness 未注册、不支持已解析的提供商 / 模型，或在产生该轮副作用之前失败，则会话会提前失败。这对于仅使用 Codex 的部署，以及必须证明 Codex app-server 路径确实在使用中的实时测试来说，是有意设计的行为。 +在禁用回退的情况下，如果请求的 Harness 未注册、不支持已解析的提供商 / 模型，或在产生该轮副作用之前失败，会话会提前失败。对于仅使用 Codex 的部署，以及必须证明 Codex app-server 路径确实正在使用的实时测试，这是有意设计的行为。 -此设置仅控制嵌入式智能体 harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商特定的模型路由。 +此设置仅控制嵌入式智能体 Harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他特定于提供商的模型路由。 ## 原生会话与转录镜像 -harness 可以保留原生 session id、thread id 或守护进程侧的 resume token。请将该绑定明确与 OpenClaw 会话关联，并持续将用户可见的 assistant / tool 输出镜像到 OpenClaw transcript 中。 +Harness 可以保留原生会话 id、线程 id 或守护进程端恢复令牌。请将这种绑定明确地与 OpenClaw 会话关联起来，并持续将用户可见的助手 / 工具输出镜像到 OpenClaw 转录中。 -OpenClaw transcript 仍然是以下场景的兼容层： +OpenClaw 转录仍然是以下内容的兼容层： - 渠道可见的会话历史 -- transcript 搜索与索引 -- 在后续轮次切换回内置 PI harness +- 转录搜索和索引 +- 在后续轮次切换回内置 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。不要在一轮中途、当原生工具、审批、assistant 文本或消息发送已经开始后切换 harness。 +- 公共导入路径是通用的，但某些 attempt / result 类型别名出于兼容性原因仍然带有 `Pi` 名称。 +- 第三方 Harness 安装仍是实验性的。在你确实需要原生会话运行时之前，请优先使用提供商插件。 +- 支持跨轮次切换 Harness。不要在一轮进行到一半时，在原生工具、审批、助手文本或消息发送已经开始之后切换 Harness。 ## 相关内容 - [SDK 概览](/zh-CN/plugins/sdk-overview) -- [运行时辅助函数](/zh-CN/plugins/sdk-runtime) +- [运行时辅助工具](/zh-CN/plugins/sdk-runtime) - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) +- [Codex Harness](/zh-CN/plugins/codex-harness) - [模型提供商](/zh-CN/concepts/model-providers)