From ac2ed368cbfcdbd045dc915fafb31a56841b2033 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 1 May 2026 23:20:55 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/agent-loop.md | 135 +++-- docs/zh-CN/concepts/queue.md | 87 ++- docs/zh-CN/gateway/configuration-reference.md | 538 +++++++++--------- docs/zh-CN/gateway/opentelemetry.md | 141 +++-- 4 files changed, 452 insertions(+), 449 deletions(-) diff --git a/docs/zh-CN/concepts/agent-loop.md b/docs/zh-CN/concepts/agent-loop.md index 5f4c38dc7..d5589a372 100644 --- a/docs/zh-CN/concepts/agent-loop.md +++ b/docs/zh-CN/concepts/agent-loop.md @@ -1,84 +1,91 @@ --- read_when: - - 你需要一份关于智能体循环或生命周期事件的精确逐步说明 - - 你正在更改会话排队、对话记录写入或会话写入锁行为 + - 你需要 Agent loop 或生命周期事件的精确演练 + - 你正在更改会话队列处理、记录写入或会话写锁行为 summary: Agent loop 生命周期、流和等待语义 title: Agent loop x-i18n: - generated_at: "2026-04-30T18:26:40Z" + generated_at: "2026-05-01T23:18:15Z" model: gpt-5.5 provider: openai - source_hash: 5466893253e1f82482284ff82db56f4c3fca018bf12e4114fad76d37cad954df + source_hash: dbb0bd7989c9ab5606cabeb632c1d0542b31cb60283c50ae945836f55024bbc1 source_path: concepts/agent-loop.md workflow: 16 --- -智能体循环是智能体完整的“真实”运行：接收 → 上下文组装 → 模型推理 → -工具执行 → 流式回复 → 持久化。它是将消息转化为操作和最终回复的权威路径，同时保持会话状态一致。 +智能体循环是智能体一次完整的“真实”运行：接收输入 → 上下文组装 → 模型推理 → +工具执行 → 流式回复 → 持久化。它是将一条消息 +转换为动作和最终回复的权威路径，同时保持会话状态一致。 -在 OpenClaw 中，一个循环是每个会话的一次串行运行，会在模型思考、调用工具和流式输出时发出生命周期和流事件。本文档说明这个真实循环如何端到端接线。 +在 OpenClaw 中，循环是每个会话一次单一、串行化的运行；随着模型思考、调用工具并流式输出，它会发出生命周期和流事件。本文档说明这个真实循环如何端到端串联起来。 ## 入口点 - Gateway 网关 RPC：`agent` 和 `agent.wait`。 - CLI：`agent` 命令。 -## 工作原理（高层） +## 工作方式（高层） 1. `agent` RPC 校验参数，解析会话（sessionKey/sessionId），持久化会话元数据，并立即返回 `{ runId, acceptedAt }`。 2. `agentCommand` 运行智能体： - 解析模型 + thinking/verbose/trace 默认值 - 加载 Skills 快照 - 调用 `runEmbeddedPiAgent`（pi-agent-core 运行时） - - 如果嵌入式循环未发出生命周期 end/error，则发出 **lifecycle end/error** + - 如果嵌入式循环没有发出生命周期结束/错误，则发出 **lifecycle end/error** 3. `runEmbeddedPiAgent`： - 通过每会话 + 全局队列串行化运行 - 解析模型 + 凭证配置，并构建 Pi 会话 - - 订阅 Pi 事件并流式传输助手/工具增量 - - 强制超时 -> 超过时中止运行 - - 对于 Codex app-server 轮次，在终端事件之前，如果已接受的轮次停止产生 app-server 进度，则中止该轮次 + - 订阅 Pi 事件并流式传输 assistant/tool 增量 + - 强制超时 -> 如果超出则中止运行 + - 对于 Codex app-server 回合，如果已接受的回合在终止事件前停止产生 app-server 进度，则中止该回合 - 返回 payload + usage 元数据 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** - 返回 `{ status: ok|error|timeout, startedAt, endedAt, error? }` -## 队列 + 并发 +## 排队 + 并发 -- 运行按会话键（会话通道）串行化，并可选通过全局通道。 -- 这会防止工具/会话竞争，并保持会话历史一致。 -- 消息渠道可以选择队列模式（collect/steer/followup），这些模式会馈入此通道系统。 +- 运行按会话键（会话 lane）串行化，并可选地经过全局 lane。 +- 这可以防止工具/会话竞态，并保持会话历史一致。 +- 消息渠道可以选择队列模式（collect/steer/followup），并将其送入这个 lane 系统。 参见 [命令队列](/zh-CN/concepts/queue)。 -- 转录写入也受会话文件上的会话写锁保护。该锁感知进程并基于文件，因此可以捕获绕过进程内队列或来自其他进程的写入者。 -- 会话写锁默认不可重入。如果某个 helper 有意在保持一个逻辑写入者的同时嵌套获取同一把锁，它必须用 `allowReentrant: true` 显式选择加入。 +- Transcript 写入也受会话文件上的会话写锁保护。该锁 + 感知进程并基于文件，因此能捕获绕过进程内队列或来自 + 另一个进程的写入者。 +- 会话写锁默认不可重入。如果某个辅助函数有意在保留同一个逻辑写入者的同时嵌套获取 + 同一把锁，它必须使用 + `allowReentrant: true` 显式选择加入。 ## 会话 + 工作区准备 - 解析并创建工作区；沙箱隔离运行可能会重定向到沙箱工作区根目录。 -- 加载 Skills（或从快照复用），并注入到 env 和提示词中。 +- 加载 Skills（或复用快照中的 Skills）并注入到环境变量和提示词中。 - 解析 bootstrap/context 文件，并注入到系统提示词报告中。 -- 获取会话写锁；在流式传输前打开并准备 `SessionManager`。任何后续转录重写、压缩或截断路径，在打开或修改转录文件前都必须获取同一把锁。 +- 获取会话写锁；`SessionManager` 会在流式传输前打开并完成准备。任何 + 后续 transcript 重写、压缩或截断路径都必须在打开或 + 修改 transcript 文件前获取同一把锁。 ## 提示词组装 + 系统提示词 -- 系统提示词由 OpenClaw 的基础提示词、Skills 提示词、bootstrap 上下文和每次运行的覆盖项构建。 +- 系统提示词由 OpenClaw 的基础提示词、Skills 提示词、bootstrap 上下文和每次运行覆盖项构建而成。 - 会强制执行模型特定限制和压缩预留 token。 -- 参见 [系统提示词](/zh-CN/concepts/system-prompt) 了解模型看到的内容。 +- 参见 [系统提示词](/zh-CN/concepts/system-prompt)，了解模型会看到什么。 ## 钩子点（你可以拦截的位置） OpenClaw 有两套钩子系统： -- **内部钩子**（Gateway 网关钩子）：用于命令和生命周期事件的事件驱动脚本。 -- **插件钩子**：智能体/工具生命周期和 Gateway 网关流水线中的扩展点。 +- **内部钩子**（Gateway 网关钩子）：面向命令和生命周期事件的事件驱动脚本。 +- **插件钩子**：智能体/工具生命周期和 Gateway 网关流水线内部的扩展点。 ### 内部钩子（Gateway 网关钩子） -- **`agent:bootstrap`**：在系统提示词最终确定前构建 bootstrap 文件时运行。 - 用它来添加/移除 bootstrap 上下文文件。 +- **`agent:bootstrap`**：在构建 bootstrap 文件、系统提示词最终确定之前运行。 + 用它添加/移除 bootstrap 上下文文件。 - **命令钩子**：`/new`、`/reset`、`/stop` 和其他命令事件（参见 Hooks 文档）。 参见 [Hooks](/zh-CN/automation/hooks) 获取设置和示例。 @@ -88,58 +95,62 @@ OpenClaw 有两套钩子系统： 这些钩子在智能体循环或 Gateway 网关流水线内运行： - **`before_model_resolve`**：在会话前运行（没有 `messages`），用于在模型解析前确定性地覆盖提供商/模型。 -- **`before_prompt_build`**：在会话加载后运行（带 `messages`），用于在提交提示词前注入 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。将 `prependContext` 用于每轮动态文本，将系统上下文字段用于应放在系统提示词空间中的稳定指导。 +- **`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`**：检查内置扫描发现，并可选阻止 skill 或插件安装。 -- **`tool_result_persist`**：在工具结果写入 OpenClaw 拥有的会话转录之前，同步转换工具结果。 +- **`before_install`**：检查内置扫描发现，并可选择阻止 Skill 或插件安装。 +- **`tool_result_persist`**：在工具结果写入 OpenClaw 拥有的会话 transcript 前，同步转换工具结果。 - **`message_received` / `message_sending` / `message_sent`**：入站 + 出站消息钩子。 - **`session_start` / `session_end`**：会话生命周期边界。 - **`gateway_start` / `gateway_stop`**：Gateway 网关生命周期事件。 出站/工具防护的钩子决策规则： -- `before_tool_call`：`{ block: true }` 是终止性的，并会停止较低优先级 handler。 -- `before_tool_call`：`{ block: false }` 是无操作，不会清除先前的阻止。 -- `before_install`：`{ block: true }` 是终止性的，并会停止较低优先级 handler。 -- `before_install`：`{ block: false }` 是无操作，不会清除先前的阻止。 -- `message_sending`：`{ cancel: true }` 是终止性的，并会停止较低优先级 handler。 -- `message_sending`：`{ cancel: false }` 是无操作，不会清除先前的取消。 +- `before_tool_call`：`{ block: true }` 是终止性的，会停止较低优先级处理器。 +- `before_tool_call`：`{ block: false }` 是无操作，不会清除先前的 block。 +- `before_install`：`{ block: true }` 是终止性的，会停止较低优先级处理器。 +- `before_install`：`{ block: false }` 是无操作，不会清除先前的 block。 +- `message_sending`：`{ cancel: true }` 是终止性的，会停止较低优先级处理器。 +- `message_sending`：`{ cancel: false }` 是无操作，不会清除先前的 cancel。 -参见 [插件钩子](/zh-CN/plugins/hooks) 获取钩子 API 和注册细节。 +参见 [插件钩子](/zh-CN/plugins/hooks) 获取钩子 API 和注册详情。 -Harness 可能会以不同方式适配这些钩子。Codex app-server harness 将 OpenClaw 插件钩子保留为已记录镜像表面的兼容性契约，而 Codex 原生钩子仍然是单独的较低层 Codex 机制。 +Harness 可能会以不同方式适配这些钩子。Codex app-server harness 将 +OpenClaw 插件钩子保留为已记录镜像 +表面的兼容性契约，而 Codex 原生钩子仍是单独的较低层 Codex 机制。 ## 流式传输 + 部分回复 -- 助手增量从 pi-agent-core 流式传输，并作为 `assistant` 事件发出。 +- Assistant 增量从 pi-agent-core 流式传输，并作为 `assistant` 事件发出。 - 分块流式传输可以在 `text_end` 或 `message_end` 上发出部分回复。 -- 推理流可以作为单独流发出，也可以作为块回复发出。 -- 参见 [流式传输](/zh-CN/concepts/streaming) 了解分块和块回复行为。 +- 推理流可以作为单独的流发出，也可以作为块回复发出。 +- 参见 [流式传输](/zh-CN/concepts/streaming)，了解分块和块回复行为。 ## 工具执行 + 消息工具 - 工具 start/update/end 事件会在 `tool` 流上发出。 -- 工具结果在记录/发出前会针对大小和图片 payload 进行净化。 -- 会跟踪消息工具发送，以抑制重复的助手确认。 +- 工具结果在记录/发出前会针对大小和图像 payload 进行清理。 +- 会跟踪消息工具发送，以抑制重复的 assistant 确认。 -## 回复塑形 + 抑制 +## 回复整形 + 抑制 - 最终 payload 由以下内容组装： - - 助手文本（以及可选推理） + - assistant 文本（以及可选推理） - 内联工具摘要（当 verbose + 允许时） - - 模型出错时的助手错误文本 -- 精确静默 token `NO_REPLY` / `no_reply` 会从出站 payload 中过滤。 + - 模型出错时的 assistant 错误文本 +- 精确的静默 token `NO_REPLY` / `no_reply` 会从出站 + payload 中过滤掉。 - 消息工具重复项会从最终 payload 列表中移除。 -- 如果没有剩余可渲染 payload 且某个工具出错，则会发出后备工具错误回复（除非消息工具已经发送了用户可见回复）。 +- 如果没有剩余可渲染 payload 且工具出错，则发出后备工具错误回复 + （除非消息工具已经发送了用户可见回复）。 ## 压缩 + 重试 - 自动压缩会发出 `compaction` 流事件，并可能触发重试。 -- 重试时，内存缓冲区和工具摘要会被重置，以避免重复输出。 +- 重试时，会重置内存缓冲区和工具摘要，以避免重复输出。 - 参见 [压缩](/zh-CN/concepts/compaction) 了解压缩流水线。 ## 事件流（当前） @@ -150,17 +161,17 @@ Harness 可能会以不同方式适配这些钩子。Codex app-server harness ## 聊天渠道处理 -- 助手增量会缓冲为聊天 `delta` 消息。 -- 聊天 `final` 会在 **lifecycle end/error** 时发出。 +- Assistant 增量会缓冲为聊天 `delta` 消息。 +- 在 **lifecycle end/error** 时发出聊天 `final`。 ## 超时 -- `agent.wait` 默认值：30 秒（仅等待）。`timeoutMs` 参数会覆盖。 -- 智能体运行时：`agents.defaults.timeoutSeconds` 默认值为 172800 秒（48 小时）；在 `runEmbeddedPiAgent` 中由中止计时器强制执行。 -- Cron 运行时：隔离智能体轮次的 `timeoutSeconds` 由 cron 拥有。调度器在执行开始时启动该计时器，在配置的截止时间中止底层运行，然后在记录超时前运行有界清理，确保陈旧子会话不会让通道卡住。 -- 卡住会话恢复：启用诊断后，`diagnostics.stuckSessionWarnMs` 会检测长时间处于 `processing` 的会话。默认情况下，活跃嵌入式运行、活跃回复操作和活跃会话通道任务仅发出警告；如果诊断显示该会话没有活跃工作，watchdog 会释放受影响的会话通道，使排队的启动工作可以排空。 -- 模型空闲超时：当空闲窗口到期前未收到响应块时，OpenClaw 会中止模型请求。`models.providers..timeoutSeconds` 会为缓慢的本地/自托管提供商扩展此空闲 watchdog；否则，OpenClaw 会在已配置时使用 `agents.defaults.timeoutSeconds`，默认上限为 120 秒。没有显式模型或智能体超时的 cron 触发运行会禁用空闲 watchdog，并依赖 cron 外层超时。 -- 提供商 HTTP 请求超时：`models.providers..timeoutSeconds` 适用于该提供商的模型 HTTP fetch，包括连接、headers、body、SDK 请求超时、总 guarded-fetch 中止处理，以及模型流空闲 watchdog。对于 Ollama 等缓慢的本地/自托管提供商，应先使用此项，再提高整个智能体运行时超时。 +- `agent.wait` 默认值：30s（仅等待）。`timeoutMs` 参数会覆盖。 +- 智能体运行时：`agents.defaults.timeoutSeconds` 默认值为 172800s（48 小时）；在 `runEmbeddedPiAgent` 中由中止计时器强制执行。 +- Cron 运行时：隔离的智能体回合 `timeoutSeconds` 由 cron 拥有。调度器会在执行开始时启动该计时器，在配置的截止时间中止底层运行，然后在记录超时前运行有界清理，防止陈旧子会话让 lane 卡住。 +- 会话活性诊断：启用诊断后，`diagnostics.stuckSessionWarnMs` 会分类长时间 `processing` 的会话。活跃的嵌入式运行、模型调用和工具调用会报告为 `session.long_running`；存在活跃工作但近期没有进度时报告为 `session.stalled`；`session.stuck` 仅保留给没有活跃工作的陈旧会话记账，并且只有该路径会释放受影响的会话 lane，以便排队的启动工作可以排空。 +- 模型空闲超时：当响应块在空闲窗口前没有到达时，OpenClaw 会中止模型请求。`models.providers..timeoutSeconds` 会为较慢的本地/自托管提供商扩展此空闲看门狗；否则，OpenClaw 会在配置时使用 `agents.defaults.timeoutSeconds`，默认上限为 120s。没有显式模型或智能体超时的 cron 触发运行会禁用空闲看门狗，并依赖 cron 外层超时。 +- 提供商 HTTP 请求超时：`models.providers..timeoutSeconds` 适用于该提供商的模型 HTTP fetch，包括连接、headers、body、SDK 请求超时、总 guarded-fetch 中止处理，以及模型流空闲看门狗。对于 Ollama 等较慢的本地/自托管提供商，请先使用它，再提高整个智能体运行时超时。 ## 可能提前结束的位置 @@ -173,6 +184,6 @@ Harness 可能会以不同方式适配这些钩子。Codex app-server harness - [工具](/zh-CN/tools) — 可用的智能体工具 - [Hooks](/zh-CN/automation/hooks) — 由智能体生命周期事件触发的事件驱动脚本 -- [压缩](/zh-CN/concepts/compaction) — 长对话如何摘要 +- [压缩](/zh-CN/concepts/compaction) — 长对话如何被摘要 - [Exec Approvals](/zh-CN/tools/exec-approvals) — shell 命令的批准门禁 -- [思考](/zh-CN/tools/thinking) — 思考/推理级别配置 +- [Thinking](/zh-CN/tools/thinking) — thinking/reasoning 级别配置 diff --git a/docs/zh-CN/concepts/queue.md b/docs/zh-CN/concepts/queue.md index 6484b21d5..804ca5aac 100644 --- a/docs/zh-CN/concepts/queue.md +++ b/docs/zh-CN/concepts/queue.md @@ -1,65 +1,61 @@ --- read_when: - - 更改自动回复执行或并发 - - 解释 /queue 模式或消息引导行为 + - 更改自动回复执行或并发设置 + - 说明 /queue 模式或消息导向行为 summary: 自动回复队列模式、默认值和按会话覆盖设置 title: 命令队列 x-i18n: - generated_at: "2026-04-30T18:26:37Z" + generated_at: "2026-05-01T23:18:11Z" model: gpt-5.5 provider: openai - source_hash: fbf1bb1ffd4ce06fa138f63e31651b8821226d9c95dd6b93d68326a5fb91fdd0 + source_hash: b3b24643eea9c8f374b041b251675a1a3c6567306dca07001b4ba82d20391eb1 source_path: concepts/queue.md workflow: 16 --- -我们通过一个极小的进程内队列串行化入站自动回复运行（所有渠道），以防止多个智能体运行相互冲突，同时仍允许跨会话安全并行。 +我们通过一个极小的进程内队列，序列化入站自动回复运行（所有渠道），防止多个智能体运行相互冲突，同时仍允许跨会话的安全并行。 ## 原因 -- 自动回复运行可能开销较高（LLM 调用），并且当多条入站消息接近同时到达时可能发生冲突。 -- 串行化可避免争用共享资源（会话文件、日志、CLI stdin），并降低触发上游速率限制的概率。 +- 自动回复运行可能很昂贵（LLM 调用），并且当多条入站消息接近同时到达时可能发生冲突。 +- 序列化可避免争抢共享资源（会话文件、日志、CLI stdin），并降低触发上游速率限制的概率。 -## 工作方式 +## 工作原理 -- 一个感知 lane 的 FIFO 队列会按可配置的并发上限排空每个 lane（未配置的 lane 默认值为 1；main 默认值为 4，subagent 默认值为 8）。 -- `runEmbeddedPiAgent` 按 **会话键**（lane `session:`）入队，以保证每个会话同一时间只有一个活动运行。 -- 然后，每个会话运行都会被排入一个 **全局 lane**（默认 `main`），使整体并行度受 `agents.defaults.maxConcurrent` 限制。 -- 启用详细日志时，如果排队的运行在开始前等待超过约 2 秒，会发出一条简短通知。 -- 输入指示器仍会在入队时立即触发（如果渠道支持），因此用户体验在等待轮到我们时保持不变。 +- 感知 lane 的 FIFO 队列会按可配置的并发上限排空每个 lane（未配置的 lane 默认值为 1；main 默认值为 4，subagent 为 8）。 +- `runEmbeddedPiAgent` 按**会话键**（lane `session:`）入队，以保证每个会话同一时间只有一个活跃运行。 +- 随后，每个会话运行会被排入**全局 lane**（默认是 `main`），因此总体并行度受 `agents.defaults.maxConcurrent` 限制。 +- 启用详细日志时，如果排队运行在开始前等待超过约 2 秒，会发出一条简短通知。 +- 输入指示器仍会在入队时立即触发（如果渠道支持），因此在等待轮到自己时，用户体验保持不变。 ## 默认值 -未设置时，所有入站渠道界面使用： +未设置时，所有入站渠道表面使用： - `mode: "steer"` - `debounceMs: 500` - `cap: 20` - `drop: "summarize"` -`steer` 是默认值，因为它能保持活动模型轮次响应迅速，而无需 -启动第二个会话运行。它会排空在下一个模型边界之前到达的所有 Steering 消息。如果当前运行无法接受 steering， -OpenClaw 会回退到一个 followup 队列条目。 +`steer` 是默认值，因为它能让活跃模型回合保持响应，而无需启动第二个会话运行。它会排空下一次模型边界之前到达的所有 steering 消息。如果当前运行无法接受 steering，OpenClaw 会回退到后续队列条目。 ## 队列模式 -入站消息可以 steer 当前运行、等待 followup 轮次，或两者都做： +入站消息可以 steer 当前运行、等待后续回合，或两者兼有： -- `steer`：将 Steering 消息排入活动运行时。Pi 会在 **当前 assistant 轮次执行完其工具调用之后**、下一次 LLM 调用之前，交付所有待处理的 Steering 消息；Codex app-server 会接收一个批量的 `turn/steer`。如果该运行未处于活动流式传输状态，或 steering 不可用，OpenClaw 会回退到一个 followup 队列条目。 -- `queue`（旧版）：旧的一次一条 steering。Pi 会在每个模型边界交付一条排队的 Steering 消息；Codex app-server 会接收单独的 `turn/steer` 请求。除非你需要以前的串行化行为，否则优先使用 `steer`。 -- `followup`：在当前运行结束后，将每条消息入队，供后续智能体轮次处理。 -- `collect`：在静默窗口之后，将排队的消息合并为 **单个** followup 轮次。如果消息面向不同渠道/线程，它们会单独排空以保留路由。 -- `steer-backlog`（也称为 `steer+backlog`）：立即 steer，**并且** 保留同一条消息用于 followup 轮次。 -- `interrupt`（旧版）：中止该会话的活动运行，然后运行最新消息。 +- `steer`：将 steering 消息排入活跃运行时。Pi 会在**当前 assistant 回合执行完其工具调用之后**、下一次 LLM 调用之前交付所有待处理的 steering 消息；Codex app-server 会收到一个批处理的 `turn/steer`。如果该运行未处于活跃流式传输状态，或 steering 不可用，OpenClaw 会回退到后续队列条目。 +- `queue`（旧版）：旧的一次一条 steering。Pi 会在每个模型边界交付一条排队的 steering 消息；Codex app-server 会收到单独的 `turn/steer` 请求。除非你需要之前的序列化行为，否则优先使用 `steer`。 +- `followup`：将每条消息入队，在当前运行结束后交给稍后的智能体回合。 +- `collect`：在静默窗口之后，将排队消息合并成**单个**后续回合。如果消息目标是不同渠道/线程，它们会单独排空以保留路由。 +- `steer-backlog`（又称 `steer+backlog`）：现在 steer，**并且**为后续回合保留同一条消息。 +- `interrupt`（旧版）：中止该会话的活跃运行，然后运行最新消息。 -Steer-backlog 表示你可能会在被 steered 的运行之后得到一个 followup 响应，因此 -流式传输界面可能看起来像重复响应。如果你希望每条入站消息只有 -一个响应，请优先使用 `collect`/`steer`。 +Steer-backlog 意味着你可能会在 steered 运行之后收到后续响应，因此流式传输表面可能看起来像重复响应。如果你希望每条入站消息只有一个响应，请优先使用 `collect`/`steer`。 -有关特定运行时的时序和依赖行为，请参阅 +有关运行时特定的时序和依赖行为，请参阅 [Steering queue](/zh-CN/concepts/queue-steering)。 -通过 `messages.queue` 进行全局配置或按渠道配置： +通过 `messages.queue` 进行全局或按渠道配置： ```json5 { @@ -80,47 +76,44 @@ Steer-backlog 表示你可能会在被 steered 的运行之后得到一个 follo 选项适用于 `followup`、`collect` 和 `steer-backlog`（也适用于 steering 回退到 followup 时的 `steer` 或旧版 `queue`）： - `debounceMs`：排空排队 followup 之前的静默窗口。裸数字表示毫秒；`/queue` 选项接受单位 `ms`、`s`、`m`、`h` 和 `d`。 -- `cap`：每个会话最多排队的消息数。低于 `1` 的值会被忽略。 -- `drop: "summarize"`：默认值。按需丢弃最旧的排队条目，保留紧凑摘要，并将其作为合成 followup prompt 注入。 -- `drop: "old"`：按需丢弃最旧的排队条目，不保留摘要。 +- `cap`：每个会话的最大排队消息数。低于 `1` 的值会被忽略。 +- `drop: "summarize"`：默认值。按需丢弃最旧的队列条目，保留紧凑摘要，并将它们作为合成 followup 提示注入。 +- `drop: "old"`：按需丢弃最旧的队列条目，不保留摘要。 - `drop: "new"`：当队列已满时拒绝最新消息。 默认值：`debounceMs: 500`、`cap: 20`、`drop: summarize`。 ## 优先级 -对于模式选择，OpenClaw 的解析顺序为： +对于模式选择，OpenClaw 按以下顺序解析： 1. 内联或已存储的按会话 `/queue` 覆盖。 2. `messages.queue.byChannel.`。 3. `messages.queue.mode`。 4. 默认 `steer`。 -对于选项，内联或已存储的 `/queue` 选项优先于配置。然后依次应用 -渠道特定 debounce（`messages.queue.debounceMsByChannel`）、插件 -debounce 默认值、全局 `messages.queue` 选项以及内置默认值。`cap` 和 `drop` 是全局/会话选项，而不是按渠道的配置 -键名。 +对于选项，内联或已存储的 `/queue` 选项优先于配置。随后应用渠道特定 debounce（`messages.queue.debounceMsByChannel`）、插件 debounce 默认值、全局 `messages.queue` 选项以及内置默认值。`cap` 和 `drop` 是全局/会话选项，不是按渠道配置键。 ## 按会话覆盖 - 将 `/queue ` 作为独立命令发送，以存储当前会话的模式。 -- 选项可以组合使用：`/queue collect debounce:0.5s cap:25 drop:summarize` +- 选项可以组合：`/queue collect debounce:0.5s cap:25 drop:summarize` - `/queue default` 或 `/queue reset` 会清除会话覆盖。 -## 范围与保证 +## 范围和保证 -- 适用于所有使用 Gateway 网关回复管线的入站渠道中的自动回复智能体运行（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat 等）。 -- 默认 lane（`main`）在进程范围内用于入站 + 主 Heartbeat；设置 `agents.defaults.maxConcurrent` 以允许多个会话并行。 -- 可能存在其他 lane（例如 `cron`、`cron-nested`、`nested`、`subagent`），以便后台作业可以并行运行，而不会阻塞入站回复。隔离的 cron 智能体轮次在其内部智能体执行使用 `cron-nested` 时会占用一个 `cron` slot；两者都使用 `cron.maxConcurrentRuns`。共享的非 cron `nested` 流程会保留自身的 lane 行为。这些分离运行会作为 [后台任务](/zh-CN/automation/tasks) 跟踪。 -- 按会话 lane 保证同一时间只有一个智能体运行会触及给定会话。 -- 无外部依赖或后台 worker 线程；纯 TypeScript + promises。 +- 适用于所有使用 Gateway 网关回复流水线的入站渠道上的自动回复智能体运行（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat 等）。 +- 默认 lane（`main`）在进程范围内适用于入站 + main Heartbeat；设置 `agents.defaults.maxConcurrent` 可允许多个会话并行。 +- 可能存在额外 lane（例如 `cron`、`cron-nested`、`nested`、`subagent`），因此后台作业可以并行运行，而不会阻塞入站回复。隔离的 cron 智能体回合会占用一个 `cron` slot，而其内部智能体执行使用 `cron-nested`；两者都使用 `cron.maxConcurrentRuns`。共享的非 cron `nested` 流程保持自己的 lane 行为。这些分离运行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 +- 按会话 lane 保证同一时间只有一个智能体运行会触碰给定会话。 +- 没有外部依赖或后台 worker 线程；纯 TypeScript + promises。 ## 故障排除 -- 如果命令似乎卡住，请启用详细日志并查找 “queued for …ms” 行，以确认队列正在排空。 +- 如果命令看起来卡住，请启用详细日志，并查找 “queued for …ms” 行来确认队列正在排空。 - 如果你需要队列深度，请启用详细日志并观察队列时序行。 -- Codex app-server 中接受一个轮次后停止发出进度的运行，会由 Codex adapter 中断，以便活动会话 lane 可以释放，而不是等待外层运行超时。 -- 启用诊断时，保持 `processing` 超过 `diagnostics.stuckSessionWarnMs` 的会话会记录卡住会话警告。默认情况下，活动嵌入式运行、活动回复操作和活动 lane 任务仍仅发出警告；如果陈旧的启动记账没有活动会话工作，则可以释放受影响的会话 lane，使排队工作得以排空。 +- Codex app-server 运行如果接受了一个回合后停止发出进度，会被 Codex 适配器中断，这样活跃会话 lane 可以释放，而不是等待外层运行超时。 +- 启用诊断时，超过 `diagnostics.stuckSessionWarnMs` 仍保持 `processing` 的会话会按当前活动分类。活跃工作记录为 `session.long_running`；没有近期进度的活跃工作记录为 `session.stalled`；`session.stuck` 保留给没有活跃工作的陈旧会话簿记，并且只有该路径可以释放受影响的会话 lane，让排队工作继续排空。 ## 相关内容 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 4b87d9bee..4eb05c4cb 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,66 +2,66 @@ read_when: - 你需要精确的字段级配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考的链接 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键、默认值，以及指向专用子系统参考的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-29T01:48:44Z" + generated_at: "2026-05-01T23:18:13Z" model: gpt-5.5 provider: openai - source_hash: 83fd28b7d6a2e670ab97aac206bb14343bd887da3236c6135d7958cc6e97b735 + source_hash: d5e167fb8f9670e206a7b3794c8a2b1cf269fc7ad816c2feae00d1309edd1d54 source_path: gateway/configuration-reference.md workflow: 16 --- -Core 配置参考，适用于 `~/.openclaw/openclaw.json`。如需面向任务的概览，请参阅[配置](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。如需面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。 -涵盖主要的 OpenClaw 配置表面；当某个子系统有自己的更深入参考时，会链接到对应页面。渠道和插件拥有的命令目录，以及深层内存/QMD 调节项，位于它们自己的页面，而不是本页。 +涵盖主要的 OpenClaw 配置表面；当某个子系统有自己的深入参考时，会链接到对应页面。由渠道和插件拥有的命令目录以及深层记忆/QMD 调节项位于各自页面，而不是本页。 -代码依据： +代码事实来源： - `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema；可用时会合并内置/插件/渠道元数据 -- `config.schema.lookup` 会为向下钻取工具返回一个按路径限定的 schema 节点 +- `config.schema.lookup` 会返回一个按路径限定的 schema 节点，用于下钻工具 - `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希 -智能体查找路径：编辑前，使用 `gateway` 工具动作 `config.schema.lookup` +Agent 查找路径：编辑前使用 `gateway` 工具操作 `config.schema.lookup` 获取精确的字段级文档和约束。使用 [配置](/zh-CN/gateway/configuration) 获取面向任务的指导，并使用本页 -查看更广泛的字段映射、默认值和子系统参考链接。 +查看更广泛的字段映射、默认值以及指向子系统参考的链接。 -专用深度参考： +专用深入参考： -- [内存配置参考](/zh-CN/reference/memory-config)，涵盖 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 -- [斜杠命令](/zh-CN/tools/slash-commands)，涵盖当前内置 + 内置插件命令目录 -- 拥有渠道专属命令表面的渠道/插件页面 +- [记忆配置参考](/zh-CN/reference/memory-config)，涵盖 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 +- [斜杠命令](/zh-CN/tools/slash-commands)，涵盖当前内置 + 捆绑命令目录 +- 拥有对应渠道特定命令表面的渠道/插件页面 -配置格式为 **JSON5**（允许注释 + 尾随逗号）。所有字段都是可选的 — OpenClaw 会在省略时使用安全默认值。 +配置格式是 **JSON5**（允许注释 + 尾随逗号）。所有字段都是可选的；省略时，OpenClaw 会使用安全默认值。 --- ## 渠道 -按渠道配置键已移至专用页面 — 请参阅 -[配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`， +各渠道配置键已移到专用页面；请参阅 +[配置 — 渠道](/zh-CN/gateway/config-channels)，其中包含 `channels.*`， 包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他 -内置渠道（凭证、访问控制、多账户、提及门控）。 +内置渠道（认证、访问控制、多账号、提及门控）。 ## 智能体默认值、多智能体、会话和消息 -已移至专用页面 — 请参阅 -[配置 — 智能体](/zh-CN/gateway/config-agents)，了解： +已移到专用页面；请参阅 +[配置 — 智能体](/zh-CN/gateway/config-agents)，其中包括： -- `agents.defaults.*`（工作区、模型、thinking、心跳、内存、媒体、Skills、沙箱） +- `agents.defaults.*`（工作区、模型、thinking、heartbeat、记忆、媒体、Skills、沙箱） - `multiAgent.*`（多智能体路由和绑定） -- `session.*`（会话生命周期、压缩、裁剪） +- `session.*`（会话生命周期、压缩、剪枝） - `messages.*`（消息投递、TTS、Markdown 渲染） - `talk.*`（Talk 模式） - - `talk.speechLocale`：Talk 在 iOS/macOS 上进行语音识别时使用的可选 BCP 47 语言区域 ID - - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转写文本前保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`） + - `talk.speechLocale`：iOS/macOS 上 Talk 语音识别的可选 BCP 47 区域设置 id + - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录前保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`） ## 工具和自定义提供商 -工具策略、实验性开关、提供商支持的工具配置，以及自定义 -提供商 / base-URL 设置已移至专用页面 — 请参阅 +工具策略、实验性开关、由提供商支持的工具配置，以及自定义 +提供商 / 基础 URL 设置已移到专用页面；请参阅 [配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。 ## Models @@ -80,17 +80,18 @@ Core 配置参考，适用于 `~/.openclaw/openclaw.json`。如需面向任务 ``` - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：按提供商 ID 键控的自定义提供商映射。 +- `models.providers`：按提供商 id keyed 的自定义提供商映射。 - `models.pricing.enabled`：控制后台定价引导。当为 - `false` 时，Gateway 网关启动会跳过 OpenRouter 和 LiteLLM 定价目录拉取； + `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,19 +115,19 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 } ``` -- `mcp.servers`：命名的 stdio 或远程 MCP 服务器定义，供暴露已配置 MCP 工具的运行时使用。 +- `mcp.servers`：具名 stdio 或远程 MCP 服务器定义，供暴露已配置 MCP 工具的运行时使用。 远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`； `type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和 `openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。 - `mcp.sessionIdleTtlMs`：会话作用域内置 MCP 运行时的空闲 TTL。 - 一次性嵌入运行会请求运行结束清理；此 TTL 是长生命周期会话 - 和未来调用方的兜底机制。 -- `mcp.*` 下的更改会通过处置缓存的会话 MCP 运行时进行热应用。 + 一次性嵌入式运行会请求运行结束清理；此 TTL 是 + 长生命周期会话和未来调用方的兜底机制。 +- `mcp.*` 下的变更会通过释放缓存的会话 MCP 运行时来热应用。 下一次工具发现/使用会根据新配置重新创建它们，因此移除的 - `mcp.servers` 条目会立即被回收，而不是等待空闲 TTL。 + `mcp.servers` 条目会立即回收，而不是等待空闲 TTL。 请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 -[CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)了解运行时行为。 +[CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays) 了解运行时行为。 ## Skills @@ -153,14 +154,13 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 } ``` -- `allowBundled`：仅用于内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。 -- `load.extraDirs`：额外的共享 Skill 根目录（优先级最低）。 -- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器， - 然后再回退到其他安装器类型。 +- `allowBundled`：仅用于内置 Skills 的可选允许列表（不影响托管/工作区 Skills）。 +- `load.extraDirs`：额外的共享 Skill 根目录（最低优先级）。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后再回退到其他安装器类型。 - `install.nodeManager`：`metadata.openclaw.install` 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false` 会禁用某个 Skill，即使它是内置/已安装的。 -- `entries..apiKey`：供声明主环境变量的 Skills 使用的便捷项（明文字符串或 SecretRef 对象）。 +- `entries..enabled: false` 会禁用某个 Skill，即使它已内置/已安装。 +- `entries..apiKey`：供声明主要环境变量的 Skills 使用的便捷项（明文字符串或 SecretRef 对象）。 --- @@ -189,42 +189,42 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 -- **配置更改需要重启 Gateway 网关。** -- `allow`：可选允许列表（只加载列出的插件）。`deny` 优先。 +- 设备发现接受原生 OpenClaw 插件以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- **配置变更需要重启 Gateway 网关。** +- `allow`：可选允许列表（只加载列出的插件）。`deny` 优先生效。 - `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 - `plugins.entries..env`：插件作用域的环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子和受支持 bundle 提供的钩子目录。 -- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可以从类型化钩子中读取原始对话内容，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`。 -- `plugins.entries..subagent.allowModelOverride`：显式信任此插件为后台子智能体运行请求每次运行的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的标准 `provider/model` 目标的可选允许列表。仅在你有意允许任何模型时使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（当可用时由原生 OpenClaw 插件 schema 验证）。 -- 渠道插件账户/运行时设置位于 `channels.` 下，并应由所属插件的 manifest `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取提供商设置。 - - `apiKey`：Firecrawl API key（接受 SecretRef）。回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 - - `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。 - - `onlyMainContent`：仅提取页面主内容（默认：`true`）。 - - `maxAgeMs`：最大缓存年龄，单位为毫秒（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时时间，单位为秒（默认：`60`）。 -- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok 网页搜索）设置。 +- `plugins.entries..hooks.allowPromptInjection`：当为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的由 bundle 提供的钩子目录。 +- `plugins.entries..hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可以从类型化钩子读取原始对话内容，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`。 +- `plugins.entries..subagent.allowModelOverride`：显式信任此插件，让它可以为后台子智能体运行请求每次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的标准 `provider/model` 目标可选允许列表。只有在你有意允许任何模型时才使用 `"*"`。 +- `plugins.entries..config`：由插件定义的配置对象（可用时由原生 OpenClaw 插件 schema 验证）。 +- 渠道插件账号/运行时设置位于 `channels.` 下，并应由所属插件的 manifest `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。 + - `apiKey`：Firecrawl API key（接受 SecretRef）。回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。 + - `baseUrl`：Firecrawl API 基础 URL（默认值：`https://api.firecrawl.dev`）。 + - `onlyMainContent`：仅从页面提取主要内容（默认值：`true`）。 + - `maxAgeMs`：最大缓存年龄，单位为毫秒（默认值：`172800000` / 2 天）。 + - `timeoutSeconds`：抓取请求超时，单位为秒（默认值：`60`）。 +- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok Web 搜索）设置。 - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：内存 Dreaming 设置。请参阅 [Dreaming](/zh-CN/concepts/dreaming) 了解阶段和阈值。 - - `enabled`：主 Dreaming 开关（默认 `false`）。 - - `frequency`：每次完整 Dreaming 扫描的 cron 节奏（默认为 `"0 3 * * *"`）。 - - `model`：可选 Dream Diary 子智能体模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；配合 `allowedModels` 使用以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退。 +- `plugins.entries.memory-core.config.dreaming`：记忆 dreaming 设置。请参阅 [Dreaming](/zh-CN/concepts/dreaming) 了解阶段和阈值。 + - `enabled`：总 dreaming 开关（默认值为 `false`）。 + - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认值为 `"0 3 * * *"`）。 + - `model`：可选的 Dream Diary 子智能体模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；与 `allowedModels` 搭配使用以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退。 - 阶段策略和阈值是实现细节（不是面向用户的配置键）。 -- 完整内存配置位于[内存配置参考](/zh-CN/reference/memory-config)： +- 完整记忆配置位于 [记忆配置参考](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude bundle 插件也可以从 `settings.json` 贡献嵌入式 Pi 默认值；OpenClaw 会将其作为经过清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活跃的内存插件 ID，或选择 `"none"` 以禁用内存插件。 -- `plugins.slots.contextEngine`：选择活跃的上下文引擎插件 ID；默认值为 `"legacy"`，除非你安装并选择了另一个引擎。 +- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些默认值应用为经过清理的智能体设置，而不是原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动记忆插件 id，或选择 `"none"` 以禁用记忆插件。 +- `plugins.slots.contextEngine`：选择活动 context engine 插件 id；除非你安装并选择了其他引擎，否则默认为 `"legacy"`。 -请参阅[插件](/zh-CN/tools/plugin)。 +请参阅 [插件](/zh-CN/tools/plugin)。 --- @@ -274,27 +274,27 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 } ``` -- `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `tabCleanup` 会在空闲时间后或会话超出上限时回收已跟踪的主智能体标签页。设置 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 可禁用这些单独的清理模式。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 未设置时处于禁用状态，因此浏览器导航默认保持严格。 -- 只有在你有意信任专用网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间会受到相同的专用网络阻止。 +- `evaluateEnabled: false` 会停用 `act:evaluate` 和 `wait --fn`。 +- `tabCleanup` 会在空闲时间之后，或在会话超过上限时，回收已跟踪的主智能体标签页。设置 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 可停用这些单独的清理模式。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 未设置时处于停用状态，因此浏览器导航默认保持严格。 +- 仅在你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间会受到相同的私有网络阻止。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。 -- 远程配置文件仅支持附加（禁用启动/停止/重置）。 +- 在严格模式下，使用 `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，并且可以在所选主机上附加，或通过已连接的浏览器节点附加。 +- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 `attachOnly` CDP 可达性以及标签页打开请求。托管的 loopback 配置文件保留本地 CDP 默认值。 +- 如果外部托管的 CDP 服务可通过 loopback 访问，请将该配置文件的 `attachOnly: true`；否则 OpenClaw 会把该 loopback 端口视为本地托管浏览器配置文件，并可能报告本地端口归属错误。 +- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以在所选主机上或通过已连接的浏览器节点附加。 - `existing-session` 配置文件可以设置 `userDataDir`，以指向特定的基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。 -- `existing-session` 配置文件保留当前的 Chrome MCP 路由限制：基于快照/引用的操作，而不是 CSS 选择器定位；单文件上传钩子；无对话框超时覆盖；无 `wait --load networkidle`；并且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 +- `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 的正整数；无效配置值会被拒绝。 +- 本地托管配置文件可以设置 `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`、窗口大小或调试标志）。 --- @@ -312,8 +312,8 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 } ``` -- `seamColor`：原生应用 UI 外壳的强调色（Talk Mode 气泡色调等）。 -- `assistant`：控制 UI 身份覆盖。回退到活动智能体身份。 +- `seamColor`：原生应用 UI chrome 的强调色（Talk Mode 气泡色调等）。 +- `assistant`：Control UI 身份覆盖。回退到活跃智能体身份。 --- @@ -391,51 +391,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`。两者都已配置且未设置模式时，启动以及服务安装/修复流程会失败。 +- **旧版 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 桥接网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此无法访问 Gateway 网关。使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并设置 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认必需。非 loopback bind 需要 Gateway 网关认证。实际上，这意味着需要共享令牌/密码，或使用带有 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成令牌。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。两者都已配置但 mode 未设置时，启动和服务安装/修复流程会失败。 - `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的 local loopback 设置；新手引导提示有意不提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将浏览器/用户认证委托给带身份感知能力的反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)）。默认情况下，此模式期望代理来源为 **非 loopback**；同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。内部同主机调用方可以使用 `gateway.auth.password` 作为本地直连回退；`gateway.auth.token` 仍然与 trusted-proxy 模式互斥。 -- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份标头可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头认证；它们改为遵循 Gateway 网关的普通 HTTP 认证模式。此无令牌流程假定 Gateway 网关主机可信。当 `tailscale.mode = "serve"` 时默认值为 `true`。 +- `gateway.auth.mode: "trusted-proxy"`：将浏览器/用户认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)）。此模式默认期望一个**非 loopback** 代理来源；同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。内部同主机调用方可以使用 `gateway.auth.password` 作为本地直接回退；`gateway.auth.token` 仍然与 trusted-proxy 模式互斥。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份标头可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头认证；它们改用 Gateway 网关的常规 HTTP 认证模式。此无令牌流程假定 Gateway 网关主机可信。当 `tailscale.mode = "serve"` 时默认值为 `true`。 - `gateway.auth.rateLimit`：可选的认证失败限制器。按客户端 IP 和认证作用域应用（shared-secret 和 device-token 会独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败之前串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求上触发限制器，而不是两个请求都以普通不匹配的方式竞争通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；当你有意也要限制 localhost 流量时（用于测试设置或严格代理部署），请设置为 `false`。 -- 浏览器来源的 WS 认证尝试始终会被限流，并禁用 loopback 豁免（针对基于浏览器的 localhost 暴力破解提供纵深防御）。 -- 在 loopback 上，这些浏览器来源锁定会按规范化后的 `Origin` - 值隔离，因此来自一个 localhost 来源的重复失败不会自动 - 锁定另一个来源。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开，需要认证）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时必需。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，启用 Host 标头来源回退，用于有意依赖 Host 标头来源策略的部署。 -- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境中的 - break-glass 覆盖开关，允许对受信任的私有网络 - IP 使用明文 `ws://`；明文默认仍仅限 loopback。没有等效的 `openclaw.json` - 配置，并且浏览器私有网络配置（例如 - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`）不会影响 Gateway 网关 + - 在异步 Tailscale Serve Control UI 路径上，写入失败前，同一 `{scope, clientIp}` 的失败尝试会被串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求触发限制器，而不是两个都以普通不匹配的形式竞争通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意希望 localhost 流量也受到速率限制时（用于测试设置或严格代理部署），请设置为 `false`。 +- 浏览器来源的 WS 认证尝试始终会被限流，并禁用 loopback 豁免（针对基于浏览器的 localhost 暴力破解的纵深防御）。 +- 在 loopback 上，这些浏览器来源的锁定会按规范化后的 `Origin` + 值隔离，因此来自一个 localhost origin 的重复失败不会自动 + 锁定另一个 origin。 +- `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`：官方/TestFlight iOS 构建将中继支持的注册发布到 Gateway 网关后，外部 APNs 中继使用的基础 HTTPS URL。此 URL 必须与编译进 iOS 构建的中继 URL 匹配。 +- `gateway.remote.token` / `.password` 是远程客户端凭据字段。它们本身不会配置 Gateway 网关认证。 +- `gateway.push.apns.relay.baseUrl`：外部 APNs 中继的基础 HTTPS URL，官方/TestFlight iOS 构建在向 Gateway 网关发布由中继支持的注册后会使用它。此 URL 必须与编译进 iOS 构建的中继 URL 匹配。 - `gateway.push.apns.relay.timeoutMs`：Gateway 网关到中继的发送超时时间，单位为毫秒。默认值为 `10000`。 -- 中继支持的注册会委托给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并将注册作用域的发送授权转发给 Gateway 网关。另一个 Gateway 网关无法复用该已存储的注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述中继配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发使用的逃生口，用于 loopback HTTP 中继 URL。生产中继 URL 应保持使用 HTTPS。 -- `gateway.handshakeTimeoutMs`：认证前 Gateway 网关 WebSocket 握手超时时间，单位为毫秒。默认值：`15000`。设置后，`OPENCLAW_HANDSHAKE_TIMEOUT_MS` 优先。当本地客户端可以连接但启动预热仍在稳定中的高负载或低性能主机上，请增大此值。 +- 由中继支持的注册会委托给特定 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并向 Gateway 网关转发一个注册作用域的发送授权。另一个 Gateway 网关无法复用该已存储的注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述中继配置的临时环境变量覆盖项。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发的逃生口，允许 loopback HTTP 中继 URL。生产中继 URL 应保持使用 HTTPS。 +- `gateway.handshakeTimeoutMs`：认证前 Gateway 网关 WebSocket 握手超时时间，单位为毫秒。默认值：`15000`。设置后，`OPENCLAW_HANDSHAKE_TIMEOUT_MS` 优先。对于负载较高或性能较低的主机，如果本地客户端可以连接但启动预热仍在收敛，请增大此值。 - `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位为分钟。设置为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：过期 socket 阈值，单位为分钟。保持此值大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道/账号的最大健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保持全局监控启用。 -- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，它优先于渠道级覆盖。 -- 仅当未设置 `gateway.auth.*` 时，本地 Gateway 网关调用路径才可以使用 `gateway.remote.*` 作为回退。 -- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 且未解析，解析会失败关闭（不会用远程回退来掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 条件。 -- `allowRealIpFallback`：当为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现失败关闭行为。 -- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准未请求作用域的首次节点设备配对。未设置时禁用。这不会自动批准操作者/浏览器/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和平台允许列表评估后，对已声明节点命令进行全局允许/拒绝整形。使用 `allowCommands` 选择加入危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式允许本来会包含某个命令，`denyCommands` 也会移除它。节点更改其已声明命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。 -- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 阻止的额外工具名称（扩展默认拒绝列表）。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内的最大健康监控重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：按渠道选择停用健康监控重启，同时保持全局监控启用。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖项。设置后，它优先于渠道级覆盖项。 +- 本地 Gateway 网关调用路径只能在 `gateway.auth.*` 未设置时使用 `gateway.remote.*` 作为回退。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置且未解析，则解析会闭合失败（不会用远程回退掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**使 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。 +- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现闭合失败行为。 +- `gateway.nodes.pairing.autoApproveCidrs`：可选 CIDR/IP 允许列表，用于自动批准首次节点设备配对且没有请求作用域的情况。未设置时禁用。这不会自动批准操作者/浏览器/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：配对和平台允许列表评估后，对已声明节点命令的全局允许/拒绝整形。使用 `allowCommands` 选择启用危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式 allow 原本会包含某个命令，`denyCommands` 也会移除它。节点更改其声明的命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。 +- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 阻止的额外工具名称（扩展默认拒绝列表）。 - `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。 @@ -451,11 +451,11 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 空允许列表会被视为未设置；使用 `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 origin 设置；参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在一台主机上使用唯一端口和状态目录运行多个 Gateway 网关： +使用唯一端口和状态目录在一台主机上运行多个 Gateway 网关： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -483,8 +483,8 @@ 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 路径。 @@ -503,13 +503,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制运行时如何应用配置编辑。 +- `mode`：控制如何在运行时应用配置编辑。 - `"off"`：忽略实时编辑；更改需要显式重启。 - - `"restart"`：配置变更时始终重启 Gateway 网关进程。 - - `"hot"`：在进程内应用更改，不重启。 + - `"restart"`：配置更改时始终重启 Gateway 网关进程。 + - `"hot"`：在进程内应用更改而不重启。 - `"hybrid"`（默认）：先尝试热重载；必要时回退到重启。 - `debounceMs`：应用配置更改前的防抖窗口，单位为毫秒（非负整数）。 -- `deferralTimeoutMs`：可选的最大等待时间，单位为毫秒，用于在强制重启前等待进行中的操作。省略它会使用默认的有界等待（`300000`）；设置为 `0` 可无限期等待，并定期记录仍有待处理操作的警告。 +- `deferralTimeoutMs`：强制重启前等待进行中操作的可选最长时间，单位为毫秒。省略它会使用默认有界等待（`300000`）；设置为 `0` 会无限期等待并定期记录仍在等待的警告。 --- @@ -551,34 +551,34 @@ openclaw gateway --port 19001 验证和安全说明： -- `hooks.enabled=true` 要求 `hooks.token` 非空。 -- `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关令牌会被拒绝。 +- `hooks.enabled=true` 需要非空的 `hooks.token`。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关令牌会被拒绝。 - `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 - 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果某个映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该选择加入。 +- 如果映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该显式启用。 **端点：** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受来自请求载荷的 `sessionKey`。 + - 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受请求负载中的 `sessionKey`。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - - 模板渲染的映射 `sessionKey` 值会被视为外部提供，也要求 `hooks.allowRequestSessionKey=true`。 + - 模板渲染的映射 `sessionKey` 值会被视为外部提供的值，并且也需要 `hooks.allowRequestSessionKey=true`。 - + - `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 匹配通用路径的载荷字段。 -- 像 `{{messages[0].subject}}` 这样的模板会从载荷中读取。 -- `transform` 可以指向一个返回钩子操作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且保留在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。 +- `match.source` 匹配通用路径的负载字段。 +- `{{messages[0].subject}}` 这样的模板会从负载读取。 +- `transform` 可以指向返回钩子操作的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且保持在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。 - `agentId` 路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 拒绝全部）。 -- `defaultSessionKey`：用于没有显式 `sessionKey` 的钩子智能体运行的可选固定会话键。 +- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的钩子智能体运行。 - `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化 `sessionKey` 时，它会变为必需项。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化的 `sessionKey` 时，它会变为必需。 - `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 -- `model` 会覆盖此钩子运行使用的 LLM（如果已设置模型目录，则必须允许该模型）。 +- `model` 会为此次钩子运行覆盖 LLM（如果已设置模型目录，则必须被允许）。 @@ -586,7 +586,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 { @@ -626,18 +626,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"`（默认）。 +- 仅限本地：保持 `gateway.bind: "loopback"`（默认）。 - 非 loopback 绑定：canvas 路由需要 Gateway 网关身份验证（令牌/密码/受信代理），与其他 Gateway 网关 HTTP 表面相同。 -- Node WebViews 通常不会发送身份验证标头；节点完成配对并连接后，Gateway 网关会发布节点作用域的能力 URL，用于访问 canvas/A2UI。 -- 能力 URL 绑定到活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 -- 将实时重载客户端注入到提供服务的 HTML 中。 -- 为空时自动创建起始 `index.html`。 -- 还会在 `/__openclaw__/a2ui/` 提供 A2UI。 +- Node WebViews 通常不会发送身份验证标头；节点完成配对并连接后，Gateway 网关会通告节点作用域的 capability URL，用于访问 canvas/A2UI。 +- Capability URL 绑定到活跃的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。 +- 将 live-reload 客户端注入到所服务的 HTML 中。 +- 为空时自动创建入门 `index.html`。 +- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 - 更改需要重启 Gateway 网关。 -- 对于大型目录或 `EMFILE` 错误，请禁用实时重载。 +- 对于大型目录或 `EMFILE` 错误，请禁用 live reload。 --- @@ -657,7 +657,7 @@ openclaw gateway --port 19001 - `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。 - `full`：包含 `cliPath` + `sshPort`。 -- 当系统主机名是有效 DNS 标签时，主机名默认使用系统主机名，否则回退到 `openclaw`。可用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 +- 当系统主机名是有效 DNS 标签时，主机名默认使用系统主机名，否则回退到 `openclaw`。可使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 ### 广域（DNS-SD） @@ -669,7 +669,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`。 @@ -694,14 +694,14 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境缺少该键时，内联环境变量才会被应用。 -- `.env` 文件：CWD 的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 +- 仅当进程环境缺少该键时，才会应用内联环境变量。 +- `.env` 文件：CWD `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 - `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。 - 完整优先级见 [环境](/zh-CN/help/environment)。 ### 环境变量替换 -在任何配置字符串中使用 `${VAR_NAME}` 引用环境变量： +在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -712,8 +712,8 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失或为空的变量会在配置加载时抛出错误。 -- 使用 `$${VAR}` 转义为字面量 `${VAR}`。 +- 缺失或为空的变量会在配置加载时报错。 +- 使用 `$${VAR}` 转义，表示字面量 `${VAR}`。 - 可与 `$include` 配合使用。 --- @@ -733,16 +733,16 @@ openclaw gateway --port 19001 验证： - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` -- `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` 的 id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） -- `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` 的 id 不能包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝） +- `source: "env"` id 模式：`^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"` id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） +- `source: "exec"` id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- `source: "exec"` id 不得包含 `.` 或 `..` 这种以斜杠分隔的路径段（例如 `a/../b` 会被拒绝） -### 支持的凭证范围 +### 支持的凭证表面 -- 规范矩阵：[SecretRef 凭证范围](/zh-CN/reference/secretref-credential-surface) +- 规范矩阵：[SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) - `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。 -- `auth-profiles.json` 引用包含在运行时解析和审计覆盖范围内。 +- `auth-profiles.json` 引用会纳入运行时解析和审计覆盖范围。 ### 密钥提供商配置 @@ -774,14 +774,14 @@ 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 验证不可用时，文件和 exec 提供商路径会安全失败。仅对无法验证的可信路径设置 `allowInsecurePath: true`。 +- `exec` 提供商需要绝对 `command` 路径，并通过 stdin/stdout 使用协议载荷。 +- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可以允许符号链接路径，同时验证解析后的目标路径。 - 如果配置了 `trustedDirs`，可信目录检查会应用于解析后的目标路径。 -- 默认情况下，`exec` 子进程环境是最小化的；请使用 `passEnv` 显式传递所需变量。 -- 密钥引用会在激活时解析为内存中的快照，之后请求路径只读取该快照。 -- 激活期间会应用活跃范围过滤：启用范围上的未解析引用会导致启动或重新加载失败，而非活跃范围会被跳过并给出诊断信息。 +- 默认情况下，`exec` 子进程环境是最小化的；请使用 `passEnv` 显式传入必需变量。 +- 密钥引用会在激活时解析为内存快照，之后请求路径只读取该快照。 +- 激活期间会应用活跃表面过滤：已启用表面上的未解析引用会导致启动或重新加载失败，而非活跃表面会被跳过并给出诊断信息。 --- @@ -804,10 +804,10 @@ 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.json` 条目时会将其清除。 +- `auth-profiles.json` 支持值级引用（静态凭证模式中，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- 旧版扁平 `auth-profiles.json` 映射（例如 `{ "provider": { "apiKey": "..." } }`）不是运行时格式；`openclaw doctor --fix` 会将它们重写为规范的 `provider:default` API-key 配置文件，并创建 `.legacy-flat.*.bak` 备份。 +- OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支撑的身份验证配置文件凭证。 +- 静态运行时凭证来自内存中已解析的快照；发现旧版静态 `auth.json` 条目时会将其清理。 - 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。 - 见 [OAuth](/zh-CN/concepts/oauth)。 - 密钥运行时行为和 `audit/configure/apply` 工具：[密钥管理](/zh-CN/gateway/secrets)。 @@ -832,15 +832,15 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`：当配置文件因确认为计费或信用额度不足错误而失败时，以小时为单位的基础退避（默认值：`5`）。即使在 `401`/`403` 响应中，明确的计费文本仍可能归入这里，但特定提供商的文本匹配器仍限定在其所属的提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或组织/工作区支出上限消息会保留在 `rate_limit` 路径中。 -- `billingBackoffHoursByProvider`：可选的按提供商覆盖的计费退避小时数。 -- `billingMaxHours`：计费退避指数增长的小时上限（默认值：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的分钟级基础退避（默认值：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟上限（默认值：`60`）。 -- `failureWindowHours`：用于退避计数器的滚动窗口小时数（默认值：`24`）。 -- `overloadedProfileRotations`：在切换到模型回退之前，过载错误允许的最大同提供商身份验证配置文件轮换次数（默认值：`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`。 --- @@ -861,9 +861,9 @@ 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/工具/诊断安全表面在发出前仍会遮蔽密钥。 +- `consoleLevel` 在使用 `--verbose` 时提升为 `debug`。 +- `maxFileBytes`：轮转前当前活动日志文件的最大大小（以字节为单位，正整数；默认值：`104857600` = 100 MB）。OpenClaw 会在当前活动文件旁边最多保留五个编号归档。 +- `redactSensitive` / `redactPatterns`：对控制台输出、文件日志、OTLP 日志记录和持久化的会话转录文本进行尽力而为的掩码处理。`redactSensitive: "off"` 只会禁用这个通用日志/转录策略；UI/工具/诊断安全表面仍会在发出前遮盖密钥。 --- @@ -911,25 +911,25 @@ openclaw gateway --port 19001 } ``` -- `enabled`：仪表化输出的总开关（默认：`true`）。 -- `flags`：启用定向日志输出的标志字符串数组（支持类似 `"telegram.*"` 或 `"*"` 的通配符）。 -- `stuckSessionWarnMs`：当会话保持处理状态时，发出卡住会话警告的毫秒年龄阈值。 -- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。完整配置、信号目录和隐私模型请参阅 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 +- `enabled`：仪表化输出的主开关（默认值：`true`）。 +- `flags`：启用目标日志输出的标志字符串数组（支持像 `"telegram.*"` 或 `"*"` 这样的通配符）。 +- `stuckSessionWarnMs`：用于将长时间运行的处理会话分类为 `session.long_running`、`session.stalled` 或 `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.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`：周期性遥测刷新的间隔，单位为毫秒。 -- `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`）。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。 +- `otel.sampleRate`：trace 采样率 `0`–`1`。 +- `otel.flushIntervalMs`：周期性遥测刷新间隔（毫秒）。 +- `otel.captureContent`：选择加入的原始内容捕获，用于 OTEL span 属性。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于最新实验性 GenAI span 提供商属性的环境开关。默认情况下，span 会保留旧版 `gen_ai.system` 属性以实现兼容；GenAI metrics 使用有界语义属性。 +- `OPENCLAW_OTEL_PRELOADED=1`：用于已经注册全局 OpenTelemetry SDK 的宿主的环境开关。OpenClaw 随后会跳过插件自有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。 +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：在未设置匹配配置键时使用的特定信号端点环境变量。 +- `cacheTrace.enabled`：为嵌入式运行记录缓存 trace 快照（默认值：`false`）。 +- `cacheTrace.filePath`：缓存 trace JSONL 的输出路径（默认值：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存 trace 输出中包含的内容（全部默认值：`true`）。 --- @@ -952,11 +952,11 @@ 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`：测试版渠道检查运行频率，单位为小时（默认：`1`；最大：`24`）。 +- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认值：`true`）。 +- `auto.enabled`：为包安装启用后台自动更新（默认值：`false`）。 +- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟小时数（默认值：`6`；最大值：`168`）。 +- `auto.stableJitterHours`：额外的稳定渠道 rollout 分散窗口小时数（默认值：`12`；最大值：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查的运行频率（小时，默认值：`1`；最大值：`24`）。 --- @@ -989,22 +989,22 @@ openclaw gateway --port 19001 } ``` -- `enabled`：全局 ACP 功能门控（默认：`true`；设为 `false` 可隐藏 ACP 分发和生成入口）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 +- `enabled`：全局 ACP 功能门控（默认值：`true`；设置为 `false` 可隐藏 ACP 分发和生成入口）。 +- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认值：`true`）。设置为 `false` 可保持 ACP 命令可用，同时阻止执行。 - `backend`：默认 ACP 运行时后端 ID（必须匹配已注册的 ACP 运行时插件）。 如果设置了 `plugins.allow`，请包含后端插件 ID（例如 `acpx`），否则内置默认插件不会加载。 - `defaultAgent`：当生成未指定显式目标时的后备 ACP 目标智能体 ID。 - `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 允许列表；为空表示没有额外限制。 - `maxConcurrentSessions`：最大并发活动 ACP 会话数。 -- `stream.coalesceIdleMs`：流式文本的空闲刷新窗口，单位为毫秒。 -- `stream.maxChunkChars`：拆分流式块投影前的最大块大小。 -- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 增量流式传输；`"final_only"` 缓冲到轮次终止事件为止。 -- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次投影的最大助手输出字符数。 -- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行的最大字符数。 +- `stream.coalesceIdleMs`：流式文本的空闲刷新窗口（毫秒）。 +- `stream.maxChunkChars`：拆分流式 block projection 前的最大 chunk 大小。 +- `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.ttlMinutes`：ACP 会话工作进程在可清理前的空闲 TTL（分钟）。 - `runtime.installCommand`：引导 ACP 运行时环境时要运行的可选安装命令。 --- @@ -1022,10 +1022,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`。 --- @@ -1055,9 +1055,9 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 ## Bridge（旧版，已移除） -当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再是配置架构的一部分（在移除前验证会失败；`openclaw doctor --fix` 可以剥离未知键）。 +当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再属于配置 schema（验证会失败，直到移除；`openclaw doctor --fix` 可以剥离未知键）。 - + ```json { @@ -1095,11 +1095,11 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- `sessionRetention`：在从 `sessions.json` 修剪前，保留已完成隔离 cron 运行会话的时长。也控制已归档删除 cron 转录的清理。默认：`24h`；设为 `false` 可禁用。 -- `runLog.maxBytes`：修剪前每个运行日志文件（`cron/runs/.jsonl`）的最大大小。默认：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志修剪时保留的最新行数。默认：`2000`。 -- `webhookToken`：用于 cron webhook POST 递送（`delivery.mode = "webhook"`）的 bearer token；如果省略，则不会发送身份验证标头。 -- `webhook`：已弃用的旧版后备 webhook URL（http/https），仅用于仍包含 `notify: true` 的已存储任务。 +- `sessionRetention`：在从 `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；如果省略，则不会发送 auth 标头。 +- `webhook`：已弃用的旧版后备 webhook URL（http/https），仅用于仍带有 `notify: true` 的已存储作业。 ### `cron.retry` @@ -1115,11 +1115,11 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- `maxAttempts`：一次性任务在瞬时错误上的最大重试次数（默认：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试的退避延迟数组，单位为毫秒（默认：`[30000, 60000, 300000]`；1–10 个条目）。 +- `maxAttempts`：一次性作业在瞬时错误上的最大重试次数（默认值：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试尝试的退避延迟数组（毫秒，默认值：`[30000, 60000, 300000]`；1–10 个条目）。 - `retryOn`：触发重试的错误类型 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则重试所有瞬时类型。 -仅适用于一次性 cron 任务。周期性任务使用单独的失败处理。 +仅适用于一次性 cron 作业。周期性作业使用单独的失败处理。 ### `cron.failureAlert` @@ -1138,12 +1138,12 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- `enabled`：启用 cron 任务失败警报（默认：`false`）。 -- `after`：触发警报前的连续失败次数（正整数，最小：`1`）。 -- `cooldownMs`：同一任务重复警报之间的最小毫秒数（非负整数）。 -- `includeSkipped`：将连续跳过的运行计入警报阈值（默认：`false`）。跳过的运行会单独跟踪，不影响执行错误退避。 -- `mode`：递送模式 — `"announce"` 通过渠道消息发送；`"webhook"` 发布到配置的 webhook。 -- `accountId`：用于限定警报递送范围的可选账号或渠道 ID。 +- `enabled`：启用 cron 作业失败警报（默认值：`false`）。 +- `after`：触发警报前的连续失败次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复警报之间的最小毫秒数（非负整数）。 +- `includeSkipped`：将连续跳过的运行计入警报阈值（默认值：`false`）。跳过的运行会单独跟踪，不影响执行错误退避。 +- `mode`：投递模式 — `"announce"` 通过渠道消息发送；`"webhook"` 发布到配置的 webhook。 +- `accountId`：用于限定警报投递范围的可选账户或渠道 ID。 ### `cron.failureDestination` @@ -1160,51 +1160,51 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- 所有任务中 cron 失败通知的默认目标位置。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。 -- `channel`：announce 投递的渠道覆盖项。`"last"` 会复用最后已知的投递渠道。 -- `to`：显式 announce 目标或 webhook URL。webhook 模式必需。 +- 所有作业的 cron 失败通知默认目标。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认为 `"announce"`。 +- `channel`：announce 投递的渠道覆盖项。`"last"` 会复用上一次已知的投递渠道。 +- `to`：显式 announce 目标或 webhook URL。webhook 模式必填。 - `accountId`：可选的投递账号覆盖项。 -- 每个任务的 `delivery.failureDestination` 会覆盖此全局默认值。 -- 当既没有设置全局失败目标位置，也没有设置每个任务的失败目标位置时，已通过 `announce` 投递的任务在失败时会回退到该主要 announce 目标。 -- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 任务，除非该任务的主要 `delivery.mode` 是 `"webhook"`。 +- 每个作业的 `delivery.failureDestination` 会覆盖此全局默认值。 +- 当既未设置全局失败目标，也未设置每个作业的失败目标时，已通过 `announce` 投递的作业会在失败时回退到该主 announce 目标。 +- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。 -请参阅 [Cron 任务](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 +参见 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)跟踪。 --- ## 媒体模型模板变量 -在 `tools.media.models[].args` 中展开的模板占位符： +`tools.media.models[].args` 中会展开的模板占位符： | 变量 | 描述 | | ------------------ | ------------------------------------------------- | -| `{{Body}}` | 完整的入站消息正文 | -| `{{RawBody}}` | 原始正文（没有历史记录/发送者包装） | +| `{{Body}}` | 完整的传入消息正文 | +| `{{RawBody}}` | 原始正文（无历史/发送者包装） | | `{{BodyStripped}}` | 去除群组提及后的正文 | | `{{From}}` | 发送者标识符 | | `{{To}}` | 目标标识符 | | `{{MessageSid}}` | 渠道消息 ID | | `{{SessionId}}` | 当前会话 UUID | | `{{IsNewSession}}` | 创建新会话时为 `"true"` | -| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaUrl}}` | 传入媒体伪 URL | | `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（图像/音频/文档/…） | +| `{{MediaType}}` | 媒体类型（图片/音频/文档/…） | | `{{Transcript}}` | 音频转录文本 | -| `{{Prompt}}` | 为 CLI 条目解析后的媒体提示词 | -| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 | +| `{{Prompt}}` | CLI 条目的已解析媒体提示词 | +| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | | `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力而为） | -| `{{GroupMembers}}` | 群组成员预览（尽力而为） | -| `{{SenderName}}` | 发送者显示名称（尽力而为） | -| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| `{{GroupSubject}}` | 群组主题（尽力提供） | +| `{{GroupMembers}}` | 群组成员预览（尽力提供） | +| `{{SenderName}}` | 发送者显示名称（尽力提供） | +| `{{SenderE164}}` | 发送者电话号码（尽力提供） | | `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- -## 配置 include（`$include`） +## 配置包含（`$include`） -将配置拆分到多个文件： +将配置拆分为多个文件： ```json5 // ~/.openclaw/openclaw.json @@ -1220,13 +1220,13 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 **合并行为：** - 单个文件：替换包含它的对象。 -- 文件数组：按顺序深度合并（后面的会覆盖前面的）。 -- 同级键：在 include 之后合并（覆盖包含的值）。 -- 嵌套 include：最多 10 层深度。 -- 路径：相对于包含文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。只有在仍解析到该边界内时，才允许绝对路径/`../` 形式。 -- OpenClaw 拥有的写入如果只更改一个由单文件 include 支持的顶层区段，会透传写入该被包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。 -- 根 include、include 数组，以及带同级覆盖项的 include 对 OpenClaw 拥有的写入是只读的；这些写入会封闭失败，而不是展平配置。 -- 错误：针对缺失文件、解析错误和循环 include 提供清晰消息。 +- 文件数组：按顺序深度合并（后面的覆盖前面的）。 +- 同级键：在包含项之后合并（覆盖包含值）。 +- 嵌套包含：最多深入 10 层。 +- 路径：相对于包含它的文件解析，但必须保留在顶层配置目录（`openclaw.json` 的 `dirname`）内。只有在仍解析到该边界内时，才允许绝对路径/`../` 形式。 +- OpenClaw 拥有的写入如果只更改由单文件包含支持的一个顶层部分，会透传写入到该被包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。 +- 根包含、包含数组，以及带同级覆盖项的包含，对于 OpenClaw 拥有的写入是只读的；这些写入会失败关闭，而不是扁平化配置。 +- 错误：针对缺失文件、解析错误和循环包含提供清晰消息。 --- diff --git a/docs/zh-CN/gateway/opentelemetry.md b/docs/zh-CN/gateway/opentelemetry.md index 77c3d8d75..c2803a235 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 后端 - - 你需要确切的指标名称、span 名称或属性结构来构建仪表板或告警 + - 你想将 OpenClaw 模型使用情况、消息流或会话指标发送到 OpenTelemetry 收集器 + - 你正在将链路追踪、指标或日志接入 Grafana、Datadog、Honeycomb、New Relic、Tempo 或其他 OTLP 后端 + - 你需要确切的指标名称、span 名称或属性结构，才能构建仪表盘或告警 summary: 通过 diagnostics-otel 插件（OTLP/HTTP）将 OpenClaw 诊断数据导出到任意 OpenTelemetry 收集器 title: OpenTelemetry 导出 x-i18n: - generated_at: "2026-04-27T08:31:25Z" - model: gpt-5.4 + generated_at: "2026-05-01T23:18:19Z" + model: gpt-5.5 provider: openai - source_hash: e9d06589d281223ebb57e76f6f19441d30c138b9f7b0636198ab7bae5fad3c8a + source_hash: 6afa805f9212571b325e00badff15d58fdc16be1b60c3f41dc7801e4241ed092 source_path: gateway/opentelemetry.md - workflow: 15 + workflow: 16 --- -OpenClaw 通过内置的 `diagnostics-otel` 插件使用 **OTLP/HTTP（protobuf）** 导出诊断数据。任何接受 OTLP/HTTP 的收集器或后端都可以直接使用，无需修改代码。有关本地文件日志及其读取方式，请参阅[日志记录](/zh-CN/logging)。 +OpenClaw 通过内置的 `diagnostics-otel` 插件使用 **OTLP/HTTP (protobuf)** 导出诊断数据。任何接受 OTLP/HTTP 的收集器或后端都无需代码更改即可工作。关于本地文件日志以及如何读取它们，请参阅 [日志记录](/zh-CN/logging)。 -## 它是如何协同工作的 +## 它如何组合在一起 -- **诊断事件**是由 Gateway 网关和内置插件发出的结构化进程内记录，用于模型运行、消息流、会话、队列和 exec。 -- **`diagnostics-otel` 插件**订阅这些事件，并通过 OTLP/HTTP 将其导出为 OpenTelemetry **指标**、**追踪**和**日志**。 -- 当提供商传输支持自定义请求头时，**提供商调用**会从 OpenClaw 受信任的模型调用 span 上下文接收 W3C `traceparent` 请求头。插件发出的追踪上下文不会传播。 -- 只有当诊断功能面和该插件都启用时，导出器才会附加，因此默认情况下进程内开销几乎为零。 +- **诊断事件** 是由 Gateway 网关和内置插件针对模型运行、消息流、会话、队列和 exec 发出的结构化进程内记录。 +- **`diagnostics-otel` 插件** 订阅这些事件，并通过 OTLP/HTTP 将它们导出为 OpenTelemetry **指标**、**追踪**和**日志**。 +- 当提供商传输层接受自定义标头时，**提供商调用**会从 OpenClaw 受信任的模型调用 span 上下文接收 W3C `traceparent` 标头。插件发出的追踪上下文不会被传播。 +- 只有当诊断界面和插件都启用时，导出器才会附加，因此默认情况下进程内成本接近于零。 ## 快速开始 @@ -50,7 +50,7 @@ OpenClaw 通过内置的 `diagnostics-otel` 插件使用 **OTLP/HTTP（protobuf } ``` -你也可以通过 CLI 启用该插件： +你也可以从 CLI 启用该插件： ```bash openclaw plugins enable diagnostics-otel @@ -62,13 +62,13 @@ openclaw plugins enable diagnostics-otel ## 导出的信号 -| 信号 | 包含内容 | +| 信号 | 其中包含的内容 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| **指标** | 用于令牌使用量、成本、运行时长、消息流、队列通道、会话状态、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 时，三者默认全部开启。 ## 配置参考 @@ -105,38 +105,38 @@ 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` | 当其他预加载项或宿主进程已经注册了全局 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），绝不会包含提示词文本、响应文本、工具输入、工具输出或会话键。 +默认情况下不会导出原始模型/工具内容。Span 携带有界标识符（渠道、提供商、模型、错误类别、仅哈希的请求 ID），绝不包含提示文本、响应文本、工具输入、工具输出或会话键。 -出站模型请求可能包含 W3C `traceparent` 请求头。该请求头仅根据 OpenClaw 自有的活动模型调用诊断追踪上下文生成。现有的调用方提供的 `traceparent` 请求头会被替换，因此插件或自定义提供商选项无法伪造跨服务追踪祖先关系。 +出站模型请求可能包含 W3C `traceparent` 标头。该标头仅从活动模型调用的 OpenClaw 自有诊断追踪上下文生成。现有调用方提供的 `traceparent` 标头会被替换，因此插件或自定义提供商选项无法伪造跨服务追踪祖先关系。 -仅当你的收集器和保留策略已获准存储提示词、响应、工具或系统提示文本时，才将 `diagnostics.otel.captureContent.*` 设为 `true`。每个子键都需要单独显式启用： +仅当你的收集器和保留策略已获准用于提示、响应、工具或系统提示文本时，才将 `diagnostics.otel.captureContent.*` 设置为 `true`。每个子键都单独选择启用： - `inputMessages` — 用户提示内容。 - `outputMessages` — 模型响应内容。 -- `toolInputs` — 工具参数负载。 -- `toolOutputs` — 工具结果负载。 -- `systemPrompt` — 组装后的 system/developer 提示词。 +- `toolInputs` — 工具参数载荷。 +- `toolOutputs` — 工具结果载荷。 +- `systemPrompt` — 组装后的系统/开发者提示。 -当任一子键启用时，模型和工具 span 会仅为该类内容附加有界、已脱敏的 `openclaw.content.*` 属性。 +启用任何子键时，模型和工具 span 仅会为对应类别获得有界、已脱敏的 `openclaw.content.*` 属性。 -## 采样与刷新 +## 采样和刷新 -- **追踪：** `diagnostics.otel.sampleRate`（仅根 span，`0.0` 表示全部丢弃，`1.0` 表示全部保留）。 -- **指标：** `diagnostics.otel.flushIntervalMs`（最小值为 `1000`）。 -- **日志：** OTLP 日志遵循 `logging.level`（文件日志级别）。它们使用诊断日志记录脱敏路径，而不是控制台格式化。对于高流量部署，建议优先使用 OTLP 收集器采样/过滤，而不是本地采样。 -- **文件日志关联：** 当日志调用携带有效的诊断追踪上下文时，JSONL 文件日志会包含顶层的 `traceId`、`spanId`、`parentSpanId` 和 `traceFlags`，这样日志处理器就能将本地日志行与导出的 span 关联起来。 -- **请求关联：** Gateway 网关 HTTP 请求和 WebSocket 帧会创建内部请求追踪作用域。该作用域内的日志和诊断事件默认继承该请求追踪，而 智能体 运行和模型调用 span 会作为其子级创建，因此提供商 `traceparent` 请求头会保留在同一条追踪中。 +- **追踪：** `diagnostics.otel.sampleRate`（仅根 span，`0.0` 丢弃全部，`1.0` 保留全部）。 +- **指标：** `diagnostics.otel.flushIntervalMs`（最小 `1000`）。 +- **日志：** OTLP 日志遵循 `logging.level`（文件日志级别）。它们使用诊断日志记录脱敏路径，而不是控制台格式化。高流量安装应优先使用 OTLP 收集器采样/过滤，而不是本地采样。 +- **文件日志关联：** 当日志调用携带有效的诊断追踪上下文时，JSONL 文件日志会包含顶层 `traceId`、`spanId`、`parentSpanId` 和 `traceFlags`，这让日志处理器可以将本地日志行与导出的 span 关联起来。 +- **请求关联：** Gateway 网关 HTTP 请求和 WebSocket 帧会创建内部请求追踪作用域。该作用域内的日志和诊断事件默认继承请求追踪，而 agent 运行和模型调用 span 会创建为子级，因此提供商 `traceparent` 标头会保留在同一条追踪上。 ## 导出的指标 @@ -147,11 +147,11 @@ openclaw plugins enable diagnostics-otel - `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`） -- `openclaw.model_call.duration_ms`（直方图，属性：`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`，以及在分类错误下的 `openclaw.errorCategory` 和 `openclaw.failureKind`） -- `openclaw.model_call.request_bytes`（直方图，最终模型请求负载的 UTF-8 字节大小；不包含原始负载内容） +- `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`（直方图，最终模型请求载荷的 UTF-8 字节大小；不包含原始载荷内容） - `openclaw.model_call.response_bytes`（直方图，流式模型响应事件的 UTF-8 字节大小；不包含原始响应内容） -- `openclaw.model_call.time_to_first_byte_ms`（直方图，第一个流式响应事件之前的耗时） +- `openclaw.model_call.time_to_first_byte_ms`（直方图，第一个流式响应事件前经过的时间） ### 消息流 @@ -171,13 +171,13 @@ 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`） ### Harness 生命周期 -- `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`） ### Exec @@ -196,16 +196,16 @@ openclaw plugins enable diagnostics-otel - `openclaw.model.usage` - `openclaw.channel`、`openclaw.provider`、`openclaw.model` - `openclaw.tokens.*`（input/output/cache_read/cache_write/total） - - 默认使用 `gen_ai.system`，或者在启用最新 GenAI 语义约定时使用 `gen_ai.provider.name` + - 默认使用 `gen_ai.system`，或者在选择使用最新 GenAI 语义约定时使用 `gen_ai.provider.name` - `gen_ai.request.model`、`gen_ai.operation.name`、`gen_ai.usage.*` - `openclaw.run` - `openclaw.outcome`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`、`openclaw.errorCategory` - `openclaw.model.call` - - 默认使用 `gen_ai.system`，或者在启用最新 GenAI 语义约定时使用 `gen_ai.provider.name` + - 默认使用 `gen_ai.system`，或者在选择使用最新 GenAI 语义约定时使用 `gen_ai.provider.name` - `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`（基于 SHA 的上游提供商请求 ID 有界哈希；不会导出原始 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` @@ -231,15 +231,15 @@ openclaw plugins enable diagnostics-otel - `openclaw.memory.pressure` - `openclaw.memory.level`、`openclaw.memory.heap_used_bytes`、`openclaw.memory.rss_bytes` -当显式启用内容采集时，模型和工具 span 还可以包含你所选择的特定内容类别对应的有界、已脱敏 `openclaw.content.*` 属性。 +显式启用内容捕获后，模型和工具 span 还可以包含有界且已遮盖的 `openclaw.content.*` 属性，用于你选择加入的特定内容类别。 ## 诊断事件目录 -下列事件构成了上面的指标和 span。插件也可以直接订阅这些事件，而无需通过 OTLP 导出。 +以下事件支撑上面的指标和 span。插件也可以直接订阅它们，而无需 OTLP 导出。 -**模型使用情况** +**模型用量** -- `model.usage` — 令牌、成本、持续时间、上下文、提供商/模型/渠道、会话 id。`usage` 是提供商/轮次级别的成本和遥测记账；`context.used` 是当前的提示词/上下文快照，当涉及缓存输入或工具循环调用时，它可能低于提供商的 `usage.total`。 +- `model.usage` — token、成本、时长、上下文、提供商/模型/渠道、会话 ID。`usage` 是提供商/轮次层面的成本与遥测计量；`context.used` 是当前提示词/上下文快照，当涉及缓存输入或工具循环调用时，可能低于提供商的 `usage.total`。 **消息流** @@ -250,21 +250,21 @@ openclaw plugins enable diagnostics-otel **队列和会话** - `queue.lane.enqueue` / `queue.lane.dequeue` -- `session.state` / `session.stuck` -- `run.attempt` -- `diagnostic.heartbeat`（聚合计数器：webhooks/队列/会话） +- `session.state` / `session.long_running` / `session.stalled` / `session.stuck` +- `run.attempt` / `run.progress` +- `diagnostic.heartbeat`（聚合计数器：webhooks/queue/session） **Harness 生命周期** -- `harness.run.started` / `harness.run.completed` / `harness.run.error` — 智能体 harness 的逐次运行生命周期。包含 `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` — agent harness 的每次运行生命周期。包含 `harnessId`、可选的 `pluginId`、提供商/模型/渠道和运行 ID。完成时会添加 `durationMs`、`outcome`、可选的 `resultClassification`、`yieldDetected` 和 `itemLifecycle` 计数。错误会添加 `phase`（`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory` 和可选的 `cleanupFailed`。 **Exec** -- `exec.process.completed` — 最终结果、持续时间、目标、模式、退出码和失败类型。不包含命令文本和工作目录。 +- `exec.process.completed` — 终端结果、时长、目标、模式、退出代码和失败类型。不包含命令文本和工作目录。 -## 没有导出器时 +## 没有导出器 -你可以在不运行 `diagnostics-otel` 的情况下，仍然让诊断事件可供插件或自定义接收端使用： +你可以在不运行 `diagnostics-otel` 的情况下，让诊断事件继续可供插件或自定义接收端使用： ```json5 { @@ -272,7 +272,7 @@ openclaw plugins enable diagnostics-otel } ``` -如果你想获得定向调试输出而不提高 `logging.level`，请使用诊断标记。标记不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）： +如需有针对性的调试输出而不提高 `logging.level`，请使用诊断标志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）： ```json5 { @@ -280,14 +280,14 @@ openclaw plugins enable diagnostics-otel } ``` -或者作为一次性的环境变量覆盖： +也可以作为一次性的环境变量覆盖： ```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)。 ## 禁用 @@ -297,13 +297,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 tail 查看，以及 Control UI 的日志标签页 +- [日志](/zh-CN/logging) — 文件日志、控制台输出、CLI tail，以及 Control UI Logs 标签页 - [Gateway 网关日志内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获 -- [诊断标记](/zh-CN/diagnostics/flags) — 定向调试日志标记 -- [诊断导出](/zh-CN/gateway/diagnostics) — 面向运维人员的支持包工具（与 OTEL 导出分开） +- [诊断标志](/zh-CN/diagnostics/flags) — 有针对性的调试日志标志 +- [诊断导出](/zh-CN/gateway/diagnostics) — 运维支持包工具（独立于 OTEL 导出） - [配置参考](/zh-CN/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 字段参考