Concepts·live · auto-updated

消息接入 — 把一座蜂群城连上所有 IM

OpenClaw 连上 Telegram,进来的是一个 bot;LocalKin 连上 Telegram,进来的是一座城 —— 130 个专家、隔离的多租户、连着 IoT 边缘的巡查蜂群。

这一层让任何 agent 能跟外界的消息应用双向通信。设计上全 stdlib:输出走 HTTP/SMTP,输入走 HTTP long-poll,没有引入任何 websocket/第三方依赖。

架构:三件套

                    ┌─────────────── 输出侧(agent 主动发)
                    │   send_telegram / send_discord / send_slack
                    │   send_email / send_sms  —— 都是 SKILL.md + python
                    │   一个模子:读 ~/.localkin/env 凭证 → HTTP POST / SMTP
   agent ◄──────────┤
                    │
                    └─────────────── 输入侧(平台消息进来)
                        localkin -telegram-bridge —— 常驻进程
                        long-poll 平台 → 按 soul channels 路由 → /v1/chat
                        → 回复发回平台

   soul 的 channels: 块 —— 声明这个 agent 监听哪个平台/哪个 chat

●输出侧 = send_* skill:agent 要发通知/告警/回复,调一下就行。每个平台一个 skill,但都是同一个模子(HTTP POST 或 SMTP),凭证从 ~/.localkin/env 读,绝不进 argv/日志。
●输入侧 = bridge 进程:像 gateway/world 那样常驻一个轻进程,连平台、收消息、按 soul 配置路由给对应 agent、把回复发回去。
●channels: 块:在 soul frontmatter 里声明监听关系,全配置化。

接入矩阵

平台	输出(发)	输入(收)	接入难度
Telegram	✅ `send_telegram`	✅ `-telegram-bridge`(long-poll,无需公网)	⭐ 最简单,双向已通
Discord	✅ `send_discord`(Incoming Webhook)	⚠️ 需 gateway websocket 或公网 Interactions	输出 ⭐ / 输入 ⭐⭐⭐
Slack	✅ `send_slack`(Incoming Webhook)	⚠️ 需 Socket Mode 或公网 Events API	输出 ⭐ / 输入 ⭐⭐⭐
Email	✅ `send_email`(SMTP)	⚠️ 需 IMAP poll(后续)	输出 ⭐
SMS	✅ `send_sms`(Twilio)	⚠️ 需 Twilio 公网 webhook	输出 ⭐
WhatsApp	🔜 Twilio/Meta(要资质审核)	🔜 公网 webhook	⭐⭐⭐⭐ 见下方说明

为什么 Telegram 是首选双向通道:它的 Bot API 支持 long-poll(getUpdates), 一个进程拉就行,不需要公网 endpoint、不需要 websocket —— 唯一一个零基建的优雅双向。其它平台的输入要么要 websocket(违反 stdlib-only),要么要把一个公网 webhook endpoint 暴露给平台(你有 cloudflared,可做,但多一道配置)。所以现阶段:Telegram 管双向对话,其余平台管输出通知,这覆盖 80% 的真实场景。

凭证配置(`~/.localkin/env` 一览)

每个 skill 只在用到时才要对应凭证,缺了就优雅报错、绝不空发:

# Telegram —— 找 @BotFather /newbot 拿 token
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."

# Discord —— 频道设置 → 整合 → Webhooks → 复制 URL
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/.../..."

# Slack —— api.slack.com/apps → Incoming Webhooks → 复制 URL
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/.../.../..."

# Email —— Gmail 用 App Password(非登录密码)
export SMTP_HOST="smtp.gmail.com"
export SMTP_PORT="587"
export SMTP_USER="you@gmail.com"
export SMTP_PASS="16-char-app-password"
export SMTP_FROM="you@gmail.com"

# SMS —— twilio.com 拿号 + SID + Token
export TWILIO_ACCOUNT_SID="ACxxxx"
export TWILIO_AUTH_TOKEN="xxxx"
export TWILIO_FROM="+1xxxxxxxxxx"

agent 怎么用

1. 让 agent 能发 —— 在 soul 的 skills.enable 加上要用的 send skill:

skills:
  enable: ["send_telegram", "send_discord", "send_email", "knowledge_search"]

之后 agent 在对话/自治中需要发通知时,直接调用即可。

2. 让 agent 能收(Telegram) —— 在 soul 加 channels 块:

channels:
  telegram:
    chat_id: "*"                       # "*" = 接所有 chat,或具体 id
    endpoint: "http://127.0.0.1:8019"  # 这个 agent 的 base url
    # auth_token 可选,默认回退到 server.auth_token,再回退 "lk2026"

3. 起 bridge:

localkin -telegram-bridge

它扫所有 soul 的 channels.telegram,建路由表,然后 long-poll。参考实现见 souls/telegram_concierge.soul.md(一个前台客服人设)。

物业场景的完整闭环

租户在 Telegram 发"B栋3楼漏水"
   → bridge 收到 → 路由进隔离的物业蜂群
   → 前台 agent 分类 → 巡查 agent 调 IoT 看现场传感器
   → send_telegram 回租户 "已派单,预计30分钟到场"
   → send_sms 给值班维修 "🚨 B栋3楼漏水,IoT 已确认"
全链路在一台 mini 上闭环,租户之间隐私隔离。

WhatsApp 单独说明

商业价值最高(物业/拉美/东南亚/中东主场),但最讲究:

●别用第三方逆向库(whatsapp-web.js/Baileys):封号风险 = 给客户交付的死刑。
●用 Twilio(BSP)或 Meta Cloud API:官方合规,有 sandbox 可立即 demo。
●难在合规不在技术:Meta Business 验证 + 号码 + 模板审核,要的是营业资质 —— 那是客户(物业公司)自己有的东西,对真实交付反而不是障碍。
●技术上就是 bridge(webhook,走你现成的 cloudflared)+ send_whatsapp skill, 和这套架构一个模子。

扩展一个新平台 = 填一个适配器

输出:照 skills/send_telegram/ 复制一份,改 API 端点和 payload 字段即可。输入:照 cmd/localkin/telegram_bridge.go 的 scan→route→ask→reply 四段,换成目标平台的拉取/接收方式。soul 的 channels 块和路由逻辑完全复用。

← All entries