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 前缀
Sourced from ClawHub,
Authored by mwangxiang