OpenClaw (Clawdbot) WSL 安装 + 飞书接入完整教程

本教程整合了有道云笔记的 WSL 安装指南与 GitHub 上 m1heng/clawdbot-feishu 项目的飞书接入方法，帮助你从零开始搭建一个可以通过飞书交互的个人 AI 助手。

1. 什么是 OpenClaw

OpenClaw（曾用名 ClawdBot、MoltBot）是一个开源的个人 AI 助手平台。它部署在你自己的电脑上，让你能够完全掌控自己的数据。通过 WhatsApp、Telegram、飞书等聊天工具，你可以与它交互，让它处理邮件、管理文件、编写代码，甚至控制你的电脑。

核心特点：

本地部署，数据私有
支持多种大语言模型（Claude、GPT、Gemini 等）
支持多平台聊天渠道
可扩展的技能（Skills）系统
拥有持久记忆功能

2. 环境准备

2.1 系统要求

| 项目 | 要求 |

|------|------|

| 操作系统 | Windows 10 版本 2004+ 或 Windows 11 |

| WSL2 | Ubuntu 22.04 或 24.04（推荐） |

| Node.js | 版本 22 或更高 |

| 内存 | 建议 8GB+ |

| 飞书账户 | 企业版账户（个人账户无法创建自建应用） |

2.2 需要准备的 API Key（任选其一）

Anthropic API Key（推荐，用于 Claude 模型）
OpenAI API Key（用于 GPT 模型）
Google AI API Key（用于 Gemini 模型）

3. WSL2 安装与配置

3.1 安装 WSL2

以管理员身份打开 PowerShell，执行：

wsl --install

这将自动安装 WSL2 和 Ubuntu。安装完成后重启电脑。

3.2 初始化 Ubuntu

重启后，Ubuntu 会自动启动并要求你设置用户名和密码。

3.3 更新系统

sudo apt update && sudo apt upgrade -y

3.4 安装 Node.js 22

安装 nvm (Node Version Manager)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

重新加载配置

source ~/.bashrc

安装 Node.js 22

nvm install 22

验证安装

node --version # 应显示 v22.x.x

npm --version

3.5 配置 systemd（WSL2 后台服务必需）

编辑或创建 /etc/wsl.conf：

sudo nano /etc/wsl.conf

添加以下内容：

$boot$
systemd=true

保存后，在 PowerShell 中重启 WSL：

wsl --shutdown

wsl

4. OpenClaw 安装

4.1 一键安装（推荐）

在 WSL Ubuntu 终端中执行：

curl -fsSL https://openclaw.ai/install.sh | bash

安装脚本会自动检测系统环境并安装 OpenClaw CLI。

4.2 手动安装（如一键安装失败）

npm install -g openclaw@latest

如果遇到权限问题：

复制代码

# 配置 npm 全局目录

mkdir -p ~/.npm-global

npm config set prefix '~/.npm-global'

# 添加到 PATH

echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

source ~/.bashrc

# 重新安装

npm install -g openclaw@latest

4.3 验证安装

openclaw --version

5. OpenClaw 初始配置

5.1 运行配置向导

openclaw onboard --install-daemon

向导会引导你完成以下配置：

Gateway 模式 ：选择 Local（本地）
AI 模型认证：

选择你的模型提供商（Anthropic/OpenAI/Google）
输入对应的 API Key

通信渠道：暂时跳过（稍后配置飞书）
后台服务 ：选择 Yes 安装 systemd 服务

这里需要选择一个大模型，软件集成了Anth ropic 可以不要钱。

接下来是配置channel，也就是配置具体的应用。可以看到海外主流的通信软件

但是飞书不在这里面，点击Skip for now，跳过配置

Skills配置这里可以选No, 等安装好后，可以在后台界面去配置

后面的Hooks 也选 Skip for Now。用处不大

Hatch in TUI (recommended):意思是在终端界面运行

Open the Web UI:网页版界面

最后一个是 "以后再说"。这里选默认的就行了。

所有都配置完后，终端界面就可以进行聊天，也可以在网页中输入红框的地址进行后台配置

在后台中能看到各种各样的配置，所以前面安装的时候，其实都可以忽略。

5.2 验证配置

健康检查

openclaw health

查看状态

openclaw status

诊断问题

openclaw doctor

5.3 启动 Gateway

如果服务未自动启动：

openclaw gateway start

或手动运行（便于查看日志）：

openclaw gateway --port 18789 --verbose

访问 http://127.0.0.1:18789/ 可打开 Web 控制台。

6. 飞书开放平台应用创建

重要：飞书机器人功能需要企业版账户，个人账户无法创建自建应用。

6.1 创建自建应用

【总结】首先要在飞书管理后台建一个机器人应用

进入飞书开发者后台：

https://open.feishu.cn/app?lang=zh-CN

点击创建企业应用

应用名字是: clawbot机器人（这个名字随便起）

接下来，在应用中创建一个机器人

先点创建版本发布，这就算发布了第一版的机器人应用

访问飞书开放平台（国际版使用 Lark Open Platform）
登录企业账户
点击「创建企业自建应用」
填写应用名称和描述（如：OpenClaw AI 助手）
点击「创建」

6.2 添加机器人能力

进入应用详情页
在「添加应用能力」中选择「机器人」
点击添加

6.3 获取凭证

在「凭证与基础信息」页面记录：

App ID ：格式为 cli_xxxxxxxxx
App Secret：保密字符串

6.4 配置权限

进入「权限管理」，开启以下权限：

必需权限（6项）：

| 权限标识 | 说明 |

|----------|------|

| contact:user.base:readonly | 获取用户基本信息 |

| im:message | 发送和接收消息 |

| im:message.p2p_msg:readonly | 读取私聊消息 |

| im:message.group_at_msg:readonly | 接收群聊 @机器人消息 |

| im:message:send_as_bot | 以机器人身份发送消息 |

| im:resource | 上传和下载图片/文件 |

可选权限（完整功能）：

| 权限标识 | 说明 |

|----------|------|

| im:message.group_msg | 读取群聊所有消息（敏感） |

| im:message:readonly | 获取消息历史 |

| im:message:update | 更新/编辑已发送消息 |

| im:message:recall | 撤回已发送消息 |

6.5 配置事件订阅

进入「事件与回调」
关键步骤：选择「长连接」作为订阅方式（不要选 Webhook）
添加事件：搜索「接收消息」，启用 im.message.receive_v1

为什么选择长连接？ 长连接模式更稳定，无需暴露端口或配置 SSL 证书，适合本地部署。

6.6 发布应用

进入「版本管理与发布」
创建版本
至少发布到「测试版本」（供自己使用）或提交审核发布到正式版本

7. 安装飞书插件

7.1 安装插件

在 WSL 终端中执行：

openclaw plugins install @m1heng-clawd/feishu

如果安装失败，可手动安装：

# 下载插件包

curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz

# 从本地安装

openclaw plugins install ./feishu-0.1.3.tgz

7.2 验证安装

openclaw plugins list

应显示已安装的 feishu 插件。

8. 飞书插件配置

8.1 配置凭证

# 设置 App ID

openclaw config set channels.feishu.appId "cli_xxxxxxxxx"

# 设置 App Secret

openclaw config set channels.feishu.appSecret "your_app_secret"

# 启用飞书渠道

openclaw config set channels.feishu.enabled true

8.2 完整配置选项

编辑配置文件 ~/.openclaw/openclaw.json，找到或添加 channels.feishu 部分：

{

"channels": {

"feishu": {

"enabled": true,

"appId": "cli_xxxxxxxxx",

"appSecret": "your_app_secret",

"domain": "feishu",

"connectionMode": "websocket",

"dmPolicy": "pairing",

"groupPolicy": "allowlist",

"requireMention": true,

"mediaMaxMb": 30,

"renderMode": "auto"

}

}

}

配置项说明：

| 配置项 | 说明 | 可选值 |

|--------|------|--------|

| domain | 服务区域 | feishu（中国）/ lark（国际） |

| connectionMode | 连接模式 | websocket（推荐）/ webhook |

| dmPolicy | 私聊策略 | pairing（需配对）/ open（开放）/ allowlist（白名单） |

| groupPolicy | 群聊策略 | open / allowlist / disabled |

| requireMention | 群聊是否需要 @机器人 | true / false |

| renderMode | 回复渲染模式 | auto / raw / card |

8.3 重启 Gateway

配置完成后重启服务：

openclaw gateway restart

9. 启动与测试

9.1 检查服务状态

# 查看整体状态

openclaw status --all

# 查看渠道状态

openclaw channels status

# 查看日志

openclaw logs --follow

9.2 在飞书中测试

私聊测试：

在飞书中搜索你的机器人名称
发送消息「你好」
如果设置了 dmPolicy: "pairing"，首次会收到配对码

群聊测试：

将机器人添加到群聊
@机器人并发送消息

9.3 处理配对请求

查看待处理的配对请求

openclaw pairing list feishu

批准配对（使用返回的配对码）

openclaw pairing approve feishu <code>

10. 常见问题排查

10.1 Gateway 无法启动

检查端口占用

lsof -i :18789

查看详细错误

openclaw gateway --verbose

运行诊断

openclaw doctor --fix

10.2 飞书消息无响应

检查渠道状态

openclaw channels status --probe

查看飞书相关日志

openclaw logs --follow | grep -i feishu

检查配对状态

openclaw pairing list feishu

10.3 API Key 配置问题

重新配置模型

openclaw configure

或手动设置

openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4-0"

10.4 插件加载错误

如果升级后出现 Cannot find module 'clawdbot/plugin-sdk' 错误：

卸载旧插件

openclaw plugins uninstall feishu

重新安装最新版

openclaw plugins install @m1heng-clawd/feishu

10.5 WSL2 网络问题

如需从其他设备访问 WSL 中的服务，需要设置端口转发：

# 在 PowerShell（管理员）中运行

$WslIp = (wsl -- hostname -I).Trim().Split(" ")[0]

netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$WslIp

11. 进阶配置

11.1 飞书云文档/知识库集成

要让机器人访问飞书文档，需要额外配置：

在飞书开放平台添加权限：

wiki:wiki:readonly（读取知识库）
drive:drive:readonly（读取云文档）

重要：将机器人添加到知识库空间

仅有 API 权限不够，还需要将机器人添加到知识库空间
机器人没有自己的「我的空间」，只能访问被分享给它的文件/文件夹

11.2 @mention 转发功能

飞书插件支持 @mention 转发：

在消息中 @某人，机器人回复时会自动 @他们
私聊：@张三打个招呼 → 机器人回复 @张三你好！
群聊：@机器人 @张三打个招呼 → 机器人回复 @张三你好！

11.3 开机自启动

WSL2 配置 systemd 后，OpenClaw 服务会自动启动。确认服务状态：

systemctl --user status openclaw-gateway

11.4 日常维护命令

日常检查

openclaw status

openclaw health

查看日志

openclaw logs --follow

更新 OpenClaw

curl -fsSL https://openclaw.ai/install.sh | bash

更新插件

openclaw plugins update feishu