# How to Configure Agent Routing and Model Overrides in OpenClaude

> Master agent routing and model overrides in OpenClaude. Learn to use settings.json and environment variables for static or dynamic agent selection and customization.

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

---

**You can configure agent routing and model overrides in OpenClaude through the [`settings.json`](https://github.com/Gitlawb/openclaude/blob/main/settings.json) file using `agentModels` for static assignments or `smartRouting` for dynamic selection, supplemented by environment variables like `OPENCLAUDE_SMART_ROUTING_SIMPLE` and the `routingSubagentType` parameter for sub-agent invocation.**

OpenClaude's routing system determines which provider endpoint and concrete model an agent uses for each conversational turn. The mechanism is driven by a hierarchical **settings** structure and runtime flags that resolve model keys to specific API endpoints according to the source code in [`src/services/api/agentRouting.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/agentRouting.ts).

## Configuring Static Model Assignments with agentModels

The primary configuration for agent routing resides in the `agentModels` section of your settings. Each entry maps a model key to either a bare identifier string or a configuration object containing endpoint overrides.

### Basic Model Key Definitions

In [`src/utils/settings/types.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/settings/types.ts), the schema defines `agentModels` as a record where keys are arbitrary identifiers and values specify the target model. A simple configuration uses a bare string:

```json
{
  "agentModels": {
    "fast-agent": "gpt-4o-mini",
    "power-agent": "claude-3-opus-20240229"
  }
}

```

### Cross-Provider Endpoint Overrides

For routing requests to custom endpoints like Azure-hosted OpenAI or private API gateways, specify an object with `base_url` and `api_key` fields. According to [`src/services/api/agentRouting.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/agentRouting.ts) at line 85, the routing logic validates these fields and warns when only one is present:

```json
{
  "agentModels": {
    "azure-gpt": {
      "model": "gpt-5-mini",
      "base_url": "https://my-azure-openai.example.com/v1",
      "api_key": "sk-my-azure-key"
    }
  }
}

```

## Implementing Dynamic Smart Routing

OpenClaude supports intelligent model selection through the `smartRouting` configuration block, which automatically classifies turns as "simple" or "strong" and routes accordingly.

### Simple vs. Strong Model Selection

When `smartRouting.enabled` is true, the session classifies each user turn. The classification determines whether to use `simpleModel` or `strongModel` keys defined in `settings.smartRouting`. As implemented in [`src/services/api/smartRouting/resolveConfig.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/smartRouting/resolveConfig.ts) at line 14, these keys resolve through the same `agentModels` registry:

```json
{
  "smartRouting": {
    "enabled": true,
    "simpleModel": "my-gpt-mini",
    "strongModel": "gpt-5-big"
  }
}

```

### Environment Variable Overrides

For temporary overrides without modifying settings files, the `managedEnv` module in [`src/utils/managedEnvConstants.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/managedEnvConstants.ts) recognizes specific environment variables. Set `OPENCLAUDE_SMART_ROUTING_SIMPLE` to override the simple-turn model key, or `OPENCLAUDE_SMART_ROUTING_STRONG` for complex turns:

```bash
OPENCLAUDE_SMART_ROUTING_SIMPLE=my-gpt-mini \
OPENCLAUDE_SMART_ROUTING_STRONG=gpt-5-big \
openclaude run my-agent

```

## Runtime Resolution Flow

The routing resolution follows a deterministic hierarchy: CLI flags take precedence over environment variables, which override user settings, which finally fall back to defaults. This precedence is validated in [`src/utils/settings/agentModelsSchema.test.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/settings/agentModelsSchema.test.ts) and applied in [`src/utils/providerFlag.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerFlag.ts) at line 321.

The resolution flow in [`src/services/api/agentRouting.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/agentRouting.ts) executes as follows:

1. Load merged settings from [`src/utils/settings/settings.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/settings/settings.ts)
2. If smart routing is enabled, classify the turn and select the appropriate model key
3. Resolve the key to a concrete model string and optional custom endpoint
4. Build the request using provider-specific clients with resolved credentials

## Practical Implementation Examples

### Complete settings.json Configuration

Combine static and dynamic routing in your configuration file:

```json
{
  "agentModels": {
    "my-gpt-mini": {
      "model": "gpt-5-mini",
      "base_url": "https://my-azure-openai.example.com/v1",
      "api_key": "sk-my-azure-key"
    },
    "claude-default": "claude-3-sonnet-20240229"
  },
  "smartRouting": {
    "enabled": true,
    "simpleModel": "my-gpt-mini",
    "strongModel": "claude-default"
  }
}

```

### Programmatic Sub-Agent Routing

When invoking sub-agents from within tools, explicitly specify routing via the `routingSubagentType` field. In [`src/tools/AgentTool/runAgent.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/tools/AgentTool/runAgent.ts), this parameter forces the sub-agent to use a specific model key regardless of the parent agent's configuration:

```typescript
await runAgent({
  agentName: "my-agent",
  routingSubagentType: "my-gpt-mini",
});

```

This overrides the default resolution path and forces the sub-agent to use the specified `agentModels` entry.

## Summary

- Configure static model assignments in [`settings.json`](https://github.com/Gitlawb/openclaude/blob/main/settings.json) under the `agentModels` block, supporting both string identifiers and objects with `base_url`/`api_key` for cross-provider routing.
- Enable `smartRouting` to automatically classify turns as simple or strong, routing to different models based on `simpleModel` and `strongModel` keys.
- Override configurations temporarily using `OPENCLAUDE_SMART_ROUTING_SIMPLE` and `OPENCLAUDE_SMART_ROUTING_STRONG` environment variables.
- Use the `routingSubagentType` parameter when calling `runAgent()` to force specific routing for sub-agents.
- The resolution hierarchy follows: CLI flags → environment variables → user settings → defaults, as implemented in [`src/utils/providerFlag.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerFlag.ts).

## Frequently Asked Questions

### How do I route an agent to a custom Azure OpenAI endpoint?

Define an object in `agentModels` with both `base_url` and `api_key` fields. The routing logic in [`src/services/api/agentRouting.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/agentRouting.ts) detects these fields and directs requests to your specified endpoint while warning if only one field is provided.

### What happens if I specify both smart routing and a specific model key?

Smart routing determines which model key to use based on turn classification, but the actual resolution to a concrete model and endpoint always flows through the `agentModels` registry. If you specify `routingSubagentType` programmatically, it overrides the smart routing selection for that specific invocation.

### Can I override routing without editing the settings.json file?

Yes. Set the `OPENCLAUDE_SMART_ROUTING_SIMPLE` or `OPENCLAUDE_SMART_ROUTING_STRONG` environment variables for temporary overrides, or use the `--model` CLI flag if supported. These take precedence over file-based settings according to the hierarchy in [`src/utils/providerFlag.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerFlag.ts).

### Why am I seeing a warning about partial provider configuration?

The resolver at line 85 of [`src/services/api/agentRouting.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/agentRouting.ts) emits a warning when you provide only one of `base_url` or `api_key` in an `agentModels` entry. Both fields are required for cross-provider routing to function correctly.