OpenClaw multiple agents and models: routing, isolation and cost

OpenClaw multi agents and multiple models are two different layers of one config file: several agents are keyed entries under agents.entries, each owning its own workspace, state directory and session store, while several models are per-agent model values inside those entries. Two more layers sit alongside them — bindings decides which agent answers, and a fallback chain decides what one agent does when its model fails. Editing the wrong layer is the single most common reason a change appears to do nothing.

Running more agents costs nothing in software. OpenClaw's documentation overview states it is developed in the open by "the OpenClaw Foundation, an independent 501(c)(3)" with "No paid tier, no telemetry by default beyond a version check you can turn off, no lab owns it", and openclaw.ai adds "No subscription. No hosted tier. No token." The npm package openclaw is MIT, with latest at 2026.9.5 beside an extended-stable channel at 2026.7.35 and engines.node of >=24.16.0 <25 || >=26.1.0 (npm registry, checked September 21, 2026). What a second agent adds to your bill is tokens.

OpenClaw multi agents: four layers, and the symptom when you edit the wrong one

All four were read from OpenClaw's own documentation on September 21, 2026: entries and multi-agent, agent bindings and model failover. Two shapes in older tutorials are stale: an agents.list array roster is the legacy form Doctor migrates, and a default: true marker on an entry is retired — the entries page states plainly that "default is retired" and that multi-agent operations need a binding or an explicit target. OpenClaw also ran under two earlier names, so any Moltbot- or Clawdbot-era config you find predates this schema.

OpenClaw multiple agents setup: a minimal two-agent, two-model config

This fragment assumes you already have a working models.providers block — best API for OpenClaw carries the Kunavo one, including api: "anthropic-messages" and the base URL published at Anthropic base URL. What follows is only the agent and routing layer.

{
  "agents": {
    "defaults": {
      "modelSelectionScope": "session",
      "model": {
        "primary": "kunavo/claude-haiku-4-5",
        "fallbacks": [
          "kunavo/claude-sonnet-5"
        ]
      }
    },
    "entries": {
      "ops": {
        "name": "Ops",
        "workspace": "~/.openclaw/workspace-ops",
        "agentDir": "~/.openclaw/agents/ops/agent",
        "model": "kunavo/claude-haiku-4-5",
        "modelPolicy": {
          "allow": [
            "kunavo/claude-haiku-4-5"
          ]
        }
      },
      "build": {
        "name": "Build",
        "workspace": "~/.openclaw/workspace-build",
        "agentDir": "~/.openclaw/agents/build/agent",
        "model": {
          "primary": "kunavo/claude-opus-5",
          "fallbacks": [
            "kunavo/claude-sonnet-5"
          ]
        },
        "utilityModel": "kunavo/claude-haiku-4-5"
      }
    }
  },
  "bindings": [
    {
      "agentId": "build",
      "match": {
        "channel": "discord",
        "accountId": "build"
      }
    },
    {
      "agentId": "ops",
      "match": {
        "channel": "discord",
        "accountId": "*"
      }
    }
  ]
}

Four things in that block are load-bearing. Each agent has its own agentDir, because the multi-agent page warns "Never reuse agentDir across agents — it causes auth/session state collisions." The ops agent uses the string form of model, which the entries page defines as "a strict per-agent primary with no model fallback" — so a failure surfaces instead of silently moving routine work to a pricier tier. The build agent uses the object form with an explicit fallbacks list, which is how you opt an agent in; the failover page adds that an agent can set model: { fallbacks: [...] } alone and keep inheriting the shared primary. And the narrow binding sits above the wildcard, because within one match tier "the first matching bindings entry wins."

Workspace defaults differ between the default agent and the rest, and are worth setting explicitly: the default agent's workspace is <stateDir>/workspace while other agents default to <stateDir>/workspace-<agentId>. Memory follows the workspace, since OpenClaw's built-in engine "remembers things by writing plain Markdown files in your agent's workspace" — so isolating workspaces is what isolates memory. Session permission modes are a separate axis again: read-only, guarded, workspace and full, where "full requires operator.admin. The other modes require operator.write" (permission modes, September 21, 2026). A cheap model on a permissive agent is still a permissive agent.

What separate agents separate — and what they do not

This is the boundary the price tables miss. Separate entries give you separate files, memory, history, tool policy and stored auth profiles. They do not, by themselves, give each agent its own API key for an environment-configured custom provider — the documented per-agent schema has no baseUrl, apiKey or providers field at all. Absence from the documentation is not proof the code forbids it, so read this as not documented; if you need hard key separation per tenant, run separate Gateways. A related limit applies to identity: OpenClaw's WhatsApp DM-split example notes that "Replies still come from the same WhatsApp number — there is no per-agent sender identity", and that "Direct chats collapse to the agent's main session key by default, so true isolation requires one agent per person." That sentence is stated for WhatsApp; check your own channel's page before generalizing it.

One capability boundary to note while you are splitting roles: Kunavo serves no text-to-speech, speech-to-text or embedding model, so an agent that needs voice output or a vector index has to call an outside provider for that step.

OpenClaw multiple models: strict, fallback, policy and the utility lane

Per-agent model selection has four controls worth setting deliberately. model as a string is strict. { primary, fallbacks: [...] } opts that agent into failover. modelPolicy.allow is an allowlist that "replaces the default policy for that agent" — accepting aliases, exact refs and trailing wildcards — which is how you stop a routine agent ever reaching an expensive model. And utilityModel is a separate, usually cheaper model for "short internal tasks such as generated session and thread titles", with a per-agent override.

The documented trigger list is specific. OpenClaw advances on "auth failures, rate limits and cooldown exhaustion, overloaded/provider-busy errors, timeout-shaped failover errors, billing disables, model_not_found", and on other unrecognised errors while candidates remain — but not on context-overflow errors, which stay inside compaction and retry logic, and not on "explicit aborts that are not timeout/failover-shaped". Outside group and channel conversations it is visible: those surfaces post a status notice of the form Model Fallback: <fallback> (selected <primary>; <reason>) and a matching cleared notice, while group and channel conversations "suppress the visible notices while retaining the same fallback state", so do not rely on seeing one in a shared room. An explicit session selection — /model, the model picker, session_status(model=...) or sessions.patch — is strict: if that model fails before producing a reply, OpenClaw reports the failure instead of answering from a configured fallback. A cron job's --model is not one of those; the documentation calls it a job primary that still uses configured fallbacks unless the job sets payload.fallbacks: [].

Two more mechanics decide whether your intent survives. Request params merge through four layers, from agents.defaults.params to agents.entries.*.params, with later layers overriding by key. And parallelism has a computed ceiling: agents.defaults.maxConcurrent defaults to max(8, available CPU parallelism * 4) across sessions, while each session stays serialized — two messages to one agent do not run at once. For choosing which model belongs in which role, Opus vs Sonnet vs Haiku covers the capability side.

Cost attribution by route, not by agent

Because no documented command reports spend per agent, attribute by route. The arithmetic below is illustrative, not a measured bill and not a ceiling. It assumes a 30-day month, the documented 30m heartbeat default (1,440 runs), 300 output tokens per heartbeat, no cache hits, and a main conversation lane of 8M input and 500K output tokens. The ~100K and ~2–5K per-run context figures are OpenClaw's own illustration of what isolatedSession removes, not something measured here; 3,000 is the midpoint. Rates are live Kunavo catalog prices per million tokens.

Claude Haiku 4.5 lists $0.40 / $2.00 and Claude Opus 5 lists $2.00 / $10.00 per million input / output tokens on the live catalog. The reading that matters: under these assumptions the scheduled lane dominates. A shared-session heartbeat on the strong model works out to $292.32 a month, against $2.59 for the same cadence with isolatedSession: true on the cheap model. OpenClaw says as much itself — "Heartbeats run full agent turns. Shorter intervals burn more tokens" — and names isolatedSession, lightContext, a cheaper model and target: "none" as the levers.

The cheap-heartbeat trick has a documented failure mode, and it is the reason isolatedSession is the better lever than the model swap alone. Heartbeats "preserve the shared session's existing runtime model after the run completes", so a heartbeat that switched a session to a smaller model can leave it in place for the next main-session turn, which may then report context overflow — OpenClaw's recovery message calls this heartbeat model bleed. The documentation's worked example is a local model with a 32k window, so the size of the risk depends on how much smaller the heartbeat model's context window is than the shared session needs. One scheduling note: the documented default interval is 30m, bumped to 1h only when the resolved auth mode is Anthropic OAuth/token, so a plain API-key route keeps 30m unless you set heartbeat.every yourself. Check your own value before budgeting.

Two caveats on the dollar figures. Kunavo's catalog amount is a billing floor rather than a cap: when the upstream reports its charge, the bill is the greater of catalog cost and upstream cost times the applicable markup. And a custom provider declared without a per-model cost object makes OpenClaw's own readout useless — it defaults to cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, showing $0 while the supplier bills normally. Declare cost, contextWindow and maxTokens on each model you add, and reconcile against the provider ledger. The minimum Kunavo top-up is $10 in prepaid credit — a funding minimum, not a task fee or a subscription. See billing details and AI cost optimization.

Which buying route fits a multi-agent Gateway

One note on dialects, because caching is where the money is. The Kunavo block in the sibling guide declares api: "anthropic-messages", which OpenClaw treats as a non-direct Anthropic endpoint. Two documented consequences follow. Implicit Anthropic beta headers are suppressed on such endpoints, so features like interleaved thinking are opt-in through an explicit headers["anthropic-beta"] rather than automatic. And caching has to be asked for: OpenClaw seeds cacheRetention: "short" only for the direct anthropic and anthropic-vertex providers, while "custom anthropic-messages-compatible endpoints" are supported "when cacheRetention is set explicitly" — so set params.cacheRetention yourself rather than assuming a default (prompt caching, September 21, 2026). A separate rule covers the other dialect: an openai-completions route to a non-native endpoint sends "no prompt-cache hints". Verify the reported cache usage on your own route before budgeting recurring context as cache hits. Prompt caching covers the rate side.

Verify it landed where you meant

openclaw config validate
openclaw gateway restart
openclaw agents list --bindings
openclaw models status --agent ops --json --check
openclaw models list --agent build

Config validation checks shape, and gateway restart reloads it; neither proves a billed request succeeded. openclaw agents list --bindings shows the routing actually loaded — prefer it to --tree, which appears in the concepts pages but not in the CLI command table. openclaw models status --agent <id> explains that agent's configured default, and models list --agent <id> shows its inventory. If models set exits nonzero on an unknown provider, that is the model layer: the provider must be an installed plugin or declared under models.providers. If messages reach no agent, that is the routing layer. If duplicate runs appear once several agents share a channel, OpenClaw documents bot loop protection keys as the guard — the documentation describes prevention, not a root cause, so diagnose before assuming.

Then run one bounded task per agent and read the charge your provider account recorded for it. Kunavo has not runtime-tested OpenClaw, single- or multi-agent: everything above is read from OpenClaw's published documentation, and a published configuration is not a compatibility test. Keep a working route available while you try it. Start from the provider configuration, compare the full operating bill in OpenClaw pricing, and create a Kunavo account when you are ready to fund a key.

FAQ

OpenClaw documentation, CLI reference and the npm registry entry checked September 21, 2026 at package version 2026.9.5; no Gateway, agent, binding or paid request was exercised here. Kunavo token rates are read from the live catalog, and every dollar figure on this page is illustrative token arithmetic rather than a measured bill.