跳转至

诊断标志

诊断标志可为某个子系统开启额外日志记录,而无需全局提高 logging.level。除非某个子系统检查该标志,否则标志不生效。

工作原理

  • 标志是大小写不敏感的字符串,从配置中的 diagnostics.flags 以及 OPENCLAW_DIAGNOSTICS 环境变量覆盖中解析而来,并经过去重和转小写处理。
  • name.* 匹配 name 本身以及 name. 之下的任何内容(例如 telegram.* 匹配 telegram.http)。
  • * 或 all 启用所有标志。
  • 修改配置中的 diagnostics.flags 后需要重启网关;它不会热重载。

已知标志

标志 启用项
telegram.http Telegram Bot API HTTP 错误日志记录
brave.http Brave Search 请求/响应/缓存日志记录
profiler 回复阶段 profiler 和 Codex 应用服务器 profiler(两者)
reply.profiler 仅回复阶段 profiler
codex.profiler 仅 Codex 应用服务器 profiler
health 网关健康检查/账户/绑定的调试详情
ingress.timing 会话加载、模型选择和模型目录的计时信息
plugin.load-profile 同步插件模块加载的计时信息
timeline 结构化 JSONL 时间线产物(见下文)

通过配置启用

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

多个标志:

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

环境变量覆盖(一次性)

OPENCLAW_DIAGNOSTICS=telegram.http,brave.http

值按逗号或空白分隔。特殊值:

值 效果
0、false、off、none 禁用所有标志,并同时覆盖配置
1、true、all、* 启用所有标志

OPENCLAW_DIAGNOSTICS=0 会为该进程禁用来自环境变量和配置的所有标志,可用于在不编辑文件的情况下临时屏蔽配置中遗留的 profiler 标志。

Profiler 标志

在未启用 profiler 标志的情况下,缓慢的回复准备过程和 Codex 启动过程会以默认日志级别记录:当某个阶段耗时至少 5 秒或跟踪总耗时至少 10 秒时,会发出警告。快速路径保持静默。Profiler 标志将计时阈值降低为每阶段 500 毫秒、总计 1 秒,并启用额外的详细信息。

为单次网关运行启用所有受 profiler 控制的跨度:

OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run

仅启用回复分发 profiler 跨度:

OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

仅启用 Codex 应用服务器启动/工具/线程 profiler 跨度:

OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run

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

或在配置中设置:

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

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

时间线产物

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 仅通过配置启用时,最早的配置加载跨度会缺失,因为 OpenClaw 此时尚未读取配置;后续的启动跨度会正常捕获。

网关客户端命令从源配置中读取时间线标志,而无需打开共享状态数据库。即使网关离线,这也同样有效。

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

时间线中的事件循环延迟采样需要在 timeline 之外额外选择启用:在启用时间线的基础上,设置 OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1(或 on/true/yes)。

时间线记录使用 openclaw.diagnostics.v1 信封格式,可包含进程 ID、阶段名称、跨度名称、持续时间、插件 ID、依赖项计数、事件循环延迟采样、提供者操作名称、子进程退出状态以及启动错误名称/消息。请将时间线文件视为本地诊断产物;在分享到机器外部之前,请先审阅。

内置模型请求会添加一个 provider.request.started 标记和一条最终的 provider.request 记录,通过运行 ID 和调用/跨度 ID 进行关联。在流式传输过程中,provider.request.activity 使用现有的流进度报告器,每 30 秒最多标记一次观察到的分块样本。最终记录将请求起始时间保留在 timestamp 中,并报告 terminalAtMs(即最后观察到的提供者回调/分块时间,对应 lastProviderActivityAtMs,当观察到时)以及一个有界的 terminalReason。活动包括簿记分块;它并不证明有可见输出,延迟的结果结算不会刷新已观察到的最终分块。未知原因或缺少活动不能作为提供者故障、超时或 CPU 故障的证据。

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

时间线写入会将具有相同目标的相邻事件批量写入一个有界的 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 更改日志目标、级别和脱敏设置。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw