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 输出版本号 |
关键命令模板
远程执行前缀（必需）
CODEBLOCK0
配置 AI 模型（阶段4）
CODEBLOCK1
设置主模型
CODEBLOCK2
配置飞书通道（阶段6）
CODEBLOCK3
重启网关（阶段8）
CODEBLOCK4
查看日志
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 语法错误 | INLINECODE8 |
| 网关启动超时 |
被禁用的插件仍在尝试连接 | 禁用不需要的插件 |
| SSH 远程命令 node 找不到 | nvm 未加载 | 命令前加远程执行前缀 |
日志关键字
| 关键字 | 含义 |
|---|
| INLINECODE9 | 模型配置已识别 |
| INLINECODE10 |
飞书连接成功 |
|
[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 配置有误 |
使用说明
- 1. 先确认用户在哪个阶段或遇到什么错误
- 提供对应的命令模板或解决方案
- 所有远程命令都需要加 nvm 前缀
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 输出版本号 |
关键命令模板
远程执行前缀（必需）
bash
export NVM
DIR=/root/.nvm; . $NVMDIR/nvm.sh;
配置 AI 模型（阶段4）
bash
ssh root@
export NVMDIR=/root/.nvm; . $NVMDIR/nvm.sh; openclaw config set models.providers.<名称> --json {
\baseUrl\: \<代理地址>\,
\apiKey\: \\,
\api\: \anthropic-messages\,
\models\: [{
\id\: \claude-sonnet-4-6\,
\name\: \Claude Sonnet 4.6\,
\reasoning\: true,
\input\: [\text\, \image\],
\contextWindow\: 200000,
\maxTokens\: 32000
}]
}
设置主模型
bash
ssh root@ export NVMDIR=/root/.nvm; . $NVMDIR/nvm.sh; openclaw config set agents.defaults.model.primary <名称>/claude-sonnet-4-6
配置飞书通道（阶段6）
bash
ssh root@ export NVMDIR=/root/.nvm; . $NVMDIR/nvm.sh; openclaw config set channels.feishu --json {
\enabled\: true,
\domain\: \feishu\,
\groupPolicy\: \open\,
\appId\: \\,
\appSecret\: \\
}
重启网关（阶段8）
bash
ssh root@ systemctl --user restart openclaw-gateway.service
查看日志
bash
ssh root@ 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 配置有误 |
使用说明
- 1. 先确认用户在哪个阶段或遇到什么错误
- 提供对应的命令模板或解决方案
- 所有远程命令都需要加 nvm 前缀
