最近不少做 AI Agent 的朋友都在问同一个问题:Agent 写好了,怎么让团队在飞书里直接跟它对话?把 AI Agent 接进飞书这件事,听起来像是个大工程,实际上只要理清链路、选对工具,一个下午就能跑通。这篇攻略我就围绕 cc-connect 这个连接器,把从零开始的完整配置过程、原理、坑点全部拆开讲清楚,给后面想接的人省点时间。
这个方案适合谁?如果你手上已经有一个跑得起来的 AI Agent 服务(不管是基于开源框架搭建的,还是自己写的推理接口),现在只差一个入口让飞书用户能触发它、接收它的回复,那这份攻略就是给你准备的。哪怕你从来没配过飞书开放平台,只要按步骤走,也能完成接入。
1. 项目到底在解决什么问题
1.1 为什么是飞书,为什么是 cc-connect
飞书在企业协作里的渗透率已经很高了,团队日常沟通、审批、文档、多维表格都在上面。如果一个 AI Agent 只能通过命令行或者网页访问,那它始终是个"开发者的玩具",业务同事根本用不起来。把 Agent 接进飞书,本质上是给它装了一个"企业级入口":员工在聊天窗口里 @ 机器人,就能触发 Agent 能力,结果直接以消息形式返回。
那为什么用 cc-connect 而不是自己写一套飞书 API 对接逻辑?如果你看过飞书开放平台的文档就会知道,要实现一个能收发消息的机器人,涉及应用创建、权限配置、事件订阅、加密校验、长连接维护、消息回调解析、主动发送消息的 token 刷新……这一套流程自己写下来,光踩文档坑就能花掉一周。cc-connect 这类连接器的价值就在这里:它把飞书开放平台的底层通信细节封装好了,你只需要关注"收到消息之后,叫哪个 Agent 去处理"这一件事。
1.2 整体方案的工作原理
从架构上看,整个链路并不复杂,你可以把它理解成"翻译官 + 邮差"的组合:
- 飞书侧:用户在聊天窗口给机器人发消息,飞书开放平台把这个事件推送给连接器(cc-connect)。
- 连接器侧:cc-connect 收到事件后,解析出消息内容、发送者、会话 ID,然后把这些信息转发给配置好的 AI Agent 接口。
- Agent 侧:AI Agent 处理完成后返回结果文本,cc-connect 再把结果通过飞书 API 发回到原会话。
这个链路里最关键的一点是:飞书和 AI Agent 之间不直接通信,中间靠 cc-connect 做协议转换和数据搬运。好处是,Agent 那侧不管是 HTTP 接口还是 WebSocket 服务,只要 cc-connect 能按约定调用,整体就能工作,Agent 本身不用改动太多。
记住这个整体框架,后面配置的时候你就能时刻知道自己正在做的是哪一环,不至于被一堆参数绕晕。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 动手前的环境准备与账号配置
2.1 本地环境:Node.js 和 Git 的安装检查
cc-connect 基于 Node.js 开发,所以本地必须先有 Node 运行时。建议装 LTS 版本,我实测 Node 16 以上的版本跑起来都比较稳。打开终端执行:
bash复制node -v
npm -v
如果提示找不到命令,需要先安装 Node.js。官网下载 LTS 安装包一路下一步就行,macOS 用户可以用 Homebrew:
bash复制brew install node
Git 用来拉取 cc-connect 源码,也顺手检查一下:
bash复制git --version
没有的话根据操作系统装一下,Windows 用户直接装 Git for Windows,装完自带 Git Bash,后面操作命令更方便。
提示:装完 Node 后如果 npm 下载依赖慢,可以临时切换镜像源,但注意只影响 npm 下载,不会影响系统其他配置。
2.2 飞书开放平台应用创建与权限配置
现在去飞
