Openclaw 原生安装路径与第三方搭建全指南

Mon, 09 Mar 2026 00:00:00 +0000

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

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

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

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

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

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

1) 环境前置检查

# macOS / Linux
uname -a
node -v

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

2) 执行安装

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

Windows PowerShell：

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

3) 首次引导与验证

openclaw doctor
openclaw status
openclaw dashboard

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

4) 常见报错与修复

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

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

1) 安装命令

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

或 pnpm：

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

2) PATH 修复模板

npm prefix -g
echo "$PATH"

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

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

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

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

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

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

2) 指定安装目录

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

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

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

这个路径的优势在于：

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

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

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（速度优先）

操作流程：

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

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

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

操作流程：

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

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

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

操作流程：

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

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

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

建议步骤：

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

新手最容易忽略的 6 个坑

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

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

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

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

参考资料（官方）

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

Docker on 忘川

Openclaw 原生安装路径与第三方搭建全指南

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

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

1) 环境前置检查

2) 执行安装

3) 首次引导与验证

4) 常见报错与修复

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

1) 安装命令

2) PATH 修复模板

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

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

2) 指定安装目录

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

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

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

方案 A：Railway（速度优先）

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

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

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

新手最容易忽略的 6 个坑

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

参考资料（官方）