OpenClaw 报错了怎么办?新手必备的故障排查自救指南

哈喽各位小伙伴们：

有没有遇到过这种情况：兴冲冲装好了 OpenClaw，敲下启动命令，结果跳出来一串红色报错，心直接凉了半截。

别慌。我用了 OpenClaw 这段时间，红字见过不少，蓝屏也差点见到。今天就把我踩过的坑、学到的排查方法一次性整理出来。

这篇文章不是那种”错误码大全”——那种东西你看都不想看。我用的是症状分类法：你遇到什么问题，直接对号入座，2 分钟找到解法。

一、装都装不上：安装类问题

这是新手最常碰到的坎，也是最好解决的。

症状1：提示 “npm: command not found” 或者 “node: command not found”

原因： 你没装 Node.js，或者装了但系统没认到。

解决：

1. 去 Node.js 官网 https://nodejs.org 下载 LTS 版本（就是左边那个大按钮）
2. 安装时**勾选 “Add to PATH”**，这步很多人跳过去就出事了
3. 装完以后关掉所有命令行窗口重新打开，让环境变量生效
4. 验证：输入 node -v 和 npm -v，能看到版本号就 OK

症状2：npm install 跑到一半报错，出现一堆 ERR!

原因： 通常是网络问题，npm 默认从国外服务器拉包，部分依赖下载超时。

解决（三选一）：

• 换淘宝镜像（推荐）：

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

• 或者用 cnpm：

npm install -g cnpm --registry=https://registry.npmmirror.comcnpm install -g openclaw

• 或者挂代理（如果你有）：

npm config set proxy http://127.0.0.1:你的端口

症状3：装了以后输入 openclaw，系统说”不是内部或外部命令”

原因： npm 全局安装路径没加到系统 PATH。

解决：

1. 运行 npm root -g，看全局模块装在哪（通常是 C:\Users\你的用户名\AppData\Roaming\npm）
2. 把这个路径加到系统环境变量的 Path 里面
3. 重启命令行窗口

症状4：Windows 上 PowerShell 执行策略拦截

原因： PowerShell 默认禁止运行脚本。

解决：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

输完按 Enter，选 Y 确认。

二、配置卡壳：模型和渠道类问题

东西装好了，但死活跑不起来，往往是这层出了问题。

症状1：启动后报 “API key not configured” 或者模型调用失败

原因： 没配置模型，或者 API Key 写错了。

解决：

1. 检查你用的模型提供商有没有给你 API Key（不是网页版的登录密码，是开发者后台那种）
2. 确认 Key 没有过期，额度没有用完
3. 在 OpenClaw 配置里找到 models 部分，确保 provider 和 key 都填对了
4. 一个容易被忽略的点：API Key 前后不要有空格或换行

症状2：选好了模型但回复乱七八糟，甚至全是英文

原因： 有些模型对中文支持不好，或者模型选择的不是 chat 模型。

解决：

• 把 default model 换成明确支持中文的（DeepSeek、Qwen、GLM 等国产模型都可以）
• 避免选 code 模型或 instruct 模型来聊天，它们不是干这个的

症状3：配了渠道但收不到消息

原因： 渠道配置有问题，或者渠道插件没装。

解决：

1. 先确认渠道对应的插件装没装（比如微信要装 @tencent-weixin/openclaw-weixin）
2. 检查配置里 channel 的拼写和参数
3. 看看官网文档该渠道的接入前提（比如微信需要 iLink Bot 插件）
4. 所有渠道都先在本机测通再给别人用，别一上来就发群里

三、启动就崩：运行时问题

症状1：启动马上退出，什么错误都没看到

原因： 配置文件有格式错误，进程启动就 crash 了。

解决：

1. 手动运行 OpenClaw 的命令，不要通过快捷方式
2. 看终端输出的最后几行，通常会有报错信息
3. 如果是 JSON/YAML 配置格式错误，去在线 JSON 校验工具粘贴你的配置文件看看哪不对
4. 少个逗号、多个空格这种事真的会崩，别问我怎么知道的

症状2：提示端口被占用

原因： 默认端口（通常是 18789）被其他程序占了。

解决：

1. 找谁占的端口：

netstat -ano | findstr :18789

1. 记下输出的 PID，用任务管理器杀掉那个进程
2. 或者在 OpenClaw 配置里换一个端口

症状3：CCA（自定义头像/配色）显示不正常

原因： 图片格式不支持或路径写错了。

解决：

• 头像图用 PNG 或 JPG，不要用 WebP
• 路径用绝对路径或者相对 workspace 的路径
• 图片别太大，控制在 1MB 以内
• 颜色值确认是 6 位 hex 格式（如 #FF6600），别漏了 # 号

症状4：整个配置看起来没问题但就是不行

原因： 可能是某个 Skill 与当前版本不兼容。

解决：

1. 把所有自定义 Skill 先禁用
2. 一条一条启用，定位是哪个 Skill 出问题
3. 搜索式排查思维： 原理很简单——二分法缩小范围，别一上来全改
4. 如果是新装的 Skill 导致崩溃，卸载它或者看看它有没有兼容性说明

四、渠道折腾：平台接入问题

症状1：微信扫了码但连不上

原因： 微信 iLink Bot 插件的扫码有时间限制，或者网络环境问题。

解决：

1. 确保电脑和手机在同一个网络下（或者你配好了穿透）
2. 扫码要在二维码刷出来的 2 分钟内完成
3. 如果一直失败，重启 OpenClaw 重新生成二维码
4. 家用路由器偶尔会阻断某些端口，换手机热点试试

症状2：其他渠道（Telegram / Discord）配了没反应

原因： Bot Token 没填对，或者 Bot 没有被正确添加到目标群/频道。

解决：

1. 确认 Token 是 Bot 的 Token，不是你的用户 Token
2. Telegram 的 Bot 需要先在 @BotFather 创建，拿到的 Token 才是对的
3. Discord 的 Bot 需要在开发者后台配置好 Intents 和权限
4. 把 Bot 拉到群里后，先在群里 @它 发一条消息测试

症状3：有时能收到消息，有时收不到

原因： 大概率是网络不稳定，或者 Bot 被平台限流了。

解决：

1. 检查你的网络环境，尤其是用代理的时候
2. 确认 API 调用频率没有超过平台限制（比如 Telegram 每秒最多 30 条）
3. OpenClaw 本身有重试机制，不需要额外配置

五、终极自救心法

上面这么多问题，不可能全部记住。但只要你掌握这三个排查原则，大部分问题自己就能解决：

1. 看日志，别看心情。

90% 的问题，第一行报错信息已经把答案告诉你了。不要一看到红字就慌，先冷静读完那句英文在说什么。

2. 二分法定位。

不知道哪个环节出问题 → 先回到”最简配置” → 只保留核心功能 → 逐步加回来。这和修电脑的”最小系统法”是一个道理。

3. 复制报错去搜索。

把报错信息里最关键的那句（不含你个人路径的部分）直接复制到搜索引擎。你遇到的问题，90% 别人也遇到过。

好了，这篇”自救指南”就到这。说实话，玩 OpenClaw 到现在，报错才是最好的老师——你搞明白一个报错，就多懂一层原理。

下一期我打算聊聊怎么用 OpenClaw 搞零代码自动化，不用写一行代码，让 AI 帮你自动处理重复性工作。感兴趣的等我更新。

有问题评论区见，我能回的都会回。