先交代一下背景我最近把 OpenClaw 这个项目完整跑了一遍而且是同时在三类环境里折腾——Windows 主力机、Ubuntu 服务器、手机 Termux。这项目本身不复杂核心是一个基于 Node.js 的开源智能体框架把大模型接到命令行工作流里让 AI 能直接调工具、读写文件、执行任务。但真正让人头大的从来不是功能而是开发环境。网上搜“openclaw”相关的问题十有八九是环境安装类的什么 WSL2 无法安全验证、node 版本不对、Ollama 接不上、怎么卸载等等。这篇文章就是把我实测过的环境方案、判断思路、踩过的坑一次性讲清楚给准备捣鼓 OpenClaw 的人一条能直接抄的路线。1. OpenClaw 项目定位先搞懂你在搭什么环境1.1 核心定位一个能跑在命令行里的开源智能体先打消一个误区OpenClaw 不是某个大模型本身而是一个“AI 助手外壳”。你可以把它理解成一个调度中心负责连接大模型云端 API 或本地模型都行和你本机的操作系统能力。你给它一个任务它会自己拆解、规划调用对应工具去执行比如读写文件、跑脚本、请求接口最后把结果整理给你。这种思路和 Claude Code、WorkBuddy 这类工具有共通之处本质上是“模型 工具 工作流”的组合。而 OpenClaw 之所以值得单独折腾一是因为完全开源可改造二是因为部署形态非常灵活不绑死某一家云服务。但灵活的另一面就是麻烦有人装 Windows 当日常助手有人装 Ubuntu 服务器当后台服务有人用 Ollama 接本地模型离线跑还有人在手机 Termux 里折腾。每种形态的环境依赖完全不一样这是它环境问题特别多的根本原因。1.2 环境分析的价值别让精力全耗在“跑起来”上从热词分布就能看出来和 OpenClaw 相关的搜索里环境安装类占了绝对大头。这非常符合生态型开源项目的规律真正的门槛不是“怎么用”而是“怎么把它跑起来”。OpenClaw 横跨 Windows、Linux、Android每一端又有 Node.js 版本、包管理器、虚拟化层、本地模型运行时这些前置依赖排列组合之后问题数量爆炸。我实测下来一个很深的感受环境选型决定后续 90% 的体验。Windows 上选“原生安装”还是“WSL2 安装”后续网络、权限、性能问题的出现概率完全不同Linux 上选“Docker”还是“裸机”依赖冲突的排查难度不是一个量级。这篇文章就是把这些选择背后的利弊、适用场景、常见坑全部捋一遍你照着选就行少走弯路。2. 环境选型解析Node.js、WSL2 与包管理器2.1 Node.js 版本第一道门槛别追新OpenClaw 是 Node.js 生态项目装任何东西之前先确认 Node.js 版本。我的实测结论是能稳定跑 OpenClaw 的 Node.js 集中在 18.x 和 20.x 的 LTS 版本22.x 也能跑但如果你用的是刚发布没多久的大版本遇到原生模块编译失败的概率会明显上升。这里有个反常识的点很多人觉得版本越新越好但对 OpenClaw 这种依赖较多原生模块的项目Node.js 太新反而容易触发 node-gyp 编译失败报错是一大段 C 编译日志特别劝退。具体建议Windows直接去 nodejs.org 下载 LTS 安装包我用的 20.x一路下一步就行Ubuntu用 nvm 而不是 apt 源里的 Node.jsapt 源版本经常滞后Termux执行pkg install nodejs-lts同样避开最新版。装完在终端跑node -v和npm -v确认版本npm 最好在 9 以上。这一步做完后面会顺畅很多。2.2 WSL2 配置“无法安全验证”的真相热搜词里有句很典型的话“openclaw无法安全验证 WSL2 环境请在 powershell 中运行 wsl -- status”。这个场景是 Windows 用户准备在 WSL2 里跑 OpenClaw检查环境时发现 WSL 状态异常。错误提示让你在 PowerShell 里执行wsl --status这是非常标准的排查入口。这个报错本质大多数情况是WSL2 的内核组件没装全或者虚拟化功能被禁用了。注意 WSL 和 WSL2 完全是两回事WSL2 基于轻量虚拟机依赖 Windows 的“虚拟机平台”功能和一个独立 Linux 内核。如果系统更新后内核丢了或者 BIOS 里虚拟化被关了wsl --status就会显示异常。排查思路按下面顺序走管理员身份打开 PowerShell运行wsl --status看具体输出内容运行wsl --update更新内核打开“启用或关闭 Windows 功能”确认“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两项都勾选还不行就wsl --shutdown重启 WSL 服务再试。提示如果wsl --status提示需要开启虚拟化先去 BIOS 检查 SVMAMD或 Intel VT-x 开关是否打开。这个问题在老笔记本上特别常见和 OpenClaw 本身没关系。2.3 包管理器npm 就够了别自找麻烦OpenClaw 最常见的安装方式是通过 npm 全局安装流程极简npm install -g openclaw装完直接执行openclaw --version验证是否成功。这里有几个高频坑第一npm 下载慢或无响应。国内网络环境下先切换镜像源npm config set registry https://registry.npmmirror.com第二全局安装权限不足。Windows 下提示 EACCES 或 EPERM用管理员身份跑 PowerShellLinux 下如果全局路径是/usr/lib直接改装 nvm全局包会落在用户目录天然避开权限问题。第三要不要换 pnpm 或 yarn。我的意见文档明确写了 npm 就用 npm。pnpm 的全局包管理用了软链接机制在某些环境会导致 CLI 找不到可执行文件没必要在这种基础环节冒险。3. 算力接入API 模式还是本地模型这是个选择题3.1 OpenClaw 必须接 API 吗未必热词里有一条“openclaw只能用接入api的方式使用算力吗”很多新手都在问。答案是不必须。OpenClaw 的模型接入层是抽象过的既可以配 OpenAI、Anthropic 这类云端 API也可以接本地模型运行时最常用的就是 Ollama。两种模式各有各的适用场景对比维度API 模式本地模型Ollama响应速度依赖网络本地推理无网络延迟成本按 token 计费只有电费隐私数据经过第三方完全本地模型能力强可达 GPT-4 级别取决于机器一般 7B 以下部署门槛低高我的建议是尝鲜阶段先用 API 模式把流程跑通后续如果要长期用或涉及隐私数据再切本地模型。别一上来就在本地拉一个 13B 模型机器跑不动反而会冤枉 OpenClaw。3.2 Ollama 部署和 Qwen 系列模型选择用本地模型的话Ollama 是目前最省事的方案。安装方式如下Windows从 ollama.com 下载安装包Ubuntucurl -fsSL https://ollama.com/install.sh | shTermux能装但性能和内存限制太明显一般不推荐。装完拉模型ollama pull qwen2.5:3b热搜词里的“qwen2.5-3b 关联到 openclaw”指的就是把 Qwen2.5 3B 模型接到 OpenClaw 上。3B 参数模型大小约 2GB8GB 内存的机器可以跑但速度不会太快想要更流畅可以选 1.5B 或 3B要更强逻辑能力选 qwen2.5:7b但内存最好到 16GB。关于模型选型我的体感是OpenClaw 这种工具调用场景模型推理能力比闲聊能力更重要。你需要模型在正确时机调用正确工具太小的模型经常会把 JSON 指令格式写错导致工具调用失败。Qwen2.5 系列在中文和工具调用上表现均衡3B 起步可用7B 体验更稳。3.3 OpenClaw 接入 Ollama 的配置示例OpenClaw 的模型配置通常写在项目根目录的.env文件里。以常见实践为例本地模型模式OPENCLAW_MODEL_PROVIDERollama OLLAMA_HOSThttp://127.0.0.1:11434 OPENCLAW_MODELqwen2.5:3bAPI 模式OPENCLAW_MODEL_PROVIDERopenai OPENAI_API_KEYsk-xxxx OPENCLAW_MODELgpt-4o-mini配置完重启 openclaw 进程然后随便发一个简单任务看日志里有没有出现 Ollama 的请求记录。本地模型首次调用会有明显的模型加载等待时间这是正常的不是卡死。另外注意Ollama 默认监听 11434 端口如果有防火墙记得放行本机回环地址就行不需要对外开放端口。4. 三平台实操Windows / Ubuntu / Termux 部署实录4.1 Windows 部署原生和 WSL2 怎么选Companion 是什么热词里“openclaw windows companion 怎么配置”问得很多。Companion 是 OpenClaw 在 Windows 端的桌面伴侣程序主要做系统级集成比如剪贴板读取、通知推送、后台常驻。纯 Node.js 的 CLI 进程在 Windows 上很难实现这些功能所以 Companion 应运而生。我的经验如果只在命令行里跑任务不装 Companion 也行但想让 OpenClaw 变成桌面常驻助手就得装。Companion 配置流程大致是先按前面步骤装好 OpenClaw CLI再从项目 release 页面下载 Companion 安装包启动后它会自动发现本地已有的 OpenClaw 配置并配对。配对成功后系统托盘能看到图标。如果没自动发现手动在 Companion 设置里把 CLI 路径指过去。关于 Windows 下原生 vs WSL2 的选择场景推荐方案日常命令行使用Windows 原生最省事系统级集成剪贴板、通知Windows 原生 Companion服务器级长期运行Ubuntu systemd应急、尝鲜Termux需要注意的是WSL2 里跑 OpenClaw 时网络是 NAT 模式WSL 内部访问 Windows 主机上的 Ollama 服务时host 要填 Windows 主机的 IP不能用 127.0.0.1。这个 IP 可以在 WSL 里通过ip route查看默认网关或者直接查/etc/resolv.conf里的 nameserver。4.2 Ubuntu 部署从裸机到 Nginx 反代Ubuntu 是所有平台里最省心的。完整流程如下# 1. 安装 nvm 并安装 Node.js 20 LTS curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 # 2. 全局安装 OpenClaw npm install -g openclaw # 3. 初始化配置 openclaw init这里有个 Ubuntu 特有的坑apt 源里的 Node.js 版本通常很老升级也麻烦所以强烈推荐 nvm。如果要把 OpenClaw 做成常驻服务可以写一个 systemd unit[Unit] DescriptionOpenClaw Agent Afternetwork.target [Service] ExecStart/root/.nvm/versions/node/v20.17.0/bin/openclaw serve Restartalways Userroot [Install] WantedBymulti-user.target另外热词里“本地虚拟机 多端口nginx 开发环境多站点自定义域名配置”是另一个常见场景本地或虚拟机里跑多个开发环境用 Nginx 按域名路由到不同端口。OpenClaw 也可以作为一个站点暴露在外Nginx 配置核心就一句话server { server_name agent.mydev.local; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; } }然后在 hosts 或内网 DNS 把自定义域名指到 Nginx 所在机器配合多个 server 块就能实现一个 Nginx 多站点、多域名路由多个开发服务。4.3 Termux 手机端能装但要降低预期“如何用termux安装openclaw手机版下载步骤”是热词里比较硬核的一条。Termux 是 Android 上的终端模拟器相当于随身携带的迷你 Linux 环境。理论上 OpenClaw 可以装pkg update pkg upgrade pkg install nodejs-lts git npm install -g openclaw openclaw --version但实测下来有三大硬伤性能手机 CPU 跑本地模型基本没戏API 模式勉强能用后台保活Android 系统会杀掉 Termux 后台进程锁屏后 OpenClaw 就断连了需要 wakelock 类工具辅助交互命令行在手机屏幕上操作很别扭应急可以日常不推荐。所以 Termux 的定位就是验证流程、纯粹尝鲜不要指望它替代桌面端。另外 Termux 的包管理用的是 pkg对 apt 的封装版本更新节奏比较慢如果 npm 安装时报依赖错误多半是系统包太旧先执行pkg upgrade再重试。5. 常见问题速查与排查实录5.1 WSL 状态异常修复手册现象wsl --status输出组件缺失或者提示虚拟化未开启。排查顺序wsl --update→ 重启 Windows → 检查 BIOS 虚拟化开关。如果wsl --status完全无输出大概率是 WSL 服务没起来先执行wsl --shutdown再执行wsl --status。这个问题在 Windows 大版本更新后特别容易出现本质上和 OpenClaw 无关但很容易被误解为 OpenClaw 的问题。判断标准很简单单独在 WSL 里跑node -v如果也报错说明问题出在 WSL 层不是 OpenClaw。5.2 Node.js 版本导致的安装失败现象npm install 时报 node-gyp 错误、找不到 python、提示缺少 Visual Studio Build Tools。排查思路先确认 node 版本不是 LTS 就切到 20.x。Windows 下用 nvm-windows 管理Linux 下用 nvm。Windows 下 node-gyp 报错时最简单的方案是安装 Visual Studio Build Tools 中的“使用 C 的桌面开发”组件这基本能解决所有原生模块编译问题。这里多说一句如果不想装编译工具链另一个办法是找项目 release 里的预编译二进制包就是在搜“openclaw windows companion 怎么配置”时经常能看到的那些预构建产物。能用预编译就别自己编译省心。5.3 到底怎么卸载干净热词的“怎么卸载 openclaw”必须单独回答。很多人在卸载时只执行了一条 npm 命令结果发现配置残留还影响第二次安装。# 卸载全局 CLI npm uninstall -g openclaw # 清理用户配置目录Linux / macOS rm -rf ~/.openclaw rm -rf ~/.config/openclaw # Windows 下额外清理 rd /s /q %USERPROFILE%\.openclawWindows 上如果装过 Companion还要去系统的“应用”列表里卸载 Companion并确认任务管理器里相关进程已退出。npm 卸载只删命令行工具配置和日志文件不会被自动清理这是最常见的残留来源。重新安装前一定要把配置目录清理干净否则可能出现新旧版本配置不兼容的诡异问题。再补充一个排查技巧卸载后如果端口还被占用说明某个 openclaw 子进程还在后台跑。Windows 上用netstat -ano | findstr 端口号找到 PID再在任务管理器里结束Linux 上用lsof -i :端口号或者fuser -k 端口号/tcp强制释放。6. 最后说点个人体会几轮部署下来我最大的感受是环境搭建的问题90% 来自没有先想清楚自己的使用场景。比如有人为了在 Windows 上用 OpenClaw先装虚拟机、再装 Docker、再配端口映射绕了一大圈结果 OpenClaw 原生安装一把就完事。还有人非要追求最新版 Node.js结果被 node-gyp 折磨一下午。先回答三个问题再动手一是用 API 还是本地模型二是 Windows 原生还是 Ubuntu 服务器三是全面使用还是简单尝鲜。想清楚之后照着这篇文章的对应路线选一条走到黑基本不会出大问题。最后分享一个实用小技巧无论哪个平台配置好环境后第一时间执行openclaw doctor如果有这个命令的话或者openclaw --version做个自检确认所有依赖都正常。然后跑一个最小任务比如让它读一下当前目录文件列表确认模型链路通不通。环境这东西跑通一次就值了。