OpenClaw故障排查完全指南：基于官方文档的10个问题解决方案

配置文件位置说明

OpenClaw主配置文件：~/.openclaw/openclaw.json

环境变量配置：~/.openclaw/.env

官方文档： https://docs.openclaw.ai/gateway/configuration^[1]

故障1：Gateway启动失败 - 配置文件格式错误

错误现象

[ERROR] Config validation failed: Invalid JSON format

解决方案

使用官方诊断工具：

openclaw doctor

修复配置文件：

openclaw doctor --fix

或手动检查JSON格式：

cat ~/.openclaw/openclaw.json | python -m json.tool

故障2：WhatsApp无法登录

错误现象

[ERROR] WhatsApp login failed: QR code expired

解决方案

修改配置文件 ~/.openclaw/openclaw.json：

{"channels":{"whatsapp":{"allowFrom":["+15555550123"],"groups":{"*":{"requireMention":true}}}}}

重新登录：

openclaw channels login

故障3：Agent无响应

错误现象

[ERROR] Agent timeout: No response from model

解决方案

修改配置文件 ~/.openclaw/openclaw.json：

{"agent":{"timeout":60000,"maxRetries":3},"models":{"default":{"provider":"openai","model":"gpt-4"}}}

故障4：内存不足崩溃

错误现象

FATAL ERROR: JavaScript heap out of memory

解决方案

修改配置文件 ~/.openclaw/openclaw.json：

{"browser":{"maxPages":3}}

或设置环境变量：

export NODE_OPTIONS="--max-old-space-size=4096"

故障5：API Key无效

错误现象

[ERROR] Authentication failed: Invalid API key

解决方案

修改环境变量 ~/.openclaw/.env：

OPENAI_API_KEY=sk-...

或修改配置文件 ~/.openclaw/openclaw.json：

models.providers.provider[实际的].apiKey

故障6：日志写入失败

错误现象

[ERROR] Failed to write log: Permission denied

解决方案

修改配置文件 ~/.openclaw/openclaw.json：

{"logging":{"file":"~/.openclaw/logs","level":"info"}}

创建日志目录：

mkdir -p ~/.openclaw/logs

故障7：端口被占用

错误现象

[ERROR] Port 18789 is already in use

解决方案

修改配置文件 ~/.openclaw/openclaw.json：

{"gateway":{"port":3000}}

或使用环境变量：

PORT=3000

故障8：热重载失败

错误现象

[WARNING] Config hot reload failed

解决方案

修改配置文件 ~/.openclaw/openclaw.json：

{"gateway":{"reload":{"mode":"hybrid","debounceMs":300}}}

手动重启：

openclaw gateway restart

故障9：插件加载失败

错误现象

[ERROR] Failed to load plugin: xxx

解决方案

修改命令：

openclaw plugins enable <id>

故障10：远程访问失败

错误现象

[ERROR] Remote access denied

解决方案

修改配置文件 ~/.openclaw/openclaw.json：

{"gateway":{"auth":{"token":"your-secure-token"},"remote":{"enabled":true}}}

本文基于OpenClaw官方文档编写，配置文件位置：~/.openclaw/openclaw.json

引用链接