Skip to main content

Connect Codex with Zeldoc.ai

Codex is OpenAI's open source coding agent, available as a terminal app and IDE extension. Codex talks to models over the OpenAI Responses API, and Zeldoc.ai serves that API at /v1/responses, so you can add Zeldoc.ai as a custom model provider in your Codex config.

Prerequisites​

Add Zeldoc.ai as a model provider​

Codex reads its configuration from ~/.codex/config.toml. Add a zeldoc provider and make it the default:

model = "zdev"
model_provider = "zeldoc"

[model_providers.zeldoc]
name = "Zeldoc.ai"
base_url = "https://api.zeldoc.ai/v1"
env_key = "ZELDOC_API_KEY"
wire_api = "responses"

The provider reads your API key from the ZELDOC_API_KEY environment variable, so make sure it's set before starting Codex:

export ZELDOC_API_KEY=your-api-key
Persist the environment variable

Add the export line to your shell profile (e.g. ~/.bashrc or ~/.zshrc) so the key is available in every new terminal session.

Provider settings must live in the user-level config

Codex ignores model_provider and model_providers in a project-local .codex/config.toml and prints a warning. Always put the provider block in ~/.codex/config.toml.

Why wire_api = "responses"?

Codex only speaks the Responses API — the older "chat" value was removed in early 2026, and Codex refuses to start if it's set. Zeldoc.ai supports the Responses API natively, so no translation proxy is needed.

Keep OpenAI as the default and switch with a profile​

If you also use Codex with your OpenAI account, you don't have to make Zeldoc.ai the default. Leave model and model_provider out of config.toml, keep only the [model_providers.zeldoc] block, and create a profile file next to it at ~/.codex/zeldoc.config.toml:

model = "zdev"
model_provider = "zeldoc"
model_reasoning_effort = "high"

Then start Codex with the profile whenever you want Zeldoc.ai:

codex --profile zeldoc

model_reasoning_effort controls how much the model thinks before answering. ZDev supports low, medium, high, and max. You can set it in the main config as well.

Verify the connection​

Run a one-off prompt from the terminal:

codex exec "Reply with the single word OK."

The session header should show model: zdev and provider: zeldoc, followed by the model's reply. Codex also prints a warning that model metadata for zdev was not found and that it's falling back to defaults. That warning is expected for any custom model and doesn't affect the connection.

Use other Zeldoc.ai models​

Any model ID from your Zeldoc.ai model list works as the model value — see list your available models. You can also override the model for a single run:

codex --model zdev-2