第 22 章 排错

AI 卡住了别慌，跟着当当老师来修。

朋友们好呀，我是当当老师 🐾！不管多好的软件都会有出问题的时候。这一章我们不教怎么用 OpenClaw，而是教修 OpenClaw。

从"为什么连不上"到"AI 怎么不听使唤"，我帮你把常见问题一网打尽。

---

排错排查流程

22.1 常见的"翻车"现场

以下都是 OpenClaw 新手最常遇到的情况：

问题 1：WebChat 打不开

❌ 浏览器输入 http://127.0.0.1:18789/ 显示「无法访问」

原因和解决方法：

原因	怎么解决
OpenClaw 没启动	运行 openclaw status 检查
端口冲突	别的程序占了 18789 端口
权限问题	换非 root 用户试试
没装 WebChat 组件	openclaw install webchat

# 快速排查
openclaw status
# 如果显示 not running：
openclaw start

问题 2：AI 回答不了问题

❌ AI：抱歉，我无法回答这个问题

可能原因：

• 模型 API key 没配置或过期了
• 网络不通（特别是国内访问国外 API）
• Token 额度用完了

解决方法：

# 检查 API 配置
openclaw config show | grep api

# 测试网络
openclaw doctor --network

问题 3：AI 执行命令被拒绝

❌ AI 试图执行 "rm -rf /"，已拒绝

这不是 Bug，是安全特性！你的 tools.exec.mode 设置为 deny 或 allowlist 了。按第 19 章的方法调整即可。

问题 4：手机连不上

❌ Node 状态显示「离线」

排查步骤：

1. 手机和电脑是否在同一个网络？
2. 手机 App 是否是最新版？
3. 有没有输错 Gateway 地址？
4. 防火墙有没有阻挡 WebSocket 连接？

问题 5：TaskFlow 卡住了

❌ TaskFlow "备份" 停留在步骤 3/5 不动了

# 查看卡在哪个步骤
openclaw taskflow inspect backup

# 如果超时了，可以取消
openclaw taskflow cancel backup

# 重新从失败步骤开始
openclaw taskflow rerun backup --from-step 3

[截图：WebChat 中的错误日志显示]

22.2 查看日志

日志是排错最重要的工具。OpenClaw 把日志写得明明白白。

实时查看日志

# 查看所有日志（类似 tail -f）
openclaw logs

# 只看错误
openclaw logs --level error

# 只看某个模块的日志
openclaw logs --module gateway

# 带时间过滤
openclaw logs --since "2025-06-26 10:00"

日志级别

从轻到重：

级别	何时出现	需要管吗
DEBUG	AI 每一步思考都记录	调试时看
INFO	正常运行信息	不用管
WARN	有问题但不影响运行	有空看看
ERROR	错误，功能可能受影响	⚠️ 需要处理
FATAL	严重错误，程序可能挂了	🚨 立刻处理

日志文件在哪？

# macOS
~/Library/Logs/OpenClaw/

# Linux
/var/log/openclaw/

# Docker
docker logs openclaw

看懂日志

[2025-06-26T10:30:15.123Z] INFO  [gateway] Server listening on 127.0.0.1:18789
[2025-06-26T10:30:16.456Z] WARN  [tools.exec] Command "rm -rf /" blocked by policy
[2025-06-26T10:30:17.789Z] ERROR [gateway] WebSocket connection failed: connection refused

每行日志都包含：

• ⏰ 时间戳
• 📋 级别
• 📦 模块名
• 💬 具体信息

[截图：终端中的彩色日志输出]

日志搜索技巧

# 搜索关键词
openclaw logs | grep "error"

# 按时间范围
openclaw logs --since "1 hour ago"

# 输出 JSON 格式
openclaw logs --json > debug-report.json

22.3 openclaw doctor（一键诊断）

openclaw doctor 是 OpenClaw 自带的"体检医生"，能自动检查很多问题。

运行医生

openclaw doctor

输出示例：

🏥 OpenClaw 医生诊断报告
━━━━━━━━━━━━━━━━━━━━━━━━
✅ Node.js 版本: v24.5.0（推荐）
✅ OpenClaw 版本: v0.12.0（最新）
✅ Gateway 运行中: 127.0.0.1:18789
✅ API Key 配置: 3 个模型已配置
⚠️ 网络测试: 到 openai.com 延迟 320ms（稍高）
⚠️ 磁盘空间: 剩下 15%（建议清理）
✅ 配置文件权限: 正确（600）
━━━━━━━━━━━━━━━━━━━━━━━━━━
建议：
1. 国内用户建议配置代理访问海外 API
2. 清理一下磁盘空间

Doctor 能检查什么

检查项	说明
Node.js 版本	检查是否 >= 22.19
OpenClaw 版本	检查是否为最新
网络连通性	测试到各大模型 API 的延迟
磁盘空间	防止日志撑爆磁盘
配置权限	检查配置文件是不是太开放
Gateway 状态	检查网关是否正常运行
API Key 有效性	测试所有配置的 API key 是否有效
端口占用	检查 18789 等端口是否被占用

自动修复

# 自动修复检测到的问题
openclaw doctor --fix

⚠️ --fix 会自动修改配置，建议先备份。

[截图：openclaw doctor 输出的彩色报告]

22.4 常见报错速查表

报错信息	意思	怎么办
bind EADDRINUSE	端口被占了	查谁占了端口，或者改端口
ENOENT: no such file	找不到文件	检查路径对不对
ECONNREFUSED	连接被拒绝	检查目标服务有没有启动
ETIMEDOUT	连接超时	检查网络
UNABLE_TO_VERIFY_LEAF_SIGNATURE	SSL 证书问题	检查证书或关闭 SSL 验证（不推荐）
MODEL_NOT_FOUND	模型名写错了	检查配置文件里的模型名
RATE_LIMITED	API 调用太频繁	等一会再试，或者减少频率
INVALID_API_KEY	API key 不对	检查并重新设置

22.5 网络问题特别指南

在国内使用 OpenClaw 经常会遇到网络问题。

现象

• AI 回答特别慢
• 报 ETIMEDOUT 超时
• AI 说"我无法访问这个网站"

解决方案

方案一：用国内模型 OpenClaw 支持很多国内模型服务：

# 国内模型配置示例
models:
  deepseek:
    provider: deepseek
    apiKey: "sk-xxx"
    baseUrl: "https://api.deepseek.com"
    
  qwen:
    provider: qwen
    apiKey: "sk-xxx"
    baseUrl: "https://dashscope.aliyuncs.com"

方案二：配置代理

# 在 OpenClaw 中配置代理
network:
  proxy: "http://127.0.0.1:7890"   # 你的代理地址

方案三：使用路由器 VPN 如果 FQ 是在路由器上直接做好的，OpenClaw 不需要额外配置。

22.6 备份和恢复

预防胜于治疗。定期备份可以让你在出问题时快速恢复。

备份配置

# 一键备份
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw

Docker 的备份

# 备份 Docker 卷的数据
docker run --rm -v openclaw_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/openclaw-data.tar.gz -C /data .

恢复

# 恢复配置
tar -xzf openclaw-backup-20250626.tar.gz -C ~/

# Docker 恢复
docker run --rm -v openclaw_data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/openclaw-data.tar.gz -C /data

---

22.7 本章小结

记住排错三板斧：

1️⃣ openclaw status        → 看看是不是活着
2️⃣ openclaw logs          → 翻翻日志找线索
3️⃣ openclaw doctor        → 让医生帮你检查

大部分问题都可以用这三步搞定。搞不定的，下一章我们学的社区里找人帮忙！

---