【AI+教育】OpenClaw 坏了别慌！新手最常见的 8 个故障，90% 都能自己搞定

这两天，OpenClaw 几乎成了深圳打工人圈子里的“隐形同事”——福田 CBD 的销售用它整理客户跟进表，南山程序员靠它生成接口文档，龙岗的跨境电商从业者拿它批量同步物流单号。GitHub 星标已经突破 30 万，连深圳龙岗区都拟推出“龙虾十条”扶持政策（目前还是征求意见稿），火到这个程度，你不装一个都感觉落伍了。

但不少人第一次上手，遇到的不是“哇好好用”，而是一串红色报错。

说实话，这不是你的问题，也不是 OpenClaw 不好——官方文档明确说过，90% 的新手故障都能在 60 秒内定位。今天这篇文章，就是把那份急救清单用人话重新说一遍。不保证每个问题都能 5 分钟搞定，但至少能让你知道该往哪个方向查。

故障 01｜刚装完就报「command not found」

场景：按教程装好，输完最后一行命令回车——终端蹦出红色报错，明明刚装好，怎么就找不到了？

为什么：安装程序修改了系统的 PATH 环境变量，但当前终端窗口还不知道这件事。就像换了灯泡但电闸没合上，灯当然还是不亮。

怎么修：

• macOS/Linux：执行source ~/.zshrc（或source ~/.bashrc）

• Windows：关掉当前终端，重新开一个窗口

大多数情况，重开终端就解决了。

故障 02｜发了指令，Agent 没反应

场景：发了三次指令，界面一直转圈，显示“正在思考”——就像打电话给客服，对方一直说“请稍候转接”，你不知道是线路断了还是对面在摸鱼。

为什么：API Key 无效、Gateway 没启动、网络限流，都可能导致 Agent 罢工。