> ## Documentation Index
> Fetch the complete documentation index at: https://claw-tw.jackle.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Logging（日誌）

# 日誌 (Logging)

關於使用者面向的概觀 (CLI + Control UI + Config)，參閱 [/logging](/zh-Hant/logging)。

OpenClaw 有兩個 Log “Surfaces”：

* **Console output** (您在終端機 / Debug UI 看到的)。
* **File logs** (JSON lines) 由 Gateway Logger 寫入。

## File-based Logger

* 預設滾動日誌檔位於 `/tmp/openclaw/` 下 (每天一個檔案)：`openclaw-YYYY-MM-DD.log`
  * 日期使用 Gateway Host 的本地時區。
* Log 檔案路徑與等級可透過 `~/.openclaw/openclaw.json` 設定：
  * `logging.file`
  * `logging.level`

檔案格式為每行一個 JSON 物件。

Control UI 的 Logs 分頁透過 Gateway (`logs.tail`) 追蹤此檔案。CLI 也可以做同樣的事：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw logs --follow
```

**Verbose vs. Log Levels**

* **File logs** 僅由 `logging.level` 控制。
* `--verbose` 僅影響 **Console verbosity** (以及 WS log style)；它 **不會** 同步提高 File Log Level。
* 要在 File Logs 中擷取 verbose-only 細節，將 `logging.level` 設定為 `debug` 或 `trace`。

## Console Capture

CLI 擷取 `console.log/info/warn/error/debug/trace` 並將它們寫入 File Logs，同時仍輸出至 stdout/stderr。

您可以獨立調整 Console Verbosity：

* `logging.consoleLevel` (預設 `info`)
* `logging.consoleStyle` (`pretty` | `compact` | `json`)

## Tool Summary Redaction (工具摘要遮蔽)

詳細的 Tool Summaries (例如 `🛠️ Exec: ...`) 可以在輸出至 Console Stream 之前遮蔽機密 Tokens。這是 **Tools-only** 且不會變更 File Logs。

* `logging.redactSensitive`: `off` | `tools` (預設: `tools`)
* `logging.redactPatterns`: Regex 字串陣列 (覆蓋預設值)
  * 使用原始 Regex 字串 (自動 `gi`)，或若需自訂 Flags 則使用 `/pattern/flags`。
  * 相符項目透過保留前 6 + 後 4 字元 (長度 >= 18) 進行遮蔽，否則為 `***`。
  * 預設值涵蓋常見的 Key Assignments, CLI Flags, JSON Fields, Bearer Headers, PEM Blocks, 以及熱門 Token 前綴。

## Gateway WebSocket Logs

Gateway 以兩種模式印出 WebSocket 協定日誌：

* **Normal mode (無 `--verbose`)**: 僅印出“有趣”的 RPC 結果：
  * 錯誤 (`ok=false`)
  * 慢速呼叫 (預設門檻: `>= 50ms`)
  * 解析錯誤
* **Verbose mode (`--verbose`)**: 印出所有 WS 請求/回應流量。

### WS Log Style

`openclaw gateway` 支援 Per-gateway 的樣式切換：

* `--ws-log auto` (預設): Normal Mode 最佳化；Verbose Mode 使用 Compact Output
* `--ws-log compact`: Verbose 時使用 Compact Output (成對的 Request/Response)
* `--ws-log full`: Verbose 時使用 Full Per-frame Output
* `--compact`: `--ws-log compact` 的別名

範例:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 最佳化 (僅錯誤/慢速)
openclaw gateway

# 顯示所有 WS 流量 (成對)
openclaw gateway --verbose --ws-log compact

# 顯示所有 WS 流量 (完整 Meta)
openclaw gateway --verbose --ws-log full
```

## Console Formatting (Subsystem Logging)

Console Formatter 具 **TTY 感知能力 (TTY-aware)** 並印出一致、帶前綴的行。Subsystem Loggers 讓輸出保持分組且可掃描。

行為:

* 每行皆有 **Subsystem prefixes** (例如 `[gateway]`, `[canvas]`, `[tailscale]`)
* **Subsystem colors** (每個 Subsystem 穩定) 加上 Level Coloring
* **當輸出是 TTY 或環境看起來像 Rich Terminal 時上色** (`TERM`/`COLORTERM`/`TERM_PROGRAM`)，尊重 `NO_COLOR`
* **縮短 Subsystem prefixes**: 丟棄開頭的 `gateway/` + `channels/`，保留最後 2 個區段 (例如 `whatsapp/outbound`)
* **Sub-loggers by subsystem** (自動 Prefix + Structured Field `{ subsystem }`)
* **`logRaw()`** 用於 QR/UX 輸出 (無 Prefix，無 Formatting)
* **Console styles** (例如 `pretty | compact | json`)
* **Console log level** 獨立於 File Log Level (當 `logging.level` 設定為 `debug`/`trace` 時 File 保持完整細節)
* **WhatsApp message bodies** 在 `debug` 等級記錄 (使用 `--verbose` 查看)

這讓既有的 File Logs 保持穩定，同時讓互動式輸出易於掃描。