1. 为什么要在本地跑 OpenClaw先想清楚这件事OpenClaw 这个项目前身叫 Clawdbot中间还短暂叫过 Moltbot名字换了几轮但核心定位一直没变——它是一个把 AI 大模型能力接到即时通讯软件里的开源网关。你可以把它理解成一个翻译官调度员一边连着你的聊天软件账号一边连着本地或云端的大模型服务中间负责消息收发、上下文管理、工具调用这些脏活累活。那为什么非要本地部署我自己的理由有三条。第一是数据不出门聊天记录、联系人、群消息这些内容全部留在自己机器上不经过任何第三方服务器。第二是可控模型换哪个、上下文留多长、哪些群允许触发、哪些人拉黑全在配置文件里说了算。第三是省钱云端 API 按 token 计费聊得多了账单很难看本地跑个量化模型电费就是全部成本。适合看这篇的人我大致分三类。一类是手里有台闲置电脑或者小主机想折腾点实用东西的技术爱好者一类是对数据隐私比较敏感、不想把聊天内容交给第三方的小团队还有一类是已经在用 Ollama 或者 LM Studio 跑本地模型想找个前端把模型接到日常聊天工具里的人。如果你属于这三类中的任何一类接下来的内容应该能帮你少走不少弯路。需要提前说明的是OpenClaw 的部署门槛不算低它不是那种双击安装包就能用的软件。你需要跟命令行打交道需要理解 Node.js 的版本管理需要会看日志排查问题。但好消息是一旦跑通后续维护成本很低配置文件改改就能调整行为不用天天折腾。2. 部署前的环境盘点别急着敲命令2.1 硬件与操作系统的现实预期先说硬件。OpenClaw 本身是个 Node.js 应用它自己不吃什么资源内存占用通常在几百 MB 级别。真正吃资源的是它背后连的大模型。如果你打算用本地模型那显存或者内存才是瓶颈。我的经验是7B 级别的量化模型Q4 量化大概需要 6-8GB 显存14B 需要 12GB 左右32B 就得 24GB 往上了。如果只有 CPU跑 7B Q4 也能用但响应速度大概在每秒几个 token聊天体验会比较肉。操作系统方面Linux 是最省心的选择Ubuntu 22.04 或者 Debian 12 都行社区里遇到问题最容易搜到答案。macOS 也可以Apple Silicon 芯片跑本地模型效率还不错但要注意 Node.js 的架构问题后面会细说。Windows 是最麻烦的因为 OpenClaw 依赖的一些系统调用在 Windows 上行为不一致官方推荐用 WSL2。这里就引出一个高频报错——openclaw could not safely verify the wsl2 environment这个后面在排查章节会专门讲。提示如果你用的是 Windows 且不想折腾 WSL2可以考虑在虚拟机里跑一个 Ubuntu虽然多一层开销但环境隔离干净出问题好恢复。2.2 Node.js 版本这是最容易翻车的地方OpenClaw 要求 Node.js 18 及以上。听起来很简单但实际部署中Node.js 版本问题占了报错的一半以上。我见过太多人系统里装了个老版本 Node或者用包管理器装了个版本不对的然后卡在启动阶段。热词里有个很典型的报错node.js 18 the requested module node:util does not provide an export named。这个错误的本质是你的 Node.js 版本低于代码里使用的 API 要求。OpenClaw 的某些依赖用到了 Node 18 之后才有的node:util导出如果你实际运行的是 Node 16就会报这个。解决办法不是去改代码而是把 Node 版本升上去。另一个热词node.js v24.21.0 is not yet released or is not available则是版本管理工具的问题。有人用 nvm 或者 fnm 装 Node指定了一个还不存在的版本号工具就会报这个。这时候你需要先nvm ls-remote看看有哪些版本可用别凭记忆写版本号。我的建议是直接用 nvm 管理 Node 版本装一个 20.x 的 LTS 版本。为什么不用最新的 22 或者 24因为 LTS 版本经过更长时间的测试依赖兼容性更稳。具体操作# 安装 nvm如果还没装 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装 Node 20 LTS nvm install 20 nvm use 20 nvm alias default 20 # 验证 node -v npm -v装完之后node -v应该输出 v20.x.x。如果输出的是别的版本说明 PATH 里有其他 Node 在捣乱用which node看看指向哪里。2.3 包管理器与构建工具Node.js 装好之后还需要确认 npm 能用。OpenClaw 用 npm 安装依赖如果你的网络环境访问 npm 官方源比较慢可以换成国内镜像npm config set registry https://registry.npmmirror.com另外有些依赖需要编译原生模块所以系统里得有build-essentialUbuntu/Debian或者xcode-select --installmacOS。如果编译时报gyp ERR!之类的错误八成是缺编译工具链。3. 从零到跑通OpenClaw 部署全流程3.1 获取代码与安装依赖OpenClaw 的代码托管在 GitHub 上直接 clone 下来就行。这里要注意项目改名过仓库地址可能跟着变如果Clawdbot或者Moltbot的地址 404 了就搜OpenClaw找最新的。git clone https://github.com/openclaw/openclaw.git cd openclaw npm installnpm install这一步可能会比较久取决于网络。如果卡在某个包上不动可以试试npm install --verbose看看卡在哪通常是某个原生模块在编译。安装完成后通常会有一个.env.example或者config.example.yaml之类的模板文件复制一份改成自己的配置cp .env.example .env3.2 配置文件详解每个参数都有它的脾气OpenClaw 的配置分几块模型接入、聊天平台接入、行为控制。我拿一个典型的配置结构来说明具体字段名以你拉到的版本为准但逻辑是相通的。模型接入部分如果你用 Ollama配置大概长这样model: provider: ollama baseUrl: http://127.0.0.1:11434 model: qwen2.5:7b temperature: 0.7 maxTokens: 2048这里baseUrl指向 Ollama 的默认端口 11434。model字段填你在 Ollama 里ollama list看到的模型名。temperature控制随机性聊天场景 0.7 比较合适做严谨问答可以调到 0.2。maxTokens是单次回复的最大长度设太大浪费资源设太小回复会被截断2048 是个平衡点。聊天平台接入部分以某个支持扫码登录的平台为例配置里通常需要指定会话存储路径、登录方式等。第一次启动时OpenClaw 会生成一个二维码图片热词里的openclaw二维码图片就是指这个你用手机扫码登录登录态会保存到本地文件后续重启不用重复扫。行为控制部分比较重要的几个参数参数作用建议值contextWindow保留多少轮对话上下文10-20 轮triggerPrefix触发回复的前缀按需设置allowedGroups允许响应的群列表白名单模式rateLimit单用户请求频率限制5次/分钟注意allowedGroups一定要用白名单模式不然机器人进了大群会被消息淹没既费资源又容易触发平台风控。3.3 启动与首次验证配置改好之后启动命令通常是npm start或者有些版本是node index.js启动后观察日志。正常的话你会看到类似model connected、platform logged in、listening for messages这样的输出。如果卡在某一步日志会给出线索。首次启动如果出现二维码用手机扫码。扫完之后给自己发一条测试消息看看机器人有没有回复。如果没回复先别急着改代码按下面的顺序排查模型服务是否在跑、配置文件里的模型名是否和ollama list一致、日志里有没有报错、消息是否被allowedGroups过滤掉了。4. 模型接入的几种路线Ollama、LM Studio 与云端 API4.1 Ollama最省心的本地模型方案Ollama 是目前本地跑模型最方便的工具一条命令就能拉模型、起服务。OpenClaw 对接 Ollama 也是最常见的组合。安装 Ollamacurl -fsSL https://ollama.com/install.sh | sh拉一个模型ollama pull qwen2.5:7b然后确认服务在跑ollama list curl http://127.0.0.1:11434/api/tags如果curl能返回模型列表说明 Ollama 正常。这时候 OpenClaw 配置里的baseUrl填http://127.0.0.1:11434就能连上。关于ollama本地部署大模型哪个模型最佳这个问题我的经验是中文聊天场景Qwen 系列表现最稳英文为主可以选 Llama 系列如果机器资源紧张Phi 或者 Gemma 的小尺寸版本也能凑合用。7B 是甜点尺寸再小智商不够再大资源吃不消。4.2 LM Studio图形界面党的选择LM Studio 适合不想碰命令行的人它有图形界面下载模型、加载模型都是点按钮。它默认的 API 端口是 1234OpenClaw 配置里把baseUrl改成http://127.0.0.1:1234/v1就行。LM Studio 的好处是模型管理直观能看到每个模型占多少显存还能调 GPU 层数。坏处是它是个桌面应用在无头服务器上跑不了。所以我的建议是本地开发调试用 LM Studio正式部署到服务器用 Ollama。4.3 云端 API 作为兜底本地模型再强遇到复杂任务还是不如云端大模型。OpenClaw 支持配置多个模型源可以设置一个本地模型做日常聊天遇到特定关键词或者复杂问题再转发给云端 API。这种混合模式兼顾了成本和能力。配置上通常是在model下面加一个fallback字段指定备用模型。具体写法看版本但思路是主模型超时或者返回错误时自动切到备用模型。5. 高频报错与排查实录5.1 WSL2 环境验证失败openclaw could not safely verify the wsl2 environment这个报错出现在 Windows WSL2 的组合下。OpenClaw 启动时会检查运行环境如果它无法确认自己在一个正常的 WSL2 里就会拒绝启动。原因通常有几个WSL2 没装好、WSL 版本是 1 不是 2、或者 WSL 里的网络配置有问题。排查步骤# 在 PowerShell 里查看 WSL 版本 wsl -l -v # 如果 VERSION 显示 1需要转换 wsl --set-version Ubuntu 2如果 WSL2 正常但还报这个错可能是 OpenClaw 的环境检测逻辑对某些 WSL 发行版不兼容。这时候可以看看有没有跳过检测的环境变量或者在 issue 里搜一下有没有人遇到同样的问题。5.2 Node.js 模块导出错误前面提到的node.js 18 the requested module node:util does not provide an export named根因是 Node 版本太低。解决办法就是升级 Node。但要注意升级之后要重新npm install因为有些原生模块需要针对新版本重新编译。nvm install 20 nvm use 20 rm -rf node_modules package-lock.json npm install5.3 消息发出去了但没回复热词里有个很具体的现象openclaw能发消息微信.但微信发消息没回复。这个问题的排查链路比较长我按概率从高到低列一下第一模型服务挂了。先curl一下 Ollama 的接口确认模型能正常返回。第二上下文超了。如果contextWindow设得太大历史消息把 token 占满了模型就没空间生成回复。把contextWindow调小试试。第三消息被过滤了。检查allowedGroups和triggerPrefix确认你发消息的会话在允许列表里且消息内容符合触发规则。第四登录态失效。有些平台的登录态会过期需要重新扫码。日志里通常会有session expired之类的提示。第五平台风控。如果短时间内发太多消息平台可能临时限制账号。这种情况只能等或者降低rateLimit。5.4 常见问题速查表现象可能原因排查动作启动即报错退出Node 版本不对node -v确认 ≥18二维码不显示终端不支持图片输出用支持六线图的终端或查看生成的图片文件模型连接超时Ollama 没启动或端口不对curl http://127.0.0.1:11434/api/tags回复内容乱码编码问题检查终端和配置文件的编码设置内存占用飙升上下文累积过多调小contextWindow重启服务扫码后无反应登录态保存失败检查会话存储目录的写权限6. 几个容易被忽略的实操细节6.1 会话存储目录的权限OpenClaw 会把登录态、上下文缓存写到本地目录。如果这个目录权限不对会出现扫码成功但重启后又要扫的情况。建议把存储目录设在一个当前用户有读写权限的地方别放在/root或者系统目录下。mkdir -p ~/.openclaw/sessions chmod 700 ~/.openclaw6.2 后台运行与日志管理npm start是前台运行关掉终端就停了。正式用的话建议用pm2或者systemd托管。用 pm2npm install -g pm2 pm2 start npm --name openclaw -- start pm2 logs openclaw pm2 save pm2 startup这样服务会常驻崩溃了自动重启日志也能随时看。6.3 模型切换的成本换模型不是改个配置就完事。不同模型的 prompt 格式不一样有些模型对 system prompt 敏感有些对上下文长度敏感。换模型之后建议先跑几轮测试对话确认回复质量符合预期再正式用。另外Ollama 加载新模型需要时间第一次请求会慢之后模型常驻内存就快了。如果机器内存不够Ollama 会自动卸载不用的模型下次请求再重新加载这个切换过程会有几秒延迟。6.4 关于卸载热词里有openclaw卸载说明有人装完发现不合适想删。卸载其实很简单停掉服务删掉代码目录删掉会话存储目录如果装了 pm2 就pm2 delete openclaw。但要注意如果你在配置里填了云端 API 的 key记得去对应平台把 key 吊销掉别留着。7. 这套东西还能怎么扩展跑通基础功能之后OpenClaw 的可玩性其实挺高。比如可以接多个模型源按消息内容路由到不同模型可以写自定义工具函数让模型能查天气、查数据库可以把上下文存到 Redis 里支持多实例部署。我自己比较常用的一个扩展是加了个静默模式在特定群里机器人只记录消息不回复需要的时候用命令让它总结最近聊了什么。这个功能靠改一点代码就能实现比翻聊天记录高效多了。另一个思路是把它当成一个本地 AI 网关不只接聊天软件还可以接其他需要 AI 能力的本地服务。OpenClaw 的架构本身是解耦的消息接入层和模型调用层分开改起来不算难。最后分享一个小技巧部署的时候把日志级别调到 debug虽然输出多但出问题的时候能省很多排查时间。等稳定运行一周之后再调回 info 级别减少日志量。这个习惯帮我省过好几次通宵排查的功夫。