在 Windows+WSL2 上部署 OpenClaw AI员工的实践与踩坑

wAEWQ6Ib7

383人浏览 · 2026-03-30 15:10:46

wAEWQ6Ib7 · 2026-03-30 15:10:46 发布

一，核心问题是"你已经有了"。 大多数开发者家里都有一台闲置笔记本——换了新电脑后老的扔抽屉里吃灰。它的硬件成本对你来说是零，因为钱已经花过了。Mac Mini 的钱是一笔新支出，而云服务器每月 38~80 元是持续支出。功耗差距算下来每月也就几块钱电费的事。

第二，Windows中的WSL2 原生支持 Linux。 OpenClaw 的 Gateway 跑在 Node.js + systemd 上，本质上需要一个 Linux 环境。WSL2 给你的不是模拟器，是一个跑在 Hyper-V 上的真实 Linux 内核，而且你不需要学习linux，就像操作Windows上的一个命令行窗口一样简单。我实测 Ubuntu 24.04 + systemd 完全能撑住 24/7 常驻。

第三，本地数据不经过任何第三方。 云服务器的数据存在别人的机房里，你的 API Key、聊天记录、知识库全在云端。自己的笔记本上这些东西不出家门，飞书用长连接不需要公网域名，安全感完全不一样。

环境搭建：WSL2 + systemd，两个命令但有一个隐藏陷阱

wsl2-architecture

装 WSL2 本身没什么好说的

PowerShell 管理员运行：

wsl --install -d Ubuntu-24.04

重启电脑，设置 Ubuntu 用户名密码，结束。

wsl-welcome

隐藏陷阱：systemd 默认是关的

OpenClaw 的 Gateway 需要 systemd 做进程托管。但 WSL2 默认不启动 systemd——这意味着 systemctl 命令全部报错，Gateway 根本起不来。

修复只需要两步，但第二步很多人会忘：

# 在 WSL 内部
sudo bash -c 'cat > /etc/wsl.conf << EOF
[boot]
systemd=true
EOF'

然后必须回到 Windows PowerShell 执行：

wsl --shutdown

重新打开 WSL 终端，systemctl 才能用。只关终端窗口是不够的，必须 wsl --shutdown 彻底关掉虚拟机再重新进入。

防爆内存：给 WSL2 上个紧箍咒

WSL2 默认会吃掉宿主机 50%~80% 的内存。闲置笔记本跑 24/7，不限制的话迟早卡死宿主机。

在 Windows 侧创建 C:\Users\你的用户名\.wslconfig：

[wsl2]
memory=6GB
processors=6
swap=0

再 wsl --shutdown 一次生效。这个文件只需要创建一次，以后每次启动 WSL 自动读取。

安装 OpenClaw + 启动守护进程

install-flow

进入 WSL Ubuntu 终端：

sudo apt update && sudo apt upgrade -y
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw --version   # 确认版本号
openclaw doctor      # 环境体检

然后跑 Onboarding 向导：

openclaw onboard --install-daemon --no-interactive-defaults

向导里先选 DeepSeek 做默认模型，Daemon 选启用 systemd 服务。通道先随便选一个，后面单独配。

systemctl --user enable --now openclaw-gateway.service
openclaw status --deep   # 这条命令后面会救你的命

写到这可能有人想问，为什么我用 DeepSeek？其实单纯是因为我 DeepSeek API Key 早都充过值了，想利用一下。如果你本身有其他更好的多模态大模型 API 可选（比如支持视觉的），完全可以用别的。

踩坑实录：4 个让人想砸键盘的致命问题

这才是这篇文章的核心价值。网上那些 Mac Mini 教程之所以"看起来简单"，是因为 macOS 环境天然规避了这些坑。在 WSL 上你躲不掉，但我已经替你趟过了。

每个坑我都给出原始报错 → 根因分析 → 解法，直接抄就行。

坑 1：环境变量死锁 —— CLI 被自己的配置文件锁死

按文档在 openclaw.json 里写了模板变量：

"botToken": "${TELEGRAM_BOT_TOKEN}"

然后所有 openclaw 命令都废了：

MissingEnvVarError: Missing env var "TELEGRAM_BOT_TOKEN"
  referenced at config path: channels.telegram.accounts.default.botToken

这个报错看起来像是"你还没填 Token"，但真正的问题比这狠得多：OpenClaw CLI 在执行任何命令之前——包括 openclaw doctor、openclaw config set——都会全量解析 openclaw.json。环境变量不存在？CLI 直接拒绝启动。你想用 CLI 设置环境变量？CLI 都启动不了。

经典的死锁。

解法：别跟 CLI 较劲，直接手动编辑 ~/.openclaw/openclaw.json，把所有 ${...} 替换成空字符串或者直接填上真实值。等 CLI 复活后再用命令行注入：

openclaw config set env.DEEPSEEK_API_KEY "sk-你的key"

坑 2：升级后"幽灵进程" —— 前台新版本，后台旧版本

执行了 npm i -g openclaw@latest --force，openclaw --version 确认 2026.3.1。配置了 DeepSeek，信心满满发条消息，Telegram 秒回：

Agent failed before reply: Unknown model: deepseek/deepseek-chat

我在这个报错上卡了将近两个小时。模型名对了，Provider 也注册了，openclaw doctor 也没报错。

最后是 openclaw status --deep 救了我。这条命令的输出暴露了致命矛盾：

CLI 版本：2026.3.1
Gateway 版本：2026.2.26

前台升级了，后台 systemd 服务还指着旧版本的路径。旧版物理源码里根本没有 DeepSeek 的驱动——当然报 Unknown model。

解法——"换芯手术"：

# 1. 停掉旧进程
systemctl --user stop openclaw-gateway.service
pkill -9 node

# 2. 找到新版本的真实路径
which openclaw
# 假设返回 /home/hdev/.npm-global/bin/openclaw
REAL_INDEX="/home/hdev/.npm-global/lib/node_modules/openclaw/dist/index.js"

# 3. 把 systemd 服务指向新版本
sed -i "s|ExecStart=.*|ExecStart=/usr/bin/node $REAL_INDEX gateway --port 18789|" \
  ~/.config/systemd/user/openclaw-gateway.service

# 4. 重载并启动
systemctl --user daemon-reload
systemctl --user start openclaw-gateway.service

做完再跑一次 openclaw status --deep，确认两边版本一致。

坑 3：模型注册表的"名分"问题

我还试过一个骚操作：把 model ID 写成 openai/gpt-4o，但 baseUrl 指向 DeepSeek——想"借壳上市"。

不行。2026.3.1 会原封不动地向远端发送 {"model": "gpt-4o"}，DeepSeek 收到一个不属于自己的模型名，直接拒绝。

新版 OpenClaw 必须在 JSON 顶层显式建立 providers 注册表，给每个模型上正式"户口"：

"models": {
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com/v1",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "api": "openai-completions",
      "models": [
        { "id": "deepseek-chat", "name": "DeepSeek V3" },
        { "id": "deepseek-reasoner", "name": "DeepSeek R1" }
      ]
    }
  }
}

这里有两个细节卡了我很久：

baseUrl 必须带 /v1，写成 https://api.deepseek.com 直接 404
api 字段必须写 openai-completions，不能只写 openai——少写半截就是另一个协议

坑 4：WSL 里的 OAuth 回调黑洞

这个坑只有 WSL 环境才会遇到。Google Gemini 的 OAuth 登录需要浏览器回调到 127.0.0.1。但 WSL 里没有浏览器，Windows 侧浏览器的回调又穿不透 WSL 的网络隔离——登录流程无限挂起，没有任何报错，就是卡住不动。

解法——暴力克隆凭证：

如果你之前在 WSL 里用 gemini 命令登录过 Google 账号（即 @google/gemini-cli），那 OAuth Token 已经存在本地了，直接提取给 OpenClaw 用：

第一步，从 ~/.gemini/oauth_creds.json 提取 refresh_token。

第二步，写入 OpenClaw 能读懂的格式。创建 ~/.openclaw/credentials/auth-profiles.json：

{
  "version": 1,
  "profiles": {
    "google-gemini-cli:your@gmail.com": {
      "provider": "google-gemini-cli",
      "type": "oauth",
      "email": "your@gmail.com",
      "tokens": {
        "access_token": "...",
        "refresh_token": "1//0gtqXi...",
        "token_type": "Bearer"
      }
    }
  },
  "order": {
    "google-gemini-cli": ["google-gemini-cli:your@gmail.com"],
    "google": ["google-gemini-cli:your@gmail.com"]
  }
}

第三步，也是最容易漏的：order 映射表。没有它，系统依然报 No API key found。这个字段的作用是把 google 这个别名强制解析到你刚定义的 profile 上。

补充：三大 Agent CLI，接入难度差距很大

agent-cli-compare

说完四个坑，顺便对比一下 OpenClaw 支持的三大 Agent CLI（Codex、Gemini CLI、Claude Code）各自的接入体感。

Codex：耗不费力，也没什么顾虑。ChatGPT 用户直接通过 openclaw onboard --auth-choice openai-codex 走官方 OAuth，一步到位，认证自动写入 auth-profiles.json，主脑切换即可用。

Gemini CLI：OpenClaw 2026.3.1 已内置插件式接入，加上坑 4 里的凭证克隆方案，总体也算顺滑。最大阻力就是 WSL 无头环境那个 OAuth 黑洞，但克隆 Token 完全解决了。

Claude Code：要谨慎。它的认证深度绑定 Anthropic 生态，与 OpenClaw ACP 协议的整合目前还不够完整，贸然接入容易出现权限混用或 Token 冲突。除非你明确知道自己在做什么，否则建议等官方支持成熟后再动。

接通飞书 + Telegram 双通道

dual-channel

OpenClaw 支持多种 IM 通道同时接入。我的配置是飞书为主、Telegram 为辅。

飞书：国内首选，权限配置是重点

飞书是我推荐的首选通道。原因很实际：国内网络直连、注册零门槛、长连接模式不需要公网域名，而且飞书在国内职场的普及率摆在那里。

在飞书开放平台创建企业自建应用后，权限配置必须到位，这里很多人会踩坑——权限少勾一个，消息就收不到或发不出去，但不会有明确报错。

必须开启的 3 个权限（缺一个都不能正常收发消息）：

权限标识	干什么用的
`im:message:send_as_bot`	让机器人能发消息——没有这个，你的 AI 同事是个哑巴
`im:message.p2p_msg:readonly`	读私聊消息——没有这个，私聊给机器人它收不到
`im:message.group_at_msg:readonly`	读群里 @ 机器人的消息——没有这个，群里 @ 它没反应

建议加上的 2 个权限（不加也能跑，但加了更稳）：

权限标识	干什么用的
`im:chat.members:bot_access`	读群成员和会话信息，很多 bot 场景会用到
`im:resource`	发图片、文件、富媒体时需要，不发可以先不加

事件回调选"长连接"模式——这是关键选择。长连接不需要公网域名和 HTTPS 证书，WSL 内网环境完美适配。如果你选了"HTTP 推送"模式，那就得自己搞定公网回调地址，纯属给自己找麻烦。

添加事件 im.message.receive_v1，创建版本，提审，发布。然后回到 WSL 配置 OpenClaw：

openclaw channels add feishu
# 输入 App ID 和 App Secret

openclaw gateway restart
openclaw logs --follow   # 看到 feishu connected 就成功了

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

Java Web 信息化在线教学平台系统源码-SpringBoot2+Vue3+MyBatis-Plus+MySQL8.0【含文档】

AtomGit开源社区

前后端分离汽车票网上预订系统系统｜SpringBoot+Vue+MyBatis+MySQL完整源码+部署教程

AtomGit开源社区

企业级信息化在线教学平台管理系统源码｜SpringBoot+Vue+MyBatis架构+MySQL数据库【完整版】

AtomGit开源社区

所有评论(0)

查看更多评论

wAEWQ6Ib7

@wAEWQ6Ib7

已为社区贡献9条内容