旧电脑秒变 AI 员工：OpenClaw 本地部署教程（含环境配置 + 插件开发 + 常见坑）

Ne0inhk

15 Mar 2026 — 23 min read

前言

本文基于最新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 .\node-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 2026年已更名为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 # 彻底删除插件目录

四、常见坑排查

核心说明：所有坑均来自2026年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

前言