跳轉到主要內容
診斷旗標會為單一子系統開啟額外記錄，而不會全域提高 logging.level。除非子系統檢查該旗標，否則旗標不會產生效果。

​
運作方式

  • 旗標是不區分大小寫的字串，會從設定中的 diagnostics.flags 加上 OPENCLAW_DIAGNOSTICS 環境覆寫解析，去除重複並轉為小寫。
  • name.* 會匹配 name 本身以及 name. 底下的任何項目（例如 telegram.* 會匹配 telegram.http）。
  • * 或 all 會啟用所有旗標。
  • 在設定中變更 diagnostics.flags 後，請重新啟動閘道；它不會 熱重新載入。

​
已知旗標

旗標啟用項目
telegram.httpTelegram Bot API HTTP 錯誤記錄
brave.httpBrave Search 請求/回應/快取記錄
profiler回覆階段分析器與 Codex 應用程式伺服器分析器（兩者）
reply.profiler僅回覆階段分析器
codex.profiler僅 Codex 應用程式伺服器分析器
timeline結構化 JSONL 時間軸成品（見下方）

​
透過設定啟用

{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}
多個旗標： 
{
  "diagnostics": {
    "flags": ["telegram.http", "brave.http", "gateway.*"]
  }
}

​
環境覆寫（一次性）

OPENCLAW_DIAGNOSTICS=telegram.http,brave.http
值會以逗號或空白分割。特殊值：
值效果
0, false, off, none停用所有旗標，也會覆寫設定
1, true, all, *啟用所有旗標
OPENCLAW_DIAGNOSTICS=0 會停用該程序中來自環境與設定的旗標，適合用來 暫時靜音設定中遺留開啟的分析器旗標，而不必編輯檔案。

​
分析器旗標

分析器旗標會控管輕量時間跨度；關閉時不會增加額外負擔。 為一次閘道執行啟用所有受分析器控管的跨度： 
OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run
僅啟用回覆派送分析器跨度： 
OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run
僅啟用 Codex 應用程式伺服器啟動/工具/執行緒分析器跨度： 
OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run
profiler 會同時啟用回覆分析器與 Codex 分析器；若只要啟用其中一個， 請使用具範圍的旗標名稱。 或在設定中設定： 
{
  "diagnostics": {
    "flags": ["reply.profiler", "codex.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，即使旗標本身是在 設定中設定；路徑沒有對應的設定鍵。當 timeline 只從設定啟用時，最早的 設定載入跨度會遺失，因為 OpenClaw 尚未讀取設定；後續啟動跨度會正常擷取。 OPENCLAW_DIAGNOSTICS=1、=all 和 =* 也會啟用時間軸，因為它們會啟用 所有旗標。若你只想要 JSONL 成品，而不是所有其他診斷旗標，請優先使用 具範圍的 timeline 旗標。 時間軸中的事件迴圈延遲樣本需要在 timeline 之外再額外選擇啟用： 在啟用時間軸的同時設定 OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 （或 on/true/yes）。 時間軸記錄使用 openclaw.diagnostics.v1 封套，並可包含程序 ID、階段名稱、 跨度名稱、持續時間、外掛 ID、相依項目數量、事件迴圈延遲樣本、供應者操作名稱、 子程序結束狀態，以及啟動錯誤名稱/訊息。請將時間軸檔案視為本機診斷成品； 在分享至你的機器之外前先審查。

​
記錄位置

旗標會將記錄送到標準診斷記錄檔。預設為： 
/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 Search HTTP 診斷： 
rg "brave http" /tmp/openclaw/openclaw-*.log
或在重現時追蹤： 
tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"
對於遠端閘道，請改用 openclaw logs --follow（見 /cli/logs）。

​
注意事項

  • 如果 logging.level 設得高於 warn，受旗標控管的記錄可能會被 抑制。預設的 info 沒問題。
  • brave.http 會記錄 Brave Search 請求 URL/查詢參數、回應 狀態/計時，以及快取命中/未命中/寫入事件。它不會記錄 API 金鑰 （以請求標頭送出）或回應主體，但搜尋查詢可能具有敏感性。
  • 旗標可以安全地保持啟用；它們只會影響特定子系統的記錄量。
  • 使用 /logging 變更記錄目的地、層級與遮蔽。

​
相關