很多开发者在跑 AI Agent 任务时都会遇到一个非常具体的体验瓶颈Agent 明明已经能自主规划任务、调用工具了可每到执行敏感操作之前总要停下来等人点一次“允许”。如果任务是在本地终端里跑这个确认动作往往只能回到电脑前完成。一旦任务数量多、执行周期长人就被牢牢钉在工位上谈不上“自动化”。于是越来越多人开始把目光投向一个更顺手的入口把飞书机器人变成 Agent 的远程授权面板。用户在手机飞书里就能收到 Agent 发来的审批请求点一点按钮Agent 继续往下跑。这个思路听起来很直接但要安全、稳定地落地还缺一个把飞书消息和 Agent 执行链路串起来的中间层。botmux 就是这类桥接工具中比较有代表性的一种。这篇教程会从概念、原理、环境准备、完整实战和常见排查几个方面把“用 botmux 打通飞书与 Agent”这条路完整走一遍适合正在做 Agent 工程化落地、或者想把 AI 任务接入办公软件的开发者参考。1. 先理解为什么要用 botmux 打通飞书与 Agent1.1 Agent 授权的“最后一公里”难题一个成熟的 Agent 不只是会聊天它通常具备调用 Shell 命令、读写文件、请求外部 API、操作数据库等能力。这些能力越强风险边界就越需要控制。所以大多数 Agent 框架在设计时都会加入人工授权环节Agent 在执行某个高风险动作之前先弹出一个确认框等用户批准后再继续。这种设计本身没有问题问题出在“确认框”的形态上。本地终端里的确认框只能和电脑前的人交互IDE 插件里的授权弹窗也只能在桌面环境使用即使 Agent 跑在服务器上如果授权界面绑定在某个网页控制台里你依然需要打开浏览器、登录、找到对应任务再点一次允许。对单机跑一两个任务来说还能接受但如果同时跑多个 Agent、多个任务授权就会变成高频率打断操作甚至比 Agent 本身更耗时。飞书的价值在于它把“授权入口”从电脑端搬到了手机端也搬到了团队协作的聊天窗口里。Agent 需要授权时通过飞书机器人把任务信息、风险说明、审批按钮推送给指定用户用户在飞书里点一下按钮授权结果就传回 Agent。这个流程看起来不复杂但涉及消息接收、身份校验、状态管理、执行结果回传等多个环节这些都是 botmux 要处理的核心问题。1.2 botmux 到底是什么从名称来看“botmux”可以拆成 bot 和 mux 两部分。mux 在计算机领域通常指多路复用multiplex所以 botmux 强调的是把多个机器人消息渠道统一接入、按规则分发。在实际工程里它更像一个连接 IM 平台与 Agent 执行引擎的“消息网关”飞书消息先进 botmuxbotmux 做身份校验和意图解析再调用后面的 Agent 服务Agent 执行完后的结果也由 botmux 封装后送回飞书。有了这层网关飞书和 Agent 之间就不再是简单的“点对点直连”。botmux 可以替飞书屏蔽掉 Agent 内部实现细节也可以替 Agent 统一处理来自飞书的身份认证、权限校验、消息格式转换、回调重试等问题。开发者需要改 Agent 的后端逻辑时只要 Agent 对外暴露的接口保持不变飞书侧就不需要跟着调整反之如果换掉飞书机器人账号也只是改 botmux 配置Agent 侧无感。1.3 botmux 在飞书与 Agent 之间扮演的角色下面用一个表格说明三种常见连接方式之间的区别连接方式是否接收飞书事件是否能做权限控制是否适合生产环境飞书自定义机器人 Webhook只能发消息不能接收回调弱只有简单签名不适合做授权闭环飞书自建应用机器人 业务代码直连 Agent可以接收消息但逻辑散落在业务代码里需要自己实现适合小规模但扩展性一般botmux 中间层 Agent 服务统一接入消息、统一回调可做身份校验、授权过期、审计日志更适合多 Agent、多团队协作场景自定义机器人 Webhook 最大的限制是“只能单向发送”。你可以让它把 Agent 执行结果推送到群里却没有办法接收用户在飞书里点击按钮后的回调。自建应用机器人解决了双向通信问题但如果每个项目都自己实现一套“接收飞书消息 → 解析指令 → 调 Agent → 回传结果”的代码后续维护成本会很高。botmux 这类中间层把公共逻辑抽出来之后Agent 侧只需要关心“接收审批请求、执行任务、返回结果”飞书侧的接入细节全部收敛到网关层。2. 环境准备与版本说明2.1 准备环境清单在开始之前先列一下完成这套流程需要的环境。本文示例以常见开发环境为例重点演示配置思路具体版本需要根据你本机的实际情况调整。操作系统Linux / macOS / Windows 均可示例代码基于 Python 编写。Python 版本建议 3.9 及以上示例使用 FastAPI 框架。飞书开放平台账号需要能登录飞书开放平台后台并创建企业自建应用。Agent 服务可以是任意语言实现的 HTTP 服务只要能接收 botmux 转发的请求即可。为了演示本文用 Python 写一个最小接口。botmux下文会提供一份通用配置结构具体字段以你下载版本对应的官方文档为准。回调地址botmux 需要暴露一个可供飞书服务器访问的公网 HTTP 地址。本地测试时可以使用内网穿透工具把本机端口映射到公网也可以直接部署到一台有公网 IP 的开发服务器上。2.2 飞书开放平台需要提前准备什么飞书开放平台是这套方案里无法绕开的基础设施。你需要创建一个企业自建应用然后在这个应用里完成三件事开启机器人能力、配置事件订阅、获取应用凭证。创建应用后后台通常能看到几个关键凭证App ID、App Secret、Verification Token、Encrypt Key。其中 App ID 用于标识应用App Secret 用于调用飞书开放接口时获取 tenant_access_tokenVerification Token 和 Encrypt Key 用于事件订阅的验签和加解密。这些字段在后续配置 botmux 时都会用到建议先复制保存到本地但不要在公开项目里泄露。事件订阅需要配置一个请求地址飞书服务器收到新消息后会把事件内容 POST 到这个地址。为了让飞书能访问到这个地址必须是公网可达的。飞书在配置回调地址时通常会先发送一个 URL 验证请求你的服务端需要正确响应 challenge 才能保存成功这部分我们会放到实战章节细讲。2.3 关于版本的提醒飞书开放平台的接口权限和事件类型会随官方版本迭代调整botmux 这种成长中的工具也可能频繁更新配置格式。本文写的字段名、端点和 JSON 结构都属于“示例思路”如果和你手头的版本不一致一定以官方文档为准。尤其注意不要照抄网上的老教程配置一个已经废弃的回调事件类型否则会出现“消息收到了但程序不触发”的奇怪问题。3. 核心原理拆解一条授权消息的完整链路3.1 从飞书消息到 Agent 执行为了让后面实战部分更容易理解先来看一条授权消息的完整生命周期。假设用户小张在飞书里给 Agent 机器人发了一条消息“明天上午十点提醒我在周会发言”。这条消息从发送到 Agent 真正执行中间会经过以下步骤飞书服务器把消息事件推送到 botmux 配置的回调地址。botmux 先做验签确认这个事件确实来自飞书而不是伪造请求。botmux 读取消息内容识别发送者身份判断该用户是否有权限给这个 Agent 下令。botmux 把消息转成 Agent 能理解的请求调用 Agent 的入口接口。Agent 解析任务、生成计划判断是否需要人工授权。如果不需要授权Agent 直接执行并把结果返回。如果需要授权Agent 返回一个“待授权”状态botmux 把任务信息封装成飞书卡片消息推送给对应审批人。审批人在飞书里点击“允许”或“拒绝”botmux 收到回调后更新任务状态并通知 Agent 继续执行。从第 1 步到第 8 步关键点并不在于每段代码有多复杂而在于“状态”的维护同一个任务在飞书侧和 Agent 侧必须能够对应起来用户点了按钮之后Agent 才知道批准的是哪一个任务。3.2 回调验签与消息解析飞书事件订阅为了保证安全性会在回调请求里带上校验信息。早期版本常用 Verification Token 做双重校验也支持在配置 Encrypt Key 后对回调内容进行加密。botmux 拿到请求后第一件事就是校验这个请求是否来自飞书避免攻击者伪造一个请求来触发 Agent 执行。对于 URL 验证请求飞书通常会发送一个带有 challenge 字段的 JSON服务端校验 token 无误后需要把 challenge 原样返回。常见响应格式如下{ challenge: xxxxxx }消息事件的类型不同数据结构也会不同。接收用户消息通常对应的事件类型是 im.message.receive_v1具体字段以飞书开放平台当前文档为准。解析时一般需要获取发送者 open_id、消息内容、消息类型等字段这些信息会作为后续权限判断和 Agent 请求参数的来源。3.3 授权状态机授权流程本质上是一个状态机。一个任务至少会经历以下几个状态PENDINGAgent 已生成任务等待用户批准。APPROVED用户在飞书里点了允许任务可以被执行。REJECTED用户在飞书里点了拒绝任务终止。EXPIRED等待超时授权失效。EXECUTEDAgent 已执行完成。为什么要把状态设计得这么清楚因为在实际并发场景里同一个用户可能在短时间内收到多个 Agent 的授权请求。如果状态不区分很容易出现“用户点了最新一个按钮结果之前所有任务都被放行”的问题。botmux 在处理飞书按钮回调时必须把 task_id 和飞书消息 ID 绑定起来确认用户点击的到底是哪个任务。给每个授权加一个过期时间也很有必要避免一个审批请求在聊天记录里挂了好几天后还能被误触发放行。3.4 为什么要引入中间层而不是业务代码直连有些开发者会问直接在 Agent 的代码里调用飞书接口不也能实现吗确实可以小规模验证阶段没有任何问题。但一旦 Agent 数量变多局面就会失控。假设你有三个 Agent一个负责定时任务一个负责数据分析一个负责自动发周报。如果每个 Agent 都自己实现“发飞书消息 → 接收用户回调 → 维护授权状态”那这个逻辑就被复制了三次而且三个 Agent 的消息卡片样式、权限规则、登录校验很可能还不一致。引入 botmux 之后飞书侧的能力被抽成公共层三个 Agent 只需要在业务代码里调用统一的“待授权查询”和“授权结果通知”接口即可。这也是为什么很多团队最终会选择在中间层做文章而不是把所有逻辑塞进 Agent。4. 完整实战用 botmux 打通飞书与 Agent4.1 创建飞书自建应用并开启机器人首先登录飞书开放平台创建一个企业自建应用。应用创建完成后进入应用后台在“添加应用能力”里找到机器人开启机器人功能。这一步完成后飞书中会出现一个该应用对应的机器人之后你可以在飞书聊天里搜索到这个机器人并给它发消息。接着在应用后台获取 App ID、App Secret、Verification Token 和 Encrypt Key。如果你希望回调内容加密传输可以设置 Encrypt Key如果刚开始调试建议先不启用加密等消息链路跑通之后再打开排查问题会更容易一些。还需要配置权限。飞书开放平台的接口调用需要申请对应权限比如给用户发消息、读取用户信息等。不同企业应用的管理员审核策略不同建议提前申请应用所在企业内测试成员的管理权限避免联调时卡在权限不足上。4.2 准备 botmux 网关配置botmux 安装完成后通常会有一个配置文件用来描述飞书接入信息、Agent 服务地址和授权策略。下面是一份通用配置示例# botmux 配置示例字段名以实际版本文档为准 server: port: 8080 feishu: app_id: cli_xxxxxxxxxxxxxxxx app_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx verification_token: xxxxxxxxxxxxxxxx encrypt_key: agent: endpoint: http://127.0.0.1:8000 pending_path: /agent/pending authorize_path: /agent/authorize execute_path: /agent/execute timeout_seconds: 120 auth: mode: feishu_user expire_minutes: 10 allowed_users: - ou_xxxxxxxxxxxxxxxx配置里最关键的是三个部分feishu 区域的凭证要和飞书开放平台后台保持一致agent 区域的 endpoint 要指向你真实的 Agent 服务地址auth 区域定义了哪些飞书用户可以触发 Agent 授权。allowed_users 是一项非常实用的安全手段如果配置为空则可能默认允许所有企业成员使用这通常不是我们想要的结果。启动 botmux 之后它会在配置的端口上监听飞书回调。默认情况下你应该看到一个类似“botmux started”的日志输出具体启动命令以你使用的版本为准。4.3 编写 Agent 侧适配接口为了让 botmux 能调用 AgentAgent 侧至少需要提供几个 HTTP 接口。下面用 Python FastAPI 写一个最小可运行的示例帮助你理解 Agent 侧接口应该长什么样。这个文件可以直接保存为agent_server.py运行也可以作为真实 Agent 项目的接口设计参考# 文件路径agent_server.py from fastapi import FastAPI, Request import uvicorn app FastAPI() # 查询当前待授权的任务列表 app.get(/agent/pending) async def pending_tasks(): return { code: 0, data: [ { task_id: task_20250101_001, action: 执行 rm -rf /tmp/cache, risk: high, status: pending } ] } # 接收授权结果 app.post(/agent/authorize) async def authorize_task(request: Request): body await request.json() task_id body.get(task_id) decision body.get(decision) # approved / rejected print(ftask {task_id} decision: {decision}) return { code: 0, task_id: task_id, status: approved if decision approved else rejected } # Agent 执行入口 app.post(/agent/execute) async def execute_agent(request: Request): body await request.json() user_input body.get(user_input, ) print(fexecute task: {user_input}) return { code: 0, message: task started } if __name__ __main__: uvicorn.run(app, host0.0.0.0, port8000)在这份示例里/agent/pending返回尚未被授权的任务列表/agent/authorize接收 botmux 转来的用户审批结果/agent/execute是真正执行 Agent 逻辑的入口。真实项目中这三个接口通常会把请求落到消息队列或任务调度系统而不是像示例这样直接打印日志但接口设计思路是通用的。如果你的 Agent 已经有自己的任务系统可以把这三个接口改造成对现有服务的代理让 botmux 只负责转发。4.4 配置飞书事件订阅地址飞书事件订阅地址需要配置为 botmux 对外暴露的回调地址例如https://your-domain.example.com/webhook/feishu如果你在本地调试可以使用内网穿透工具把本机 8080 端口映射到公网然后把穿透工具生成的公网地址填到飞书后台。需要注意的是飞书服务器必须能够稳定访问这个地址如果网络不稳定配置验证可能会失败。在飞书开放平台后台的“事件订阅”页面添加“接收消息”事件。事件类型通常为im.message.receive_v1。添加时飞书会向回调地址发送一个验证请求如果你的 botmux 配置正确它会自动响应 challenge飞书页面会显示连接成功。如果你暂时没有可用的回调地址可以先看下面这段极简代码理解飞书 URL 验证的响应逻辑。它不依赖 botmux只是帮你验证“飞书回调连通性”。# 文件路径webhook_demo.py仅用于理解回调响应格式 from fastapi import FastAPI, Request from fastapi.responses import JSONResponse app FastAPI() app.post(/webhook/feishu) async def feishu_callback(request: Request): event await request.json() # 如果是 URL 验证请求返回 challenge if event.get(type) url_verification: return JSONResponse({challenge: event.get(challenge)}) return {code: 0}这个极简示例不处理具体业务只验证飞书回调链路是否连通。确认这段代码能通过飞书后台验证后再把地址切换到 botmux可以大幅减少排查范围。4.5 启动联调假设你在本机同时启动了 Agent 服务和 botmux 服务Agent 监听 8000 端口botmux 监听 8080 端口那么联调流程大致如下在飞书里搜索你创建的应用机器人发送一条消息例如“查看待授权任务”。飞书把消息事件推送到 botmux 的回调地址。botmux 解析消息后调用 Agent 的/agent/pending接口获取待授权任务列表。botmux 把任务列表封装成飞书消息通过飞书机器人发送给当前用户。用户在飞书里看到任务后如果点击了“允许”按钮飞书会把按钮回调推送到 botmux。botmux 再调用 Agent 的/agent/authorize接口把审批结果传过去。Agent 判断审批通过后继续执行任务。如果一切正常你会在 Agent 服务的日志里看到授权结果打印飞书聊天窗口也能收到最终的执行反馈。4.6 验证与观察联调过程中建议重点观察三个日志位置。第一个是 botmux 的访问日志看飞书回调是否正常进入、响应是否超时第二个是 Agent 服务日志看/agent/pending和/agent/authorize是否被调用、参数是否正确第三个是飞书开放平台后台的“调试工具”里的回调记录如果飞书服务器推送失败通常能在后台看到失败原因。常见情况是飞书回调成功但 botmux 调用 Agent 超时。这种问题往往不是 botmux 的问题而是 Agent 接口处理太慢超过了配置里的timeout_seconds阈值。调试时可以把超时时间调大同时优化 Agent 接口的响应速度。5. 常见问题与排查思路问题现象常见原因解决思路飞书后台配置回调地址时验证失败回调地址不可达或没有正确响应 challenge先用极简 webhook 代码验证连通性再切换到 botmux消息事件收到但 Agent 不执行事件类型配置错误或 botmux 转发规则没匹配检查事件类型是否为 im.message.receive_v1检查 Agent endpoint 配置飞书机器人发不出消息App 权限不足或 tenant_access_token 获取失败检查应用权限、App Secret 是否配置正确用户点击授权按钮后没有反应按钮 callback 没有推送到 botmux或 task_id 匹配不到任务检查飞书卡片回调地址、任务状态是否还在有效期内授权状态互相覆盖多个任务共用同一个状态字段没有用 task_id 区分把每个按钮事件都绑定 task_id避免状态全局覆盖回调内容解析乱码启用了 Encrypt Key但 botmux 未配置对应密钥要么关闭加密要么保证 Encrypt Key 与飞书后台一致同一个任务审批了两次用户重复点击按钮或回调重试机制触发在 Agent 侧做幂等处理用 task_id 做去重部分用户无法触发 Agentallowed_users 名单未包含该用户把用户 open_id 加入白名单或者调整授权策略排查这类链路问题时建议按“飞书 → botmux → Agent”的顺序一层层确认。先用极简 webhook 确认飞书能回调成功再用 curl 模拟 botmux确认 Agent 接口能正常响应最后才把两端连接起来。跳步排查往往会浪费很多时间。6. 最佳实践与工程建议6.1 安全边界必须前置把 Agent 授权入口搬到飞书之后便利性提升的同时安全边界也需要重新审视。飞书消息虽然是企业内部系统但并不意味着所有企业成员都能对 Agent 下发高危指令。在 botmux 配置中一定要用 allowed_users 之类机制限制可用用户范围。Agent 侧接口也不能假设所有请求都来自 botmux建议在内部网络中让 botmux 和 Agent 服务之间使用独立的 API Token 或者 mTLS 认证避免局域网内其他服务伪造请求。涉及删除文件、操作数据库、发外部请求等高危操作时最好再加一层“双人复核”机制而不是单人在飞书里点一下就放行。授权过期时间也要设置得短一些比如十分钟内有效超过时间必须重新申请。这些细节在个人项目里也许不重要但在企业环境里是底线。6.2 状态管理与幂等性授权回调在分布式系统里经常出现重试飞书服务器如果没收到成功响应可能会在几十秒后再次推送同一个回调。如果 Agent 不处理重复回调同一个任务可能被执行两次。解决思路是让授权结果处理具备幂等性以 task_id 为唯一键先查询任务是否已经处理过如果已经处理直接返回成功不再重复执行。同理任务状态要避免用布尔值表示。比如用一个status字段存储 pending、approved、rejected、expired、executed这样排查问题时能知道任务到底卡在哪一步。很多“点击没反应”的问题最后查下来就是任务状态已经被改成 executed但前端卡片还停留在 pending 状态。6.3 配置管理与日志审计botmux 的配置文件中包含 App Secret、Verification Token 等敏感信息不要提交到 Git 仓库。建议通过环境变量或配置中心注入并在发布流程中做密钥轮换。注意即使配置中心接管了密钥也需要保证配置文件的模板不会把密钥明文写死。Agent 授权是高风险操作必须留审计日志。每次授权请求至少要记录任务 ID、操作描述、风险等级、发起用户、审批用户、审批结果、审批时间。这些日志在排查问题、安全回溯、合规审计时非常有用。建议在 botmux 侧和 Agent 侧各记一份两侧日志字段关联到同一个 task_id。6.4 生产环境部署建议生产环境不建议把 botmux 和 Agent 部署在同一台机器上至少要做到进程隔离。botmux 可以只暴露飞书回调端口Agent 服务完全放在内网只有 botmux 能访问。如果条件允许把 botmux 部署到独立的容器或虚拟机上配合容器健康检查避免单点故障。上线前一定要在测试环境完整演练一遍“飞书发消息 → Agent 执行 → 授权 → 结果回传”的流程并且专门测试异常场景用户拒绝授权、回调超时、权限不足、重复点击按钮。这样生产环境出现问题时你手上已经有一份可靠的排查清单。6.5 与飞书多维表格、消息通知结合打通飞书与 Agent 之后能力边界还可以继续扩展。很多团队会把 Agent 执行的记录、审批结果同步到飞书多维表格形成可视化台账也会把构建、监控告警等其他系统接入飞书通知统一消息入口。不过要记住这些都属于“飞书集成”的延伸场景核心仍然是消息与任务状态的可靠传递。先把最核心的授权链路做稳定再逐步叠加多维表格和通知能力比一开始把所有功能都铺开更容易维护。7. 总结使用 botmux 打通飞书与 Agent本质上是在解决 Agent 落地过程中的“授权交互”问题。它把原本只能在本地点确认的授权流程转化为飞书聊天窗里的即时操作提升了自动化任务的连续性也方便了团队成员之间的协作。本文从 Agent 授权的痛点出发梳理了 botmux 作为消息网关的工作原理并通过一个最小可运行的实战示例演示了从飞书创建应用、配置事件订阅、编写 Agent 适配接口到授权消息完整链路的打通方法。如果你正准备在自己的项目里落地这套方案建议优先关注三件事第一安全边界要前置权限校验和密钥管理不能省第二任务状态和幂等性设计要提前做好避免重复审批和状态错乱第三生产环境部署前一定要在测试环境把异常用例跑一遍。把这三点想清楚飞书与 Agent 的打通就不再只是“能跑”而是“能稳定地在生产环境跑”。