From 4f6e92f19c237265e9c703a27c0a009a984efab1 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 5 May 2026 03:09:04 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/agent-loop.md | 161 +++-- docs/zh-CN/gateway/configuration-reference.md | 583 +++++++++--------- docs/zh-CN/gateway/opentelemetry.md | 141 +++-- 3 files changed, 431 insertions(+), 454 deletions(-) diff --git a/docs/zh-CN/concepts/agent-loop.md b/docs/zh-CN/concepts/agent-loop.md index 03af71236..f1d323f99 100644 --- a/docs/zh-CN/concepts/agent-loop.md +++ b/docs/zh-CN/concepts/agent-loop.md @@ -1,169 +1,166 @@ --- read_when: - - 你需要 Agent loop 或生命周期事件的精确逐步说明 - - 你正在修改会话排队、会话记录写入或会话写锁行为 + - 你需要 Agent loop 或生命周期事件的精确逐步讲解 + - 你正在更改会话排队、会话记录写入或会话写锁行为 summary: Agent loop 生命周期、流和等待语义 title: Agent loop x-i18n: - generated_at: "2026-05-03T17:21:23Z" + generated_at: "2026-05-05T03:06:19Z" model: gpt-5.5 provider: openai - source_hash: 1bdd8e98710dce6412f499c37d2d74445f44f93142364c30993de517fdea6c56 + source_hash: 1c7031a2b70e7a891f51fa127df6f04663db81400715717f50dd840a3fa5b745 source_path: concepts/agent-loop.md workflow: 16 --- -智能体式循环是智能体完整的“真实”运行：接收 → 上下文组装 → 模型推理 → -工具执行 → 流式回复 → 持久化。它是权威路径，会把一条消息转化为操作和最终回复， -同时保持会话状态一致。 +智能体式循环是一次智能体完整的“真实”运行：接收 → 上下文组装 → 模型推理 → +工具执行 → 流式回复 → 持久化。它是把消息转化为动作和最终回复的权威路径，同时保持会话状态一致。 -在 OpenClaw 中，一个循环是每个会话一次的单个串行运行，会在模型思考、调用工具并流式输出时发出生命周期和流事件。本文说明这个真实循环如何端到端串接。 +在 OpenClaw 中，一个循环是每个会话单次、序列化的运行，并在模型思考、调用工具和流式输出时发出生命周期和流事件。本文说明这个真实循环如何端到端串接。 ## 入口点 - Gateway 网关 RPC：`agent` 和 `agent.wait`。 - CLI：`agent` 命令。 -## 工作原理（高层） +## 工作方式（高层） -1. `agent` RPC 会校验参数，解析会话（sessionKey/sessionId），持久化会话元数据，并立即返回 `{ runId, acceptedAt }`。 +1. `agent` RPC 校验参数，解析会话（sessionKey/sessionId），持久化会话元数据，并立即返回 `{ runId, acceptedAt }`。 2. `agentCommand` 运行智能体： - 解析模型 + thinking/verbose/trace 默认值 - 加载 Skills 快照 - 调用 `runEmbeddedPiAgent`（pi-agent-core 运行时） - - 如果嵌入式循环没有发出生命周期 end/error，则发出 **lifecycle end/error** + - 如果嵌入式循环没有发出结束/错误生命周期事件，则发出**生命周期结束/错误** 3. `runEmbeddedPiAgent`： - - 通过每会话 + 全局队列串行化运行 - - 解析模型 + 凭证配置文件，并构建 Pi 会话 - - 订阅 Pi 事件并流式传输助手/工具增量 - - 强制超时 -> 超过则中止运行 - - 对 Codex app-server 轮次，在终止事件前如果一个已接受轮次停止产出 app-server 进度，则中止它 + - 通过每会话 + 全局队列序列化运行 + - 解析模型 + 凭证配置文件并构建 pi 会话 + - 订阅 pi 事件并流式传输 assistant/tool 增量 + - 强制超时 -> 超过后中止运行 + - 对于 Codex app-server 回合，中止已经接受但在终端事件前停止产生 app-server 进度的回合 - 返回载荷 + 用量元数据 4. `subscribeEmbeddedPiSession` 将 pi-agent-core 事件桥接到 OpenClaw `agent` 流： - 工具事件 => `stream: "tool"` - - 助手增量 => `stream: "assistant"` + - assistant 增量 => `stream: "assistant"` - 生命周期事件 => `stream: "lifecycle"`（`phase: "start" | "end" | "error"`） 5. `agent.wait` 使用 `waitForAgentRun`： - - 等待 `runId` 的 **lifecycle end/error** + - 等待 `runId` 的**生命周期结束/错误** - 返回 `{ status: ok|error|timeout, startedAt, endedAt, error? }` ## 排队 + 并发 -- 运行按会话键（会话通道）串行化，并且可选地经过全局通道。 -- 这可以防止工具/会话竞争，并保持会话历史一致。 -- 消息渠道可以选择队列模式（collect/steer/followup），这些模式会送入这套通道系统。 - 参见 [命令队列](/zh-CN/concepts/queue)。 -- 转录写入也会受到会话文件上的会话写入锁保护。该锁感知进程并基于文件，因此可以捕获绕过进程内队列或来自其他进程的写入方。会话转录写入方最多等待 `session.writeLock.acquireTimeoutMs`，之后才会报告会话繁忙；默认值为 `60000` ms。 -- 会话写入锁默认不可重入。如果某个辅助函数有意在保留一个逻辑写入方的同时嵌套获取同一把锁，它必须通过 `allowReentrant: true` 显式选择启用。 +- 运行按会话键（会话通道）序列化，并可选择再经过全局通道。 +- 这可以避免工具/会话竞争，并保持会话历史一致。 +- 消息渠道可以选择队列模式（collect/steer/followup），这些模式会馈入此通道系统。 + 参见 [Command Queue](/zh-CN/concepts/queue)。 +- 转录写入也受会话文件上的会话写锁保护。该锁感知进程且基于文件，因此可以捕获绕过进程内队列或来自其他进程的写入者。会话转录写入者最多等待 `session.writeLock.acquireTimeoutMs`，然后才报告会话正忙；默认值为 `60000` ms。 +- 会话写锁默认不可重入。如果某个辅助函数有意在保留同一个逻辑写入者的同时嵌套获取同一把锁，必须通过 `allowReentrant: true` 显式选择启用。 ## 会话 + 工作区准备 -- 解析并创建工作区；沙箱隔离的运行可能会重定向到沙箱工作区根目录。 -- 加载 Skills（或从快照复用），并注入到环境变量和提示词中。 -- 解析启动/上下文文件，并注入到系统提示词报告中。 -- 获取会话写入锁；在流式传输前打开并准备 `SessionManager`。之后任何转录重写、压缩或截断路径，都必须在打开或修改转录文件前获取同一把锁。 +- 解析并创建工作区；沙箱隔离运行可能会重定向到沙箱工作区根目录。 +- 加载 Skills（或从快照复用），并注入到环境和提示词中。 +- 解析 bootstrap/context 文件，并注入到系统提示词报告中。 +- 获取会话写锁；在开始流式传输前打开并准备 `SessionManager`。任何后续转录重写、压缩或截断路径，都必须在打开或修改转录文件前获取同一把锁。 ## 提示词组装 + 系统提示词 -- 系统提示词由 OpenClaw 的基础提示词、Skills 提示词、启动上下文和每次运行的覆盖项构建。 -- 会强制执行模型特定限制和压缩预留 token。 -- 参见[系统提示词](/zh-CN/concepts/system-prompt)，了解模型会看到什么。 +- 系统提示词由 OpenClaw 的基础提示词、Skills 提示词、bootstrap 上下文和每次运行的覆盖项构建。 +- 强制执行模型特定限制和压缩保留令牌。 +- 参见 [System prompt](/zh-CN/concepts/system-prompt)，了解模型会看到什么。 -## 钩子点（你可以拦截的位置） +## 钩子点（可以拦截的位置） -OpenClaw 有两个钩子系统： +OpenClaw 有两套钩子系统： -- **内部钩子**（Gateway 网关钩子）：面向命令和生命周期事件的事件驱动脚本。 -- **插件钩子**：智能体/工具生命周期和 Gateway 网关流水线中的扩展点。 +- **内部钩子**（Gateway 网关钩子）：用于命令和生命周期事件的事件驱动脚本。 +- **插件钩子**：智能体/工具生命周期和 Gateway 网关管线内的扩展点。 ### 内部钩子（Gateway 网关钩子） -- **`agent:bootstrap`**：在系统提示词最终确定前构建启动文件时运行。 - 用它来添加/移除启动上下文文件。 -- **命令钩子**：`/new`、`/reset`、`/stop` 和其他命令事件（参见钩子文档）。 +- **`agent:bootstrap`**：在系统提示词最终确定前构建 bootstrap 文件时运行。 + 用它添加/移除 bootstrap 上下文文件。 +- **命令钩子**：`/new`、`/reset`、`/stop` 和其他命令事件（参见 Hooks 文档）。 -参见[钩子](/zh-CN/automation/hooks)了解设置和示例。 +参见 [Hooks](/zh-CN/automation/hooks) 获取设置和示例。 ### 插件钩子（智能体 + Gateway 网关生命周期） -这些在智能体循环或 Gateway 网关流水线内运行： +这些钩子在智能体循环或 Gateway 网关管线内运行： -- **`before_model_resolve`**：在会话前运行（没有 `messages`），用于在模型解析前确定性地覆盖提供商/模型。 -- **`before_prompt_build`**：在会话加载后运行（带有 `messages`），用于在提交提示词前注入 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。对每轮动态文本使用 `prependContext`，对应该位于系统提示词空间的稳定指引用 system-context 字段。 +- **`before_model_resolve`**：在会话前运行（无 `messages`），用于在模型解析前确定性地覆盖提供商/模型。 +- **`before_prompt_build`**：在会话加载后运行（带 `messages`），用于在提交提示词前注入 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。将 `prependContext` 用于每回合动态文本，将系统上下文字段用于应位于系统提示词空间中的稳定指导。 - **`before_agent_start`**：旧版兼容钩子，可能在任一阶段运行；优先使用上面的显式钩子。 -- **`before_agent_reply`**：在内联操作之后、LLM 调用之前运行，让插件接管该轮并返回合成回复，或完全静默该轮。 -- **`agent_end`**：在完成后检查最终消息列表和运行元数据。 -- **`before_compaction` / `after_compaction`**：观察或标注压缩周期。 +- **`before_agent_reply`**：在内联动作之后、LLM 调用之前运行，让插件接管该回合并返回合成回复，或完全静默该回合。 +- **`agent_end`**：完成后检查最终消息列表和运行元数据。 +- **`before_compaction` / `after_compaction`**：观察或注释压缩周期。 - **`before_tool_call` / `after_tool_call`**：拦截工具参数/结果。 -- **`before_install`**：检查内置扫描发现，并可选地阻止 Skills 或插件安装。 -- **`tool_result_persist`**：在工具结果写入 OpenClaw 所属的会话转录前同步转换它们。 +- **`before_install`**：检查内置扫描发现，并可选地阻止 Skill 或插件安装。 +- **`tool_result_persist`**：在工具结果写入 OpenClaw 拥有的会话转录前，同步转换工具结果。 - **`message_received` / `message_sending` / `message_sent`**：入站 + 出站消息钩子。 - **`session_start` / `session_end`**：会话生命周期边界。 - **`gateway_start` / `gateway_stop`**：Gateway 网关生命周期事件。 -出站/工具防护的钩子决策规则： +出站/工具守卫的钩子决策规则： -- `before_tool_call`：`{ block: true }` 是终止性的，会停止较低优先级处理程序。 -- `before_tool_call`：`{ block: false }` 是无操作，不会清除之前的阻止。 -- `before_install`：`{ block: true }` 是终止性的，会停止较低优先级处理程序。 -- `before_install`：`{ block: false }` 是无操作，不会清除之前的阻止。 -- `message_sending`：`{ cancel: true }` 是终止性的，会停止较低优先级处理程序。 -- `message_sending`：`{ cancel: false }` 是无操作，不会清除之前的取消。 +- `before_tool_call`：`{ block: true }` 是终止性的，会停止更低优先级的处理器。 +- `before_tool_call`：`{ block: false }` 是空操作，不会清除先前的阻止。 +- `before_install`：`{ block: true }` 是终止性的，会停止更低优先级的处理器。 +- `before_install`：`{ block: false }` 是空操作，不会清除先前的阻止。 +- `message_sending`：`{ cancel: true }` 是终止性的，会停止更低优先级的处理器。 +- `message_sending`：`{ cancel: false }` 是空操作，不会清除先前的取消。 -参见[插件钩子](/zh-CN/plugins/hooks)了解钩子 API 和注册详情。 +参见 [Plugin hooks](/zh-CN/plugins/hooks) 获取钩子 API 和注册详情。 -Harness 可以以不同方式适配这些钩子。Codex app-server harness 会把 OpenClaw 插件钩子作为已记录镜像表面的兼容性契约，而 Codex 原生钩子仍然是单独的、更底层的 Codex 机制。 +运行框架可能会以不同方式适配这些钩子。Codex app-server 运行框架将 OpenClaw 插件钩子保留为已文档化镜像表面的兼容性契约，而 Codex 原生钩子仍是一个单独的更低层级 Codex 机制。 ## 流式传输 + 部分回复 -- 助手增量从 pi-agent-core 流式传输，并作为 `assistant` 事件发出。 +- Assistant 增量从 pi-agent-core 流式传输，并作为 `assistant` 事件发出。 - 分块流式传输可以在 `text_end` 或 `message_end` 上发出部分回复。 - 推理流可以作为单独的流发出，也可以作为分块回复发出。 -- 参见[流式传输](/zh-CN/concepts/streaming)了解分块和分块回复行为。 +- 参见 [Streaming](/zh-CN/concepts/streaming) 获取分块和分块回复行为。 ## 工具执行 + 消息工具 -- 工具 start/update/end 事件会在 `tool` 流上发出。 -- 工具结果会在记录/发出前按大小和图片载荷进行清理。 -- 会跟踪消息工具发送，以抑制重复的助手确认。 +- 工具 start/update/end 事件在 `tool` 流上发出。 +- 工具结果在记录/发出前会按大小和图像载荷进行清理。 +- 消息工具发送会被跟踪，以抑制重复的 assistant 确认。 ## 回复塑形 + 抑制 - 最终载荷由以下内容组装： - - 助手文本（以及可选推理） - - 内联工具摘要（当 verbose + 允许时） - - 模型出错时的助手错误文本 -- 精确的静默 token `NO_REPLY` / `no_reply` 会从出站 - 载荷中过滤掉。 + - assistant 文本（以及可选推理） + - 内联工具摘要（verbose + 允许时） + - 模型出错时的 assistant 错误文本 +- 精确静默令牌 `NO_REPLY` / `no_reply` 会从出站载荷中过滤掉。 - 消息工具重复项会从最终载荷列表中移除。 -- 如果没有剩余可渲染载荷且某个工具出错，则会发出回退工具错误回复 - （除非某个消息工具已经发送了用户可见回复）。 +- 如果没有剩余可渲染载荷且工具出错，则会发出后备工具错误回复（除非消息工具已经发送了用户可见的回复）。 ## 压缩 + 重试 -- 自动压缩会发出 `compaction` 流事件，并且可以触发重试。 +- 自动压缩会发出 `compaction` 流事件，并可能触发重试。 - 重试时，内存缓冲区和工具摘要会被重置，以避免重复输出。 -- 参见[压缩](/zh-CN/concepts/compaction)了解压缩流水线。 +- 参见 [Compaction](/zh-CN/concepts/compaction) 了解压缩管线。 ## 事件流（当前） -- `lifecycle`：由 `subscribeEmbeddedPiSession` 发出（也由 `agentCommand` 作为回退发出） +- `lifecycle`：由 `subscribeEmbeddedPiSession` 发出（并由 `agentCommand` 作为后备发出） - `assistant`：来自 pi-agent-core 的流式增量 - `tool`：来自 pi-agent-core 的流式工具事件 ## 聊天渠道处理 -- 助手增量会缓冲为聊天 `delta` 消息。 -- 在 **lifecycle end/error** 上发出聊天 `final`。 +- Assistant 增量会缓冲为聊天 `delta` 消息。 +- 在**生命周期结束/错误**时发出聊天 `final`。 ## 超时 - `agent.wait` 默认值：30s（仅等待）。`timeoutMs` 参数会覆盖。 -- 智能体运行时：`agents.defaults.timeoutSeconds` 默认 172800s（48 小时）；由 `runEmbeddedPiAgent` 中止计时器强制执行。 -- Cron 运行时：隔离智能体轮次的 `timeoutSeconds` 由 cron 拥有。调度器在执行开始时启动该计时器，在配置的截止时间中止底层运行，然后在记录超时前运行有界清理，避免过期子会话让通道一直卡住。 -- 会话活跃度诊断：启用诊断后，`diagnostics.stuckSessionWarnMs` 会将没有观测到回复、工具、状态、分块或 ACP 进度的长时间 `processing` 会话分类。活跃的嵌入式运行、模型调用和工具调用报告为 `session.long_running`；没有最近进度的活跃工作报告为 `session.stalled`；`session.stuck` 保留给没有活跃工作的过期会话簿记。过期会话簿记会立即释放受影响的会话通道；停滞的嵌入式运行只有在更长的无进度窗口之后才会被中止并排空（至少 10 分钟且为告警阈值的 5 倍），这样排队工作可以恢复，而不会切断只是较慢的运行。重复的 `session.stuck` 诊断会在会话保持不变时退避。 -- 模型空闲超时：如果在空闲窗口之前没有响应分块到达，OpenClaw 会中止模型请求。`models.providers..timeoutSeconds` 会为缓慢的本地/自托管提供商延长这个空闲看门狗；否则 OpenClaw 会在已配置时使用 `agents.defaults.timeoutSeconds`，默认上限为 120s。没有显式模型或智能体超时的 cron 触发运行会禁用空闲看门狗，并依赖 cron 外层超时。 -- 提供商 HTTP 请求超时：`models.providers..timeoutSeconds` 适用于该提供商的模型 HTTP fetch，包括连接、头部、正文、SDK 请求超时、总 guarded-fetch 中止处理和模型流空闲看门狗。对 Ollama 等缓慢的本地/自托管提供商，应先使用它，再提高整个智能体运行时超时。 +- 智能体运行时：`agents.defaults.timeoutSeconds` 默认 172800s（48 小时）；在 `runEmbeddedPiAgent` 中由中止定时器强制执行。 +- Cron 运行时：隔离智能体回合的 `timeoutSeconds` 由 cron 拥有。调度器在执行开始时启动该定时器，在配置的截止时间中止底层运行，然后在记录超时前运行有界清理，避免陈旧子会话让通道卡住。 +- 会话活性诊断：启用诊断后，`diagnostics.stuckSessionWarnMs` 会对没有观察到回复、工具、状态、分块或 ACP 进度的长时间 `processing` 会话进行分类。活跃嵌入式运行、模型调用和工具调用会报告为 `session.long_running`；有活跃工作但近期没有进度会报告为 `session.stalled`；`session.stuck` 保留给没有活跃工作的陈旧会话记账。陈旧会话记账会立即释放受影响的会话通道；停滞的嵌入式运行只会在 `diagnostics.stuckSessionAbortMs` 之后才中止并排空（默认：至少 10 分钟且为警告阈值的 5 倍），以便排队工作可以恢复，而不会切断只是较慢的运行。恢复会发出结构化的 requested/completed 结果，并且只有在同一个 processing 代际仍为当前时，诊断状态才会标记为空闲。重复的 `session.stuck` 诊断会在会话保持不变时退避。 +- 模型空闲超时：如果在空闲窗口前没有响应分块到达，OpenClaw 会中止模型请求。`models.providers..timeoutSeconds` 会为较慢的本地/自托管提供商扩展该空闲看门狗；否则，OpenClaw 会在已配置时使用 `agents.defaults.timeoutSeconds`，默认上限为 120s。没有显式模型或智能体超时的 cron 触发运行会禁用空闲看门狗，并依赖 cron 外层超时。 +- 提供商 HTTP 请求超时：`models.providers..timeoutSeconds` 适用于该提供商的模型 HTTP 获取，包括连接、标头、正文、SDK 请求超时、总 guarded-fetch 中止处理和模型流空闲看门狗。对于 Ollama 等较慢的本地/自托管提供商，先使用此项，再提高整个智能体运行时超时。 ## 可能提前结束的位置 @@ -174,8 +171,8 @@ Harness 可以以不同方式适配这些钩子。Codex app-server harness 会 ## 相关 -- [工具](/zh-CN/tools) — 可用的智能体工具 -- [钩子](/zh-CN/automation/hooks) — 由智能体生命周期事件触发的事件驱动脚本 -- [压缩](/zh-CN/concepts/compaction) — 长对话如何被总结 -- [Exec 审批](/zh-CN/tools/exec-approvals) — shell 命令的审批门禁 +- [Tools](/zh-CN/tools) — 可用智能体工具 +- [Hooks](/zh-CN/automation/hooks) — 由智能体生命周期事件触发的事件驱动脚本 +- [Compaction](/zh-CN/concepts/compaction) — 长对话如何被摘要 +- [Exec Approvals](/zh-CN/tools/exec-approvals) — shell 命令的审批门禁 - [Thinking](/zh-CN/tools/thinking) — thinking/reasoning 级别配置 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 33b68abb2..61281c41b 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -1,74 +1,63 @@ --- read_when: - - 你需要精确的字段级配置语义或默认值 + - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考的链接 +summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键名、默认值，以及指向专用子系统参考的链接 title: 配置参考 x-i18n: - generated_at: "2026-05-04T22:54:29Z" + generated_at: "2026-05-05T03:06:17Z" model: gpt-5.5 provider: openai - source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684 + source_hash: fd0b6bf9a77d91bcc240088e4be92e44b6e70910efe00f7ed99534fb70983479 source_path: gateway/configuration-reference.md workflow: 16 --- -`~/.openclaw/openclaw.json` 的核心配置参考。对于面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。如需面向任务的概览，请参见[配置](/zh-CN/gateway/configuration)。 -涵盖主要的 OpenClaw 配置界面；当某个子系统有自己的更深入参考时，会链接到对应页面。渠道和插件拥有的命令目录，以及深层 memory/QMD 调节项，位于各自页面，而不在本页。 +涵盖主要的 OpenClaw 配置面，并在子系统有自己的更深入参考时链接到对应页面。渠道和插件拥有的命令目录以及深层记忆/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 表面验证配置文档基线哈希 -智能体查找路径：编辑前，使用 `gateway` 工具操作 `config.schema.lookup` -获取精确到字段级别的文档和约束。使用 -[配置](/zh-CN/gateway/configuration) 获取面向任务的指导，使用本页 -查看更广泛的字段映射、默认值以及指向子系统参考的链接。 +智能体查找路径：编辑前，使用 `gateway` 工具动作 `config.schema.lookup` 获取精确的字段级文档和约束。使用[配置](/zh-CN/gateway/configuration)查看面向任务的指南，并使用本页查看更宽泛的字段图、默认值以及指向子系统参考的链接。 -专门的深层参考： +专用深入参考： -- [记忆配置参考](/zh-CN/reference/memory-config)，用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 -- [斜杠命令](/zh-CN/tools/slash-commands)，用于当前内置 + 捆绑命令目录 -- 拥有对应渠道特定命令界面的渠道/插件页面 +- [记忆配置参考](/zh-CN/reference/memory-config)：用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 +- [Slash commands](/zh-CN/tools/slash-commands)：用于当前内置 + 内置捆绑命令目录 +- 归属渠道/插件页面：用于渠道特定的命令表面 -配置格式是 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 — 省略时 OpenClaw 会使用安全默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 — 省略时 OpenClaw 会使用安全默认值。 --- ## 渠道 -每个渠道的配置键已移至专用页面 — 请参阅 -[配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`， -包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 以及其他 -内置渠道（认证、访问控制、多账号、提及门控）。 +按渠道配置键已移至专用页面 — 请参见[配置 — 渠道](/zh-CN/gateway/config-channels)了解 `channels.*`，包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道（认证、访问控制、多账号、提及门控）。 ## 智能体默认值、多智能体、会话和消息 -已移至专用页面 — 请参阅 -[配置 — 智能体](/zh-CN/gateway/config-agents)，了解： +已移至专用页面 — 请参见[配置 — 智能体](/zh-CN/gateway/config-agents)，内容包括： - `agents.defaults.*`（工作区、模型、thinking、heartbeat、记忆、媒体、Skills、沙箱） - `multiAgent.*`（多智能体路由和绑定） - `session.*`（会话生命周期、压缩、修剪） - `messages.*`（消息投递、TTS、Markdown 渲染） - `talk.*`（Talk 模式） - - `talk.speechLocale`：iOS/macOS 上 Talk 语音识别的可选 BCP 47 区域设置 ID - - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`） + - `talk.speechLocale`：可选的 BCP 47 区域设置 ID，用于 iOS/macOS 上的 Talk 语音识别 + - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保留平台默认暂停窗口（`700 ms on macOS and Android, 900 ms on iOS`） ## 工具和自定义提供商 -工具策略、实验性开关、提供商支持的工具配置，以及自定义 -提供商 / base-URL 设置已移至专用页面 — 请参阅 -[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。 +工具策略、实验性开关、由提供商支持的工具配置，以及自定义提供商 / 基础 URL 设置已移至专用页面 — 请参见[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。 ## Models -提供商定义、模型允许列表和自定义提供商设置位于 -[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。 -`models` 根节点也拥有全局模型目录行为。 +提供商定义、模型允许列表和自定义提供商设置位于[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。`models` 根节点还拥有全局模型目录行为。 ```json5 { @@ -80,17 +69,12 @@ x-i18n: ``` - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：按提供商 ID 键控的自定义提供商映射。 -- `models.pricing.enabled`：控制后台价格引导；该引导会在 sidecar 和渠道到达 Gateway 网关 ready 路径后启动。当为 `false` 时， - Gateway 网关会跳过 OpenRouter 和 LiteLLM 价格目录拉取；已配置的 - `models.providers.*.models[].cost` 值仍可用于本地成本估算。 +- `models.providers`：按提供商 ID 作为键的自定义提供商映射。 +- `models.pricing.enabled`：控制后台定价引导流程，该流程会在 sidecars 和渠道到达 Gateway 网关就绪路径后启动。为 `false` 时，Gateway 网关会跳过 OpenRouter 和 LiteLLM 定价目录拉取；配置的 `models.providers.*.models[].cost` 值仍可用于本地成本估算。 ## MCP -OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由 -嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、 -`show`、`set` 和 `unset` 命令会管理此块，且在配置编辑期间不会连接到 -目标服务器。 +OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、`show`、`set` 和 `unset` 命令会管理此块，并且在编辑配置时不会连接到目标服务器。 ```json5 { @@ -114,18 +98,11 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由 } ``` -- `mcp.servers`：命名的 stdio 或远程 MCP 服务器定义，供公开已配置 MCP 工具的运行时使用。 - 远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`； - `type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和 - `openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。 -- `mcp.sessionIdleTtlMs`：会话作用域的内置 MCP 运行时的空闲 TTL。 - 一次性嵌入式运行会请求运行结束清理；此 TTL 是长生命周期会话和未来调用方的兜底。 -- `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时来热应用。 - 下一次工具发现/使用会从新配置重新创建它们，因此移除的 - `mcp.servers` 条目会立即被回收，而不是等待空闲 TTL。 +- `mcp.servers`：命名的 stdio 或远程 MCP 服务器定义，用于暴露已配置 MCP 工具的运行时。远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`；`type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和 `openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。 +- `mcp.sessionIdleTtlMs`：会话范围内置 MCP 运行时的空闲 TTL。一次性嵌入式运行会请求运行结束清理；此 TTL 是长期会话和未来调用方的兜底。 +- `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时来热应用。下一次工具发现/使用会基于新配置重新创建它们，因此移除的 `mcp.servers` 条目会立即回收，而不是等待空闲 TTL。 -请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 -[CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays) 了解运行时行为。 +运行时行为请参见 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 [CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。 ## Skills @@ -153,12 +130,11 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由 ``` - `allowBundled`：仅用于内置 Skills 的可选允许列表（不影响托管/工作区 Skills）。 -- `load.extraDirs`：额外的共享 Skills 根目录（最低优先级）。 +- `load.extraDirs`：额外共享 Skills 根目录（最低优先级）。 - `install.preferBrew`：为 true 时，如果 `brew` 可用，会优先使用 Homebrew 安装器，然后再回退到其他安装器类型。 -- `install.nodeManager`：用于 `metadata.openclaw.install` - 规范的节点安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false` 会禁用某个 Skill，即使它是内置/已安装的。 -- `entries..apiKey`：用于声明主环境变量的 Skills 的便捷配置（明文字符串或 SecretRef 对象）。 +- `install.nodeManager`：用于 `metadata.openclaw.install` 规格的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false` 会禁用某个 Skills，即使它是内置/已安装的。 +- `entries..apiKey`：为声明主环境变量的 Skills 提供的便捷项（明文字符串或 SecretRef 对象）。 --- @@ -188,46 +164,43 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex 包和 Claude 包，包括无清单的 Claude 默认布局包。 +- 发现流程接受原生 OpenClaw 插件，以及兼容的 Codex 捆绑包和 Claude 捆绑包，包括无清单的 Claude 默认布局捆绑包。 - **配置更改需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `bundledDiscovery`：新配置默认值为 `"allowlist"`，因此非空的 - `plugins.allow` 也会门控内置提供商插件，包括 Web 搜索 - 运行时提供商。Doctor 会为迁移的旧版允许列表配置写入 `"compat"`， - 以便在你选择加入前保留现有的内置提供商行为。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 -- `plugins.entries..env`：插件作用域的环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子和受支持的包提供钩子目录。 -- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可以从类型化钩子（如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`）读取原始对话内容。 -- `plugins.entries..subagent.allowModelOverride`：显式信任此插件，使其可为后台子智能体运行请求每次运行的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标的可选允许列表。只有在你有意允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（可用时由原生 OpenClaw 插件 schema 验证）。 -- 渠道插件账号/运行时设置位于 `channels.` 下，应由拥有该渠道的插件清单 `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。 +- `bundledDiscovery`：新配置默认使用 `"allowlist"`，因此非空的 `plugins.allow` 也会限制内置提供商插件，包括 Web 搜索运行时提供商。Doctor 会为迁移的旧版允许列表配置写入 `"compat"`，以保留现有内置提供商行为，直到你选择启用。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（在插件支持时）。 +- `plugins.entries..env`：插件范围的环境变量映射。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子和受支持的捆绑包提供的钩子目录。 +- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可以从类型化钩子读取原始对话内容，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`。 +- `plugins.entries..subagent.allowModelOverride`：显式信任此插件，使其可以为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可用的规范 `provider/model` 目标的可选允许列表。仅当你明确想允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。 +- 渠道插件账号/运行时设置位于 `channels.` 下，并应由归属插件清单的 `channelConfigs` 元数据描述，而不是由中心化 OpenClaw 选项注册表描述。 - `plugins.entries.firecrawl.config.webFetch`：Firecrawl Web 抓取提供商设置。 - `apiKey`：Firecrawl API key（接受 SecretRef）。回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 - `baseUrl`：Firecrawl API 基础 URL（默认：`https://api.firecrawl.dev`；自托管覆盖必须指向私有/内部端点）。 - - `onlyMainContent`：仅提取页面主内容（默认：`true`）。 - - `maxAgeMs`：最大缓存时长，单位为毫秒（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时，单位为秒（默认：`60`）。 + - `onlyMainContent`：仅从页面提取主要内容（默认：`true`）。 + - `maxAgeMs`：最大缓存年龄，单位为毫秒（默认：`172800000` / 2 天）。 + - `timeoutSeconds`：抓取请求超时时间，单位为秒（默认：`60`）。 - `plugins.entries.xai.config.xSearch`：xAI X Search（Grok Web 搜索）设置。 - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：记忆 Dreaming 设置。请参阅 [Dreaming](/zh-CN/concepts/dreaming) 了解阶段和阈值。 +- `plugins.entries.memory-core.config.dreaming`：记忆 Dreaming 设置。阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。 - `enabled`：主 Dreaming 开关（默认 `false`）。 - `frequency`：每次完整 Dreaming 扫描的 cron 频率（默认为 `"0 3 * * *"`）。 - `model`：可选的 Dream Diary 子智能体模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；与 `allowedModels` 搭配使用以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退。 - - 阶段策略和阈值是实现细节（不是面向用户的配置键）。 -- 完整记忆配置位于 [记忆配置参考](/zh-CN/reference/memory-config)： + - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 +- 完整记忆配置位于[记忆配置参考](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude 包插件还可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些值作为经过清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。 +- 启用的 Claude 捆绑插件也可以从 `settings.json` 贡献嵌入式 Pi 默认值；OpenClaw 会将这些应用为经过清理的智能体设置，而不是原始 OpenClaw 配置补丁。 - `plugins.slots.memory`：选择活动记忆插件 ID，或使用 `"none"` 禁用记忆插件。 -- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；默认为 `"legacy"`，除非你安装并选择了另一个引擎。 +- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；除非你安装并选择其他引擎，否则默认为 `"legacy"`。 -请参阅 [插件](/zh-CN/tools/plugin)。 +请参见[插件](/zh-CN/tools/plugin)。 --- @@ -235,10 +208,10 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由 `commitments` 控制推断式跟进记忆：OpenClaw 可以从对话轮次中检测 check-in，并通过 heartbeat 运行投递它们。 -- `commitments.enabled`：为推断式跟进承诺启用隐藏 LLM 提取、存储和 heartbeat 投递。默认值：`false`。 -- `commitments.maxPerDay`：每个智能体会话在滚动一天内投递的最大推断式跟进承诺数量。默认值：`3`。 +- `commitments.enabled`：启用隐藏的 LLM 提取、存储和 heartbeat 投递，用于推断式跟进承诺。默认：`false`。 +- `commitments.maxPerDay`：每个智能体会话在滚动一天内投递的最大推断式跟进承诺数。默认：`3`。 -请参阅 [推断式跟进承诺](/zh-CN/concepts/commitments)。 +请参见[推断式跟进承诺](/zh-CN/concepts/commitments)。 --- @@ -289,30 +262,30 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `tabCleanup` 会在空闲时间后，或当某个会话超过上限时，回收已跟踪的主智能体标签页。设置 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 可禁用对应的单项清理模式。 -- 未设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork` 时它会被禁用，因此浏览器导航默认保持严格。 -- 只有在你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止限制。 +- `tabCleanup` 会在空闲一段时间后，或在会话超出上限时，回收已跟踪的主智能体标签页。设置 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 可禁用对应的单项清理模式。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 未设置时处于禁用状态，因此浏览器导航默认保持严格。 +- 仅当你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止规则约束。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 - 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。 -- 远程配置文件仅支持附加（禁用启动/停止/重置）。 -- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当你的提供商提供直接的 DevTools WebSocket URL 时使用 WS(S)。 -- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 `attachOnly` CDP 可达性以及打开标签页请求。托管的 loopback 配置文件保留本地 CDP 默认值。 -- 如果外部托管的 CDP 服务可通过 loopback 访问，请将该配置文件的 `attachOnly: true`；否则 OpenClaw 会把该 loopback 端口视为本地托管浏览器配置文件，并可能报告本地端口所有权错误。 -- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以在所选主机上附加，或通过已连接的浏览器节点附加。 +- 远程配置文件仅可附加（禁用启动/停止/重置）。 +- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当你的提供商给出直接的 DevTools WebSocket URL 时使用 WS(S)。 +- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 `attachOnly` CDP 可达性以及打开标签页请求。托管的 local loopback 配置文件保留本地 CDP 默认值。 +- 如果外部托管的 CDP 服务可通过 loopback 访问，请将该配置文件的 `attachOnly: true`；否则 OpenClaw 会将该 loopback 端口视为本地托管浏览器配置文件，并可能报告本地端口所有权错误。 +- `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`。 -- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 `browser.executablePath`。可用它让一个配置文件运行在 Chrome 中，另一个运行在 Brave 中。 -- 本地托管配置文件在进程启动后使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP 发现，并使用 `browser.localCdpReadyTimeoutMs` 等待启动后的 CDP websocket 就绪。在较慢主机上，如果 Chrome 启动成功但就绪检查与启动过程竞争，请调高这些值。两个值都必须是最大为 `120000` 毫秒的正整数；无效配置值会被拒绝。 +- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：使用快照/引用驱动操作，而非 CSS 选择器定位；单文件上传钩子；无对话框超时覆盖；无 `wait --load networkidle`；并且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅对远程 CDP 显式设置 `cdpUrl`。 +- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 `browser.executablePath`。可用它让一个配置文件在 Chrome 中运行，另一个在 Brave 中运行。 +- 本地托管配置文件在进程启动后使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP 发现，并使用 `browser.localCdpReadyTimeoutMs` 等待启动后的 CDP WebSocket 就绪。在较慢的主机上，如果 Chrome 已成功启动但就绪检查与启动过程发生竞态，可调高这些值。两个值都必须是最大为 `120000` ms 的正整数；无效配置值会被拒绝。 - 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- `browser.executablePath` 和 `browser.profiles..executablePath` 都接受 `~` 和 `~/...`，并会在 Chromium 启动前解析为你的操作系统主目录。`existing-session` 配置文件中的按配置文件 `userDataDir` 也会展开波浪号。 -- 控制服务：仅 loopback（端口派生自 `gateway.port`，默认值为 `18791`）。 -- `extraArgs` 会向本地 Chromium 启动追加额外启动标志（例如 `--disable-gpu`、窗口尺寸或调试标志）。 +- `browser.executablePath` 和 `browser.profiles..executablePath` 在 Chromium 启动前都接受 `~` 和 `~/...` 来表示你的操作系统主目录。`existing-session` 配置文件上的按配置文件 `userDataDir` 也会展开波浪号。 +- 控制服务：仅 loopback（端口派生自 `gateway.port`，默认 `18791`）。 +- `extraArgs` 会向本地 Chromium 启动追加额外启动标志（例如 `--disable-gpu`、窗口大小或调试标志）。 --- -## UI +## 用户界面 ```json5 { @@ -327,7 +300,7 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由 ``` - `seamColor`：原生应用 UI chrome 的强调色（Talk Mode 气泡色调等）。 -- `assistant`：Control UI 身份覆盖。回退到活跃智能体身份。 +- `assistant`：控制 UI 身份覆盖。回退到活跃智能体身份。 --- @@ -406,51 +379,51 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由 - `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 -- `port`：用于 WS + HTTP 的单个多路复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `port`：WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 - **旧版绑定别名**：在 `gateway.bind` 中使用绑定模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认 `loopback` 绑定会在容器内监听 `127.0.0.1`。使用 Docker 桥接网络（`-p 18789:18789`）时，流量会从 `eth0` 到达，因此 Gateway 网关无法访问。使用 `--network host`，或设置 `bind: "lan"`（或使用 `bind: "custom"` 并设置 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **认证**：默认必需。非 loopback 绑定需要 Gateway 网关认证。实践中，这意味着需要共享令牌/密码，或使用带身份感知能力的反向代理并设置 `gateway.auth.mode: "trusted-proxy"`。新手引导向导默认会生成令牌。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。两者都已配置而模式未设置时，启动以及服务安装/修复流程会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的 local loopback 设置；新手引导提示有意不提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将浏览器/用户认证委托给带身份感知能力的反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式默认预期代理来源为**非 loopback**；同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。内部同主机调用方可以使用 `gateway.auth.password` 作为本地直连回退；`gateway.auth.token` 仍然与 trusted-proxy 模式互斥。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份标头可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头认证；它们会改用 Gateway 网关的正常 HTTP 认证模式。此无令牌流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时默认为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域应用（shared-secret 和 device-token 会分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败前被串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求时触发限流器，而不是两个请求都以普通不匹配的形式竞态通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意也希望对 localhost 流量限流时（用于测试设置或严格代理部署），将其设置为 `false`。 -- 浏览器来源的 WS 认证尝试始终会被限流，并禁用 loopback 豁免（纵深防御，防止基于浏览器的 localhost 暴力破解）。 -- 在 loopback 上，这些浏览器来源锁定会按规范化后的 `Origin` - 值隔离，因此来自一个 localhost 来源的重复失败不会自动 +- **Docker 注意事项**：默认的 `loopback` 绑定会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此无法访问 Gateway 网关。使用 `--network host`，或设置 `bind: "lan"`（或使用 `customBindHost: "0.0.0.0"` 设置 `bind: "custom"`）以监听所有接口。 +- **认证**：默认必需。非 loopback 绑定需要 Gateway 网关认证。实际使用中，这意味着需要共享 token/密码，或使用带身份感知的反向代理并设置 `gateway.auth.mode: "trusted-proxy"`。新手引导向导默认会生成一个 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。当二者都已配置且未设置 mode 时，启动以及服务安装/修复流程会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅用于可信的 local loopback 设置；新手引导提示有意不提供此选项。 +- `gateway.auth.mode: "trusted-proxy"`：将浏览器/用户认证委托给带身份感知的反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [可信代理认证](/zh-CN/gateway/trusted-proxy-auth)）。此模式默认预期代理来源为**非 loopback**；同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。内部同主机调用方可使用 `gateway.auth.password` 作为本地直连回退；`gateway.auth.token` 仍与 trusted-proxy 模式互斥。 +- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份标头可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不**使用该 Tailscale 标头认证；它们改为遵循 Gateway 网关的常规 HTTP 认证模式。此无 token 流程假定 Gateway 网关主机可信。当 `tailscale.mode = "serve"` 时默认为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限制器。按客户端 IP 和认证作用域分别应用（shared-secret 和 device-token 会独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败前被串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求触发限制器，而不是两个请求都以普通不匹配的方式竞速通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意让 localhost 流量也被限速时（用于测试设置或严格代理部署），请设为 `false`。 +- 浏览器来源的 WS 认证尝试始终会被节流，并禁用 loopback 豁免（作为防御纵深，防止基于浏览器的 localhost 暴力破解）。 +- 在 loopback 上，这些浏览器来源锁定会按规范化的 `Origin` + 值隔离，因此一个 localhost 来源的重复失败不会自动 锁定另一个来源。 - `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开，需要认证）。 - `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时必需。 -- `controlUi.chatMessageMaxWidth`：分组 Control UI 聊天消息的可选最大宽度。接受受限 CSS 宽度值，例如 `960px`、`82%`、`min(1280px, 82%)` 和 `calc(100% - 2rem)`。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，会为有意依赖 Host 标头来源策略的部署启用 Host 标头来源回退。 +- `controlUi.chatMessageMaxWidth`：分组 Control UI 聊天消息的可选最大宽度。接受受约束的 CSS 宽度值，例如 `960px`、`82%`、`min(1280px, 82%)` 和 `calc(100% - 2rem)`。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 标头来源策略的部署启用 Host 标头来源回退。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 - `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境中的 - break-glass 覆盖项，允许明文 `ws://` 连接到受信任的私有网络 - IP；默认仍然仅允许明文连接到 loopback。没有等效的 `openclaw.json` + 应急覆盖，允许明文 `ws://` 连接到可信的私有网络 + IP；明文默认仍仅限 loopback。没有等效的 `openclaw.json` 配置，并且 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - 等浏览器私有网络配置不会影响 Gateway 网关 WebSocket - 客户端。 + 等浏览器私有网络配置不会影响 Gateway 网关 + WebSocket 客户端。 - `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 Gateway 网关发布基于中继的注册后所使用的外部 APNs 中继的基础 HTTPS URL。此 URL 必须匹配编译进 iOS 构建的中继 URL。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到中继的发送超时，单位为毫秒。默认值为 `10000`。 -- 基于中继的注册会委托给特定 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并将注册作用域的发送授权转发给 Gateway 网关。另一个 Gateway 网关无法复用该已存储注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述中继配置的临时环境变量覆盖项。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发使用的逃生口，用于 loopback HTTP 中继 URL。生产中继 URL 应保持使用 HTTPS。 -- `gateway.handshakeTimeoutMs`：认证前 Gateway 网关 WebSocket 握手超时，单位为毫秒。默认值：`15000`。设置后，`OPENCLAW_HANDSHAKE_TIMEOUT_MS` 优先级更高。对于负载较高或低功耗主机，本地客户端可能在启动预热尚未稳定时连接，可增大此值。 -- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位为分钟。设置为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧套接字阈值，单位为分钟。保持该值大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内的最大健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：每个渠道的健康监控重启退出开关，同时保持全局监控启用。 -- `channels..accounts..healthMonitor.enabled`：多账号渠道的每账号覆盖项。设置后，其优先级高于渠道级覆盖项。 -- 只有在未设置 `gateway.auth.*` 时，本地 Gateway 网关调用路径才可以使用 `gateway.remote.*` 作为回退。 -- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 且未解析，解析会失败关闭（不会被远程回退掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求具备使用 `gateway.auth.mode: "trusted-proxy"` 的资格。 -- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，用于失败关闭行为。 -- `gateway.nodes.pairing.autoApproveCidrs`：可选 CIDR/IP 允许列表，用于自动批准没有请求作用域的首次节点设备配对。未设置时禁用。它不会自动批准操作员/浏览器/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：配对和平台允许列表评估后，对已声明节点命令进行全局允许/拒绝塑形。使用 `allowCommands` 来选择启用危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式允许本会包含某个命令，`denyCommands` 也会移除该命令。节点更改其已声明命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。 +- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建将中继支持的注册发布到 Gateway 网关后，所使用的外部 APNs 中继的基础 HTTPS URL。此 URL 必须与编译进 iOS 构建的中继 URL 匹配。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到中继的发送超时时间，单位为毫秒。默认为 `10000`。 +- 中继支持的注册会委托给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并将注册作用域的发送授权转发给 Gateway 网关。另一个 Gateway 网关无法复用该已存储的注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上方中继配置的临时环境变量覆盖。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发使用的逃生通道，用于 loopback HTTP 中继 URL。生产中继 URL 应保持使用 HTTPS。 +- `gateway.handshakeTimeoutMs`：认证前 Gateway 网关 WebSocket 握手超时时间，单位为毫秒。默认：`15000`。设置 `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 时它优先生效。在负载较高或低性能主机上，如果本地客户端可连接但启动预热仍在稳定中，请增大此值。 +- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位为分钟。设为 `0` 可全局禁用健康监控重启。默认：`5`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。保持此值大于或等于 `gateway.channelHealthCheckMinutes`。默认：`30`。 +- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道/账户的最大健康监控重启次数。默认：`10`。 +- `channels..healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保留全局监控启用。 +- `channels..accounts..healthMonitor.enabled`：多账户渠道的按账户覆盖。设置后，它优先于渠道级覆盖。 +- 只有在未设置 `gateway.auth.*` 时，本地 Gateway 网关调用路径才能使用 `gateway.remote.*` 作为回退。 +- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 且无法解析，解析会以关闭方式失败（不会被远程回退掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。Loopback 条目对于同主机代理/本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**使 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。 +- `allowRealIpFallback`：当为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现失败关闭行为。 +- `gateway.nodes.pairing.autoApproveCidrs`：可选 CIDR/IP 允许列表，用于自动批准首次节点设备配对，且不带请求的作用域。未设置时禁用。它不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：配对和平台允许列表评估之后，对已声明节点命令进行全局允许/拒绝塑形。使用 `allowCommands` 选择启用危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式允许本会包含某个命令，`denyCommands` 也会将其移除。节点更改其声明的命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。 - `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 阻止的额外工具名称（扩展默认拒绝列表）。 - `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。 @@ -460,14 +433,14 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由 - Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 - Responses API：`gateway.http.endpoints.responses.enabled`。 -- Responses URL 输入强化： +- Responses URL 输入加固： - `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.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 禁用 URL 获取。 +- 可选响应加固标头： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅为你控制的 HTTPS 来源设置；参见 [可信代理认证](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 @@ -499,11 +472,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 捆绑包路径。 +- `keyPath`：TLS 私钥文件的文件系统路径；保持权限受限。 +- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 ### `gateway.reload` @@ -521,11 +494,11 @@ openclaw gateway --port 19001 - `mode`：控制运行时如何应用配置编辑。 - `"off"`：忽略实时编辑；更改需要显式重启。 - - `"restart"`：配置更改时始终重启 Gateway 网关进程。 - - `"hot"`：在进程内应用更改而不重启。 + - `"restart"`：配置变更时始终重启 Gateway 网关进程。 + - `"hot"`：在进程内应用更改，无需重启。 - `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。 -- `debounceMs`：应用配置更改前的防抖窗口，单位为毫秒（非负整数）。 -- `deferralTimeoutMs`：在强制重启前等待进行中操作的可选最大时间，单位为毫秒。省略时使用默认有界等待（`300000`）；设置为 `0` 表示无限等待并定期记录仍有待处理的警告。 +- `debounceMs`：应用配置变更前的去抖窗口，单位为 ms（非负整数）。 +- `deferralTimeoutMs`：强制重启前等待进行中操作的可选最长时间，单位为 ms。省略时使用默认的有界等待（`300000`）；设为 `0` 可无限期等待并记录周期性的仍待处理警告。 --- @@ -562,39 +535,39 @@ openclaw gateway --port 19001 } ``` -认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -查询字符串中的钩子令牌会被拒绝。 +凭证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 +查询字符串中的钩子 token 会被拒绝。 验证和安全注意事项： -- `hooks.enabled=true` 需要非空的 `hooks.token`。 -- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关令牌会被拒绝。 +- `hooks.enabled=true` 要求 `hooks.token` 非空。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关 token 会被拒绝。 - `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 - 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该选择加入。 +- 如果映射或预设使用模板化 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该选择加入。 **端点：** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - 只有当 `hooks.allowRequestSessionKey=true`（默认值：`false`）时，才接受请求负载中的 `sessionKey`。 + - 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受请求载荷中的 `sessionKey`。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - - 模板渲染的映射 `sessionKey` 值会被视为外部提供，也需要 `hooks.allowRequestSessionKey=true`。 + - 模板渲染的映射 `sessionKey` 值会被视为外部提供，也要求 `hooks.allowRequestSessionKey=true`。 -- `match.path` 匹配 `/hooks` 后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 匹配通用路径的负载字段。 -- 类似 `{{messages[0].subject}}` 的模板会从负载读取。 +- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 +- `match.source` 为通用路径匹配某个载荷字段。 +- 类似 `{{messages[0].subject}}` 的模板会从载荷中读取。 - `transform` 可以指向返回钩子动作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且保留在 `hooks.transformsDir` 内（绝对路径和目录遍历会被拒绝）。 - - 将 `hooks.transformsDir` 保持在 `~/.openclaw/hooks/transforms` 下；工作区 Skills 目录会被拒绝。如果 `openclaw doctor` 报告此路径无效，请将转换模块移动到钩子转换目录中，或移除 `hooks.transformsDir`。 + - `transform.module` 必须是相对路径，并且保留在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。 + - 将 `hooks.transformsDir` 保持在 `~/.openclaw/hooks/transforms` 下；工作区 Skills 目录会被拒绝。如果 `openclaw doctor` 报告此路径无效，请将转换模块移入 hooks transforms 目录，或移除 `hooks.transformsDir`。 - `agentId` 路由到特定智能体；未知 ID 会回退到默认值。 -- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 拒绝全部）。 -- `defaultSessionKey`：用于没有显式 `sessionKey` 的钩子智能体运行的可选固定会话键。 -- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化的 `sessionKey` 时，它会变为必需。 -- `deliver: true` 会将最终回复发送到渠道；`channel` 默认值为 `last`。 +- `allowedAgentIds`：限制显式路由（`*` 或省略 = 全部允许，`[]` = 全部拒绝）。 +- `defaultSessionKey`：没有显式 `sessionKey` 的钩子智能体运行使用的可选固定会话键。 +- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化 `sessionKey` 时，它会变为必需。 +- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 - `model` 会为此次钩子运行覆盖 LLM（如果设置了模型目录，则必须被允许）。 @@ -603,7 +576,7 @@ openclaw gateway --port 19001 - 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 - 如果保留这种按消息路由，请设置 `hooks.allowRequestSessionKey: true`，并限制 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 -- 如果需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖预设，而不是使用模板化默认值。 +- 如果需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖预设，而不是使用模板化默认值。 ```json5 { @@ -631,7 +604,7 @@ openclaw gateway --port 19001 --- -## Canvas 主机 +## Canvas 宿主 ```json5 { @@ -646,15 +619,15 @@ openclaw gateway --port 19001 - 通过 Gateway 网关端口下的 HTTP 提供智能体可编辑的 HTML/CSS/JS 和 A2UI： - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- 仅限本地：保持 `gateway.bind: "loopback"`（默认值）。 -- 非 loopback 绑定：canvas 路由需要 Gateway 网关认证（令牌/密码/受信任代理），与其他 Gateway 网关 HTTP 表面相同。 -- Node WebViews 通常不会发送认证标头；节点配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告节点作用域的能力 URL。 -- 能力 URL 绑定到活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 -- 向提供的 HTML 注入实时重载客户端。 -- 为空时自动创建起始 `index.html`。 +- 仅本地：保持 `gateway.bind: "loopback"`（默认）。 +- 非 loopback 绑定：canvas 路由要求 Gateway 网关认证（token/password/trusted-proxy），与其他 Gateway 网关 HTTP 表面相同。 +- 节点 WebView 通常不会发送认证标头；节点配对并连接后，Gateway 网关会播发用于 canvas/A2UI 访问的节点作用域能力 URL。 +- 能力 URL 绑定到活动节点 WS 会话，并且很快过期。不会使用基于 IP 的回退。 +- 将实时重载客户端注入到提供的 HTML 中。 +- 为空时自动创建初始 `index.html`。 - 还会在 `/__openclaw__/a2ui/` 提供 A2UI。 - 更改需要重启 Gateway 网关。 -- 对于大型目录或 `EMFILE` 错误，请禁用实时重载。 +- 对大型目录或 `EMFILE` 错误，请禁用实时重载。 --- @@ -673,10 +646,10 @@ openclaw gateway --port 19001 ``` - `minimal`（启用内置 `bonjour` 插件时的默认值）：从 TXT 记录中省略 `cliPath` + `sshPort`。 -- `full`：包含 `cliPath` + `sshPort`；LAN 组播通告仍然要求启用内置 `bonjour` 插件。 -- `off`：在不更改插件启用状态的情况下抑制 LAN 组播通告。 -- 内置 `bonjour` 插件会在 macOS 主机上自动启动，并在 Linux、Windows 和容器化 Gateway 网关部署中选择加入。 -- 当系统主机名是有效 DNS 标签时，主机名默认使用系统主机名，否则回退到 `openclaw`。可使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 +- `full`：包含 `cliPath` + `sshPort`；LAN 多播通告仍要求启用内置 `bonjour` 插件。 +- `off`：在不更改插件启用状态的情况下抑制 LAN 多播通告。 +- 内置 `bonjour` 插件会在 macOS 主机上自动启动，在 Linux、Windows 和容器化 Gateway 网关部署上需要选择加入。 +- 当系统主机名是有效 DNS 标签时，主机名默认使用系统主机名，否则回退到 `openclaw`。可用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 ### 广域 (DNS-SD) @@ -688,7 +661,7 @@ openclaw gateway --port 19001 } ``` -在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale 拆分 DNS。 +在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 设置：`openclaw dns setup --apply`。 @@ -713,10 +686,10 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境中缺少对应键时，才会应用内联环境变量。 -- `.env` 文件：CWD `.env` + `~/.openclaw/.env`（两者都不会覆盖已有变量）。 +- 仅当进程环境缺少该键时，才会应用内联环境变量。 +- `.env` 文件：CWD `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 - `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。 -- 完整优先级见[环境](/zh-CN/help/environment)。 +- 请参阅[环境](/zh-CN/help/environment)了解完整优先级。 ### 环境变量替换 @@ -732,14 +705,14 @@ openclaw gateway --port 19001 - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 - 缺失或为空的变量会在配置加载时抛出错误。 -- 使用 `$${VAR}` 转义，表示字面量 `${VAR}`。 +- 使用 `$${VAR}` 转义，以表示字面量 `${VAR}`。 - 可与 `$include` 配合使用。 --- ## 密钥 -密钥引用是增量能力：明文值仍然可用。 +密钥引用是增量式的：明文值仍然可用。 ### `SecretRef` @@ -749,18 +722,18 @@ openclaw gateway --port 19001 { source: "env" | "file" | "exec", provider: "default", id: "..." } ``` -校验： +验证： - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` - `source: "env"` id 模式：`^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） - `source: "exec"` id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` ids 不得包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝） +- `source: "exec"` id 不得包含 `.` 或 `..` 作为斜杠分隔的路径段（例如 `a/../b` 会被拒绝） -### 支持的凭据作用面 +### 支持的凭证表面 -- 规范矩阵：[SecretRef 凭据作用面](/zh-CN/reference/secretref-credential-surface) -- `secrets apply` 目标支持的 `openclaw.json` 凭据路径。 +- 规范矩阵：[SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 目标支持的 `openclaw.json` 凭证路径。 - `auth-profiles.json` 引用包含在运行时解析和审计覆盖范围内。 ### 密钥提供商配置 @@ -793,18 +766,18 @@ openclaw gateway --port 19001 注意： -- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。 -- 当 Windows ACL 校验不可用时，文件和 exec 提供商路径会失败关闭。仅对无法校验的可信路径设置 `allowInsecurePath: true`。 -- `exec` 提供商要求绝对 `command` 路径，并通过 stdin/stdout 使用协议载荷。 -- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时校验解析后的目标路径。 +- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- 当 Windows ACL 验证不可用时，file 和 exec 提供商路径会失败关闭。仅对无法验证但可信的路径设置 `allowInsecurePath: true`。 +- `exec` 提供商要求使用绝对 `command` 路径，并在 stdin/stdout 上使用协议载荷。 +- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证解析后的目标路径。 - 如果配置了 `trustedDirs`，可信目录检查会应用于解析后的目标路径。 -- 默认情况下，`exec` 子进程环境是最小化的；请使用 `passEnv` 显式传入所需变量。 -- 密钥引用会在激活时解析为内存快照，随后请求路径只读取该快照。 -- 激活期间会应用活动作用面过滤：已启用作用面上的未解析引用会导致启动/重载失败，而非活动作用面会跳过并输出诊断信息。 +- `exec` 子环境默认是最小化的；请使用 `passEnv` 显式传递所需变量。 +- 密钥引用会在激活时解析为内存中的快照，之后请求路径只读取该快照。 +- 激活期间会应用活动表面过滤：启用表面上未解析的引用会导致启动或重载失败，而非活动表面会被跳过并生成诊断信息。 --- -## 凭证存储 +## 认证存储 ```json5 { @@ -822,14 +795,14 @@ openclaw gateway --port 19001 } ``` -- 每个智能体的配置文件存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持静态凭据模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- 旧版扁平 `auth-profiles.json` 映射（例如 `{ "provider": { "apiKey": "..." } }`）不是运行时格式；`openclaw doctor --fix` 会将它们重写为规范的 `provider:default` API-key 配置文件，并创建 `.legacy-flat.*.bak` 备份。 -- OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭据。 -- 静态运行时凭据来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会将其清理。 +- 每个智能体的 profile 存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 支持静态凭证模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- 旧版扁平 `auth-profiles.json` 映射（例如 `{ "provider": { "apiKey": "..." } }`）不是运行时格式；`openclaw doctor --fix` 会将其重写为规范的 `provider:default` API-key profile，并生成 `.legacy-flat.*.bak` 备份。 +- OAuth 模式 profile（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 +- 静态运行时凭证来自内存中已解析的快照；发现旧版静态 `auth.json` 条目时会将其清理。 - 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。 -- 见 [OAuth](/zh-CN/concepts/oauth)。 -- 密钥运行时行为和 `audit/configure/apply` 工具：[密钥管理](/zh-CN/gateway/secrets)。 +- 请参阅 [OAuth](/zh-CN/concepts/oauth)。 +- Secrets 运行时行为和 `audit/configure/apply` 工具：[Secrets 管理](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -851,19 +824,19 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`：当配置文件因真正的账单/额度不足错误失败时，以小时为单位的基础退避时间（默认：`5`）。明确的账单文本即使出现在 `401`/`403` 响应中，仍可能归入这里，但特定提供商的文本匹配器会限定在拥有它们的提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或组织/工作区支出限制消息则继续走 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的按提供商覆盖账单退避小时数。 -- `billingMaxHours`：账单退避指数增长的小时数上限（默认：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟数上限（默认：`60`）。 -- `failureWindowHours`：用于退避计数器的滚动窗口小时数（默认：`24`）。 -- `overloadedProfileRotations`：在切换到模型回退之前，过载错误允许的同一提供商认证配置文件轮换最大次数（默认：`1`）。诸如 `ModelNotReadyException` 之类的提供商繁忙形态会归入这里。 -- `overloadedBackoffMs`：在重试过载的提供商/配置文件轮换之前的固定延迟（默认：`0`）。 -- `rateLimitedProfileRotations`：在切换到模型回退之前，限流错误允许的同一提供商认证配置文件轮换最大次数（默认：`1`）。该限流桶包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 +- `billingBackoffHours`: 当配置文件因真实的账单/余额不足错误失败时，以小时为单位的基础退避时间（默认值：`5`）。明确的账单文本即使出现在 `401`/`403` 响应中，仍可能归入这里，但提供商特定的文本匹配器会保持限定在拥有它们的提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或组织/工作区支出限制消息会保留在 `rate_limit` 路径中。 +- `billingBackoffHoursByProvider`: 可选的按提供商覆盖账单退避小时数。 +- `billingMaxHours`: 账单退避指数增长的小时上限（默认值：`24`）。 +- `authPermanentBackoffMinutes`: 高置信度 `auth_permanent` 失败的基础退避时间，以分钟为单位（默认值：`10`）。 +- `authPermanentMaxMinutes`: `auth_permanent` 退避增长的分钟上限（默认值：`60`）。 +- `failureWindowHours`: 用于退避计数器的滚动窗口，以小时为单位（默认值：`24`）。 +- `overloadedProfileRotations`: 在切换到模型回退之前，针对过载错误允许的同一提供商身份配置轮换最大次数（默认值：`1`）。诸如 `ModelNotReadyException` 的提供商忙碌形态会归入这里。 +- `overloadedBackoffMs`: 在重试过载的提供商/配置轮换之前的固定延迟（默认值：`0`）。 +- `rateLimitedProfileRotations`: 在切换到模型回退之前，针对限流错误允许的同一提供商身份配置轮换最大次数（默认值：`1`）。该限流桶包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- -## 日志 +## 日志记录 ```json5 { @@ -879,10 +852,10 @@ openclaw gateway --port 19001 ``` - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 -- 设置 `logging.file` 可使用稳定路径。 -- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。 -- `maxFileBytes`：轮换前活动日志文件的最大字节数（正整数；默认：`104857600` = 100 MB）。OpenClaw 会在活动文件旁保留最多五个编号归档文件。 -- `redactSensitive` / `redactPatterns`：对控制台输出、文件日志、OTLP 日志记录以及持久化的会话转录文本进行尽力而为的遮蔽。`redactSensitive: "off"` 只会禁用这项通用日志/转录策略；UI/工具/诊断安全表面仍会在发出前遮蔽密钥。 +- 设置 `logging.file` 以使用稳定路径。 +- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 +- `maxFileBytes`: 轮转前活动日志文件的最大字节数（正整数；默认值：`104857600` = 100 MB）。OpenClaw 会在活动文件旁最多保留五个编号归档。 +- `redactSensitive` / `redactPatterns`: 对控制台输出、文件日志、OTLP 日志记录以及持久化的会话转录文本进行尽力掩码。`redactSensitive: "off"` 只会禁用这一通用日志/转录策略；UI/工具/诊断安全表面在发出前仍会遮蔽密钥。 --- @@ -894,6 +867,7 @@ openclaw gateway --port 19001 enabled: true, flags: ["telegram.*"], stuckSessionWarnMs: 30000, + stuckSessionAbortMs: 600000, otel: { enabled: false, @@ -930,25 +904,26 @@ openclaw gateway --port 19001 } ``` -- `enabled`：仪表输出的总开关（默认：`true`）。 -- `flags`：启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 这类通配符）。 -- `stuckSessionWarnMs`：用于将长时间运行的处理会话分类为 `session.long_running`、`session.stalled` 或 `session.stuck` 的无进展时间阈值，单位为 ms。回复、工具、状态、分块和 ACP 进度会重置计时器；重复的 `session.stuck` 诊断会在未变化时退避。 -- `otel.enabled`：启用 OpenTelemetry 导出流水线（默认：`false`）。完整配置、信号目录和隐私模型见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 -- `otel.endpoint`：用于 OTel 导出的收集器 URL。 -- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的特定信号 OTLP 端点。设置后，它们只会覆盖对应信号的 `otel.endpoint`。 -- `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据标头。 -- `otel.serviceName`：资源属性的服务名称。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用跟踪、指标或日志导出。 -- `otel.sampleRate`：跟踪采样率 `0`–`1`。 -- `otel.flushIntervalMs`：周期性遥测刷新间隔，单位为 ms。 -- `otel.captureContent`：选择性启用 OTEL span 属性的原始内容捕获。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于最新实验性 GenAI span 提供商属性的环境开关。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI 指标使用有界语义属性。 -- `OPENCLAW_OTEL_PRELOADED=1`：适用于已经注册全局 OpenTelemetry SDK 的宿主的环境开关。随后 OpenClaw 会跳过插件拥有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。 -- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：当匹配的配置键未设置时使用的特定信号端点环境变量。 -- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。 -- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含的内容（全部默认：`true`）。 +- `enabled`: instrumentation 输出的总开关（默认值：`true`）。 +- `flags`: 启用定向日志输出的标志字符串数组（支持像 `"telegram.*"` 或 `"*"` 这样的通配符）。 +- `stuckSessionWarnMs`: 用于将长时间运行的处理会话分类为 `session.long_running`、`session.stalled` 或 `session.stuck` 的无进展时长阈值，以毫秒为单位。回复、工具、Status、块和 ACP 进度会重置计时器；重复的 `session.stuck` 诊断在未变化时会退避。 +- `stuckSessionAbortMs`: 符合条件的停滞活动工作在为了恢复而可能被中止排空之前的无进展时长阈值，以毫秒为单位。未设置时，OpenClaw 会使用更安全的扩展嵌入式运行窗口，即至少 10 分钟且为 `stuckSessionWarnMs` 的 5 倍。 +- `otel.enabled`: 启用 OpenTelemetry 导出管线（默认值：`false`）。完整配置、信号目录和隐私模型见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 +- `otel.endpoint`: OTel 导出的收集器 URL。 +- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: 可选的特定信号 OTLP 端点。设置后，它们只会覆盖该信号的 `otel.endpoint`。 +- `otel.protocol`: `"http/protobuf"`（默认）或 `"grpc"`。 +- `otel.headers`: 随 OTel 导出请求发送的额外 HTTP/gRPC 元数据标头。 +- `otel.serviceName`: 资源属性的服务名称。 +- `otel.traces` / `otel.metrics` / `otel.logs`: 启用 trace、metrics 或 log 导出。 +- `otel.sampleRate`: trace 采样率 `0`–`1`。 +- `otel.flushIntervalMs`: 定期遥测刷新间隔，以毫秒为单位。 +- `otel.captureContent`: 选择加入原始内容捕获，用于 OTEL span 属性。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: 最新实验性 GenAI span 提供商属性的环境开关。默认情况下，为保持兼容性，span 会保留旧版 `gen_ai.system` 属性；GenAI metrics 使用有界语义属性。 +- `OPENCLAW_OTEL_PRELOADED=1`: 用于已注册全局 OpenTelemetry SDK 的主机的环境开关。OpenClaw 随后会跳过插件拥有的 SDK 启动/关闭，同时保持诊断监听器活动。 +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: 在匹配配置键未设置时使用的特定信号端点环境变量。 +- `cacheTrace.enabled`: 为嵌入式运行记录缓存跟踪快照（默认值：`false`）。 +- `cacheTrace.filePath`: 缓存跟踪 JSONL 的输出路径（默认值：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: 控制缓存跟踪输出中包含的内容（全部默认值：`true`）。 --- @@ -970,12 +945,12 @@ openclaw gateway --port 19001 } ``` -- `channel`：npm/git 安装的发布渠道，取值为 `"stable"`、`"beta"` 或 `"dev"`。 -- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。 -- `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 -- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟小时数（默认：`6`；最大值：`168`）。 -- `auto.stableJitterHours`：稳定渠道发布扩散的额外小时窗口（默认：`12`；最大值：`168`）。 -- `auto.betaCheckIntervalHours`：Beta 渠道检查运行的频率，单位为小时（默认：`1`；最大值：`24`）。 +- `channel`: npm/git 安装的发布渠道 — `"stable"`、`"beta"` 或 `"dev"`。 +- `checkOnStart`: Gateway 网关启动时检查 npm 更新（默认值：`true`）。 +- `auto.enabled`: 为包安装启用后台自动更新（默认值：`false`）。 +- `auto.stableDelayHours`: stable 渠道自动应用前的最小延迟小时数（默认值：`6`；最大值：`168`）。 +- `auto.stableJitterHours`: stable 渠道发布扩散窗口的额外小时数（默认值：`12`；最大值：`168`）。 +- `auto.betaCheckIntervalHours`: beta 渠道检查运行频率，以小时为单位（默认值：`1`；最大值：`24`）。 --- @@ -1008,23 +983,23 @@ openclaw gateway --port 19001 } ``` -- `enabled`：全局 ACP 功能门控（默认：`true`；设为 `false` 可隐藏 ACP 分发和生成入口）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 -- `backend`：默认 ACP 运行时后端 id（必须匹配已注册的 ACP 运行时插件）。 - 先安装后端插件；如果设置了 `plugins.allow`，请包含后端插件 id（例如 `acpx`），否则 ACP 后端不会加载。 -- `defaultAgent`：当生成未指定显式目标时使用的后备 ACP 目标智能体 id。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示没有额外限制。 -- `maxConcurrentSessions`：并发活动 ACP 会话的最大数量。 -- `stream.coalesceIdleMs`：流式文本的空闲刷新窗口，单位为 ms。 -- `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 运行时环境时可运行的可选安装命令。 +- `enabled`: 全局 ACP 功能门控（默认值：`true`；设为 `false` 可隐藏 ACP 分发和生成入口）。 +- `dispatch.enabled`: ACP 会话轮次分发的独立门控（默认值：`true`）。设为 `false` 可保留 ACP 命令可用，但阻止执行。 +- `backend`: 默认 ACP 运行时后端 ID（必须匹配已注册的 ACP 运行时插件）。 + 先安装后端插件；如果设置了 `plugins.allow`，请包含后端插件 ID（例如 `acpx`），否则 ACP 后端不会加载。 +- `defaultAgent`: 当生成未指定显式目标时使用的回退 ACP 目标 agent ID。 +- `allowedAgents`: 允许用于 ACP 运行时会话的 agent ID 允许列表；为空表示没有额外限制。 +- `maxConcurrentSessions`: 同时活动的 ACP 会话最大数量。 +- `stream.coalesceIdleMs`: 流式文本的空闲刷新窗口，以毫秒为单位。 +- `stream.maxChunkChars`: 分割流式块投影前的最大块大小。 +- `stream.repeatSuppression`: 抑制每轮中重复的 Status/工具行（默认值：`true`）。 +- `stream.deliveryMode`: `"live"` 增量流式传输；`"final_only"` 缓冲直到轮次终止事件。 +- `stream.hiddenBoundarySeparator`: 隐藏工具事件后可见文本之前的分隔符（默认值：`"paragraph"`）。 +- `stream.maxOutputChars`: 每个 ACP 轮次投影的助手输出字符最大数量。 +- `stream.maxSessionUpdateChars`: 投影的 ACP Status/更新行的最大字符数。 +- `stream.tagVisibility`: 标签名称到布尔可见性覆盖的记录，用于流式事件。 +- `runtime.ttlMinutes`: ACP 会话 worker 在符合清理条件前的空闲 TTL，以分钟为单位。 +- `runtime.installCommand`: 引导 ACP 运行时环境时要运行的可选安装命令。 --- @@ -1041,10 +1016,10 @@ openclaw gateway --port 19001 ``` - `cli.banner.taglineMode` 控制横幅标语样式： - - `"random"`（默认）：轮换的趣味/季节性标语。 - - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：无标语文本（仍显示横幅标题/版本）。 -- 要隐藏整个横幅（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `"random"`（默认）：轮换有趣/季节性标语。 + - `"default"`: 固定中性标语（`All your chats, one OpenClaw.`）。 + - `"off"`: 无标语文本（仍会显示横幅标题/版本）。 +- 若要隐藏整个横幅（不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -1068,13 +1043,13 @@ openclaw gateway --port 19001 ## 身份 -参见 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。 +参见 [Agent defaults](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。 --- ## 桥接（旧版，已移除） -当前构建不再包含 TCP 桥接。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再属于配置 schema（在移除之前验证会失败；`openclaw doctor --fix` 可以清理未知键）。 +当前构建不再包含 TCP 桥接。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再属于配置架构（在移除前验证会失败；`openclaw doctor --fix` 可以剥离未知键）。 @@ -1096,7 +1071,7 @@ openclaw gateway --port 19001 --- -## 定时任务 +## Cron ```json5 { @@ -1114,10 +1089,10 @@ openclaw gateway --port 19001 } ``` -- `sessionRetention`：已完成的隔离定时任务运行会话在从 `sessions.json` 裁剪前保留多久。也控制已归档的已删除定时任务转录文本的清理。默认：`24h`；设为 `false` 可禁用。 -- `runLog.maxBytes`：裁剪前每个运行日志文件（`cron/runs/.jsonl`）的最大大小。默认：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认：`2000`。 -- `webhookToken`：用于定时任务 webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；如果省略，则不会发送认证标头。 +- `sessionRetention`：在从 `sessions.json` 清理前，已完成的隔离 cron 运行会话保留多久。也控制已归档删除 cron 转写记录的清理。默认值：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在清理前的最大大小。默认值：`2_000_000` 字节。 +- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认值：`2000`。 +- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；如果省略，则不发送认证标头。 - `webhook`：已弃用的旧版后备 webhook URL（http/https），仅用于仍带有 `notify: true` 的已存储作业。 ### `cron.retry` @@ -1157,12 +1132,12 @@ openclaw gateway --port 19001 } ``` -- `enabled`：为 cron 作业启用失败警报（默认值：`false`）。 -- `after`：警报触发前的连续失败次数（正整数，最小值：`1`）。 -- `cooldownMs`：同一作业重复警报之间的最小毫秒数（非负整数）。 -- `includeSkipped`：将连续跳过的运行计入警报阈值（默认值：`false`）。跳过的运行会单独跟踪，并且不会影响执行错误退避。 -- `mode`：投递模式 — `"announce"` 通过渠道消息发送；`"webhook"` 发布到配置的 webhook。 -- `accountId`：用于限定警报投递范围的可选账号或渠道 ID。 +- `enabled`：为 cron 作业启用失败提醒（默认值：`false`）。 +- `after`：触发提醒前的连续失败次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复提醒之间的最小毫秒数（非负整数）。 +- `includeSkipped`：将连续跳过的运行计入提醒阈值（默认值：`false`）。跳过的运行会单独跟踪，不影响执行错误退避。 +- `mode`：投递模式 — `"announce"` 通过渠道消息发送；`"webhook"` 发布到已配置的 webhook。 +- `accountId`：可选的账户或渠道 ID，用于限定提醒投递范围。 ### `cron.failureDestination` @@ -1179,16 +1154,16 @@ openclaw gateway --port 19001 } ``` -- 所有作业的 cron 失败通知默认目的地。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认值为 `"announce"`。 -- `channel`：announce 投递的渠道覆盖项。`"last"` 会复用最后已知的投递渠道。 -- `to`：显式 announce 目标或 webhook URL。webhook 模式必填。 -- `accountId`：可选的投递账号覆盖项。 +- 所有作业的 cron 失败通知默认目标位置。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认为 `"announce"`。 +- `channel`：用于 announce 投递的渠道覆盖。`"last"` 会复用最后已知的投递渠道。 +- `to`：显式 announce 目标或 webhook URL。webhook 模式必需。 +- `accountId`：用于投递的可选账户覆盖。 - 每个作业的 `delivery.failureDestination` 会覆盖这个全局默认值。 -- 当既未设置全局失败目的地，也未设置每个作业的失败目的地时，已经通过 `announce` 投递的作业会在失败时回退到该主要 announce 目标。 -- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 作业，除非该作业的主要 `delivery.mode` 是 `"webhook"`。 +- 当既未设置全局失败目标位置，也未设置每个作业的失败目标位置时，已通过 `announce` 投递的作业会在失败时回退到其主要 announce 目标。 +- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 作业，除非该作业的主要 `delivery.mode` 为 `"webhook"`。 -参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 +参见 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离 cron 执行会作为[后台任务](/zh-CN/automation/tasks)跟踪。 --- @@ -1198,32 +1173,32 @@ openclaw gateway --port 19001 | 变量 | 描述 | | ------------------ | ------------------------------------------------- | -| `{{Body}}` | 完整的入站消息正文 | +| `{{Body}}` | 完整的传入消息正文 | | `{{RawBody}}` | 原始正文（无历史记录/发送者包装） | -| `{{BodyStripped}}` | 移除了群组提及的正文 | +| `{{BodyStripped}}` | 去除群组提及后的正文 | | `{{From}}` | 发送者标识符 | -| `{{To}}` | 目的地标识符 | +| `{{To}}` | 目标标识符 | | `{{MessageSid}}` | 渠道消息 ID | | `{{SessionId}}` | 当前会话 UUID | | `{{IsNewSession}}` | 创建新会话时为 `"true"` | -| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaUrl}}` | 传入媒体伪 URL | | `{{MediaPath}}` | 本地媒体路径 | | `{{MediaType}}` | 媒体类型（图像/音频/文档/…） | -| `{{Transcript}}` | 音频转录文本 | +| `{{Transcript}}` | 音频转写 | | `{{Prompt}}` | CLI 条目的已解析媒体提示词 | | `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | | `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力获取） | -| `{{GroupMembers}}` | 群组成员预览（尽力获取） | -| `{{SenderName}}` | 发送者显示名称（尽力获取） | -| `{{SenderE164}}` | 发送者电话号码（尽力获取） | -| `{{Provider}}` | 提供商提示（WhatsApp、Telegram、Discord 等） | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群组成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名称（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- ## 配置包含（`$include`） -将配置拆分为多个文件： +将配置拆分到多个文件： ```json5 // ~/.openclaw/openclaw.json @@ -1239,19 +1214,19 @@ openclaw gateway --port 19001 **合并行为：** - 单个文件：替换包含它的对象。 -- 文件数组：按顺序深度合并（后面的覆盖前面的）。 -- 同级键：在包含之后合并（覆盖已包含的值）。 +- 文件数组：按顺序深度合并（后者覆盖前者）。 +- 同级键：在包含项之后合并（覆盖已包含的值）。 - 嵌套包含：最多 10 层深。 -- 路径：相对于包含它的文件解析，但必须保留在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式仍解析在该边界内时才允许使用。 -- OpenClaw 拥有的写入如果只更改由单文件包含支持的一个顶层部分，会写入该被包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。 -- 根包含、包含数组以及带有同级覆盖项的包含，对于 OpenClaw 拥有的写入是只读的；这些写入会失败关闭，而不是扁平化配置。 +- 路径：相对于包含它的文件解析，但必须留在顶层配置目录（`openclaw.json` 的 `dirname`）内。绝对路径/`../` 形式只有在仍解析到该边界内时才允许。 +- 仅更改由单文件包含支持的一个顶层部分的 OpenClaw 所有写入，会透传写入该包含文件。例如，`plugins install` 会更新 `plugins.json5` 中的 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。 +- 根包含、包含数组以及带有同级覆盖的包含，对 OpenClaw 所有写入是只读的；这些写入会失败关闭，而不是扁平化配置。 - 错误：针对缺失文件、解析错误和循环包含提供清晰消息。 --- -_相关：[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) · [Doctor](/zh-CN/gateway/doctor)_ ## 相关 -- [Configuration](/zh-CN/gateway/configuration) -- [Configuration examples](/zh-CN/gateway/configuration-examples) +- [配置](/zh-CN/gateway/configuration) +- [配置示例](/zh-CN/gateway/configuration-examples) diff --git a/docs/zh-CN/gateway/opentelemetry.md b/docs/zh-CN/gateway/opentelemetry.md index 868a18a64..6f170e09e 100644 --- a/docs/zh-CN/gateway/opentelemetry.md +++ b/docs/zh-CN/gateway/opentelemetry.md @@ -1,27 +1,27 @@ --- read_when: - - 你想将 OpenClaw 模型使用情况、消息流或会话指标发送到 OpenTelemetry 收集器 - - 你正在将追踪、指标或日志接入 Grafana、Datadog、Honeycomb、New Relic、Tempo 或其他 OTLP 后端 - - 你需要精确的指标名称、跨度名称或属性结构来构建控制面板或告警 -summary: 将 OpenClaw 诊断数据通过 diagnostics-otel 插件（OTLP/HTTP）导出到任何 OpenTelemetry 收集器 + - 你想将 OpenClaw 模型使用量、消息流或会话指标发送到 OpenTelemetry 采集器 + - 你正在将跟踪、指标或日志接入 Grafana、Datadog、Honeycomb、New Relic、Tempo 或其他 OTLP 后端 + - 你需要确切的指标名称、跨度名称或属性结构，才能构建仪表板或告警 +summary: 将 OpenClaw 诊断数据通过 diagnostics-otel 插件（OTLP/HTTP）导出到任意 OpenTelemetry 收集器 title: OpenTelemetry 导出 x-i18n: - generated_at: "2026-05-04T02:07:39Z" + generated_at: "2026-05-05T03:06:22Z" model: gpt-5.5 provider: openai - source_hash: d0b5be99b29fe5f13132b03cfeaf3ce978ee16f29e307aa76769bc414b5ca35f + source_hash: b5030b8b16624f114e31838d3a055c24e8a23a6c77d63495a445cb9f2e227b6a source_path: gateway/opentelemetry.md workflow: 16 --- -OpenClaw 通过官方 `diagnostics-otel` 插件使用 **OTLP/HTTP（protobuf）** 导出诊断信息。任何接受 OTLP/HTTP 的收集器或后端都无需修改代码即可工作。关于本地文件日志以及如何读取它们，请参阅 [Logging](/zh-CN/logging)。 +OpenClaw 通过官方 `diagnostics-otel` 插件使用 **OTLP/HTTP (protobuf)** 导出诊断。任何接受 OTLP/HTTP 的收集器或后端都无需代码更改即可工作。有关本地文件日志以及如何读取它们，请参阅[日志](/zh-CN/logging)。 -## 工作方式 +## 它如何协同工作 -- **诊断事件** 是结构化的进程内记录，由 Gateway 网关和内置插件发出，用于模型运行、消息流、会话、队列和 exec。 -- **`diagnostics-otel` 插件** 订阅这些事件，并通过 OTLP/HTTP 将其导出为 OpenTelemetry **指标**、**追踪**和**日志**。 -- 当提供商传输支持自定义 header 时，**提供商调用** 会从 OpenClaw 受信任的模型调用 span 上下文接收 W3C `traceparent` header。插件发出的追踪上下文不会被传播。 -- 只有在诊断表面和插件都启用时，导出器才会附加，因此默认情况下进程内开销接近于零。 +- **诊断事件**是由 Gateway 网关和内置插件在进程内发出的结构化记录，涵盖模型运行、消息流、会话、队列和 exec。 +- **`diagnostics-otel` 插件**订阅这些事件，并通过 OTLP/HTTP 将它们导出为 OpenTelemetry **指标**、**链路追踪**和**日志**。 +- 当提供商传输层接受自定义标头时，**提供商调用**会从 OpenClaw 的可信模型调用 span 上下文接收 W3C `traceparent` 标头。插件发出的 trace 上下文不会被传播。 +- 只有在诊断表面和插件都启用时，导出器才会挂载，因此默认情况下进程内成本接近于零。 ## 快速开始 @@ -56,25 +56,25 @@ openclaw plugins install clawhub:@openclaw/diagnostics-otel } ``` -你也可以通过 CLI 启用插件： +你也可以从 CLI 启用该插件： ```bash openclaw plugins enable diagnostics-otel ``` -`protocol` 目前仅支持 `http/protobuf`。`grpc` 会被忽略。 +`protocol` 当前仅支持 `http/protobuf`。`grpc` 会被忽略。 ## 导出的信号 -| 信号 | 包含内容 | +| 信号 | 内容 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| **指标** | 用于 token 用量、成本、运行耗时、消息流、队列 lane、会话状态、exec 和内存压力的计数器与直方图。 | -| **追踪** | 用于模型使用情况、模型调用、harness 生命周期、工具执行、exec、webhook/消息处理、上下文组装和工具循环的 span。 | -| **日志** | 当 `diagnostics.otel.logs` 启用时，通过 OTLP 导出的结构化 `logging.file` 记录。 | +| **指标** | 用于 token 用量、成本、运行时长、消息流、队列通道、会话状态、exec 和内存压力的计数器与直方图。 | +| **链路追踪** | 用于模型用量、模型调用、harness 生命周期、工具执行、exec、webhook/消息处理、上下文组装和工具循环的 span。 | +| **日志** | 在启用 `diagnostics.otel.logs` 时，通过 OTLP 导出的结构化 `logging.file` 记录。 | -可以分别切换 `traces`、`metrics` 和 `logs`。当 `diagnostics.otel.enabled` 为 true 时，三者默认都开启。 +可以独立切换 `traces`、`metrics` 和 `logs`。当 `diagnostics.otel.enabled` 为 true 时，三者默认都开启。 ## 配置参考 @@ -111,52 +111,52 @@ openclaw plugins enable diagnostics-otel ### 环境变量 -| 变量 | 用途 | +| 变量 | 用途 | | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆盖 `diagnostics.otel.endpoint`。如果值已包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，则会原样使用。 | -| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 当匹配的 `diagnostics.otel.*Endpoint` 配置键未设置时使用的信号专用端点覆盖项。信号专用配置优先于信号专用环境变量，信号专用环境变量优先于共享端点。 | -| `OTEL_SERVICE_NAME` | 覆盖 `diagnostics.otel.serviceName`。 | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆盖线路协议（目前仅采用 `http/protobuf`）。 | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | 设置为 `gen_ai_latest_experimental` 可发出最新的实验性 GenAI span 属性（`gen_ai.provider.name`），而不是旧版 `gen_ai.system`。无论如何，GenAI 指标始终使用有界、低基数语义属性。 | -| `OPENCLAW_OTEL_PRELOADED` | 当另一个 preload 或宿主进程已注册全局 OpenTelemetry SDK 时设置为 `1`。插件随后会跳过自身的 NodeSDK 生命周期，但仍会连接诊断监听器并遵循 `traces`/`metrics`/`logs`。 | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆盖 `diagnostics.otel.endpoint`。如果该值已包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，则会按原样使用。 | +| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 在对应的 `diagnostics.otel.*Endpoint` 配置键未设置时使用的按信号划分的端点覆盖项。按信号划分的配置优先于按信号划分的环境变量，后者又优先于共享端点。 | +| `OTEL_SERVICE_NAME` | 覆盖 `diagnostics.otel.serviceName`。 | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆盖线路协议（目前只认可 `http/protobuf`）。 | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | 设置为 `gen_ai_latest_experimental` 可发出最新的实验性 GenAI span 属性（`gen_ai.provider.name`），而不是旧版 `gen_ai.system`。无论如何，GenAI 指标始终使用有界、低基数的语义属性。 | +| `OPENCLAW_OTEL_PRELOADED` | 当另一个 preload 或宿主进程已经注册了全局 OpenTelemetry SDK 时设置为 `1`。随后该插件会跳过自身的 NodeSDK 生命周期，但仍会连接诊断监听器，并遵循 `traces`/`metrics`/`logs`。 | ## 隐私和内容捕获 -默认情况下不会导出原始模型/工具内容。Span 携带有界标识符（渠道、提供商、模型、错误类别、仅哈希请求 ID），并且永远不包含 prompt 文本、响应文本、工具输入、工具输出或会话键。 +默认情况下不会导出原始模型/工具内容。span 携带有界标识符（渠道、提供商、模型、错误类别、仅哈希请求 ID），绝不包含 prompt 文本、响应文本、工具输入、工具输出或会话键。 -出站模型请求可能包含 W3C `traceparent` header。该 header 仅根据活动模型调用的 OpenClaw 自有诊断追踪上下文生成。现有调用方提供的 `traceparent` header 会被替换，因此插件或自定义提供商选项无法伪造跨服务追踪祖先关系。 +出站模型请求可能包含 W3C `traceparent` 标头。该标头仅根据活动模型调用的 OpenClaw 自有诊断 trace 上下文生成。已有调用方提供的 `traceparent` 标头会被替换，因此插件或自定义提供商选项无法伪造跨服务 trace 祖先关系。 -仅当你的收集器和保留策略已获准处理 prompt、响应、工具或系统 prompt 文本时，才将 `diagnostics.otel.captureContent.*` 设置为 `true`。每个子键都独立选择启用： +仅当你的收集器和保留策略已获准处理 prompt、响应、工具或 system-prompt 文本时，才将 `diagnostics.otel.captureContent.*` 设置为 `true`。每个子键都需要单独选择启用： - `inputMessages` — 用户 prompt 内容。 - `outputMessages` — 模型响应内容。 -- `toolInputs` — 工具参数 payload。 -- `toolOutputs` — 工具结果 payload。 -- `systemPrompt` — 组装后的系统/开发者 prompt。 +- `toolInputs` — 工具参数负载。 +- `toolOutputs` — 工具结果负载。 +- `systemPrompt` — 组装后的 system/developer prompt。 -当启用任一子键时，模型和工具 span 只会为对应类别获得有界、已脱敏的 `openclaw.content.*` 属性。 +启用任何子键时，模型和工具 span 只会为该类别获得有界、已脱敏的 `openclaw.content.*` 属性。 ## 采样和刷新 -- **追踪：** `diagnostics.otel.sampleRate`（仅 root span，`0.0` 丢弃全部，`1.0` 保留全部）。 -- **指标：** `diagnostics.otel.flushIntervalMs`（最小值 `1000`）。 -- **日志：** OTLP 日志遵循 `logging.level`（文件日志级别）。它们使用诊断日志记录脱敏路径，而不是控制台格式化。高流量安装应优先使用 OTLP 收集器采样/过滤，而不是本地采样。 -- **文件日志关联：** 当日志调用携带有效的诊断追踪上下文时，JSONL 文件日志会包含顶层 `traceId`、`spanId`、`parentSpanId` 和 `traceFlags`，这让日志处理器可以将本地日志行与导出的 span 关联起来。 -- **请求关联：** Gateway 网关 HTTP 请求和 WebSocket frame 会创建内部请求追踪作用域。该作用域内的日志和诊断事件默认继承请求追踪，而 agent 运行和模型调用 span 会作为子级创建，因此提供商 `traceparent` header 会保留在同一条追踪上。 +- **链路追踪：**`diagnostics.otel.sampleRate`（仅 root-span，`0.0` 丢弃全部，`1.0` 保留全部）。 +- **指标：**`diagnostics.otel.flushIntervalMs`（最小值 `1000`）。 +- **日志：**OTLP 日志遵循 `logging.level`（文件日志级别）。它们使用诊断日志记录脱敏路径，而不是控制台格式化。高流量安装应优先使用 OTLP 收集器采样/过滤，而不是本地采样。 +- **文件日志关联：**当日志调用携带有效诊断 trace 上下文时，JSONL 文件日志会包含顶层 `traceId`、`spanId`、`parentSpanId` 和 `traceFlags`，从而让日志处理器把本地日志行与导出的 span 关联起来。 +- **请求关联：**Gateway 网关 HTTP 请求和 WebSocket 帧会创建内部请求 trace 作用域。该作用域内的日志和诊断事件默认继承请求 trace，而 agent 运行和模型调用 span 会作为子项创建，因此提供商 `traceparent` 标头会保持在同一个 trace 上。 ## 导出的指标 -### 模型使用情况 +### 模型用量 - `openclaw.tokens`（计数器，属性：`openclaw.token`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`、`openclaw.agent`） - `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`） - `gen_ai.client.token.usage`（直方图，GenAI 语义约定指标，属性：`gen_ai.token.type` = `input`/`output`、`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`） -- `gen_ai.client.operation.duration`（直方图，秒，GenAI 语义约定指标，属性：`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`、可选 `error.type`） +- `gen_ai.client.operation.duration`（直方图，秒，GenAI 语义约定指标，属性：`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`，可选 `error.type`） - `openclaw.model_call.duration_ms`（直方图，属性：`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`，以及分类错误上的 `openclaw.errorCategory` 和 `openclaw.failureKind`） -- `openclaw.model_call.request_bytes`（直方图，最终模型请求 payload 的 UTF-8 字节大小；不包含原始 payload 内容） -- `openclaw.model_call.response_bytes`（直方图，流式模型响应事件的 UTF-8 字节大小；不包含原始响应内容） +- `openclaw.model_call.request_bytes`（直方图，最终模型请求负载的 UTF-8 字节大小；不含原始负载内容） +- `openclaw.model_call.response_bytes`（直方图，流式模型响应事件的 UTF-8 字节大小；不含原始响应内容） - `openclaw.model_call.time_to_first_byte_ms`（直方图，第一个流式响应事件之前经过的时间） ### 消息流 @@ -177,25 +177,29 @@ openclaw plugins enable diagnostics-otel - `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.session.stuck`（计数器，属性：`openclaw.state`；仅针对没有活动工作的陈旧会话簿记发出） +- `openclaw.session.stuck_age_ms`（直方图，属性：`openclaw.state`；仅针对没有活动工作的陈旧会话簿记发出） - `openclaw.run.attempt`（计数器，属性：`openclaw.attempt`） ### 会话活性遥测 -`diagnostics.stuckSessionWarnMs` 是会话活性诊断的无进展时长阈值。当 OpenClaw 观察到回复、工具、Status、block 或 ACP 运行时进展时，`processing` 会话不会朝此阈值累计时长。Typing keepalive 不计为进展，因此静默的模型或 harness 仍可被检测到。 +`diagnostics.stuckSessionWarnMs` 是用于会话活性诊断的无进展时长阈值。当 OpenClaw 观察到回复、工具、Status、block 或 ACP 运行时进展时，`processing` 会话不会朝该阈值老化。输入 keepalive 不会被计为进展，因此静默的模型或 harness 仍可被检测到。 -OpenClaw 会按它仍能观察到的工作对会话进行分类： +OpenClaw 根据仍能观察到的工作对会话进行分类： -- `session.long_running`：活跃的嵌入式工作、模型调用或工具调用仍在取得进展。 -- `session.stalled`：存在活跃工作，但活跃运行最近没有报告进展。停滞的嵌入式运行起初保持仅观察状态；随后在至少 10 分钟且达到 5 倍 `diagnostics.stuckSessionWarnMs` 仍无进展后执行中止清空，以便该队列通道后面的排队轮次可以恢复。 -- `session.stuck`：没有活跃工作的过期会话记账。这会立即释放受影响的会话队列通道。 +- `session.long_running`：活动中的嵌入式工作、模型调用或工具调用仍在取得进展。 +- `session.stalled`：存在活动工作，但活动运行最近没有报告进展。停滞的嵌入式运行起初保持仅观察状态；如果在 `diagnostics.stuckSessionAbortMs` 后仍无进展，则进入 abort-drain，使该通道后方排队的轮次可以恢复。未设置时，中止阈值默认使用更安全的扩展窗口，即至少 10 分钟且为 `diagnostics.stuckSessionWarnMs` 的 5 倍。 +- `session.stuck`：没有活动工作的陈旧会话记账状态。这会立即释放受影响的会话通道。 -只有 `session.stuck` 会发出 `openclaw.session.stuck` 计数器、`openclaw.session.stuck_age_ms` 直方图和 `openclaw.session.stuck` 跨度。当会话保持不变时，重复的 `session.stuck` 诊断会退避，因此仪表盘应针对持续增长告警，而不是对每个 Heartbeat 滴答告警。有关配置开关和默认值，请参见[配置参考](/zh-CN/gateway/configuration-reference#diagnostics)。 +恢复会发出结构化的 `session.recovery.requested` 和 +`session.recovery.completed` 事件。只有在产生变更的恢复结果（`aborted` 或 `released`）之后，并且只有当同一处理代仍然是当前代时，诊断会话状态才会标记为空闲。 + +只有 `session.stuck` 会发出 `openclaw.session.stuck` 计数器、`openclaw.session.stuck_age_ms` 直方图和 `openclaw.session.stuck` span。重复的 `session.stuck` 诊断会在会话保持不变时退避，因此仪表板应针对持续增长发出警报，而不是针对每次 Heartbeat 跳动。有关配置旋钮和默认值，请参阅 +[配置参考](/zh-CN/gateway/configuration-reference#diagnostics)。 ### 运行框架生命周期 -- `openclaw.harness.duration_ms`（直方图，属性：`openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`，错误时还有 `openclaw.harness.phase`） +- `openclaw.harness.duration_ms`（直方图，属性：`openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`，错误时包含 `openclaw.harness.phase`） ### 执行 @@ -209,11 +213,11 @@ OpenClaw 会按它仍能观察到的工作对会话进行分类： - `openclaw.tool.loop.iterations`（计数器，属性：`openclaw.toolName`、`openclaw.outcome`） - `openclaw.tool.loop.duration_ms`（直方图，属性：`openclaw.toolName`、`openclaw.outcome`） -## 导出的跨度 +## 导出的 span - `openclaw.model.usage` - `openclaw.channel`、`openclaw.provider`、`openclaw.model` - - `openclaw.tokens.*`（输入/输出/缓存读取/缓存写入/总计） + - `openclaw.tokens.*`（input/output/cache_read/cache_write/total） - 默认使用 `gen_ai.system`，或在选择启用最新 GenAI 语义约定时使用 `gen_ai.provider.name` - `gen_ai.request.model`、`gen_ai.operation.name`、`gen_ai.usage.*` - `openclaw.run` @@ -223,11 +227,11 @@ OpenClaw 会按它仍能观察到的工作对会话进行分类： - `gen_ai.request.model`、`gen_ai.operation.name`、`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport` - 错误时包含 `openclaw.errorCategory` 和可选的 `openclaw.failureKind` - `openclaw.model_call.request_bytes`、`openclaw.model_call.response_bytes`、`openclaw.model_call.time_to_first_byte_ms` - - `openclaw.provider.request_id_hash`（上游提供商请求 ID 的有界 SHA 哈希；不会导出原始 ID） + - `openclaw.provider.request_id_hash`（上游提供商请求 id 的有界 SHA 哈希；不会导出原始 id） - `openclaw.harness.run` - `openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`、`openclaw.provider`、`openclaw.model`、`openclaw.channel` - 完成时：`openclaw.harness.result_classification`、`openclaw.harness.yield_detected`、`openclaw.harness.items.started`、`openclaw.harness.items.completed`、`openclaw.harness.items.active` - - 错误时：`openclaw.harness.phase`、`openclaw.errorCategory`、可选的 `openclaw.harness.cleanup_failed` + - 出错时：`openclaw.harness.phase`、`openclaw.errorCategory`、可选的 `openclaw.harness.cleanup_failed` - `openclaw.tool.execution` - `gen_ai.tool.name`、`openclaw.toolName`、`openclaw.errorCategory`、`openclaw.tool.params.*` - `openclaw.exec` @@ -243,21 +247,21 @@ OpenClaw 会按它仍能观察到的工作对会话进行分类： - `openclaw.session.stuck` - `openclaw.state`、`openclaw.ageMs`、`openclaw.queueDepth` - `openclaw.context.assembled` - - `openclaw.prompt.size`、`openclaw.history.size`、`openclaw.context.tokens`、`openclaw.errorCategory`（不包含提示词、历史、响应或会话键内容） + - `openclaw.prompt.size`、`openclaw.history.size`、`openclaw.context.tokens`、`openclaw.errorCategory`（不包含提示词、历史记录、响应或会话键内容） - `openclaw.tool.loop` - `openclaw.toolName`、`openclaw.outcome`、`openclaw.iterations`、`openclaw.errorCategory`（不包含循环消息、参数或工具输出） - `openclaw.memory.pressure` - `openclaw.memory.level`、`openclaw.memory.heap_used_bytes`、`openclaw.memory.rss_bytes` -当明确启用内容捕获时，模型和工具跨度还可以为你选择启用的特定内容类别包含有界且已脱敏的 `openclaw.content.*` 属性。 +显式启用内容捕获时，模型和工具 span 还可以为你选择启用的特定内容类别包含有界且已脱敏的 `openclaw.content.*` 属性。 ## 诊断事件目录 -以下事件支撑上面的指标和跨度。插件也可以在不通过 OTLP 导出的情况下直接订阅它们。 +下面的事件支撑上述指标和 span。插件也可以直接订阅这些事件，无需 OTLP 导出。 **模型用量** -- `model.usage` — 令牌、成本、时长、上下文、提供商/模型/渠道、会话 ID。`usage` 是用于成本和遥测的提供商/轮次记账；`context.used` 是当前提示词/上下文快照，当涉及缓存输入或工具循环调用时，它可能低于提供商 `usage.total`。 +- `model.usage` — token、成本、持续时间、上下文、提供商/模型/渠道、会话 id。`usage` 是用于成本和遥测的提供商/轮次记账；`context.used` 是当前提示词/上下文快照，在涉及缓存输入或工具循环调用时，可能低于提供商的 `usage.total`。 **消息流** @@ -274,15 +278,15 @@ OpenClaw 会按它仍能观察到的工作对会话进行分类： **运行框架生命周期** -- `harness.run.started` / `harness.run.completed` / `harness.run.error` — 智能体运行框架的每次运行生命周期。包括 `harnessId`、可选的 `pluginId`、提供商/模型/渠道以及运行 ID。完成时会添加 `durationMs`、`outcome`、可选的 `resultClassification`、`yieldDetected` 和 `itemLifecycle` 计数。错误会添加 `phase`（`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory` 和可选的 `cleanupFailed`。 +- `harness.run.started` / `harness.run.completed` / `harness.run.error` — 智能体运行框架的逐运行生命周期。包含 `harnessId`、可选 `pluginId`、提供商/模型/渠道以及运行 id。完成时会添加 `durationMs`、`outcome`、可选的 `resultClassification`、`yieldDetected` 和 `itemLifecycle` 计数。错误会添加 `phase`（`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory` 和可选的 `cleanupFailed`。 **执行** -- `exec.process.completed` — 终端结果、时长、目标、模式、退出代码和失败类型。不包含命令文本和工作目录。 +- `exec.process.completed` — 终端结果、持续时间、目标、模式、退出码和失败类型。不包含命令文本和工作目录。 ## 没有导出器时 -你可以在不运行 `diagnostics-otel` 的情况下，让诊断事件可供插件或自定义接收端使用： +你可以在不运行 `diagnostics-otel` 的情况下，让插件或自定义接收端仍可使用诊断事件： ```json5 { @@ -290,7 +294,7 @@ OpenClaw 会按它仍能观察到的工作对会话进行分类： } ``` -如需在不提高 `logging.level` 的情况下输出定向调试内容，请使用诊断标志。标志不区分大小写并支持通配符（例如 `telegram.*` 或 `*`）： +如需定向调试输出而不提高 `logging.level`，请使用诊断标志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）： ```json5 { @@ -298,13 +302,14 @@ OpenClaw 会按它仍能观察到的工作对会话进行分类： } ``` -或作为一次性环境覆盖： +或作为一次性环境变量覆盖： ```bash OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ``` -标志输出会写入标准日志文件（`logging.file`），并且仍会由 `logging.redactSensitive` 脱敏。完整指南：[诊断标志](/zh-CN/diagnostics/flags)。 +标志输出会写入标准日志文件（`logging.file`），并且仍会被 `logging.redactSensitive` 脱敏。完整指南： +[诊断标志](/zh-CN/diagnostics/flags)。 ## 禁用 @@ -314,12 +319,12 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway } ``` -你也可以将 `diagnostics-otel` 排除在 `plugins.allow` 之外，或运行 `openclaw plugins disable diagnostics-otel`。 +你也可以不将 `diagnostics-otel` 放入 `plugins.allow`，或运行 `openclaw plugins disable diagnostics-otel`。 ## 相关 -- [日志记录](/zh-CN/logging) — 文件日志、控制台输出、CLI 跟踪以及 Control UI Logs 标签页 +- [日志](/zh-CN/logging) — 文件日志、控制台输出、CLI 尾随查看以及 Control UI 日志标签页 - [Gateway 网关日志内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获 - [诊断标志](/zh-CN/diagnostics/flags) — 定向调试日志标志 -- [诊断导出](/zh-CN/gateway/diagnostics) — 操作者支持包工具（独立于 OTEL 导出） +- [诊断导出](/zh-CN/gateway/diagnostics) — 操作员支持包工具（与 OTEL 导出分开） - [配置参考](/zh-CN/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 字段参考