OpenClaw Guide

← 返回教程列表

OpenClaw 排错指南 —— 修复安装、Gateway 与渠道故障

运维 doctor日志升级排错维护 OpenClaw 指南编辑部 📅 2026-09-09 ⏱ 7 分钟

一线排错指南：doctor 自检、Gateway 崩溃、渠道断连、模型错误、版本回滚。

OpenClaw 的每个版本都经过维护者测试，但现实世界总是充满意外：公司代理、锁定的系统钥匙串、半安装的 macOS 配置。本指南汇总了我们最常见的故障模式，以及修好它们所需的精确命令。

先跑一遍 doctor

openclaw doctor

doctor 会逐项检查 Gateway 启动时做的所有事情：

  • Node.js 版本（24.16+ 或 26.1+）
  • 磁盘空间与文件权限
  • 模型供应商身份认证
  • 渠道可达性（Telegram、Discord、Slack、WhatsApp、iMessage）
  • 记忆数据库完整性
  • 升级渠道可用性

健康的安装会对每一项输出绿色 ✓。红色 ✗ 会打印出故障组件和修复建议。

✓ Node.js 26.1.0
✓ Disk space (12.4 GB free)
✓ Model provider: anthropic (authenticated)
✗ Telegram channel: HTTP 401 from api.telegram.org
   → Token rejected. Run `openclaw channels rotate telegram`.
✓ Memory database (842 facts)
✓ Update channel: stable

查看实时日志

openclaw logs --follow

可加 --channel telegram、--skill weather 或 --level warn 缩小范围：

openclaw logs --channel telegram --level error --follow

日志是 JSON 结构化的，默认写入 ~/.openclaw/logs/gateway.log，保留 14 天自动轮转。

Gateway 起不来

Gateway 启动失败最常见的三类原因如下。

18789 端口已被占用

Error: listen EADDRINUSE :::18789

要么已经有另一个 OpenClaw 实例在跑（用 openclaw status 检查），要么是别的进程占用了端口。找出占用者：

lsof -i :18789

在 Linux 上也可以直接换一个端口：

openclaw serve --port 28889

主目录权限被拒

Error: EACCES: permission denied, open '/Users/me/.openclaw/gateway.pid'

修复归属：

sudo chown -R "$USER" ~/.openclaw

…或者用另一个 OPENCLAW_HOME 跑：

OPENCLAW_HOME=~/work/.openclaw openclaw serve

残留锁文件

Error: gateway.pid exists but process 41823 is not running
rm ~/.openclaw/gateway.pid
openclaw serve

模型供应商返回 401 或 429

401 表示 API Key 错误或已过期。轮换：

openclaw config set providers.anthropic.apiKey ""
openclaw gateway reload

429 表示触发限流。doctor 会打印 retry-after 头：

✗ Provider anthropic: 429 Too Many Requests (retry-after: 17s)
   → Lower your `requestsPerMinute` setting or upgrade your tier.

调整每个供应商的预算：

openclaw config set providers.anthropic.requestsPerMinute 30

渠道反复断连

openclaw doctor --channel whatsapp --verbose

详细模式会打印最近 10 次重连尝试的时间戳和底层错误。

WhatsApp 的链接设备会话大约每 14 天过期。可以保持长连接：

openclaw channels set whatsapp --keep-alive true

Discord 最常见的"沉默"原因是缺少特权 Intent：

✗ Discord: messages not received. Enable "Message Content Intent" in the
   developer portal under Bot → Privileged Gateway Intents.

iMessage 在 macOS 更新后"完整磁盘访问权限"可能被重置，需要重新在 系统设置 → 隐私与安全性 → 完整磁盘访问权限 中把 OpenClaw 重新加入。

升级后出问题

OpenClaw 会在磁盘上保留上一个版本 30 天，回滚只需一行：

openclaw update --rollback

如果升级后 Gateway 都起不来，用纯 CLI 安装器回滚：

curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --channel stable

想看版本之间改了什么：

openclaw update --notes

彻底重置（最后手段）

当你已经尝试过所有办法、安装完全卡住时，彻底重置是最干净的路径。注意：这会删除所有记忆并卸载所有技能。

openclaw uninstall --purge
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard

之后可以从备份恢复：

tar xzf openclaw-memory-2026-09-21.tgz -C ~

求助前请准备

请先执行并保留以下输出：

openclaw doctor > doctor.txt 2>&1
openclaw --version > version.txt
openclaw logs --since 24h > logs.txt

把这三个文件附到联系表单工单里，并写明你正在看的页面 URL。这些输出能告诉我们大部分复现问题所需的信息。

下一步

OpenClaw 指南编辑部
独立维护的 OpenClaw 教程与生态解读。

发现问题或需要更正？ 联系我们.