包包和糖葫芦先说结论：这套“Clawdbot 部署到飞书（飞连）”的方案，本质上是把 Claude Code 的能力封装成一个可远程调用的服务，再把飞书机器人作为交互入口。团队成员不需要在自己电脑上装任何 AI 开发环境，直接在飞书群里 @ 机器人，就能让它写代码、解释报错、做代码审查，甚至跑一些自动化脚本。实测下来，整个链路的稳定性和使用体验都远超预期。
我是在一次内部工具改造里把 Clawdbot 接入飞书的，现在团队每天在飞书里发起上百次任务，效果比预想中好很多。这篇教程会从整体架构讲起，把飞书应用创建、Clawdbot 服务部署、事件订阅配置、消息回传这些环节全部拆开揉碎，最后再把我踩过的坑和排查方法整理成速查清单。如果你是第一次接触这套东西，照着一步步做，大概半小时能把机器人拉起来。
1. 先把整体链路想清楚再动手
1.1 Clawdbot 到底解决了什么问题
很多人第一次看到 Clawdbot 会以为它又是一个聊天机器人框架，其实它的核心定位更准确：把 Claude Code 变成可以被外部消息平台调用的服务。Claude Code 本身是一个终端里的 AI 编码代理，能读文件、写代码、执行命令，能力很强，但它默认是“一个人坐在终端前面”的使用方式。团队里不是每个人都有精力去配置环境、管理 API Key，更不可能每个人都把终端挂在后台等 AI 输出。
Clawdbot 做的事情就是把这一层能力抽出来，做成一个 HTTP API 服务。你向它发一条文本消息，它调用 Claude Code 的底层能力处理完，再把结果返回。这样一来，前端接什么都可以是飞书、钉钉、Slack，甚至是一个网页对话框。接入飞书之后，整个团队只需要打开飞书，把消息发给机器人，剩下的事情由服务端完成。这个模式在开发团队里特别实用，产品和测试同学也能直接用上 AI 编码能力，而不需要理解背后是什么工具。
1.2 从飞书消息到 AI 回复的完整链路
在开始部署之前，我建议先把整条数据链路在脑子里过一遍，因为后面配置踩坑的时候，大部分问题都出在链路某一个环节断了。
链路整体是这样走的：
- 用户在飞书里给机器人发一条消息，或者在一个群里 @ 机器人。
- 飞书开放平台收到消息，通过事件订阅机制把消息事件推送给 Clawdbot 服务。
- Clawdbot 解析消息内容，把它包装成 Claude Code 能处理的任务请求。
- Clawdbot 调用 Anthropic API，Claude Code 执行分析、编码、生成文本等任务。
- 结果返回给 Clawdbot 服务。
- Clawdbot 调用飞书开放平台的发送消息 API，把结果回传给用户或群聊。
这里最容易被忽略的是第 2 步和第 6 步：进入飞书的消息是“事件订阅”在推动，出去的回复是“OpenAPI 消息接口”在推送。两套体系，一个被动接收，一个主动发送，配置的位置和凭证都不一样。很多教程只说了怎么发消息，没说怎么收消息，导致机器人只能单向回复，收不到用户的输入，这是新手最容易遇到的第一个大坑。
1.3 为什么选择“Clawdbot 服务 + 飞书连接器”这套组合
市面上接入飞书机器人的方案大致有几种：直接在飞书低代码平台上搭机器人、用飞书中转 Webhook、自己部署服务接入开放平台。我最终选择 Clawdbot 服务，因为 Claude Code 这类工具的执行逻辑没法用低代码平台的普通节点来承载，它需要真正的终端环境、文件系统和长任务运行能力。飞书里的低代码节点更适合做简单问答和流程编排，遇到复杂编码任务就力不从心了。
而飞书连接器（很多飞书教程把它叫做“飞连”）在这里的角色是转发层，它可以把飞书消息的事件通过 HTTP 请求转发到我的 Clawdbot 服务上，同时也可以把返回内容再送回飞书会话。也就是说，在我这版方案里，Clawdbot 是真正干活的引擎，飞书连接器负责把飞书侧的消息路由和回传打通。这样拆的好处是：飞书侧的配置集中在连接器里，服务端只需要暴露一个 HTTP 接口，职责清晰，后面单独替换成其他消息平台也很方便。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 部署前需要准备好的东西
2.1 必需的三样东西：API Key、飞书应用凭证、运行环境
在动手之前，我建议先把下面这三样东西准备齐，不要等到配置到一半才发现缺了某个 key，那会很打断节奏。
第一是 Anthropic 的 API Key，也就是使用 Claude Code 时用到的那把 key。Clawdbot 在运行时需要用它来认证并对接 Claude Code 的能力。注意这个 key 是服务端使用的，千万不要把它写进飞书侧的配置里，否则相当于把核心密钥暴露在第三方平台上，后面我会专门讲安全问题。
第二是飞书开放平台的应用凭证，包括 App ID 和 App Secret。这两项在飞书开放平台创建应用之后可以拿到，App ID 是应用的唯一标识，App Secret 相当于应用的密码，后面获取 tenant_access_token 时要用到。另外还需要在应用里开启“机器人”能力，并且开启“接收消息”相关的事件订阅权限。
第三是运行环境。最省事的方式是准备一台能跑 Docker 的 Linux 服务器或者本机 Docker 环境，当然直接用本地终端跑 Node.js 服务也可以，但我强烈建议用 Docker Desktop 或者云服务器部署，因为 Clawdbot 依赖的 Node 环境和各种依赖包已经通过镜像打包好了，不需要在每台机器上手动装。
2.2 在飞书开放平台创建应用并开启机器人能力
这一步看起来很简单，但我见过不少人在权限配置上栽了跟头，所以我单独列一个小节来说。
打开飞书开放平台后台，用管理员账号登录，在“开发者后台”里创建一个企业自建应用。应用名称我建议写得明确一点，比如“AI 编码助手”，后面在飞书里搜索应用会比较方便。创建完成之后，进入应用详情页，在“添加应用能力”里找到“机器人”，点击启用。这一步如果不做，你在飞书里根本搜不到这个应用，也就没法给它发消息。
接下来把页面切到“权限管理”，搜索并开通下面几个权限：
im:message（获取与发送单聊、群组消息）im:message.receive_v1（接收消息事件）im:chat（获取群组信息，用于群聊 @ 机器人场景）
注意，飞书权限有“仅本应用”和“企业”两个层级，建议按实际需求选择。如果只是团队内部使用，直接授权给企业成员即可，不需要发布到应用商店。之后在“版本管理与发布”里创建一个版本并发布，这样团队成员才可以在飞书里搜索到这个应用并开始使用。
2.3 本机环境准备：Docker 和基础网络连通性检查
环境准备上，我推荐的方式是安装 Docker Desktop（Windows / macOS）或在服务器上安装 Docker Engine。如果你是在服务器上部署，直接安装 Docker Engine + Docker Compose 插件就可以了。安装完成后跑一下 docker version 确认成功。
网络检查这件事很多人会忽略，但其实特别重要。Clawdbot 既需要访问 Anthropic 的 API，也可能需要在回复里带上 Markdown 格式的代码块，所以服务所在机器必须能够稳定访问外部网络。如果你用的服务器是在内网环境里，请先确认外网连通性，否则后面可能出现“飞书消息收到了但 Clawdbot 一直不回复”这种看起来毫无头绪的问题。
还有一个细节：如果你是在本地开发机部署，飞书事件订阅用 WebSocket 长连接模式会更方便，因为不需要公网 IP 回调，服务主动向外建立连接即可。后面配置事件订阅的时候我会展开讲。
3. 把 Clawdbot 服务跑起来
3.1 获取代码并完成环境变量配置
Clawdbot 的部署方式，我实际测试下来最稳的还是 Docker。先拉取镜像，或者从代码仓库把项目 clone 下来本地构建，两条路都可以。如果你是第一次接触，我建议先拉官方镜像，省去本地构建依赖的麻烦。
在项目根目录创建一个 .env 文件，把核心配置写进去。完整的配置项大致如下：
bash复制# Anthropic API 配置
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
CLAUDE_MODEL=claude-sonnet-4-20250514
# 飞书应用凭证
FEISHU_APP_ID=cli_xxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_EVENT_ENCRYPT_KEY=xxxxxxxxxxxxxxxxxxxxxxxx
# 服务监听配置
PORT=8787
HOST=0.0.0.0
这里有几个地方需要解释一下。
CLAUDE_MODEL 不一定每个版本都要求配置，但如果你对模型有明确的偏好，最好显式指定，避免服务端用默认模型，默认模型能力或者价格跟你预期不一致。我自己实测时用 claude-sonnet-4-20250514 效果稳定，复杂任务也能处理，成本上比用超大杯模型划算不少。
FEISHU_EVENT_ENCRYPT_KEY 是用来解密飞书推送过来的事件消息的，这个值在飞书开放平台“事件订阅”页面可以配置，自定义一个 32 位字符串即可。如果不配置加密，也可以留空跳过，但为了安全，还是建议开启。
3.2 用 Docker Compose 一键启动
我习惯用 Docker Compose 管理这种需要多个环境变量的服务，配置清晰，后面想加一个 Nginx 或者 Redis 也很方便。下面是一份可以拿来直接用的 docker-compose.yml：
yaml复制version: "3.8"
services:
clawdbot:
image: clawdbot/clawdbot:latest
container_name: clawdbot
restart: always
ports:
- "8787:8787"
env_file:
- .env
volumes:
- ./workspace:/workspace
启动之前，先确认 .env 文件和 docker-compose.yml 在同一个目录下。然后执行：
bash复制docker compose up -d
执行完之后用 docker compose logs -f 跟踪日志，看到类似 Clawdbot is running on http://0.0.0.0:8787 的输出，就说明服务起来了。
./workspace 这个目录挂载是给 Clawdbot 用的工作目录，它生成的临时文件、脚本文件都会放在这里。挂载到宿主机的好处是容器重建后数据还在，不会被 Docker 的容器生命周期一起清掉。
3.3 用 curl 快速验证服务是否正常
服务启动后，先别急着接飞书，用 curl 在本地验证一下接口能力，确认 Anthropic API Key 配置正确，Clawdbot 确实能完成任务。
bash复制curl -X POST http://localhost:8787/api/chat \
-H "Content-Type: application/json" \
-d '{
"message": "请写一个Python快速排序函数，并给出一行注释说明时间复杂度"
}'
正常情况下，等待几秒到十几秒后，接口会返回一段 JSON，里面包含生成好的代码和说明。
这一步的意义在于把问题隔离：如果 curl 请求能正常返回，说明 Clawdbot 服务本身没有问题，后面接飞书出问题就是飞书侧配置的事；如果 curl 请求超时或报鉴权错误，那要先处理 API Key 和网络，不要急着去调飞书。这个排查思路我后面还会反复用到。
3.4 本地运行时的几个注意点
如果你不想用 Docker，直接在本地跑 Node.js 也完全可以，但有几个细节需要提前知道。
Clawdbot 依赖 Node.js 18 以上的版本，装好依赖后需要通过环境变量加载配置，然后执行 npm start。在 Windows 上直接跑会遇到终端的符号兼容问题，比如路径分隔符和命令执行方式可能跟 Linux 不一样，所以如果非要用 Windows 本机调试，我建议还是先装一个 WSL2 环境，然后在 WSL 里跑，能少踩很多坑。
另外关于超时。Claude Code 处理复杂任务耗时会比较长，尤其是让它读代码仓库、跑测试的时候，几十秒甚至几分钟都很正常。这意味着 Clawdbot 服务本身要有足够的超时时间，同时也提示我们接入飞书时，对于重任务最好采用“先回复已收到，再异步推送结果”的方案。否则飞书侧等待响应超时，用户看到的就是机器人“装死”。
4. 把机器人挂到飞书会话里
4.1 事件订阅：选择长连接还是 Webhook
飞书开放平台接入机器人，实际上就是让飞书把消息事件推送给你的服务。飞书支持两种推送方式：一种是 Webhook 回调，需要提供一个公网可达的 HTTPS 地址；另一种是长连接（WebSocket）模式，服务主动向飞书服务器建立连接，飞书通过这个长连接推送事件。
在选择之前，先看你的运行环境。如果你用的是云服务器，已经有一个公网 IP 或者域名，那用 Webhook 回调更直接，所有事件实时推送到服务，排查问题也方便。如果你是本地开发机或者公司内网部署，没有公网 IP，那强烈建议用长连接模式。长连接模式下 Clawdbot 只需要能访问外网，不需要对外暴露任何端口，配置起来省掉一大半烦恼。
我这次实际部署的时候用的是 Webhook 模式，因为服务器在公网上，不用再多套一层反向代理。如果你和我一样用 Webhook，在飞书后台“事件订阅”页面填上回调地址，飞书会发一个 URL 验证请求，你的服务需要正确响应 challenge 字段。Clawdbot 已经内置了这个响应逻辑，你只需要在飞书后台把地址填成 http://你的域名:8787/feishu/webhook 即可。注意这个地址必须是公网可访问的 HTTPS 地址，HTTP 在飞书侧大部分场景会被拒绝。
4.2 飞书消息的接收与回传逻辑
飞书推送消息事件的 JSON 结构里，核心字段包括事件类型 im.message.receive_v1、消息内容 event.message.content、发送者 event.sender.sender_id.open_id、会话 ID event.message.chat_id。Clawdbot 收到事件后，会先从 content 里解析出用户发的文本，再把文本作为指令交给 Claude Code，最后通过飞书 OpenAPI 把结果发回去。
发送消息这一步用的是飞书 im/v1/messages 接口，请求头里需要带 tenant_access_token。这个 token 的获取方式是在服务端用 App ID 和 App Secret 去换：
bash复制curl -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
-H "Content-Type: application/json" \
-d '{
"app_id": "cli_xxxxxx",
"app_secret": "xxxxxx"
}'
拿到 token 之后，再调用发送消息接口：
bash复制curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
-H "Authorization: Bearer {tenant_access_token}" \
-H "Content-Type: application/json" \
-d '{
"receive_id": "ou_xxxxxx",
"msg_type": "text",
"content": "{\"text\":\"代码已生成，请查收。\"}"
}'
关于 receive_id_type，如果你在单聊场景回复用户，可以用 open_id；如果你要在群里回复所有人，得先用 chat_id。用错了 id 类型接口会报错，排查的时候注意看错误信息里提示的是 invalid receive_id 还是 invalid param。
Clawdbot 内部已经封装好了这套逻辑，正常情况下你不需要手动调 API 发消息。但理解这个机制很重要，因为你以后想给机器人加“主动推送通知”功能时，就得自己写一段代码完成 token 管理和消息发送。
4.3 用飞书连接器（飞连）做低代码编排
如果你不想在自己服务里写太多飞书侧的逻辑，或者你只是想在现有飞书流程里快速接一个 HTTP 接口，那可以试试飞书连接器（飞连）这个低代码方案。
这套方案的思路是：在飞书连接器里新建一个自动化流程，触发器选择“收到机器人消息”，动作节点选择“HTTP 请求”，把用户发来的消息内容作为请求体 POST 到 Clawdbot 的 /api/chat 接口。Clawdbot 返回结果后，连接器再把响应内容通过“发送消息”节点回复到飞书会话里。
这样做的好处是飞书消息的接收和发送全部由飞书连接器托管，你只需要维护 Clawdbot 服务本身。缺点也很明显：飞书连接器对超时、重试、复杂逻辑的处理能力偏弱，如果 Clawdbot 处理一个任务超过飞书连接器节点的超时限制，响应就丢了。所以我的建议是：轻量问答和简单代码生成用飞书连接器够用；但要执行复杂仓库级任务，还是用 4.2 那种自建事件订阅的方式更靠谱。
4.4 群聊 @ 机器人场景配置
单聊场景配置好基本就能用了，但团队内部更常见的使用方式是在群里 @ 机器人。这时候需要额外注意：飞书群聊里的消息事件只有在机器人被 @ 时才会推送，你需要让 Clawdbot 在解析消息时判断 event.message.mentions 里是否包含机器人自己的 open_id，然后提取出 @ 后面的实际内容。
Clawdbot 目前的处理逻辑是：如果事件里带 mentions 信息，它会自动剔除 @ 的文本前缀，只把真正的问题发给 Claude Code。这样用户在群里发“@AI助手 帮我解释一下这段代码的报错”，机器人收到的实际指令就是“帮我解释一下这段代码的报错”，干净利落。
不过测试的时候要注意，飞书对新发布应用的群聊权限有延迟生效的情况。如果你刚把应用发布到团队，立刻在群里 @ 机器人发现没有响应，多半是权限还没同步，等几分钟或者重新进入群聊再试一下。
5. 部署完最容易踩的坑
5.1 事件订阅地址验证一直失败怎么办
第一个高频问题是飞书后台的事件订阅地址验证失败。飞书会向你的回调地址发送一个带 challenge 字段的 POST 请求，你的服务需要在响应里原样返回这个字段。如果验证失败，先检查三件事：
- 地址是否公网可达，可以在服务器本机
curl http://localhost:8787/feishu/webhook看是否返回 200。 - 服务是否绑定了正确的 Host，如果你在服务器上开了防火墙，8787 端口需要放行。
- 如果配置了事件加密，需要确定 Encrypt Key 和 Clawdbot 环境变量里的
FEISHU_EVENT_ENCRYPT_KEY一致，否则解密失败也会导致校验失败。
我遇到的比较隐蔽的问题是：把两个不同的应用环境混在一起了。测试环境的 App Secret 和线上环境搞混，token 换不出来，回调地址验证一直超时。这种低级错误浪费了我半个多小时，后来把 .env 文件重新对了一遍才发现。
5.2 机器人能收到消息但不回复
如果你确认飞书事件已经推送过来了，但机器人就是不回复，绝大多数问题出在 Clawdbot 这一侧。
先看 Clawdbot 的日志。如果日志里显示收到了请求但调用 Anthropic API 超时，那十有八九是服务器到外部网络的连通性或者代理配置问题。如果日志里压根没有收到飞书推送，那问题出在事件订阅配置上，回过去看 4.1 节的内容。
还有一种情况是：飞书推送成功了，Clawdbot 也处理成功了，但回传消息时没有拿到 token。飞书的 tenant_access_token 有效期是 2 小时，Clawdbot 一般会自动刷新，但如果你手工改了 App Secret，旧的 token 就失效了，需要重启服务重新获取。
5.3 回复内容过长或者格式变形
Claude Code 生成的代码和解释往往很长，飞书对消息长度有限制，超长消息会发送失败。另外，飞书对 Markdown 的渲染规则跟 GitHub 不完全一致，代码块里的语言标注有时候会被当成纯文本显示。
处理这个问题的最好方式，是让 Clawdbot 在返回内容之前做一次格式化。我自己的做法是：在系统提示词里要求 AI“先给结论，再给代码，代码块使用标准 Markdown”，同时在后端对超过 2000 字的回复做分段处理，切片成多条消息逐条发送。
如果你用的是飞书卡片消息，还支持把长文本折叠，用户体验会好很多。Clawdbot 有些版本支持配置消息为卡片格式，我建议能开就开。
5.4 并发高了之后偶发超时
Clawdbot 默认对请求的处理是串行的，因为单次 Claude Code 任务会占用大量 CPU 和终端资源。如果团队里同时在飞书里发起多个请求，后面排队的请求可能等待时间过长，最终超时。
我在实际使用中做的一个优化，是用 Nginx 给 Clawdbot 加了一个简单的并发缓冲，把超时时间加到 120 秒，同时在 Clawdbot 外层做了一个任务队列，确保同一时间只有一个任务在真正执行。虽然请求还是排队，但至少不会因为 HTTP 连接超时把任务丢掉。
如果你需要真正支撑高并发，可以考虑横向扩容：起多个 Clawdbot 实例，前面挂一个负载均衡，每个实例对应不同的 Anthropic Key，把流量分散到多个 Key 上，避免单 Key 触达速率限制。
5.5 密钥和安全问题的几个细节
安全这块一定要多说两句。Clawdbot 的 API Key 是核心敏感资产，任何情况下都不要把它写在飞书侧的代码、连接器配置或者公开的文档里。飞书后台的权限配置也不要图省事给最高权限，只开通 im:message 相关的最小权限集就好。
另外，如果你的 Clawdbot 服务暴露在公网，建议在 Nginx 层加一个简单的访问令牌校验，比如要求请求头带一个自定义的 X-Clawdbot-Token，飞书连接器转发请求时把这个令牌带上，这样即使别人扫描到你的端口，也没法直接调用你的服务。Clawdbot 本身在飞书事件校验上做了签名验证，但这个校验只对飞书推送的事件生效，/api/chat 这个通用接口如果没有额外的鉴权，等于是裸奔的。这一步千万不要省。
6. 几个让机器人更好用的落地细节
部署只是开始，真正让 Clawdbot 在团队里高频用起来，还需要在体验层面做一些打磨。
第一，给 Clawdbot 约法三章。Claude Code 默认执行任务比较随意，可以在启动参数里挂一个 system prompt，让它回答问题时先给出结论、提供可复制的代码块、不做多余解释。这样团队里其他同事用起来不会觉得 AI 回话冗长。
第二，把回复内容改成卡片。飞书机器人默认的纯文本回复没有折叠能力，代码一长就把整个屏幕刷满了。用飞书卡片可以实现长文折叠、代码独立展示、按钮交互，成本不高但体验提升巨大。Clawdbot 如果支持卡片模板，直接用官方模板改一改字段就行。
第三，做好任务队列和限流。Claude Code 消耗的是 API 额度，如果团队里有人把机器人当成无限计算资源随意刷，月底账单会让你心疼。我在服务端加了一个简单的每日配额，每个 open_id 一天最多发起 50 次任务，超出的直接提示“今日额度已用完”。这个功能实现不难，但对成本控制非常有效。
第四，日志一定要留。Clawdbot 服务跑久了，总会有奇奇怪怪的问题。我习惯把每次请求的 message_id、open_id、耗时、模型名称全部打到日志里，这样出问题的时候能快速定位到具体是哪条消息触发的。
这套部署我从第一次尝试到现在已经稳定跑了几个月，期间除了偶尔的网络抖动和 Key 配额触顶外，基本没有出现不可用的情况。我自己最大的感受是：接入飞书之后，AI 编码能力从“开发者自己的终端工具”变成了“团队共享的基础设施”，这中间跨越的并不只是技术对接，还有使用习惯的转变。如果你也正打算把 Clawdbot 或者其他类似的 AI 能力接到飞书上，这篇文章里提到的链路梳理和排查思路应该能帮你少走不少弯路。