安装阶段最常见的问题，通常并不是 OpenClaw 本身“坏了”，而是运行时、PATH、守护进程安装或状态目录权限没有对齐。真正有效的排查方式，不是第一时间删目录重装，而是先把基础层一层层确认清楚。
安装问题最常集中在哪几层
最常见的根因通常是：
- Node 版本不满足要求
openclaw已安装，但 PATH 没带上全局目录- Gateway 服务没接管成功
- 状态目录权限异常
- 升级后存在迁移问题
你可以把安装问题粗略分成三类：
- 根本没装起来
- 装上了，但命令不可用
- 命令可用，但服务没跑起来
先分清属于哪类，后面排查会快很多。
推荐的第一轮排查命令
node -v
openclaw doctor
openclaw gateway status
这三步分别在确认：
node -v：底层运行时是否达标openclaw doctor：安装、迁移和常见修复项是否存在异常openclaw gateway status：服务是不是真的已经在运行
如果你只记得一套最小排查动作，就先记住这三个。
先按现象来判断问题落点
下面这组“现象对照”很实用：
- 安装命令执行时就报错：先看 Node、npm 和网络
- 安装完成后找不到
openclaw：先看 PATH openclaw能运行但 Dashboard 打不开：先看 Gateway 服务- 升级后突然异常：先看
doctor和迁移 - 某些目录报权限错误：先看状态目录和历史
sudo
很多人排障慢，不是因为不会排，而是一开始就没把问题落到正确层级。
常见问题 1：Node 版本不对
现象通常是：
- 安装阶段报依赖错误
- 命令可以装上，但运行不稳定
- 某些功能或插件异常
先检查：
node -v
如果版本明显偏旧，先把 Node 问题解决，再继续看 OpenClaw 本身。因为只要运行时不对，后面很多报错都会变成噪音。
常见问题 2：命令装上了，但终端找不到 openclaw
这通常是 PATH 问题，不一定是 OpenClaw 没装成功。先确认：
- CLI 是否真的完成安装
- 当前 shell 是否重新加载
- 全局 npm/bin 目录是否在 PATH 里
不要一看到 command not found 就直接判断安装包坏了。很多时候只是当前终端还没拿到正确路径。
常见问题 3：服务没有正确启动
如果你用的是：
openclaw onboard --install-daemon
或者：
openclaw gateway install
装完后却发现控制台打不开，先看：
openclaw gateway status
openclaw logs --follow
比起盲目重复安装，这更容易判断是服务没接上、端口没监听，还是进程刚启动就报错退出。
常见问题 4：升级后变得不对劲
升级问题通常更适合先跑：
openclaw doctor
因为它更清楚当前状态目录、配置结构和迁移路径。很多看起来像“安装坏了”的问题，其实是迁移没完成，或者旧配置和新版本预期不一致。
常见问题 5：权限或状态目录异常
这类问题最容易发生在：
- 不同用户混着运行
- 某次安装用了
sudo - 旧状态目录遗留了错误拥有者
这时候不要直接乱删目录，先让 doctor 和日志告诉你到底是哪一层权限出了问题。尤其是“昨天能用，今天升级后不行”的情况，很常见就是目录拥有者不一致。
常见问题 6：Dashboard 或本地页面打不开
这类现象经常被误判成“没安装成功”，但它更可能是服务层问题。优先确认：
- Gateway 是否真的启动
- 监听端口是否已经占用
- 当前访问的是不是正确地址
- 服务是否启动后立刻退出
如果 CLI 正常、但页面打不开，排查重点应该从“安装”切换到“服务运行”。
一个更稳的排查顺序
推荐按下面顺序走：
- 先确认运行时
- 再确认 CLI 是否可用
- 再确认服务状态
- 再确认日志里有没有明确报错
- 最后才考虑删目录或重装
这个顺序会比“遇到问题先重装”稳定得多。
新手最容易踩的两个坑
一装不上就反复重装
如果根因是 Node、PATH 或权限，反复重装通常不会有帮助，只会让状态越来越混乱。
混用不同用户执行
比如第一次用普通用户，后面某步用了 sudo，结果状态目录和构建目录权限开始错位。后面很多“莫名其妙”的错误，都是从这里开始的。
安装排障的关键，不是动作多，而是顺序对。先确认运行时，再确认命令入口，再确认 Gateway 服务，最后才动重装思路。只要前面这三层没看清，删目录和重装大概率只是在重复制造新变量。