最近圈子里好几个同事都在折腾 OpenClaw作为一个长期和 AI 工具打交道的程序员我对这种开源智能体框架向来是有新版本就忍不住上手。OpenClaw 的核心思路很简单把本地大模型、自动化技能、消息通道组合成一个可以持续运行的个人智能体你告诉它任务它调用模型理解意图再通过技能模块去执行最后把结果反馈回来。对我来说OpenClaw 最吸引人的不是功能有多花哨而是它开源、可扩展、能跑在自己机器上数据和配置完全可控。这篇文章我打算把从零部署到日常使用踩过的坑都捋一遍包括 Windows 和 Ubuntu 两套环境、本地模型关联、Skill 编写、常见报错排查适合刚接触智能体开发、想在自己电脑上搭一套 AI 助理的开发者参考。1. 为什么一个程序员要折腾 OpenClaw先说个实际场景。我手上同时管着几个小项目每天要处理仓库状态检查、待办整理、定时抓取网页信息、把零散笔记归档。这些事情单个看都不难但零零碎碎加起来很耗时间。云端 AI 助手确实能做一部分可数据要传到别人服务器上有些内部脚本、代码片段我是不太放心往外发的。OpenClaw 这类本地智能体框架刚好解决这个问题模型可以跑在本机技能代码由自己控制消息通道自己接整个链路都在自己手里。当然也有人会问市面上那堆 AI 助理产品不也挺好吗为什么非要自己搭一套。我的看法是闭源产品的能力边界是别人定义的你只能用它预设好的功能遇到特殊需求就得等官方更新。OpenClaw 这种开源框架的好处在于你能直接看源码、改代码、加技能比如我后来写了一个自动整理代码 review 意见的 Skill这种高度个性化的需求现成产品根本给不了。还有人拿 WorkBuddy 这类产品来对比其实思路大同小异OpenClaw 最大的优势就是开源可自建灵活度和掌控感完全不一样。关于“OpenClaw 是不是只能用 API 方式接入算力”这个问题我一开始也困惑。实际用下来它完全支持本地模型推理配合 Ollama 就能跑。我主力机器的配置是去年买的普通笔记本16G 内存、没有独显跑 Qwen2.5-3B 这种小尺寸模型非常流畅日常对话、任务规划、脚本生成都没问题。API 只是其中一种算力来源不是唯一选择。选择哪种方式取决于你对数据隐私的要求和硬件条件完全没有必要一上来就花钱开 API。2. 部署前的准备环境选型与依赖梳理2.1 操作系统怎么选Windows、Ubuntu 还是手机上跑我建议按用途分。如果你只是想在日常开发机上体验一下Windows 加 WSL2 是最舒服的路径图形界面、编辑器和终端都有排错也方便。如果你想要一个 7x24 小时稳定运行的智能体服务比如让它定时执行任务、接收消息并自动处理那直接丢到一台 Ubuntu 小服务器上更靠谱没有休眠、没有自动更新重启的烦恼资源占用也更干净。至于热词里提到的 Termux 手机装 OpenClaw我试过一次确实能装上但体验比较“折腾”。手机性能有限长时间挂着智能体很耗电而且 Termux 里进程容易被系统杀掉稳定性远不如 PC。我的建议是先玩熟 PC 版再考虑手机端。移动场景更适合做一个远程控制端而不是跑主服务。2.2 Node.js 环境最容易被卡住的第一关OpenClaw 的安装依赖 Node.js这就是热词里会看到“node.js 官网下载 openclaw”的原因。这里有个常见坑很多人以为随便装个 Node 就行结果装完后npm install直接报错一脸懵。我实际用过之后建议直接装 Node.js 18 或 20 的 LTS 版本不要追最新的奇数版本也不要装太老的版本。安装完成后务必确认两件事。第一在终端里运行node -v和npm -v两个命令都要有输出说明 Node 环境本身是好的。第二因为国内网络原因npm install经常慢到怀疑人生我一般提前把 npm 源切到国内镜像这一步能省掉后面 90% 的安装超时问题。切换命令很简单npm config set registry https://registry.npmmirror.com。改完之后后续安装 OpenClaw 的依赖基本一两分钟就完事。2.3 本地模型选型为什么我推荐 Qwen2.5-3BOpenClaw 本身不包含模型它需要一个“大脑”也就是本地推理服务。目前社区里最常用的搭配是 Ollama 加 Qwen 系列模型。Ollama 是一个极简的本地模型运行工具一条命令就能下载并启动模型还自动暴露一个 HTTP 接口OpenClaw 通过这个接口就能调用模型能力。模型参数怎么选直接决定你跑得顺不顺。我列一个实际对比表模型参数量内存占用推理时CPU 可跑中文效果适用场景Qwen2.5-3B3B约 3-4 GB可以速度尚可中上日常任务、轻量对话、脚本生成Qwen2.5-7B7B约 6-8 GB勉强偏慢更好复杂推理、长文本处理Qwen2.5-14B14B约 12-16 GB很吃力接近商用高质量写作、复杂规划我在普通笔记本上跑 3B 模型生成速度大概是每秒 20 到 40 个 token普通对话几乎无感延迟。如果机器有 32G 内存甚至更好上 7B 体验更佳。个人经验是先拿 3B 把流程跑通再逐步升级模型是最稳的路径。拉取模型的命令是ollama pull qwen2.5:3b启动一行命令ollama run qwen2.5:3b非常无脑。3. Windows 版 OpenClaw 安装与 Companion 配置3.1 先把 WSL2 环境弄利索Windows 下安装 OpenClaw第一步其实不是装 OpenClaw而是把 WSL2 准备好。热词里那句“openclaw 无法安全验证 sl2 环境。请在 powershell 中运行 wsl -- status”说的就是这个问题。很多人在 Windows 上装了半天 OpenClaw一启动就报错提示 WSL 环境异常或无法验证原因基本都是 WSL 内核没更新、版本不对、或者根本没装。正确的操作是以管理员身份打开 PowerShell先运行wsl --status看看当前状态。如果提示没有安装任何发行版就运行wsl --install装完后重启电脑。重启后再运行wsl --status正常情况下能看到默认版本是 2。这里有个细节Windows 10 和 Windows 11 的界面略有差异但判断标准就一条wsl --status 明确显示 WSL 2 且没有警告信息这就是合格状态。提示如果wsl --install装完后提示需要更新内核去微软官网下载 WSL2 内核更新包装一下否则 OpenClaw 的底层组件会一直报诡异错误。3.2 主程序安装步骤WSL2 就绪后正式开始装 OpenClaw。我走的路径是 npm 全局安装和装任何 Node 工具链一样npm install -g openclaw装完之后先不要急着启动第一次启动会生成配置目录。在 Windows 上配置和数据通常放在用户目录下的.openclaw文件夹里。启动命令一般是openclaw start或者openclaw具体看版本。第一次启动时会要求你选择模型提供方选 Ollama填上本地地址http://localhost:11434再把模型名填成qwen2.5:3b就行。这一步如果报“无法安全验证”之类的错误基本都出在 WSL 上先回到上一步把 WSL2 状态确认好。如果报依赖缺失把 node_modules 删掉重新npm install一次基本能解决。装完主程序后顺手跑一下openclaw --version能打印出版本号就说明底座是好的。3.3 Windows Companion 到底怎么配置关于“openclaw windows companion 怎么配置”这是很多人卡住的地方。Companion 可以理解成一个桥接组件负责让 OpenClaw 能调用 Windows 系统的能力比如操作文件、读取剪贴板、启动本地程序、发送系统通知等。没有它OpenClaw 就只是个能聊天的问答机器人有了它才能真正“动手干活”。配置流程并不复杂。主程序启动后你会看到一个配对码类似xxxx-yyyy这个码就是主程序和 Companion 之间的“暗号”。然后在 Windows 上安装并启动 Companion 客户端在配对界面输入这个码它会完成握手并自动建立本地连接。连接成功后主程序里会显示 Companion 在线。几个我亲测有效的配置细节端口默认端口一般不用改除非你本机其他服务占用了。改的话主程序和 Companion 两边要一致。权限范围建议在 Companion 设置里勾选你实际需要的权限比如“允许文件读写”不要全开毕竟智能体执行的是模型生成的指令权限越小越安全。开机启动如果你打算让 OpenClaw 常驻可以把 Companion 设成开机自启省得每次手动点。日志位置Windows 下 Companion 日志一般在安装目录的 logs 文件夹里排查连不上问题全靠它。我第一次配的时候遇到“配对成功但无法执行命令”的情况最后发现是权限没勾选。所以记一个排查顺序先看主程序是否显示 Online再看授权权限是否齐全最后看本地端口是否被拦截九成问题都能解决。4. Ubuntu 服务器部署与本地模型关联实操4.1 从零开始装 Ubuntu 版 OpenClaw如果你打算把 OpenClaw 常驻在服务器Ubuntu 是更干净的方案。我自己的部署过程大概三步。第一步更新系统基础环境sudo apt update sudo apt upgrade -y第二步安装 Node.js 和 npm。这里我不建议用 apt 直接装因为版本太老。用 nvm 装指定版本最稳curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20装完确认node -v输出 v20 开头就行。第三步就是 npm 全局安装 OpenClaw和 Windows 下一样。装完后第一次启动会提示设置模型和技能目录按提示操作即可。如果你在服务器上跑记得用systemd或者pm2把进程托起来不然 SSH 一断服务就没了这个坑我踩过一次。4.2 如何把 Qwen2.5-3B 关联到 OpenClaw这一步是热词“qwen2.5-3b 关联到 openclaw”背后的真相。先在服务器上装 Ollamacurl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:3b ollama serve注意ollama serve会占住一个终端你可以把它也做成服务或者用nohup后台跑。确认 Ollama 正常工作可以单独访问http://localhost:11434能看到 response 就对了。然后回到 OpenClaw 的配置文件在模型配置段填入提供方为 ollama、接口地址为本地地址、模型名 qwen2.5:3b。配置文件是 JSON 格式我贴一个最小可用的写法{ model: { provider: ollama, baseUrl: http://localhost:11434, modelName: qwen2.5:3b, temperature: 0.7 } }填完后重启 OpenClaw在对话里随便问它一句“用一句话介绍你自己”如果它能流畅回答说明模型链路已经打通。如果报错连不上模型第一步检查ollama serve是否在跑第二步确认 baseUrl 没有拼错第三步确认 OpenClaw 进程和 Ollama 在同一台机器或网络上能互通。这三步排完基本不会有问题。4.3 顺带聊聊 Termux 手机版既然热词里有人问 Termux 怎么装 OpenClaw 手机版我简单说下可行路径但不建议新手当主方案。Termux 本质上是一个 Android 上的 Linux 模拟环境你可以通过 pkg 安装 nodejs、git然后按 Linux 的安装方式装 OpenClaw。难点在于 Android 的后台限制非常严格锁屏几分钟进程就被回收了。我的建议是手机端只用来远程查看状态比如通过网页端或消息通道发指令真正的重型任务还是留给 PC 或服务器。5. Skill 体系让 OpenClaw 听懂你的“暗号”5.1 Skill 到底是什么很多人把 Skill 理解成“插件”这个类比方向是对的但更准确地说Skill 是一组“意图到动作”的映射。OpenClaw 收到用户指令后先让模型理解意图然后去匹配一个合适的 Skill由 Skill 执行具体逻辑再把结果交回模型组织语言回复。举个例子你说“整理一下今天的待办”模型负责识别出“整理待办”这个意图然后调用你写的待办 SkillSkill 去读取数据、分类、排序最后返回一份清单。理解这个机制很重要因为它决定了你写 Skill 时关注什么。Skill 不需要包含复杂的对话逻辑那部分是模型干的Skill 的核心是“把事情做对”。就像你去餐厅点菜服务员模型负责听懂你要什么后厨Skill负责把菜做出来。5.2 手写一个“每日待办” Skill 实战我拿自己写的一个待办 Skill 举例让大家看看一个 Skill 的完整落地过程。在 OpenClaw 的技能目录下新建一个文件夹名字叫daily-todo里面放两个文件一个清单文件一个执行脚本。先看清单文件它的作用是在 OpenClaw 启动时告诉系统“我有这个技能”{ name: daily-todo, description: 读取并整理每日待办事项, triggers: [整理待办, 查看今日任务, todo list], handler: index.js }再看执行脚本我用 Node.js 写了一个最小实现读取本地 todo 文件并按优先级排序输出// index.js const fs require(fs); const path require(path); module.exports async function (context) { const file path.join(context.baseDir, todo.txt); if (!fs.existsSync(file)) { return 今天还没有待办事项可以添加一些。; } const lines fs.readFileSync(file, utf8).split(\n).filter(Boolean); const tasks lines.map((line, i) { return { index: i 1, raw: line, urgent: line.startsWith([高]) }; }); tasks.sort((a, b) (a.urgent b.urgent ? 0 : a.urgent ? -1 : 1)); return tasks.map(t ${t.index}. ${t.raw}).join(\n); };放好文件后在 OpenClaw 里重载技能然后输入“整理待办”它就会读取todo.txt并返回排好序的清单。这个例子虽然简单但把 Skill 的核心链路完整走了一遍清单声明、脚本实现、意图触发、字段返回。5.3 写 Skill 的几条实用心得写多了你会发现Skill 设计得好不好直接影响智能体的实用性。我有几条实战心得权限要收敛Skill 脚本能做什么尽量控制在一个明确范围内。比如读取指定目录不要给全局文件访问权限。模型生成的指令不可控Skill 越收敛越安全。超时要有兜底凡是涉及外部调用的 Skill比如抓网页、调第三方接口一定要设超时并返回友好错误信息不然 OpenClaw 会一直卡在那里等。返回结构保持简单Skill 返回的内容最好是一段清晰的文本或结构化数据别让模型再去猜。字段多的时候输出 JSON 比自然语言更稳。日志一定要留Skill 执行出错时日志是唯一能告诉你发生了什么的东西。我每个 Skill 都会在入口和出口各打一条日志。6. 常见问题排查与卸载清理实录6.1 “无法安全验证 sl2 环境”到底怎么解决这个报错我见了不下十次基本上全是 WSL 的问题。它出现的原因通常是你在 Windows 上启动了 OpenClaw但底层 WSL 环境状态不对或版本太老。解决办法就是热词里那句提示——在 PowerShell 里运行wsl --status看到输出里默认版本是 2且没有红色警告就放心了。如果报错提示找不到 WSL就运行wsl --install然后重启。如果提示内核损坏或版本过旧去官网下载 WSL2 内核更新包重新安装。这个排查步骤我建议放到所有 OpenClaw 启动问题的最前面因为很多后续的诡异报错根因都在 WSL 上。6.2 模型不响应、回复慢或者乱说话怎么办本地模型和 OpenClaw 之间如果出问题现象通常分三种。第一种是完全不响应基本都是 Ollama 没起来或者地址配错检查ollama serve和配置里的 baseUrl。第二种是响应很慢多半是模型太大硬件扛不住换小模型或者增加内存也可以把 temperature 调低一点生成速度会略有提升。第三种是乱说话比如答非所问、重复输出这是模型量化精度和参数设置的问题可以试试重新拉取原版模型、提高 context 长度或者干脆换更大参数量的模型。6.3 怎么彻底卸载 OpenClaw卸载这件事看似简单但残留配置最恶心。如果你是想重装建议彻底卸载。先停掉正在运行的进程然后执行npm uninstall -g openclaw接着手动删除配置目录。Windows 下删掉用户主目录里的.openclaw文件夹Linux 下删掉~/.openclaw。如果装了 Windows Companion还要在设置里卸载组件同时把它生成的配置文件和日志目录一并删除否则下次重装时老配置会直接影响新实例的行为。卸载后运行openclaw --version如果提示找不到命令说明卸载成功。6.4 踩坑速查表现象可能原因解决动作启动时报无法安全验证 sl2WSL 环境异常PowerShell 运行wsl --status按提示修复npm install 卡死源太慢切换到 npmmirror 镜像源Companion 连不上主程序端口不同或配对码错误检查两边配置的端口和配对状态模型无响应Ollama 未启动确认ollama serve运行中回复速度很慢模型太大或内存不足换 3B 模型或增加系统内存技能不被触发触发词没写对检查清单文件里的 triggers 字段卸载后残留旧配置配置目录未删除手动删除.openclaw文件夹这些坑基本上覆盖了初学者到中级用户 80% 的日常问题。最后一个建议不管什么报错先去翻日志日志里的错误信息比任何猜的都准。OpenClaw 日志一般在配置目录的 logs 文件夹下Windows 和 Linux 路径一致养成“出错先看日志”的习惯能帮你少走很多弯路。我在实际使用中的体会是OpenClaw 这类工具的价值不在“装好”而在“用好”。装好只是开始真正让它变成生产力需要你不断给它加技能、调模型、改流程。每加一个 Skill它就能多干一类活用得越久越顺手。如果你也正在折腾记住一条原则先跑通最小链路再逐步加功能。不要一上来就追求完美配置那只会让你卡在环境问题上怀疑人生。