diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index 52a99d782..57ecdd319 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -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 `。 -- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/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.` 配置；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.` 配置；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__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,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/"].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 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 @@ -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/"].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/"].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` -- 基础 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/"].params.tool_stream` 为 `false` 可将其关闭 + - `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 兼容基础 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.` 条目。 +下面许多内置提供商插件已经发布了默认目录。 +只有当你想覆盖默认 base URL、请求头或模型列表时，才需要使用显式的 `models.providers.` 条目。 ### 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) — 按提供商分类的设置指南 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 32e5fcf2a..97db85d0c 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - 你需要精确到字段级别的配置语义或默认值 - - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专门子系统参考文档的链接 + - 你正在验证渠道、模型、Gateway 网关或工具配置块】【。 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值以及指向专用子系统参考文档的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-10T18:36:59Z" + generated_at: "2026-04-10T20:28:58Z" model: gpt-5.4 provider: openai - source_hash: 9ad435d9c7ea41d2a63c097e30d6f86c2ae8c3e71ab0d386d4b60f206f201b36 + source_hash: dae596e545735012a048b7e3aed66c04353f8fd497af3971f7e5b9f928f6f0c8 source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 的核心配置参考。若想查看面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若需按任务划分的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 -本页介绍 OpenClaw 的主要配置面，并在某个子系统拥有自己更深入的参考文档时提供跳转链接。它**不会**尝试在单个页面中内联列出每个由渠道/插件拥有的命令目录，或每个深层 memory/QMD 调节项。 +本页涵盖 OpenClaw 的主要配置表面，并在某个子系统拥有更深入的独立参考时提供链接。它**不会**尝试在单页中内联每个渠道 / 插件自有的命令目录，或每个深层 memory / QMD 细项参数。 -代码中的事实依据： +代码事实依据： -- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 +- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置 / 插件 / 渠道元数据 - `config.schema.lookup` 会返回一个按路径限定的 schema 节点，供下钻工具使用 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 面校验配置文档基线哈希 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面校验配置文档基线哈希 -专门的深入参考文档： +专门的深度参考： - [Memory configuration reference](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 -- [Slash Commands](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置插件的命令目录 -- 相应渠道/插件页面，适用于特定渠道的命令面 +- [Slash Commands](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置插件命令目录 +- 各自所属的渠道 / 插件页面，适用于特定渠道的命令表面 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— OpenClaw 在省略时会使用安全的默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— OpenClaw 在省略时会使用安全默认值。 --- ## 渠道 -每个渠道在其配置节存在时都会自动启动（除非设置了 `enabled: false`）。 +每个渠道在其配置段存在时都会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | --------------------------------------------- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许存储） | -| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| 私信策略 | 行为 | +| ------------------- | ------------------------------------------------------------ | +| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 | +| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许列表存储中的发送者） | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| --------------------- | ------------------------------------- | -| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | -| `open` | 绕过群组允许列表（仍适用提及门控） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| --------------------- | ---------------------------------------------- | +| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | +| `open` | 绕过群组允许列表（仍会应用提及门控） | +| `disabled` | 阻止所有群组 / 房间消息 | -`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时作为默认值。 -配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。 -如果某个提供商配置块完全缺失（即不存在 `channels.`），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 +当提供商的 `groupPolicy` 未设置时，`channels.defaults.groupPolicy` 用于设置默认值。 +配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多为 **3 个**。 +如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（默认拒绝）并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话尚未有模型覆盖时（例如通过 `/model` 设置），才会应用渠道映射。 +使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当会话尚未具有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。 ```json5 { @@ -85,9 +85,9 @@ x-i18n: } ``` -### 渠道默认值与心跳 +### 渠道默认值和心跳 -使用 `channels.defaults` 为各个提供商共享群组策略和心跳行为： +使用 `channels.defaults` 为各提供商共享群组策略和心跳行为： ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的后备群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时使用的回退群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用 / 线程 / 历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用 / 回复上下文）。按渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 -- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 -- `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 +- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级 / 错误状态。 +- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器样式心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在已关联会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。在已存在已关联会话时会自动启动。 ```json5 { @@ -164,10 +164,10 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- 出站命令默认使用账号 `default`（如果存在）；否则使用第一个已配置的账号 ID（按排序顺序）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖该后备默认账号选择。 -- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 -- 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 +- 出站命令默认使用账号 `default`；若不存在，则使用第一个已配置的账号 ID（按排序顺序）。 +- 可选的 `channels.whatsapp.defaultAccount` 可在其匹配已配置账号 ID 时，覆盖该回退默认账号选择。 +- 旧版单账号 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 按账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -225,12 +225,12 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- Bot 令牌：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账号还可回退使用 `TELEGRAM_BOT_TOKEN`。 -- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 在多账号设置（2 个及以上账号 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`），以避免回退路由；若缺失或无效，`openclaw doctor` 会发出警告。 +- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。 +- 可选的 `channels.telegram.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。 +- 在多账号设置（2 个及以上账号 ID）中，设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；若缺失或无效，`openclaw doctor` 会发出警告。 - `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范形式 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 -- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中都可用）。 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目会为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范格式 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群聊）。 - 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 ### Discord @@ -333,36 +333,36 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- 令牌：`channels.discord.token`，默认账号可回退使用 `DISCORD_BOT_TOKEN`。 -- 提供显式 Discord `token` 的直接出站调用会使用该令牌执行调用；账号重试/策略设置仍来自活动运行时快照中选定的账号。 -- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 使用 `user:`（私信）或 `channel:`（服务器频道）作为投递目标；裸数字 ID 会被拒绝。 -- 服务器 slug 使用小写，并将空格替换为 `-`；频道键使用 slug 化后的名称（不带 `#`）。优先使用服务器 ID。 -- 默认会忽略由机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则仅接受提及机器人的机器人消息（机器人自己的消息仍会被过滤）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及了其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会拆分行数过多的消息，即使其长度未超过 2000 个字符。 +- Token：`channels.discord.token`，默认账号还可回退到 `DISCORD_BOT_TOKEN`。 +- 直接出站调用如果显式提供 Discord `token`，该调用会使用该 token；账号的重试 / 策略设置仍来自当前运行时快照中选定的账号。 +- 可选的 `channels.discord.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。 +- 交付目标请使用 `user:`（私信）或 `channel:`（服务器频道）；裸数字 ID 会被拒绝。 +- 服务器 slug 为小写，空格会替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用服务器 ID。 +- 由 bot 自己发送的消息默认会被忽略。`allowBots: true` 会启用这些消息；使用 `allowBots: "mentions"` 则仅接受提及该 bot 的 bot 消息（自身消息仍会被过滤）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及了其他用户或角色但未提及 bot 的消息（不包括 @everyone/@here）。 +- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其未超过 2000 个字符。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） - - `idleHours`：以小时为单位的 Discord 非活动自动取消聚焦覆盖（`0` 表示禁用） - - `maxAgeHours`：以小时为单位的 Discord 硬性最大存续时长覆盖（`0` 表示禁用） - - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程启用的选择加入开关 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道/线程 ID）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 -- `channels.discord.ui.components.accentColor` 为 Discord components v2 容器设置强调色。 + - `enabled`：线程绑定会话功能的 Discord 覆盖项（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定交付 / 路由） + - `idleHours`：以小时为单位的非活动自动取消聚焦 Discord 覆盖项（`0` 表示禁用） + - `maxAgeHours`：以小时为单位的硬性最大存活时长 Discord 覆盖项（`0` 表示禁用） + - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建 / 绑定线程启用的选择加入开关 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目会为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道 / 线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 +- `channels.discord.ui.components.accentColor` 用于设置 Discord components v2 容器的强调色。 - `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。 -- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 -- OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试恢复语音接收。 -- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 -- `channels.discord.autoPresence` 将运行时可用性映射为机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（紧急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 批准投递和批准人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出批准人时，exec 批准会激活。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 +- OpenClaw 还会在重复解密失败后，通过离开 / 重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔 `streaming` 值会被自动迁移。 +- `channels.discord.autoPresence` 将运行时可用性映射到 bot 在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 +- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称 / 标签匹配（破窗兼容模式）。 +- `channels.discord.execApprovals`：Discord 原生 exec 审批交付和审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会启用。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的批准请求。 - - `sessionFilter`：可选的会话键模式（子串或正则表达式）。 - - `target`：发送批准提示的位置。`"dm"`（默认）发送到批准人的私信，`"channel"` 发送到发起来源频道，`"both"` 两处都发送。当目标包含 `"channel"` 时，按钮仅对已解析出的批准人可用。 - - `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除批准私信。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 + - `sessionFilter`：可选的会话键模式（子串或正则）。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到源频道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮仅可由已解析出的审批人使用。 + - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**反应通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users`，应用于所有消息）。 +**Reaction notification 模式：** `off`（无）、`own`（bot 自己的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中所有消息的用户）。 ### Google Chat @@ -396,8 +396,8 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 - 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 - 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 使用 `spaces/` 或 `users/` 作为投递目标。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。 +- 交付目标请使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（破窗兼容模式）。 ### Slack @@ -466,36 +466,37 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 - **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 - **HTTP mode** 需要 `botToken` 加 `signingSecret`（可位于根级或按账号配置）。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 可接受明文 字符串或 SecretRef 对象。 -- Slack 账号快照会公开每项凭证的来源/状态字段，例如 +- Slack 账号快照会暴露按凭证划分的来源 / 状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 - `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef - 配置，但当前命令/运行时路径无法解析该密钥值。 + `signingSecretStatus`。`configured_unavailable` 表示该账号 + 通过 SecretRef 完成配置，但当前命令 / 运行时路径无法 + 解析该 secret 值。 - `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会自动迁移。 -- 使用 `user:`（私信）或 `channel:` 作为投递目标。 +- 可选的 `channels.slack.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。 +- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔 `streaming` 和 `nativeStreaming` 值会被自动迁移。 +- 交付目标请使用 `user:`（私信）或 `channel:`。 -**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 为每线程独立（默认）或在整个频道中共享。`thread.inheritParent` 会将父频道的转录复制到新线程中。 +**线程会话隔离：** `thread.historyScope` 可设为按线程（默认）或在整个频道内共享。`thread.inheritParent` 会将父频道转录复制到新线程。 -- Slack 原生流式传输以及 Slack 助手风格的“正在输入...”线程状态都需要回复线程目标。顶层私信默认保持在线程外，因此会使用 `typingReaction` 或普通投递，而不是线程式预览。 -- `typingReaction` 会在回复运行期间为传入的 Slack 消息添加临时反应，并在完成后移除。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 批准投递和批准人授权。其 schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- Slack 原生流式传输加上 Slack 助手样式的“正在输入...”线程状态需要一个回复线程目标。顶层私信默认保持不在线程中，因此它们会使用 `typingReaction` 或普通交付，而不是线程样式预览。 +- `typingReaction` 会在回复进行期间为传入的 Slack 消息添加一个临时 reaction，并在完成后移除。请使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批交付和审批人授权。与 Discord 使用相同 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认 | 说明 | -| ------------ | ------- | -------------------- | -| reactions | 已启用 | 反应 + 列出反应 | -| messages | 已启用 | 读取/发送/编辑/删除 | -| pins | 已启用 | 置顶/取消置顶/列出 | -| memberInfo | 已启用 | 成员信息 | -| emojiList | 已启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ------------ | ------ | ------------------ | +| reactions | 启用 | React + 列出 reactions | +| messages | 启用 | 读取 / 发送 / 编辑 / 删除 | +| pins | 启用 | 置顶 / 取消置顶 / 列出 | +| memberInfo | 启用 | 成员信息 | +| emojiList | 启用 | 自定义 emoji 列表 | ### Mattermost -Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -525,21 +526,22 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（回复以触发前缀开头的消息）。 -当启用 Mattermost 原生命令时： +启用 Mattermost 原生命令时： - `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。 -- 原生 slash 回调通过 Mattermost 在 slash 命令注册期间返回的每命令令牌进行认证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调，并返回 - `Unauthorized: invalid command token.`。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器必须能够访问。 +- 原生斜杠回调通过 Mattermost 在斜杠命令注册期间返回的每命令 token 进行认证。如果注册失败或没有 + 激活任何命令，OpenClaw 会使用 + `Unauthorized: invalid command token.` 拒绝回调。 - 对于私有 / tailnet / 内部回调主机，Mattermost 可能要求 - `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。 - 请使用主机/域名值，而不是完整 URL。 + `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机 / 域名。 + 请使用主机 / 域名值，而不是完整 URL。 - `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 - `channels.mattermost.requireMention`：在频道中回复前要求 `@mention`。 -- `channels.mattermost.groups..requireMention`：按频道设置的提及门控覆盖（`"*"` 为默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- `channels.mattermost.groups..requireMention`：按频道覆盖提及门控（`"*"` 表示默认值）。 +- 可选的 `channels.mattermost.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。 ### Signal @@ -560,15 +562,15 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos } ``` -**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 - `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。 - `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 可选的 `channels.signal.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `channels.bluebubbles`）。 +BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `channels.bluebubbles` 下）。 ```json5 { @@ -584,13 +586,13 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `chann ``` - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 -- 完整的 BlueBubbles 渠道配置记录于 [BlueBubbles](/zh-CN/channels/bluebubbles)。 +- 可选的 `channels.bluebubbles.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage -OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需守护进程或端口。 +OpenClaw 会启动 `imsg rpc`（通过 stdio 进行 JSON-RPC）。不需要守护进程或端口。 ```json5 { @@ -614,15 +616,15 @@ OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需守护进 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。 -- 需要对 Messages 数据库授予“完全磁盘访问”权限。 +- 需要对 Messages 数据库授予完全磁盘访问权限。 - 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 +- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以便通过 SCP 抓取附件。 - `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 - `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 @@ -635,7 +637,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展支持，并配置在 `channels.matrix` 下。 +Matrix 由扩展支持，并在 `channels.matrix` 下配置。 ```json5 { @@ -665,25 +667,25 @@ Matrix 由扩展支持，并配置在 `channels.matrix` 下。 } ``` -- 令牌认证使用 `accessToken`；密码认证使用 `userId` + `password`。 +- Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 - `channels.matrix.proxy` 会通过显式 HTTP(S) 代理转发 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 与此网络选择加入项是彼此独立的控制项。 -- `channels.matrix.defaultAccount` 会在多账号设置中选择首选账号。 -- `channels.matrix.autoJoin` 默认值为 `off`，因此邀请加入的房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 批准投递和批准人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出批准人时，exec 批准会激活。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有 / 内部 homeserver。`proxy` 与此网络选择加入开关是相互独立的控制项。 +- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 +- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 +- `channels.matrix.execApprovals`：Matrix 原生 exec 审批交付和审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会启用。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的批准请求。 - - `sessionFilter`：可选的会话键模式（子串或正则表达式）。 - - `target`：发送批准提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 + - `sessionFilter`：可选的会话键模式（子串或正则）。 + - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（源房间）或 `"both"`。 - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归组为会话：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组成会话：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 - Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 -- 完整的 Matrix 配置、目标规则和设置示例记录于 [Matrix](/zh-CN/channels/matrix)。 +- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams -Microsoft Teams 由扩展支持，并配置在 `channels.msteams` 下。 +Microsoft Teams 由扩展支持，并在 `channels.msteams` 下配置。 ```json5 { @@ -699,11 +701,11 @@ Microsoft Teams 由扩展支持，并配置在 `channels.msteams` 下。 ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/频道覆盖）记录于 [Microsoft Teams](/zh-CN/channels/msteams)。 +- 完整的 Teams 配置（凭证、webhook、私信 / 群组策略、按团队 / 按频道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 ### IRC -IRC 由扩展支持，并配置在 `channels.irc` 下。 +IRC 由扩展支持，并在 `channels.irc` 下配置。 ```json5 { @@ -725,12 +727,12 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 完整的 IRC 渠道配置（主机/端口/TLS/频道/允许列表/提及门控）记录于 [IRC](/zh-CN/channels/irc)。 +- 可选的 `channels.irc.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。 +- 完整的 IRC 渠道配置（host / port / TLS / channels / allowlists / mention gating）记录在 [IRC](/zh-CN/channels/irc) 中。 ### 多账号（所有渠道） -为每个渠道运行多个账号（每个都有自己的 `accountId`）： +为每个渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -751,28 +753,28 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 } ``` -- 省略 `accountId` 时会使用 `default`（CLI + 路由）。 -- 环境变量令牌仅适用于 **default** 账号。 -- 基础渠道设置适用于所有账号，除非在每账号级别覆盖。 +- 当省略 `accountId` 时，会使用 `default`（CLI + 路由）。 +- 环境变量 token 仅适用于**默认**账号。 +- 基础渠道设置会应用到所有账号，除非被按账号覆盖。 - 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。 -- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，而当前仍是单账号顶层渠道配置，OpenClaw 会先将账号范围的顶层单账号值提升到渠道账号映射中，以便原账号继续工作。多数渠道会将它们移到 `channels..accounts.default`；Matrix 则可以保留现有匹配的命名/default 目标。 -- 现有仅渠道级绑定（无 `accountId`）会继续匹配默认账号；账号范围绑定仍然是可选的。 -- `openclaw doctor --fix` 也会通过将账号范围的顶层单账号值移动到该渠道所选的提升账号中来修复混合形态。多数渠道使用 `accounts.default`；Matrix 则可以保留现有匹配的命名/default 目标。 +- 如果你在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将具有账号作用域的顶层单账号值提升到渠道账号映射中，以便原账号继续工作。大多数渠道会将它们移到 `channels..accounts.default`；Matrix 则可以保留现有的匹配命名 / 默认目标。 +- 现有仅渠道级绑定（无 `accountId`）会继续匹配默认账号；账号级绑定仍是可选的。 +- `openclaw doctor --fix` 也会通过将具有账号作用域的顶层单账号值移动到为该渠道选定的提升账号中，修复混合形状。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有的匹配命名 / 默认目标。 ### 其他扩展渠道 -许多扩展渠道配置为 `channels.`，并在各自专门的渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +许多扩展渠道配置为 `channels.`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 请参见完整渠道索引：[Channels](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认 **要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** -- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式下会被忽略。 +- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式中会被忽略。 - **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅当能够进行检测时（原生提及，或至少有一个模式），才会强制执行提及门控。 +- 仅在能够检测到提及时（原生提及或至少一个模式），才会强制执行提及门控。 ```json5 { @@ -785,9 +787,9 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。各渠道可通过 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 用于设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设为 `0` 可禁用。 -#### 私信历史限制 +#### 私信历史记录限制 ```json5 { @@ -802,13 +804,13 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 } ``` -解析顺序：按私信覆盖 → 提供商默认值 → 不限制（保留全部）。 +解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 #### 自聊模式 -将你自己的号码包含在 `allowFrom` 中即可启用自聊模式（忽略原生 @ 提及，只响应文本模式）： +将你自己的号码包含在 `allowFrom` 中即可启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -829,7 +831,7 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 } ``` -### Commands（聊天命令处理） +### 命令（聊天命令处理） ```json5 { @@ -858,31 +860,31 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 -- 此块配置命令面。当前内置 + 内置插件命令目录请参见 [Slash Commands](/zh-CN/tools/slash-commands)。 -- 本页是**配置键参考**，不是完整命令目录。由渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice`，记录在其各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 -- 文本命令必须是以 `/` 开头的**独立**消息。 -- `native: "auto"` 会为 Discord/Telegram 打开原生命令，Slack 保持关闭。 -- `nativeSkills: "auto"` 会为 Discord/Telegram 打开原生 Skills 命令，Slack 保持关闭。 -- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册的命令。 -- 使用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 注册。 -- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 -- `bash: true` 会为主机 shell 启用 `! `。要求 `tools.elevated.enabled` 已启用，且发送者在 `tools.elevated.allowFrom.` 中。 -- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还要求 `operator.admin`；只读的 `/config show` 对普通写入范围的 operator 客户端仍然可用。 -- `mcp: true` 会为位于 `mcp.servers` 下、由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 -- `plugins: true` 会启用 `/plugins`，用于插件发现、安装以及启用/禁用控制。 -- `channels..configWrites` 会按渠道控制配置变更（默认：true）。 +- 此配置块用于配置命令表面。当前内置 + 内置插件命令目录请参见 [Slash Commands](/zh-CN/tools/slash-commands)。 +- 本页是**配置键参考**，不是完整命令目录。由渠道 / 插件拥有的命令，如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice`，记录在它们各自的渠道 / 插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 +- 文本命令必须是带有前导 `/` 的**独立**消息。 +- `native: "auto"` 会为 Discord / Telegram 开启原生命令，对 Slack 保持关闭。 +- `nativeSkills: "auto"` 会为 Discord / Telegram 开启原生 Skills 命令，对 Slack 保持关闭。 +- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前注册的命令。 +- 使用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 命令注册。 +- `channels.telegram.customCommands` 会添加额外的 Telegram bot 菜单项。 +- `bash: true` 会为主机 shell 启用 `! `。需要 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.` 中。 +- `config: true` 会启用 `/config`（读取 / 写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久的 `/config set|unset` 写入还需要 `operator.admin`；只读的 `/config show` 对普通写权限 operator 客户端仍然可用。 +- `mcp: true` 会为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 +- `plugins: true` 会启用 `/plugins`，用于插件发现、安装以及启用 / 禁用控制。 +- `channels..configWrites` 按渠道控制配置变更（默认：true）。 - 对于多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 - `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 -- `ownerAllowFrom` 是 owner 专用命令/工具的显式 owner 允许列表。它与 `allowFrom` 分开。 -- `ownerDisplay: "hash"` 会在系统提示中对 owner ID 进行哈希。设置 `ownerDisplaySecret` 以控制哈希方式。 -- `allowFrom` 按提供商生效。设置后，它会成为**唯一**的授权来源（渠道允许列表/配对以及 `useAccessGroups` 会被忽略）。 +- `ownerAllowFrom` 是 owner 专用命令 / 工具的显式 owner 允许列表。它与 `allowFrom` 分开。 +- `ownerDisplay: "hash"` 会在系统提示中对 owner ID 进行哈希。设置 `ownerDisplaySecret` 可控制哈希。 +- `allowFrom` 是按提供商划分的。设置后，它将成为**唯一**的授权来源（渠道允许列表 / 配对 和 `useAccessGroups` 会被忽略）。 - `useAccessGroups: false` 会在未设置 `allowFrom` 时允许命令绕过访问组策略。 - 命令文档映射： - 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands) - - 渠道特定命令面：[Channels](/zh-CN/channels) + - 特定渠道命令表面：[Channels](/zh-CN/channels) - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) - 配对命令：[Pairing](/zh-CN/channels/pairing) - - LINE 卡片命令：[LINE](/zh-CN/channels/line) + - LINE card 命令：[LINE](/zh-CN/channels/line) - memory dreaming：[Dreaming](/zh-CN/concepts/dreaming) @@ -903,7 +905,7 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历自动检测。 +显示在系统提示 Runtime 行中的可选仓库根目录。如果未设置，OpenClaw 会从 workspace 开始向上遍历并自动检测。 ```json5 { @@ -913,8 +915,8 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 ### `agents.defaults.skills` -适用于未设置 -`agents.list[].skills` 的智能体的可选默认 Skills 允许列表。 +为未设置 +`agents.list[].skills` 的智能体提供可选默认 Skills 允许列表。 ```json5 { @@ -937,7 +939,7 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 ### `agents.defaults.skipBootstrap` -禁用工作区 bootstrap 文件的自动创建（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用自动创建 workspace bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -947,9 +949,9 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 ### `agents.defaults.contextInjection` -控制何时将工作区 bootstrap 文件注入系统提示。默认值：`"always"`。 +控制何时将 workspace bootstrap 文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全续写轮次（在 assistant 已完成回复之后）会跳过工作区 bootstrap 的重新注入，从而减少提示大小。心跳运行和压缩后的重试仍会重建上下文。 +- `"continuation-skip"`：安全续接回合（在 assistant 完成一次回复之后）会跳过 workspace bootstrap 的重复注入，从而减少提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。 ```json5 { @@ -959,7 +961,7 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 ### `agents.defaults.bootstrapMaxChars` -每个工作区 bootstrap 文件在被截断前允许的最大字符数。默认值：`20000`。 +单个 workspace bootstrap 文件在被截断前允许的最大字符数。默认值：`20000`。 ```json5 { @@ -969,7 +971,7 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 ### `agents.defaults.bootstrapTotalMaxChars` -所有工作区 bootstrap 文件合计可注入的最大总字符数。默认值：`150000`。 +所有 workspace bootstrap 文件合计可注入的最大字符数。默认值：`150000`。 ```json5 { @@ -979,8 +981,7 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制 bootstrap 上下文被截断时向智能体显示的警告文本。 -默认值：`"once"`。 +控制 bootstrap 上下文被截断时，对智能体可见的警告文本。默认值：`"once"`。 - `"off"`：绝不在系统提示中注入警告文本。 - `"once"`：对每个唯一的截断签名仅注入一次警告（推荐）。 @@ -994,11 +995,11 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 +在调用提供商之前，转录 / 工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少视觉 token 使用量，以及以截图为主的运行中的请求负载大小。 -较高的值则会保留更多视觉细节。 +较低的值通常会减少 vision token 使用量以及以截图为主的运行请求负载大小。 +较高的值会保留更多视觉细节。 ```json5 { @@ -1008,7 +1009,7 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 ### `agents.defaults.userTimezone` -系统提示上下文所使用的时区（不影响消息时间戳）。会回退到主机时区。 +系统提示上下文所使用的时区（不是消息时间戳）。未设置时回退到主机时区。 ```json5 { @@ -1057,6 +1058,10 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 fallbacks: ["openai/gpt-5.4-mini"], }, params: { cacheRetention: "long" }, // global default provider params + embeddedHarness: { + runtime: "auto", // auto | pi | registered harness id, e.g. codex + fallback: "pi", // pi | none + }, pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1071,43 +1076,71 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 } ``` -- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 +- `model`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 字符串形式仅设置主模型。 - - 对象形式设置主模型以及按顺序排列的故障转移模型。 -- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 对象形式设置主模型以及有序故障转移模型。 +- `imageModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 由 `image` 工具路径用作其视觉模型配置。 - - 当所选/默认模型无法接受图像输入时，也用作回退路由。 -- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享图像生成功能以及任何未来会生成图像的工具/插件面使用。 - - 典型值：`google/gemini-3.1-flash-image-preview`（Gemini 原生图像生成）、`fal/fal-ai/flux/dev`（fal）或 `openai/gpt-image-1`（OpenAI Images）。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/API 密钥（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断出一个具备认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider ID 顺序尝试其余已注册的图像生成提供商。 -- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享音乐生成功能和内置 `music_generate` 工具使用。 + - 当选定 / 默认模型无法接受图像输入时，也会用作回退路由。 +- `imageGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享图像生成能力以及任何未来生成图像的工具 / 插件表面使用。 + - 典型值：`google/gemini-3.1-flash-image-preview` 用于原生 Gemini 图像生成，`fal/fal-ai/flux/dev` 用于 fal，或 `openai/gpt-image-1` 用于 OpenAI Images。 + - 如果你直接选择某个提供商 / 模型，也请配置对应的提供商认证 / API key（例如 `google/*` 对应 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 对应 `OPENAI_API_KEY`，`fal/*` 对应 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断出一个具备认证的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 +- `musicGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享音乐生成能力和内置 `music_generate` 工具使用。 - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 如果省略，`music_generate` 仍可推断出一个具备认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider ID 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/API 密钥。 -- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享视频生成功能和内置 `video_generate` 工具使用。 + - 如果省略，`music_generate` 仍可推断出一个具备认证的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个提供商 / 模型，也请配置对应的提供商认证 / API key。 +- `videoGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享视频生成能力和内置 `video_generate` 工具使用。 - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断出一个具备认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider ID 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/API 密钥。 - - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 -- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 如果省略，`video_generate` 仍可推断出一个具备认证的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个提供商 / 模型，也请配置对应的提供商认证 / API key。 + - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 +- `pdfModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 由 `pdf` 工具用于模型路由。 - - 如果省略，PDF 工具会回退到 `imageModel`，再回退到解析后的会话/默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小上限。 + - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到解析后的会话 / 默认模型。 +- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。 - `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。 - `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 -- `elevatedDefault`：智能体的默认 elevated-output 级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试对该精确模型 ID 的唯一已配置提供商匹配，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此优先使用显式 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续使用陈旧的已移除提供商默认值。 -- `models`：`/model` 使用的已配置模型目录和允许列表。每个条目都可包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 -- `params`：应用于所有模型的全局默认提供商参数。设置位置为 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 ID）会按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退添加/移除命令）会保存规范的对象形式，并在可能时保留现有回退列表。 -- `maxConcurrent`：跨会话的智能体最大并行运行数（每个会话仍然串行）。默认值：4。 +- `elevatedDefault`：智能体的默认 elevated 输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议显式使用 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商 / 模型，而不是继续暴露已过时且已移除提供商的默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用于所有模型的全局默认提供商参数。设置于 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 ID）会按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 让已注册的插件 harness 认领受支持模型，使用 `runtime: "pi"` 强制使用内置 PI harness，或使用已注册 harness ID，如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。 +- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退 add/remove 命令）会保存规范对象形式，并尽可能保留现有回退列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍会串行化）。默认值：4。 -**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： +### `agents.defaults.embeddedHarness` + +`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体回合。 +大多数部署应保持默认值 `{ runtime: "auto", fallback: "pi" }`。 +当受信任插件提供原生 harness 时使用它，例如内置的 +Codex app-server harness。 + +```json5 +{ + agents: { + defaults: { + model: "codex/gpt-5.4", + embeddedHarness: { + runtime: "codex", + fallback: "none", + }, + }, + }, +} +``` + +- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness ID。内置的 Codex 插件会注册 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 会让缺失或不受支持的插件 harness 选择直接失败，而不是静默使用 PI。 +- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 PI 回退。 +- 对于仅 Codex 的部署，设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 +- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商 / 模型设置。 + +**内置别名简写**（仅在模型位于 `agents.defaults.models` 中时适用）： | 别名 | 模型 | | ------------------- | -------------------------------------- | @@ -1122,13 +1155,13 @@ IRC 由扩展支持，并配置在 `channels.irc` 下。 你配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 -Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `adaptive` thinking。 +Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 +Z.AI 模型默认启用 `tool_stream` 用于工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 +Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -适用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，可作为备选方案。 +可选的 CLI 后端，用于纯文本回退运行（无工具调用）。当 API 提供商失败时可作为备份。 ```json5 { @@ -1156,13 +1189,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad } ``` -- CLI 后端以文本为主；工具始终被禁用。 +- CLI 后端以文本优先；工具始终禁用。 - 设置了 `sessionArg` 时支持会话。 -- 当 `imageArg` 接受文件路径时，支持图像透传。 +- 当 `imageArg` 接受文件路径时，支持图像直通。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体级别（`agents.list[].systemPromptOverride`）设置。按智能体设置优先；空值或仅空白字符的值会被忽略。适用于受控的提示实验。 +使用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别设置（`agents.defaults.systemPromptOverride`），也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体设置的值优先；空值或仅空白值会被忽略。适合用于受控提示实验。 ```json5 { @@ -1176,7 +1209,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad ### `agents.defaults.heartbeat` -周期性心跳运行。 +周期性 Heartbeat 运行。 ```json5 { @@ -1202,14 +1235,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 -- `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：为 true 时，会在心跳运行期间抑制工具错误警告负载。 -- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行会使用轻量 bootstrap 上下文，并且只保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳都会在一个全新的会话中运行，不带任何先前的对话历史。隔离模式与 cron 的 `sessionTarget: "isolated"` 相同。可将每次心跳的 token 成本从约 100K 降低到约 2-5K。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 -- 心跳会运行完整的智能体轮次 —— 间隔越短，消耗的 token 越多。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 +- `includeSystemPromptSection`：设为 false 时，会从系统提示中省略 Heartbeat 章节，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。 +- `directPolicy`：direct / 私信交付策略。`allow`（默认）允许 direct-target 交付。`block` 会抑制 direct-target 交付并发出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，Heartbeat 运行使用轻量 bootstrap 上下文，并且仅保留 workspace bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次 Heartbeat 运行都会在一个新的会话中执行，不带任何先前的对话历史。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 Heartbeat 的 token 成本从约 100K 降至约 2-5K token。 +- 按智能体设置：设置 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。 +- Heartbeat 会运行完整的智能体回合 —— 更短的间隔会消耗更多 token。 ### `agents.defaults.compaction` @@ -1239,19 +1272,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad } ``` -- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册 compaction 提供商插件的 ID。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时回退到内置方式。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最大秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指引。 +- `mode`：`default` 或 `safeguard`（针对长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `provider`：已注册 compaction 提供商插件的 ID。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。在失败时会回退到内置实现。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最长秒数。默认值：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指导。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：compaction 后可选的重新注入 AGENTS.md H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置或显式设置为该默认对时，也接受旧版 `Every Session`/`Safety` 标题作为兼容回退。 -- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应继续使用某个模型，但 compaction 摘要应在另一个模型上运行时使用它；未设置时，compaction 使用会话的主模型。 -- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如“正在压缩上下文...”）。默认禁用，以保持 compaction 静默。 -- `memoryFlush`：在自动 compaction 之前执行的静默智能体轮次，用于存储持久 memory。在工作区为只读时会跳过。 +- `postCompactionSections`：compaction 后重新注入的可选 AGENTS.md H2/H3 章节名。默认为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置，或显式设置为该默认值对时，也会接受旧版 `Every Session` / `Safety` 标题作为兼容性回退。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。用于主会话保持一个模型，而 compaction 摘要改用另一个模型的场景；未设置时，compaction 使用会话的主模型。 +- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送一条简短通知（例如“正在压缩上下文...”）。默认禁用，以保持 compaction 静默。 +- `memoryFlush`：自动 compaction 前的静默智能体回合，用于存储持久记忆。workspace 为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送到 LLM 之前，从内存上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史记录。 ```json5 { @@ -1273,25 +1306,25 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad } ``` - + - `mode: "cache-ttl"` 会启用修剪过程。 -- `ttl` 控制下一次允许重新运行修剪的频率（自上次缓存触碰后）。 -- 修剪会先对过大的工具结果执行软裁剪，如仍有需要，再对更旧的工具结果执行硬清除。 +- `ttl` 控制再次允许运行修剪的频率（自上次缓存触达后计算）。 +- 修剪会先对过大的工具结果进行软截断，必要时再对较旧的工具结果执行硬清除。 -**软裁剪**会保留开头 + 结尾，并在中间插入 `...`。 +**软截断**会保留开头 + 结尾，并在中间插入 `...`。 **硬清除**会用占位符替换整个工具结果。 -注意： +说明： -- 图像块永远不会被裁剪/清除。 -- 比例基于字符数（近似），不是精确 token 数。 -- 如果 assistant 消息少于 `keepLastAssistants` 条，则会跳过修剪。 +- 图像块永远不会被截断 / 清除。 +- 比例基于字符数（近似值），不是精确 token 计数。 +- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。 -行为详情请参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为细节参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1309,13 +1342,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 的默认值为 `minChars: 1500`。 +- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 +- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal / Slack / Discord / Google Chat 默认 `minChars: 1500`。 - `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块详情请参见 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节参见 [Streaming](/zh-CN/concepts/streaming)。 -### 输入指示器 +### 输入中指示器 ```json5 { @@ -1328,7 +1361,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad } ``` -- 默认值：私聊/提及时为 `instant`，未被提及的群聊为 `message`。 +- 默认值：私聊 / 提及时为 `instant`，未提及的群聊为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 @@ -1337,7 +1370,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1440,44 +1473,44 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad - `ssh`：通用 SSH 支持的远程运行时 - `openshell`：OpenShell 运行时 -当选择 `backend: "openshell"` 时，运行时特定设置会移动到 +当选择 `backend: "openshell"` 时，运行时特定设置会移至 `plugins.entries.openshell.config`。 **SSH 后端配置：** - `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按作用域工作区的绝对远程根目录 +- `workspaceRoot`：用于按作用域 workspace 的远程绝对根路径 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 - `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 -- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略控制项 +- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略选项 **SSH 认证优先级：** - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前从活动 secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前活动的 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后，会先为远程工作区执行一次初始化 -- 之后保持远程 SSH 工作区为规范状态 +- 在创建或重建后，仅对远程 workspace 进行一次初始化 +- 之后保持远程 SSH workspace 为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 -**工作区访问：** +**workspace 访问：** -- `none`：每作用域沙箱工作区位于 `~/.openclaw/sandboxes` -- `ro`：沙箱工作区位于 `/workspace`，智能体工作区只读挂载到 `/agent` -- `rw`：智能体工作区以读写方式挂载到 `/workspace` +- `none`：在 `~/.openclaw/sandboxes` 下使用按作用域划分的沙箱 workspace +- `ro`：沙箱 workspace 位于 `/workspace`，智能体 workspace 以只读方式挂载到 `/agent` +- `rw`：智能体 workspace 以读写方式挂载到 `/workspace` **作用域：** -- `session`：每会话一个容器 + 工作区 -- `agent`：每个智能体一个容器 + 工作区（默认） -- `shared`：共享容器和工作区（无跨会话隔离） +- `session`：每会话一个容器 + workspace +- `agent`：每个智能体一个容器 + workspace（默认） +- `shared`：共享容器和 workspace（无跨会话隔离） **OpenShell 插件配置：** @@ -1507,29 +1540,29 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad **OpenShell 模式：** -- `mirror`：在执行前从本地初始化远程，执行后同步回本地；本地工作区保持为规范状态 -- `remote`：在创建沙箱时仅初始化远程一次，之后保持远程工作区为规范状态 +- `mirror`：在执行前从本地初始化远程，执行后再同步回来；本地 workspace 保持为规范副本 +- `remote`：在创建沙箱时仅初始化远程一次，之后保持远程 workspace 为规范副本 -在 `remote` 模式下，在 OpenClaw 外部于主机本地进行的编辑，不会在初始化步骤之后自动同步到沙箱中。 -传输方式是通过 SSH 进入 OpenShell 沙箱，但沙箱生命周期和可选的镜像同步由插件负责。 +在 `remote` 模式下，于初始化步骤之后在 OpenClaw 外部对主机本地所做的编辑，不会自动同步到沙箱中。 +传输方式是通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期和可选 mirror 同步的控制权。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。它需要网络出口、可写根文件系统以及 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 **容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急开关）。 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗模式）。 -**传入附件** 会被暂存到活动工作区中的 `media/inbound/*`。 +**传入附件** 会被暂存到当前活动 workspace 中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。 +**`docker.binds`** 会挂载其他主机目录；全局和按智能体的绑定会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 -默认情况下，noVNC 观察者访问使用 VNC 认证，OpenClaw 会发出一个短期有效的 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示。不需要在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。 -- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 +- `allowHostControl: false`（默认）会阻止沙箱隔离会话将目标指向主机浏览器。 - `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连通性时，才设置为 `bridge`。 -- `cdpSourceRange` 可选地在容器边界将 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替代浏览器容器的 `docker.binds`。 +- `cdpSourceRange` 可选，用于在容器边界将 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱隔离浏览器容器中。设置后（包括 `[]`），它会替代浏览器容器的 `docker.binds`。 - 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机做了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` @@ -1549,20 +1582,20 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad - `--metrics-recording-only` - `--disable-extensions`（默认启用） - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用；如果 WebGL/3D 使用场景需要，可通过 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用它们。 + 默认启用；如果 WebGL / 3D 使用场景需要，可通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 将其禁用。 - 如果你的工作流 - 依赖扩展，可通过 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。 + 依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展。 - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 会使用 Chromium 的 - 默认进程上限。 - - 另外，当启用 `noSandbox` 时，还会附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带自定义 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的 + 默认进程限制。 + - 此外，当启用 `noSandbox` 时，还会附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值属于容器镜像基线；如需更改容器默认行为，请使用带有自定义 入口点的自定义浏览器镜像。 -浏览器沙箱隔离和 `sandbox.docker.binds` 仅支持 Docker。 +浏览器沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。 构建镜像： @@ -1587,6 +1620,7 @@ scripts/sandbox-browser-setup.sh # optional browser image thinkingDefault: "high", // per-agent thinking level override reasoningDefault: "on", // per-agent reasoning visibility override fastModeDefault: false, // per-agent fast mode override + embeddedHarness: { runtime: "auto", fallback: "pi" }, params: { cacheRetention: "none" }, // overrides matching defaults.models params by key skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { @@ -1620,25 +1654,26 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`：稳定的智能体 ID（必填）。 -- `default`：设置多个时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个条目为默认值。 -- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局回退）。仅覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 -- `params`：按智能体设置的流参数，会合并覆盖到 `agents.defaults.models` 中所选模型条目之上。用它来做智能体特定的覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。若省略，则在已设置时继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置按消息或会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或会话级 reasoning 覆盖时适用。 -- `fastModeDefault`：可选的按智能体默认快速模式（`true | false`）。当未设置按消息或会话级快速模式覆盖时适用。 -- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 并配合 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 -- `identity.avatar`：相对于工作区的路径、`http(s)` URL 或 `data:` URI。 -- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 +- `default`：如果设置了多个，则第一个生效（会记录警告）。如果一个都未设置，则列表中的第一个条目为默认值。 +- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局回退）。仅覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 +- `params`：按智能体的流参数，会合并覆盖 `agents.defaults.models` 中选定模型条目。用它可为特定智能体覆盖 `cacheRetention`、`temperature` 或 `maxTokens` 等参数，而无需复制整个模型目录。 +- `skills`：可选的按智能体 Skills 允许列表。若省略，则该智能体会在已设置时继承 `agents.defaults.skills`；显式列表会替代默认值而不是合并，`[]` 表示不启用任何 Skills。 +- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置按消息或按会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。 +- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。在未设置按消息或按会话 reasoning 覆盖时生效。 +- `fastModeDefault`：可选的按智能体 fast mode 默认值（`true | false`）。在未设置按消息或按会话 fast-mode 覆盖时生效。 +- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某一个智能体仅使用 Codex，而其他智能体继续保留默认 PI 回退。 +- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `identity.avatar`：workspace 相对路径、`http(s)` URL 或 `data:` URI。 +- `identity` 会推导默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name` / `emoji`。 - `subagents.allowAgents`：`sessions_spawn` 可用的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱隔离继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱隔离方式运行的目标。 -- `subagents.requireAgentId`：为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。 +- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。 +- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关中运行多个相互隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关内运行多个相互隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1657,12 +1692,12 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 绑定匹配字段 -- `type`（可选）：`route` 表示普通路由（缺失时默认是 route），`acp` 表示持久 ACP 会话绑定。 +- `type`（可选）：正常路由使用 `route`（未指定 type 时默认为 route），持久 ACP 对话绑定使用 `acp`。 - `match.channel`（必填） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；渠道特定） -- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId`（可选；特定渠道） +- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1670,16 +1705,16 @@ scripts/sandbox-browser-setup.sh # optional browser image 2. `match.guildId` 3. `match.teamId` 4. `match.accountId`（精确匹配，无 peer/guild/team） -5. `match.accountId: "*"`（全渠道） +5. `match.accountId: "*"`（整个渠道范围） 6. 默认智能体 -在每个层级内，首个匹配的 `bindings` 条目获胜。 +在每一层内，首个匹配的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上述 route 绑定分层顺序。 -### 按智能体的访问配置文件 +### 按智能体访问配置 - + ```json5 { @@ -1697,7 +1732,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1726,7 +1761,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1772,7 +1807,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -优先级详情请参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1826,34 +1861,34 @@ scripts/sandbox-browser-setup.sh # optional browser image - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在某个渠道上下文内，每个发送者都有独立会话。 - - `global`：某个渠道上下文中的所有参与者共享同一个会话（仅在确实需要共享上下文时使用）。 -- **`dmScope`**：私信的分组方式。 + - `per-sender`（默认）：在某个渠道上下文内，每个发送者拥有独立会话。 + - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在明确需要共享上下文时使用）。 +- **`dmScope`**：私信如何分组。 - `main`：所有私信共享主会话。 - `per-peer`：按发送者 ID 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 ID 映射到带提供商前缀的 peer，用于跨渠道会话共享。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。如果两者都已配置，以先到期者为准。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名接受。 -- **`parentForkMaxTokens`**：创建分叉线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。 - - 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父转录历史。 - - 设置为 `0` 可禁用此保护，并始终允许父会话分叉。 +- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端标识，以实现跨渠道会话共享。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都配置时，以先到期者为准。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍接受为 `direct` 的别名。 +- **`parentForkMaxTokens`**：创建分叉线程会话时，允许父会话 `totalTokens` 的最大值（默认 `100000`）。 + - 如果父会话 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父转录历史。 + - 设为 `0` 可禁用此保护，并始终允许父会话分叉。 - **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间相互通信时允许的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 会禁用乒乓式链式回复。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。首个拒绝规则优先。 +- **`agentToAgent.maxPingPongTurns`**：智能体之间交换期间，彼此回传的最大轮数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式往返。 +- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版别名为 `dm`）、`keyPrefix` 或 `rawKeyPrefix` 匹配。首个 deny 生效。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 仅发出警告；`enforce` 会实际执行清理。 - - `pruneAfter`：过期条目的年龄截止值（默认 `30d`）。 + - `mode`：`warn` 仅发出警告；`enforce` 则实际执行清理。 + - `pruneAfter`：陈旧条目的时间裁剪阈值（默认 `30d`）。 - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认等于 `pruneAfter`；设置为 `false` 可禁用。 - - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的制品/会话。 + - `rotateBytes`：当 `sessions.json` 超过该大小时轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下仅记录警告；在 `enforce` 模式下会优先移除最旧的产物 / 会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认的非活动自动取消聚焦小时数（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认的硬性最大存续时长（小时）（`0` 表示禁用；提供商可覆盖） + - `idleHours`：以小时为单位的默认非活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：以小时为单位的默认硬性最大存活时长（`0` 表示禁用；提供商可覆盖） @@ -1891,9 +1926,9 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 回复前缀 -按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +按渠道 / 账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 +解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止继续回退。`"auto"` 会推导为 `[{identity.name}]`。 **模板变量：** @@ -1903,24 +1938,24 @@ scripts/sandbox-browser-setup.sh # optional browser image | `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | | `{provider}` | 提供商名称 | `anthropic` | | `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| `{identity.name}` | 智能体 identity 名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 -### 确认反应 +### 确认 reaction -- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设置 `""` 可禁用。 +- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退值。 +- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 - 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，会在回复后移除确认反应。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则状态反应保持启用。 - 在 Telegram 上，需要显式将其设为 `true` 才会启用生命周期状态反应。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认 reaction。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reaction。 + 在 Slack 和 Discord 上，未设置时，如果确认 reaction 处于活动状态，则会保持状态 reaction 启用。 + 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态 reaction。 ### 入站防抖 -将来自同一发送者的快速连续纯文本消息合并为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 +将来自同一发送者的快速纯文本消息批处理为一个智能体回合。媒体 / 附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1963,18 +1998,18 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，`/tts status` 会显示生效状态。 +- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，而 `/tts status` 会显示生效状态。 - `summaryModel` 会覆盖自动摘要所用的 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认值为 `false`（需显式选择加入）。 -- API 密钥会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置值，然后 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 -- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容 TTS 服务器，并放宽模型/语音校验。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认是 `false`（需显式选择加入）。 +- API key 会回退到 `ELEVENLABS_API_KEY` / `XI_API_KEY` 和 `OPENAI_API_KEY`。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置值，然后 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型 / 语音校验。 --- ## Talk -Talk 模式（macOS/iOS/Android）的默认值。 +Talk 模式（macOS / iOS / Android）的默认值。 ```json5 { @@ -1998,51 +2033,51 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- 当配置了多个 Talk 提供商时，`talk.provider` 必须与 `talk.providers` 中的某个键匹配。 -- 旧版平铺 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 +- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容性，并会自动迁移到 `talk.providers.`。 - Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 -- `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- `ELEVENLABS_API_KEY` 回退仅在未配置任何 Talk API 密钥时生效。 -- `providers.*.voiceAliases` 让 Talk 指令可使用易读名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久才发送转录。未设置时，保持平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- `providers.*.apiKey` 可接受明文字符串或 SecretRef 对象。 +- 仅当未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送转录。未设置时会保持平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- ## 工具 -### 工具配置文件 +### 工具配置 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： +`tools.profile` 会在 `tools.allow` / `tools.deny` 之前设置基础允许列表： -本地新手引导会在未设置时将新的本地配置默认为 `tools.profile: "coding"`（现有的显式配置文件会保留）。 +本地新手引导会在未设置时将新的本地配置默认设为 `tools.profile: "coding"`（已有的显式配置会保留）。 -| 配置文件 | 包含 | -| ----------- | --------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | -| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | -| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | -| `full` | 不限制（与未设置相同） | +| 配置 | 包含内容 | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | 仅 `session_status` | +| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | +| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | +| `full` | 不限制（与未设置相同） | ### 工具组 -| 组 | 工具 | -| ------------------ | --------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | -| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | -| `group:memory` | `memory_search`、`memory_get` | -| `group:web` | `web_search`、`x_search`、`web_fetch` | -| `group:ui` | `browser`、`canvas` | -| `group:automation` | `cron`、`gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不包括提供商插件） | +| 组 | 工具 | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | +| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | +| `group:memory` | `memory_search`、`memory_get` | +| `group:web` | `web_search`、`x_search`、`web_fetch` | +| `group:ui` | `browser`、`canvas` | +| `group:automation` | `cron`、`gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | +| `group:openclaw` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱隔离关闭，也会生效。 +全局工具允许 / 拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会生效。 ```json5 { @@ -2052,7 +2087,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.byProvider` -进一步限制特定提供商或模型可用的工具。顺序：基础配置文件 → 提供商配置文件 → allow/deny。 +进一步限制特定提供商或模型的工具。顺序：基础配置 → 提供商配置 → allow / deny。 ```json5 { @@ -2068,7 +2103,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.elevated` -控制沙箱隔离之外的 elevated `exec` 访问： +控制沙箱外的 elevated `exec` 访问： ```json5 { @@ -2085,8 +2120,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 ``` - 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅对单条消息生效。 -- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或者当 exec 目标是 `node` 时使用 `node`）。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 +- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。 ### `tools.exec` @@ -2110,8 +2145,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.loopDetection` -工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。 -设置可在全局 `tools.loopDetection` 中定义，并可在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 +工具循环安全检查**默认关闭**。设置 `enabled: true` 以启用检测。 +设置可在全局 `tools.loopDetection` 中定义，并可按智能体在 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -2132,13 +2167,13 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- `historySize`：为循环分析保留的最大工具调用历史数。 -- `warningThreshold`：触发警告的重复无进展模式阈值。 +- `historySize`：为循环分析保留的最大工具调用历史。 +- `warningThreshold`：重复无进展模式触发警告的阈值。 - `criticalThreshold`：用于阻止严重循环的更高重复阈值。 -- `globalCircuitBreakerThreshold`：对任何无进展运行的硬停止阈值。 -- `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展轮询发出警告/阻止。 -- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 +- `globalCircuitBreakerThreshold`：任意无进展运行的硬停止阈值。 +- `detectors.genericRepeat`：对重复调用相同工具 / 相同参数发出警告。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告 / 阻止。 +- `detectors.pingPong`：对交替出现的无进展成对模式发出警告 / 阻止。 - 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 ### `tools.web` @@ -2173,7 +2208,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.media` -配置入站媒体理解（图像/音频/视频）： +配置入站媒体理解（图像 / 音频 / 视频）： ```json5 { @@ -2209,9 +2244,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 **提供商条目**（`type: "provider"` 或省略）： -- `provider`：API 提供商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） +- `provider`：API 提供商 ID（`openai`、`anthropic`、`google` / `gemini`、`groq` 等） - `model`：模型 ID 覆盖 -- `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 +- `profile` / `preferredProfile`：`auth-profiles.json` 配置选择 **CLI 条目**（`type: "cli"`）： @@ -2220,7 +2255,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 **通用字段：** -- `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 +- `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai` / `anthropic` / `minimax` → image，`google` → image+audio+video，`groq` → audio。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 - 失败时会回退到下一个条目。 @@ -2229,8 +2264,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 **异步完成字段：** - `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会优先尝试直接投递到渠道。默认值：`false` - （旧版请求方会话唤醒/模型投递路径）。 + 和 `video_generate` 任务会先尝试直接交付到渠道。默认值：`false` + （旧版请求方会话唤醒 / 模型交付路径）。 @@ -2249,9 +2284,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.sessions` -控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以定位哪些会话。 +控制 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）可以将哪些会话作为目标。 -默认值：`tree`（当前会话 + 由其产生的会话，例如子智能体）。 +默认值：`tree`（当前会话 + 由其派生出的会话，例如子智能体）。 ```json5 { @@ -2264,13 +2299,13 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -注意： +说明： - `self`：仅当前会话键。 -- `tree`：当前会话 + 由当前会话产生的会话（子智能体）。 -- `agent`：属于当前智能体 ID 的任意会话（如果你在同一个智能体 ID 下运行按发送者隔离的会话，则可能包含其他用户）。 -- `all`：任意会话。跨智能体定位仍然要求 `tools.agentToAgent`。 -- 沙箱隔离钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- `tree`：当前会话 + 由当前会话派生出的会话（子智能体）。 +- `agent`：属于当前智能体 ID 的任意会话（如果你在同一智能体 ID 下运行按发送者划分的会话，可能包含其他用户）。 +- `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。 +- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2292,18 +2327,18 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -注意： +说明： -- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会实体化到子工作区的 `.openclaw/attachments//` 中，并带有 `.manifest.json`。 +- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。 +- 文件会实体化到子 workspace 的 `.openclaw/attachments//` 中，并带有 `.manifest.json`。 - 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会使用严格的字母表/填充校验，以及解码前大小保护。 -- 文件权限：目录为 `0700`，文件为 `0600`。 -- 清理由 `cleanup` 策略控制：`delete` 始终删除附件；仅当 `retainOnSessionKeep: true` 时，`keep` 才会保留它们。 +- Base64 输入会执行严格字母表 / 填充校验，并带有解码前大小保护。 +- 目录权限为 `0700`，文件权限为 `0600`。 +- 清理由 `cleanup` 策略决定：`delete` 始终移除附件；仅当 `retainOnSessionKeep: true` 时，`keep` 才会保留它们。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非适用某条运行时特定的自动启用规则。 +实验性内置工具标志。默认关闭，除非某条运行时特定自动启用规则适用。 ```json5 { @@ -2315,11 +2350,11 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -注意： +说明： - `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：对非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行在未设置时会自动启用它；设为 `false` 可禁用该自动启用。 -- 启用后，系统提示还会添加使用指导，以便模型仅在实质性工作中使用它，并始终保持最多一个步骤处于 `in_progress`。 +- 默认值：对于非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行在未设置时会自动启用它；设为 `false` 可禁用该自动启用。 +- 启用时，系统提示还会添加使用指导，以便模型仅在重要工作中使用它，并且最多只保留一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -2339,10 +2374,10 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- `model`：生成的子智能体所使用的默认模型。若省略，子智能体会继承调用方模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 允许的目标智能体 ID 默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时时间（秒）。`0` 表示无超时。 -- 按子智能体的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- `model`：派生子智能体的默认模型。若省略，子智能体会继承调用方模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 的默认目标智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。 +- 按子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- @@ -2377,48 +2412,48 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 使用 `authHeader: true` + `headers` 来满足自定义认证需求。 +- 对于自定义认证需求，使用 `authHeader: true` + `headers`。 - 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 对于匹配的提供商 ID，合并优先级如下： +- 匹配提供商 ID 的合并优先级： - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在该提供商在当前配置/auth-profile 上下文中不受 SecretRef 管理时优先。 - - 受 SecretRef 管理的提供商 `apiKey` 值会根据源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化解析后的密钥。 - - 受 SecretRef 管理的提供商 header 值会根据源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 - - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高者。 - - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；使用它可以在不更改原生模型元数据的情况下限制有效上下文。 - - 当你希望配置完全重写 `models.json` 时，请使用 `models.mode: "replace"`。 - - 标记持久化以来源为权威：标记从活动源配置快照（解析前）写入，而不是从解析后的运行时密钥值写入。 + - 非空的智能体 `apiKey` 值仅在该提供商在当前 config / auth-profile 上下文中不是由 SecretRef 管理时优先。 + - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用用 `ENV_VAR_NAME`，文件 / exec 引用用 `secretref-managed`），而不是持久化已解析的 secret。 + - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用用 `secretref-env:ENV_VAR_NAME`，文件 / exec 引用用 `secretref-managed`）。 + - 空或缺失的智能体 `apiKey` / `baseUrl` 会回退到配置中的 `models.providers`。 + - 匹配模型的 `contextWindow` / `maxTokens` 会在显式配置值和隐式目录值之间取较高值。 + - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；用它可在不更改原生模型元数据的情况下限制有效上下文。 + - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 + - 标记持久化以源为准：标记写入自当前激活的源配置快照（解析前），而不是来自已解析的运行时 secret 值。 ### 提供商字段详情 - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：按提供商 ID 键控的自定义提供商映射。 +- `models.providers`：按提供商 ID 作为键的自定义提供商映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 +- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef / 环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`：用于 Ollama + `openai-completions` 时，将 `options.num_ctx` 注入请求（默认：`true`）。 +- `models.providers.*.injectNumCtxForOpenAICompat`：用于 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求（默认：`true`）。 - `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 -- `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。 +- `models.providers.*.headers`：用于代理 / 租户路由的额外静态 headers。 - `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 - - `request.headers`：额外 headers（与提供商默认值合并）。值接受 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。 - - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 - - `request.tls`：直接连接的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均接受 SecretRef）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`：为 `true` 时，当 DNS 将 `baseUrl` 解析为私有、CGNAT 或类似地址范围时，允许通过提供商 HTTP 获取保护访问 HTTPS（这是针对受信任自托管 OpenAI 兼容端点的 operator 选择加入项）。WebSocket 会为 headers/TLS 使用同一个 `request`，但不会使用该获取 SSRF 防护。默认值为 `false`。 + - `request.headers`：额外 headers（与提供商默认值合并）。值可接受 SecretRef。 + - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value` 和可选的 `prefix`）。 + - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 + - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均接受 SecretRef）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`：为 `true` 时，当 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似网段时，通过提供商 HTTP 抓取保护允许访问该 HTTPS 地址（面向受信任自托管 OpenAI 兼容端点的 operator 显式选择加入）。WebSocket 会对 headers / TLS 使用同一个 `request`，但不适用该抓取 SSRF 防护。默认值为 `false`。 - `models.providers.*.models`：显式提供商模型目录条目。 - `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。 -- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容提示。对于 `api: "openai-completions"` 且非空、非原生 `baseUrl`（主机不是 `api.openai.com`），OpenClaw 会在运行时强制将其设为 `false`。空或省略的 `baseUrl` 会保留默认 OpenAI 行为。 -- `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串的 OpenAI 兼容聊天端点的可选兼容提示。为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组压平成普通字符串。 -- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根。 -- `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式发现。 +- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你想让有效上下文预算小于模型原生 `contextWindow` 时使用它。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空非原生值（主机不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空或省略的 `baseUrl` 会保留默认 OpenAI 行为。 +- `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串的 OpenAI 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组压平为普通字符串。 +- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根路径。 +- `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启 / 关闭隐式发现。 - `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：可选的 provider ID 过滤器，用于定向发现。 -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新轮询间隔。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的后备上下文窗口。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的后备最大输出 token 数。 +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选提供商 ID 过滤器。 +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新的轮询间隔。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。 ### 提供商示例 @@ -2473,7 +2508,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录使用 `opencode/...` 引用，Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 +设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录请使用 `opencode/...` 引用，Go 目录请使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 @@ -2494,7 +2529,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` - 通用端点：`https://api.z.ai/api/paas/v4` - 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 如需使用通用端点，请定义带有 base URL 覆盖的自定义提供商。 +- 若要使用通用端点，请定义一个带有 base URL 覆盖的自定义提供商。 @@ -2533,11 +2568,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -对于中国端点：使用 `baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 +中国区端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 原生 Moonshot 端点会在共享的 -`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 会根据端点能力 -而不仅仅是内置 provider ID 来判断这一点。 +`openai-completions` 传输上声明流式传输用法兼容性，而 OpenClaw 会基于端点能力 +而不只是内置提供商 ID 来判断这一点。 @@ -2594,7 +2629,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 +Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 @@ -2638,15 +2673,16 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 模型目录默认仅包含 M2.7。 -在 Anthropic 兼容的流式路径上，除非你显式设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。 -`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 +在兼容 Anthropic 的流式传输路径上，OpenClaw 默认会禁用 MiniMax thinking， +除非你显式自行设置 `thinking`。`/fast on` 或 +`params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能足够强的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型用于回退。 @@ -2677,12 +2713,13 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。 -- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 -- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后再回退到其他安装器类型。 -- `install.nodeManager`：`metadata.openclaw.install` 规范所用的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使某个技能已内置/已安装，也将其禁用。 -- `entries..apiKey`：为声明了主环境变量的技能提供便利配置（明文字符串或 SecretRef 对象）。 +- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管 / workspace Skills 不受影响）。 +- `load.extraDirs`：额外的共享 Skills 根目录（最低优先级）。 +- `install.preferBrew`：为 true 时，若 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。 +- `install.nodeManager`：用于 `metadata.openclaw.install` + 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 Skill 已内置 / 已安装，也会将其禁用。 +- `entries..apiKey`：为声明了主环境变量的 Skills 提供便捷配置（明文字符串或 SecretRef 对象）。 --- @@ -2711,40 +2748,40 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现支持原生 OpenClaw 插件以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- 设备发现可接受原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，其中包括无 manifest 的 Claude 默认布局 bundles。 - **配置变更需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API 密钥便捷字段（在插件支持时可用）。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 以及受支持的 bundle 提供的 hook 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可用的规范 `provider/model` 目标可选允许列表。仅当你明确希望允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（若可用，则由原生 OpenClaw 插件 schema 验证）。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web 获取提供商设置。 - - `apiKey`：Firecrawl API 密钥（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 以及受支持 bundle 提供的 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可以为后台子智能体运行请求按次的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的可选规范 `provider/model` 目标允许列表。仅当你明确要允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 进行验证）。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。 + - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。 - `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。 - `onlyMainContent`：仅提取页面主体内容（默认：`true`）。 - `maxAgeMs`：最大缓存年龄（毫秒）（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。 + - `timeoutSeconds`：抓取请求超时秒数（默认：`60`）。 - `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 - `enabled`：启用 X Search 提供商。 - - `model`：搜索使用的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：memory dreaming（实验性）设置。有关阶段和阈值，请参见 [Dreaming](/zh-CN/concepts/dreaming)。 - - `enabled`：dreaming 总开关（默认 `false`）。 - - `frequency`：每次完整 dreaming 扫描的 cron 周期（默认 `"0 3 * * *"`）。 + - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 +- `plugins.entries.memory-core.config.dreaming`：memory dreaming（实验性）设置。各阶段与阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。 + - `enabled`：dreaming 主开关（默认 `false`）。 + - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整的 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)： +- 完整 memory 配置见 [Memory configuration reference](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供内嵌 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活动的 memory 插件 ID，或设为 `"none"` 以禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择活动的上下文引擎插件 ID；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 +- 已启用的 Claude bundle 插件还可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已清洗的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动 memory 插件 ID，或使用 `"none"` 禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 + - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 + - 请将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令，而不是手动编辑。 参见 [Plugins](/zh-CN/tools/plugin)。 @@ -2788,24 +2825,23 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 - `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用，因此浏览器导航默认保持严格模式。 -- 仅在你明确可信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止策略约束。 -- `ssrfPolicy.allowPrivateNetwork` 仍然作为旧版别名受支持。 -- 在严格模式下，请使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。 -- 远程配置文件为仅附加模式（禁用 start/stop/reset）。 +- 仅当你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP profile 端点（`profiles.*.cdpUrl`）在可达性 / 设备发现检查期间也会受到相同的私有网络阻止策略约束。 +- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。 +- 远程 profiles 为仅附加模式（禁用 start / stop / reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；当提供商直接提供 DevTools WebSocket URL 时，请使用 WS(S)。 -- `existing-session` 配置文件仅支持主机，并使用 Chrome MCP 而不是 CDP。 -- `existing-session` 配置文件可以设置 `userDataDir`，以定位特定的 - Chromium 系浏览器配置文件，例如 Brave 或 Edge。 -- `existing-session` 配置文件保留当前 Chrome MCP 路由限制： - 使用基于快照/ref 的操作，而不是 CSS 选择器定位；单文件上传 - hook；不支持对话框超时覆盖；不支持 `wait --load networkidle`，也不支持 + 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；当提供商直接给出 DevTools WebSocket URL 时，请使用 WS(S)。 +- `existing-session` profiles 仅适用于主机，并使用 Chrome MCP 而不是 CDP。 +- `existing-session` profiles 可以设置 `userDataDir` 以定位特定的 + Chromium 系浏览器 profile，例如 Brave 或 Edge。 +- `existing-session` profiles 保留当前 Chrome MCP 路由限制： + 使用 snapshot / ref 驱动的操作而不是 CSS 选择器定向、单文件上传 + hooks、无对话框超时覆盖、无 `wait --load networkidle`，以及不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在 - 远程 CDP 场景下显式设置 `cdpUrl`。 -- 自动检测顺序：如果默认浏览器是 Chromium 系则优先默认浏览器 → Chrome → Brave → Edge → Chromium → Chrome Canary。 -- 控制服务：仅 loopback（端口由 `gateway.port` 推导，默认 `18791`）。 +- 本地受管 `openclaw` profiles 会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下显式设置 `cdpUrl`。 +- 自动检测顺序：默认浏览器（若为 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅绑定 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 - `extraArgs` 会将额外启动标志附加到本地 Chromium 启动参数中（例如 `--disable-gpu`、窗口大小设置或调试标志）。 @@ -2825,8 +2861,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 -- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。 +- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡色调等）。 +- `assistant`：Control UI identity 覆盖。未设置时回退到当前活动智能体 identity。 --- @@ -2893,64 +2929,64 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 +- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 - `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 -- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 说明**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或使用 `bind: "custom"` 并设置 `customBindHost: "0.0.0.0"`）以在所有接口上监听。 -- **认证**：默认必需。非 loopback bind 要求 Gateway 网关认证。实际使用中，这意味着共享 token/password，或带有 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设置为 `token` 或 `password`。如果两者都已配置但 mode 未设置，启动以及服务安装/修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份 header（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。该模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 header 可用于满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用这种 Tailscale header 认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥和设备 token 会分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，相同 `{scope, clientIp}` 的失败尝试会在写入失败记录之前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都作为普通不匹配而直接通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；当你明确希望 localhost 流量也受到限流（用于测试设置或严格代理部署）时，可设为 `false`。 -- 来自浏览器源的 WS 认证尝试总会启用限流，并禁用 loopback 豁免（作为对基于浏览器的 localhost 暴力破解的纵深防御）。 +- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），而不是主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关不可访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **Auth**：默认必需。非 loopback bind 必须启用 Gateway 网关 auth。实际意味着需要共享 token / password，或使用配置了 `gateway.auth.mode: "trusted-proxy"` 的 identity-aware 反向代理。新手引导向导默认会生成 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。如果两者都已配置但 mode 未设置，启动和服务安装 / 修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无 auth 模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会提供此选项。 +- `gateway.auth.mode: "trusted-proxy"`：将 auth 委托给 identity-aware 反向代理，并信任来自 `gateway.trustedProxies` 的身份 headers（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 代理来源；同机 loopback 反向代理不满足 trusted-proxy auth 条件。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 headers 可满足 Control UI / WebSocket auth（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header auth；它们仍遵循 Gateway 网关正常的 HTTP auth 模式。此无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的 auth 失败限流器。按客户端 IP 和 auth 作用域生效（共享密钥和设备 token 会分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都作为普通不匹配同时穿过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；若你有意希望 localhost 流量也受到限流（用于测试设置或严格代理部署），请设为 `false`。 +- 来自浏览器源的 WS auth 尝试始终会在禁用 loopback 豁免的情况下进行限流（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 - 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin` - 值分别隔离，因此来自某个 localhost 源的重复失败不会自动 - 锁定另一个源。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开，需要认证）。 -- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当浏览器客户端来自非 loopback 源时必须设置。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为那些刻意依赖 Host header 源策略的部署启用 Host header 源回退。 + 值隔离，因此来自某个 localhost 来源的重复失败不会自动 + 锁住另一个来源。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开，需要 auth）。 +- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时必须设置。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host header 来源策略的部署启用基于 Host header 的来源回退。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧紧急开关覆盖，允许向受信任私有网络 IP 使用明文 `ws://`；默认仍仅允许在 loopback 上使用明文。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关之后所使用的外部 APNs relay 的基础 HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值为 `10000`。 -- 基于 relay 的注册会委托给特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将基于注册范围的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅开发环境使用的紧急开关，用于允许 loopback HTTP relay URL。生产 relay URL 应保持使用 HTTPS。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧破窗覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍然仅允许对 loopback 使用明文。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关 auth。 +- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方 / TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时（毫秒）。默认值：`10000`。 +- 基于 relay 的注册会委派给特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将带注册作用域的发送授权转发给 Gateway 网关。其他 Gateway 网关不能复用该已存储注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的逃生口，允许 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。 - `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内允许的最大健康监控重启次数。默认值：`10`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道 / 账号健康监控可执行的最大重启次数。默认值：`10`。 - `channels..healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保留全局监控启用。 -- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后优先于渠道级覆盖。 -- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可将 `gateway.remote.*` 用作回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析，则解析会失败关闭（不会被远程回退所掩盖）。 -- `trustedProxies`：用于终止 TLS 或注入转发客户端 header 的反向代理 IP。只应列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**使 loopback 请求满足 `gateway.auth.mode: "trusted-proxy"` 的资格。 -- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现默认拒绝行为。 -- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。 -- `gateway.tools.allow`：将工具名称从默认 HTTP 拒绝列表中移除。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，它优先于渠道级覆盖。 +- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可以将 `gateway.remote.*` 用作回退。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析，将以默认拒绝方式失败（不会由远程回退掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端 headers 的反向代理 IP。只列出你可控的代理。loopback 条目在同机代理 / 本地检测设置（例如 Tailscale Serve 或本地反向代理）中仍然有效，但它们**不会**使 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。 +- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以保持默认拒绝行为。 +- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认拒绝列表）。 +- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名。 ### OpenAI 兼容端点 -- Chat Completions：默认禁用。通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 +- Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 - Responses API：`gateway.http.endpoints.responses.enabled`。 - Responses URL 输入加固： - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 空允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 获取。 + 空允许列表会被视为未设置；如需禁用 URL 抓取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 和 / 或 `gateway.http.endpoints.responses.images.allowUrl=false`。 - 可选的响应加固 header： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一主机上运行多个 Gateway 网关，并使用唯一的端口和状态目录： +在同一主机上通过唯一端口和状态目录运行多个 Gateway 网关： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -2978,11 +3014,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 -- `autoGenerate`：在未配置显式文件时自动生成本地自签名证书/密钥对；仅适用于本地/开发环境。 +- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS / WSS）（默认：`false`）。 +- `autoGenerate`：在未配置显式文件时自动生成本地自签名证书 / 密钥对；仅适用于本地 / 开发用途。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；应限制权限。 -- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 +- `keyPath`：TLS 私钥文件的文件系统路径；应保持权限受限。 +- `caPath`：可选的 CA bundle 路径，用于客户端校验或自定义信任链。 ### `gateway.reload` @@ -2998,13 +3034,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制运行时如何应用配置编辑。 +- `mode`：控制配置编辑在运行时如何应用。 - `"off"`：忽略实时编辑；变更需要显式重启。 - `"restart"`：配置变更时始终重启 Gateway 网关进程。 - - `"hot"`：在进程内应用变更而不重启。 + - `"hot"`：进程内应用变更而不重启。 - `"hybrid"`（默认）：先尝试热重载；必要时回退到重启。 -- `debounceMs`：应用配置变更前的防抖窗口（毫秒）（非负整数）。 -- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最大时间（毫秒）（默认：`300000` = 5 分钟）。 +- `debounceMs`：应用配置变更前的防抖窗口（毫秒，非负整数）。 +- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最长时间（毫秒）（默认：`300000` = 5 分钟）。 --- @@ -3042,13 +3078,13 @@ openclaw gateway --port 19001 ``` 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -拒绝使用查询字符串中的 hook token。 +查询字符串中的 hook token 会被拒绝。 -验证与安全说明： +验证和安全说明： -- `hooks.enabled=true` 要求 `hooks.token` 为非空。 -- `hooks.token` 必须**不同于** `gateway.auth.token`；复用 Gateway 网关 token 会被拒绝。 -- `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。 +- `hooks.enabled=true` 需要非空的 `hooks.token`。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关 token 会被拒绝。 +- `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 - 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 **端点：** @@ -3060,18 +3096,18 @@ openclaw gateway --port 19001 -- `match.path` 会匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 会匹配通用路径中的某个负载字段。 -- `{{messages[0].subject}}` 之类的模板会从负载中读取值。 -- `transform` 可以指向一个返回 hook 操作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。 +- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 +- `match.source` 匹配通用路径中的某个负载字段。 +- 类似 `{{messages[0].subject}}` 的模板会从负载中读取。 +- `transform` 可以指向一个返回 hook action 的 JS / TS 模块。 + - `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 - `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 全部允许，`[]` = 全部拒绝）。 -- `defaultSessionKey`：可选固定会话键，用于未显式提供 `sessionKey` 的 hook 智能体运行。 +- `defaultSessionKey`：对于未显式提供 `sessionKey` 的 hook 智能体运行，可选的固定会话键。 - `allowRequestSessionKey`：允许 `/hooks/agent` 调用方设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：对显式 `sessionKey` 值（请求 + 映射）生效的可选前缀允许列表，例如 `["hook:"]`。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。 - `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认值为 `last`。 -- `model` 会覆盖该次 hook 运行所用的 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `model` 会覆盖此次 hook 运行的 LLM（如果设置了模型目录，则该模型必须被允许）。 @@ -3099,7 +3135,7 @@ openclaw gateway --port 19001 ``` - 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 -- 不要在 Gateway 网关旁边单独运行另一个 `gog gmail watch serve`。 +- 不要在 Gateway 网关旁边另外运行独立的 `gog gmail watch serve`。 --- @@ -3115,18 +3151,18 @@ openclaw gateway --port 19001 } ``` -- 通过 Gateway 网关端口下的 HTTP 提供由智能体可编辑的 HTML/CSS/JS 和 A2UI： +- 通过 Gateway 网关端口下的 HTTP 提供可由智能体编辑的 HTML / CSS / JS 和 A2UI： - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- 仅限本地：请保持 `gateway.bind: "loopback"`（默认）。 -- 对于非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面相同，需要 Gateway 网关认证（token/password/trusted-proxy）。 -- Node WebView 通常不会发送认证 header；在某个节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告节点作用域 capability URL。 -- Capability URL 会绑定到活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 -- 会将实时重载客户端注入到所提供的 HTML 中。 -- 为空时会自动创建起始 `index.html`。 +- 仅本地：保持 `gateway.bind: "loopback"`（默认）。 +- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 表面一样，需要 Gateway 网关 auth（token / password / trusted-proxy）。 +- Node WebView 通常不会发送 auth headers；当某个节点完成配对并连接后，Gateway 网关会广播节点作用域的 capability URL，用于访问 canvas / A2UI。 +- Capability URL 绑定到活动中的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 +- 会向已提供的 HTML 注入 live-reload 客户端。 +- 为空时会自动创建初始 `index.html`。 - 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 - 变更需要重启 Gateway 网关。 -- 对于大型目录或 `EMFILE` 错误，请禁用实时重载。 +- 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 --- @@ -3144,11 +3180,11 @@ openclaw gateway --port 19001 } ``` -- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。 +- `minimal`（默认）：在 TXT 记录中省略 `cliPath` + `sshPort`。 - `full`：包含 `cliPath` + `sshPort`。 - 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 -### 广域（DNS-SD） +### 广域网（DNS-SD） ```json5 { @@ -3158,7 +3194,7 @@ openclaw gateway --port 19001 } ``` -会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若要进行跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS 使用。 +在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 设置：`openclaw dns setup --apply`。 @@ -3184,13 +3220,13 @@ openclaw gateway --port 19001 ``` - 仅当进程环境中缺少该键时，才会应用内联环境变量。 -- `.env` 文件：当前工作目录中的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 -- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。 +- `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 +- `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 - 完整优先级请参见 [Environment](/zh-CN/help/environment)。 ### 环境变量替换 -可在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： +可在任意配置字符串中通过 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -3201,19 +3237,19 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/空环境变量会在加载配置时抛出错误。 -- 使用 `$${VAR}` 以表示字面量 `${VAR}`。 -- 与 `$include` 兼容。 +- 缺失 / 为空的变量会在加载配置时报错。 +- 用 `$${VAR}` 转义，以表示字面量 `${VAR}`。 +- 适用于 `$include`。 --- -## 密钥 +## Secrets -SecretRef 是增量式的：明文值仍然可用。 +Secret refs 为增量能力：明文值仍然可用。 ### `SecretRef` -使用以下对象形状之一： +使用一种对象形状： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3225,15 +3261,15 @@ SecretRef 是增量式的：明文值仍然可用。 - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` 的 id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） - `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` 的 id 不能包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝） +- `source: "exec"` 的 id 不得包含 `.` 或 `..` 这样的按斜杠分隔路径段（例如 `a/../b` 会被拒绝） -### 支持的凭证面 +### 支持的凭证表面 - 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) -- `secrets apply` 会定位到受支持的 `openclaw.json` 凭证路径。 -- `auth-profiles.json` 引用也包含在运行时解析和审计覆盖中。 +- `secrets apply` 会针对受支持的 `openclaw.json` 凭证路径执行。 +- `auth-profiles.json` refs 也包含在运行时解析和审计覆盖范围内。 -### 密钥提供商配置 +### Secret providers 配置 ```json5 { @@ -3261,19 +3297,19 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -注意： +说明： -- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。 -- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。 -- 默认会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可在验证解析后的目标路径时允许符号链接路径。 +- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- `exec` provider 要求使用绝对 `command` 路径，并通过 stdin / stdout 使用协议负载。 +- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证解析后的目标路径。 - 如果配置了 `trustedDirs`，受信任目录检查会作用于解析后的目标路径。 -- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传递所需变量。 -- SecretRef 会在激活时解析到内存快照中，之后请求路径只读取该快照。 -- 激活期间会应用活动面过滤：已启用面上的未解析引用会导致启动/重载失败，而不活跃的面会被跳过并给出诊断信息。 +- `exec` 子进程环境默认最小化；请使用 `passEnv` 显式传递所需变量。 +- Secret refs 会在激活时解析为内存中的快照，之后请求路径仅读取该快照。 +- 激活期间会应用活动表面过滤：已启用表面上的未解析 refs 会导致启动 / 重载失败，而非活动表面会被跳过并附带诊断信息。 --- -## 凭证存储 +## Auth 存储 ```json5 { @@ -3292,9 +3328,9 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - 按智能体的配置文件存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 对静态凭证模式支持值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- `auth-profiles.json` 对静态凭证模式支持值级 refs（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 - OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自已解析的内存快照；发现旧版静态 `auth.json` 条目时会将其清除。 +- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会将其清理。 - 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。 - 参见 [OAuth](/zh-CN/concepts/oauth)。 - Secrets 运行时行为以及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。 @@ -3319,20 +3355,20 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `billingBackoffHours`：当某个配置文件因真正的 - 计费/余额不足错误而失败时的基础退避时长（小时）（默认：`5`）。显式的计费文本 - 即使出现在 `401`/`403` 响应中，也可能走到这里，但提供商特定的文本 - 匹配器仍限定在拥有它们的提供商内（例如 OpenRouter +- `billingBackoffHours`：当某个配置文件因真实 + 计费 / 余额不足错误而失败时的基础退避小时数（默认：`5`）。即使在 `401` / `403` 响应上， + 明确的计费文本仍可能归入这里，但提供商特定的文本 + 匹配器仍只作用于拥有它们的提供商（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或 - 组织/工作区支出上限消息则仍会进入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的按提供商计费退避小时数覆盖。 -- `billingMaxHours`：计费退避指数增长的上限（小时）（默认：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时长（分钟）（默认：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限（分钟）（默认：`60`）。 + organization / workspace 支出上限消息则仍归入 `rate_limit` 路径。 +- `billingBackoffHoursByProvider`：可选的按提供商覆盖计费退避小时数。 +- `billingMaxHours`：计费退避指数增长的小时数上限（默认：`24`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟数上限（默认：`60`）。 - `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认：`24`）。 -- `overloadedProfileRotations`：对于 overloaded 错误，在切换到模型回退之前，同一提供商 auth-profile 最多允许轮换的次数（默认：`1`）。例如 `ModelNotReadyException` 这类提供商繁忙形态会进入这里。 -- `overloadedBackoffMs`：在重试 overloaded 提供商/配置文件轮换前的固定延迟（毫秒）（默认：`0`）。 -- `rateLimitedProfileRotations`：对于 rate-limit 错误，在切换到模型回退之前，同一提供商 auth-profile 最多允许轮换的次数（默认：`1`）。该 rate-limit 桶包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 +- `overloadedProfileRotations`：在切换到模型回退之前，同一提供商下因 overloaded 错误而进行 auth-profile 轮换的最大次数（默认：`1`）。诸如 `ModelNotReadyException` 之类的提供商繁忙形态会归入这里。 +- `overloadedBackoffMs`：在重试 overloaded 提供商 / 配置文件轮换前的固定延迟（默认：`0`）。 +- `rateLimitedProfileRotations`：在切换到模型回退之前，同一提供商下因限流错误而进行 auth-profile 轮换的最大次数（默认：`1`）。该 rate-limit 类别包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -3352,13 +3388,13 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 -- 设置 `logging.file` 可使用固定路径。 -- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- 设置 `logging.file` 可使用稳定路径。 +- `consoleLevel` 在 `--verbose` 时会提升到 `debug`。 +- `maxFileBytes`：在抑制写入之前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- -## 诊断 +## Diagnostics ```json5 { @@ -3391,15 +3427,15 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：instrumentation 输出的总开关（默认：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 之类的通配符）。 -- `stuckSessionWarnMs`：当会话持续处于处理中状态时，用于发出卡住会话警告的年龄阈值（毫秒）。 +- `enabled`：检测输出的总开关（默认：`true`）。 +- `flags`：用于启用定向日志输出的标志字符串数组（支持类似 `"telegram.*"` 或 `"*"` 的通配符）。 +- `stuckSessionWarnMs`：当会话持续处于处理中状态时，发出卡住会话警告的年龄阈值（毫秒）。 - `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。 -- `otel.endpoint`：OTel 导出的收集器 URL。 +- `otel.endpoint`：用于 OTel 导出的收集器 URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据 headers。 -- `otel.serviceName`：资源属性使用的服务名称。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。 +- `otel.headers`：随 OTel 导出请求发送的额外 HTTP / gRPC 元数据 headers。 +- `otel.serviceName`：资源属性中的服务名称。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 logs 导出。 - `otel.sampleRate`：`0`–`1` 的 trace 采样率。 - `otel.flushIntervalMs`：周期性 telemetry 刷新间隔（毫秒）。 - `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。 @@ -3426,12 +3462,12 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `channel`：适用于 npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 -- `checkOnStart`：在 Gateway 网关启动时检查 npm 更新（默认：`true`）。 +- `channel`：npm / git 安装所使用的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 +- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。 - `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 -- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟小时数（默认：`6`；最大：`168`）。 -- `auto.stableJitterHours`：稳定渠道额外的分批发布扩散窗口小时数（默认：`12`；最大：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道检查的运行间隔（小时）（默认：`1`；最大：`24`）。 +- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟（小时）（默认：`6`；最大：`168`）。 +- `auto.stableJitterHours`：稳定渠道额外的发布分散窗口（小时）（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时）（默认：`1`；最大：`24`）。 --- @@ -3465,21 +3501,21 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - `enabled`：全局 ACP 功能开关（默认：`false`）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 -- `backend`：默认 ACP 运行时后端 ID（必须匹配某个已注册 ACP 运行时插件）。 -- `defaultAgent`：当生成操作未指定显式目标时，回退使用的 ACP 目标智能体 ID。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 允许列表；为空表示不增加额外限制。 -- `maxConcurrentSessions`：最大并发活跃 ACP 会话数。 +- `dispatch.enabled`：ACP 会话回合分发的独立开关（默认：`true`）。设为 `false` 可保留 ACP 命令可用，但阻止执行。 +- `backend`：默认 ACP 运行时 backend ID（必须匹配某个已注册的 ACP 运行时插件）。 +- `defaultAgent`：当 spawn 未指定显式目标时，ACP 的回退目标智能体 ID。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 允许列表；空值表示无额外限制。 +- `maxConcurrentSessions`：同时活跃的 ACP 会话最大数量。 - `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。 -- `stream.maxChunkChars`：在拆分流式分块投影前允许的最大块大小。 -- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 进行增量流式传输；`"final_only"` 会缓冲到轮次终止事件后再输出。 -- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前使用的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次投影的 assistant 输出最大字符数。 -- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行的最大字符数。 -- `stream.tagVisibility`：标签名称到布尔可见性覆盖的记录，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话工作进程在可清理前的空闲 TTL（分钟）。 -- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 +- `stream.maxChunkChars`：拆分流式块投影前的最大块大小。 +- `stream.repeatSuppression`：按回合抑制重复的状态 / 工具行（默认：`true`）。 +- `stream.deliveryMode`：`"live"` 增量流式传输；`"final_only"` 则缓冲到回合终止事件再输出。 +- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。 +- `stream.maxOutputChars`：每个 ACP 回合投影的 assistant 输出最大字符数。 +- `stream.maxSessionUpdateChars`：投影的 ACP 状态 / 更新行最大字符数。 +- `stream.tagVisibility`：流式事件中标签名到布尔可见性覆盖的记录。 +- `runtime.ttlMinutes`：ACP 会话 worker 在空闲后具备可清理资格前的 TTL（分钟）。 +- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。 --- @@ -3496,9 +3532,9 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - `cli.banner.taglineMode` 控制 banner 标语样式： - - `"random"`（默认）：轮换的有趣/季节性标语。 - - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 + - `"random"`（默认）：轮换的有趣 / 季节性标语。 + - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 + - `"off"`：不显示标语文本（仍显示 banner 标题 / 版本）。 - 若要隐藏整个 banner（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -3521,15 +3557,15 @@ SecretRef 是增量式的：明文值仍然可用。 --- -## 身份 +## Identity -请参见 [Agent defaults](#agent-defaults) 下 `agents.list` 的身份字段。 +请参见 [Agent defaults](#agent-defaults) 下 `agents.list` 的 identity 字段。 --- ## Bridge protocol（旧版节点，历史参考）（旧版，已移除） -当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可以剥离未知键）。 +当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可清理未知键）。 @@ -3569,11 +3605,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `sessionRetention`：在从 `sessions.json` 中修剪前，已完成的隔离 cron 运行会话保留多久。也控制已归档且被删除的 cron 转录的清理。默认值：`24h`；设为 `false` 可禁用。 -- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发修剪前的最大大小。默认值：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志修剪时保留的最新行数。默认值：`2000`。 -- `webhookToken`：用于 cron webhook `POST` 投递（`delivery.mode = "webhook"`）的 bearer token；若省略，则不会发送认证 header。 -- `webhook`：已弃用的旧版后备 webhook URL（http/https），仅用于仍然带有 `notify: true` 的已存储作业。 +- `sessionRetention`：在从 `sessions.json` 中清理完成的隔离 cron 运行会话之前保留多长时间。也控制已归档且被删除的 cron 转录清理。默认值：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发清理前的最大大小。默认值：`2_000_000` 字节。 +- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认值：`2000`。 +- `webhookToken`：用于 cron webhook POST 交付（`delivery.mode = "webhook"`）的 bearer token；若省略则不发送 auth header。 +- `webhook`：已弃用的旧版回退 webhook URL（http / https），仅用于仍保留 `notify: true` 的已存储作业。 ### `cron.retry` @@ -3589,11 +3625,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `maxAttempts`：一次性作业在瞬时错误下允许的最大重试次数（默认：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试使用的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 -- `retryOn`：会触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则重试所有瞬时错误类型。 +- `maxAttempts`：一次性作业在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试尝试的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。若省略，则会对所有瞬时错误类型进行重试。 -仅适用于一次性 cron 作业。周期性作业使用独立的失败处理方式。 +仅适用于一次性 cron 作业。周期性作业使用独立的失败处理逻辑。 ### `cron.failureAlert` @@ -3611,11 +3647,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：为 cron 作业启用失败提醒（默认：`false`）。 -- `after`：触发提醒前所需的连续失败次数（正整数，最小值：`1`）。 -- `cooldownMs`：同一作业重复提醒之间的最小间隔（毫秒）（非负整数）。 -- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 会向已配置的 webhook 发起 `POST`。 -- `accountId`：可选的账号或渠道 ID，用于限定提醒投递范围。 +- `enabled`：为 cron 作业启用失败告警（默认：`false`）。 +- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复告警之间的最小毫秒间隔（非负整数）。 +- `mode`：交付模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 则发送到已配置的 webhook。 +- `accountId`：用于限定告警交付范围的可选账号或渠道 ID。 ### `cron.failureDestination` @@ -3632,16 +3668,16 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 所有作业共享的 cron 失败通知默认目标。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。 -- `channel`：用于 announce 投递的渠道覆盖。`"last"` 会复用上一次已知投递渠道。 -- `to`：显式的 announce 目标或 webhook URL。webhook 模式下必填。 -- `accountId`：可选的投递账号覆盖。 -- 按作业的 `delivery.failureDestination` 会覆盖该全局默认值。 -- 当既未设置全局也未设置按作业的失败目标时，那些原本就通过 `announce` 投递的作业会在失败时回退到该主 announce 目标。 +- 所有作业共用的 cron 失败通知默认目标。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认是 `"announce"`。 +- `channel`：用于 announce 交付的渠道覆盖。`"last"` 会复用最后一次已知交付渠道。 +- `to`：显式 announce 目标或 webhook URL。webhook 模式下为必填。 +- `accountId`：可选的交付账号覆盖。 +- 按作业的 `delivery.failureDestination` 会覆盖此全局默认值。 +- 当全局和按作业的失败目标都未设置时，那些已通过 `announce` 进行交付的作业在失败时会回退到其主 announce 目标。 - `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。 -参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会被跟踪为 [background tasks](/zh-CN/automation/tasks)。 +参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [background tasks](/zh-CN/automation/tasks) 进行跟踪。 --- @@ -3649,34 +3685,34 @@ SecretRef 是增量式的：明文值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| 变量 | 说明 | -| ------------------ | ----------------------------------- | -| `{{Body}}` | 完整入站消息正文 | -| `{{RawBody}}` | 原始正文（无历史/发送者包装） | -| `{{BodyStripped}}` | 去除群组提及后的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 ID | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 新建会话时为 `"true"` | -| `{{MediaUrl}}` | 入站媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频转录 | -| `{{Prompt}}` | 为 CLI 条目解析后的媒体提示 | -| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力而为） | -| `{{GroupMembers}}` | 群组成员预览（尽力而为） | -| `{{SenderName}}` | 发送者显示名称（尽力而为） | -| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| 变量 | 说明 | +| ------------------ | --------------------------------- | +| `{{Body}}` | 完整入站消息正文 | +| `{{RawBody}}` | 原始正文（无历史记录 / 发送者包装） | +| `{{BodyStripped}}` | 去除群组提及后的正文 | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 ID | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 新建会话时为 `"true"` | +| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（image / audio / document / …） | +| `{{Transcript}}` | 音频转录 | +| `{{Prompt}}` | CLI 条目的已解析媒体提示 | +| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群组成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名称（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | | `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- -## 配置 include（`$include`） +## 配置包含（`$include`） -将配置拆分到多个文件中： +将配置拆分为多个文件： ```json5 // ~/.openclaw/openclaw.json @@ -3691,12 +3727,12 @@ SecretRef 是增量式的：明文值仍然可用。 **合并行为：** -- 单个文件：替换所在的对象。 +- 单文件：替换所在的包含对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在 include 之后合并（覆盖 include 中的值）。 -- 嵌套 include：最多 10 层深。 -- 路径：相对于发起 include 的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许。 -- 错误：对缺失文件、解析错误和循环 include 提供清晰的错误消息。 +- 同级键：在 includes 之后合并（覆盖已包含值）。 +- 嵌套 includes：最多 10 层深。 +- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径 / `../` 形式最终仍解析到该边界内时才允许。 +- 错误：对缺失文件、解析错误和循环 include 提供清晰报错。 --- diff --git a/docs/zh-CN/help/testing.md b/docs/zh-CN/help/testing.md index bc951e8a5..df056e4ed 100644 --- a/docs/zh-CN/help/testing.md +++ b/docs/zh-CN/help/testing.md @@ -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 ` 调整工作进程数量，或使用 `--concurrency 1` 回到旧的串行通道。 + - 直接在主机上运行由仓库支持的 QA 场景。 + - 默认并行运行多个选定场景，并使用隔离的 Gateway 网关工作进程，最多 64 个工作进程或所选场景数量。使用 `--concurrency ` 调整工作进程数，或使用 `--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 ` 会把路由后的 `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 ` 会针对该已提交 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=` 强制指定工作进程数（上限为 16）。 + - `OPENCLAW_E2E_WORKERS=` 强制设置工作进程数（上限为 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 `。 + - 图像探测：测试附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat `。 - 实现参考：`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: "" }]` 发送 - - 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 --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@'` - 说明： - - 该通道使用 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//agent/auth-profiles.json`（这就是实时测试里 “profile keys” 的含义） +- 按智能体划分的鉴权 profile：`~/.openclaw/agents//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.`，否则会跳过各项能力 - - 在修改 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 ...` -- 保留此脚本用于回归 / 调试工作流。之后可能还会再次需要它来验证 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 时有意失败，这样新类别就无法被静默跳过。 diff --git a/docs/zh-CN/plugins/sdk-agent-harness.md b/docs/zh-CN/plugins/sdk-agent-harness.md index 22add9aa9..8ada35be8 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: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 的已注册 Harness。 -2. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI Harness。 -3. `OPENCLAW_AGENT_RUNTIME=auto` 会让已注册的 Harness 查询其是否支持已解析的提供商/模型。 -4. 如果没有匹配的已注册 Harness，OpenClaw 会使用 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。 +强制使用插件 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)