> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 診斷旗標

診斷旗標可為單一子系統啟用額外記錄，而不會全域提高
`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`            | 回覆階段分析器與 Codex app-server 分析器（兩者） |
| `reply.profiler`      | 僅限回覆階段分析器                         |
| `codex.profiler`      | 僅限 Codex app-server 分析器           |
| `health`              | 閘道健康狀態探測／帳號／繫結偵錯詳細資料              |
| `ingress.timing`      | 工作階段載入、模型選擇及模型目錄計時                |
| `plugin.load-profile` | 同步外掛模組載入計時                        |
| `timeline`            | 結構化 JSONL 時間軸成品（請見下文）             |

## 透過設定啟用

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}
```

多個旗標：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "diagnostics": {
    "flags": ["telegram.http", "brave.http", "gateway.*"]
  }
}
```

## 環境變數覆寫（單次）

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_DIAGNOSTICS=telegram.http,brave.http
```

值會依逗號或空白分割。特殊值：

| 值                           | 效果             |
| --------------------------- | -------------- |
| `0`, `false`, `off`, `none` | 停用所有旗標，並一併覆寫設定 |
| `1`, `true`, `all`, `*`     | 啟用所有旗標         |

`OPENCLAW_DIAGNOSTICS=0` 會針對該處理程序停用環境變數與設定中的旗標，
適合用來暫時關閉設定中仍啟用的分析器旗標，而不必編輯檔案。

## 分析器旗標

分析器旗標可管控輕量級計時範圍；關閉時不會增加任何負擔。

為單次閘道執行啟用所有受分析器管控的範圍：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run
```

僅啟用回覆分派分析器範圍：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run
```

僅啟用 Codex app-server 啟動／工具／執行緒分析器範圍：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run
```

`profiler` 會同時啟用回覆分析器與 Codex 分析器；若只要啟用其中一個，
請使用具範圍限定的旗標名稱。

或在設定中指定：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "diagnostics": {
    "flags": ["reply.profiler", "codex.profiler"]
  }
}
```

變更設定旗標後，請重新啟動閘道。若要停用分析器旗標，
請將它從 `diagnostics.flags` 中移除並重新啟動，或使用
`OPENCLAW_DIAGNOSTICS=0` 啟動處理程序，以在該次執行中覆寫所有診斷旗標。

## 時間軸成品

`timeline` 旗標（別名：`diagnostics.timeline`）會將結構化的啟動
與執行階段計時事件寫入 JSONL，供外部 QA 測試框架使用：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_DIAGNOSTICS=timeline \
OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \
openclaw gateway run
```

或在設定中啟用：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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
```

具名設定檔使用 `/tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log`；例如，
`--dev` 使用 `openclaw-dev-YYYY-MM-DD.log`。

若設定了 `logging.file`，則改用該路徑。記錄採 JSONL 格式（每行一個 JSON
物件）。資料遮蔽仍會依據 `logging.redactSensitive` 套用。
如需完整的記錄檔路徑解析、輪替與資料遮蔽模型，請參閱[記錄](/zh-TW/logging)。

## 擷取記錄

讀取作用中設定檔的最新記錄檔：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw logs --plain
# 具名設定檔範例：
openclaw --profile work logs --plain
```

篩選 Telegram HTTP 診斷資訊：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw logs --plain --limit 5000 | rg "telegram http error"
```

篩選 Brave Search HTTP 診斷資訊：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw logs --plain --limit 5000 | rg "brave http"
```

或在重現問題時持續追蹤：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw logs --follow --plain | rg "telegram http error"
```

對於遠端閘道，請改用 `openclaw logs --follow`（請參閱
[/cli/logs](/zh-TW/cli/logs)）。

## 注意事項

* 如果 `logging.level` 設定得高於 `warn`，受旗標管控的記錄可能會
  遭到抑制。預設的 `info` 即可。
* `brave.http` 會記錄 Brave Search 請求 URL／查詢參數、回應
  狀態／計時，以及快取命中／未命中／寫入事件。它不會記錄 API 金鑰
  （透過請求標頭傳送）或回應本文，但搜尋查詢可能包含敏感資訊。
* 旗標可安全地保持啟用；它們只會影響特定子系統的
  記錄量。
* 使用 [/logging](/zh-TW/logging) 變更記錄目的地、層級與資料遮蔽設定。

## 相關內容

* [閘道診斷](/zh-TW/gateway/diagnostics)
* [閘道疑難排解](/zh-TW/gateway/troubleshooting)