调试指南

本页介绍 OpenClaw 的调试方法和诊断工具，帮助你定位和解决运行过程中遇到的问题。

日志查看

基本日志命令

# 查看最近的日志
openclaw logs

# 实时跟踪日志输出（推荐排查问题时使用）
openclaw logs --follow

# 过滤特定频道的日志
openclaw logs --channel telegram

# 过滤特定日志级别
openclaw logs --level error

日志级别

OpenClaw 使用以下日志级别（从低到高）：

级别	说明	使用场景
debug	详细调试信息	开发调试
info	常规运行信息	日常监控
warn	警告信息	需要关注的异常
error	错误信息	功能异常

日志文件位置

日志文件默认保存在 OpenClaw 数据目录下：

~/.openclaw/logs/
├── gateway.log        # 网关主日志
├── channels/          # 各频道日志
│   ├── telegram.log
│   └── discord.log
└── cron.log           # 定时任务日志

日志文件过大？

长时间运行后日志文件可能占用较多磁盘空间。OpenClaw 会自动轮转日志，但你也可以手动清理旧日志文件。

Debug 模式

当普通日志无法定位问题时，可以启用 Debug 模式获取更详细的输出。

启用方式

# 方式一：通过环境变量启用（推荐）
DEBUG=openclaw:* openclaw gateway start

# 方式二：只调试特定模块
DEBUG=openclaw:gateway openclaw gateway start
DEBUG=openclaw:channels openclaw gateway start
DEBUG=openclaw:models openclaw gateway start

# 方式三：通过配置启用
openclaw config set log.level debug
openclaw gateway restart

Debug 模式会输出大量信息

Debug 模式下日志量会显著增加，包括每次 API 请求的详细内容。排查完问题后记得关闭：

openclaw config set log.level info
openclaw gateway restart

Gateway 诊断

openclaw doctor 深度诊断

openclaw doctor 是内置的全面诊断工具，它会依次检查：

openclaw doctor

检查项目包括：

1. 环境检查：Node.js 版本、npm 版本、操作系统兼容性
2. 配置检查：openclaw.json 语法、必填字段、值格式
3. 网关检查：进程状态、端口占用、内存使用
4. API 检查：各模型提供商的 API Key 有效性和连通性
5. 频道检查：各频道 Token 有效性和连接状态
6. 磁盘检查：日志和缓存占用的磁盘空间

每个检查项会显示 ✓（通过）、!（警告）或 ✗（失败），失败项会附带修复建议。

状态检查

# 快速状态检查
openclaw status

# 深度健康检查（包含 API 连通性测试）
openclaw status --deep

openclaw status 输出示例：

OpenClaw v3.8.2
Gateway:    running (PID 12345, uptime 2d 3h)
Channels:   telegram (connected), discord (connected)
Models:     claude-sonnet-4-20250514 (default)
Cron jobs:  3 active

openclaw status --deep 会额外测试每个模型 API 的响应时间和可用性。

配置验证

检查配置文件

OpenClaw 的配置文件为项目目录下的 openclaw.json 或全局 ~/.openclaw/config.json。

# 查看当前生效的完整配置
openclaw config list

# 查看特定配置项
openclaw config get models.default
openclaw config get tools.profile
openclaw config get channels

# 验证配置文件语法
openclaw doctor  # 会包含配置文件检查

常见配置错误

• JSON 语法错误：多余的逗号、缺少引号等
• API Key 格式错误：Key 前后有空格或换行
• 频道 Token 过期：需要重新生成
• 模型名称拼写错误：使用 openclaw models list 查看支持的模型列表

常用调试命令速查表

命令	说明
openclaw status	查看网关运行状态
openclaw status --deep	深度健康检查（含 API 连通性测试）
openclaw doctor	全面系统诊断，自动给出修复建议
openclaw logs --follow	实时查看日志输出
openclaw logs --level error	只查看错误日志
openclaw channels status	查看所有频道的连接状态
openclaw cron list	查看已注册的定时任务
openclaw config get <key>	查看特定配置项的值
openclaw config list	查看完整配置
openclaw skills list	查看已安装的技能列表
openclaw models list	查看可用的模型列表
openclaw gateway restart	重启网关

卸载与重装

当问题无法修复时，可以考虑卸载后重新安装。

交互式卸载

openclaw uninstall

会依次询问你是否删除配置文件、日志、缓存等数据。

非交互式完全卸载

openclaw uninstall --all --yes

跳过所有确认提示，删除 OpenClaw 及其全部数据。

手动完全清理

如果 openclaw uninstall 命令无法正常运行，可以手动清理：

# 1. 停止网关
openclaw gateway stop

# 2. 卸载系统服务（如果注册了开机自启）
openclaw service uninstall

# 3. 删除 OpenClaw 数据目录
rm -rf ~/.openclaw

# 4. 卸载 npm 全局包
npm rm -g openclaw

手动删除前请备份

~/.openclaw 目录包含你的所有配置和日志。如果需要保留配置，先备份 ~/.openclaw/config.json。

重新安装

npm install -g openclaw@latest
openclaw onboard