如果你最近在折腾个人AI助理多半听过 OpenClaw 这个名字。先说人话它不是什么花里胡哨的聊天机器人而是一套开源的“个人AI网关”——负责把大模型、本地工具、笔记知识库串成一条完整的工作流。今天这篇不聊概念把我从零到一安装 OpenClaw 的完整过程、踩过的坑、以及排查思路全部摊开直接照着做就能跑通。文章节奏适合两类人一类是刚接触 WSL2、想在 Windows 上跑通全套的另一类是手里有 Ubuntu 服务器、想直接上生产环境的。1. 先搞清楚 OpenClaw 是什么再决定装在哪1.1 它不是聊天机器人是个人AI网关很多人第一次看到 OpenClaw 这个名字以为是个对话软件装上之后跑去跟它聊天结果发现它不务正业——真正干活的其实是“调度”。你可以把 OpenClaw 理解成一个中转大脑你给它一个指令它判断需要用哪个模型来理解、需要调用哪个工具来执行然后把结果拿回来整理给你。举个例子。你跟它说“把 Obsidian 里昨天记录的三个想法做成表格发我邮箱”它内部会做三件事先调用模型解析意图然后读取 Obsidian 指定目录下的笔记再通过邮件插件把表格发出去。整个过程不是简单一问一答而是多步骤、多工具协作。这类设计思路现在很多 AI 助理框架都在用源头就是这类早期开源网关产品的核心理念。从技术架构看OpenClaw 大概由几个部分组成核心引擎负责流程编排和模型调度、插件系统负责对接各种外部工具、命令行工具CLI以及面向桌面的 Companion 组件。不同的部署方式涉及的组件不一样这也是为什么安装文档看起来五花八门其实都是在装同一套东西的不同切片。搞清楚这个定位很重要因为后面所有安装选择都围绕它展开既然核心是调度和工具调用那么运行环境的稳定性、Node.js 版本的兼容性、网络的连通性就比模型本身的大小更关键。1.2 Windows、WSL2、Ubuntu 服务器怎么选OpenClaw 的依赖栈偏向 Linux 生态尤其是原生模块编译、shell 工具链、systemd 托管这些能力在 Linux 下最顺。所以在 Windows 上装绕不开 WSL2如果你的主力环境就是 Ubuntu那可以直接省掉一层虚拟化。我自己的实践是“双轨并行”日常调试用 Windows 11 WSL2Ubuntu 22.04因为图形界面方便、改配置直观长期运行的实例放在一台 Ubuntu 24.04 小服务器上用 systemd 托管开机自启稳得很。选型逻辑很简单本地 Windows 适合开发、测试、折腾——你可以在里面随便造坏了就删了重建服务器适合稳定运行——装好了就别乱动交给 systemd 看管。两个环境的核心安装步骤完全一致区别只在服务托管方式上。后面我会把两条路线都走一遍你先确定自己走哪条再对应看章节即可。这里有个小提醒如果你只是好奇想试试优先选 Windows WSL2门槛最低如果你是要给团队或者家庭提供长期可用的服务那直接上 Ubuntu 服务器省得后面迁移。2. Windows 11 宿主环境搭建把 WSL2 地基打牢2.1 一条命令启用 WSL2 并完成状态检查Windows 下安装 OpenClaw先说难听的话90% 的失败都发生在 WSL2 环境本身而不是 OpenClaw。所以地基必须打好。打开 PowerShell管理员权限执行wsl --install -d Ubuntu这条命令会把 WSL 功能、虚拟机平台、Linux 内核更新包一次性装好然后自动下载 Ubuntu 发行版。装完要求重启时照做别拖着因为后续所有步骤依赖这次重启生效。重启之后打开 PowerShell先看状态wsl --status wsl -l -vwsl --status主要看“默认版本”是不是 2。如果显示“默认版本1”说明之前装过旧版 WSL需要手动升级wsl --set-version Ubuntu 2如果wsl --status报错或者提示找不到 WSL那就先执行wsl --update升级内核再重新检查。wsl -l -v是查看发行版列表和每个发行版的 WSL 版本号确保 Ubuntu 那一行显示的是 2。首次进入 Ubuntu 会要求创建 UNIX 用户名和密码这个账号是 WSL 里的 Linux 用户跟 Windows 账号完全独立别跟微软账号搞混。密码输入时不会显示这是正常的不是键盘坏了。进系统之后建议顺手做两件事。第一更新软件源sudo apt update sudo apt upgrade -y第二编辑/etc/wsl.conf启用 systemd因为后面很多服务需要它[boot] systemdtrue改完退出 WSL在 PowerShell 里执行wsl --shutdown再重新进让配置生效。可以验证一下systemctl is-system-running如果输出running或者degraded不是offline说明 systemd 正常。这一招是很多人容易漏掉的不配 systemd后面有些服务启停会比较别扭。2.2 在 WSL 内部安装 Node.js别用 Windows 版本冒名顶替OpenClaw 基于 Node.js 开发所以 Node 环境必须有。这里有个新手最容易踩的坑跑去 Node.js 官网下载了 Windows 安装包装完之后发现 WSL 里用不了。因为你打开的终端是 Ubuntu 环境它不认识 Windows 安装的 node 命令。正确做法是在 WSL 内部安装 Linux 版 Node。推荐用 nvmNode 版本管理器方便后续切换版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 node -v npm -v输出版本号就说明装好了。选 20 的原因很简单它是当前 LTS长期支持版兼容性最好OpenClaw 这类项目对 Node 版本的要求一般是 1820 既能满足又不会太激进。别一上来装最新版 Node 24 之类有些原生依赖还没跟上容易翻车。那 Node.js 官网到底要不要去如果你是在 WSL 里装不需要如果你是 Ubuntu 服务器直装更不需要同样用 nvm 或者 apt 都行。官网下载那个只有一种情况需要考虑你不想用 WSL非得在 Windows 原生环境跑。但我实测下来不建议OpenClaw 很多依赖在 Windows 原生环境编译容易出幺蛾子WSL 里反而一次过。装完 Node最好再补一组编译工具链以防 npm 安装时碰到需要编译原生模块的包sudo apt install build-essential python3 make g -y这些是常见的 C/C 编译依赖某些 npm 包在安装时会自动编译缺了就会报gyp ERR!之类的错误。提前装好后面省事。3. 在 WSL2 里完成 OpenClaw 核心安装与首次启动3.1 克隆仓库与依赖安装全过程环境就绪后进入 WSL 终端开始安装 OpenClaw。我这里选择的是克隆官方仓库的方式而不是直接用 npm 全局安装——原因稍后说。cd ~ git clone https://github.com/openclaw/openclaw.git cd openclaw仓库地址以官方文档为准如果你的网络访问 GitHub 不稳定可以配置镜像或手动下载压缩包。克隆完之后先看看项目结构确认有package.json和模板配置文件这说明仓库是对的。接下来安装依赖npm install如果项目有package-lock.json也可以用npm ci它按锁定文件精确安装速度更快、版本更一致。npm install 耗时取决于网络和机器性能几分钟到十几分钟都可能耐心等。这一步如果报错大部分原因是缺编译工具链也就是上一节装的那一组包还有一类是 Node 版本太低换成 20 就行。npm 输出里有gyp ERR!字样基本就是编译问题回到 2.2 检查环境。装完之后项目里一般会有一个环境变量模板文件比如.env.example。把它复制成真正的配置文件cp .env.example .env这个.env就是 OpenClaw 的配置文件后面所有模型、端口、令牌都在这里设置。先把文件打开看看有哪些必填项——通常会有模型供应商的 API Key、服务监听端口、以及一些路径配置。这一步不要跳过直接盲启动十有八九会报缺配置。3.2 编写 .env 配置并把模型接上OpenClaw 支持接入多种模型来源包括各大云厂商的 API以及本地跑的模型。配置方式都是改.env。以最常用的云端模型为例你需要填入你的 API Key 和模型名称OPENCLAW_MODEL_PROVIDERopenai OPENCLAW_MODEL_API_KEYsk-xxxx OPENCLAW_MODEL_NAMEgpt-4o-mini注意不同的服务商要求的字段名可能不一样具体看官方模板里的注释。如果你用的是国内云厂商的 OpenAI 兼容接口通常还要加一个OPENCLAW_MODEL_BASE_URL指到厂商提供的地址。如果不想用云端模型想本地跑那就指向本地推理服务的兼容接口例如 Ollama 起的服务。这个我在 5.2 里详细展开这里只需要知道配置结构就行OPENCLAW_MODEL_PROVIDERopenai OPENCLAW_MODEL_BASE_URLhttp://localhost:11434/v1 OPENCLAW_MODEL_API_KEYollama OPENCLAW_MODEL_NAMEqwen2.5:3b配置完先别急着填一堆高级参数把最基本的这几项设置好能启动、能对话再逐步加高级功能。这个安装顺序很重要我见过太多人第一步就试图把所有插件配齐结果不知道是哪个环节出了问题排查一晚上。先跑通最小闭环再谈扩展。3.3 首次启动与健康检查配置好.env之后就可以启动了。根据项目实际情况启动命令可能是npm run dev或者项目自带 CLI 入口npx openclaw start以你实际拿到的项目 package.json 里 scripts 为准。启动后观察日志输出如果看到类似 “OpenClaw is running on http://localhost:3000” 的字样说明核心服务已经起来了。这时候做两个验证。第一个用命令行工具直接问一句openclaw chat 你好介绍一下你自己如果它正常回复说明模型调度链路是通的。第二个在 WSL 里用 curl 检查健康接口curl http://localhost:3000/health返回ok或者{status:ok}就说明 HTTP 服务正常。这里补充一个细节WSL2 默认把 Linux 里监听的 localhost 端口自动转发到 Windows所以你在 Windows 浏览器里直接访问http://localhost:3000也能通不需要额外做端口映射。但反过来的情况需要注意WSL2 内要访问 Windows 宿主机上的服务不能用 localhost因为两个是独立的系统。我在配置 Windows Companion 时就被这个问题卡过Companion 跑在 Windows 上OpenClaw 跑在 WSL 里两边通信的地址到底怎么写其实因为 localhost 自动转发Windows 访问 WSL 服务直接用 localhost 就行。如果你发现访问不了先检查 WSL 里服务是不是在监听0.0.0.0或127.0.0.1防火墙有没有拦截。4. Ubuntu 服务器直装 OpenClaw从零到 systemd 托管4.1 基础环境准备新装系统 30 分钟搭好运行环境手里有云服务器或者家里的 NAS 跑 Ubuntu思路和 WSL2 类似但少了虚拟化这一层更干净。我用的是 Ubuntu 24.04以下命令同样适用于 20.04 和 22.04。先更新基础软件包sudo apt update sudo apt upgrade -y然后安装编译工具链和 Gitsudo apt install git curl build-essential python3 make g -y接下来装 Node.js。服务器上我不会用 apt 直接装的默认版本通常偏旧仍然用 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 node -v有一点跟本地环境不同服务器上最好创建一个独立用户来运行 OpenClaw不要直接拿 root 跑。这不是形式主义而是安全习惯——万一服务被攻破攻击者拿到的权限被限制在普通用户范围内不至于一锅端。sudo useradd -m -s /bin/bash openclaw后续的 OpenClaw 文件都放在这个用户的家目录下。你可以用su - openclaw切换到该用户再继续安装或者先以 openclaw 身份登录操作。4.2 用 systemd 让 OpenClaw 常驻后台WSL 里面服务怎么折腾都行关了终端就停没关系但服务器上不行用户随时可能来访问服务必须常驻、开机自启、崩溃自动拉起。这些交给 systemd 最合适。安装步骤跟前面一样以 openclaw 用户身份克隆仓库、配置.env、装依赖。区别在于启动方式从“手动执行 npm run dev”改成 systemd 托管。创建一个 service 文件sudo vim /etc/systemd/system/openclaw.service内容大致如下[Unit] DescriptionOpenClaw Personal AI Gateway Afternetwork.target [Service] Useropenclaw WorkingDirectory/home/openclaw/openclaw ExecStart/home/openclaw/.nvm/versions/node/v20.19.4/bin/npx openclaw start Restartalways RestartSec5 EnvironmentFile/home/openclaw/openclaw/.env [Install] WantedBymulti-user.target注意ExecStart里的 npx 路径要写绝对路径因为 systemd 的环境和登录 shell 不同找不到 PATH。可以先用which npx查看路径再填进去。启动服务并设置开机自启sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw查看运行状态和日志systemctl status openclaw journalctl -u openclaw -f看到日志里出现监听端口的输出服务就起来了。以后更新代码只需要进目录git pull npm install然后sudo systemctl restart openclaw即可不用手动 kill 进程比本地开发干净得多。4.3 安全加固端口监听与反向代理建议服务起来之后先别急着往外网开放。OpenClaw 默认监听本机 127.0.0.1这是最安全的状态——只有本机能访问。如果你只想内网用那保持这个默认值再通过 SSH 隧道访问也行。如果需要对外提供服务建议不要直接暴露 OpenClaw 端口。正确姿势是前面套一层反向代理Nginx 或 Caddy把域名或子路径转发到 OpenClaw 的本地端口同时加上 TLS 和访问认证。Caddy 配置最省事几行搞定自动 HTTPSclaw.example.com { reverse_proxy 127.0.0.1:3000 }再加一层基本认证或者 OAuth避免服务裸奔在公网。模型 API Key 也存在.env里如果 OpenClaw 被未授权访问等于把 Key 暴露给全世界这个后果很严重。所以对外暴露端口这件事能不做就不做非要做必须套反代加认证。我在服务器上的实践是默认绑定 127.0.0.1外网访问走 Tailscale 之类的组网工具连公司电脑直接访问内网地址不开公网入口。这是最省心的方案既安全又不需要申请证书。5. 集成配置实战Windows Companion、Obsidian 与本地模型5.1 Windows Companion 配置要点Companion 是 OpenClaw 跑在 Windows 宿主机的配套组件作用是把系统级能力桥接给 WSL 里的服务比如托盘图标、全局快捷键、剪贴板读写、系统通知这类桌面体验。很多人装 OpenClaw 是为了把它当后台服务用其实配合 Companion 才算真正落地到日常使用。安装 Companion 一般有两种方式从官方 Release 页面下载安装包或者通过 npm 以工具形式安装。看你的版本决定。装完之后首次启动会要求填写核心服务地址和访问令牌——核心服务地址就是 WSL 里 OpenClaw 监听的端口由于 WSL2 的 localhost 自动转发所以填http://localhost:3000访问令牌在.env里配置没有的话去加一个。配置完成后重点验证一件事Windows 上的 Companion 能不能正常连上 WSL 里的 OpenClaw。如果连接失败排查顺序是WSL 里的服务有没有在跑ps aux | grep openclaw端口监听在哪个地址netstat -tlnp如果只监听 127.0.0.1Companion 从 Windows 访问 localhost 也能通因为转发是基于 localhost 的Windows 防火墙有没有拦截首次运行通常会弹窗询问是否允许必须点允许否则连接会被静默拦截这里有个实操心得很多时候 Companion 连不上不是配置错了而是你根本没在 WSL 里启动 OpenClaw。WSL 服务不会自动常驻关掉终端它就没了。如果你希望它常驻要么用 tmux 挂着要么像服务器那样也配置 systemdWSL 里开了 systemd 之后同样支持。5.2 将 Qwen2.5-3B 本地模型关联到 OpenClawOpenClaw 不一定非要接付费 API本地模型也能跑得很好。我用得最多的组合是 Qwen2.5-3B Ollama3B 参数量的模型量化之后占用大约 2GB 内存普通笔记本的 CPU 也能跑生成速度虽然比不上云上大模型但胜在免费、离线、数据不出本地。先在 WSL 或服务器上安装 Ollamacurl -fsSL https://ollama.com/install.sh | sh拉取模型ollama pull qwen2.5:3b然后确认 Ollama 的 OpenAI 兼容服务已经开启。Ollama 默认监听http://localhost:11434它的/v1接口兼容 OpenAI 格式所以 OpenClaw 可以直接把它当作模型服务商来配置。回到 OpenClaw 的.envOPENCLAW_MODEL_PROVIDERopenai OPENCLAW_MODEL_BASE_URLhttp://localhost:11434/v1 OPENCLAW_MODEL_API_KEYollama OPENCLAW_MODEL_NAMEqwen2.5:3b重启 OpenClaw再试试对话。这里有个细节如果 OpenClaw 和 Ollama 装在同一台机器localhost 没问题如果 Ollama 在另一台机器BASE_URL要改成那台机器的 IP。在 WSL 场景下如果 Ollama 装在 Windows 宿主机WSL 里访问宿主机不能写 localhost要从/etc/resolv.conf里找 nameserver 地址那个才是宿主机 IP所以BASE_URL写成http://宿主机IP:11434/v1。实测体验方面Qwen2.5-3B 在中文指令理解上表现超出预期做笔记整理、文本分类、简单问答都够用但如果要代码生成、长文写作、复杂推理建议还是路由到云端大模型。OpenClaw 如果支持多模型路由可以按任务类型分模型调用这个后面再展开。5.3 Obsidian 接入让笔记成为 AI 的记忆库Obsidian 是本地 Markdown 笔记软件很多人积累了几百上千条笔记但检索困难。把 OpenClaw 和 Obsidian 打通之后相当于给 AI 装了一个私有长期记忆库——你可以直接问它“我上次记录的关于家庭网络改造的思路是什么”它会在你的笔记库里检索并回答。接法目前比较常用的是两条路径。第一条Obsidian 装一个本地 REST API 插件把笔记库暴露成 HTTP 接口OpenClaw 通过插件模块去调用第二条直接把 Obsidian 的 Vault 目录挂载给 OpenClaw 只读访问。在 WSL 里Windows 的 Vault 路径通常在/mnt/c/Users/你的用户名/Documents/笔记库直接配置指向即可。服务器上则要把 Vault 同步过去或者通过 WebDAV 方式访问。配置层面在.env或配置文件里加类似这样的路径OPENCLAW_OBSIDIAN_VAULT/mnt/c/Users/YourName/Documents/MyVault OPENCLAW_OBSIDIAN_READONLYtrue配置好之后你可以在对话里试探性问一条笔记里的内容验证是否生效。注意默认保持只读模式很重要别让 AI 随便往 Vault 里写文件。真要让它写指定一个专门的Inbox目录把自动写入范围限制住否则几百条笔记被改得乱七八糟想恢复都难。我自己的使用体验是这一项集成带来的价值最大。装上之后笔记库终于在“记录”之外有了“召回”能力之前躺在文件夹里的想法开始被反复使用这是我装 OpenClaw 之后最满意的一个收益。6. 常见故障排查实录从 “无法安全验证” 到端口冲突6.1 “无法安全验证 WSL2 环境” 的根因与三步排查安装过程中很多人会碰到一条报错大意是“无法安全验证 WSL2 环境请在 PowerShell 中运行 wsl --status”。第一次遇到时确实让人慌像是环境坏了其实大部分情况下是 WSL 内核版本太旧或者虚拟化平台没完整开启。遇到这个报错不要急着重装 OpenClaw按下面顺序排查基本都是几分钟内解决。第一步在 PowerShell 运行wsl --status重点看“默认版本”是不是 2。如果显示 1 或者提示“没有已安装的分发”执行wsl --update更新 WSL 内核。这个命令会把 WSL 本身升级到最新版覆盖很多旧版本兼容问题。第二步检查 Windows 功能。到“控制面板 - 启用或关闭 Windows 功能”确认两个条目都勾选适用于 Linux 的 Windows 子系统、虚拟机平台。如果之前只勾了第一个第二个缺失会导致 WSL2 无法正常工作报错就会指向环境验证失败。改完勾选需要重启电脑。第三步彻底重启 WSLwsl --shutdown再重新进入 WSL。很多人配置完 /etc/wsl.conf 或升级完内核没有冷重启旧进程还占着验证脚本读到的是残旧状态。这一步虽然简单但非常有效。照这个顺序走完绝大多数 “无法安全验证 WSL2 环境” 的问题都会消失。说实话这个报错 90% 是 WSL 自身状态问题不是 OpenClaw 的锅。6.2 WSL 状态核验速查表为了方便查阅我把自己常用的几条 WSL 命令整理成一张表。Powershell 里执行记得有疑问先跑一遍再折腾其他东西。命令作用用什么状态判断wsl --status查看 WSL 整体状态和默认版本默认版本应显示 2wsl -l -v查看所有发行版及其 WSL 版本Ubuntu 的 WSL 版本应为 2wsl --update更新 WSL 内核提示“已安装的 Windows 组件都是最新的”wsl --shutdown停止所有 WSL 虚拟机无输出再执行 wsl 重新进入wsl --set-version Ubuntu 2把发行版切换到 WSL2显示“转换已完成”wsl --export / wsl --import备份和还原发行版生成.tar文件在 WSL 内部还可以检查 systemd 状态systemctl is-system-running输出running或degraded都算正常degraded表示有非关键服务失败不影响主要功能。如果是offline说明 systemd 没起来回到 2.1 检查/etc/wsl.conf。6.3 高频坑位清单与解决方案最后把安装过程中经常遇到的一批问题集中过一遍按我的经验按出现频率排序。第一坑npm install 报gyp ERR!。这是编译原生模块失败根因几乎都是缺build-essential和python3回到 2.2 把编译工具链装上即可。注意装完之后要重开终端或者source ~/.bashrc。第二坑端口被占用。OpenClaw 默认 3000 端口如果被其他服务占了启动会报EADDRINUSE。WSL 里用lsof -i :3000查占用进程Windows 里用netstat -ano | findstr :3000要么改 OpenClaw 端口要么停掉占用方的服务。第三坑服务能启动但 Windows 浏览器访问不到。先确认 WSL 里的服务监听地址如果是127.0.0.1正常应该能转发如果是::1或者只监听容器网络可能转发不上。解决方式是把监听地址改到0.0.0.0或者直接在 WSL 里用 curl 测本地链路区分是服务问题还是转发问题。第四坑内存占用过高。WSL2 默认最多使用宿主机一半内存被几个 Linux 环境同时吃满会很卡。在 Windows 用户目录下建.wslconfig限制内存和交换分区[wsl2] memory4GB swap2GB然后wsl --shutdown再重启生效。第五坑模型下载太慢。Ollama 拉取大模型动辄几个 GB官方源在国外高峰期确实慢。可以改从国内模型社区下载 GGUF 格式文件再通过 Modelfile 导入 Ollama或者直接用 llama.cpp 以 OpenAI 兼容接口跑。方法不唯一核心思路是模型文件不一定非要走 Ollama 的下载链路。第六坑误删或弄坏了 WSL 系统。这个我有惨痛教训折腾 OpenClaw 时把系统的 Python 环境改坏了WSL 直接进不去。建议在自己觉得环境正常时做一次备份wsl --export Ubuntu ~/ubuntu-backup.tar wsl --import OpenClawBackup ~/wsl-backup ubuntu-backup.tar一个 tar 包几 GB 到十几 GB但关键时刻能救命。这个操作不复杂强烈建议在开始折腾之前做一次。最后一个经验装 OpenClaw 真正耗时间的不是命令本身而是环境对齐。每走几步就用对应命令验证当前状态别一口气把一串命令全贴进去就跑尤其是 WSL 这种有状态的虚拟化底座一步错了后面会叠加出各种莫名其妙的报错。按顺序来把最小闭环先跑通再研究插件和自动化整个过程基本一小时以内能完成。我现在日常用得最多的场景就是让它在 Obsidian 笔记库里做检索和整理——那种“输入一句话拿到一条带引用笔记的完整回答”的体验绝对不是普通聊天框能替代的。