OpenClaw 最新部署安装教程

文档版本：v2026.6.17 适配 OpenClaw：v2026.5.24-beta.1 最新版 项目简介：OpenClaw 是开源自主 AI Agent 调度框架，可对接各类大模型 API、机器人渠道、自动化任务、代码助手、定时工作流；支持 Windows/macOS/Linux/Docker 多部署模式。

一、系统最低环境要求

1. 硬性依赖

• Node.js ≥ v22.14.0，推荐 Node 24 LTS
• Git（源码安装必须，一键脚本可自动按需安装）
• 网络可访问 npm 官方 / GitHub，国内建议配置镜像加速

2. 系统兼容列表

表格

系统	版本要求	备注
Windows	Win10 1809+/Win11	原生 PowerShell / WSL2（更稳定）
macOS	macOS 11+	Intel / Apple Silicon M 系列全兼容
Linux	Ubuntu20.04+/Debian11+/Fedora36+	GLIBC ≥ 2.31

3. 端口说明

默认网关端口：18789，防火墙需放行，端口占用可自定义修改

二、四种安装方案（按需选择）

方案一：官方一键安装脚本（新手首选，自动配置环境）

1. macOS / Linux / WSL2

正常安装（安装后弹出初始化向导）

# 原版官方脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 国内社区加速脚本（推荐国内用户）
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

静默安装（跳过初始化向导，后续手动配置）

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

2. Windows（必须以管理员身份打开 PowerShell）

常规一键安装

powershell

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

# 国内加速版
iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex

静默安装（跳过初始化）

powershell

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

方案二：npm 手动全局安装（已有 Node 环境，版本可控）

步骤 1：校验 Node 版本

node --version
# 输出必须 ≥ v22.14.0，不满足先升级Node

步骤 2：配置国内 npm 镜像（解决安装卡顿）

npm config set registry https://registry.npmmirror.com

步骤 3：全局安装最新稳定版

npm install -g openclaw@latest
# 或使用pnpm（依赖安装更快）
pnpm add -g openclaw@latest

步骤 4：初始化配置向导

openclaw onboard
# 如需注册后台开机自启服务
openclaw onboard --install-daemon

方案三：源码编译安装（开发者二次开发 / 自定义构建）

1. 前置依赖：Node22+、Git、pnpm

# 全局安装pnpm
npm install -g pnpm

1. 拉取源码（二选一）

# GitHub官方仓库
git clone https://github.com/openclaw/openclaw.git

# Gitee国内镜像（下载更快）
git clone https://gitee.com/openclaw/openclaw.git
cd openclaw

1. 镜像加速 + 依赖安装

pnpm config set registry https://registry.npmmirror.com
pnpm install

1. 项目构建

pnpm run build
# 构建前端UI资源
pnpm run ui:build

1. 本地链接全局命令（调试使用）

pnpm link --global
# 验证
openclaw --version

方案四：Docker 容器部署（服务器多实例、隔离部署首选）

1. 拉取官方镜像

docker pull openclaw/openclaw:latest

1. 启动容器（持久化配置、端口映射）

docker run -d \
  --name openclaw-gateway \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  --restart always \
  openclaw/openclaw:latest

1. 进入容器初始化配置

docker exec -it openclaw-gateway openclaw onboard

三、安装校验 & 基础启停命令

1. 验证是否安装成功

openclaw --version
# 输出版本号即代表安装完成

2. 常用 CLI 命令汇总

# 启动网关服务
openclaw start

# 停止服务
openclaw stop

# 实时查看运行日志
openclaw logs --follow

# 重新运行初始化配置（填写API密钥、机器人渠道）
openclaw configure

# 一键升级到最新版本
openclaw update

# 环境自检排错
openclaw doctor

# 指定自定义端口启动
openclaw gateway --port 18790

3. 访问 Web 管理面板

启动后浏览器打开：

plaintext

http://localhost:18789

四、初始化配置流程（onboard 向导）

1. 选择大模型服务商：OpenAI / Claude / 通义千问 / Ollama 本地模型 / OpenRouter 等
2. 填入对应平台 API Key，配置接口代理（按需）
3. 配置消息渠道：Telegram、Discord、企业微信、Web 控制台等
4. 设置访问白名单、管理员权限、安全密码
5. 完成后自动常驻后台运行

五、更新、卸载操作

1. 在线升级

# 全局npm安装方式
openclaw update

# 源码安装方式
cd openclaw
git pull
pnpm install
pnpm run build
pnpm link --global

2. 完整卸载

# 卸载全局包
npm uninstall -g openclaw

# 删除配置目录（清理所有配置数据）
# macOS/Linux
rm -rf ~/.openclaw

# Windows PowerShell
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw

六、常见报错排错指南

问题 1：openclaw 命令找不到

• 原因：npm 全局路径未加入系统环境变量
• 解决：执行 npm config get prefix 查看全局路径，手动添加至系统 PATH，重启终端重试

问题 2：端口 18789 被占用

# Linux/macOS 查询占用进程
lsof -i :18789
kill 进程PID

# Windows
netstat -ano | findstr :18789
taskkill /F /PID 进程号
# 或启动时换端口
openclaw start --port 18790

问题 3：依赖安装超时、网络失败

• 全程使用淘宝 npm 镜像
• 切换 Gitee 源码地址克隆，避开 GitHub 访问慢问题

问题 4：启动报错 Node 版本过低

使用 nvm 管理多 Node 版本（推荐）

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 24
nvm use 24
nvm alias default 24

问题 5：安装脚本执行被系统安全拦截

• Windows：PowerShell 执行 Set-ExecutionPolicy RemoteSigned，输入 Y 放行脚本策略
• macOS：系统设置→安全性与隐私，允许脚本运行

七、官方地址汇总

• 官方文档：https://docs.openclaw.ai
• GitHub 主仓库：https://github.com/openclaw/openclaw
• 国内社区文档：https://open-claw.org.cn
• Docker 镜像：openclaw/openclaw