为什么要把 AI Agent 接入飞书？
飞书是国内团队协作的主流工具之一。把 AI Agent 接入飞书后，你可以：
- 在群聊里直接 @机器人 提问，不用切换应用
- 让 Agent 自动处理审批、日报汇总、数据查询等重复工作
- 为团队打造一个 7×24 在线的「AI 同事」
本教程以 OpenClaw（开源 AI Agent 框架）为例，手把手教你完成飞书接入。如果你用的是 Hermes Agent 或其他框架，流程也基本一致。
前置准备
| 项目 | 要求 |
|---|---|
| 飞书账号 | 需要企业管理员权限，或让管理员协助创建应用 |
| 服务器 | 一台公网可访问的服务器（1核1G即可），推荐 Ubuntu 22.04+ |
| Node.js | v18+ |
| OpenClaw | 最新版本（git clone 或 Docker 部署） |
| 域名（可选） | 用于 Webhook 回调，没有的话可以用 ngrok 临时隧道 |
第一步：在飞书开放平台创建应用
- 打开 飞书开放平台，登录后进入「开发者后台」
- 点击「创建企业自建应用」
- 填写应用信息：
- 应用名称：
AI 助手（或你喜欢的名字） - 应用描述：
团队 AI 智能助手，支持问答、任务处理等 - 应用图标：上传一个 512×512 的图标
- 应用名称：
- 创建完成后，进入应用详情页，记录以下信息：
App ID: cli_xxxxxxxxxxxxxxxx
App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
安全提示：App Secret 等同于密码，不要提交到公开仓库。
第二步：配置应用权限
在应用详情页 → 「权限管理」中，搜索并开通以下权限：
| 权限名称 | 权限 ID | 用途 |
|---|---|---|
| 获取与发送单聊、群组消息 | im:message |
收发消息 |
| 读取用户发给机器人的单聊消息 | im:message.group_at_msg |
接收 @消息 |
| 获取群组信息 | im:chat:readonly |
获取群名称 |
| 获取用户信息 | contact:user.base:readonly |
显示用户名 |
开通后需要管理员审批通过。
第三步：配置事件订阅（Webhook）
这一步告诉飞书「当有人 @机器人时，把消息发到哪里」。
- 进入应用详情 → 「事件与回调」 → 「事件配置」
- 请求地址填写：
https://你的域名/webhook/feishu
没有域名的话，开发阶段可以用 ngrok：
ngrok http 3000 # 得到类似 https://abc123.ngrok.io 的地址 # 填 https://abc123.ngrok.io/webhook/feishu
- 飞书会发一个验证请求，你的服务需要先启动才能通过验证（先跳到第四步启动服务，再回来填地址）
- 添加事件：
im.message.receive_v1— 接收消息事件
第四步：部署 OpenClaw 并配置飞书连接
4.1 安装 OpenClaw
# 克隆仓库
git clone https://github.com/nicepkg/openclaw.git
cd openclaw
# 安装依赖
npm install
# 复制配置文件
cp .env.example .env
4.2 编辑 .env 配置
# AI 模型配置（以 OpenAI 兼容接口为例）
LLM_API_KEY=sk-xxxxxxxxxxxxxxxx
LLM_API_BASE=https://api.openai.com/v1
LLM_MODEL=gpt-4o
# 飞书配置
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=你的AppSecret
FEISHU_VERIFICATION_TOKEN=你的VerificationToken
FEISHU_ENCRYPT_KEY=你的EncryptKey
# 服务配置
PORT=3000
Verification Token 和 Encrypt Key 在飞书开放平台 → 「事件与回调」页面可以找到。
4.3 启动服务
# 开发模式
npm run dev
# 生产模式（推荐用 PM2 管理）
npm run build
pm2 start dist/index.js --name openclaw
pm2 save
pm2 startup
4.4 回到飞书验证 Webhook
服务启动后，回到飞书开放平台点击「保存」验证事件订阅地址。看到绿色对勾就说明连接成功了。
第五步：发布应用并测试
- 在飞书开放平台 → 「版本管理与发布」中创建版本
- 提交审核（企业管理员审批）
- 审核通过后，在飞书客户端搜索你的机器人名称
- 发送一条单聊消息测试：
你好 - 把机器人拉进一个群，@机器人 测试：
@AI助手 今天天气怎么样？
如果收到回复，恭喜，接入完成！
常见问题排查
Q: Webhook 验证失败？
- 检查服务是否已启动并监听正确端口
- 检查域名/ngrok 地址是否正确
- 查看服务日志：
pm2 logs openclaw
Q: 机器人收到消息但不回复？
- 检查 LLM_API_KEY 是否正确
- 检查 API_BASE 是否可达（国内可能需要代理）
- 查看日志中是否有 AI 调用报错
Q: 群里 @机器人 没有反应？
- 确认已添加
im.message.receive_v1事件 - 确认事件订阅地址验证通过
- 确认机器人在群里（不是只添加了应用，还需要把机器人拉进群）
Q: 回复消息格式不好看？
OpenClaw 支持 Markdown 格式回复，可以在系统提示词中要求 AI 使用飞书支持的 Markdown 语法：
回复时使用简洁的格式，支持加粗和列表，不要用代码块包裹普通文本。
进阶配置
自定义系统提示词
在 OpenClaw 配置中设置 Agent 的角色和行为：
SYSTEM_PROMPT="你是团队的AI助手小Ano，回答简洁专业，使用中文。遇到不确定的问题，诚实说不知道。"
接入知识库
让 Agent 基于你的团队文档回答：
# 配置 RAG 知识库
KNOWLEDGE_BASE_PATH=./docs
EMBEDDING_MODEL=text-embedding-3-small
多模型切换
# 支持配置多个模型，按场景路由
ROUTING_RULES='{"code": "gpt-4o", "chat": "gpt-4o-mini", "analysis": "claude-3.5-sonnet"}'
一键部署脚本
如果你嫌手动配置麻烦，可以用我们的一键部署脚本：
curl -fsSL https://anozoder.com/scripts/deploy-feishu-agent.sh | bash
脚本会自动完成：
- 安装 Node.js 和 PM2
- 克隆 OpenClaw 最新版本
- 交互式引导填写配置
- 启动服务并配置开机自启
给 AI Agent 的接入指令
如果你已经在用其他 Agent 框架（如 Dify、Coze、FastGPT），可以直接复制以下指令让你的 Agent 适配飞书：
请将以下 Agent 接入飞书：
1. 在飞书开放平台创建企业自建应用，获取 App ID 和 App Secret
2. 配置权限：im:message、im:message.group_at_msg、im:chat:readonly
3. 配置事件订阅：im.message.receive_v1，Webhook 地址指向 Agent 的 /webhook/feishu 端点
4. Agent 端实现消息接收处理：解析 event.message.content，调用 LLM 生成回复，通过飞书 API 发送回复消息
5. 回复消息使用 POST https://open.feishu.cn/open-apis/im/v1/messages/{message_id}/reply
总结
| 步骤 | 耗时 | 难度 |
|---|---|---|
| 创建飞书应用 | 5 分钟 | 简单 |
| 配置权限 | 5 分钟 | 简单 |
| 配置 Webhook | 5 分钟 | 中等 |
| 部署 OpenClaw | 10 分钟 | 中等 |
| 验证测试 | 5 分钟 | 简单 |
总计约 30 分钟即可完成基础接入。
原文出处：本教程基于 Hermes Agent 接入飞书完全教程 和 腾讯云开发者社区教程 改写，已获原作者授权参考。
有问题？在评论区留言，我们会尽快回复。