概念

當 OpenClaw 出問題時，logging 是你的朋友。了解 log 結構和 debug 工具，可以快速定位問題。

核心檔案

src/logging/
├── logger.ts              # 主要 logger
├── subsystem.ts           # 子系統 logger
├── formats.ts             # Log 格式化
└── levels.ts              # Log levels

~/.openclaw/logs/          # Log 檔案
├── gateway.log            # Gateway logs
├── error.log              # Error logs
└── debug.log              # Debug logs (verbose)

Log Levels

檔案：src/logging/levels.ts

export type LogLevel = 
  | "error"    // 錯誤，需要注意
  | "warn"     // 警告，可能有問題
  | "info"     // 一般資訊
  | "debug"    // Debug 資訊
  | "trace";   // 詳細追蹤

export const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
  error: 0,
  warn: 1,
  info: 2,
  debug: 3,
  trace: 4,
};

Subsystem Logger

檔案：src/logging/subsystem.ts

每個子系統有自己的 logger：

export function createSubsystemLogger(subsystem: string): SubsystemLogger {
  return {
    error: (msg, meta?) => log("error", subsystem, msg, meta),
    warn: (msg, meta?) => log("warn", subsystem, msg, meta),
    info: (msg, meta?) => log("info", subsystem, msg, meta),
    debug: (msg, meta?) => log("debug", subsystem, msg, meta),
    trace: (msg, meta?) => log("trace", subsystem, msg, meta),
  };
}

// 使用範例
const log = createSubsystemLogger("session-init");
log.info("Session started", { sessionId, agentId });
log.error("Failed to load session", { error: err.message });

Log 格式

檔案：src/logging/formats.ts

export function formatLogEntry(entry: LogEntry): string {
  const timestamp = new Date(entry.timestamp).toISOString();
  const level = entry.level.toUpperCase().padEnd(5);
  const subsystem = entry.subsystem.padEnd(15);
  
  let line = `${timestamp} [${level}] [${subsystem}] ${entry.message}`;
  
  if (entry.meta && Object.keys(entry.meta).length > 0) {
    line += ` ${JSON.stringify(entry.meta)}`;
  }
  
  return line;
}

// 輸出範例：
// 2026-03-09T07:15:00.000Z [INFO ] [session-init   ] Session started {"sessionId":"abc","agentId":"my-assistant"}

設定

// openclaw.json
{
  "logging": {
    "level": "info",           // 預設 level
    "console": {
      "enabled": true,
      "level": "info"
    },
    "file": {
      "enabled": true,
      "path": "~/.openclaw/logs",
      "level": "debug",        // 檔案可以更詳細
      "maxSize": "10MB",
      "maxFiles": 5
    },
    "subsystems": {
      "session-init": "debug", // 特定子系統更詳細
      "tool-exec": "trace"
    }
  }
}

Debug 工具

1. Gateway Status

openclaw gateway status

顯示：

Gateway 是否運行
連接的 channels
活躍的 sessions

2. Session Inspect

openclaw session inspect <sessionKey>

顯示：

Session metadata
對話歷史
Token 使用量

3. Log Tail

# 即時看 logs
tail -f ~/.openclaw/logs/gateway.log

# 只看 errors
tail -f ~/.openclaw/logs/error.log

# 搜尋特定內容
grep "session-init" ~/.openclaw/logs/gateway.log

常見 Debug 情境

Session 沒回應

# 1. 檢查 gateway 狀態
openclaw gateway status

# 2. 看最近的 logs
tail -50 ~/.openclaw/logs/gateway.log

# 3. 找 error
grep -i error ~/.openclaw/logs/gateway.log | tail -20

Tool 執行失敗

# 設定 tool-exec 為 trace
# 在 openclaw.json:
# "logging": { "subsystems": { "tool-exec": "trace" } }

# 重啟 gateway
openclaw gateway restart

# 看詳細 log
grep "tool-exec" ~/.openclaw/logs/debug.log

Memory Search 沒結果

# 檢查 memory index 狀態
openclaw memory status

# 看 embedding logs
grep "memory" ~/.openclaw/logs/gateway.log | tail -20

Verbose Mode

透過 /verbose 指令開啟 verbose mode，會在回覆中顯示：

使用的 model
Token 使用量
執行時間

/verbose on

💡 關鍵洞察

Subsystem 幫助定位
- 每個子系統有標籤
- 快速過濾相關 logs
Level 分層
- Production 用 info
- Debug 時用 debug 或 trace
檔案 log 可以更詳細
- Console 用 info
- 檔案用 debug
- 方便事後查看
CLI 工具方便
- openclaw gateway status
- openclaw session inspect

🔗 核心檔案

功能	檔案
Logger	`src/logging/logger.ts`
Subsystem	`src/logging/subsystem.ts`
格式化	`src/logging/formats.ts`
Levels	`src/logging/levels.ts`

Day 17: Logging 與 Debug