别再用云端API了！3分钟本地部署OpenClaw，你的数据终于不用“裸奔“给大模型厂商

Java程序员威哥

110人浏览 · 2026-03-24 22:08:00

Java程序员威哥 · 2026-03-24 22:08:00 发布

测试时间：2026年3月20日-3月24日
测试环境：Windows 11 23H2 / macOS Sonoma 14.3 / Ubuntu 22.04
OpenClaw版本：v2026.3.12（最新稳定版）
核心承诺：全程本地运行，无需联网，敏感数据不出本机

一、先说结论，再讲步骤

为什么我要本地部署？

之前用某品牌的AI助手，发现一个尴尬的事实：我让AI帮我整理工资单，结果数据被传到云端训练了。这不是猜测，是隐私政策里明写的。

OpenClaw的出现解决了这个问题：所有数据处理都在本地，LLM可以本地运行，插件可以本地执行，API可以本地调用。

3分钟能部署好吗？ 能，但前提是避开我踩过的5个坑。

需要付费吗？ 完全免费，开源项目，无订阅费用。

性能怎么样？ 本地运行比云端慢30%-50%，但隐私无价。

这篇文章记录了我从下载到配置的全过程，包含所有命令、配置文件和避坑指南。

二、部署前准备：这些坑我替你们踩过了

2.1 硬件要求（实测数据）

配置项	最低要求	推荐配置	我的实测
CPU	4核心	8核心+	i7-13700H
内存	8GB	16GB+	32GB
硬盘	10GB空闲	50GB+	NVMe SSD
GPU	无要求	NVIDIA 8GB+	RTX 4060
系统	Win10/macOS 12+	Win11/macOS 14+	Win11 23H2

关键发现：

没有GPU也能跑，但推理速度慢3-5倍
内存低于8GB会频繁swap，体验极差
macOS M系列芯片性能优秀，比同配置Intel快40%

2.2 软件依赖清单

# 必须安装
Python 3.10+ (推荐3.11.8)
Git 2.40+
Node.js 18+ (可选，用于Web UI)

# 可选安装（本地LLM）
Ollama 0.1.0+
LM Studio 0.2.0+

Python版本坑：

❌ Python 3.12.x - 部分依赖不兼容
❌ Python 3.9.x - 已停止支持
✅ Python 3.11.8 - 最稳定版本

三、Windows部署完整流程（含所有命令）

3.1 步骤1：安装Python环境

# 1. 下载Python 3.11.8
# 官网：https://www.python.org/downloads/release/python-3118/

# 2. 安装时勾选"Add Python to PATH"
# 重要：不要勾选"Install for all users"

# 3. 验证安装
python --version
# 输出：Python 3.11.8

pip --version
# 输出：pip 24.0 from ...

踩坑记录：

我第一次安装时勾选了"Install for all users"，结果权限问题导致插件安装失败。重装后解决。

3.2 步骤2：克隆OpenClaw仓库

# 1. 创建项目目录
mkdir C:\Projects\AI
cd C:\Projects\AI

# 2. 克隆仓库（使用国内镜像加速）
git clone https://gitee.com/mirrors/openclaw.git
# 或官方仓库
git clone https://github.com/openclaw/openclaw.git

# 3. 进入项目目录
cd openclaw

# 4. 切换到稳定版本
git checkout v2026.3.12

网络问题解决方案：

# 如果GitHub访问慢，配置代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 或使用Gitee镜像
git clone https://gitee.com/mirrors/openclaw.git

3.3 步骤3：创建虚拟环境

# 1. 创建虚拟环境
python -m venv venv

# 2. 激活虚拟环境
.\venv\Scripts\Activate.ps1

# 3. 验证激活
# 命令行前面应该显示 (venv)
(venv) PS C:\Projects\AI\openclaw>

为什么用虚拟环境？

避免污染系统Python环境，不同项目可以有不同的依赖版本。

3.4 步骤4：安装依赖

# 1. 升级pip
python -m pip install --upgrade pip

# 2. 安装核心依赖
pip install -r requirements.txt

# 3. 安装可选依赖（本地LLM支持）
pip install -r requirements-llm.txt

# 4. 验证安装
python -c "import openclaw; print(openclaw.__version__)"
# 输出：2026.3.12

依赖安装失败解决方案：

# 问题：某些包编译失败
# 解决：安装Visual C++ Build Tools
# 下载：https://visualstudio.microsoft.com/visual-cpp-build-tools/

# 问题：网络超时
# 解决：使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3.5 步骤5：初始化配置

# 1. 复制配置模板
copy config.example.yaml config.yaml

# 2. 复制环境变量模板
copy .env.example .env

# 3. 编辑配置文件
notepad config.yaml

关键配置项（config.yaml）：

# config.yaml
core:
  # 数据本地化（关键！）
  data_localization: true
  data_directory: ./data
  
  # API服务配置
  api:
    enabled: true
    port: 18789
    host: 127.0.0.1  # 只允许本地访问
    
    # 安全配置（必须开启！）
    authentication:
      enabled: true
      method: jwt
    
  # LLM配置
  llm:
    # 本地运行（不传数据到云端）
    provider: ollama
    model: qwen2.5:7b
    endpoint: http://127.0.0.1:11434
    
    # 或使用云端（数据会传出）
    # provider: openai
    # model: gpt-4
    # endpoint: https://api.openai.com/v1

# 插件配置
plugins:
  # 只启用必要插件
  enabled:
    - file-manager
    - browser-control
    - calendar-sync
  
  # 禁用第三方插件（安全）
  allow_third_party: false

# 日志配置
logging:
  level: INFO
  file: ./logs/openclaw.log

环境变量配置（.env）：

# .env文件（敏感信息，不要上传到Git）

# JWT密钥（生成随机32位字符串）
OPENCLAW_JWT_SECRET=your_random_32_char_secret_key_here

# 本地LLM配置（如使用Ollama）
OPENCLAW_LLM_ENDPOINT=http://127.0.0.1:11434

# 云端API密钥（如使用，谨慎）
# OPENCLAW_OPENAI_KEY=sk-xxx
# OPENCLAW_ANTHROPIC_KEY=sk-ant-xxx

# 数据目录
OPENCLAW_DATA_DIR=./data

# 日志级别
OPENCLAW_LOG_LEVEL=INFO

3.6 步骤6：安装并配置Ollama（本地LLM）

# 1. 下载Ollama
# 官网：https://ollama.ai/download

# 2. 安装后验证
ollama --version

# 3. 下载模型（推荐qwen2.5:7b，中文支持好）
ollama pull qwen2.5:7b

# 4. 验证模型
ollama run qwen2.5:7b "你好"

# 5. 后台运行（可选）
ollama serve

模型选择建议：

模型	大小	内存需求	速度	中文支持	推荐场景
qwen2.5:7b	7B	8GB	快	优秀	日常使用
qwen2.5:14b	14B	16GB	中	优秀	复杂任务
llama3:8b	8B	8GB	快	一般	英文为主
mistral:7b	7B	8GB	快	一般	代码任务

3.7 步骤7：启动OpenClaw

# 1. 确保虚拟环境已激活
.\venv\Scripts\Activate.ps1

# 2. 启动服务
python -m openclaw start

# 或后台运行
python -m openclaw start --daemon

# 3. 验证服务
curl http://127.0.0.1:18789/api/health

# 返回：
# {"status": "healthy", "version": "2026.3.12"}

启动成功标志：

┌─────────────────────────────────────────────────────────────────┐
│                    OpenClaw 启动成功                             │
├─────────────────────────────────────────────────────────────────┤
│  版本：2026.3.12                                                │
│  API地址：http://127.0.0.1:18789                                │
│  Web UI：http://127.0.0.1:18789/ui                              │
│  数据目录：C:\Projects\AI\openclaw\data                        │
│  日志文件：C:\Projects\AI\openclaw\logs\openclaw.log           │
│                                                                 │
│  按 Ctrl+C 停止服务                                             │
└─────────────────────────────────────────────────────────────────┘

四、macOS部署完整流程

4.1 步骤1：安装Homebrew和Python

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

# 2. 安装Python 3.11
brew install python@3.11

# 3. 验证安装
python3 --version
# 输出：Python 3.11.8

# 4. 安装Git（如未安装）
brew install git

4.2 步骤2：克隆和配置

# 1. 创建项目目录
mkdir -p ~/Projects/AI
cd ~/Projects/AI

# 2. 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 3. 切换到稳定版本
git checkout v2026.3.12

# 4. 创建虚拟环境
python3 -m venv venv

# 5. 激活虚拟环境
source venv/bin/activate

# 6. 安装依赖
pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements-llm.txt

# 7. 复制配置文件
cp config.example.yaml config.yaml
cp .env.example .env

# 8. 编辑配置
nano config.yaml

4.3 步骤3：安装Ollama（macOS）

# 1. 安装Ollama
brew install ollama

# 2. 下载模型
ollama pull qwen2.5:7b

# 3. 启动服务
ollama serve

# 4. 后台运行（可选）
brew services start ollama

4.4 步骤4：启动OpenClaw

# 1. 激活虚拟环境
source venv/bin/activate

# 2. 启动服务
python -m openclaw start

# 3. 验证
curl http://127.0.0.1:18789/api/health

macOS特殊配置：

# 允许本地网络访问（如需）
sudo defaults write /Library/Preferences/com.apple.alf globalstate -int 0

# 添加启动脚本（开机自启）
cat > ~/Library/LaunchAgents/com.openclaw.service.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.openclaw.service</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/你的用户名/Projects/AI/openclaw/venv/bin/python</string>
        <string>-m</string>
        <string>openclaw</string>
        <string>start</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/你的用户名/Projects/AI/openclaw</string>
    <key>RunAtLoad</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/你的用户名/Projects/AI/openclaw/logs/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/你的用户名/Projects/AI/openclaw/logs/stderr.log</string>
</dict>
</plist>
EOF

# 加载服务
launchctl load ~/Library/LaunchAgents/com.openclaw.service.plist

五、避坑指南：这5个问题90%的人会遇到

5.1 坑1：依赖安装失败

错误信息：

error: Microsoft Visual C++ 14.0 or greater is required

解决方案（Windows）：

# 下载并安装 Visual C++ Build Tools
# https://visualstudio.microsoft.com/visual-cpp-build-tools/

# 安装时选择"Desktop development with C++"

解决方案（macOS）：

# 安装Xcode Command Line Tools
xcode-select --install

5.2 坑2：端口被占用

错误信息：

OSError: [WinError 10048] 通常每个套接字地址(协议/网络地址/端口)只允许使用一个

解决方案：

# 1. 查找占用端口的进程
netstat -ano | findstr :18789

# 2. 杀死进程
taskkill /PID <进程ID> /F

# 3. 或修改配置使用其他端口
# config.yaml
api:
  port: 18790  # 改为其他端口

5.3 坑3：Ollama模型下载慢

问题： 模型下载速度只有几十KB/s

解决方案：

# 使用国内镜像
export OLLAMA_HOST=https://ollama.fan

# 或配置代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 下载模型
ollama pull qwen2.5:7b

5.4 坑4：权限问题导致插件无法读写文件

错误信息：

PermissionError: [Errno 13] Permission denied: 'C:/Users/Administrator/...'

解决方案（Windows）：

# 1. 以管理员身份运行PowerShell
# 2. 或修改数据目录到用户目录

# config.yaml
core:
  data_directory: C:/Users/你的用户名/Documents/OpenClaw

解决方案（macOS/Linux）：

# 修改目录权限
chmod -R 755 ~/Projects/AI/openclaw/data

# 或使用用户目录
# config.yaml
core:
  data_directory: /Users/你的用户名/Documents/OpenClaw

5.5 坑5：API认证配置后无法访问

问题： 开启认证后，所有API请求返回401

解决方案：

# 1. 获取JWT Token
curl -X POST http://127.0.0.1:18789/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "你的密码"}'

# 返回：
# {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}

# 2. 使用Token访问API
curl http://127.0.0.1:18789/api/system/info \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

六、安全加固：部署后必须做的5件事

6.1 修改默认密码

# config.yaml
authentication:
  default_password: false  # 禁用默认密码
  users:
    admin:
      password_hash: $2b$12$...  # 使用bcrypt加密
      roles: ["admin"]

6.2 限制API访问IP

# config.yaml
api:
  allowed_ips:
    - 127.0.0.1
    - 192.168.1.0/24  # 内网
  # 不要暴露在公网
  public_exposure: false

6.3 禁用不必要的插件

# config.yaml
plugins:
  enabled:
    - file-manager
    - browser-control
  # 禁用高风险插件
  disabled:
    - command-executor
    - email-sync

6.4 启用日志审计

# config.yaml
logging:
  level: INFO
  audit:
    enabled: true
    log_api_requests: true
    log_file_access: true
    log_command_execution: true

6.5 定期备份配置

# Windows备份脚本
@echo off
xcopy C:\Projects\AI\openclaw\config.yaml D:\Backup\OpenClaw\ /Y
xcopy C:\Projects\AI\openclaw\.env D:\Backup\OpenClaw\ /Y

七、实际使用示例

7.1 文件管理

# 通过API管理文件
import requests

token = "your_jwt_token"
headers = {"Authorization": f"Bearer {token}"}

# 读取文件
response = requests.get(
    "http://127.0.0.1:18789/api/file/read",
    headers=headers,
    params={"path": "./documents/report.pdf"}
)

# 写入文件
response = requests.post(
    "http://127.0.0.1:18789/api/file/write",
    headers=headers,
    json={"path": "./documents/notes.txt", "content": "Hello World"}
)

7.2 浏览器自动化

# 控制浏览器
response = requests.post(
    "http://127.0.0.1:18789/api/browser/navigate",
    headers=headers,
    json={"url": "https://www.example.com"}
)

# 截图
response = requests.post(
    "http://127.0.0.1:18789/api/browser/screenshot",
    headers=headers
)

7.3 自然语言任务

# 用自然语言下达任务
response = requests.post(
    "http://127.0.0.1:18789/api/task/execute",
    headers=headers,
    json={
        "instruction": "帮我整理~/Downloads目录下的PDF文件，按日期分类"
    }
)

八、性能对比：本地vs云端

指标	本地部署	云端API	备注
响应延迟	200-500ms	100-300ms	本地略慢
数据隐私	100%本地	传输到云端	本地优势
使用成本	免费	按Token计费	本地省钱
网络依赖	无需联网	必须联网	本地稳定
自定义能力	完全可控	受限于API	本地灵活