OpenClaw 教程封面

【保姆级教程】Windows 11 安装运行 OpenClaw:WSL2 环境部署与飞书接入全攻略

📖 前言

最近,一款名为 OpenClaw(俗称"大龙虾")的开源 AI 智能体(Agent)在技术圈热度飙升。与传统的聊天机器人不同,OpenClaw 的核心优势在于强执行能力——它能通过自然语言指令自动拆解任务,帮你处理邮件、管理文件,甚至调用系统工具,真正实现"说的就能让它做"。

然而,官方对 Windows 原生环境的支持并不算友好,很多同学在安装 Node 依赖、权限、路径问题上频频踩坑。官方唯一推荐的 Windows 方案,就是通过 WSL2(Windows Subsystem for Linux)运行。

本文将手把手带你从零开始,在 Windows 11 上通过 WSL2 搭建 Ubuntu 环境,完整部署 OpenClaw,并将其接入国内常用的飞书。全文干货,附带所有避坑指南。

🎯 第一部分:为什么选择 WSL2 方案?

在开始操作前,我们先明确为什么要走这套流程:

🖥️ 第二部分:环境准备(Win11 + WSL2)

2.1 Windows 11 前置检查

在开始之前,请确保你的系统满足以下条件:

2.2 启用 WSL 核心功能

  1. 按下 Win + S 搜索"Windows 功能",打开 "启用或关闭 Windows 功能"。
  2. 勾选以下三项,点击确定后重启电脑:
    • 虚拟机平台
    • Windows 虚拟机监控程序平台
    • 适用于 Linux 的 Windows 子系统

2.3 安装 WSL2 与 Ubuntu

重启后,右键点击开始菜单,选择 "Windows PowerShell (管理员)"。

输入以下命令,这将自动安装 WSL2 并默认搭载 Ubuntu 最新 LTS 版:

代码语言:bash
wsl --install -d Ubuntu

安装完成后,系统会自动弹出 Ubuntu 终端窗口。根据提示创建用户名和密码(例如用户名为 openclaw,不要使用中文)。

验证安装成功。在 PowerShell 中输入:

代码语言:bash
wsl -l -v

如果看到 VERSION 列为 2,说明安装成功。

2.4 更新 WSL 内核与 Ubuntu 系统

打开已安装的 Ubuntu 终端(可在开始菜单中找到),依次执行以下命令进行系统更新:

代码语言:bash
sudo apt update && sudo apt upgrade -y

🔧 第三部分:在 WSL2 中部署 OpenClaw

3.1 安装 Node.js 环境

OpenClaw 基于 Node.js,官方推荐使用 v22 LTS 版本。我们通过 nvm 来安装,以便将来切换版本。

在 Ubuntu 终端中执行:

代码语言:bash
# 安装 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 下载慢,可以配置淘宝镜像:
npm config set registry https://registry.npmmirror.com

3.2 一键安装 OpenClaw

OpenClaw 官方提供了便捷的安装脚本。继续在 Ubuntu 终端中执行:

代码语言:bash
curl -fsSL https://openclaw.ai/install.sh | bash

如果遇到权限问题,脚本会自动处理。安装完成后,脚本通常会引导你进入 onboard 初始化流程。如果未自动进入,请手动执行:

代码语言:bash
openclaw onboard

3.3 初始化配置(Onboarding)

onboard 向导会以问答形式引导你完成核心配置:

  1. 风险提示:你会看到 I understand this is powerful and inherently risky. Continue?
    • 输入 Yes 并回车。
  2. 选择 AI 模型提供商:
    • 国内用户推荐选择 glm (智谱) 或 dashscope (阿里云百炼),访问更稳定。
    • 如果你有 OpenAI 或 Anthropic 的 Key,也可以按需选择。
  3. 输入 API Key:
    • 粘贴你提前在对应平台申请好的 API Key。
    • 如何获取? 以阿里云百炼为例:登录阿里云百炼控制台 → 密钥管理 → 创建 API-Key。
  4. 选择消息渠道:
    • 这里我们先选择 Skip(跳过)。因为后续我们要专门配置飞书插件,避免现在配置出错。
  5. 配置 Skills 和 Hooks:
    • Skills(技能包):新手建议选 No 跳过,后续按需安装。
    • Hooks(记忆功能):推荐选中 session-memory,让 AI 记住对话上下文。

配置完成后,OpenClaw 会自动启动 Gateway 服务,并尝试打开浏览器进入控制台。

📊 第四部分:验证安装与常用命令

4.1 访问 Web 控制台

在 WSL 终端中,执行以下命令打开仪表盘:

代码语言:bash
openclaw dashboard

该命令会生成一个包含临时 Token 的本地链接(通常为 http://127.0.0.1:18789),浏览器会自动打开。如果未能自动打开,手动复制地址访问即可。

⚠️ 遇到访问失败? 由于 WSL2 使用虚拟网卡,有时 Windows 浏览器无法直接通过 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,你需要习惯使用以下命令来管理它:

代码语言:bash
# 查看服务状态
openclaw status

# 启动网关(如果未运行)
openclaw gateway start

# 重启网关(修改配置后常用)
openclaw gateway restart

# 查看实时日志(排错神器)
openclaw logs follow

📱 第五部分:高级玩法——接入飞书机器人

OpenClaw 的魅力在于可以通过聊天软件交互。下面是将它接入飞书的具体步骤。

5.1 安装飞书插件

在 WSL 终端中执行:

代码语言:bash
openclaw plugins install @m1heng-clawd/feishu

等待插件安装完成。

5.2 配置飞书开放平台

创建应用:访问 飞书开放平台,点击"创建企业自建应用",取名"AI 助理"。

添加机器人能力:在应用详情页,点击"添加应用能力" → 选择"机器人"。

配置权限:进入"权限管理" → "批量导入权限"。粘贴以下 JSON 代码(核心消息权限),点击导入:

代码语言: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(在飞书开放平台"凭证与基础信息"中查看)。

执行命令添加渠道:

代码语言:bash
openclaw channels add

按照提示粘贴 App ID 和 App Secret。

重启网关使配置生效:

代码语言:bash
openclaw gateway restart

最终测试:

❓ 第六部分:常见问题与排错指南

问题现象可能原因解决方案
安装卡在 node-gyp缺少 C++ 编译环境在 WSL 中执行:sudo apt install build-essential
openclaw: command not foundPATH 环境未刷新重启 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 -