OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

环境与调试

诊断标志

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

工作原理

  • 标志是不区分大小写的字符串，由配置中的 diagnostics.flags 与 OPENCLAW_DIAGNOSTICS 环境变量覆盖值合并解析，并进行去重和小写转换。
  • name.* 会匹配 name 本身及 name. 下的所有内容（例如， telegram.* 会匹配 telegram.http）。
  • * 或 all 会启用所有标志。
  • 更改配置中的 diagnostics.flags 后，请重启 Gateway 网关；该设置 不支持热重载。

已知标志

标志 启用的功能
telegram.http Telegram Bot API HTTP 错误日志
brave.http Brave Search 请求/响应/缓存日志
profiler 回复阶段分析器和 Codex app-server 分析器（两者）
reply.profiler 仅回复阶段分析器
codex.profiler 仅 Codex app-server 分析器
timeline 结构化 JSONL 时间线产物（见下文）

通过配置启用

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

多个标志：

json
{  "diagnostics": {    "flags": ["telegram.http", "brave.http", "gateway.*"]  }}

环境变量覆盖（单次）

bash
OPENCLAW_DIAGNOSTICS=telegram.http,brave.http

值以逗号或空白字符分隔。特殊值：

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

OPENCLAW_DIAGNOSTICS=0 会针对该进程禁用来自环境变量和配置的标志， 适合在不编辑文件的情况下，临时关闭配置中仍处于启用状态的分析器标志。

分析器标志

分析器标志控制轻量级计时区间；关闭时不会增加任何开销。

为单次 Gateway 网关运行启用所有受分析器控制的计时区间：

bash
OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run

仅启用回复分派分析器计时区间：

bash
OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

仅启用 Codex app-server 启动/工具/线程分析器计时区间：

bash
OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run

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

也可以在配置中设置：

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

更改配置标志后，请重启 Gateway 网关。要禁用分析器标志， 请从 diagnostics.flags 中移除该标志并重启，或使用 OPENCLAW_DIAGNOSTICS=0 启动进程，以在该次运行中覆盖所有诊断标志。

时间线产物

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

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

也可以在配置中启用：

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

即使标志本身在配置中设置，输出路径也始终来自 OPENCLAW_DIAGNOSTICS_TIMELINE_PATH；没有用于该路径的配置键。 如果仅通过配置启用 timeline，最早的配置加载计时区间将会缺失， 因为 OpenClaw 此时尚未读取配置；后续启动计时区间会正常捕获。

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

时间线中的事件循环延迟样本除 timeline 外还需要额外选择启用： 在启用时间线的基础上，设置 OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 （或 on/true/yes）。

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

日志位置

标志会将日志写入标准诊断日志文件。默认路径为：

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

如果设置了 logging.file，则改用该路径。日志采用 JSONL 格式（每行一个 JSON 对象）。仍会根据 logging.redactSensitive 应用脱敏。 有关完整的日志路径解析、轮转和脱敏模型，请参阅日志。

提取日志

选择最新的日志文件：

bash
ls -t /tmp/openclaw/openclaw-*.log | head -n 1

筛选 Telegram HTTP 诊断日志：

bash
rg "telegram http error" /tmp/openclaw/openclaw-*.log

筛选 Brave Search HTTP 诊断日志：

bash
rg "brave http" /tmp/openclaw/openclaw-*.log

或者在复现问题时持续查看：

bash
tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"

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

注意事项

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

相关内容

Was this useful?
On this page

On this page