OpenClaw Manual OpenClaw
问题排查

OpenClaw 问题排查

遇到问题？这里有常见问题的快速诊断和解决方案

快速诊断

使用以下命令快速诊断问题

openclaw status --all

最佳的一键诊断报告，包含所有状态信息

openclaw gateway status

检查守护进程和 RPC 连接状态

openclaw doctor

自动修复常见配置问题

建议先运行 openclaw status --all 获取完整的诊断报告，然后根据输出定位问题。

启动与安装问题

解决 OpenClaw 启动失败、依赖缺失等问题

OpenClaw 需要 Node.js 22 或更高版本。如果版本过低，常见报错是 unsupported engine。

解决方案

$ node --version
$ nvm install 22
$ nvm use 22
升级后重新打开终端，再执行 openclaw onboard 或 openclaw health 验证。

默认端口 18789 被其他进程占用时，网关会启动失败。

解决方案

$ lsof -i :18789
$ openclaw gateway --port 18790
确认端口释放后，也可以继续使用默认端口；如果改端口，记得同步更新访问地址和反向代理。

这表示模型认证还没有完成，OpenClaw 无法连接到 AI 提供商。

解决方案

$ openclaw onboard
$ openclaw models status
如果你使用 OAuth 方式，也可以重新执行对应 provider 的 auth login。

认证与模型问题

解决 OAuth、API Key、模型访问等认证相关问题

OAuth 凭证可能已过期，或者本地缓存的 refresh token 不再有效。

解决方案

$ openclaw models auth login --provider anthropic
$ openclaw models status
必要时删除旧的 OAuth 凭证文件后重新登录，再检查 ~/.openclaw/credentials/ 目录。

通常是 API Key 填写错误、环境变量未生效，或当前 key 没有可用额度。

解决方案

$ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
$ openclaw models status
重新复制 key 时注意不要带空格，修改环境变量后需要重新开启终端或重启 gateway。

模型名拼写错误、provider 前缀不匹配，或者当前账号没有该模型权限，都会导致无响应。

解决方案

$ openclaw models status
$ openclaw status --deep
优先确认 openclaw.json 中的 provider/model 格式，例如 anthropic/claude-sonnet-4-20250514 或 openai/gpt-4o。

渠道连接问题

解决 WhatsApp、Telegram、Discord 等渠道连接失败的问题

常见原因是二维码过期、手机网络不稳定，或当前 WhatsApp 会话状态异常。

解决方案

$ openclaw channels login whatsapp
$ openclaw channels logout whatsapp
重新生成二维码后，保持手机联网，并在 WhatsApp 的已连接设备页面立即扫描。

多数情况下是 BotFather 的隐私模式没有关闭，或者 bot token 配置错误。

解决方案

$ export TELEGRAM_BOT_TOKEN="123456:ABC..."
$ openclaw channels login telegram
如果是群聊不响应，请到 BotFather 关闭 Group Privacy，或把机器人设为管理员。

OpenClaw 默认可能限制群聊响应，需要在配对或群组设置里显式允许。

解决方案

$ openclaw pairing list whatsapp
$ openclaw pairing approve whatsapp [CODE]
先确认机器人在私聊能正常工作，再检查群组响应策略和 allowlist 配置。

消息与会话问题

解决会话超时、环境变量等配置问题

会话频繁重置通常与 gateway 状态异常、上下文未持久化，或外部模型请求失败有关。

解决方案

$ openclaw status --deep
$ openclaw gateway status
$ openclaw logs --follow
先看日志里是否有 timeout、401、rate limit 之类的错误，再继续定位模型或渠道侧问题。

环境变量只在进程启动时读取。修改后如果没有重启 OpenClaw，旧值会继续生效。

解决方案

$ openclaw configure
$ openclaw gateway status
$ openclaw status --all
更新 .env 或 shell 环境变量后，重新开启终端并重启 gateway，再做验证。

调试与日志

学习如何查看日志、生成调试报告和获取帮助

查看日志

通过日志查看详细的运行信息和错误

实时查看日志

$ openclaw logs --follow

前台启动查看完整输出

$ openclaw gateway

生成调试报告

生成完整的调试报告，方便排查问题或寻求帮助

$ openclaw status --all
调试报告包含系统状态、配置信息等，是寻求帮助时最有用的信息。

获取帮助

如果以上方法无法解决你的问题，可以通过以下渠道获取帮助

官方 FAQ 文档 GitHub Discussions（提问交流） Discord 社区

问题解决了吗？

如果你的问题已解决，可以继续探索 OpenClaw 的其他功能。

相关文档