前言
本文基于 OpenClaw 最新版本编写，适配低配置场景（最低 2vCPU+2GiB 内存 +40GiB SSD），兼容 Windows 10/11（优先 WSL2）、Ubuntu 20.04+ 系统。内容覆盖环境配置、本地部署、插件开发及高频问题排查，重点解决国内网络适配、插件开发思路及报错处理等问题。
一、前置准备（适配优化）
1.1 硬件要求（最低适配）
- CPU：Intel i3 4 代+/AMD Ryzen 3 2000+（支持虚拟化，需在 BIOS 中开启）
- 内存：最低 2GiB（建议 4GiB，开启轻量化配置可适配 2GiB）
- 存储：最低 40GiB SSD（机械硬盘需优化读写）
- 系统：Windows 10 64 位+/Ubuntu 20.04 LTS 64 位+
1.2 必备工具与依赖
核心依赖：Node.js v22+、Git、pnpm、Python 3.10-3.11、Ollama v0.15.4+（本地模型运行核心）
1.2.1 Windows 系统（优先 WSL2，无 WSL2 则用原生系统）
# 1. 配置系统执行权限（管理员身份打开 PowerShell）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
Get-ExecutionPolicy -List
# 2. 安装 Node.js v22+（国内镜像，无需手动配置环境变量）
iwr -useb https://registry.npmmirror.com/binary.html?path=node/v22.0.0/node-v22.0.0-x64.msi -OutFile node-v22.0.0-x64.msi
.
ode-v22.0.0-x64.msi /quiet
node -v
npm -v
# 3. 配置 npm 国内镜像
npm config set registry https://registry.npmmirror.com
npm config set puppeteer_download_host https://registry.npmmirror.com/binary.html?path=chromium-browser-snapshots/
# 4. 安装 Git
iwr -useb https://registry.npmmirror.com/binary.html?path=git-for-windows/v2.43.0.windows.1/Git-2.43.0-64-bit.exe -OutFile Git-2.43.0-64-bit.exe
.
Git-2.43.0-64-bit.exe /silent /norestart
git --version
# 5. 安装 Python 3.10
iwr -useb https://mirrors.aliyun.com/python/3.10/python-3.10.11-amd64.exe -OutFile python-3.10.11-amd64.exe
.
python-3.10.11-amd64.exe /quiet InstallAllUsers=1 PrependPath=1
python --version
pip --version
# 6. 配置 pip 国内镜像
mkdir %APPDATA%\pip
echo "[global] index-url = https://mirrors.aliyun.com/pypi/simple/ [install] trusted-host = mirrors.aliyun.com timeout = 60" > %APPDATA%\pip\pip.ini
pip install pip -U
# 7. 安装 Ollama
winget install ollama
ollama --version
1.2.2 Ubuntu 系统（含 WSL2，轻量化首选）
# 1. 更新系统依赖
sudo apt update && sudo apt install -y curl git build-essential --no-install-recommends
# 2. 安装 Node.js v22+
curl -fsSL https://registry.npmmirror.com/binary.html?path=node/v22.0.0/node-v22.0.0-linux-x64.tar.xz | sudo tar -xJ -C /usr/local/
echo "export PATH=/usr/local/node-v22.0.0-linux-x64/bin:$PATH" >> ~/.bashrc
source ~/.bashrc
node -v
npm -v
# 3. 配置 npm 国内镜像
npm config set registry https://registry.npmmirror.com
npm config set puppeteer_download_host https://registry.npmmirror.com/binary.html?path=chromium-browser-snapshots/
# 4. 安装 Python 3.10
sudo apt install -y python3.10 python3.10-pip python3.10-venv --no-install-recommends
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1
python3 --version
# 5. 配置 pip 国内镜像
mkdir -p ~/.config/pip
echo "[global] index-url = https://mirrors.aliyun.com/pypi/simple/ [install] trusted-host = mirrors.aliyun.com timeout = 60" > ~/.config/pip/pip.conf
pip3 install pip -U
# 6. 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama --version
1.3 API Key 获取（国内大模型，无联网也可跳过，用本地模型）
优先选择阿里通义千问（免费额度足，国内直连）。步骤如下：
- 打开通义千问开放平台。
- 登录后进入「控制台」→「API 密钥」→「新建密钥」。
- 复制 sk-开头的 API Key，保存至本地记事本。
1.4 轻量化优化（核心，解决卡顿、内存不足）
# Windows 优化（管理员 PowerShell 执行）
# 1. 关闭非必要后台进程
taskkill /f /im chrome.exe /im qq.exe /im wechat.exe
# 2. 优化虚拟内存
wmic pagefileset where name='C:\pagefile.sys' set InitialSize=4096,MaximumSize=8192
# 3. 关闭 Windows 自动更新
sc config wuauserv start= disabled
sc stop wuauserv
# Ubuntu/WSL2 优化（终端执行）
# 1. 关闭无关服务
sudo systemctl stop cron.service bluetooth.service --no-block
# 2. 限制内存使用
echo "* soft memlock 2097152" >> /etc/security/limits.conf
echo "* hard memlock 2097152" >> /etc/security/limits.conf
# 3. 优化硬盘读写
sudo sysctl -w vm.dirty_ratio=5
sudo sysctl -w vm.dirty_background_ratio=2
二、OpenClaw 核心部署（最新版本）
核心说明：旧版本命令全部失效，需按以下步骤全新安装，禁止混合旧版本文件。
2.1 克隆 OpenClaw 最新源码（国内镜像）
# 1. 创建部署目录
mkdir D:\OpenClaw && cd D:\OpenClaw
# 或 Ubuntu/WSL2: mkdir ~/openclaw && cd ~/openclaw
# 2. 克隆源码（国内镜像）
git clone https://github.moeyy.xyz/https://github.com/openclaw/openclaw.git
cd openclaw
2.2 安装项目依赖（国内源加速）
# 1. 安装 pnpm
npm install -g pnpm --registry https://registry.npmmirror.com
pnpm -v
# 2. 安装项目核心依赖
pnpm install --registry https://registry.npmmirror.com --no-optional
# 3. 补充 Python 依赖
pip3 install dashscope requests pyyaml python-dotenv -i https://mirrors.aliyun.com/pypi/simple/
2.3 核心配置（本地模型/在线模型二选一）
配置文件为项目根目录 config.yaml，对缩进敏感。
bot:
name: OpenClaw-AI-Employee
version: 2026.1.30
language: zh-CN
memory:
enabled: true
max_size: 100
model:
type: local # local=本地模型，online=在线模型
# 在线模型配置
online:
api_key: "你的通义千问 API Key"
base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
model: "qwen-turbo"
# 本地模型配置
local:
model: "ministral-3:8b"
ollama_url: "http://localhost:11434"
gateway:
port: 18789
enabled: true
lightweight: true
skills:
enabled: true
auto_load: true
max_concurrent: 2
2.4 本地模型部署（无联网必做，Ollama）
# 1. 拉取本地模型
ollama pull ministral-3:8b
# 或 2GiB 内存：ollama pull llama3:8b-instruct-q4_0
# 2. 启动 Ollama 服务
# Windows: start /b ollama serve
# Ubuntu: nohup ollama serve > ollama.log 2>&1 &
# 验证
curl http://localhost:11434/api/version
2.5 启动 OpenClaw 服务
# 1. 启动服务
# Windows: pnpm start:lightweight
# Ubuntu: nohup pnpm start:lightweight > openclaw.log 2>&1 &
# 2. 验证服务
start http://127.0.0.1:18789/
curl http://localhost:18789/health
# 3. 开机自启配置（可选）
# Windows: New-Item -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Run" ...
# Ubuntu: echo "nohup pnpm start:lightweight ..." >> ~/.bashrc
2.6 部署验证（必做）
# 验证 1：文件自动化
pnpm run agent -- --message "在当前目录创建 test 文件夹，新建 3 个 txt 文件"
# 验证 2：文本处理
echo "OpenClaw 是开源 AI 助手，可本地部署，实现自动化办公" > test.txt
pnpm run agent -- --message "总结 test.txt 文件的内容，不超过 50 字"
# 验证 3：本地模型响应
pnpm run agent -- --message "介绍你自己，用中文，简洁明了"
三、OpenClaw 插件开发
核心说明：插件基于 TypeScript 开发，遵循 Oxlint/Oxfmt 规范，通过 SKILL.md 定义功能。以下以'文件批量压缩插件'为例。
3.1 插件开发环境准备
# 1. 安装插件开发依赖
pnpm install -D typescript @types/node oxlint oxfmt --registry https://registry.npmmirror.com
# 2. 初始化 TS 配置
npx tsc --init --target ES6 --module ESNext --outDir dist --rootDir src
# 3. 创建插件目录结构
mkdir -p src/plugins/compress-files
cd src/plugins/compress-files
touch index.ts SKILL.md package.json .eslintrc.js
3.2 插件核心代码编写（批量压缩文件）
3.2.1 package.json
{
"name": "compress-files-plugin",
"version": "1.0.0",
"description": "OpenClaw 文件批量压缩插件",
"main": "dist/index.js",
"type": "module",
"dependencies": {
"archiver": "^7.0.1"
},
"devDependencies": {
"@types/archiver": "^6.0.2"
}
}
3.2.2 SKILL.md
# 插件名称：文件批量压缩插件
# 插件功能：批量压缩指定目录下的文件/文件夹，生成 zip 压缩包
# 适用场景：文件整理、空间释放
# 输入参数：
# - dirPath：必填，需要压缩的目录路径
# - zipName：必填，压缩包名称
# - ignore：可选，需要忽略的文件/文件夹
3.2.3 index.ts
import fs from 'fs';
import path from 'path';
import archiver from 'archiver';
export class CompressFilesPlugin {
public static pluginId = 'compress-files-plugin';
public static version = '1.0.0';
private static readonly isLightweight = true;
public async execute(params: { dirPath: string; zipName: string; ignore?: string[]; }): Promise<{ success: boolean; data?: any; error?: string }> {
try {
const { dirPath, zipName, ignore = [] } = params;
if (!fs.existsSync(dirPath)) {
return { success: false, error: `目录不存在：${dirPath}` };
}
const absoluteDirPath = path.resolve(dirPath);
const zipPath = path.resolve();
output = fs.(zipPath);
archive = (, { : { : } });
archive.(output);
archive.(absoluteDirPath, , {
isIgnore = ignore.( {
(ignoreItem.()) {
ext = path.(entry.);
ext === ignoreItem.();
} {
entry. === ignoreItem || entry..(ignoreItem);
}
});
!isIgnore;
});
archive.();
zipStats = fs.(zipPath);
zipSize = (zipStats. / / ).();
{ : , : { zipPath, : , : } };
} (error) {
{ : , : };
}
}
() {
{ : ., : ., : ().(params) };
}
}
.();
3.2.4 .eslintrc.js
module.exports = {
env: { node: true, es2021: true },
extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
parser: '@typescript-eslint/parser',
parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
plugins: ['@typescript-eslint'],
rules: {
'@typescript-eslint/explicit-module-boundary-types': 'off',
'@typescript-eslint/no-unused-vars': 'warn',
'no-console': 'off'
}
};
3.3 插件打包与安装
# 1. 回到插件目录
cd src/plugins/compress-files
# 2. 安装插件依赖
pnpm install --registry https://registry.npmmirror.com
# 3. 打包插件
npx tsc
# 4. 回到项目根目录
cd ../../../..
# 5. 安装插件
pnpm run plugin:install -- --path src/plugins/compress-files
# 6. 验证插件安装
pnpm run plugin:list
# 7. 重启服务
pnpm run restart:lightweight
3.4 插件测试
# 测试 1：压缩当前目录下的 test 文件夹
pnpm run agent -- --message "调用文件批量压缩插件，dirPath=./test，zipName=test-compress，ignore=[\"*.log\"]"
# 测试 2：验证压缩包是否存在
ls | grep test-compress.zip
# 测试 3：异常场景测试
pnpm run agent -- --message "调用文件批量压缩插件，dirPath=./nonexistent，zipName=error-test"
3.5 插件开发规范
- 体积控制：插件打包后体积≤100KB。
- CPU/内存控制：禁用多线程、多进程，压缩级别设为最低。
- 异常处理：所有异常必须捕获，返回明确报错。
四、常见坑排查
坑 1：启动失败，报错'VT-x is disabled in BIOS/UEFI'
- 原因：BIOS 中未开启虚拟化。
- 解决：重启电脑进入 BIOS，找到'虚拟化技术'（VT-x/AMD-V），设置为'Enabled'，保存重启。
坑 2：依赖安装超时，报错'request timed out'
- 原因：未配置国内镜像。
- 解决：重新配置 npm 和 pip 国内镜像，清理缓存后重装。
坑 3：启动后卡顿，CPU 占用 100%
- 原因：未开启轻量化配置，并发数过高。
- 解决：修改
config.yaml，设置gateway.lightweight: true，skills.max_concurrent: 1，关闭无关进程。
坑 4：插件安装失败，报错'Plugin id already exists'
- 原因：插件 ID 重复。
- 解决：卸载重复插件，清理缓存，修改新插件的
pluginId。
坑 5：本地模型启动失败，报错'insufficient memory'
- 原因：内存不足，模型体积过大。
- 解决：删除原有模型，拉取量化版（如
llama3:8b-instruct-q4_0），设置OLLAMA_MAX_MEMORY。
坑 6：Web Dashboard 无法访问，报错'Connection refused'
- 原因：网关未启动、端口被占用或防火墙拦截。
- 解决：检查网关状态，结束占用进程，临时关闭防火墙。
坑 7：启动报错'Cannot find module 'dashscope''
- 原因：Python 依赖未安装。
- 解决：重新安装
dashscope等依赖。
坑 8：机械硬盘部署，报错'EIO: i/o error, write'
- 原因：机械硬盘读写速度慢。
- 解决：优化硬盘读写缓存，更换部署目录至 SSD，降低 IO 频率。
五、进阶优化（可选）
- 模型优化：使用量化模型（如
llama3:8b-instruct-q2_k），禁用模型记忆。 - 服务优化：创建后台服务，开机自启。
- 插件优化：仅保留必要插件，手动加载。
- 日志优化：仅记录错误日志，禁用日志文件写入。
六、部署/开发常用命令汇总
- 启动：
pnpm start:lightweight - 重启：
pnpm run restart:lightweight - 停止：
pnpm run stop - 健康检查：
curl http://localhost:18789/health - 插件安装：
pnpm run plugin:install -- --path 插件路径 - 插件卸载：
pnpm run plugin:uninstall -- --id 插件 ID - 查看日志：
cat openclaw.log（Ubuntu）；type openclaw.log（Windows）
