OpenClaw 本地部署完整指南 - 学习笔记-OpenClaw-上海佼艾

一、系统要求

在开始部署 OpenClaw 之前，请确保您的开发环境满足以下最低系统要求。不同操作系统版本的要求略有差异，但核心依赖保持一致。

1.1 硬件要求

硬件项	最低配置	推荐配置
CPU	双核 2.0 GHz	四核 3.0 GHz 及以上
内存	4 GB RAM	16 GB RAM 及以上
磁盘空间	10 GB 可用空间	50 GB 可用空间（SSD 优先）
网络	宽带互联网连接	稳定光纤宽带

1.2 软件依赖

依赖项	版本要求	说明
Python	3.10 及以上	推荐 3.11 或 3.12，获得最佳兼容性
Node.js	18.x 及以上	用于前端构建和脚本运行
Git	2.30 及以上	版本控制和项目克隆
pip	23.0 及以上	Python 包管理器
Poetry（可选）	1.5 及以上	Python 依赖管理（推荐）
Docker（可选）	20.10 及以上	容器化部署（推荐）

1.3 支持的平台

Windows：Windows 10 22H2 及以上，Windows 11
macOS：macOS Monterey 12 及以上（Intel / Apple Silicon）
Linux：Ubuntu 20.04 / 22.04 / 24.04，Debian 11 / 12，CentOS 7 / 8，Fedora 36+

提示

如果您使用的是 Windows 系统，强烈建议安装 Windows Terminal 和 PowerShell 7+，以获得更好的命令行体验。macOS 和 Linux 用户建议使用系统自带终端即可。

二、Windows 部署详细步骤

本节将逐步指导您在 Windows 系统上完成 OpenClaw 的本地部署。整个过程分为环境准备、项目克隆、依赖安装和启动运行四个阶段。

2.1 安装 Python

访问 Python 官方网站，下载 Python 3.11 或 3.12 版本
运行安装程序，务必勾选"Add Python to PATH" 选项
点击 "Install Now" 完成安装
验证安装：打开命令提示符或 PowerShell，执行以下命令

# 验证 Python 安装
python --version
# 应输出：Python 3.11.x 或 3.12.x
pip --version
# 应输出：pip 23.x.x (python 3.11.x)

2.2 安装 Git

访问 Git 官方网站，下载 Windows 版本
运行安装程序，一路使用默认选项即可
验证安装：

git --version
# 应输出：git version 2.xx.x.windows.x

2.3 安装 Node.js

访问 Node.js 官方网站，下载 LTS 版本（18.x 或 20.x）
运行安装程序，勾选 "Automatically install the necessary tools"
验证安装：

node --version
# 应输出：v18.x.x 或 v20.x.x
npm --version
# 应输出：9.x.x 或 10.x.x

2.4 克隆 OpenClaw 项目

# 进入您希望存放项目的目录
cd C:\Projects
# 克隆 OpenClaw 仓库
git clone https://github.com/[组织名]/OpenClaw.git
# 进入项目目录
cd OpenClaw

注意

请将上述 URL 替换为实际的 OpenClaw 仓库地址。如果您使用的是私有仓库，请确保已配置 SSH 密钥或使用 personal access token 进行身份验证。

2.5 创建虚拟环境并安装依赖

# 创建 Python 虚拟环境
python -m venv venv
# 激活虚拟环境
venv\Scripts\activate
# 升级 pip
python -m pip install --upgrade pip
# 安装项目依赖
pip install -r requirements.txt
# 如果项目使用 Poetry（推荐）
# pip install poetry
# poetry install

2.6 安装前端依赖并构建

# 进入前端目录（如果项目有单独的前端目录）
cd frontend 或 cd ui
npm install
npm run build
# 返回项目根目录
cd ..

关键点

Windows 系统中如果遇到 pip install 超时或失败，可以尝试使用国内镜像源加速：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple。

三、macOS 部署详细步骤

macOS 的部署流程与 Windows 基本相似，但在工具安装和依赖管理方面有所不同。如果您是 Apple Silicon（M1/M2/M3/M4）用户，需要注意架构兼容性问题。

3.1 安装 Homebrew

Homebrew 是 macOS 上最流行的包管理器，建议通过它来安装所有依赖。

# 安装 Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 验证安装
brew --version

3.2 安装 Python

# 使用 Homebrew 安装 Python 3.11
brew install python@3.11
# 验证安装
python3 --version
# 建立软链接（可选）
# 将 python3 指向默认 python 命令
which python3

提示

macOS 系统自带 Python 3（在较新版本中），但版本可能较旧。建议通过 Homebrew 安装独立版本，避免与系统 Python 产生冲突。使用 python3 而不是 python 命令是最安全的选择。

3.3 安装 Git 和 Node.js

# 安装 Git（macOS 可能已自带）
brew install git
# 安装 Node.js LTS
brew install node@18
# 验证安装
git --version
node --version
npm --version

3.4 克隆项目并安装依赖

# 克隆项目
cd ~/Projects
git clone https://github.com/[组织名]/OpenClaw.git
cd OpenClaw
# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate
# 升级 pip 并安装依赖
python3 -m pip install --upgrade pip
pip install -r requirements.txt
# 前端依赖
cd frontend
npm install
npm run build
cd ..

关键点

Apple Silicon 兼容性：如果您使用 M 系列芯片的 Mac，某些 Python 包可能需要从源码编译。确保已安装 Xcode Command Line Tools（xcode-select --install），否则可能出现编译错误。

3.5 配置 Docker（可选但推荐）

# 通过 Homebrew 安装 Docker
brew install --cask docker
# 启动 Docker Desktop（首次需手动启动）
open /Applications/Docker.app
# 验证 Docker 运行状态
docker --version
docker info

四、Linux 部署详细步骤

Linux 是 OpenClaw 最推荐的部署平台。以下步骤以 Ubuntu 22.04 LTS 为例，其他发行版可参考对应的包管理器命令。

4.1 系统包更新

# 更新系统包索引并升级已安装包
sudo apt update
sudo apt upgrade -y
# 安装必要的系统工具
sudo apt install -y curl wget build-essential software-properties-common

4.2 安装 Python

# 安装 Python 3.11
sudo apt install -y python3.11 python3.11-venv python3.11-dev
# 安装 pip
curl -sS https://bootstrap.pypa.io/get-pip.py | python3.11
# 验证安装
python3.11 --version
pip3.11 --version
# 创建 python3 软链接（可选）
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1

4.3 安装 Git 和 Node.js

# 安装 Git
sudo apt install -y git
# 安装 Node.js 18.x LTS（使用 NodeSource 源）
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
# 验证安装
git --version
node --version
npm --version

4.4 克隆项目并安装依赖

# 克隆项目
cd ~/Projects
git clone https://github.com/[组织名]/OpenClaw.git
cd OpenClaw
# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate
# 安装依赖
pip install --upgrade pip
pip install -r requirements.txt
# 前端构建
cd frontend
npm install
npm run build
cd ..

4.5 安装 Docker（可选但推荐）

# 安装 Docker（Ubuntu 官方源）
sudo apt install -y docker.io docker-compose-v2
# 启动 Docker 服务
sudo systemctl enable docker
sudo systemctl start docker
# 将当前用户加入 docker 组（避免每次使用 sudo）
sudo usermod -aG docker $USER
# 验证安装（添加用户到组后需重新登录）
docker --version
docker compose version

注意

将用户添加到 docker 组后，需要退出并重新登录终端会话才能生效。如果不希望重新登录，可以使用 newgrp docker 命令临时切换。

五、环境变量配置

OpenClaw 的运行依赖于多个环境变量。本节将介绍如何正确配置这些变量，确保应用能够正常运行。

5.1 创建环境变量文件

在项目根目录下创建一个 .env 文件，用于存放所有环境变量配置。项目通常会提供一个 .env.example 模板文件作为参考。

# 从模板文件复制（推荐）
# Windows
copy .env.example .env
# macOS / Linux
cp .env.example .env

5.2 核心环境变量说明

变量名	是否必填	说明	示例值
`OPENAI_API_KEY`	是	OpenAI API 密钥，用于调用 GPT 模型	`sk-xxxxxxxxxxxxxxxx`
`DATABASE_URL`	是	数据库连接字符串	`sqlite:///./data/claw.db`
`LOG_LEVEL`	否	日志级别	`INFO` / `DEBUG` / `WARNING`
`PORT`	否	应用监听端口，默认 8000	`8000`
`HOST`	否	绑定地址，默认 127.0.0.1	`0.0.0.0`（允许外部访问）
`REDIS_URL`	否	Redis 连接地址（如有缓存需求）	`redis://localhost:6379/0`
`CLAUDE_API_KEY`	否	Anthropic Claude API 密钥（可选）	`sk-ant-xxxxxxxxxxxx`

5.3 环境变量配置示例

# .env 文件示例
# API 密钥配置
OPENAI_API_KEY=sk-your-openai-api-key-here
# 数据库配置（使用 SQLite 本地文件）
DATABASE_URL=sqlite:///./data/claw.db
# 服务配置
HOST=127.0.0.1
PORT=8000
# 日志配置
LOG_LEVEL=INFO

关键点

安全警告：切勿将 .env 文件提交到 Git 仓库。项目应已配置 .gitignore 来排除该文件。如果尚未配置，请立即将 .env 添加到 .gitignore 中。

六、API Key 配置

API Key 是 OpenClaw 与大语言模型服务通信的凭证。本节详细说明如何获取和配置各类 API Key。

6.1 OpenAI API Key 获取

访问 OpenAI Platform 并登录账号
点击右上角个人头像，选择 "View API Keys"
点击 "Create new secret key"，生成一个新的 API Key
复制并妥善保存 API Key（关闭弹窗后将无法再次查看完整密钥）
将密钥填入 .env 文件的 OPENAI_API_KEY 字段

提示

OpenAI API Key 以 sk- 开头。建议创建多个 Key 并做好命名管理（如标注用途为 "OpenClaw-dev"），方便在需要时单独撤销某个 Key 而不会影响其他服务。

6.2 Anthropic Claude API Key 获取（可选）

访问 Anthropic Console 并登录账号
点击 "API Keys" 菜单，然后点击 "Create Key"
输入 Key 名称（如 "OpenClaw"），点击创建
复制密钥（以 sk-ant- 开头）并填入 .env

6.3 其他模型 API Key

OpenClaw 可能还支持以下模型的 API Key 配置，具体请参考项目文档：

模型提供商	环境变量名	获取方式
Google Gemini	`GEMINI_API_KEY`	Google AI Studio
Azure OpenAI	`AZURE_OPENAI_KEY`	Azure Portal
智谱 ChatGLM	`ZHIPUAI_API_KEY`	智谱开放平台
百度文心一言	`WENXIN_API_KEY`	百度智能云
阿里通义千问	`DASHSCOPE_API_KEY`	阿里云灵积平台

安全警告

API Key 保护措施：

不要将 API Key 硬编码在代码中
不要将 API Key 上传到公开的代码仓库
定期轮换 API Key，降低泄露风险
为不同的环境（开发、测试、生产）使用不同的 API Key
设置 API 使用预算上限，防止意外超额

七、部署验证

完成上述所有配置后，需要通过一系列验证步骤确认 OpenClaw 已正确安装并可正常运行。

7.1 验证依赖安装完整性

# 检查 Python 依赖完整性
pip list
# 或者使用 Poetry 检查
poetry check
# 检查所有核心模块是否能正常导入
python -c "import openclaw; print('OpenClaw 核心模块导入成功')"

7.2 启动开发服务器

# 确保虚拟环境已激活
# Windows: venv\Scripts\activate
# macOS/Linux: source venv/bin/activate
# 启动 OpenClaw 服务
python main.py 或 uvicorn openclaw.main:app --reload
# 服务启动后应看到类似输出：
# INFO:     Uvicorn running on http://127.0.0.1:8000
# INFO:     Application startup complete.

7.3 健康检查

服务启动后，打开浏览器或使用 curl 验证服务是否正常运行。

# 使用 curl 进行健康检查
curl http://127.0.0.1:8000/health
# 预期返回：{"status": "ok", "version": "x.x.x"}
# 或访问 API 文档
curl http://127.0.0.1:8000/docs
# 应返回 Swagger UI 页面 HTML

7.4 验证 API 功能

# 测试基本 API 调用
curl -X POST http://127.0.0.1:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, OpenClaw!", "model": "gpt-3.5-turbo"}'
# 预期应返回 AI 响应内容

7.5 验证前端页面

如果 OpenClaw 包含 Web 界面，在浏览器中访问 http://127.0.0.1:8000 或前端对应的 URL，确认页面正常加载并无控制台报错。

关键点

验证清单：

服务进程无异常退出
健康检查接口返回 200 状态码
API 文档页面可正常访问
模型调用能正常返回结果
前端界面（如有）无白屏或报错
日志文件正常输出，无 ERROR 级别异常

八、常见部署问题排查表

部署过程中可能会遇到各种问题，下表汇总了最常见的错误及其解决方案。

问题现象	可能原因	解决方案
`python 不是内部或外部命令`	Python 未添加到 PATH	重新安装 Python 并勾选 "Add Python to PATH"，或在系统环境变量中手动添加 Python 安装路径
`pip 无法识别`	pip 未安装或不在 PATH 中	执行 `python -m ensurepip --upgrade`，或下载 get-pip.py 后执行 `python get-pip.py`
`Microsoft Visual C++ 14.0 或更高版本是必需的`	Windows 缺少 C++ 编译工具	下载安装 Visual Studio Build Tools，选择 "C++ 生成工具" 组件
`ERROR: Could not build wheels for xx`	缺少编译依赖或编译环境不完整	Linux：`sudo apt install build-essential python3-dev`；macOS：`xcode-select --install`
`pip install 超时`	网络连接不稳定或被阻断	使用国内镜像源：`pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`
`Address already in use`	端口已被占用	检查占用：`lsof -i:8000`（macOS/Linux）或 `netstat -ano \| findstr :8000`（Windows），终止占用进程或修改 `.env` 中的 `PORT`
`ModuleNotFoundError: No module named 'xx'`	依赖未正确安装	确认虚拟环境已激活，重新运行 `pip install -r requirements.txt`，检查是否漏装某个依赖
`OpenAI API 返回 401 Unauthorized`	API Key 无效或未正确配置	检查 `.env` 文件中的 API Key 是否正确，确认 Key 未过期且有足够配额
`ImportError: cannot import name 'xx' from 'yy'`	Python 版本不兼容或包版本冲突	确认 Python 版本 >= 3.10，尝试重新创建虚拟环境，使用 `pip install --upgrade -r requirements.txt` 更新依赖
`Docker 权限被拒绝 (permission denied)`	当前用户不在 docker 用户组中	执行 `sudo usermod -aG docker $USER`，然后退出并重新登录终端
`npm install 失败或卡住`	网络问题，npm 源访问缓慢	切换为淘宝镜像源：`npm config set registry https://registry.npmmirror.com/`
`git clone 速度极慢或失败`	网络连接问题或仓库过大	使用 `--depth=1` 参数进行浅克隆：`git clone --depth=1 [仓库URL]`

通用排查建议

在排查问题时，建议按以下顺序依次检查：

查看日志：检查应用日志文件和控制台输出，定位具体的错误信息
检查环境：确认 Python、Node.js、Git 等工具版本符合要求
验证配置：检查 .env 文件中的变量名和值是否正确
重新安装：删除虚拟环境从头开始安装，排除依赖缓存问题
查阅文档：访问 OpenClaw 官方文档或 GitHub Issues 搜索相似问题

九、核心要点总结

部署流程总览

环境准备：安装 Python 3.10+、Node.js 18+、Git，配置系统编译工具链
项目克隆：git clone 获取 OpenClaw 源码
虚拟环境：使用 python -m venv venv 创建隔离环境，避免依赖冲突
依赖安装：pip install -r requirements.txt 安装 Python 依赖，npm install && npm run build 构建前端
环境变量：从 .env.example 复制并配置 .env 文件，填写 API Key 等关键配置
服务启动：运行 python main.py 启动服务，通过健康检查接口验证

关键注意事项

虚拟环境必须激活：未激活虚拟环境会导致依赖错乱，使用系统全局的 Python 安装可能导致版本冲突
API Key 安全：所有密钥信息必须通过 .env 文件管理，严禁硬编码或提交到版本控制
网络访问：如果所在网络环境无法直接访问海外 API 服务，需配置代理或使用国内兼容的模型提供商
跨平台差异：Windows 路径使用反斜杠（\），macOS/Linux 使用正斜杠（/）；Windows 激活虚拟环境使用 venv\Scripts\activate，macOS/Linux 使用 source venv/bin/activate
版本兼容：始终参考 OpenClaw 官方文档中标注的版本依赖要求，避免使用过新或过旧的工具版本

部署后的下一步

熟悉 OpenClaw 的配置文件和可调参数
阅读官方文档了解 Agent 的创建和管理方法
尝试运行官方示例项目，验证端到端流程
根据实际需求调整数据库、缓存等基础设施配置
配置日志轮转和监控告警，确保生产环境稳定性

核心理念

OpenClaw 的本地部署遵循"环境隔离、配置外置、最小依赖"三大原则。环境隔离确保开发环境之间互不干扰；配置外置将变动参数与代码分离，便于管理和维护；最小依赖仅安装项目必需的包，降低安全风险和维护成本。理解这三大原则，不仅有助于成功部署 OpenClaw，也是所有现代软件工程的最佳实践。