前言

OpenClaw 是一个非常灵活的本地/自托管 AI 中枢：既可以接入多家模型（官方 + 中转），又能连接飞书、钉钉、企业微信、Slack、Telegram 等协作工具，还支持自定义 Agent 和 Skill。

但功能一多，第一次上手时难免会遇到各种问题：安装报错、端口冲突、模型调用失败、机器人不回消息、配置改完不生效……

这篇文章不讲概念，专门帮你总结「在使用 OpenClaw 时常见的问题与解决方法」，你可以当作一本小小排障手册，遇到问题就对照查一查。

一、安装与启动阶段的常见问题

问题 1：openclaw 命令找不到 / 无法识别

现象：

  • 终端执行 openclaw 提示「command not found」或「不是内部或外部命令」。

可能原因：

  1. 没有通过 npm 全局安装 OpenClaw。
  2. Node/npm 安装不完整或 PATH 没配置好。
  3. Windows 上全局路径没有加入环境变量。

解决方法：

  1. 确认已经安装：

    npm install -g openclaw

  2. 检查 openclaw 是否在 PATH 中：

    • Linux/macOS：

      which openclaw

    • Windows (PowerShell)：

      where openclaw

  3. 如果找不到：

    • 检查 Node/npm 是否安装、版本是否兼容（一般 Node 18+ 比较稳）
    • 检查 npm 全局安装路径是否在 PATH 中（Windows 尤其注意）

问题 2：openclaw gateway start 后无法访问 Web 界面

现象：

  • Gateway 启动看起来正常，但浏览器访问 http://localhost:端口 失败。
  • 或远程服务器部署后，外网访问不到。

可能原因：

  1. 端口被占用（比如 3000、8787 等）。
  2. 防火墙 / 安全组未放行该端口。
  3. 绑定的地址仅为 127.0.0.1，而你从外网访问。

解决方法：

  1. 确认 Gateway 状态：

    openclaw gateway status

  2. 查看端口使用情况（以 3000 为例）：

    • Linux/macOS：

      lsof -i:3000

    • Windows (PowerShell)：

      netstat -ano | findstr 3000

    如果被其他进程占用，换一个端口或者关掉对应服务。

  3. 服务器部署时：

    • 在云服务商（阿里云、腾讯云、AWS 等）的安全组中开放对应端口。
    • 确认 OpenClaw 配置中绑定的是 0.0.0.0 或期望的 IP，而不是只监听本地。

问题 3：升级 Node/npm 后 OpenClaw 报错

现象：

  • 之前能用，升级 Node 后启动报某些模块错误/版本不兼容。

解决方法：

  1. 先卸载原来的 OpenClaw：

    npm uninstall -g openclaw

  2. 清理 npm 缓存（可选）：

    npm cache clean --force

  3. 再重装：

    npm install -g openclaw

  4. 如果是源码方式安装，建议删除 node_modules 后重新 npm install。

二、模型与中转 API 相关问题

问题 4：调用模型时报 401 / 403（未授权）

现象：

  • Chat/Agent 无法返回结果，日志里有「Unauthorized / 401 / 403」相关错误。
  • 你正在使用 OpenAI 或某个中转 API。

可能原因：

  1. API Key 配错 / 过期 / 被禁用。
  2. 配置中引用的环境变量未生效。
  3. 使用了错误的 Header 或认证方式（尤其是兼容 API）。

解决方法：

  1. 检查配置中模型 provider 的 apiKey 设置：

    • 推荐使用：

      "apiKey": "env:MY_PROXY_API_KEY"

    然后在环境中设置：

    export MY_PROXY_API_KEY="真实的 key"

  2. 确认 OpenClaw 的运行环境能读取到该环境变量：

    • systemd / Docker 请在对应配置里加上 Environment= 或 env。

  3. 对于中转服务：

    • 确认它使用的是 Authorization: Bearer xxx 标准写法；
    • 如果要求自定义 Header（如 X-API-Key），需要在 provider 配置中支持自定义 header（按 OpenClaw 文档设置）。

问题 5：调用中转 API 报 404 / 405 / 500

现象：

  • 通过中转的模型调用报 404/405/500。
  • 官方 API 正常，中转不正常。

可能原因：

  1. baseUrl 配错（比如少了一层 /proxy/openai/v1）。
  2. 中转期望的路径不是 /v1/chat/completions，而是其他前缀。
  3. 中转服务本身内部错误。

解决方法：

  1. 对照中转服务文档确认 baseUrl：

    • 有的写法是：

      https://your-proxy.example.com/v1

    • 有的写法是：

      https://your-proxy.example.com/proxy/openai/v1

    要和文档完全一致。

  2. 用 curl 直接访问中转接口，验证：

    curl https://your-proxy.example.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

    如果 curl 都失败，说明问题在中转服务本身或网络上。

  3. 检查 OpenClaw 中 provider 的 baseUrl 与实际 curl 使用的是否一致。

问题 6：模型别名不起作用 / 用别名报错

现象：

  • 配置了 aliases，在 UI 或 Agent 里用别名时报「模型不存在」。

可能原因：

  1. aliases 没写对：格式应该是 别名: "provider/model-id"。
  2. provider 下未定义对应 models 条目。

解决方法：

  1. 检查配置示例：

    {
  "models": {
    "providers": {
      "my_proxy": {
        "kind": "openai-compatible",
        "baseUrl": "https://your-proxy.example.com/v1",
        "apiKey": "env:MY_PROXY_API_KEY",
        "models": {
          "cheap-gpt": {
            "name": "gpt-4o-mini",
            "maxTokens": 16000
          }
        }
      }
    },
    "aliases": {
      "cheap-gpt": "my_proxy/cheap-gpt"
    }
  }
}

  2. 确认当前会话中，模型设置为 cheap-gpt，而不是写错成 cheap_gpt 等。

三、连接飞书 / 钉钉 / 企业微信等协作工具的常见问题

问题 7：飞书事件订阅 URL 验证失败

现象：

  • 在飞书开放平台填写事件订阅 URL 时，一直显示「验证失败」。

可能原因：

  1. OpenClaw 部署在内网，飞书无法访问。
  2. Nginx / 反向代理没有把指定路径转发到 OpenClaw。
  3. OpenClaw 中没有启用飞书 channel 或 endpoint 写错。

解决方法：

  1. 从外网机器或手机网络测试访问你的 URL：

    curl -i https://your-openclaw-server.com/feishu/webhook
    • 如果完全连不上：检查域名解析、防火墙、端口。
    • 如果 404 / 500：说明能到你的服务器，但内部路由有问题。

  2. 检查 Nginx 配置：

    • 是否有类似：

      location /feishu/webhook {
  proxy_pass http://127.0.0.1:网关端口/feishu/webhook;
}

  3. 确认 OpenClaw 配置的飞书 channel：

    • enabled: true
    • endpoint 和你在飞书后台填的路径一致。

问题 8：飞书机器人验证通过，但群里 @不回消息

可能原因：

  1. 权限不完整：没有「读取消息」或「发送消息」权限。
  2. 只订阅了私聊事件，没有订阅群聊/被@事件。
  3. 群里并没有真正使用「@机器人」，只是打字。

解决方法：

  1. 检查飞书应用后台的「权限管理」：

    • 是否勾选消息相关权限，并已通过管理员审核？

  2. 检查事件订阅有没有选：

    • 群消息事件
    • 被 @ 机器人的事件

  3. 在群里使用飞书的「@」操作，选择机器人头像，不要只打字。

  4. 查看 OpenClaw 日志，确认是否收到飞书推来的事件。

问题 9：钉钉 / 企业微信回调加解密失败

现象：

  • 钉钉或企业微信的回调 URL 验证不通过，日志里有「签名错误 / 解密失败」。

可能原因：

  1. Token / AES Key / EncodingAESKey 填错或多了空格。
  2. 企业微信/钉钉控制台里改过配置，但 OpenClaw 的配置没更新。

解决方法：

  1. 在企业微信/钉钉后台重新复制 Token 和 AESKey，避免手动输入。
  2. 确认 OpenClaw 配置中对应字段完全一致，无多余空白。
  3. 重新重启 Gateway 并在控制台重新发起验证。

四、配置变更不生效 / 行为异常

问题 10：改了配置，但行为没变

现象：

  • 修改了模型、channel、agent 的配置，但实际使用中仍然是旧配置。

可能原因：

  1. 只修改了文件，没有通过 config.patch 或重启 Gateway。
  2. 改错了配置文件位置（正确路径不是你编辑的那个）。
  3. 浏览器 / 客户端缓存了旧信息（尤其是前端 UI）。

解决方法：

  1. 优先使用：

    openclaw gateway config.patch --file your-config.json

    让系统帮你合并并重启。

  2. 确认你编辑的配置文件确实是 OpenClaw 正在使用的那一个（可用 config.get 查看当前实际配置内容）。

  3. 刷新浏览器，重开对话，看新配置是否生效。

五、性能与稳定性问题

问题 11：响应变慢 / 偶尔超时

可能原因：

  1. 模型/中转服务本身限流或延迟高。
  2. 部署服务器带宽/CPU 不足。
  3. 日志堆积、磁盘快满等导致 I/O 阻塞。

解决方法：

  1. 先用 curl 直接测一下模型接口响应时间，排除 OpenClaw 以外的问题。
  2. 检查服务器：
    • CPU、内存、磁盘使用情况。
    • 是否有多进程/多服务竞争资源。
  3. 减少不必要的日志级别或定期清理日志。

问题 12：内存占用偏高

可能原因：

  1. 开了很多并发会话 / 子进程 / 多个模型后端。
  2. 使用了大模型 + 长上下文，持续堆积上下文历史。

解决方法：

  1. 控制并发会话数量，适当关掉不再使用的 Agent/子任务。
  2. 调整默认模型为轻量模型（例如中转里的 mini 模型）。
  3. 定期清理或缩短历史上下文长度（视具体设置而定）。

六、总结

OpenClaw 的能力很强，但也因此带来较多配置与集成场景。这篇文章主要帮你从实战角度梳理了使用过程中常见的问题和解决思路，包括：

  • 安装与启动阶段：命令找不到、端口访问不了
  • 模型与中转 API：401/403 未授权，404/500，模型别名问题
  • 连接飞书/钉钉/企业微信：URL 验证失败、机器人不回复、加解密错误
  • 配置变更不生效、响应慢、资源占用高等运行问题

你可以把这篇当作「常见问题排查指南」，遇到问题时先按模块对照，很多坑其实都具有共性：网络、权限、配置、环境变量、回调 URL、签名/加密等。

Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

从基础算法到机器学习的研究轨迹

本文介绍了Python编程学习路径及多个专业软件包推荐。从基础算法学习推荐sortingx排序库开始，到optimtool优化算法库、perming神经网络训练工具，再到porgo全局优化算法。高级应用部分介绍了stkan变分自编码器和KAN模型工具、ctdecon细胞类型反卷积工具，以及mmspao多组学融合软件。每个工具都提供了安装命令和适用场景说明，涵盖从编程基础到机器学习、生物信息学等多个

avatar AtomGit开源社区
cover

【Spring Boot 接通义千问，5 分钟跑通第一个 AI 对话 】

avatar AtomGit开源社区
cover

别再把“强推理模型”混为一谈：强 CoT、强 Agent 与 Harness 的真实分工（GPT-5.4 生成）

avatar AtomGit开源社区