跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客我的书AI学习GitHub 精选镜像AI 生图工具UI配色美学关于
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
JavaScriptNode.jsAI

OpenClaw 安装与飞书机器人配置全流程指南

OpenClaw 是一款开源 AI Agent 框架，支持接入飞书等聊天平台。详细记录了在 Linux 环境下安装 OpenClaw 的步骤，包括环境准备、节点版本检查、一键安装及初始配置。重点阐述了飞书机器人的创建流程，涵盖应用创建、权限开通、事件订阅配置及长连接模式选择。文中还总结了常见故障排查方法，如网关未运行导致的事件保存失败、权限不足导致的消息发送问题以及配对码获取异常等解决方案，帮助用户快速完成 AI 助手部署并实现群聊私聊交互。

JavaCoder发布于 2026/3/22更新于 2026/9/1275 浏览

OpenClaw 安装与飞书机器人配置全流程指南

一、OpenClaw 是什么？

OpenClaw 是一个开源的 AI Agent 框架，简单理解就是：它让你拥有一个私人 AI 助手，可以接入飞书、Telegram、WhatsApp、Discord 等各种聊天平台。

它的核心架构很简单：

你的消息 → 飞书/Telegram/... → OpenClaw Gateway → AI 模型 → 回复

为什么选 OpenClaw？

  • 数据自托管，隐私可控
  • 支持多种聊天平台（飞书、Telegram、WhatsApp、Discord……）
  • 支持多种 AI 模型（Claude、GPT、Gemini……）
  • 可扩展的 Skill 系统，像安装 App 一样给 AI 加技能
  • 完全开源免费

二、环境准备

2.1 系统要求
项目要求
操作系统Linux / macOS / Windows (WSL2)
Node.jsv22 或更高
网络能访问飞书开放平台 + AI API
2.2 安装 Node.js（如果还没装）
# 检查是否已安装
node --version
# 如果没有或版本太低，用 nvm 安装
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

提示：输入 node --version 后如果显示 v22.x.x，说明安装成功。

三、安装 OpenClaw

3.1 一键安装

macOS / Linux：

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

Windows (PowerShell)：

iwr -useb https://openclaw.ai/install.ps1 | iex

安装完成后验证：

openclaw --version

看到版本号（如 2026.3.2）就说明安装成功了。

3.2 手动安装（备选）

如果一键脚本有问题，也可以用 npm 安装：

npm install -g openclaw

注意：如果遇到 EACCES: permission denied 错误，不要用 sudo npm install -g！正确做法是调整 npm 目录权限。

四、初始配置（onboard 向导）

安装完后，运行引导向导：

openclaw onboard --install-daemon

向导会引导你配置：

  1. AI 模型密钥 — 输入你的 Anthropic / OpenAI / Google API Key
  2. Gateway 设置 — 默认端口 18789，一般不用改
  3. 聊天渠道 — 这里先跳过，我们后面单独配飞书

提示：--install-daemon 参数会把 Gateway 安装为系统服务，开机自动启动。

配置完后检查 Gateway 状态：

openclaw gateway status

如果显示 running，基础安装就完成了。

此时你已经可以通过 Web UI 聊天了：

openclaw dashboard

浏览器会自动打开 http://127.0.0.1:18789，这就是 OpenClaw 的控制面板。

五、飞书机器人配置全流程

这是本文的重头戏。飞书机器人配置分 三大步：飞书侧建应用 → OpenClaw 侧配置 → 联调测试。

5.1 安装飞书插件

OpenClaw 的飞书支持是通过插件提供的，先安装：

openclaw plugins install @openclaw/feishu

安装完后重启 Gateway：

openclaw gateway restart
5.2 飞书开放平台：创建应用
Step 1：登录飞书开放平台

打开 https://open.feishu.cn/app，用你的飞书账号登录。

注意：如果你用的是 Lark（国际版），地址是 https://open.larksuite.com/app。

Step 2：创建企业自建应用
  1. 点击 「创建企业自建应用」
  2. 填写应用名称（比如 '我的 AI 助手'）
  3. 填写应用描述
  4. 选一个图标
Step 3：获取凭证（重要！）

进入应用后，在 「凭证与基础信息」 页面，复制两个东西：

  • App ID（格式：cli_xxxxxxxxx）
  • App Secret

安全提示：App Secret 务必妥善保管，不要泄露给任何人，不要提交到 Git。

Step 4：配置权限

进入 「权限管理」，点击 「批量开通」，粘贴以下 JSON：

{"scopes":{"tenant":["im:message","im:message.group_at_msg:readonly","im:message.p2p_msg:readonly","im:message:readonly","im:message:send_as_bot","im:resource","im:chat.access_event.bot_p2p_chat:read","im:chat.members:bot_access","contact:user.employee_id:readonly"],"user":["im:chat.access_event.bot_p2p_chat:read"]}}

说明：上面是最基本的权限集。如果后续需要操作飞书文档、多维表格等，可以追加更多权限（如 docx:document、bitable:app 等）。

Step 5：开启机器人能力

进入 「应用能力」→「机器人」：

  1. 开启机器人能力
  2. 设置机器人名称
Step 6：配置事件订阅（⚠️ 这步容易翻车！）

进入 「事件与回调」：

  1. 选择「使用长连接接收事件」（WebSocket 方式）
  2. 添加事件：搜索并勾选 im.message.receive_v1（接收消息 v1）

警告：一定要选「长连接」而不是「Webhook」！长连接不需要公网 IP，不需要域名，不需要配置 HTTPS，对个人开发者友好得多。配置事件订阅之前，OpenClaw Gateway 必须在运行！ 否则飞书检测不到长连接端，可能导致保存失败。先跑 openclaw gateway status 确认 Gateway 在线，再来配这一步。

Step 7：发布应用
  1. 进入 「版本管理与发布」
  2. 创建一个版本
  3. 提交审核并发布
  4. 等待管理员审批（企业自建应用一般秒批）

注意：不发布 = 不生效！很多人配完权限和机器人就以为搞定了，结果发消息没反应——因为应用还没发布。

5.3 OpenClaw 侧配置
方式一：交互式向导（推荐）
openclaw channels add

选择 Feishu，然后按提示输入 App ID 和 App Secret。

方式二：手动编辑配置文件

编辑 ~/.openclaw/openclaw.json，添加飞书配置：

{"channels":{"feishu":{"enabled":true,"dmPolicy":"pairing","accounts":{"main":{"appId":"cli_xxxxxxxxx","appSecret":"你的 AppSecret"}}}}}

配置完后重启 Gateway：

openclaw gateway restart
5.4 首次联调
  1. 在飞书里找到你的机器人，发一条消息（比如 '你好'）
  2. 机器人会回复一个 配对码（Pairing Code）
  3. 在终端执行配对确认：
openclaw pairing approve feishu <配对码>
  1. 配对成功后，再次发消息，AI 就会正常回复了。

六、踩坑实录 & 避坑指南

以下是我们实际配置过程中踩过的坑，排列按「痛苦指数」从高到低。

🕳️ 坑 1：事件订阅保存失败

现象：在飞书开放平台配置长连接事件订阅时，点保存没反应或报错。

原因：OpenClaw Gateway 没有在运行，飞书检测不到 WebSocket 连接。

解决：

# 先确保 Gateway 在跑
openclaw gateway start
openclaw gateway status # 确认是 running
# 然后再去飞书平台配置事件订阅
🕳️ 坑 2：机器人不回复消息

现象：飞书里发消息，机器人完全没反应。

排查清单（按顺序检查）：

  1. ✅ 应用有没有 发布？（最常见原因！）
  2. ✅ 事件订阅里有没有添加 im.message.receive_v1？
  3. ✅ 是否选择了 「长连接」 方式？
  4. ✅ 权限是否已经全部开通？
  5. ✅ Gateway 是否在运行？
# 实时查看日志，发消息后观察输出
openclaw logs --follow
🕳️ 坑 3：群聊里机器人不回复

现象：私聊正常，群聊里 @机器人 没反应。

原因：默认配置下，群聊需要 @mention 机器人才会响应。而且机器人必须被 添加到群里。

解决：

  1. 确认机器人已加入群聊
  2. 发消息时 @机器人
  3. 如果想不 @也能回复，修改配置：
{"channels":{"feishu":{"groups":{"oc_你的群 ID":{"requireMention":false}}}}}

提示：群 ID 怎么获取？启动 Gateway 后在群里 @机器人，然后 openclaw logs --follow 里找 chat_id。

🕳️ 坑 4：权限不足导致各种奇怪问题

现象：消息发送失败、无法读取文件、操作飞书文档报错。

原因：飞书权限是细粒度的，缺什么权限就报什么错。

解决：回到飞书开放平台 → 权限管理，按需补充权限。常用的：

场景需要的权限
收发消息im:message, im:message:send_as_bot
读取群消息im:message.group_at_msg:readonly
操作文档docx:document, docx:document:readonly
操作多维表格bitable:app
云盘操作drive:drive, drive:file

注意：添加新权限后，需要 重新发布应用版本 才能生效！

🕳️ 坑 5：配对码（Pairing）一直等不到

现象：发消息后机器人没有回复配对码。

原因：Gateway 没有成功连接飞书 WebSocket。

解决：

# 查看详细日志
openclaw logs --follow
# 看看有没有 feishu 连接成功的日志
# 如果有 error，根据错误信息排查（通常是 App ID/Secret 填错了）
🕳️ 坑 6：Node.js 版本太低

现象：安装 OpenClaw 报错，或启动后各种奇怪问题。

原因：OpenClaw 要求 Node.js 22+，很多系统默认装的是 18 或 20。

解决：

node --version # 检查版本
nvm install 22 # 升级到 22
nvm use 22
openclaw gateway restart # 重启

七、验证一切正常

跑完整个流程后，用这个清单逐项确认：

# 1. OpenClaw 安装正常
openclaw --version
# 2. Gateway 在运行
openclaw gateway status
# 3. 飞书插件已安装
openclaw plugins list # 应该能看到 @openclaw/feishu
# 4. 飞书连接正常
openclaw status # 应该显示 feishu: connected
# 5. 在飞书里发一条消息测试
# → 收到 AI 回复 = 全部搞定

八、进阶：常用命令速查

命令用途
openclaw gateway status查看 Gateway 状态
openclaw gateway restart重启 Gateway
openclaw logs --follow实时查看日志
openclaw channels add添加聊天渠道
openclaw pairing list feishu查看飞书配对请求
openclaw pairing approve feishu <CODE>确认配对
openclaw dashboard打开 Web 控制面板
openclaw skills list查看已安装技能
openclaw doctor健康检查 + 快速修复
在飞书里可以发的命令
命令用途
/status查看机器人状态
/reset重置对话
/model查看/切换 AI 模型

本文基于 OpenClaw 2026.3.2 版本，飞书开放平台截至 2026 年 3 月。如有版本差异请以官方文档为准：https://docs.openclaw.ai

目录

  1. OpenClaw 安装与飞书机器人配置全流程指南
  2. 一、OpenClaw 是什么？
  3. 二、环境准备
  4. 2.1 系统要求
  5. 2.2 安装 Node.js（如果还没装）
  6. 检查是否已安装
  7. 如果没有或版本太低，用 nvm 安装
  8. 三、安装 OpenClaw
  9. 3.1 一键安装
  10. 3.2 手动安装（备选）
  11. 四、初始配置（onboard 向导）
  12. 五、飞书机器人配置全流程
  13. 5.1 安装飞书插件
  14. 5.2 飞书开放平台：创建应用
  15. Step 1：登录飞书开放平台
  16. Step 2：创建企业自建应用
  17. Step 3：获取凭证（重要！）
  18. Step 4：配置权限
  19. Step 5：开启机器人能力
  20. Step 6：配置事件订阅（⚠️ 这步容易翻车！）
  21. Step 7：发布应用
  22. 5.3 OpenClaw 侧配置
  23. 方式一：交互式向导（推荐）
  24. 方式二：手动编辑配置文件
  25. 5.4 首次联调
  26. 六、踩坑实录 & 避坑指南
  27. 🕳️ 坑 1：事件订阅保存失败
  28. 先确保 Gateway 在跑
  29. 然后再去飞书平台配置事件订阅
  30. 🕳️ 坑 2：机器人不回复消息
  31. 实时查看日志，发消息后观察输出
  32. 🕳️ 坑 3：群聊里机器人不回复
  33. 🕳️ 坑 4：权限不足导致各种奇怪问题
  34. 🕳️ 坑 5：配对码（Pairing）一直等不到
  35. 查看详细日志
  36. 看看有没有 feishu 连接成功的日志
  37. 如果有 error，根据错误信息排查（通常是 App ID/Secret 填错了）
  38. 🕳️ 坑 6：Node.js 版本太低
  39. 七、验证一切正常
  40. 1. OpenClaw 安装正常
  41. 2. Gateway 在运行
  42. 3. 飞书插件已安装
  43. 4. 飞书连接正常
  44. 5. 在飞书里发一条消息测试
  45. → 收到 AI 回复 = 全部搞定
  46. 八、进阶：常用命令速查
  47. 在飞书里可以发的命令

更多推荐文章

查看全部
  • 前端国际化实现方案：React 与 i18next 最佳实践
  • Web-Check 部署与远程访问指南
  • AirSim 无人机仿真入门：实现起飞与降落
  • 从 0 到 1 打造 RISC-V 智能家居中控：硬件 + 固件 + 通信全链路实战
  • AI Coding 核心概念、工作流与工程化实践指南
  • 大模型 RAG 技术深度解析：低成本实现 AI 升级
  • VS Code 官方 Copilot 不支持自定义模型 API：替代方案与搜索用法
  • 数据结构实战：快速排序分区逻辑与冒泡排序性能评测
  • Flutter 三方库 eth_sig_util 的鸿蒙适配与 Web3 签名实战
  • STL map 与 multimap 核心特性及接口详解
  • Android Studio Kotlin 开发安卓 WebView 应用及按键交互
  • Android 及 Java 核心技术面试指南：高频考点与解析
  • RabbitMQ 分布式系统实战：从安装部署到 C++ 调用
  • MySQL 与 Navicat 入门：数据库连接、建库和常用命令
  • WebGIS + 无人机 + AI：下一代智能巡检系统
  • 机器人实践开发①：Foxglove 开发环境完整搭建指南
  • Windows 环境 llama.cpp 编译与 Qwen 模型本地部署指南
  • ROS 实战：5 分钟掌握 rqt 工具箱核心插件配置与调试技巧
  • SpringAI + Deepseek 大模型应用开发实战：对话机器人、Function Calling 与 RAG
  • GPT-4 微调 API 安全漏洞分析：绕过防护与滥用风险

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Keycode 信息

    查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online

  • Escape 与 Native 编解码

    JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online

  • JavaScript / HTML 格式化

    使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online