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

• Codex CLI installed on your machine
• A Zeldoc.ai API key — see Generate an API key

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. Keep your existing OpenAI settings in config.toml and add only the [model_providers.zeldoc] block from above. 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 has three levels: low, high, and max. Any other value, medium included, runs at max, and so does leaving the setting out. You can set it in the main config as well.

Current profile format

Codex 0.134.0 and later use separate <name>.config.toml files. Do not add a [profiles.zeldoc] table or a profile = "zeldoc" selector to config.toml; these are legacy settings that cause current Codex versions to reject the profile.

Models and providers are separate

/model changes the model on the current provider; it does not switch providers or API keys. Start a new Codex session with --profile zeldoc to use Zeldoc.ai, or without that profile to use your configured default provider.

Verify the connection

If Zeldoc.ai is your default provider, run:

codex exec "Reply with the single word OK."

If you kept OpenAI as the default, select the Zeldoc.ai profile:

codex --profile zeldoc exec "Reply with the single word OK."

The session header should show model: zdev and provider: zeldoc, followed by the model's reply.

Model metadata and context limits

Codex may warn that metadata for zdev was not found and that it is using fallback metadata. A successful reply confirms the connection works, but the warning is not just cosmetic: fallback metadata can give Codex the wrong context limit or omit supported reasoning choices from the model picker.

ZDev's capabilities are:

Capability	Value
Context window	1,000,000 tokens
Maximum output	131,072 tokens
Input	Text and images
Output	Text
Reasoning effort	low, high, max
Tool calling	Supported

For accurate context limits, a complete model-picker entry, and warning-free metadata, use Codex's model_catalog_json setting with a custom catalog containing a zdev entry. Set context_window and max_context_window to 1000000, input_modalities to ["text", "image"], and supported_reasoning_levels to presets for low, high, and max.

A catalog must also include Codex's required fields and a valid instruction template; it is not just a list of model names. See the Codex configuration reference and the Codex 0.155.1 model schema. Use a schema compatible with your installed Codex version. Keep model_catalog_json in the Zeldoc.ai profile if you use profiles: it replaces the catalog for that session rather than adding entries to the default OpenAI catalog. For example, after creating the catalog, add this top-level setting to the profile, replacing the path with its actual location:

model_catalog_json = "/absolute/path/to/zdev.json"

Setting model_context_window alone does not remove the warning and may still be clamped to the fallback metadata's maximum context window.

Codex 0.155.1 has no model-catalog field for the maximum completion-token count. Do not put 131072 in truncation_policy: that setting limits tool output, not model output.

Use other Zeldoc.ai models

Choose a model ID from your available models that supports the Responses API and tool calling. You can override the model for a single run when Zeldoc.ai is your default provider:

codex --model <model-id>

Or select both the profile and model:

codex --profile zeldoc --model <model-id>

Replace <model-id> with the actual ID. --model alone does not change the provider. Reasoning levels and context limits are model-specific; do not reuse ZDev's settings or catalog entry unchanged for another model.