# How to Configure Smart Routing in OpenClaude: A Complete Guide

> Configure smart routing in OpenClaude by enabling it in your settings and defining models for efficient input handling. Optimize your AI for speed and accuracy.

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

---

**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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/settings/types.ts) and read via [`src/services/api/smartRouting/settings.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/smartRouting/settings.ts).

### Enabling the Feature

Set the `enabled` boolean to activate the router:

```json
{
  "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.

```json
{
  "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.

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

Turn smart routing on:

```bash
openclaude /smartroute on

```

Turn it off:

```bash
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`:

```typescript
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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/settings/types.ts) at lines 919-944. This schema ensures type safety across the application's configuration layer.