智能体绑定

当消息到达某个频道时，OpenClaw 必须决定由哪个代理来回复。代理绑定会为流量的一部分做出该选择——每个绑定都会指定一个 agentId，并匹配频道事实，例如账户、对端、服务器、团队或 Discord 角色；匹配到的代理将拥有由此产生的会话。

绑定只负责选择代理。它们不会创建频道账户，也不会授予访问权限——只有当频道已经通过其常规配对、允许列表和账户规则接受消息后，才会查询绑定。

使用绑定的场景¶

如果只配置了一个代理，所有会话都可以共享一个工作区、一个模型策略和一个会话边界，无需绑定。当你希望进行稳定的拆分时，可以使用绑定，例如：

• 每个代理对应一个频道账户
• 支持收件箱路由到支持工作区
• 某条私信或某个群组路由到专门代理
• 某个服务器、团队或 Discord 角色与账户中的其他部分采用不同路由

先配置频道账户，然后再绑定它。指向频道从不接受的账户的绑定不会生效。

将账户路由到代理¶

此示例使用显式多代理所有权，将名为 support 的 Discord 账户路由到其专属代理和工作区，并将其他 Discord 账户发送到 main：

{
  agents: {
    ownership: "explicit",
    entries: {
      main: {
        workspace: "~/.openclaw/workspace",
      },
      support: {
        workspace: "~/.openclaw/workspace-support",
      },
    },
  },
  bindings: [
    {
      agentId: "support",
      comment: "Route the support bot account to the support agent",
      match: {
        channel: "discord",
        accountId: "support",
      },
    },
    {
      agentId: "main",
      match: {
        channel: "discord",
        accountId: "*",
      },
    },
  ],
}

support 账户上的消息现在会解析为 agentId: "support"。全频道绑定会将其他 Discord 账户路由到 main；为需要路由的其他频道添加绑定。

当没有绑定匹配时，路由可以使用调用方提供的所有者、已配置或保留的默认所有者，或唯一已配置的代理。如果在多代理设置中没有任何可用项，路由会报告 AGENT_SELECTION_REQUIRED，并要求你添加绑定。

旧配置中可能仍包含一个 default: true 标记。Doctor 迁移 会将其所有权转换为显式绑定和服务目标，同时保留现有的显式选择。该标记不能与 agents.ownership: "explicit" 组合使用。

在默认 hybrid 重载模式 下，有效的绑定更改会自动应用。如果 gateway.reload.mode 为 off，请重启 Gateway 以应用更改。然后验证名册和频道账户：

openclaw agents list --bindings
openclaw channels status --probe

匹配特定会话¶

当只有一条私信、一个群组或一个频道应该到达专门代理时，添加 match.peer：

{
  bindings: [
    {
      agentId: "support",
      match: {
        channel: "discord",
        accountId: "default",
        peer: {
          kind: "channel",
          id: "123456789012345678",
        },
      },
    },
  ],
}

peer.kind 接受 direct、group 或 channel。请使用频道的规范对端 ID，而不是显示名称。

匹配字段与优先级¶

每个绑定都需要 agentId 和 match.channel。其他字段用于控制匹配和会话范围：

• accountId：一个已配置账户。省略它时只匹配频道的默认账户；"*" 是显式的全频道回退。
• peer：具体的或通配符形式的私信、群组或频道对端
• guildId 和 teamId：频道特定的群组空间约束
• roles：Discord 角色 ID，与服务器约束一起评估
• session.dmScope：用于匹配私信的可选会话范围覆盖
• session.groupScope：用于匹配群组和频道的可选 main 或 per-group 覆盖

优先级按具体程度确定：具体会话和群组空间匹配优先于账户和频道回退。在同一层级中，配置顺序中的第一个绑定获胜——当它们处于同一层级时，请将窄规则放在宽规则之前。

顶层 bindings 还接受用于持久 ACP 会话的 type: "acp" 条目。这些条目需要具体的 match.peer.id，并遵循 ACP 会话身份契约，而不是普通路由优先级；如果需要该功能，请参阅 ACP 代理。

常见错误¶

省略 accountId 表示所有账户¶

省略 accountId 时只匹配频道的默认账户。如果你想要全频道回退，请显式使用 accountId: "*"。

绑定到未知代理¶

从 agents.entries 中选择一个 agentId。不要依赖缺失目标回退到另一个代理。如果路由针对某个绑定报告 AGENT_SELECTION_REQUIRED，请将其 agentId 更新为预期的已配置代理。

将绑定视为访问控制¶

绑定为已被接受的消息选择代理。配对、dmPolicy、群组策略和允许列表是独立的控制项——请分别配置它们。

相关¶

• 多代理路由
• 代理配置
• 频道路由