如果你最近在部署 OpenClaw大概率会被那一串安装报错磨掉不少耐心。我是在把 OpenClaw 当作自托管个人 AI 助手网关来用的需要在 Windows 上跑 WSL2同时接 Claude、OpenAI 和本地模型还要在 Microsoft Teams、Obsidian 里跟它对话。结果光安装阶段就撞了七个让我头疼的 bugWSL2 环境无法安全验证、PowerShell 执行策略拦脚本、Node 版本不对、npm 权限和缓存混乱、模型密钥没生效、Teams 机器人 401、Obsidian 插件连不上最后还有云服务器部署时的安全组和守护进程问题。这篇东西不打算写成安装命令的复读机版本而是把我实际踩坑时的报错信息、排查路径和最终解决办法都摊开讲适合在 Windows 本地折腾、也想往云服务器上搬的朋友参考。1. 先把 OpenClaw 的安装链路看明白才知道 bug 卡在哪一环1.1 OpenClaw 是什么为什么它值得折腾OpenClaw早期叫 Clawdbot是一个开源的个人 AI 助手网关它的核心价值在于把模型接入、工具调用和消息渠道做成了统一的一层。你可以把它理解成一个自带插线板的中控台后面接 Anthropic、OpenAI 或本地模型前面接 Web、Microsoft Teams、Obsidian、Telegram 这类入口然后在任何一端发消息它都能帮你调模型、跑工具、读文档。对我来说最吸引人的一点是它可以完全自托管配置文件和密钥都握在自己手里不用把数据塞给某个第三方 SaaS。但自托管意味着你要自己处理运行环境。OpenClaw 是基于 Node.js 的在 Windows 上还需要 WSL2在 Linux 服务器上则要面对 systemd、安全组、域名这些东西。安装本身不复杂真正复杂的是这些环节彼此咬合任何一个前提没满足报错都容易让人摸不着头脑。我前后折腾了两天把官方文档和 GitHub Issues 翻了个遍才把七个最常见的安装 bug 挨个拿下。1.2 标准安装流程和七个 bug 速览我在 Windows 11 家庭版上是这样跑通的先在 WSL2 里装 Ubuntu 22.04然后在 Ubuntu 内安装 Node.js 20 LTS再用 npm 全局安装 OpenClaw。云服务器上则是 Ubuntu 22.04 裸系统流程基本一致差别只在进程守护和网络安全组。标准命令大概是下面这样sudo apt update sudo apt upgrade -y # 通过 NodeSource 安装 Node.js 20 LTS curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs node -v npm install -g openclaw openclaw --version这看起来很短但每一步都可能炸。我把这七个 bug 先列成一张表后面逐个拆序号典型现象主要根因1提示“无法安全验证 WSL2 环境请在 PowerShell 中运行 wsl --status”WSL2 未启用或默认版本不对2运行安装脚本时报“禁止运行脚本”PowerShell 执行策略限制3安装后启动直接崩溃或报语法错误Node.js 版本过低/过新4提示 EACCES 或装完后版本还是旧的npm 全局权限与 npx 缓存问题5服务能启动但无法调用模型API 密钥或模型配置没生效6Microsoft Teams 机器人接入后 401Bot 应用注册/通道配置错误7Obsidian 插件一直连不上 OpenClaw监听地址、端口或鉴权配置不一致你会发现这七个问题没有一个需要高深技巧但它们的共同特点是报错信息不会直接告诉你“该改哪个文件”而是让你自己去拼图。下面我按实际排查顺序一个坑一个坑说。2. Windows 用户第一道坎WSL2 识别失败与 PowerShell 执行策略拦路2.1 Bug 1提示“无法安全验证 WSL2 环境请在 PowerShell 中运行 wsl --status”这个报错是最容易劝退 Windows 用户的一条。它出现在 OpenClaw 检测运行环境的时候大意是OpenClaw 需要一套可信的 WSL2 环境但当前系统没法证明这套环境是完整的。第一次看到时我以为是 OpenClaw 的问题后来才发现它只是把 WSL 的状态报告原样丢给了用户。直接在 PowerShell 里运行wsl --status看输出就能定位。常见原因有三类第一Windows 功能里没开“适用于 Linux 的 Windows 子系统”或“虚拟机平台”第二WSL 内核更新包没装导致 WSL2 无法真正启动第三WSL 默认版本仍然是 1而 OpenClaw 明确要求 WSL2。因为 WSL1 和 WSL2 的内核机制完全不同OpenClaw 依赖很多 Linux 原生能力在 WSL1 里跑起来会遇到各种莫名其妙的问题。我的处理步骤是这样的先用管理员身份打开 PowerShell依次执行wsl --status wsl --version wsl --update wsl --set-default-version 2如果wsl --status显示没有启用虚拟机平台就去“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”然后重启电脑。重启后再跑wsl --status确保输出里有类似于“默认版本: 2”的字样。这里要特别提醒一句不要在 WSL 里开了一堆发行版后才想起来检查默认版本wsl --set-default-version 2只影响之后安装的发行版已安装的发行版要单独用wsl --set-version 发行版名 2转换。还有个小坑wsl --status有时候会提示“正在检查更新”或者“内核版本太旧”前者多等一会儿后者直接执行wsl --update拉取最新内核。官方文档说的“解决报告的问题”其实就是让你把wsl --status里列出来的每一项都处理干净而不是只跑一遍命令就完事。2.2 Bug 2PowerShell 执行策略把安装脚本挡在门外WSL2 搞定之后紧跟着就会出现第二个问题OpenClaw 的安装脚本或辅助脚本是.ps1文件在 PowerShell 里一跑就报“无法加载文件 ... 因为在此系统上禁止运行脚本”。这个报错的核心是 Windows PowerShell 的默认执行策略是 Restricted也就是说本机脚本一概不允许运行跟脚本本身好坏无关。最简单的解决办法是给当前用户设置成 RemoteSignedSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser为什么建议用 RemoteSigned 而不是 Unrestricted因为 RemoteSigned 的意思是本地写的脚本可以运行从互联网下载的脚本必须有可信签名。这比完全放开要安全得多。我自己在开发机上也是用的这个策略既能跑 OpenClaw又不至于让 PowerShell 变成一个随便执行脚本的环境。设置完后可以用Get-ExecutionPolicy确认当前值。如果你在一个被企业策略锁死的环境里可能Set-ExecutionPolicy本身就会报错这种情况需要联系管理员处理或者绕过安装脚本、直接在 WSL2 的 bash 里完成全部安装这也是一种非常干净的替代方案。我当时就是在 WSL2 的 Ubuntu 里绕过 PowerShell 脚本直接用 npm 装完的。3. 装到一半“假成功”Node 版本、npm 权限和 npx 缓存三个坑3.1 Bug 3Node.js 版本不对CLI 启动即崩WSL2 环境没问题后我在 Ubuntu 里安装 OpenClaw结果装完执行openclaw启动时直接报语法错误。查到最后才发现问题出在系统自带的 Node.js 版本太老。有人可能会在 Node.js 官网下载页里找“OpenClaw 安装包”这里先说清楚OpenClaw 本身是 npm 包不在 Node 官网但 Node 官网提供的 LTS 版本是它正常运行的前提。OpenClaw 对 Node.js 的版本要求并不低我的经验是至少 Node 20 LTS。如果你用 apt 直接安装很多 Ubuntu 版本默认源里的 Node 是 12 或 14跑现代 CLI 工具基本必挂。版本过低时Node 解析不了新语法会报ERR_REQUIRE_ESM或各种SyntaxError版本过新时又可能踩到依赖兼容性问题。最稳妥的方式是用 nvm 管理 Node 版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v还有一个在 WSL2 里特别容易踩的隐藏坑node -v显示出来的版本看着没问题但实际用的是 Windows 里的 Node。判断方法很简单运行which node。如果输出是/usr/bin/node或~/.nvm/versions/node/...正常如果输出带/mnt/c/路径说明你在 WSL 里调用的是 Windows 解释器。这种情况会导致很多原生依赖路径错乱OpenClaw 装完能装上跑起来却各种找不到模块。解决办法是在~/.bashrc里把 Windows 的 Node 路径从 PATH 里清掉或者干脆全部交给 nvm 管理。3.2 Bug 4npm 全局权限不足装完还是个残缺品Node 版本解决后又出现了一个很经典的 npm 全局安装错误EACCES: permission denied。这是因为系统级 Node 的全局安装目录通常放在/usr/lib/node_modules这类需要 root 权限的位置普通用户执行npm install -g openclaw自然会被拒。很多教程会直接让你sudo npm install -g openclaw我不推荐这么做因为 sudo 之后的 npm 生命周期脚本会以 root 身份运行权限过大后续维护也不方便。更好的方案是把 npm 全局目录挪到用户目录下npm config set prefix ~/.npm-global export PATH$HOME/.npm-global/bin:$PATH echo export PATH$HOME/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc npm install -g openclaw这之后openclaw命令就能直接用了。如果你用的是 nvm其实不会有这个权限问题因为 nvm 安装的 Node 全局目录就在用户目录下所以前面我坚持推荐 nvm。解决了权限紧接着是 npx 缓存问题。我身边有人习惯用npx openclawlatest来运行但升级 OpenClaw 版本后npx 还是用旧缓存导致 bug 反复出现看起来像是没修好。这不是 OpenClaw 的问题是 npx 的_npx目录缓存了老版本。在 Ubuntu 或 WSL2 里可以把这个缓存目录清理掉rm -rf ~/.npm/_npx npm cache verify如果你在 Windows 原生环境用 npm路径会略有不同但思路一致找到缓存目录清掉再重新执行 npx。这个操作我后来定期做尤其是从 beta 版切回正式版的时候几乎必用。4. 装好了却只会报错模型密钥、本地模型和启动验证4.1 Bug 5模型密钥没生效启动后一头雾水前面几个 bug 解决完OpenClaw 终于能启动了。但新的问题随之而来无论我怎么发消息它都不回或者直接提示没有可用的模型供应商。原因是模型 API 密钥没有真正生效。OpenClaw 默认会从配置目录读取环境变量通常是在~/.openclaw/下首次启动会自动生成.env和配置文件。如果你是用npx临时跑的配置也可能落在当前项目目录这个要先确认清楚。我犯过的最低级错误是在.env文件里给密钥加了双引号。很多配置解析库能容忍引号但加引号之后密钥值可能会变成sk-xxx包含多余的引号字符调用模型时直接鉴权失败。正确写法是不加任何引号也不要有多余空格mkdir -p ~/.openclaw cd ~/.openclaw echo ANTHROPIC_API_KEYsk-ant-xxxxxxx .env echo OPENAI_API_KEYsk-xxxxxxxx .env chmod 600 .env写完.env后务必重启 OpenClaw让它重新加载环境变量。再用env | grep API检查一下当前进程里到底有没有读到这些变量这是排查“明明写了却没用”的最快方法。还有一个细节如果.env文件权限是 644其他用户也能读我是直接chmod 600收紧权限毕竟里面都是密钥。如果你和我一样同时配置了多个模型供应商还要注意 OpenClaw 配置文件里默认模型的指向。密钥读到了但配置里还是指向一个你根本没填密钥的供应商同样会失败。所以不是“有密钥就行”而是“密钥、供应商、默认模型”三者要一致。4.2 低成本玩法把 Qwen2.5-3B 关联到 OpenClaw如果你不想一上来就花钱买商业 API完全可以在 OpenClaw 里接入本地模型我用的是通义千问的 Qwen2.5-3B。3B 参数量的模型好处是资源要求低普通 CPU 或小内存云服务器也能跑坏处是复杂推理能力有限但做日常问答、信息整理、工具调用的中转完全够用。这也是我建议新手先在本地模型上跑通整条链路的原因省得还没学会配置就先被 API 账单吓跑。接入方式走 Ollama 最方便。先在 Ubuntu 里安装 Ollama拉取模型并启动服务ollama pull qwen2.5:3b ollama serve然后让 OpenClaw 走 OpenAI 兼容接口指向 Ollama。OpenClaw 的模型配置里把 provider 设置成支持 OpenAI 兼容协议的类型base_url指向http://127.0.0.1:11434/v1模型名填qwen2.5:3bAPI key 可以先填一个占位字符串因为 Ollama 本地服务默认不校验 key。这里最容易踩的坑是base_url填错很多人会漏掉末尾的/v1或者把localhost写成127.0.0.1之外的其他地址。在 WSL2 里特别注意如果你把 OpenClaw 跑在 Windows 侧、Ollama 跑在 WSL 侧两者网络互通方式不一样建议把两边都放在同一个 WSL2 环境里省掉一层网络迷雾。4.3 如何确认 OpenClaw 真的“活了”配置完模型之后不要急着接 Teams 和 Obsidian先确认核心服务能正常起来。我现在的习惯是拉起来之后盯着启动日志看看到类似“listening”“ready”或者模型连接成功的字样才继续下一步。如果你连本地命令行对话都发不出去那后面接什么都白搭。一个简单的自检顺序是先确认进程在跑再确认模型供应商能连通最后确认消息入口能触达。日志就是这里最好的朋友。不要一上来就怀疑插件问题90% 的时候是服务本身没就绪。我在调 Qwen 本地模型时就是靠日志里的一行连接拒绝反推出 Ollama 服务没启动而不是去改 OpenClaw 的配置。5. 平台接入连不上Teams、Obsidian、云服务器三个场景5.1 Bug 6Microsoft Teams 机器人接入总是 401/无法对话OpenClaw 接入 Microsoft Teams需要的是一个 Microsoft Bot Framework 里的 Bot 资源而不是普通微软账号。很多人在这里卡住是因为在 Azure 里创建了 Bot 资源后没有在“Channels”里启用 Teams 通道或者把 App ID 记成了 Teams App ID。OpenClaw 侧需要配置的是 Bot 的 Microsoft App ID 和 client secret也就是通常说的 Application ID 和密码。常见报错是 401这种基本上都是 client secret 不对或者 secret 已经过期重置。另一个很隐蔽的问题是你在 Bot 资源里改了 secret但 OpenClaw 进程还持有旧的环境变量重启服务又没彻底重新加载结果还是旧的。解决办法是配置完环境变量后确认进程完全退出再启动不要用热重载。完整接入时我建议按这样的顺序先在 Azure 里建 Bot 资源拿到 App ID 和 client secret再把 Teams 通道启用然后在 OpenClaw 里写入TEAMS_APP_ID和TEAMS_APP_PASSWORD最后通过 Teams 的 App Studio 或开发者工具创建一个应用清单把 botId 填成前面那个 App ID。如果 Teams 里始终搜不到你的应用先检查清单里的 botId 是否和 Bot 资源的 App ID 一致。这个字段看起来像小事实际是最容易翻车的地方。5.2 Bug 7Obsidian 插件连不上本地 OpenClawObsidian 接入 OpenClaw 的思路和 Teams 完全不同它通常是本地插件通过 HTTP 接口去连 OpenClaw 服务。插件一直提示连不上时我见过最多的原因是监听地址和鉴权配置不一致。OpenClaw 默认可能只监听127.0.0.1插件配置里却填了localhost在部分系统上localhost会解析成 IPv6 的::1服务监听在 IPv4自然连不上。改用http://127.0.0.1:端口通常就好了。另一个因素是端口冲突。你可以在 WSL2 或 Ubuntu 里用ss -tlnp | grep 端口查看实际监听状态。如果发现端口被别的服务占了要么换端口要么把那个服务停掉。插件配置里的端口必须和 OpenClaw 实际监听的端口完全一致这里没有任何自动发现机制。如果你想让 Obsidian 插件从局域网内其他设备连接比如手机端 Obsidian 去连电脑上的 OpenClaw那就得把监听地址改成0.0.0.0同时开启鉴权 token插件里填同一个 token。但我不建议在本地开发阶段开0.0.0.0除非你很清楚局域网环境否则属于给自己找麻烦。5.3 扩展阿里云服务器部署时最容易忽略的安全组与进程守护严格来说云服务器部署不算安装 bug但我在把 OpenClaw 搬到阿里云免费试用的 ECS 上时几乎把前面所有 bug 重新踩了一遍。免费试用的实例配置一般不高装 OpenClaw 本身没问题问题往往出在“装好了但访问不到”。第一个大坑是安全组。实例的端口并不是只要在系统里放行就能公网访问阿里云控制台的安全组规则也必须放行对应端口。比如 OpenClaw 监听8080你在控制台安全组入方向要加一条允许 TCP8080的规则然后在系统里确认防火墙也放行sudo ufw allow 8080/tcp如果你发现本机curl http://127.0.0.1:8080有响应但从公网 IP 访问超时那基本可以断定是安全组或云防火墙的问题和 OpenClaw 无关。这类问题最好的排查方式就是分层确认本机通、局域网通、公网不同一层一层定位。第二个大坑是进程守护。SSH 断开后服务就没了是因为没有用 systemd 托管。我给 OpenClaw 写了一个简单的 systemd 服务文件[Unit] DescriptionOpenClaw Gateway Afternetwork.target [Service] Userubuntu WorkingDirectory/home/ubuntu/.openclaw EnvironmentFile/home/ubuntu/.openclaw/.env ExecStart/usr/bin/openclaw start Restartalways RestartSec5 [Install] WantedBymulti-user.target保存到/etc/systemd/system/openclaw.service然后执行sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclaw这样服务会自动重启日志可以用journalctl -u openclaw -f实时看。如果部署的是本地模型的方案还要注意 Ollama 也得是常驻服务朋友服务器上出现过 OpenClaw 正常、但 Ollama 没起来导致模型连接失败的情况。6. 装完之后逐项验证以及我踩坑后才明白的几件事6.1 全流程验证清单我每次在新环境部署 OpenClaw都会按下面这个清单过一遍能省下大量试错时间WSL2 环境wsl --status显示版本为 2已安装发行版正常启动。PowerShell 执行策略Get-ExecutionPolicy返回RemoteSigned。Node 版本node -v输出 20.x 及以上且在 WSL 内which node指向 Linux 路径。npm 全局目录which openclaw能正确找到命令路径。模型配置.env文件存在且权限为 600env | grep API能看到密钥。本地模型服务ollama list能看到模型curl http://127.0.0.1:11434能通。OpenClaw 进程启动日志无异常命令行能完成一次对话。平台接入Teams 机器人发送消息能收到回复Obsidian 插件状态显示已连接。云服务器部署安全组端口已放行systemd 服务处于 active 状态。这条清单覆盖了七个 bug 的全部修复点。你不需要按顺序逐条死磕但如果遇到了问题这其实就是最优排查顺序。6.2 再遇到“怪问题”优先检查这几处我最想分享的一点是不要一开始就怀疑软件有 bug。OpenClaw 作为一个开源项目确实可能有自己的问题但安装阶段的绝大多数“怪问题”都能归结到环境不一致上。比如你换个 Node 版本就好了说明是版本问题你清掉 npx 缓存就好了说明是缓存问题你把.env引号去掉就好了说明是配置格式问题。这些都是环境问题。建议把配置目录当成一个独立的东西来管理。我习惯在~/.openclaw/下维护一份openclaw.json和.env在换机器或升级版本前先备份整个目录。遇到升级后起不来直接回滚配置比现场排查快得多。另外日志级别也很关键启动时加上调试参数能输出更多上下文很多在正常日志里被吞掉的错误细节会在调试日志里现出原形。最后再分享一个小技巧不要追求最新版本。OpenClaw 本身迭代速度很快但你的环境不一定跟得上。如果正式环境已经在稳定运行就锁定一个版本号安装不要每次都用latest更不要混合使用 npx 临时版本和全局安装版本。版本混用是我后来最容易踩的坑清除缓存加固定版本基本能消灭一半的“灵异现象”。