调试指南
本指南帮助你通过日志分析和调试工具深入排查 OpenClaw 运行中的各类问题。
日志级别（Log Levels）
OpenClaw 支持以下五个日志级别，从详细到精简依次为：
| 级别 | 说明 | 使用场景 |
|---|---|---|
trace | 最详细的追踪信息 | 开发调试、追踪数据流 |
debug | 调试信息，含请求/响应详情 | 排查具体功能异常 |
info | 常规运行信息（默认级别） | 日常监控 |
warn | 警告信息，不影响运行 | 关注潜在问题 |
error | 错误信息，功能受损 | 故障排查 |
查看日志
实时查看
bash
# 实时跟踪所有日志
openclaw logs --follow
# 仅显示特定级别及以上的日志
openclaw logs --follow --level debug
# 过滤特定模块的日志
openclaw logs --follow --module gateway
openclaw logs --follow --module agent
openclaw logs --follow --module channel历史日志查询
bash
# 查看最近 100 条日志
openclaw logs --tail 100
# 按时间范围查询
openclaw logs --since "2026-03-01" --until "2026-03-05"
# 搜索包含特定关键词的日志
openclaw logs --search "connection timeout"日志文件位置
日志存储路径
默认日志路径因安装方式不同而有所区别。
bash
# 默认日志目录
~/.openclaw/logs/
# 主日志文件
~/.openclaw/logs/openclaw.log
# 错误日志
~/.openclaw/logs/error.logbash
# 容器内路径
/app/logs/
# 通过 Docker 查看
docker logs openclaw --tail 100 --follow
# 导出日志到宿主机
docker cp openclaw:/app/logs/ ./openclaw-logs/常见日志模式解读
正常启动日志
log
[INFO] Gateway started on port 7681
[INFO] Model provider "deepseek" connected successfully
[INFO] Channel "wecom" authenticated and listening
[INFO] Automation scheduler initialized with 3 tasks模型连接失败
log
[ERROR] Model provider "openai" connection failed: 401 Unauthorized
[WARN] Falling back to secondary model provider "deepseek"解决方案：检查 API Key 是否正确，确认账户余额充足。
通道认证失败
log
[ERROR] Channel "telegram" auth failed: 403 Forbidden - bot token invalid解决方案：重新生成 Bot Token（机器人令牌）并更新配置。
上下文溢出
log
[WARN] Context overflow: 132000 tokens exceeds model limit 128000
[INFO] Auto-truncating context to fit model window解决方案：启用自动上下文裁剪，或切换到更大上下文窗口（Context Window）的模型。
调试模型问题
启用请求/响应的完整日志记录：
bash
# 临时开启模型调试模式
openclaw config set models.debug true
# 查看完整的 API 请求和响应
openclaw logs --follow --level trace --module model注意
模型调试模式会记录完整的请求和响应内容，可能包含敏感信息。排查完毕后请及时关闭：openclaw config set models.debug false
bash
# 测试特定模型的连接和响应
openclaw models test --provider deepseek --verbose
# 查看模型请求耗时统计
openclaw models stats --last 1h调试通道问题
消息流追踪（Message Flow Tracing）
bash
# 开启通道消息追踪
openclaw channels debug --name wecom --trace
# 查看消息处理流水线
openclaw logs --follow --module channel --level trace消息处理流程为：
收到消息 → 通道适配器解析 → Agent 处理 → 模型调用 → 响应格式化 → 通道发送每个环节的耗时和状态都会记录在 trace 级别日志中。
通道连接诊断
bash
# 检查所有通道连接状态
openclaw channels status --verbose
# 探测特定通道的网络连通性
openclaw channels status --probe --name telegram调试自动化任务
Cron 任务调试
bash
# 查看所有定时任务及下次执行时间
openclaw automation list --verbose
# 手动触发一个 cron 任务进行调试
openclaw automation trigger --name "daily-report" --dry-run
# 查看自动化执行历史
openclaw automation history --last 10Webhook（钩子）调试
bash
# 查看 webhook 接收记录
openclaw logs --follow --module webhook --level debug
# 模拟发送 webhook 请求进行测试
curl -X POST http://localhost:7681/api/hooks/test \
-H "Content-Type: application/json" \
-d '{"event": "test", "payload": {"message": "debug"}}'性能分析（Performance Profiling）
bash
# 生成性能分析报告
openclaw doctor --profile --duration 60
# 查看实时资源使用
openclaw status --watch
# 导出性能指标到文件
openclaw metrics export --format json --output metrics.json性能基准参考
- 模型响应（首 Token）：< 2 秒为正常
- 消息端到端延迟：< 5 秒为正常
- 内存占用（空载）：< 200MB 为正常
- CPU 使用率（空载）：< 5% 为正常
远程调试
如果需要在远程服务器上调试：
bash
# 导出完整诊断包（包含脱敏后的配置和最近日志）
openclaw doctor --export --output /tmp/debug-bundle.tar.gz
# 通过 SSH 端口转发访问远程控制台
ssh -L 7681:localhost:7681 user@your-server
# 远程实时日志
ssh user@your-server "openclaw logs --follow"安全提醒
导出的诊断包默认会脱敏处理 API Key 等敏感信息，但仍建议在分享前人工复查，确保不含任何密钥和个人数据。