本文覆盖 Windows(WSL2)、macOS、Linux(Ubuntu) 三套部署方案，含一键脚本快速部署、源码编译部署、Docker 容器部署三种方式，配套图文标注、报错解决、初始化配置全流程。
一、前置硬件 & 软件环境（必看）

一、环境最低要求

内存≥4GB，推荐 8GB 以上；磁盘空闲≥10GB；Node.js 固定 22.x LTS；Windows 必须 WSL2 Ubuntu22.04，原生 CMD/PowerShell 不兼容。

二、Windows 前置：安装 WSL2（管理员 PowerShell 执行）

1. 开启 WSL 并自动安装 Ubuntu wsl --install
2. 重启电脑，打开 Ubuntu 设置用户名、密码
3. 校验 WSL 版本 wsl --list --verbose 输出 VERSION=2 即正常

三、通用基础依赖安装（macOS/Linux/WSL Ubuntu 终端）

1. 安装 Git sudo apt update && sudo apt install git -y

macOS 替换：brew install git

1. 使用 nvm 安装 Node22 LTS curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 nvm alias default 22 node -v

输出 v22.x.x 代表成功

1. 设置国内 npm 镜像加速 npm config set registry https://registry.npmmirror.com

四、三种部署方式（任选其一）

方式 1：国内一键脚本（新手推荐）

1. macOS/Linux/WSL 终端 curl -fsSL https://open-claw.org.cn/install-cn.sh | bash
2. Windows 管理员 PowerShell iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex 执行完成自动进入初始化配置向导

方式 2：npm 手动全局安装（已有 Node 环境）

npm install -g openclaw@latest openclaw --version openclaw doctor openclaw onboard

方式 3：Docker 容器部署（隔离环境）

1. 安装 Docker Desktop
2. 创建 docker-compose.yml 文件，内容： version: "3" services: openclaw: image: ghcr.io/openclaw/openclaw:latest ports:
   • "18789:18789" volumes:
   • ./.openclaw:/root/.openclaw restart: always extra_hosts:
   • "host.docker.internal:host-gateway"
3. 启动容器 docker compose up -d
4. 进入容器初始化 docker exec -it openclaw bash openclaw onboard

五、初始化向导统一配置流程

1. 网关设置 默认 Local Gateway 直接回车；端口默认 18789，占用则更换 18790；后台守护进程输入 y。
2. 模型二选一 方案 A：云端 API 模型 选择对应厂商，粘贴 API 密钥，填写模型名称（qwen-turbo/gpt-3.5-turbo）。 方案 B：本地 Ollama 模型（免费无密钥） 选择 Ollama Local Model；本地部署地址默认http://127.0.0.1:11434；Docker 部署填写http://host.docker.internal:11434；输入本地模型名（qwen2:7b、llama3:8b）；温度、上下文窗口默认回车。
3. 技能安装 输入 y，空格勾选 koluhab，回车自动安装依赖。
4. 保存自动生成管理员 Token，用于网页登录。

六、Ollama 本地模型前置操作

1. 官网下载安装 Ollama 客户端，启动后台服务
2. 终端拉取开源模型示例 ollama pull qwen2:7b
3. 查看本地模型列表 ollama list

七、服务启停与访问

常用运维命令

openclaw gateway start -d 后台启动 openclaw gateway status 查看运行状态 openclaw logs 实时日志 openclaw gateway stop 停止服务 openclaw gateway restart 重启服务 openclaw onboard 重新配置 openclaw doctor 环境自检修复 npm update -g openclaw 升级程序 npm uninstall -g openclaw && rm -rf ~/.openclaw 完整卸载

Web 访问地址

浏览器打开 http://localhost:18789，粘贴初始化 Token 登录后台面板。

八、常见报错解决

1. Node 版本过低：使用 nvm 切换至 Node22 LTS
2. 18789 端口占用：初始化阶段更换端口号
3. Ollama 连接超时：本地确认 Ollama 客户端已启动；Docker 部署使用 host.docker.internal 地址
4. 依赖下载超时：切换淘宝 npm 镜像、使用国内一键安装脚本
5. Windows 网页打不开：必须使用 WSL2 Ubuntu 环境，禁止原生 PowerShell 运行
6. 权限不足：Ubuntu 执行命令前加 sudo，PowerShell 全程管理员身份运行