Providers

A provider connects Orek to the service running your model. Configure its credentials and endpoint, then choose a model from Orek’s catalog. You can configure several providers and use routing to select between them.

By default, Orek stores provider API keys in your operating system’s credential store, not in plain-text configuration files.

Connect a provider

For OpenAI, Anthropic, Google, Mistral, or Kimi Code, add the provider or rotate its key inside Orek with:

/setup provider openai

Replace openai with anthropic, google, mistral, or kimi_code, or run /setup provider to pick from a list. It saves the provider settings and a reference to the stored key in your user config (or updates an existing project entry). Your saved model pin and theme stay unchanged; a temporary /model choice resets to your saved pin.

To run the full setup wizard, which also sets your default provider, model pin, and theme, run /setup; see Quickstart.

From a shell, this example prompts privately for an OpenAI key and stores it in your operating system’s credential store:

orek providers setup openai --scope user --credential-store keyring

The shell command also adds or updates the provider without changing your model or provider pins. A running Orek picks up the change when you restart it.

To use a key from your environment instead:

orek providers setup openai --scope user --credential-store environment --environment OPENAI_API_KEY --yes

This saves a ${OPENAI_API_KEY} reference, not the key itself; export the variable before launching Orek. Setting the variable alone does not add the provider. See credential storage.

Built-in providers

Orek has seven built-in providers. Any other service with an OpenAI-compatible API works as a provider you declare yourself; see Add your own model.

For each built-in provider, Orek supplies the endpoint and the details you would otherwise have to look up, such as which reasoning efforts each model accepts and how to use the provider’s prompt cache. Ollama is covered under Local models, and the gateway under Cloudflare AI Gateway.

The credential variables are the setup defaults. Keys saved in your operating system’s credential store do not need them.

Orek has no built-in provider for Vertex AI or Amazon Bedrock.

Endpoints and model families

The catalog describes each built-in model: its selector, context size, capabilities, and API. A catalog entry does not grant access or confirm that your account can use the model.

OpenAI’s built-in catalog includes openai/gpt-6-luna (default), openai/gpt-6-astra, and openai/gpt-6.1-sol (up to 922,000 input tokens in a 1,050,000-token window, with 2x input/cached-input and 1.5x output rates above 272,000 input tokens). Add a [[models]] entry for any model not in the catalog.

Open the picker to select a configured model:

/model

Run /model list for a summary of built-in and custom models, or orek models --json in your shell for JSON output.

Anthropic Claude

Claude accepts its earlier thinking back only while everything before it (the system prompt, the tools, and the earlier messages) is unchanged. Orek therefore keeps a Claude conversation’s history as it was and only adds to it, including with provider web tools on or off, in --no-tools turns, and in orek run --output-schema corrections. When a session setting such as the approval mode changes, Orek sends the update with your next message instead of rewriting the start of the conversation. When you resume a session saved by an earlier version of Orek, its first request leaves out Claude’s earlier thinking, and Orek tells you once.

If Anthropic still finds an earlier thinking block that no longer matches, providers.anthropic.prefix_mismatch_behavior decides what happens:

orek config set providers.anthropic.prefix_mismatch_behavior error

This setting is experimental. It applies to every request with thinking on, including Claude models you declared without reasoning controls, which think at the model’s default effort. At effort none (Claude Haiku 5.5 and Sonnet 5.5), Anthropic does not accept the setting, so your account’s default applies; for accounts created on or after 2026-08-31, that means Anthropic rejects such a request if a resent thinking block no longer matches.

orek session export lists each block Anthropic leaves out under dropped_thinking, with its position and the reason: prefix_binding_mismatch when the conversation before it changed, model_binding_mismatch when another Claude model wrote it, organization_binding_mismatch when another Anthropic account wrote it, or unrecognized for a reason Orek does not know. Orek also logs a warning for each one, except blocks from another Claude model, which are expected after a switch.

An Anthropic-compatible endpoint, set as providers.anthropic.base_url, may reject system messages in the middle of a conversation. For such an endpoint, turn them off:

orek config set providers.anthropic.inline_system_messages false

Then, when a session setting changes, your next message starts the conversation’s history over: Orek sends it with the updated system context and without Claude’s earlier thinking, and writes the conversation to the prompt cache again, which costs more for that request. Orek notes each restart. This setting is experimental.

For a Claude model you declared yourself on such an endpoint, you can instead set append_only = false under [models.reasoning.replay] (see Declare how a model takes back reasoning). Orek then rebuilds each request from the history, so during tool calls Anthropic leaves out earlier thinking under drop_block and rejects the request under error.

Google Gemini

Each model also has a -flex selector (google/gemini-3.8-flash-flex, google/gemini-4-argon-flex, google/gemini-3.5-flash-lite-flex) with a longer timeout and half-price input and output (cached input: $0.0375, $0.05, and $0.02 per 1M tokens).

Orek does not send temperature to Gemini models (see Google’s parameter changes). It also leaves out efforts a model does not support (none, or minimal on 3.8 Flash and 4 Argon), so Google’s default effort applies. Gemini 4 Argon shares its 1,048,576-token window between input and output, with at most 65,536 output tokens.

Mistral

All built-in Mistral models use Mistral’s Responses API at https://api.mistral.ai/v1, with up to 128,000 output tokens, several tool calls at once, and prompt caching for prompts of 64 tokens or more. Mistral has no provider web tools on this API. Mistral models you declare in [[models]] can use Chat Completions instead.

Mistral does not support effort none on GLM 5.3, so with a session effort of none, Orek sends GLM 5.3 and GLM 5.3 Flash no effort and Mistral’s default applies.

Kimi Code

Kimi Code uses a membership plan rather than pay-per-token billing. Run /setup provider kimi_code (or orek providers setup kimi_code), or add this block to your user config.toml:

[providers.kimi_code]
api_key = "${KIMI_CODE_API_KEY}"

Orek sends requests to https://api.kimi.com/coding/v1. Kimi documents https://api.kimi.ai/coding/v1 for members outside China; to use it, add base_url = "https://api.kimi.ai/coding/v1" to the same table.

Plus (Moderato) keys are limited to 262,144 tokens and Kimi rejects larger requests with HTTP 401, so kimi_code/k3-256k is the default. Select a 1M or highspeed model on Pro (Allegretto) plans and above. Orek sends only the efforts listed in the table; for any other session effort, Kimi’s model default applies (see the Kimi Code models page).

Kimi models can return several tool calls at once, and Orek runs them together; see Tool calls in one response.

While it thinks, Kimi requires each earlier tool call to come with reasoning. Orek sends Kimi’s own earlier reasoning back and adds an empty reasoning value to tool calls that have none, such as calls another model made before you switched to Kimi. With thinking off (kimi_code/kimi-for-coding at effort none), Orek adds no empty values but still sends Kimi’s own reasoning back. See What each provider receives.

Kimi Code credentials and endpoints are separate from Moonshot Open Platform and from Kimi models served through Cloudflare.

Provider web tools

Provider web tools are web search and page fetching that the model provider runs on its own servers. Orek has no web search of its own. For page fetching, Orek uses the provider’s tool when one is enabled, or its own webfetch tool otherwise, subject to your permissions.

Provider web tools are on by default for openai, anthropic, and google on all their built-in models. Mistral’s built-in models have none.

You can turn these tools off or change them per provider or per model in your user or project configuration ([] turns them off for that provider or model), then start a new session:

[providers.openai.provider_tools]
enabled = []

[providers.anthropic.provider_tools.models]
"anthropic/claude-haiku-5-5" = ["web_search"]

• Model support: A provider’s enabled list applies to each of its models that has no entry under models. New models you declare yourself get none, and Orek refuses to load a configuration that lists these tools for a model that does not support them.
• Disabling tools: --no-tools turns off both Orek’s tools and provider web tools.
• Configuration and URL policy: See the configuration reference for provider-specific options and limits. Setting permissions.url_allowlist turns provider web tools off; see URL policy.
• Failed responses: A response that fails after a provider web search, page fetch, or citation is saved as an incomplete answer and is not retried, so you do not pay for that work twice. A response that fails before any such work and before showing you anything is handled like any other failed request: a temporary failure is retried.
• Usage and billing: Provider web search can be billed separately from tokens. When a provider reports web tool usage, orek run --json includes provider_tool_requests in its usage, and marks the USD cost as incomplete when that search has no known price.

Cloudflare AI Gateway

Cloudflare AI Gateway is built in and becomes active when CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are set in your environment. To set the gateway name or routes explicitly, add this block to your user config.toml:

[providers.cloudflare_ai_gateway]
provider_type = "cloudflare_ai_gateway"
api_key = "${CLOUDFLARE_API_TOKEN}"
cloudflare_account_id = "${CLOUDFLARE_ACCOUNT_ID}"
cloudflare_gateway_name = "default"
cloudflare_enabled_routes = ["workers-ai/v1"]

Without an explicit route, Orek uses workers-ai/v1, and the base URL is https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/workers-ai/v1. Use your gateway’s actual name; Orek uses default when none is set.

For an authenticated gateway, also supply its token in cloudflare_aig_token, for example cloudflare_aig_token = "${CLOUDFLARE_AIG_TOKEN}" in the same table. This is separate from api_key.

Built-in Workers AI models

Both models need the Workers Paid plan or prepaid AI Gateway credits. Cloudflare limits each to 20 requests per minute per account per model, or 50 with credits.

Workers AI cannot turn GLM 5.3 reasoning off, and runs none, minimal, medium, and xhigh at max. Orek therefore offers only low, high, and max for this model; any other session effort runs at max.

Add another Workers AI model

Declare any other Workers AI text model in [[models]] on the workers-ai/v1 route. This example adds DeepSeek V4 Pro:

[[models]]
id = "cloudflare_ai_gateway/workers-ai/deepseek-v4-pro"
provider = "cloudflare_ai_gateway"
display_name = "DeepSeek V4 Pro (Workers AI)"
api_model_id = "@cf/deepseek-ai/deepseek-v4-pro-0813"
provider_route = "workers-ai/v1"
endpoint_family = "workers_ai_v1"
context_window = 1048576
supports_tools = true
supports_streaming = true
capability_source = "user_override"
capability_confidence = "high"
billing = "openai"

[models.pricing]
input_per_million_usd = 1.32
cached_read_per_million_usd = 0.044
output_per_million_usd = 3.96

[models.reasoning]
control = "controllable"
allowed_efforts = ["none", "low", "high", "max"]
default_effort = "high"
supports_tools_with_reasoning = true

endpoint_family = "workers_ai_v1" keeps a conversation on the same Workers AI server so it can reuse the prompt cache. billing = "openai" tells Orek that Workers AI already counts cached tokens in the prompt total, so cost reports do not count them twice. List in allowed_efforts only the efforts the model accepts on Workers AI; see Reasoning efforts.

Other providers through the gateway

cloudflare_ai_gateway also supports the compat, openai, and responses routes when you add matching [[models]] entries. On compat and workers-ai/v1, api_key holds a Cloudflare token. On openai and responses, api_key is passed to OpenAI; use cloudflare_aig_token to authenticate with the gateway.

The compat route reaches other providers’ models through Cloudflare’s OpenAI-compatible endpoint, which names each model as provider/model. Add compat to the enabled routes and declare the model. This example runs Mistral Medium 3.5 through the gateway:

[providers.cloudflare_ai_gateway]
cloudflare_enabled_routes = ["workers-ai/v1", "compat"]

[[models]]
id = "cloudflare_ai_gateway/compat/mistral/mistral-medium-3-5"
provider = "cloudflare_ai_gateway"
display_name = "Mistral Medium 3.5 (AI Gateway)"
api_model_id = "mistral/mistral-medium-3-5"
provider_route = "compat"
endpoint_family = "chat_completions"
context_window = 256000
supports_tools = true
supports_streaming = true
capability_source = "user_override"
capability_confidence = "high"

Without cloudflare_aig_token, the compat route sends api_key as the gateway credential, and the gateway must pay the upstream provider through Cloudflare unified billing or a provider key stored in the gateway. A model without a [models.reasoning] block is sent no reasoning effort.

Add your own model

Declare an OpenAI-compatible service and add one of its models to the catalog:

[providers.example]
provider_type = "openai_compatible"
base_url = "https://llm.example.com/v1"
api_key = "${EXAMPLE_API_KEY}"

[[models]]
id = "example/coder-large"
provider = "example"
api_model_id = "coder-large"
context_window = 262144
supports_tools = true
supports_streaming = true
capability_source = "user_override"
capability_confidence = "high"

id is the selector Orek displays, provider names the provider table, and api_model_id is the name the service expects. Only id, provider, and context_window are required, but agent work normally needs an accurate supports_tools: a model without it runs without tools when you pick it, and Orek says so once per session. A capability setting describes the model; it does not add the capability.

A custom entry with a built-in model’s ID replaces that catalog entry and inherits some of its fields. See Custom model definitions for inheritance, every model field, pricing, reasoning, API selection, and prompt-cache settings. For a server on your machine, use Local models.

The configuration reference describes tool calls in one response, malformed tool calls, prompt-length pricing, API fields for built-in providers, reasoning efforts, and reasoning replay fields. Ollama and llama.cpp setup discovers the served model, loaded context and advertised capabilities, writes model rows, and preserves existing rows. Both have typed local profiles; vLLM and LM Studio profiles also apply local timeouts and a default limit of one active request per connection. See Local models for setup and manual metadata options.

Grok through xAI

Orek has no built-in xAI provider or Grok models. xAI’s API accepts OpenAI-compatible Chat Completions requests, so you can declare it as a compatible provider and describe each Grok model you use. Merge this example into your user config (find it with /config path), and supply XAI_API_KEY through your environment:

[providers.xai]
provider_type = "openai_compatible"
base_url = "https://api.x.ai/v1"
api_key = "${XAI_API_KEY}"

[[models]]
id = "xai/grok-4.6"
provider = "xai"
display_name = "Grok 4.6"
api_model_id = "grok-4.6"
quality_tier = "Frontier"
latency_class = "Medium"
context_window = 500000
max_output_tokens = 128000
supports_tools = true
supports_parallel_tools = true
supports_streaming = true
supports_vision = true
capability_source = "user_override"
capability_confidence = "high"
billing = "openai"

[models.pricing]
input_per_million_usd = 2.00
cached_read_per_million_usd = 0.50
output_per_million_usd = 6.00

[models.reasoning]
control = "controllable"
allowed_efforts = ["low", "medium", "high", "xhigh"]
default_effort = "high"
supports_tools_with_reasoning = true

[models.prompt_cache]
key = "header_grok_conversation"

Orek does not maintain this example. Before relying on it, check xAI’s model documentation for current model IDs, context sizes, prices, and reasoning efforts, and add a [[models]] entry for each other Grok model you want.

key = "header_grok_conversation" sends xAI the Orek conversation ID so a conversation’s requests can reuse xAI’s prompt cache. Without a [models.prompt_cache] table, no cache key is sent.

supports_parallel_tools = true lets Orek run the tool calls Grok returns in one response together; see Tool calls in one response.

Switching models and providers

You can change the model in the middle of a conversation: with /model, through routing, by a provider fallback, or by resuming a session with another --model. The new model always gets your messages, the earlier answers, and every tool call and result. What can differ is earlier reasoning: the thinking a model returned, which providers often sign or encrypt so that only they can read it.

Orek never passes earlier reasoning to another model as ordinary message text. It reaches the new model only if the new model’s API has a field for it; otherwise it is not sent.

Switching during a web search

If Claude is in the middle of a step that uses its provider web tools when you switch models, Orek hands the step to the new model instead of stopping. The TUI shows one line as you pick, for example “the current Claude Haiku 5.5 step will close; GPT-6 Luna continues it”. The same happens when Orek falls back to another model because Claude is unavailable.

The new model gets what Claude found so far: its text, the searches it ran, the pages it used, and up to 8,000 characters of each page it fetched. It can search or fetch again if it needs more. Messages you typed during the step are kept. A search that had not returned yet is marked “step closed; results unavailable”.

Preserve or drop earlier reasoning

The agent.reasoning_replay setting chooses what happens to reasoning from before a switch:

Orek fixes the method when a new model takes over, and keeps it until the next switch. A change to the setting therefore applies at the next switch, and the current model never sees its own history change. A resumed session keeps its method; resuming on another model counts as a switch and uses the current setting. Only finished turns carry reasoning across a switch: reasoning from a turn that failed, was interrupted, or hit the output limit stays with the model that produced it.

This setting is experimental: drop stays the default while preserve is being evaluated. Save a method with:

orek config set agent.reasoning_replay preserve

Inside Orek, /config set agent.reasoning_replay preserve saves it too. To choose a method for one process, pass the global --reasoning-replay flag (preserve or drop) to orek, orek chat, orek run, or orek acp. It overrides the saved setting for that process, including every session an orek acp server runs. See the [agent] settings.

What each provider receives

Under both methods, other providers’ turns reach the new model as their text, tool calls, and tool results. Reasoning from the current model, since it took over, is sent back whenever its API accepts reasoning.

• OpenAI: Orek asks OpenAI not to store your requests and sends encrypted reasoning back itself, so GPT-6 reasoning carries over with or without provider web tools. Other Responses servers that return signed reasoning, such as Ollama’s, get back only the same model’s reasoning.
• Chat Completions servers: a model gets reasoning back only when its entry declares a reasoning field; see Reasoning replay fields.
• Prompt cache: each model has its own cache, so the first request after a switch pays full price for its input. Under preserve, switching back to a Claude model can reuse its earlier cache.

Reasoning not carried over yet

Some hand-offs are not turned on yet because they have not been confirmed with the provider. Under preserve they behave as under drop, and /context lists what they left out as “not verified yet”:

• Gemini: reasoning between different Gemini models, and other providers’ reasoning.
• Kimi Code: other providers’ reasoning.
• Mistral (Chat Completions models declared without reasoning replay fields): the model’s own earlier thinking, reasoning between different Mistral models, and other providers’ reasoning.
• OpenAI: reasoning summaries, and web search results between different GPT-6 models.
• Chat Completions servers: reasoning sent back to a model whose entry declares no reasoning field, and other models’ reasoning.

To turn one on for a model you have tested yourself, declare the reasoning replay fields in its model entry.

Unfinished Claude turns

Anthropic accepts a thinking block only while the history before it is what Claude saw when it wrote the block, and Orek cannot restore a block once it has left it out. So under preserve:

• If the last Claude turn before the switch did not finish, its thinking is left out; its text and tool calls are still sent.
• If more Claude turns followed an unfinished one before the switch, all of Claude’s earlier thinking is left out, as under drop.
• Thinking from before a stretch of the conversation that ran under drop is never sent again.

A different set of tools at the switch, for example from per-model tool settings, also leaves out earlier thinking. If a block Orek sends back still fails Anthropic’s check, prefix_mismatch_behavior decides whether Anthropic leaves it out or rejects the request. Under preserve, if a Claude model’s model guidance differs, Orek sends the new guidance with your next message.

See what a switch did

• The line under your message names the new model and what happened to earlier reasoning, for example openai/gpt-6-luna · earlier reasoning dropped (drop).
• /context lists what the latest request sent back, passed on from another model, filled with an empty value, or dropped, and why. /usage shows token use and cost for each model, in the order they took over. See After a model switch.
• The session keeps a record of each switch and each request, which orek session export includes; see Troubleshooting & diagnostics.

Compare the two methods

A forked session continues from identical history, so you can compare the two methods after the same switch:

1. Work until the point where you want to switch models, then quit Orek.
2. Fork the session with orek session fork <ID>, which prints a new ID.
3. Resume the original with --reasoning-replay drop and the fork with --reasoning-replay preserve, both with --model set to the new model, and give both the same next prompt.
4. Compare the answers, /usage, and /context.

Everything before the switch is identical, so the differences come from the method. Forking a session shows the commands and what a fork keeps.

Check the connection

Use these commands for different checks:

orek providers, orek models, and /model list treat a provider as configured when its ${VAR} variable is set or its key is saved in your credential store; they do not contact the provider. If the variable is unset in the current shell or the saved key is missing, the provider is shown as unavailable until you export the variable or run orek providers setup. Use orek providers check or /doctor to test the live connection.

A successful check shows that the endpoint is reachable, not that every model or tool call will work. A gateway that offers no way to list models can show as degraded, because Orek will not run a paid request just to test it. Real failures still appear when you use a model.

The catalog ships with Orek and is combined with your configuration. Update Orek for new built-in models, or add your own model when you need one that is missing.

After setup, select a model with /model, ask it to explain a project file, and check the result. Provider setup saves connection settings; the model picker changes only the current session.

Next, choose and route models. Embedding providers are configured separately from your chat model.