BETA

Docs
Instructions

How to connect Codex CLI to Apily

Codex CLI lets you declare extra model providers in ~/.codex/config.toml. Add one apily block that points at Apily's Responses endpoint and the agent runs as usual.

Tool
Codex CLI OpenAI Responses
Base URL
https://apily.pro/v1
Key
apily_your-api-key
Config file
~/.codex/config.toml

Requirements

  • Node.js LTS or the standalone binary from the Codex releases page.
  • A git repository — Codex refuses to run outside one.
  • An Apily API key from your account at apily.pro.

Install Codex CLI

terminal
npm install -g @openai/codex
codex --version

Run codex once so that ~/.codex/ is created, then open ~/.codex/config.toml in an editor.

Configuration

Append an apily provider and make it the default. The provider id must not collide with the reserved ids (openai, ollama, lmstudio):

~/.codex/config.toml
model = "gpt-5.6-sol"
model_provider = "apily"

[model_providers.apily]
name = "Apily"
base_url = "https://apily.pro/v1"
env_key = "APILY_API_KEY"
wire_api = "responses"

wire_api = "responses" targets /v1/responses, which Apily serves for the whole catalog. Export the key in your shell profile:

~/.bashrc or ~/.zshrc
export APILY_API_KEY=apily_your-api-key

Prefer a key straight in the file (no environment variable)? Use the inline token field instead of env_key:

~/.codex/config.toml
[model_providers.apily]
name = "Apily"
base_url = "https://apily.pro/v1"
wire_api = "responses"
experimental_bearer_token = "apily_your-api-key"

Your first request

terminal
curl https://apily.pro/v1/responses \
  -H "Authorization: Bearer apily_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","input":"ping","max_output_tokens":20}'

Then, inside a git repository:

terminal
codex exec "Explain this repository in one paragraph"

Switching models

Change model in config.toml, or pass -m <model-id> per run. Check the current catalog on the Models page or with GET /v1/models — for example:

  • gpt-5.6-sol — a solid default
  • claude-opus-5 · deepseek-v4-flash-0731

Configuring reasoning

Add model_reasoning_effort = "medium" (or "low" / "high") to config.toml; Apily forwards it upstream as reasoning_effort. Thinking bills as output tokens, and with long reasoning the first token can take a while — that is normal.

Common errors and how to fix them

SymptomCauseFix
401 Invalid API keyKey truncated, or APILY_API_KEY not exported in the shell that launched Codex.Export the key in the same shell profile; restart the terminal.
Unknown provider errormodel_provider name mismatch.It must match the [model_providers.apily] section name exactly.
404 Not foundBase URL without /v1, or the wrong wire protocol.Base URL: https://apily.pro/v1 — every request must land on a path Apily serves (/chat/completions, /responses, /models, …).
503 Model temporarily unavailableThe model exists, but no upstream provider is reachable right now.Retry in a moment — it usually recovers within a minute. Switch models if it keeps happening.
402 Insufficient balanceYour token balance can't cover the request's estimated cost.Top up your balance on the Billing page in your Apily account.

FAQ

All guidesPreviousClaude CodeNextOpenCode