前言
本文基于最新 OpenClaw 版本编写，适配电脑低配置场景（最低 2vCPU+2GiB 内存+40GiB SSD），兼容 Windows 10/11（优先 WSL2）、Ubuntu 20.04+系统，全程操作指令，覆盖环境配置、本地部署、插件开发、高频坑排查。核心解决部署卡顿、国内网络适配、插件开发无思路、报错无法排查四大痛点，全程适配国内网络（国内镜像源）、国内大模型（通义千问、阿里云百炼等），无需海外代理，可稳定运行实现自动化办公（文件处理、IM 对接、任务调度等）。
一、前置准备（适配优化）
1.1 硬件要求（最低适配）
- CPU：Intel i3 4 代+/AMD Ryzen 3 2000+（支持虚拟化，需在 BIOS 中开启，步骤见常见坑 1）
- 内存：最低 2GiB（建议 4GiB，开启轻量化配置可适配 2GiB，优化步骤见 1.4）
- 存储：最低 40GiB SSD（机械硬盘需优化读写，步骤见 1.4）
- 系统：Windows 10 64 位+/Ubuntu 20.04 LTS 64 位+（Windows 7 不兼容，请勿尝试）
1.2 必备工具与依赖
核心依赖：Node.js v22+、Git、pnpm、Python 3.10-3.11（禁止 3.12+，避免依赖冲突）、Ollama v0.15.4+（本地模型运行核心）
1.2.1 Windows 系统（优先 WSL2，无 WSL2 则用原生系统）
# 1. 配置系统执行权限（管理员身份打开 PowerShell）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
Get-ExecutionPolicy -List # 验证，LocalMachine 显示 RemoteSigned 即为成功
# 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 # 验证，输出 v22.0.0+ 即为成功
npm -v # 验证，输出 10.5.0+ 即为成功
# 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 # 验证，输出 git version 2.43.0+ 即为成功
# 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 # 验证，输出 Python 3.10.11 即为成功
pip --version # 验证，输出 pip 24.0+ 即为成功
# 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 v0.15.4+（本地模型运行核心，适配）
winget install ollama # 若无 winget，手动下载：https://ollama.com/download
ollama --version # 验证，输出 0.15.4+ 即为成功
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 # 验证，输出 v22.0.0+ 即为成功
npm -v # 验证，输出 10.5.0+ 即为成功
# 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 # 验证，输出 Python 3.10.12+ 即为成功
# 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 v0.15.4+
curl -fsSL https://ollama.com/install.sh | sh
ollama --version # 验证，输出 0.15.4+ 即为成功
1.3 API Key 获取（国内大模型，无联网也可跳过，用本地模型）
优先选择阿里通义千问（免费额度足，国内直连，无压力），步骤如下（纯操作）：
# 1. 打开通义千问开放平台（国内直连，无需代理）
start https://dashscope.aliyun.com/ # Windows
xdg-open https://dashscope.aliyun.com/ # Ubuntu
# 2. 操作步骤（手动执行，30 秒完成）
# 2.1 支付宝/淘宝一键登录，进入「个人中心」→「实名认证」（人脸验证，10 秒）
# 2.2 实名认证后，左侧「控制台」→「API 密钥」→「新建密钥」，生成 sk-开头的 API Key
# 2.3 复制 API Key，保存至本地记事本（后续配置用，切勿泄露）
1.4 轻量化优化（核心，解决卡顿、内存不足）
# Windows 优化（管理员 PowerShell 执行）
# 1. 关闭非必要后台进程（释放内存）
taskkill /f /im chrome.exe /im qq.exe /im wechat.exe # 关闭浏览器、IM 等无关进程
# 2. 优化虚拟内存（机械硬盘必做，SSD 可选）
wmic pagefileset where name='C:\\pagefile.sys' set InitialSize=4096,MaximumSize=8192 # 虚拟内存设为 4-8GiB
# 3. 关闭 Windows 自动更新（避免后台占用 CPU/内存）
sc config wuauserv start= disabled
sc stop wuauserv
# Ubuntu/WSL2 优化（终端执行）
# 1. 关闭无关服务，释放内存
sudo systemctl stop cron.service bluetooth.service --no-block
# 2. 限制内存使用（2GiB 内存电脑必做）
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 核心部署（最新版本）
核心说明：OpenClaw 当前版本已整合（原 ClawdBot、Moltbot），旧版本命令全部失效，需按以下步骤全新安装，禁止混合旧版本文件。
2.1 克隆 OpenClaw 最新源码（国内镜像）
# 1. 创建部署目录（非系统盘，避免 C 盘空间不足，必做）
# Windows
mkdir D:\OpenClaw && cd D:\OpenClaw
# Ubuntu/WSL2
mkdir ~/openclaw && cd ~/openclaw
# 2. 克隆源码（国内镜像，替代 GitHub，下载无压力）
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 # 验证，输出 9.0.0+ 即为成功
# 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，对缩进敏感，直接复制以下内容，仅修改 API Key（在线模型）或模型名称（本地模型）即可。
# 1. 创建并编辑 config.yaml（Windows/Ubuntu 通用）
# Windows（记事本打开）
notepad config.yaml
# Ubuntu（vim 打开，不懂 vim 可用 nano）
vim config.yaml
# 2. 粘贴以下配置（轻量化适配，删除所有冗余参数）
bot:
name: OpenClaw-AI-Employee
version: latest
language: zh-CN # 中文环境，无需额外配置语言包
memory:
enabled: true
max_size: 100 # 限制记忆大小，节省内存（必设）
model:
type: local # local=本地模型（无联网可用），online=在线模型（需 API Key）
# 在线模型配置（有联网，阿里通义千问，免费额度足）
online:
api_key: "你的通义千问 API Key" # 替换为步骤 1.3 获取的 sk-开头密钥
base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
model: "qwen-turbo" # 轻量模型，无压力
# 本地模型配置（无联网，Ollama，优先选 ministral-3:8b）
local:
model: "ministral-3:8b" # 6GiB 大小，8GiB 内存可运行，2GiB 内存替换为"llama3:8b-instruct-q4_0"
ollama_url: "http://localhost:11434" # Ollama 默认地址，无需修改
gateway:
port: 18789 # 默认端口，避免冲突，无需修改
enabled: true
2.4 本地模型部署（无联网必做，Ollama）
# 1. 拉取本地模型（按内存选择，二选一）
# 8GiB 内存（推荐）：ministral-3:8b（6GiB，响应快）
ollama pull ministral-3:8b
# 2GiB 内存（勉强运行）：llama3:8b-instruct-q4_0（4GiB，量化版）
ollama pull llama3:8b-instruct-q4_0
# 2. 启动 Ollama 服务（后台运行，无压力）
# Windows（后台启动，无弹窗）
start /b ollama serve
# Ubuntu/WSL2（后台启动，关闭终端不影响）
nohup ollama serve > ollama.log 2>&1 &
# 验证 Ollama 服务（输出 OK 即为成功）
curl http://localhost:11434/api/version
2.5 启动 OpenClaw 服务
# 1. 启动服务（轻量化模式，优先）
# Windows（PowerShell，后台启动可加 start /b）
pnpm start:lightweight
# Ubuntu/WSL2（后台启动，关闭终端不影响）
nohup pnpm start:lightweight > openclaw.log 2>&1 &
# 2. 验证服务（核心，无报错即为部署成功）
# 方法 1：访问 Web Dashboard（浏览器打开，本地访问）
start http://127.0.0.1:18789/ # Windows
xdg-open http://127.0.0.1:18789/ # Ubuntu
# 方法 2：命令行验证（输出 success 即为成功）
curl http://localhost:18789/health
# 方法 3：快速测试 AI 员工功能（输出响应即为正常）
pnpm run test:agent -- --message "列出当前目录下所有文件"
# 3. 开机自启配置（可选，无需手动启动）
# Windows（管理员 PowerShell）
New-Item -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Run" -Name "OpenClaw" -Value "D:\OpenClaw\openclaw\node_modules\.bin\pnpm start:lightweight"
# Ubuntu/WSL2
echo "nohup pnpm start:lightweight > ~/openclaw/openclaw.log 2>&1 &" >> ~/.bashrc
2.6 部署验证（必做，确保 AI 员工可正常工作）
# 验证 1：文件自动化（AI 员工批量重命名文件）
pnpm run agent -- --message "在当前目录创建 test 文件夹，新建 3 个 txt 文件，分别命名为 file1.txt、file2.txt、file3.txt"
# 验证 2：文本处理（AI 员工总结文本内容）
echo "OpenClaw 是热门开源 AI 助手，可本地部署，适配，实现自动化办公" > test.txt
pnpm run agent -- --message "总结 test.txt 文件的内容，不超过 50 字"
# 验证 3：本地模型响应（无联网必做）
pnpm run agent -- --message "介绍你自己，用中文，简洁明了"
# 以上 3 个验证均输出正常结果，即为部署成功
三、OpenClaw 插件开发
核心说明：OpenClaw 插件基于 TypeScript（ESM）开发，遵循 Oxlint/Oxfmt 规范，采用 AgentSkills 标准格式，通过 SKILL.md 定义功能，开发无需高配置，插件体积控制在 100KB 以内即可正常运行。以下以'文件批量压缩插件'为例（高频需求），全程实操，可直接复制代码。
3.1 插件开发环境准备
# 1. 安装插件开发依赖（国内源，轻量无冗余）
pnpm install -D typescript @types/node oxlint oxfmt --registry https://registry.npmmirror.com
# 2. 初始化 TS 配置（生成 tsconfig.json，适配）
npx tsc --init --target ES6 --module ESNext --outDir dist --rootDir src
# 3. 创建插件目录结构（固定规范，不可修改）
mkdir -p src/plugins/compress-files
cd src/plugins/compress-files
# 创建核心文件（4 个文件即可，无多余文件）
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 文件批量压缩插件，支持 zip 格式，轻量化无冗余",
"main": "dist/index.js",
"type": "module",
"dependencies": {
"archiver": "^7.0.1" # 轻量压缩库，无压力
},
"devDependencies": {
"@types/archiver": "^6.0.2"
}
}
3.2.2 SKILL.md（插件功能定义，AI 识别核心）
# 插件名称：文件批量压缩插件（compress-files-plugin）
# 插件功能：批量压缩指定目录下的文件/文件夹，生成 zip 压缩包，适配低配置
# 适用场景：文件整理、空间释放
# 输入参数：
- dirPath：必填，需要压缩的目录路径（绝对路径/相对路径均可）
- zipName：必填，压缩包名称（无需加.zip 后缀）
- ignore：可选，需要忽略的文件/文件夹（数组格式，如 ["node_modules", "*.log"]）
# 输出结果：压缩包保存路径、压缩大小、耗时
# 异常处理：目录不存在、无权限时，返回明确报错信息，不崩溃
# 优化：禁用多线程压缩，降低 CPU 占用
3.2.3 index.ts（核心逻辑，TypeScript，轻量化）
import fs from 'fs';
import path from 'path';
import archiver from 'archiver';
// 插件核心类，遵循 OpenClaw 插件规范
export class CompressFilesPlugin {
// 插件标识（唯一，不可重复）
public static pluginId = 'compress-files-plugin';
// 插件版本
public static version = '1.0.0';
// 优化：禁用多线程，降低 CPU 占用
private static readonly isLightweight = true;
// 核心执行方法（AI 调用入口，参数与 SKILL.md 一致）
public async execute(params: { dirPath: string; zipName: string; ignore?: string[]; }): Promise<{ success: boolean; data?: any; error?: string }> {
try {
const { dirPath, zipName, ignore = [] } = params;
// 1. 验证目录是否存在
if (!fs.existsSync(dirPath)) {
return { success: false, error: };
}
absoluteDirPath = path.(dirPath);
zipPath = path.();
output = fs.(zipPath);
archive = (, {
: { : },
...(. && { : * }),
});
output.(, {});
archive.(, {
(err. === ) {
.();
} {
err;
}
});
archive.(, {
err;
});
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. 回到插件目录（src/plugins/compress-files）
cd src/plugins/compress-files
# 2. 安装插件依赖（国内源，轻量）
pnpm install --registry https://registry.npmmirror.com
# 3. 打包插件（生成 dist 目录，打包无压力）
npx tsc
# 4. 回到 OpenClaw 项目根目录
cd ../../../..
# 5. 安装插件（OpenClaw 自带命令，自动注册）
pnpm run plugin:install -- --path src/plugins/compress-files
# 6. 验证插件安装（输出插件列表，包含 compress-files-plugin 即为成功）
pnpm run plugin:list
# 7. 重启 OpenClaw 服务（使插件生效，重启快速）
pnpm run restart:lightweight
3.4 插件测试（必做，确保电脑可正常使用）
# 测试 1：压缩当前目录下的 test 文件夹，忽略.log 文件
pnpm run agent -- --message "调用文件批量压缩插件，dirPath=./test，zipName=test-compress，ignore=[\"*.log\"]"
# 测试 2：验证压缩包是否存在
ls | grep test-compress.zip # Ubuntu/WSL2
dir | findstr test-compress.zip # Windows
# 测试 3：异常场景测试（目录不存在）
pnpm run agent -- --message "调用文件批量压缩插件，dirPath=./nonexistent，zipName=error-test"
# 测试 4：压力测试（压缩 100 个小文件，验证 CPU 占用）
mkdir test-100 && cd test-100
for i in {1..100}; do echo "test" > file$i.txt; done # Ubuntu
for /l %i in (1,1,100) do echo test > file%i.txt # Windows
cd ..
pnpm run agent -- --message "调用文件批量压缩插件，dirPath=./test-100，zipName=100-files-compress"
# 测试通过标准：压缩成功、无报错、CPU 占用≤50%
3.5 插件开发规范（适配补充）
# 1. 插件开发 3 个核心原则（必遵循）
# 1.1 体积控制：插件打包后体积≤100KB，避免依赖大型库（如 axios 可用 node 内置 http 替代）
# 1.2 CPU/内存控制：禁用多线程、多进程，压缩级别、缓存大小设为最低
# 1.3 异常处理：所有异常必须捕获，返回明确报错，禁止崩溃（抗干扰弱）
# 2. 常用插件开发模板（直接复用，适配）
# 2.1 文件操作类（批量重命名、批量删除）：复用压缩插件结构，替换核心逻辑
# 2.2 文本处理类（批量替换、文本提取）：无需依赖大型库，用 node 内置 fs、string 方法
# 2.3 IM 对接类（企业微信、钉钉）：使用轻量 SDK，禁用长连接（节省内存）
# 3. 插件卸载（无需时删除，释放空间）
pnpm run plugin:uninstall -- --id compress-files-plugin
rm -rf src/plugins/compress-files # 彻底删除插件目录
四、常见坑排查
核心说明：所有坑均来自 OpenClaw 最新版本，结合低配置场景，每个坑均提供'报错信息 + 原因 + 解决命令'，可直接复制执行，无需复杂排查。
坑 1：启动失败，报错'VT-x is disabled in BIOS/UEFI'
# 报错原因：BIOS 中未开启虚拟化，Ollama 和 OpenClaw 网关无法运行
# 解决步骤（纯操作，通用）
1. 关闭电脑，重启时连续按 BIOS 快捷键（联想 F2、戴尔 F12、惠普 F10，其他品牌百度）
2. 进入 BIOS，找到'虚拟化技术'（VT-x/AMD-V），设置为'Enabled'
3. 保存 BIOS 设置（按 F10，选择 Yes），电脑自动重启
4. 重启后重新启动 OpenClaw 和 Ollama，验证是否正常
pnpm start:lightweight
nohup ollama serve > ollama.log 2>&1 &
坑 2：依赖安装超时，报错'request timed out'（国内网络）
# 报错原因：未配置国内镜像，或镜像配置错误，网络速度慢
# 解决命令（Windows/Ubuntu 通用，一键修复）
# 1. 重新配置 npm 国内镜像
npm config delete registry
npm config set registry https://registry.npmmirror.com
npm config set puppeteer_download_host https://registry.npmmirror.com/binary.html?path=chromium-browser-snapshots/
# 2. 重新配置 pip 国内镜像
# Windows
echo "[global] index-url = https://mirrors.aliyun.com/pypi/simple/ [install] trusted-host = mirrors.aliyun.com timeout = 120" > %APPDATA%\pip\pip.ini
# Ubuntu
echo "[global] index-url = https://mirrors.aliyun.com/pypi/simple/ [install] trusted-host = mirrors.aliyun.com timeout = 120" > ~/.config/pip/pip.conf
# 3. 清理缓存，重新安装依赖
npm cache clean --force
pnpm cache clean
pnpm install --registry https://registry.npmmirror.com --no-optional
坑 3：启动后卡顿，CPU 占用 100%
# 报错原因：未开启轻量化配置，并发数过高，本地模型配置不当
# 解决命令（一键优化，必做）
# 1. 修改 config.yaml，开启轻量化配置（重新启动生效）
# Windows notepad config.yaml
# Ubuntu vim config.yaml
# 关键修改参数（确保以下配置一致）
gateway:
lightweight: true
skills:
max_concurrent: 1 # 并发数设为 1，进一步降低 CPU 占用
model:
local:
model: "llama3:8b-instruct-q4_0" # 2GiB 内存必设，量化版更轻量
# 2. 关闭无关进程，释放 CPU/内存
# Windows（管理员 PowerShell）
taskkill /f /im chrome.exe /im qq.exe /im wechat.exe /im explorer.exe # 保留核心进程
start explorer.exe # 重启桌面进程
# Ubuntu/WSL2
sudo killall -9 chrome firefox qq wechat
sudo systemctl stop cron.service bluetooth.service
# 3. 重启 OpenClaw 服务（轻量化模式）
pnpm run restart:lightweight
# 验证 CPU 占用（≤50% 即为正常）
# Windows tasklist | findstr node
# Ubuntu top -p $(pgrep node)
坑 4：插件安装失败，报错'Plugin id already exists'
# 报错原因：插件 ID 重复（OpenClaw 插件 ID 唯一），或之前安装过同名插件未卸载干净
# 解决命令（一键清理，重新安装）
# 1. 查看已安装插件，找到重复 ID
pnpm run plugin:list
# 2. 卸载重复插件（替换为重复的插件 ID）
pnpm run plugin:uninstall -- --id 重复的插件 ID
# 3. 清理插件缓存（必做，避免缓存残留）
rm -rf node_modules/.cache/openclaw-plugin
# 4. 修改新插件的 pluginId（src/plugins/compress-files/index.ts）
# 找到 pluginId，修改为唯一值，如 compress-files-plugin-v1
# 5. 重新打包安装插件
cd src/plugins/compress-files
npx tsc
cd ../../../..
pnpm run plugin:install -- --path src/plugins/compress-files
坑 5：本地模型启动失败，报错'insufficient memory'
# 报错原因：内存不足，本地模型体积过大（如 ministral-3:8b 需要 8GiB 内存）
# 解决命令（专属，轻量化模型替换）
# 1. 删除原有大型模型
ollama rm ministral-3:8b
# 2. 拉取轻量化量化模型（2GiB 内存可运行）
ollama pull llama3:8b-instruct-q4_0 # 4GiB 大小，量化版
# 3. 修改 OpenClaw 配置，适配轻量化模型
# Windows notepad config.yaml
# Ubuntu vim config.yaml
# 修改 model.local.model 为轻量化模型
model:
type: local
local:
model: "llama3:8b-instruct-q4_0"
# 4. 优化 Ollama 内存占用（必做）
# Windows（管理员 PowerShell）
setx OLLAMA_MAX_MEMORY "2GB" /m
# Ubuntu/WSL2
echo "export OLLAMA_MAX_MEMORY=2GB" >> ~/.bashrc
source ~/.bashrc
# 5. 重启 Ollama 和 OpenClaw 服务
# Windows
taskkill /f /im ollama.exe
start /b ollama serve
pnpm run restart:lightweight
# Ubuntu/WSL2
pkill ollama
nohup ollama serve > ollama.log 2>&1 &
pnpm run restart:lightweight
坑 6：Web Dashboard 无法访问，报错'Connection refused'
# 报错原因：网关未启动、端口被占用，或防火墙拦截
# 解决命令（一键排查修复）
# 1. 检查 OpenClaw 网关状态
pnpm run gateway:status
# 若未启动，启动网关
pnpm run gateway:start -- --lightweight
# 2. 检查端口是否被占用（默认 18789）
# Windows netstat -ano | findstr 18789
# 若占用，结束占用进程（替换为占用进程 ID）
taskkill /f /pid 占用进程 ID
# Ubuntu/WSL2
lsof -i:18789
# 若占用，结束占用进程（替换为占用进程 ID）
sudo kill -9 占用进程 ID
# 3. 关闭防火墙（临时，验证是否拦截）
# Windows（管理员 PowerShell）
netsh advfirewall set allprofiles state off
# Ubuntu
sudo ufw disable
# 4. 重新访问 Web Dashboard
start http://127.0.0.1:18789/ # Windows
xdg-open http://127.0.0.1:18789/ # Ubuntu
坑 7：启动报错'Cannot find module 'dashscope''
# 报错原因：Python 依赖未安装，或安装失败，pip 镜像配置错误
# 解决命令（一键安装修复）
# 1. 重新配置 pip 国内镜像
# Windows
echo "[global] index-url = https://mirrors.aliyun.com/pypi/simple/ [install] trusted-host = mirrors.aliyun.com timeout = 120" > %APPDATA%\pip\pip.ini
# Ubuntu
echo "[global] index-url = https://mirrors.aliyun.com/pypi/simple/ [install] trusted-host = mirrors.aliyun.com timeout = 120" > ~/.config/pip/pip.conf
# 2. 重新安装缺失的 Python 依赖
pip3 install dashscope requests pyyaml python-dotenv -i https://mirrors.aliyun.com/pypi/simple/
# 3. 验证依赖是否安装成功
pip3 list | grep dashscope # 输出 dashscope 版本即为成功
# 4. 重启 OpenClaw 服务
pnpm run restart:lightweight
坑 8：机械硬盘部署，报错'EIO: i/o error, write'
# 报错原因：机械硬盘读写速度慢，文件 IO 超时，或硬盘存在坏道
# 解决命令（机械硬盘专属优化）
# 1. 优化硬盘读写缓存（Windows/Ubuntu 通用）
# Windows（管理员 PowerShell）
fsutil behavior set DisableLastAccess 1 # 禁用文件最后访问时间记录
# Ubuntu/WSL2
sudo sysctl -w vm.dirty_ratio=3
sudo sysctl -w vm.dirty_background_ratio=1
# 2. 更换部署目录（机械硬盘→SSD，若无 SSD，选择空间充足的分区）
# Windows
mkdir E:\OpenClaw && cd E:\OpenClaw
git clone https://github.moeyy.xyz/https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install --registry https://registry.npmmirror.com --no-optional
# 3. 降低文件 IO 频率（修改 config.yaml）
model:
cache: false # 禁用模型缓存，减少硬盘读写
skills:
auto_load: false # 禁用插件自动加载，手动加载所需插件
# 4. 手动加载插件（避免启动时大量 IO 操作）
pnpm run plugin:load -- --id compress-files-plugin
# 5. 重启 OpenClaw 服务
pnpm run restart:lightweight
五、进阶优化（可选，进一步提升流畅度）
# 1. 模型优化（本地模型，核心）
# 1.1 量化模型（进一步降低内存占用）
ollama pull llama3:8b-instruct-q2_k # 2GiB 内存极致优化版（2.5GiB 大小）
# 1.2 禁用模型记忆（节省内存，无需记忆功能时）
# 修改 config.yaml
bot:
memory:
enabled: false
# 2. 服务优化（后台运行，不占用桌面资源）
# Windows（创建后台服务，开机自启）
sc create OpenClaw binPath= "D:\OpenClaw\openclaw\node_modules\.bin\pnpm start:lightweight" start= auto
sc start OpenClaw
# Ubuntu/WSL2（创建 systemd 服务）
sudo echo "[Unit] Description=OpenClaw AI Employee After=network.target ollama.service [Service] User=$USER ExecStart=$HOME/openclaw/node_modules/.bin/pnpm start:lightweight Restart=always RestartSec=5 [Install] WantedBy=multi-user.target" > /etc/systemd/system/openclaw.service
sudo systemctl daemon-reload
sudo systemctl enable openclaw.service
sudo systemctl start openclaw.service
# 3. 插件优化（仅保留必要插件）
pnpm run plugin:uninstall -- --id 无需的插件 ID
# 手动加载插件（仅加载常用插件）
pnpm run plugin:load -- --id compress-files-plugin
# 4. 日志优化（禁用多余日志，减少硬盘读写）
# 修改 config.yaml
logger:
level: "error" # 仅记录错误日志，禁用 info、debug 日志
file: false # 禁用日志文件写入，仅控制台输出
六、部署/开发常用命令汇总
# 一、部署常用命令
1. 启动 OpenClaw（轻量化）：pnpm start:lightweight
2. 重启 OpenClaw：pnpm run restart:lightweight
3. 停止 OpenClaw：pnpm run stop
4. 验证服务健康：curl http://localhost:18789/health
5. 启动 Ollama 服务：nohup ollama serve > ollama.log 2>&1 &（Ubuntu）
6. 拉取本地模型：ollama pull llama3:8b-instruct-q4_0
# 二、插件开发常用命令
1. 打包插件：npx tsc（插件目录下）
2. 安装插件：pnpm run plugin:install -- --path 插件路径
3. 卸载插件：pnpm run plugin:uninstall -- --id 插件 ID
4. 查看插件列表：pnpm run plugin:list
5. 手动加载插件：pnpm run plugin:load -- --id 插件 ID
# 三、优化常用命令
1. 释放内存/CPU：taskkill /f /im 无关进程（Windows）；sudo killall -9 无关进程（Ubuntu）
2. 优化硬盘读写：sudo sysctl -w vm.dirty_ratio=3（Ubuntu）；fsutil behavior set DisableLastAccess 1（Windows）
3. 查看 CPU 占用：top -p $(pgrep node)（Ubuntu）；tasklist | findstr node（Windows）
# 四、问题排查常用命令
1. 查看 OpenClaw 日志：cat openclaw.log（Ubuntu）；type openclaw.log（Windows）
2. 查看 Ollama 日志：cat ollama.log（Ubuntu）；type ollama.log（Windows）
3. 检查端口占用：lsof -i:18789（Ubuntu）；netstat -ano | findstr 18789（Windows）
4. 验证依赖安装：pnpm list && pip3 list
