诊断标志

诊断标志会为单个子系统开启额外日志，而不会全局提高 logging.level。除非某个子系统检查该标志，否则标志不会生效。

How it works¶

• 标志是不区分大小写的字符串，从配置中的 diagnostics.flags 以及 OPENCLAW_DIAGNOSTICS 环境变量覆盖项中解析，并去重、转为小写。
• name.* 匹配 name 本身以及 name. 下的所有内容（例如 telegram.* 匹配 telegram.http）。
• * 或 all 启用所有标志。
• 在配置中修改 diagnostics.flags 后，请重启 gateway；它不会热加载。

Known flags¶

Enable via config¶

{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}

多个标志：

{
  "diagnostics": {
    "flags": ["telegram.http", "brave.http", "health"]
  }
}

Env override (one-off)¶

OPENCLAW_DIAGNOSTICS=telegram.http,brave.http

值按逗号或空白拆分。特殊值：

OPENCLAW_DIAGNOSTICS=0 会禁用该进程来自环境变量和配置的所有标志，适用于在 不编辑文件的情况下，临时静默配置中遗留开启的 profiler 标志。

Profiler flags¶

在没有 profiler 标志时，缓慢的回复准备和 Codex 启动会在默认日志级别记录： 某个阶段耗时至少 5 秒，或受跟踪的总耗时至少 10 秒，会发出警告。快速路径保持 安静。Profiler 标志会将计时阈值降低到每个阶段 500 毫秒、总计 1 秒，并启用 更多细节。

为一次 gateway 运行启用所有由 profiler 控制的 span：

OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run

仅启用回复分发 profiler span：

OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

仅启用 Codex app-server 启动/工具/线程 profiler span：

OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run

profiler 会同时启用回复 profiler 和 Codex profiler；如需只启用其中一个， 请使用限定范围的标志名称。

或在配置中设置：

{
  "diagnostics": {
    "flags": ["reply.profiler", "codex.profiler"]
  }
}

修改配置标志后，请重启 gateway。要禁用某个 profiler 标志，请将其从 diagnostics.flags 中移除并重启，或者以 OPENCLAW_DIAGNOSTICS=0 启动进程， 以覆盖该次运行的所有诊断标志。

Timeline artifacts¶

timeline 标志（别名：diagnostics.timeline）会将结构化的启动和运行时计时 事件写入 JSONL，供外部 QA 测试框架使用：

OPENCLAW_DIAGNOSTICS=timeline \
OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \
openclaw gateway run

或在配置中启用：

{
  "diagnostics": {
    "flags": ["timeline"]
  }
}

输出路径始终来自 OPENCLAW_DIAGNOSTICS_TIMELINE_PATH，即使标志本身在配置中 设置；没有用于路径的配置键。有关 OpenClaw 从哪里读取 OPENCLAW_DIAGNOSTICS、OPENCLAW_DIAGNOSTICS_TIMELINE_PATH 和 OPENCLAW_DIAGNOSTICS_EVENT_LOOP，以及优先级顺序，请参阅 环境变量。 当 timeline 仅从配置启用时，最早的配置加载 span 会缺失，因为 OpenClaw 尚未 读取配置；后续启动 span 会正常捕获。

Gateway 客户端命令会从源配置读取 timeline 标志，而无需打开共享状态数据库。 当 Gateway 离线时，这也有效。

OPENCLAW_DIAGNOSTICS=1、=all 和 =* 也会启用 timeline，因为它们会启用 所有标志。如果你只需要 JSONL 产物而不需要其他所有诊断标志，请优先使用限定 范围的 timeline 标志。

时间线中的事件循环延迟采样需要在 timeline 之外再额外开启一项：在启用 timeline 的基础上，设置 OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1（或 on/true/yes）。

时间线记录使用 openclaw.diagnostics.v1 信封，并可包含进程 ID、阶段名称、 span 名称、持续时间、插件 ID、依赖数量、事件循环延迟采样、provider 操作名称、 子进程退出状态，以及启动错误名称/消息。请将时间线文件视为本地诊断产物；在 将其分享到机器之外之前，请先审查。

嵌入式模型请求会添加一个 provider.request.started 标记和一个终结 provider.request 记录，并通过 run 和 call/span ID 进行关联。在流式传输期间， provider.request.activity 标记会使用现有的流进度报告器，对已观察到的 chunk 进行采样标记，最多每 30 秒一次。终结记录会在 timestamp 中保留请求开始时间，并 报告 terminalAtMs、最后观察到的 provider 回调/chunk 时间（如果观察到，则为 lastProviderActivityAtMs），以及有界的 terminalReason。Activity 包含簿记 chunk；它不能证明可见输出，延迟的结果结算也不会刷新已经观察到的终结 chunk。 未知原因或缺失的 activity 不是 provider、超时或 CPU 故障的证据。

model.recovery.decision 标记会报告现有尝试所有者已接受或已拒绝的恢复分支，以及重放安全性和先前工具结算布尔值。model.retry.decision 标记会解释重试所有者的预算、延迟和等待结果。这些标记不会添加提示词、工具参数、原始错误文本、模型路由或会话标识。它们不会更改重试或超时策略，并且仅通过现有可选时间线发出。

时间线写入会将具有相同目标的相邻事件批量写入有界的 64 KiB 缓冲区，并在下一个事件循环轮次、达到容量或进程正常退出时刷新。事件时间戳反映发出时间。写入仍为尽力而为；强制终止可能导致待处理输出丢失。外部测试框架应在进程退出后读取最终产物，并且不得在进程运行期间截断该产物。

日志存放位置¶

标志会将日志输出到标准诊断日志文件。默认情况下：

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

命名配置文件使用 /tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log；例如，--dev 使用 openclaw-dev-YYYY-MM-DD.log。

如果设置了 logging.file，则改用该路径。日志为 JSONL（每行一个 JSON 对象）。脱敏仍然适用；它始终开启。 有关完整的日志路径解析、轮转和脱敏模型，请参阅 日志。

提取日志¶

读取当前配置文件的最新日志文件：

openclaw logs --plain
# Named profile example:
openclaw --profile work logs --plain

筛选 Telegram HTTP 诊断信息：

openclaw logs --plain --limit 5000 | rg "telegram http error"

筛选 Brave Search HTTP 诊断信息：

openclaw logs --plain --limit 5000 | rg "brave http"

或在复现时跟踪：

openclaw logs --follow --plain | rg "telegram http error"

对于远程网关，请改用 openclaw logs --follow（参见 /cli/logs）。

说明¶

• 如果将 logging.level 设置为 error、fatal 或 silent，由标志控制的日志 可能会被抑制。默认 info 即可。
• brave.http 会记录 Brave Search 请求 URL/查询参数、响应 状态/耗时以及缓存命中/未命中/写入事件。它不会记录 API 密钥 （作为请求头发送）或响应正文，但搜索查询可能敏感。
• 标志可以保持启用；它们只影响特定子系统的 日志量。
• 使用 /logging 更改日志目标、级别和脱敏。

相关¶

• 网关诊断
• 网关故障排查