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 前缀