OpenClaw 装不上或装完命令找不到：按官方文档走一遍安装失败排查路径

2026-08-17

站内工具 AI 编程工具报错分诊器 → 把报错原文贴进去，先分清是网络、额度、配置还是上游故障，再决定往哪个方向查。

安装类问题最难受的地方在于，它很少给你一个干净的失败。你把 curl ... | bash 那一行贴进终端，脚本哗啦啦刷了一屏，最后没有红字，你以为成了；然后新开一个终端敲 openclaw，提示 command not found。或者更隐蔽：命令有了，openclaw status 也能跑，但插件全是灰的，doctor 里蹦出一行 plugin present but blocked。

OpenClaw 官方文档把安装类问题拆在两个地方：一个是 help 下的 troubleshooting 总入口，它的定位是”症状优先的分诊台”，自称两分钟给出诊断方向再跳深页；另一个是 install 下的安装器内部文档，末尾挂着一组针对脚本本身的 troubleshooting 条目。这两处内容不重叠——前者管”装完之后运行不起来”，后者管”装的过程中/装完那一刻就不对”。很多人只翻了其中一处，所以卡住。

这篇把两处按”你实际看到的现象”重排一遍。所有命令、报错原文、路径都取自官方文档，没有实测环节。安装方式本身怎么选，是另一个话题，可以看OpenClaw 该用哪种方式装。

先跑官方那条 60 秒阶梯

troubleshooting 页开门第一节叫 “First 60 seconds”，给了一串按顺序执行的命令，官方的措辞是”run this ladder in order”：

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

这串命令的价值不在于跑，在于文档同时给了每一条的”正常输出应该长什么样”。对照着看，你能一眼知道断在哪一层：

命令	官方给的合格输出
`openclaw status`	列出已配置的渠道，没有 auth 报错
`openclaw status --all`	产出一份完整的、可分享的报告
`openclaw gateway probe`	显示 `Reachable: yes`，`Capability: ...` 是本次探测证明的鉴权级别
`openclaw gateway status`	`Runtime: running`、`Connectivity probe: ok`，以及一个合理的 `Capability: ...`
`openclaw doctor`	不报任何阻断性的配置/服务错误
`openclaw channels status --probe`	网关可达时返回各账号的实时传输状态（`works` / `audit ok`）
`openclaw logs --follow`	活动平稳，没有反复出现的致命错误

有两个细节容易误判。第一，gateway probe 里出现 Read probe: limited - missing scope: operator.read，官方明确说这是”诊断能力受限”，不是连接失败——别把它当成安装没成功。第二，gateway status 可以加 --require-rpc，让它额外要求读作用域的 RPC 证明，不加的时候通过不代表 RPC 层没问题。channels status --probe 在网关不可达时会退化成只读配置的摘要，看起来像”有结果”，其实什么都没探到。

如果这七条里 openclaw status 就直接 command not found，那你的问题在下一节；如果命令都在、只是网关起不来，跳到本文靠后的网关那一节，或者看网关起不来怎么查。

`openclaw` 命令找不到：几乎总是 PATH

安装器文档在正文中间就插了一条提示：如果安装成功但新开终端里找不到 openclaw，去看 Node.js 那一页的 troubleshooting。末尾的折叠条目里也重复了同一句判断——“openclaw not found after install：通常是 PATH 问题”。

Windows 上官方给了具体到命令的处置。看到 openclaw is not recognized，执行：

npm config get prefix

把打印出来的目录加进用户 PATH，然后重开 PowerShell。文档特别标注了一句：Windows 上不需要再加 \bin 后缀。这一条值得记，因为在 macOS/Linux 的习惯里你会下意识补一个 bin，在 Windows 上补了反而不对。

install.ps1 自己也会做一部分 PATH 工作：安装后任务里写明”在可能的情况下把需要的 bin 目录加入用户 PATH”。注意措辞是”when possible”，不是保证。另外 Windows 上如果走到了便携版兜底路径——没有 winget / Chocolatey / Scoop 时，脚本会把官方 Node.js 26 的 Windows zip 下载到 %LOCALAPPDATA%\OpenClaw\deps\portable-node，并加入当前进程和用户 PATH——那么”当前进程”这三个字意味着旧窗口不会自动生效。

不同安装方式的可执行文件落点也不一样，找不到命令的时候按这张表去核实文件到底在不在：

安装方式	可执行文件位置
`install.sh` 走 npm（默认）	全局 npm 前缀下
`install.sh` 走 git	`~/.local/bin/openclaw`
`install-cli.sh`（npm 或 git）	`<prefix>/bin/openclaw`，prefix 默认 `~/.openclaw`
`install.ps1` 走 git	`%USERPROFILE%\.local\bin\openclaw.cmd`

install-cli.sh 在这一点上比另外两个脚本讲究：它装完会跑一次 <prefix>/bin/openclaw --version，拿不到非空版本号就直接报错停下。也就是说这条路上如果脚本说成功了，二进制至少是能启动的，剩下的就只可能是 PATH。

npm EACCES 与 Git 缺失：官方给的两条已知路

Linux 上 npm 报 EACCES，官方的解释是有些环境把 npm 的全局前缀指向了 root 拥有的路径。install.sh 具备把前缀切到 ~/.npm-global 并往 shell rc 文件追加 PATH 导出的能力——但文档带了一个前提条件：“when those files exist”，rc 文件不存在它就不写。install-cli.sh 把同一件事做成了显式开关：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --set-npm-prefix

这个 --set-npm-prefix 的官方说明是：在 Linux 上，当前 npm 前缀不可写时强制改为 ~/.npm-global。

Git 这一侧有个常被误解的点。有人走的是 npm 安装方式，却看到脚本在装 Git，以为脚本跑偏了。官方在”Why is Git required”里写清楚了：git 安装方式当然需要 Git；而 npm 安装方式仍然会检查并安装 Git，目的是避免依赖里出现 git URL 时报 spawn git ENOENT。

Windows 上如果真的撞到 npm error spawn git / ENOENT，官方给两个办法：重跑安装器让它引导安装用户级 MinGit，或者装 Git for Windows 后重开 PowerShell。MinGit 的落点是 %LOCALAPPDATA%\OpenClaw\deps\portable-git，同样会加进当前进程和用户 PATH。文档还补了一句：-InstallMethod git 且 Git 缺失时，脚本会先尝试用户级 MinGit 引导，实在不行才打印 Git for Windows 的链接。

Node 版本与 Alpine 的 SQLite：这两类不是脚本能兜的

安装器文档在最前面就把版本门槛写死了：三个脚本都支持 Node 22.22.3+、24.15+ 或 25.9+，并且明确写了 Node 23 不受支持。macOS 和 Linux 上全新安装会配置 Node 26；Windows 上 winget/Chocolatey/Scoop 装受支持的 Node LTS 线，便携兜底下载 Node 26。你的机器上如果卡着一个 Node 23，脚本按文档是不会认的。

Alpine / musl 是另一类。安装器在 Alpine 上改用 apk 包而不是 NodeSource，并且会校验实际链接的 SQLite 版本。官方原文的意思很直接：当前稳定版 Alpine 包流可能给出一个足够新的 Node，却仍链着有漏洞的系统 SQLite；发生这种情况时，改用官方的 node:26-alpine 容器或者一台基于 glibc 的主机。install-cli.sh 的说法一致，只是对应的容器写的是 node:24-alpine，因为它装的是内嵌固定版本的 Node LTS（默认 24.15.0，Linux ARMv7 上用 22.22.3，理由是官方没有 Node 24+ 的 ARMv7 二进制）。

这两种情况的共同点是：脚本已经把问题告诉你了，但解决办法在宿主机环境，不在安装参数里。继续换参数重试是浪费时间。

排查安装脚本本身：dry-run、退出码、verbose

三个脚本都能在不改动系统的前提下先看它打算干什么：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun

自动化场景里有几条关于失败信号的约定，值得单独拎出来：

install.sh 在安装方式选择非法、或 --install-method 取值非法时，以退出码 2 结束。
install.ps1 通过 iwr ... | iex 或 scriptblock 形式运行时，失败会报一个终止性错误，但不会关掉当前 PowerShell 会话；而直接用 powershell -File / pwsh -File 跑，失败仍会以非零码退出。所以在 CI 里要拿退出码判断成败的，必须用 -File 形式。
install.ps1 会在下载、改 PATH、开始安装之前就拒绝未知选项和位置参数。参数敲错的话，它是提前失败，不是装到一半失败。

想看 Windows 上更细的执行过程，官方说明 install.ps1 用了 CmdletBinding，所以接受 PowerShell 通用的 -Verbose 参数，但安装器目前并没有写专门的 verbose 流。要脚本级诊断只能用 PowerShell 自己的跟踪：

Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

还有一条容易踩的参数陷阱：openclaw@main 这类 GitHub 源码 spec 不是合法的 npm --version 目标，要装 main 分支得写 --install-method git --version main。

装完那一刻脚本在做什么：理解 doctor 为什么没跑

不少人反馈”安装脚本没跑 doctor”或者”没提示我配置”，其实是安装后任务有分支。install.sh 的官方描述是：对于未配置的安装，先进入 onboarding，然后才是 doctor 和网关探测；加了 --no-onboard 或者没有 TTY 时，它会打印稍后完成配置的命令。对于已配置的安装，则是尽力刷新并重启已加载的网关服务，然后跑 doctor。--verify 只在配置已存在之后才检查网关健康。

install.ps1 的分支略有不同：它在升级和 git 安装时跑 openclaw doctor --non-interactive，同样标注为尽力而为。install-cli.sh 则是在检测到网关服务已从同一前缀加载时，执行 openclaw gateway install --force 激活替换后的服务，再尽力探一次网关健康。

所以”doctor 没跑”往往不是失败，是你落在了另一个分支上。手动补一次就是，输出怎么读可以看doctor 体检报告怎么对号入座。

网关起不来：三条日志签名

命令装好了、配置也有了，但服务起不来，troubleshooting 页给了对应的一档。先跑：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

合格输出是 Service: ... (loaded)、Runtime: running、Connectivity probe: ok，以及 read-only / write-capable / admin-capable 三者之一的 Capability。日志里的三条签名对应三种完全不同的原因：

Gateway start blocked: set gateway.mode=local 或 existing config is missing gateway.mode——网关模式是 remote，或者配置缺少 local 模式标记需要修复。
refusing to bind gateway ... without auth——绑到了非回环地址却没有有效的鉴权路径（token/密码，或在支持的场景下的可信代理）。
another gateway instance is already listening 或 EADDRINUSE——端口已被占用。

第三条在刚装完的机器上尤其常见：旧版本的后台进程还在，新装的服务抢不到端口。

插件被拦：装完最容易被当成”没装好”的一类

有三类插件问题会在安装或升级后立刻显形，它们都不是安装脚本的错，但看起来很像装坏了。

一是 package.json missing openclaw.extensions。 官方的解释是这个插件包用了 OpenClaw 已经不再接受的形态。修法在插件包那边：给 package.json 加上 openclaw.extensions，指向构建出来的运行时文件（通常是 ./dist/index.js），重新发布后再执行一次 openclaw plugins install <package>。

{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

二是安装策略把插件更新拦了。 现象是更新跑完了，插件却是旧的、被禁用的，或者出现 blocked by install policy、install policy failed closed、Disabled "<plugin>" after plugin update failure。要查的是 security.installPolicy。这里有个关键机制：@openclaw/* 系列插件的版本通常跟着 OpenClaw 发行版一起走，所以一次 OpenClaw 升级在升级后同步阶段就需要一次匹配的插件更新。官方点名了几种会把自己坑住的策略写法——把 OpenClaw 自带插件冻死在某个精确旧版本；只按来源类型拦（所有 npm、所有网络、所有 request.mode: "update"）；把策略命令当可选项（启用 security.installPolicy 后，策略可执行文件缺失、太慢、读不了或被权限挡住，都会 fail closed）；以及不核对请求里的 openclawVersion 就批准版本。恢复动作是：

openclaw doctor --deep
openclaw plugins update --all
openclaw status --all

如果更新失败已经把插件禁用了，官方建议先查再启用：openclaw plugins inspect <plugin-id> --runtime --json，然后 openclaw plugins enable <plugin-id>。

三是属主可疑被拦。 doctor、setup 或启动告警里出现 blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) 和 plugin present but blocked，含义是插件文件的 Unix 属主跟加载它的进程不是同一个用户。官方明确说：不要删插件配置，去修文件属主，或者改用拥有状态目录的那个用户来跑 OpenClaw。Docker 安装是重灾区，因为容器里以 node（uid 1000）运行，宿主机的 bind mount 属主往往对不上：

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fix

如果你是有意以 root 跑，那要修的是托管插件根目录：

sudo chown -R root:root /path/to/openclaw-config/npm
openclaw doctor --fix

插件体系本身的装法和写法是另一条线，见OpenClaw 插件体系。

还有一类不是”装失败”：助手能力变少了

装完之后觉得助手变笨、工具不全，很容易被归到安装失败里。troubleshooting 页把它单列了一节，起手仍是 openclaw status / openclaw status --all / openclaw doctor，看的是生效的工具画像：tools.profile: "minimal" 只允许 session_status；"messaging" 很窄，是给纯聊天 agent 用的；"coding" 是新建本地配置的默认值，覆盖仓库、文件、shell 和运行时相关的工作；"full" 去掉画像限制，官方建议只给受信任的、由运维方控制的 agent。另外 agents.entries.*.tools 的单 agent 覆盖会在根画像基础上收窄或放宽。改完画像要重启或重载网关，再用 openclaw status --all 复核。

这篇覆盖不到的地方

几件事需要说清楚边界：

第一，--compatible-with <ver> 这个参数在 install-cli.sh 里的定义是”拒绝一个无法修改由 <ver> 写出的配置的 CLI”。它是降级安装时的保护，文档只给了这一句说明，具体触发条件官方文档未展开。

第二，troubleshooting 页的决策树还分出了渠道连上但消息不流转、cron/heartbeat 没触发、节点配对了但工具失败、浏览器工具失败等多个分支，本文只处理了与安装直接相关的那几条，其余各有专门的深页。

第三，也是最重要的一条：官方在本地 OpenAI 兼容后端那一节里写了一个判断——“很小的直连调用能跑通，但 OpenClaw 较大的提示词把后端搞崩了，那是上游模型/服务器的限制，不是 OpenClaw 的 bug”。这个思路适用于整个排查过程。安装脚本能兜的是 Node、Git、PATH、前缀权限这几层；宿主机的 SQLite 链接、插件包自己的打包形态、你写的安装策略、端口被别的进程占着，都不在它的职责范围内。分清这条界线，能省掉大量把安装器反复重跑的时间。

延伸阅读

从头读起：OpenClaw 架构总览：网关、Agent、渠道、节点、插件五层各管什么，出问题该往哪查
本专题共 40 篇，完整分组目录见专题页
openclaw doctor 体检输出怎么读：五种姿态、findings 字段与退出码对号入座
OpenClaw 用 Docker 部署：镜像怎么选、状态存在哪、升级卡住怎么救

本文依据 OpenClaw 官方仓库（github.com/openclaw/openclaw）docs/ 下的官方文档整理，核对日 2026-08-17。 我们没有安装或运行过 OpenClaw，因此不涉及界面外观、操作手感与实测耗时的任何描述；文中的默认值、命令与配置项均为文档口径，不构成对实际运行结果的保证。该项目迭代很快，请以仓库最新内容为准。接入即时通讯平台前，请自行确认所在平台的规则与合规要求。