OpenClaw 常见问题与解决方案

🔧 快速诊断命令

遇到问题时，按顺序运行以下命令：

# 1. 快速状态概览openclaw status

# 2. 完整诊断（可安全分享）openclaw status --all

# 3. 深度检查（包括模型探测）openclaw status --deep

# 4. 实时日志追踪openclaw logs --follow

❌ 常见问题

1. No API key found for provider

No API key found for provider “anthropic”

原因：智能体的认证存储为空

修复：

openclaw models auth setup-token --provider anthropic

2. Control UI 在 HTTP 上失败

device identity required / connect failed

修复：

• 优先使用 Tailscale Serve（HTTPS）
• 或在 Gateway 主机本地打开

3. 服务已安装但没有运行

检查：

openclaw gateway status
openclaw doctor

日志位置：

• macOS: ~/.openclaw/logs/
• Linux: journalctl --user -u openclaw-gateway
• 文件: /tmp/openclaw/openclaw-YYYY-MM-DD.log

4. 端口已被使用（18789）

# 检查端口占用lsof -nP -iTCP:18789 -sTCP:LISTEN

# 停止现有服务openclaw gateway stop

5. Gateway 网关拒绝启动

Gateway start blocked: set gateway.mode=local

修复：

openclaw config set gateway.mode local

6. WhatsApp 断开连接

# 检查状态openclaw status

# 查看连接日志openclaw logs --limit 200 | grep "connection\|disconnect"

# 重新登录openclaw channels logout
openclaw channels login --verbose

7. 图片发送失败

检查文件限制：

• 图片：最大 6MB
• 音频/视频：最大 16MB
• 文档：最大 100MB

8. 高内存使用

设置会话历史限制：

{  "session": {    "historyLimit": 100  }}

📋 日志位置速查

🆘 获取帮助

1. 首先检查日志
2. 在 GitHub 搜索现有问题
3. 提交新问题时包含：
   • OpenClaw 版本
   • 相关日志片段
   • 重现步骤
   • 配置（隐藏密钥！）

别忘了：试试 openclaw doctor 和 openclaw doctor --fix！

🔗 相关资源

• 官方故障排除文档
• 渠道故障排除
• 健康检查