3. Gateway 架构与渠道接入

这是什么：Gateway（网关） = OpenClaw 的中枢进程，一个实例同时监听所有已配置的聊天渠道，负责会话、路由、工具调用和记忆。渠道（channel） 就是它支持的聊天软件。

为什么用：第 2 章你已经跑起来了 Gateway，但它此刻还只会待在网页控制台里。这一章把它接进 Telegram 等聊天软件——从此你人在外面、用手机发条消息，助手就开工了。

如何用：本章先讲清 Gateway 和渠道的分工，再拿 Telegram（最快，只要一个 bot token）完整走一遍：建 bot → 写配置 → 配对 → 拉进群。

3.1 Gateway：一个进程统管一切

                 ┌──────────────┐
  Telegram ──────►│              │
  Discord  ──────►│   Gateway    │──► 模型 API / 本地模型
  Slack    ──────►│  （一个进程）│──► 工具：命令 / 文件 / 浏览器
  WhatsApp ──────►│              │──► 记忆 + 技能
  iMessage ──────►└──────────────┘
                 ▲      ▲
              CLI   Control UI（浏览器）

三个要点：Gateway 是会话的唯一真相来源（换设备、换渠道，上下文还在）；渠道可以同时开多个，消息按「谁发的、在哪个群」路由到对应 Agent；默认只听本机（bind: "loopback"，端口 18789）——要远程访问走 Tailscale 或反向代理，别把端口直接暴露到公网。

3.2 常驻形态

openclaw gateway install 之后，Gateway 变成一个由系统托管的服务：macOS 上是 LaunchAgent，Linux / WSL2 上是 systemd user service，Windows 上是计划任务（被拒时退回登录启动项）。三种平台都用同一组命令管理：

openclaw gateway status

你会看到（示意）：

service: running (systemd user unit)
pid:     4821
listen:  127.0.0.1:18789
agents:  main

3.3 渠道是怎么插进来的

渠道以插件形式提供，分三类：

类型	例子	怎么装
内置插件	Telegram、WebChat、X/Twitter、A2A	随核心安装，不用管
官方插件	Discord、Slack、WhatsApp、iMessage、Signal、Matrix、Teams、飞书、LINE……	`openclaw plugins install @openclaw/<id>`（id 用 `openclaw plugins search` 查），或在 `openclaw onboard` / `openclaw channels add` 时按需自动安装
外部插件	WeChat、WeCom、Yuanbao 等	第三方维护，照它的文档走

从零装起最快的路子是 Telegram：只要一个 bot token，不用装插件。官方文档原话："Start with Telegram."

3.4 接入第一个渠道：Telegram

第 1 步：找 @BotFather 要 token

在 Telegram 里跟 @BotFather 对话（认准这个 handle），发 /newbot，按提示起名字、选 username，最后拿到一串形如 123456789:AAExxxxxxxxxxxxxxxxxxxxx 的 bot token。这串东西等同于你机器的钥匙，别贴到聊天里。

第 2 步：写进配置

openclaw channels add --channel telegram --token <bot-token>

你会看到（示意）：

Configured channel: telegram (account "default")
  dmPolicy:   pairing
  groups:     requireMention=true
Gateway will hot-reload the new account configuration.

不带参数跑 openclaw channels add，它会列一个渠道清单让你选。

第 3 步：确认通道活着

openclaw channels status --probe

你会看到（示意）：

telegram  default  enabled  probe: ok  bot=my_assistant_bot

Gateway 默认开启 hot reload（热重载），新配置会被正在跑的进程直接吃进去，不用重启。Gateway 没在跑的话先 openclaw gateway start。

第 4 步：配对你自己

给机器人发条消息试试——你不会立刻收到回复，而是拿到一串配对码。批准它：

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

你会看到（示意）：

pending: telegram  sender=987654321  code=7KQ4M2XP  expires in 42m
approved: telegram  sender=987654321  (DM access granted)

配对码是 8 位大写字母数字（不含容易混淆的 0 O 1 I），1 小时后过期，每个渠道账号最多同时挂 3 个待批请求。也可以在 Control UI 的 Settings → Channels → DM access requests 里点批准。

批准 DM 不等于给了它群聊权限——群权限是另一套规则。

第 5 步（可选）：拉进群

机器人默认开 Privacy Mode，只能看到 @ 它或回复它的消息。要让它看到全部群消息：在 BotFather 发 /setprivacy 关掉，然后把机器人移出群再重新拉进去（Telegram 只在重新入群时应用这个设置），或者直接给它管理员权限。

群里还要两样 ID：你的 Telegram user ID（填进 allowFrom / groupAllowFrom）和群 chat ID（填进 groups 的键）。群 chat ID 通常是 -100 开头的负数。不确定就先进群看 openclaw logs --follow，拉进群后发 /whoami@<bot_username>，机器人会把自己的 ID 报给你。

3.5 配对：陌生人先拿到的是验证码

OpenClaw 对「谁能跟助手说话」的默认答案是配对（pairing），这是它最关键的一道防线：

DM 策略	行为	适合谁
`pairing`	陌生人收到一串码，消息不会被处理，等你批准	默认，个人使用
`allowlist`	只有白名单里的人能说话	已配好后收紧
`open`	任何人都能说话（必须同时含 `"*"` 才算真正的公开）	几乎别用
`disabled`	完全关闭该渠道的 DM	纯群聊场景

群聊默认是 groupPolicy: "allowlist"，并且通常要 @ 提及才响应：

{
  channels: {
    telegram: {
      dmPolicy: "pairing",
      allowFrom: ["987654321"],
      groups: { "*": { requireMention: true } },
    },
  },
}

你会看到（示意）：

$ openclaw channels status --probe
telegram  default  enabled  dmPolicy=pairing  requireMention=true  probe: ok

多个渠道想共用同一批信任的人，可以定义 accessGroups（访问组）：在 accessGroups.<name> 里按渠道列出成员，再用 accessGroup:<name> 引用挂到各渠道的 allowFrom 上。

3.6 其他渠道速查

渠道	类型	需要什么	备注
Telegram	内置	bot token	最快，官方首推
Discord	官方插件	bot token + applicationId	需开 privileged intents
Slack	官方插件	bot token / app token	支持 Socket Mode、HTTP Request URLs、relay 模式
WhatsApp	官方插件	扫码登录（`openclaw channels login`）	存盘状态多；建议用单独一个号码
iMessage	官方插件	macOS + imsg	原生接入，依赖宿主系统
Signal / Teams / Matrix / 飞书 / LINE	官方插件	各家应用凭证	企业场景常用

关于 WhatsApp 的一句忠告：别把它绑在你本人的私人号码上——你发给助手的每条私信都会变成「给 Agent 的输入」。要用就另买一张卡或开一个 eSIM。

3.7 多渠道同时跑

渠道可以并行开着，OpenClaw 按「发送者 + 渠道 + 房间」路由。默认规则：私聊共用 Agent 的主会话（想一人一会话可设 session.dmScope: "per-channel-peer"），群聊每个群一个独立会话。

想让不同群走不同 Agent，在顶层加一条 bindings[]，按 agentId + match.channel + match.accountId 匹配即可。

动手改

按 3.4 完整跑一遍 Telegram：建 bot → channels add → status --probe → 配对 → 发条消息收到回复
把 dmPolicy 从 pairing 改成 allowlist 并填上你的 user ID，然后用另一个账号试着给它发消息，观察它被拒
跑 openclaw channels status --probe 看所有渠道状态，再跑 openclaw logs --follow，找出群 chat ID 长什么样

小结

Gateway = 一个常驻进程统管会话、路由、工具和记忆；渠道只是插进来的遥控器
默认只听 127.0.0.1:18789；要远程访问走 Tailscale / 反代，别裸暴露端口
渠道分内置 / 官方 / 外部三类插件；Telegram 最快，只要 bot token
接入四步：channels add 写 token → status --probe 验证 → 配对批准 →（可选）拉进群
配对码 8 位、1 小时过期；DM 批准 ≠ 群权限；群默认 allowlist + 需 @ 提及
WhatsApp 建议单独用一张号，别绑私人号码

下一章：技能与记忆，让它把重复流程固化下来，并记住你 🐸