OpenClaw 部署与故障排查

快速查询 OpenClaw 部署步骤和错误解决方案。

触发词

用户询问以下内容时启动本 skill：

OpenClaw 部署、安装、配置
OpenClaw 报错、故障、不回复、连不上
"openclaw 怎么..." / "小龙虾报错"

部署导航（九阶段）

| 阶段 | 内容 | 关键验证 | |-----|------|---------| | 1 | 服务器购买与初始访问 | 能看到 root@主机名 提示符 | | 2 | SSH 免密登录配置 | ssh root@IP "echo ok" 无需密码 | | 3 | 服务器环境确认 | openclaw --version 输出版本号 | | 4 | 配置 AI 模型（models.providers） | providers 列表非空，primary model 已设置 | | 5 | 飞书应用创建 | 获得 App ID（cli_ 开头）和 App Secret | | 6 | 飞书通道配置（服务器端） | channels.feishu.enabled=true，凭证已设置 | | 7 | 飞书权限与事件订阅 | im:message 等权限已开通，版本已上线 | | 8 | 重启网关与端到端测试 | 机器人成功回复消息 | | 9 | 安装 Claude Code（可选） | claude --version 输出版本号 |

关键命令模板

远程执行前缀（必需）

export NVM_DIR=/root/.nvm; . "$NVM_DIR/nvm.sh";

配置 AI 模型（阶段4）

ssh root@<IP> 'export NVM_DIR=/root/.nvm; . "$NVM_DIR/nvm.sh"; openclaw config set "models.providers.<名称>" --json "{
  \"baseUrl\": \"<代理地址>\",
  \"apiKey\": \"<API_Key>\",
  \"api\": \"anthropic-messages\",
  \"models\": [{
    \"id\": \"claude-sonnet-4-6\",
    \"name\": \"Claude Sonnet 4.6\",
    \"reasoning\": true,
    \"input\": [\"text\", \"image\"],
    \"contextWindow\": 200000,
    \"maxTokens\": 32000
  }]
}"'

设置主模型

ssh root@<IP> 'export NVM_DIR=/root/.nvm; . "$NVM_DIR/nvm.sh"; openclaw config set "agents.defaults.model.primary" "<名称>/claude-sonnet-4-6"'

配置飞书通道（阶段6）

ssh root@<IP> 'export NVM_DIR=/root/.nvm; . "$NVM_DIR/nvm.sh"; openclaw config set "channels.feishu" --json "{
  \"enabled\": true,
  \"domain\": \"feishu\",
  \"groupPolicy\": \"open\",
  \"appId\": \"<App_ID>\",
  \"appSecret\": \"<App_Secret>\"
}"'

重启网关（阶段8）

ssh root@<IP> 'systemctl --user restart openclaw-gateway.service'

查看日志

ssh root@<IP> 'journalctl --user -u openclaw-gateway.service --no-pager -n 30'

故障速查表

飞书相关

| 错误现象 | 可能原因 | 解决方案 | |---------|---------|---------| | 机器人收到消息但不回复 | models 未配置 | 执行阶段4配置 models.providers | | 日志显示 99991672 | 飞书 API 权限不足 | 飞书开放平台添加 im:message 等权限并重新发布 | | "应用未建立长连接" | appId/appSecret 未正确写入 | 凭证必须写入 channels.feishu，不是环境变量 | | 飞书连接后秒断 | Encrypt Key/Verification Token 不匹配 | 核对飞书开放平台的加密策略 | | 搜索不到机器人 | 应用未发布 | 创建版本并发布 |

模型相关

| 错误现象 | 可能原因 | 解决方案 | |---------|---------|---------| | "No API key found for provider" | models.providers 为空 | 执行阶段4配置模型 | | "Embedded agent failed" | API Key 无效或代理地址错误 | 检查 baseUrl 和 apiKey | | 模型回复乱码/格式错误 | api 字段选错 | Anthropic 用 anthropic-messages，OpenAI 用 openai-responses | | "must NOT have additional properties" | 配置字段名错误 | 删除无效字段 | | HTTP 404: Invalid URL /v1/v1/messages | baseUrl 多了 /v1 | baseUrl 填 https://域名，不加 /v1 |

服务相关

| 错误现象 | 可能原因 | 解决方案 | |---------|---------|---------| | 网关启动失败 | 配置文件 JSON 语法错误 | node -e "JSON.parse(require('fs').readFileSync('/root/.openclaw/openclaw.json'))" | | 网关启动超时 | 被禁用的插件仍在尝试连接 | 禁用不需要的插件 | | SSH 远程命令 node 找不到 | nvm 未加载 | 命令前加远程执行前缀 |

日志关键字

| 关键字 | 含义 | |--------|------| | agent model: xxx/xxx | 模型配置已识别 | | feishu[default]: WebSocket client started | 飞书连接成功 | | [ws] ws client ready | WebSocket 就绪 | | listening on ws://0.0.0.0:18789 | 网关正在监听 | | received message from | 消息已收到 | | Embedded agent failed | 模型调用失败 | | Access denied + 99991672 | 飞书权限不足 | | No API key found | models.providers 配置有误 |

使用说明

先确认用户在哪个阶段或遇到什么错误
提供对应的命令模板或解决方案
所有远程命令都需要加 nvm 前缀