ClawStart 排障中心

遇到问题？按现象快速找到解决办法

安装过程中遇到报错很正常，大部分问题都有现成的解决方案。
先判断你是打不开、装不上、模型连不上，还是运行后出问题，再做最短动作。

🔧 先做这三件事
1. 确认你是按平台页的一键包路径在操作
2. 回到 快速开始 看自己卡在第几步
3. 再到下面按“打不开 / 连不上 / 配不好”分类排查

先看你卡在哪一类

先判断属于"打不开""安装失败""模型连不上"还是"运行后报错"，一次只排查一个方向，效率最高。

找到最短解决路径

一键包用户先处理权限、杀软、路径问题。只有明确走命令行安装时，才需要继续看 Node、Git、CLI 和 npm 错误。

按现象选入口，快速定位

入口 1

打不开 / 启动失败

适合 macOS 安全拦截、Windows SmartScreen、杀软拦截、双击没反应这类问题。
入口 2

安装失败 / 依赖报错

适合 Git 权限错误、npm 依赖损坏、找不到命令、文件缺失这类问题。
入口 3

模型连不上 / API Key 不通过

适合网络不通、Key 错误、余额问题、代理或证书环境干扰这类问题。
入口 4

运行后出问题

适合端口占用、内存过高、技能安装异常，以及消息渠道接入不稳定这类问题。

🔌 打不开 / 启动失败

macOS 提示"无法验证开发者"或"已损坏"

这是 macOS Gatekeeper（系统自带的安全验证机制）在起作用。两种解决方式：

方式一：前往「系统设置 → 隐私与安全性」，找到被拦截的应用，点击「仍要打开」。

方式二：在终端执行：

xattr -cr "/你的解压目录"

如果你走的是一键包路径，不需要先把它装进系统目录，优先对当前解压目录执行上面的命令即可。

Windows SmartScreen（系统安全拦截）弹窗

弹出"Windows 已保护你的电脑"时，点击「更多信息」→「仍要运行」。这是 Windows 对未签名程序的正常拦截。OpenClaw 是开源软件，源码可在 GitHub 查看。

Windows SmartScreen 或杀毒软件反复拦截

这通常不是安装包本身坏了，而是系统把“第一次出现的未签名文件”当成风险项。

  • 将当前一键包解压目录加入信任列表
  • 关闭仍在占用文件的旧进程后再试
  • 用管理员权限重新运行启动器

📦 安装与依赖错误

出现 Git SSH 权限错误或 exit 128

常见关键词包括 permission denied (publickey)、git@github.com、exit 128。这通常表示当前机器没有正确处理 GitHub 拉取权限。

先确认 Git 已安装，再把 Git 拉取方式切到 HTTPS：

git --version git config --global url."https://github.com/".insteadOf ssh://git@github.com/ git config --global --add url."https://github.com/".insteadOf git@github.com:
出现 EPERM / operation not permitted

这通常表示文件被占用、被杀软拦截，或当前终端权限不足。

  • 关闭仍在运行的旧 Gateway 或相关进程
  • 临时关闭杀软实时防护后重试
  • 用管理员权限重新打开终端或启动器
出现 ENOENT / -4058 / cannot find module

这表示文件没写完整、目录异常，或上次安装被中断了。

如果你走的是命令行安装路径，先清理 npm 缓存，再重新安装OpenClaw 核心程序：

npm cache clean --force npm install -g openclaw

如果你走的是一键包路径，优先重新下载并解压到一个新的空目录，不要覆盖旧目录。

出现 native binding / engine / unsupported

这类错误通常意味着必要组件没装完整，或者 Node.js 版本太低。

  • native binding：先重装OpenClaw 核心程序
  • engine / unsupported：先升级 Node.js 到当前要求版本以上

如果你只是想最快用起来，建议优先回到一键包路径，不要继续手动折腾命令行环境。

安装后找不到 openclaw 命令

只有你明确走了命令行安装路径，才需要处理这个问题。一键包用户不需要手动调用 openclaw 命令。

关闭并重新打开终端窗口。如果仍然找不到：

# 检查 npm 全局路径 npm config get prefix # 确认该路径在 PATH 中 echo $PATH # 如果不在，手动添加 export PATH="$(npm config get prefix)/bin:$PATH"

🤖 模型连不上 / API Key 不通过

API Key 测试失败

检查以下几点：

  • API Key 是否正确复制（注意前后空格）
  • API Key 是否已过期或被禁用
  • 账户余额是否充足
  • 网络是否能访问对应的 API 地址
# 手动测试 API 连通性 curl https://api.openai.com/v1/models \ -H "Authorization: Bearer YOUR_API_KEY"
国内网络无法连接 OpenAI / Anthropic

几种解决方案：

  • 使用国内模型（豆包、通义千问、文心一言）
  • 使用 API 中转服务，修改 baseUrl
  • 使用本地模型（Ollama + 开源模型）
# 配置自定义 API 地址 openclaw config set providers.openai.baseUrl "https://your-proxy.com/v1"
出现 etimedout / econnreset / 证书错误

这通常是网络、代理、证书或公司环境限制，不一定是模型本身有问题。

  • 先切换网络后再试
  • 临时关闭代理或 VPN 后重试
  • 优先使用国内模型或国内镜像
# 如果是 npm 证书问题，可临时关闭严格 SSL npm config set strict-ssl false
模型响应很慢或超时
  • 尝试换一个模型或服务商
  • 缩短对话上下文长度
  • 调整超时：openclaw config set requestTimeout 60000

⚙️ 运行时问题

Gateway 启动失败，端口被占用
# 查看谁占用了端口 lsof -i :3100 # macOS / Linux netstat -ano | findstr :3100 # Windows # 修改运行端口 openclaw config set port 3101 openclaw gateway restart
内存占用过高
  • 重启 Gateway：openclaw gateway restart
  • 减少同时活跃的会话数量
  • 清理历史：openclaw sessions prune --older-than 7d
技能安装失败
  • 网络问题：检查是否能访问 GitHub / npm
  • 权限问题：确保工作目录有写入权限
  • 版本冲突：openclaw skills update --force

📱 进阶渠道问题

Telegram Bot 收不到消息
  • Bot Token 是否正确
  • 是否已向 Bot 发送 /start
  • Gateway 是否正在运行：openclaw status
  • 查看日志中是否有 Telegram 相关错误
微信连接不稳定

微信接入是实验性功能。建议：

  • 保持手机微信在线
  • 不要在其他设备登录同一微信号
  • 如果频繁掉线，考虑用 Telegram 作为主要渠道

寻求更多帮助

按上面试了 5 分钟还没解决，就别继续单打独斗啦

我们准备了几个遇到安装问题时的交流通道。欢迎带着报错截图来找大家帮忙，一定能快速帮你把 AI 助手跑起来。

求助时请带上

系统版本 + 当前步骤 + 报错截图 + diagnostic.txt（如果你已经跑过诊断）。这样无论是群里公开答疑还是私聊小助手一对一排查，解决效率都会高很多。

1 对 1 帮助

企业微信

最适合处理“各种疑难杂症”、“需要看截图”、“想进群交流”的场景。

  • 复杂报错
  • 发图求助
  • 进交流群
找小助手 回到快速开始 →
新手围观

QQ 交流群

适合把错误提示、系统环境和操作截图发出来，让更多群友一起帮你判断。

进公开群
高频互动

微信大群

适合快速讨论各类运行报错和连通性问题，大家在这里分享经验互助解决。

扫码进群
💼

添加企业微信

添加后可获得1对1答疑支持，优先解决安装和配置问题

二维码

打开微信/QQ扫码即可加入

👋 加入用户社区

遇到问题优先看 排障页