05. CLI 入口：openclaw 命令怎么启动

这篇解决什么问题

你在终端输入：

openclaw gateway status

或：

openclaw agent --message "Hello"

到底先跑了什么？

这一篇只看入口，不展开每个子命令。

package.json 指向 openclaw.mjs

package.json 里有：

"bin": {
  "openclaw": "openclaw.mjs"
}

所以 npm 全局安装后，系统里的 openclaw 命令会指向仓库根目录的 openclaw.mjs。

openclaw.mjs 先检查 Node 版本

源码里有：

MIN_NODE_MAJOR = 22
MIN_NODE_MINOR = 19

也就是至少 Node 22.19。

README 推荐 Node 24，或者 Node 22.19+。

如果版本不够，launcher 会打印升级提示并退出。这就是为什么安装前要先确认 Node 版本。

launcher 不只是转发

openclaw.mjs 做了不少启动前工作：

• Node 版本检查；
• 判断是否是源码 checkout；
• 处理 Node compile cache；
• Windows Node 24 compile cache deadlock 规避；
• 子进程 respawn；
• 打包产物和源码运行路径选择；
• 信号转发和退出处理。

它不是业务逻辑核心，但它决定 CLI 能不能稳定启动。

子命令在哪里

真正命令实现不在 openclaw.mjs。

后面会进入：

src/cli/
src/commands/

常见命令对应：

openclaw onboard        → setup / onboard commands
openclaw gateway ...    → gateway-cli / gateway commands
openclaw agent ...      → commands/agent
openclaw doctor         → commands/doctor
openclaw cron ...       → cli/cron-cli

具体文件要按命令名再查。

如果 CLI 启动失败怎么查

先按顺序查：

node -v
which openclaw
openclaw --version
openclaw doctor

如果是源码开发：

pnpm install
pnpm build
pnpm openclaw --version

如果连 openclaw --version 都失败，先不要看 Agent Runtime。问题还在 launcher / Node / 安装层。

实践：CLI 入口自检

用现成命令做一次 3—5 分钟的启动层检查：

node -v
which openclaw
openclaw --version
openclaw doctor

把失败停留在哪一步记下来；如果 openclaw --version 尚未成功，不进入 Runtime 排障。

完成标准

• Node 至少为 22.19；
• 能定位当前执行的 openclaw；
• CLI 能输出版本，或已明确失败发生在 Node、安装还是 launcher 层。

多走一步

如果使用源码 checkout，再运行 pnpm openclaw --version，比较它与全局命令是否指向同一版本。

下一篇看什么

下一篇进入 Agent Runtime。