OpenClaw 本地部署教程：环境配置、插件开发与常见问题

前言

本文基于最新 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 已更名为 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: 2026.1.30
  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
    lightweight: true # 开启网关轻量化，节省 CPU/内存（必设）
  skills:
    enabled: true
    auto_load: true # 自动加载插件，无需手动注册
    max_concurrent: 2 # 限制并发数，避免卡顿

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 是 2026 年热门开源 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: `目录不存在：${dirPath}` };
      }
      // 2. 处理路径（避免路径过长报错）
      const absoluteDirPath = path.resolve(dirPath);
      const zipPath = path.resolve(`${zipName}.zip`);
      // 3. 初始化压缩器（优化：压缩级别设为最低，节省 CPU）
      const output = fs.createWriteStream(zipPath);
      const archive = archiver('zip', {
        zlib: { level: 1 }, // 压缩级别 1（最低），优先
        ...(CompressFilesPlugin.isLightweight && { highWaterMark: 64 * 1024 }), // 降低内存占用
      });
      // 4. 绑定事件（避免内存泄漏）
      output.on('close', () => {});
      archive.on('warning', (err) => {
        if (err.code === 'ENOENT') {
          console.warn(`压缩警告：${err.message}`);
        } else {
          throw err;
        }
      });
      archive.on('error', (err) => {
        throw err;
      });
      // 5. 管道连接
      archive.pipe(output);
      // 6. 添加文件/文件夹，处理忽略列表
      archive.directory(absoluteDirPath, false, (entry) => {
        // 忽略指定文件/文件夹
        const isIgnore = ignore.some((ignoreItem) => {
          if (ignoreItem.startsWith('*.')) {
            // 后缀匹配（如*.log）
            const ext = path.extname(entry.name);
            return ext === ignoreItem.slice(1);
          } else {
            // 文件名/文件夹名匹配
            return entry.name === ignoreItem || entry.name.includes(ignoreItem);
          }
        });
        return !isIgnore;
      });
      // 7. 完成压缩（禁用异步并行，避免卡顿）
      await archive.finalize();
      // 8. 获取压缩包信息
      const zipStats = fs.statSync(zipPath);
      const zipSize = (zipStats.size / 1024 / 1024).toFixed(2); // 转换为 MB
      // 9. 返回结果
      return {
        success: true,
        data: {
          zipPath,
          zipSize: `${zipSize} MB`,
          耗时：`${Date.now() - Date.now()} ms`,
          message: '压缩成功，适配低配置'
        }
      };
    } catch (error) {
      return { success: false, error: `压缩失败：${(error as Error).message}` };
    }
  }

  // 插件注册方法（OpenClaw 自动调用，无需手动执行）
  public static register() {
    return {
      pluginId: this.pluginId,
      version: this.version,
      execute: (params: any) => new this().execute(params)
    };
  }
}

// 导出插件，供 OpenClaw 加载
export default CompressFilesPlugin.register();

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