最近我把 OpenClaw 完整部署了一遍。从 Windows 侧准备 WSL2 环境到 Ubuntu 里装 Node.js、拉源码、装依赖再到接入 Qwen2.5 本地模型和 Microsoft Teams 渠道整个过程踩了不少坑。尤其是“无法安全验证 WSL2 环境”这个报错我在 PowerShell 里折腾了一个多小时才搞清楚原因。这篇文章是我自己的部署记录同时也是给准备上手 OpenClaw 的朋友的一份可以直接抄作业的实操指南。我会先把 OpenClaw 是什么、适合谁讲清楚然后按步骤拆解部署过程最后集中整理典型报错的排查思路。不管你是第一次听说 OpenClaw还是已经装到一半卡住了这篇文章应该都能帮到你。1. 先搞清楚 OpenClaw 是什么别急着装1.1 一个带工具的常驻 AI 助手OpenClaw 本质上是一个开源的 AI 助手框架以前叫 Clawdbot后来改过名字现在叫 OpenClaw。它跟你在网页上打开 ChatGPT、豆包这类聊天窗口不太一样OpenClaw 是一个常驻运行的进程你可以把它部署在自己的电脑、服务器或者云主机上然后通过 Discord、Microsoft Teams、Telegram、Slack 这些聊天渠道跟它对话。它最核心的区别在于“带工具”和“带记忆”。普通聊天窗口只能一问一答OpenClaw 可以把对话内容保存到本地文件下次再问的时候它能自己翻历史记录同时它还能调用一系列工具搜索网页、读取本地文件、执行命令、整理笔记等等。说白了OpenClaw 给大模型装上了手脚和记事本。这个设计思路其实很关键。很多人以为部署 OpenClaw 只是为了“私有化一个聊天机器人”但实际上它是一个可以持续使用、越用越懂你的助手框架。它解决的问题不是“怎么调用大模型接口”而是“怎么把大模型放到一个真实的工作流里”。1.2 适合谁部署不适合谁部署先泼一盆冷水OpenClaw 不是那种双击安装、五分钟搞定的软件。它需要你具备基本的命令行操作能力知道怎么改配置文件遇到报错的时候愿意自己去查日志。如果你是纯小白只想要一个网页聊天界面那 OpenClaw 现阶段不一定适合你。但如果你满足下面任何一个条件就很值得花一个下午折腾它你经常要用 Teams、Discord、Telegram 这类软件想直接在聊天窗口里调用同一个 AI 助手而不是来回切换网页你希望 AI 助手有长期记忆能记住你们一个多月前聊过的内容而不是每次开新对话就“失忆”你有本地显卡或者有足够的内存想跑 Qwen2.5、Llama 这类开源模型让数据不出本地你在用 Obsidian 这类知识库工具想让自己记的笔记能被 AI 助手真正读取和使用。我实际测下来上面这四种场景 OpenClaw 都能覆盖而且配置方式差别很大。下文会逐个展开。2. 部署前的环境准备每一步都要对2.1 Windows 用户先把 WSL2 装明白OpenClaw 官方推荐在 Linux 或 macOS 上运行。Windows 用户最常见的做法是装 WSL2 后在 Ubuntu 子系统里部署。我一开始就是在 Windows 上直接试结果很快撞上了开头提到的那个报错“无法安全验证 WSL2 环境请在 PowerShell 中运行 wsl --status”。这个报错的意思是 OpenClaw 的安装脚本在启动时检查当前系统是否满足运行条件发现 WSL2 没有正确启用或者版本不对。先别急着在 PowerShell 里敲命令先确认三件事。第一Windows 版本。WSL2 需要 Windows 10 版本 2004 及以上或者 Windows 11。老版本系统即便装了 WSL 也只是 WSL1跑不了 OpenClaw 需要的完整 Linux 环境。第二是否启用了“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个功能。以管理员身份打开 PowerShell运行dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart两个命令执行完重启电脑再继续。第三安装最新的 WSL2 内核并设置默认版本。重启后执行wsl --update wsl --set-default-version 2然后运行wsl --status看输出。正常应该看到“默认版本: 2”而且不会出现“WSL2 不受支持”的字样。如果这里一切正常接下来再打开命令行输入wsl进入 Ubuntu 子系统。我在这一步踩过的坑是之前电脑里装过 Docker Desktop它自带的 WSL 内核很旧导致wsl --update不走系统更新通道。解决方法是先把 Docker Desktop 退出或者单独执行wsl --update --web-download强制走网络下载最新内核。2.2 Ubuntu 里安装 Node.js版本别乱选OpenClaw 是基于 Node.js 写的对 Node 版本有明确要求需要 20.11.1 以上或者 22.x 以上。有些教程让你直接用apt install nodejs这在 Ubuntu 默认源里装的往往是 18.x装完 OpenClaw 大概率跑不起来。我推荐用 nvm 来管理 Node 版本。在 Ubuntu 终端里依次执行curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 node -v npm -v看到v22.x.x和10.x.x这样的输出就说明环境没问题。这里有一个容易被忽视的点nvm 是装在当前用户目录下的如果你在 Windows 的 PowerShell 里直接执行wsl进入默认用户没问题但如果你经常用sudo切到 root 用户会发现node命令不存在——因为 nvm 只对当前用户生效。OpenClaw 部署时建议全程使用你自己创建的普通用户不要用 root后面配置文件和密钥权限管理会省心很多。另外npm 的网络下载速度有时候会比较感人如果npm install长时间卡住可以临时把 npm 源切换到可用的镜像装完再切回来。这个因人而异我不展开记住“慢就换源”这个思路就行。2.3 模型接入的两种模式OpenClaw 本身不带模型它需要你提供一个可调用的大模型接口。部署前就要想清楚走哪条路。模式一是接入云端模型 API。这种方式最简单申请好 API Key 之后按照配置文档填进去就行OpenClaw 直接用启动参数或配置文件读取。模式二是接入本地模型。热词里提到的“qwen2.5-3b 关联到 openclaw”指的就是这一种。思路是先找一个本地模型的服务框架比如 Ollama把 Qwen2.5-3B 跑起来然后让 OpenClaw 通过本地 HTTP 接口去连接它。我在这一步刚开始犯了个糊涂我以为 OpenClaw 可以自己直接加载模型文件像跑 llama.cpp 那样。实际不是。OpenClaw 只是“客户端”模型要由 Ollama、LM Studio 这类“服务端”程序加载。换句话说你要同时起两个服务一个模型服务一个 OpenClaw 主程序两者通过接口互相通信。如果你有 NVIDIA 显卡建议优先考虑在 WSL2 里启用 GPU 直通来跑 Ollama体验会比 CPU 推理好不少。至少 8GB 显存跑 Qwen2.5-7B 是可以接受的3B 版本用 CPU 也能流畅跑起来内存 8GB 以上就行。3. 完整部署实操从拉代码到跑起来3.1 获取源码并安装依赖环境准备好之后开始实际操作。先到项目仓库把源码拉下来git clone https://github.com/openclaw/openclaw.git cd openclaw然后安装依赖。这个项目依赖不少npm install需要跑一段时间。建议安装前先看一眼项目里的package.json确认 Node 版本要求也顺便看看有哪些启动脚本这样后面不会对着文档发懵。安装依赖npm install如果项目有提供一键初始化脚本通常会在安装依赖后执行。以 OpenClaw 的常见流程来说核心动作是执行初始化命令它会引导你完成以下配置选择要使用的模型提供商填写 API Key 或本地模型服务地址选择要接入的聊天渠道设置数据存储目录我用过的很多 Node.js 项目初始化命令都是npx开头的因为这样可以在不全局安装的情况下直接调用项目里的 CLI 工具。OpenClaw 也是类似思路初始化命令大致是npx openclaw init执行后按交互提示一步步选。这里我不建议一路回车有些选项默认值并不适合你的实际环境。比如模型服务地址如果你用的是 Ollama默认可能是http://localhost:11434但 OpenClaw 跑在 WSL2 的 Ubuntu 里而 Ollama 也跑在同一个 Ubuntu 里这个地址没问题如果你把 OpenClaw 部署在云服务器上而模型服务跑在本机那就要把地址改成能被服务器访问到的内网或公网地址。3.2 配置文件的核心字段解读初始化完成后项目根目录下会生成一个配置文件。不同版本的字段名可能不一样但核心结构大致是固定的。我拿我自己的配置拆解一下{ model: { provider: ollama, model: qwen2.5:3b, endpoint: http://localhost:11434 }, platforms: { teams: { enabled: true, appId: ..., appPassword: ... } }, memory: { directory: ~/.openclaw/memory } }三个核心部分模型配置决定 OpenClaw 用哪个模型。provider指定来源model是模型名endpoint是模型服务的地址。如果是云端模型endpoint往往不需要填改填apiKey就行如果是本地模型endpoint就是 Ollama 这类服务的地址。平台配置决定你从哪个聊天软件里跟 OpenClaw 对话。这里以 Teams 为例appId和appPassword需要在 Microsoft Entra 管理中心注册一个应用后获取。这个过程不复杂但很多人会卡在“注册完应用不知道去哪找密码”实际是在“客户端凭据”这一栏里新建一个“客户端密码”复制保存即可。记忆配置决定 OpenClaw 把对话记录和知识文件存在哪。这个目录一定要提前规划好因为它会被持续写入也会影响后续备份和迁移。我建议放在一个独立且有规律的位置比如~/.openclaw/memory而不是项目代码目录里这样以后升级代码不会误删数据。3.3 启动 OpenClaw 并验证连通性配置写好后启动主程序。开发模式启动命令一般是npm run dev生产模式则是npm run build npm run start首次启动会打印日志。看到类似“OpenClaw started”或“listening”这类输出说明服务起来了。但服务起来不代表万事大吉还要做两个验证。第一验证模型服务连通。比较直接的办法是单独向本地模型服务发一个测试请求curl http://localhost:11434/api/tags如果返回模型列表说明模型服务正常。然后在 OpenClaw 的日志里看发起对话时有没有报错。如果日志里出现连接拒绝通常是模型服务地址写错或者 Ollama 没起。第二验证平台渠道连通。如果你配置了 Teams此时到 Teams 聊天窗口里给应用发一条消息。OpenClaw 应该会在几秒内回复。我实测第一轮回复往往比较慢因为程序要初始化记忆索引和工具列表属于正常现象多等几秒。4. 典型报错与排查实录4.1 无法安全验证 WSL2 环境这是 Windows 用户最容易遇到的问题报错信息类似无法安全验证 WSL2 环境。请在 PowerShell 中运行 wsl --status解决报告的问题。这个报错出现的时机是在运行初始化或启动脚本时程序先检查宿主环境发现 WSL2 状态异常就直接拒绝启动。先运行wsl --status重点看两行输出“默认版本”是否显示 2是否有“出现错误”或“需要更新”等提示如果默认版本是 1执行wsl --set-default-version 2再试。如果提示内核需要更新就执行wsl --update。还有一个高频原因是装过旧版本 WSL 而没有启用“虚拟机平台”功能需要回到第 2.1 节执行那两个 dism 命令并重启。排完这些还不行卸载 WSL 再重装也是可选方案。管理员命令是wsl --unregister Ubuntu wsl --install -d Ubuntu注意这会清空子系统中所有数据执行前确认没有重要文件在 Ubuntu 里。4.2 Node.js 版本或依赖冲突第二个常见问题是npm install时报引擎版本不兼容error openclawx.x.x: The engine node is incompatible with this module.这个报错很直白当前 Node 版本不在项目要求的范围内。用node -v确认版本如果不满足要求用 nvm 切换nvm install 22 nvm alias default 22切完版本之后记得删掉旧的node_modules重新安装rm -rf node_modules npm install如果不删旧依赖有时候即便 Node 版本正确了残留的编译产物依然会让程序崩溃而且报错信息千奇百怪排查起来很费时间。4.3 模型接入后对话无响应这个问题有两种常见表现。一是 OpenClaw 启动正常但发消息后一直不回复日志停在“Sending to model”再没下文二是直接报 404 或 500。先检查模型服务curl http://localhost:11434/api/tags如果连接失败说明 Ollama 没起或者地址不对。如果返回正常但 OpenClaw 仍然报错很可能是配置里的model名称跟 Ollama 里实际拉取的模型名称不一致。用ollama list看一下确切名称比如是qwen2.5:3b还是qwen2.5:3b-instruct填错一个字都会失败。另外提醒一点本地模型服务默认只监听本机地址。如果 OpenClaw 跑在同一台机器上没问题但如果你是 OpenClaw 在服务器、模型服务在另一台机器需要在启动 Ollama 时加上OLLAMA_HOST0.0.0.0环境变量并确认防火墙放行了对应端口。4.4 平台渠道收不到消息的排查以 Teams 为例配置好后在聊天窗口给应用发消息结果 OpenClaw 完全没反应。先不要去看代码按这个顺序排查。第一步确认 Teams 应用本身是否注册成功。到 Microsoft Entra 管理中心的“应用注册”里看应用状态确认客户端 ID 和客户端密码都没过期。密码默认有效期是一年或两年过期后要重新生成并同步到 OpenClaw 配置里。第二步确认聊天入口消息能否到达。Teams 的 Bot 需要开启“消息传递”能力并且在应用清单里正确配置了消息通知的端点 URL。这个 URL 必须能被微软的服务从公网访问到。第三步打开 OpenClaw 日志发一条测试消息看日志里有没有对应的入站记录。如果日志干干净净问题基本出在前面两步如果日志有记录但没回复再回到模型配置排查。说实话平台渠道接入是最容易让人劝退的一步。如果你只为了体验 OpenClaw 的功能第一遍可以先不配置 Teams直接用它的命令行交互方式跑通模型和工具再回头折腾平台渠道。这样能把“模型问题”和“渠道问题”分开排查出错了也知道该看哪边。5. 进阶玩法Teams 接入、Obsidian 联动与服务器部署5.1 Teams 接入的完整思路接入 Microsoft Teams 是很多人部署 OpenClaw 的第一动力因为日常办公沟通都在 Teams 里能直接在聊天窗口里喊一个 AI 助手干活体验确实不一样。整体流程分四步在 Microsoft Entra 管理中心注册应用得到应用 ID为该应用创建一个客户端密码在 Teams 管理后台或应用目录中配置 Bot设置消息通知端点把应用 ID、密码回填到 OpenClaw 配置并启用 Teams 渠道。这里的核心在于消息通知端点。OpenClaw 启动后会在本机监听某个端口如果服务器在公网直接把http://服务器公网IP:端口/api/teams这类地址填到 Bot 配置里如果服务器在局域网就要借助端口转发或反向代理把公网请求转发到本机端口。对于后一种情况我建议选一个顺手的工具固定下来别每次调试都临时改配置。我个人的习惯是把 OpenClaw 部署在云服务器上然后用 systemd 把它注册成服务让它开机自启、崩溃自动拉起。具体 unit 文件大致长这样[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] Useropenclaw WorkingDirectory/opt/openclaw ExecStart/usr/bin/npm run start Restartalways RestartSec10 [Install] WantedBymulti-user.target注意ExecStart里 npm 的路径要改成你自己的实际路径可以先用which npm查一下。很多用 nvm 安装的环境路径在用户目录下直接写/usr/bin/npm会报错。5.2 与 Obsidian 联动让 AI 真正“读”你的笔记热词里有“openclaw obsidian”说明不少人想把它接到 Obsidian 上。这个需求其实很自然OpenClaw 有记忆能力而 Obsidian 里存的是你真正要长期沉淀的知识两者打通之后AI 就能从你的笔记库中检索内容回答问题了。常规做法是把 Obsidian 的 vault 目录直接配置成 OpenClaw 的访问目录然后告诉它这个目录里的 Markdown 文件是参考资料需要回答问题或者整理思路时去搜这些文件。配置本身不复杂本质就是把这个目录加入 OpenClaw 的工具可以读取的路径列表。但这里我劝大家注意一个细节不要把所有笔记一股脑扔给 OpenClaw 去索引尤其是里面如果有密码、密钥、身份证号这类敏感信息等于把钥匙交给了一个随叫随到的助手。稳妥的做法是单独建一个AI 笔记目录只把愿意让 AI 看到的内容放进去再在配置里把这个目录加为可访问路径。5.3 免费试用云服务器部署热词里有“openclaw配置阿里云服务器免费试用”这个方向我也是推荐的。跟本地部署相比云服务器至少有三个好处7x24 小时在线、不用开着电脑、方便团队一起用。云服务器部署的步骤跟本地 Ubuntu 几乎一样唯一多出来的是网络和安全组配置。以常见的 Linux 云服务器为例在服务器上安装 Node.js 20.22 及以上版本拉取 OpenClaw 源码并安装依赖配置模型服务。如果服务器有 GPU直接本机跑如果没有回连到本地或者其他机器的模型服务在云控制台的安全组里放行 OpenClaw 监听的端口。这里我特别提醒端口放行范围一定要小比如只对需要访问的 IP 开放而不是0.0.0.0/0全放。OpenClaw 对外暴露的其实是带认证的 API但对公网完全开放路子总归不安全。免费试用期的服务器一般配置不高通常也就 2 核 4G 或者 2 核 2G 的样子。这个配置跑 Qwen2.5-3B 的 CPU 推理有点吃力但够用来跑通流程、熟悉配置。如果想真正用起来我更建议先用本地电脑跑通全部功能确定自己确实需要了再买一台带 GPU 的云服务器。我个人部署 OpenClaw 这几次下来最大的体会是这类开源 AI 助手框架的价值不在于“装好一个机器人”而在于你愿意花多少时间去配置它的记忆和工具。模型能力再强如果它记不住你的上下文、碰不到你的资料、不能主动去查网页那跟一个网页聊天框没有本质区别。所以如果你现在正准备部署我的建议是先别急着接满所有平台渠道先用最简单的方式跑通“模型加命令行”这个最小闭环然后一项一项加工具、加记忆、加渠道。每加一项就验证一项这样出了问题你知道往哪里查。千万不要照着网上教程一口气把所有配置都贴上出错了只能对着满屏日志发懵。最后再分享一个小技巧OpenClaw 的日志默认输出到控制台但建议加一个文件日志输出把运行日志写到固定路径。这样即使程序崩溃事后也能翻日志定位问题。我在本地跑了整整一周之后才真正把各个渠道和工具的使用场景摸清楚——这个项目值得你慢慢折腾。