1. 为什么要把本地 AI Agent 接到飞书里很多人第一次听到「AI Agent 接入飞书」会以为要写一堆服务端代码其实核心诉求特别朴素我本地跑着一个能读写文件、能执行命令的 Agent但每次都得坐在电脑前敲终端出门在外就断了。cc-connect 这个开源连接器解决的就是这件事——它在你本机和飞书之间架一条长连接你在手机飞书里发一句话消息通过飞书开放平台推到你电脑上的 cc-connectcc-connect 再转给本地 Agent 执行执行结果包括截图、生成的图片、PDF 附件原路推回飞书聊天框。所以这套方案适合谁适合零基础但愿意照着敲命令的开发者适合想把 Claude Code 这类本地 Agent 变成「随身助手」的人也适合团队里想给内部工具加一个飞书入口的工程师。你不需要公网 IP不需要买服务器一台装着 Node.js 的 Windows 或 macOS 电脑就够。整条链路里有两个关键配置点一个是 cc-connect 自己的config.toml另一个是 Agent 调用大模型时用的统一 Key。后者我用 TaoToken 来统一管理一个 Key 覆盖多个模型省得在 cc-connect、Claude Code、Codex 之间来回换凭证。这篇就按「装环境 → 拿飞书凭证 → 写配置 → 填 Key → 本地联调 → 排错」的顺序走一遍目标是一次跑通消息收发。你跟着做遇到报错直接跳到第 5 节对照。2. 前置准备Node.js、npm 与 TaoToken 统一 Key先说环境。cc-connect 是 Node.js 写的所以第一步是确认本机有 Node.js 和 npm。打开 PowerShellWindows或终端macOS执行node -v npm -v正常会打印类似v20.11.0和10.2.4。如果提示「不是内部或外部命令」说明没装或没进 PATH去 Node.js 官网下 LTS 版本装上安装时勾选「Add to PATH」。版本建议 Node 18 以上太老的版本跑长连接会缺 WebSocket 支持。接着是 TaoToken 统一 Key。为什么这里要提它因为 cc-connect 本身只是「消息管道」真正干活的是背后的 Agent而 Agent 要调大模型就得有 Base URL 和 Key。TaoToken 提供的是 OpenAI 兼容接口一个 Key 可以走多个模型配置时只要把 Base URL 指向https://taotoken.net/api再填上你的 Key 和 Model ID 就行。这样 cc-connect、Claude Code、Codex 三处用的是同一套凭证改起来只改一个地方。拿 Key 的路径登录 TaoToken 控制台进 API Keys 页面创建一个新 Key复制出来一般以sk-开头。这个 Key 只显示一次先存到记事本里。如果你还没账号从官网进控制台注册即可整个流程几分钟。注意Key 属于敏感凭证别直接提交到 Git 仓库。后面写auth.json时我会说明放在哪个目录那个目录默认不在版本控制里。环境齐了之后我们先把 cc-connect 装上再去飞书后台拿凭证。3. 可复制配置cc-connect 安装、飞书凭证与 auth.json 填写这一节是全文的核心所有片段都可以直接复制。先装 cc-connect为了支持图片和附件回传装 beta 版npm install -g cc-connectbetaWindows 下如果报权限错误用管理员身份开 PowerShell 再执行。装完验证cc-connect --version能打印版本号就说明全局命令可用。接下来去飞书开放平台建应用。登录后点「创建企业自建应用」名字随便起比如cc-connect。进应用后左侧「凭据与基础信息」里能拿到两个值App ID形如cli_xxxxxxxx和App Secret。这两个就是 cc-connect 连飞书的钥匙。拿到后回到终端用一条命令自动生成配置cc-connect feishu setup --project my-project --app cli_xxxxxxxx:你的AppSecret这条命令会在C:\Users\你的用户名\.cc-connect\config.tomlmacOS 是~/.cc-connect/config.toml生成飞书专用配置并默认开启附件回传。生成的config.toml大致长这样你可以打开核对[project.my-project] platform feishu app_id cli_xxxxxxxx app_secret 你的AppSecret attachment_send on [project.my-project.agent] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model claude-sonnet-4-20250514这里三个字段必须写全base_url指向 TaoToken 的 API 地址api_key填你刚创建的 Keymodel填你要用的 Model ID。Model ID 以 TaoToken 控制台模型列表里显示的为准别自己拼。如果你用的是 Claude Code 或 Codex 这类走auth.json的 Agent还要在对应目录写一份凭证文件。以 Codex 为例路径通常是~/.codex/auth.json内容{ OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: sk-你的TaoTokenKey, model: claude-sonnet-4-20250514 }Claude Code 的settings.json里则对应{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }三件套记住Base URL、Key、Model ID缺一个都会在调用时报错。cc-connect 的config.toml和 Agent 的auth.json用的是同一个 Key这就是「统一 Key」的意义——换模型只改 Model ID不用重新申请凭证。配置写完飞书那边还有权限要开。回到开放平台左侧「权限管理」搜索并勾选这几项获取与更新用户基本信息、接收群聊消息、接收单聊消息、读取群消息、读取单聊消息、以应用身份发送群消息。然后进「事件订阅」订阅方式选「使用长连接接收事件」并启用事件里添加im.message.receive_v1接收消息。最后去「版本管理与发布」创建版本并发布——每次改权限都要重新发布否则不生效。4. 验证请求本地联调与消息收发实测配置和权限都就绪后直接在终端跑cc-connect看到控制台打印类似[Info] connected to wss://msg-frontier.feishu.cn/ws/v2?...的日志说明长连接已经打通。这一步不需要公网 IP飞书的长连接模式会主动把事件推到你本机。现在打开飞书搜索你刚创建的应用名进入单聊窗口发一句「你好」。正常情况下 cc-connect 终端会打印收到消息的日志Agent 处理后把回复推回飞书。如果 Agent 配的是 TaoToken 的接口你可以在终端看到一次 HTTP 请求记录返回 200 就说明 Key 和 Base URL 都对。再验证附件回传。首次聊天时先发一条指令/bind setup这会把附件回传的指令写进项目记忆文件Agent 之后生成图片就会调用正确命令。然后对机器人说「帮我截取当前桌面」Agent 执行截图后飞书聊天框里应该直接弹出桌面原图而不是一行本地路径。这一步是很多人卡住的地方——不预热的话Agent 只会回你C:\Users\...\screenshot.png这种路径图片传不回来。验证模型调用是否真的走了 TaoToken可以单独发一个请求测curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:ping}]}返回里带choices字段就说明 Key 有效、模型可用。这个请求和 cc-connect 内部调的是同一个接口先单独测通能帮你快速定位问题出在链路哪一段。5. 常见报错排查401、local proxy failed 与 reading choices跑不通的时候别慌大部分问题集中在几个固定报错上对照下面处理。401 UnauthorizedKey 错了或没生效。检查config.toml里的api_key和auth.json里的OPENAI_API_KEY是不是同一个有没有多余空格。TaoToken 的 Key 以sk-开头复制时别漏字符。如果刚在控制台重新生成过 Key旧 Key 会失效记得同步更新所有配置文件。local proxy failed / connection refused通常是 Base URL 写错。确认是https://taotoken.net/api不要多加/v1或结尾斜杠不同 Agent 对路径拼接方式不一样多写一段就会 404。另外检查本机网络能不能访问外网公司网络如果有出口限制curl 那条测试命令会先失败。reading choices 报错Cannot read properties of undefined (reading choices)说明返回体里没有choices字段一般是模型名写错或接口返回了错误对象。先用第 4 节的 curl 命令确认 Model ID 正确再检查config.toml的model字段。有些 Agent 要求模型名带前缀以 TaoToken 控制台列表为准。飞书侧收不到消息先看 cc-connect 终端有没有打印收到事件的日志。没有的话多半是事件订阅没配im.message.receive_v1或者权限改了没重新发布版本。有日志但 Agent 没响应就是 Agent 侧的问题回到 401 那条排查。OAuth 相关报错Claude Code 或 Codex 如果提示 OAuth 失败说明它还在走官方登录流程没读你的auth.json。确认文件路径正确~/.codex/auth.json或对应目录JSON 格式没写错字段名大小写一致。改完重启 Agent 进程。图片只发路径不发图回到第 4 节先发/bind setup预热再让 Agent 截图。没预热是最高频的原因。排查顺序建议先 curl 测 Key → 再跑 cc-connect 看长连接 → 再飞书发消息看事件 → 最后测附件。一层层往下问题一定落在某一层。6. 后续升级与长期使用建议cc-connect 更新比较勤升级就一条命令npm install -g cc-connectbeta升级后配置不会丢config.toml还在原目录。如果新版本改了配置字段启动时会提示按提示补上即可。长期用下来我建议把 Agent 的凭证统一收敛到 TaoToken 一处管理。cc-connect、Claude Code、Codex 都指向同一个 Base URL 和 Key换模型只改 Model ID不用每个工具重新配。需要看用量或换 Key进 TaoToken 控制台操作就行。如果你打算把 Agent 用在日常编码和自动化任务上可以考虑 Coding Plan额度更稳适合长期挂着 cc-connect 跑。最后提醒两点一是飞书应用每次改权限都要重新发布版本别改完就忘二是auth.json和config.toml里的 Key 别提交到公开仓库本地目录默认不在版本控制里保持这样就好。按这套流程走完你的本地 Agent 就真正变成手机飞书里随叫随到的助手了。