1
确认问题现象
明确问题的具体表现，收集错误信息和复现步骤
- 记录错误消息
- 截图问题现象
- 确定复现步骤
- 评估影响范围
Diagnostics
诊断与排障
工具排障最忌讳的是一出问题就重新安装。更高效的方法，是先判断问题出在层级、配置、权限、运行环境还是版本变化，然后针对性解决。
Process
诊断流程
按照这个流程系统性地定位和解决问题。
2
定位问题层级
判断问题属于哪个层级：插件、配置、权限、环境
- 检查是否已安装
- 检查是否已启用
- 检查配置是否正确
- 检查环境是否满足
3
收集诊断信息
使用诊断工具收集系统状态和日志
- 运行诊断命令
- 查看日志文件
- 检查系统状态
- 收集环境信息
4
分析根因
根据收集的信息分析问题根本原因
- 对比正常状态
- 检查变更历史
- 分析错误模式
- 查阅已知问题
5
实施修复
根据分析结果实施修复方案
- 备份当前状态
- 应用修复方案
- 验证修复效果
- 记录解决方案
Commands
诊断命令参考
掌握这些命令，快速收集诊断信息。
openclaw doctor运行系统诊断，检查常见问题Running OpenClaw diagnostics...
✓ Configuration file exists
✓ Gateway is running
✓ Database connection OK
⚠ Plugin 'telegram' not enabled
✗ Missing environment variable: OPENAI_API_KEY
Summary: 3 passed, 1 warning, 1 erroropenclaw status查看系统运行状态OpenClaw Status
─────────────────────────────────
Version: 1.2.3
Uptime: 2d 4h 32m
Gateway: Running (port 3000)
Agents: 2 active
Channels: 3 connected
Memory: 256MB / 1GB
CPU: 2.3%openclaw logs [type]查看系统日志# 查看所有日志
openclaw logs
# 查看错误日志
openclaw logs --level error
# 实时查看日志
openclaw logs --follow
# 查看特定组件日志
openclaw logs --component gatewayopenclaw config show显示当前配置Current Configuration
─────────────────────────────────
Gateway:
Host: 0.0.0.0
Port: 3000
Auth: enabled
Agents:
Default: assistant
Model: claude-3-sonnet
Channels:
telegram: enabled
discord: disabledopenclaw plugins list列出已安装插件Installed Plugins
─────────────────────────────────
telegram v1.2.3 enabled
chroma v0.8.1 enabled
whisper v1.0.0 disabledopenclaw health健康检查Health Check Results
─────────────────────────────────
✓ Gateway responding
✓ Database healthy
✓ Memory usage normal
✓ All channels connected
✓ No pending errorsCommon Issues
常见问题分类
按类别查找问题和解决方案。
安装与启动
插件安装后不生效
可能原因：
- 插件未启用
- 需要重启 Gateway
- 配置位置错误
解决方案：
- 运行 openclaw plugins enable <name>
- 重启 Gateway: openclaw restart
- 检查配置是否在正确位置
Gateway 启动失败
可能原因：
- 端口被占用
- 配置文件错误
- 依赖缺失
解决方案：
- 检查端口占用: lsof -i :3000
- 验证配置: openclaw config validate
- 安装依赖: npm install
配置修改后未生效
可能原因：
- 需要重载配置
- 配置格式错误
- 配置位置错误
解决方案：
- 重载配置: openclaw reload
- 验证配置格式
- 确认配置文件路径正确
渠道接入
消息收不到
可能原因：
- Webhook 未配置
- Bot Token 无效
- 权限不足
解决方案：
- 检查 Webhook 配置
- 验证 Bot Token 有效性
- 确认 Bot 有必要权限
消息发送失败
可能原因：
- 频率限制
- 消息格式错误
- 用户权限问题
解决方案：
- 检查 API 限制
- 验证消息格式
- 确认用户允许接收消息
群组消息无响应
可能原因：
- 未配置群组规则
- 缺少 mention
- 权限不足
解决方案：
- 配置群组规则
- 检查 requireMention 设置
- 确认 Bot 在群组中的权限
执行与权限
工具执行被拒绝
可能原因：
- 审批策略限制
- Sandbox 隔离
- 权限不足
解决方案：
- 检查审批配置
- 确认 Sandbox 设置
- 调整权限配置
文件操作失败
可能原因：
- 路径不存在
- 权限不足
- Sandbox 限制
解决方案：
- 确认文件路径正确
- 检查文件权限
- 调整 Sandbox 范围
命令执行超时
可能原因：
- 命令执行时间过长
- 资源不足
- 网络问题
解决方案：
- 增加超时时间
- 检查系统资源
- 检查网络连接
性能问题
响应缓慢
可能原因：
- 模型响应慢
- 内存不足
- 并发过高
解决方案：
- 检查模型 API 延迟
- 增加内存配置
- 限制并发数量
内存占用过高
可能原因：
- 会话过多
- 日志过大
- 内存泄漏
解决方案：
- 清理旧会话
- 清理日志文件
- 重启服务
CPU 占用过高
可能原因：
- 任务过多
- 死循环
- 资源竞争
解决方案：
- 减少并发任务
- 检查任务逻辑
- 优化配置
Log Analysis
日志分析
学会阅读和分析日志，快速定位问题。
日志级别
debug调试信息，详细执行过程
info常规信息，正常操作记录
warn警告信息，潜在问题提示
error错误信息，需要关注处理
常见错误模式
模式含义解决方案
ECONNREFUSED连接被拒绝检查目标服务是否运行，端口是否正确ETIMEDOUT连接超时检查网络连接，增加超时时间ENOENT文件不存在确认文件路径正确，创建必要文件EACCES权限不足检查文件/目录权限，使用正确的用户运行Unauthorized认证失败检查 API Key 是否正确，是否过期Rate limit频率限制降低请求频率，等待限制重置日志配置
{
"logging": {
"level": "debug",
"format": "json",
"outputs": ["console", "file"],
"file": {
"path": "~/.openclaw/logs/debug.log",
"maxSize": "50m",
"maxFiles": 10
}
}
}Tips
调试技巧
启用详细日志
将日志级别设置为 debug，获取更多执行细节
使用测试环境
在隔离的测试环境中复现问题，避免影响生产
逐步排查
从最简单的配置开始，逐步添加复杂度
对比正常状态
与正常工作的配置对比，找出差异点
检查变更历史
查看最近的配置变更，定位问题引入时间
查阅文档和社区
搜索官方文档和社区讨论，查找已知问题
Performance
性能优化建议
优化模型调用
- 使用合适的模型，避免过度使用高成本模型
- 控制上下文大小，避免过长的对话历史
- 使用流式响应，提升用户体验
优化资源使用
- 定期清理旧会话和日志
- 限制并发任务数量
- 使用缓存减少重复计算
优化网络请求
- 使用连接池复用连接
- 设置合理的超时时间
- 实现请求重试机制
优化存储
- 定期清理向量数据库
- 压缩历史数据
- 使用高效的存储格式
FAQ
常见问题
如何查看详细的错误信息？
将日志级别设置为 debug，查看日志文件或使用 openclaw logs --level debug 命令。
问题只在生产环境出现怎么办？
检查生产环境与本地环境的差异：配置、环境变量、网络、资源等。使用 openclaw doctor 收集诊断信息。
如何判断是插件问题还是配置问题？
禁用插件后测试，如果问题消失则是插件问题。检查插件配置是否正确，查看插件日志。
Gateway 响应很慢怎么排查？
检查系统资源使用、模型 API 延迟、网络连接状态。使用 openclaw status 查看运行状态。
如何恢复到上一个稳定状态？
使用版本控制管理配置文件，保留备份。插件可以使用 openclaw plugins update <name>@<version> 回滚。
Related