From af817dcd7f8397350de09c6961b892aed7d32938 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 29 Apr 2026 01:51:28 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/gateway/configuration-reference.md | 607 +++++++++--------- 1 file changed, 303 insertions(+), 304 deletions(-) diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 1c8ae4762..4b87d9bee 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,71 +2,71 @@ read_when: - 你需要精确的字段级配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键、默认值，以及指向专用子系统参考文档的链接 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-28T22:57:48Z" + generated_at: "2026-04-29T01:48:44Z" model: gpt-5.5 provider: openai - source_hash: ed99df1a7ec858e79380704e29d1a31e7b10f0429aa928d205503f7ea97187b8 + source_hash: 83fd28b7d6a2e670ab97aac206bb14343bd887da3236c6135d7958cc6e97b735 source_path: gateway/configuration-reference.md workflow: 16 --- -`~/.openclaw/openclaw.json` 的核心配置参考。有关面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。 +Core 配置参考，适用于 `~/.openclaw/openclaw.json`。如需面向任务的概览，请参阅[配置](/zh-CN/gateway/configuration)。 -涵盖主要的 OpenClaw 配置表面；当某个子系统有自己的更深入参考时，会链接到对应页面。渠道和插件拥有的命令目录，以及深层 memory/QMD 开关，放在各自页面中，而不是本页。 +涵盖主要的 OpenClaw 配置表面；当某个子系统有自己的更深入参考时，会链接到对应页面。渠道和插件拥有的命令目录，以及深层内存/QMD 调节项，位于它们自己的页面，而不是本页。 -代码事实来源： +代码依据： -- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 -- `config.schema.lookup` 会为钻取工具返回一个按路径限定的 schema 节点 +- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema；可用时会合并内置/插件/渠道元数据 +- `config.schema.lookup` 会为向下钻取工具返回一个按路径限定的 schema 节点 - `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希 -智能体查找路径：编辑前，使用 `gateway` 工具操作 `config.schema.lookup` -获取精确到字段级别的文档和约束。使用 +智能体查找路径：编辑前，使用 `gateway` 工具动作 `config.schema.lookup` +获取精确的字段级文档和约束。使用 [配置](/zh-CN/gateway/configuration) 获取面向任务的指导，并使用本页 -查看更广泛的字段映射、默认值，以及到子系统参考的链接。 +查看更广泛的字段映射、默认值和子系统参考链接。 -专用深入参考： +专用深度参考： -- [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 -- [斜杠命令](/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 会使用安全默认值。 +配置格式为 **JSON5**（允许注释 + 尾随逗号）。所有字段都是可选的 — OpenClaw 会在省略时使用安全默认值。 --- ## 渠道 -每个渠道的配置键已移到专用页面；请参阅 -[配置 — 渠道](/zh-CN/gateway/config-channels) 了解 `channels.*`， +按渠道配置键已移至专用页面 — 请参阅 +[配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`， 包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他 -内置渠道（身份验证、访问控制、多账号、提及门控）。 +内置渠道（凭证、访问控制、多账户、提及门控）。 ## 智能体默认值、多智能体、会话和消息 -已移到专用页面；请参阅 -[配置 — 智能体](/zh-CN/gateway/config-agents)，其中包括： +已移至专用页面 — 请参阅 +[配置 — 智能体](/zh-CN/gateway/config-agents)，了解： -- `agents.defaults.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱） +- `agents.defaults.*`（工作区、模型、thinking、心跳、内存、媒体、Skills、沙箱） - `multiAgent.*`（多智能体路由和绑定） -- `session.*`（会话生命周期、压缩、修剪） +- `session.*`（会话生命周期、压缩、裁剪） - `messages.*`（消息投递、TTS、Markdown 渲染） - `talk.*`（Talk 模式） - - `talk.speechLocale`：用于 iOS/macOS 上 Talk 语音识别的可选 BCP 47 locale id - - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录前保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`） + - `talk.speechLocale`：Talk 在 iOS/macOS 上进行语音识别时使用的可选 BCP 47 语言区域 ID + - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转写文本前保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`） ## 工具和自定义提供商 -工具策略、实验性开关、由提供商支持的工具配置，以及自定义 -提供商/base-URL 设置已移到专用页面；请参阅 +工具策略、实验性开关、提供商支持的工具配置，以及自定义 +提供商 / base-URL 设置已移至专用页面 — 请参阅 [配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。 ## Models -提供商定义、模型 allowlist 和自定义提供商设置位于 +提供商定义、模型允许列表和自定义提供商设置位于 [配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。 `models` 根节点还拥有全局模型目录行为。 @@ -80,18 +80,17 @@ x-i18n: ``` - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：以提供商 id 为键的自定义提供商映射。 -- `models.pricing.enabled`：控制后台定价引导。为 - `false` 时，Gateway 网关启动会跳过 OpenRouter 和 LiteLLM 定价目录获取； +- `models.providers`：按提供商 ID 键控的自定义提供商映射。 +- `models.pricing.enabled`：控制后台定价引导。当为 + `false` 时，Gateway 网关启动会跳过 OpenRouter 和 LiteLLM 定价目录拉取； 已配置的 `models.providers.*.models[].cost` 值仍可用于本地成本 估算。 ## MCP -由 OpenClaw 管理的 MCP server 定义位于 `mcp.servers` 下，并由嵌入式 Pi -和其他运行时适配器使用。`openclaw mcp list`、 -`show`、`set` 和 `unset` 命令可在配置编辑期间管理此块，而不会连接到 -目标服务器。 +OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 Pi +和其他运行时适配器使用。`openclaw mcp list`、`show`、`set` 和 +`unset` 命令会管理此块，而不会在配置编辑期间连接到目标服务器。 ```json5 { @@ -115,19 +114,19 @@ x-i18n: } ``` -- `mcp.servers`：命名的 stdio 或远程 MCP server 定义，供暴露已配置 MCP 工具的运行时使用。 +- `mcp.servers`：命名的 stdio 或远程 MCP 服务器定义，供暴露已配置 MCP 工具的运行时使用。 远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`； `type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和 `openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。 -- `mcp.sessionIdleTtlMs`：按会话限定的内置 MCP 运行时的空闲 TTL。 - 一次性嵌入式运行会请求运行结束清理；此 TTL 是长生命周期会话和未来调用方的 - 兜底机制。 -- `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时热应用。 - 下一次工具发现/使用会基于新配置重新创建它们，因此被移除的 - `mcp.servers` 条目会立即回收，而不是等待空闲 TTL。 +- `mcp.sessionIdleTtlMs`：会话作用域内置 MCP 运行时的空闲 TTL。 + 一次性嵌入运行会请求运行结束清理；此 TTL 是长生命周期会话 + 和未来调用方的兜底机制。 +- `mcp.*` 下的更改会通过处置缓存的会话 MCP 运行时进行热应用。 + 下一次工具发现/使用会根据新配置重新创建它们，因此移除的 + `mcp.servers` 条目会立即被回收，而不是等待空闲 TTL。 请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 -[CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays) 了解运行时行为。 +[CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)了解运行时行为。 ## Skills @@ -154,14 +153,14 @@ x-i18n: } ``` -- `allowBundled`：可选 allowlist，仅适用于内置 Skills（托管/工作区 Skills 不受影响）。 -- `load.extraDirs`：额外的共享 skill 根目录（最低优先级）。 -- `install.preferBrew`：为 true 时，如果 `brew` 可用，会优先使用 Homebrew 安装器， +- `allowBundled`：仅用于内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。 +- `load.extraDirs`：额外的共享 Skill 根目录（优先级最低）。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器， 然后再回退到其他安装器类型。 - `install.nodeManager`：`metadata.openclaw.install` - 规格的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false` 会禁用某个 skill，即使它是内置/已安装的。 -- `entries..apiKey`：为声明主环境变量的 Skills 提供的便捷配置（明文字符串或 SecretRef 对象）。 + 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false` 会禁用某个 Skill，即使它是内置/已安装的。 +- `entries..apiKey`：供声明主环境变量的 Skills 使用的便捷项（明文字符串或 SecretRef 对象）。 --- @@ -190,42 +189,42 @@ x-i18n: ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundle。 +- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 - **配置更改需要重启 Gateway 网关。** -- `allow`：可选 allowlist（只加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（在插件支持时可用）。 +- `allow`：可选允许列表（只加载列出的插件）。`deny` 优先。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 - `plugins.entries..env`：插件作用域的环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略来自旧版 `before_agent_start` 的提示词修改字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子和受支持 bundle 提供的钩子目录。 -- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可从类型化钩子读取原始对话内容，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`。 -- `plugins.entries..subagent.allowModelOverride`：显式信任此插件为后台 subagent 运行请求每次运行的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任 subagent 覆盖目标的标准 `provider/model` 可选 allowlist。仅当你有意允许任何模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。 -- 渠道插件账号/运行时设置位于 `channels.` 下，应由拥有方插件的 manifest `channelConfigs` 元数据描述，而不是由中心 OpenClaw 选项注册表描述。 -- `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`）。 -- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web search）设置。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子和受支持 bundle 提供的钩子目录。 +- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可以从类型化钩子中读取原始对话内容，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`。 +- `plugins.entries..subagent.allowModelOverride`：显式信任此插件为后台子智能体运行请求每次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的标准 `provider/model` 目标的可选允许列表。仅在你有意允许任何模型时使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（当可用时由原生 OpenClaw 插件 schema 验证）。 +- 渠道插件账户/运行时设置位于 `channels.` 下，并应由所属插件的 manifest `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取提供商设置。 + - `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`）。 +- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok 网页搜索）设置。 - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 - `plugins.entries.memory-core.config.dreaming`：内存 Dreaming 设置。请参阅 [Dreaming](/zh-CN/concepts/dreaming) 了解阶段和阈值。 - - `enabled`：Dreaming 总开关（默认 `false`）。 - - `frequency`：每次完整 Dreaming 扫描的 cron 周期（默认为 `"0 3 * * *"`）。 - - `model`：可选的 Dream Diary subagent 模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；配合 `allowedModels` 使用以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或 allowlist 失败不会静默回退。 + - `enabled`：主 Dreaming 开关（默认 `false`）。 + - `frequency`：每次完整 Dreaming 扫描的 cron 节奏（默认为 `"0 3 * * *"`）。 + - `model`：可选 Dream Diary 子智能体模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；配合 `allowedModels` 使用以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退。 - 阶段策略和阈值是实现细节（不是面向用户的配置键）。 -- 完整内存配置位于 [内存配置参考](/zh-CN/reference/memory-config)： +- 完整内存配置位于[内存配置参考](/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`：选择活动内存插件 id，或使用 `"none"` 禁用内存插件。 -- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；除非你安装并选择其他引擎，否则默认值为 `"legacy"`。 +- 已启用的 Claude bundle 插件也可以从 `settings.json` 贡献嵌入式 Pi 默认值；OpenClaw 会将其作为经过清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活跃的内存插件 ID，或选择 `"none"` 以禁用内存插件。 +- `plugins.slots.contextEngine`：选择活跃的上下文引擎插件 ID；默认值为 `"legacy"`，除非你安装并选择了另一个引擎。 -请参阅 [插件](/zh-CN/tools/plugin)。 +请参阅[插件](/zh-CN/tools/plugin)。 --- @@ -276,30 +275,30 @@ x-i18n: ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `tabCleanup` 会在空闲时间后，或当某个会话超过其上限时，回收已跟踪的主智能体标签页。设置 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 可禁用这些单独的清理模式。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时处于禁用状态，因此浏览器导航默认保持严格。 -- 仅当你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到同样的私有网络阻止。 +- `tabCleanup` 会在空闲时间后或会话超出上限时回收已跟踪的主智能体标签页。设置 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 可禁用这些单独的清理模式。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 未设置时处于禁用状态，因此浏览器导航默认保持严格。 +- 只有在你有意信任专用网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间会受到相同的专用网络阻止。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 - 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。 -- 远程配置文件仅支持附加（start/stop/reset 已禁用）。 -- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当你的提供商给你直接的 DevTools WebSocket URL 时使用 WS(S)。 -- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 `attachOnly` CDP 可达性以及打开标签页请求。托管的 loopback 配置文件会保留本地 CDP 默认值。 -- 如果外部托管的 CDP 服务可通过 loopback 访问，请将该配置文件的 `attachOnly: true`；否则 OpenClaw 会将该 loopback 端口视为本地托管浏览器配置文件，并可能报告本地端口所有权错误。 -- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到选定主机或通过已连接的浏览器节点附加。 +- 远程配置文件仅支持附加（禁用启动/停止/重置）。 +- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当你的提供商提供直接的 DevTools WebSocket URL 时使用 WS(S)。 +- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程以及 `attachOnly` CDP 可达性检查和打开标签页请求。托管的 loopback 配置文件保留本地 CDP 默认值。 +- 如果外部托管的 CDP 服务可通过 loopback 访问，请为该配置文件设置 `attachOnly: true`；否则 OpenClaw 会把 loopback 端口视为本地托管的浏览器配置文件，并可能报告本地端口所有权错误。 +- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以在所选主机上附加，或通过已连接的浏览器节点附加。 - `existing-session` 配置文件可以设置 `userDataDir`，以指向特定的基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。 -- `existing-session` 配置文件保留当前的 Chrome MCP 路由限制：基于快照/ref 的操作而不是 CSS 选择器目标定位、单文件上传钩子、无对话框超时覆盖、无 `wait --load networkidle`，以及无 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅针对远程 CDP 显式设置 `cdpUrl`。 -- 本地托管配置文件可以设置 `executablePath`，为该配置文件覆盖全局 `browser.executablePath`。用它可以让一个配置文件运行在 Chrome 中，另一个运行在 Brave 中。 -- 本地托管配置文件在进程启动后使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP 设备发现，并使用 `browser.localCdpReadyTimeoutMs` 进行启动后的 CDP WebSocket 就绪检查。在 Chrome 能成功启动但就绪检查与启动过程发生竞争的较慢主机上，请调高这些值。两个值都必须是最高 `120000` 毫秒的正整数；无效的配置值会被拒绝。 +- `existing-session` 配置文件保留当前的 Chrome MCP 路由限制：基于快照/引用的操作，而不是 CSS 选择器定位；单文件上传钩子；无对话框超时覆盖；无 `wait --load networkidle`；并且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅为远程 CDP 显式设置 `cdpUrl`。 +- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 `browser.executablePath`。可用它让一个配置文件运行 Chrome，另一个运行 Brave。 +- 本地托管配置文件在进程启动后使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP 发现，并使用 `browser.localCdpReadyTimeoutMs` 进行启动后的 CDP websocket 就绪检查。在 Chrome 能成功启动但就绪检查与启动过程竞争的较慢主机上提高这些值。两个值都必须是最大为 `120000` ms 的正整数；无效配置值会被拒绝。 - 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- `browser.executablePath` 和 `browser.profiles..executablePath` 都接受 `~` 和 `~/...`，用于在 Chromium 启动前表示你的 OS 主目录。`existing-session` 配置文件上的按配置文件 `userDataDir` 也会展开波浪号。 +- `browser.executablePath` 和 `browser.profiles..executablePath` 在 Chromium 启动前都接受 `~` 和 `~/...` 表示你的操作系统主目录。`existing-session` 配置文件上的按配置文件 `userDataDir` 也会展开波浪号。 - 控制服务：仅限 loopback（端口从 `gateway.port` 派生，默认 `18791`）。 -- `extraArgs` 会向本地 Chromium 启动附加额外启动标志（例如 `--disable-gpu`、窗口大小或调试标志）。 +- `extraArgs` 会向本地 Chromium 启动追加额外启动标志（例如 `--disable-gpu`、窗口大小或调试标志）。 --- -## UI +## 界面 ```json5 { @@ -307,14 +306,14 @@ x-i18n: seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji、短文本、图片 URL 或 data URI + avatar: "CB", // emoji, short text, image URL, or data URI }, }, } ``` - `seamColor`：原生应用 UI 外壳的强调色（Talk Mode 气泡色调等）。 -- `assistant`：Control UI 身份覆盖。回退到当前活跃智能体身份。 +- `assistant`：控制 UI 身份覆盖。回退到活动智能体身份。 --- @@ -329,8 +328,8 @@ x-i18n: auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth + // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -348,9 +347,9 @@ x-i18n: basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // 危险：允许绝对外部 http(s) 嵌入 URL - // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必需 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header 源回退模式 + // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs + // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI + // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -361,20 +360,20 @@ x-i18n: // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // 可选。默认 false。 + // Optional. Default false. allowRealIpFallback: false, nodes: { pairing: { - // 可选。默认未设置/禁用。 + // Optional. Default unset/disabled. autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"], }, allowCommands: ["canvas.navigate"], denyCommands: ["system.run"], }, tools: { - // 额外的 /tools/invoke HTTP 拒绝项 + // Additional /tools/invoke HTTP denies deny: ["browser"], - // 从默认 HTTP 拒绝列表中移除工具 + // Remove tools from the default HTTP deny list allow: ["gateway"], }, push: { @@ -389,55 +388,55 @@ x-i18n: } ``` - + -- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关拒绝启动。 -- `port`：用于 WS + HTTP 的单个复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 +- `port`：WS + HTTP 共用的单个复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 -- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` 绑定会在容器内的 `127.0.0.1` 上监听。使用 Docker 桥接网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关不可访问。使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 并使用 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **认证**：默认必需。非 loopback 绑定需要 Gateway 网关认证。实际中，这意味着共享令牌/密码，或带有 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认生成令牌。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。两者都配置且未设置 mode 时，启动以及服务安装/修复流程会失败。 +- **旧版绑定别名**：在 `gateway.bind` 中使用绑定模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 注意事项**：默认的 `loopback` 绑定会监听容器内的 `127.0.0.1`。使用 Docker 桥接网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此无法访问 Gateway 网关。使用 `--network host`，或设置 `bind: "lan"`（或使用 `bind: "custom"` 并设置 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认必需。非 loopback 绑定需要 Gateway 网关认证。实际含义是需要共享令牌/密码，或使用带身份感知能力的反向代理并设置 `gateway.auth.mode: "trusted-proxy"`。新手引导向导默认生成令牌。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。两者都已配置且未设置模式时，启动以及服务安装/修复流程会失败。 - `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的 local loopback 设置；新手引导提示有意不提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将浏览器/用户认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)）。默认情况下，此模式预期使用**非 loopback** 代理来源；同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。内部同主机调用方可以使用 `gateway.auth.password` 作为本地直连回退；`gateway.auth.token` 仍然与 trusted-proxy 模式互斥。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份标头可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头认证；它们改用 Gateway 网关的普通 HTTP 认证模式。此无令牌流程假定 Gateway 网关主机受信任。当 `tailscale.mode = "serve"` 时默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域应用（shared-secret 和 device-token 会独立跟踪）。被阻止的尝试返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，相同 `{scope, clientIp}` 的失败尝试会在写入失败记录前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求触发限流器，而不是两者都作为普通不匹配竞争通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意也要限流 localhost 流量时（用于测试设置或严格代理部署），请设置为 `false`。 -- 来自浏览器 Origin 的 WS 认证尝试始终会被限流，并禁用 loopback 豁免（针对基于浏览器的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些来自浏览器 Origin 的锁定会按规范化后的 `Origin` +- `gateway.auth.mode: "trusted-proxy"`：将浏览器/用户认证委托给带身份感知能力的反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)）。默认情况下，此模式期望代理来源为 **非 loopback**；同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。内部同主机调用方可以使用 `gateway.auth.password` 作为本地直连回退；`gateway.auth.token` 仍然与 trusted-proxy 模式互斥。 +- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份标头可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头认证；它们改为遵循 Gateway 网关的普通 HTTP 认证模式。此无令牌流程假定 Gateway 网关主机可信。当 `tailscale.mode = "serve"` 时默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限制器。按客户端 IP 和认证作用域应用（shared-secret 和 device-token 会独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败之前串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求上触发限制器，而不是两个请求都以普通不匹配的方式竞争通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；当你有意也要限制 localhost 流量时（用于测试设置或严格代理部署），请设置为 `false`。 +- 浏览器来源的 WS 认证尝试始终会被限流，并禁用 loopback 豁免（针对基于浏览器的 localhost 暴力破解提供纵深防御）。 +- 在 loopback 上，这些浏览器来源锁定会按规范化后的 `Origin` 值隔离，因此来自一个 localhost 来源的重复失败不会自动 锁定另一个来源。 - `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开，需要认证）。 -- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器 Origin 允许列表。当预期浏览器客户端来自非 loopback 来源时必需。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，启用 Host 标头 Origin 回退，适用于有意依赖 Host 标头 Origin 策略的部署。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时必需。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，启用 Host 标头来源回退，用于有意依赖 Host 标头来源策略的部署。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 - `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境中的 - 应急覆盖，允许明文 `ws://` 连接到受信任的私有网络 - IP；明文默认仍仅限 loopback。没有等价的 `openclaw.json` - 配置，且浏览器私有网络配置，例如 - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`，不会影响 Gateway 网关 + break-glass 覆盖开关，允许对受信任的私有网络 + IP 使用明文 `ws://`；明文默认仍仅限 loopback。没有等效的 `openclaw.json` + 配置，并且浏览器私有网络配置（例如 + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`）不会影响 Gateway 网关 WebSocket 客户端。 -- `gateway.remote.token` / `.password` 是远程客户端凭据字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：外部 APNs 中继的基础 HTTPS URL，供官方/TestFlight iOS 构建在向 Gateway 网关发布中继支持的注册后使用。此 URL 必须与编译进 iOS 构建的中继 URL 匹配。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到中继的发送超时时间，单位毫秒。默认值为 `10000`。 -- 中继支持的注册会委托给特定 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并将注册作用域的发送授权转发给 Gateway 网关。另一个 Gateway 网关无法复用该已存储的注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述中继配置的临时环境覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅开发用途的应急开关，用于 loopback HTTP 中继 URL。生产中继 URL 应保持使用 HTTPS。 -- `gateway.handshakeTimeoutMs`：认证前 Gateway 网关 WebSocket 握手超时时间，单位毫秒。默认值：`15000`。设置 `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 时优先使用它。对于负载较高或低功耗的主机，如果本地客户端可能在启动预热尚未稳定时连接，请增大此值。 -- `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。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**使 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。 -- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关接受 `X-Real-IP`。默认值为 `false`，以保持失败即关闭行为。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 +- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建将中继支持的注册发布到 Gateway 网关后，外部 APNs 中继使用的基础 HTTPS URL。此 URL 必须与编译进 iOS 构建的中继 URL 匹配。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到中继的发送超时时间，单位为毫秒。默认值为 `10000`。 +- 中继支持的注册会委托给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并将注册作用域的发送授权转发给 Gateway 网关。另一个 Gateway 网关无法复用该已存储的注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述中继配置的临时环境变量覆盖。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发使用的逃生口，用于 loopback HTTP 中继 URL。生产中继 URL 应保持使用 HTTPS。 +- `gateway.handshakeTimeoutMs`：认证前 Gateway 网关 WebSocket 握手超时时间，单位为毫秒。默认值：`15000`。设置后，`OPENCLAW_HANDSHAKE_TIMEOUT_MS` 优先。当本地客户端可以连接但启动预热仍在稳定中的高负载或低性能主机上，请增大此值。 +- `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.*` 作为回退。 +- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 且未解析，解析会失败关闭（不会用远程回退来掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 条件。 +- `allowRealIpFallback`：当为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现失败关闭行为。 - `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准未请求作用域的首次节点设备配对。未设置时禁用。这不会自动批准操作者/浏览器/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和平台允许列表评估之后，对已声明节点命令应用的全局允许/拒绝规则。使用 `allowCommands` 选择启用危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式允许原本会包含某个命令，`denyCommands` 也会移除该命令。节点更改其已声明命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。 -- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。 -- `gateway.tools.allow`：从默认 HTTP 拒绝列表移除的工具名称。 +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和平台允许列表评估后，对已声明节点命令进行全局允许/拒绝整形。使用 `allowCommands` 选择加入危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式允许本来会包含某个命令，`denyCommands` 也会移除它。节点更改其已声明命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。 +- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 阻止的额外工具名称（扩展默认拒绝列表）。 +- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。 @@ -450,7 +449,7 @@ x-i18n: - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` 空允许列表会被视为未设置；使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 获取。 + 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 禁用 URL 获取。 - 可选响应加固标头： - `gateway.http.securityHeaders.strictTransportSecurity`（仅为你控制的 HTTPS 来源设置；参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） @@ -485,10 +484,10 @@ openclaw gateway --port 19001 ``` - `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。 -- `autoGenerate`：未配置显式文件时，自动生成本地自签名证书/密钥对；仅限本地/开发使用。 +- `autoGenerate`：在未配置显式文件时自动生成本地自签名证书/密钥对；仅用于本地/开发。 - `certPath`：TLS 证书文件的文件系统路径。 - `keyPath`：TLS 私钥文件的文件系统路径；保持权限受限。 -- `caPath`：用于客户端验证或自定义信任链的可选 CA 捆绑包路径。 +- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 ### `gateway.reload` @@ -498,19 +497,19 @@ openclaw gateway --port 19001 reload: { mode: "hybrid", // off | restart | hot | hybrid debounceMs: 500, - deferralTimeoutMs: 0, + deferralTimeoutMs: 300000, }, }, } ``` -- `mode`：控制配置编辑在运行时如何应用。 +- `mode`：控制运行时如何应用配置编辑。 - `"off"`：忽略实时编辑；更改需要显式重启。 - - `"restart"`：配置更改时始终重启 Gateway 网关进程。 - - `"hot"`：在进程内应用更改，无需重启。 - - `"hybrid"`（默认）：先尝试热重载；如果需要则回退到重启。 -- `debounceMs`：应用配置更改前的 debounce 窗口，单位 ms（非负整数）。 -- `deferralTimeoutMs`：可选的最大等待时间，单位 ms，用于在强制重启前等待进行中的操作。省略或设置为 `0` 表示无限期等待，并定期记录仍在等待的警告。 + - `"restart"`：配置变更时始终重启 Gateway 网关进程。 + - `"hot"`：在进程内应用更改，不重启。 + - `"hybrid"`（默认）：先尝试热重载；必要时回退到重启。 +- `debounceMs`：应用配置更改前的防抖窗口，单位为毫秒（非负整数）。 +- `deferralTimeoutMs`：可选的最大等待时间，单位为毫秒，用于在强制重启前等待进行中的操作。省略它会使用默认的有界等待（`300000`）；设置为 `0` 可无限期等待，并定期记录仍有待处理操作的警告。 --- @@ -550,44 +549,44 @@ openclaw gateway --port 19001 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 查询字符串钩子令牌会被拒绝。 -验证和安全注意事项： +验证和安全说明： -- `hooks.enabled=true` 需要非空的 `hooks.token`。 +- `hooks.enabled=true` 要求 `hooks.token` 非空。 - `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关令牌会被拒绝。 - `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 - 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该选择加入。 +- 如果某个映射或预设使用模板化的 `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` 解析 - - 模板渲染的映射 `sessionKey` 值会被视为外部提供，也需要 `hooks.allowRequestSessionKey=true`。 + - 模板渲染的映射 `sessionKey` 值会被视为外部提供，也要求 `hooks.allowRequestSessionKey=true`。 - `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 匹配通用路径的负载字段。 -- `{{messages[0].subject}}` 这类模板会从负载中读取。 -- `transform` 可以指向返回钩子操作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 +- `match.source` 匹配通用路径的载荷字段。 +- 像 `{{messages[0].subject}}` 这样的模板会从载荷中读取。 +- `transform` 可以指向一个返回钩子操作的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且保留在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。 - `agentId` 路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 拒绝全部）。 - `defaultSessionKey`：用于没有显式 `sessionKey` 的钩子智能体运行的可选固定会话键。 -- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。 -- `allowedSessionKeyPrefixes`：用于显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化的 `sessionKey` 时，它就变为必需。 +- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化 `sessionKey` 时，它会变为必需项。 - `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 -- `model` 会覆盖此钩子运行的 LLM（如果设置了模型目录，则必须被允许）。 +- `model` 会覆盖此钩子运行使用的 LLM（如果已设置模型目录，则必须允许该模型）。 ### Gmail 集成 - 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 -- 如果你保留这种按消息路由，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 -- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该预设，而不是使用模板化默认值。 +- 如果保留这种按消息路由，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 +- 如果需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该预设，而不是使用模板化默认值。 ```json5 { @@ -610,12 +609,12 @@ openclaw gateway --port 19001 } ``` -- Gateway 网关会在配置后于启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 -- 不要在 Gateway 网关旁边单独运行 `gog gmail watch serve`。 +- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 +- 不要在 Gateway 网关旁边另外运行一个 `gog gmail watch serve`。 --- -## Canvas host +## Canvas 主机 ```json5 { @@ -627,16 +626,16 @@ 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 绑定：canvas 路由需要 Gateway 网关认证（令牌/密码/受信任代理），与其他 Gateway 网关 HTTP 表面相同。 -- Node WebViews 通常不会发送认证标头；节点配对并连接后，Gateway 网关会通告用于 canvas/A2UI 访问的节点作用域 capability URL。 -- Capability URL 绑定到活动节点 WS 会话，并会快速过期。不使用基于 IP 的回退。 -- 将实时重载客户端注入到提供的 HTML 中。 -- 为空时自动创建入门 `index.html`。 -- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 +- 仅本地：保持 `gateway.bind: "loopback"`（默认）。 +- 非 loopback 绑定：canvas 路由需要 Gateway 网关身份验证（令牌/密码/受信代理），与其他 Gateway 网关 HTTP 表面相同。 +- Node WebViews 通常不会发送身份验证标头；节点完成配对并连接后，Gateway 网关会发布节点作用域的能力 URL，用于访问 canvas/A2UI。 +- 能力 URL 绑定到活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 +- 将实时重载客户端注入到提供服务的 HTML 中。 +- 为空时自动创建起始 `index.html`。 +- 还会在 `/__openclaw__/a2ui/` 提供 A2UI。 - 更改需要重启 Gateway 网关。 - 对于大型目录或 `EMFILE` 错误，请禁用实时重载。 @@ -656,7 +655,7 @@ openclaw gateway --port 19001 } ``` -- `minimal`（默认值）：从 TXT 记录中省略 `cliPath` + `sshPort`。 +- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。 - `full`：包含 `cliPath` + `sshPort`。 - 当系统主机名是有效 DNS 标签时，主机名默认使用系统主机名，否则回退到 `openclaw`。可用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 @@ -670,7 +669,7 @@ openclaw gateway --port 19001 } ``` -在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale 拆分 DNS。 +在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 设置：`openclaw dns setup --apply`。 @@ -695,14 +694,14 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境变量缺少该键时，才会应用内联环境变量。 -- `.env` 文件：CWD `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 -- `shellEnv`：从你的登录 shell profile 中导入缺失的预期键名。 -- 查看 [环境](/zh-CN/help/environment) 了解完整优先级。 +- 仅当进程环境缺少该键时，内联环境变量才会被应用。 +- `.env` 文件：CWD 的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 +- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。 +- 完整优先级见 [环境](/zh-CN/help/environment)。 ### 环境变量替换 -在任意配置字符串中用 `${VAR_NAME}` 引用环境变量： +在任何配置字符串中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -712,20 +711,20 @@ openclaw gateway --port 19001 } ``` -- 只匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失或为空的变量会在配置加载时报错。 -- 用 `$${VAR}` 转义，以表示字面量 `${VAR}`。 -- 可与 `$include` 一起使用。 +- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 +- 缺失或为空的变量会在配置加载时抛出错误。 +- 使用 `$${VAR}` 转义为字面量 `${VAR}`。 +- 可与 `$include` 配合使用。 --- ## 密钥 -密钥引用是增量支持的：明文值仍然可用。 +密钥引用是增量式的：明文值仍然可用。 ### `SecretRef` -使用一种对象形态： +使用一种对象形状： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -734,16 +733,16 @@ openclaw gateway --port 19001 验证： - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` -- `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: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"` 的 id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） +- `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- `source: "exec"` 的 id 不能包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝） -### 支持的凭据范围 +### 支持的凭证范围 -- 规范矩阵：[SecretRef 凭据范围](/zh-CN/reference/secretref-credential-surface) -- `secrets apply` 以支持的 `openclaw.json` 凭据路径为目标。 -- `auth-profiles.json` 引用会包含在运行时解析和审计覆盖范围中。 +- 规范矩阵：[SecretRef 凭证范围](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。 +- `auth-profiles.json` 引用包含在运行时解析和审计覆盖范围内。 ### 密钥提供商配置 @@ -775,18 +774,18 @@ openclaw gateway --port 19001 说明： -- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。 -- 当 Windows ACL 验证不可用时，file 和 exec 提供商路径会失败关闭。仅对无法验证的可信路径设置 `allowInsecurePath: true`。 -- `exec` 提供商要求绝对 `command` 路径，并在 stdin/stdout 上使用协议载荷。 -- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可在验证解析后的目标路径时允许符号链接路径。 +- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- 当 Windows ACL 验证不可用时，文件和 exec 提供商路径会失败关闭。仅对可信但无法验证的路径设置 `allowInsecurePath: true`。 +- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议载荷。 +- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证解析后的目标路径。 - 如果配置了 `trustedDirs`，可信目录检查会应用于解析后的目标路径。 -- `exec` 子环境默认是最小环境；请用 `passEnv` 显式传递所需变量。 -- 密钥引用会在激活时解析为内存快照，之后请求路径只读取该快照。 -- 激活期间会应用活跃范围过滤：已启用范围上的未解析引用会导致启动/重新加载失败，而非活跃范围会被跳过并附带诊断信息。 +- 默认情况下，`exec` 子进程环境是最小化的；请使用 `passEnv` 显式传递所需变量。 +- 密钥引用会在激活时解析为内存中的快照，之后请求路径只读取该快照。 +- 激活期间会应用活跃范围过滤：启用范围上的未解析引用会导致启动或重新加载失败，而非活跃范围会被跳过并给出诊断信息。 --- -## 凭证存储 +## 身份验证存储 ```json5 { @@ -804,13 +803,13 @@ openclaw gateway --port 19001 } ``` -- 每个智能体的 profile 存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持用于静态凭据模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- 旧版扁平 `auth-profiles.json` 映射（例如 `{ "provider": { "apiKey": "..." } }`）不是运行时格式；`openclaw doctor --fix` 会将它们重写为规范的 `provider:default` API-key profiles，并创建 `.legacy-flat.*.bak` 备份。 -- OAuth 模式 profiles（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支撑的 auth-profile 凭据。 -- 静态运行时凭据来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会清除它们。 +- 每个智能体的配置文件存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 支持静态凭证模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- 旧版扁平 `auth-profiles.json` 映射（例如 `{ "provider": { "apiKey": "..." } }`）不是运行时格式；`openclaw doctor --fix` 会将其重写为规范的 `provider:default` API key 配置文件，并创建 `.legacy-flat.*.bak` 备份。 +- OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的身份验证配置文件凭证。 +- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会将其清除。 - 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。 -- 查看 [OAuth](/zh-CN/concepts/oauth)。 +- 见 [OAuth](/zh-CN/concepts/oauth)。 - 密钥运行时行为和 `audit/configure/apply` 工具：[密钥管理](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -833,15 +832,15 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`：当 profile 因确切的账单/额度不足错误失败时，以小时计的基础退避（默认：`5`）。即使在 `401`/`403` 响应上，明确的账单文本仍可能落到这里，但提供商特定的文本匹配器仍限定在拥有它们的提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或组织/工作区支出上限消息会留在 `rate_limit` 路径中。 -- `billingBackoffHoursByProvider`：可选的按提供商覆盖账单退避小时数。 -- `billingMaxHours`：账单退避指数增长的小时上限（默认：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟上限（默认：`60`）。 -- `failureWindowHours`：用于退避计数器的滚动窗口小时数（默认：`24`）。 -- `overloadedProfileRotations`：在切换到模型 fallback 之前，针对过载错误允许的同提供商 auth-profile 轮换最大次数（默认：`1`）。`ModelNotReadyException` 等提供商繁忙形态会落到这里。 -- `overloadedBackoffMs`：重试过载提供商/profile 轮换前的固定延迟（默认：`0`）。 -- `rateLimitedProfileRotations`：在切换到模型 fallback 之前，针对限流错误允许的同提供商 auth-profile 轮换最大次数（默认：`1`）。该限流桶包括提供商形态文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 +- `billingBackoffHours`：当配置文件因确认为计费或信用额度不足错误而失败时，以小时为单位的基础退避（默认值：`5`）。即使在 `401`/`403` 响应中，明确的计费文本仍可能归入这里，但特定提供商的文本匹配器仍限定在其所属的提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或组织/工作区支出上限消息会保留在 `rate_limit` 路径中。 +- `billingBackoffHoursByProvider`：可选的按提供商覆盖的计费退避小时数。 +- `billingMaxHours`：计费退避指数增长的小时上限（默认值：`24`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的分钟级基础退避（默认值：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟上限（默认值：`60`）。 +- `failureWindowHours`：用于退避计数器的滚动窗口小时数（默认值：`24`）。 +- `overloadedProfileRotations`：在切换到模型回退之前，过载错误允许的最大同提供商身份验证配置文件轮换次数（默认值：`1`）。诸如 `ModelNotReadyException` 这样的提供商繁忙形态会归入这里。 +- `overloadedBackoffMs`：重试过载的提供商/配置文件轮换之前的固定延迟（默认值：`0`）。 +- `rateLimitedProfileRotations`：在切换到模型回退之前，速率限制错误允许的最大同提供商身份验证配置文件轮换次数（默认值：`1`）。该速率限制桶包含提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -863,8 +862,8 @@ openclaw gateway --port 19001 - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 - 设置 `logging.file` 以使用稳定路径。 - 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：轮转前活动日志文件的最大字节数（正整数；默认：`104857600` = 100 MB）。OpenClaw 会在活动文件旁最多保留五个带编号的归档文件。 -- `redactSensitive` / `redactPatterns`：对控制台输出、文件日志、OTLP 日志记录和持久化会话转录文本进行尽力而为的遮蔽。`redactSensitive: "off"` 只会禁用这项通用日志/转录策略；UI/工具/诊断安全界面在发出内容前仍会遮蔽密钥。 +- `maxFileBytes`：轮转前当前活动日志文件的最大字节数（正整数；默认：`104857600` = 100 MB）。OpenClaw 会在活动文件旁最多保留五个编号归档。 +- `redactSensitive` / `redactPatterns`：对控制台输出、文件日志、OTLP 日志记录以及持久化的会话转录文本进行尽力遮蔽。`redactSensitive: "off"` 只会禁用这项通用日志/转录策略；UI/工具/诊断安全表面在发出前仍会遮蔽密钥。 --- @@ -912,25 +911,25 @@ openclaw gateway --port 19001 } ``` -- `enabled`：检测输出的主开关（默认：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 这类通配符）。 -- `stuckSessionWarnMs`：当会话保持处理状态时，发出卡住会话警告的时长阈值，单位为毫秒。 -- `otel.enabled`：启用 OpenTelemetry 导出流水线（默认：`false`）。完整配置、信号目录和隐私模型请参阅 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 +- `enabled`：仪表化输出的总开关（默认：`true`）。 +- `flags`：启用定向日志输出的标志字符串数组（支持类似 `"telegram.*"` 或 `"*"` 的通配符）。 +- `stuckSessionWarnMs`：当会话保持处理状态时，发出卡住会话警告的毫秒年龄阈值。 +- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。完整配置、信号目录和隐私模型请参阅 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 - `otel.endpoint`：用于 OTel 导出的收集器 URL。 -- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的特定信号 OTLP 端点。设置后，它们只会覆盖该信号的 `otel.endpoint`。 +- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的按信号划分 OTLP 端点。设置后，它们只会覆盖该信号的 `otel.endpoint`。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 - `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据标头。 - `otel.serviceName`：资源属性的服务名称。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 -- `otel.sampleRate`：trace 采样率 `0`–`1`。 -- `otel.flushIntervalMs`：周期性遥测刷新间隔，单位为毫秒。 -- `otel.captureContent`：选择加入的 OTEL span 属性原始内容采集。默认关闭。布尔值 `true` 会采集非系统消息/工具内容；对象形式可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于最新实验性 GenAI span 提供商属性的环境开关。默认情况下，span 保留旧版 `gen_ai.system` 属性以实现兼容；GenAI metrics 使用有界语义属性。 -- `OPENCLAW_OTEL_PRELOADED=1`：适用于已注册全局 OpenTelemetry SDK 的宿主的环境开关。随后 OpenClaw 会跳过插件自有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。 -- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：当匹配的配置键未设置时使用的特定信号端点环境变量。 -- `cacheTrace.enabled`：为嵌入式运行记录缓存 trace 快照（默认：`false`）。 -- `cacheTrace.filePath`：缓存 trace JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存 trace 输出中包含哪些内容（全部默认：`true`）。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用追踪、指标或日志导出。 +- `otel.sampleRate`：追踪采样率 `0`–`1`。 +- `otel.flushIntervalMs`：周期性遥测刷新的间隔，单位为毫秒。 +- `otel.captureContent`：选择启用 OTEL span 属性的原始内容捕获。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：启用最新实验性 GenAI span 提供商属性的环境开关。默认情况下，为兼容性，span 保留旧版 `gen_ai.system` 属性；GenAI 指标使用有界语义属性。 +- `OPENCLAW_OTEL_PRELOADED=1`：用于已注册全局 OpenTelemetry SDK 的主机的环境开关。随后 OpenClaw 会跳过插件拥有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。 +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：当匹配的配置键未设置时使用的按信号划分端点环境变量。 +- `cacheTrace.enabled`：为嵌入式运行记录缓存追踪快照（默认：`false`）。 +- `cacheTrace.filePath`：缓存追踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含的内容（全部默认：`true`）。 --- @@ -952,12 +951,12 @@ openclaw gateway --port 19001 } ``` -- `channel`：npm/git 安装使用的发布渠道，即 `"stable"`、`"beta"` 或 `"dev"`。 +- `channel`：npm/git 安装的发布渠道 — `"stable"`、`"beta"` 或 `"dev"`。 - `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。 -- `auto.enabled`：为软件包安装启用后台自动更新（默认：`false`）。 -- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟小时数（默认：`6`；最大：`168`）。 -- `auto.stableJitterHours`：stable 渠道发布扩散窗口的额外小时数（默认：`12`；最大：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道检查的运行频率，单位为小时（默认：`1`；最大：`24`）。 +- `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 +- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟小时数（默认：`6`；最大：`168`）。 +- `auto.stableJitterHours`：稳定渠道发布扩散的额外窗口小时数（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：测试版渠道检查运行频率，单位为小时（默认：`1`；最大：`24`）。 --- @@ -990,22 +989,22 @@ openclaw gateway --port 19001 } ``` -- `enabled`：全局 ACP 功能开关（默认：`true`；设置为 `false` 可隐藏 ACP 分发和生成入口）。 -- `dispatch.enabled`：ACP 会话回合分发的独立开关（默认：`true`）。设置为 `false` 可保留 ACP 命令可用，同时阻止执行。 +- `enabled`：全局 ACP 功能门控（默认：`true`；设为 `false` 可隐藏 ACP 分发和生成入口）。 +- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 - `backend`：默认 ACP 运行时后端 ID（必须匹配已注册的 ACP 运行时插件）。 - 如果设置了 `plugins.allow`，请包含后端插件 ID（例如 `acpx`），否则内置默认插件将不会加载。 -- `defaultAgent`：当生成未指定显式目标时使用的后备 ACP 目标智能体 ID。 + 如果设置了 `plugins.allow`，请包含后端插件 ID（例如 `acpx`），否则内置默认插件不会加载。 +- `defaultAgent`：当生成未指定显式目标时的后备 ACP 目标智能体 ID。 - `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 允许列表；为空表示没有额外限制。 -- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。 +- `maxConcurrentSessions`：最大并发活动 ACP 会话数。 - `stream.coalesceIdleMs`：流式文本的空闲刷新窗口，单位为毫秒。 - `stream.maxChunkChars`：拆分流式块投影前的最大块大小。 -- `stream.repeatSuppression`：抑制每个回合中重复的状态/工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 会增量流式传输；`"final_only"` 会缓冲到回合终止事件。 -- `stream.hiddenBoundarySeparator`：隐藏工具事件后、可见文本前的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 回合投影的最大助手输出字符数。 -- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。 +- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认：`true`）。 +- `stream.deliveryMode`：`"live"` 增量流式传输；`"final_only"` 缓冲到轮次终止事件为止。 +- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。 +- `stream.maxOutputChars`：每个 ACP 轮次投影的最大助手输出字符数。 +- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行的最大字符数。 - `stream.tagVisibility`：标签名称到流式事件布尔可见性覆盖的记录。 -- `runtime.ttlMinutes`：ACP 会话工作进程符合清理条件前的空闲 TTL，单位为分钟。 +- `runtime.ttlMinutes`：ACP 会话 worker 符合清理条件前的空闲 TTL，单位为分钟。 - `runtime.installCommand`：引导 ACP 运行时环境时要运行的可选安装命令。 --- @@ -1025,7 +1024,7 @@ openclaw gateway --port 19001 - `cli.banner.taglineMode` 控制横幅标语样式： - `"random"`（默认）：轮换的趣味/季节性标语。 - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：无标语文本（仍显示横幅标题/版本）。 + - `"off"`：不显示标语文本（横幅标题/版本仍会显示）。 - 要隐藏整个横幅（不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -1056,9 +1055,9 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 ## Bridge（旧版，已移除） -当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再属于配置架构的一部分（移除前验证会失败；`openclaw doctor --fix` 可以剔除未知键）。 +当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再是配置架构的一部分（在移除前验证会失败；`openclaw doctor --fix` 可以剥离未知键）。 - + ```json { @@ -1096,11 +1095,11 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- `sessionRetention`：已完成的隔离 cron 运行会话在从 `sessions.json` 中修剪前保留多久。也控制已删除 cron 转录归档的清理。默认：`24h`；设置为 `false` 可禁用。 -- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在修剪前的最大大小。默认：`2_000_000` 字节。 +- `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 令牌；如果省略，则不会发送认证标头。 -- `webhook`：已弃用的旧版后备 webhook URL（http/https），仅用于仍带有 `notify: true` 的已存储任务。 +- `webhookToken`：用于 cron webhook POST 递送（`delivery.mode = "webhook"`）的 bearer token；如果省略，则不会发送身份验证标头。 +- `webhook`：已弃用的旧版后备 webhook URL（http/https），仅用于仍包含 `notify: true` 的已存储任务。 ### `cron.retry` @@ -1118,7 +1117,7 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 - `maxAttempts`：一次性任务在瞬时错误上的最大重试次数（默认：`3`；范围：`0`–`10`）。 - `backoffMs`：每次重试尝试的退避延迟数组，单位为毫秒（默认：`[30000, 60000, 300000]`；1–10 个条目）。 -- `retryOn`：会触发重试的错误类型，即 `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则会重试所有瞬时类型。 +- `retryOn`：触发重试的错误类型 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则重试所有瞬时类型。 仅适用于一次性 cron 任务。周期性任务使用单独的失败处理。 @@ -1139,12 +1138,12 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- `enabled`：启用 cron 任务的失败提醒（默认：`false`）。 -- `after`：触发提醒前的连续失败次数（正整数，最小：`1`）。 -- `cooldownMs`：同一任务重复提醒之间的最小毫秒数（非负整数）。 -- `includeSkipped`：将连续跳过的运行计入提醒阈值（默认：`false`）。跳过的运行会单独跟踪，不会影响执行错误退避。 -- `mode`：投递模式，即 `"announce"` 通过渠道消息发送；`"webhook"` 发布到已配置的 webhook。 -- `accountId`：用于限定提醒投递范围的可选账号或渠道 ID。 +- `enabled`：启用 cron 任务失败警报（默认：`false`）。 +- `after`：触发警报前的连续失败次数（正整数，最小：`1`）。 +- `cooldownMs`：同一任务重复警报之间的最小毫秒数（非负整数）。 +- `includeSkipped`：将连续跳过的运行计入警报阈值（默认：`false`）。跳过的运行会单独跟踪，不影响执行错误退避。 +- `mode`：递送模式 — `"announce"` 通过渠道消息发送；`"webhook"` 发布到配置的 webhook。 +- `accountId`：用于限定警报递送范围的可选账号或渠道 ID。 ### `cron.failureDestination` @@ -1161,16 +1160,16 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- 所有作业的 cron 失败通知默认目标。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认为 `"announce"`。 -- `channel`：用于 `announce` 投递的渠道覆盖项。`"last"` 会复用上次已知的投递渠道。 -- `to`：显式 `announce` 目标或 webhook URL。webhook 模式必填。 +- 所有任务中 cron 失败通知的默认目标位置。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。 +- `channel`：announce 投递的渠道覆盖项。`"last"` 会复用最后已知的投递渠道。 +- `to`：显式 announce 目标或 webhook URL。webhook 模式必需。 - `accountId`：可选的投递账号覆盖项。 -- 单个作业的 `delivery.failureDestination` 会覆盖此全局默认值。 -- 当既未设置全局失败目标，也未设置单个作业失败目标时，已经通过 `announce` 投递的作业会在失败时回退到该主 `announce` 目标。 -- 除非作业的主 `delivery.mode` 是 `"webhook"`，否则 `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 作业。 +- 每个任务的 `delivery.failureDestination` 会覆盖此全局默认值。 +- 当既没有设置全局失败目标位置，也没有设置每个任务的失败目标位置时，已通过 `announce` 投递的任务在失败时会回退到该主要 announce 目标。 +- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 任务，除非该任务的主要 `delivery.mode` 是 `"webhook"`。 -参见 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 +请参阅 [Cron 任务](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 --- @@ -1178,34 +1177,34 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 在 `tools.media.models[].args` 中展开的模板占位符： -| 变量 | 描述 | -| ------------------ | ------------------------------------------------ | -| `{{Body}}` | 完整的入站消息正文 | -| `{{RawBody}}` | 原始正文（无历史/发送者包装） | -| `{{BodyStripped}}` | 去除群组提及后的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 ID | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 创建新会话时为 `"true"` | -| `{{MediaUrl}}` | 入站媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频转录 | -| `{{Prompt}}` | CLI 条目的已解析媒体提示词 | -| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力获取） | -| `{{GroupMembers}}` | 群组成员预览（尽力获取） | -| `{{SenderName}}` | 发送者显示名称（尽力获取） | -| `{{SenderE164}}` | 发送者电话号码（尽力获取） | -| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | +| 变量 | 描述 | +| ------------------ | ------------------------------------------------- | +| `{{Body}}` | 完整的入站消息正文 | +| `{{RawBody}}` | 原始正文（没有历史记录/发送者包装） | +| `{{BodyStripped}}` | 去除群组提及后的正文 | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 ID | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 创建新会话时为 `"true"` | +| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（图像/音频/文档/…） | +| `{{Transcript}}` | 音频转录文本 | +| `{{Prompt}}` | 为 CLI 条目解析后的媒体提示词 | +| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群组成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名称（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- -## 配置包含项（`$include`） +## 配置 include（`$include`） -将配置拆分到多个文件中： +将配置拆分到多个文件： ```json5 // ~/.openclaw/openclaw.json @@ -1221,13 +1220,13 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 **合并行为：** - 单个文件：替换包含它的对象。 -- 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在包含项之后合并（覆盖已包含的值）。 -- 嵌套包含：最多 10 层深。 -- 路径：相对于包含它的文件解析，但必须位于顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式仍解析到该边界内时才允许使用。 -- 仅更改由单文件包含支撑的一个顶层分区的 OpenClaw 所有写入，会透传写入该被包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。 -- 根包含项、包含数组，以及带同级覆盖项的包含项，对于 OpenClaw 所有写入是只读的；这些写入会失败关闭，而不是扁平化配置。 -- 错误：针对缺失文件、解析错误和循环包含提供清晰消息。 +- 文件数组：按顺序深度合并（后面的会覆盖前面的）。 +- 同级键：在 include 之后合并（覆盖包含的值）。 +- 嵌套 include：最多 10 层深度。 +- 路径：相对于包含文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。只有在仍解析到该边界内时，才允许绝对路径/`../` 形式。 +- OpenClaw 拥有的写入如果只更改一个由单文件 include 支持的顶层区段，会透传写入该被包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。 +- 根 include、include 数组，以及带同级覆盖项的 include 对 OpenClaw 拥有的写入是只读的；这些写入会封闭失败，而不是展平配置。 +- 错误：针对缺失文件、解析错误和循环 include 提供清晰消息。 ---