日志
Gateway 提供完善的日志（Logging）系统，帮助你监控运行状态、诊断问题和审计操作。
日志级别
Gateway 支持五个日志级别（Log Level），从最详细到最精简：
| 级别 | 说明 | 适用场景 |
|---|---|---|
trace | 最详细，包含所有内部调用 | 深度调试 |
debug | 调试信息，包含请求/响应细节 | 开发环境 |
info | 常规运行信息 | 默认 — 日常运维 |
warn | 警告信息，非致命问题 | 生产环境（推荐） |
error | 错误信息，需要关注 | 生产环境（最低限度） |
设置日志级别
bash
# CLI 设置
openclaw config set gateway.logLevel debug
# 环境变量
export OPENCLAW_GATEWAY_LOGLEVEL=debug
# 启动时指定
openclaw gateway --log-level debug动态调整
在 hot 或 hybrid 热加载模式下，修改日志级别无需重启 Gateway。
查看日志
实时日志
bash
# 跟踪实时日志（类似 tail -f）
openclaw logs --follow
# 指定日志级别过滤
openclaw logs --follow --level error
# 指定关键字过滤
openclaw logs --follow --filter "channel"历史日志
bash
# 查看最近 100 行日志
openclaw logs --lines 100
# 按时间范围查看
openclaw logs --since "2025-01-15 10:00" --until "2025-01-15 12:00"
# 按会话 ID 过滤
openclaw logs --filter "sess_abc123"日志输出示例
text
2025-01-15T10:30:00.123Z [INFO] Gateway started on 127.0.0.1:18789
2025-01-15T10:30:00.456Z [INFO] Channel "openai-main" connected
2025-01-15T10:30:01.789Z [INFO] Channel "anthropic" connected
2025-01-15T10:32:15.012Z [INFO] New session: sess_abc123 (device: MacBook)
2025-01-15T10:32:15.345Z [DEBUG] Routing model gpt-4o to channel openai-main
2025-01-15T10:32:16.678Z [DEBUG] Stream response started (sess_abc123)
2025-01-15T10:32:18.901Z [INFO] Request completed: 2.5s, 175 tokens
2025-01-15T10:45:00.000Z [WARN] Channel "anthropic" rate limited, retry in 30s
2025-01-15T11:00:00.000Z [ERROR] Channel "anthropic" connection lost: timeout日志文件位置
| 平台 | 路径 |
|---|---|
| macOS / Linux | ~/.openclaw/logs/gateway.log |
| Windows | %USERPROFILE%\.openclaw\logs\gateway.log |
bash
# 查看日志目录
ls ~/.openclaw/logs/
# 输出:
# gateway.log 当前日志
# gateway.2025-01-14.log 历史日志
# gateway.2025-01-13.log 历史日志日志轮转
Gateway 自动执行日志轮转（Log Rotation），防止日志文件无限增长。
配置
json5
{
"gateway": {
"logging": {
"level": "info",
"rotation": {
"maxSize": "50MB", // 单个文件最大大小
"maxFiles": 10, // 保留的历史文件数
"maxAge": 30, // 保留天数
"compress": true // 压缩历史日志
}
}
}
}手动轮转
bash
# 手动触发日志轮转
openclaw logs rotate自动清理
超过 maxFiles 或 maxAge 的旧日志文件会被自动删除。启用 compress 后，历史日志文件以 .gz 格式压缩存储。
结构化日志
Gateway 支持 JSON 格式的结构化日志（Structured Logging），适合日志分析平台（如 ELK、Loki）消费。
启用 JSON 日志
json5
{
"gateway": {
"logging": {
"format": "json" // "text" (默认) 或 "json"
}
}
}JSON 日志格式
json
{
"timestamp": "2025-01-15T10:30:00.123Z",
"level": "info",
"message": "Request completed",
"sessionId": "sess_abc123",
"channel": "openai-main",
"model": "gpt-4o",
"duration": 2500,
"tokens": {
"prompt": 25,
"completion": 150,
"total": 175
}
}Debug 模式
Debug 模式启用最详细的日志输出，包含完整的请求/响应内容。
bash
# 以 debug 模式启动
openclaw gateway --log-level debug
# 或临时开启 debug
openclaw config set gateway.logLevel debug性能影响
Debug 模式会记录大量信息，包括完整的 API 请求和响应体。切勿在生产环境长期启用，可能导致：
- 日志文件快速膨胀
- I/O 性能下降
- 敏感信息泄露
日志脱敏
Gateway 自动对日志中的敏感信息进行脱敏处理（Redaction）：
text
# 自动脱敏前：
Channel connected with apiKey: sk-proj-abc123def456
# 自动脱敏后：
Channel connected with apiKey: sk-proj-****f456自动脱敏的内容：
- API Key 和 Token
- 密码
- Gateway Token
- 环境变量中的敏感值
集成外部日志系统
输出到 syslog
json5
{
"gateway": {
"logging": {
"outputs": [
{"type": "file", "path": "~/.openclaw/logs/gateway.log"},
{"type": "syslog", "facility": "local0"}
]
}
}
}输出到 stdout（容器部署）
json5
{
"gateway": {
"logging": {
"outputs": [
{"type": "stdout", "format": "json"}
]
}
}
}容器最佳实践
容器部署时，建议日志输出到 stdout，由容器运行时（Docker、Kubernetes）负责日志收集。