诊断标志让你针对特定子系统（如 Telegram、Brave Search）开启调试日志，而不影响全局日志级别。在 config.json 的 diagnostics.flags 中配置要启用的标志，或通过环境变量 OPENCLAW_DIAGNOSTICS 临时启用，支持通配符（如 telegram.* 匹配所有 Telegram 相关子系统）。修改后必须重启网关才能生效。注意：如果 logging.level 高于 warn，日志可能被抑制。

OpenClaw 诊断标志：怎么开启特定子系统调试日志

诊断标志（Diagnostics Flags）允许你只为特定子系统输出详细日志，而不必全局开启冗长模式。标志默认不输出任何内容，仅当子系统主动检查到对应标志时才会写入。

工作原理

• 标志是不区分大小写的字符串。
• 可以在配置文件中长期启用，或通过环境变量临时覆盖。
• 支持通配符：
  • telegram.* 会匹配 telegram.http、telegram.payload 等。
  • * 启用所有已定义标志。

怎么通过配置文件启用

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

多个标志：

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

修改配置后必须重启 Gateway：

openclaw gateway restart

怎么通过环境变量临时启用

适合一次性排查，无需修改配置文件：

export OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
openclaw gateway run

禁用所有诊断标志：

export OPENCLAW_DIAGNOSTICS=0

Timeline 时间线输出

timeline 标志会输出结构化的启动和运行时时序事件，供外部 QA 工具使用。通过环境变量启用：

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

也可以在配置中启用：

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

注意：当仅通过配置启用 timeline 时，配置加载之前的最早启动跨度不会输出（因为配置文件尚未读取）。后续的启动跨度正常输出。

OPENCLAW_DIAGNOSTICS=1、OPENCLAW_DIAGNOSTICS=all 或 OPENCLAW_DIAGNOSTICS=* 也会启用 timeline，因为它们会开启所有诊断标志。如果你只想要 JSONL 时序数据，建议明确使用 timeline。

Timeline 记录使用 openclaw.diagnostics.v1 信封格式，可能包含进程 ID、阶段名、跨度名、耗时、插件 ID、依赖数量、事件循环延迟采样、Provider 操作名、子进程退出状态、启动错误名称/消息等。这些文件是本地诊断产物，分享前请检查是否包含敏感信息。

日志输出位置

启用标志后，日志写入标准诊断日志文件。默认路径：

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

如果配置了 logging.file，则写入该路径。日志为 JSONL 格式（每行一个 JSON 对象）。脱敏规则仍由 logging.redactSensitive 控制。

怎么提取与分析日志

# 获取最新的日志文件
ls -t /tmp/openclaw/openclaw-*.log | head -n 1

# 筛选 Telegram HTTP 诊断日志
rg "telegram http error" /tmp/openclaw/openclaw-*.log

# 筛选 Brave HTTP 诊断日志
rg "brave http" /tmp/openclaw/openclaw-*.log

# 实时跟踪当天的日志（在另一个终端复现问题）
tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"

对于远程 Gateway，也可以使用 openclaw logs --follow（参见 /openclaw/cli/logs）。

注意事项

• 如果 logging.level 设置高于 warn（例如 error），诊断日志可能会被抑制。默认 info 不影响。
• brave.http 标志会记录 Brave Search 的请求 URL、查询参数、响应状态/耗时、缓存命中/未命中/写入事件。不会记录 API Key 或响应体，但搜索查询本身可能敏感。
• 诊断标志可以长期保持启用；它们只影响特定子系统的日志量，不会显著增加全局开销。
• 可通过 /openclaw/logging 修改日志目标、级别和脱敏设置。

相关文档

• /openclaw/gateway/diagnostics
• /openclaw/gateway/troubleshooting

常见问题

为什么配置了诊断标志却没有日志输出？

先检查 logging.level 是否高于 warn（日志可能被抑制）。其次确认你是否重启了 Gateway（修改配置后必须重启，环境变量方式不需要重启）。最后确保你的子系统确实检查了该标志，不是所有代码都支持诊断标志。

怎么只开启 Telegram 渠道的调试日志？

在配置文件的 diagnostics.flags 中添加 "telegram.http"，或通过环境变量 OPENCLAW_DIAGNOSTICS=telegram.http。如果需要更详细的载荷日志，可以加 telegram.payload。注意 Telegram 插件本身必须已正确配置。

诊断标志会影响性能吗？

安全，诊断标志只影响你指定的子系统。它们不会全局降低性能，但会额外产生日志写入。对于高频调用（如 Telegram 消息轮询），建议完成排查后关闭。