快速状态检查
openclaw status

详细报告
openclaw status --all

深度检查
openclaw status --deep

运行医生
openclaw doctor

遇到问题
    ↓
openclaw status
    ↓
 Gateway 运行？
 ├─ 否 → openclaw gateway start
 └─ 是 → 继续
    ↓
 通道连接？
 ├─ 否 → 重新认证通道
 └─ 是 → 继续
    ↓
 模型可用？
 ├─ 否 → 检查 API Key
 └─ 是 → 查看日志

Error: Node.js version 22 or higher is required

使用 nvm 安装
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh 
bash
nvm install 22
nvm use 22


2.2 权限错误
错误信息：

Error: EACCES: permission denied


解决方案：

修复 npm 权限
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH


2.3 安装卡住
解决方案：

使用 verbose 模式
curl -fsSL https://openclaw.ai/install.sh
bash -s -- --verbose

清理后重试
rm -rf ~/.openclaw
curl -fsSL https://openclaw.ai/install.sh
bash



三、Gateway 问题
3.1 Gateway 无法启动
诊断：

openclaw gateway status
openclaw logs --follow


常见原因：
原因
解决方案
端口占用
修改配置使用其他端口 





配置错误
openclaw doctor --fix
认证失败
检查 API Key

3.2 端口被占用

错误信息：

Error: Port 18789 is already in use


解决方案：

查找占用进程
lsof -i :18789

杀死进程
kill -9 

或修改配置
# ~/.openclaw/openclaw.json
{ gateway: { port: 18790 } }


3.3 认证失败
错误信息：

unauthorized: gateway token mismatch


解决方案：

生成新 token
openclaw doctor --generate-gateway-token

更新配置
# ~/.openclaw/openclaw.json
{
  gateway: {
    auth: { token: "new-token" }
  }
}

重启
openclaw gateway restart



四、通道问题
4.1 WhatsApp 断开
症状：无法接收/发送消息
解决方案：


重新扫码
rm -rf ~/.openclaw/credentials/whatsapp/
openclaw channels login whatsapp


4.2 Telegram 无响应
症状：Bot 不回复消息
检查清单：


[ ] Bot Token 是否正确


[ ] 用户是否在 allowFrom 中


[ ] Bot 隐私模式是否关闭

解决方案：

在 Telegram 中
@BotFather → /setprivacy → 选择 Bot → Disable


4.3 Discord 离线
症状：Bot 显示离线
解决方案：

1. 检查 Bot Token
2. 重新邀请 Bot 到服务器
3. 检查服务器权限

五、模型问题
5.1 认证失败
错误信息：

No credentials found for profile "anthropic:default"


解决方案：

重新认证
openclaw models auth paste-token --provider anthropic


5.2 速率限制
错误信息：

HTTP 429: rate_limit_error


解决方案：
1. 等待配额重置
2. 升级订阅
3. 配置故障转移

{
  models: {
    defaults: {
      primary: "anthropic/claude-sonnet-4-5-20260514",
      fallbacks: ["openai/gpt-4o"]
    }
  }
}


5.3 模型不可用
错误信息：

Unknown model: xxx


解决方案：

查看可用模型
openclaw models list

设置有效模型
openclaw models set-default anthropic/claude-sonnet-4-5-20260514



六、会话问题
6.1 上下文丢失
症状：AI 不记得之前的对话
原因：


会话已重置


历史限制太小

解决方案：

{
  channels: {
    telegram: {
      dmHistoryLimit: 50  // 增加历史限制
    }
  }
}


6.2 上下文过大
错误信息：

Context too large


解决方案：

开始新会话
/new

或减少历史限制



七、性能问题
7.1 响应慢
可能原因：
原因
解决方案
网络延迟
使用更近的服务器 





模型负载
切换到更快的模型
资源不足
升级服务器配置

7.2 内存不足

症状：Gateway 崩溃
解决方案：


增加 Swap
fallocate -l 2G /swapfile
mkswap /swapfile
swapon /swapfile

或减少历史限制



八、日志分析
8.1 查看日志

实时查看
openclaw logs --follow

查看错误
openclaw logs --level error

查看特定时间
grep "2026-03-23" /tmp/openclaw/openclaw-.log


8.2 常见错误模式

错误模式
含义
解决方案




connection refused



服务未运行 | 启动服务 |
| timeout| 网络问题 | 检查网络 |
| unauthorized| 认证失败 | 检查 Token |