跳转至

通道与路由

OpenClaw 将回复路由回消息来源的通道。模型不选择通道;路由是确定性的,并由主机配置控制。在默认 DM 作用域下,来自所有通道的直接消息都会汇聚到代理的主会话。

关键术语

  • 通道:通道插件,例如 discord、googlechat、imessage、irc、line、signal、slack、telegram 或 whatsapp。webchat 是内部 WebChat UI 通道,不是可配置的外发通道。
  • AccountId:按通道的账户实例(如果支持)。
  • 可选的通道默认账户:channels.<channel>.defaultAccount 用于选择在外发路径未指定 accountId 时使用的账户。
  • 在多账户配置中,当配置了两个或更多账户时,请设置显式默认值(defaultAccount 或名为 default 的账户)。否则,回退路由可能会选择第一个规范化后的账户 ID。
  • AgentId:隔离的工作区 + 会话存储(“大脑”)。
  • SessionKey:用于存储上下文并控制并发性的桶键。

外发目标前缀

显式外发目标可以包含提供商前缀,例如 telegram:123 或 tg:123。核心仅在选择通道为 last 或无法解析时,才将该前缀视为通道选择提示,并且仅当已加载的插件声明了该前缀时才如此。如果调用方已经选择了显式通道,则提供商前缀必须与该通道匹配;诸如将 WhatsApp 投递到 telegram:123 的跨通道组合会在插件特定的目标规范化之前失败。

诸如 channel:<id>、user:<id>、room:<id>、thread:<id>、imessage:<handle> 和 sms:<number> 的目标类型和服务前缀仍保留在所选通道的语法内。它们本身不会选择提供商。

报告失败、抑制或演练的插件发送回执不会更改会话中已存储的路由和投递记录。已确认的部分发送可以建立路由,但请求内容不会被镜像为已完全投递。

会话键形状(示例)

直接消息默认会合并到代理的主会话:

  • agent:<agentId>:main(例如:agent:main:main)

session.dmScope 控制 DM 合并:main(默认)共享一个主会话,而 per-peer、per-channel-peer 和 per-account-channel-peer 会将 DM 保留在独立会话中。路由绑定可以通过 bindings[].session.dmScope 为其匹配的对端覆盖作用域。

即使直接消息对话历史与主会话共享,沙箱和工具策略也会为外部 DM 使用派生的按账户直接聊天运行时键,因此通道来源的消息不会被当作本地主会话运行。

在默认 session.groupScope: "per-group" 下,群组与通道仍按通道保持隔离:

  • 群组:agent:<agentId>:<channel>:group:<id>
  • 通道/房间:agent:<agentId>:<channel>:channel:<id>

设置 session.groupScope: "main" 可将所有非直接对端路由到代理的主会话,或为选定房间使用 bindings[].session.groupScope。绑定覆盖优先于全局值。这只更改共享上下文;提及门控和回复仍使用来源群组或通道。

线程:

  • Slack/Discord 线程会在基础键后追加 :thread:<threadId>。
  • Telegram 论坛主题会在群组键中嵌入 :topic:<topicId>。

示例:

  • agent:main:telegram:group:-1001234567890:topic:42
  • agent:main:discord:channel:123456:thread:987654

主 DM 路由固定

当 session.dmScope 为 main 时,直接消息可能共享一个主会话。为防止会话的 lastRoute 被非所有者 DM 覆盖,当以下所有条件都为真时,OpenClaw 会从 allowFrom 推断一个固定的所有者:

  • allowFrom 恰好有一个非通配符条目。
  • 该条目可以规范化为该通道的具体发送者 ID。
  • 入站 DM 发送者不匹配该固定所有者。

在这种不匹配情况下,OpenClaw 仍会记录入站会话元数据,但会跳过更新主会话 lastRoute。

受保护的入站记录

当受保护路径不得创建新的 OpenClaw 会话时,通道插件可以将入站会话记录标记为 createIfMissing: false。在该模式下,OpenClaw 可以更新现有会话的元数据和 lastRoute,但不会仅仅因为观察到一条消息就创建仅路由的会话条目。

路由规则(如何选择代理)

普通路由会为每条入站消息选择一个代理:

  1. 精确对端匹配(bindings 中的 peer.kind + peer.id)。
  2. 父对端匹配(线程继承)。
  3. 对端通配符匹配(针对某种对端类型的 peer.id: "*")。
  4. Guild + 角色匹配(Discord),通过 guildId + roles。
  5. Guild 匹配(Discord),通过 guildId。
  6. Team 匹配(Slack),通过 teamId。
  7. 账户匹配(通道上的 accountId)。
  8. 通道匹配(该通道上的任意账户,accountId: "*")。
  9. 回退所有者:由调用方提供的所有者;否则是唯一已配置的代理或保留的遗留所有者。多个代理且没有所有者时需要匹配的绑定;路由不会选择花名册中的第一个条目。

在启动前运行 openclaw doctor --fix 以迁移遗留默认标记。没有代理花名册的新配置会获得单个 main 代理。

当绑定包含多个匹配字段(peer、guildId、teamId、roles)时,所有提供的字段都必须匹配,该绑定才会生效。

匹配的代理决定使用哪个工作区和会话存储。

广播组(运行多个代理)

代理组线程使用顶层 broadcast 配置,为已接受的入站消息运行多个代理。带限定符的 "<channel>:<peerId>" 键优先于未限定的 WhatsApp 对端键。普通路由仍提供会话路由;协调器会为每个参与者针对该通道、账户、对端和线程提供其自己的代理会话。

{
  broadcast: {
    strategy: "parallel",
    "telegram:-100123": {
      agents: ["reviewer", "writer"],
      maxRounds: 2,
      maxTurns: 4,
    },
    "slack:C0123": ["support", "reviewer"],
    "120363403215116621@g.us": ["alfred", "baerbel"],
  },
}

符合条件的条目默认采用显式提及选择、一轮,以及每个已配置智能体一个回合。maxTurns 限制的是跨所有轮次启动的参与者运行次数,而不是物理平台消息数。旧版 WhatsApp 数组保留对所有列出智能体的单遍扇出。

频道允许列表仍然适用。在 Discord、Slack 和 Telegram 上,显式提及任何符合条件的参与者即可满足房间的提及门槛。已配置的 ACP 绑定仍然保持独占,并绕过群线程扇出。

有关选择、继续资格、预算和参与者标签,请参阅 广播组。控制 UI 目前尚未提供专用的团队线程会话。

配置概览

  • agents.entries:命名智能体定义(工作区、模型等)。
  • bindings:将传入频道/账户/对等方映射到智能体。

示例:

{
  agents: {
    entries: {
      support: {
        name: "Support",
        workspace: "~/.openclaw/workspace-support",
      },
    },
  },
  bindings: [
    { match: { channel: "slack", teamId: "T123" }, agentId: "support" },
    {
      match: { channel: "slack", peer: { kind: "channel", id: "C0123TEAM" } },
      agentId: "support",
      session: { groupScope: "main" },
    },
  ],
}

会话存储

运行时会话行和转录本位于状态目录(默认 ~/.openclaw)下每个智能体的 SQLite 数据库中:

  • ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite

较早的安装可能在 ~/.openclaw/agents/<agentId>/sessions/ 下具有旧版转录 JSONL 文件和 sessions.json 行存储。要将该历史导入 SQLite,请停止 Gateway,备份其状态,并在重启前运行 openclaw doctor --fix。Gateway 启动时不会导入旧版会话文件:如果发现旧版存储,它会拒绝就绪,并打印活动配置文件的 Doctor 命令。使用 openclaw doctor --session-sqlite inspect --session-sqlite-all-agents 以及 Doctor 迁移序列进行检查和验证。

session.store 支持 {agentId} 模板。运行时,旧版存储路径会选择其对应的 SQLite 数据库;JSON 文件本身只是迁移输入或显式离线维护目标。

Gateway 会话发现可以包括默认 agents/ 根目录下的磁盘存储,以及使用 agents/<agentId>/sessions/sessions.json 布局的模板化 session.store 根目录。它可以识别对应的 agent/openclaw-agent.sqlite 数据库,而不要求存在旧版 sessions.json 文件。发现的存储文件必须是已解析智能体根目录内的常规文件;符号链接存储文件和根目录外路径会被忽略。

ACP 会话发现会读取 SQLite ACP 元数据,并将其与对应的会话条目关联。

WebChat 行为

WebChat 会附加到 所选智能体,并默认使用该智能体的主会话。因此,WebChat 可以让你在一个地方查看该智能体的跨频道上下文。

WebChat 回合及其后台补全会保留在 WebChat 中,除非显式选择外部路由。会话保存的外部路由会保留给有意使用它的调用方;它不会覆盖当前回合的来源。内部触发的媒体任务可以在没有交互式 WebChat 来源的情况下使用 WebChat 频道哨兵;其媒体准入仍会固定保存的外部路由。

出站 send 请求可以设置 sessionKey,以将已交付输出镜像到另一个转录本。这不会重新绑定该转录本的交付路由:已解析的目标会话拥有保存的路由,包括当频道路由有意选择共享主会话时。

回复上下文

传入回复包括:

  • 在可用时,包括 ReplyToId、ReplyToBody 和 ReplyToSender。
  • 引用上下文会作为 [Replying to ...] 块追加到 Body。

这在所有频道中保持一致。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw