OpenClaw 中文文档

Appearance

常见问题与故障排除 ​

收集了安装和使用 OpenClaw 过程中常见的问题和解决方法。

安装问题 ​

npm 安装 openclaw 很慢 ​

解决方法：使用淘宝镜像加速：

bash
npm config set registry https://registry.npmmirror.com/

然后重新安装：

bash
npm install -g openclaw@latest

权限错误 EACCES ​

全局安装时出现权限错误：

Error: EACCES: permission denied, mkdir ...

解决方法：

bash
npm install -g openclaw@latest --unsafe-perm

或者配置 npm 使用全局目录在用户目录：

bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

然后重新安装。

openclaw: command not found ​

安装完成后提示命令找不到：

原因：npm 的全局 bin 目录不在 PATH 中。

解决方法：

  1. 找到 npm 全局目录：

    bash
    npm config get prefix

  2. 将输出的 bin 目录添加到 PATH：

    bash
    echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

启动问题 ​

端口 18789 被占用 ​

启动时报错：listen EADDRINUSE: address already in use :::18789

解决方法：使用其他端口启动：

bash
openclaw gateway --port 28789

如果使用 systemd，编辑服务文件修改端口。

飞书回调 404 错误 ​

飞书事件回调返回 404：

检查点：

  1. baseUrl 配置是否正确
  2. 端口是否正确，防火墙是否开放
  3. webhook 路径是否正确：/v1/webhook/feishu

正确的回调地址格式：

https://your-domain:18789/v1/webhook/feishu

飞书挑战验证不通过 ​

常见原因：

  1. App ID 或 App Secret 配置错误
  2. 网络不通，OpenClaw 无法访问飞书 API

解决方法：

检查 config.json 中的 appId 和 appSecret 是否与飞书开发者后台一致。

运行问题 ​

消息发出去没有回复 ​

排查步骤：

  1. 检查网关是否运行：

    bash
    ps aux | grep openclaw

  2. 查看日志：

    bash
    tail -f ~/.openclaw/openclaw.log

  3. 检查通道是否启用：

    bash
    openclaw channels list

    确认你的通道 enabled: true。

  4. 检查白名单： 如果配置了 allowFrom，确认你的用户 ID 在列表中。

AI 找不到技能文件 ​

原因：技能目录结构不对，或者路径错误。

解决方法：

技能必须放在 ~/.openclaw/workspace/skills/技能名/SKILL.md，确认目录结构正确。

opencli doctor 提示 "Extension not installed in any browser" ​

原因：Playwright MCP Bridge 扩展没有安装在你的 Chrome 中，或者 token 不正确。

解决方法：

  1. 在本地 Chrome 应用商店搜索 "Playwright MCP Bridge" 安装扩展
  2. 打开扩展选项，点击 "Generate Token"
  3. 在服务器执行 opencli setup，粘贴 token
  4. 验证：opencli doctor

opencli 返回空表格，所有单元格都是空的 ​

常见原因：

  1. 浏览器可执行文件找不到：

    Error: "chrome" executable not found

    解决：安装 Chromium 并设置环境变量：

    bash
    # Debian/Ubuntu
sudo apt install -y chromium
    bash
    export OPENCLI_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium

  2. 没有配置 browser: true： 如果站点需要 JavaScript 渲染，必须在 yaml 配置中添加：

    yaml
    domain: zhihu.com
browser: true

    修改后重新编译：

    bash
    npm run build

Git 克隆 GitHub 超时 ​

国内访问 GitHub 经常超时，解决方法：

  1. 配置 Clash 代理：

    bash
    git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

  2. 使用 GitHub 镜像： 将 https://github.com/user/repo.git 替换为 https://mirror.ghproxy.com/https://github.com/user/repo.git

  3. TLS 握手失败： 切换 Clash 代理节点重试，有些节点不稳定。

网络问题 ​

GitHub 克隆报错 HTTP2 framing layer ​

fatal: unable to access '...': Error in the HTTP2 framing layer

解决方法：配置 git 全局代理强制走 Clash：

bash
git config --global http.proxy socks5://127.0.0.1:7890
git config --global https.proxy socks5://127.0.0.1:7890

或者强制使用 HTTP/1.1：

bash
git config --global http.version HTTP/1.1

GnuTLS handshake failed ​

GnuTLS, handshake failed: The TLS connection was non-properly terminated.

原因：代理节点不稳定。

解决方法：通过 Clash API 切换到其他节点后重试。

Debian 13 特定问题 ​

pip 安装报错 externally-managed-environment ​

error: externally-managed-environment
× This environment is externally managed

原因：Debian 13 默认不允许 pip 修改系统 Python。

解决方法：安装时添加 --break-system-packages 参数：

bash
pip install --break-system-packages package-name

which chromium 找不到命令 ​

Debian 13 中 apt install chromium 只是占位符，不会实际安装。

解决方法：使用 snap 安装：

bash
sudo snap install chromium

然后设置环境变量：

bash
export OPENCLI_BROWSER_EXECUTABLE_PATH=/snap/bin/chromium

还有问题？ ​

如果这里没有解决你的问题，可以：

  1. 查看网关日志：tail -f ~/.openclaw/openclaw.log
  2. 去 GitHub 提交 issue：https://github.com/openclaw/openclaw/issues
  3. 加入 Discord 社区提问：https://discord.com/invite/clawd