From cdd3d2fa9ea9c83839145f86bf0f4129957dec2a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 21 Apr 2026 21:01:54 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/model-providers.md | 367 ++--- docs/zh-CN/gateway/configuration-reference.md | 1457 +++++++++-------- docs/zh-CN/help/testing.md | 808 ++++----- docs/zh-CN/providers/fireworks.md | 30 +- docs/zh-CN/providers/ollama.md | 112 +- docs/zh-CN/providers/openai.md | 138 +- docs/zh-CN/tools/image-generation.md | 124 +- 7 files changed, 1525 insertions(+), 1511 deletions(-) diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index 481b3d6b4..ffa87dad9 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -1,150 +1,149 @@ --- read_when: - - 你需要一份按提供商分别说明的模型设置参考文档 - - 你想要模型提供商的示例配置或 CLI 新手引导命令 -summary: 模型提供商概览，包含示例配置和 CLI 流程 + - 你需要一份按提供商逐一说明的模型设置参考。 + - 你想要模型提供商的示例配置或 CLI 新手引导命令。 +summary: 模型提供商概览，包含示例配置 + CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-04-21T08:24:19Z" + generated_at: "2026-04-21T20:53:28Z" model: gpt-5.4 provider: openai - source_hash: 6732ab672757579c09395583a0f7d110348c909d4e4ab1d2accad68ad054c636 + source_hash: 6cbb8c9caf148c8db124638a036503fc4d4d3cce947ad99cffdf68a137edaab7 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` 是运行时生效的上限。 -- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前将该输出合并到 `models.providers` 中。 -- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样基于通用环境变量的凭证探测和提供商变体就不需要加载插件运行时。当前核心中的其余环境变量映射现在只用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic 以 API key 优先的新手引导。 -- 提供商插件还可以通过 `normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`resolveThinkingProfile`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 和 `onModelSelected` 来拥有提供商运行时行为。 -- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录/工具行为特性、传输/缓存提示）。它不同于[公开 capability 模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。 -- 内置的 `codex` 提供商与内置 Codex 智能体 harness 配对使用。当你需要 Codex 自有登录、模型发现、原生线程恢复和 app-server 执行时，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍然会使用 OpenAI 提供商和标准 OpenClaw 提供商传输。仅使用 Codex 的部署可以通过设置 `agents.defaults.embeddedHarness.fallback: "none"` 来禁用自动 PI 回退；参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 +- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 +- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover) 中。 +- `models.providers.*.models[].contextWindow` 是模型原生元数据；`models.providers.*.models[].contextTokens` 是运行时生效的上限。 +- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前，将该输出合并到 `models.providers` 中。 +- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样通用的基于环境变量的凭证探测和提供商变体就不需要加载插件运行时。当前剩余的核心环境变量映射现在仅用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic API 密钥优先的新手引导。 +- 提供商插件还可以通过 `normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`resolveThinkingProfile`、`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 提供商传输。仅使用 Codex 的部署可以通过设置 `agents.defaults.embeddedHarness.fallback: "none"` 禁用自动 PI 回退；参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 ## 插件自有的提供商行为 -提供商插件现在可以拥有大部分提供商特定逻辑，而 OpenClaw 则保留通用推理循环。 +现在，提供商插件可以拥有大多数提供商特定逻辑，而 OpenClaw 保留通用推理循环。 -典型划分如下： +典型划分： -- `auth[].run` / `auth[].runNonInteractive`：提供商拥有 `openclaw onboard`、`openclaw models auth` 和无头设置的引导/登录流程 -- `wizard.setup` / `wizard.modelPicker`：提供商拥有凭证选择标签、旧版别名、新手引导允许列表提示，以及新手引导/模型选择器中的设置项 -- `catalog`：提供商显示在 `models.providers` 中 -- `normalizeModelId`：提供商在查找或规范化之前标准化旧版/预览模型 ID -- `normalizeTransport`：提供商在通用模型组装之前标准化传输家族 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后再检查其他支持该 hook 的提供商插件，直到其中一个实际更改了传输 -- `normalizeConfig`：提供商在运行时使用前标准化 `models.providers.` 配置；OpenClaw 会先检查匹配的提供商，然后再检查其他支持该 hook 的提供商插件，直到其中一个实际更改了配置。如果没有提供商 hook 重写配置，内置的 Google 家族助手仍会标准化受支持的 Google 提供商条目。 -- `applyNativeStreamingUsageCompat`：提供商对配置提供商应用由端点驱动的原生流式用量兼容性重写 -- `resolveConfigApiKey`：提供商为配置提供商解析环境变量标记凭证，而不强制加载完整运行时凭证。`amazon-bedrock` 这里也有一个内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是 AWS SDK 默认链。 -- `resolveSyntheticAuth`：提供商可以在不持久化明文密钥的情况下公开本地/自托管或其他基于配置的凭证可用性 -- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置占位凭证标记为低于环境变量/配置支持凭证的优先级 -- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 ID +- `auth[].run` / `auth[].runNonInteractive`：提供商负责 `openclaw onboard`、`openclaw models auth` 和无头设置的引导/登录流程 +- `wizard.setup` / `wizard.modelPicker`：提供商负责凭证选择标签、旧版别名、新手引导允许列表提示，以及新手引导/模型选择器中的设置项 +- `catalog`：提供商出现在 `models.providers` 中 +- `normalizeModelId`：提供商在查找或规范化之前，规范化旧版/预览模型 id +- `normalizeTransport`：提供商在通用模型组装之前规范化传输族的 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后检查其他支持该 hook 的提供商插件，直到某个插件实际修改了传输 +- `normalizeConfig`：提供商在运行时使用前规范化 `models.providers.` 配置；OpenClaw 会先检查匹配的提供商，然后检查其他支持该 hook 的提供商插件，直到某个插件实际修改了配置。如果没有提供商 hook 重写配置，内置的 Google 家族辅助逻辑仍会规范化受支持的 Google 提供商条目。 +- `applyNativeStreamingUsageCompat`：提供商为配置型提供商应用由端点驱动的原生流式使用量兼容性重写 +- `resolveConfigApiKey`：提供商为配置型提供商解析环境变量标记凭证，而无需强制加载完整运行时凭证。`amazon-bedrock` 在这里也有一个内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是 AWS SDK 默认链。 +- `resolveSyntheticAuth`：提供商可以暴露本地/自托管或其他基于配置的可用凭证，而无需持久化明文密钥 +- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置档占位凭证标记为低于环境变量/配置支持凭证的优先级 +- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 id - `prepareDynamicModel`：提供商在重试动态解析之前需要刷新元数据 -- `normalizeResolvedModel`：提供商需要重写传输或基础 URL -- `contributeResolvedModelCompat`：即使其供应商模型通过另一个兼容传输到达，提供商也会为其贡献兼容性标志 -- `capabilities`：提供商发布转录/工具/提供商家族行为特性 +- `normalizeResolvedModel`：提供商需要重写传输或 base URL +- `contributeResolvedModelCompat`：即使供应商模型是通过其他兼容传输接入的，提供商也能为其贡献兼容性标记 +- `capabilities`：提供商发布转录记录/工具/提供商家族相关的行为差异 - `normalizeToolSchemas`：提供商在内置运行器看到工具 schema 之前对其进行清理 -- `inspectToolSchemas`：提供商在标准化之后暴露传输特定的 schema 警告 +- `inspectToolSchemas`：提供商在规范化后暴露传输特定的 schema 警告 - `resolveReasoningOutputMode`：提供商选择原生或带标签的推理输出契约 -- `prepareExtraParams`：提供商为每个模型的请求参数设置默认值或进行标准化 -- `createStreamFn`：提供商用完全自定义的传输替换正常的流路径 +- `prepareExtraParams`：提供商为每个模型的请求参数设置默认值或进行规范化 +- `createStreamFn`：提供商用完全自定义的传输替换正常流式路径 - `wrapStreamFn`：提供商应用请求头/请求体/模型兼容性包装器 -- `resolveTransportTurnState`：提供商提供逐轮原生传输头或元数据 +- `resolveTransportTurnState`：提供商提供每轮原生传输头或元数据 - `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话头或会话冷却策略 -- `createEmbeddingProvider`：当内存嵌入行为应属于提供商插件而不是核心嵌入切换板时，由提供商拥有该行为 -- `formatApiKey`：提供商将已存储的凭证配置格式化为传输所期望的运行时 `apiKey` 字符串 -- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足时，由提供商拥有 OAuth 刷新 -- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商追加修复指导 -- `matchesContextOverflowError`：提供商识别通用启发式规则会漏掉的、提供商特定的上下文窗口溢出错误 +- `createEmbeddingProvider`：当记忆嵌入行为应归属于提供商插件而不是核心嵌入切换板时，由提供商负责 +- `formatApiKey`：提供商将已存储的凭证配置档格式化为传输所期望的运行时 `apiKey` 字符串 +- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足以处理时，由提供商负责 OAuth 刷新 +- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商追加修复指引 +- `matchesContextOverflowError`：提供商识别通用启发式规则无法发现的提供商特定上下文窗口溢出错误 - `classifyFailoverReason`：提供商将提供商特定的原始传输/API 错误映射为回退原因，例如速率限制或过载 -- `isCacheTtlEligible`：提供商决定哪些上游模型 ID 支持提示词缓存 TTL -- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用凭证存储错误 -- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并可在直接解析失败时返回供应商自有错误 -- `augmentModelCatalog`：提供商在发现和配置合并之后追加合成/最终目录条目 -- `resolveThinkingProfile`：提供商拥有所选模型的精确 `/think` 级别集合、可选显示标签和默认级别 +- `isCacheTtlEligible`：提供商决定哪些上游模型 id 支持提示缓存 TTL +- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用的凭证存储错误 +- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并可在直接解析失败时返回由供应商自有的错误 +- `augmentModelCatalog`：提供商在发现和配置合并后追加合成/最终目录条目 +- `resolveThinkingProfile`：提供商负责所选模型精确的 `/think` 级别集合、可选显示标签和默认级别 - `isBinaryThinking`：用于二元开/关思考 UX 的兼容性 hook - `supportsXHighThinking`：用于选定 `xhigh` 模型的兼容性 hook - `resolveDefaultThinkingLevel`：用于默认 `/think` 策略的兼容性 hook -- `applyConfigDefaults`：提供商在基于凭证模式、环境变量或模型家族进行配置具体化时应用提供商特定的全局默认值 -- `isModernModelRef`：提供商拥有实时/冒烟测试首选模型匹配逻辑 -- `prepareRuntimeAuth`：提供商将已配置的凭证转换为短期有效的运行时令牌 -- `resolveUsageAuth`：提供商为 `/usage` 以及相关状态/报告界面解析用量/配额凭证 -- `fetchUsageSnapshot`：提供商拥有用量端点的抓取/解析逻辑，而核心仍拥有摘要外壳和格式化 -- `onModelSelected`：提供商在模型被选中后运行副作用，例如遥测或提供商自有的会话记账 +- `applyConfigDefaults`：提供商在配置具体化期间，基于凭证模式、环境变量或模型家族应用提供商特定的全局默认值 +- `isModernModelRef`：提供商负责 live/smoke 首选模型匹配 +- `prepareRuntimeAuth`：提供商将已配置凭证转换为短时效运行时令牌 +- `resolveUsageAuth`：提供商为 `/usage` 及相关状态/报告界面解析用量/配额凭证 +- `fetchUsageSnapshot`：提供商负责用量端点的获取/解析，而核心仍负责摘要外壳和格式化 +- `onModelSelected`：提供商在模型选定后运行副作用，例如遥测或提供商自有的会话记账 当前内置示例： -- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、用量端点抓取、缓存 TTL/提供商家族元数据，以及具备凭证感知能力的全局配置默认值 +- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、用量端点获取、缓存 TTL/提供商家族元数据，以及具备凭证感知能力的全局配置默认值 - `amazon-bedrock`：由提供商自有的上下文溢出匹配，以及针对 Bedrock 特有节流/未就绪错误的回退原因分类，外加共享的 `anthropic-by-model` 重放家族，用于 Anthropic 流量上仅限 Claude 的重放策略保护 -- `anthropic-vertex`：针对 Anthropic 消息流量的仅限 Claude 的重放策略保护 -- `openrouter`：直通模型 ID、请求包装器、提供商 capability 提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族进行代理推理注入、路由元数据转发，以及缓存 TTL 策略 -- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude thinking 转录提示、运行时令牌交换，以及用量端点抓取 -- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输标准化、具备 Codex 感知能力的缺失凭证提示、Spark 抑制、合成 OpenAI/Codex 目录条目、thinking/实时模型策略、用量令牌别名标准化（`input` / `output` 和 `prompt` / `completion` 家族）、共享的 `openai-responses-defaults` 流家族（用于原生 OpenAI/Codex 包装器）、提供商家族元数据、为 `gpt-image-1` 内置的图像生成提供商注册，以及为 `sora-2` 内置的视频生成提供商注册 -- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、引导重放清理、带标签的推理输出模式、现代模型匹配、为 Gemini image-preview 模型内置的图像生成提供商注册，以及为 Veo 模型内置的视频生成提供商注册；此外，Gemini CLI OAuth 还拥有凭证配置令牌格式化、用量令牌解析，以及面向用量界面的配额端点抓取 -- `moonshot`：共享传输、插件自有的 thinking 负载标准化 -- `kilocode`：共享传输、插件自有的请求头、推理负载标准化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略 -- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元 thinking/实时模型策略，以及用量凭证 + 配额抓取；未知的 `glm-5*` ID 会基于内置的 `glm-4.7` 模板合成 -- `xai`：原生 Responses 传输标准化、针对 Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特有的工具 schema / 推理负载清理，以及为 `grok-imagine-video` 内置的视频生成提供商注册 -- `mistral`：插件自有的 capability 元数据 -- `opencode` 和 `opencode-go`：插件自有的 capability 元数据，以及代理 Gemini thought-signature 清理 -- `alibaba`：针对直接 Wan 模型引用（如 `alibaba/wan2.6-t2v`）的插件自有视频生成目录 -- `byteplus`：插件自有目录，以及为 Seedance 文生视频/图生视频模型内置的视频生成提供商注册 -- `fal`：为托管第三方图像生成 FLUX 图像模型内置的图像生成提供商注册，以及为托管第三方视频模型内置的视频生成提供商注册 -- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅有插件自有目录 -- `qwen`：文本模型的插件自有目录，以及其多模态界面的共享媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点，并配套内置 Wan 模型，如 `wan2.6-t2v` 和 `wan2.7-r2v` -- `runway`：为原生 Runway 基于任务的模型（如 `gen4.5`）提供插件自有的视频生成提供商注册 -- `minimax`：插件自有目录、为 Hailuo 视频模型内置的视频生成提供商注册、为 `image-01` 内置的图像生成提供商注册、Anthropic/OpenAI 混合重放策略选择，以及用量凭证/快照逻辑 -- `together`：插件自有目录，以及为 Wan 视频模型内置的视频生成提供商注册 -- `xiaomi`：插件自有目录，以及用量凭证/快照逻辑 +- `anthropic-vertex`：针对 Anthropic-message 流量的仅限 Claude 的重放策略保护 +- `openrouter`：透传模型 id、请求包装器、提供商能力提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族进行的代理推理注入、路由元数据转发，以及缓存 TTL 策略 +- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude-thinking 转录提示、运行时令牌交换，以及用量端点获取 +- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输规范化、具备 Codex 感知能力的缺失凭证提示、Spark 屏蔽、合成 OpenAI/Codex 目录条目、thinking/live-model 策略、用量令牌别名规范化（`input` / `output` 和 `prompt` / `completion` 家族）、用于原生 OpenAI/Codex 包装器的共享 `openai-responses-defaults` 流家族、提供商家族元数据、为 `gpt-image-2` 注册的内置图像生成提供商，以及为 `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 策略、二元思考/live-model 策略，以及用量凭证 + 配额获取；未知的 `glm-5*` id 会基于内置的 `glm-4.7` 模板进行合成 +- `xai`：原生 Responses 传输规范化、针对 Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特有的工具 schema / 推理负载清理，以及为 `grok-imagine-video` 注册的内置视频生成提供商 +- `mistral`：插件自有能力元数据 +- `opencode` 和 `opencode-go`：插件自有能力元数据，外加代理 Gemini thought-signature 清理 +- `alibaba`：针对直接 Wan 模型引用（例如 `alibaba/wan2.6-t2v`）的插件自有视频生成目录 +- `byteplus`：插件自有目录，外加为 Seedance 文生视频/图生视频模型注册的内置视频生成提供商 +- `fal`：为托管第三方图像模型注册的内置图像生成提供商（FLUX 图像模型），外加为托管第三方视频模型注册的内置视频生成提供商 +- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅插件自有目录 +- `qwen`：文本模型的插件自有目录，外加针对其多模态能力的共享媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点和内置 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v` +- `runway`：针对原生 Runway 任务型模型（例如 `gen4.5`）的插件自有视频生成提供商注册 +- `minimax`：插件自有目录、为 Hailuo 视频模型注册的内置视频生成提供商、为 `image-01` 注册的内置图像生成提供商、混合 Anthropic/OpenAI 重放策略选择，以及用量凭证/快照逻辑 +- `together`：插件自有目录，外加为 Wan 视频模型注册的内置视频生成提供商 +- `xiaomi`：插件自有目录，外加用量凭证/快照逻辑 -内置的 `openai` 插件现在同时拥有两个提供商 ID：`openai` 和 `openai-codex`。 +内置的 `openai` 插件现在同时负责两个提供商 id：`openai` 和 `openai-codex`。 -以上涵盖了仍适配 OpenClaw 常规传输的提供商。若某个提供商需要完全自定义的请求执行器，那就是另一类、更深层的扩展接口。 +以上涵盖了仍适合 OpenClaw 常规传输方式的提供商。若某个提供商需要完全自定义的请求执行器，那就是一个单独且更深层的扩展接口。 -## API key 轮换 +## API 密钥轮换 -- 支持为选定提供商进行通用提供商轮换。 -- 通过以下方式配置多个 key： - - `OPENCLAW_LIVE__KEY`（单个实时覆盖，最高优先级） +- 支持对选定提供商进行通用提供商轮换。 +- 可通过以下方式配置多个密钥： + - `OPENCLAW_LIVE__KEY`（单个 live 覆盖，最高优先级） - `_API_KEYS`（逗号或分号分隔列表） - - `_API_KEY`（主 key） + - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） -- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退项包含在内。 -- key 选择顺序会保留优先级并去重数值。 -- 仅在收到速率限制响应时，才会使用下一个 key 重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性的用量限制消息）。 -- 非速率限制失败会立即失败；不会尝试 key 轮换。 -- 当所有候选 key 都失败时，返回最后一次尝试的最终错误。 +- 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退项包含在内。 +- 密钥选择顺序会保留优先级并对值去重。 +- 只有在收到速率限制响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性的用量限制消息）。 +- 非速率限制失败会立即失败；不会尝试密钥轮换。 +- 当所有候选密钥都失败时，返回最后一次尝试的最终错误。 ## 内置提供商（pi-ai 目录） -OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** -`models.providers` 配置；只需设置凭证并选择模型。 +OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置凭证并选择模型。 ### OpenAI - 提供商：`openai` - 凭证：`OPENAI_API_KEY` -- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖） +- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单一覆盖） - 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-pro` - CLI：`openclaw onboard --auth-choice openai-api-key` -- 默认传输为 `auto`（WebSocket 优先，SSE 回退） +- 默认传输是 `auto`（优先 WebSocket，回退 SSE） - 可通过 `agents.defaults.models["openai/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） - OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`） - 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先级处理 - `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority` -- 当你希望使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier` -- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）只适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理 -- 原生 OpenAI 路由还会保留 Responses `store`、提示词缓存提示，以及 OpenAI 推理兼容负载整形；代理路由则不会 -- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 会拒绝它；Spark 被视为仅限 Codex +- 当你想使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier` +- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理 +- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示和 OpenAI 推理兼容负载整形；代理路由则不会 +- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex ```json5 { @@ -156,12 +155,12 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** - 提供商：`anthropic` - 凭证：`ANTHROPIC_API_KEY` -- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖） +- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单一覆盖） - 示例模型：`anthropic/claude-opus-4-6` - CLI：`openclaw onboard --auth-choice apiKey` -- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 凭证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`） -- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为该集成已获许可。 -- Anthropic setup-token 仍可作为受支持的 OpenClaw 令牌路径使用，但 OpenClaw 现在在可用时更倾向于 Claude CLI 复用和 `claude -p`。 +- 直接公共 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 { @@ -175,12 +174,12 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** - 凭证：OAuth（ChatGPT） - 示例模型：`openai-codex/gpt-5.4` - CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex` -- 默认传输为 `auto`（WebSocket 优先，SSE 回退） +- 默认传输是 `auto`（优先 WebSocket，回退 SSE） - 可通过 `agents.defaults.models["openai-codex/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）上传递 +- `params.serviceTier` 也会转发到原生 Codex Responses 请求（`chatgpt.com/backend-api`）上 - 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理 -- 与直接 `openai/*` 共用相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority` -- 当 Codex OAuth 目录暴露 `openai-codex/gpt-5.3-codex-spark` 时，该模型仍可用；是否可用取决于 entitlement +- 与直接 `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 这样的外部工具/工作流。 @@ -204,8 +203,8 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** ### 其他订阅式托管选项 -- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商界面，以及 Alibaba DashScope 和 Coding Plan 端点映射 -- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API key 访问 +- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射 +- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问 - [GLM Models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点 ### OpenCode @@ -222,23 +221,21 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** } ``` -### Google Gemini（API key） +### Google Gemini（API 密钥） - 提供商：`google` - 凭证：`GEMINI_API_KEY` -- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） +- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单一覆盖） - 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview` -- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被标准化为 `google/gemini-3-flash-preview` +- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview` - CLI：`openclaw onboard --auth-choice gemini-api-key` -- 直接 Gemini 运行也接受 `agents.defaults.models["google/"].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` @@ -246,10 +243,9 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** - 启用：`openclaw plugins enable google` - 登录：`openclaw models auth login --provider google-gemini-cli --set-default` - 默认模型：`google-gemini-cli/gemini-3-flash-preview` - - 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的凭证配置中。 + - 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的凭证配置档中。 - 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。 - - Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 - `stats`，其中 `stats.cached` 会被标准化为 OpenClaw `cacheRead`。 + - Gemini CLI JSON 回复从 `response` 解析；用量会回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 ### Z.AI（GLM） @@ -257,8 +253,8 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** - 凭证：`ZAI_API_KEY` - 示例模型：`zai/glm-5.1` - CLI：`openclaw onboard --auth-choice zai-api-key` - - 别名：`z.ai/*` 和 `z-ai/*` 会被标准化为 `zai/*` - - `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定界面 + - 别名：`z.ai/*` 和 `z-ai/*` 会被规范化为 `zai/*` + - `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口 ### Vercel AI Gateway @@ -274,31 +270,26 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** - 示例模型：`kilocode/kilo/auto` - CLI：`openclaw onboard --auth-choice kilocode-api-key` - Base URL：`https://api.kilo.ai/api/gateway/` -- 静态回退目录内置 `kilocode/kilo/auto`；实时 - `https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时 - 目录。 -- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 自行管理， - 并非在 OpenClaw 中硬编码。 +- 静态回退目录附带 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 发现还可以进一步扩展运行时目录。 +- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 负责，不是 OpenClaw 中硬编码的。 -设置详情请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。 +有关设置详情，请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。 ### 其他内置提供商插件 - OpenRouter：`openrouter`（`OPENROUTER_API_KEY`） - 示例模型：`openrouter/auto` -- OpenClaw 仅在请求实际发往 `openrouter.ai` 时才会应用 OpenRouter 文档中说明的应用归因请求头 -- OpenRouter 特有的 Anthropic `cache_control` 标记同样只会作用于经过验证的 OpenRouter 路由，而不是任意代理 URL -- OpenRouter 仍走代理风格的 OpenAI 兼容路径，因此仅适用于原生 OpenAI 的请求整形（`serviceTier`、Responses `store`、提示词缓存提示、OpenAI 推理兼容负载）不会被转发 -- 基于 Gemini 的 OpenRouter 引用只保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和引导重写保持关闭 +- 只有当请求实际发往 `openrouter.ai` 时，OpenClaw 才会应用 OpenRouter 文档中的应用归因请求头 +- OpenRouter 特有的 Anthropic `cache_control` 标记同样只会在已验证的 OpenRouter 路由上启用，而不是任意代理 URL +- OpenRouter 仍然走代理风格的 OpenAI 兼容路径，因此原生仅限 OpenAI 的请求整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容负载）不会被转发 +- 基于 Gemini 的 OpenRouter 引用仅保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和引导重写保持关闭 - Kilo Gateway：`kilocode`（`KILOCODE_API_KEY`） - 示例模型：`kilocode/kilo/auto` -- 基于 Gemini 的 Kilo 引用保留相同的代理 Gemini thought-signature - 清理路径；`kilocode/kilo/auto` 以及其他不支持代理推理的提示会跳过代理推理注入 -- MiniMax：`minimax`（API key）和 `minimax-portal`（OAuth） +- 基于 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 key 设置会写入显式的 M2.7 模型定义，并带有 - `input: ["text", "image"]`；内置提供商目录会在该提供商配置具体化之前，将聊天引用保持为仅文本 +- MiniMax 新手引导/API 密钥设置会写入显式 M2.7 模型定义，并包含 `input: ["text", "image"]`；在该提供商配置具体化之前，内置提供商目录会将聊天引用保持为仅文本 - Moonshot：`moonshot`（`MOONSHOT_API_KEY`） - 示例模型：`moonshot/kimi-k2.6` - Kimi Coding：`kimi`（`KIMI_API_KEY` 或 `KIMICODE_API_KEY`） @@ -321,39 +312,32 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** - Cloudflare AI Gateway：`cloudflare-ai-gateway`（`CLOUDFLARE_AI_GATEWAY_API_KEY`） - Volcengine：`volcengine`（`VOLCANO_ENGINE_API_KEY`） - 示例模型：`volcengine-plan/ark-code-latest` -- BytePlus：`byteplus`（`BYTEPLUS_API_KEY`） +- BytePlus（国际版）：`byteplus`（`BYTEPLUS_API_KEY`） - 示例模型：`byteplus-plan/ark-code-latest` - xAI：`xai`（`XAI_API_KEY`） - 原生内置 xAI 请求使用 xAI Responses 路径 - - `/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、 - `grok-4` 和 `grok-4-0709` 重写为其 `*-fast` 变体 - - `tool_stream` 默认开启；设置 - `agents.defaults.models["xai/"].params.tool_stream` 为 `false` 可 - 关闭 + - `/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为它们的 `*-fast` 变体 + - `tool_stream` 默认开启；将 `agents.defaults.models["xai/"].params.tool_stream` 设为 `false` 可关闭它 - Mistral：`mistral`（`MISTRAL_API_KEY`） - 示例模型：`mistral/mistral-large-latest` - CLI：`openclaw onboard --auth-choice mistral-api-key` - Groq：`groq`（`GROQ_API_KEY`） - Cerebras：`cerebras`（`CEREBRAS_API_KEY`） - - Cerebras 上的 GLM 模型使用 ID `zai-glm-4.7` 和 `zai-glm-4.6`。 + - 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)。 -## 通过 `models.providers` 使用提供商（自定义/Base URL） +## 通过 `models.providers` 配置的提供商（自定义/Base URL） -使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 -OpenAI/Anthropic 兼容代理。 +使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。 -下方许多内置提供商插件已经发布了默认目录。 -只有在你想覆盖默认 Base URL、请求头或模型列表时，才需要显式使用 -`models.providers.` 条目。 +下面许多内置提供商插件已经发布了默认目录。 +只有当你想覆盖默认 Base URL、请求头或模型列表时，才使用显式 `models.providers.` 条目。 ### Moonshot AI（Kimi） -Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在你 -需要覆盖 Base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` -条目： +Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在你需要覆盖 Base URL 或模型元数据时，才添加显式 `models.providers.moonshot` 条目： - 提供商：`moonshot` - 凭证：`MOONSHOT_API_KEY` @@ -408,13 +392,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： } ``` -旧版 `kimi/k2p5` 仍然作为兼容模型 ID 被接受。 +旧版 `kimi/k2p5` 仍然作为兼容模型 id 被接受。 ### Volcano Engine（Doubao） Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。 -- 提供商：`volcengine`（coding：`volcengine-plan`） +- 提供商：`volcengine`（编程方案：`volcengine-plan`） - 凭证：`VOLCANO_ENGINE_API_KEY` - 示例模型：`volcengine-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice volcengine-api-key` @@ -427,12 +411,9 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访 } ``` -新手引导默认使用 coding 界面，但通用 `volcengine/*` -目录会同时注册。 +新手引导默认使用编程接口，但通用的 `volcengine/*` 目录会同时注册。 -在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 -`volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未加载， -OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范围选择器。 +在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -442,7 +423,7 @@ OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范 - `volcengine/glm-4-7-251222`（GLM 4.7） - `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K） -Coding 模型（`volcengine-plan`）： +编程模型（`volcengine-plan`）： - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` @@ -454,7 +435,7 @@ Coding 模型（`volcengine-plan`）： BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 -- 提供商：`byteplus`（coding：`byteplus-plan`） +- 提供商：`byteplus`（编程方案：`byteplus-plan`） - 凭证：`BYTEPLUS_API_KEY` - 示例模型：`byteplus-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice byteplus-api-key` @@ -467,12 +448,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 } ``` -新手引导默认使用 coding 界面，但通用 `byteplus/*` -目录会同时注册。 +新手引导默认使用编程接口，但通用的 `byteplus/*` 目录会同时注册。 -在新手引导/配置模型选择器中，BytePlus（国际版）凭证选项会优先显示 -`byteplus/*` 和 `byteplus-plan/*` 条目。如果这些模型尚未加载， -OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范围选择器。 +在新手引导/配置模型选择器中，BytePlus（国际版）凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -480,7 +458,7 @@ OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范 - `byteplus/kimi-k2-5-260127`（Kimi K2.5） - `byteplus/glm-4-7-251222`（GLM 4.7） -Coding 模型（`byteplus-plan`）： +编程模型（`byteplus-plan`）： - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` @@ -522,33 +500,30 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点： - MiniMax OAuth（Global）：`--auth-choice minimax-global-oauth` - MiniMax OAuth（CN）：`--auth-choice minimax-cn-oauth` -- MiniMax API key（Global）：`--auth-choice minimax-global-api` -- MiniMax API key（CN）：`--auth-choice minimax-cn-api` -- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 - `MINIMAX_API_KEY` +- MiniMax API 密钥（Global）：`--auth-choice minimax-global-api` +- 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`。 -插件自有 capability 划分： +插件自有能力划分： - 文本/聊天默认保持在 `minimax/MiniMax-M2.7` - 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01` -- 图像理解在两种 MiniMax 凭证路径上都使用插件自有的 `MiniMax-VL-01` -- Web 搜索保持使用提供商 ID `minimax` +- 图像理解由两个 MiniMax 凭证路径上的插件自有 `MiniMax-VL-01` 负责 +- Web 搜索仍使用提供商 id `minimax` ### LM Studio -LM Studio 作为内置提供商插件提供，并使用原生 API： +LM Studio 作为一个使用原生 API 的内置提供商插件提供： - 提供商：`lmstudio` - 凭证：`LM_API_TOKEN` - 默认推理 Base URL：`http://localhost:1234/v1` -然后设置一个模型（请替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）： ```json5 { @@ -558,16 +533,15 @@ LM Studio 作为内置提供商插件提供，并使用原生 API： } ``` -OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` -进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。 -设置和故障排除请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 +OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` 进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。 +有关设置和故障排除，请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 ### Ollama Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API： - 提供商：`ollama` -- 凭证：不需要（本地服务器） +- 凭证：无需（本地服务器） - 示例模型：`ollama/llama3.3` - 安装：[https://ollama.com/download](https://ollama.com/download) @@ -584,26 +558,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` 明确启用时，系统会在 `http://127.0.0.1:11434` 本地检测 Ollama，并且内置提供商插件会将 Ollama 直接加入 `openclaw onboard` 和模型选择器。有关新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。 ### vLLM -vLLM 作为内置提供商插件提供，适用于本地/自托管的 OpenAI 兼容 -服务器： +vLLM 作为内置提供商插件提供，适用于本地/自托管的 OpenAI 兼容服务器： - 提供商：`vllm` - 凭证：可选（取决于你的服务器） - 默认 Base URL：`http://127.0.0.1:8000/v1` -要在本地选择启用自动发现（如果你的服务器不强制凭证，任意值都可以）： +要在本地启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）： ```bash export VLLM_API_KEY="vllm-local" ``` -然后设置一个模型（请替换为 `/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： ```json5 { @@ -617,21 +588,19 @@ export VLLM_API_KEY="vllm-local" ### SGLang -SGLang 作为内置提供商插件提供，适用于快速自托管的 -OpenAI 兼容服务器： +SGLang 作为内置提供商插件提供，适用于高速自托管的 OpenAI 兼容服务器： - 提供商：`sglang` - 凭证：可选（取决于你的服务器） - 默认 Base URL：`http://127.0.0.1:30000/v1` -要在本地选择启用自动发现（如果你的服务器不强制 -凭证，任意值都可以）： +要在本地启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）： ```bash export SGLANG_API_KEY="sglang-local" ``` -然后设置一个模型（请替换为 `/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： ```json5 { @@ -680,20 +649,18 @@ export SGLANG_API_KEY="sglang-local" 说明： -- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选项。 - 如果省略，OpenClaw 默认使用： +- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。 + 省略时，OpenClaw 默认值为： - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- 建议：设置与你的代理/模型限制相匹配的显式值。 -- 对于非原生端点上的 `api: "openai-completions"`（任何 host 不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 -- 代理风格的 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求 - 整形：没有 `service_tier`、没有 Responses `store`、没有提示词缓存提示、没有 - OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归因请求头。 -- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认的 OpenAI 行为（即解析到 `api.openai.com`）。 -- 为了安全起见，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。 +- 建议：设置与你的代理/模型限制一致的显式值。 +- 对于非原生端点上的 `api: "openai-completions"`（任何 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`）。 +- 为了安全起见，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍然会被覆盖。 ## CLI 示例 @@ -710,4 +677,4 @@ openclaw models list - [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) — 按提供商分别说明的设置指南 +- [Providers](/zh-CN/providers) — 按提供商划分的设置指南 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index d4886a529..8260fb73b 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -1,35 +1,35 @@ --- read_when: - - 你需要精确到字段级别的配置语义或默认值 - - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键、默认值，以及指向各专用子系统参考文档的链接 + - 你需要精确到字段级别的配置语义或默认值。 + - 你正在验证渠道、模型、Gateway 网关或工具配置块。 +summary: 用于核心 OpenClaw 键、默认值以及指向专用子系统参考的链接的 Gateway 网关配置参考。 title: 配置参考 x-i18n: - generated_at: "2026-04-21T06:04:37Z" + generated_at: "2026-04-21T20:53:27Z" model: gpt-5.4 provider: openai - source_hash: f82a9a150a862c20863c187ac5c118b74aeac624e99849cf4c6e3fb56629423e + source_hash: ee1fc48831793d8e751ae86cff414faa36290a86d7bf64ac3e5d8eade2ec8a44 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 的主要配置面，并在某个子系统有自己更深入的参考时提供链接。它**不会**尝试在一个页面中内联所有由渠道/插件拥有的命令目录，或所有深入的内存 / QMD 调节项。 -代码事实来源： +代码中的事实来源： -- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 -- `config.schema.lookup` 返回一个按路径范围限定的 schema 节点，用于下钻工具 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希 +- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置 / 插件 / 渠道元数据 +- `config.schema.lookup` 返回一个按路径范围限定的 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) 用于当前内置 + 内置插件命令目录 -- 各自所属的渠道/插件页面，用于渠道特定的命令表面 +- [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 +- [斜杠命令](/zh-CN/tools/slash-commands)，用于查看当前内置 + 内置插件命令目录 +- 各自所属的渠道 / 插件页面，用于查看特定渠道的命令面 配置格式为 **JSON5**（允许注释 + 尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 @@ -37,34 +37,34 @@ x-i18n: ## 渠道 -每个渠道在其配置段存在时都会自动启动（除非设置了 `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` 未设置时充当默认值。 +`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设为默认值。 配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。 -如果某个提供商配置块完全缺失（即不存在 `channels.`），运行时群组策略会回退到 `allowlist`（默认拒绝，fail-closed），并在启动时发出警告。 +如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（失败时默认关闭），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未有模型覆盖时（例如通过 `/model` 设置），就会应用该渠道映射。 +使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当某个会话尚未有模型覆盖时，渠道映射才会生效（例如通过 `/model` 设置）。 ```json5 { @@ -105,10 +105,10 @@ 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.showAlerts`：在心跳输出中包含降级 / 错误状态。 - `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 ### WhatsApp @@ -124,7 +124,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 蓝色对勾（自聊模式下为 false） + sendReadReceipts: true, // 蓝色已读勾（在 self-chat 模式下为 false） groups: { "*": { requireMention: true }, }, @@ -164,9 +164,9 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 出站命令默认使用 `default` 账号；如果不存在，则使用首个已配置的账号 id（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 id 时，覆盖该回退默认账号选择。 -- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 出站命令默认使用账号 `default`（如果存在）；否则使用第一个已配置的账号 ID（排序后）。 +- 可选的 `channels.whatsapp.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖该回退默认账号选择。 +- 旧版单账号 Baileys auth 目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 - 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -202,7 +202,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress（默认：off；明确选择启用，以避免预览编辑速率限制） + streaming: "partial", // off | partial | block | progress（默认：off；需显式启用以避免预览编辑速率限制） actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,13 +225,13 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 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`（在私聊和群聊中都可用）。 -- 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 +- 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 发起的配置写入（supergroup 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`（可用于私聊和群聊）。 +- 重试策略：参见 [重试策略](/zh-CN/concepts/retry)。 ### Discord @@ -297,7 +297,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // 对 `sessions_spawn({ thread: true })` 的显式启用 + spawnSubagentSessions: false, // 对 `sessions_spawn({ thread: true })` 的选择启用项 }, voice: { enabled: true, @@ -333,36 +333,36 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Token：`channels.discord.token`，默认账号可回退到 `DISCORD_BOT_TOKEN`。 -- 直接出站调用如果显式提供 Discord `token`，该次调用会使用该 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:`（guild 渠道）作为投递目标；裸数字 ID 会被拒绝。 +- Guild slug 使用小写，并将空格替换为 `-`；渠道键使用 slug 化后的名称（不带 `#`）。优先使用 guild ID。 +- 默认会忽略由 bot 自己编写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 时，仅接受提及该 bot 的 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` 会重新启用可变名称/tag 匹配（紧急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 审批投递与审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 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 允许列表。省略时会为所有智能体转发审批请求。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的批准请求。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起来源频道，`"both"` 同时发送到两者。当 target 包含 `"channel"` 时，按钮仅对已解析出的审批人可用。 - - `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除审批私信。 + - `target`：批准提示发送位置。`"dm"`（默认）发送到批准者私信，`"channel"` 发送到来源渠道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮仅可由已解析的批准者使用。 + - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除批准私信。 -**Reaction notification 模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中用户对所有消息的反应）。 +**反应通知模式：** `off`（无）、`own`（bot 自己的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users`，适用于所有消息）。 ### Google Chat @@ -393,7 +393,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 服务账号 JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 - 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 - 使用 `spaces/` 或 `users/` 作为投递目标。 @@ -449,7 +449,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // 当 mode=partial 时使用 Slack 原生流式 API + nativeTransport: true, // 当 mode=partial 时使用 Slack 原生流式传输 API }, mediaMaxMb: 20, execApprovals: { @@ -464,38 +464,39 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号可通过 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` 环境变量回退）。 -- **HTTP mode** 需要 `botToken` 加上 `signingSecret`（位于根级或账号级）。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 支持纯文本 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级别或账号级别）。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 字符串或 SecretRef 对象。 -- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 +- Slack 账号快照会暴露按凭证划分的来源 / 状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 - `signingSecretStatus`。`configured_unavailable` 表示该账号是通过 SecretRef - 配置的，但当前命令/运行时路径无法解析该 secret 值。 + `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` 值会被自动迁移。 +- 可选的 `channels.slack.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 +- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版的 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会被自动迁移。 - 使用 `user:`（私信）或 `channel:` 作为投递目标。 -**Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 可以是按线程（默认）或跨频道共享。`thread.inheritParent` 会将父频道的对话记录复制到新线程中。 +**线程会话隔离：** `thread.historyScope` 可设为按线程（默认）或在整个渠道内共享。`thread.inheritParent` 会将父渠道的转录复制到新线程中。 -- Slack 原生流式传输，以及 Slack 助手样式的“正在输入...”线程状态，都要求目标是某个回复线程。顶层私信默认不在线程内，因此会使用 `typingReaction` 或常规投递，而不是线程样式预览。 -- `typingReaction` 会在回复进行期间，为传入的 Slack 消息临时添加一个反应，并在完成后移除。使用 Slack 表情 shortcode，例如 `"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 批准投递和批准者授权。其 schema 与 Discord 相同：`enabled`（`true` / `false` / `"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认值 | 说明 | -| ------------ | ------- | ---------------------- | -| reactions | 启用 | 添加反应 + 列出反应 | -| messages | 启用 | 读取/发送/编辑/删除 | -| pins | 启用 | 置顶/取消置顶/列出 | -| memberInfo | 启用 | 成员信息 | -| emojiList | 启用 | 自定义表情列表 | +| 操作组 | 默认值 | 说明 | +| ---------- | ------ | ------------------ | +| reactions | 启用 | 添加反应 + 列出反应 | +| messages | 启用 | 读取 / 发送 / 编辑 / 删除 | +| pins | 启用 | 置顶 / 取消置顶 / 列出 | +| memberInfo | 启用 | 成员信息 | +| emojiList | 启用 | 自定义 emoji 列表 | ### Mattermost -Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -512,10 +513,10 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos "team-channel-id": { requireMention: false }, }, commands: { - native: true, // 显式启用 + native: true, // 选择启用 nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 面向反向代理/公网部署的可选显式 URL + // 适用于反向代理 / 公网部署的可选显式 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -525,21 +526,21 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos } ``` -聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（对以触发前缀开头的消息回复）。 +聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 启用 Mattermost 原生命令时： -- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可以访问。 -- 原生斜杠命令回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行身份验证。如果注册失败或没有任何命令被激活，OpenClaw 会拒绝回调，并返回 - `Unauthorized: invalid command token.` -- 对于私有/tailnet/内网回调主机，Mattermost 可能要求 - `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。 - 使用主机/域名值，而不是完整 URL。 +- `commands.callbackPath` 必须是一个路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可访问。 +- 原生斜杠回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行认证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调，并返回 + `Unauthorized: invalid command token.`。 +- 对于私有 / tailnet / 内部回调主机，Mattermost 可能要求 + `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机 / 域名。 + 请使用主机 / 域名值，而不是完整 URL。 - `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 -- `channels.mattermost.requireMention`：在频道中回复前要求 `@mention`。 -- `channels.mattermost.groups..requireMention`：按频道覆盖提及门控（`"*"` 表示默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 id 时覆盖默认账号选择。 +- `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。 +- `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（`"*"` 表示默认值）。 +- 可选的 `channels.mattermost.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 ### Signal @@ -548,7 +549,7 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos channels: { signal: { enabled: true, - account: "+15555550123", // 可选的账号绑定 + account: "+15555550123", // 可选账号绑定 dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -560,15 +561,15 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos } ``` -**Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**反应通知模式：** `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 +585,13 @@ BlueBubbles 是推荐的 iMessage 接入路径（由插件支持，配置位于 ``` - 此处涵盖的核心键路径：`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)。 +- 可选的 `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 +615,15 @@ OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 id 时覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 -- 需要对 Messages 数据库授予完全磁盘访问权限。 +- 需要对 Messages DB 授予完全磁盘访问权限。 - 优先使用 `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` 中。 - `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 +636,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展支持，配置位于 `channels.matrix`。 +Matrix 由扩展支持，并在 `channels.matrix` 下配置。 ```json5 { @@ -666,24 +667,24 @@ Matrix 由扩展支持，配置位于 `channels.matrix`。 ``` - Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理转发 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内网 homeserver。`proxy` 与这个网络显式启用项是相互独立的控制项。 +- `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"`（默认）。在 auto 模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 +- `channels.matrix.execApprovals`：Matrix 原生 exec 批准投递和批准者授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出批准者时，exec 批准会被激活。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会为所有智能体转发审批请求。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的批准请求。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 + - `target`：批准提示发送位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归入会话：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 -- Matrix 状态探测和实时目录查询与运行时流量使用相同的代理策略。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归组到会话中：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 +- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 - 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams -Microsoft Teams 由扩展支持，配置位于 `channels.msteams`。 +Microsoft Teams 由扩展支持，并在 `channels.msteams` 下配置。 ```json5 { @@ -691,7 +692,7 @@ Microsoft Teams 由扩展支持，配置位于 `channels.msteams`。 msteams: { enabled: true, configWrites: true, - // appId、appPassword、tenantId、webhook、团队/频道策略： + // appId、appPassword、tenantId、webhook、团队 / 渠道策略： // 参见 /channels/msteams }, }, @@ -699,11 +700,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 +726,12 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 id 时覆盖默认账号选择。 -- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/mention gating）记录在 [IRC](/zh-CN/channels/irc) 中。 +- 可选的 `channels.irc.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 +- 完整的 IRC 渠道配置（host / port / TLS / 渠道 / 允许列表 / 提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 ### 多账号（所有渠道） -按渠道运行多个账号（每个账号都有自己的 `accountId`）： +为每个渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -751,17 +752,17 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -- 省略 `accountId` 时会使用 `default`（CLI + 路由）。 +- 省略 `accountId` 时使用 `default`（CLI + 路由）。 - 环境变量 token 仅适用于 **default** 账号。 -- 基础渠道设置会应用到所有账号，除非按账号覆盖。 -- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。 -- 如果你在仍处于单账号顶层渠道配置的情况下，通过 `openclaw channels add`（或渠道新手引导）添加一个非默认账号，OpenClaw 会先把按账号范围的顶层单账号值提升到该渠道的账号映射中，以便原账号继续工作。大多数渠道会将它们移动到 `channels..accounts.default`；Matrix 则可以保留现有的匹配命名/default 目标。 -- 现有仅渠道级的绑定（无 `accountId`）将继续匹配默认账号；账号级绑定仍然是可选的。 -- `openclaw doctor --fix` 也会通过将按账号范围的顶层单账号值移动到为该渠道选择的提升后账号中来修复混合形状。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有的匹配命名/default 目标。 +- 基础渠道设置适用于所有账号，除非被按账号覆盖。 +- 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。 +- 如果你通过 `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)。 ### 群聊提及门控 @@ -770,9 +771,9 @@ IRC 由扩展支持，配置位于 `channels.irc`。 **提及类型：** -- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式下会被忽略。 -- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 只有在能够检测时（原生提及或至少一个模式），才会强制执行提及门控。 +- **元数据提及**：平台原生 @ 提及。在 WhatsApp self-chat 模式中会被忽略。 +- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 +- 只有在能够检测提及时才会强制执行提及门控（原生提及或至少一个模式）。 ```json5 { @@ -787,7 +788,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 `messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 -#### 私信历史限制 +#### 私信历史记录限制 ```json5 { @@ -802,13 +803,13 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。 +解析顺序：按私信覆盖 → 提供商默认值 → 无限制（全部保留）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 -#### 自聊模式 +#### self-chat 模式 -将你自己的号码加入 `allowFrom` 以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： +将你自己的号码加入 `allowFrom` 以启用 self-chat 模式（忽略原生 @ 提及，只响应文本模式）： ```json5 { @@ -829,13 +830,13 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -### Commands（聊天命令处理） +### 命令（聊天命令处理） ```json5 { commands: { - native: "auto", // 在支持时注册原生命令 - nativeSkills: "auto", // 在支持时注册原生 Skills 命令 + native: "auto", // 支持时注册原生命令 + nativeSkills: "auto", // 支持时注册原生 Skills 命令 text: true, // 解析聊天消息中的 /commands bash: false, // 允许 !（别名：/bash） bashForegroundMs: 2000, @@ -858,32 +859,32 @@ IRC 由扩展支持，配置位于 `channels.irc`。 -- 此配置块用于配置命令表面。关于当前内置 + 内置插件命令目录，请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。 -- 本页是**配置键参考**，不是完整命令目录。像 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/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 保持关闭。 +- 此配置块用于配置命令面。若要查看当前内置 + 内置插件命令目录，请参阅 [斜杠命令](/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` 这类由渠道 / 插件拥有的命令，记录在它们各自的渠道 / 插件页面以及 [斜杠命令](/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 客户端仍然可用。 +- `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....`）。 +- `plugins: true` 会启用 `/plugins`，用于插件发现、安装以及启用 / 禁用控制。 +- `channels..configWrites` 控制每个渠道是否允许配置变更（默认：true）。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会控制面向该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 - `restart: false` 会禁用 `/restart` 和 gateway restart 工具操作。默认值：`true`。 -- `ownerAllowFrom` 是 owner-only 命令/工具的显式所有者允许列表。它与 `allowFrom` 分开。 -- `ownerDisplay: "hash"` 会在系统提示中对 owner id 进行哈希。设置 `ownerDisplaySecret` 可控制哈希方式。 -- `allowFrom` 是按提供商设置的。设置后，它将成为**唯一**授权来源（渠道允许列表/配对 和 `useAccessGroups` 都会被忽略）。 -- `useAccessGroups: false` 允许在未设置 `allowFrom` 时，命令绕过访问组策略。 +- `ownerAllowFrom` 是仅限所有者命令 / 工具的显式所有者允许列表。它与 `allowFrom` 分开。 +- `ownerDisplay: "hash"` 会在系统提示中对所有者 ID 做哈希。设置 `ownerDisplaySecret` 可控制哈希方式。 +- `allowFrom` 按提供商生效。设置后，它将成为**唯一**的授权来源（渠道允许列表 / 配对和 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 会在未设置 `allowFrom` 时，允许命令绕过访问组策略。 - 命令文档映射： - - 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands) - - 渠道特定命令表面：[Channels](/zh-CN/channels) + - 内置 + 内置插件目录：[斜杠命令](/zh-CN/tools/slash-commands) + - 特定渠道命令面：[Channels](/zh-CN/channels) - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) - 配对命令：[Pairing](/zh-CN/channels/pairing) - LINE 卡片命令：[LINE](/zh-CN/channels/line) - - memory Dreaming：[Dreaming](/zh-CN/concepts/dreaming) + - memory dreaming：[Dreaming](/zh-CN/concepts/dreaming) @@ -903,7 +904,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。若未设置，OpenClaw 会从 workspace 向上遍历自动检测。 ```json5 { @@ -913,8 +914,9 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.skills` -为未设置 -`agents.list[].skills` 的智能体提供可选的默认技能允许列表。 +适用于未设置 +`agents.list[].skills` +的智能体的可选默认 Skills 允许列表。 ```json5 { @@ -930,14 +932,14 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ``` - 省略 `agents.defaults.skills` 时，默认 Skills 不受限制。 -- 省略 `agents.list[].skills` 时，将继承默认值。 -- 设置 `agents.list[].skills: []` 表示不使用任何 Skills。 +- 省略 `agents.list[].skills` 时会继承默认值。 +- 设置 `agents.list[].skills: []` 表示无 Skills。 - 非空的 `agents.list[].skills` 列表是该智能体的最终集合；它 不会与默认值合并。 ### `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 重新注入，从而减少提示大小。Heartbeat 运行和压缩后重试仍会重建上下文。 +- `"continuation-skip"`：安全续接轮次（在助手完成响应之后）会跳过 workspace bootstrap 的重新注入，以减少提示大小。心跳运行和压缩后重试仍会重建上下文。 ```json5 { @@ -959,7 +961,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapMaxChars` -每个工作区 bootstrap 文件在截断前的最大字符数。默认值：`12000`。 +每个 workspace bootstrap 文件在截断前的最大字符数。默认值：`12000`。 ```json5 { @@ -969,7 +971,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapTotalMaxChars` -跨所有工作区 bootstrap 文件注入的总最大字符数。默认值：`60000`。 +跨所有 workspace bootstrap 文件注入的最大总字符数。默认值：`60000`。 ```json5 { @@ -979,11 +981,11 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制在 bootstrap 上下文被截断时，向智能体显示的警告文本。 +控制 bootstrap 上下文被截断时，对智能体可见的警告文本。 默认值：`"once"`。 - `"off"`：绝不将警告文本注入系统提示。 -- `"once"`：对每个唯一的截断签名只注入一次警告（推荐）。 +- `"once"`：每个唯一的截断签名只注入一次警告（推荐）。 - `"always"`：只要存在截断，就在每次运行时注入警告。 ```json5 @@ -994,25 +996,24 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### 上下文预算归属映射 -OpenClaw 有多个高容量的提示/上下文预算，它们 -有意按子系统拆分，而不是全部流经同一个通用 -调节项。 +OpenClaw 有多个高容量的提示 / 上下文预算，并且 +这些预算是有意按子系统拆分的，而不是全部流经一个通用 +旋钮。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： - 普通工作区 bootstrap 注入。 + 常规 workspace bootstrap 注入。 - `agents.defaults.startupContext.*`： 一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日 `memory/*.md` 文件。 - `skills.limits.*`： - 注入系统提示中的紧凑 Skills 列表。 + 注入系统提示的紧凑 Skills 列表。 - `agents.defaults.contextLimits.*`： 有界的运行时摘录和由运行时拥有的注入块。 - `memory.qmd.limits.*`： - 已索引 memory 搜索片段与注入大小。 + 已索引 memory 搜索片段和注入大小控制。 -仅当某个智能体需要不同 -预算时，才使用相应的按智能体覆盖： +仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖： - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` @@ -1041,7 +1042,7 @@ OpenClaw 有多个高容量的提示/上下文预算，它们 #### `agents.defaults.contextLimits` -用于有界运行时上下文表面的共享默认值。 +用于有界运行时上下文面的共享默认值。 ```json5 { @@ -1059,15 +1060,15 @@ OpenClaw 有多个高容量的提示/上下文预算，它们 ``` - `memoryGetMaxChars`：`memory_get` 摘录在添加截断 - 元数据和续接提示之前的默认上限。 + 元数据和续接通知前的默认上限。 - `memoryGetDefaultLines`：省略 `lines` 时，`memory_get` 的默认行窗口。 - `toolResultMaxChars`：用于持久化结果和 溢出恢复的实时工具结果上限。 -- `postCompactionMaxChars`：用于压缩后刷新注入时的 AGENTS.md 摘录上限。 +- `postCompactionMaxChars`：压缩后刷新注入期间使用的 AGENTS.md 摘录上限。 #### `agents.list[].contextLimits` -共享 `contextLimits` 调节项的按智能体覆盖。省略的字段会继承 +用于共享 `contextLimits` 旋钮的按智能体覆盖。省略的字段会继承 自 `agents.defaults.contextLimits`。 ```json5 @@ -1094,7 +1095,7 @@ OpenClaw 有多个高容量的提示/上下文预算，它们 #### `skills.limits.maxSkillsPromptChars` -注入系统提示中的紧凑 Skills 列表的全局上限。此项 +注入系统提示的紧凑 Skills 列表的全局上限。此项 不会影响按需读取 `SKILL.md` 文件。 ```json5 @@ -1109,7 +1110,7 @@ OpenClaw 有多个高容量的提示/上下文预算，它们 #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Skills 提示预算的按智能体覆盖。 +用于 Skills 提示预算的按智能体覆盖。 ```json5 { @@ -1128,11 +1129,11 @@ Skills 提示预算的按智能体覆盖。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，transcript/工具图像块中图像最长边的最大像素尺寸。 +在调用提供商之前，转录 / 工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少视觉 token 使用量，以及以截图为主运行时的请求负载大小。 -较高的值会保留更多视觉细节。 +较低的值通常会减少视觉 token 用量，以及以截图为主的运行中的请求负载大小。 +较高的值则会保留更多视觉细节。 ```json5 { @@ -1142,7 +1143,7 @@ Skills 提示预算的按智能体覆盖。 ### `agents.defaults.userTimezone` -用于系统提示上下文的时区（不是消息时间戳）。会回退到主机时区。 +系统提示上下文使用的时区（不是消息时间戳）。会回退到宿主机时区。 ```json5 { @@ -1179,7 +1180,7 @@ Skills 提示预算的按智能体覆盖。 fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"], }, imageGenerationModel: { - primary: "openai/gpt-image-1", + primary: "openai/gpt-image-2", fallbacks: ["google/gemini-3.1-flash-image-preview"], }, videoGenerationModel: { @@ -1192,7 +1193,7 @@ Skills 提示预算的按智能体覆盖。 }, params: { cacheRetention: "long" }, // 全局默认提供商参数 embeddedHarness: { - runtime: "auto", // auto | pi | 已注册的 harness id，例如 codex + runtime: "auto", // auto | pi | 已注册 harness id，例如 codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1210,47 +1211,47 @@ Skills 提示预算的按智能体覆盖。 ``` - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 字符串形式仅设置主模型。 - - 对象形式设置主模型以及有序故障转移模型。 + - 字符串形式只设置主模型。 + - 对象形式设置主模型以及按顺序排列的故障转移模型。 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由 `image` 工具路径用作其视觉模型配置。 - - 当所选/默认模型不能接受图像输入时，也用作回退路由。 + - 作为 `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）。 - - 如果你直接选择某个 provider/model，也要配置匹配的提供商凭证/API key（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断出带凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。 + - 由共享图像生成能力，以及任何未来生成图像的工具 / 插件面使用。 + - 典型值：`google/gemini-3.1-flash-image-preview`（用于原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（用于 fal），或 `openai/gpt-image-2`（用于 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` 仍可推断出带凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个 provider/model，也要配置匹配的提供商凭证/API key。 + - 如果省略，`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` 仍可推断出带凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个 provider/model，也要配置匹配的提供商凭证/API key。 + - 如果省略，`video_generate` 仍可推断出一个基于认证的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个提供商 / 模型，也要配置匹配的提供商凭证 / API key。 - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 - `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 由 `pdf` 工具用于模型路由。 - - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到已解析的会话/默认模型。 + - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到已解析的会话 / 默认模型。 - `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。 -- `pdfMaxPages`：`pdf` 工具中提取回退模式默认考虑的最大页数。 -- `verboseDefault`：智能体的默认 verbose 级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 +- `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)。 -- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 可让已注册插件 harness 接管受支持模型，使用 `runtime: "pi"` 可强制使用内置 PI harness，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及 fallback add/remove 命令）会保存为规范对象形式，并在可能时保留现有 fallback 列表。 -- `maxConcurrent`：跨会话并行运行的最大智能体数（每个会话本身仍为串行）。默认值：4。 +- `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.embeddedHarness` `embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。 -大多数部署应保留默认值 `{ runtime: "auto", fallback: "pi" }`。 -当受信任插件提供原生 harness 时使用它，例如内置的 +大多数部署应保持默认值 `{ runtime: "auto", fallback: "pi" }`。 +当受信任插件提供原生 harness 时，请使用它，例如内置的 Codex app-server harness。 ```json5 @@ -1267,15 +1268,15 @@ Codex app-server harness。 } ``` -- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置 Codex 插件注册的是 `codex`。 +- `runtime`：`"auto"`、`"pi"` 或已注册插件 harness id。内置 Codex 插件注册的 id 为 `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 仍使用各自的 provider/model 设置。 +- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们各自的提供商 / 模型设置。 -**内置 alias 简写**（仅在模型位于 `agents.defaults.models` 中时生效）： +**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： -| Alias | 模型 | +| 别名 | 模型 | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1286,15 +1287,15 @@ Codex app-server harness。 | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -你配置的 alias 始终优先于默认值。 +你配置的别名始终优先于默认值。 -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` 可禁用。 +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 { @@ -1322,13 +1323,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- CLI 后端以文本为主；工具始终禁用。 +- CLI 后端以文本为主；工具始终被禁用。 - 设置了 `sessionArg` 时支持会话。 - 当 `imageArg` 接受文件路径时，支持图像透传。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别设置（`agents.defaults.systemPromptOverride`），也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅包含空白的值会被忽略。适用于受控提示实验。 +用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅空白值会被忽略。适用于受控提示实验。 ```json5 { @@ -1342,7 +1343,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.heartbeat` -定期 Heartbeat 运行。 +周期性心跳运行。 ```json5 { @@ -1352,9 +1353,9 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 every: "30m", // 0m 表示禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 部分 - lightContext: false, // 默认：false；true 仅保留工作区 bootstrap 文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 会在全新会话中运行每次 Heartbeat（无对话历史） + includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 节 + lightContext: false, // 默认：false；true 仅保留 workspace bootstrap 文件中的 HEARTBEAT.md + isolatedSession: false, // 默认：false；true 会在全新会话中运行每次心跳（无对话历史） session: "main", to: "+15555550123", directPolicy: "allow", // allow（默认）| block @@ -1369,15 +1370,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API-key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 -- `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。 -- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最长秒数。若未设置，则使用 `agents.defaults.timeoutSeconds`。 -- `directPolicy`：direct/私信投递策略。`allow`（默认）允许 direct-target 投递。`block` 会抑制 direct-target 投递，并输出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，Heartbeat 运行会使用轻量 bootstrap 上下文，并且仅保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次 Heartbeat 都会在一个没有任何既有对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 Heartbeat 的 token 成本从约 100K 降低到约 2-5K token。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。 -- Heartbeat 会运行完整的智能体轮次——更短的间隔会消耗更多 token。 +- `every`：时长字符串（ms / s / m / h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 +- `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 节，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：为 true 时，会在心跳运行期间抑制工具错误警告负载。 +- `timeoutSeconds`：心跳智能体轮次在中止前允许的最长秒数。若未设置，则使用 `agents.defaults.timeoutSeconds`。 +- `directPolicy`：直接 / 私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，心跳运行会使用轻量 bootstrap 上下文，并且仅保留 workspace bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳都会在一个全新会话中运行，不带任何先前对话历史。其隔离模式与 cron 的 `sessionTarget: "isolated"` 相同。可将每次心跳的 token 成本从约 100K 降至约 2-5K token。 +- 按智能体设置：使用 `agents.list[].heartbeat`。当任何智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 +- 心跳会运行完整的智能体轮次——间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -1387,19 +1388,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // 已注册 compaction 提供商插件的 id（可选） + provider: "my-provider", // 已注册 compaction provider 插件的 id（可选） timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "在压缩摘要期间，精确保留部署 ID、工单 ID 和 host:port 对。", // 当 identifierPolicy=custom 时使用 + identifierInstructions: "精确保留部署 ID、工单 ID 和 host:port 对。", // 当 identifierPolicy=custom 时使用 postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 model: "openrouter/anthropic/claude-sonnet-4-6", // 仅用于 compaction 的可选模型覆盖 notifyUser: true, // 在 compaction 开始和完成时发送简短通知（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "会话即将压缩。现在请存储持久记忆。", - prompt: "将任何持久笔记写入 memory/YYYY-MM-DD.md；如果没有需要存储的内容，请精确回复静默 token NO_REPLY。", + systemPrompt: "会话即将压缩。现在存储持久记忆。", + prompt: "将任何持久备注写入 memory/YYYY-MM-DD.md；如果没有需要存储的内容，请精确回复静默 token NO_REPLY。", }, }, }, @@ -1407,19 +1408,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册 compaction 提供商插件的 id。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时回退到内置实现。设置 provider 会强制使用 `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 provider 插件的 id。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时回退到内置实现。设置 provider 会强制使用 `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 之前执行的静默智能体轮次，用于存储持久记忆。当工作区为只读时会跳过。 +- `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 { @@ -1444,22 +1445,22 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `mode: "cache-ttl"` 会启用修剪流程。 -- `ttl` 控制多久之后才能再次运行修剪（自上次缓存触达之后）。 -- 修剪会先对过大的工具结果执行软修剪，然后在需要时对更旧的工具结果执行硬清除。 +- `ttl` 控制再次执行修剪的频率（从上次缓存触碰后开始计算）。 +- 修剪会先对过大的工具结果执行软截断，如有需要，再对更旧的工具结果执行硬清除。 -**软修剪**会保留开头 + 结尾，并在中间插入 `...`。 +**软截断**会保留开头 + 结尾，并在中间插入 `...`。 **硬清除**会用占位符替换整个工具结果。 -注意： +说明： -- 图像块永远不会被修剪/清除。 -- 比例是基于字符的（近似），不是精确 token 数。 +- 图像块永远不会被截断 / 清除。 +- 比例基于字符数（近似值），不是精确 token 数。 - 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。 -行为细节请参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为详情参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1477,13 +1478,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 非 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 { @@ -1496,7 +1497,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：私聊/被提及时为 `instant`，未被提及的群聊为 `message`。 +- 默认值：私聊 / 提及聊天为 `instant`，未提及的群聊为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 @@ -1505,7 +1506,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1615,37 +1616,37 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按作用域工作区的远程绝对根目录 +- `workspaceRoot`：用于按作用域 workspace 的远程绝对根目录 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 - `identityData` / `certificateData` / `knownHostsData`：OpenClaw 会在运行时将其实体化为临时文件的内联内容或 SecretRef -- `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 插件配置：** @@ -1675,30 +1676,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：执行前将本地内容同步到远程，执行后再同步回本地；本地工作区保持为规范副本 -- `remote`：在创建沙箱时仅初始化一次远程内容，之后保持远程工作区为规范副本 +- `mirror`：执行前将本地内容同步到远程，执行后再同步回来；本地 workspace 保持为规范副本 +- `remote`：创建沙箱时一次性初始化远程，之后保持远程 workspace 为规范副本 -在 `remote` 模式下，在 OpenClaw 外部对主机本地所做的编辑，在初始化之后不会自动同步到沙箱中。 -传输使用 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。 +在 `remote` 模式下，在初始化步骤之后，于 OpenClaw 外部在宿主机本地所做的编辑不会自动同步进沙箱。 +传输使用 SSH 连接到 OpenShell 沙箱，但该插件负责沙箱生命周期以及可选的镜像同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 +**`setupCommand`** 会在容器创建后执行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 -**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急兜底模式）。 +**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设为 `"bridge"`（或自定义 bridge 网络）。 +`"host"` 被阻止。默认情况下，`"container:"` 也会被阻止，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急开关）。 -**传入附件**会被暂存到活动工作区的 `media/inbound/*` 中。 +**传入附件** 会被暂存到活动 workspace 中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。 +**`docker.binds`** 会挂载额外的宿主目录；全局和按智能体的 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`。 -- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器宿主机进行了调优： +- `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=` - `--user-data-dir=${HOME}/.chrome` @@ -1716,17 +1717,17 @@ noVNC 观察者访问默认使用 VNC 认证，且 OpenClaw 会发出一个短 - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions`（默认启用） - - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用；如果 WebGL/3D 使用场景需要，可通过 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 + - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认 + 启用；如果 WebGL / 3D 使用需要它们，可通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用。 - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，如果你的工作流 依赖它们。 - `--renderer-process-limit=2` 可通过 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的 - 默认进程上限。 - - 以及当启用 `noSandbox` 时的 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带自定义 - 入口点的自定义浏览器镜像。 + 默认进程限制。 + - 以及当启用 `noSandbox` 时附加的 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义 + entrypoint 的自定义浏览器镜像。 @@ -1736,7 +1737,7 @@ noVNC 观察者访问默认使用 VNC 认证，且 OpenClaw 会发出一个短 ```bash scripts/sandbox-setup.sh # 主沙箱镜像 -scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 +scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ``` ### `agents.list`（按智能体覆盖） @@ -1754,7 +1755,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } thinkingDefault: "high", // 按智能体覆盖 thinking 级别 reasoningDefault: "on", // 按智能体覆盖 reasoning 可见性 - fastModeDefault: false, // 按智能体覆盖 fast mode + fastModeDefault: false, // 按智能体覆盖快速模式 embeddedHarness: { runtime: "auto", fallback: "pi" }, params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params skills: ["docs-search"], // 设置后会替换 agents.defaults.skills @@ -1789,26 +1790,26 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ``` - `id`：稳定的智能体 id（必填）。 -- `default`：当设置了多个时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个条目是默认值。 -- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局 fallback）。仅覆盖 `primary` 的 cron 作业仍会继承默认 fallback，除非你设置 `fallbacks: []`。 -- `params`：合并到 `agents.defaults.models` 中所选模型条目之上的按智能体 stream 参数。用于对某个智能体做特定覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。若省略，则当设置了 `agents.defaults.skills` 时该智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当没有按消息或会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当没有按消息或会话级 reasoning 覆盖时生效。 -- `fastModeDefault`：可选的按智能体默认 fast mode（`true | false`）。当没有按消息或会话级 fast-mode 覆盖时生效。 -- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某一个智能体仅使用 Codex，而其他智能体保留默认的 PI fallback。 -- `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 | max`）。当未设置按消息或按会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。 +- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话 reasoning 覆盖时生效。 +- `fastModeDefault`：可选的按智能体快速模式默认值（`true | false`）。当未设置按消息或按会话快速模式覆盖时生效。 +- `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 { @@ -1827,11 +1828,11 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（缺失时默认是 route），持久化 ACP 会话绑定使用 `acp`。 +- `type`（可选）：`route` 用于常规路由（缺失时默认是 route），`acp` 用于持久化 ACP 会话绑定。 - `match.channel`（必填） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；渠道特定） +- `match.guildId` / `match.teamId`（可选；特定渠道） - `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1839,15 +1840,15 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（精确匹配，无 peer/guild/team） +4. `match.accountId`（精确匹配，无 peer / guild / team） 5. `match.accountId: "*"`（渠道范围） 6. 默认智能体 -在每个层级内，第一个匹配的 `bindings` 条目获胜。 +在每一层级内，第一个匹配的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 会按精确会话标识（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确会话标识（`match.channel` + 账号 + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。 -### 按智能体访问配置 +### 按智能体划分的访问配置文件 @@ -1867,7 +1868,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 - + ```json5 { @@ -1942,7 +1943,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 -优先级细节请参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级详情参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1968,7 +1969,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程 fork（0 表示禁用） + parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程分叉（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1980,8 +1981,8 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时设置的非活动自动取消聚焦（`0` 表示禁用） - maxAgeHours: 0, // 默认按小时设置的硬性最大存活期（`0` 表示禁用） + idleHours: 24, // 默认按小时计算的不活跃自动取消聚焦（`0` 表示禁用） + maxAgeHours: 0, // 默认按小时计算的硬最大存续时间（`0` 表示禁用） }, mainKey: "main", // 旧版字段（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, @@ -1996,34 +1997,34 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在同一渠道上下文中，每个发送者都有独立会话。 - - `global`：同一渠道上下文中的所有参与者共享一个会话（仅在你明确需要共享上下文时使用）。 + - `per-sender`（默认）：每个发送者在渠道上下文内获得独立会话。 + - `global`：渠道上下文中的所有参与者共享单一会话（仅在需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - - `per-peer`：按发送者 id 跨渠道隔离。 + - `per-peer`：按发送者 id 在跨渠道范围内隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 id 映射到带提供商前缀的对端标识，用于跨渠道共享会话。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都配置时，哪个先到期就以哪个为准。 +- **`identityLinks`**：将规范 id 映射到带提供商前缀的对端，用于跨渠道共享会话。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都配置时，谁先到期就以谁为准。 - **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建 fork 线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。 - - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个全新的线程会话，而不是继承父会话 transcript 历史。 - - 设为 `0` 可禁用此保护，并始终允许父会话 fork。 +- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。 + - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父转录历史。 + - 设为 `0` 可禁用此保护，并始终允许父会话分叉。 - **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间在 agent-to-agent 交互期间的最大来回回复轮数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链。 -- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 进行匹配。第一个 deny 生效。 +- **`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.` transcript 归档的保留时长。默认继承 `pruneAfter`；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的工件/会话。 + - `rotateBytes`：当 `sessions.json` 超过此大小时进行轮换（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留时间。默认为 `pruneAfter`；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的产物 / 会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时设置的非活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认按小时设置的硬性最大存活期（`0` 表示禁用；提供商可覆盖） + - `idleHours`：默认按小时计算的不活跃自动取消聚焦时间（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：默认按小时计算的硬最大存续时间（`0` 表示禁用；提供商可覆盖） @@ -2061,19 +2062,19 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ### 响应前缀 -按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +按渠道 / 账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会推导为 `[{identity.name}]`。 +解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 **模板变量：** -| Variable | 说明 | 示例 | -| ----------------- | ---- | ---- | -| `{model}` | 短模型名 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体 identity 名称 | （与 `"auto"` 相同） | +| 变量 | 说明 | 示例 | +| ----------------- | ---------------- | --------------------------- | +| `{model}` | 短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 @@ -2082,15 +2083,15 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 - 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，会在回复后移除确认反应。 +- 范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除确认反应。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则保持状态反应启用。 - 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时，如果确认反应处于激活状态，则状态反应保持启用。 + 在 Telegram 上，需将其显式设为 `true` 才会启用生命周期状态反应。 -### 入站去抖 +### 入站防抖 -将来自同一发送者的快速连续纯文本消息批处理为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过去抖。 +将同一发送者快速连续发送的纯文本消息合并为一次智能体轮次。媒体 / 附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -2135,16 +2136,16 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 - `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 - `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 -- `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-compatible TTS 服务器，并放宽模型/voice 校验。 +- `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 { @@ -2168,51 +2169,51 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 +- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `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 对象。 -- 仅当未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 -- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久才发送 transcript。未设置时会保留平台默认暂停窗口（`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: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: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 { @@ -2222,7 +2223,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.byProvider` -进一步限制特定提供商或模型的工具。顺序：基础 profile → 提供商 profile → allow/deny。 +进一步为特定提供商或模型限制工具。顺序：基础配置文件 → 提供商配置文件 → allow / deny。 ```json5 { @@ -2238,7 +2239,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.elevated` -控制沙箱之外的 elevated `exec` 访问： +控制沙箱外的 elevated exec 访问： ```json5 { @@ -2254,9 +2255,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧权限。 -- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 -- Elevated `exec` 会绕过沙箱隔离，并使用已配置的 escape 路径（默认是 `gateway`，或当 exec 目标是 `node` 时使用 `node`）。 +- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅对单条消息生效。 +- Elevated `exec` 会绕过沙箱隔离，并使用已配置的 escape 路径（默认是 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。 ### `tools.exec` @@ -2280,8 +2281,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.loopDetection` -工具循环安全检查默认**关闭**。设置 `enabled: true` 以启用检测。 -设置可在全局 `tools.loopDetection` 中定义，也可按智能体在 `agents.list[].tools.loopDetection` 中覆盖。 +工具循环安全检查默认**关闭**。设置 `enabled: true` 可启用检测。 +设置可在全局 `tools.loopDetection` 中定义，也可在按智能体的 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -2303,12 +2304,12 @@ Talk 模式的默认值（macOS/iOS/Android）。 ``` - `historySize`：为循环分析保留的最大工具调用历史。 -- `warningThreshold`：对重复无进展模式发出警告的阈值。 +- `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` @@ -2343,7 +2344,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.media` -配置传入媒体理解（图像/音频/视频）： +配置入站媒体理解（图像 / 音频 / 视频）： ```json5 { @@ -2351,7 +2352,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 media: { concurrency: 2, asyncCompletion: { - directSend: false, // 显式启用：将已完成的异步音乐/视频直接发送到渠道 + directSend: false, // 选择启用：将已完成的异步音乐 / 视频直接发送到渠道 }, audio: { enabled: true, @@ -2379,7 +2380,7 @@ 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` 配置文件选择 @@ -2390,7 +2391,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`：按条目覆盖。 - 失败时会回退到下一个条目。 @@ -2399,8 +2400,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 **异步完成字段：** - `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会优先尝试直接渠道投递。默认值：`false` - （旧版请求方会话唤醒/模型投递路径）。 + 和 `video_generate` 任务会先尝试直接渠道投递。默认值：`false` + （旧版请求者会话唤醒 / 模型投递路径）。 @@ -2419,9 +2420,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.sessions` -控制 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）可定位哪些会话。 +控制哪些会话可以成为会话工具（`sessions_list`、`sessions_history`、`sessions_send`）的目标。 -默认值：`tree`（当前会话 + 由其生成的会话，例如子智能体）。 +默认值：`tree`（当前会话 + 由其生成的会话，例如 subagents）。 ```json5 { @@ -2434,13 +2435,13 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -注意： +说明： - `self`：仅当前会话键。 -- `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 -- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行按发送者隔离的会话，可能包含其他用户）。 -- `all`：任意会话。跨智能体定位仍要求 `tools.agentToAgent`。 -- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- `tree`：当前会话 + 由当前会话生成的会话（subagents）。 +- `agent`：属于当前智能体 id 的任何会话（如果你在同一智能体 id 下按发送者运行会话，可能包括其他用户）。 +- `all`：任何会话。跨智能体目标仍要求 `tools.agentToAgent`。 +- 沙箱收紧：当当前会话处于沙箱隔离中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2451,7 +2452,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 tools: { sessions_spawn: { attachments: { - enabled: false, // 显式启用：设为 true 以允许内联文件附件 + enabled: false, // 选择启用：设为 true 以允许内联文件附件 maxTotalBytes: 5242880, // 所有文件总计 5 MB maxFiles: 50, maxFileBytes: 1048576, // 每个文件 1 MB @@ -2462,18 +2463,18 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -注意： +说明： - 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会被实体化到子工作区的 `.openclaw/attachments//` 中，并附带一个 `.manifest.json`。 -- 附件内容会自动从 transcript 持久化中脱敏。 -- Base64 输入会使用严格的字母表/填充校验，以及解码前大小保护进行验证。 -- 文件权限为目录 `0700`、文件 `0600`。 -- 清理遵循 `cleanup` 策略：`delete` 始终移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 +- 文件会被实体化到子 workspace 的 `.openclaw/attachments//` 中，并带有 `.manifest.json`。 +- 附件内容会自动从转录持久化中脱敏。 +- Base64 输入会通过严格的字母表 / 填充校验以及解码前大小保护进行验证。 +- 文件权限为：目录 `0700`，文件 `0600`。 +- 清理遵循 `cleanup` 策略：`delete` 总是删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留它们。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非严格 agentic GPT-5 自动启用规则生效。 +实验性内置工具开关。默认关闭，除非适用 strict-agentic GPT-5 自动启用规则。 ```json5 { @@ -2485,11 +2486,11 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -注意： +说明： - `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）被设为 `"strict-agentic"`，且当前运行是 OpenAI 或 OpenAI Codex GPT-5 家族。设为 `true` 可在该范围之外强制启用此工具，设为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。 -- 启用后，系统提示还会添加使用指南，使模型仅在实质性工作中使用它，并始终最多只保留一个 `in_progress` 步骤。 +- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）被设置为 OpenAI 或 OpenAI Codex GPT-5 系列运行的 `"strict-agentic"`。设为 `true` 可在该范围外强制启用该工具，设为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。 +- 启用后，系统提示还会加入使用指引，使模型仅在实质性工作中使用它，并始终最多保持一个步骤处于 `in_progress`。 ### `agents.defaults.subagents` @@ -2509,9 +2510,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `model`：生成的子智能体默认模型。若省略，子智能体会继承调用方模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 id 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时时长（秒）。`0` 表示无超时。 +- `model`：生成的子智能体的默认模型。若省略，子智能体会继承调用方模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，用于 `sessions_spawn` 目标智能体 id 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时（秒）。`0` 表示无超时。 - 按子智能体的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- @@ -2548,45 +2549,45 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ ``` - 对于自定义认证需求，使用 `authHeader: true` + `headers`。 -- 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用旧版环境变量别名 `PI_CODING_AGENT_DIR`）。 -- 匹配提供商 id 的合并优先级： +- 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 +- 对匹配提供商 ID 的合并优先级： - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在当前配置/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` 会在存在时保留显式运行时上限；用它可限制生效上下文，而不更改模型的原生元数据。 + - 非空的智能体 `apiKey` 值仅在该提供商在当前配置 / 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 值。 + - 标记持久化遵循来源权威：标记写入自活动来源配置快照（解析前），而不是已解析的运行时 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`：用于代理/租户路由的额外静态 header。 +- `models.providers.*.headers`：用于代理 / 租户路由的额外静态 headers。 - `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 - - `request.headers`：额外 header（与提供商默认值合并）。值支持 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 解析到私有、CGNAT 或类似网段时，允许通过提供商 HTTP 获取保护访问 `baseUrl` 上的 HTTPS（这是针对受信任自托管 OpenAI-compatible 端点的 operator 显式启用项）。WebSocket 对 header/TLS 也使用相同的 `request`，但不使用该 fetch 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 解析为私有、CGNAT 或类似地址范围时，允许通过提供商 HTTP fetch 防护访问 `baseUrl` 上的 HTTPS（适用于对受信任自托管 OpenAI 兼容端点的 operator 选择启用）。WebSocket 对 headers / TLS 使用相同的 `request`，但不使用该 fetch 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-compatible 聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前，将纯文本 `messages[].content` 数组扁平化为普通字符串。 +- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时，请使用此项。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且非空、非原生的 `baseUrl`（host 不是 `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.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.providerFilter`：用于定向发现的可选提供商 id 过滤器。 +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新轮询间隔。 - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。 - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。 @@ -2626,7 +2627,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 +对 Cerebras 使用 `cerebras/zai-glm-4.7`；对 Z.AI 直连使用 `zai/glm-4.7`。 @@ -2643,7 +2644,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`。 @@ -2664,7 +2665,7 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 - 通用端点：`https://api.z.ai/api/paas/v4` - Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 若要使用通用端点，请定义带 base URL 覆盖的自定义提供商。 +- 对于通用端点，请定义带有 base URL 覆盖的自定义提供商。 @@ -2703,11 +2704,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 会基于端点能力 -而不仅仅是内置提供商 id 来决定相关行为。 +`openai-completions` 传输上声明流式使用兼容性，OpenClaw 会根据端点能力来决定 +相关行为，而不只是依据内置提供商 id。 @@ -2725,11 +2726,11 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 } ``` -内置的 Anthropic-compatible 提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +兼容 Anthropic 的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - + ```json5 { @@ -2764,7 +2765,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`。 @@ -2808,16 +2809,15 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 模型目录默认仅包含 M2.7。 -在 Anthropic-compatible 流式路径上，除非你显式设置 `thinking`，否则 OpenClaw -默认会禁用 MiniMax thinking。`/fast on` 或 -`params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 +在兼容 Anthropic 的流式路径上，除非你显式设置 `thinking`，否则 OpenClaw 默认会关闭 MiniMax thinking。 +`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在较强硬件上通过 LM Studio Responses API 运行大型本地模型；保留已合并的托管模型作为回退。 +参见 [本地模型](/zh-CN/gateway/local-models)。简要说明：在性能足够强的硬件上，通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 @@ -2838,7 +2838,7 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或纯文本字符串 + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或明文字符串 env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2848,13 +2848,14 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（对受管/workspace Skills 无影响）。 +- `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 对象）。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器， + 然后才回退到其他安装器类型。 +- `install.nodeManager`：用于 `metadata.openclaw.install` + 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使 Skills 已内置 / 已安装，也会将其禁用。 +- `entries..apiKey`：用于声明主环境变量的 Skills 的便捷项（明文字符串或 SecretRef 对象）。 --- @@ -2884,41 +2885,41 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 - 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 -- **配置更改需要重启 Gateway 网关。** +- **配置变更需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便利字段（当插件支持时）。 -- `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hook 和受支持 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 key（支持 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 +- `plugins.entries..env`：插件作用域的环境变量映射。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `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`）。 + - `maxAgeMs`：最大缓存时长（毫秒）（默认：`172800000` / 2 天）。 + - `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 配置位于 [内存配置参考](/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 插件。 +- 已启用的 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`。 + - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - 将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令，而不是手动编辑。 -参见 [Plugins](/zh-CN/tools/plugin)。 +参见 [插件](/zh-CN/tools/plugin)。 --- @@ -2931,7 +2932,7 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问场景下显式启用 + // dangerouslyAllowPrivateNetwork: true, // 仅在信任私有网络访问时选择启用 // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2959,28 +2960,28 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用，因此浏览器导航默认保持严格模式。 -- 仅当你明确相信私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP profile 端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止。 +- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用状态，因此浏览器导航默认保持严格模式。 +- 仅当你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性 / 发现检查期间也会受到相同的私有网络阻止。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 - 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。 -- 远程 profile 是仅附加模式（禁用 start/stop/reset）。 +- 远程配置文件为仅附加模式（禁用 start / stop / reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)； - 当提供方直接给你 DevTools WebSocket URL 时，使用 WS(S)。 -- `existing-session` profile 使用 Chrome MCP 而不是 CDP，并且可以在所选主机上附加， - 或通过已连接的浏览器节点附加。 -- `existing-session` profile 可以设置 `userDataDir`，以定位特定的 - Chromium-based 浏览器 profile，例如 Brave 或 Edge。 -- `existing-session` profile 保留当前 Chrome MCP 的路由限制： - 使用基于快照/ref 的操作，而不是 CSS 选择器定位、单文件上传 - hook、无对话框超时覆盖、无 `wait --load networkidle`，并且不支持 + 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；使用 WS(S) + 则适用于你的提供商直接给出 DevTools WebSocket URL 的情况。 +- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可在 + 选定宿主上或通过已连接的浏览器节点进行附加。 +- `existing-session` 配置文件可设置 `userDataDir` 以指定某个特定的 + 基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。 +- `existing-session` 配置文件仍保留当前 Chrome MCP 路由限制： + 使用 snapshot / ref 驱动的操作而非 CSS 选择器定位、单文件上传 + hooks、无对话框超时覆盖、无 `wait --load networkidle`，以及不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地受管的 `openclaw` profile 会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 时 - 才显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器（如果是 Chromium-based）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- Control 服务：仅限 loopback（端口派生自 `gateway.port`，默认 `18791`）。 -- `extraArgs` 会为本地 Chromium 启动追加额外启动标志（例如 +- 本地受管 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在 + 远程 CDP 场景下才显式设置 `cdpUrl`。 +- 自动检测顺序：默认浏览器（若为基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅限 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会为本地 Chromium 启动附加额外启动标志（例如 `--disable-gpu`、窗口尺寸或调试标志）。 --- @@ -2993,14 +2994,14 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji、短文本、图片 URL 或 data URI + avatar: "CB", // emoji、短文本、图像 URL 或 data URI }, }, } ``` -- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 -- `assistant`：Control UI 的 identity 覆盖。会回退到活动智能体 identity。 +- `seamColor`：原生应用 UI 外壳的强调色（Talk Mode 气泡着色等）。 +- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。 --- @@ -3036,7 +3037,7 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 // embedSandbox: "scripts", // strict | scripts | trusted // allowExternalEmbedUrls: false, // 危险：允许绝对外部 http(s) 嵌入 URL // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header origin 回退模式 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3069,64 +3070,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`），不要使用 host 别名（`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 认证模式。该无 token 流程假设 Gateway 网关主机是受信任的。当 `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 暴力破解的纵深防御）。 +- **Docker 说明**：默认的 `loopback` 绑定会在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 gateway 不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并搭配 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认必需。非 loopback 绑定要求 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` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 代理来源；同主机上的 loopback 反向代理不满足 trusted-proxy 认证条件。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可满足 Control UI / WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头认证；它们仍遵循 gateway 的常规 HTTP 认证模式。该无 token 流程假定 gateway 宿主机是受信任的。当 `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 暴力破解的纵深防御）。 - 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin` - 值进行隔离，因此一个 localhost origin 的重复失败不会自动 - 锁死另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预期有来自非 loopback 源的浏览器客户端时必填。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，会为有意依赖 Host header 源策略的部署启用 Host-header origin 回退。 -- `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。 -- `gateway.channelHealthCheckMinutes`：渠道健康监视器间隔（分钟）。设为 `0` 可全局禁用基于健康监视器的重启。默认值：`5`。 -- `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。只列出你控制的代理。对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理），loopback 条目仍然有效，但它们**不会**使 loopback 请求具备 `gateway.auth.mode: "trusted-proxy"` 的资格。 -- `allowRealIpFallback`：为 `true` 时，当 `X-Forwarded-For` 缺失时，Gateway 网关会接受 `X-Real-IP`。默认 `false`，采用默认拒绝行为。 + 值进行隔离，因此某个 localhost origin 的重复失败不会自动 + 锁定另一个 origin。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公网，需要认证）。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预期浏览器客户端来自非 loopback 源时为必填项。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为那些有意依赖 Host-header origin 策略的部署启用 Host-header origin 回退。 +- `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 base 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。 +- `gateway.channelHealthCheckMinutes`：渠道健康监视器间隔（分钟）。设为 `0` 可全局禁用健康监视器重启。默认值：`5`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道 / 账号允许的健康监视器最大重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：按渠道选择退出健康监视器重启，同时保持全局监视器启用。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后优先于渠道级覆盖。 +- 本地 gateway 调用路径仅在 `gateway.auth.*` 未设置时，才可将 `gateway.remote.*` 用作回退。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析，解析会以失败关闭方式处理（不会用远程回退来掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。仅列出你控制的代理。对于同主机代理 / 本地检测场景（例如 Tailscale Serve 或本地反向代理），loopback 条目仍然有效，但它们**不会**让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。 +- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时，gateway 会接受 `X-Real-IP`。默认 `false`，以保持失败关闭行为。 - `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认 deny 列表）。 -- `gateway.tools.allow`：将工具名从默认 HTTP deny 列表中移除。 +- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名。 -### OpenAI-compatible 端点 +### 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` - 空 allowlist 会被视为未设置；如需禁用 URL 获取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和/或 `gateway.http.endpoints.responses.images.allowUrl=false`。 -- 可选的响应加固 header： + 空允许列表会被视为未设置；使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 和 / 或 `gateway.http.endpoints.responses.images.allowUrl=false` 可禁用 URL 抓取。 +- 可选响应加固 header： - `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 \ @@ -3154,10 +3155,10 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 -- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅用于本地/开发环境。 +- `enabled`：在 gateway 监听器上启用 TLS 终止（HTTPS / WSS）（默认：`false`）。 +- `autoGenerate`：在未配置显式文件时自动生成本地自签名证书 / 密钥对；仅用于本地 / 开发场景。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；应限制权限。 +- `keyPath`：TLS 私钥文件的文件系统路径；请限制其访问权限。 - `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 ### `gateway.reload` @@ -3174,13 +3175,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制配置编辑如何在运行时应用。 - - `"off"`：忽略实时编辑；更改需要显式重启。 - - `"restart"`：配置变更时始终重启 Gateway 网关进程。 - - `"hot"`：不重启，直接在进程内应用更改。 - - `"hybrid"`（默认）：先尝试热重载；必要时回退到重启。 -- `debounceMs`：应用配置更改前的去抖窗口，单位毫秒（非负整数）。 -- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最长时间，单位毫秒（默认：`300000` = 5 分钟）。 +- `mode`：控制在运行时如何应用配置编辑。 + - `"off"`：忽略实时编辑；变更需要显式重启。 + - `"restart"`：配置变更时始终重启 gateway 进程。 + - `"hot"`：在不重启的情况下进程内应用变更。 + - `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。 +- `debounceMs`：应用配置变更前的防抖窗口（毫秒）（非负整数）。 +- `deferralTimeoutMs`：在强制重启前，为进行中的操作等待的最长时间（毫秒）（默认：`300000` = 5 分钟）。 --- @@ -3207,7 +3208,7 @@ openclaw gateway --port 19001 wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", - messageTemplate: "发件人：{{messages[0].from}}\n主题：{{messages[0].subject}}\n{{messages[0].snippet}}", + messageTemplate: "来自：{{messages[0].from}}\n主题：{{messages[0].subject}}\n{{messages[0].snippet}}", deliver: true, channel: "last", model: "openai/gpt-5.4-mini", @@ -3218,36 +3219,36 @@ openclaw gateway --port 19001 ``` 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -查询字符串中的 hook token 会被拒绝。 +拒绝查询字符串中的 hook token。 -验证与安全说明： +验证和安全说明： -- `hooks.enabled=true` 要求提供非空 `hooks.token`。 +- `hooks.enabled=true` 要求 `hooks.token` 为非空。 - `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。 - `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。 - 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果某个 mapping 或 preset 使用模板化 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态 mapping key 不需要该显式启用项。 +- 如果某个映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该选择启用项。 **端点：** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受请求负载中的 `sessionKey`。 + - 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受来自请求负载的 `sessionKey`。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - - 模板渲染后的 mapping `sessionKey` 值会被视为外部提供，因此也要求 `hooks.allowRequestSessionKey=true`。 + - 模板渲染后的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 - `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 匹配通用路径中的某个负载字段。 -- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取值。 -- `transform` 可以指向一个返回 hook action 的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且必须位于 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 -- `agentId` 会路由到特定智能体；未知 id 会回退到默认值。 +- `match.source` 为通用路径匹配某个负载字段。 +- 类似 `{{messages[0].subject}}` 的模板会从负载中读取。 +- `transform` 可指向一个返回 hook action 的 JS / TS 模块。 + - `transform.module` 必须是相对路径，并且保持在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 +- `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 -- `defaultSessionKey`：hook 智能体运行在未显式提供 `sessionKey` 时使用的可选固定会话键。 +- `defaultSessionKey`：对未显式设置 `sessionKey` 的 hook 智能体运行使用的可选固定会话键。 - `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或 preset 使用模板化 `sessionKey` 时，该项变为必需。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化 `sessionKey` 时，它会成为必填项。 - `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 - `model` 会为此次 hook 运行覆盖 LLM（如果设置了模型目录，则该模型必须在允许范围内）。 @@ -3255,9 +3256,9 @@ openclaw gateway --port 19001 ### Gmail 集成 -- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 +- 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 - 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 约束为匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 -- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该 preset，而不是使用模板化默认值。 +- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该预设，而不是使用默认的模板化值。 ```json5 { @@ -3281,7 +3282,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`。 --- @@ -3297,17 +3298,17 @@ 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 网关会为该节点通告有作用域限制的能力 URL，用于访问 canvas/A2UI。 -- 能力 URL 绑定到当前活动的节点 WS 会话，并且很快过期。不会使用基于 IP 的回退。 -- 将 live-reload 客户端注入到所提供的 HTML 中。 -- 为空时会自动创建起始 `index.html`。 +- 非 loopback 绑定：canvas 路由与其他 Gateway 网关 HTTP 面一样，需要 Gateway 网关认证（token / password / trusted-proxy）。 +- 节点 WebView 通常不会发送认证头；当节点完成配对并连接后，Gateway 网关会为 canvas / A2UI 访问发布按节点范围划分的 capability URL。 +- Capability URL 绑定到活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 +- 会向所提供的 HTML 中注入 live-reload 客户端。 +- 为空时会自动创建初始 `index.html`。 - 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 -- 更改需要重启 Gateway 网关。 +- 变更需要重启 Gateway 网关。 - 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 --- @@ -3326,7 +3327,7 @@ openclaw gateway --port 19001 } ``` -- `minimal`（默认）：在 TXT 记录中省略 `cliPath` + `sshPort`。 +- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。 - `full`：包含 `cliPath` + `sshPort`。 - 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 @@ -3340,7 +3341,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`。 @@ -3365,14 +3366,14 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境缺少该键时，才会应用内联环境变量。 +- 仅当进程环境中缺少该键时，才会应用内联环境变量。 - `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 -- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。 -- 完整优先级请参见 [Environment](/zh-CN/help/environment)。 +- `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 +- 完整优先级参见 [Environment](/zh-CN/help/environment)。 ### 环境变量替换 -可在任意配置字符串中用 `${VAR_NAME}` 引用环境变量： +可在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -3383,19 +3384,19 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/为空的变量会在配置加载时抛出错误。 -- 使用 `$${VAR}` 转义为字面量 `${VAR}`。 +- 缺失 / 为空的变量会在配置加载时抛出错误。 +- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 - 适用于 `$include`。 --- ## Secrets -Secret ref 是增量功能：纯文本值仍然可用。 +SecretRef 是增量式的：明文值仍然可用。 ### `SecretRef` -使用以下对象形状之一： +使用以下对象结构： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3407,21 +3408,21 @@ Secret ref 是增量功能：纯文本值仍然可用。 - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` 的 id：绝对 JSON pointer（例如 `"/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` refs 包含在运行时解析和审计覆盖范围中。 +- `secrets apply` 面向受支持的 `openclaw.json` 凭证路径。 +- `auth-profiles.json` 引用也包含在运行时解析和审计覆盖范围中。 -### Secret providers 配置 +### Secret 提供商配置 ```json5 { secrets: { providers: { - default: { source: "env" }, // 可选的显式 env provider + default: { source: "env" }, // 可选的显式 env 提供商 filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3445,17 +3446,17 @@ Secret ref 是增量功能：纯文本值仍然可用。 说明： -- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。 -- `exec` provider 要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。 -- 默认会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可在验证解析后的目标路径时允许符号链接路径。 -- 如果配置了 `trustedDirs`，受信任目录检查会应用到解析后的目标路径。 -- 默认情况下，`exec` 子进程环境是最小化的；请使用 `passEnv` 显式传递所需变量。 -- Secret refs 会在激活时解析到内存快照中，之后请求路径仅从该快照读取。 -- 激活期间会应用活动表面过滤：启用表面上的未解析 refs 会导致启动/重载失败，而非活动表面会被跳过并附带诊断信息。 +- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin / stdout 上的协议负载进行通信。 +- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可在验证已解析目标路径的同时允许符号链接路径。 +- 如果配置了 `trustedDirs`，则受信任目录检查会应用于已解析目标路径。 +- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传入所需变量。 +- Secret 引用会在激活时解析为内存快照，之后请求路径只读取该快照。 +- 激活期间会应用活动表面过滤：启用表面上的未解析引用会导致启动 / 重载失败，而非活动表面会被跳过并附带诊断信息。 --- -## Auth 存储 +## 凭证存储 ```json5 { @@ -3473,13 +3474,13 @@ Secret ref 是增量功能：纯文本值仍然可用。 } ``` -- 按智能体的配置文件存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持静态凭证模式的值级 refs（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- 按智能体配置文件存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 支持静态凭证模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 - OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自内存中已解析的快照；发现旧版静态 `auth.json` 条目时会进行清理。 -- 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。 +- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会将其清理。 +- 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。 - 参见 [OAuth](/zh-CN/concepts/oauth)。 -- Secrets 运行时行为以及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。 +- Secrets 运行时行为及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -3501,20 +3502,20 @@ Secret ref 是增量功能：纯文本值仍然可用。 } ``` -- `billingBackoffHours`：当某个配置文件因真实的 - 计费/额度不足错误而失败时的基础退避小时数（默认：`5`）。显式计费文本 - 即使出现在 `401`/`403` 响应上，也仍可能落入该路径，但提供商特定的文本 - 匹配器仍会限定在拥有它们的提供商范围内（例如 OpenRouter 的 - `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 - organization/workspace 支出上限消息则仍归入 `rate_limit` 路径。 +- `billingBackoffHours`：当配置文件因真实的 + 计费 / 余额不足错误而失败时的基础退避小时数（默认：`5`）。明确的计费文本 + 即使出现在 `401` / `403` 响应中，仍可能归入这里，但提供商特定的文本 + 匹配器仍限定在所属提供商范围内（例如 OpenRouter 的 + `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或 + 组织 / 工作区支出限制消息则仍归入 `rate_limit` 路径。 - `billingBackoffHoursByProvider`：可选的按提供商计费退避小时数覆盖。 -- `billingMaxHours`：计费退避指数增长的小时上限（默认：`24`）。 +- `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`。 +- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限分钟数（默认：`60`）。 +- `failureWindowHours`：用于退避计数器的滚动窗口小时数（默认：`24`）。 +- `overloadedProfileRotations`：对于过载错误，在切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。如 `ModelNotReadyException` 这类提供商繁忙形态会归入这里。 +- `overloadedBackoffMs`：重试某个过载提供商 / 配置文件轮换前的固定延迟（默认：`0`）。 +- `rateLimitedProfileRotations`：对于速率限制错误，在切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。该速率限制桶包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -3534,9 +3535,9 @@ Secret ref 是增量功能：纯文本值仍然可用。 ``` - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 -- 设置 `logging.file` 可使用固定路径。 -- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。 -- `maxFileBytes`：日志文件在抑制写入前的最大大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- 设置 `logging.file` 可使用稳定路径。 +- 传入 `--verbose` 时，`consoleLevel` 会提升到 `debug`。 +- `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮换。 --- @@ -3574,19 +3575,19 @@ Secret ref 是增量功能：纯文本值仍然可用。 ``` - `enabled`：instrumentation 输出的总开关（默认：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持如 `"telegram.*"` 或 `"*"` 的通配符）。 -- `stuckSessionWarnMs`：当会话保持在 processing 状态时，用于发出卡住会话警告的年龄阈值，单位毫秒。 +- `flags`：用于启用定向日志输出的标志字符串数组（支持如 `"telegram.*"` 或 `"*"` 这样的通配符）。 +- `stuckSessionWarnMs`：当某个会话仍处于 processing 状态时，发出卡住会话警告的年龄阈值（毫秒）。 - `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。 -- `otel.endpoint`：OTel 导出的采集器 URL。 +- `otel.endpoint`：OTel 导出的 collector URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求一同发送的额外 HTTP/gRPC 元数据 header。 -- `otel.serviceName`：资源属性中的服务名称。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 logs 导出。 +- `otel.headers`：随 OTel 导出请求发送的额外 HTTP / gRPC 元数据 headers。 +- `otel.serviceName`：资源属性中的服务名。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 - `otel.sampleRate`：trace 采样率，范围 `0`–`1`。 -- `otel.flushIntervalMs`：周期性遥测刷新间隔，单位毫秒。 +- `otel.flushIntervalMs`：定期刷出 telemetry 的间隔（毫秒）。 - `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。 - `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认都为 `true`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认全为 `true`）。 --- @@ -3608,12 +3609,12 @@ Secret ref 是增量功能：纯文本值仍然可用。 } ``` -- `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`：stable 渠道自动应用前的最小延迟小时数（默认：`6`；最大：`168`）。 +- `auto.stableJitterHours`：stable 渠道额外的滚动发布扩散窗口小时数（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时）（默认：`1`；最大：`24`）。 --- @@ -3646,22 +3647,22 @@ Secret ref 是增量功能：纯文本值仍然可用。 } ``` -- `enabled`：ACP 功能的全局开关（默认：`false`）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 +- `enabled`：全局 ACP 功能开关（默认：`false`）。 +- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在阻止执行的同时保留 ACP 命令可用。 - `backend`：默认 ACP 运行时后端 id（必须匹配某个已注册 ACP 运行时插件）。 -- `defaultAgent`：当 spawn 未指定显式目标时，使用的回退 ACP 目标智能体 id。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示不增加额外限制。 -- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。 -- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口，单位毫秒。 +- `defaultAgent`：当生成操作未指定显式目标时使用的 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`：记录 tag 名称到布尔可见性覆盖的映射，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话 worker 空闲后在可清理前的 TTL，单位分钟。 -- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 +- `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 运行时环境时要执行的可选安装命令。 --- @@ -3678,16 +3679,16 @@ Secret ref 是增量功能：纯文本值仍然可用。 ``` - `cli.banner.taglineMode` 控制 banner 标语样式： - - `"random"`（默认）：轮换的有趣/季节性标语。 + - `"random"`（默认）：轮换的有趣 / 季节性标语。 - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 -- 若要隐藏整个 banner（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `"off"`：不显示标语文本（仍显示 banner 标题 / 版本）。 +- 若要隐藏整个 banner（不仅仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- ## 向导 -由 CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数据： +由 CLI 引导设置流程（`onboard`、`configure`、`doctor`）写入的元数据： ```json5 { @@ -3703,15 +3704,15 @@ Secret ref 是增量功能：纯文本值仍然可用。 --- -## Identity +## 身份 -参见 [智能体默认值](#agent-defaults) 下 `agents.list` 的 identity 字段。 +参见 [智能体默认值](#agent-defaults) 下 `agents.list` 的身份字段。 --- -## Bridge protocol（旧版节点，历史参考，已移除） +## Bridge protocol（旧版节点，历史参考）（旧版，已移除） -当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可清除未知键）。 +当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可清除未知键）。 @@ -3740,8 +3741,8 @@ Secret ref 是增量功能：纯文本值仍然可用。 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // 已弃用：供已存储 notify:true 作业使用的回退地址 - webhookToken: "replace-with-dedicated-token", // 可选：出站 webhook 认证用 bearer token + webhook: "https://example.invalid/legacy", // 已弃用：用于已存储 notify:true 作业的回退 + webhookToken: "replace-with-dedicated-token", // 可选：用于出站 webhook 认证的 bearer token sessionRetention: "24h", // 时长字符串或 false runLog: { maxBytes: "2mb", // 默认 2_000_000 字节 @@ -3751,11 +3752,11 @@ Secret ref 是增量功能：纯文本值仍然可用。 } ``` -- `sessionRetention`：已完成的隔离 cron 运行会话在从 `sessions.json` 清理前保留多久。也控制已归档、已删除 cron transcript 的清理。默认：`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；若省略，则不会发送认证头。 +- `webhook`：已弃用的旧版回退 webhook URL（http / https），仅用于仍保留 `notify: true` 的已存储作业。 ### `cron.retry` @@ -3771,11 +3772,11 @@ Secret ref 是增量功能：纯文本值仍然可用。 } ``` -- `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` @@ -3793,11 +3794,11 @@ Secret ref 是增量功能：纯文本值仍然可用。 } ``` -- `enabled`：启用 cron 作业失败告警（默认：`false`）。 -- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。 -- `cooldownMs`：同一作业两次重复告警之间的最短间隔，单位毫秒（非负整数）。 -- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 会 POST 到已配置的 webhook。 -- `accountId`：用于限定告警投递范围的可选账号或渠道 id。 +- `enabled`：为 cron 作业启用失败告警（默认：`false`）。 +- `after`：触发告警前允许的连续失败次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复告警之间的最小毫秒间隔（非负整数）。 +- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置 webhook 发起 POST。 +- `accountId`：可选的账号或渠道 id，用于限定告警投递范围。 ### `cron.failureDestination` @@ -3814,16 +3815,16 @@ Secret ref 是增量功能：纯文本值仍然可用。 } ``` -- 所有作业共用的 cron 失败通知默认目标。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认使用 `"announce"`。 +- 所有作业共享的 cron 失败通知默认目标。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认是 `"announce"`。 - `channel`：announce 投递的渠道覆盖。`"last"` 会复用上次已知的投递渠道。 -- `to`：显式 announce 目标或 webhook URL。webhook 模式下必填。 +- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。 - `accountId`：可选的投递账号覆盖。 - 按作业的 `delivery.failureDestination` 会覆盖该全局默认值。 -- 当全局和按作业失败目标都未设置时，那些本就通过 `announce` 投递的作业，在失败时会回退到其主 announce 目标。 +- 当全局和按作业失败目标都未设置时，已经通过 `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 执行会作为 [后台任务](/zh-CN/automation/tasks) 进行跟踪。 --- @@ -3831,27 +3832,27 @@ Secret ref 是增量功能：纯文本值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| Variable | 说明 | -| ------------------ | ---- | -| `{{Body}}` | 完整传入消息正文 | -| `{{RawBody}}` | 原始正文（无历史/发送者包装） | -| `{{BodyStripped}}` | 去除群组提及后的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 id | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 新建会话时为 `"true"` | -| `{{MediaUrl}}` | 传入媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频 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 等） | --- @@ -3873,12 +3874,12 @@ Secret ref 是增量功能：纯文本值仍然可用。 **合并行为：** -- 单文件：替换所在容器对象。 +- 单文件：替换所在的容器对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在 includes 之后合并（会覆盖被包含的值）。 -- 嵌套 include：最多 10 层深。 -- 路径：相对于包含它的文件解析，但必须始终位于顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许。 -- 错误：对于缺失文件、解析错误和循环 include，会给出清晰提示。 +- 同级键：在 include 之后合并（覆盖包含进来的值）。 +- 嵌套 include：最多支持 10 层。 +- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径 / `../` 形式最终仍解析到该边界内时才允许。 +- 错误：对缺失文件、解析错误和循环包含提供清晰消息。 --- diff --git a/docs/zh-CN/help/testing.md b/docs/zh-CN/help/testing.md index a80620b9b..cdac79fa0 100644 --- a/docs/zh-CN/help/testing.md +++ b/docs/zh-CN/help/testing.md @@ -1,116 +1,113 @@ --- read_when: - 在本地或 CI 中运行测试 - - 为模型/提供商缺陷添加回归测试 + - 为模型 / 提供商 bug 添加回归测试 - 调试 Gateway 网关 + 智能体行为 -summary: 测试工具包：unit/e2e/live 测试套件、Docker 运行器，以及每项测试覆盖的内容 +summary: 测试工具包：单元 / e2e / live 测试套件、Docker 运行器，以及每项测试覆盖的内容 title: 测试 x-i18n: - generated_at: "2026-04-21T07:31:03Z" + generated_at: "2026-04-21T20:53:28Z" model: gpt-5.4 provider: openai - source_hash: 3290113f28dab37f4b6ceb0bda6ced70c7d2b24ad3fccac6488b6aab1ad65e52 + source_hash: 6f890d6aa69925e09c5847b7fa082f3076b3bc79aae3e72445c750633a2451fa source_path: help/testing.md workflow: 15 --- # 测试 -OpenClaw 有三个 Vitest 测试套件（unit/integration、e2e、live）以及一小组 Docker 运行器。 +OpenClaw 有三个 Vitest 测试套件（单元 / 集成、e2e、live）以及一小组 Docker 运行器。 本文档是一份“我们如何测试”的指南： -- 每个测试套件覆盖什么内容（以及它刻意 _不_ 覆盖什么） -- 常见工作流（本地、推送前、调试）应运行哪些命令 -- live 测试如何发现凭证并选择模型/提供商 -- 如何为真实世界中的模型/提供商问题添加回归测试 +- 每个测试套件覆盖什么内容（以及它有意 _不_ 覆盖什么） +- 常见工作流应运行哪些命令（本地、推送前、调试） +- live 测试如何发现凭证并选择模型 / 提供商 +- 如何为真实世界中的模型 / 提供商问题添加回归测试 ## 快速开始 大多数时候： -- 完整门禁（推送前预期执行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- 在配置较强的机器上更快地运行本地全套测试：`pnpm test:max` -- 直接进入 Vitest 监听循环：`pnpm test:watch` -- 直接指定文件现在也会路由到 extension/channel 路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- 当你在迭代处理单个失败用例时，优先先跑有针对性的测试。 +- 完整门禁（预计在推送前运行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- 在配置充足的机器上更快地运行本地完整测试套件：`pnpm test:max` +- 直接使用 Vitest watch 循环：`pnpm test:watch` +- 直接指定文件现在也会路由到 extension / channel 路径：`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` -当你修改了测试，或想获得更多信心时： +当你修改了测试或想要更多信心时： - 覆盖率门禁：`pnpm test:coverage` - E2E 测试套件：`pnpm test:e2e` -当你在调试真实的提供商/模型时（需要真实凭证）： +当调试真实提供商 / 模型时（需要真实凭证）： -- Live 测试套件（模型 + Gateway 网关工具/图像探测）：`pnpm test:live` -- 安静地只跑一个 live 文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Moonshot/Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，运行 - `openclaw models list --provider moonshot --json`，然后针对 `moonshot/kimi-k2.6` 运行隔离的 +- Live 测试套件（模型 + Gateway 网关工具 / 图像探测）：`pnpm test:live` +- 安静地只运行一个 live 文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Moonshot / Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，运行 + `openclaw models list --provider moonshot --json`，然后针对 `moonshot/kimi-k2.6` 运行独立的 `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - 。验证 JSON 报告的是 Moonshot/K2.6，并且 assistant transcript 存储了标准化的 `usage.cost`。 + 。验证 JSON 报告的是 Moonshot / K2.6，并且助手转录存储了规范化的 `usage.cost`。 提示：当你只需要一个失败用例时，优先使用下面描述的 allowlist 环境变量来缩小 live 测试范围。 ## QA 专用运行器 -当你需要更贴近真实情况的 qa-lab 时，这些命令与主测试套件并列存在： +当你需要接近 `qa-lab` 真实环境的 QA 时，这些命令与主测试套件并列存在： - `pnpm openclaw qa suite` - - 直接在宿主机上运行基于仓库的 QA 场景。 - - 默认并行运行多个选定场景，并使用隔离的 Gateway 网关 worker。 - - `qa-channel` 默认并发数为 4（受所选场景数量限制）。使用 `--concurrency ` 调整 worker 数量，或使用 `--concurrency 1` 采用旧的串行通道。 - - 任一场景失败时以非零状态退出。若你想保留产物而不让退出码失败，请使用 `--allow-failures`。 - - 支持 `live-frontier`、`mock-openai` 和 `aimock` 提供商模式。 - `aimock` 会启动一个本地基于 AIMock 的提供商服务器，用于实验性的夹具与协议 mock 覆盖，但不会替代感知场景的 `mock-openai` 通道。 + - 直接在主机上运行基于仓库的 QA 场景。 + - 默认情况下会并行运行多个所选场景，并使用隔离的 Gateway 网关工作进程。`qa-channel` 默认并发数为 4（受所选场景数量限制）。使用 `--concurrency ` 调整工作进程数量，或使用 `--concurrency 1` 启用较旧的串行通道。 + - 当任一场景失败时，以非零状态退出。如果你想保留产物但不希望以失败退出码结束，请使用 `--allow-failures`。 + - 支持提供商模式 `live-frontier`、`mock-openai` 和 `aimock`。 + `aimock` 会启动一个本地 AIMock 支持的提供商服务器，用于实验性夹具和协议 mock 覆盖，但不会替代具备场景感知能力的 `mock-openai` 通道。 - `pnpm openclaw qa suite --runner multipass` - - 在一次性的 Multipass Linux VM 内运行同一套 QA 测试。 - - 保持与宿主机上 `qa suite` 相同的场景选择行为。 - - 复用与 `qa suite` 相同的提供商/模型选择标志。 - - Live 运行会转发对来宾系统实际可行的受支持 QA 鉴权输入： + - 在一次性 Multipass Linux VM 中运行同一个 QA 测试套件。 + - 与主机上的 `qa suite` 保持相同的场景选择行为。 + - 复用与 `qa suite` 相同的提供商 / 模型选择标志。 + - Live 运行会转发对来宾系统实用的受支持 QA 认证输入： 基于环境变量的提供商密钥、QA live 提供商配置路径，以及存在时的 `CODEX_HOME`。 - - 输出目录必须保持在仓库根目录下，这样来宾系统才能通过挂载的工作区回写。 - - 将常规 QA 报告 + 摘要以及 Multipass 日志写入 - `.artifacts/qa-e2e/...`。 + - 输出目录必须保持在仓库根目录下，以便来宾系统可以通过挂载的工作区回写。 + - 会在 `.artifacts/qa-e2e/...` 下写入常规 QA 报告 + 摘要以及 Multipass 日志。 - `pnpm qa:lab:up` - - 启动基于 Docker 的 QA 站点，用于偏操作员风格的 QA 工作。 + - 启动基于 Docker 的 QA 站点，供操作员风格的 QA 工作使用。 - `pnpm test:docker:bundled-channel-deps` - - 在 Docker 中打包并安装当前 OpenClaw 构建，启动已配置 OpenAI 的 Gateway 网关，然后通过编辑配置启用 Telegram 和 Discord。 - - 验证第一次重启 Gateway 网关时会按需安装每个内置渠道插件的运行时依赖，而第二次重启不会重新安装已激活的依赖。 + - 在 Docker 中打包并安装当前 OpenClaw 构建版本，启动已配置 OpenAI 的 Gateway 网关，然后通过配置编辑启用 Telegram 和 Discord。 + - 验证第一次 Gateway 网关重启时，会按需安装每个内置渠道插件的运行时依赖；第二次重启时，不会重新安装已经激活的依赖。 - `pnpm openclaw qa aimock` - 仅启动本地 AIMock 提供商服务器，用于直接协议冒烟测试。 - `pnpm openclaw qa matrix` - - 针对一次性的、基于 Docker 的 Tuwunel homeserver 运行 Matrix live QA 通道。 - - 该 QA 宿主当前仅供仓库/开发使用。已打包的 OpenClaw 安装不包含 - `qa-lab`，因此不会暴露 `openclaw qa`。 - - 仓库检出会直接加载内置运行器；不需要单独安装插件。 - - 预配三个临时 Matrix 用户（`driver`、`sut`、`observer`）以及一个私有房间，然后启动一个 QA gateway 子进程，并使用真实 Matrix 插件作为 SUT 传输层。 - - 默认使用固定稳定版 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。当你需要测试其他镜像时，可用 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。 - - Matrix 不暴露共享凭证源标志，因为该通道会在本地预配一次性用户。 - - 将 Matrix QA 报告、摘要、observed-events 产物以及合并后的 stdout/stderr 输出日志写入 `.artifacts/qa-e2e/...`。 + - 对基于 Docker 的一次性 Tuwunel homeserver 运行 Matrix live QA 通道。 + - 这个 QA 主机目前仅供仓库 / 开发使用。打包后的 OpenClaw 安装不包含 `qa-lab`，因此不会暴露 `openclaw qa`。 + - 仓库检出会直接加载内置运行器；不需要单独的插件安装步骤。 + - 会创建三个临时 Matrix 用户（`driver`、`sut`、`observer`）以及一个私有房间，然后使用真实 Matrix 插件作为 SUT 传输层启动一个 QA gateway 子进程。 + - 默认使用固定的稳定版 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。当你需要测试其他镜像时，可使用 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。 + - Matrix 不暴露共享凭证源标志，因为该通道会在本地创建一次性用户。 + - 会在 `.artifacts/qa-e2e/...` 下写入 Matrix QA 报告、摘要、observed-events 产物，以及合并后的 stdout / stderr 输出日志。 - `pnpm openclaw qa telegram` - - 使用来自环境变量的 driver 和 SUT bot token，针对真实私有群组运行 Telegram live QA 通道。 - - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是 Telegram chat 的数字 id。 - - 支持 `--credential-source convex` 以使用共享池化凭证。默认使用 env 模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。 - - 任一场景失败时以非零状态退出。若你想保留产物而不让退出码失败，请使用 `--allow-failures`。 - - 需要两个处于同一私有群组中的不同 bot，并且 SUT bot 需要公开一个 Telegram 用户名。 - - 为了实现稳定的 bot 对 bot 观察，请在 `@BotFather` 中为两个 bot 都启用 Bot-to-Bot Communication Mode，并确保 driver bot 可以观察群组中的 bot 流量。 - - 将 Telegram QA 报告、摘要和 observed-messages 产物写入 `.artifacts/qa-e2e/...`。 + - 使用环境变量中的 driver 和 SUT bot token，在真实私有群组中运行 Telegram live QA 通道。 + - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是数字形式的 Telegram chat id。 + - 支持 `--credential-source convex` 用于共享池化凭证。默认使用 env 模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。 + - 当任一场景失败时，以非零状态退出。如果你想保留产物但不希望以失败退出码结束，请使用 `--allow-failures`。 + - 需要同一个私有群组中的两个不同 bot，并且 SUT bot 需要暴露 Telegram 用户名。 + - 为了实现稳定的 bot 到 bot 观察，请在 `@BotFather` 中为两个 bot 都启用 Bot-to-Bot Communication Mode，并确保 driver bot 可以观察群组中的 bot 流量。 + - 会在 `.artifacts/qa-e2e/...` 下写入 Telegram QA 报告、摘要和 observed-messages 产物。 -Live 传输通道共享一份标准契约，以防新传输层发生漂移： +Live 传输通道共享一个标准契约，因此新传输不会发生漂移： -`qa-channel` 仍然是广义的合成 QA 测试套件，不属于 live +`qa-channel` 仍然是广义的合成 QA 测试套件，并不属于 live 传输覆盖矩阵的一部分。 -| 通道 | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | -| ---- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| 通道 | Canary | Mention gating | Allowlist block | 顶层回复 | 重启恢复 | 线程后续跟进 | 线程隔离 | 反应观察 | 帮助命令 | +| ---- | ------ | -------------- | --------------- | -------- | -------- | ------------ | -------- | -------- | -------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### 通过 Convex 共享 Telegram 凭证（v1） -当为 `openclaw qa telegram` 启用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）时，QA lab 会从基于 Convex 的池中获取独占租约，在通道运行期间对该租约发送心跳，并在关闭时释放该租约。 +当为 `openclaw qa telegram` 启用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）时，QA lab 会从一个基于 Convex 的池中获取独占租约，在通道运行期间为该租约发送心跳，并在关闭时释放租约。 参考 Convex 项目脚手架： @@ -119,12 +116,12 @@ Live 传输通道共享一份标准契约，以防新传输层发生漂移： 必需环境变量： - `OPENCLAW_QA_CONVEX_SITE_URL`（例如 `https://your-deployment.convex.site`） -- 为所选角色提供一个 secret： +- 为所选角色设置一个 secret： - `maintainer` 使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` - `ci` 使用 `OPENCLAW_QA_CONVEX_SECRET_CI` - 凭证角色选择： - CLI：`--credential-role maintainer|ci` - - 默认环境变量：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认为 `ci`，否则默认为 `maintainer`） + - 环境变量默认值：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认是 `ci`，否则是 `maintainer`） 可选环境变量： @@ -133,12 +130,12 @@ Live 传输通道共享一份标准契约，以防新传输层发生漂移： - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`（默认 `90000`） - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（默认 `15000`） - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（默认 `/qa-credentials/v1`） -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选的 trace id） +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选追踪 id） - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` 允许仅用于本地开发的 loopback `http://` Convex URL。 `OPENCLAW_QA_CONVEX_SITE_URL` 在正常运行中应使用 `https://`。 -维护者管理命令（池添加/移除/列出）必须专门使用 +维护者管理命令（池添加 / 删除 / 列表）明确要求使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。 面向维护者的 CLI 辅助命令： @@ -149,51 +146,51 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -在脚本和 CI 工具中，使用 `--json` 获取机器可读输出。 +在脚本和 CI 工具中使用 `--json` 获取机器可读输出。 默认端点契约（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）： - `POST /acquire` - 请求：`{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - 成功：`{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - 耗尽/可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - 资源耗尽 / 可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - 请求：`{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - - 成功：`{ status: "ok" }`（或空的 `2xx`） + - 成功：`{ status: "ok" }`（或空 `2xx`） - `POST /release` - 请求：`{ kind, ownerId, actorRole, credentialId, leaseToken }` - - 成功：`{ status: "ok" }`（或空的 `2xx`） -- `POST /admin/add`（仅限 maintainer secret） + - 成功：`{ status: "ok" }`（或空 `2xx`） +- `POST /admin/add`（仅维护者 secret） - 请求：`{ kind, actorId, payload, note?, status? }` - 成功：`{ status: "ok", credential }` -- `POST /admin/remove`（仅限 maintainer secret） +- `POST /admin/remove`（仅维护者 secret） - 请求：`{ credentialId, actorId }` - 成功：`{ status: "ok", changed, credential }` - 活跃租约保护：`{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list`（仅限 maintainer secret） +- `POST /admin/list`（仅维护者 secret） - 请求：`{ kind?, status?, includePayload?, limit? }` - 成功：`{ status: "ok", credentials, count }` Telegram 类型的 payload 结构： - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` 必须是 Telegram chat 的数字 id 字符串。 -- 对于 `kind: "telegram"`，`admin/add` 会验证此结构并拒绝格式错误的 payload。 +- `groupId` 必须是数字形式的 Telegram chat id 字符串。 +- 当 `kind: "telegram"` 时，`admin/add` 会验证此结构，并拒绝格式错误的 payload。 ### 向 QA 添加一个渠道 -向 markdown QA 系统添加一个渠道，严格来说只需要两样东西： +向 Markdown QA 系统添加一个渠道只需要严格满足两件事： 1. 该渠道的传输适配器。 -2. 一个用于验证该渠道契约的场景包。 +2. 一个用于验证渠道契约的场景包。 -当共享的 `qa-lab` 宿主可以承载整个流程时，不要新增新的顶层 QA 命令根。 +当共享的 `qa-lab` 主机可以负责整个流程时，不要添加新的顶层 QA 命令根。 -`qa-lab` 负责共享宿主机制： +`qa-lab` 负责共享主机机制： - `openclaw qa` 命令根 -- 测试套件启动与关闭 -- worker 并发 +- 测试套件启动和拆除 +- 工作进程并发 - 产物写入 - 报告生成 - 场景执行 @@ -201,35 +198,35 @@ Telegram 类型的 payload 结构： 运行器插件负责传输契约： -- 如何将 `openclaw qa ` 挂载到共享的 `qa` 根下 +- `openclaw qa ` 如何挂载到共享 `qa` 根命令下 - 如何为该传输配置 gateway - 如何检查就绪状态 - 如何注入入站事件 - 如何观察出站消息 -- 如何暴露 transcript 和标准化后的传输状态 -- 如何执行由传输支持的操作 +- 如何暴露转录和规范化传输状态 +- 如何执行基于传输的操作 - 如何处理传输特定的重置或清理 -新渠道的最低接入门槛是： +新渠道的最低采纳标准是： -1. 保持由 `qa-lab` 拥有共享的 `qa` 根。 -2. 在共享的 `qa-lab` 宿主接缝上实现传输运行器。 -3. 将传输特定机制保留在运行器插件或渠道 harness 内。 +1. 保持 `qa-lab` 作为共享 `qa` 根的拥有者。 +2. 在共享的 `qa-lab` 主机接缝上实现传输运行器。 +3. 将传输特定机制保留在运行器插件或渠道 harness 内部。 4. 将运行器挂载为 `openclaw qa `，而不是注册一个竞争性的根命令。 运行器插件应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。 - 保持 `runtime-api.ts` 轻量；惰性 CLI 和运行器执行应保留在独立入口点之后。 -5. 在带主题的 `qa/scenarios/` 目录下编写或改造 markdown 场景。 -6. 为新场景使用通用场景辅助函数。 -7. 除非仓库正在进行有意的迁移，否则保持现有兼容别名继续可用。 + 保持 `runtime-api.ts` 足够轻量；惰性 CLI 和运行器执行应放在独立入口点之后。 +5. 在按主题组织的 `qa/scenarios/` 目录下编写或适配 Markdown 场景。 +6. 对新场景使用通用场景辅助工具。 +7. 除非仓库正在进行有意迁移，否则保持现有兼容别名继续工作。 决策规则是严格的： -- 如果某种行为可以在 `qa-lab` 中统一表达一次，就把它放进 `qa-lab`。 -- 如果某种行为依赖某一个渠道传输层，就把它保留在该运行器插件或插件 harness 中。 -- 如果某个场景需要新增一种能力，并且多个渠道都能使用，就添加一个通用辅助函数，而不是在 `suite.ts` 中加入渠道特定分支。 -- 如果某种行为只对某一个传输层有意义，就让该场景保持传输层特定，并在场景契约中明确说明。 +- 如果某个行为可以在 `qa-lab` 中统一表达一次，就把它放到 `qa-lab` 中。 +- 如果某个行为依赖于单一渠道传输，就把它保留在对应的运行器插件或插件 harness 中。 +- 如果某个场景需要一个可供多个渠道使用的新能力，请添加通用辅助工具，而不是在 `suite.ts` 中添加渠道特定分支。 +- 如果某个行为只对一种传输有意义，就让该场景保持传输特定，并在场景契约中明确说明。 -新场景推荐使用的通用辅助函数名称如下： +新场景推荐使用的通用辅助工具名称包括： - `waitForTransportReady` - `waitForChannelReady` @@ -252,104 +249,102 @@ Telegram 类型的 payload 结构： - `formatConversationTranscript` - `resetBus` -新的渠道开发应使用这些通用辅助函数名称。 -兼容别名的存在是为了避免一次性强制迁移，而不是作为 -新场景编写的范式。 +新的渠道工作应使用通用辅助工具名称。 +兼容别名的存在是为了避免一次性强制迁移，而不是作为新场景编写的范式。 ## 测试套件（各自运行位置） -可以把这些测试套件理解为“真实度逐步提高”（以及逐步增加的不稳定性/成本）： +可以把这些测试套件理解为“真实度逐步提升”（同时不稳定性 / 成本也逐步上升）： -### Unit / integration（默认） +### 单元 / 集成（默认） - 命令：`pnpm test` -- 配置：基于现有作用域化 Vitest 项目，按顺序运行十个分片配置（`vitest.full-*.config.ts`） -- 文件：`src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 下的 core/unit 清单，以及由 `vitest.unit.config.ts` 覆盖的白名单 `ui` node 测试 +- 配置：对现有作用域 Vitest project 运行十个顺序分片（`vitest.full-*.config.ts`） +- 文件：`src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 下的核心 / 单元测试清单，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` Node 测试 - 范围： - 纯单元测试 - - 进程内集成测试（gateway 凭证、路由、工具、解析、配置） - - 已知缺陷的确定性回归测试 + - 进程内集成测试（gateway 认证、路由、工具、解析、配置） + - 已知 bug 的确定性回归测试 - 预期： - 在 CI 中运行 - 不需要真实密钥 - 应该快速且稳定 -- 项目说明： - - 无目标的 `pnpm test` 现在会运行十一个更小的分片配置（`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`），而不是一个巨大的原生 root-project 进程。这能降低高负载机器上的峰值 RSS，并避免 auto-reply/extension 工作拖累无关测试套件。 - - `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` 项目图，因为多分片 watch 循环并不现实。 - - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 现在会优先将显式文件/目录目标路由到作用域化通道，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 不必承担完整 root project 启动成本。 - - 当改动的 diff 仅涉及可路由的 source/test 文件时，`pnpm test:changed` 会将改动的 git 路径扩展为相同的作用域化通道；配置/setup 改动仍会回退到更广泛的 root-project 重跑。 - - `pnpm check:changed` 是常规窄范围开发下的智能本地门禁。它会将 diff 归类为 core、core tests、extensions、extension tests、apps、docs 和 tooling，然后运行对应的 typecheck/lint/test 通道。公共 Plugin SDK 和 plugin-contract 的改动会包含 extension 验证，因为 extension 依赖这些 core 契约。 - - 来自 agents、commands、plugins、auto-reply 辅助函数、`plugin-sdk` 以及类似纯工具区域的轻导入 unit 测试，会通过 `unit-fast` 通道运行，该通道跳过 `test/setup-openclaw-runtime.ts`；有状态/运行时较重的文件仍保留在现有通道上。 - - 选定的 `plugin-sdk` 和 `commands` 辅助源码文件也会在 changed 模式下，将运行映射到这些轻量通道中的显式同级测试，因此辅助函数改动无需为该目录重跑完整的重型套件。 - - `auto-reply` 现在有三个专用桶：顶层 core 辅助函数、顶层 `reply.*` 集成测试，以及 `src/auto-reply/reply/**` 子树。这样可以让最重的 reply harness 工作不影响轻量的状态/chunk/token 测试。 -- 嵌入式运行器说明： - - 当你修改消息工具发现输入或压缩运行时上下文时， - 要同时保持两个层级的覆盖。 - - 为纯路由/标准化边界添加聚焦的辅助函数回归测试。 - - 还要保持嵌入式运行器集成测试套件健康： +- Projects 说明： + - 无目标的 `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`），而不是一个庞大的原生根 project 进程。这样可以降低高负载机器上的峰值 RSS，并避免 auto-reply / extension 工作拖累无关测试套件。 + - `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` project 图，因为多分片 watch 循环并不实际。 + - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 现在会先通过有作用域的通道来路由显式文件 / 目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 不必承担完整根 project 启动成本。 + - 当变更集只涉及可路由的源文件 / 测试文件时，`pnpm test:changed` 会将变更的 git 路径扩展到相同的有作用域通道；配置 / setup 编辑仍然会回退到较宽泛的根 project 重跑。 + - `pnpm check:changed` 是针对小范围工作的常规智能本地门禁。它会将 diff 分类为 core、core tests、extensions、extension tests、apps、docs 和 tooling，然后运行匹配的 typecheck / lint / test 通道。公共 Plugin SDK 和插件契约变更会包含 extension 验证，因为 extensions 依赖这些核心契约。 + - 来自 agents、commands、plugins、auto-reply helpers、`plugin-sdk` 以及类似纯工具区域的轻导入单元测试会通过 `unit-fast` 通道路由，该通道会跳过 `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.test.ts` 和 `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。 - - 这些测试套件会验证作用域化 id 和压缩行为仍然会流经真实的 `run.ts` / `compact.ts` 路径；仅有辅助函数测试 - 不能充分替代这些集成路径。 + - 这些测试套件验证带作用域的 id 和压缩行为仍然会流经真实的 `run.ts` / `compact.ts` 路径；仅有辅助工具测试并不能充分替代这些集成路径。 - Pool 说明： - 基础 Vitest 配置现在默认使用 `threads`。 - - 共享 Vitest 配置也固定了 `isolate: false`，并在 root projects、e2e 和 live 配置中使用非隔离运行器。 - - 根 UI 通道保留其 `jsdom` setup 和 optimizer，但现在也运行在共享的非隔离运行器上。 + - 共享 Vitest 配置还固定了 `isolate: false`，并在根 projects、e2e 和 live 配置中使用非隔离运行器。 + - 根 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 changed:lanes` 会显示某个 diff 会触发哪些架构通道。 - - pre-commit hook 会在暂存格式化/lint 之后运行 `pnpm check:changed --staged`，因此纯 core 提交不会承担 extension 测试成本，除非它们触及面向 extension 的公共契约。 - - `pnpm test:changed` 会在改动路径能清晰映射到较小测试套件时，通过作用域化通道运行。 + - 共享的 `scripts/run-vitest.mjs` 启动器现在默认也会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。如果你需要与默认 V8 行为对比，请设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1`。 +- 快速本地迭代说明： + - `pnpm changed:lanes` 会显示某个 diff 触发了哪些架构通道。 + - pre-commit hook 会在已暂存格式化 / lint 之后运行 `pnpm check:changed --staged`，因此仅 core 的提交不必承担 extension 测试成本，除非它们触及面向 extension 的公共契约。 + - `pnpm test:changed` 会在变更路径可以明确映射到较小测试套件时，通过有作用域通道进行路由。 - `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的路由行为，只是使用更高的 worker 上限。 - - 本地 worker 自动缩放现在故意更保守，并且当宿主的 load average 已经较高时也会退让，因此多个并发 Vitest 运行默认造成的影响会更小。 - - 基础 Vitest 配置将项目/配置文件标记为 `forceRerunTriggers`，这样当测试接线发生变化时，changed 模式下的重跑仍然正确。 - - 配置会在受支持的宿主上保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你想为直接性能分析指定一个显式缓存位置，请设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。 + - 本地 worker 自动扩缩现在刻意更保守，并且当主机负载平均值已经很高时也会退让，因此默认情况下多个并发 Vitest 运行带来的影响会更小。 + - 基础 Vitest 配置会将 projects / 配置文件标记为 `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 ` 会针对该已提交 diff，将路由后的 `test:changed` 与原生 root-project 路径进行比较，并输出 wall time 以及 macOS 最大 RSS。 -- `pnpm test:perf:changed:bench -- --worktree` 会通过 `scripts/test-projects.mjs` 和根 Vitest 配置，将改动文件列表路由后，对当前脏工作树进行基准测试。 - - `pnpm test:perf:profile:main` 会为 Vitest/Vite 启动和 transform 开销写出主线程 CPU profile。 - - `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为 unit 测试套件写出运行器 CPU + heap profile。 + - `pnpm test:perf:imports:changed` 会将相同的性能分析视图限定到自 `origin/main` 以来变更的文件。 +- `pnpm test:perf:changed:bench -- --ref ` 会将路由后的 `test:changed` 与该提交 diff 的原生根 project 路径进行比较，并打印 wall time 以及 macOS 最大 RSS。 +- `pnpm test:perf:changed:bench -- --worktree` 会通过 `scripts/test-projects.mjs` 和根 Vitest 配置，将变更文件列表路由到当前脏工作树并进行基准测试。 + - `pnpm test:perf:profile:main` 会为 Vitest / Vite 启动和 transform 开销写入主线程 CPU profile。 + - `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为单元测试套件写入运行器 CPU + heap profile。 -### E2E（gateway 冒烟测试） +### E2E（Gateway 网关冒烟） - 命令：`pnpm test:e2e` - 配置：`vitest.e2e.config.ts` - 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts` - 运行时默认值： - - 使用 Vitest `threads` 和 `isolate: false`，与仓库其余部分保持一致。 - - 使用自适应 worker（CI：最多 2 个，本地：默认 1 个）。 - - 默认以静默模式运行，以减少控制台 I/O 开销。 -- 常用覆盖项： - - `OPENCLAW_E2E_WORKERS=` 强制指定 worker 数量（上限 16）。 - - `OPENCLAW_E2E_VERBOSE=1` 重新启用详细控制台输出。 + - 使用带 `isolate: false` 的 Vitest `threads`，与仓库其他部分保持一致。 + - 使用自适应 worker（CI：最多 2，本地：默认 1）。 + - 默认以 silent 模式运行，以减少控制台 I/O 开销。 +- 常用覆盖设置： + - `OPENCLAW_E2E_WORKERS=` 用于强制指定 worker 数量（上限为 16）。 + - `OPENCLAW_E2E_VERBOSE=1` 用于重新启用详细控制台输出。 - 范围： - 多实例 gateway 端到端行为 - - WebSocket/HTTP 接口、节点配对以及更重的网络行为 + - WebSocket / HTTP 接口、节点配对以及更重的网络行为 - 预期： - 在 CI 中运行（当流水线启用时） - 不需要真实密钥 - - 比 unit 测试涉及更多活动部件（可能更慢） + - 比单元测试有更多活动部件（可能更慢） -### E2E：OpenShell 后端冒烟测试 +### E2E：OpenShell 后端冒烟 - 命令：`pnpm test:e2e:openshell` - 文件：`test/openshell-sandbox.e2e.test.ts` - 范围： - - 通过 Docker 在宿主机上启动一个隔离的 OpenShell gateway - - 从临时本地 Dockerfile 创建一个沙箱 - - 通过真实的 `sandbox ssh-config` + SSH 执行来验证 OpenClaw 的 OpenShell 后端 + - 通过 Docker 在主机上启动隔离的 OpenShell gateway + - 根据临时本地 Dockerfile 创建一个沙箱 + - 通过真实的 `sandbox ssh-config` + SSH exec 运行 OpenClaw 的 OpenShell 后端 - 通过沙箱 fs bridge 验证远端规范文件系统行为 - 预期： - - 仅按需启用；不属于默认的 `pnpm test:e2e` 运行 + - 仅按需启用；不是默认 `pnpm test:e2e` 运行的一部分 - 需要本地 `openshell` CLI 和可用的 Docker daemon - 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 gateway 和沙箱 -- 常用覆盖项： - - `OPENCLAW_E2E_OPENSHELL=1`：在手动运行更广义的 e2e 测试套件时启用该测试 - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`：指向非默认 CLI 二进制文件或包装脚本 +- 常用覆盖设置： + - `OPENCLAW_E2E_OPENSHELL=1` 用于在手动运行更广泛 e2e 测试套件时启用该测试 + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 用于指向非默认 CLI 二进制文件或包装脚本 ### Live（真实提供商 + 真实模型） @@ -358,30 +353,30 @@ Telegram 类型的 payload 结构： - 文件：`src/**/*.live.test.ts` - 默认：由 `pnpm test:live` **启用**（设置 `OPENCLAW_LIVE_TEST=1`） - 范围： - - “这个提供商/模型 _今天_ 在真实凭证下是否真的可用？” - - 捕获提供商格式变化、工具调用怪癖、鉴权问题和速率限制行为 + - “这个提供商 / 模型 _今天_ 是否真的能在真实凭证下正常工作？” + - 捕获提供商格式变化、工具调用怪癖、认证问题和速率限制行为 - 预期： - - 按设计不具备 CI 稳定性（真实网络、真实提供商策略、配额、故障） - - 会花钱 / 消耗速率限制额度 + - 天生不适合 CI 稳定运行（真实网络、真实提供商策略、配额、故障） + - 会花钱 / 消耗速率限制 - 优先运行缩小范围的子集，而不是“全部” -- Live 运行会读取 `~/.profile`，以获取缺失的 API key。 -- 默认情况下，live 运行仍会隔离 `HOME`，并将 config/auth 材料复制到临时测试 home 中，这样 unit 夹具就不会修改你真实的 `~/.openclaw`。 -- 仅当你明确需要让 live 测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。 -- `pnpm test:live` 现在默认使用更安静的模式：保留 `[live] ...` 进度输出，但会抑制额外的 `~/.profile` 提示，并静音 gateway 启动日志/Bonjour 杂音。如果你想恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。 -- API key 轮换（提供商特定）：设置 `*_API_KEYS`，使用逗号/分号格式，或设置 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或通过 `OPENCLAW_LIVE_*_KEY` 进行每个 live 测试的单独覆盖；测试会在收到速率限制响应时重试。 -- 进度/心跳输出： - - Live 测试套件现在会将进度行输出到 stderr，因此即使 Vitest 控制台捕获处于安静模式，长时间的提供商调用也能明显显示仍在运行。 - - `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，这样提供商/gateway 进度行会在 live 运行期间立即流式输出。 - - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型的心跳。 - - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 gateway/探测心跳。 +- Live 运行会 source `~/.profile` 以获取缺失的 API key。 +- 默认情况下，live 运行仍然会隔离 `HOME`，并将 config / auth 材料复制到临时测试 home 中，以便单元测试夹具不会修改你真实的 `~/.openclaw`。 +- 只有在你明确需要 live 测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。 +- `pnpm test:live` 现在默认采用更安静的模式：它会保留 `[live] ...` 进度输出，但抑制额外的 `~/.profile` 提示，并静默 gateway 启动日志 / Bonjour 杂音。如果你想恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。 +- API key 轮换（提供商特定）：设置逗号 / 分号格式的 `*_API_KEYS` 或 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或通过 `OPENCLAW_LIVE_*_KEY` 进行每个 live 运行的覆盖；测试会在收到速率限制响应时重试。 +- 进度 / 心跳输出： + - Live 测试套件现在会将进度行输出到 stderr，因此即使 Vitest 控制台捕获较安静，较长的提供商调用仍然会明显显示为活跃状态。 + - `vitest.live.config.ts` 禁用了 Vitest 控制台拦截，因此提供商 / gateway 进度行会在 live 运行期间立即流式输出。 + - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型心跳。 + - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 gateway / probe 心跳。 ## 我应该运行哪个测试套件？ 使用这个决策表： -- 修改逻辑/测试：运行 `pnpm test`（如果你改动很多，再加上 `pnpm test:coverage`） -- 涉及 gateway 网络 / WS 协议 / 配对：增加运行 `pnpm test:e2e` -- 调试“我的 bot 挂了”/ 提供商特定故障 / 工具调用：运行缩小范围的 `pnpm test:live` +- 编辑逻辑 / 测试：运行 `pnpm test`（如果你改动很多，也运行 `pnpm test:coverage`） +- 触及 gateway 网络 / WS 协议 / 配对：额外运行 `pnpm test:e2e` +- 调试“我的 bot 挂了” / 提供商特定故障 / 工具调用：运行缩小范围的 `pnpm test:live` ## Live：Android 节点能力扫描 @@ -389,23 +384,23 @@ Telegram 类型的 payload 结构： - 脚本：`pnpm android:test:integration` - 目标：调用已连接 Android 节点当前声明的**每一个命令**，并断言命令契约行为。 - 范围： - - 依赖前置条件/手动设置（该测试套件不会安装/运行/配对应用）。 + - 预设条件 / 手动 setup（该测试套件不会安装 / 运行 / 配对应用）。 - 针对所选 Android 节点，逐命令验证 gateway `node.invoke`。 -- 必需的前置设置： - - Android 应用已连接并与 gateway 完成配对。 +- 必需的预先 setup： + - Android 应用已连接并与 gateway 配对。 - 应用保持在前台。 - - 对于你期望通过的能力，相关权限/捕获授权已授予。 + - 你期望通过的能力所需的权限 / 捕获同意已授予。 - 可选目标覆盖： - `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。 - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。 -- 完整 Android 设置细节：[Android 应用](/zh-CN/platforms/android) +- 完整 Android setup 详情：[Android App](/zh-CN/platforms/android) -## Live：模型冒烟测试（profile key） +## Live：模型冒烟（profile keys） -Live 测试分为两层，这样我们可以隔离失败来源： +Live 测试分为两层，这样我们可以隔离故障： -- “Direct model” 用于告诉我们，提供商/模型是否至少能在给定 key 下正常回复。 -- “Gateway smoke” 用于告诉我们，针对该模型，完整的 gateway + 智能体管线是否工作正常（会话、历史、工具、沙箱策略等）。 +- “直接模型”告诉我们，在给定 key 下，该提供商 / 模型是否至少能回复。 +- “Gateway 网关冒烟”告诉我们，针对该模型，完整的 gateway + 智能体 流水线是否正常工作（会话、历史、工具、沙箱策略等）。 ### 第 1 层：直接模型补全（无 gateway） @@ -413,86 +408,86 @@ Live 测试分为两层，这样我们可以隔离失败来源： - 目标： - 枚举发现到的模型 - 使用 `getApiKeyForModel` 选择你有凭证的模型 - - 为每个模型运行一个小型补全测试（并在需要时运行定向回归测试） + - 对每个模型运行一个小型补全（以及在需要时运行定向回归） - 启用方式： - `pnpm test:live`（或在直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`） -- 设置 `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=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 扫描，或设为正数以使用更小上限。 -- 如何选择提供商： - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔 allowlist） -- key 来自哪里： - - 默认：profile store 和环境变量回退 - - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅**使用 profile store -- 此层存在的原因： - - 将“提供商 API 已损坏 / key 无效”与“gateway 智能体管线已损坏”区分开 - - 容纳小型、隔离的回归测试（例如：OpenAI Responses/Codex Responses 推理回放 + 工具调用流程） + - 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（逗号分隔的 allowlist） + - modern / all 全量扫描默认有一个经过筛选的高信号上限；将 `OPENCLAW_LIVE_MAX_MODELS=0` 设为完整 modern 扫描，或设为正数以使用更小的上限。 +- 选择提供商的方法： + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔的 allowlist） +- key 的来源： + - 默认：profile store 和环境变量回退值 + - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅使用 profile store** +- 存在原因： + - 将“提供商 API 坏了 / key 无效”与“gateway 智能体 流水线坏了”分离 + - 容纳小型、隔离的回归测试（示例：OpenAI Responses / Codex Responses 推理回放 + 工具调用流程） -### 第 2 层：Gateway + dev 智能体冒烟测试（也就是 “@openclaw” 实际做的事） +### 第 2 层：Gateway 网关 + dev 智能体冒烟（也就是 “@openclaw” 实际做的事） - 测试：`src/gateway/gateway-models.profiles.live.test.ts` - 目标： - 启动一个进程内 gateway - - 创建/修补一个 `agent:dev:*` 会话（每次运行都可覆盖模型） - - 遍历带 key 的模型，并断言： - - 有“有意义”的回复（无工具） - - 一次真实工具调用能正常工作（read 探测） - - 可选的额外工具探测（exec+read 探测） - - OpenAI 回归路径（仅工具调用 → 后续跟进）仍保持可用 -- 探测细节（这样你能快速解释失败）： - - `read` 探测：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 该文件并回显 nonce。 - - `exec+read` 探测：测试会要求智能体通过 `exec` 将 nonce 写入临时文件，然后再 `read` 回来。 - - 图像探测：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat `。 + - 创建 / 修补一个 `agent:dev:*` 会话（每次运行都覆盖模型） + - 遍历带 key 的模型并断言： + - “有意义”的回复（无工具） + - 一次真实工具调用成功（read probe） + - 可选的额外工具探测（exec+read probe） + - OpenAI 回归路径（仅工具调用 → 后续跟进）持续可用 +- Probe 细节（这样你能快速解释失败原因）： + - `read` probe：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 该文件并回显 nonce。 + - `exec+read` probe：测试会要求智能体通过 `exec` 将 nonce 写入临时文件，然后再将其 `read` 出来。 + - image probe：测试会附加一个生成的 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） +- 选择模型的方法： + - 默认：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 全部跑一遍”）： - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔 allowlist） -- 在该 live 测试中，工具 + 图像探测始终开启： - - `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`） - - 嵌入式智能体向模型转发一条多模态用户消息 - - 断言：回复中包含 `cat` + 该代码（OCR 容错：允许轻微错误） + - 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） +- 工具 + 图像探测在这个 live 测试中始终开启： + - `read` probe + `exec+read` probe（工具压力测试） + - 当模型声明支持图像输入时，会运行 image probe + - 流程（高层）： + - 测试会生成一个带有 “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`） + - 内嵌智能体会向模型转发一条多模态用户消息 + - 断言：回复包含 `cat` + 该代码（OCR 容忍：允许轻微错误） -提示：若要查看你机器上可以测试什么（以及精确的 `provider/model` id），请运行： +提示：若要查看你这台机器上可以测试什么（以及精确的 `provider/model` id），请运行： ```bash openclaw models list openclaw models list --json ``` -## Live：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI） +## Live：CLI 后端冒烟（Claude、Codex、Gemini，或其他本地 CLI） - 测试：`src/gateway/gateway-cli-backend.live.test.ts` -- 目标：使用本地 CLI 后端验证 Gateway 网关 + 智能体管线，且不触碰你的默认配置。 -- 后端特定的冒烟测试默认值位于所属 extension 的 `cli-backend.ts` 定义中。 +- 目标：使用本地 CLI 后端验证 Gateway 网关 + 智能体 流水线，同时不触碰你的默认配置。 +- 后端特定的默认冒烟配置位于所属 extension 的 `cli-backend.ts` 定义中。 - 启用： - `pnpm test:live`（或在直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`） - `OPENCLAW_LIVE_CLI_BACKEND=1` - 默认值： - - 默认提供商/模型：`claude-cli/claude-sonnet-4-6` - - 命令/参数/图像行为来自所属 CLI 后端插件元数据。 + - 默认 provider / model：`claude-cli/claude-sonnet-4-6` + - command / args / image 行为来自所属 CLI 后端插件元数据。 - 覆盖项（可选）： - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径会注入到提示词中）。 - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 通过 CLI 参数传递图像文件路径，而不是注入到提示词中。 - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）控制在设置 `IMAGE_ARG` 时如何传递图像参数。 - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮消息并验证恢复流程。 - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` 关闭默认的 Claude Sonnet -> Opus 同会话连续性探测（当所选模型支持切换目标时，设为 `1` 可强制开启）。 + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 用于发送真实图像附件（路径会注入到 prompt 中）。 + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 用于将图像文件路径作为 CLI 参数传递，而不是注入到 prompt 中。 + - `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` 可强制启用）。 示例： @@ -520,27 +515,27 @@ pnpm test:docker:live-cli-backend:gemini 说明： - Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。 -- 它会在仓库 Docker 镜像内以非 root 的 `node` 用户身份运行 live CLI 后端冒烟测试。 -- 它会从所属 extension 解析 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，可通过 `~/.claude/.credentials.json` 中的 `claudeAiOauth.subscriptionType` 或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供。它会先证明 Docker 中的直接 `claude -p` 可用，然后在不保留 Anthropic API key 环境变量的情况下，运行两轮 Gateway CLI 后端交互。由于 Claude 当前会通过额外用量计费来处理第三方应用使用，而不是走普通订阅计划限额，因此该订阅通道默认关闭 Claude MCP/工具和图像探测。 -- 现在，live CLI 后端冒烟测试会对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮次、图像分类轮次，然后通过 gateway CLI 验证 MCP `cron` 工具调用。 -- Claude 的默认冒烟测试还会将会话从 Sonnet 修补到 Opus，并验证恢复后的会话仍记得之前的说明。 +- 它会在仓库 Docker 镜像内，以非 root 的 `node` 用户身份运行 live CLI 后端冒烟测试。 +- 它会从所属 extension 解析 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 key 环境变量的情况下运行两轮 Gateway 网关 CLI 后端回合。这个订阅通道默认禁用了 Claude MCP / 工具和图像探测，因为 Claude 当前会将第三方应用使用计入额外用量计费，而不是普通订阅方案额度。 +- 现在，live CLI 后端冒烟测试会对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本回合、图像分类回合，然后通过 gateway CLI 验证 MCP `cron` 工具调用。 +- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍然记得先前的备注。 -## Live：ACP 绑定冒烟测试（`/acp spawn ... --bind here`） +## Live：ACP 绑定冒烟（`/acp spawn ... --bind here`） - 测试：`src/gateway/gateway-acp-bind.live.test.ts` - 目标：使用 live ACP 智能体验证真实 ACP 会话绑定流程： - 发送 `/acp spawn --bind here` - - 原地绑定一个合成的消息渠道会话 - - 在同一会话上发送一条普通后续消息 - - 验证该后续消息落入已绑定的 ACP 会话 transcript 中 + - 就地绑定一个合成的消息渠道会话 + - 在同一会话上发送一次普通后续消息 + - 验证该后续消息落入已绑定 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 私信的会话上下文 + - 直接 `pnpm test:live ...` 的 ACP 智能体：`claude` + - 合成渠道：Slack 私信 风格的会话上下文 - ACP 后端：`acpx` - 覆盖项： - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -549,8 +544,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` 接口，并带有仅管理员可用的合成 originating-route 字段，这样测试就能附加消息渠道上下文，而无需假装从外部投递。 - - 当 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 未设置时，测试会使用内置 `acpx` 插件的内建智能体注册表来处理所选 ACP harness 智能体。 + - 该通道使用 gateway `chat.send` 接口，并带有仅管理员可用的合成 originating-route 字段，因此测试可以附加消息渠道上下文，而无需伪装成外部投递。 + - 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用内置 `acpx` 插件的内建智能体注册表来选择 ACP harness 智能体。 示例： @@ -577,30 +572,30 @@ pnpm test:docker:live-acp-bind:gemini Docker 说明： - Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。 -- 默认情况下，它会按顺序对所有受支持的 live CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`、然后 `gemini`。 +- 默认情况下，它会依次对所有受支持的 live 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 前缀中，并在缺失时安装所请求的 live 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。 +- 它会 source `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，把 `acpx` 安装到可写 npm 前缀中，并在缺失时安装所请求的 live CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。 +- 在 Docker 内，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，这样 `acpx` 就能让来自已 source profile 的 provider 环境变量继续对其子 harness CLI 可用。 -## Live：Codex app-server harness 冒烟测试 +## Live：Codex app-server harness 冒烟 -- 目标：通过正常的 gateway - `agent` 方法验证由插件拥有的 Codex harness： - - 加载内置的 `codex` 插件 +- 目标：通过常规 gateway + `agent` 方法验证插件自有的 Codex harness： + - 加载内置 `codex` 插件 - 选择 `OPENCLAW_AGENT_RUNTIME=codex` - - 向 `codex/gpt-5.4` 发送第一轮 gateway 智能体请求 + - 向 `codex/gpt-5.4` 发送第一轮 gateway 智能体消息 - 向同一个 OpenClaw 会话发送第二轮消息，并验证 app-server - 线程可以恢复 - - 通过同一个 gateway 命令 + 线程能够恢复 + - 通过相同的 gateway 命令 路径运行 `/codex status` 和 `/codex models` - 测试：`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` -- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，因此损坏的 Codex - harness 不会通过静默回退到 PI 而蒙混过关。 -- 鉴权：来自 shell/profile 的 `OPENAI_API_KEY`，以及可选复制的 +- 可选 MCP / 工具探测：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，这样损坏的 Codex + harness 就无法通过静默回退到 PI 来蒙混过关。 +- 认证：来自 shell / profile 的 `OPENAI_API_KEY`，以及可选复制的 `~/.codex/auth.json` 和 `~/.codex/config.toml` 本地配方： @@ -624,24 +619,24 @@ 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 live 测试。 -- Docker 默认启用图像和 MCP/工具探测。若你需要更窄的调试运行，请设置 +- 它会 source 挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI + 认证文件，将 `@openai/codex` 安装到一个可写的挂载 npm + 前缀中，暂存源代码树，然后仅运行 Codex harness live 测试。 +- Docker 默认启用图像和 MCP / 工具探测。需要更窄范围的调试运行时，可设置 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`。 -- Docker 还会导出 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，与 live - 测试配置保持一致，因此 `openai-codex/*` 或 PI 回退都无法掩盖 Codex harness - 回归问题。 +- Docker 也会导出 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，与 live + 测试配置保持一致，因此 `openai-codex/*` 或 PI 回退无法掩盖 Codex harness + 回归。 ### 推荐的 live 配方 -范围窄、明确的 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` - 跨多个提供商的工具调用： @@ -655,18 +650,18 @@ Docker 说明： - `google/...` 使用 Gemini API（API key）。 - `google-antigravity/...` 使用 Antigravity OAuth bridge（Cloud Code Assist 风格的智能体端点）。 -- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立的鉴权 + 工具行为差异）。 +- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立认证 + 工具行为差异）。 - Gemini API 与 Gemini CLI： - - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API key / profile 鉴权）；这通常就是大多数用户所说的 “Gemini”。 - - CLI：OpenClaw 通过 shell 调用本地 `gemini` 二进制；它有自己的鉴权方式，行为也可能不同（流式传输/工具支持/版本偏差）。 + - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API key / profile 认证）；这也是大多数用户所说的 “Gemini”。 + - CLI：OpenClaw 会 shell out 到本地 `gemini` 二进制；它有自己的认证，并且行为可能不同（流式传输 / 工具支持 / 版本偏差）。 ## Live：模型矩阵（我们覆盖什么） -这里没有固定的“CI 模型列表”（live 是按需启用的），但以下是**推荐**在具有 key 的开发机器上定期覆盖的模型。 +这里没有固定的“CI 模型列表”（live 是按需启用的），但以下是**建议**在具备 keys 的开发机器上定期覆盖的模型。 -### 现代冒烟集（工具调用 + 图像） +### Modern 冒烟集（工具调用 + 图像） -这是我们预期始终保持可用的“常用模型”运行集： +这是我们期望持续可用的“常用模型”运行集： - OpenAI（非 Codex）：`openai/gpt-5.4`（可选：`openai/gpt-5.4-mini`） - OpenAI Codex：`openai-codex/gpt-5.4` @@ -676,7 +671,7 @@ Docker 说明： - 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） @@ -689,7 +684,7 @@ Docker 说明： - Z.AI（GLM）：`zai/glm-4.7` - MiniMax：`minimax/MiniMax-M2.7` -可选附加覆盖（有更好，没有也可以）： +可选的额外覆盖（有则更好）： - xAI：`xai/grok-4`（或最新可用版本） - Mistral：`mistral/`…（选择一个你已启用、支持 “tools” 的模型） @@ -698,42 +693,42 @@ Docker 说明： ### Vision：图像发送（附件 → 多模态消息） -在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude/Gemini/OpenAI 支持视觉的变体等），以覆盖图像探测。 +在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude / Gemini / OpenAI 支持 vision 的变体等），以覆盖 image probe。 ### 聚合器 / 替代 Gateway 网关 -如果你启用了相关 key，我们也支持通过以下方式测试： +如果你启用了 keys，我们也支持通过以下方式进行测试： -- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选模型） -- OpenCode：`opencode/...` 用于 Zen，`opencode-go/...` 用于 Go（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 鉴权） +- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选项） +- OpenCode：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证） -如果你有凭证/配置，还可以将更多提供商纳入 live 矩阵： +如果你有 creds / config，也可以将更多提供商纳入 live 矩阵： - 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot` -- 通过 `models.providers`（自定义端点）：`minimax`（云/API），以及任何兼容 OpenAI/Anthropic 的代理（LM Studio、vLLM、LiteLLM 等） +- 通过 `models.providers`（自定义端点）：`minimax`（云端 / API），以及任何兼容 OpenAI / Anthropic 的代理（LM Studio、vLLM、LiteLLM 等） -提示：不要试图在文档中硬编码“所有模型”。权威列表就是你机器上 `discoverModels(...)` 的返回结果，加上当前可用的 key。 +提示：不要尝试在文档中硬编码“所有模型”。权威列表是你机器上的 `discoverModels(...)` 返回结果，加上当前可用的所有 keys。 ## 凭证（绝不要提交） Live 测试发现凭证的方式与 CLI 相同。实际含义如下： -- 如果 CLI 能工作，live 测试也应该能找到相同的 key。 -- 如果 live 测试提示“no creds”，就像调试 `openclaw models list` / 模型选择一样去调试它。 +- 如果 CLI 可用，live 测试应该能找到相同的 key。 +- 如果 live 测试说“没有凭证”，那就像排查 `openclaw models list` / 模型选择问题一样去排查。 -- 每个智能体的鉴权 profile：`~/.openclaw/agents//agent/auth-profiles.json`（这就是 live 测试中 “profile keys” 的含义） +- 每个智能体的认证 profile：`~/.openclaw/agents//agent/auth-profiles.json`（这就是 live 测试中 “profile keys” 的含义） - 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`） -- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的 live home 中，但它不是主 profile-key 存储） -- 默认情况下，本地 live 运行会把当前活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 鉴权目录复制到临时测试 home 中；暂存的 live home 会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，从而让探测不会落到你真实宿主的工作区上。 +- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的 live home 中，但它不是主 profile-key store） +- 本地 live 运行默认会将活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/`，以及受支持的外部 CLI 认证目录复制到临时测试 home 中；暂存的 live home 会跳过 `workspace/` 和 `sandboxes/`，并且会去除 `agents.*.workspace` / `agentDir` 路径覆盖，以确保 probes 不会落到你真实主机的工作区上。 -如果你想依赖环境变量 key（例如在你的 `~/.profile` 中导出），请在本地测试前运行 `source ~/.profile`，或使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。 +如果你想依赖环境变量 key（例如在 `~/.profile` 中导出的 key），请在本地测试前运行 `source ~/.profile`，或者使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。 ## Deepgram live（音频转录） - 测试：`src/media-understanding/providers/deepgram/audio.live.test.ts` - 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## BytePlus 编码计划 live +## BytePlus（国际版） 编码计划 live - 测试：`src/agents/byteplus.live.test.ts` - 启用：`BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` @@ -744,9 +739,9 @@ Live 测试发现凭证的方式与 CLI 相同。实际含义如下： - 测试：`extensions/comfy/comfy.live.test.ts` - 启用：`OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - 范围： - - 验证内置 comfy 图像、视频和 `music_generate` 路径 - - 除非配置了 `models.providers.comfy.`，否则会跳过各项能力 - - 在修改 comfy 工作流提交、轮询、下载或插件注册后尤其有用 + - 覆盖内置 comfy 图像、视频和 `music_generate` 路径 + - 除非配置了 `models.providers.comfy.`，否则会跳过每项能力 + - 在修改 comfy 工作流提交、轮询、下载或插件注册后很有用 ## 图像生成 live @@ -754,10 +749,10 @@ Live 测试发现凭证的方式与 CLI 相同。实际含义如下： - 命令：`pnpm test:live src/image-generation/runtime.live.test.ts` - Harness：`pnpm test:live:media image` - 范围： - - 枚举每个已注册的图像生成提供商插件 + - 枚举每一个已注册的图像生成提供商插件 - 在探测前从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量 - - 默认优先使用 live/env API key，而不是已存储的鉴权 profile，这样 `auth-profiles.json` 中过期的测试 key 就不会掩盖 shell 中真实的凭证 - - 跳过没有可用鉴权/profile/模型的提供商 + - 默认优先使用 live / env API key，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过期的测试 key 不会掩盖真实 shell 凭证 + - 跳过没有可用认证 / profile / model 的提供商 - 通过共享运行时能力运行标准图像生成变体： - `google:flash-generate` - `google:pro-generate` @@ -768,10 +763,10 @@ Live 测试发现凭证的方式与 CLI 相同。实际含义如下： - `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_MODELS="openai/gpt-image-2,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 store 鉴权，并忽略仅来自环境变量的覆盖 +- 可选认证行为： + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 以强制使用 profile store 认证，并忽略仅环境变量的覆盖 ## 音乐生成 live @@ -779,23 +774,23 @@ Live 测试发现凭证的方式与 CLI 相同。实际含义如下： - 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness：`pnpm test:live:media music` - 范围： - - 验证共享的内置音乐生成提供商路径 + - 覆盖共享的内置音乐生成提供商路径 - 当前覆盖 Google 和 MiniMax - 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量 - - 默认优先使用 live/env API key，而不是已存储的鉴权 profile，这样 `auth-profiles.json` 中过期的测试 key 就不会掩盖 shell 中真实的凭证 - - 跳过没有可用鉴权/profile/模型的提供商 - - 在可用时运行两个已声明的运行时模式： - - `generate`，仅使用提示词输入 - - 当提供商声明 `capabilities.edit.enabled` 时运行 `edit` + - 默认优先使用 live / env API key，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过期的测试 key 不会掩盖真实 shell 凭证 + - 跳过没有可用认证 / profile / model 的提供商 + - 在可用时运行两种已声明的运行时模式： + - `generate`：仅 prompt 输入 + - `edit`：当提供商声明 `capabilities.edit.enabled` - 当前共享通道覆盖： - `google`：`generate`、`edit` - `minimax`：`generate` - - `comfy`：单独的 Comfy live 文件，不在这次共享扫描内 + - `comfy`：单独的 Comfy live 文件，不在这个共享扫描中 - 可选缩小范围： - `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 store 鉴权，并忽略仅来自环境变量的覆盖 +- 可选认证行为： + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 以强制使用 profile store 认证，并忽略仅环境变量的覆盖 ## 视频生成 live @@ -803,161 +798,170 @@ Live 测试发现凭证的方式与 CLI 相同。实际含义如下： - 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness：`pnpm test:live:media video` - 范围： - - 验证共享的内置视频生成提供商路径 - - 默认走发布安全的冒烟路径：非 FAL 提供商、每个提供商一次 text-to-video 请求、一秒龙虾提示词，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每提供商操作上限（默认 `180000`） + - 覆盖共享的内置视频生成提供商路径 + - 默认使用对发布安全的冒烟路径：非 FAL 提供商、每个提供商一次文本生成视频请求、一秒钟龙虾 prompt，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每提供商操作上限（默认 `180000`） - 默认跳过 FAL，因为提供商侧队列延迟可能主导发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行它 - 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量 - - 默认优先使用 live/env API key，而不是已存储的鉴权 profile，这样 `auth-profiles.json` 中过期的测试 key 就不会掩盖 shell 中真实的凭证 - - 跳过没有可用鉴权/profile/模型的提供商 - - 默认仅运行 `generate` - - 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，在可用时也会运行已声明的转换模式： - - 当提供商声明 `capabilities.imageToVideo.enabled`，且所选提供商/模型在共享扫描中接受基于 buffer 的本地图像输入时，运行 `imageToVideo` - - 当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商/模型在共享扫描中接受基于 buffer 的本地视频输入时，运行 `videoToVideo` + - 默认优先使用 live / env API key，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过期的测试 key 不会掩盖真实 shell 凭证 + - 跳过没有可用认证 / profile / model 的提供商 + - 默认只运行 `generate` + - 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`，在可用时也运行已声明的转换模式： + - `imageToVideo`：当提供商声明 `capabilities.imageToVideo.enabled`，并且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地图像输入 + - `videoToVideo`：当提供商声明 `capabilities.videoToVideo.enabled`，并且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地视频输入 - 当前在共享扫描中已声明但跳过的 `imageToVideo` 提供商： - `vydra`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL - 提供商特定的 Vydra 覆盖： - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - 该文件会运行 `veo3` text-to-video，以及一个默认使用远程图像 URL 夹具的 `kling` 通道 + - 该文件会运行 `veo3` 文本生成视频，以及默认使用远程图像 URL fixture 的 `kling` 通道 - 当前 `videoToVideo` live 覆盖： - - 仅 `runway`，并且所选模型为 `runway/gen4_aleph` 时才运行 + - 仅 `runway`，且所选模型为 `runway/gen4_aleph` 时 - 当前在共享扫描中已声明但跳过的 `videoToVideo` 提供商： - - `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 参考 URL - - `google`，因为当前共享 Gemini/Veo 通道使用本地基于 buffer 的输入，而该路径在共享扫描中不被接受 - - `openai`，因为当前共享通道缺少针对组织特定视频 inpaint/remix 访问权限的保证 + - `alibaba`、`qwen`、`xai`，因为这些路径当前要求远程 `http(s)` / MP4 参考 URL + - `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_VIDEO_GENERATION_SKIP_PROVIDERS=""` 以在默认扫描中包含每个提供商，包括 FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 以降低激进冒烟运行中每个提供商的操作上限 -- 可选鉴权行为： - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用 profile store 鉴权，并忽略仅来自环境变量的覆盖 + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 以减少每个提供商的操作上限，用于更激进的冒烟运行 +- 可选认证行为： + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 以强制使用 profile store 认证，并忽略仅环境变量的覆盖 ## 媒体 live harness - 命令：`pnpm test:live:media` -- 用途： +- 目的： - 通过一个仓库原生入口点运行共享的图像、音乐和视频 live 测试套件 - 自动从 `~/.profile` 加载缺失的提供商环境变量 - - 默认自动将每个测试套件缩小到当前具有可用鉴权的提供商 - - 复用 `scripts/test-live.mjs`，因此心跳和安静模式行为保持一致 + - 默认自动将每个测试套件缩小到当前具有可用认证的提供商 + - 复用 `scripts/test-live.mjs`，因此心跳和静默模式行为保持一致 - 示例： - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker 运行器（可选的“在 Linux 中可工作”检查） +## Docker 运行器（可选的“在 Linux 中可用”检查） 这些 Docker 运行器分为两类： -- Live 模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 仅在仓库 Docker 镜像内运行与其对应的 profile-key live 文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），同时挂载你的本地 config 目录和工作区（若已挂载，也会读取 `~/.profile`）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。 -- Docker live 运行器默认使用更小的冒烟上限，以便完整 Docker 扫描仍具可行性： - `test:docker:live-models` 默认设置 `OPENCLAW_LIVE_MAX_MODELS=12`，而 +- Live 模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像中运行各自匹配的 profile-key live 文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），并挂载你的本地配置目录和工作区（如果已挂载，则会 source `~/.profile`）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。 +- Docker live 运行器默认使用更小的冒烟上限，以便完整 Docker 扫描仍然可行： + `test:docker:live-models` 默认设置 `OPENCLAW_LIVE_MAX_MODELS=12`，并且 `test:docker:live-gateway` 默认设置 `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、 `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` 以及 - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你明确想要更大的穷尽式扫描时，再覆盖这些环境变量。 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你 + 明确想要更大的完整扫描时，再覆盖这些环境变量。 - `test:docker:all` 会先通过 `test:docker:live-build` 构建一次 live Docker 镜像，然后在两个 live Docker 通道中复用它。 - 容器冒烟运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:gateway-network`、`test:docker:mcp-channels` 和 `test:docker:plugins` 会启动一个或多个真实容器，并验证更高层级的集成路径。 -Live 模型 Docker 运行器还会仅绑定挂载所需的 CLI 鉴权 home（如果运行未缩小范围，则挂载所有受支持的鉴权 home），然后在运行前将它们复制到容器 home 中，这样外部 CLI OAuth 就能刷新 token，而不会修改宿主机的鉴权存储： +这些 live 模型 Docker 运行器还会只 bind mount 所需的 CLI 认证 home（或者在运行未缩小范围时挂载所有受支持的 home），然后在运行前将它们复制到容器 home 中，这样外部 CLI OAuth 就可以刷新 token，而不会修改主机认证存储： - 直接模型：`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 网关 + dev 智能体：`pnpm test:docker:live-gateway`（脚本：`scripts/test-live-gateway-models-docker.sh`） -- Open WebUI live 冒烟测试：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`） -- 新手引导向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`） -- Gateway 网关网络（两个容器、WS 鉴权 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`） -- MCP 渠道桥接（带种子数据的 Gateway 网关 + stdio bridge + 原始 Claude notification-frame 冒烟测试）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`） -- 插件（安装冒烟测试 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`） +- Open WebUI live 冒烟：`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`） -Live 模型 Docker 运行器还会以只读方式绑定挂载当前检出的代码，并在容器内将其暂存到一个临时 workdir 中。这样可以让运行时镜像保持精简，同时仍能针对你精确的本地源码/配置运行 Vitest。 -暂存步骤会跳过大型本地专用缓存和应用构建输出，例如 +这些 live 模型 Docker 运行器还会以只读方式 bind mount 当前检出内容， +并将其暂存到容器内的临时工作目录中。这样既能让运行时 +镜像保持精简，又仍然可以针对你当前本地的确切源代码 / 配置运行 Vitest。 +暂存步骤会跳过大型的仅本地缓存和应用构建输出，例如 `.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地的 `.build` 或 -Gradle 输出目录，因此 Docker live 运行不会浪费数分钟去复制机器特定的产物。 -它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 gateway live 探测就不会在容器内启动真实的 Telegram/Discord 等渠道 worker。 -`test:docker:live-models` 仍然运行 `pnpm test:live`，因此当你需要在该 Docker 通道中缩小或排除 gateway live 覆盖时，也要一并传递 +Gradle 输出目录，这样 Docker live 运行就不会花几分钟去复制 +机器特定的产物。 +它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，因此 gateway live 探测不会在容器内启动 +真实的 Telegram / Discord / 等渠道工作进程。 +`test:docker:live-models` 仍然运行 `pnpm test:live`，因此当你需要缩小范围或从该 Docker 通道中排除 gateway +live 覆盖时，也要同时传递 `OPENCLAW_LIVE_GATEWAY_*`。 -`test:docker:openwebui` 是一个更高层级的兼容性冒烟测试：它会启动一个启用了 OpenAI 兼容 HTTP 端点的 -OpenClaw gateway 容器，再针对该 gateway 启动一个固定版本的 Open WebUI 容器，通过 -Open WebUI 登录，验证 `/api/models` 暴露了 `openclaw/default`，然后通过 -Open WebUI 的 `/api/chat/completions` 代理发送一条真实聊天请求。 -第一次运行可能会明显更慢，因为 Docker 可能需要拉取 -Open WebUI 镜像，而 Open WebUI 也可能需要完成自己的冷启动设置。 -该通道需要可用的 live 模型 key，而 `OPENCLAW_PROFILE_FILE` -（默认 `~/.profile`）是在 Docker 化运行中提供它的主要方式。 -成功运行会打印一个简短的 JSON 载荷，例如 `{ "ok": true, "model": +`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 可能需要完成自身的冷启动 setup。 +这个通道要求有可用的 live 模型 key，而 `OPENCLAW_PROFILE_FILE` +（默认 `~/.profile`）是在 Docker 化运行中提供该 key 的主要方式。 +成功运行会打印一个小型 JSON 载荷，例如 `{ "ok": true, "model": "openclaw/default", ... }`。 -`test:docker:mcp-channels` 是有意设计为确定性的，不需要真实的 -Telegram、Discord 或 iMessage 账号。它会启动一个带种子数据的 Gateway 网关 -容器，启动第二个容器来执行 `openclaw mcp serve`，然后 -通过真实的 stdio MCP bridge 验证路由后的会话发现、transcript 读取、附件元数据、 -实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 + -权限通知。通知检查会直接检查原始 stdio MCP 帧，因此该冒烟测试验证的是 bridge 实际发出的内容，而不只是某个特定客户端 SDK 恰好暴露出来的内容。 +`test:docker:mcp-channels` 刻意保持确定性，不需要 +真实的 Telegram、Discord 或 iMessage 账号。它会启动一个预置的 Gateway 网关 +容器，启动第二个容器来运行 `openclaw mcp serve`，然后 +通过真实的 stdio MCP bridge 验证路由后的会话发现、转录读取、附件元数据、 +live 事件队列行为、出站发送路由，以及 Claude 风格的渠道 + +权限通知。通知检查会直接检查原始 stdio MCP 帧， +因此这个冒烟测试验证的是 bridge 实际发出了什么， +而不仅仅是某个特定客户端 SDK 恰好暴露了什么。 手动 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_PROFILE_ENV_ONLY=1` 用于只验证从 `OPENCLAW_PROFILE_FILE` 读取的环境变量；它会使用临时 config/workspace 目录，并且不挂载外部 CLI 鉴权 -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于在 Docker 内缓存 CLI 安装 -- `$HOME` 下的外部 CLI 鉴权目录/文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...` +- `OPENCLAW_PROFILE_FILE=...`（默认：`~/.profile`）挂载到 `/home/node/.profile`，并在运行测试前 source +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` 用于仅验证从 `OPENCLAW_PROFILE_FILE` source 的环境变量，使用临时 config / workspace 目录且不挂载外部 CLI 认证 +- `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_LIVE_REQUIRE_PROFILE_KEYS=1` 用于确保凭证来自 profile store（而非环境变量） -- `OPENCLAW_OPENWEBUI_MODEL=...` 用于选择在 Open WebUI 冒烟测试中由 gateway 暴露的模型 -- `OPENCLAW_OPENWEBUI_PROMPT=...` 用于覆盖 Open WebUI 冒烟测试所使用的 nonce 检查提示词 +- `OPENCLAW_SKIP_DOCKER_BUILD=1` 用于复用现有的 `openclaw:local-live` 镜像，以便在无需重建的情况下重新运行 +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于确保 creds 来自 profile store（而不是环境变量） +- `OPENCLAW_OPENWEBUI_MODEL=...` 用于选择 gateway 为 Open WebUI 冒烟测试暴露的模型 +- `OPENCLAW_OPENWEBUI_PROMPT=...` 用于覆盖 Open WebUI 冒烟测试所用的 nonce 检查 prompt - `OPENWEBUI_IMAGE=...` 用于覆盖固定的 Open WebUI 镜像标签 ## 文档完整性检查 -编辑文档后运行文档检查：`pnpm check:docs`。 -如果你还需要检查页内标题锚点，请运行完整的 Mintlify 锚点校验：`pnpm docs:check-links:anchors`。 +在修改文档后运行文档检查：`pnpm check:docs`。 +当你还需要检查页内标题锚点时，运行完整的 Mintlify 锚点验证：`pnpm docs:check-links:anchors`。 ## 离线回归（CI 安全） -这些是在没有真实提供商时的“真实管线”回归测试： +这些是在没有真实提供商的情况下对“真实流水线”进行的回归测试： - Gateway 网关工具调用（mock OpenAI，真实 gateway + 智能体循环）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”） -- Gateway 网关向导（WS `wizard.start`/`wizard.next`，强制写入 config + auth）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”） +- Gateway 网关向导（WS `wizard.start` / `wizard.next`，强制写入 config + auth）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”） ## 智能体可靠性评估（Skills） 我们已经有一些 CI 安全的测试，它们的行为类似“智能体可靠性评估”： -- 通过真实的 gateway + 智能体循环进行 mock 工具调用（`src/gateway/gateway.test.ts`）。 -- 用于验证会话接线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。 +- 通过真实 gateway + 智能体循环进行 mock 工具调用（`src/gateway/gateway.test.ts`）。 +- 验证会话接线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。 -对于 Skills（参见 [Skills](/zh-CN/tools/skills)），目前仍然缺少： +对于 Skills（见 [Skills](/zh-CN/tools/skills)），目前仍然缺少的内容： -- **决策：** 当提示词中列出 Skills 时，智能体是否会选择正确的 skill（或避开无关的 skill）？ -- **合规：** 智能体在使用前是否会读取 `SKILL.md`，并遵循要求的步骤/参数？ -- **工作流契约：** 断言工具顺序、会话历史延续和沙箱边界的多轮场景。 +- **决策：** 当 prompt 中列出了 Skills 时，智能体是否会选择正确的 skill（或避免使用无关 skill）？ +- **合规性：** 智能体在使用前是否会读取 `SKILL.md`，并遵循要求的步骤 / 参数？ +- **工作流契约：** 用于断言工具顺序、会话历史延续和沙箱边界的多轮场景。 未来的评估应优先保持确定性： -- 使用 mock 提供商的场景运行器，用于断言工具调用 + 顺序、skill 文件读取以及会话接线。 -- 一小组聚焦 skill 的场景（使用 vs 避免、门控、提示词注入）。 -- 只有在 CI 安全测试套件就位之后，才添加可选的 live 评估（按需启用、受环境变量门控）。 +- 一个使用 mock 提供商的场景运行器，用于断言工具调用 + 顺序、skill 文件读取和会话接线。 +- 一小组聚焦于 skill 的场景（使用 vs 避免、门控、prompt 注入）。 +- 只有在 CI 安全测试套件就位之后，才添加可选的 live 评估（按需启用、由环境变量控制）。 ## 契约测试（插件和渠道形状） -契约测试用于验证每个已注册的插件和渠道都符合其 -接口契约。它们会遍历所有已发现的插件，并运行一套关于形状和行为的断言。默认的 `pnpm test` unit 通道会有意 -跳过这些共享接缝和冒烟测试文件；当你修改共享渠道或提供商接口时，请显式运行契约命令。 +契约测试用于验证每个已注册插件和渠道都符合其 +接口契约。它们会遍历所有发现到的插件，并运行一组关于形状和行为的断言。默认的 `pnpm test` 单元通道会刻意 +跳过这些共享接缝和冒烟文件；当你修改共享渠道或提供商表面时，请显式运行契约命令。 ### 命令 @@ -974,10 +978,10 @@ Telegram、Discord 或 iMessage 账号。它会启动一个带种子数据的 Ga - **session-binding** - 会话绑定行为 - **outbound-payload** - 消息载荷结构 - **inbound** - 入站消息处理 -- **actions** - 渠道操作处理器 +- **actions** - 渠道动作处理器 - **threading** - 线程 ID 处理 -- **directory** - 目录/花名册 API -- **group-policy** - 群组策略执行 +- **directory** - 目录 / roster API +- **group-policy** - 群组策略强制执行 ### 提供商状态契约 @@ -990,18 +994,18 @@ Telegram、Discord 或 iMessage 账号。它会启动一个带种子数据的 Ga 位于 `src/plugins/contracts/*.contract.test.ts`： -- **auth** - 鉴权流程契约 -- **auth-choice** - 鉴权选择/选取 +- **auth** - 认证流程契约 +- **auth-choice** - 认证选择 / 选取 - **catalog** - 模型目录 API - **discovery** - 插件发现 - **loader** - 插件加载 - **runtime** - 提供商运行时 -- **shape** - 插件形状/接口 +- **shape** - 插件形状 / 接口 - **wizard** - 设置向导 ### 何时运行 -- 在修改 plugin-sdk 导出或子路径之后 +- 在修改 Plugin SDK 导出或子路径之后 - 在新增或修改渠道或提供商插件之后 - 在重构插件注册或发现逻辑之后 @@ -1009,13 +1013,13 @@ Telegram、Discord 或 iMessage 账号。它会启动一个带种子数据的 Ga ## 添加回归测试（指南） -当你修复了一个在 live 中发现的提供商/模型问题时： +当你修复在 live 中发现的提供商 / 模型问题时： -- 如果可能，添加一个 CI 安全的回归测试（mock/stub 提供商，或捕获精确的请求形状转换） -- 如果它本质上只能在 live 中复现（速率限制、鉴权策略），就让 live 测试保持范围窄，并通过环境变量按需启用 -- 优先针对能捕获该缺陷的最小层级： - - 提供商请求转换/回放缺陷 → 直接模型测试 - - gateway 会话/历史/工具管线缺陷 → gateway live 冒烟测试或 CI 安全的 gateway mock 测试 -- SecretRef 遍历防护： +- 如果可能，添加一个 CI 安全的回归测试（mock / stub 提供商，或捕获精确的请求形状转换） +- 如果问题本质上只能通过 live 复现（速率限制、认证策略），就让 live 测试保持范围窄，并通过环境变量按需启用 +- 优先针对能捕获该 bug 的最小层级： + - 提供商请求转换 / 回放 bug → 直接模型测试 + - gateway 会话 / 历史 / 工具流水线 bug → gateway live 冒烟测试或 CI 安全的 gateway mock 测试 +- SecretRef 遍历护栏： - `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言遍历段 exec id 会被拒绝。 - - 如果你在 `src/secrets/target-registry-data.ts` 中新增了一个 `includeInPlan` SecretRef 目标家族，请更新该测试中的 `classifyTargetClass`。该测试会在遇到未分类目标 id 时故意失败，因此新类别无法被静默跳过。 + - 如果你在 `src/secrets/target-registry-data.ts` 中添加了新的 `includeInPlan` SecretRef 目标家族，请更新该测试中的 `classifyTargetClass`。该测试会在未分类目标 id 上故意失败，因此新的类别无法被静默跳过。 diff --git a/docs/zh-CN/providers/fireworks.md b/docs/zh-CN/providers/fireworks.md index ae4004b57..d2826eed8 100644 --- a/docs/zh-CN/providers/fireworks.md +++ b/docs/zh-CN/providers/fireworks.md @@ -2,13 +2,13 @@ read_when: - 你想在 OpenClaw 中使用 Fireworks - 你需要 Fireworks API 密钥环境变量或默认模型 ID -summary: Fireworks 设置（凭证 + 模型选择） +summary: Fireworks 设置（认证 + 模型选择） title: Fireworks x-i18n: - generated_at: "2026-04-21T19:44:01Z" + generated_at: "2026-04-21T20:53:27Z" model: gpt-5.4 provider: openai - source_hash: fb2268b8d6d58da66c7db7423062d6b308a6f657e2825a406e2b5d1d499afa05 + source_hash: 1b2aae346f1fb7e6d649deefe9117d8d8399c0441829cb49132ff5b86a7051ce source_path: providers/fireworks.md workflow: 15 --- @@ -20,7 +20,7 @@ x-i18n: | 属性 | 值 | | ------------- | ------------------------------------------------------ | | 提供商 | `fireworks` | -| 凭证 | `FIREWORKS_API_KEY` | +| 认证 | `FIREWORKS_API_KEY` | | API | 与 OpenAI 兼容的 chat/completions | | 基础 URL | `https://api.fireworks.ai/inference/v1` | | 默认模型 | `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo` | @@ -28,7 +28,7 @@ x-i18n: ## 入门指南 - + ```bash openclaw onboard --auth-choice fireworks-api-key ``` @@ -59,17 +59,17 @@ openclaw onboard --non-interactive \ ## 内置目录 | 模型引用 | 名称 | 输入 | 上下文 | 最大输出 | 说明 | -| ------------------------------------------------------ | --------------------------- | ---------- | ------- | ---------- | ------------------------------------------ | -| `fireworks/accounts/fireworks/models/kimi-k2p6` | Kimi K2.6 | text,image | 262,144 | 262,144 | Fireworks 上最新的 Kimi 模型 | +| ------------------------------------------------------ | --------------------------- | ---------- | ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `fireworks/accounts/fireworks/models/kimi-k2p6` | Kimi K2.6 | text,image | 262,144 | 262,144 | Fireworks 上最新的 Kimi 模型。Fireworks K2.6 请求已禁用 thinking；如果你需要 Kimi 的 thinking 输出，请直接通过 Moonshot 路由。 | | `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo` | Kimi K2.5 Turbo（Fire Pass） | text,image | 256,000 | 256,000 | Fireworks 上默认内置的入门模型 | -如果 Fireworks 发布了更新的模型，例如新的 Qwen 或 Gemma 版本，你可以直接使用其 Fireworks 模型 ID 切换到该模型，而无需等待内置目录更新。 +如果 Fireworks 发布了更新的模型，例如新的 Qwen 或 Gemma 版本，你可以直接使用其 Fireworks 模型 id 切换到该模型，而无需等待内置目录更新。 -## 自定义 Fireworks 模型 ID +## 自定义 Fireworks 模型 id -OpenClaw 也接受动态 Fireworks 模型 ID。使用 Fireworks 显示的精确模型或路由器 ID，并为其添加 `fireworks/` 前缀。 +OpenClaw 也接受动态 Fireworks 模型 id。请使用 Fireworks 显示的精确模型或路由 id，并加上 `fireworks/` 前缀。 ```json5 { @@ -84,13 +84,13 @@ OpenClaw 也接受动态 Fireworks 模型 ID。使用 Fireworks 显示的精确 ``` - - OpenClaw 中的每个 Fireworks 模型引用都以 `fireworks/` 开头，后面跟着 Fireworks 平台中的精确 ID 或路由路径。例如： + + OpenClaw 中的每个 Fireworks 模型引用都以 `fireworks/` 开头，后接 Fireworks 平台中的精确 id 或路由路径。例如： - 路由模型：`fireworks/accounts/fireworks/routers/kimi-k2p5-turbo` - 直接模型：`fireworks/accounts/fireworks/models/` - OpenClaw 在构建 API 请求时会去掉 `fireworks/` 前缀，并将剩余路径发送到 Fireworks 端点。 + OpenClaw 在构建 API 请求时会去掉 `fireworks/` 前缀，并将其余路径发送到 Fireworks 端点。 @@ -98,7 +98,7 @@ OpenClaw 也接受动态 Fireworks 模型 ID。使用 Fireworks 显示的精确 如果 Gateway 网关 运行在你的交互式 shell 之外，请确保 `FIREWORKS_API_KEY` 对该进程也可用。 - 如果密钥仅存在于 `~/.profile` 中，那么对于 `launchd`/`systemd` 守护进程它不会起作用，除非该环境也被导入到那里。请在 `~/.openclaw/.env` 中设置该密钥，或通过 `env.shellEnv` 设置，以确保网关进程可以读取它。 + 仅存在于 `~/.profile` 中的密钥无法帮助 `launchd`/`systemd` 守护进程，除非该环境也被导入到那里。请在 `~/.openclaw/.env` 中设置该密钥，或通过 `env.shellEnv` 设置，以确保 Gateway 网关 进程可以读取它。 @@ -111,6 +111,6 @@ OpenClaw 也接受动态 Fireworks 模型 ID。使用 Fireworks 显示的精确 选择提供商、模型引用和故障切换行为。 - 常规故障排除和常见问题。 + 一般故障排除和常见问题。 diff --git a/docs/zh-CN/providers/ollama.md b/docs/zh-CN/providers/ollama.md index 00b96d748..d6b0981c5 100644 --- a/docs/zh-CN/providers/ollama.md +++ b/docs/zh-CN/providers/ollama.md @@ -1,21 +1,21 @@ --- read_when: - 你想通过 Ollama 使用云端或本地模型运行 OpenClaw - - 你需要 Ollama 的设置和配置指导 + - 你需要 Ollama 的设置和配置指南 summary: 使用 Ollama（云端和本地模型）运行 OpenClaw title: Ollama x-i18n: - generated_at: "2026-04-15T13:38:11Z" + generated_at: "2026-04-21T20:53:29Z" model: gpt-5.4 provider: openai - source_hash: 098e083e0fc484bddb5270eb630c55d7832039b462d1710372b6afece5cefcdf + source_hash: 197612f2173409d186b915b838e5fdba2f594912672f3c450accb4877e732c9c source_path: providers/ollama.md workflow: 15 --- # Ollama -OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模型以及本地/自托管的 Ollama 服务器。你可以通过三种模式使用 Ollama：通过可访问的 Ollama 主机实现的 `Cloud + Local`、直接连接 `https://ollama.com` 的 `Cloud only`，或连接可访问的 Ollama 主机的 `Local only`。 +OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模型以及本地/自托管的 Ollama 服务器。你可以通过三种模式使用 Ollama：通过可访问的 Ollama 主机实现的 `Cloud + Local`、对接 `https://ollama.com` 的 `Cloud only`，或对接可访问 Ollama 主机的 `Local only`。 **远程 Ollama 用户**：不要在 OpenClaw 中使用 `/v1` 的 OpenAI 兼容 URL（`http://host:11434/v1`）。这会破坏工具调用，模型还可能将原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL：`baseUrl: "http://host:11434"`（不要加 `/v1`）。 @@ -27,7 +27,7 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模 - **最适合：** 以最快路径完成可用的 Ollama 云端或本地设置。 + **最适合：** 以最快方式完成可用的 Ollama 云端或本地设置。 @@ -35,15 +35,15 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模 openclaw onboard ``` - 在提供商列表中选择 **Ollama**。 + 从提供商列表中选择 **Ollama**。 - - **Cloud + Local** — 本地 Ollama 主机加上通过该主机路由的云模型 - - **Cloud only** — 通过 `https://ollama.com` 使用托管的 Ollama 模型 + - **Cloud + Local** — 本地 Ollama 主机，加上通过该主机路由的云模型 + - **Cloud only** — 通过 `https://ollama.com` 使用托管 Ollama 模型 - **Local only** — 仅使用本地模型 - `Cloud only` 会提示输入 `OLLAMA_API_KEY`，并推荐托管云模型的默认值。`Cloud + Local` 和 `Local only` 会要求提供 Ollama 基础 URL、发现可用模型，并在所选本地模型尚不可用时自动拉取。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以启用云访问。 + `Cloud only` 会提示输入 `OLLAMA_API_KEY`，并推荐托管云端默认模型。`Cloud + Local` 和 `Local only` 会要求提供 Ollama base URL，发现可用模型，并在所选本地模型尚不可用时自动拉取。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以启用云访问。 ```bash @@ -60,7 +60,7 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模 --accept-risk ``` - 也可以选择指定自定义基础 URL 或模型： + 你也可以选择指定自定义 base URL 或模型： ```bash openclaw onboard --non-interactive \ @@ -78,10 +78,10 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模 - **Cloud + Local**：安装 Ollama，使用 `ollama signin` 登录，并通过该主机路由云请求 - - **Cloud only**：使用 `https://ollama.com` 并提供 `OLLAMA_API_KEY` + - **Cloud only**：使用带有 `OLLAMA_API_KEY` 的 `https://ollama.com` - **Local only**：从 [ollama.com/download](https://ollama.com/download) 安装 Ollama - + ```bash ollama pull gemma4 # 或 @@ -91,7 +91,7 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模 ``` - 对于 `Cloud only`，请使用真实的 `OLLAMA_API_KEY`。对于基于主机的设置，任意占位值都可以： + 对于 `Cloud only`，请使用你真实的 `OLLAMA_API_KEY`。对于基于主机的设置，任意占位值都可以： ```bash # 云端 @@ -104,7 +104,7 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模 openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY" ``` - + ```bash openclaw models list openclaw models set ollama/gemma4 @@ -133,16 +133,18 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模 `Cloud + Local` 使用可访问的 Ollama 主机作为本地模型和云模型的统一控制点。这是 Ollama 推荐的混合流程。 - 在设置时使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama 基础 URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以启用云访问。当主机已登录时，OpenClaw 还会推荐托管云模型默认值，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。 + 在设置期间使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama base URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以启用云访问。当主机已登录时，OpenClaw 还会推荐托管云端默认模型，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。 - 如果该主机尚未登录，OpenClaw 会将设置保持为仅本地模式，直到你运行 `ollama signin`。 + 如果主机尚未登录，OpenClaw 会将设置保持为仅本地模式，直到你运行 `ollama signin`。 - `Cloud only` 通过 Ollama 的托管 API `https://ollama.com` 运行。 + `Cloud only` 对接 Ollama 的托管 API `https://ollama.com`。 - 在设置时使用 **Cloud only**。OpenClaw 会提示输入 `OLLAMA_API_KEY`，设置 `baseUrl: "https://ollama.com"`，并初始化托管云模型列表。此路径**不**需要本地 Ollama 服务器或 `ollama signin`。 + 在设置期间使用 **Cloud only**。OpenClaw 会提示输入 `OLLAMA_API_KEY`，设置 `baseUrl: "https://ollama.com"`，并初始化托管云模型列表。此路径**不**需要本地 Ollama 服务器或 `ollama signin`。 + + `openclaw onboard` 中显示的云模型列表会从 `https://ollama.com/api/tags` 实时加载，最多 500 项，因此选择器反映的是当前托管模型目录，而不是静态预置列表。如果在设置时 `ollama.com` 无法访问或未返回任何模型，OpenClaw 会回退到之前硬编码的推荐项，以便新手引导仍可完成。 @@ -156,21 +158,21 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模 ## 模型发现（隐式 provider） -当你设置了 `OLLAMA_API_KEY`（或身份验证配置）且**没有**定义 `models.providers.ollama` 时，OpenClaw 会从位于 `http://127.0.0.1:11434` 的本地 Ollama 实例中发现模型。 +当你设置 `OLLAMA_API_KEY`（或 auth profile），并且**没有**定义 `models.providers.ollama` 时，OpenClaw 会从 `http://127.0.0.1:11434` 上的本地 Ollama 实例发现模型。 -| 行为 | 详细信息 | +| 行为 | 详情 | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 目录查询 | 查询 `/api/tags` | -| 能力检测 | 使用尽力而为的 `/api/show` 查询来读取 `contextWindow` 并检测能力（包括视觉） | -| 视觉模型 | 由 `/api/show` 报告具有 `vision` 能力的模型会被标记为支持图像输入（`input: ["text", "image"]`），因此 OpenClaw 会自动将图片注入到提示中 | +| 能力检测 | 使用尽力而为的 `/api/show` 查询来读取 `contextWindow` 并检测能力（包括 vision） | +| 视觉模型 | 由 `/api/show` 报告具有 `vision` 能力的模型会被标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图像注入提示词 | | 推理检测 | 使用模型名称启发式规则（`r1`、`reasoning`、`think`）标记 `reasoning` | | Token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 | -| 费用 | 将所有费用设置为 `0` | +| 成本 | 所有成本均设置为 `0` | 这样可以避免手动录入模型，同时让目录与本地 Ollama 实例保持一致。 ```bash -# 查看有哪些模型可用 +# 查看有哪些可用模型 ollama list openclaw models list ``` @@ -181,10 +183,10 @@ openclaw models list ollama pull mistral ``` -新模型会被自动发现并可立即使用。 +新模型会被自动发现并可直接使用。 -如果你显式设置了 `models.providers.ollama`，则会跳过自动发现，你必须手动定义模型。参见下面的显式配置部分。 +如果你显式设置了 `models.providers.ollama`，将跳过自动发现，你必须手动定义模型。请参阅下方的显式配置部分。 ## 配置 @@ -198,13 +200,13 @@ ollama pull mistral ``` - 如果设置了 `OLLAMA_API_KEY`，你可以在 provider 条目中省略 `apiKey`，OpenClaw 会在可用性检查时自动补齐它。 + 如果设置了 `OLLAMA_API_KEY`，你可以在 provider 条目中省略 `apiKey`，OpenClaw 会在可用性检查时自动填充它。 - 当你想使用托管云端设置、Ollama 运行在其他主机/端口、你想强制指定特定上下文窗口或模型列表，或你希望完全手动定义模型时，请使用显式配置。 + 当你希望使用托管云设置、Ollama 运行在其他主机/端口、你想强制指定特定上下文窗口或模型列表，或者你想完全手动定义模型时，请使用显式配置。 ```json5 { @@ -233,7 +235,7 @@ ollama pull mistral - + 如果 Ollama 运行在不同的主机或端口上（显式配置会禁用自动发现，因此你需要手动定义模型）： ```json5 @@ -243,7 +245,7 @@ ollama pull mistral ollama: { apiKey: "ollama-local", baseUrl: "http://ollama-host:11434", // 不要加 /v1 - 使用原生 Ollama API URL - api: "ollama", // 显式设置以确保使用原生工具调用行为 + api: "ollama", // 显式设置以确保原生工具调用行为 }, }, }, @@ -251,7 +253,7 @@ ollama pull mistral ``` - 不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，而该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama 基础 URL。 + 不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama 基础 URL。 @@ -276,15 +278,15 @@ ollama pull mistral ## Ollama Web 搜索 -OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider 使用。 +OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 -| 属性 | 详细信息 | +| 属性 | 详情 | | ----------- | ----------------------------------------------------------------------------------------------------------------- | | 主机 | 使用你配置的 Ollama 主机（设置了 `models.providers.ollama.baseUrl` 时使用该值，否则为 `http://127.0.0.1:11434`） | | 认证 | 无需密钥 | | 要求 | Ollama 必须正在运行，并且已通过 `ollama signin` 登录 | -在 `openclaw onboard` 或 `openclaw configure --section web` 中选择 **Ollama Web 搜索**，或设置： +在 `openclaw onboard` 或 `openclaw configure --section web` 中选择 **Ollama Web 搜索**，或者设置： ```json5 { @@ -299,7 +301,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider ``` -完整的设置和行为细节，请参见 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。 +完整的设置与行为细节，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。 ## 高级配置 @@ -307,10 +309,10 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider - **在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要通过代理使用 OpenAI 格式，且不依赖原生工具调用行为时，才应使用此模式。 + **在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为代理使用 OpenAI 格式，并且不依赖原生工具调用行为时，才应使用此模式。 - 如果你需要改用 OpenAI 兼容端点（例如位于仅支持 OpenAI 格式的代理之后），请显式设置 `api: "openai-completions"`： + 如果你确实需要改用 OpenAI 兼容端点（例如位于仅支持 OpenAI 格式的代理之后），请显式设置 `api: "openai-completions"`： ```json5 { @@ -328,9 +330,9 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider } ``` - 在此模式下，可能无法同时支持流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 来禁用流式传输。 + 此模式可能无法同时支持流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 来禁用流式传输。 - 当 Ollama 使用 `api: "openai-completions"` 时，OpenClaw 默认会注入 `options.num_ctx`，以避免 Ollama 静默回退到 4096 的上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段，请禁用此行为： + 当在 Ollama 中使用 `api: "openai-completions"` 时，OpenClaw 默认会注入 `options.num_ctx`，这样 Ollama 就不会悄悄回退到 4096 的上下文窗口。如果你的代理/上游会拒绝未知的 `options` 字段，请禁用此行为： ```json5 { @@ -351,7 +353,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider - 对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口；否则，会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。 + 对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，否则会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。 你可以在显式 provider 配置中覆盖 `contextWindow` 和 `maxTokens`： @@ -376,29 +378,29 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider - OpenClaw 默认会将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为支持推理的模型。 + OpenClaw 默认将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为支持推理的模型。 ```bash ollama pull deepseek-r1:32b ``` - 无需额外配置——OpenClaw 会自动标记它们。 + 不需要额外配置——OpenClaw 会自动标记它们。 - - Ollama 可免费使用并在本地运行，因此所有模型费用都设置为 $0。这同时适用于自动发现的模型和手动定义的模型。 + + Ollama 是免费的，并且在本地运行，因此所有模型成本都设为 $0。这同时适用于自动发现的模型和手动定义的模型。 - 内置的 Ollama 插件会为 [memory search](/zh-CN/concepts/memory) 注册一个 memory embedding provider。它使用已配置的 Ollama 基础 URL 和 API 密钥。 + 内置的 Ollama 插件会为 [memory search](/zh-CN/concepts/memory) 注册一个记忆嵌入 provider。它使用已配置的 Ollama base URL 和 API key。 | 属性 | 值 | | ------------- | ------------------- | | 默认模型 | `nomic-embed-text` | - | 自动拉取 | 是——如果 embedding 模型在本地不存在，则会自动拉取 | + | 自动拉取 | 是 —— 如果嵌入模型尚未在本地存在，将自动拉取 | - 要将 Ollama 选为 memory search 的 embedding provider： + 要选择 Ollama 作为 memory search 的嵌入 provider： ```json5 { @@ -413,10 +415,10 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider - OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），可同时完整支持流式传输和工具调用。无需任何特殊配置。 + OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），可同时完整支持流式传输和工具调用。不需要任何特殊配置。 - 如果你需要使用 OpenAI 兼容端点，请参阅上面的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。 + 如果你需要使用 OpenAI 兼容端点，请参阅上方的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。 @@ -426,13 +428,13 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider - 请确保 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或身份验证配置），同时**没有**定义显式的 `models.providers.ollama` 条目： + 请确认 Ollama 正在运行，并且你已经设置了 `OLLAMA_API_KEY`（或 auth profile），同时**没有**定义显式的 `models.providers.ollama` 条目： ```bash ollama serve ``` - 验证 API 可访问： + 验证 API 是否可访问： ```bash curl http://localhost:11434/api/tags @@ -441,7 +443,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider - 如果列表中没有你的模型，请在本地拉取该模型，或在 `models.providers.ollama` 中显式定义它。 + 如果列表中没有你的模型，请在本地拉取该模型，或者在 `models.providers.ollama` 中显式定义它。 ```bash ollama list # 查看已安装的模型 @@ -453,7 +455,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider - 检查 Ollama 是否在正确的端口上运行： + 检查 Ollama 是否运行在正确的端口上： ```bash # 检查 Ollama 是否正在运行 @@ -473,14 +475,14 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider ## 相关内容 - + 所有提供商、模型引用和故障切换行为的概览。 如何选择和配置模型。 - 了解 Ollama 驱动的网页搜索的完整设置和行为细节。 + 由 Ollama 驱动的 Web 搜索的完整设置与行为细节。 完整的配置参考。 diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index 85dd4bfdb..b02f4e553 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -1,15 +1,15 @@ --- read_when: - 你想在 OpenClaw 中使用 OpenAI 模型 - - 你希望使用 Codex 订阅认证，而不是 API 密钥 + - 你想使用 Codex 订阅认证，而不是 API 密钥 - 你需要更严格的 GPT-5 智能体执行行为 -summary: 在 OpenClaw 中使用 API 密钥或 Codex 订阅来使用 OpenAI +summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅 title: OpenAI x-i18n: - generated_at: "2026-04-21T05:16:43Z" + generated_at: "2026-04-21T20:53:31Z" model: gpt-5.4 provider: openai - source_hash: 172beb28b099e3d71998458408c9a6b32b03790d2b016351f724bc3f0d9d3245 + source_hash: 692615b77885c0387d339d47c02ff056ba95d3608aa681882893a46d2a0f723f source_path: providers/openai.md workflow: 15 --- @@ -19,7 +19,7 @@ x-i18n: OpenAI 提供用于 GPT 模型的开发者 API。OpenClaw 支持两种认证方式： - **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型） -- **Codex 订阅** — 通过 ChatGPT/Codex 登录并使用订阅权限（`openai-codex/*` 模型） +- **Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型） OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。 @@ -74,13 +74,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA ``` - OpenClaw **不会** 在直接 API 路径上暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。 + OpenClaw **不会** 在直连 API 路径上暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。 - **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。 + **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要使用 ChatGPT 登录。 @@ -111,10 +111,10 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA | 模型引用 | 路由 | 认证 | |-----------|-------|------| | `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex 登录 | - | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于权限） | + | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于授权资格） | - 这一路径与 `openai/gpt-5.4` 是刻意分开的。要直接访问 Platform，请使用带 API 密钥的 `openai/*`；要使用 Codex 订阅访问，请使用 `openai-codex/*`。 + 这一路由刻意与 `openai/gpt-5.4` 分开。使用 API 密钥配合 `openai/*` 进行直接 Platform 访问，使用 `openai-codex/*` 进行 Codex 订阅访问。 ### 配置示例 @@ -126,7 +126,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA ``` - 如果新手引导复用了现有的 Codex CLI 登录，这些凭证仍由 Codex CLI 管理。凭证过期时，OpenClaw 会先重新读取外部 Codex 来源，再将刷新后的凭证写回 Codex 存储。 + 如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续由 Codex CLI 管理。凭证过期后，OpenClaw 会先重新读取外部 Codex 来源，再将刷新后的凭证写回 Codex 存储。 ### 上下文窗口上限 @@ -138,7 +138,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA - 原生 `contextWindow`：`1050000` - 默认运行时 `contextTokens` 上限：`272000` - 在实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它： + 较小的默认上限在实践中具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它： ```json5 { @@ -153,7 +153,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA ``` - 使用 `contextWindow` 来声明模型的原生元数据。使用 `contextTokens` 来限制运行时上下文预算。 + 使用 `contextWindow` 声明模型原生元数据。使用 `contextTokens` 限制运行时上下文预算。 @@ -163,39 +163,53 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA 内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。 -| 功能 | 值 | +| 能力 | 值 | | ------------------------- | ---------------------------------- | -| 默认模型 | `openai/gpt-image-1` | +| 默认模型 | `openai/gpt-image-2` | | 每次请求的最大图像数 | 4 | | 编辑模式 | 已启用（最多 5 张参考图像） | -| 尺寸覆盖 | 支持 | -| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | +| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | +| 宽高比 / 分辨率 | 不会转发给 OpenAI Images API | ```json5 { agents: { defaults: { - imageGenerationModel: { primary: "openai/gpt-image-1" }, + imageGenerationModel: { primary: "openai/gpt-image-2" }, }, }, } ``` -有关共享工具参数、提供商选择和故障转移行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。 +有关共享工具参数、提供商选择和故障切换行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。 +`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。 + +生成： + +``` +/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 +``` + +编辑： + +``` +/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 +``` + ## 视频生成 内置的 `openai` 插件通过 `video_generate` 工具注册视频生成功能。 -| 功能 | 值 | +| 能力 | 值 | | ---------------- | --------------------------------------------------------------------------------- | | 默认模型 | `openai/sora-2` | | 模式 | 文生视频、图生视频、单视频编辑 | | 参考输入 | 1 张图像或 1 个视频 | | 尺寸覆盖 | 支持 | -| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并附带工具警告 | +| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 | ```json5 { @@ -208,18 +222,18 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA ``` -有关共享工具参数、提供商选择和故障转移行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。 +有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。 ## GPT-5 提示词贡献 -OpenClaw 会为 `openai/*` 和 `openai-codex/*` 的 GPT-5 系列运行添加一个 OpenAI 专用的 GPT-5 提示词贡献。它位于内置的 OpenAI 插件中，适用于 `gpt-5`、`gpt-5.2`、`gpt-5.4` 和 `gpt-5.4-mini` 等模型 id，不适用于较旧的 GPT-4.x 模型。 +OpenClaw 会为 `openai/*` 和 `openai-codex/*` 的 GPT-5 系列运行添加 OpenAI 专用的 GPT-5 提示词贡献。它位于内置的 OpenAI 插件中，适用于 `gpt-5`、`gpt-5.2`、`gpt-5.4` 和 `gpt-5.4-mini` 等模型 ID，不适用于较旧的 GPT-4.x 模型。 -GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人格持续性、执行安全、工具纪律、输出形态、完成检查和验证。渠道特定的回复行为和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。对于匹配的模型，GPT-5 指导始终启用。友好互动风格层是独立的，并且可配置。 +GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、完成检查和验证增加了带标签的行为契约。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。对于匹配的模型，GPT-5 指导始终启用。友好的交互风格层是独立且可配置的。 | 值 | 效果 | | ---------------------- | ------------------------------------------- | -| `"friendly"`（默认） | 启用友好互动风格层 | +| `"friendly"`（默认） | 启用友好的交互风格层 | | `"on"` | `"friendly"` 的别名 | | `"off"` | 仅禁用友好风格层 | @@ -246,23 +260,23 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人 这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 -## 语音与语音处理 +## 语音和语音合成 - 内置的 `openai` 插件为 `messages.tts` 接口注册语音合成功能。 + 内置的 `openai` 插件为 `messages.tts` 接口注册了语音合成功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | - | 音色 | `messages.tts.providers.openai.voice` | `coral` | + | 声音 | `messages.tts.providers.openai.voice` | `coral` | | 语速 | `messages.tts.providers.openai.speed` | （未设置） | | 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） | - | 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺使用 `opus`，文件使用 `mp3` | + | 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` | | API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` | | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | - 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用音色：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 + 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用声音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 ```json5 { @@ -277,13 +291,13 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人 ``` - 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 Base URL，而不会影响聊天 API 端点。 + 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS Base URL，而不会影响聊天 API 端点。 - 内置的 `openai` 插件为 Voice Call 插件注册实时转录功能。 + 内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| @@ -293,18 +307,18 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人 | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | - 使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law 音频。 + 使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并采用 G.711 u-law 音频。 - 内置的 `openai` 插件为 Voice Call 插件注册实时语音功能。 + 内置的 `openai` 插件为 Voice Call 插件注册了实时语音功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime` | - | 音色 | `...openai.voice` | `alloy` | + | 声音 | `...openai.voice` | `alloy` | | 温度 | `...openai.temperature` | `0.8` | | VAD 阈值 | `...openai.vadThreshold` | `0.5` | | 静音时长 | `...openai.silenceDurationMs` | `500` | @@ -320,20 +334,20 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人 ## 高级配置 - - 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都默认使用 WebSocket 优先并在失败时回退到 SSE（`"auto"`）。 + + 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先，并在失败时回退到 SSE（`"auto"`）。 在 `"auto"` 模式下，OpenClaw 会： - - 在回退到 SSE 之前，对一次早期 WebSocket 失败进行重试 - - 发生失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE - - 为重试和重连附加稳定的会话与轮次标识头 + - 在回退到 SSE 之前重试一次早期 WebSocket 失败 + - 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE + - 为重试和重连附加稳定的会话和轮次身份标头 - 在不同传输变体之间规范化使用量计数器（`input_tokens` / `prompt_tokens`） | 值 | 行为 | |-------|----------| - | `"auto"`（默认） | WebSocket 优先，失败回退到 SSE | - | `"sse"` | 强制仅使用 SSE | - | `"websocket"` | 强制仅使用 WebSocket | + | `"auto"`（默认） | WebSocket 优先，SSE 回退 | + | `"sse"` | 仅强制使用 SSE | + | `"websocket"` | 仅强制使用 WebSocket | ```json5 { @@ -356,7 +370,7 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人 - OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以降低首轮延迟。 + OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以减少首轮延迟。 ```json5 // 禁用预热 @@ -397,13 +411,13 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人 ``` - 会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置的默认值。 + 会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将返回到已配置的默认值。 - OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型进行设置： + OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它： ```json5 { @@ -421,21 +435,21 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人 支持的值：`auto`、`default`、`flex`、`priority`。 - `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 将保持 `service_tier` 不变。 + `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。 - 对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩： + 对于直连 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩： - - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`） + - 强制 `store: true`（除非模型兼容性设置了 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` - 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`） - 适用于 Azure OpenAI Responses 等兼容端点： + 适用于 Azure OpenAI Responses 这类兼容端点： ```json5 { @@ -487,7 +501,7 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人 - `responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。 + `responsesServerCompaction` 仅控制 `context_management` 注入。直连 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置了 `supportsStore: false`。 @@ -507,31 +521,31 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人 使用 `strict-agentic` 时，OpenClaw 会： - 当工具操作可用时，不再将仅规划的轮次视为成功进展 - - 使用“立即执行”的引导重试该轮次 - - 对于实质性工作自动启用 `update_plan` - - 如果模型持续规划而不执行，则显式呈现阻塞状态 + - 使用“立即行动”的引导重试该轮次 + - 对于较大工作自动启用 `update_plan` + - 如果模型持续只做规划而不行动，则显式显示阻塞状态 - 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型家族仍保持默认行为。 + 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧模型系列保持默认行为。 - OpenClaw 会以不同方式处理直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用的 OpenAI 兼容 `/v1` 代理不同： + OpenClaw 会以不同方式处理直连 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI 兼容 `/v1` 代理： **原生路由**（`openai/*`、`openai-codex/*`、Azure OpenAI）： - 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }` - - 对于拒绝 `reasoning.effort: "none"` 的模型或代理，省略已禁用的 reasoning + - 对拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的 reasoning - 默认将工具 schema 设为严格模式 - - 仅在已验证的原生主机上附加隐藏归因头 - - 保留 OpenAI 专用的请求塑形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示） + - 仅在已验证的原生主机上附加隐藏归属标头 + - 保留 OpenAI 专用的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示） **代理 / 兼容路由：** - - 使用更宽松的兼容行为 - - 不会强制严格工具 schema 或原生专用头 + - 使用更宽松的兼容性行为 + - 不强制严格工具 schema 或仅限原生的标头 - Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因头。 + Azure OpenAI 使用原生传输和兼容性行为，但不会接收隐藏归属标头。 @@ -540,7 +554,7 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人 - 选择提供商、模型引用和故障转移行为。 + 选择提供商、模型引用和故障切换行为。 共享图像工具参数和提供商选择。 diff --git a/docs/zh-CN/tools/image-generation.md b/docs/zh-CN/tools/image-generation.md index 01c7e040e..52ab8e0cb 100644 --- a/docs/zh-CN/tools/image-generation.md +++ b/docs/zh-CN/tools/image-generation.md @@ -6,20 +6,20 @@ read_when: summary: 使用已配置的提供商（OpenAI、Google Gemini、fal、MiniMax、ComfyUI、Vydra）生成和编辑图像 title: 图像生成 x-i18n: - generated_at: "2026-04-06T22:52:16Z" + generated_at: "2026-04-21T20:53:27Z" model: gpt-5.4 provider: openai - source_hash: 8f7303c199d46e63e88f5f9567478a1025631afb03cb35f44344c12370365e57 + source_hash: e365cd23f4f8d8c9ce88d57e65f06ac5ae5285b8b7f9ea37f0b08ab5f6ff7235 source_path: tools/image-generation.md workflow: 15 --- # 图像生成 -`image_generate` 工具让智能体能够使用你已配置的提供商创建和编辑图像。生成的图像会自动作为媒体附件随智能体的回复一并发送。 +`image_generate` 工具允许智能体使用你已配置的提供商来创建和编辑图像。生成的图像会作为媒体附件自动随智能体的回复一并发送。 -只有在至少有一个图像生成提供商可用时，此工具才会显示。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel` 或设置提供商 API 密钥。 +只有在至少有一个图像生成提供商可用时，该工具才会显示。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel` 或设置提供商 API 密钥。 ## 快速开始 @@ -32,7 +32,7 @@ x-i18n: agents: { defaults: { imageGenerationModel: { - primary: "openai/gpt-image-1", + primary: "openai/gpt-image-2", }, }, }, @@ -41,20 +41,20 @@ x-i18n: 3. 向智能体提问：_“生成一张友好的龙虾吉祥物图像。”_ -智能体会自动调用 `image_generate`。无需将工具加入允许列表——当有可用提供商时，它默认启用。 +智能体会自动调用 `image_generate`。无需允许工具白名单 —— 只要有可用提供商，它默认就会启用。 ## 支持的提供商 -| 提供商 | 默认模型 | 编辑支持 | API 密钥 | -| ------ | -------------------------------- | ---------------------------------- | ------------------------------------------------------ | -| OpenAI | `gpt-image-1` | 是（最多 5 张图像） | `OPENAI_API_KEY` | -| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | -| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` | +| 提供商 | 默认模型 | 编辑支持 | API 密钥 | +| ------ | -------------------------------- | ---------------------------------- | ------------------------------------------------------- | +| OpenAI | `gpt-image-2` | 是（最多 5 张图像） | `OPENAI_API_KEY` | +| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | +| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` | | MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） | | ComfyUI | `workflow` | 是（1 张图像，由工作流配置） | 云端使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | -| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` | +| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` | -使用 `action: "list"` 可在运行时查看可用的提供商和模型： +使用 `action: "list"` 可在运行时查看可用提供商和模型： ``` /tool image_generate action=list @@ -62,22 +62,22 @@ x-i18n: ## 工具参数 -| 参数 | 类型 | 描述 | -| ------------- | -------- | ----------------------------------------------------------------------------------- | -| `prompt` | string | 图像生成提示词（`action: "generate"` 时必填） | -| `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 | -| `model` | string | 提供商/模型覆盖，例如 `openai/gpt-image-1` | -| `image` | string | 编辑模式下的单个参考图像路径或 URL | -| `images` | string[] | 编辑模式下的多个参考图像（最多 5 张） | -| `size` | string | 尺寸提示：`1024x1024`、`1536x1024`、`1024x1536`、`1024x1792`、`1792x1024` | -| `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` | -| `resolution` | string | 分辨率提示：`1K`、`2K` 或 `4K` | -| `count` | number | 要生成的图像数量（1–4） | -| `filename` | string | 输出文件名提示 | +| 参数 | 类型 | 说明 | +| ------------- | -------- | ------------------------------------------------------------------------------------- | +| `prompt` | string | 图像生成提示词（`action: "generate"` 时必填） | +| `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 | +| `model` | string | 提供商/模型覆盖，例如 `openai/gpt-image-2` | +| `image` | string | 编辑模式下的单个参考图像路径或 URL | +| `images` | string[] | 编辑模式下的多个参考图像（最多 5 张） | +| `size` | string | 尺寸提示：`1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`3840x2160` | +| `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` | +| `resolution` | string | 分辨率提示：`1K`、`2K` 或 `4K` | +| `count` | number | 要生成的图像数量（1–4） | +| `filename` | string | 输出文件名提示 | -并非所有提供商都支持全部参数。当回退提供商支持的是接近的几何选项而不是精确请求的选项时，OpenClaw 会在提交前重新映射到最接近的受支持尺寸、宽高比或分辨率。确实不受支持的覆盖项仍会在工具结果中报告。 +并非所有提供商都支持所有参数。当回退提供商支持接近的几何选项但不支持你精确请求的值时，OpenClaw 会在提交前重映射为最接近的受支持尺寸、宽高比或分辨率。真正不受支持的覆盖项仍会在工具结果中报告。 -工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。 +工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。 ## 配置 @@ -88,7 +88,7 @@ x-i18n: agents: { defaults: { imageGenerationModel: { - primary: "openai/gpt-image-1", + primary: "openai/gpt-image-2", fallbacks: ["google/gemini-3.1-flash-image-preview", "fal/fal-ai/flux/dev"], }, }, @@ -103,55 +103,81 @@ x-i18n: 1. 工具调用中的 **`model` 参数**（如果智能体指定了） 2. 配置中的 **`imageGenerationModel.primary`** 3. 按顺序使用 **`imageGenerationModel.fallbacks`** -4. **自动检测** —— 仅使用基于认证的提供商默认值： +4. **自动检测** —— 仅使用有凭证支持的提供商默认值： - 先使用当前默认提供商 - - 然后按提供商 ID 顺序使用其余已注册的图像生成提供商 + - 再按提供商 ID 顺序使用其余已注册的图像生成提供商 -如果某个提供商失败（认证错误、速率限制等），系统会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。 +如果某个提供商失败（凭证错误、速率限制等），会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。 说明： -- 自动检测会感知认证状态。只有当 OpenClaw 实际能够验证该提供商时， - 该提供商默认值才会进入候选列表。 -- 自动检测默认启用。如果你希望图像生成仅使用显式的 `model`、`primary` 和 `fallbacks` - 条目，请设置 - `agents.defaults.mediaGenerationAutoProviderFallback: false`。 -- 使用 `action: "list"` 可查看当前已注册的提供商、它们的 - 默认模型以及认证环境变量提示。 +- 自动检测会感知认证状态。只有当 OpenClaw 实际能够认证该提供商时，该提供商默认值才会进入候选列表。 +- 自动检测默认启用。如果你希望图像生成只使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。 +- 使用 `action: "list"` 可查看当前已注册的提供商、它们的默认模型以及认证环境变量提示。 ### 图像编辑 OpenAI、Google、fal、MiniMax 和 ComfyUI 支持编辑参考图像。传入参考图像路径或 URL： ``` -"把这张照片生成为水彩风格版本" + image: "/path/to/photo.jpg" +"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg" ``` OpenAI 和 Google 通过 `images` 参数最多支持 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。 -MiniMax 图像生成可通过两种内置的 MiniMax 认证路径使用： +### OpenAI `gpt-image-2` + +OpenAI 图像生成默认使用 `openai/gpt-image-2`。较旧的 `openai/gpt-image-1` 模型仍可显式选择，但新的 OpenAI 图像生成和图像编辑请求应使用 `gpt-image-2`。 + +`gpt-image-2` 同时支持文生图生成和参考图像编辑，均通过同一个 `image_generate` 工具完成。OpenClaw 会将 `prompt`、`count`、`size` 和参考图像转发给 OpenAI。OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；在可能的情况下，OpenClaw 会将它们映射为受支持的 `size`，否则工具会将其报告为被忽略的覆盖项。 + +生成一张 4K 横版图像： + +``` +/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1 +``` + +生成两张方形图像： + +``` +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2 +``` + +编辑一张本地参考图像： + +``` +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536 +``` + +使用多张参考图像进行编辑： + +``` +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 +``` + +MiniMax 图像生成功能可通过两种内置的 MiniMax 认证路径使用： - `minimax/image-01`，用于 API 密钥配置 - `minimax-portal/image-01`，用于 OAuth 配置 ## 提供商能力 -| 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | -| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（输出由工作流定义） | 是（1 张） | -| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | -| 尺寸控制 | 是 | 是 | 是 | 否 | 否 | 否 | -| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | -| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 | +| 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | +| --------------------- | --------------- | ------------------- | ------------- | -------------------- | --------------------------- | ------- | +| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（由工作流定义输出） | 是（1 张） | +| 编辑/参考图 | 是（最多 5 张） | 是（最多 5 张） | 是（1 张） | 是（1 张，主体参考） | 是（1 张，由工作流配置） | 否 | +| 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | +| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | +| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 | ## 相关内容 - [工具概览](/zh-CN/tools) — 所有可用的智能体工具 - [fal](/zh-CN/providers/fal) — fal 图像和视频提供商设置 - [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud 工作流设置 -- [Google (Gemini)](/zh-CN/providers/google) — Gemini 图像提供商设置 +- [Google（Gemini）](/zh-CN/providers/google) — Gemini 图像提供商设置 - [MiniMax](/zh-CN/providers/minimax) — MiniMax 图像提供商设置 - [OpenAI](/zh-CN/providers/openai) — OpenAI Images 提供商设置 - [Vydra](/zh-CN/providers/vydra) — Vydra 图像、视频和语音设置 - [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — `imageGenerationModel` 配置 -- [模型](/zh-CN/concepts/models) — 模型配置和故障转移 +- [模型](/zh-CN/concepts/models) — 模型配置与故障转移