安装与部署

这一课你将能做到

在 macOS / Linux / Windows 上用官方脚本完成安装
用 openclaw onboard 完成初始化并把 Gateway 装成开机自启的系统服务
说清楚本地、Docker、VPS 三种部署形态各自的适用场景

为什么要学

团队 bot 和个人玩具的区别就一个字：稳。你笔记本上前台跑的进程，合上盖子就死；同事的值班问答 bot 不能这样。这一课解决的是「让 Gateway 像 nginx 一样常驻、崩溃自愈、重启自恢复」。

人话：装软件谁都会，装成「服务」才是工程。

先建立图像

安装完成后，你磁盘和系统里会多出这些东西：

~/.openclaw/                    ← 状态目录：配置、会话、记忆、插件
├── openclaw.json               ← 主配置文件
├── workspace/                  ← agent 工作区（SOUL.md 等）
└── ...

系统服务层（openclaw gateway install 写入）：
├── macOS    → LaunchAgent（~/Library/LaunchAgents/）
├── Linux    → systemd user unit
└── Windows  → Scheduled Task（计划任务）

进程：
openclaw gateway  ← 常驻，默认监听 127.0.0.1:18789

跟着做

步骤 1：安装（三选一）

macOS / Linux / WSL 推荐官方一键脚本（会自动检测并装 Node 24）：

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

Windows 用 PowerShell：

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

已有 Node 24+ 的话，直接 npm 全局装也行：

npm i -g openclaw

步骤 2：初始化

openclaw onboard

向导会引导你选模型 Provider（可复用已有的 Claude Code / Codex CLI 登录态，或填 API key），并写入 ~/.openclaw/openclaw.json。选 Quick start 可跳过大部分选项。全程无人值守部署时用非交互模式：

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local --auth-choice openai-api-key --skip-channels --no-install-daemon

步骤 3：装成系统服务

onboard 结束后 Gateway 是前台进程，Ctrl+C 停掉它，然后：

openclaw gateway install

这一条命令在 macOS 写 LaunchAgent、Linux/WSL2 写 systemd user unit、Windows 写计划任务，实现登录自启 + 崩溃拉起。

步骤 4：验证

openclaw gateway status    # 应看到监听在 18789 端口
openclaw dashboard         # 打开 Web 控制台发一条消息测试

步骤 5：Docker / VPS 路径（团队共享实例）

Docker 部署时把状态目录挂出来即可：

docker run -d --name openclaw \
  -v openclaw-data:/home/node/.openclaw \
  -p 18789:18789 \
  openclaw/openclaw:latest

VPS（Hetzner/DigitalOcean 等）就是「一台 Linux 机器 + 上面的 Linux 流程」，官方文档有各云厂商的专门指南。2C2G 的小机器足够跑，瓶颈在模型 API 不在本地算力。

讲清楚要点

配置文件是 ~/.openclaw/openclaw.json（JSON 格式），不是 YAML。环境变量 OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR 可改路径。
gateway.mode=local 是启动开关：配置文件里必须有它，否则 openclaw gateway 拒绝启动（防误跑）；临时调试可用 --allow-unconfigured 绕过但不写配置。
install 写服务、uninstall 撤服务：openclaw gateway uninstall 只删系统服务注册，配置、会话、插件都保留。
更新是一条命令：openclaw update；想追新特性可切频道 openclaw update --channel dev，生产建议留在 stable。
Windows 原生支持但 WSL2 更省心：原生 Windows 走计划任务，行为细节与 Unix 系略有差异；团队文档若写 systemd 命令，Windows 同事走 WSL2 路径更一致。

你可能会懵的地方

为什么不能直接 npx 跑着用？ 可以体验，但 npx openclaw@latest 是前台临时进程，终端一关就没了。正式使用要走「npm 全局安装 + gateway install 服务化」。
端口 18789 是什么？ Gateway 的 WebSocket 端口，Control UI、CLI、各渠道都通过它和 Gateway 通信。默认只绑 127.0.0.1，不对公网暴露。
openclaw setup 和 openclaw onboard 有啥区别？ 功能重叠的入口：onboard 是面向新手的初始化向导，setup 偏脚本化（setup --baseline 直接生成基线配置不走向导）。已装好用 openclaw configure 做局部修改。
多环境怎么隔离？ 用 profile：openclaw --profile staging status 会把状态隔离到 ~/.openclaw-staging/；--dev 是内置的开发隔离档（默认端口 19001）。
部署到公司服务器要给老板看什么？ openclaw backup create 出的备份 + openclaw doctor --lint 的健康报告 + 渠道白名单配置，这三样是上线评审的硬材料。

错法对照

错法	问题	正解
用 `nohup openclaw gateway &` 挂后台	无崩溃自愈、无开机自启、日志乱飞	`openclaw gateway install` 走系统服务
把 API key 明文写进 `openclaw.json` 后提交 git	密钥泄露	用环境变量 `${ANTHROPIC_API_KEY}` 引用或 secrets 管理
Node 18 硬跑	引擎不兼容，装不上或运行炸	Node 24+（官方推荐 26）
Docker 不挂卷	容器一删，记忆和配置全丢	`-v openclaw-data:/home/node/.openclaw`
服务装完不管了	版本过期、安全补丁缺失	定期 `openclaw update`，关注 release notes

卡点急救

openclaw 命令找不到：新开一个终端；npm 全局 bin 目录可能没进 PATH，重新跑安装脚本会自动修。
gateway install 后 status 显示没起来：openclaw doctor 先自检；Linux 确认是 systemctl --user 层面且 lingering 已开（否则登出即停）。
端口被占：openclaw gateway status --deep 看是不是已有实例在跑；不要急着 kill，可能是上一个服务没卸干净，先 openclaw gateway stop。

面试常问

如何把 OpenClaw Gateway 做成生产级常驻服务？ openclaw gateway install 注册为系统原生服务（macOS LaunchAgent / Linux systemd user unit / Windows 计划任务），获得登录自启与崩溃重启；配合 openclaw gateway status --deep 做健康检查、openclaw backup create 做状态备份、留在 stable 频道定期 openclaw update。
Docker 部署的关键点？ 状态目录挂卷（~/.openclaw）、只映射 Gateway 端口、API key 走环境变量注入、镜像固定版本而非 latest 追新。容器重启后服务自动恢复，因为服务定义在卷内配置里。
多实例（dev/staging）怎么共存？ 用 --profile <name> 隔离状态目录与派生端口，互不影响；CI 里则可用 --dev 快速起隔离实例跑冒烟。

自测三问

openclaw gateway install 在三个操作系统上分别做了什么？
为什么 openclaw gateway 在缺少 gateway.mode=local 时拒绝启动？
Docker 部署时最容易丢数据的一步是什么？

小结一句话

安装只是开始，把 Gateway 装成系统服务、状态落盘可备份、密钥走环境变量，才算完成「能交给团队用」的部署。

延伸

官方安装文档
Getting started
下一课：Workspace 文件——用 SOUL.md / AGENTS.md / USER.md 定义你的 agent 是谁、听谁的。