OpenClaw 快速排查指南

1. 快速开始

安装

bash# 检查环境（Node.js ≥ 18）
node -v

# 全局安装
npm i -g openclaw@latest

# 国内网络换镜像
npm config set registry https://registry.npmmirror.com

# 验证
openclaw -v

启动

bash# 首次运行自动生成配置
openclaw

# 启动 Gateway
openclaw gateway start

# 确认状态
openclaw status

配置文件 .openclaw/openclaw.json，至少填 API Key：

json{
  "llm": {
    "apiKey": "sk-你的API密钥",
    "model": "qwen/qwen-plus"
  }
}

遇到问题先跑这 5 步

bashopenclaw -v                                # 1. 确认版本
openclaw doctor --fix                      # 2. 自动诊断（解决 50%+ 问题）
openclaw status                            # 3. 检查服务状态
openclaw logs 2>&1 | findstr ERROR        # 4. 查看错误
openclaw gateway restart                   # 5. 重启

2. 常用命令速查表

🐳 Docker 部署

yamlservices:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: my_openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./data:/root/.openclaw

bashdocker compose up -d                     # 启动
docker compose ps                        # 状态
docker compose logs -f                   # 日志
docker compose restart                   # 重启
docker compose pull && docker compose up -d  # 更新
docker rm -f my_openclaw                 # 强制删除（数据不丢）

3. 常见问题排查

Gateway 启动失败

现象： 立即退出，status 显示未运行。

bash# 检查端口
netstat -ano | findstr 18789

# 检查 JSON 语法
Get-Content .openclaw\openclaw.json | ConvertFrom-Json

# 诊断
openclaw doctor --fix

# 清理状态后重启（不丢数据）
openclaw gateway stop
Remove-Item .openclaw\gateway-state.json -ErrorAction SilentlyContinue
openclaw gateway start

端口被占用 (EADDRINUSE)

方案 A — 杀进程：

bashnetstat -ano | findstr 18789   # 找到 PID
taskkill /F /PID 12345        # 替换实际 PID

方案 B — 改端口：

json{ "gateway": { "port": 18790 } }

API Key 错误 (401 Unauthorized)

1. 检查 llm.apiKey 是否完整、无空格
2. 到模型控制台确认 Key 未过期
3. openclaw gateway restart

飞书连接超时 (ETIMEDOUT)

bashping open.feishu.cn
curl -I https://open.feishu.cn/open-apis/bot/v3/dispatch/

• 确认：机器人已启用、App ID/Secret 正确、事件订阅 URL 已配置
• 检查防火墙/代理：$env:HTTPS_PROXY="http://代理:端口"

模型限流 (429)

json{ "llm": { "maxConcurrent": 3 } }

• 等 1~2 分钟自动恢复
• 配置 fallbackModel 自动降级（见 5.6）

配置文件 JSON 格式错误 (SyntaxError)

常见错误：结尾多了逗号、引号不配对、用了中文引号。用 ConvertFrom-Json 检查。

容器无限重启 (Docker)

bashdocker logs my_openclaw --tail 100                    # 看错误
docker exec -it my_openclaw cat /root/.openclaw/openclaw.json  # 查配置
docker rm -f my_openclaw && docker compose up -d      # 重建

日志关键词速查

4. 搬家迁移指南

完整步骤（Windows）

powershell# 1. 停止所有进程（管理员）
taskkill /F /IM node.exe /T
taskkill /F /IM openclaw.exe /T

# 2. 设置新数据目录
[Environment]::SetEnvironmentVariable("OPENCLAW_STATE_DIR", "D:\openclaw\.openclaw", "Machine")
$env:OPENCLAW_STATE_DIR = "D:\openclaw\.openclaw"

# 3. 复制数据
Copy-Item -Path "C:\Users\Administrator\.openclaw" -Destination "D:\openclaw\.openclaw" -Recurse -Force

# 4. 重命名旧目录（先别删）
Rename-Item -Path "C:\Users\Administrator\.openclaw" -NewName ".openclaw_bak" -Force

# 5. 开新 PowerShell 窗口验证
openclaw -v
openclaw gateway start
openclaw status

备份

bashtar -czf openclaw-backup-$(Get-Date -Format yyyyMMdd).tar.gz .openclaw/

5. 实战踩坑经验

5.1 重启超时误报（Windows）

openclaw gateway restart 可能卡 60 秒报超时，但 gateway 已经重启成功。超时后直接跑 openclaw status 确认。

5.2 重启后飞书消息静默失败

Gateway 重启后，飞书 Bot 身份恢复需 60-90 秒。这段时间发消息 API 返回 ok 但实际投递失败。重启后等 90 秒再发。

5.3 频繁重启导致崩溃

短时间内多次 SIGUSR1 会让 Gateway 在重载中被杀死，循环崩溃。两次重启间隔至少 30 秒。 已崩溃：

bashopenclaw gateway stop
# 等 10 秒
openclaw gateway start

5.4 Watchdog 进程退出

Watchdog 挂了就无法自动恢复 Gateway。检查：

powershellGet-Process | Where-Object { $_.ProcessName -like "*watchdog*" }

用任务计划程序托管开机启动。

5.5 doctor 的 memory 警告是误报

"No active memory plugin is registered" 是检测 bug，memory_recall / memory_store 实际可用，忽略即可。

5.6 免费模型限流

OpenRouter 的 :free 模型限制严格。配置 fallback：

json{
  "llm": {
    "model": "qwen/qwen3.6-plus:free",
    "fallbackModel": "qwen/qwen-plus"
  }
}

5.7 clawhub 安装走中国镜像

国内直连超时，必须加 --registry：

bashclawhub install <插件名> --registry https://cn.clawhub-mirror.com

5.8 Agent 无响应/返回空

现象： 调用 sessions_spawn 或直接与 Agent 对话时，长时间无响应或直接返回空结果。

原因：

• Agent 进程已崩溃或未启动
• 配置文件 allowAgents 未包含该 Agent ID
• Agent 任务超时（默认 5 分钟）
• 推理模式（reasoning）开启导致卡顿

解决：

1. 用 sessions_list 查看 Agent 是否在运行
2. 检查配置文件中 allowAgents 列表是否包含目标 Agent ID
3. 调整 runTimeoutSeconds（spawn 时设置）
4. 关闭推理：openclaw config set reasoning off
5. 查看日志：openclaw logs | findstr AGENT

5.9 配置文件改完不生效

现象： 修改 .openclaw/openclaw.json 后，重启 Gateway，配置未更新。

原因：

• JSON 语法错误导致解析失败，回退到旧配置
• 修改的是错误的配置文件（多份配置导致混淆）
• Gateway 使用 gateway-state.json 缓存，未完全重启

解决：

1. 验证 JSON：Get-Content .openclaw\openclaw.json | ConvertFrom-Json
2. 清理缓存：Remove-Item .openclaw\gateway-state.json -ErrorAction SilentlyContinue
3. 完整重启：openclaw gateway stop; openclaw gateway start
4. 确认修改的是正确文件：openclaw config show 查看当前生效配置路径

5.10 技能安装失败（网络超时、权限问题）

现象： clawhub install <skill> 报网络错误或权限拒绝。

原因：

• NPM registry 访问超时（国内直连 GitHub）
• 全局安装权限不足（需管理员/root）
• 防病毒软件/防火墙阻止

解决：

1. 换国内镜像：npm config set registry https://registry.npmmirror.com
2. 使用 clawhub 的 --registry 参数：clawhub install <skill> --registry https://cn.clawhub-mirror.com
3. 管理员权限运行 PowerShell（右键 → 以管理员身份运行）
4. 临时关闭防火墙/AV 测试

5.11 memory_recall 工具不可用

现象： 调用 memory_recall 报错或返回空，即使已存过记忆。

原因：

• Memory 插件未正确加载（SQLite 文件损坏、权限不足）
• 查询条件过于严格，匹配不到
• 向量化服务异常（若启用 embedding）

解决：

1. 检查数据库文件：Get-ChildItem .openclaw\memory*
2. 确认文件权限：icacls .openclaw\memory
3. 简化查询：memory_recall --query "关键词" --limit 10
4. 重启 Gateway：openclaw gateway restart
5. 若仍不行，备份 .openclaw 后重新初始化

5.12 多 agent 之间 allowAgents 配置错误导致调用失败

现象： Agent A 调用 Agent B 时返回 permission denied 或无响应。

原因：

• 配置文件中只单向配置了 A.allowAgents = [B]，但 B 的 allowAgents 未包含 A（双向需对称）
• Agent ID 写错（大小写、前缀）
• 使用子 Agent 时，主 Agent 未授权子 Agent 调用外部 Agent

解决：

1. 查看当前配置：openclaw config get allowAgents
2. 确保双向配置：A 的列表有 B，B 的列表有 A
3. 使用 sessions_list 确认 Agent ID 正确
4. 修改后重启：openclaw gateway restart

5.13 搬家/迁移后 Gateway 不起

现象： 迁移 .openclaw 目录到新位置/新机器后，Gateway 无法启动。

原因：

• 环境变量 OPENCLAW_STATE_DIR 未更新或指向旧路径
• 文件权限丢失（Linux 权限 UID/GID 变化）
• 配置文件路径硬编码在脚本/服务中

解决：

1. 确认环境变量：echo $env:OPENCLAW_STATE_DIR（Windows 或 echo $OPENCLAW_STATE_DIR（Linux）
2. 临时显式指定：OPENCLAW_STATE_DIR=新路径 openclaw gateway start
3. 检查权限：icacls 新路径\.openclaw（Windows）或 ls -la .openclaw（Linux）
4. 重启终端或系统，确保环境变量全局生效