Skip to content
Skip to Content
Batchwell Docs

Codex setup

Use Batchwell in Codex by adding a custom provider to ~/.codex/config.toml with base_url set to the Batchwell base URL.

To use Batchwell in Codex, add a custom provider to ~/.codex/config.toml with base_url set to https://api.batchwell.ai/v1, wire_api = "responses" and env_key naming the environment variable that holds your Batchwell API key, then select it with model_provider and a Batchwell model id as model. This is Codex's documented setup for a custom provider.

Tested end to end

This setup was tested end to end with the real Codex CLI against the Batchwell API translation layer, which serves Codex's Responses API requests.

Create a key as described in the Quickstart and Authentication, then run:

Shell
curl -fsSL https://batchwell.ai/connect.sh | sh -s -- codex --model batchwell/kimi-k3.1-pro-uncensored

It writes ~/.codex/batchwell.config.toml and ~/.config/batchwell/api-key, a Codex profile file, and leaves ~/.codex/config.toml as it is. It needs Codex 0.134.0 or later. It reads your key from BATCHWELL_API_KEY, or asks for it on the terminal with the input hidden, and checks it with GET /v1/models before it writes anything. Then start the agent with codex --profile batchwell. Every file it changes is first copied to <file>.batchwell-backup-<time>; to undo it, copy that backup back over the file, or delete a file the command created. The command runs on macOS, Linux and WSL; see Connect an agent for every option.

Paste this prompt into the agent, or into any coding agent, and it sets itself up the same way. It names the variable that holds the key, never the key itself, and tells the agent to back up each file before it changes it.

Prompt
Set up Codex CLI to use Batchwell. Change ~/.codex/batchwell.config.toml and ~/.config/batchwell/api-key.

Base URL: https://api.batchwell.ai/v1
Model id: batchwell/kimi-k3.1-pro-uncensored
API format: OpenAI Responses
API key: in the environment variable BATCHWELL_API_KEY

Rules:
- Read the key from BATCHWELL_API_KEY. If it is unset, stop and ask me to export it. Never ask me to paste a key into this chat, never print it, and never write it into a file inside a git repository.
- Back up every file before you change it, as <file>.batchwell-backup-<UTC time>.
- Change only the Batchwell entries. Keep every other setting.

Steps:
- Write the Codex profile file ~/.codex/batchwell.config.toml (Codex 0.134.0 or later) with top-level keys model = "batchwell/kimi-k3.1-pro-uncensored" and model_provider = "batchwell", and a [model_providers.batchwell] table: name = "Batchwell", base_url = "https://api.batchwell.ai/v1", env_key = "BATCHWELL_API_KEY", wire_api = "responses".
- Do not change ~/.codex/config.toml.
- Check: GET https://api.batchwell.ai/v1/models with the header Authorization: Bearer $BATCHWELL_API_KEY. A 200 that lists the model id means it works.
- Tell me to restart with: codex --profile batchwell. The first answer comes back.

curl -fsSL https://batchwell.ai/connect.sh | sh -s -- codex --model batchwell/kimi-k3.1-pro-uncensored does the same in one step. Guide: https://batchwell.ai/docs/clients/codex
config.toml
model_provider = "batchwell"
model = "batchwell/kimi-k3.1-pro-uncensored"

[model_providers.batchwell]
name = "Batchwell"
base_url = "https://api.batchwell.ai/v1"
env_key = "BATCHWELL_API_KEY"
wire_api = "responses"

The snippet is made for batchwell/kimi-k3.1-pro-uncensored, a model Batchwell serves today. In ~/.codex/config.toml, put model_provider and model before the first [table], replacing any model_provider and model lines already there, and replace an existing [model_providers.batchwell] table rather than adding a second one: Codex will not read a file that sets a key twice. Codex reads the key from BATCHWELL_API_KEY, so no key is written into the file. Create a key as described in the Quickstart and Authentication, then start Codex:

Shell
export BATCHWELL_API_KEY="bw_live_..."
codex
  • model_provider picks the provider Codex sends requests to, by its id under model_providers.
  • model is the model Codex uses. Set it to the model id from GET /v1/models; see models.
  • name is the label Codex shows for the provider.
  • base_url is the address Codex sends its requests to. Set it to the Batchwell base URL, which ends in /v1.
  • env_key names the environment variable that holds the key. Codex sends it as a bearer token. The key starts with bw_live_ or bw_test_.
  • wire_api = "responses" selects the OpenAI Responses API. Batchwell serves it at /v1/responses and runs each request as a chat completion on the same key, so credits, limits and usage work as they do for any other request.

Codex has no context window on record for a Batchwell model. Set model_context_window in the same file to the context length of the model you choose, from models.

That model lists these supported parameters: temperature, top_p, max_tokens, max_completion_tokens, stop, stream_options, tools, tool_choice, reasoning_effort. These are the model's tunable parameters, not the whole request. Batchwell turns each Codex request into a chat completion, which accepts the fields listed under accepted fields, including stream and tools.

Batchwell accepts text content only. A request with an image, such as a screenshot added to a Codex prompt, gets 400 unsupported_content. The full list is on chat completions.