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

> Master agent routing in OpenClaude. Learn to define routes and map agents in settings.json for efficient model selection and enhanced AI workflows.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: how-to-guide
- Published: 2026-09-06

---

** 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`](https://github.com/Gitlawb/openclaude/blob/main/settings.json) file and leveraging the routing logic in [`src/services/api/agentRouting.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`:

```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.

```json
{
  "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`](https://github.com/Gitlawb/openclaude/blob/main/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

```typescript
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

```typescript
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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/docs/agent-routing.md)** within the OpenClaude repository, while the TypeScript type definitions and validation schemas are located in [`src/services/api/agentRouteSettings.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/agentRouteSettings.ts).