**这是一份面向新手的 Openclaw 安装与部署实操手册：先本地跑通，再决定上云，最后补齐安全与运维。**

![Openclaw 安装部署示意图](feature.jpg "Openclaw 安装部署示意图")

> **版本说明（2026-03-09）**：文中命令与路径基于 Openclaw 官方文档和官方仓库整理。若后续版本有差异，优先以官方文档最新说明为准。

## 一图看懂：先选哪条安装路线

| 路线 | 适合谁 | 上手速度 | 可控性 | 推荐指数 |
|---|---|---:|---:|---:|
| 官方安装脚本 | 第一次接触 Openclaw | 很快 | 中 | ⭐⭐⭐⭐⭐ |
| npm / pnpm 全局安装 | 有 Node 经验 | 快 | 中高 | ⭐⭐⭐⭐ |
| install-cli 前缀安装 | 无 root 权限环境 | 中 | 高 | ⭐⭐⭐⭐ |
| 源码构建安装 | 二开/深度定制 | 慢 | 很高 | ⭐⭐⭐ |
| 第三方托管（Railway/Render/Northflank） | 想快速上线 | 很快 | 中 | ⭐⭐⭐⭐ |

> **建议顺序**：**本地跑通** -> **确认业务需求** -> **再决定托管平台**。  
> 不要一上来就做复杂生产部署，否则排错成本会很高。

## 路径一：官方安装脚本（最推荐）

### 1) 环境前置检查

```bash
# macOS / Linux
uname -a
node -v
```

- Node 建议 `22+`
- Windows 建议优先使用 WSL2

### 2) 执行安装

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

Windows PowerShell：

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

### 3) 首次引导与验证

```bash
openclaw doctor
openclaw status
openclaw dashboard
```

- `doctor`：检查依赖和运行条件
- `status`：看服务是否健康
- `dashboard`：进入控制台

### 4) 常见报错与修复

| 现象 | 原因 | 处理 |
|---|---|---|
| `openclaw: command not found` | 全局 bin 不在 PATH | 补 PATH 后重开终端 |
| 安装卡住 | 网络/代理问题 | 换网络或配置代理再试 |
| 权限错误 | 系统权限不足 | 使用用户目录安装或加 sudo（谨慎） |

## 路径二：npm / pnpm 全局安装（可控版）

### 1) 安装命令

```bash
npm install -g openclaw@latest
openclaw onboard --install-daemon
```

或 pnpm：

```bash
pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon
```

### 2) PATH 修复模板

```bash
npm prefix -g
echo "$PATH"
```

如果路径缺失，补到 `~/.zshrc` 或 `~/.bashrc`：

```bash
export PATH="$(npm prefix -g)/bin:$PATH"
```

> **注意**：不要同时混用多套 Node 管理器（如 nvm + fnm + 系统 Node）并交叉全局安装，这会造成命令漂移和版本冲突。

## 路径三：install-cli 前缀安装（企业受限环境友好）

### 1) 默认安装（用户目录）

```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
```

### 2) 指定安装目录

```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest
```

### 3) 自动化安装（CI/CD 可用）

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

这个路径的优势在于：

- 不污染全局环境
- 便于多版本并行测试
- 更适合受限服务器权限场景

## 路径四：源码构建安装（开发者路线）

```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
openclaw onboard --install-daemon
```

适用场景：

- 需要改 UI 或流程逻辑
- 需要提交 PR
- 需要做企业内部插件开发

## 第三方部署：如何选平台更稳

### 方案 A：Railway（速度优先）

操作流程：

1. 使用官方模板一键部署。
2. 配置持久化目录（如 `/data`）。
3. 设置关键环境变量：`SETUP_PASSWORD`、`PORT`。
4. 访问 `https://你的域名/setup` 完成初始化。
5. 使用 `https://你的域名/openclaw` 进入控制台。

优点：快。  
注意点：免费配额与休眠策略要提前评估。

### 方案 B：Render（配置可版本化）

操作流程：

1. 按官方 Blueprint 导入。
2. 配置 `SETUP_PASSWORD` 与持久化磁盘。
3. 部署完成后访问 `/setup` 初始化。

优点：IaC 友好，团队协作清晰。  
注意点：首次构建与冷启动要考虑耗时。

### 方案 C：Northflank（面板体验好）

操作流程：

1. 一键部署官方模板。
2. 填写环境变量并启动服务。
3. 打开 `/setup` 完成首启配置。

优点：上手直观。  
注意点：资源规格与成本要按实际流量调优。

### 方案 D：VPS + Docker（长期生产推荐）

建议步骤：

1. 选稳定 Linux 发行版并更新系统。
2. 使用官方镜像 `ghcr.io/openclaw/openclaw` 部署。
3. 挂载数据目录，避免容器重建丢状态。
4. 加反向代理（Nginx/Caddy）并启用 HTTPS。
5. 增加监控、日志归档、自动备份。

## 新手最容易忽略的 6 个坑

1. **只关注安装，不做权限边界**：应先定义谁可调用哪些工具。
2. **把密钥写进仓库**：应使用环境变量与密钥管理服务。
3. **不做限流与预算控制**：模型调用量会在高并发下快速放大。
4. **不区分测试环境与生产环境**：先在测试环境走通再放量。
5. **无备份策略**：至少要做每日快照与关键配置备份。
6. **盲目追新版本**：生产环境升级前先灰度验证。

> **安全底线**：最小权限、密钥隔离、日志留痕、可回滚发布。  
> 这四件事做到了，线上风险会下降一个数量级。

## 快速验收清单（安装后 10 分钟内完成）

- [ ] `openclaw doctor` 全项通过
- [ ] `openclaw status` 显示运行中
- [ ] Dashboard 可访问
- [ ] 至少连接 1 个外部工具并完成一次读写测试
- [ ] 已设置管理员密码与最小权限策略
- [ ] 已启用日志与数据目录备份

## 参考资料（官方）

1. Install 总览：https://docs.openclaw.ai/install/index
2. Installer Internals：https://docs.openclaw.ai/install/installer
3. Docker：https://docs.openclaw.ai/install/docker
4. Podman：https://docs.openclaw.ai/install/podman
5. Nix：https://docs.openclaw.ai/install/nix
6. Ansible：https://docs.openclaw.ai/install/ansible
7. Railway：https://docs.openclaw.ai/install/railway
8. Render：https://docs.openclaw.ai/install/render
9. Northflank：https://docs.openclaw.ai/install/northflank
10. OpenClaw GitHub：https://github.com/openclaw/openclaw
11. 配图来源（Pexels）：https://www.pexels.com/photo/a-close-up-image-of-computer-circuit-board-34804019/