How to Toggle Smart Routing in OpenClaude: A Complete Guide to the /smartroute Command

Use the /smartroute slash command to toggle smart routing in OpenClaude by running /smartroute on to enable, /smartroute off to disable, or set model keys with /smartroute simple <key> and /smartroute strong <key>.

OpenClaude, an open-source AI assistant interface from Gitlawb/openclaude, ships an experimental smart-routing layer that automatically directs each user turn to either a lightweight simple model or a more capable strong model based on query complexity. This feature is controlled through a configuration object stored under settings.smartRouting and exposed entirely through the /smartroute slash command interface.

What Is Smart Routing in OpenClaude?

Smart routing is an experimental optimization mechanism that reduces API costs and latency by classifying incoming requests and routing them to appropriately sized models. When enabled, the system consults src/services/api/smartRouting/index.ts (specifically the resolveSmartRoutingRoleModelString function) at runtime to select between the configured simple and strong model keys.

The configuration resides in your user settings and can be initialized with environment variables such as SMART_ROUTING_ENABLED, SMART_ROUTING_SIMPLE_MODEL, and SMART_ROUTING_STRONG_MODEL (read by src/services/api/smartRouting/settings.ts lines 34-68).

How to Toggle Smart Routing Using the /smartroute Command

The primary interface for managing this feature is the /smartroute slash command implemented in src/commands/smartroute/index.ts.

Checking Current Status

To view the current configuration without making changes, invoke the command without arguments:

/smartroute

The system calls readCurrentSmartRouting (lines 45-50) to read the persisted configuration via readSmartRouting(settings), then outputs the enabled flag, model keys, and any auto-disable status (lines 68-82). A typical response looks like:

Smart routing (experimental)
  status: enabled
  simple: mini
  strong: main
  available agentModels keys: default, my-custom

Enabling Smart Routing

To activate the feature, run:

/smartroute on

According to the source code at lines 87-96, this command sets enabled: true only if both the simple and strong model keys are already defined in the smartRouting block. It also clears any session-level auto-disable flags. The change persists through updateSettingsForSource('userSettings', …) (lines 58-66), which serializes the updated configuration to your user settings store.

Disabling Smart Routing

To deactivate the feature immediately:

/smartroute off

As implemented at lines 99-101, this writes enabled: false to the configuration object and persists the change to your user settings.

Configuring Model Keys for Smart Routing

Before enabling smart routing, you must define which models correspond to the "simple" and "strong" classifications using the available agent model keys from your configuration.

Setting the Simple Model

Assign the lightweight model for the simple routing tier:

/smartroute simple mini

This updates the smartRouting.simple entry in your settings file. The key must match an available model defined in your agent configuration.

Setting the Strong Model

Assign the high-capability model for complex queries:

/smartroute strong default

This updates the smartRouting.strong entry. Both keys must be set before the /smartroute on command will succeed.

Understanding the Configuration Architecture

When you issue toggle commands, OpenClaude performs several coordinated operations across its service layer:

1. Configuration Reading: The command handler invokes readCurrentSmartRouting which normalizes settings from src/services/api/smartRouting/settings.ts, including any environment variable defaults.

2. Persistence: All writes flow through updateSettingsForSource('userSettings', …) at lines 58-66 of the smartroute command file, ensuring atomic updates to the user settings store.

3. Runtime Enforcement: During actual query processing, src/services/api/smartRouting/index.ts exports resolveSmartRoutingRoleModelString, which consults the same smartRouting configuration block to determine which model string to use for the current turn.

4. Schema Validation: The TypeScript definitions in src/utils/settings/types.ts define the smartRouting schema within the global SettingsJson type, ensuring type safety across the configuration pipeline.

Summary

• Smart routing in OpenClaude automatically selects between simple and strong models based on query classification.
• Use /smartroute on and /smartroute off to toggle the feature, implemented in src/commands/smartroute/index.ts.
• Both model keys must be configured before enabling; set them with /smartroute simple <key> and /smartroute strong <key>.
• Configuration persists through updateSettingsForSource and is read at runtime by resolveSmartRoutingRoleModelString in the API service layer.
• Environment variables like SMART_ROUTING_ENABLED can provide default values as parsed by src/services/api/smartRouting/settings.ts.

Frequently Asked Questions

Why does /smartroute on fail with an error about missing model keys?

The enable logic at lines 87-96 explicitly validates that both simple and strong model keys exist in your configuration before setting enabled: true. You must define these first using /smartroute simple <key> and /smartroute strong <key> commands, ensuring the keys match available models in your agent configuration.

Can I configure smart routing via environment variables instead of commands?

Yes. The src/services/api/smartRouting/settings.ts file (lines 34-68) implements readEnvSmartRouting which reads SMART_ROUTING_ENABLED, SMART_ROUTING_SIMPLE_MODEL, and related variables. These provide default values that the /smartroute command can then override and persist to your user settings.

How does OpenClaude decide which model to use for each turn?

The routing decision occurs in src/services/api/smartRouting/index.ts through the resolveSmartRoutingRoleModelString function. This service reads the current smartRouting configuration and classifies the incoming query to return either the simple or strong model string, which the query engine then uses for the API request.

Where is the smart routing configuration stored after I run toggle commands?

All changes persist to your user settings file through the updateSettingsForSource('userSettings', …) helper at lines 58-66 of src/commands/smartroute/index.ts. This updates the smartRouting block within your global settings object, making the configuration available to the runtime resolver in subsequent sessions.

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