OpenClaw 常见报错解决方案大全（2026 持续更新） [2026]

Q: 怎么看 OpenClaw 的日志？

运行 pnpm gateway 时，日志直接输出在终端。后台运行时，日志文件位于项目根目录的 logs/gateway.log，使用 tail -f logs/gateway.log 实时查看。

Q: 如何提 Issue？

在 GitHub 仓库的 Issues 页面新建 Issue，请附上：错误截图、openclaw.json（隐去 API Key）、Node.js 版本（node -v）、操作系统信息。 ---

通用排查流程

遇到任何问题，先按以下顺序排查：

查看日志：tail -f logs/gateway.log 或运行 pnpm gateway 时看终端输出
检查配置：确认 openclaw.json 是合法的 JSON（用在线工具验证）
重启服务：很多问题重启后自愈
检查网络：确认模型 API 地址可达（curl https://api.minimaxi.com）

一、安装阶段报错

pnpm install 报错：EACCES permission denied

原因：npm/pnpm 全局目录权限不足。

解决： sudo chown -R $(whoami) ~/.pnpm-store pnpm install

Node 版本不对：Unsupported engine

原因：OpenClaw 要求 Node.js 18+，系统版本过低。

解决：使用 nvm 切换版本： nvm install 20 nvm use 20 pnpm install

二、Gateway 启动失败

端口被占用：EADDRINUSE

原因：3000 端口已被其他进程占用。

解决： lsof -i :3000 kill -9

或在 openclaw.json 中修改端口："port": 3001

内存不足：JavaScript heap out of memory

原因：Node.js 默认内存限制不够。

解决： NODE_OPTIONS="--max-old-space-size=4096" pnpm gateway

三、模型配置问题

API Key 无效：401 Unauthorized

原因：API Key 填写错误或已过期。

解决：重新从对应平台控制台复制 API Key，注意不要有前后空格。

模型不出现在列表中

原因：模型名称拼写错误，或 JSON 格式有问题。

解决：检查 openclaw.json 中模型名称，严格区分大小写（如 MiniMax-M2.5 不能写成 minimax-m2.5）。

连接超时：Request timeout

原因：模型 API 地址不可达，或需要代理。

解决：确认使用国内可直连的模型（MiniMax、DeepSeek），或配置代理环境变量： export HTTPS_PROXY=http://127.0.0.1:7890

四、Skill 相关

Skill 安装失败：Registry fetch error

原因：ClawHub 或 SkillHub 连接超时。

解决：国内用户切换到 SkillHub 源： openclaw skill install xxx --registry skillhub

斜杠命令不生效

原因：Skill 安装后未重载，或 gateway 未重启。

解决：运行 /reload 命令，或完全重启 gateway。

五、Telegram Bot 问题

Bot Token 无效：Unauthorized

原因：Token 填写错误，或 Bot 被删除后重新创建了新 Token。

解决：前往 @BotFather 查看当前有效的 Bot Token，更新 openclaw.json 并重启。

消息延迟严重

原因：服务器到 Telegram 服务器的网络延迟高。

解决：确认服务器的网络可以访问 api.telegram.org，如不能访问需配置代理或使用 Telegram Bot API 镜像。

常见问题

Q：怎么看 OpenClaw 的日志？

运行 pnpm gateway 时，日志直接输出在终端。后台运行时，日志文件位于项目根目录的 logs/gateway.log，使用 tail -f logs/gateway.log 实时查看。

Q：如何提 Issue？

在 GitHub 仓库的 Issues 页面新建 Issue，请附上：错误截图、openclaw.json（隐去 API Key）、Node.js 版本（node -v）、操作系统信息。

OpenClaw 常见报错解决方案大全（2026 持续更新）