chore(i18n): refresh zh-CN translations

2026-04-24 23:47:06 +00:00 · 2026-04-24 23:47:06 +00:00 · 5bce178f8e
commit 5bce178f8e
parent 907d5925f6
2 changed files with 386 additions and 392 deletions
--- a/docs/zh-CN/gateway/configuration-reference.md
+++ b/docs/zh-CN/gateway/configuration-reference.md
@ -2,61 +2,61 @@
 read_when:
    - 你需要精确到字段级别的配置语义或默认值
    - 你正在验证渠道、模型、Gateway 网关或工具配置块
-summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键名、默认值，以及指向各专用子系统参考文档的链接
+summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向各专用子系统参考文档的链接
 title: 配置参考
 x-i18n:
-    generated_at: "2026-04-24T19:33:54Z"
+    generated_at: "2026-04-24T23:44:41Z"
    model: gpt-5.4
    provider: openai
-    source_hash: f54e51abc83dd7e72cc4220fa881f488cfb441b97710ba6852382814d4055344
+    source_hash: 94a945cbe0633c75e55b99324ae9174a7c82770b07bd773fe82f342f67c5a44c
    source_path: gateway/configuration-reference.md
    workflow: 15
 ---

-`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。
+`~/.openclaw/openclaw.json` 的核心配置参考。若需按任务组织的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。

-本页涵盖 OpenClaw 的主要配置表面，并在某个子系统拥有更深入的独立参考时提供链接。它**不会**尝试在单页中内联每个渠道/插件自有的命令目录，或每个深入的内存/QMD 调节项。
+本页介绍 OpenClaw 的主要配置面，并在某个子系统有自己更深入的参考文档时提供外部链接。它**不会**尝试在同一页内联列出每个渠道 / 插件自有的命令目录，也不会内联所有深层 memory / QMD 细项配置。

 代码事实来源：

- `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据
- `config.schema.lookup` 会返回一个按路径范围限定的 schema 节点，供向下钻取工具使用
- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面校验配置文档基线哈希
+- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置 / 插件 / 渠道元数据
+- `config.schema.lookup` 会返回单个按路径限定的 schema 节点，供下钻工具使用
+- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 面校验配置文档基线哈希

-专门的深度参考：
+专门的深度参考文档：

- [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
- [斜杠命令](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置插件命令目录
- 各自所属的渠道/插件页面，适用于渠道专属命令表面
+- [Memory configuration reference](/zh-CN/reference/memory-config)，用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
+- [Slash Commands](/zh-CN/tools/slash-commands)，用于查看当前内置 + 捆绑命令目录
+- 各自所属的渠道 / 插件页面，用于查看渠道特定的命令面

-配置格式为 **JSON5**（允许注释 + 尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。
+配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全默认值。

 ---

 ## 渠道

-每个渠道的配置键已移至独立页面——请参阅
-[配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`，
-其中包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 及其他
+每个渠道的配置键已移至独立页面——请参见
+[Configuration — channels](/zh-CN/gateway/config-channels) 了解 `channels.*`，
+其中包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 以及其他
 内置渠道（凭证、访问控制、多账号、提及门控）。

 ## 智能体默认值、多智能体、会话和消息

-已移至独立页面——请参阅
-[配置 — 智能体](/zh-CN/gateway/config-agents)，内容包括：
+已移至独立页面——请参见
+[Configuration — agents](/zh-CN/gateway/config-agents) 了解：

- `agents.defaults.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱）
- `multiAgent.*`（多智能体路由和绑定）
+- `agents.defaults.*`（工作区、模型、思考、心跳、memory、媒体、Skills、沙箱）
+- `multiAgent.*`（多智能体路由与绑定）
 - `session.*`（会话生命周期、压缩、清理）
 - `messages.*`（消息投递、TTS、Markdown 渲染）
 - `talk.*`（Talk 模式）
-  - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录内容前保留平台默认的停顿窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）
+  - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保留平台默认的停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）

 ## 工具和自定义提供商

 工具策略、实验性开关、由提供商支持的工具配置，以及自定义
-提供商 / base URL 设置已移至独立页面——请参阅
-[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。
+提供商 / base-URL 设置已移至独立页面——请参见
+[Configuration — tools and custom providers](/zh-CN/gateway/config-tools)。

 ## Skills

@ -83,12 +83,12 @@ x-i18n:
 }
 ```

- `allowBundled`：仅针对内置 skills 的可选允许列表（受管/workspace skills 不受影响）。
- `load.extraDirs`：额外的共享 skill 根目录（优先级最低）。
- `install.preferBrew`：设为 true 时，若 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。
+- `allowBundled`：仅对内置 Skills 生效的可选允许列表（托管 / 工作区 Skills 不受影响）。
+- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。
+- `install.preferBrew`：当为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。
 - `install.nodeManager`：用于 `metadata.openclaw.install` 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
- `entries.<skillKey>.enabled: false`：即使 skill 已内置/已安装，也会禁用该 skill。
- `entries.<skillKey>.apiKey`：为声明主要环境变量的 skills 提供的便捷字段（明文字符串或 SecretRef 对象）。
+- `entries.<skillKey>.enabled: false`：即使某个 skill 已内置 / 安装，也会将其禁用。
+- `entries.<skillKey>.apiKey`：为声明了主环境变量的 skill 提供的便捷字段（明文字符串或 SecretRef 对象）。

 ---

@ -118,42 +118,42 @@ x-i18n:

 - 从 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions` 以及 `plugins.load.paths` 加载。
 - 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。
- **配置变更需要重启 Gateway 网关。**
- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先生效。
- `plugins.entries.<id>.apiKey`：插件级 API 密钥便捷字段（插件支持时可用）。
+- **配置更改需要重启 Gateway 网关。**
+- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。
+- `plugins.entries.<id>.apiKey`：插件级 API 密钥便捷字段（当插件支持时）。
 - `plugins.entries.<id>.env`：插件作用域的环境变量映射。
- `plugins.entries.<id>.hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子，以及受支持的 bundle 提供的钩子目录。
- `plugins.entries.<id>.hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可从 `llm_input`、`llm_output` 和 `agent_end` 等类型化钩子中读取原始对话内容。
- `plugins.entries.<id>.subagent.allowModelOverride`：显式信任该插件可在后台子智能体运行时请求按次运行的 `provider` 和 `model` 覆盖。
- `plugins.entries.<id>.subagent.allowedModels`：受信任子智能体覆盖可用的规范 `provider/model` 目标可选允许列表。仅在你有意允许任意模型时才使用 `"*"`。
+- `plugins.entries.<id>.hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的 bundle 提供的 hook 目录。
+- `plugins.entries.<id>.hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可从类型化钩子（如 `llm_input`、`llm_output` 和 `agent_end`）读取原始对话内容。
+- `plugins.entries.<id>.subagent.allowModelOverride`：显式信任此插件，使其可为后台子智能体运行请求逐次运行的 `provider` 和 `model` 覆盖。
+- `plugins.entries.<id>.subagent.allowedModels`：受信任子智能体覆盖可使用的规范 `provider/model` 目标的可选允许列表。仅当你明确想允许任意模型时才使用 `"*"`。
 - `plugins.entries.<id>.config`：插件定义的配置对象（若可用，则由原生 OpenClaw 插件 schema 验证）。
- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取提供商设置。
-  - `apiKey`：Firecrawl API 密钥（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。
+- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。
+  - `apiKey`：Firecrawl API 密钥（接受 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 天）。
+  - `maxAgeMs`：缓存的最长保留时间（毫秒）（默认：`172800000` / 2 天）。
  - `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。
- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok 网页搜索）设置。
+- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。
  - `enabled`：启用 X Search 提供商。
-  - `model`：搜索使用的 Grok 模型（例如 `"grok-4-1-fast"`）。
- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。阶段和阈值请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
+  - `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 * * *"`）。
  - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。
- 完整的内存配置见 [内存配置参考](/zh-CN/reference/memory-config)：
+- 完整的 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)：
  - `agents.defaults.memorySearch.*`
  - `memory.backend`
  - `memory.citations`
  - `memory.qmd.*`
  - `plugins.entries.memory-core.config.dreaming`
- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供内嵌的 Pi 默认值；OpenClaw 会将其作为净化后的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。
- `plugins.slots.memory`：选择活动内存插件 id，或设为 `"none"` 以禁用内存插件。
- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。
+- 已启用的 Claude bundle 插件也可通过 `settings.json` 提供内嵌的 Pi 默认值；OpenClaw 会将其作为已清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。
+- `plugins.slots.memory`：选择活动的 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。
+- `plugins.slots.contextEngine`：选择活动的 context engine 插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。
 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。
  - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。
-  - 将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令而不是手动编辑。
+  - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。

-参阅 [插件](/zh-CN/tools/plugin)。
+请参见 [Plugins](/zh-CN/tools/plugin)。

 ---

@ -194,22 +194,22 @@ x-i18n:
 ```

 - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。
- 未设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork` 时，该项默认为禁用，因此浏览器导航默认保持严格模式。
- 仅当你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止策略约束。
- `ssrfPolicy.allowPrivateNetwork` 仍然作为旧版别名受支持。
- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。
- 远程配置文件为仅附加模式（禁用 start/stop/reset）。
+- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时处于禁用状态，因此默认会严格限制浏览器导航。
+- 仅当你明确信任私有网络浏览器导航时，才设置 `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)。
- `existing-session` 配置文件使用 Chrome MCP 而非 CDP，并且可以附加到所选主机上，或通过已连接的浏览器节点附加。
- `existing-session` 配置文件可设置 `userDataDir`，以定位特定的基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。
- `existing-session` 配置文件保留当前的 Chrome MCP 路由限制：使用快照/引用驱动的操作而非 CSS 选择器定位、单文件上传钩子、不支持对话框超时覆盖、不支持 `wait --load networkidle`，以及不支持 `responsebody`、PDF 导出、下载拦截或批量操作。
- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下才显式设置 `cdpUrl`。
+- `existing-session` 配置文件使用 Chrome MCP 而非 CDP，可附加到所选主机上，或通过已连接的浏览器节点附加。
+- `existing-session` 配置文件可设置 `userDataDir`，以指定特定的基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。
+- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：使用 snapshot / ref 驱动的操作而非 CSS 选择器定位、单文件上传钩子、不支持对话框超时覆盖、不支持 `wait --load networkidle`，且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。
+- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下显式设置 `cdpUrl`。
 - 自动检测顺序：默认浏览器（若基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
- 控制服务：仅限 loopback（端口派生自 `gateway.port`，默认值为 `18791`）。
- `extraArgs` 会为本地 Chromium 启动附加额外的启动标志（例如 `--disable-gpu`、窗口尺寸或调试标志）。
+- 控制服务：仅限 loopback（端口从 `gateway.port` 派生，默认 `18791`）。
+- `extraArgs` 会将额外启动标志附加到本地 Chromium 启动命令中（例如 `--disable-gpu`、窗口大小设置或调试标志）。

 ---

@ -227,8 +227,8 @@ x-i18n:
 }
 ```

- `seamColor`：原生应用 UI 外框的强调色（Talk 模式气泡着色等）。
- `assistant`：Control UI 身份覆盖。会回退到当前活动智能体身份。
+- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡色调等）。
+- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。

 ---

@ -275,10 +275,10 @@ x-i18n:
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
-    // 可选。默认值为 false。
+    // 可选。默认 false。
    allowRealIpFallback: false,
    tools: {
-      // 额外的 /tools/invoke HTTP 拒绝项
+      // 对 /tools/invoke HTTP 的额外拒绝项
      deny: ["browser"],
      // 从默认 HTTP 拒绝列表中移除工具
      allow: ["gateway"],
@ -301,46 +301,45 @@ x-i18n:
 - `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。
 - **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关将无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以在所有接口上监听。
- **认证**：默认必需。非 loopback bind 要求 Gateway 网关认证。实际来说，这意味着需要共享 token/password，或使用设置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成一个 token。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。当两者都已配置但 mode 未设置时，启动以及服务安装/修复流程都会失败。
- `gateway.auth.mode: "none"`：显式无认证模式。仅可用于受信任的本地 local loopback 设置；新手引导提示中不会主动提供此选项。
- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（见 [可信代理认证](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。
- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头部认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。此无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。
- `gateway.auth.rateLimit`：可选的认证失败限制器。按客户端 IP 和认证作用域生效（共享密钥和设备 token 分别独立跟踪）。被阻止的请求会返回 `429` + `Retry-After`。
-  - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败请求会在写入失败记录前串行化。因此，同一客户端的并发错误请求可能会在第二个请求时触发限制器，而不是两个请求都像普通不匹配那样同时穿过。
-  - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你有意也要对 localhost 流量实施速率限制（例如测试环境或严格代理部署），请设为 `false`。
- 来自浏览器源的 WS 认证尝试始终会启用限流，且不会豁免 loopback（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。
- 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin`
-  值隔离，因此来自某个 localhost 源的重复失败不会自动
-  锁定另一个不同的源。
- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。
- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预期浏览器客户端来自非 loopback 源时，这是必需的。
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 头部源策略的部署启用基于 Host 头的源回退。
+- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。
+- **凭证**：默认必须启用。非 loopback 的 bind 要求 Gateway 网关凭证。实际使用中，这意味着共享 token / password，或设置 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成 token。
+- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设为 `token` 或 `password`。如果两者都已配置且 mode 未设置，启动以及服务安装 / 修复流程都会失败。
+- `gateway.auth.mode: "none"`：显式无凭证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会提供此选项。
+- `gateway.auth.mode: "trusted-proxy"`：将凭证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份头（见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求代理来源为**非 loopback**；同主机 loopback 反向代理不满足 trusted-proxy 凭证要求。
+- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份头可满足 Control UI / WebSocket 凭证要求（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头部凭证；它们仍遵循 Gateway 网关的常规 HTTP 凭证模式。当 `tailscale.mode = "serve"` 时，默认值为 `true`。这种无 token 流程假定 Gateway 网关主机是受信任的。
+- `gateway.auth.rateLimit`：可选的凭证失败限流器。按客户端 IP 和凭证作用域应用（共享密钥和设备 token 分别独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。
+  - 在异步 Tailscale Serve Control UI 路径中，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前串行化。因此，同一客户端并发发起的错误尝试可能会在第二个请求时触发限流，而不是两个请求都作为普通不匹配并发通过。
+  - `gateway.auth.rateLimit.exemptLoopback` 默认是 `true`；如果你明确希望连 localhost 流量也受到限流（例如测试环境或严格代理部署），请设为 `false`。
+- 来自浏览器来源的 WS 凭证尝试始终会启用限流，且不会豁免 loopback（作为对基于浏览器的 localhost 暴力破解的纵深防御）。
+- 在 loopback 上，这些来自浏览器来源的锁定会按归一化后的 `Origin`
+  值隔离，因此某个 localhost 来源的重复失败不会自动
+  锁定另一个来源。
+- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `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`：客户端进程环境中的紧急放行开关，允许明文 `ws://` 连接到受信任的私有网络 IP；默认仍只允许 loopback 使用明文。没有与之对应的 `openclaw.json` 配置项，而且诸如
-  `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 之类的浏览器私有网络配置也不会影响 Gateway 网关 WebSocket 客户端。
- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。
- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。
+- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量中的紧急放开开关，允许对受信任私有网络 IP 使用明文 `ws://`；默认情况下，明文连接仍仅限 loopback。`openclaw.json` 中没有等价配置，且浏览器私有网络配置（例如 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`）不会影响 Gateway 网关 WebSocket 客户端。
+- `gateway.remote.token` / `.password`：远程客户端凭证字段。它们本身不会配置 Gateway 网关凭证。
+- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方 / TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。
 - `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值为 `10000`。
- 基于 relay 的注册会委派给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，将该身份包含在 relay 注册中，并将针对该注册范围的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储的注册。
+- 基于 relay 的注册会委托给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将基于注册范围的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。
 - `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：用于覆盖上述 relay 配置的临时环境变量。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发环境的逃生开关，用于允许 loopback HTTP relay URL。生产环境 relay URL 应保持使用 HTTPS。
- `gateway.channelHealthCheckMinutes`：渠道健康监视器间隔，单位为分钟。设为 `0` 可全局禁用健康监视器重启。默认值：`5`。
- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。应保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内允许的最大健康监视器重启次数。默认值：`10`。
- `channels.<provider>.healthMonitor.enabled`：在保持全局监视器启用的情况下，按渠道选择退出健康监视器重启。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，它的优先级高于渠道级覆盖。
- 本地 Gateway 网关调用路径仅在 `gateway.auth.*` 未设置时，才能使用 `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.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。
+- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的放开开关，允许 loopback HTTP relay URL。生产环境的 relay URL 应保持为 HTTPS。
+- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。
+- `gateway.channelStaleEventThresholdMinutes`：陈旧套接字阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
+- `gateway.channelMaxRestartsPerHour`：每个渠道 / 账号在滚动一小时内的最大健康监控重启次数。默认值：`10`。
+- `channels.<provider>.healthMonitor.enabled`：渠道级退出设置，用于在保留全局监控启用的情况下禁用健康监控重启。
+- `channels.<provider>.accounts.<accountId>.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.tools.deny`：针对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。
 - `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。

 </Accordion>

-### 与 OpenAI 兼容的端点
+### OpenAI 兼容端点

 - Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。
 - Responses API：`gateway.http.endpoints.responses.enabled`。
@ -348,14 +347,14 @@ x-i18n:
  - `gateway.http.endpoints.responses.maxUrlParts`
  - `gateway.http.endpoints.responses.files.urlAllowlist`
  - `gateway.http.endpoints.responses.images.urlAllowlist`
-    空的允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false`
-    和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。
+    空允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false`
+    和 / 或 `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 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）

 ### 多实例隔离

-在同一主机上运行多个 Gateway 网关实例时，请使用唯一的端口和状态目录：
+在同一主机上运行多个 Gateway 网关时，请使用唯一的端口和状态目录：

 ```bash
 OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
@ -363,9 +362,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \
 openclaw gateway --port 19001
 ```

-便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile <name>`（使用 `~/.openclaw-<name>`）。
+便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`），`--profile <name>`（使用 `~/.openclaw-<name>`）。

-参阅 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。
+请参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。

 ### `gateway.tls`

@ -383,11 +382,11 @@ openclaw gateway --port 19001
 }
 ```

- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。
- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅用于本地/开发环境。
+- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS / WSS）（默认：`false`）。
+- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书 / 密钥对；仅供本地 / 开发使用。
 - `certPath`：TLS 证书文件的文件系统路径。
- `keyPath`：TLS 私钥文件的文件系统路径；应限制访问权限。
- `caPath`：可选 CA bundle 路径，用于客户端验证或自定义信任链。
+- `keyPath`：TLS 私钥文件的文件系统路径；请限制其权限。
+- `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。

 ### `gateway.reload`

@ -403,17 +402,17 @@ openclaw gateway --port 19001
 }
 ```

- `mode`：控制运行时如何应用配置编辑。
-  - `"off"`：忽略实时编辑；变更需要显式重启。
+- `mode`：控制如何在运行时应用配置编辑。
+  - `"off"`：忽略实时编辑；更改需要显式重启。
  - `"restart"`：配置变更时始终重启 Gateway 网关进程。
-  - `"hot"`：在不重启的情况下于进程内应用变更。
-  - `"hybrid"`（默认）：优先尝试热重载；如有需要则回退为重启。
+  - `"hot"`：在不重启的情况下于进程内应用更改。
+  - `"hybrid"`（默认）：先尝试热重载；如有需要则回退为重启。
 - `debounceMs`：应用配置变更前的防抖窗口（毫秒）（非负整数）。
 - `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最长时间（毫秒）（默认：`300000` = 5 分钟）。

 ---

-## Hooks
+## 钩子

 ```json5
 {
@ -446,47 +445,47 @@ openclaw gateway --port 19001
 }
 ```

-认证：`Authorization: Bearer <token>` 或 `x-openclaw-token: <token>`。
-会拒绝查询字符串中的 hook token。
+凭证：`Authorization: Bearer <token>` 或 `x-openclaw-token: <token>`。
+不接受查询字符串中的 hook token。

 验证与安全说明：

- `hooks.enabled=true` 要求提供非空的 `hooks.token`。
+- `hooks.enabled=true` 要求 `hooks.token` 为非空。
 - `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。
 - `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。
- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
- 如果某个 mapping 或 preset 使用了模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态 mapping 键不需要该显式启用项。
+- 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
+- 如果某个 mapping 或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态 mapping 键不需要此显式启用。

 **端点：**

 - `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/<name>` → 通过 `hooks.mappings` 解析
  - 模板渲染后的 mapping `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。

 <Accordion title="Mapping 详情">

 - `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。
- `match.source` 匹配通用路径中的某个载荷字段。
- 像 `{{messages[0].subject}}` 这样的模板会从载荷中读取。
- `transform` 可以指向一个返回 hook action 的 JS/TS 模块。
-  - `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 内（绝对路径和路径穿越都会被拒绝）。
+- `match.source` 匹配通用路径的某个负载字段。
+- 类似 `{{messages[0].subject}}` 的模板会从负载中读取。
+- `transform` 可以指向返回 hook action 的 JS / TS 模块。
+  - `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。
 - `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。
 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。
 - `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的 hook 智能体运行。
- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的 mapping 会话键设置 `sessionKey`（默认：`false`）。
- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + mapping）的可选前缀允许列表，例如 `["hook:"]`。当任意 mapping 或 preset 使用模板化 `sessionKey` 时，它会变成必填项。
- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。
- `model` 会覆盖本次 hook 运行所用的 LLM（如果设置了模型目录，则该模型必须被允许）。
+- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的 mapping 会话键设置 `sessionKey`（默认：`false`）。
+- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + mapping）的可选前缀允许列表，例如 `["hook:"]`。当任意 mapping 或 preset 使用模板化 `sessionKey` 时，它会成为必填项。
+- `deliver: true` 会将最终回复发送到渠道；`channel` 默认为 `last`。
+- `model` 会覆盖此次 hook 运行所用的 LLM（如果设置了模型目录，则该模型必须被允许）。

 </Accordion>

 ### Gmail 集成

- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖 preset，而不是使用默认的模板化值。
+- 内置的 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
+- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并限制 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
+- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖 preset，而不是使用默认的模板值。

 ```json5
 {
@ -509,8 +508,8 @@ 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`。

 ---

@ -526,18 +525,18 @@ openclaw gateway --port 19001
 }
 ```

- 在 Gateway 网关端口下通过 HTTP 提供可由智能体编辑的 HTML/CSS/JS 和 A2UI：
+- 通过 Gateway 网关端口下的 HTTP 提供可由智能体编辑的 HTML / CSS / JS 和 A2UI：
  - `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
  - `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
 - 仅限本地：保持 `gateway.bind: "loopback"`（默认）。
- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 表面一样，都需要 Gateway 网关认证（token/password/trusted-proxy）。
- Node WebView 通常不会发送认证头；在节点完成配对并连接后，Gateway 网关会通告节点作用域的 capability URL，用于访问 canvas/A2UI。
- capability URL 绑定到当前活动的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。
- 会向所提供的 HTML 注入 live-reload 客户端。
+- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面一样，需要 Gateway 网关凭证（token / password / trusted-proxy）。
+- Node WebView 通常不会发送凭证头；在某个 node 完成配对并连接后，Gateway 网关会为 canvas / A2UI 访问发布 node 作用域的 capability URL。
+- Capability URL 绑定到活动的 node WS 会话，并且很快过期。不使用基于 IP 的回退。
+- 会将 live-reload 客户端注入到所提供的 HTML 中。
 - 为空时会自动创建初始 `index.html`。
- 同时也会在 `/__openclaw__/a2ui/` 提供 A2UI。
+- 还会在 `/__openclaw__/a2ui/` 提供 A2UI。
 - 更改需要重启 Gateway 网关。
- 对于大型目录或 `EMFILE` 错误，请禁用 live reload。
+- 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。

 ---

@ -555,7 +554,7 @@ openclaw gateway --port 19001
 }
 ```

- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。
+- `minimal`（默认）：在 TXT 记录中省略 `cliPath` + `sshPort`。
 - `full`：包含 `cliPath` + `sshPort`。
 - 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。

@ -569,7 +568,7 @@ openclaw gateway --port 19001
 }
 ```

-会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS 使用。
+在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若要实现跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）和 Tailscale split DNS。

 设置：`openclaw dns setup --apply`。

@ -595,9 +594,9 @@ openclaw gateway --port 19001
 ```

 - 仅当进程环境中缺少对应键时，才会应用内联环境变量。
- `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。
+- `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖已有变量）。
 - `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。
- 完整优先级请参阅 [环境](/zh-CN/help/environment)。
+- 完整优先级请参见 [Environment](/zh-CN/help/environment)。

 ### 环境变量替换

@ -612,19 +611,19 @@ openclaw gateway --port 19001
 ```

 - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。
- 缺失/为空的变量会在配置加载时抛出错误。
- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。
+- 缺失 / 为空的变量会在配置加载时报错。
+- 若要输出字面量 `${VAR}`，请使用 `$${VAR}` 转义。
 - 适用于 `$include`。

 ---

-## 密钥
+## Secrets

-Secret ref 是增量支持的：明文值仍然可用。
+SecretRef 是增量特性：明文值仍然可用。

 ### `SecretRef`

-使用以下对象形状之一：
+使用以下对象结构之一：

 ```json5
 { source: "env" | "file" | "exec", provider: "default", id: "..." }
@ -633,18 +632,18 @@ Secret ref 是增量支持的：明文值仍然可用。
 验证规则：

 - `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: "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 pointer（例如 `"/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` 凭证路径。
+- 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)
+- `secrets apply` 会定位到受支持的 `openclaw.json` 凭证路径。
 - `auth-profiles.json` 中的 ref 也包含在运行时解析和审计覆盖范围内。

-### Secret 提供商配置
+### Secret providers 配置

 ```json5
 {
@ -674,18 +673,18 @@ Secret ref 是增量支持的：明文值仍然可用。

 说明：

- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。
- 当 Windows ACL 验证不可用时，文件和 exec 提供商路径会采用失败即关闭的策略。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。
- `exec` 提供商要求 `command` 使用绝对路径，并通过 stdin/stdout 使用协议载荷。
- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍会验证解析后的目标路径。
+- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。
+- 当无法验证 Windows ACL 时，file 和 exec provider 路径会以失败关闭方式处理。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。
+- `exec` provider 要求 `command` 为绝对路径，并通过 stdin / stdout 使用协议负载。
+- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍会验证解析后的目标路径。
 - 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。
- 默认情况下，`exec` 子进程环境是最小化的；请通过 `passEnv` 显式传入所需变量。
- Secret ref 会在激活时解析为内存中的快照，之后请求路径只读取该快照。
- 激活期间会应用活动表面过滤：已启用表面上的未解析 ref 会导致启动/重载失败，而非活动表面会被跳过并附带诊断信息。
+- 默认情况下，`exec` 子进程环境最小化；请通过 `passEnv` 显式传入所需变量。
+- Secret ref 会在激活时解析为内存快照，之后请求路径只读取该快照。
+- 激活期间会应用活动面过滤：已启用面的未解析 ref 会导致启动 / 重载失败，而未激活的面会跳过并附带诊断信息。

 ---

-## 认证存储
+## 凭证存储

 ```json5
 {
@ -703,13 +702,13 @@ Secret ref 是增量支持的：明文值仍然可用。
 }
 ```

- 每个智能体的配置文件存储在 `<agentDir>/auth-profiles.json`。
- `auth-profiles.json` 支持静态凭证模式下的值级 ref（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
- OAuth 模式配置文件（`auth.profiles.<id>.mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。
- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会进行清理。
+- 每个智能体的 profile 存储在 `<agentDir>/auth-profiles.json`。
+- `auth-profiles.json` 支持值级 ref（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
+- OAuth 模式的 profile（`auth.profiles.<id>.mode = "oauth"`）不支持由 SecretRef 提供支持的 auth-profile 凭证。
+- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会清理掉。
 - 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。
- 参阅 [OAuth](/zh-CN/concepts/oauth)。
- Secrets 运行时行为以及 `audit/configure/apply` 工具：参阅 [Secrets Management](/zh-CN/gateway/secrets)。
+- 请参见 [OAuth](/zh-CN/concepts/oauth)。
+- Secrets 运行时行为以及 `audit/configure/apply` 工具：请参见 [Secrets Management](/zh-CN/gateway/secrets)。

 ### `auth.cooldowns`

@ -731,15 +730,15 @@ Secret ref 是增量支持的：明文值仍然可用。
 }
 ```

- `billingBackoffHours`：当某个配置文件因真实的计费/余额不足错误而失败时使用的基础退避时长（小时）（默认：`5`）。即使在 `401`/`403` 响应上，明确的计费文本仍可能归入这里，但提供商特定的文本匹配器仍会限定在拥有它们的提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或组织/workspace 支出上限消息则仍归入 `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` 用量窗口或 organization / workspace 支出上限消息则仍归入 `rate_limit` 路径。
+- `billingBackoffHoursByProvider`：按提供商覆盖计费退避小时数的可选配置。
+- `billingMaxHours`：计费退避指数增长的小时上限（默认：`24`）。
+- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时间（分钟）（默认：`10`）。
+- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟上限（默认：`60`）。
+- `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认：`24`）。
+- `overloadedProfileRotations`：对于过载错误，在切换到模型回退前，同一提供商 auth-profile 允许轮换的最大次数（默认：`1`）。像 `ModelNotReadyException` 这样的提供商忙碌形态归入此项。
+- `overloadedBackoffMs`：重试过载的提供商 / profile 轮换前的固定延迟（毫秒）（默认：`0`）。
+- `rateLimitedProfileRotations`：对于速率限制错误，在切换到模型回退前，同一提供商 auth-profile 允许轮换的最大次数（默认：`1`）。该速率限制桶包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。

 ---

@ -759,9 +758,9 @@ Secret ref 是增量支持的：明文值仍然可用。
 ```

 - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。
- 设置 `logging.file` 以使用稳定路径。
- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。
- `maxFileBytes`：在停止写入前，日志文件允许的最大大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。
+- 设置 `logging.file` 可使用稳定路径。
+- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。
+- `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。

 ---

@ -785,6 +784,14 @@ Secret ref 是增量支持的：明文值仍然可用。
      logs: false,
      sampleRate: 1.0,
      flushIntervalMs: 5000,
+      captureContent: {
+        enabled: false,
+        inputMessages: false,
+        outputMessages: false,
+        toolInputs: false,
+        toolOutputs: false,
+        systemPrompt: false,
+      },
    },

    cacheTrace: {
@ -798,20 +805,21 @@ Secret ref 是增量支持的：明文值仍然可用。
 }
 ```

- `enabled`：仪表化输出的总开关（默认：`true`）。
+- `enabled`：instrumentation 输出的总开关（默认：`true`）。
 - `flags`：启用定向日志输出的标志字符串数组（支持通配符，如 `"telegram.*"` 或 `"*"`）。
- `stuckSessionWarnMs`：当会话保持在处理中状态时，发出卡住会话警告的年龄阈值（毫秒）。
- `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。
- `otel.endpoint`：OTel 导出的收集器 URL。
+- `stuckSessionWarnMs`：当会话仍处于处理中状态时，发出卡住会话警告的时长阈值（毫秒）。
+- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。
+- `otel.endpoint`：OTel 导出的 collector URL。
 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。
- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据头。
+- `otel.headers`：随 OTel 导出请求发送的额外 HTTP / gRPC 元数据头。
 - `otel.serviceName`：资源属性中的服务名称。
- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。
+- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。
 - `otel.sampleRate`：trace 采样率，范围 `0`–`1`。
- `otel.flushIntervalMs`：定期刷新遥测数据的间隔（毫秒）。
+- `otel.flushIntervalMs`：周期性刷新 telemetry 的间隔（毫秒）。
+- `otel.captureContent`：为 OTEL span 属性选择性启用原始内容捕获。默认关闭。布尔值 `true` 会捕获非 system 的消息 / 工具内容；对象形式可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
 - `cacheTrace.enabled`：为嵌入式运行记录缓存追踪快照（默认：`false`）。
 - `cacheTrace.filePath`：缓存追踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含的内容（默认均为 `true`）。
+- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含的内容（默认全部为 `true`）。

 ---

@ -833,11 +841,11 @@ Secret ref 是增量支持的：明文值仍然可用。
 }
 ```

- `channel`：用于 npm/git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。
+- `channel`：用于 npm / git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。
 - `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。
 - `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。
- `auto.stableDelayHours`：稳定渠道自动应用前的最小时延（小时）（默认：`6`；最大：`168`）。
- `auto.stableJitterHours`：稳定渠道发布扩散窗口的额外时长（小时）（默认：`12`；最大：`168`）。
+- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟（小时）（默认：`6`；最大：`168`）。
+- `auto.stableJitterHours`：稳定渠道额外的发布扩散时间窗口（小时）（默认：`12`；最大：`168`）。
 - `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时）（默认：`1`；最大：`24`）。

 ---
@ -874,19 +882,19 @@ Secret ref 是增量支持的：明文值仍然可用。
 - `enabled`：全局 ACP 功能开关（默认：`false`）。
 - `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在阻止执行的同时保留 ACP 命令可用。
 - `backend`：默认 ACP 运行时后端 id（必须匹配已注册的 ACP 运行时插件）。
- `defaultAgent`：当生成的任务未指定显式目标时使用的 ACP 回退目标智能体 id。
+- `defaultAgent`：当 spawn 未指定显式目标时使用的 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.maxChunkChars`：流式分块投影在拆分前允许的最大块大小。
+- `stream.repeatSuppression`：每轮抑制重复的状态 / 工具行（默认：`true`）。
+- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终结事件后再输出。
+- `stream.hiddenBoundarySeparator`：隐藏工具事件后、可见文本前的分隔符（默认：`"paragraph"`）。
 - `stream.maxOutputChars`：每个 ACP 轮次投影的助手输出最大字符数。
- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行最大字符数。
- `stream.tagVisibility`：标签名称到布尔可见性覆盖的记录，用于流式事件。
- `runtime.ttlMinutes`：ACP 会话 worker 在可被清理前的空闲 TTL（分钟）。
- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。
+- `stream.maxSessionUpdateChars`：ACP 状态 / 更新行投影的最大字符数。
+- `stream.tagVisibility`：tag 名称到布尔可见性覆盖的记录，用于流式事件。
+- `runtime.ttlMinutes`：ACP 会话 worker 在符合清理条件前的空闲 TTL（分钟）。
+- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。

 ---

@ -902,11 +910,11 @@ Secret ref 是增量支持的：明文值仍然可用。
 }
 ```

- `cli.banner.taglineMode` 控制横幅标语样式：
-  - `"random"`（默认）：轮换的有趣/季节性标语。
-  - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。
-  - `"off"`：不显示标语文本（仍显示横幅标题/版本）。
- 若要隐藏整个横幅（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
+- `cli.banner.taglineMode` 控制 banner 标语样式：
+  - `"random"`（默认）：轮换显示有趣 / 季节性标语。
+  - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。
+  - `"off"`：不显示标语文本（仍显示 banner 标题 / 版本）。
+- 若要隐藏整个 banner（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。

 ---

@ -930,13 +938,13 @@ Secret ref 是增量支持的：明文值仍然可用。

 ## 身份

-请参阅 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下 `agents.list` 的身份字段。
+请参见 [Agent defaults](/zh-CN/gateway/config-agents#agent-defaults) 下 `agents.list` 的身份字段。

 ---

-## Bridge protocol（旧版节点，历史参考）（旧版，已移除）
+## Bridge protocol（旧版节点，历史参考）

-当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可清除未知键）。
+当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除之前验证会失败；`openclaw doctor --fix` 可移除未知键）。

 <Accordion title="旧版 bridge 配置（历史参考）">

@ -976,11 +984,11 @@ Secret ref 是增量支持的：明文值仍然可用。
 }
 ```

- `sessionRetention`：从 `sessions.json` 中清理前，已完成的隔离 cron 运行会话会保留多久。它也控制已归档的已删除 cron 转录内容的清理。默认值：`24h`；设为 `false` 可禁用。
- `runLog.maxBytes`：每个运行日志文件（`cron/runs/<jobId>.jsonl`）在开始裁剪前的最大大小。默认值：`2_000_000` 字节。
- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认值：`2000`。
- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；如果省略，则不会发送认证头。
- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍保留 `notify: true` 的已存储任务。
+- `sessionRetention`：在从 `sessions.json` 中清理之前，保留已完成隔离 cron 运行会话的时长。也控制已归档的已删除 cron transcript 的清理。默认：`24h`；设为 `false` 可禁用。
+- `runLog.maxBytes`：每个运行日志文件（`cron/runs/<jobId>.jsonl`）在触发裁剪前的最大大小。默认：`2_000_000` 字节。
+- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认：`2000`。
+- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略则不会发送凭证头。
+- `webhook`：已弃用的旧版回退 webhook URL（http / https），仅用于仍具有 `notify: true` 的已存储任务。

 ### `cron.retry`

@ -996,11 +1004,11 @@ Secret ref 是增量支持的：明文值仍然可用。
 }
 ```

- `maxAttempts`：一次性任务在临时错误下允许的最大重试次数（默认：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试使用的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。
- `retryOn`：会触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会重试所有临时类型。
+- `maxAttempts`：一次性任务在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。
+- `backoffMs`：每次重试尝试的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。
+- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则重试所有瞬时类型。

-仅适用于一次性 cron 任务。周期性任务使用单独的失败处理方式。
+仅适用于一次性 cron 任务。周期性任务使用单独的失败处理机制。

 ### `cron.failureAlert`

@ -1021,7 +1029,7 @@ Secret ref 是增量支持的：明文值仍然可用。
 - `enabled`：启用 cron 任务失败告警（默认：`false`）。
 - `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。
 - `cooldownMs`：同一任务重复告警之间的最小间隔（毫秒）（非负整数）。
- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发起 POST。
+- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置 webhook 发起 POST。
 - `accountId`：可选的账号或渠道 id，用于限定告警投递范围。

 ### `cron.failureDestination`
@ -1039,16 +1047,16 @@ Secret ref 是增量支持的：明文值仍然可用。
 }
 ```

- 所有任务共用的 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.failureDestination` 会覆盖该全局默认值。
+- 当既未设置全局失败目标，也未设置每个任务的失败目标时，已通过 `announce` 投递的任务在失败时会回退到其主 announce 目标。
 - `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的任务，除非该任务的主 `delivery.mode` 为 `"webhook"`。

-参阅 [Cron 任务](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。
+请参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。

 ---

@ -1056,34 +1064,34 @@ Secret ref 是增量支持的：明文值仍然可用。

 在 `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}}`   | 发送者电话号码（尽力而为） |
+| Variable           | Description                          |
+| ------------------ | ------------------------------------ |
+| `{{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`）
+## 配置 includes（`$include`）

-将配置拆分到多个文件中：
+将配置拆分为多个文件：

 ```json5
 // ~/.openclaw/openclaw.json
@ -1100,18 +1108,18 @@ Secret ref 是增量支持的：明文值仍然可用。

 - 单个文件：替换其所在的包含对象。
 - 文件数组：按顺序深度合并（后者覆盖前者）。
- 同级键：在 include 之后合并（覆盖被包含的值）。
- 嵌套 include：最多 10 层深。
- 路径：相对于发起包含的文件解析，但必须保持在顶级配置目录（`openclaw.json` 的 `dirname`）内部。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许。
- 仅更改单个顶级 section 且该 section 由单文件 include 支持时，由 OpenClaw 管理的写入会透传到该被包含文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。
- 根级 include、include 数组以及带有同级覆盖的 include 对于 OpenClaw 管理的写入是只读的；这些写入会采用失败即关闭的方式，而不是扁平化配置。
- 错误：对于缺失文件、解析错误和循环 include，会给出清晰消息。
+- 同级键：在 includes 之后合并（覆盖被包含的值）。
+- 嵌套 includes：最多支持 10 层深度。
+- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录内（即 `openclaw.json` 的 `dirname`）。仅当绝对路径 / `../` 形式最终仍解析到该边界内时才允许。
+- OpenClaw 自有写入在仅更改单个由单文件 include 支持的顶层 section 时，会直接写回该被包含文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。
+- 对于根 includes、include 数组，以及带同级覆盖的 includes，OpenClaw 自有写入是只读的；这些写入会以失败关闭方式处理，而不会将配置展平。
+- 错误：对缺失文件、解析错误和循环 include 提供清晰消息。

 ---

-_相关内容：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_
+_相关内容：[Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_

 ## 相关

- [配置](/zh-CN/gateway/configuration)
- [配置示例](/zh-CN/gateway/configuration-examples)
+- [Configuration](/zh-CN/gateway/configuration)
+- [Configuration examples](/zh-CN/gateway/configuration-examples)
--- a/docs/zh-CN/logging.md
+++ b/docs/zh-CN/logging.md
@ -1,38 +1,37 @@
 ---
 read_when:
-    - 你需要一份适合初学者的日志概览
-    - 你想配置日志级别或格式
-    - 你正在进行故障排除，需要快速找到日志【อ่านข้อความเต็มanalysis to=functions.read  天天大奖彩票站_input={"path":"/home/runner/work/docs/docs/source/.agents/skills/openclaw-qa-testing/SKILL.md"} code
-summary: 日志概览：文件日志、控制台输出、CLI 尾随和控制 UI
+    - 你需要一个面向初学者的日志概览
+    - 你想要配置日志级别或格式
+    - 你正在进行故障排除，需要快速找到日志
+summary: 日志概览：文件日志、控制台输出、CLI 日志跟随，以及 Control UI
 title: 日志概览
 x-i18n:
-    generated_at: "2026-04-23T20:53:27Z"
+    generated_at: "2026-04-24T23:44:43Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 9b6f274600bcb9f5597c91aa6c30512871105a3e0de446773394abbe27276058
+    source_hash: 8e179c883d98caa7fd8d3ece8962d0b628562d35568ebf452c34bededba22e2c
    source_path: logging.md
    workflow: 15
 ---

 # 日志

-OpenClaw 有两个主要日志界面：
+OpenClaw 有两个主要的日志入口：

- **文件日志**（JSON 行格式），由 Gateway 网关写入。
- **控制台输出**，显示在终端和 Gateway 网关调试 UI 中。
+- 由 Gateway 网关 写入的**文件日志**（JSON 行格式）。
+- 在终端和 Gateway 网关调试 UI 中显示的**控制台输出**。

-控制 UI 的 **Logs** 标签页会实时跟随 gateway 文件日志。本页说明
-日志存放位置、如何读取日志，以及如何配置日志级别和格式。
+Control UI 的 **Logs** 选项卡会跟随 gateway 文件日志。本页说明日志位于哪里、如何读取日志，以及如何配置日志级别和格式。

 ## 日志存放位置

-默认情况下，Gateway 网关会将滚动日志文件写入：
+默认情况下，Gateway 网关会在以下路径写入滚动日志文件：

 `/tmp/openclaw/openclaw-YYYY-MM-DD.log`

 日期使用 gateway 主机的本地时区。

-你可以在 `~/.openclaw/openclaw.json` 中覆盖它：
+你可以在 `~/.openclaw/openclaw.json` 中覆盖这个设置：

 ```json
 {
@ -44,19 +43,19 @@ OpenClaw 有两个主要日志界面：

 ## 如何读取日志

-### CLI：实时 tail（推荐）
+### CLI：实时跟随（推荐）

-使用 CLI 通过 RPC 实时 tail gateway 日志文件：
+使用 CLI 通过 RPC 跟随 gateway 日志文件：

 ```bash
 openclaw logs --follow
 ```

-当前常用选项：
+当前有用的选项：

- `--local-time`：使用你的本地时区渲染时间戳
+- `--local-time`：以你的本地时区渲染时间戳
 - `--url <url>` / `--token <token>` / `--timeout <ms>`：标准 Gateway 网关 RPC 标志
- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（通过共享客户端层在这里接受）
+- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（这里通过共享客户端层接受）

 输出模式：

@ -66,33 +65,30 @@ openclaw logs --follow
 - `--plain`：在 TTY 会话中强制使用纯文本。
 - `--no-color`：禁用 ANSI 颜色。

-当你传入显式 `--url` 时，CLI 不会自动应用配置或
-环境变量凭证；如果目标 Gateway 网关需要认证，请自行传入 `--token`。
+当你传入显式的 `--url` 时，CLI 不会自动应用配置或环境变量凭证；如果目标 Gateway 网关需要鉴权，请自行包含 `--token`。

-在 JSON 模式下，CLI 会输出带 `type` 标记的对象：
+在 JSON 模式下，CLI 会输出带有 `type` 标签的对象：

 - `meta`：流元数据（文件、游标、大小）
 - `log`：已解析的日志条目
 - `notice`：截断 / 轮转提示
 - `raw`：未解析的原始日志行

-如果本地 loopback Gateway 网关要求配对，`openclaw logs` 会自动回退到
-已配置的本地日志文件。显式 `--url` 目标不会使用这个回退。
+如果本地 local loopback Gateway 网关要求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式的 `--url` 目标不会使用此回退机制。

-如果 Gateway 网关不可达，CLI 会打印一个简短提示，让你运行：
+如果 Gateway 网关无法访问，CLI 会打印一条简短提示，建议运行：

 ```bash
 openclaw doctor
 ```

-### 控制 UI（web）
+### Control UI（网页）

-控制 UI 的 **Logs** 标签页会使用 `logs.tail` 跟随同一个文件。
-有关如何打开它，请参阅 [/web/control-ui](/zh-CN/web/control-ui)。
+Control UI 的 **Logs** 选项卡会使用 `logs.tail` 跟随同一个文件。有关如何打开它，请参见 [/web/control-ui](/zh-CN/web/control-ui)。

 ### 仅渠道日志

-若要过滤渠道活动（WhatsApp/Telegram 等），请使用：
+要过滤渠道活动（WhatsApp/Telegram 等），请使用：

 ```bash
 openclaw channels logs --channel whatsapp
@ -102,26 +98,25 @@ openclaw channels logs --channel whatsapp

 ### 文件日志（JSONL）

-日志文件中的每一行都是一个 JSON 对象。CLI 和控制 UI 会解析这些
-条目，以渲染结构化输出（时间、级别、子系统、消息）。
+日志文件中的每一行都是一个 JSON 对象。CLI 和 Control UI 会解析这些条目，以渲染结构化输出（时间、级别、子系统、消息）。

 ### 控制台输出

-控制台日志是**TTY 感知**的，并针对可读性进行格式化：
+控制台日志会**感知 TTY**，并针对可读性进行格式化：

 - 子系统前缀（例如 `gateway/channels/whatsapp`）
 - 级别着色（info/warn/error）
- 可选的 compact 或 JSON 模式
+- 可选的紧凑模式或 JSON 模式

 控制台格式由 `logging.consoleStyle` 控制。

-### Gateway 网关 WebSocket 日志
+### Gateway WebSocket 日志

-`openclaw gateway` 还具有用于 RPC 流量的 WebSocket 协议日志：
+`openclaw gateway` 还提供用于 RPC 流量的 WebSocket 协议日志：

- 普通模式：仅记录有意义的结果（错误、解析错误、慢调用）
- `--verbose`：记录所有请求/响应流量
- `--ws-log auto|compact|full`：选择 verbose 渲染样式
+- 普通模式：仅显示值得关注的结果（错误、解析错误、慢调用）
+- `--verbose`：显示所有请求/响应流量
+- `--ws-log auto|compact|full`：选择详细渲染样式
 - `--compact`：`--ws-log compact` 的别名

 示例：
@ -134,7 +129,7 @@ openclaw gateway --verbose --ws-log full

 ## 配置日志

-所有日志配置都位于 `~/.openclaw/openclaw.json` 中的 `logging` 下。
+所有日志配置都位于 `~/.openclaw/openclaw.json` 的 `logging` 下。

 ```json
 {
@ -154,74 +149,71 @@ openclaw gateway --verbose --ws-log full
 - `logging.level`：**文件日志**（JSONL）级别。
 - `logging.consoleLevel`：**控制台**详细程度级别。

-你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两项（例如 `OPENCLAW_LOG_LEVEL=debug`）。环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅为单次运行提升详细程度。你也可以传入全局 CLI 选项 **`--log-level <level>`**（例如 `openclaw --log-level debug gateway run`），它会为该命令覆盖环境变量。
+你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两者（例如 `OPENCLAW_LOG_LEVEL=debug`）。该环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅针对单次运行提高详细程度。你也可以传递全局 CLI 选项 **`--log-level <level>`**（例如，`openclaw --log-level debug gateway run`），它会在该命令中覆盖环境变量。

-`--verbose` 只影响控制台输出和 WS 日志详细程度；它不会更改
-文件日志级别。
+`--verbose` 只影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。

 ### 控制台样式

 `logging.consoleStyle`：

- `pretty`：适合人类阅读，带颜色和时间戳。
- `compact`：更紧凑的输出（最适合长会话）。
- `json`：每行一个 JSON（用于日志处理器）。
+- `pretty`：适合人工阅读，带颜色和时间戳。
+- `compact`：输出更紧凑（最适合长时间会话）。
+- `json`：每行一个 JSON（适用于日志处理器）。

 ### 脱敏

-工具摘要可在输出到控制台之前对敏感令牌进行脱敏：
+工具摘要可以在输出到控制台之前对敏感令牌进行脱敏：

 - `logging.redactSensitive`：`off` | `tools`（默认：`tools`）
 - `logging.redactPatterns`：用于覆盖默认集合的正则表达式字符串列表

-脱敏**仅影响控制台输出**，不会更改文件日志。
+脱敏**只影响控制台输出**，不会修改文件日志。

-## Diagnostics + OpenTelemetry
+## 诊断 + OpenTelemetry

-Diagnostics 是用于模型运行**以及**
-消息流遥测（webhooks、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志；它们的存在是为了馈送指标、追踪和其他导出器。
+诊断是面向模型运行**以及**消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志；它们的存在是为了提供给指标、追踪和其他导出器。

-Diagnostics 事件会在进程内发出，但只有在启用 diagnostics + 对应导出器插件时，导出器才会附加。
+诊断事件会在进程内发出，但只有在启用 diagnostics 和导出器插件后，导出器才会附加。

-### OpenTelemetry 与 OTLP
+### OpenTelemetry 与 OTLP 的区别

- **OpenTelemetry（OTel）**：用于 traces、metrics 和 logs 的数据模型 + SDK。
- **OTLP**：将 OTel 数据导出到 collector/backend 所使用的线协议。
+- **OpenTelemetry（OTel）**：用于追踪、指标和日志的数据模型 + SDK。
+- **OTLP**：用于将 OTel 数据导出到采集器 / 后端的线协议。
 - OpenClaw 当前通过 **OTLP/HTTP（protobuf）** 导出。

 ### 导出的信号

- **Metrics**：计数器 + 直方图（token 用量、消息流、排队）。
- **Traces**：模型使用 + webhook/消息处理的 spans。
- **Logs**：在启用 `diagnostics.otel.logs` 时通过 OTLP 导出。日志
-  量可能很大；请留意 `logging.level` 和导出器过滤器。
+- **指标**：计数器 + 直方图（令牌使用量、消息流、排队）。
+- **追踪**：模型使用和 webhook / 消息处理的 span。
+- **日志**：当启用 `diagnostics.otel.logs` 时通过 OTLP 导出。日志量可能很高；请注意 `logging.level` 和导出器过滤器。

-### Diagnostics 事件目录
+### 诊断事件目录

 模型使用：

- `model.usage`：tokens、成本、时长、上下文、provider/model/channel、session ids。
+- `model.usage`：令牌、成本、时长、上下文、provider / model / channel、会话 ID。

 消息流：

 - `webhook.received`：每个渠道的 webhook 入口。
 - `webhook.processed`：webhook 已处理 + 时长。
 - `webhook.error`：webhook 处理器错误。
- `message.queued`：消息已入队等待处理。
+- `message.queued`：消息已排队等待处理。
 - `message.processed`：结果 + 时长 + 可选错误。

 队列 + 会话：

 - `queue.lane.enqueue`：命令队列 lane 入队 + 深度。
 - `queue.lane.dequeue`：命令队列 lane 出队 + 等待时间。
- `session.state`：会话状态迁移 + 原因。
- `session.stuck`：会话卡住警告 + 持续时长。
- `run.attempt`：运行重试/尝试元数据。
- `diagnostic.heartbeat`：聚合计数器（webhooks/queue/session）。
+- `session.state`：会话状态转换 + 原因。
+- `session.stuck`：会话卡住警告 + 已持续时长。
+- `run.attempt`：运行重试 / 尝试元数据。
+- `diagnostic.heartbeat`：聚合计数器（webhook / 队列 / 会话）。

-### 启用 diagnostics（无导出器）
+### 启用诊断（不使用导出器）

-如果你希望 diagnostics 事件可供插件或自定义 sink 使用，请使用：
+如果你希望诊断事件可供插件或自定义接收端使用，请使用此配置：

 ```json
 {
@ -231,10 +223,9 @@ Diagnostics 事件会在进程内发出，但只有在启用 diagnostics + 对
 }
 ```

-### Diagnostics 标志（定向日志）
+### diagnostics 标志（定向日志）

-使用标志可开启额外的、定向的调试日志，而无需提高 `logging.level`。
-标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）。
+使用标志可启用额外的、定向的调试日志，而无需提高 `logging.level`。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）。

 ```json
 {
@ -252,14 +243,13 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

 说明：

- 标志日志会写入标准日志文件（与 `logging.file` 相同）。
+- 标志日志会进入标准日志文件（与 `logging.file` 相同）。
 - 输出仍会根据 `logging.redactSensitive` 进行脱敏。
 - 完整指南：[/diagnostics/flags](/zh-CN/diagnostics/flags)。

 ### 导出到 OpenTelemetry

-Diagnostics 可通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。它
-适用于任何接受 OTLP/HTTP 的 OpenTelemetry collector/backend。
+诊断可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 采集器 / 后端。

 ```json
 {
@ -282,7 +272,15 @@ Diagnostics 可通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。它
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
-      "flushIntervalMs": 60000
+      "flushIntervalMs": 60000,
+      "captureContent": {
+        "enabled": false,
+        "inputMessages": false,
+        "outputMessages": false,
+        "toolInputs": false,
+        "toolOutputs": false,
+        "systemPrompt": false
+      }
    }
  }
 }
@ -292,100 +290,88 @@ Diagnostics 可通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。它

 - 你也可以使用 `openclaw plugins enable diagnostics-otel` 启用该插件。
 - `protocol` 当前仅支持 `http/protobuf`。`grpc` 会被忽略。
- Metrics 包括 token 用量、成本、上下文大小、运行时长，以及消息流
-  计数器/直方图（webhooks、排队、会话状态、队列深度/等待时间）。
- Traces/metrics 可通过 `traces` / `metrics` 开关控制（默认：开启）。Traces
-  在启用时包括模型使用 spans，以及 webhook/消息处理 spans。
- 当你的 collector 需要认证时，请设置 `headers`。
- 支持的环境变量：`OTEL_EXPORTER_OTLP_ENDPOINT`、
-  `OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_PROTOCOL`。
+- 指标包括令牌使用量、成本、上下文大小、运行时长，以及消息流计数器 / 直方图（webhook、排队、会话状态、队列深度 / 等待时间）。
+- 可通过 `traces` / `metrics` 切换追踪 / 指标（默认：开启）。启用后，追踪包含模型使用 span，以及 webhook / 消息处理 span。
+- 默认不会导出原始模型 / 工具内容。只有在你的采集器和保留策略已获批准可处理提示词、响应、工具或系统提示文本时，才使用 `diagnostics.otel.captureContent`。
+- 当你的采集器需要鉴权时，请设置 `headers`。
+- 支持的环境变量：`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_PROTOCOL`。

-### 已导出的 metrics（名称 + 类型）
+### 导出的指标（名称 + 类型）

 模型使用：

- `openclaw.tokens`（counter，attrs：`openclaw.token`、`openclaw.channel`、
-  `openclaw.provider`、`openclaw.model`）
- `openclaw.cost.usd`（counter，attrs：`openclaw.channel`、`openclaw.provider`、
-  `openclaw.model`）
- `openclaw.run.duration_ms`（histogram，attrs：`openclaw.channel`、
-  `openclaw.provider`、`openclaw.model`）
- `openclaw.context.tokens`（histogram，attrs：`openclaw.context`、
-  `openclaw.channel`、`openclaw.provider`、`openclaw.model`）
+- `openclaw.tokens`（计数器，属性：`openclaw.token`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
+- `openclaw.cost.usd`（计数器，属性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
+- `openclaw.run.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
+- `openclaw.context.tokens`（直方图，属性：`openclaw.context`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`）

 消息流：

- `openclaw.webhook.received`（counter，attrs：`openclaw.channel`、
-  `openclaw.webhook`）
- `openclaw.webhook.error`（counter，attrs：`openclaw.channel`、
-  `openclaw.webhook`）
- `openclaw.webhook.duration_ms`（histogram，attrs：`openclaw.channel`、
-  `openclaw.webhook`）
- `openclaw.message.queued`（counter，attrs：`openclaw.channel`、
-  `openclaw.source`）
- `openclaw.message.processed`（counter，attrs：`openclaw.channel`、
-  `openclaw.outcome`）
- `openclaw.message.duration_ms`（histogram，attrs：`openclaw.channel`、
-  `openclaw.outcome`）
+- `openclaw.webhook.received`（计数器，属性：`openclaw.channel`、`openclaw.webhook`）
+- `openclaw.webhook.error`（计数器，属性：`openclaw.channel`、`openclaw.webhook`）
+- `openclaw.webhook.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.webhook`）
+- `openclaw.message.queued`（计数器，属性：`openclaw.channel`、`openclaw.source`）
+- `openclaw.message.processed`（计数器，属性：`openclaw.channel`、`openclaw.outcome`）
+- `openclaw.message.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.outcome`）

 队列 + 会话：

- `openclaw.queue.lane.enqueue`（counter，attrs：`openclaw.lane`）
- `openclaw.queue.lane.dequeue`（counter，attrs：`openclaw.lane`）
- `openclaw.queue.depth`（histogram，attrs：`openclaw.lane` 或
-  `openclaw.channel=heartbeat`）
- `openclaw.queue.wait_ms`（histogram，attrs：`openclaw.lane`）
- `openclaw.session.state`（counter，attrs：`openclaw.state`、`openclaw.reason`）
- `openclaw.session.stuck`（counter，attrs：`openclaw.state`）
- `openclaw.session.stuck_age_ms`（histogram，attrs：`openclaw.state`）
- `openclaw.run.attempt`（counter，attrs：`openclaw.attempt`）
+- `openclaw.queue.lane.enqueue`（计数器，属性：`openclaw.lane`）
+- `openclaw.queue.lane.dequeue`（计数器，属性：`openclaw.lane`）
+- `openclaw.queue.depth`（直方图，属性：`openclaw.lane` 或 `openclaw.channel=heartbeat`）
+- `openclaw.queue.wait_ms`（直方图，属性：`openclaw.lane`）
+- `openclaw.session.state`（计数器，属性：`openclaw.state`、`openclaw.reason`）
+- `openclaw.session.stuck`（计数器，属性：`openclaw.state`）
+- `openclaw.session.stuck_age_ms`（直方图，属性：`openclaw.state`）
+- `openclaw.run.attempt`（计数器，属性：`openclaw.attempt`）

-### 已导出的 spans（名称 + 关键属性）
+### 导出的 span（名称 + 关键属性）

 - `openclaw.model.usage`
  - `openclaw.channel`、`openclaw.provider`、`openclaw.model`
-  - `openclaw.sessionKey`、`openclaw.sessionId`
-  - `openclaw.tokens.*`（input/output/cache_read/cache_write/total）
+  - `openclaw.tokens.*`（input / output / cache_read / cache_write / total）
+- `openclaw.run`
+  - `openclaw.outcome`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`、`openclaw.errorCategory`
+- `openclaw.model.call`
+  - `gen_ai.system`、`gen_ai.request.model`、`gen_ai.operation.name`、`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`
+- `openclaw.tool.execution`
+  - `gen_ai.tool.name`、`openclaw.toolName`、`openclaw.errorCategory`、`openclaw.tool.params.*`
 - `openclaw.webhook.processed`
  - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId`
 - `openclaw.webhook.error`
-  - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId`、
-    `openclaw.error`
+  - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId`、`openclaw.error`
 - `openclaw.message.processed`
-  - `openclaw.channel`、`openclaw.outcome`、`openclaw.chatId`、
-    `openclaw.messageId`、`openclaw.sessionKey`、`openclaw.sessionId`、
-    `openclaw.reason`
+  - `openclaw.channel`、`openclaw.outcome`、`openclaw.chatId`、`openclaw.messageId`、`openclaw.reason`
 - `openclaw.session.stuck`
-  - `openclaw.state`、`openclaw.ageMs`、`openclaw.queueDepth`、
-    `openclaw.sessionKey`、`openclaw.sessionId`
+  - `openclaw.state`、`openclaw.ageMs`、`openclaw.queueDepth`
+
+当显式启用内容捕获时，模型 / 工具 span 还可以包含有界、已脱敏的 `openclaw.content.*` 属性，适用于你选择启用的特定内容类别。

 ### 采样 + 刷新

- Trace 采样：`diagnostics.otel.sampleRate`（0.0–1.0，仅根 spans）。
- Metric 导出间隔：`diagnostics.otel.flushIntervalMs`（最小 1000ms）。
+- 追踪采样：`diagnostics.otel.sampleRate`（0.0–1.0，仅根 span）。
+- 指标导出间隔：`diagnostics.otel.flushIntervalMs`（最小 1000 ms）。

 ### 协议说明

- OTLP/HTTP 端点可通过 `diagnostics.otel.endpoint` 或
-  `OTEL_EXPORTER_OTLP_ENDPOINT` 设置。
- 如果端点已包含 `/v1/traces` 或 `/v1/metrics`，则按原样使用。
- 如果端点已包含 `/v1/logs`，则日志也按原样使用它。
+- 可通过 `diagnostics.otel.endpoint` 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 设置 OTLP/HTTP 端点。
+- 如果端点已包含 `/v1/traces` 或 `/v1/metrics`，则会按原样使用。
+- 如果端点已包含 `/v1/logs`，则会按原样用于日志。
 - `diagnostics.otel.logs` 会为主日志记录器输出启用 OTLP 日志导出。

 ### 日志导出行为

- OTLP 日志使用与写入 `logging.file` 相同的结构化记录。
- 遵循 `logging.level`（文件日志级别）。控制台脱敏**不会**应用于 OTLP 日志。
- 高日志量部署应优先使用 OTLP collector 侧的采样/过滤。
+- OTLP 日志使用与写入 `logging.file` 的相同结构化记录。
+- 遵循 `logging.level`（文件日志级别）。控制台脱敏**不会**应用到 OTLP 日志。
+- 高流量安装应优先使用 OTLP 采集器的采样 / 过滤功能。

 ## 故障排除提示

- **Gateway 网关不可达？** 先运行 `openclaw doctor`。
- **日志为空？** 检查 Gateway 网关是否正在运行，并且是否写入到
-  `logging.file` 中指定的文件路径。
- **需要更多细节？** 将 `logging.level` 设为 `debug` 或 `trace` 后重试。
+- **Gateway 网关无法访问？** 先运行 `openclaw doctor`。
+- **日志为空？** 检查 Gateway 网关是否正在运行，并且是否正在向 `logging.file` 中的文件路径写入。
+- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace` 后重试。

 ## 相关内容

- [Gateway 网关日志内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获
+- [Gateway Logging Internals](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获
 - [Diagnostics](/zh-CN/gateway/configuration-reference#diagnostics) — OpenTelemetry 导出和缓存追踪配置