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

OpenClaw 本地部署教程：环境配置、插件开发与问题排查 | 极客日志

前言

本教程基于 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 位+（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. 操作步骤（手动执行）
# 2.1 支付宝/淘宝一键登录，进入「个人中心」→「实名认证」（人脸验证）
# 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: 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/内存（必设）

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:  };
      }
      
       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

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

前言

一、前置准备（适配优化）

1.1 硬件要求（最低适配）

1.2 必备工具与依赖

1.2.1 Windows 系统（优先 WSL2，无 WSL2 则用原生系统）

1.2.2 Ubuntu 系统（含 WSL2，轻量化首选）

1.3 API Key 获取（国内大模型，无联网也可跳过，用本地模型）

1.4 轻量化优化（核心，解决卡顿、内存不足）

二、OpenClaw 核心部署（最新版本）

2.1 克隆 OpenClaw 最新源码（国内镜像）

2.2 安装项目依赖（国内源加速）

2.3 核心配置（本地模型/在线模型二选一）

2.4 本地模型部署（无联网必做，Ollama）

2.5 启动 OpenClaw 服务

2.6 部署验证（必做，确保 AI 员工可正常工作）

三、OpenClaw 插件开发

3.1 插件开发环境准备

3.2 插件核心代码编写（批量压缩文件）

3.2.1 package.json（插件配置，固定格式）

3.2.2 SKILL.md（插件功能定义，AI 识别核心）

3.2.3 index.ts（核心逻辑，TypeScript，轻量化）

3.2.4 .eslintrc.js（代码规范，可选）

3.3 插件打包与安装（一键完成）

3.4 插件测试（必做，确保电脑可正常使用）

3.5 插件开发规范（适配补充）

四、常见坑排查

坑 1：启动失败，报错'VT-x is disabled in BIOS/UEFI'

坑 2：依赖安装超时，报错'request timed out'（国内网络）

坑 3：启动后卡顿，CPU 占用 100%

坑 4：插件安装失败，报错'Plugin id already exists'

坑 5：本地模型启动失败，报错'insufficient memory'

坑 6：Web Dashboard 无法访问，报错'Connection refused'

坑 7：启动报错'Cannot find module 'dashscope''

坑 8：机械硬盘部署，报错'EIO: i/o error, write'

五、进阶优化（可选，进一步提升流畅度）

六、部署/开发常用命令汇总

更多推荐文章

相关免费在线工具

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

前言

一、前置准备（适配优化）

1.1 硬件要求（最低适配）

1.2 必备工具与依赖

1.2.1 Windows 系统（优先 WSL2，无 WSL2 则用原生系统）

1.2.2 Ubuntu 系统（含 WSL2，轻量化首选）

1.3 API Key 获取（国内大模型，无联网也可跳过，用本地模型）

1.4 轻量化优化（核心，解决卡顿、内存不足）

二、OpenClaw 核心部署（最新版本）

2.1 克隆 OpenClaw 最新源码（国内镜像）

2.2 安装项目依赖（国内源加速）

2.3 核心配置（本地模型/在线模型二选一）

2.4 本地模型部署（无联网必做，Ollama）

2.5 启动 OpenClaw 服务

2.6 部署验证（必做，确保 AI 员工可正常工作）

三、OpenClaw 插件开发

3.1 插件开发环境准备

3.2 插件核心代码编写（批量压缩文件）

3.2.1 package.json（插件配置，固定格式）

3.2.2 SKILL.md（插件功能定义，AI 识别核心）

3.2.3 index.ts（核心逻辑，TypeScript，轻量化）

3.2.4 .eslintrc.js（代码规范，可选）

3.3 插件打包与安装（一键完成）

3.4 插件测试（必做，确保电脑可正常使用）

3.5 插件开发规范（适配补充）

四、常见坑排查

坑 1：启动失败，报错'VT-x is disabled in BIOS/UEFI'

坑 2：依赖安装超时，报错'request timed out'（国内网络）

坑 3：启动后卡顿，CPU 占用 100%

坑 4：插件安装失败，报错'Plugin id already exists'

坑 5：本地模型启动失败，报错'insufficient memory'

坑 6：Web Dashboard 无法访问，报错'Connection refused'

坑 7：启动报错'Cannot find module 'dashscope''

坑 8：机械硬盘部署，报错'EIO: i/o error, write'

五、进阶优化（可选，进一步提升流畅度）

六、部署/开发常用命令汇总

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具