覃龙光如果你和我一样，每天有一大半工作时间泡在飞书里，大概率会冒出过这个念头：能不能让一个机器人直接在聊天框里回复那些翻来覆去被问的问题？我最后的落地选择，是把 Clawdbot 接进了飞书。
Clawdbot 这个名字听起来很具体，其实就是我基于 Claude API 封装的一个机器人服务，消息适配和模型调用完全解耦。换句话说，模型侧的逻辑不用动，你只需要把飞书这个适配器跑通，机器人就能在飞书里收消息、调模型、回消息。这篇不是官方文档的复述版，是我从飞书开放平台建应用、配权限、写回调、部署到服务器、踩完一堆错误码之后整理出的完整实操记录。适合谁看？想在公司内部用飞书机器人接 AI 能力，又不想把数据交给低代码平台的开发或运维同学。
1. 为什么我会把 Clawdbot 接进飞书，而不是再写个小程序
1.1 飞书在企业协作里的位置
飞书的本质是消息中枢。企微、钉钉也是同样的思路，但飞书开放平台在 IM 机器人和多维表格这块的接口文档相对更清晰，对于想快速验证 AI 机器人场景的团队来说，学习成本更低。
我把 Clawdbot 接进飞书，核心原因是：人已经在那里了。同事写周报、查数据、生成会议纪要，顺手在群里 @ 一下机器人就能拿到结果，不用再额外打开一个后台页面，更不用给每个人单独开账号。少一个切换动作，使用率就会高很多，这个道理做内部工具的人都懂。
1.2 Clawdbot 实质上解决的是适配层问题
如果只是想让模型聊天，直接 curl API 就行，根本不值得写一篇文章。真正麻烦的是飞书这边的脏活：事件订阅怎么建、回调怎么验签、消息里的 content 为什么取不到、群聊 @ 机器人和单聊的差异在哪、重复事件怎么幂等。这些乱七八糟的适配问题，才是大部分人对接时卡住的地方。
Clawdbot 的价值就是把这层适配做了统一封装。它自带飞书适配器，也支持后续扩展其他 IM 平台，模型层本身是接的 Claude，但设计上可以替换。团队如果不想重复造轮子，直接在这个框架上补业务逻辑会更省事。
顺带说一句选择成本问题。Coze 这类低代码平台也能接飞书，而且更快，但消息内容和业务数据会经过第三方服务。Clawdbot 是自托管的，模型 API 和飞书之间的链路数据都在自己手里，这对企业内部工具来说通常是一个硬指标，也是我选择这条路的主要原因。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 飞书开放平台准备：从自建应用到机器人权限的完整清单
2.1 创建企业自建应用的完整步骤
第一步是到飞书开放平台的开发者后台，创建一个企业自建应用。这一步本身不复杂，填名称、描述、上传图标，真正容易踩坑的是后面几个环节。
应用创建完成后，先别急着写代码，你要在应用详情页做三件事：
- 在“应用能力”里开启机器人能力。这一步很多人会漏掉，不开启的话，后面所有消息接口都会报错，而且报错信息可能让你完全摸不着头脑。
- 在“权限管理”里申请消息相关权限。接收消息一般需要
im:message.group_at_msg（群聊中@机器人接收消息）和im:message.p2p_msg（单聊接收消息），发送消息则需要im:message:send_as_bot。不同版本开放平台里权限名称可能略有差异，以你当前控制台显示的为准。 - 创建版本并发布。企业自建应用同样需要走发布流程，发布后要管理员审核通过。很多新手在本地调试时发现权限不生效，折腾半天，结果应用压根还没发布，这是最常见的低级坑。
应用创建和发布完成后，去“凭证与基础信息”页面拿到 App ID 和 App Secret，再去“事件订阅”页面拿到 Encrypt Key 和 Verification Token。这四样东西就是 Clawdbot 和飞书对话的钥匙，后面配置都要用。
2.2 事件订阅：长连接模式比回调地址更省心
飞书的事件订阅有两种接收方式，选错会直接影响你本地开发的体验。
传统方式是填一个 Request URL，也就是回调地址。飞书服务器会把事件 POST 到这个地址。问题在于，你的服务必须有一个公网可达的 HTTPS 地址，本地开发时非常不方便，要么部署到测试服务器，要么想办法做网络穿透，这本身就增加了安全和合规风险。
新版飞书开放平台支持“使用长连接接收事件”，也就是 WebSocket 模式。飞书 SDK 主动和飞书服务器建立长连接，然后事件通过这个连接推下来。你的服务不需要公网入口，本地直接就能收发消息，联调体验好了不止一个数量级。Clawdbot 的飞书适配器支持这种模式，我强烈建议你本地开发阶段先用它。
无论哪种模式，事件订阅里都要选 im.message.receive_v1 这个事件，这是接收消息的核心事件。群聊场景下，还需要在机器人配置里设置可用范围，把测试群加进去，否则群里 @ 机器人，对方理都不理你。
3. 把 Clawdbot 跑在本机：配置文件与启动方式逐项拆解
3.1 环境准备：Ubuntu 下的安装细节
我这边 Clawdbot 以 Python 3.10+ 运行，依赖安装很常规，但有几个细节需要提醒。
如果你在 Ubuntu 上搭环境，先用 python -m venv .venv 建虚拟环境，然后 source .venv/bin/activate。接着安装 Clawdbot 和飞书适配器：
bash复制pip install clawdbot[feishu]
如果安装过程报 setuptools 相关错误，先升级：
bash复制pip install --upgrade setuptools wheel
另外，测试机器人前最好在电脑上装一个飞书客户端。不少人会搜“ubuntu 中怎么下载飞书”，这里说下我的做法：去飞书官网下载页选 Linux deb 包，然后：
bash复制sudo dpkg -i feishu_xxx.deb
如果提示依赖缺失，执行 sudo apt-get install -f 修复。Windows 用户安装时想改路径到 D 盘，在安装向导里自定义安装目录即可，这不影响开发，只是测试客户端而已。
3.2 配置文件逐行拆解
Clawdbot 的配置集中在 clawdbot.yaml 里，我贴一个可用的最小配置：
yaml复制bot:
name: "clawdbot"
model:
provider: anthropic
name: claude-sonnet-4-20250514
temperature: 0.3
max_tokens: 4096
memory:
type: sqlite
path: ./data/memory.db
adapter:
type: feishu
app_id: "cli_xxxxxxxx"
app_secret: "${FEISHU_APP_SECRET}"
encrypt_key: ""
verification_token: ""
event_mode: websocket
webhook_path: "/clawdbot/callback"
几个关键字段说下：
app_secret强烈建议通过环境变量引用，不要直接写死在配置文件里，更不要提交到 git 仓库。我上面的写法用的是${FEISHU_APP_SECRET}占位符，实际运行时读取环境变量。event_mode有两个值：websocket和webhook。本地联调用 websocket，部署到服务器上如果想走统一入口，再切到 webhook。encrypt_key和verification_token是否要填，取决于你飞书应用的事件订阅里是否开启了加密。如果 open API 那边配置了 Encrypt Key，这边必须填相同值，否则事件解密会失败。memory默认是 sqlite，用来做会话上下文记忆。第一次跑通可以先不关注，进阶玩法里我会说到怎么把它替换成飞书多维表格。
配置写好后，启动服务只需一条命令：
bash复制clawdbot run -c clawdbot.yaml
看到输出里出现类似 feishu adapter started 的日志，就说明机器人已经连上飞书了。这时候去飞书里给机器人发一句“ping”，能收到“pong”就说明最基础的通路已经通了。
4. 打通飞书到 Clawdbot 的消息通道：长连接、回调与服务器部署
4.1 回调地址验证失败，问题多半出在这几处
如果你在生产环境选的是 webhook 模式，飞书开放平台里填 Request URL 时，会立刻向这个地址发一个 url_verification 的验证请求。很多人卡在这一步，验证失败的原因我梳理一下。
最容易犯的错误是服务监听在 127.0.0.1 上。本地自测没问题，但飞书服务器访问不到，因为它在公网，解析到的是你服务器的公网 IP，而你的服务只监听了回环地址。解决办法是让 Clawdbot 监听 0.0.0.0。
第二个坑是代码没有正确返回 challenge。飞书要求你在收到验证请求时，把请求体里的 challenge 字段原样返回。我用 Flask 写过一个极简回调：
python复制from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route("/clawdbot/callback", methods=["POST"])
def callback():
data = request.get_json()
if data.get("type") == "url_verification":
return jsonify({"challenge": data["challenge"]})
return jsonify({"code": 0})
注意，如果你在飞书控制台开启了 Encrypt Key，那么这个 challenge 本身也是加密的，你需要先解密才能看到原始字段。Clawdbot 封装了这层逻辑，但如果你是自己实现回调，一定要先处理解密，再做 URL 验签。
第三个坑是安全组和防火墙没放行端口。云服务器控制台里的安全组，以及服务器本机的 ufw/iptables，都要放行 Clawdbot 监听的那个端口。不放心的话，可以先在服务器上 curl localhost:端口 确认服务正常，再从外部访问试试。
第四个坑是 HTTPS。飞书回调地址要求 HTTPS，如果你用自签名证书，验证基本必挂。生产环境我建议别让 Clawdbot 直接暴露 TLS，而是让 Nginx 负责 HTTPS 证书终止，再反向代理到本地端口。
4.2 生产部署：systemd + Nginx 的稳妥组合
本地跑通之后，部署到服务器上遵循“进程托管 + 反向代理”这套组合最稳。
Clawdbot 直接用 systemd 托管，写一个 service 文件：
ini复制[Unit]
Description=Clawdbot Feishu Adapter
After=network.target
[Service]
User=www-data
WorkingDirectory=/opt/clawdbot
EnvironmentFile=/opt/clawdbot/.env
ExecStart=/opt/clawdbot/.venv/bin/clawdbot run -c /opt/clawdbot/clawdbot.yaml
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.target
EnvironmentFile 用来加载环境变量，这样密钥就不会出现在 service 文件里。
Nginx 这边，核心需求是 HTTPS 终止和反向代理：
nginx复制server {
listen 443 ssl;
server_name bot.example.com;
ssl_certificate /etc/nginx/ssl/bot_example_com.pem;
ssl_certificate_key /etc/nginx/ssl/bot_example_com.key;
location /clawdbot/callback {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
这里我会额外做一层来源 IP 白名单。飞书回调的 IP 段是固定的，在官网可以查到。把它们写进 Nginx 的 allow/deny 规则里，能挡住大量无效请求，避免事件接口被刷。
有人问，既然飞书支持长连接，为什么生产环境还要走 webhook？我的理由是：长连接模式适合本地开发和轻量部署，但 webhook 模式可以统一走 Nginx 入口，方便做访问日志、限流、安全策略，也方便和公司已有的监控体系对接。两者各有适用场景，不是非得二选一。
5. 实际收发消息时的数据格式与错误码 2700002 复盘
5.1 消息内容取不到字段，十有八九是因为 content 是字符串
飞书事件回调里，消息数据是嵌套在 event.message 对象里的。代码如下：
json复制{
"sender": {
"sender_id": {
"open_id": "ou_xxx"
},
"sender_type": "user"
},
"message": {
"chat_id": "oc_xxx",
"message_type": "text",
"content": "{\"text\":\"hello\"}"
},
"event_type": "im.message.receive_v1"
}
注意 content 字段的类型是字符串，不是对象。新手第一次处理时，很容易直接写 data["event"]["message"]["content"]["text"]，结果拿到 None，然后开始怀疑人生。
正确的做法是先解析：
python复制import json
content = event["message"]["content"]
content_dict = json.loads(content)
text = content_dict.get("text", "")
如果是群聊 @ 机器人，text 里会夹带类似 @_user_1 这种占位符。直接扔给模型的话，模型会看到一串莫名其妙的字符。我习惯在接入模型前把这类占位符去掉，并用正则处理一下其他可能出现的昵称标记。
单聊和群聊的差异也要注意。单聊时用户直接给机器人发消息，事件照常推送；群聊时通常必须 @ 机器人，机器人才能收到消息。event.message.chat_type 可以帮你区分是 p2p 还是 group，在群聊里如果要做多人会话隔离，这个字段很有用。
回复消息时，飞书 IM 接口的入参格式是：
python复制feishu_client.send_text(chat_id, answer)
内部实现调用 im/v1/messages 接口，receive_id_type 用 chat_id，content 同样是一个 JSON 字符串。这里要格外小心，content 得先 json.dumps 成字符串，而不是直接传字典。
5.2 错误码 2700002：一次典型的参数格式排查
上线后收到反馈，机器人偶尔回消息失败，日志里打印出飞书返回的错误码 2700002。
这个错误码在各个版本的飞书开放平台里，文档标注不完全一致，我们项目遇到时，定位出来的核心原因是参数格式不对。飞书接口要求的 content 是字符串，而我在某个封装的发送函数里，把已经 json.dumps 后的字符串又包了一层，导致双重转义。飞书服务端解析失败，返回 2700002。
我当时排查的链路是这样的，你可以照着走一遍：
- 先把报错日志里的
request_id记下来。后面如果要提工单，这是必备信息。 - 打开飞书开放平台的控制台，用 API 调试器重放同样的参数。如果调试器能通过，说明参数本身没问题，问题出在你自己代码的请求封装。
- 如果调试器也报同样的错误，重点检查
content是否被二次序列化。你可以在本地打印一下最终发出去的请求体，肉眼确认content是不是变成了"\"{\\\"text\\\":\\\"hello\\\"}\""这种鬼样子。 - 如果参数没问题，再检查 App ID 和 App Secret 是否匹配当前应用，以及机器人是否在可用范围内。
我最后修复的方式，是在发送层统一约束：
python复制def send_text(chat_id, text):
body = {
"receive_id": chat_id,
"msg_type": "text",
"content": json.dumps({"text": text}, ensure_ascii=False)
}
resp = feishu_client.post("/open-apis/im/v1/messages", params={"receive_id_type": "chat_id"}, json=body)
resp.raise_for_status()
一句话总结：凡是往飞书接口传的 content，统一走 json.dumps 转字符串，且只转一次。这个意识能帮你避开 90% 的奇怪错误码。
5.3 重复事件投递：不做幂等，模型会被重复调用
飞书的事件推送是至少一次的语义，网络抖动或服务端重试时，同一事件可能被推送多次。如果你没有做去重，用户发一句话，机器人可能调用两次模型，既浪费 token，又会造成重复回复。
我的做法是在 Clawdbot 入口处维护一个 event_id 去重表，用 Redis 或者 sqlite 存最近两小时的 event_id。收到事件先查表，存在就跳过，不存在就处理并写入。
python复制if dedup_store.exists(event_id):
return {"code": 0}
dedup_store.save(event_id, expire=7200)
handle_message(event)
这个细节看起来小，但在真实生产环境里特别重要。整个链路本来就涉及事件回调、模型推理、消息推送，任何一个环节重试，都可能被放大成一次明显的用户可感知故障。
6. 进阶玩法：多维表格记忆库、监控告警联动
6.1 用飞书多维表格当 Clawdbot 的记忆层
Clawdbot 默认的记忆是 sqlite，项目初期够用，但同事经常问“机器人到底记住了什么”，我总不能让他们去查数据库。后来我把记忆层换成了飞书多维表格。
多维表格的优势在于，业务同学早上打开飞书就能直接看到机器人存的上下文，还能手动改某条记录，相当于给 AI 机器人一个全员可编辑的记忆库。实现思路是写一个 memory adapter，在 Clawdbot 里把原有 sqlite 读写替换成多维表格 API 调用。
核心操作是调多维表格的记录接口：
python复制import requests
def save_record(app_token, table_id, fields):
url = f"https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records"
resp = requests.post(url, json={"fields": fields}, headers={
"Authorization": f"Bearer {user_access_token}"
})
resp.raise_for_status()
这里有个坑：多维表格的 text 类型字段有长度限制，长文本建议提前分块，或者把详细内容转到附件里，表里只存摘要。另一个坑是字段类型必须和表结构一致，比如 number 字段你传了字符串，接口会直接拒绝。我当时就是在这上面浪费了小半天。
用多维表格做记忆层后，Clawdbot 的对话逻辑可以扩展成先查表、再调模型。如果历史记录里有相关话题，就把旧摘要塞进 prompt 里，模型回答会更连贯。这个改动比想象中简单，却能让机器人显得“有记性”。
6.2 把 uptime kuma 的告警接进来，让飞书群收到的不只是“xxx is down”
监控工具 uptime kuma 支持 Webhook 通知，我之前一直把告警推到飞书群，但群里只收到一句“xxx is down”，没有上下文，也没人第一时间知道影响范围。
后来我加了一个 Clawdbot 的 /flows/uptime 端点，让 uptime kuma 的 Webhook 打到这个地址。Clawdbot 收到告警后，先把监控名称、故障时长、目标地址这些信息整理一下，再调用模型生成一段包含可能原因和排查建议的分析，最后推送到飞书群。
实际效果挺好。有一次数据库慢查询导致接口超时，kuma 触发告警，Clawdbot 根据监控名称和时长，直接在群里给出了“先看连接池是否打满，再看慢查询日志”的初步判断。虽然不能替代人，但团队响应时间明显缩短了。
这个思路也顺带回应了一个对比：有人觉得 Coze 这类低代码平台接飞书更快。确实快，但私有化部署、模型可换、和内部实时监控深度耦合这些需求，低代码平台很难满足。Clawdbot 这类自托管方案，胜在你能控制整条链路。
7. 最后给你留的检查清单
文章最后分享几个我自己的习惯，不是标准答案，但能帮你少走弯路。
上线前先逐项自查这三件事。第一，机器人可用范围是否包含测试群，没加入范围的话，群里怎么 @ 都不会有响应。第二，事件订阅是否正确选择了 im.message.receive_v1，并且日志里能看到飞书推来的原始事件，哪怕内容是空的，也至少证明链路是通的。第三，发送消息时 content 是否是字符串，以及 event_id 是否做了幂等去重，这两点我在生产环境踩过的坑最重。
另外一个小习惯：每次改完配置，先在测试群发一句“ping”，确认机器人回“pong”，再进行下一步。很多对接问题其实都出在配置没生效或网络不通上，这个最简单的探测动作，能帮你把无效沟通降到最低。Clawdbot 接飞书这件事，本质上就是“飞书消息 → 模型服务 → 飞书消息”的闭环，只要每一步的输入输出格式都严格对上，剩下的都是细节问题。