Model Routing

Model routing decides which provider serves each model Amp uses. By default Amp serves every model and bills your Amp credits. You can add your own connections so that some or all models go through your own API keys, subscriptions, or gateways instead, and your provider bills you directly.

Manage your connections in Model Routing in your personal settings. Workspace admins manage shared connections for every member in Workspace Model Routing. The same operations are available from the CLI with amp config model-providers and from Puck, which can list, add, test, reorder, and edit your connections when you ask.

Tip: We strongly recommend letting Amp or Puck configure your model routing for you, since they can try a configuration, test it, and fix it in a tight loop, which saves you a lot of time compared with working through the details by hand.

Connections

A connection is one credential plus its settings. There are three kinds:

  • API keys for a single provider, such as Anthropic, OpenAI, or xAI. Usage bills to your account with that provider.
  • Subscriptions, such as a ChatGPT or đť•Ź Premium+/SuperGrok subscription. You sign in through your browser, and usage counts against the plan’s limits. See Use a ChatGPT Subscription.
  • AI model routers and gateways, such as OpenRouter, Vercel AI Gateway, Cloudflare AI Gateway, Ollama Cloud, OpenCode Go, and any OpenAI- or Anthropic-compatible endpoint through a Custom URL connection. These can serve models from many providers through one credential. AI model routers and gateways are experimental and in early access for Megawatt, Gigawatt, and Enterprise customers only. We will roll them out to everyone soon.

The Add menu in Model Routing lists the connection types available to you. Personal connections apply to your own threads. Workspace connections apply to every member’s threads, and Enterprise workspace admins can forbid personal connections so that only the workspace’s apply. See Workspaces.

Each connection has a Check Access button that verifies the credential with the provider. From the CLI, amp config model-providers test <connection-id> does the same, and amp config model-providers check-access --provider-model <provider/model> runs one short inference and reports which connection actually served it.

Precedence

For each model, Amp tries your connections in order and uses the first active one whose model mapping includes that model. Anything no connection serves is served by Amp.

The order is:

  1. Your personal connections, from top to bottom as listed in Model Routing.
  2. Your workspace’s connections, from top to bottom.
  3. Amp.

Within a list, the order is the connection’s priority: 0 is tried first. Drag a connection by its handle in Model Routing to move it, or set its priority directly:

amp config model-providers list
amp config model-providers set-priority <connection-id> 0

Setting a priority that another connection already has moves that connection and the ones after it down one place, so 0 always means “try this connection first”. list and list --json show the current priority of each connection.

Two connections often cover the same model, for example a ChatGPT subscription and an OpenRouter router that both include openai/gpt-5.6-sol. The one higher in the list wins. To send only some models to a lower connection, exclude them from the higher connection’s model mapping rather than reordering.

The routing graph below the connection list shows which connection serves each model, so you can confirm the result after changing the order or a mapping.

Activate and Deactivate

Inactive connections are skipped during routing but keep their settings, so you can switch a connection off and on without re-entering its key. Expand the connection in Model Routing and use Activate or Deactivate, or:

amp config model-providers activate <connection-id>
amp config model-providers deactivate <connection-id>

For API keys and subscriptions, only one connection per provider is active at a time: activating one deactivates the others of that provider. Any number of AI model routers and Custom URL connections can be active at once.

Deactivating a subscription can cost more than it saves, because Amp then serves those models with your credits. The CLI asks for --yes before it deactivates a subscription.

Model Mappings

A model mapping controls which models a connection serves and, for routers and Custom URLs, what model ID the provider receives. Leave it empty to use the connection type’s default: for most types, every model the provider supports. Google Cloud Agent Platform and Amazon Bedrock connections serve no models until you choose some.

Write one pattern per line, using Amp’s canonical model IDs in provider/model form. The Models picker in the connection form searches the catalog and inserts an ID for you.

*/*                                   # include every model
-anthropic/*                          # then exclude all Anthropic models
anthropic/claude-fable-5              # but re-include this one
moonshotai/kimi-k3 -> kimi-k3-turbo   # include, and send kimi-k3-turbo to the provider
  • # starts a comment; blank lines are ignored.
  • * is allowed only at the start or end of a pattern: openai/*, *-mini, or */*.
  • A leading - excludes matching models.
  • The last matching line wins. Models that match no line are not served by the connection.
  • An exact include line may end with -> providerModelID to override the model ID sent to the provider. The line still takes part in matching. Arrows are not allowed on wildcard or exclude lines. Without an arrow, the connection type’s default provider model ID is used.

From the CLI, pass the same patterns comma- or newline-separated with --model-mapping, or --clear-model-mapping to return to the default:

amp config model-providers edit-router <connection-id> --model-mapping "*/*,-openai/gpt-5.4"
amp config model-providers edit-key <connection-id> --model-mapping "anthropic/claude-opus-4-6"

The connection form and show report nonblocking warnings about a mapping, for example a line that names a model the provider does not offer or an option the provider requires for it. A warning does not stop the connection from being saved or used.

Custom URL Connections

A Custom URL connection speaks one of three API formats. Enter the base URL, and Amp appends the API path for the format:

  • chat-completions (OpenAI Chat Completions API, the default) sends requests to <base URL>/chat/completions.
  • responses (OpenAI Responses API) sends requests to <base URL>/responses.
  • anthropic-messages (Anthropic Messages API) sends requests to <base URL>/v1/messages. A base URL that already ends in /v1 is accepted and not doubled.

For example, a base URL of https://api.example.com/v1 with chat-completions sends requests to https://api.example.com/v1/chat/completions, while https://api.example.com with anthropic-messages sends them to https://api.example.com/v1/messages. The connection form shows the exact request URL as you type. Amp warns if the base URL already contains the API path.

The key is sent as Authorization: Bearer <key> in every format. Use the Headers and Query Parameters settings, or --headers and --query-params in the CLI, when a provider needs anything else on each request.

Check Access on a Custom URL connection lists the provider’s models when the mapping is broad, and sends a one-token request for the mapped model when the mapping names exactly one model. Providers that respond to an invalid key with an HTTP 200 body containing an error are reported as failures with the provider’s message.