夜雨聆风
一、前期准备（核心必做）
1. 硬件与系统要求
2. 核心依赖安装
OpenClaw 基于 Node.js 开发，必须先安装 Node.js 18.0 及以上版本（低于 18 会报错）。
我们以windows安装为例：
（1）Windows安装 Node.js打开 Node.js 官方下载页：https://nodejs.org/选择 LTS 长期支持版（推荐 20.x 或 22.x），下载对应系统安装包运行安装包，全程点击「下一步」，勾选 Add to PATH（自动配置环境变量）
一键点Next无脑安装。
（2）windows安装git打开git官方下载页面：https://git-scm.com/install/windows
现在完后也是一键到底无脑安装。 
（3）飞书账号准备
登录飞书开放平台：https://open.feishu.cn/用手机号注册，下载飞书客户端。
二、OpenClaw 安装（全平台通用）
OpenClaw 提供npm
全局安装（推荐）、源码安装（进阶）两种方式，新手优先选 npm 安装。
npm 全局安装（新手首选，5 分钟完成）
打开命令行工具：
Windows：按 Win+R 输入 cmd，打开命令提示符
执行全局安装命令（无需管理员权限，除非报错）：
npm install -g openclawopenclaw --version # 输出 openclaw/x.x.x 即成功# 或查看帮助，确认指令可用openclaw --help
安装成功。
三、飞书开放平台配置（关键步骤）
1. 创建飞书企业自建应用
登录飞书开放平台（https://open.feishu.cn/），进入「开发者后台」 左侧菜单栏点击「创建应用」，选择「企业自建应用」 填写应用基本信息： 应用名称：自定义（如「OpenClaw 智能助手」） 应用描述：简单说明（如「对接 OpenClaw 的飞书机器人」） 应用图标：可选上传图片 点击「创建」，完成应用创建，自动进入应用详情页。
2. 获取应用核心凭证
进入应用详情页的「凭证与基础信息」标签 找到以下两个关键信息，复制保存（后续配置必填）： - App ID
：格式为 cli_xxxxxx（以 cli_ 开头） - App Secret
：点击「显示」后获取，一串随机字符（妥善保管，勿泄露）
3. 启用机器人能力
左侧菜单栏进入「应用功能」→「机器人」 点击「启用机器人」，补充机器人信息： 机器人名称：与应用名称一致即可 机器人头像：可选上传 保存设置，机器人能力即启用。
4. 配置应用权限（批量导入，避免漏配）
OpenClaw 需调用飞书消息、事件等接口，必须配置对应权限，推荐批量导入（手动添加易出错）。
左侧菜单栏进入「权限管理」→「批量导入」 粘贴以下权限 JSON 代码，点击「确定」：
{"apis": ["im:message", // 发送消息权限"im:message.group_at_msg", // 群聊@回复权限"im:message.send", // 主动发送消息权限"im:resource", // 接收/上传文件/图片权限"contact:user.id:readonly" // 获取用户ID只读权限],"events": ["im.message.receive_v1" // 接收消息事件权限]}
权限导入后，点击「提交申请」，等待管理员审批（企业内部应用通常 1 分钟内通过）。
5. 配置事件订阅（WebSocket 长连接）
核心步骤：OpenClaw 无需公网 IP，通过 WebSocket 长连接与飞书服务器通信，必须选择长连接方式。
左侧菜单栏进入「事件订阅」 订阅方式选择：使用长连接接收事件（WebSocket）（默认是 Webhook，需切换） 点击「添加事件」，搜索并选择 im.message.receive_v1（接收消息事件）勾选事件后，点击「保存」，事件订阅配置完成（暂不发布应用）。
6. 发布应用（必须！否则无法配对）
左侧菜单栏进入「版本管理与发布」→「创建版本」 填写版本信息（如「V1.0 初始版本」），点击「保存」 点击「提交审核」，企业内部应用由飞书企业管理员审批（通常秒通过） 审核通过后，点击「发布」，应用正式生效（未发布无法对接机器人）
四、OpenClaw 对接飞书通道（核心配置）
1. 安装飞书官方插件
OpenClaw 需安装飞书专属插件，才能支持飞书消息收发、事件响应。
打开命令行 / 终端，执行安装命令：
openclaw plugins install @openclaw/feishuopenclaw plugins list# 输出中包含 @openclaw/feishu 即安装成功
2. 添加飞书通道（两种方式：交互配置 / 命令行配置）
方式 1：交互配置（新手友好，无需记参数）
执行添加通道命令：
openclaw channels add按终端提示逐步输入（全程回车默认即可）：
请选择渠道类型：输入 feishu（或直接回车，按列表选择）
请输入渠道名称（自定义）：输入 feishu_default（或其他名称）
请输入 App ID：粘贴第一步复制的 cli_xxxx
请输入 App Secret：粘贴第一步复制的 Secret 字符串
请输入机器人名称：输入飞书机器人名称（如「OpenClaw 智能助手」）
请选择私聊回复策略：输入 pairing（配对模式，更安全）
请选择群聊回复策略：输入 open（仅 @机器人回复）
提示「Channel added successfully」即配置完成。
五、启动 OpenClaw 并完成配对验证
1. 启动 OpenClaw 网关
OpenClaw 网关是与飞书通信的核心，必须启动才能建立连接。
前台启动（调试用，可看日志）
openclaw gateway启动成功后，终端会输出日志，最后显示 Gateway started successfully。
后台启动（正式部署，不占终端）
# 启动网关openclaw gateway start# 查看网关状态openclaw gateway status# 停止网关openclaw gateway stop
2. 飞书端配对机器人
打开飞书客户端，搜索应用名称（如「OpenClaw 智能助手」） 找到对应的机器人，点击「添加」，将其添加到我的应用 私聊发送配对指令： /pair（必须加斜杠）飞书会回复一串配对码（如 123456），复制该码
3. OpenClaw 端完成配对
回到 OpenClaw 终端（前台启动的终端，后台启动可重新执行 openclaw gateway进入交互）终端提示「请输入配对码」，粘贴飞书回复的配对码，回车 提示「Pairing successful!」即配对成功，连接建立。
4. 最终测试验证
飞书私聊发送消息： 你好若 OpenClaw 正常回复，说明私聊通道打通 飞书群聊中 @机器人（如 @OpenClaw 智能助手 测试一下）若机器人正常回复，说明群聊通道打通 发送图片 / 文件：测试机器人是否能接收并回复（需确认已配置 im:resource权限）
六、常见问题与解决方案（避坑手册）
1. 配对失败：「App ID/Secret 错误」
检查：重新核对飞书开放平台的 App ID 和 Secret，确保没有复制错误（区分大小写） 解决：删除错误通道，重新执行 openclaw channels add配置
2. 配对失败：「应用未发布 / 未审核通过」
原因：飞书应用必须发布并审核通过后才能配对 解决：回到飞书开放平台「版本管理与发布」，确认应用已发布，状态为「已上线」
3. 机器人无响应：「权限未申请 / 未通过」
原因：未配置 im:message等核心权限，或权限未审批解决：重新批量导入权限 JSON，等待审批通过后，重启 OpenClaw 网关
4. 群聊 @机器人无响应
原因：群聊回复策略未配置为 open，或未添加im:message.group_at_msg权限解决： 重新配置通道，将 groupPolicy设为open确认飞书权限中已添加 im:message.group_at_msg并通过审批
5. OpenClaw 启动失败：「端口被占用」
原因：网关默认端口 8000 被其他程序占用 解决：修改端口，执行命令（以 8080 为例）：
openclaw gateway start --port 8080七、进阶配置（可选）
- 国际版飞书（Lark）对接
：修改配置文件中 domain为lark，其余步骤不变 - 多飞书应用接入
：重复添加通道步骤，给每个应用配置不同 account名称 - 日志查看：
openclaw gateway logs # 查看实时日志openclaw gateway logs --tail 100 # 查看最后100行日志
卸载 / 更新 OpenClaw：
# 卸载npm uninstall -g openclaw# 更新npm update -g openclaw
至此，OpenClaw 安装与飞书接入全流程完成！你可以基于 OpenClaw 扩展更多能力，如接入大语言模型、对接飞书文档 / 多维表格等。如果需要进一步优化配置，可参考 OpenClaw 官方文档：https://openclaw.dev/。
感谢观看，关注我后续继续更新。
