Implementation:Openclaw Openclaw AgentBinding Type

AgentBinding Type

AgentBinding Type documents the AgentBinding type definition in src/config/types.agents.ts and the architectural documentation in docs/concepts/multi-agent.md. Together, these define the data model and conceptual framework for multi-agent routing in OpenClaw.

Principle:Openclaw_Openclaw_Multi_Agent_Architecture

Source Location

File	Lines	Description
src/config/types.agents.ts	L72-82	AgentBinding type definition
src/config/types.agents.ts	L20-65	AgentConfig type definition (per-agent configuration)
src/config/types.agents.ts	L67-70	AgentsConfig type (top-level agents configuration)
docs/concepts/multi-agent.md	Full file	Architectural documentation for multi-agent routing

AgentBinding Type

The AgentBinding type represents a single routing rule that maps inbound messages to a specific agent:

export type AgentBinding = {
  agentId: string;
  match: {
    channel: string;
    accountId?: string;
    peer?: { kind: "dm" | "group" | "channel"; id: string };
    guildId?: string;
    teamId?: string;
  };
};

Fields

Field	Type	Required	Description
agentId	string	Yes	The target agent that receives matched messages. Normalized to lowercase.
match.channel	string	Yes	The channel identifier (e.g., "whatsapp", "telegram", "discord", "slack").
match.accountId	string	No	The channel account instance. Use "*" for wildcard matching. Defaults to DEFAULT_ACCOUNT_ID when omitted.
match.peer	{ kind, id }	No	Matches a specific conversation. kind is "dm", "group", or "channel". id is the peer identifier (e.g., E.164 phone number, group JID).
match.guildId	string	No	Matches a Discord guild (server).
match.teamId	string	No	Matches a Slack team (workspace).

AgentConfig Type

Each agent in the agents.list[] array conforms to the AgentConfig type:

export type AgentConfig = {
  id: string;
  default?: boolean;
  name?: string;
  workspace?: string;
  agentDir?: string;
  model?: AgentModelConfig;
  skills?: string[];
  memorySearch?: MemorySearchConfig;
  humanDelay?: HumanDelayConfig;
  heartbeat?: AgentDefaultsConfig["heartbeat"];
  identity?: IdentityConfig;
  groupChat?: GroupChatConfig;
  subagents?: {
    allowAgents?: string[];
    model?: string | { primary?: string; fallbacks?: string[] };
  };
  sandbox?: {
    mode?: "off" | "non-main" | "all";
    workspaceAccess?: "none" | "ro" | "rw";
    sessionToolsVisibility?: "spawned" | "all";
    scope?: "session" | "agent" | "shared";
    perSession?: boolean;
    workspaceRoot?: string;
    docker?: SandboxDockerSettings;
    browser?: SandboxBrowserSettings;
    prune?: SandboxPruneSettings;
  };
  tools?: AgentToolsConfig;
};

AgentModelConfig Type

The model configuration can be a simple string or an object with primary and fallback models:

export type AgentModelConfig =
  | string
  | {
      primary?: string;
      fallbacks?: string[];
    };

AgentsConfig Type

The top-level agents configuration groups defaults and the agent list:

export type AgentsConfig = {
  defaults?: AgentDefaultsConfig;
  list?: AgentConfig[];
};

Configuration Examples

Two WhatsApp accounts routed to two agents:

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

Per-peer override (specific group to a different agent):

{
  bindings: [
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "1203630...@g.us" },
      },
    },
  ],
}

Channel split (WhatsApp for chat, Telegram for deep work):

{
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}

Architectural Documentation

The file docs/concepts/multi-agent.md provides the canonical reference for multi-agent routing, covering:

• What constitutes "one agent" (workspace, agentDir, session store)
• Path conventions for single-agent and multi-agent mode
• Routing rules and the most-specific-wins hierarchy
• Configuration examples for common deployment patterns
• Per-agent sandbox and tool configuration
• DM split on shared accounts

Related Source Files

File	Key Export
src/routing/resolve-route.ts	resolveAgentRoute() -- runtime binding evaluation
src/commands/agents.bindings.ts	applyAgentBindings() -- binding application with conflict detection
src/routing/bindings.ts	listBindings() -- retrieves all bindings from config
src/routing/session-key.ts	normalizeAgentId(), DEFAULT_AGENT_ID -- id normalization utilities