#25 OpenClaw 常见问题排查与服务交付

用 OpenClaw 遇到问题不要慌，大部分问题都有现成的解决方案。本文汇总了最常见的问题和对应的排查方法，帮你快速恢复服务。

Gateway 服务无法启动

症状：运行 openclaw gateway start 后没有响应，或者报错退出。

排查步骤：

1. 检查端口占用：lsof -i :3000（默认端口）
2. 查看日志：openclaw gateway logs
3. 检查配置文件语法：openclaw status
4. 如果是 Node.js 版本问题，确认 Node.js ≥ 20

常见原因：端口被其他服务占用，或 openclaw.json 配置格式有误。

飞书通道报错 "Unknown channel: feishu"

症状：Agent 运行正常但飞书收不到消息。

解决方案：

1. 检查飞书插件是否安装：openclaw plugins list
2. 重新安装插件：openclaw plugins install @anthropic-ai/openclaw-feishu-plugin
3. 检查 openclaw.json 中 channels.feishu 配置
4. 重启 Gateway：openclaw gateway restart

常见原因：插件版本更新后需要重新安装，或配置文件中 channels 节点缺失。

Control UI Origin 报错

症状：打开 Control UI 页面时报 CORS 或 Origin 错误。

解决方案：在 openclaw.json 中添加：

"gateway": { "controlUi": { "origin": "http://localhost:3000" } }

然后重启 Gateway。

心跳（Heartbeat）不工作

症状：Agent 不会主动执行心跳任务。

排查步骤：

1. 确认 HEARTBEAT.md 存在于工作区
2. 检查 Gateway 是否运行：openclaw gateway status
3. 查看日志中是否有心跳轮询记录
4. 确认 Agent 的 session 没有被禁用

WebSocket 连接失败

症状：终端显示 "WebSocket connection failed" 或类似错误。

解决方案：

1. 检查防火墙是否放行了 WebSocket 端口
2. 如果使用反向代理，确认 WebSocket 代理配置正确
3. 检查 SSL 证书是否有效（HTTPS 环境）
4. 尝试重启 Gateway

模型调用超时或报错

症状：Agent 回复很慢或直接报错。

排查步骤：

1. 检查 API Key 是否有效
2. 确认模型提供商服务是否正常
3. 查看是否触发了 Rate Limit
4. 尝试切换到其他模型：/model ollama/gemma3:4b

插件重复安装

症状：同一个插件出现了多次。

解决方案：

1. 卸载重复插件：openclaw plugins uninstall 插件名
2. 重新安装一次
3. 重启 Gateway

总结

大部分问题都可以通过三步解决：检查日志 → 确认配置 → 重启 Gateway。如果以上方法都不行，可以到 OpenClaw Discord 社区寻求帮助 🔧