<!-- source: https://deepwiki.com/openclaw/openclaw/2.5-multi-agent-routing -->

# Multi-Agent Routing

- docs/cli/agent.md
- docs/tools/agent-send.md
- extensions/memory-core/src/dreaming-narrative.test.ts
- extensions/memory-core/src/dreaming-narrative.ts
- extensions/memory-core/src/dreaming-repair.test.ts
- packages/gateway-client/src/client.ts
- packages/gateway-client/src/client.watchdog.test.ts
- src/agents/command/cli-compaction.test.ts
- src/agents/command/cli-compaction.ts
- src/agents/command/types.ts
- src/agents/embedded-agent-runner/compact.types.ts
- src/agents/harness/selection.test.ts
- src/agents/harness/selection.ts
- src/auto-reply/reply/commands-compact.test.ts
- src/auto-reply/reply/commands-compact.ts
- src/cli/gateway-dispatch-dotenv.ts
- src/cli/program/command-registry-core.ts
- src/cli/program/command-registry.test.ts
- src/cli/program/register.agent-turn.ts
- src/cli/program/register.agent.test.ts
- src/cli/program/register.agent.ts
- src/commands/agent-via-gateway.test.ts
- src/commands/agent-via-gateway.ts
- src/config/config.talk-validation.test.ts
- src/config/gateway-dispatch-config.test.ts
- src/config/gateway-dispatch-config.ts
- src/gateway/call.test.ts
- src/gateway/call.ts
- src/gateway/chat-abort.test.ts
- src/gateway/chat-abort.ts
- src/gateway/client.test.ts
- src/gateway/client.ts
- src/gateway/client.watchdog.test.ts
- src/gateway/connection-details.ts
- src/gateway/server-chat-state.ts
- src/gateway/server-maintenance.test.ts
- src/gateway/server-maintenance.ts
- src/gateway/server-methods/agent.test.ts
- src/gateway/server-methods/agent.ts
- src/gateway/server-methods/chat.abort-authorization.test.ts
- src/gateway/server-methods/chat.abort-persistence.test.ts
- src/gateway/server-methods/chat.abort.test-helpers.ts
- src/gateway/server-methods/session-active-runs.ts
- src/gateway/server-methods/sessions.ts
- src/gateway/server.node-version-mismatch.test.ts
- src/gateway/server.sessions.list-changed.test.ts
- src/infra/dotenv-global.ts
- src/infra/dotenv.ts
- src/node-host/runner.credentials.test.ts
- src/node-host/runner.ts
- test/vitest/vitest.gateway-client.config.ts

## Purpose and Scope

This document explains the OpenClaw Gateway's multi-agent routing system, which allows a single process to host multiple isolated AI assistants. Each agent operates within its own isolated workspace, maintains independent session history, and utilizes its own set of authentication profiles and model configurations [src/gateway/server-methods/agent.ts120-135](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent.ts#L120-L135) Routing is handled by a deterministic mechanism that maps inbound messages from messaging channels to the appropriate agent based on configurable bindings and session keys [src/routing/session-key.ts30-40](https://github.com/openclaw/openclaw/blob/fbdf5937/src/routing/session-key.ts#L30-L40)

## Agent Isolation Model

Each agent in the Gateway is a distinct logical entity with its own filesystem resources. Isolation ensures that tools, memory, and credentials used by one agent do not leak into another.

### Agent Resource Mapping

The diagram below shows how the Gateway maps logical Agent IDs to physical filesystem entities using `resolveAgentWorkspaceDir` and `resolveAgentIdFromSessionKey` [src/gateway/server-methods/agent.test.ts122-133](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent.test.ts#L122-L133)

```

```

**Sources:**

- src/gateway/server-methods/agent.ts 120-135
- src/gateway/server-methods/agent.test.ts 122-133
- src/gateway/server-methods/sessions.ts 50-58

## Session Key Structure

Routing information is encoded directly into session keys. The Gateway uses `resolveAgentIdFromSessionKey` to extract the target agent from the session identifier [src/routing/session-key.ts33](https://github.com/openclaw/openclaw/blob/fbdf5937/src/routing/session-key.ts#L33-L33) Keys are normalized to ensure case-insensitive matching for IDs [src/routing/session-key.ts32](https://github.com/openclaw/openclaw/blob/fbdf5937/src/routing/session-key.ts#L32-L32)

The Gateway identifies internal requester sessions (like sub-agents) to manage lifecycle using `isAcpSessionKey` [src/routing/session-key.ts84](https://github.com/openclaw/openclaw/blob/fbdf5937/src/routing/session-key.ts#L84-L84)

**Sources:**

- src/routing/session-key.ts 30-40
- src/gateway/server-methods/agent.test.ts 107-119
- src/routing/session-key.ts 84

## Delegate Architecture and ACP Routing

OpenClaw supports a recursive multi-agent model where a "controller" agent can spawn "sub-agents" via the Agent Control Protocol (ACP). These sub-agents are routed to their own isolated sessions but remain bound to the requester via the `subagent-registry` [src/gateway/server-methods/agent.test.ts9-12](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent.test.ts#L9-L12)

### Sub-Agent Registry and Lifecycle

The registry manages the state of active runs, coordinating with the Gateway to ensure sessions are correctly initialized.

1. Context Resolution : registerAgentRunContext builds the execution context including account and session identifiers src/gateway/server-methods/agent.ts 67
2. Auth Planning : The system determines if auth profiles should be forwarded or resolved via resolveProviderIdForAuth src/gateway/server-methods/agent.ts 39
3. Execution : runEmbeddedPiAgent (invoked via agentHandlers ) executes the agent logic within the resolved scope src/gateway/server-methods/agent.ts 26

```

```

**Sources:**

- src/gateway/server-methods/agent.ts 39-67
- src/gateway/server-methods/agent.test.ts 9-12
- src/agents/harness/selection.ts 16-17

## Model and Auth Profile Routing

Routing also determines which model configuration and authentication profile are used for a specific turn.

### Model Overrides and Fallbacks

The system allows per-session model overrides via `resolveSessionModelRef` [src/gateway/server-methods/sessions.ts113](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/sessions.ts#L113-L113) `updateChatRunProvider` manages the transition between primary models and providers [src/gateway/chat-abort.ts13](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/chat-abort.ts#L13-L13)

### Auth Profile Scoping

Auth profiles are managed per agent. When an agent runs, it resolves its credentials using `resolveProviderIdForAuth` which is scoped to the agent's identity [src/gateway/server-methods/agent.ts39](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent.ts#L39-L39) This ensures that even if two agents use the same model provider (e.g., OpenAI), they can use different API keys stored in their respective `auth-profiles.json` files.

**Sources:**

- src/gateway/server-methods/agent.ts 39
- src/gateway/server-methods/sessions.ts 113
- src/gateway/chat-abort.ts 24-25

## Isolated Workspaces

Every agent is assigned a dedicated workspace directory via `resolveAgentWorkspaceDir` [src/gateway/server-methods/agent.test.ts122-133](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent.test.ts#L122-L133) This directory serves as the root for all file-based tools.

### Workspace Data Flow

The following diagram illustrates how the Gateway resolves the workspace for a session and passes it to the agent runtime.

```

```

**Sources:**

- src/gateway/server-methods/agent.test.ts 122-133
- src/gateway/server-methods/agent.ts 67
- src/agents/harness/selection.ts 16-17
