📖 前言
最近,一款名为 OpenClaw(俗称"大龙虾")的开源 AI 智能体(Agent)在技术圈热度飙升。与传统的聊天机器人不同,OpenClaw 的核心优势在于强执行能力——它能通过自然语言指令自动拆解任务,帮你处理邮件、管理文件,甚至调用系统工具,真正实现"说的就能让它做"。
然而,官方对 Windows 原生环境的支持并不算友好,很多同学在安装 Node 依赖、权限、路径问题上频频踩坑。官方唯一推荐的 Windows 方案,就是通过 WSL2(Windows Subsystem for Linux)运行。
本文将手把手带你从零开始,在 Windows 11 上通过 WSL2 搭建 Ubuntu 环境,完整部署 OpenClaw,并将其接入国内常用的飞书。全文干货,附带所有避坑指南。
🎯 第一部分:为什么选择 WSL2 方案?
在开始操作前,我们先明确为什么要走这套流程:
- 零硬件成本:利用现有 Windows 工作站,无需额外采购 Mac mini 或高配云服务器。
- 环境隔离:WSL2 提供一个完整的 Linux 内核,避免 Node-gyp、Python 编译等依赖与 Windows 产生冲突。
- 生态兼容:既能享受 Linux 的生态,又能方便地访问 Windows 文件系统(位于
/mnt/c/)。
🖥️ 第二部分:环境准备(Win11 + WSL2)
2.1 Windows 11 前置检查
在开始之前,请确保你的系统满足以下条件:
- 系统版本:Windows 11 22H2 及以上(64位)。
- 内存:建议 8GB 以上(16GB 更佳)。
- 虚拟化:开机进入 BIOS,确保Intel VT-x 或 AMD-V 已开启。
2.2 启用 WSL 核心功能
- 按下
Win + S搜索"Windows 功能",打开 "启用或关闭 Windows 功能"。 - 勾选以下三项,点击确定后重启电脑:
- 虚拟机平台
- Windows 虚拟机监控程序平台
- 适用于 Linux 的 Windows 子系统
2.3 安装 WSL2 与 Ubuntu
重启后,右键点击开始菜单,选择 "Windows PowerShell (管理员)"。
输入以下命令,这将自动安装 WSL2 并默认搭载 Ubuntu 最新 LTS 版:
wsl --install -d Ubuntu
安装完成后,系统会自动弹出 Ubuntu 终端窗口。根据提示创建用户名和密码(例如用户名为 openclaw,不要使用中文)。
验证安装成功。在 PowerShell 中输入:
wsl -l -v
如果看到 VERSION 列为 2,说明安装成功。
2.4 更新 WSL 内核与 Ubuntu 系统
打开已安装的 Ubuntu 终端(可在开始菜单中找到),依次执行以下命令进行系统更新:
sudo apt update && sudo apt upgrade -y
🔧 第三部分:在 WSL2 中部署 OpenClaw
3.1 安装 Node.js 环境
OpenClaw 基于 Node.js,官方推荐使用 v22 LTS 版本。我们通过 nvm 来安装,以便将来切换版本。
在 Ubuntu 终端中执行:
# 安装 nvm(Node 版本管理器)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 使 nvm 立即生效
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
# 安装 Node.js 22 LTS 并设为默认
nvm install --lts
nvm alias default 'lts/*'
# 验证安装
node -v # 应显示 v22.x.x
npm -v
npm config set registry https://registry.npmmirror.com
3.2 一键安装 OpenClaw
OpenClaw 官方提供了便捷的安装脚本。继续在 Ubuntu 终端中执行:
curl -fsSL https://openclaw.ai/install.sh | bash
如果遇到权限问题,脚本会自动处理。安装完成后,脚本通常会引导你进入 onboard 初始化流程。如果未自动进入,请手动执行:
openclaw onboard
3.3 初始化配置(Onboarding)
onboard 向导会以问答形式引导你完成核心配置:
- 风险提示:你会看到
I understand this is powerful and inherently risky. Continue?- 输入
Yes并回车。
- 输入
- 选择 AI 模型提供商:
- 国内用户推荐选择
glm(智谱) 或dashscope(阿里云百炼),访问更稳定。 - 如果你有 OpenAI 或 Anthropic 的 Key,也可以按需选择。
- 国内用户推荐选择
- 输入 API Key:
- 粘贴你提前在对应平台申请好的 API Key。
- 如何获取? 以阿里云百炼为例:登录阿里云百炼控制台 → 密钥管理 → 创建 API-Key。
- 选择消息渠道:
- 这里我们先选择
Skip(跳过)。因为后续我们要专门配置飞书插件,避免现在配置出错。
- 这里我们先选择
- 配置 Skills 和 Hooks:
- Skills(技能包):新手建议选
No跳过,后续按需安装。 - Hooks(记忆功能):推荐选中
session-memory,让 AI 记住对话上下文。
- Skills(技能包):新手建议选
配置完成后,OpenClaw 会自动启动 Gateway 服务,并尝试打开浏览器进入控制台。
📊 第四部分:验证安装与常用命令
4.1 访问 Web 控制台
在 WSL 终端中,执行以下命令打开仪表盘:
openclaw dashboard
该命令会生成一个包含临时 Token 的本地链接(通常为 http://127.0.0.1:18789),浏览器会自动打开。如果未能自动打开,手动复制地址访问即可。
127.0.0.1 访问。可以使用以下方法:
在 WSL 终端 中查看 IP:
ip addr show eth0 | grep inet
记下类似 172.xx.xx.xx 的地址,在 Windows 浏览器中访问:http://<WSL的IP>:18789。
4.2 管理 OpenClaw 服务
OpenClaw 的后台服务称为 gateway,你需要习惯使用以下命令来管理它:
# 查看服务状态
openclaw status
# 启动网关(如果未运行)
openclaw gateway start
# 重启网关(修改配置后常用)
openclaw gateway restart
# 查看实时日志(排错神器)
openclaw logs follow
📱 第五部分:高级玩法——接入飞书机器人
OpenClaw 的魅力在于可以通过聊天软件交互。下面是将它接入飞书的具体步骤。
5.1 安装飞书插件
在 WSL 终端中执行:
openclaw plugins install @m1heng-clawd/feishu
等待插件安装完成。
5.2 配置飞书开放平台
创建应用:访问 飞书开放平台,点击"创建企业自建应用",取名"AI 助理"。
添加机器人能力:在应用详情页,点击"添加应用能力" → 选择"机器人"。
配置权限:进入"权限管理" → "批量导入权限"。粘贴以下 JSON 代码(核心消息权限),点击导入:
{
"scopes": {
"tenant": [
"im:message",
"im:message:send_as_bot",
"im:message.p2p_msg:readonly",
"im:message.group_at_msg:readonly"
]
}
}
订阅事件:进入"事件与回调" → 订阅方式选择 "使用长连接接收事件"(这点很重要,无需公网回调地址)→ 点击"添加事件",搜索并添加 im.message.receive_v1(接收消息事件)。
发布版本:进入"版本管理与发布",创建一个版本并发布。只有发布后配置才会生效。
5.3 连接 OpenClaw 与飞书
在 WSL 终端中,获取飞书应用的 App ID 和 App Secret(在飞书开放平台"凭证与基础信息"中查看)。
执行命令添加渠道:
openclaw channels add
按照提示粘贴 App ID 和 App Secret。
重启网关使配置生效:
openclaw gateway restart
最终测试:
- 在飞书客户端搜索你创建的应用名称,进入聊天窗口。
- 发送任意消息(如"你好")。机器人会自动回复一个配对码。
- 回到 OpenClaw Web 控制台(
http://127.0.0.1:18789),将配对码输入,即可完成绑定。
❓ 第六部分:常见问题与排错指南
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 安装卡在 node-gyp | 缺少 C++ 编译环境 | 在 WSL 中执行:sudo apt install build-essential |
| openclaw: command not found | PATH 环境未刷新 | 重启 WSL 终端,或执行 source ~/.bashrc |
| 飞书提示"未建立长连接" | 网关未运行或长连接配置未保存 | 1. 执行 openclaw gateway restart 2. 在飞书后台等待 1-2 分钟重试 |
| 飞书机器人无回复 | 未发布应用 / 未订阅消息事件 | 1. 检查是否在飞书后台"版本管理"中发布了 2. 确认订阅了 im.message.receive_v1 |
| WSL2 IP 总变化 | WSL2 默认 NAT 特性 | 使用 Windows 端口转发:netsh interface portproxy add v4tov4 listenport=18789 connectaddress=<WSL-IP> connectport=18789 |
📝 结语
通过以上步骤,你已经在 Windows 11 上成功搭建了一个本地优先、数据私密的 AI 智能体。这不仅仅是一个聊天机器人,更是你未来自动化工作流的起点。
OpenClaw 的强大在于其"技能"的可扩展性。安装成功后,你可以尝试让它在飞书里帮你总结文档、查询天气,甚至编写代码。如果在安装过程中遇到本文未覆盖的 Bug,欢迎在评论区留言交流。
HABC2515 编辑于2026/05/12
- END -