When Codex CLI fails with a custom OpenAI-compatible base URL, the problem is rarely just the model. Work through the route in layers: base URL, API key, /v1/models, exact model ID, one tiny request, Codex CLI config, retries, and concurrency pressure.
Operator-reviewed
Maintained by the unlimitedcodex operator team responsible for manual API setup delivery, base URL handoff, package dates, and customer support workflows.
Start outside Codex CLI
Do not debug the whole coding agent first. Run one direct request against the provider from a terminal or small script. If the direct request fails, Codex CLI will only make the failure harder to read.
The first checks are mechanical: the base URL should point at the delivered /v1 endpoint, the API key should be server-side or local-secret only, and the Authorization header should use the expected Bearer shape.
Call /v1/models before choosing a model ID
A custom provider can be OpenAI-compatible without exposing the same model names as another provider. The /v1/models response is the truth source for the IDs your client can request.
If /v1/models does not return the model you configured, fix the model ID or package access before running a repo task. If /v1/models works but Codex CLI still fails, move to client configuration and request-shape debugging.
Run one tiny chat request
Send one minimal chat/completions request using the exact returned model ID. This confirms that auth, base URL, model access, response shape, and basic latency work before tool calls enter the picture.
Keep the request boring. One short user message is enough. Long prompts, tools, streaming, and repository context can wait until the basic route is proven.
Then test Codex CLI with a fresh small task
Use a fresh Codex CLI session, a tiny repository, and a narrow edit. Avoid old history, large context, and multiple simultaneous tasks during the first provider check.
If the direct request works but Codex CLI fails, compare the exact base URL, model ID, auth mode, config file path, environment variables, and whether the CLI is reading the config you edited.
Watch retry and timeout behavior
Agent loops can turn one endpoint problem into many paid requests. Look for repeated tool-call failures, model_not_found errors, 401 or 403 auth errors, 404 base URL mistakes, 429 rate-limit responses, and timeout loops.
A good provider evaluation includes error shape, Retry-After behavior, timeout guidance, and a clear concurrency boundary. Without those, a long Codex CLI task can look like a model problem when it is really a route problem.
Check whether unlimitedcodex is a fit
unlimitedcodex is built for developers who want Codex IDE or Codex CLI-compatible GPT-5.6 Sol plus Codex API access through an OpenAI-compatible key and base URL.
It is a fit for bounded build and test sprints: $19/week or $76/month, unlimited token consumption with 4 concurrent connections, and manual setup delivery that usually takes 10 minutes to 5 hours. It is independent and not affiliated with OpenAI.