🐸 青蛙编程网
首页 / AI / OpenClaw / 2. 安装与首次引导

2. 安装与首次引导

这是什么：安装（install）+ 引导（onboard） = 把 OpenClaw 的 CLI 装到机器上，跑一遍 openclaw onboard 配好模型和工作区，再让它以后台服务常驻。

为什么用：上一章知道了 OpenClaw 是什么，但概念再美也得先落地成「一个能敲 openclaw --version 的命令」。这一步装完，你手上就有一个随时能指挥的助手。

如何用：本章从 Node 版本要求讲起，用三条命令完成安装，再走完引导流程，最后用 openclaw doctor 和 openclaw gateway status 确认一切正常。

2.1 环境要求：Node 版本卡得很死

OpenClaw 对 Node 的要求是硬门槛，装错版本会在装的时候就报错：

node --version

你会看到（示意）：

v26.1.0

合法范围是 >=24.16.0 <25 || >=26.1.0——也就是 Node 24.16+ 或 Node 26.1+，官方推荐 Node 26。npm 包 openclaw 当前版本 2026.10.5，许可 MIT。

macOS / Linux / WSL2 上的安装脚本会检测系统，缺 Node 时自动装 Node 26（macOS）或 Node 24 LTS（Linux）。Windows 优先用原生 Windows Hub 应用；也可用 PowerShell 脚本，或 WSL2 跑 Gateway。

2.2 三条安装命令

① 安装脚本（最省事）——macOS / Linux / WSL2：

curl -fsSL https://openclaw.ai/install.sh | bash

你会看到（示意）：

==> Checking Node.js... found v26.1.0
==> Installing openclaw@2026.10.5 (npm global prefix: /usr/local)
==> Launching OpenClaw onboarding...

Windows PowerShell：

iwr -useb https://openclaw.ai/install.ps1 | iex

你会看到（示意）：

Checking Node.js... found v24.16.0
Installing openclaw@2026.10.5
Launching OpenClaw onboarding...

② npm（你自己管 Node）：

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

你会看到（示意）：

added 312 packages in 24s

OpenClaw Setup
  [1] Full access  - 自动探测本机已有的 AI 登录 / API Key
  ...
Installed gateway service: systemd user unit

关于 --allow-scripts：npm 12 起默认拦截未批准的安装脚本，不加这个参数，OpenClaw 的 preinstall / postinstall 会被报成 "blocked because they are not covered by allowScripts"。npm 11.16 及以上用带参数的命令；npm 11.15 及更早反过来——要去掉这个参数。

③ 本地前缀安装（不依赖系统级 Node）：

curl -fsSL https://openclaw.ai/install-cli.sh | bash

你会看到（示意）：

Installing Node 26.1.0 into ~/.openclaw/node ...
Installing openclaw into ~/.openclaw/prefix ...
Done. Add ~/.openclaw/prefix/bin to your PATH.

它把 OpenClaw 和 Node 一起装到 ~/.openclaw 下，适合不想污染系统环境的机器。

装完先验一下：

openclaw --version

你会看到（示意）：

2026.10.5

还有 pnpm、bun、从源码、Docker、Podman、Nix、Ansible、Kubernetes、各家 VPS 等路子，第 6 章实战会再提。只想试试手感，可以直接 npx openclaw@latest。

2.3 首次引导：openclaw onboard

引导的逻辑是先把模型跑通，再配其余：

openclaw onboard

你会看到（示意）：

OpenClaw Setup
  [1] Full access  - 自动探测本机已有的 AI 登录 / API Key
  [2] Ask first     - 先问再探测
> 选择你的模型接入方式...
  Detected: Claude Code CLI login
  Verifying with a real completion...  OK
  Saved: anthropic/claude-sonnet-4-5
  Workspace: ~/.openclaw/workspace
  Gateway: http://127.0.0.1:18789
  Opening dashboard...

它干这几件事：探测 AI 接入（已配置的模型、API Key 环境变量、本地 CLI）；真实验证（跑一次真实推理，通过了才保存，失败就不动原配置）；准备工作区（默认 ~/.openclaw/workspace，自动生成 AGENTS.md、SOUL.md、IDENTITY.md、USER.md，MEMORY.md 不自动建）；配置 Gateway（端口 18789，默认绑 loopback 只听本机）；打开控制台。

变体：openclaw onboard --classic 是老式一步步问答向导；openclaw setup --baseline 只建配置和工作区；之后想改模型或渠道用 openclaw configure。

2.4 让它后台常驻

引导默认把 Gateway 跑在前台终端，关掉终端就没了。要变成开机自启的服务：

openclaw gateway install

你会看到（示意）：

Installed gateway service:
  macOS   ~/Library/LaunchAgents/com.openclaw.gateway.plist
  Linux   ~/.config/systemd/user/openclaw-gateway.service
  Windows Task Scheduler \OpenClaw\Gateway
Run 'openclaw gateway status' to verify.

（Windows 上如果创建计划任务被拒，会退回「每用户登录启动项」。）

2.5 三个体检命令

openclaw doctor
openclaw gateway status
openclaw status --all

你会看到（示意）：

doctor:     config OK, 1 warning (workspace .env contains a provider key)
gateway:    running, pid 4821, listening on 127.0.0.1:18789
status:     agent=main model=anthropic/claude-sonnet-4-5 channels=0 sessions=3
命令 作用
openclaw --version 确认 CLI 装上了
openclaw doctor 体检配置问题；加 --fix 让它自动修一部分
openclaw gateway status 看 Gateway 是否在跑
openclaw status --all 只读的完整诊断，密钥已脱敏，可直接贴给别人
openclaw triage 跑只读健康检查，把结论交给本机的编码 Agent 去修

openclaw 敲不开？九成是 PATH 问题：

node -v           # Node 装了吗
npm prefix -g     # 全局包目录在哪
echo "$PATH"      # 里面有没有它

你会看到（示意）：

v26.1.0
/usr/local
/usr/local/bin:/usr/bin:/bin:/home/you/.npm-global/bin

2.6 状态目录：~/.openclaw

装完之后，所有东西都在这一个目录里：

~/.openclaw/
├── openclaw.json                    # 主配置
├── credentials/                     # 渠道凭据、配对白名单
├── state/openclaw.sqlite            # 共享运行时状态
├── agents/<agentId>/agent/
│   └── openclaw-agent.sqlite        # 该 Agent 的会话和转录
├── skills/                          # 托管技能库
└── workspace/                       # Agent 的工作区（记忆、AGENTS.md）

日志不在这里，在 /tmp/openclaw/（openclaw-YYYY-MM-DD.log）。想换位置可以设 OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH。

⚠️ ~/.openclaw/ 里全是凭据和隐私。官方要求目录权限 700、配置文件 600，openclaw doctor 会提醒你收紧。第 5 章专门讲这件事。

2.7 桌面应用

不想碰命令行也可以：Windows 有原生 Windows Hub（签名安装包，带托盘状态、聊天、节点模式），macOS 有菜单栏应用（.dmg），另有跨平台的 Tauri 应用作备选。桌面的本质是遥控器——Gateway 仍然可以跑在另一台服务器上。

动手改

  1. 跑 node --version，确认落在 >=24.16.0 <25 || >=26.1.0 区间内；不在就去升 Node
  2. 装完后执行 openclaw --version 和 openclaw doctor，把输出贴给自己看——第一条命令的输出应该带 2026.10.5
  3. 进 ~/.openclaw/workspace/ 看一眼自动生成的 AGENTS.md，找出 ## Tools 那一节——那是给它写「我这台机器上有什么工具」的地方

小结

  • Node 硬门槛：24.16+ 或 26.1+，推荐 26；安装脚本能自动补装
  • 三条主路：install.sh / install.ps1（最省事）、npm install -g（自己管 Node）、install-cli.sh（装进 ~/.openclaw）
  • npm 12 / 11.16+ 必须带 --allow-scripts=openclaw；11.15 及更早反而要去掉
  • openclaw onboard 先验证模型真能跑通再落盘，然后建工作区、开 Gateway（端口 18789）
  • openclaw gateway install 让它开机自驻；doctor / gateway status / status --all 是体检三件套
  • 所有状态在 ~/.openclaw/，权限必须是 700 / 600

下一章：Gateway 架构与渠道接入，把助手接到 Telegram 上 🐸

📥 下载本章代码

ZIP 内含本章全部代码文件与说明，解压即用，与教程内容同步生成。