How to Configure Smart Routing in OpenClaude: A Complete Guide

Enable smart routing in OpenClaude by setting smartRouting.enabled to true in your settings file and defining the simpleModel and strongModel keys to automatically route short inputs to lightweight models and complex queries to stronger ones.

OpenClaude's smart routing feature automatically classifies each user turn and routes it to either a lightweight or powerful model based on input complexity. This optimization reduces costs for simple queries while preserving high-quality responses for complex tasks. According to the Gitlawb/openclaude source code, the entire routing pipeline is configured through a centralized settings object and resolved via src/services/api/smartRouting/resolveConfig.ts.

Understanding Smart Routing Logic

Smart routing operates by comparing each input against configurable thresholds for character or word count. When enabled, OpenClaude evaluates every turn and calls routeModel to determine whether to use the simple model (for short inputs) or the strong model (for everything else).

The resolution logic in src/services/api/smartRouting/resolveConfig.ts follows strict fallback rules:

• If smart routing is disabled, mis-configured, or the strongModel cannot be resolved, the system falls back to standard model resolution (smart routing is effectively disabled).
• If only the simpleModel fails to resolve, it collapses to the strongModel, meaning every turn routes to the strong model.

Configuring Smart Routing via Settings

The primary configuration method uses the global settings file. The schema is defined in src/utils/settings/types.ts and read via src/services/api/smartRouting/settings.ts.

Enabling the Feature

Set the enabled boolean to activate the router:

{
  "smartRouting": {
    "enabled": true
  }
}

Choosing Your Models

Specify the model keys (or bare model IDs) for both routing paths:

• smartRouting.simpleModel – The lightweight model for "simple" turns.
• smartRouting.strongModel – The fallback model for complex turns.

{
  "smartRouting": {
    "enabled": true,
    "simpleModel": "mini",
    "strongModel": "main"
  }
}

Setting Input Thresholds

Optionally limit simple turns by character count or word count. If a turn exceeds either limit, OpenClaude treats it as "strong" and routes to the strong model.

{
  "smartRouting": {
    "enabled": true,
    "simpleModel": "mini",
    "strongModel": "main",
    "simpleMaxChars": 300,
    "simpleMaxWords": 50
  }
}

Both thresholds are evaluated independently—exceeding either one triggers the strong model path.

Configuring Smart Routing via CLI

For temporary toggling without editing files, use the /smartroute command implemented in src/commands/smartroute/index.ts.

Turn smart routing on:

openclaude /smartroute on

Turn it off:

openclaude /smartroute off

This command updates the settings file directly, persisting your preference across sessions.

Programmatic Configuration Inspection

When building extensions or debugging, you can resolve the active configuration programmatically using resolveSmartRoutingConfig:

import { resolveSmartRoutingConfig } from './src/services/api/smartRouting/resolveConfig.js';
import { readSettingsFile } from './src/utils/settings/read.js';

const settings = await readSettingsFile('settings.json');
const routing = resolveSmartRoutingConfig({
  settings,
  parentModel: 'gpt-4o',
  permissionMode: undefined,
});

console.log(routing);
// → { enabled: true, simpleModel: 'mini', strongModel: 'main', ... }

This function performs the full normalization logic, including validation against the Zod schema defined in src/utils/settings/types.ts (lines 919-944).

Summary

• Smart routing automatically directs simple queries to lightweight models and complex queries to strong models based on input length.
• Configure the feature in settings.json using the smartRouting object with enabled, simpleModel, strongModel, and optional threshold fields.
• Use simpleMaxChars or simpleMaxWords to define what constitutes a "simple" turn.
• Toggle the feature interactively via the /smartroute CLI command.
• The resolution logic lives in src/services/api/smartRouting/resolveConfig.ts, which handles model key resolution and fallback scenarios.

Frequently Asked Questions

What happens if the simpleModel cannot be resolved?

If the simpleModel key fails to resolve but the strongModel is valid, the router collapses the simple path to the strong model. According to the source comments in src/services/api/smartRouting/resolveConfig.ts, this means every turn gets routed to the strong model, effectively disabling cost savings but maintaining functionality.

Can I use word count and character count limits together?

Yes. You can define both simpleMaxChars and simpleMaxWords simultaneously. If an input exceeds either threshold, OpenClaude classifies it as a strong turn and routes it to the strong model. This provides flexible guardrails for different types of content.

How do I disable smart routing temporarily?

Use the CLI command openclaude /smartroute off to disable the feature without deleting your configuration. The command updates your settings file and takes effect immediately on the next turn. To re-enable, run openclaude /smartroute on.

Where is the smart routing configuration schema defined?

The Zod schema that validates the smartRouting object— including fields for enabled, simpleModel, strongModel, simpleMaxChars, and simpleMaxWords—is located in src/utils/settings/types.ts at lines 919-944. This schema ensures type safety across the application's configuration layer.

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