openclaw-helper

# 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; . "$NVM_DIR/nvm.sh"; ``` ### 配置 AI 模型（阶段4） ```bash 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 }] }"' ``` ### 设置主模型 ```bash ssh root@<IP> 'export NVM_DIR=/root/.nvm; . "$NVM_DIR/nvm.sh"; openclaw config set "agents.defaults.model.primary" "<名称>/claude-sonnet-4-6"' ``` ### 配置飞书通道（阶段6） ```bash 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） ```bash ssh root@<IP> 'systemctl --user restart openclaw-gateway.service' ``` ### 查看日志 ```bash 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 配置有误 | --- ## 使用说明 1. 先确认用户在哪个阶段或遇到什么错误 2. 提供对应的命令模板或解决方案 3. 所有远程命令都需要加 nvm 前缀