OpenClaw 跨系统本地部署全流程（新手零基础版）

OpenClaw 的安装被传得 “门槛极高”，但只要剔除冗余步骤、按系统精准操作，零基础也能搞定。本次教程针对MacOS、Linux（Ubuntu 22.04）、Windows11 三大主流系统，全程本地原生部署（无需云端服务器），包含环境配置、依赖安装、服务启动全流程，新手友好。

本教程仅针对 OpenClaw 官方开源版，所有操作均在本地完成，无需付费服务器；全程重点：版本匹配（Python 3.10-3.12）、依赖装全、配置文件正确初始化。

一、部署前置准备（必做！缺一不可）

1. 通用软件依赖（所有系统都要装）

软件	版本要求	作用
Python	3.10 ~ 3.12	OpenClaw 核心运行环境（版本错必报错）
Git	2.30+	克隆官方代码仓库

2. 系统专属依赖（按自己系统装）

MacOS：仅需安装 Xcode 命令行工具（终端执行 xcode-select --install，弹窗点 “安装” 即可）；

Linux（Ubuntu 22.04）：基础编译 / 虚拟环境工具（后续步骤会给一键安装命令）；

Windows11：必须先装 WSL2+Ubuntu 22.04 子系统（原生 Windows 兼容性差，新手必走此路）。

3. 核心凭证（必须提前准备）

注册阿里云账号并完成实名认证，开通「阿里云百炼大模型服务」，获取 API Key（需订阅阿里云百炼 Coding Plan）—— 这是 OpenClaw 调用大模型的核心凭证，后续要填到配置文件里。

二、分系统详细部署步骤（新手建议一步步复制命令）

1. MacOS 系统本地部署

bash

运行

# 步骤1：克隆OpenClaw官方仓库（下载代码）

git clone https://github.com/openclaw-project/openclaw.git

cd openclaw  # 进入代码目录（后续所有操作都在这个目录下）

 

# 步骤2：创建Python虚拟环境（避免污染系统Python）

python3 -m venv claw-env  # 创建名为claw-env的虚拟环境

source claw-env/bin/activate  # 激活虚拟环境（终端前缀会出现(claw-env)，代表激活成功）

 

# 步骤3：升级pip并安装依赖（--no-cache-dir解决缓存导致的安装失败）

pip install --upgrade pip

pip install -r requirements.txt --no-cache-dir

 

# 步骤4：初始化配置文件（复制示例配置为正式配置）

cp config/example_config.json config/claw_config.json

# 【关键】此时需要编辑claw_config.json，填入阿里云百炼的API Key（新手可用文本编辑器打开改）

 

# 步骤5：启动服务（新手先前台运行，方便看日志）

python -m openclaw.gateway

 

# （进阶）后台运行（不占用终端，关闭终端也能运行）

# nohup python -m openclaw.gateway > claw_run.log 2>&1 &

# tail -f claw_run.log  # 查看后台运行日志（有报错能及时发现）

 启动成功标志：终端无报错，显示 “OpenClaw Gateway started on port xxx”（端口号通常是 8000）。

2. Linux 系统（Ubuntu 22.04）本地部署

bash

运行

# 步骤1：更新系统源+安装基础依赖（一键执行，输入密码即可）

sudo apt update && sudo apt upgrade -y

sudo apt install -y git python3 python3-venv python3-pip gcc g++ libssl-dev

 

# 步骤2：克隆仓库并进入目录

git clone https://github.com/openclaw-project/openclaw.git

cd openclaw

 

# 步骤3：配置虚拟环境并激活

python3 -m venv claw-env

source claw-env/bin/activate

 

# 步骤4：安装依赖+初始化配置文件

pip install --upgrade pip

pip install -r requirements.txt

cp config/example_config.json config/claw_config.json

# 【关键】编辑claw_config.json，填入阿里云百炼API Key

 

# 步骤5：配置系统服务（实现开机自启，不用每次手动启动）

sudo tee /etc/systemd/system/openclaw.service << EOF

[Unit]

Description=OpenClaw AI Agent Local Service

After=network.target

 

[Service]

User=$USER

WorkingDirectory=$(pwd)

ExecStart=$(pwd)/claw-env/bin/python -m openclaw.gateway

Restart=on-failure

RestartSec=5

 

[Install]

WantedBy=multi-user.target

EOF

 

# 步骤6：启动服务并设置开机自启

sudo systemctl daemon-reload  # 重新加载系统服务配置

sudo systemctl start openclaw  # 启动OpenClaw服务

sudo systemctl enable openclaw  # 设置开机自启

 

# 步骤7：验证部署是否成功（出现active(running)即为成功）

sudo systemctl status openclaw

常见报错：如果提示 “权限不足”，确认命令前加了sudo；如果提示 “Python 版本不对”，卸载多余 Python 版本，仅保留 3.10-3.12。

3. Windows11 系统本地部署（WSL2+Ubuntu 22.04，推荐）

Windows 原生环境不兼容，必须先装 WSL2，步骤如下：

第一步：安装 WSL2+Ubuntu 22.04（管理员模式打开 PowerShell）

powershell

# 启用WSL2功能

wsl --install -d Ubuntu-22.04

# 安装完成后重启电脑，按提示设置Ubuntu的用户名和密码（记住！后续要用）

第二步：进入 Ubuntu 子系统部署（和 Linux 步骤几乎一致）

bash

运行

# 1. 打开PowerShell，进入Ubuntu 22.04子系统

wsl.exe -d Ubuntu-22.04

 

# 2. 后续命令完全复用Linux部署步骤（复制粘贴即可）

sudo apt update && sudo apt upgrade -y

sudo apt install -y git python3 python3-venv python3-pip gcc g++ libssl-dev

git clone https://github.com/openclaw-project/openclaw.git

cd openclaw

python3 -m venv claw-env

source claw-env/bin/activate

pip install --upgrade pip

pip install -r requirements.txt

cp config/example_config.json config/claw_config.json

 

# 3. 编辑配置文件填入API Key，启动服务

python -m openclaw.gateway

 验证成功：Ubuntu 终端显示 “OpenClaw Gateway started”，代表部署完成。

三、新手必看避坑指南

Python 版本问题：如果终端输入python3 --version显示不是 3.10-3.12，先卸载旧版本，或用pyenv管理多版本；

虚拟环境激活失败：Mac/Linux 下如果source命令报错，换./claw-env/bin/activate；

依赖安装失败：MacOS 确保装了 Xcode 命令行工具，Linux 确保gcc/g++安装成功，Windows 确保 WSL2 网络正常；

API Key 配置错误：阿里云百炼的 API Key 要填对，否则启动后调用大模型会提示 “认证失败”。

总结

零基础部署核心：先装对依赖（Python 3.10-3.12 + 系统专属工具），再克隆代码，用虚拟环境装依赖，填对 API Key，最后启动服务；

Windows 用户必须走 WSL2+Ubuntu 路线，避免原生环境兼容性问题；

启动成功的核心标志：终端无报错，显示 “OpenClaw Gateway started”，且能正常调用大模型（测试指令可执行简单的 “打开记事本” 等操作）。

如果部署中遇到具体报错，优先看终端日志（前台运行直接看，后台运行看claw_run.log），90% 的问题都是版本不匹配、依赖没装全、API Key 填错这三类。

【免责声明】：部分内容、图片来源于互联网，如有侵权请联系删除，QQ：228866015