多渠道接入：拆 hermes gateway 与 openclaw SOUL.md，把 Agent 接进微信飞书

你大概率经历过这一幕：辛辛苦苦写了个挺像样的 Agent，能查日志、能跑脚本、能跨会话记住你——结果它只活在你自己电脑的那个黑乎乎的终端里。你想给同事用，得教他们装 Python、配 key、敲命令。你妈想用？没门。一个再聪明的 Agent，只要它不在用户已经打开着的那个 App 里，就约等于没人用。

这一节解决的就是最后这一关：把 Agent 从"本地终端"接到用户天天在用的渠道——微信、飞书、Telegram、Slack。我们拆两种成熟的开箱方案：hermes 的 单进程多渠道 gateway，和 openclaw 的 SOUL.md 配置驱动。看懂它俩的设计，你就能判断自己该自建还是直接用现成的。

这篇适合谁：已经能写出一个能跑的 Agent，卡在"怎么让它出现在别人手机里"的人。读完你会有一份能照着改的 SOUL.md，和一张接渠道的选型判断表。

---

钩子：渠道接入到底难在哪

你可能觉得"接个微信不就是调个发消息 API 嘛"。真上手才发现，难的不是发一条消息，是下面这一堆琐碎但缺一不可的事：

• 每个渠道协议都不一样：Telegram 是长轮询/Webhook，Slack 是 Events API + 签名校验，微信飞书各有各的回调格式和加解密。
• 得长期在线收消息：用户随时发，你得有个常驻进程在那儿接，断了就丢消息。
• 会话状态要对上：同一个人在微信发的和在飞书发的，是不是同一段对话？谁的消息归谁？
• 富媒体：用户发来一条语音、一张图，你的 Agent 得能"听懂""看见"。

自己从零接，每加一个渠道就要把上面这套重写一遍。所以才有了 hermes、openclaw 这类把"渠道接入"这层单独抽出来的方案——你只管写 Agent 的脑子，渠道这层交给它。

---

最小可用一：hermes gateway —— 单进程统一管多渠道

hermes-agent（NousResearch 出品）的渠道接入是一个 gateway（网关）：一个进程，同时挂住多个渠道。

按官方说明，这个 gateway 一套就能接 Telegram、Discord、Slack、WhatsApp、Signal，微信走一个叫 HermesClaw 的桥接。所有渠道的消息进到同一个 gateway，再交给同一个 Agent 大脑处理。它的两个关键特性值得你记住：

• 语音转录：用户发语音，gateway 先转成文字再喂给 Agent。所以你的 Agent 逻辑根本不用关心"这条是文字还是语音"——到它手里都已经是文字了。
• 跨渠道会话连续：你早上在 Telegram 跟它聊了一半，下午在 Slack 接着说，它认得这是同一段对话、同一个你。这背后正是前面几节讲的那套记忆在撑——常驻的人设和用户画像不随渠道变（这块的机制见 文件即记忆：hermes 的 SOUL/MEMORY/USER）。

用心智模型概括 hermes 的设计：

        Telegram ─┐
        Discord  ─┤
        Slack    ─┼──►  一个 gateway 进程  ──►  同一个 Agent 大脑
        WhatsApp ─┤      (统一收发 + 语音转录 +        (带跨渠道记忆)
        Signal   ─┤       会话归并)
   微信(HermesClaw桥)─┘

好处：你只维护一个进程、一套 Agent 逻辑，渠道是"插上去"的。坏处也明显：它是一个有主见的整体方案，你得接受它的架构和约定，定制空间不如自己拼。具体接哪个渠道要配哪些字段、token 放哪，以 hermes 官方文档为准——这类配置项变动较勤，不背。

---

最小可用二：openclaw —— 写一份 SOUL.md 就上线

openclaw 走的是另一条路：配置驱动。它的核心理念是——你写一份 SOUL.md，跑一条命令，Agent 就上线了。

这里要分清一件容易混的事：hermes 里的 SOUL.md 是"人设"（怎么说话）；openclaw 里的 SOUL.md 被用成了整个 Agent 的配置入口——既描述它是谁、怎么说话，也声明它接哪些渠道、用什么模型。同名不同用，别搞混。

openclaw 的另外几个定位特点：

• 本地优先：默认在你自己机器上跑，数据不用先过别人家的云。
• 多渠道：和 hermes 一样支持把 Agent 接到多个聊天渠道。
• 可挂 coding agent：它能把 Claude Code 或 Codex 挂上来当"会写代码的那只手"——也就是说你可以在微信里发一句"帮我把这个 bug 修了"，背后是 Claude Code 在干活。（Codex 暂无独立工具页，想先补基础看 Codex 教程。）

它和 hermes 的根本差别：hermes 是"一个内置了记忆/子代理/网关的完整 Agent 产品"，openclaw 更像"一个把 Agent 拼装+上线的脚手架，脑子可以是别人的"。

---

原理：一份 SOUL.md 长什么样

下面给一份 示意性 的 SOUL.md，帮你建立"配置驱动"的直觉。具体字段名、层级、必填项以 openclaw 官方文档为准——下面只是让你看清"一份配置大概要交代哪几件事"，别照抄当真。openclaw 的 SOUL.md 通常是 YAML frontmatter（结构化配置）+ markdown 正文（人设描述） 这种组合形态：

---
# —— 以下字段名仅为示意，真实字段以 openclaw 官方文档为准 ——
name: 小助
model: claude-...          # 用哪个模型当大脑（具体值以官方为准）
channels:                  # 接哪些渠道
  - type: telegram
    token: ${TELEGRAM_BOT_TOKEN}   # 用环境变量，别把密钥写进文件
  - type: slack
    token: ${SLACK_BOT_TOKEN}
coding_agent: claude-code  # 可选：把 Claude Code 挂上来当写代码的手
memory_dir: ./.soul/       # 记忆/状态落盘位置
---

# 我是谁
我是小助，一个干练、直接的工程助手。
- 先给结论再给理由，不绕弯子。
- 给方案优先给可直接跑的代码，附一句怎么验证。
- 不确定的事直说"不确定"，绝不编参数。

# 我能干什么
- 回答工程问题、查资料、跑小脚本。
- 收到"修一下这个 bug"这类请求时，转交给挂着的 coding agent 执行。

看这份配置你应该能体会到配置驱动的爽点：人设、模型、渠道、要不要挂 coding agent，全在一个文件里声明清楚，剩下的启动、连渠道、收发消息都交给框架。这正是 openclaw "写配置就上线"的含义。

SOUL.md 字段速查（示意）

你想交代的事	大致对应的字段	说明
它是谁、怎么说话	markdown 正文 + name	人设，决定语气和边界
用哪个模型	model	大脑用谁，值以官方为准
接哪些渠道	channels[]	一个数组，每项一个渠道 + 它的 token
密钥怎么放	${ENV_VAR}	走环境变量，绝不硬编码进文件
要不要会写代码	coding_agent	挂 Claude Code / Codex 当执行手
记忆存哪	memory_dir	跨会话状态落盘位置

---

进阶：接一个渠道的最小思路

不管你用 hermes、openclaw，还是哪天自己接，"接一个聊天渠道"的骨架其实是固定的四步。把这个心智模型刻进脑子，看任何渠道的文档都不慌：

1. 拿到入口凭证：去渠道的开放平台建一个 bot/应用，拿到 token（或 app id + secret）。
2. 建一条"消息进来"的通道：要么你主动去拉（长轮询，如 Telegram 的 getUpdates），要么渠道回调你（Webhook，如 Slack/飞书，往往还要做签名/加解密校验）。
3. 把渠道消息翻译成 Agent 听得懂的格式：剥掉协议外壳，抽出"谁、说了啥、在哪个会话"，喂给 Agent；语音/图片这类先转成文字/描述。
4. 把 Agent 的回复翻译回渠道格式发出去：调该渠道的发消息 API，按它的格式包好回去。

下面用伪代码把这条链路串一遍——这不是某个具体 SDK 的真实 API，是帮你看清数据怎么流的骨架：

# 渠道接入骨架（伪代码示意，非任何渠道真实 API）
# 真实字段/方法名以你所用渠道与框架的官方文档为准

def on_incoming(raw_event):                      # 第2步：渠道把消息送进来
    verify_signature(raw_event)                  # Webhook 类必做：校验来源真实性

    msg = normalize(raw_event)                   # 第3步：翻译成统一格式
    # msg = {channel, user_id, conversation_id, text}
    if raw_event.is_voice:
        msg["text"] = transcribe(raw_event.audio)  # 语音先转文字（hermes gateway 替你做了这步）

    reply = agent.handle(                         # 交给你的 Agent 大脑
        text=msg["text"],
        conversation_id=msg["conversation_id"],   # 用它把跨渠道会话对上
    )

    send_to_channel(                              # 第4步：按渠道格式发回去
        channel=msg["channel"],
        conversation_id=msg["conversation_id"],
        text=reply,
    )

逐步预期

• 用户在某渠道发"今天服务正常吗"，渠道把原始事件推到 on_incoming。
• normalize 把它削成 {channel:"telegram", user_id:"u1", conversation_id:"c1", text:"今天服务正常吗"}。
• agent.handle 拿着 conversation_id 找到这段对话的上下文，回一句"正常，错误日志里有 3 条超时"。
• send_to_channel 把这句话按 Telegram 的格式发回去，用户在手机上收到。

关键洞察：conversation_id 是跨渠道会话连续的命脉——只要不同渠道的同一段对话能映射到同一个 id，hermes 那种"早上 Telegram、下午 Slack 接着聊"就实现了。用 hermes/openclaw，第 2、3、4 步和语音转录它都替你包了；你自建，就得自己把这四步对每个渠道各写一遍。

---

增量：自建 gateway vs 用 hermes/openclaw 开箱，怎么选

这是这一节真正的分水岭。别一上来就纠结"哪个框架好"，先照下面这张表对号入座：

你的情况	推荐	为什么
想快速验证"Agent 进聊天软件"这件事值不值得做	直接用 hermes/openclaw	一份配置就上线，省掉每个渠道重写四步的活，先把 idea 跑通
只接 1 个渠道、逻辑很简单	自建（直接调那一个渠道 SDK）	就一个渠道，引一个完整框架反而是负担
要接一大把渠道 + 要语音/跨渠道会话	hermes gateway	它的强项正是"单进程统管多渠道 + 语音转录 + 会话连续"，自己造这套很贵
想要"配置即 Agent"、还想把 Claude Code/Codex 当执行手挂上	openclaw	配置驱动 + 可挂 coding agent 正是它的定位
渠道协议有强定制、要深度嵌进自家系统	自建	框架的"有主见"会变成约束，自己拼才自由
团队没人懂渠道协议、只想要个能用的	开箱方案	把最脏最碎的协议层交出去，团队专注 Agent 脑子

一句话口诀：多渠道、要语音、要会话连续 → 用 hermes；想"写配置就上线"还想挂 coding agent → 用 openclaw；就一个渠道、要深定制 → 自建。

---

避坑：国内接微信飞书的现实坑

这块单独拎出来讲，因为国内渠道有一堆境外渠道没有的雷，踩了轻则封号、重则违规。

坑	后果	怎么破
拿个人微信号当 bot 挂机器人	个人号极易被封，微信对自动化收发管控很严，且违反其使用条款	别用个人号做自动应答；要做就走企业微信/微信官方开放能力，接入规则以微信官方为准
用未经授权的第三方"协议库"模拟微信客户端	违反平台条款、随时失效、有合规与法律风险	不碰灰产协议库；只用官方/企业微信提供的合规接口
飞书把 Webhook 当无校验的口子用	被伪造请求打、消息被冒充	飞书回调要做加解密 + 签名校验，配置项以飞书开放平台官方文档为准
把 token / app secret 写进 SOUL.md 提交到 git	密钥泄露，号被盗用	一律走环境变量 ${ENV}，.gitignore 掉密钥文件
拿境外渠道（Telegram 等）当国内主力对外服务	国内用户访问不稳定、有合规风险	对内/技术圈测试可以，对外正式服务优先飞书/企业微信这类境内合规渠道
一套话术全渠道照搬	微信飞书有内容与营销规范，容易触线	对外渠道避免营销式群发，遵守各平台内容规范

底线：境外渠道（Telegram/Slack/Discord）适合自己用和小圈子测试；要在国内对外正式服务，老老实实走企业微信、飞书开放平台这类合规路径，所有接入规则、限额、审核要求以官方为准——这部分变动频繁且涉及合规，绝不靠记忆下结论。

---

动手挑战

1. 挑一个最容易上手的渠道（Telegram 几乎是最快的），用它的官方 bot 接口，把你现有的 Agent 接上去，在手机上跟它对一句话。先体会"Agent 进了我口袋"的感觉。
2. 照着上面的 SOUL.md 示意，给你的 Agent 写一份你自己的配置文件：人设、模型、要接的渠道、密钥用环境变量占位。写完想清楚每一行交代的是哪件事。
3. 进阶：给你的接入骨架补上 conversation_id 映射，模拟"同一个人从渠道 A 发、再从渠道 B 发"，验证 Agent 认得这是同一段对话——这就是跨渠道会话连续的最小实现。

---

小结 · 你现在掌握了什么

• 你想清楚了"Agent 留在本地终端 = 没人用"，渠道接入解决的是让 Agent 出现在用户已经打开的 App 里这一关。
• 你看懂了 hermes gateway 的设计：单进程统管多渠道（Telegram/Discord/Slack/WhatsApp/Signal + 微信 HermesClaw 桥）、语音转录、跨渠道会话连续。
• 你看懂了 openclaw 的配置驱动：写一份 SOUL.md、跑一条命令就上线，本地优先、多渠道、还能挂 Claude Code/Codex 当 coding agent。
• 你拿到了一份可照改的 SOUL.md 字段示意、接渠道的四步最小思路，和"自建 vs 开箱"的选型表。
• 你知道了国内接微信飞书的真实雷区：个人号封号、灰产协议库违规、密钥泄露、合规渠道选型——拿不准的接入规则一律以官方为准。

记住：把 Agent 接进渠道，不是技术炫技，是让它从"你一个人的玩具"变成"别人真的会用的助手"。 渠道这层用现成的 gateway/配置驱动方案接掉，你才能把精力留在真正值钱的地方——Agent 的脑子。

下一步：渠道接上了，往后如果你的编排开始需要显式状态、检查点、复杂分支，再看 什么时候才上 LangGraph。整条路的位置对照 三支柱路线图；想顺着阶梯走就看 AI Agent 智能体阶梯 的 L5 后段。前置没补的，先看 子代理零上下文成本和 AI Agent 是什么。

👉 看看 AI 数字员工落地指南，或了解 数字员工搭建实战课。需要为企业落地方案，欢迎找我们聊 企业服务。