Codex

Revision 1 · Updated 2026-11-12 · 3 min read

Connect Codex CLI to Runtoken.

Prerequisites#

Before you start, prepare:

A working Codex CLI installation; run codex --version. See the official installation instructions if needed.
A Runtoken platform API key.
A model ID supporting Responses and the tools required by your coding task.

Connection settings#

Open your user configuration at ~/.codex/config.toml. If you set a custom CODEX_HOME, use the configuration under that directory instead. Merge the following provider table into the existing TOML file; do not replace other settings or create a duplicate table.

config.toml · provider definitiontext

[model_providers.runtoken]
name = "Runtoken"
base_url = "https://api.runtoken.net/v1"
env_key = "RUNTOKEN_API_KEY"
wire_api = "responses"

The provider definition contains no secret. Set its credential in the terminal used to launch Codex.

Configuration	Value	Purpose
Provider ID	`runtoken`	Selects the table defined above.
`base_url`	`https://api.runtoken.net/v1`	Forms the Responses endpoint; do not append `/responses` here.
`env_key`	`RUNTOKEN_API_KEY`	Names the environment variable containing your platform key.
`wire_api`	`responses`	Uses the Responses protocol.

A Chat Completions model cannot be substituted just by changing its ID. Use the Responses route for this configuration.

Set credentials and launch#

Open a separate terminal in a small test project. The launch below selects Runtoken for this invocation without changing your default provider.

bash

export RUNTOKEN_API_KEY="YOUR_PLATFORM_KEY"
codex -c 'model_provider="runtoken"' --model "YOUR_MODEL_ID"

$env:RUNTOKEN_API_KEY = "YOUR_PLATFORM_KEY"
codex -c 'model_provider="runtoken"' --model "YOUR_MODEL_ID"

Replace YOUR_PLATFORM_KEY with a platform key and YOUR_MODEL_ID with the exact Responses model ID from the Runtoken catalogue. Do not put either placeholder into a real credential store unchanged. Keep real keys out of prompts, screenshots and shared files; commands containing a key can remain in shell history.

Check the connection and file task#

In the interactive session, run /status and check the selected model and provider information. Send a short request, then locate the matching Runtoken request record by time, model and key. A saved sign-in status alone does not establish which inference route was used.

Try the following task in the test project.

Check a coding round triptext

Create greeting.py with a greet(name) function returning "Hello, " plus name.
Read the file back and explain it. Do not install packages or use the network.

Inspect the proposed file changes and keep the normal permission controls. In the same session, ask Codex to return "Hello, friend" for an empty name. Check the resulting file and the second request record as well as the text reply.

Capabilities and limits#

Runtoken inference is stateless. Do not build gateway integration around server-retained response IDs or background mode. A text response does not establish compatibility with every tool schema, compaction operation or reasoning option sent by a client.

Feature	What determines availability
Responses streaming and tool calls	Selected model, gateway route and client request format.
Context compaction	The client's compaction protocol and the selected model's supported interface.
Hosted search, image generation or other model tools	Explicit support for that tool; changing the provider does not enable it.
Local file edits and shell commands	Client permissions and the tools the model can use.

Do not enable a provider capability or enlarge a context limit solely to suppress an error. Such settings do not add server-side support.

Troubleshooting#

Use the reported path and error details to separate configuration failures from model failures.

Symptom	What to check
Missing environment key	Set `RUNTOKEN_API_KEY` in the launching terminal; do not print its value to diagnose it.
Request goes to the default provider	Check the launch override and effective configuration.
`404`	Check the base URL and reported model or route; the status alone does not identify the cause.
Unknown field or rejected protocol	Compare the field with your CLI version's official configuration reference.
Text works but a file task fails	Inspect the rejected tool fields and model support.
`429` or interrupted stream	Read the limit/reset information; retain partial results before deciding to retry.

Restore settings and further reading#

Close the test terminal and launch without the provider override to return to your normal selection. Remove only the added provider table if you no longer need it; retain unrelated configuration and sign-in data.

See OpenAI Responses for the API and official Codex configuration for client settings.

Was this page helpful?