把nanoMuse接进飞书、钉钉、企业微信与Telegram:让个人AI Agent住进你的聊天软件
把nanoMuse接进飞书、钉钉、企业微信与Telegram:让个人AI Agent住进你的聊天软件
nanoMuse 是一个开源的个人 AI Agent(personal agent):它会做事、记得你、在应用关闭后继续工作,并且做无法撤销的事之前一定会先问你。它的「聊天入口」功能,可以把这个 Agent 直接接进你每天都在用的聊天软件——飞书(Lark)、钉钉、企业微信、Telegram:手机上给机器人发一句话,回答你的就是和 App 里同一个 Muse。
为什么要把 AI Agent 放进聊天软件
传统用法是打开专门的 App 才能和 Agent 说话。而接进聊天软件后:
- 零门槛:不用记入口、不用开 App,飞书钉钉里@一下就行;
- 同一个人格:每个聊天对应一个独立对话,记忆、目标、技能、审批(Sentinel)全部一致;
- 无需公网地址:四个渠道全部走厂商的长连接(Telegram 为长轮询),机器人从你内网主动连出去——放在路由器后面的台式机、笔记本上就能跑,不开端口、不暴露 URL。
💡 实现见 nanomuse/channels/manager.py,各厂商连接分别由 feishu.py、dingtalk.py、wecom.py、telegram.py 完成。
快速安装:一行命令装上所有渠道 SDK
渠道连接依赖各家官方 SDK,以可选依赖形式提供:
pip install 'nanomuse[feishu]' # lark-oapi
pip install 'nanomuse[dingtalk]' # dingtalk-stream
pip install 'nanomuse[wecom]' # wecom-aibot-sdk-python
pip install 'nanomuse[channels]' # 以上三者全装;Telegram 无需额外依赖
Docker 镜像已自带全部 SDK。若未安装,应用会直接显示对应安装命令,不会把开关打开。
在哪里找到「聊天入口」设置
四个入口任选其一:
| 入口 | 说明 |
|---|---|
| 📱 应用 | 设置 → 「聊天入口」(Chat apps):每个聊天软件一张卡片,含开关、凭据、配对名单、「推送到这里」开关、「发一条测试消息」按钮 |
| ⌨️ 终端 | nanomuse channels status / pending / approve <code> / login feishu / test <name> |
| 🔌 API | GET /api/channels、POST /api/channels/<name>/test 等 |
| 📄 config.toml | 手工搭的服务器可写 [channels.<name>] 表,如 bot_token = "${TELEGRAM_BOT_TOKEN}" |
在应用里填写的密钥会存入保险库(vault),设置文件里只留占位符({{vault:CHANNEL_TELEGRAM_BOT_TOKEN}}),之后永不回显;密钥字段只告诉你「是否已填」。
逐个接入:四款聊天软件的最小步骤
飞书 / Lark:扫码 10 秒创建机器人
飞书最省事,支持「扫码创建」:
- 在应用里按 扫码创建机器人(或终端运行
nanomuse channels login feishu,国际版 Lark 加--lark); - 用飞书扫码、确认,App ID 与 Secret 自动保存,渠道随即开启。
这是飞书官方为个人智能体提供的扫码建应用流程,创建出来的应用已带机器人能力和长连接事件。想手动配置的话:到飞书开放平台创建企业自建应用 → 添加「机器人」能力 → 权限加 im:message、im:resource 等 → 事件与回调均选长连接 → 复制 App ID / App Secret → 发版即可。回复是带 markdown 的可交互卡片,流式生成时约每秒原地刷新,你的消息上出现 👍 表示 Muse 正在处理。
钉钉:Stream 模式,免回调地址
- 在钉钉开放平台创建企业内部应用 → 添加机器人能力;
- 消息接收模式选 Stream 模式(不需要回调 URL);
- 复制 Client ID(AppKey) 与 Client Secret(AppSecret) 填入应用;
- 权限加上机器人发消息的
qyapi_robot_sendmsg(这样「推送到这里」的聊天无需回复消息也能写入); - 发布版本,把机器人加进群或在通讯录找到它。
⚠️ 钉钉消息不支持编辑,所以回复在写完后一次性发出;群里机器人只听得到 @ 它的消息。
企业微信:长连接 API 模式
企业微信管理后台 →「安全与管理」→智能机器人:
- 创建机器人,选 API 模式,连接方式选长连接;
- 复制 Bot ID 与 Secret 填入应用;
- 把机器人加进它该监听的聊天。
socket 主机 openws.work.weixin.qq.com 已被运行时自动加入 NO_PROXY(公司 HTTPS 代理通常带不动它)。回复经同一 socket 流式返回,主动推送消息为 markdown。
Telegram:@BotFather 三步开工
- 在 Telegram 找 @BotFather,发送
/newbot,把生成的 token 复制到应用里; - 私聊立即可用;群聊把机器人拉进群即可(默认 Group Privacy 下只听 @ 与回复,正好对应 mention 策略);
- 电脑连不上
api.telegram.org时,在应用里填 代理(socks5://…或http://…)。
回复先发出、再随流式生成原地编辑(超 4096 字符自动拆分),审批为两个内联按钮。
配对机制:谁有资格和机器人说话
任何人都能找到机器人,但 Muse 只回答你放进来的人:
- 🎫 配对码:陌生人的第一条私聊只会收到一个六位配对码(10 分钟有效),消息不会到达 Muse。在 设置 → 聊天入口 里批准,或运行
nanomuse channels approve <code>,对方即完成配对; - ⭐ 免配对名单(
allow_from):直接放行特定用户 id(单独一个*放行所有人,仅适合无人可寻的机器人); - 👥 群聊:群里不发配对码,陌生人被静默忽略;已配对的人被 @ 时才回答(
group_policy = "mention"),也可设"open"每条都回。群本身是独立对话,每行消息都带发送者名字; - 🗑️ 移除:在应用里移除配对后,对方下一条消息会重新收到配对码。
配对数据存在数据目录的 pairing.json 中,不在 Agent 的工作区内——智能体自己的文件工具改不了「谁能和它说话」。
聊天里的体验:流式回复、工具状态与审批
每个聊天就是智能体的一个对话(id 形如 channel-<app>-<chat id>),标题如「飞书 · Ann」,与 App 内打字走同一个入口。运行进行时:
- 文字随模型输出流式写进回复(厂商允许编辑的地方);
- 正在跑的工具显示为一行斜体短句(「正在搜索网页」「正在运行命令」);
- 哨兵(Sentinel)要的审批会直接推到聊天里:飞书和 Telegram 是「允许 / 拒绝」按钮卡片,钉钉和企业微信是让你回一个词的消息(
allow、允许、同意为放行一次;deny、拒绝、不行为拒绝)——和在 App 里按卡片完全等效; - 运行产生的文件在结束时自动发出;Muse 提出的问题送到聊天里,你的下一行就是回答;
- 附件(照片、文件、语音)保存在工作区
attachments/下并随消息处理。
聊天中的审批是一次性决定(理由标注「来自飞书」等),不会因此记住任何长期授权。
「推送到这里」:让 Muse 主动找你
给已配对的聊天打开 Deliver here 开关,它还会收到 Muse 无人吩咐也会做的事——与手机 App 通知同一批事件:
- 后台任务结束时的最后一句话;
- 等待中的审批(可以直接在聊天里回答);
- 需要你拍板的问题。
一个 Muse 可同时推送到多个聊天,每个聊天自行开关。脚本或提醒里还可以用 POST /api/channels/deliver {"text": …} 给所有订阅聊天发一行字。
安全设计:密钥不出门,连接只出门
- 🔐 密钥进保险库,API 永不回传;日志只含厂商错误原文,不含凭据;
- 🚪 只有已配对/放行名单内的人能触达 Muse;审批卡片按钮仅对已配对者生效;
- 📂 渠道数据(
<data_dir>/channels/)在数据目录,Agent 够不着; - 🌐 所有连接均为出站长连接:不开端口、无公网地址。
排错速查表
| 你看到的 | 怎么处理 |
|---|---|
| 未安装 | 运行提示的 pip install 'nanomuse[feishu]' 等,再把开关打开 |
| 还缺设置 | 卡片会写明缺哪一项必填字段 |
| Error + 厂商原话 | 凭据被拒或连不上厂商;改好后关开关再开,或重按「保存」 |
| 机器人不回答群里消息 | 群策略是 mention 而未 @ 它;或发送者未配对(群里不发码) |
| 飞书有回复但没有卡片按钮 | 缺 im:message.group_at_msg:readonly / im:resource,或 card.action.trigger 未挂到长连接 |
| 钉钉连上但收不到消息 | 接收模式不是 Stream,或版本未发布 |
Telegram: Conflict: terminated by other getUpdates request |
同一 token 在两处轮询,只保留一处 |
更多问题对照表见官方文档 docs/channels.md 与中文版 docs/zh/channels.md,终端命令实现见 nanomuse/channels/cli.py,配对与设置存储逻辑在 nanomuse/channels/store.py。
小结
从安装 SDK 到机器人上线,飞书扫码最快只要几十秒;钉钉、企业微信、Telegram 也各在十步之内。接完之后,你的个人 AI Agent 就真正「住进」了聊天软件:私聊、群聊、审批、主动推送,全都是同一个 Muse。


