OpenAI-compatible endpoints

Many model hosts and local servers accept requests in the format of OpenAI’s Chat Completions API. You can add any of them to o4 as a custom provider: a hosted service such as Together AI, a company gateway, or a server on your own machine. You describe the provider and its models in ~/.o4/providers.toml, and o4 treats them like built-in models. o4 sends each request to <base_url>/chat/completions, the same route OpenAI’s API uses. The endpoint must support that route. Endpoints that only offer OpenAI’s newer Responses API don’t work as custom providers.

Add a provider

Describe the provider and its models

Create ~/.o4/providers.toml:

~/.o4/providers.toml

[[providers]]
id = "together"
name = "Together AI"
api_key_env = "TOGETHER_API_KEY"
base_url = "https://api.together.xyz/v1"

[[providers.models]]
id = "Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8"
name = "Qwen3 Coder 480B"
context_window = 262144
max_tokens = 32768

Give o4 the key

Export the variable you named in api_key_env:

export TOGETHER_API_KEY="your-key"

Or store the key in o4: open /config providers, set Provider to together, and fill in API key. A stored key takes precedence over the environment variable.

Check that o4 sees the models

o4 --list-models

Provider: together
  Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8 (context: 262k, max_tokens: 32768, input: text, reasoning: no)

Start a session with the model

o4 -m together:Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8

You can also pick it from /model during a session.

o4 reads providers.toml when it starts, so restart o4 after you edit the file.

If any entry in providers.toml has a TOML error or is missing a required field, o4 skips the whole file. It also skips the file if other users can write to it. o4 records the reason in ~/.o4/o4.log. If your models don’t show up in o4 --list-models, look there first.

Provider fields

Each [[providers]] table defines one provider. You can define as many as you like in the same file.

Field	Required	Description
`id`	Yes	Provider ID. Use it in model references such as `id:model`. Don’t use `groq`, `mistral`, `openrouter` or `cohere`: o4 removes providers with those IDs, so their models never appear.
`name`	Yes	Display name, used in error messages.
`api_key_env`	Yes	Name of the environment variable that holds the key.
`base_url`	Yes	API root, without `/chat/completions`. For most services this ends in `/v1`.
`auth_header`	No	Header that carries the key. Default: `Authorization`.
`auth_format`	No	Header value. `{key}` is replaced with the key. Default: `Bearer {key}`.

For a service that expects the key in a different header, change both auth fields:

auth_header = "api-key"
auth_format = "{key}"

Every custom provider needs a key, either stored in o4 or in the api_key_env variable. If the endpoint doesn’t check keys, set the variable to any placeholder value. Choose an id that isn’t already a built-in provider ID such as openai or anthropic. See Providers and API keys for the built-in list.

Model fields

Each [[providers.models]] table after a provider adds one model to it.

Field	Required	Default	Description
`id`	Yes		Model name the endpoint expects. o4 sends it unchanged.
`name`	Yes		Display name.
`context_window`	No	`0`	Context window in tokens.
`max_tokens`	No	`0`	Maximum output tokens. `0` leaves it to the endpoint.
`input`	No	`["text"]`	Input types: `"text"`, and `"image"` if the model accepts images.
`reasoning`	No	`false`	Whether the model produces reasoning. See Reasoning.
`cost`	No	all `0`	Prices in US dollars per million tokens: `input`, `output`, `cache_read`, `cache_write`.
`compat`	No		Request adjustments for endpoints that reject some fields. See below.

Always set context_window to the model’s real limit. o4 uses it to track how full the context is and to decide when to compact the conversation, and the default of 0 means o4 doesn’t know the limit. See Context and cost. Set cost if you want cost totals to reflect this provider:

[providers.models.cost]
input = 0.30
output = 1.20

Adjust requests for strict endpoints

By default o4 sends the usual Chat Completions fields: stream, max_tokens, temperature and tools, when it has values for them. Some endpoints reject fields they don’t support. The compat table on each model controls what o4 sends. The simplest control is an allowlist. When supported_parameters is set, o4 sends only the listed fields:

[providers.models.compat]
supported_parameters = ["stream", "max_tokens", "tools"]

Value	Effect
`stream` or `streaming`	Send `stream: true`.
`max_tokens`	Send `max_tokens`.
`temperature`	Send `temperature`.
`tools`, `tool_choice` or `function_call`	Send the tool definitions.
`reasoning_content` or `reasoning`	Send the model’s earlier reasoning back in the conversation.
`reasoning_effort`	Send a reasoning effort. See Reasoning.

o4 is a coding agent, and it can only read and edit files through tools. If the endpoint can’t take tool definitions, the model can talk but can’t act on your code. Keep tools in the list unless you’re sure.

Instead of the allowlist, you can turn single fields on or off with booleans:

[providers.models.compat]
supports_streaming = true
supports_max_tokens = true
supports_temperature = false
supports_tools = true
supports_reasoning_content = false
supports_reasoning_effort = false

If you set both, supported_parameters wins. Some servers render chat templates that expect tool-call arguments as a JSON object rather than the JSON string OpenAI uses. They fail with errors such as Can only get item pairs from a mapping. For those, add:

[providers.models.compat]
tool_call_arguments_object = true

When the endpoint returns 400 or 422, the error in o4 lists the fields o4 sent and your compat settings, and suggests a supported_parameters fix. Use it to find the field to drop.

Reasoning

reasoning = true tells o4 the model produces reasoning. By itself, it doesn’t make o4 send a reasoning effort. To let you choose an effort, declare the levels the endpoint accepts, lowest first:

[providers.models.compat]
supports_reasoning_effort = true

[providers.models.compat.reasoning]
efforts = ["low", "high"]

Valid levels are minimal, low, medium, high, xhigh and max. With supports_reasoning_effort turned on, o4 sends a top-level reasoning_effort field and an extra_body field that turns thinking on. That request shape follows Moonshot’s API, so check that your endpoint accepts it. The field only takes low, high or max: minimal and low go out as low, medium and high as high, and xhigh and max as max. A level the model doesn’t declare first becomes the highest declared level below it. When the reasoning level is default, or the model declares no efforts, o4 sends no reasoning_effort and asks the endpoint to turn thinking off. Without an efforts list, the reasoning setting only offers default.

A complete example

This provider accepts only a few fields, supports reasoning, and needs tool arguments as objects:

~/.o4/providers.toml

[[providers]]
id = "xiaomi"
name = "Xiaomi MiMo Token Plan"
api_key_env = "MIMO_API_KEY"
base_url = "https://token-plan-sgp.xiaomimimo.com/v1"

[[providers.models]]
id = "MiMo-V2.5-Pro"
name = "MiMo V2.5 Pro"
reasoning = true
input = ["text"]
context_window = 258000
max_tokens = 8192

[providers.models.compat]
supported_parameters = ["stream", "max_tokens", "tools"]
supports_reasoning_content = false
tool_call_arguments_object = true

export MIMO_API_KEY="your-token-plan-key"
o4 -m xiaomi/MiMo-V2.5-Pro

Add a provider from the interface

You can also create the provider entry from inside o4. Open /config providers and press a, or choose Add custom provider. The wizard asks for:

Provider ID: 2 to 32 characters, lowercase letters, digits and hyphens, starting with a letter or digit.
Base URL: must start with https://, http://localhost:, or http://127.0.0.1:.
API key environment variable: uppercase letters, digits and underscores, starting with a letter, such as FIREWORKS_API_KEY. The confirm screen shows whether that variable is set.

/config providers add and /add-provider open the Providers tab with the cursor on Add custom provider; press Enter to start the wizard. If the ID is already a custom provider, o4 shows Provider '<id>' already exists and saves nothing. When you save, o4 appends the provider to ~/.o4/providers.toml and shows Provider '<id>' added. Add models by editing ~/.o4/providers.toml. The wizard doesn’t add models, so the provider has none until you add [[providers.models]] entries by hand. The wizard also uses the ID as the display name and the default auth header; edit the file to change them.

Model references with slashes

Many hosted model IDs contain a slash, such as Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8. All of these work:

o4 -m together:Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8
o4 -m together/Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8
o4 -m Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8

The bare ID works as long as no other provider has a model with the same ID. Use the provider: prefix to be sure.

How custom providers differ from built-in ones

System prompt. o4 treats custom providers as unknown models: it picks the legacy-guided prompt profile and adds extra guidance meant for smaller local models. You can override the profile with --prompt-profile. See Reasoning and prompt profiles.
Key privacy. o4 removes the api_key_env variable of every custom provider from the environment of commands it runs for the model, the same as built-in provider keys.
Local servers. For LM Studio, llama.cpp, vLLM and similar servers on your machine, see Local models.

Get started

Using o4

Planning and agents

Models

Safety

Customize

Extend

Help

OpenAI-compatible endpoints

Add a provider

Provider fields

Model fields

Adjust requests for strict endpoints

Reasoning

A complete example

Add a provider from the interface

Model references with slashes

How custom providers differ from built-in ones

​Add a provider

​Provider fields

​Model fields

​Adjust requests for strict endpoints

​Reasoning

​A complete example

​Add a provider from the interface

​Model references with slashes

​How custom providers differ from built-in ones

​Related

Add a provider

Provider fields

Model fields

Adjust requests for strict endpoints

Reasoning

A complete example

Add a provider from the interface

Model references with slashes

How custom providers differ from built-in ones

Related