OpenClaw 故障排除完全指南：从入门到精通
说实话，我第一次用 OpenClaw 时差点放弃。那种感觉太熟悉了——工具装上了，但就是不听使唤。命令行报一堆错，不知道从哪里入手。
但用了两周之后，我发现 OpenClaw 的大多数问题其实都有规律可循。这篇文章会把我踩过的坑、总结的经验全部分享给你，让你少走弯路。
## 为什么故障排除这么重要
OpenClaw 是一个复杂的系统，它把 AI 模型、消息渠道、本地工具全部整合在一起。任何一环出问题，都会导致整体不可用。
我见过几种典型情况：
**第一种是"它坏了但我不知道哪里坏了"**。你发消息，AI 不回复。你不知道是 Gateway 挂了，还是模型 API 挂了，还是你的网络有问题。这种情况下，盲目排查只会浪费时间。
**第二种是"我知道坏了但不知道怎么修"**。你看到错误信息了，但看不懂那些技术术语代表什么意思。`spawn EBADF`、`ModuleNotFoundError`、`connection refused`——这些英文单词你认识，但放在一起就不知道怎么办了。
**第三种是"修好了但不知道为什么好了"**。你试着跑了个命令，突然又能用了。但你不知道是哪个命令起的作用，下次出问题还是得从头摸索。
这篇文章的目标，就是帮你建立系统化的故障排除思维，让你能快速定位问题、高效解决、举一反三。
## 第一章：最初的六十秒——快速诊断流程
当你的 OpenClaw 出问题时，别慌着到处搜答案。按顺序跑这几个命令，足够解决 90% 的问题。
### 1.1 基础状态检查
```bash
openclaw status
```
这个命令会告诉你 Gateway 是否在运行、连接了哪些渠道、使用了什么模型。输出通常像这样：
```
OpenClaw 2026.2.6-3
Telegram: ok
WhatsApp: linked
Agents: main (default)
```
如果这里显示 Gateway 运行正常，那问题可能出在特定渠道或会话层面。如果 Gateway 状态显示异常，直接看下一步。
### 1.2 完整状态报告
```bash
openclaw status --all
```
这个命令会输出更详细的信息，包括所有会话列表、模型配置、工具状态等。当你在社区提问时，这个输出的完整信息能帮别人快速理解你的配置和当前状态。
### 1.3 网关探测
```bash
openclaw gateway probe
```
这个命令会测试 Gateway 的可达性和响应时间。如果你的 Gateway 运行在远程服务器上，这个命令能帮你确认网络连接是否正常。
### 1.4 实时日志跟踪
```bash
openclaw logs --follow
```
这是最有价值的诊断工具。它会实时显示 Gateway 的日志输出，你能看到每一条请求、每一个错误、每一次重试。跑这个命令的同时重现问题，日志会直接告诉你哪里出了问题。
我个人的经验是：90% 的问题，看一眼日志就能定位根本原因。
### 1.5 自动化诊断
```bash
openclaw doctor
```
这个命令会自动化运行一系列检查，包括配置验证、依赖检查、权限验证等。它会告诉你哪些配置可能有风险、哪些设置需要调整。
### 1.6 深度探测
如果 Gateway 网关可达，但你想做更深入的诊断：
```bash
openclaw status --deep
```
这个命令会检查网络延迟、API 连通性、磁盘空间等更底层的指标。
## 第二章：常见问题与解决方案
### 2.1 命令找不到：PATH 问题
遇到这个错误：
```bash
-bash: openclaw: command not found
```
几乎总是 Node/npm PATH 的问题。OpenClaw 安装后没有正确添加到系统 PATH 中。
**诊断步骤：**
首先确认 Node.js 是否正确安装：
```bash
node --version
npm --version
```
你应该能看到版本号输出。如果没有输出或者版本低于 22，先去安装 Node.js。
然后检查 OpenClaw 是否真的安装了：
```bash
which openclaw
# 或者
where openclaw
```
如果安装了但找不到，PATH 里没它的位置。
**解决方案：**
最简单的方法是重新安装 OpenClaw。官方安装脚本会自动处理 PATH 问题：
```bash
# 完整安装（自动配置 PATH）
curl -fsSL https://openclaw.ai/install.sh | bash
```
如果你用的是 Homebrew：
```bash
brew install openclaw
```
手动解决 PATH 问题（macOS）：
```bash
# 在 ~/.zshrc 或 ~/.bash_profile 中添加
export PATH="/usr/local/bin/openclaw:$PATH"
# 或者
export PATH="~/Library/Python/3.x/bin:$PATH"
```
然后重新加载配置：
```bash
source ~/.zshrc # 或 ~/.bash_profile
```
**我踩过的坑：**
有时候 Node.js 是通过 nvm 安装的，而 nvm 只在新的终端会话中激活。确保你安装 OpenClaw 的那个终端会话中，Node 是可用的。
### 2.2 安装程序失败
有时候安装过程会中途失败，输出一些错误信息但不完整。想看完整日志？
以详细模式重新运行安装程序：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
```
Beta 版本安装（如果你想用最新功能）：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
```
或者设置环境变量代替命令行参数：
```bash
OPENCLAW_VERBOSE=1 ./install.sh
```
**常见的安装失败原因：**
1. **权限不够**：macOS 上有时候需要 sudo 权限，或者确保你的用户有 /usr/local 目录的写权限。
2. **网络问题**：安装脚本需要从 npm 仓库下载依赖。网络不稳定会导致下载失败。尝试切换网络或使用 VPN。
3. **磁盘空间不足**：检查还有多少可用空间：
```bash
df -h
```
4. **Node 版本不兼容**：OpenClaw 需要 Node 22+，太老或太新的版本可能不兼容：
```bash
node --version
```
### 2.3 控制 UI 在 HTTP 上失败
打开 http://127.0.0.1:18789/ 时报错，说需要设备身份？
这是因为新版 OpenClaw 默认要求 HTTPS 连接，用于本地调试的 HTTP 模式需要额外配置。
**解决方案：**
查看 Gateway 故障排除文档：
```bash
openclaw gateway --help
```
确保你的 Gateway 是在本地模式运行：
```bash
openclaw config get gateway.mode
```
如果需要临时启用 HTTP 访问（仅限本地调试）：
```bash
openclaw gateway run --insecure
```
**警告：** 只在本地开发环境使用 `--insecure` 标志，生产环境务必使用 HTTPS。
### 2.4 服务显示运行中，但 RPC 探测失败
这是最让人困惑的情况之一。`openclaw status` 显示 Gateway 在运行，但 RPC 调用失败。
**诊断步骤：**
首先确认进程确实在运行：
```bash
ps aux | grep openclaw
```
输出应该类似：
```
joinylee 1612 0.1 1.1 457132624 539952 ?? S 6:38下午 0:12.14 openclaw-gateway
```
然后检查端口是否在监听：
```bash
lsof -i :18789
```
如果端口没在监听，Gateway 进程可能启动失败但没有报错。查看日志：
```bash
openclaw logs --follow
```
**解决方案：**
强制重启 Gateway：
```bash
openclaw gateway stop
openclaw gateway start
```
或者：
```bash
openclaw gateway restart --force
```
如果还是不行，手动杀死进程后重新启动：
```bash
pkill -f openclaw-gateway
openclaw gateway start
```
**我踩过的坑：**
有时候旧进程没有完全杀死，导致端口冲突。用 `lsof -i :18789` 确认没有其他进程占用端口。
### 2.5 模型认证失败
遇到类似这样的错误？
```
Error: all models failed
Rate limit exceeded
Billing required
```
这通常是模型 API 的问题，不是 OpenClaw 本身的问题。
**诊断步骤：**
检查模型配置：
```bash
openclaw config get agents.defaults.model
```
确认 API key 设置正确：
```bash
openclaw config get models.providers
```
**常见原因和解决方案：**
1. **API key 过期或无效**：去模型提供商的官网确认你的 API key 是否有效。
2. **余额不足**：大部分 API 服务需要预付费或绑卡。确认你的账户有足够的调用额度。
3. **速率限制**：如果短时间内请求太多，会触发限流。稍等几分钟再试，或者升级你的 API 计划。
4. **地域限制**：某些 API 服务在特定地区不可用。尝试使用 VPN 或确认你的 IP 不在黑名单中。
5. **模型不支持**：确认你请求的模型 ID 正确，且该模型对你的账户开放。
**检查模型可用性：**
```bash
openclaw models list
```
### 2.6 /model 显示 model not allowed
你输入 `/model` 想切换模型，但系统说 `model not allowed`？
这说明 `agents.defaults.models` 配置了允许列表。当这个配置非空时，你只能从允许列表中选择模型。
**诊断：**
```bash
openclaw config get agents.defaults.models
```
如果输出不是空的，说明有模型白名单限制。
**解决方案：**
方法一：添加你想要的模型到允许列表
```bash
openclaw config set agents.defaults.models '{"openai": ["gpt-4"]}'
```
方法二：清空允许列表（允许所有配置的模型）
```bash
openclaw config unset agents.defaults.models
```
方法三：浏览可用的提供商和模型
```bash
openclaw /models
```
### 2.7 exec 工具被阻止
在 Web Chat 界面，你想让我执行命令，但返回 `spawn EBADF` 错误？
这是因为 Web Chat 会话默认运行在 sandbox 模式，exec 工具被禁用。
**理解 sandbox 模式：**
OpenClaw 的 sandbox 模式是一种安全机制，它限制 agent 能执行的命令，防止恶意操作。sandbox 模式下：
- ❌ 不能执行 exec 命令
- ❌ 不能运行脚本
- ❌ 不能安装软件
- ✅ 可以读取文件
- ✅ 可以搜索网页
- ✅ 可以发送消息
**解决方案：**
方法一：使用 `--local` 模式启动 agent（推荐）
```bash
openclaw agent --to +8613382188809 --message "你的消息" --local
```
`--local` 参数会绕过 sandbox 限制，允许使用所有工具。
方法二：关闭全局 sandbox 配置
在配置文件中设置：
```json
{
"agents": {
"defaults": {
"sandbox": {
"mode": "off"
}
}
}
}
```
然后重启 Gateway：
```bash
openclaw gateway restart
```
方法三：为特定 agent 配置 tools 权限
```json
{
"agents": {
"list": [
{
"id": "main",
"tools": {
"allow": ["exec", "read", "write", "edit"]
}
}
]
}
}
```
**我踩过的坑：**
修改配置后，必须重启 Gateway 才能生效。只重启浏览器会话是不够的。
### 2.8 WhatsApp/Telegram 连接问题
**WhatsApp 相关：**
1. **二维码扫描后无响应**：等待几分钟，有时候网络延迟会导致同步慢。
2. **提示"已链接"但消息发不出去**：检查消息是否发给了正确的人/群组。
3. **需要重新配对**：删除凭证后重新扫码：
```bash
rm -rf ~/.openclaw/credentials/whatsapp
openclaw channels login whatsapp
```
**Telegram 相关：**
1. **Bot Token 无效**：确认 Bot Token 正确，从 @BotFather 获取。
2. **收不到消息**：检查 bot 是否被管理员设置为只接收命令模式。
3. **群组中不响应**：确认 bot 有管理员权限，且群组策略允许 bot 发言。
### 2.9 技能（Skills）不工作
技能是 OpenClaw 强大的扩展功能。但有时候技能加载失败或无法使用。
**诊断步骤：**
查看已安装的技能：
```bash
openclaw skills list
```
检查特定技能的状态：
```bash
openclaw skills status <skill-name>
```
**常见问题：**
1. **技能未启用**：在配置中启用技能：
```bash
openclaw config set skills.entries.<skill-name>.enabled true
```
2. **依赖缺失**：某些技能需要额外的 Python 包或 CLI 工具。查看技能的 README 或 SKILL.md 文件。
3. **路径错误**：确保技能目录在正确位置（通常是 `~/.openclaw/skills/` 或 `
~/.openclaw/workspace/skills/`）。
4. **权限问题**：确保技能脚本有执行权限：
```bash
chmod +x ~/.openclaw/skills/<skill-name>/scripts/*.sh
```
### 2.10 配置文件损坏
如果配置文件 JSON 格式错误，Gateway 可能无法启动。
**诊断：**
```bash
openclaw doctor
```
它会指出配置文件中的语法错误。
**解决方案：**
查看当前配置：
```bash
openclaw config get .
```
或者直接查看文件：
```bash
cat ~/.openclaw/openclaw.json | python3 -m json.tool
```
JSON 格式化工具会高亮显示语法错误。
**最安全的修复方式：**
重置配置（会保留你的凭据和会话）：
```bash
openclaw config reset
```
然后重新运行配置向导：
```bash
openclaw configure
```
## 第三章：提交问题时的正确姿势
如果你尝试了所有方法仍然无法解决问题，需要在社区寻求帮助。
### 3.1 收集诊断信息
在提问前，先运行这些命令收集信息：
```bash
# 完整状态报告
openclaw status --all > status_report.txt
# 实时日志（同时重现问题）
openclaw logs --follow > logs.txt &
# ...重现问题...
kill %1
```
### 3.2 描述问题的模板
一个好的问题描述应该包括：
1. **环境信息**：操作系统、OpenClaw 版本、Node.js 版本
2. **问题描述**：你想做什么、发生了什么、期望什么结果
3. **重现步骤**：如何稳定重现这个问题
4. **已尝试的方案**：你已经试过哪些方法、结果如何
5. **日志输出**：相关错误日志（脱敏后）
### 3.3 示例
❌ **不好的提问方式：**
```
OpenClaw 坏了，不工作，怎么办？
```
✅ **好的提问方式：**
```
环境：macOS 15.2, OpenClaw 2026.2.6-3, Node 22.12.0
问题：exec 工具返回 "spawn EBADF" 错误
重现步骤：
1. 在 Web Chat 中发送 "运行 ls 命令"
2. 返回错误：spawn EBADF
已尝试：
- 重启 Gateway：无效果
- 修改 sandbox.mode = "off"：无效果
日志输出（相关部分）：
[ERROR] Tool execution failed: exec spawn EBADF
```
## 第四章：进阶诊断技巧
### 4.1 使用 OpenClaw Browser
OpenClaw 内置了浏览器工具，可以帮你可视化检查网页：
```bash
openclaw browser open https://example.com
openclaw browser snapshot
```
这对于调试需要网页交互的问题特别有用。
### 4.2 网络诊断
如果怀疑是网络问题：
```bash
# 测试到 Gateway 的连接
nc -zv localhost 18789
# 测试到模型 API 的连接
curl -v https://api.openai.com/v1/models
# DNS 解析测试
dig api.openai.com
```
### 4.3 磁盘和内存检查
```bash
# 磁盘空间
df -h
# 内存使用
top -l 1 | head -n 10
# OpenClaw 进程的资源使用
ps -o pid,user,%cpu,%mem,command -p $(pgrep openclaw)
```
### 4.4 配置版本控制
把配置文件纳入版本控制是个好习惯：
```bash
cd ~/.openclaw
git init
git add openclaw.json
git commit -m "Initial openclaw config"
```
这样你可以追踪配置的变更历史，快速回滚到之前的工作状态。
## 第五章：预防胜于治疗
### 5.1 定期健康检查
每周运行一次：
```bash
openclaw doctor
openclaw config get . > backup_config_$(date +%Y%m%d).json
```
### 5.2 监控和告警
配合 cron 任务监控 Gateway 状态：
```bash
# 每天检查 Gateway 是否运行
0 * * * * pgrep -f openclaw-gateway || openclaw gateway start
```
### 5.3 保持更新
定期检查 OpenClaw 更新：
```bash
openclaw update check
```
但更新前：
1. 阅读更新日志
2. 备份配置文件
3. 在非生产环境测试新版本
## 第六章：资源汇总
### 6.1 官方文档
- 官方文档：https://docs.openclaw.ai/
- GitHub：https://github.com/openclaw/openclaw
- 社区 Discord：
https://discord.com/invite/clawd
### 6.2 常用命令速查表
| 命令 | 用途 |
|------|------|
| `openclaw status` | 基础状态检查 |
| `openclaw status --all` | 完整状态报告 |
| `openclaw gateway probe` | Gateway 探测 |
| `openclaw logs --follow` | 实时日志 |
| `openclaw doctor` | 自动化诊断 |
| `openclaw config get .` | 查看完整配置 |
| `openclaw config set <key> <value>` | 修改配置 |
| `openclaw gateway restart` | 重启 Gateway |
| `openclaw skills list` | 列出技能 |
| `openclaw channels list` | 列出渠道 |
### 6.3 故障排除流程图
```
问题 → 运行 openclaw status
│
├─ Gateway 不运行 → openclaw gateway start
│ │
│ └─ 还是不运行 → 查看日志 openclaw logs --follow
│
├─ Gateway 运行但 RPC 失败 → 检查进程 ps aux | grep openclaw
│ │
│ └─ 进程异常 → openclaw gateway restart --force
│
├─ 模型相关问题 → 检查模型配置 openclaw config get models
│
├─ 渠道连接问题 → 检查具体渠道状态
│
└─ 其他问题 → openclaw doctor
```
## 写在最后
OpenClaw 是一个强大的工具，但复杂性意味着问题不可避免。关键是建立系统化的排查思维。
我最大的经验是：90% 的问题，看一眼日志就能定位根本原因。别害怕日志——那是你的朋友，不是敌人。
遇到问题时，按顺序跑诊断命令，记录输出，然后针对性地解决。这比盲目搜索答案高效得多。
如果你卡在某个具体问题很长时间都解决不了，来社区提问。但在那之前，先自己做好功课——详细的问题描述和诊断信息，是对帮助你的人最基本的尊重。
祝你使用 OpenClaw 愉快！