每日备份 2026-06-10 12:57:13

doc/LOGGING_GUIDE.md

@@ -0,0 +1,146 @@
+# OpenClaw 日志配置指南
+
+## 日志位置
+
+### 默认日志文件
+
+```
+/tmp/openclaw/openclaw-YYYY-MM-DD.log
+```
+
+### 自定义日志路径
+
+```json5
+{
+  "logging": {
+    "file": "/path/to/openclaw.log"
+  }
+}
+```
+
+## 日志级别
+
+### 配置日志级别
+
+```json5
+{
+  "logging": {
+    "level": "info",           // 文件日志级别
+    "consoleLevel": "info",   // 控制台日志级别
+    "consoleStyle": "pretty"  // 控制台样式
+  }
+}
+```
+
+### 日志级别顺序
+
+```
+trace > debug > info > warn > error
+```
+
+| 级别 | 说明 | 用途 |
+|------|------|------|
+| `trace` | 最详细 | 调试时使用 |
+| `debug` | 调试信息 | 开发调试 |
+| `info` | 默认 | 一般运行 |
+| `warn` | 警告 | 潜在问题 |
+| `error` | 错误 | 错误信息 |
+
+## 查看日志
+
+### 实时日志
+
+```bash
+openclaw logs --follow           # 实时跟踪
+openclaw logs --since 1h        # 最近 1 小时
+openclaw logs --limit 200       # 最近 200 行
+```
+
+### 日志格式
+
+```bash
+openclaw logs --json            # JSON 格式
+openclaw logs --plain          # 纯文本
+openclaw logs --no-color       # 无颜色
+```
+
+### 过滤日志
+
+```bash
+# 过滤错误
+openclaw logs | grep -i error
+
+# 过滤特定通道
+openclaw channels logs --channel whatsapp
+```
+
+## 控制台样式
+
+```json5
+{
+  "logging": {
+    "consoleStyle": "pretty"   // 人类友好，有颜色
+    "consoleStyle": "compact"  // 紧凑输出
+    "consoleStyle": "json"     // JSON 格式
+  }
+}
+```
+
+## 敏感信息脱敏
+
+### 基础配置
+
+```json5
+{
+  "logging": {
+    "redactSensitive": "tools",   // 仅工具输出脱敏
+    "redactSensitive": "off"      // 关闭脱敏
+  }
+}
+```
+
+### 自定义脱敏规则
+
+```json5
+{
+  "logging": {
+    "redactPatterns": [
+      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
+      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi",
+      "\\bAPI_KEY\\b.*"
+    ]
+  }
+}
+```
+
+## 诊断标志 (Diagnostics Flags)
+
+用于在不改变日志级别的情况下开启特定调试日志：
+
+```json5
+{
+  "diagnostics": {
+    "flags": ["telegram.http", "whatsapp.connection"]
+  }
+}
+```
+
+### 环境变量临时启用
+
+```bash
+OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
+```
+
+## 日志位置速查
+
+| 类型 | 位置 |
+|------|------|
+| Gateway 文件日志 | `/tmp/openclaw/openclaw-YYYY-MM-DD.log` |
+| macOS 服务日志 | `~/.openclaw/logs/gateway.log` |
+| Linux 服务日志 | `journalctl --user -u openclaw-gateway.service` |
+| 会话文件 | `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/` |
+| 媒体缓存 | `$OPENCLAW_STATE_DIR/media/` |
+
+---
+
+*最后更新: 2026-02-04*