How to Configure Agent Routing and Model Overrides in OpenClaude

You can configure agent routing and model overrides in OpenClaude through the 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.

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, 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:

{
  "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 at line 85, the routing logic validates these fields and warns when only one is present:

{
  "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 at line 14, these keys resolve through the same agentModels registry:

{
  "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 recognizes specific environment variables. Set OPENCLAUDE_SMART_ROUTING_SIMPLE to override the simple-turn model key, or OPENCLAUDE_SMART_ROUTING_STRONG for complex turns:

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 and applied in src/utils/providerFlag.ts at line 321.

The resolution flow in src/services/api/agentRouting.ts executes as follows:

1. Load merged settings from 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:

{
  "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, this parameter forces the sub-agent to use a specific model key regardless of the parent agent's configuration:

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

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

Why am I seeing a warning about partial provider configuration?

The resolver at line 85 of 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.

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