diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 5e44d7954..65c94e0ac 100644 --- 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..enabled: false`：即使 skill 已内置/已安装，也会禁用该 skill。 -- `entries..apiKey`：为声明主要环境变量的 skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 +- `entries..enabled: false`：即使某个 skill 已内置 / 安装，也会将其禁用。 +- `entries..apiKey`：为声明了主环境变量的 skill 提供的便捷字段（明文字符串或 SecretRef 对象）。 --- @@ -118,42 +118,42 @@ x-i18n: - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 - 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 -- **配置变更需要重启 Gateway 网关。** -- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先生效。 -- `plugins.entries..apiKey`：插件级 API 密钥便捷字段（插件支持时可用）。 +- **配置更改需要重启 Gateway 网关。** +- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 +- `plugins.entries..apiKey`：插件级 API 密钥便捷字段（当插件支持时）。 - `plugins.entries..env`：插件作用域的环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子，以及受支持的 bundle 提供的钩子目录。 -- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可从 `llm_input`、`llm_output` 和 `agent_end` 等类型化钩子中读取原始对话内容。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可在后台子智能体运行时请求按次运行的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可用的规范 `provider/model` 目标可选允许列表。仅在你有意允许任意模型时才使用 `"*"`。 +- `plugins.entries..hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的 bundle 提供的 hook 目录。 +- `plugins.entries..hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可从类型化钩子（如 `llm_input`、`llm_output` 和 `agent_end`）读取原始对话内容。 +- `plugins.entries..subagent.allowModelOverride`：显式信任此插件，使其可为后台子智能体运行请求逐次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可使用的规范 `provider/model` 目标的可选允许列表。仅当你明确想允许任意模型时才使用 `"*"`。 - `plugins.entries..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..healthMonitor.enabled`：在保持全局监视器启用的情况下，按渠道选择退出健康监视器重启。 -- `channels..accounts..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..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.tools.deny`：针对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。 - `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。 -### 与 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 `（使用 `~/.openclaw-`）。 +便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`），`--profile `（使用 `~/.openclaw-`）。 -参阅 [多个 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 ` 或 `x-openclaw-token: `。 -会拒绝查询字符串中的 hook token。 +凭证：`Authorization: Bearer ` 或 `x-openclaw-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/` → 通过 `hooks.mappings` 解析 - 模板渲染后的 mapping `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 - `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（如果设置了模型目录，则该模型必须被允许）。 ### 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://:/__openclaw__/canvas/` - `http://:/__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 是增量支持的：明文值仍然可用。 } ``` -- 每个智能体的配置文件存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持静态凭证模式下的值级 ref（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会进行清理。 +- 每个智能体的 profile 存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 支持值级 ref（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- OAuth 模式的 profile（`auth.profiles..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` 可移除未知键）。 @@ -976,11 +984,11 @@ Secret ref 是增量支持的：明文值仍然可用。 } ``` -- `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`：在从 `sessions.json` 中清理之前，保留已完成隔离 cron 运行会话的时长。也控制已归档的已删除 cron transcript 的清理。默认：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发裁剪前的最大大小。默认：`2_000_000` 字节。 +- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认：`2000`。 +- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略则不会发送凭证头。 +- `webhook`：已弃用的旧版回退 webhook URL（http / https），仅用于仍具有 `notify: true` 的已存储任务。 ### `cron.retry` @@ -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) diff --git a/docs/zh-CN/logging.md b/docs/zh-CN/logging.md index d619ffb56..ceb91f23a 100644 --- 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 ` / `--token ` / `--timeout `：标准 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 `**（例如 `openclaw --log-level debug gateway run`），它会为该命令覆盖环境变量。 +你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两者（例如 `OPENCLAW_LOG_LEVEL=debug`）。该环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅针对单次运行提高详细程度。你也可以传递全局 CLI 选项 **`--log-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 导出和缓存追踪配置