Routing recipes

This guide assumes you have a working model provider and at least one tool can make a request through OcHub. Each recipe adds only one layer so its effect is visible in the request log.

Understand the decision order

A request through the gateway:

1. Identifies the client protocol: Anthropic Messages, OpenAI Chat, or OpenAI Responses.
2. Finds the model provider connected to that app.
3. Matches the client model against the first applicable exception.
4. Chooses the upstream model name.
5. Builds candidates from enabled interfaces.
6. Prefers the client’s native interface, then tries convertible alternatives.
7. Maps or removes reasoning parameters.
8. Records request model, upstream model, pricing model, tokens, status, and latency.

Enter an upstream origin or custom prefix as the model provider’s API address, not a standard inference endpoint. If the final endpoint is https://api.example.com/v1/messages, normally enter https://api.example.com. OcHub appends the path for the selected interface.

Model-name precedence

An exception that only forces an interface and leaves the model blank bypasses the default model. This is useful for protocol constraints but can surprise you when you expected a global model override.

Patterns support *, such as claude-*, *-reasoning, or gpt-*-mini. The first matching rule wins, so put exact models before broad patterns.

Recipe 1: rewrite a client alias

Goal: let the client request claude-sonnet-current while the upstream receives anthropic/claude-sonnet-4-6.

1. Edit the model provider and expand Model exceptions.
2. Add an exception.
3. Set Model or pattern to claude-sonnet-current.
4. Set Upstream model to anthropic/claude-sonnet-4-6.
5. Leave Interface on Automatic.
6. Save and make a request with the alias.
7. In request details, compare Request model, actual Model, and Pricing model.

Some upstreams echo the client alias even after rewriting. Compare OcHub and provider-side logs when needed.

Recipe 2: use a Chat-only upstream from Codex

Goal: Codex sends Responses requests, while the commercial upstream exposes only Chat Completions.

1. Add or edit a model provider.
2. Enter the Chat upstream base without /v1/chat/completions.
3. Enable only OpenAI Chat.
4. Switch Codex onto the model provider from its app page.
5. Add no model exception initially; let automatic routing convert Responses to Chat.
6. Restart Codex and send a short request that does not depend on special Responses features.
7. Check status, model, and output in Usage.

Ordinary requests can be converted, but:

• Codex remote compaction requires a Responses upstream.
• Responses-only fields may be removed or may not have an exact equivalent.
• Tool calls, structured output, and reasoning depend on upstream behavior.

If the provider later adds Responses, detect and enable it. Automatic routing will prefer the native interface.

Recipe 3: pin model families to interfaces

Goal: Claude models use Messages and GPT models use Responses on one upstream.

Enable both real interfaces, then add:

The rules constrain only the protocol and preserve the model names. Use this when provider documentation recommends one endpoint, a model exists only on one endpoint, or tool calls fail on an otherwise responsive interface.

An exception cannot reference an interface you disable.

Recipe 4: one-model upstream

If every client request should become company-model-v2, set:

Default model: company-model-v2

Do not also add a catch-all * exception. A default already covers requests that do not match an exception.

Defaults fit a one-model internal gateway or a client whose default cannot be changed. They are a poor fit when you need model choice, want misspellings to surface, or models have very different prices.

Recipe 5: rewrite model and interface together

To send all claude-* aliases to an OpenAI Chat model:

This combines model rewrite and Messages-to-Chat conversion. Test plain text first, then tools. To isolate a failure, temporarily return Interface to Automatic to verify the model, then pin Chat again.

Recipe 6: normalize reasoning effort

The four automatic budgets must be positive and ascending:

1. Check upstream minimum, common, and maximum budgets.
2. Give Low the smallest useful value.
3. Increase Medium, High, and Maximum without exceeding the limit.
4. Verify Medium first.
5. Compare latency, output, and token use before tuning the others.

Higher reasoning budgets can increase both time to first token and billed output or reasoning tokens.

Recipe 7: prepare a backup model provider

OcHub automatically selects and retries enabled interfaces inside one model provider. It does not automatically move from one card to another.

1. Create Primary and Backup model providers.
2. Verify both with detection and a real request.
3. Configure equivalent aliases.
4. Keep the app on Primary normally.
5. During an outage, switch it manually to Backup.
6. Make a short request and inspect the log.
7. Switch back after recovery.

Do not change protocols, mappings, budgets, and pricing simultaneously during an outage. Restore a working path first.

Verify with request logs

Change one variable per test and use a recognizable short prompt.

Diagnosis table

After rules stabilize, apply the model provider to other tools one at a time and make a real request from each protocol.