How to Configure Agent Routing in OpenClaude: A Complete Guide to Model Selection

** Configure agent routing in OpenClaude by defining routes in agentModels and mapping agents to those routes via agentRouting inside ~/.openclaude/settings.json.**

OpenClaude provides fine-grained control over which large language model (and provider) each agent utilizes during execution. By configuring the settings.json file and leveraging the routing logic in src/services/api/agentRouting.ts, you can optimize costs and capabilities by sending specific agents to cheaper models or alternative providers while keeping others on premium endpoints.

Understanding the Configuration Schema

OpenClaude uses two distinct settings objects stored in ~/.openclaude/settings.json to determine agent behavior. Understanding the separation between route definitions and route assignments is essential for proper configuration.

The agentModels Dictionary

The agentModels setting defines named routes that map arbitrary keys to provider endpoints and model names. Each entry can specify:

• base_url: The API endpoint for the provider (e.g., https://api.deepseek.com/v1)
• api_key: The authentication token for that provider
• model: An explicit model name (optional for cross-provider routes, required for model-only routes)

If base_url and api_key are omitted, the route operates in model-only mode, reusing the current session's existing provider but switching the model.

The agentRouting Dictionary

The agentRouting setting associates agent identifiers with keys defined in agentModels. The lookup resolution follows a strict precedence order: agent name → sub-agent type → "default". When a match is found, the system resolves either a full AgentRoute (with provider override) or an AgentModelOnly object for the execution.

Configuring Cross-Provider Routes

Cross-provider routing allows you to send specific agents to entirely different API endpoints, such as routing exploratory tasks to DeepSeek while keeping planning tasks on OpenAI.

Add the following to your ~/.openclaude/settings.json:

{
  "agentModels": {
    "deepseek-v4-flash": {
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "sk-your-key"
    },
    "gpt-4o": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-key"
    }
  },
  "agentRouting": {
    "Explore": "deepseek-v4-flash",
    "Plan": "gpt-4o",
    "default": "gpt-4o"
  }
}

In this configuration, any agent named "Explore" routes to the DeepSeek endpoint, while "Plan" and all unspecified agents fallback to the OpenAI route defined under default.

Using Model-Only Routes

When you want to switch models without changing providers—useful for cost optimization within the same API ecosystem—define routes that omit the endpoint credentials.

{
  "agentModels": {
    "mini": {
      "model": "gpt-5-mini"
    }
  },
  "agentRouting": {
    "verification": "mini"
  }
}

Here, the verification agent runs on gpt-5-mini using whatever provider the main OpenClaude session is currently connected to. This pattern avoids duplicating API keys across multiple route definitions.

How Routing Resolution Works

The core routing implementation lives in src/services/api/agentRouting.ts. According to the OpenClaude source code, the system employs several specialized functions to resolve the final model and provider for each agent execution.

Key Resolution Functions

• resolveAgentProvider(name, subagentType, settings): Looks up the routing table using case-insensitive, hyphen/underscore-agnostic key normalization. Returns either a ProviderOverride or AgentModelOnly object.

• resolveAgentRunModelRouting({...}): Combines tool-specified models, routing configurations, and the agent definition's model to compute the final mainLoopModel and an optional providerOverride.

• resolveModelOnlyModel: Handles built-in model aliases such as inherit, sonnet, and haiku when processing model-only routes, ensuring the correct provider-aware model is selected.

When a provider override is active, applyAgentProviderOverrideToEnv(providerOverride, env) clears existing provider-selection environment variables (like OPENAI_MODEL or OPENAI_BASE_URL) and injects the new values so child processes inherit the correct endpoint configuration.

Applying Routes Programmatically

For advanced integrations, you can leverage the routing logic directly in TypeScript to resolve configurations before spawning child processes.

Resolving Routes Manually

import { resolveAgentRunModelRouting } from './src/services/api/agentRouting.js';
import type { SettingsJson } from './src/utils/settings/types.js';
import fs from 'fs';

const settings: SettingsJson = JSON.parse(
  fs.readFileSync(`${process.env.HOME}/.openclaude/settings.json`, 'utf8')
);

const routing = resolveAgentRunModelRouting({
  resolvedAgentModel: 'gpt-4o',
  parentModel: 'gpt-4o',
  agentName: 'Plan',
  subagentType: undefined,
  settings,
});

console.log(routing);
// { mainLoopModel: 'gpt-4o', providerOverride: { model: 'gpt-4o', baseURL: '...', apiKey: '...' } }

Injecting Provider Overrides into Child Processes

import { applyAgentProviderOverrideToEnv } from './src/services/api/agentRouting.js';

const childEnv = { ...process.env };
applyAgentProviderOverrideToEnv(routing.providerOverride!, childEnv);

// Spawn child with routed environment
// execa('node', ['task.js'], { env: childEnv });

This ensures that any subprocess launched by OpenClaude respects the routing configuration defined in your settings.

Summary

• Configuration Location: All routing settings reside in ~/.openclaude/settings.json under agentModels and agentRouting.
• Cross-Provider Routing: Define full provider endpoints (base_url and api_key) in agentModels to send agents to different APIs like DeepSeek or OpenAI.
• Model-Only Routing: Specify only the model field to switch models while retaining the current session's provider.
• Resolution Order: The system checks agentName first, then subagentType, then falls back to "default".
• Implementation Core: src/services/api/agentRouting.ts contains the resolution logic including resolveAgentProvider and applyAgentProviderOverrideToEnv.

Frequently Asked Questions

What is the difference between agentModels and agentRouting?

agentModels defines the available routes (the "what" and "where"), while agentRouting assigns specific agents to those routes (the "who"). Think of agentModels as creating labels for endpoints, and agentRouting as applying those labels to agent identifiers.

Can I use the same model name with different providers for different agents?

Yes. Create separate entries in agentModels with unique keys pointing to different base_url values. For example, define "gpt4-openai" and "gpt4-azure" both pointing to gpt-4 models but with different endpoints, then assign specific agents to each key in agentRouting.

How does OpenClaude handle routing when no match is found in agentRouting?

If an agent name is not found in agentRouting, the system checks for a subagentType match. If that also fails, it uses the "default" key. If no default is configured, the agent inherits the parent session's model and provider without overrides, as implemented in the resolution logic of src/services/api/agentRouting.ts.

Where is the routing configuration schema documented?

The user-facing documentation explaining these concepts lives in docs/agent-routing.md within the OpenClaude repository, while the TypeScript type definitions and validation schemas are located in src/services/api/agentRouteSettings.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}