diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 19a703fe0..1c8ae4762 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -1,74 +1,74 @@ --- read_when: - 你需要精确的字段级配置语义或默认值 - - 你正在验证渠道、模型、Gateway 网关或工具的配置块 -summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键、默认值，以及指向专用子系统参考的链接 + - 你正在验证渠道、模型、Gateway 网关或工具配置块 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键、默认值，以及指向专用子系统参考文档的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-28T11:51:17Z" + generated_at: "2026-04-28T22:57:48Z" model: gpt-5.5 provider: openai - source_hash: a6123522ecc016e5dcbede9bfd215491dc04e5b94bce5fcff1b555c29f54ff1e + source_hash: ed99df1a7ec858e79380704e29d1a31e7b10f0429aa928d205503f7ea97187b8 source_path: gateway/configuration-reference.md workflow: 16 --- -核心配置参考，适用于 `~/.openclaw/openclaw.json`。有关面向任务的概览，请参阅[配置](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。有关面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。 -涵盖主要 OpenClaw 配置表面；当某个子系统有自己的更深入参考时，会链接到对应页面。渠道和插件拥有的命令目录，以及深层 memory/QMD 开关，位于各自页面，而不是本页。 +涵盖主要的 OpenClaw 配置表面；当某个子系统有自己的更深入参考时，会链接到对应页面。渠道和插件拥有的命令目录，以及深层 memory/QMD 开关，放在各自页面中，而不是本页。 代码事实来源： -- `openclaw config schema` 会打印用于校验和控制 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 表面验证配置文档基线哈希 -智能体查找路径：编辑前，使用 `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 配置 -- [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 会使用安全默认值。 +配置格式为 **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.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱） - `multiAgent.*`（多智能体路由和绑定） - `session.*`（会话生命周期、压缩、修剪） -- `messages.*`（消息投递、TTS、markdown 渲染） +- `messages.*`（消息投递、TTS、Markdown 渲染） - `talk.*`（Talk 模式） - - `talk.speechLocale`：可选的 BCP 47 区域设置 ID，用于 iOS/macOS 上的 Talk 语音识别 - - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`） + - `talk.speechLocale`：用于 iOS/macOS 上 Talk 语音识别的可选 BCP 47 locale 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` 根级还拥有全局模型目录行为。 +`models` 根节点还拥有全局模型目录行为。 ```json5 { @@ -80,17 +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 服务器定义位于 `mcp.servers` 下，并由嵌入式 Pi +由 OpenClaw 管理的 MCP server 定义位于 `mcp.servers` 下，并由嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、 -`show`、`set` 和 `unset` 命令会管理此块，且在配置编辑期间不会连接到 +`show`、`set` 和 `unset` 命令可在配置编辑期间管理此块，而不会连接到 目标服务器。 ```json5 @@ -115,18 +115,19 @@ x-i18n: } ``` -- `mcp.servers`：命名 stdio 或远程 MCP 服务器定义，供暴露已配置 MCP 工具的运行时使用。 +- `mcp.servers`：命名的 stdio 或远程 MCP server 定义，供暴露已配置 MCP 工具的运行时使用。 远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`； `type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和 `openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。 -- `mcp.sessionIdleTtlMs`：会话级内置 MCP 运行时的空闲 TTL。 - 一次性嵌入式运行会请求运行结束清理；此 TTL 是长生命周期会话和未来调用方的兜底。 -- `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时来热应用。 - 下一次工具发现/使用会根据新配置重新创建它们，因此被移除的 +- `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 @@ -153,13 +154,14 @@ x-i18n: } ``` -- `allowBundled`：可选的内置 Skills 允许列表（受管理/工作区 Skills 不受影响）。 -- `load.extraDirs`：额外的共享 Skill 根目录（最低优先级）。 -- `install.preferBrew`：为 true 时，如果 `brew` 可用，优先使用 Homebrew 安装器，然后再回退到其他安装器类型。 -- `install.nodeManager`：用于 `metadata.openclaw.install` +- `allowBundled`：可选 allowlist，仅适用于内置 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 对象）。 +- `entries..enabled: false` 会禁用某个 skill，即使它是内置/已安装的。 +- `entries..apiKey`：为声明主环境变量的 Skills 提供的便捷配置（明文字符串或 SecretRef 对象）。 --- @@ -188,42 +190,42 @@ x-i18n: ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex 包和 Claude 包，包括没有清单的 Claude 默认布局包。 +- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundle。 - **配置更改需要重启 Gateway 网关。** -- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便利字段（当插件支持时）。 +- `allow`：可选 allowlist（只加载列出的插件）。`deny` 优先。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（在插件支持时可用）。 - `plugins.entries..env`：插件作用域的环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：当为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会改动 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子和受支持包提供的钩子目录。 -- `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.` 下，并应由所属插件的清单 `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。 +- `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 基础 URL（默认：`https://api.firecrawl.dev`）。 - - `onlyMainContent`：仅从页面提取主要内容（默认：`true`）。 - - `maxAgeMs`：最大缓存时间，单位为毫秒（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时时间，单位为秒（默认：`60`）。 -- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 + - `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）设置。 - `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`：可选的 Dream Diary 子智能体模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；搭配 `allowedModels` 使用以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退。 +- `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 失败不会静默回退。 - 阶段策略和阈值是实现细节（不是面向用户的配置键）。 -- 完整内存配置位于[内存配置参考](/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 包插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些默认值作为经过清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活动内存插件 ID，或使用 `"none"` 禁用内存插件。 -- `plugins.slots.contextEngine`：选择活动 context engine 插件 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)。 --- @@ -274,30 +276,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` 明确配置例外。 -- 远程配置文件仅支持附加（禁用启动/停止/重置）。 -- `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，并且可以在所选主机上或通过已连接的浏览器节点附加。 +- 在严格模式下，使用 `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，并且可以附加到选定主机或通过已连接的浏览器节点附加。 - `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` ms 的正整数；无效配置值会被拒绝。 +- `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` 毫秒的正整数；无效的配置值会被拒绝。 - 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- `browser.executablePath` 和 `browser.profiles..executablePath` 都接受 `~` 和 `~/...`，表示在 Chromium 启动前展开为你的操作系统主目录。`existing-session` 配置文件中的每配置文件 `userDataDir` 也会进行波浪号展开。 -- 控制服务：仅 loopback（端口派生自 `gateway.port`，默认 `18791`）。 -- `extraArgs` 会向本地 Chromium 启动追加额外启动标志（例如 `--disable-gpu`、窗口大小设置或调试标志）。 +- `browser.executablePath` 和 `browser.profiles..executablePath` 都接受 `~` 和 `~/...`，用于在 Chromium 启动前表示你的 OS 主目录。`existing-session` 配置文件上的按配置文件 `userDataDir` 也会展开波浪号。 +- 控制服务：仅限 loopback（端口从 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会向本地 Chromium 启动附加额外启动标志（例如 `--disable-gpu`、窗口大小或调试标志）。 --- -## 界面 +## UI ```json5 { @@ -305,14 +307,14 @@ x-i18n: seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji、短文本、图片 URL 或 data URI }, }, } ``` -- `seamColor`：原生应用 UI 外框的强调色（Talk Mode 气泡色调等）。 -- `assistant`：Control UI 身份覆盖。回退到活动智能体身份。 +- `seamColor`：原生应用 UI 外壳的强调色（Talk Mode 气泡色调等）。 +- `assistant`：Control UI 身份覆盖。回退到当前活跃智能体身份。 --- @@ -327,8 +329,8 @@ x-i18n: auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -346,9 +348,9 @@ x-i18n: basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // 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 + // allowExternalEmbedUrls: false, // 危险：允许绝对外部 http(s) 嵌入 URL + // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必需 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header 源回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -359,20 +361,20 @@ x-i18n: // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // 可选。默认 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: { - // Additional /tools/invoke HTTP denies + // 额外的 /tools/invoke HTTP 拒绝项 deny: ["browser"], - // Remove tools from the default HTTP deny list + // 从默认 HTTP 拒绝列表中移除工具 allow: ["gateway"], }, push: { @@ -389,52 +391,53 @@ x-i18n: -- `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`。 -- **旧版绑定别名**：在 `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`。 -- 浏览器来源的 WS 凭证尝试始终会被节流，并禁用 loopback 豁免（针对基于浏览器的 localhost 暴力破解提供纵深防御）。 -- 在 loopback 上，这些浏览器来源的锁定会按规范化的 `Origin` - 值隔离，因此来自某个 localhost 来源的重复失败不会自动 - 锁定另一个不同来源。 -- `tailscale.mode`: `serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开，需要凭证）。 -- `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`: 客户端进程环境 - break-glass 覆盖，允许对可信私有网络 - IP 使用明文 `ws://`；明文默认仍仅限 loopback。没有等价的 `openclaw.json` - 配置，并且诸如 - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 之类的浏览器私有网络配置不会影响 Gateway 网关 +- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关拒绝启动。 +- `port`：用于 WS + HTTP 的单个复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 +- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 注意事项**：默认的 `loopback` 绑定会在容器内的 `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.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` + 值隔离，因此来自一个 localhost 来源的重复失败不会自动 + 锁定另一个来源。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开，需要认证）。 +- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器 Origin 允许列表。当预期浏览器客户端来自非 loopback 来源时必需。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，启用 Host 标头 Origin 回退，适用于有意依赖 Host 标头 Origin 策略的部署。 +- `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 网关 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.channelHealthCheckMinutes`: 渠道健康监控间隔，单位为分钟。设置为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`: 陈旧套接字阈值，单位为分钟。保持其大于或等于 `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 允许列表，用于在没有请求范围的情况下自动批准首次节点设备配对。未设置时禁用。它不会自动批准 operator/browser/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.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.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 拒绝列表移除的工具名称。 @@ -447,9 +450,9 @@ 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)） + - `gateway.http.securityHeaders.strictTransportSecurity`（仅为你控制的 HTTPS 来源设置；参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 @@ -481,11 +484,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: 在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。 -- `autoGenerate`: 在未配置显式文件时自动生成本地自签名证书/密钥对；仅用于本地/开发。 -- `certPath`: TLS 证书文件的文件系统路径。 -- `keyPath`: TLS 私钥文件的文件系统路径；保持权限受限。 -- `caPath`: 用于客户端验证或自定义信任链的可选 CA bundle 路径。 +- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。 +- `autoGenerate`：未配置显式文件时，自动生成本地自签名证书/密钥对；仅限本地/开发使用。 +- `certPath`：TLS 证书文件的文件系统路径。 +- `keyPath`：TLS 私钥文件的文件系统路径；保持权限受限。 +- `caPath`：用于客户端验证或自定义信任链的可选 CA 捆绑包路径。 ### `gateway.reload` @@ -501,13 +504,13 @@ openclaw gateway --port 19001 } ``` -- `mode`: 控制运行时如何应用配置编辑。 - - `"off"`: 忽略实时编辑；更改需要显式重启。 - - `"restart"`: 配置变更时始终重启 Gateway 网关进程。 - - `"hot"`: 在进程内应用更改，无需重启。 +- `mode`：控制配置编辑在运行时如何应用。 + - `"off"`：忽略实时编辑；更改需要显式重启。 + - `"restart"`：配置更改时始终重启 Gateway 网关进程。 + - `"hot"`：在进程内应用更改，无需重启。 - `"hybrid"`（默认）：先尝试热重载；如果需要则回退到重启。 -- `debounceMs`: 应用配置变更前的去抖窗口，单位为毫秒（非负整数）。 -- `deferralTimeoutMs`: 可选的最长等待时间，单位为毫秒，用于在强制重启前等待正在进行的操作。省略或设置为 `0` 表示无限期等待，并定期记录仍在等待的警告。 +- `debounceMs`：应用配置更改前的 debounce 窗口，单位 ms（非负整数）。 +- `deferralTimeoutMs`：可选的最大等待时间，单位 ms，用于在强制重启前等待进行中的操作。省略或设置为 `0` 表示无限期等待，并定期记录仍在等待的警告。 --- @@ -544,39 +547,39 @@ openclaw gateway --port 19001 } ``` -凭证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 +认证：`Authorization: Bearer ` 或 `x-openclaw-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}}` 这样的模板从载荷读取内容。 +- `match.source` 匹配通用路径的负载字段。 +- `{{messages[0].subject}}` 这类模板会从负载中读取。 - `transform` 可以指向返回钩子操作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且保留在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。 -- `agentId` 路由到特定智能体；未知 ID 回退到默认智能体。 + - `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 +- `agentId` 路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 拒绝全部）。 -- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的钩子智能体运行。 +- `defaultSessionKey`：用于没有显式 `sessionKey` 的钩子智能体运行的可选固定会话键。 - `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化的 `sessionKey` 时，它会变为必需项。 -- `deliver: true` 将最终回复发送到渠道；`channel` 默认为 `last`。 -- `model` 会覆盖此钩子运行使用的 LLM（如果设置了模型目录，则必须被允许）。 +- `allowedSessionKeyPrefixes`：用于显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化的 `sessionKey` 时，它就变为必需。 +- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 +- `model` 会覆盖此钩子运行的 LLM（如果设置了模型目录，则必须被允许）。 @@ -607,12 +610,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 主机 +## Canvas host ```json5 { @@ -624,15 +627,15 @@ 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 绑定：画布路由需要 Gateway 网关认证（令牌/密码/可信代理），与其他 Gateway 网关 HTTP 表面相同。 -- Node WebViews 通常不会发送认证标头；节点配对并连接后，Gateway 网关会公布节点作用域的能力 URL，用于访问画布/A2UI。 -- 能力 URL 绑定到活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 -- 将实时重载客户端注入到所提供的 HTML 中。 -- 为空时自动创建起始 `index.html`。 +- 仅限本地：保持 `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 网关。 - 对于大型目录或 `EMFILE` 错误，请禁用实时重载。 @@ -653,11 +656,11 @@ openclaw gateway --port 19001 } ``` -- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。 +- `minimal`（默认值）：从 TXT 记录中省略 `cliPath` + `sshPort`。 - `full`：包含 `cliPath` + `sshPort`。 - 当系统主机名是有效 DNS 标签时，主机名默认使用系统主机名，否则回退到 `openclaw`。可用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 -### 广域 (DNS-SD) +### 广域（DNS-SD） ```json5 { @@ -667,7 +670,7 @@ openclaw gateway --port 19001 } ``` -在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale 分割 DNS。 +在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale 拆分 DNS。 设置：`openclaw dns setup --apply`。 @@ -692,14 +695,14 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境缺少该键时，才会应用内联环境变量。 +- 仅当进程环境变量缺少该键时，才会应用内联环境变量。 - `.env` 文件：CWD `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 -- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。 -- 完整优先级见[环境](/zh-CN/help/environment)。 +- `shellEnv`：从你的登录 shell profile 中导入缺失的预期键名。 +- 查看 [环境](/zh-CN/help/environment) 了解完整优先级。 ### 环境变量替换 -在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： +在任意配置字符串中用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -710,37 +713,37 @@ openclaw gateway --port 19001 ``` - 只匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/空变量会在配置加载时报错。 -- 使用 `$${VAR}` 转义，以表示字面量 `${VAR}`。 -- 可与 `$include` 配合使用。 +- 缺失或为空的变量会在配置加载时报错。 +- 用 `$${VAR}` 转义，以表示字面量 `${VAR}`。 +- 可与 `$include` 一起使用。 --- ## 密钥 -密钥引用是增量式的：明文值仍然可用。 +密钥引用是增量支持的：明文值仍然可用。 ### `SecretRef` -使用一种对象形状： +使用一种对象形态： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } ``` -验证规则： +验证： - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` - `source: "env"` id 模式：`^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） +- `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 凭证作用面](/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` 引用会包含在运行时解析和审计覆盖范围中。 ### 密钥提供商配置 @@ -772,14 +775,14 @@ openclaw gateway --port 19001 说明： -- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式中，`id` 必须是 `"value"`）。 -- 当 Windows ACL 验证不可用时，file 和 exec 提供商路径会以关闭方式失败。仅对无法验证但可信的路径设置 `allowInsecurePath: true`。 -- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议载荷。 -- 默认情况下会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可在验证解析后的目标路径时允许符号链接路径。 -- 如果配置了 `trustedDirs`，可信目录检查会应用到解析后的目标路径。 -- 默认情况下，`exec` 子环境是最小化的；请使用 `passEnv` 显式传递所需变量。 -- 密钥引用会在激活时解析为内存快照，随后请求路径只读取该快照。 -- 激活期间会应用活跃作用面过滤：已启用作用面上的未解析引用会导致启动/重新加载失败，而非活跃作用面会被跳过并附带诊断信息。 +- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。 +- 当 Windows ACL 验证不可用时，file 和 exec 提供商路径会失败关闭。仅对无法验证的可信路径设置 `allowInsecurePath: true`。 +- `exec` 提供商要求绝对 `command` 路径，并在 stdin/stdout 上使用协议载荷。 +- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可在验证解析后的目标路径时允许符号链接路径。 +- 如果配置了 `trustedDirs`，可信目录检查会应用于解析后的目标路径。 +- `exec` 子环境默认是最小环境；请用 `passEnv` 显式传递所需变量。 +- 密钥引用会在激活时解析为内存快照，之后请求路径只读取该快照。 +- 激活期间会应用活跃范围过滤：已启用范围上的未解析引用会导致启动/重新加载失败，而非活跃范围会被跳过并附带诊断信息。 --- @@ -801,14 +804,14 @@ openclaw gateway --port 19001 } ``` -- 每个智能体的配置文件存储在 `/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-profile 凭证。 -- 静态运行时凭证来自内存中解析后的快照；发现旧版静态 `auth.json` 条目时会将其清理。 +- 每个智能体的 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` 条目时会清除它们。 - 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。 -- 见 [OAuth](/zh-CN/concepts/oauth)。 -- 密钥运行时行为以及 `audit/configure/apply` 工具：[密钥管理](/zh-CN/gateway/secrets)。 +- 查看 [OAuth](/zh-CN/concepts/oauth)。 +- 密钥运行时行为和 `audit/configure/apply` 工具：[密钥管理](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -830,15 +833,15 @@ openclaw gateway --port 19001 } ``` -- `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`：在切换到模型回退前，过载错误允许的同一提供商 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`。 +- `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`。 --- @@ -860,8 +863,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/工具/诊断安全界面在发出内容前仍会遮蔽密钥。 --- @@ -909,25 +912,25 @@ openclaw gateway --port 19001 } ``` -- `enabled`：仪表化输出的总开关（默认值：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 等通配符）。 -- `stuckSessionWarnMs`：当会话保持处理状态时，发出卡住会话警告的年龄阈值，单位为 ms。 -- `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.protocol`：`"http/protobuf"`（默认值）或 `"grpc"`。 +- `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`：周期性遥测刷新间隔，单位为 ms。 -- `otel.captureContent`：选择启用 OTEL span 属性的原始内容捕获。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于最新实验性 GenAI span provider 属性的环境开关。默认情况下，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.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`）。 --- @@ -949,12 +952,12 @@ openclaw gateway --port 19001 } ``` -- `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`）。 +- `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`）。 --- @@ -987,23 +990,23 @@ openclaw gateway --port 19001 } ``` -- `enabled`：全局 ACP 功能门控（默认值：`true`；设为 `false` 可隐藏 ACP 分派和生成入口）。 -- `dispatch.enabled`：ACP 会话回合分派的独立门控（默认值：`true`）。设为 `false` 可保留 ACP 命令可用，同时阻止执行。 -- `backend`：默认 ACP 运行时后端 id（必须匹配已注册的 ACP 运行时插件）。 - 如果设置了 `plugins.allow`，请包含后端插件 id（例如 `acpx`），否则内置默认插件不会加载。 -- `defaultAgent`：当生成未指定显式目标时使用的后备 ACP 目标智能体 id。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 许可列表；为空表示没有额外限制。 -- `maxConcurrentSessions`：同时活跃的 ACP 会话最大数量。 -- `stream.coalesceIdleMs`：流式文本的空闲刷新窗口，单位为 ms。 +- `enabled`：全局 ACP 功能开关（默认：`true`；设置为 `false` 可隐藏 ACP 分发和生成入口）。 +- `dispatch.enabled`：ACP 会话回合分发的独立开关（默认：`true`）。设置为 `false` 可保留 ACP 命令可用，同时阻止执行。 +- `backend`：默认 ACP 运行时后端 ID（必须匹配已注册的 ACP 运行时插件）。 + 如果设置了 `plugins.allow`，请包含后端插件 ID（例如 `acpx`），否则内置默认插件将不会加载。 +- `defaultAgent`：当生成未指定显式目标时使用的后备 ACP 目标智能体 ID。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 允许列表；为空表示没有额外限制。 +- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。 +- `stream.coalesceIdleMs`：流式文本的空闲刷新窗口，单位为毫秒。 - `stream.maxChunkChars`：拆分流式块投影前的最大块大小。 -- `stream.repeatSuppression`：按回合抑制重复的 Status/工具行（默认值：`true`）。 +- `stream.repeatSuppression`：抑制每个回合中重复的状态/工具行（默认：`true`）。 - `stream.deliveryMode`：`"live"` 会增量流式传输；`"final_only"` 会缓冲到回合终止事件。 -- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认值：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 回合投影的助手输出最大字符数。 -- `stream.maxSessionUpdateChars`：投影的 ACP Status/更新行最大字符数。 -- `stream.tagVisibility`：将标签名称映射到流式事件布尔可见性覆盖值的记录。 -- `runtime.ttlMinutes`：ACP 会话 worker 在可被清理前的空闲 TTL，单位为分钟。 -- `runtime.installCommand`：引导 ACP 运行时环境时可选执行的安装命令。 +- `stream.hiddenBoundarySeparator`：隐藏工具事件后、可见文本前的分隔符（默认：`"paragraph"`）。 +- `stream.maxOutputChars`：每个 ACP 回合投影的最大助手输出字符数。 +- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。 +- `stream.tagVisibility`：标签名称到流式事件布尔可见性覆盖的记录。 +- `runtime.ttlMinutes`：ACP 会话工作进程符合清理条件前的空闲 TTL，单位为分钟。 +- `runtime.installCommand`：引导 ACP 运行时环境时要运行的可选安装命令。 --- @@ -1020,10 +1023,10 @@ openclaw gateway --port 19001 ``` - `cli.banner.taglineMode` 控制横幅标语样式： - - `"random"`（默认值）：轮换显示有趣/季节性标语。 + - `"random"`（默认）：轮换的趣味/季节性标语。 - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍显示横幅标题/版本）。 -- 要隐藏整个横幅（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `"off"`：无标语文本（仍显示横幅标题/版本）。 +- 要隐藏整个横幅（不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -1053,9 +1056,9 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 ## Bridge（旧版，已移除） -当前构建不再包含 TCP Bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再是配置架构的一部分（验证会失败，直到移除；`openclaw doctor --fix` 可以剥离未知键）。 +当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再属于配置架构的一部分（移除前验证会失败；`openclaw doctor --fix` 可以剔除未知键）。 - + ```json { @@ -1093,11 +1096,11 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- `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` 的已存储任务。 +- `sessionRetention`：已完成的隔离 cron 运行会话在从 `sessions.json` 中修剪前保留多久。也控制已删除 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` 的已存储任务。 ### `cron.retry` @@ -1113,9 +1116,9 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- `maxAttempts`：一次性任务遇到瞬态错误时的最大重试次数（默认值：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试的退避延迟数组，单位为 ms（默认值：`[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 任务。周期性任务使用单独的失败处理。 @@ -1136,12 +1139,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` @@ -1158,16 +1161,16 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- 所有作业的 cron 失败通知的默认目标。 +- 所有作业的 cron 失败通知默认目标。 - `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认为 `"announce"`。 -- `channel`：用于 announce 投递的渠道覆盖项。`"last"` 会复用最后一次已知的投递渠道。 -- `to`：显式的 announce 目标或 webhook URL。webhook 模式必填。 -- `accountId`：用于投递的可选账号覆盖项。 -- 单个作业的 `delivery.failureDestination` 会覆盖这个全局默认值。 -- 当既没有设置全局失败目标，也没有设置单个作业失败目标时，已经通过 `announce` 投递的作业在失败时会回退到该主 announce 目标。 -- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 作业，除非该作业的主 `delivery.mode` 是 `"webhook"`。 +- `channel`：用于 `announce` 投递的渠道覆盖项。`"last"` 会复用上次已知的投递渠道。 +- `to`：显式 `announce` 目标或 webhook URL。webhook 模式必填。 +- `accountId`：可选的投递账号覆盖项。 +- 单个作业的 `delivery.failureDestination` 会覆盖此全局默认值。 +- 当既未设置全局失败目标，也未设置单个作业失败目标时，已经通过 `announce` 投递的作业会在失败时回退到该主 `announce` 目标。 +- 除非作业的主 `delivery.mode` 是 `"webhook"`，否则 `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 作业。 -参见 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)跟踪。 +参见 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 --- @@ -1175,34 +1178,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}}` | 媒体类型（image/audio/document/…） | +| `{{Transcript}}` | 音频转录 | +| `{{Prompt}}` | CLI 条目的已解析媒体提示词 | +| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力获取） | +| `{{GroupMembers}}` | 群组成员预览（尽力获取） | +| `{{SenderName}}` | 发送者显示名称（尽力获取） | +| `{{SenderE164}}` | 发送者电话号码（尽力获取） | +| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- -## 配置包含（`$include`） +## 配置包含项（`$include`） -将配置拆分为多个文件： +将配置拆分到多个文件中： ```json5 // ~/.openclaw/openclaw.json @@ -1219,12 +1222,12 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 - 单个文件：替换包含它的对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在 includes 之后合并（覆盖已包含的值）。 -- 嵌套 includes：最多深入 10 层。 -- 路径：相对于执行包含的文件解析，但必须保留在顶层配置目录（`openclaw.json` 的 `dirname`）内。绝对路径/`../` 形式只有在仍解析到该边界内时才允许。 -- 由 OpenClaw 拥有的写入，如果只更改单个顶层分区且该分区由单文件 include 支持，则会透传写入该包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。 -- 根 includes、include 数组以及带有同级覆盖项的 includes 对于 OpenClaw 拥有的写入是只读的；这些写入会失败关闭，而不是扁平化配置。 -- 错误：针对缺失文件、解析错误和循环 includes 提供清晰消息。 +- 同级键：在包含项之后合并（覆盖已包含的值）。 +- 嵌套包含：最多 10 层深。 +- 路径：相对于包含它的文件解析，但必须位于顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式仍解析到该边界内时才允许使用。 +- 仅更改由单文件包含支撑的一个顶层分区的 OpenClaw 所有写入，会透传写入该被包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。 +- 根包含项、包含数组，以及带同级覆盖项的包含项，对于 OpenClaw 所有写入是只读的；这些写入会失败关闭，而不是扁平化配置。 +- 错误：针对缺失文件、解析错误和循环包含提供清晰消息。 --- diff --git a/docs/zh-CN/gateway/configuration.md b/docs/zh-CN/gateway/configuration.md index 45a704c5f..d1e3d44f9 100644 --- a/docs/zh-CN/gateway/configuration.md +++ b/docs/zh-CN/gateway/configuration.md @@ -3,36 +3,38 @@ read_when: - 首次设置 OpenClaw - 正在查找常见配置模式 - 导航到特定配置部分 -summary: 配置概览：常见任务、快速设置，以及完整参考链接 +summary: 配置概览：常见任务、快速设置，以及完整参考的链接 title: 配置 x-i18n: - generated_at: "2026-04-28T11:51:34Z" + generated_at: "2026-04-28T22:57:53Z" model: gpt-5.5 provider: openai - source_hash: 432209fd9b8570a75639bc21b1611899d30a78217e55bb2a45bf3555988e3f40 + source_hash: b425a43ea6e40b8380d3a295dc9b190e5dbce7a6d044df786133bfadf3b07c0d source_path: gateway/configuration.md workflow: 16 --- -OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 **JSON5** 配置。 +OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 **JSON5** 配置。 活动配置路径必须是常规文件。对于 OpenClaw 自有写入，不支持符号链接形式的 `openclaw.json` -布局；原子写入可能会替换该路径，而不是保留符号链接。如果你把配置保存在 +布局；原子写入可能会替换 +该路径，而不是保留符号链接。如果你将配置保存在 默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。 如果文件缺失，OpenClaw 会使用安全默认值。添加配置的常见原因： -- 连接渠道并控制谁可以给机器人发消息 +- 连接渠道并控制谁可以给 bot 发消息 - 设置模型、工具、沙箱隔离或自动化（cron、钩子） - 调整会话、媒体、网络或 UI -查看[完整参考](/zh-CN/gateway/configuration-reference)，了解每个可用字段。 +请参阅[完整参考](/zh-CN/gateway/configuration-reference)，了解每个可用字段。 -智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 查看精确的字段级 -文档。本页提供面向任务的指导，[配置参考](/zh-CN/gateway/configuration-reference) 提供更完整的 -字段地图和默认值。 +智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 获取精确的字段级 +文档。使用本页获取面向任务的指导，并使用 +[配置参考](/zh-CN/gateway/configuration-reference) 查看更完整的 +字段映射和默认值。 -**刚开始配置？** 使用 `openclaw onboard` 进行交互式设置，或查看 [配置示例](/zh-CN/gateway/configuration-examples)指南以获取完整的可复制粘贴配置。 +**刚开始接触配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看 [配置示例](/zh-CN/gateway/configuration-examples)指南，获取完整的可复制粘贴配置。 ## 最小配置 @@ -62,53 +64,54 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 - 打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，使用 **配置** 标签页。 - 控制 UI 会根据实时配置 schema 渲染表单，其中包含字段 - `title` / `description` 文档元数据，并在可用时包含插件和渠道 schema， - 同时提供 **Raw JSON** 编辑器作为兜底入口。对于下钻 - UI 和其他工具，Gateway 网关还会暴露 `config.schema.lookup`，用于 - 获取一个路径范围内的 schema 节点及其直接子项摘要。 + 打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，并使用 **配置** 标签页。 + 控制 UI 会根据实时配置 schema 渲染表单，包括字段 + `title` / `description` 文档元数据，以及可用的插件和渠道 schema， + 并提供 **Raw JSON** 编辑器作为备用方式。对于下钻 + UI 和其他工具，Gateway 网关还会暴露 `config.schema.lookup`， + 用于获取一个限定路径的 schema 节点及其直接子项摘要。 - 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。 + 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监听该文件并自动应用更改（参见[热重载](#config-hot-reload)）。 ## 严格校验 -OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），以便编辑器附加 JSON Schema 元数据。 +OpenClaw 只接受完全匹配 schema 的配置。未知键、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器可以附加 JSON Schema 元数据。 -`openclaw config schema` 会打印控制 UI 和校验使用的规范 JSON Schema。 -`config.schema.lookup` 会获取单个路径范围内的节点以及用于下钻工具的 -子项摘要。字段 `title`/`description` 文档元数据会贯穿嵌套对象、通配符（`*`）、 -数组项（`[]`）以及 `anyOf`/ -`oneOf`/`allOf` 分支。加载 manifest registry 后，运行时插件和渠道 schema 会合并进来。 +`openclaw config schema` 会打印控制 UI +和校验使用的权威 JSON Schema。`config.schema.lookup` 会获取单个限定路径的节点及 +子项摘要，供下钻工具使用。字段 `title`/`description` 文档元数据会 +传递到嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/ +`oneOf`/`allOf` 分支中。加载 manifest 注册表后，运行时插件和渠道 schema 会合并进来。 校验失败时： - Gateway 网关不会启动 - 只有诊断命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`） -- 运行 `openclaw doctor` 查看精确问题 +- 运行 `openclaw doctor` 查看确切问题 - 运行 `openclaw doctor --fix`（或 `--yes`）应用修复 Gateway 网关会在每次成功启动后保留一份可信的最后已知良好副本。 -如果 `openclaw.json` 后续校验失败（或丢失 `gateway.mode`、体积 -急剧缩小，或前面被误加一行日志），OpenClaw 会将损坏文件保留为 +如果 `openclaw.json` 之后校验失败（或丢失 `gateway.mode`、大幅缩小， +或者前面被插入了一行杂散日志），OpenClaw 会将损坏的文件保留为 `.clobbered.*`，恢复最后已知良好副本，并记录恢复 -原因。下一个智能体轮次也会收到系统事件警告，避免主 -智能体盲目重写已恢复的配置。当候选内容包含已打码的密钥占位符（例如 `***`）时， -会跳过提升为最后已知良好副本。当所有校验问题都限定在 `plugins.entries....` 范围内时， -OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状态，并 -暴露插件本地失败，以免插件 schema 或主机版本不匹配 +原因。下一次智能体轮次也会收到系统事件警告，避免主 +智能体盲目重写已恢复的配置。当候选配置包含经过遮蔽的密钥占位符（例如 `***`）时， +会跳过提升为最后已知良好副本。 +当所有校验问题都限定在 `plugins.entries....` 范围内时，OpenClaw +不会执行整文件恢复。它会保持当前配置生效，并 +呈现插件本地失败，以免插件 schema 或主机版本不匹配 回滚无关的用户设置。 ## 常见任务 - 每个渠道在 `channels.` 下都有自己的配置段。设置步骤请查看对应的渠道页面： + 每个渠道在 `channels.` 下都有自己的配置部分。请查看对应的渠道页面了解设置步骤： - [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp` - [Telegram](/zh-CN/channels/telegram) — `channels.telegram` @@ -139,7 +142,7 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 - 设置主模型和可选回退： + 设置主模型和可选回退模型： ```json5 { @@ -159,30 +162,30 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 ``` - `agents.defaults.models` 定义模型目录，并作为 `/model` 的允许列表。 - - 使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加允许列表条目，而不移除现有模型。如果普通替换会移除条目，则会被拒绝，除非你传入 `--replace`。 + - 使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加允许列表条目，而不会移除现有模型。除非传入 `--replace`，否则会移除条目的普通替换会被拒绝。 - 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。 - - `agents.defaults.imageMaxDimensionPx` 控制 transcript/工具图片降采样（默认 `1200`）；较低值通常会减少截图密集运行中的视觉 token 用量。 - - 参见 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，并参见[模型故障转移](/zh-CN/concepts/model-failover)了解身份验证轮换和回退行为。 - - 对于自定义/自托管提供商，请参见参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。 + - `agents.defaults.imageMaxDimensionPx` 控制 transcript/工具图片缩小尺寸（默认 `1200`）；较低的值通常会减少大量截图运行中的视觉 token 用量。 + - 请参阅 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，并参阅[模型故障转移](/zh-CN/concepts/model-failover)了解认证轮换和回退行为。 + - 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。 - - 私信访问按渠道通过 `dmPolicy` 控制： + + 私信访问通过每个渠道的 `dmPolicy` 控制： - - `"pairing"`（默认）：未知发送者会获得一次性配对码以供批准 - - `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者） + - `"pairing"`（默认）：未知发送者会收到一次性配对码，用于批准 + - `"allowlist"`：只允许 `allowFrom`（或已配对允许存储）中的发送者 - `"open"`：允许所有入站私信（需要 `allowFrom: ["*"]`） - `"disabled"`：忽略所有私信 - 对于群组，使用 `groupPolicy` + `groupAllowFrom` 或渠道专用允许列表。 + 对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定允许列表。 - 查看[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)，了解每个渠道的详细信息。 + 请参阅[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)，了解每个渠道的详细信息。 - 群组消息默认**需要提及**。按智能体配置触发模式，并让可见房间回复保持在默认消息工具路径上，除非你明确需要旧版自动最终回复： + 群消息默认**需要提及**。按智能体配置触发模式，并让可见的房间回复保留在默认消息工具路径上，除非你有意使用旧版自动最终回复： ```json5 { @@ -211,14 +214,14 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 - **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等） - **文本模式**：`mentionPatterns` 中的安全正则模式 - - **可见回复**：`message_tool` 会保持普通最终回复为私密；智能体必须调用 `message(action=send)` 才能在群组/渠道中可见发帖。 - - 查看[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)，了解可见回复模式、每渠道覆盖和自聊模式。 + - **可见回复**：`message_tool` 会保持普通最终回复私密；智能体必须调用 `message(action=send)` 才能在群组/渠道中可见地发布。 + - 请参阅[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)，了解可见回复模式、每个渠道的覆盖项以及自聊天模式。 - 使用 `agents.defaults.skills` 作为共享基线，然后用 `agents.list[].skills` 覆盖特定 - 智能体： + 使用 `agents.defaults.skills` 设置共享基线，然后用 `agents.list[].skills` + 覆盖特定智能体： ```json5 { @@ -235,16 +238,16 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 } ``` - - 省略 `agents.defaults.skills`，默认不限制 Skills。 - - 省略 `agents.list[].skills` 以继承默认值。 + - 默认情况下省略 `agents.defaults.skills` 表示不限制 Skills。 + - 省略 `agents.list[].skills` 表示继承默认值。 - 设置 `agents.list[].skills: []` 表示没有 Skills。 - - 参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 + - 请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及 [配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。 - 控制 Gateway 网关重启疑似停滞渠道的积极程度： + 控制 Gateway 网关对看起来停滞的渠道执行重启的激进程度： ```json5 { @@ -268,8 +271,25 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 - 设置 `gateway.channelHealthCheckMinutes: 0` 可全局禁用健康监控重启。 - `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。 - - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled` 可为单个渠道或账号禁用自动重启，而不禁用全局监控。 - - 参见[健康检查](/zh-CN/gateway/health)进行运维调试，并参见[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。 + - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled`，可在不禁用全局监控器的情况下，为某个渠道或账号禁用自动重启。 + - 请参阅[健康检查](/zh-CN/gateway/health)了解运维调试，并参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)查看所有字段。 + + + + + 给本地客户端更多时间，在负载较高或低性能主机上完成认证前 WebSocket 握手： + + ```json5 + { + gateway: { + handshakeTimeoutMs: 30000, + }, + } + ``` + + - 默认值为 `15000` 毫秒。 + - `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 对一次性服务或 shell 覆盖仍然优先。 + - 优先修复启动/事件循环停顿；这个旋钮适用于健康但预热期间较慢的主机。 @@ -296,8 +316,8 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 - `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer` - `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。 - - 参见[会话管理](/zh-CN/concepts/session)，了解范围、身份链接和发送策略。 - - 参见[完整参考](/zh-CN/gateway/config-agents#session)，了解所有字段。 + - 查看[会话管理](/zh-CN/concepts/session)，了解作用域、身份关联和发送策略。 + - 查看[完整参考](/zh-CN/gateway/config-agents#session)，了解所有字段。 @@ -319,12 +339,12 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 先构建镜像：`scripts/sandbox-setup.sh` - 请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)获取完整指南，并参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。 + 查看[沙箱隔离](/zh-CN/gateway/sandboxing)获取完整指南，并查看[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。 - - relay 后端推送在 `openclaw.json` 中配置。 + + 中继支持的推送在 `openclaw.json` 中配置。 在 Gateway 网关配置中设置： @@ -344,7 +364,7 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 } ``` - 等效 CLI： + CLI 等效命令： ```bash openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com @@ -352,35 +372,35 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 这会执行以下操作： - - 让 Gateway 网关通过外部 relay 发送 `push.test`、唤醒提醒和重连唤醒。 - - 使用由已配对 iOS 应用转发的注册作用域发送授权。Gateway 网关不需要部署范围的 relay 令牌。 - - 将每个 relay 后端注册绑定到 iOS 应用配对的 Gateway 网关身份，因此另一个 Gateway 网关无法复用已存储的注册。 - - 让本地/手动 iOS 构建继续使用直接 APNs。relay 后端发送仅适用于通过 relay 注册的官方分发构建。 - - 必须匹配内置到官方/TestFlight iOS 构建中的 relay 基础 URL，确保注册和发送流量到达同一个 relay 部署。 + - 允许 Gateway 网关通过外部中继发送 `push.test`、唤醒提醒和重连唤醒。 + - 使用由已配对 iOS 应用转发、限定于注册范围的发送授权。Gateway 网关不需要部署范围的中继令牌。 + - 将每个中继支持的注册绑定到 iOS 应用配对的 Gateway 网关身份，因此另一个 Gateway 网关无法复用已存储的注册。 + - 让本地/手动 iOS 构建继续使用直接 APNs。中继支持的发送仅适用于通过中继注册的官方分发构建。 + - 必须匹配内置到官方/TestFlight iOS 构建中的中继基础 URL，以便注册和发送流量到达同一个中继部署。 端到端流程： - 1. 安装使用相同 relay 基础 URL 编译的官方/TestFlight iOS 构建。 + 1. 安装使用相同中继基础 URL 编译的官方/TestFlight iOS 构建。 2. 在 Gateway 网关上配置 `gateway.push.apns.relay.baseUrl`。 - 3. 将 iOS 应用与 Gateway 网关配对，并让节点和 operator 会话都连接。 - 4. iOS 应用获取 Gateway 网关身份，使用 App Attest 加应用收据向 relay 注册，然后将 relay 后端 `push.apns.register` 载荷发布到已配对的 Gateway 网关。 - 5. Gateway 网关存储 relay handle 和发送授权，然后将它们用于 `push.test`、唤醒提醒和重连唤醒。 + 3. 将 iOS 应用与 Gateway 网关配对，并让节点和操作员会话都连接。 + 4. iOS 应用获取 Gateway 网关身份，使用 App Attest 加应用收据向中继注册，然后将中继支持的 `push.apns.register` 负载发布到已配对的 Gateway 网关。 + 5. Gateway 网关存储中继句柄和发送授权，然后将它们用于 `push.test`、唤醒提醒和重连唤醒。 运维说明： - - 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它可以发布绑定到该 Gateway 网关的新 relay 注册。 - - 如果你发布指向不同 relay 部署的新 iOS 构建，应用会刷新其缓存的 relay 注册，而不是复用旧的 relay 来源。 + - 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接该应用，以便它发布绑定到该 Gateway 网关的新中继注册。 + - 如果你发布指向不同中继部署的新 iOS 构建，应用会刷新其缓存的中继注册，而不是复用旧的中继来源。 兼容性说明： - `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。 - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限 loopback 的开发逃生口；不要在配置中持久化 HTTP relay URL。 + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限 loopback 的开发逃生口；不要在配置中持久化 HTTP 中继 URL。 - 请参阅 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并参阅[身份验证和信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解 relay 安全模型。 + 查看 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并查看[身份验证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解中继安全模型。 - + ```json5 { agents: { @@ -396,12 +416,12 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 - `every`：持续时间字符串（`30m`、`2h`）。设置为 `0m` 可禁用。 - `target`：`last` | `none` | ``（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`） - - `directPolicy`：对于私信风格的 heartbeat 目标，使用 `allow`（默认）或 `block` - - 请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)获取完整指南。 + - `directPolicy`：用于私信样式心跳目标的 `allow`（默认）或 `block` + - 查看[心跳](/zh-CN/gateway/heartbeat)获取完整指南。 - + ```json5 { cron: { @@ -418,11 +438,11 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 - `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。 - `runLog`：按大小和保留行数清理 `cron/runs/.jsonl`。 - - 请参阅 [Cron 任务](/zh-CN/automation/cron-jobs)了解功能概览和 CLI 示例。 + - 查看 [Cron 作业](/zh-CN/automation/cron-jobs)了解功能概览和 CLI 示例。 - + 在 Gateway 网关上启用 HTTP webhook 端点： ```json5 @@ -447,15 +467,15 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 ``` 安全说明： - - 将所有 hook/webhook 载荷内容都视为不可信输入。 - - 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关令牌。 - - Hook 认证仅通过 header（`Authorization: Bearer ...` 或 `x-openclaw-token`）；query-string 令牌会被拒绝。 - - `hooks.path` 不能是 `/`；请将 webhook 入口放在专用子路径上，例如 `/hooks`。 - - 除非进行严格限定范围的调试，否则保持不安全内容绕过标志禁用（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。 - - 如果启用 `hooks.allowRequestSessionKey`，还要设置 `hooks.allowedSessionKeyPrefixes`，以约束调用方选择的会话键。 - - 对于 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息传递，并在可行时加上沙箱隔离）。 + - 将所有 hook/webhook 负载内容视为不受信任的输入。 + - 使用专用的 `hooks.token`；不要复用共享 Gateway 网关令牌。 + - Hook 认证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串令牌会被拒绝。 + - `hooks.path` 不能是 `/`；请将 webhook 入口保持在专用子路径上，例如 `/hooks`。 + - 保持不安全内容绕过标志处于禁用状态（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非正在进行严格限定范围的调试。 + - 如果启用 `hooks.allowRequestSessionKey`，还要设置 `hooks.allowedSessionKeyPrefixes` 来限定调用方选择的会话键。 + - 对于 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅限消息发送，并尽可能加上沙箱隔离）。 - 请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)了解所有映射选项和 Gmail 集成。 + 查看[完整参考](/zh-CN/gateway/configuration-reference#hooks)了解所有映射选项和 Gmail 集成。 @@ -477,12 +497,12 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 } ``` - 请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和每个智能体的访问配置档案。 + 查看[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和每智能体访问配置文件。 - 使用 `$include` 组织大型配置： + 使用 `$include` 来组织大型配置： ```json5 // ~/.openclaw/openclaw.json @@ -495,18 +515,14 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 } ``` - - **单个文件**：替换所在对象 + - **单个文件**：替换包含它的对象 - **文件数组**：按顺序深度合并（后者优先） - - **同级键**：在 include 之后合并（覆盖已 include 的值） - - **嵌套 includes**：最多支持 10 层 + - **同级键**：在 include 后合并（覆盖已包含的值） + - **嵌套 include**：最多支持 10 层深度 - **相对路径**：相对于执行 include 的文件解析 - - **OpenClaw 拥有的写入**：当一次写入只更改一个顶层 section， - 且该 section 由单文件 include 支持（例如 `plugins: { $include: "./plugins.json5" }`）时， - OpenClaw 会更新该 include 文件，并保持 `openclaw.json` 不变 - - **不支持的写穿透**：root includes、include 数组以及带同级覆盖的 includes - 对 OpenClaw 拥有的写入会 fail closed，而不是 - 将配置扁平化 - - **错误处理**：针对缺失文件、解析错误和循环 includes 提供清晰错误 + - **OpenClaw 拥有的写入**：当写入只更改一个由单文件 include 支持的顶层区段时，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该被包含文件，并保持 `openclaw.json` 不变 + - **不支持的透传写入**：root include、include 数组以及带同级覆盖的 include 会对 OpenClaw 拥有的写入失败关闭，而不是扁平化配置 + - **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误 @@ -515,22 +531,11 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状 Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改，大多数设置无需手动重启。 -直接文件编辑在通过验证前会被视为不可信。监视器会等待 -编辑器临时写入/重命名抖动稳定，读取最终文件，并通过恢复 -last-known-good 配置来拒绝无效的外部编辑。OpenClaw 拥有的 -配置写入在写入前使用相同的 schema gate；破坏性覆盖 -（例如删除 `gateway.mode` 或将文件缩小超过一半）会被拒绝， -并保存为 `.rejected.*` 以供检查。 +直接文件编辑在通过验证前会被视为不受信任。监视器会等待编辑器临时写入/重命名抖动稳定，读取最终文件，并通过恢复上一个已知良好配置来拒绝无效的外部编辑。OpenClaw 拥有的配置写入在写入前使用同一个 schema 门禁；破坏性覆盖（例如删除 `gateway.mode` 或将文件缩小超过一半）会被拒绝，并保存为 `.rejected.*` 以供检查。 -插件本地验证失败是例外：如果所有问题都位于 -`plugins.entries....` 下，重载会保留当前配置并报告插件 -问题，而不是恢复 `.last-good`。 +插件本地验证失败是例外：如果所有问题都位于 `plugins.entries....` 下，重载会保留当前配置并报告插件问题，而不是恢复 `.last-good`。 -如果你在日志中看到 `Config auto-restored from last-known-good` 或 -`config reload restored last-known-good config`，请检查 `openclaw.json` -旁边匹配的 `.clobbered.*` 文件，修复被拒绝的载荷，然后运行 -`openclaw config validate`。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config) -获取恢复检查清单。 +如果你在日志中看到 `Config auto-restored from last-known-good` 或 `config reload restored last-known-good config`，请检查 `openclaw.json` 旁边匹配的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行 `openclaw config validate`。查看 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)获取恢复检查清单。 ### 重载模式 @@ -549,13 +554,13 @@ last-known-good 配置来拒绝无效的外部编辑。OpenClaw 拥有的 } ``` -### 哪些可热应用，哪些需要重启 +### 哪些会热应用，哪些需要重启 大多数字段都可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。 -| 类别 | 字段 | 需要重启？ | +| 类别 | 字段 | 是否需要重启？ | | ------------------- | ----------------------------------------------------------------- | --------------- | -| 渠道 | `channels.*`、`web`（WhatsApp）— 所有内置渠道和插件渠道 | 否 | +| 渠道 | `channels.*`、`web`（WhatsApp）— 所有内置和插件渠道 | 否 | | 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 | | 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 | | 会话和消息 | `session`、`messages` | 否 | @@ -565,34 +570,31 @@ last-known-good 配置来拒绝无效的外部编辑。OpenClaw 拥有的 | 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** | -`gateway.reload` 和 `gateway.remote` 是例外 — 更改它们**不会**触发重启。 +`gateway.reload` 和 `gateway.remote` 是例外，更改它们**不会**触发重启。 ### 重载规划 -当你编辑通过 `$include` 引用的源文件时，OpenClaw 会从源文件编写的布局 -规划重载，而不是从扁平化的内存视图规划。这会让热重载决策 -（热应用还是重启）保持可预测，即使单个顶层 section 位于自己的 -include 文件中，例如 `plugins: { $include: "./plugins.json5" }`。 -如果源布局存在歧义，重载规划会 fail closed。 +OpenClaw 通过 `$include` 引用的源文件时，OpenClaw 会根据源文件编写时的布局来规划重新加载，而不是根据扁平化的内存视图。 +这样即使单个顶级区段位于自己的包含文件中，例如 +`plugins: { $include: "./plugins.json5" }`，热重载决策（热应用与重启）也保持可预测。如果源布局存在歧义，重新加载规划会保守失败。 ## 配置 RPC（程序化更新） 对于通过 Gateway 网关 API 写入配置的工具，优先使用此流程： -- `config.schema.lookup` 检查一个子树（浅层 schema 节点 + 子项 - 摘要） -- `config.get` 获取当前快照和 `hash` -- `config.patch` 用于部分更新（JSON merge patch：对象合并，`null` - 删除，数组替换） -- `config.apply` 仅在你打算替换整个配置时使用 -- `update.run` 用于显式自更新并重启 -- `update.status` 检查最新的更新重启 sentinel，并在重启后验证正在运行的版本 +- `config.schema.lookup` 用于检查一个子树（浅层 schema 节点 + 子项摘要） +- `config.get` 用于获取当前快照以及 `hash` +- `config.patch` 用于部分更新（JSON 合并补丁：对象合并，`null` 删除，数组替换） +- 仅当你打算替换整个配置时才使用 `config.apply` +- `update.run` 用于显式自我更新并重启 +- `update.status` 用于检查最新的更新重启哨兵，并在重启后验证正在运行的版本 -智能体应将 `config.schema.lookup` 作为查看精确字段级文档和约束的第一站。当需要更完整的配置映射、默认值或指向专用子系统参考的链接时，请使用[配置参考](/zh-CN/gateway/configuration-reference)。 +智能体应将 `config.schema.lookup` 视为获取精确字段级文档和约束的第一站。当需要更广泛的配置映射、默认值或专用子系统参考链接时，使用 [配置参考](/zh-CN/gateway/configuration-reference)。 -控制平面写入（`config.apply`、`config.patch`、`update.run`）按 `deviceId+clientIp` 每 60 秒最多 3 个请求进行速率限制。重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。`update.status` 是只读的，但限定为管理员范围，因为重启哨兵可能包含更新步骤摘要和命令输出尾部。 +控制平面写入（`config.apply`、`config.patch`、`update.run`）按每个 `deviceId+clientIp` 每 60 秒 3 个请求进行限速。重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。 +`update.status` 是只读的，但作用域为管理员，因为重启哨兵可能包含更新步骤摘要和命令输出尾部。 部分补丁示例： @@ -605,11 +607,11 @@ openclaw gateway call config.patch --params '{ }' ``` -`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。当配置已存在时，这两种方法都要求提供 `baseHash`。 +`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。当配置已存在时，这两个方法都需要 `baseHash`。 ## 环境变量 -OpenClaw 会从父进程以及以下位置读取环境变量： +OpenClaw 会从父进程读取环境变量，并额外读取： - 当前工作目录中的 `.env`（如果存在） - `~/.openclaw/.env`（全局回退） @@ -626,7 +628,7 @@ OpenClaw 会从父进程以及以下位置读取环境变量： ``` - 如果启用且未设置预期键名，OpenClaw 会运行你的登录 shell，并仅导入缺失的键： + 如果启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并只导入缺失的键： ```json5 { @@ -640,7 +642,7 @@ OpenClaw 会从父进程以及以下位置读取环境变量： - 在任意配置字符串值中使用 `${VAR_NAME}` 引用环境变量： + 使用 `${VAR_NAME}` 在任意配置字符串值中引用环境变量： ```json5 { @@ -653,13 +655,13 @@ OpenClaw 会从父进程以及以下位置读取环境变量： - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*` - 缺失或为空的变量会在加载时抛出错误 -- 使用 `$${VAR}` 转义以输出字面值 -- 在 `$include` 文件中也可用 +- 使用 `$${VAR}` 转义以输出字面量 +- 可在 `$include` 文件中使用 - 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"` - + 对于支持 SecretRef 对象的字段，你可以使用： ```json5 @@ -692,15 +694,15 @@ OpenClaw 会从父进程以及以下位置读取环境变量： } ``` -SecretRef 详情（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）见[密钥管理](/zh-CN/gateway/secrets)。 -支持的凭证路径列在 [SecretRef 凭证范围](/zh-CN/reference/secretref-credential-surface)中。 +SecretRef 详细信息（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）见 [Secrets 管理](/zh-CN/gateway/secrets)。 +支持的凭证路径列在 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) 中。 -有关完整优先级和来源，请参阅[环境](/zh-CN/help/environment)。 +完整优先级和来源见 [环境](/zh-CN/help/environment)。 ## 完整参考 -如需完整的逐字段参考，请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。 +完整的逐字段参考见 **[配置参考](/zh-CN/gateway/configuration-reference)**。 --- diff --git a/docs/zh-CN/install/docker.md b/docs/zh-CN/install/docker.md index 13bc0918d..1dba0d8eb 100644 --- a/docs/zh-CN/install/docker.md +++ b/docs/zh-CN/install/docker.md @@ -2,38 +2,38 @@ read_when: - 你想使用容器化的 Gateway 网关，而不是本地安装 - 你正在验证 Docker 流程 -summary: 可选的基于 Docker 的 OpenClaw 设置和新手引导 +summary: OpenClaw 可选的基于 Docker 的设置和新手引导 title: Docker x-i18n: - generated_at: "2026-04-28T11:56:02Z" + generated_at: "2026-04-28T22:57:52Z" model: gpt-5.5 provider: openai - source_hash: d2fe308bdcc243b59923d2b05ba543d63fa146747b9df9bdd59eef76bac187c8 + source_hash: 71027022ab9fe1c5a14aa67f0e3edabb0e2aa3c668752637caef49bab5a591de source_path: install/docker.md workflow: 16 --- -Docker 是**可选**的。仅当你想要容器化 Gateway 网关，或想验证 Docker 流程时才使用它。 +Docker 是**可选的**。只有在你想使用容器化 Gateway 网关或验证 Docker 流程时才需要使用它。 ## Docker 适合我吗？ -- **是**：你想要一个隔离、用完即丢的 Gateway 网关环境，或想在没有本地安装的主机上运行 OpenClaw。 -- **否**：你正在自己的机器上运行，并且只想要最快的开发循环。请改用常规安装流程。 -- **沙箱注意事项**：启用沙箱隔离时，默认沙箱后端使用 Docker，但沙箱隔离默认关闭，并且**不**要求完整 Gateway 网关在 Docker 中运行。SSH 和 OpenShell 沙箱后端也可用。参见[沙箱隔离](/zh-CN/gateway/sandboxing)。 +- **是**：你想要一个隔离的、可丢弃的 Gateway 网关环境，或想在没有本地安装的主机上运行 OpenClaw。 +- **否**：你正在自己的机器上运行，只想要最快的开发循环。请改用常规安装流程。 +- **沙箱注意事项**：启用沙箱隔离时，默认沙箱后端会使用 Docker，但沙箱隔离默认关闭，并且**不**要求完整 Gateway 网关在 Docker 中运行。SSH 和 OpenShell 沙箱后端也可用。参见[沙箱隔离](/zh-CN/gateway/sandboxing)。 -## 前提条件 +## 前置条件 - Docker Desktop（或 Docker Engine）+ Docker Compose v2 -- 镜像构建至少需要 2 GB RAM（在 1 GB 主机上，`pnpm install` 可能因 OOM 被终止并以退出码 137 退出） -- 有足够磁盘空间存放镜像和日志 +- 镜像构建至少需要 2 GB RAM（`pnpm install` 在 1 GB 主机上可能因 OOM 被终止，并以 137 退出） +- 足够的磁盘空间用于镜像和日志 - 如果在 VPS/公网主机上运行，请查看 - [网络暴露的安全加固](/zh-CN/gateway/security)， + [网络暴露安全加固](/zh-CN/gateway/security)， 尤其是 Docker `DOCKER-USER` 防火墙策略。 ## 容器化 Gateway 网关 - + 从仓库根目录运行设置脚本： ```bash @@ -53,23 +53,23 @@ Docker 是**可选**的。仅当你想要容器化 Gateway 网关，或想验证 - + 设置脚本会自动运行新手引导。它会： - 提示输入提供商 API 密钥 - 生成 Gateway 网关令牌并写入 `.env` - 通过 Docker Compose 启动 Gateway 网关 - 在设置过程中，启动前的新手引导和配置写入会直接通过 - `openclaw-gateway` 运行。`openclaw-cli` 用于在 - Gateway 网关容器已经存在之后运行的命令。 + 设置期间，启动前的新手引导和配置写入会直接通过 + `openclaw-gateway` 运行。`openclaw-cli` 用于 Gateway 网关容器已存在后 + 你运行的命令。 - - 在浏览器中打开 `http://127.0.0.1:18789/`，并将已配置的 - 共享密钥粘贴到设置中。设置脚本默认会将令牌写入 `.env`； - 如果你把容器配置切换为密码认证，请改用该密码。 + + 在浏览器中打开 `http://127.0.0.1:18789/`，并将配置好的 + 共享密钥粘贴到 Settings 中。设置脚本默认会将令牌写入 `.env`； + 如果你将容器配置切换为密码认证，请改用该密码。 还需要再次获取 URL？ @@ -79,7 +79,7 @@ Docker 是**可选**的。仅当你想要容器化 Gateway 网关，或想验证 - + 使用 CLI 容器添加消息渠道： ```bash @@ -100,7 +100,7 @@ Docker 是**可选**的。仅当你想要容器化 Gateway 网关，或想验证 ### 手动流程 -如果你更想自己运行每个步骤，而不是使用设置脚本： +如果你更希望自己逐步运行，而不是使用设置脚本： ```bash docker build -t openclaw:local -f Dockerfile . @@ -112,52 +112,52 @@ docker compose up -d openclaw-gateway ``` -请从仓库根目录运行 `docker compose`。如果你启用了 `OPENCLAW_EXTRA_MOUNTS` +从仓库根目录运行 `docker compose`。如果你启用了 `OPENCLAW_EXTRA_MOUNTS` 或 `OPENCLAW_HOME_VOLUME`，设置脚本会写入 `docker-compose.extra.yml`； -请用 `-f docker-compose.yml -f docker-compose.extra.yml` 将其包含进来。 +请使用 `-f docker-compose.yml -f docker-compose.extra.yml` 将其包含进来。 因为 `openclaw-cli` 共享 `openclaw-gateway` 的网络命名空间，所以它是一个 -启动后工具。在运行 `docker compose up -d openclaw-gateway` 之前，请通过 -`openclaw-gateway` 并带上 `--no-deps --entrypoint node` 来运行新手引导 -和设置时的配置写入。 +启动后工具。在执行 `docker compose up -d openclaw-gateway` 之前，请通过 +带有 `--no-deps --entrypoint node` 的 `openclaw-gateway` 运行新手引导 +和设置时配置写入。 ### 环境变量 -设置脚本接受这些可选环境变量： +设置脚本接受以下可选环境变量： | 变量 | 用途 | | ------------------------------------------ | --------------------------------------------------------------- | | `OPENCLAW_IMAGE` | 使用远程镜像，而不是在本地构建 | -| `OPENCLAW_DOCKER_APT_PACKAGES` | 在构建期间安装额外 apt 包（以空格分隔） | -| `OPENCLAW_EXTENSIONS` | 在构建时预安装插件依赖（以空格分隔的名称） | -| `OPENCLAW_EXTRA_MOUNTS` | 额外主机绑定挂载（以逗号分隔的 `source:target[:opts]`） | -| `OPENCLAW_HOME_VOLUME` | 将 `/home/node` 持久化到一个命名 Docker 卷 | +| `OPENCLAW_DOCKER_APT_PACKAGES` | 构建期间安装额外 apt 包（空格分隔） | +| `OPENCLAW_EXTENSIONS` | 构建时预安装插件依赖（空格分隔的名称） | +| `OPENCLAW_EXTRA_MOUNTS` | 额外主机绑定挂载（逗号分隔的 `source:target[:opts]`） | +| `OPENCLAW_HOME_VOLUME` | 在命名 Docker 卷中持久化 `/home/node` | | `OPENCLAW_PLUGIN_STAGE_DIR` | 生成的内置插件依赖和镜像的容器路径 | -| `OPENCLAW_SANDBOX` | 选择启用沙箱启动流程（`1`、`true`、`yes`、`on`） | -| `OPENCLAW_DOCKER_SOCKET` | 覆盖 Docker socket 路径 | +| `OPENCLAW_SANDBOX` | 选择启用沙箱引导（`1`、`true`、`yes`、`on`） | +| `OPENCLAW_SKIP_ONBOARDING` | 跳过交互式新手引导步骤（`1`、`true`、`yes`、`on`） | +| `OPENCLAW_DOCKER_SOCKET` | 覆盖 Docker 套接字路径 | | `OPENCLAW_DISABLE_BONJOUR` | 禁用 Bonjour/mDNS 广播（Docker 默认值为 `1`） | -| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | 禁用内置插件源码绑定挂载覆盖层 | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | 用于 OpenTelemetry 导出的共享 OTLP/HTTP 收集器端点 | -| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | 用于 traces、metrics 或 logs 的信号专用 OTLP 端点 | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 协议覆盖。当前仅支持 `http/protobuf` | +| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | 禁用内置插件源代码绑定挂载覆盖层 | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | 用于 OpenTelemetry 导出的共享 OTLP/HTTP 采集器端点 | +| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | 面向 traces、metrics 或 logs 的信号专用 OTLP 端点 | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 协议覆盖。目前仅支持 `http/protobuf` | | `OTEL_SERVICE_NAME` | 用于 OpenTelemetry 资源的服务名称 | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | 选择启用最新的实验性 GenAI 语义属性 | -| `OPENCLAW_OTEL_PRELOADED` | 当已有一个 OpenTelemetry SDK 预加载时，跳过启动第二个 SDK | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | 选择启用最新实验性 GenAI 语义属性 | +| `OPENCLAW_OTEL_PRELOADED` | 当已有一个 OpenTelemetry SDK 预加载时，跳过启动第二个 | -维护者可以通过将某个插件源码目录挂载到其打包源码路径上，针对打包镜像测试 -内置插件源码，例如 +维护者可以通过将某个插件源目录挂载到其打包源路径上，针对打包镜像测试内置插件源代码，例如 `OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro`。 -该挂载的源码目录会针对相同插件 id 覆盖匹配的已编译 +该挂载的源目录会覆盖同一插件 ID 对应的已编译 `/app/dist/extensions/synology-chat` 包。 ### 可观测性 -OpenTelemetry 导出是从 Gateway 网关容器向你的 OTLP 收集器发出的出站流量。 -它不需要发布 Docker 端口。如果你在本地构建镜像，并且希望镜像内可使用 -内置 OpenTelemetry exporter，请包含它的运行时依赖： +OpenTelemetry 导出是从 Gateway 网关容器出站到你的 OTLP +采集器。它不需要发布 Docker 端口。如果你在本地构建镜像，并希望内置 OpenTelemetry 导出器在镜像内可用， +请包含其运行时依赖： ```bash export OPENCLAW_EXTENSIONS="diagnostics-otel" @@ -167,33 +167,35 @@ export OTEL_SERVICE_NAME="openclaw-gateway" ``` 官方 OpenClaw Docker 发布镜像包含内置 -`diagnostics-otel` 插件源码。根据镜像和缓存状态，Gateway 网关在首次启用 -该插件时仍可能会暂存插件本地的 OpenTelemetry 运行时依赖，因此请允许首次启动 -访问包 registry，或在你的发布通道中预热镜像。若要启用导出，请在配置中允许并启用 -`diagnostics-otel` 插件，然后设置 `diagnostics.otel.enabled=true`，或使用 -[OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)中的配置示例。收集器认证头通过 +`diagnostics-otel` 插件源代码。根据镜像和缓存状态，Gateway 网关在首次启用该插件时 +可能仍会暂存插件本地 OpenTelemetry 运行时依赖，因此请允许首次启动访问包注册表， +或在你的发布流程中预热镜像。若要启用导出，请在配置中允许并启用 +`diagnostics-otel` 插件，然后设置 +`diagnostics.otel.enabled=true`，或使用 +[OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)中的配置示例。采集器认证标头通过 `diagnostics.otel.headers` 配置，而不是通过 Docker 环境变量配置。 -Prometheus 指标使用已经发布的 Gateway 网关端口。启用 +Prometheus metrics 使用已发布的 Gateway 网关端口。启用 `diagnostics-prometheus` 插件，然后抓取： ```text http://:18789/api/diagnostics/prometheus ``` -该路由受 Gateway 网关认证保护。不要暴露单独的公开 `/metrics` 端口或未认证的反向代理路径。参见 -[Prometheus 指标](/zh-CN/gateway/prometheus)。 +该路由受 Gateway 网关认证保护。不要暴露单独的公共 +`/metrics` 端口或未认证的反向代理路径。参见 +[Prometheus metrics](/zh-CN/gateway/prometheus)。 ### 健康检查 -容器探针端点（无需认证）： +容器探测端点（无需认证）： ```bash curl -fsS http://127.0.0.1:18789/healthz # liveness curl -fsS http://127.0.0.1:18789/readyz # readiness ``` -Docker 镜像包含一个内置 `HEALTHCHECK`，用于 ping `/healthz`。 +Docker 镜像包含一个内置 `HEALTHCHECK`，会 ping `/healthz`。 如果检查持续失败，Docker 会将容器标记为 `unhealthy`，编排系统可以重启或替换它。 已认证的深度健康快照： @@ -204,15 +206,16 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA ### LAN 与 loopback -`scripts/docker/setup.sh` 默认设置 `OPENCLAW_GATEWAY_BIND=lan`，因此主机可通过 -`http://127.0.0.1:18789` 使用 Docker 端口发布来访问。 +`scripts/docker/setup.sh` 默认设置 `OPENCLAW_GATEWAY_BIND=lan`，因此主机可以通过 +`http://127.0.0.1:18789` 访问 Docker 发布的端口。 - `lan`（默认）：主机浏览器和主机 CLI 可以访问已发布的 Gateway 网关端口。 -- `loopback`：只有容器网络命名空间内的进程可以直接访问 Gateway 网关。 +- `loopback`：只有容器网络命名空间内的进程才能直接访问 + Gateway 网关。 -请使用 `gateway.bind` 中的绑定模式值（`lan` / `loopback` / `custom` / -`tailnet` / `auto`），不要使用 `0.0.0.0` 或 `127.0.0.1` 这类主机别名。 +在 `gateway.bind` 中使用绑定模式值（`lan` / `loopback` / `custom` / +`tailnet` / `auto`），不要使用 `0.0.0.0` 或 `127.0.0.1` 这样的主机别名。 ### 主机本地提供商 @@ -220,16 +223,17 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA 当 OpenClaw 在 Docker 中运行时，容器内的 `127.0.0.1` 指的是容器本身， 而不是你的主机机器。对于在主机上运行的 AI 提供商，请使用 `host.docker.internal`： -| 提供商 | 主机默认 URL | Docker 设置 URL | +| 提供商 | 主机默认 URL | Docker 设置 URL | | --------- | ------------------------ | ----------------------------------- | | LM Studio | `http://127.0.0.1:1234` | `http://host.docker.internal:1234` | | Ollama | `http://127.0.0.1:11434` | `http://host.docker.internal:11434` | -内置 Docker 设置会将这些主机 URL 用作 LM Studio 和 Ollama 的新手引导默认值， -并且 `docker-compose.yml` 会将 `host.docker.internal` 映射到 Linux Docker Engine -的 Docker 主机网关。Docker Desktop 已经在 macOS 和 Windows 上提供相同主机名。 +内置 Docker 设置会将这些主机 URL 用作 LM Studio 和 Ollama +新手引导默认值，并且 `docker-compose.yml` 会在 Linux Docker Engine 上将 +`host.docker.internal` 映射到 Docker 的主机 Gateway 网关。Docker Desktop 已在 +macOS 和 Windows 上提供相同主机名。 -主机服务也必须监听 Docker 可访问的地址： +主机服务还必须监听 Docker 可访问的地址： ```bash lms server start --port 1234 --bind 0.0.0.0 @@ -241,58 +245,52 @@ OLLAMA_HOST=0.0.0.0:11434 ollama serve ### Bonjour / mDNS -Docker bridge 网络通常无法可靠转发 Bonjour/mDNS 组播 +Docker 桥接网络通常无法可靠转发 Bonjour/mDNS 多播 （`224.0.0.251:5353`）。因此，内置 Compose 设置默认使用 -`OPENCLAW_DISABLE_BONJOUR=1`，使 Gateway 网关在 bridge 丢弃组播流量时不会崩溃循环或反复重启广播。 +`OPENCLAW_DISABLE_BONJOUR=1`，避免 Gateway 网关在桥接网络丢弃多播流量时崩溃循环或反复重启广播。 -对于 Docker 主机，请使用已发布的 Gateway 网关 URL、Tailscale 或广域 DNS-SD。 -只有在使用 host networking、macvlan，或其他已知 mDNS 组播可以工作的网络时， -才设置 `OPENCLAW_DISABLE_BONJOUR=0`。 +Docker 主机请使用已发布的 Gateway 网关 URL、Tailscale 或广域 DNS-SD。 +只有在使用主机网络、macvlan 或其他已知 mDNS 多播可用的网络时，才设置 +`OPENCLAW_DISABLE_BONJOUR=0`。 -有关注意事项和故障排除，请参见 [Bonjour 发现](/zh-CN/gateway/bonjour)。 +有关注意事项和故障排除，请参见 [Bonjour 设备发现](/zh-CN/gateway/bonjour)。 ### 存储和持久化 Docker Compose 会将 `OPENCLAW_CONFIG_DIR` 绑定挂载到 `/home/node/.openclaw`， -并将 `OPENCLAW_WORKSPACE_DIR` 绑定挂载到 `/home/node/.openclaw/workspace`， -因此这些路径会在容器替换后保留下来。 +并将 `OPENCLAW_WORKSPACE_DIR` 绑定挂载到 `/home/node/.openclaw/workspace`，因此这些路径 +会在容器替换后保留。 -该挂载的配置目录是 OpenClaw 存放以下内容的位置： +该挂载的配置目录是 OpenClaw 保存以下内容的位置： - 用于行为配置的 `openclaw.json` -- 用于已存储提供商 OAuth/API-key 认证的 `agents//agent/auth-profiles.json` -- 用于环境变量支持的运行时密钥的 `.env`，例如 `OPENCLAW_GATEWAY_TOKEN` +- 用于已存储提供商 OAuth/API 密钥认证的 `agents//agent/auth-profiles.json` +- 用于环境变量支持的运行时密钥（如 `OPENCLAW_GATEWAY_TOKEN`）的 `.env` -内置插件运行时依赖和镜像的运行时文件属于生成状态，不是用户配置。Compose 会将它们存储在名为 -`openclaw-plugin-runtime-deps` 的 Docker 命名卷中，并挂载到 -`/var/lib/openclaw/plugin-runtime-deps`。将这个高频变更的目录树排除在主机配置绑定挂载之外， -可以避免缓慢的 Docker Desktop/WSL 文件操作，以及冷启动 Gateway 网关时陈旧的 Windows 句柄问题。 +内置插件运行时依赖和镜像运行时文件是生成状态，而不是用户配置。Compose 将它们存储在命名 Docker 卷 +`openclaw-plugin-runtime-deps` 中，挂载点为 +`/var/lib/openclaw/plugin-runtime-deps`。将这个高变更频率目录放在主机配置绑定挂载之外， +可避免 Docker Desktop/WSL 文件操作缓慢，以及冷启动 Gateway 网关期间出现过期的 +Windows 句柄。 -默认 Compose 文件会为 `openclaw-gateway` 和 `openclaw-cli` 都将 -`OPENCLAW_PLUGIN_STAGE_DIR` 设置为该路径，因此 `openclaw doctor --fix`、渠道 -登录/设置命令以及 Gateway 网关启动都会使用同一个生成运行时卷。 +默认 Compose 文件会为 `openclaw-gateway` 和 `openclaw-cli` 将 `OPENCLAW_PLUGIN_STAGE_DIR` 设置为该路径，因此 `openclaw doctor --fix`、渠道登录/设置命令以及 Gateway 网关启动都会使用同一个生成的运行时卷。 -有关 VM 部署上的完整持久化详情，请参阅 -[Docker VM 运行时 - 哪些内容持久化在哪里](/zh-CN/install/docker-vm-runtime#what-persists-where)。 +有关 VM 部署中完整的持久化详情，请参阅 [Docker VM 运行时 - 持久化内容的位置](/zh-CN/install/docker-vm-runtime#what-persists-where)。 -**磁盘增长热点：**关注 `media/`、会话 JSONL 文件、`cron/runs/*.jsonl`、 -`openclaw-plugin-runtime-deps` Docker 卷，以及 -`/tmp/openclaw/` 下的滚动文件日志。 +**磁盘增长热点：**留意 `media/`、会话 JSONL 文件、`cron/runs/*.jsonl`、`openclaw-plugin-runtime-deps` Docker 卷，以及 `/tmp/openclaw/` 下的滚动文件日志。 ### Shell 辅助工具（可选） -为了让日常 Docker 管理更方便，请安装 `ClawDock`： +为了更轻松地进行日常 Docker 管理，请安装 `ClawDock`： ```bash mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ``` -如果你此前从较旧的 `scripts/shell-helpers/clawdock-helpers.sh` 原始路径安装了 ClawDock，请重新运行上面的安装命令，让你的本地辅助工具文件跟踪新位置。 +如果你是从旧的 `scripts/shell-helpers/clawdock-helpers.sh` raw 路径安装 ClawDock，请重新运行上面的安装命令，让你的本地辅助文件跟踪新位置。 -然后使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等命令。运行 -`clawdock-help` 查看全部命令。 -完整辅助工具指南请参阅 [ClawDock](/zh-CN/install/clawdock)。 +然后使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等命令。运行 `clawdock-help` 查看所有命令。完整辅助工具指南请参阅 [ClawDock](/zh-CN/install/clawdock)。 @@ -301,7 +299,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ./scripts/docker/setup.sh ``` - 自定义套接字路径（例如无 root Docker）： + 自定义 socket 路径（例如 rootless Docker）： ```bash export OPENCLAW_SANDBOX=1 @@ -309,9 +307,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ./scripts/docker/setup.sh ``` - 该脚本只会在沙箱前置条件通过后挂载 `docker.sock`。如果 - 沙箱设置无法完成，脚本会将 `agents.defaults.sandbox.mode` - 重置为 `off`。 + 脚本只会在沙箱先决条件通过后挂载 `docker.sock`。如果沙箱设置无法完成，脚本会将 `agents.defaults.sandbox.mode` 重置为 `off`。 @@ -326,16 +322,11 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - `openclaw-cli` 使用 `network_mode: "service:openclaw-gateway"`，这样 CLI - 命令可以通过 `127.0.0.1` 访问 Gateway 网关。请将其视为共享的 - 信任边界。compose 配置会移除 `NET_RAW`/`NET_ADMIN`，并在 - `openclaw-cli` 上启用 - `no-new-privileges`。 + `openclaw-cli` 使用 `network_mode: "service:openclaw-gateway"`，因此 CLI 命令可以通过 `127.0.0.1` 访问 Gateway 网关。将其视为共享信任边界。compose 配置会移除 `NET_RAW`/`NET_ADMIN`，并在 `openclaw-cli` 上启用 `no-new-privileges`。 - 该镜像以 `node`（uid 1000）身份运行。如果你在 - `/home/node/.openclaw` 上看到权限错误，请确保你的主机绑定挂载归 uid 1000 所有： + 镜像以 `node`（uid 1000）运行。如果你在 `/home/node/.openclaw` 上看到权限错误，请确保主机 bind mount 归 uid 1000 所有： ```bash sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace @@ -344,9 +335,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - 调整你的 Dockerfile 顺序，让依赖层可以被缓存。这样除非锁文件发生变化， - 否则可以避免重新运行 - `pnpm install`： + 排列你的 Dockerfile，让依赖层可被缓存。这样除非 lockfile 变更，否则可以避免重新运行 `pnpm install`： ```dockerfile FROM node:24-bookworm @@ -369,56 +358,43 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - 默认镜像以安全优先，并以非 root 的 `node` 身份运行。对于功能更完整的容器： + 默认镜像以安全优先，并以非 root 的 `node` 身份运行。如需功能更完整的容器： 1. **持久化 `/home/node`**：`export OPENCLAW_HOME_VOLUME="openclaw_home"` - 2. **烘焙系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"` + 2. **预置系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"` 3. **安装 Playwright 浏览器**： ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` - 4. **持久化浏览器下载内容**：设置 - `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright`，并使用 - `OPENCLAW_HOME_VOLUME` 或 `OPENCLAW_EXTRA_MOUNTS`。 + 4. **持久化浏览器下载内容**：设置 `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright`，并使用 `OPENCLAW_HOME_VOLUME` 或 `OPENCLAW_EXTRA_MOUNTS`。 - 如果你在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL。在 - Docker 或无头设置中，请复制你最终到达的完整重定向 URL，并将其粘贴回 - 向导以完成认证。 + 如果你在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL。在 Docker 或无头设置中，复制你最终落到的完整重定向 URL，并将其粘贴回向导以完成认证。 - 主 Docker 运行时镜像使用 `node:24-bookworm-slim`，并发布 OCI - 基础镜像注解，包括 `org.opencontainers.image.base.name`、 - `org.opencontainers.image.source` 和其他注解。Node 基础摘要会 - 通过 Dependabot Docker 基础镜像 PR 刷新；发布构建不会运行 - 发行版升级层。请参阅 - [OCI 镜像注解](https://github.com/opencontainers/image-spec/blob/main/annotations.md)。 + 主 Docker 运行时镜像使用 `node:24-bookworm-slim`，并发布 OCI 基础镜像注解，包括 `org.opencontainers.image.base.name`、`org.opencontainers.image.source` 等。Node 基础摘要会通过 Dependabot Docker 基础镜像 PR 刷新；发布构建不会运行发行版升级层。请参阅 [OCI 镜像注解](https://github.com/opencontainers/image-spec/blob/main/annotations.md)。 ### 在 VPS 上运行？ -有关共享 VM 部署步骤，包括二进制烘焙、持久化和更新，请参阅 [Hetzner（Docker VPS）](/zh-CN/install/hetzner) 和 -[Docker VM 运行时](/zh-CN/install/docker-vm-runtime)。 +请参阅 [Hetzner（Docker VPS）](/zh-CN/install/hetzner) 和 [Docker VM 运行时](/zh-CN/install/docker-vm-runtime)，了解共享 VM 部署步骤，包括二进制预置、持久化和更新。 -## 智能体沙箱 +## Agent 沙箱 -当 `agents.defaults.sandbox` 通过 Docker 后端启用时，Gateway 网关会在隔离的 Docker -容器中运行智能体工具执行（shell、文件读写等），而 Gateway 网关本身仍留在主机上。这为不受信任或多租户的智能体会话提供了一道硬边界，而不需要将整个 -Gateway 网关容器化。 +当 `agents.defaults.sandbox` 通过 Docker 后端启用时，Gateway 网关会在隔离的 Docker 容器中运行智能体工具执行（shell、文件读/写等），而 Gateway 网关本身仍保留在主机上。这样可以在不将整个 Gateway 网关容器化的情况下，为不受信任或多租户的智能体会话提供硬隔离边界。 -沙箱作用域可以是按智能体（默认）、按会话或共享。每个作用域都有自己的工作区，挂载在 `/workspace`。你还可以配置 -允许/拒绝工具策略、网络隔离、资源限制和浏览器容器。 +沙箱范围可以是每智能体（默认）、每会话或共享。每个范围都会获得自己的工作区，并挂载在 `/workspace`。你还可以配置工具允许/拒绝策略、网络隔离、资源限制和浏览器容器。 有关完整配置、镜像、安全说明和多智能体配置文件，请参阅： - [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整沙箱参考 - [OpenShell](/zh-CN/gateway/openshell) -- 对沙箱容器的交互式 shell 访问 -- [多智能体沙箱和工具](/zh-CN/tools/multi-agent-sandbox-tools) -- 按智能体覆盖 +- [多智能体沙箱和工具](/zh-CN/tools/multi-agent-sandbox-tools) -- 每智能体覆盖项 ### 快速启用 @@ -445,29 +421,23 @@ scripts/sandbox-setup.sh - 使用 - [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) - 构建沙箱镜像，或将 `agents.defaults.sandbox.docker.image` 设置为你的自定义镜像。 - 容器会按会话在需要时自动创建。 + 使用 [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) 构建沙箱镜像，或将 `agents.defaults.sandbox.docker.image` 设置为你的自定义镜像。容器会按需为每个会话自动创建。 - 将 `docker.user` 设置为与你挂载工作区所有权匹配的 UID:GID， - 或对工作区文件夹运行 chown。 + 将 `docker.user` 设置为与你挂载的工作区所有权匹配的 UID:GID，或对工作区文件夹执行 chown。 - OpenClaw 使用 `sh -lc`（登录 shell）运行命令，它会加载 - `/etc/profile`，并且可能重置 PATH。设置 `docker.env.PATH` 来前置你的 - 自定义工具路径，或在你的 Dockerfile 中的 `/etc/profile.d/` 下添加脚本。 + OpenClaw 使用 `sh -lc`（login shell）运行命令，它会加载 `/etc/profile`，并且可能重置 PATH。设置 `docker.env.PATH` 以前置你的自定义工具路径，或在你的 Dockerfile 中将脚本添加到 `/etc/profile.d/` 下。 - - VM 至少需要 2 GB RAM。请使用更大的机器规格后重试。 + + VM 至少需要 2 GB RAM。使用更大的机器规格后重试。 - - 获取新的仪表盘链接，并批准浏览器设备： + + 获取新的 dashboard 链接并批准浏览器设备： ```bash docker compose run --rm openclaw-cli dashboard --no-open @@ -475,7 +445,7 @@ scripts/sandbox-setup.sh docker compose run --rm openclaw-cli devices approve ``` - 更多详情：[仪表盘](/zh-CN/web/dashboard)、[设备](/zh-CN/cli/devices)。 + 更多详情：[Dashboard](/zh-CN/web/dashboard)、[Devices](/zh-CN/cli/devices)。 @@ -490,7 +460,7 @@ scripts/sandbox-setup.sh -## 相关内容 +## 相关 - [安装概览](/zh-CN/install) — 所有安装方法 - [Podman](/zh-CN/install/podman) — Docker 的 Podman 替代方案