Using Codex CLI with Codex4Less

Using Codex CLI with Codex4Less

Codex CLI is OpenAI's open-source coding agent that runs in your terminal: it can inspect a repository, make edits, run commands and automate repeatable work. The CLI is built around a configurable model provider layer, which means you can point it at an OpenAI-compatible endpoint other than the default one.

This guide shows how to configure the official Codex CLI to send its requests to Codex4Less using a custom model provider. Every value in the example configuration was verified end-to-end with codex-cli 0.163.0 against the live Codex4Less API. Platform-specific notes that were not executed during testing are explicitly marked as such.

Note: Codex CLI evolves quickly. If an option name or behavior differs in your version, check the official configuration reference linked below — it is the source of truth for the CLI itself.

Prerequisites

• Codex CLI installed (see Step 2). Install methods differ per operating system; follow the official instructions for your platform.
• A Codex4Less account and API key. You can create both for free — you only pay for the tokens you actually use.
• A terminal. On Windows, use PowerShell (or Windows Terminal); the environment-variable syntax for PowerShell is shown below.
• Basic familiarity with TOML. The Codex CLI configuration file uses TOML syntax (key = "value" and [section] tables).

Step 1 — Create Your Codex4Less API Key

1. Create an account: codex4less.com/register
2. Sign in, open the dashboard and go to API Keys: codex4less.com/dashboard/api-keys
3. Click Create New API Key, copy the key and store it somewhere safe.

The full key is shown only once, at creation time. Requests are billed per token against your balance, so make sure there are funds on the account before running the CLI.

Security: never paste a real API key into documentation, screenshots, chat messages or source code. In the steps below the key is stored in an environment variable and the configuration file only references the variable name.

Step 2 — Install Codex CLI

The recommended method on macOS and Linux is the standalone installer from OpenAI:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

OpenAI also documents npm, Homebrew and Windows installation methods — see the official Codex CLI page and pick the method that fits your system.

Verify the installation:

codex --version

In a healthy installation this prints the version, for example:

codex-cli 0.163.0

Linux note: for sandboxed command execution (Codex running shell commands on your machine), the official docs recommend the bubblewrap sandbox package. This affects local command execution only — not the connection to Codex4Less. See the sandboxing prerequisites for details.

Step 3 — Configure a Custom Provider

This is the core of the setup. The Codex CLI reads its user-level configuration from:

~/.codex/config.toml

Create or edit that file and add the following:

model = "gpt-6.1-sol"
model_provider = "codex4less"

[model_providers.codex4less]
name = "Codex4Less"
base_url = "https://api.codex4less.com/v1"
env_key = "CODEX4LESS_API_KEY"
wire_api = "responses"
supports_websockets = false

What each key does:

Set the API key as an environment variable

macOS / Linux:

export CODEX4LESS_API_KEY="sk-..."

To make it permanent, add the same line to your shell profile (~/.bashrc, ~/.zshrc, …) and open a new terminal. Avoid putting the key directly on the command line in shared machines — it may end up in your shell history.

Windows (PowerShell):

$env:CODEX4LESS_API_KEY = "sk-..."

For a persistent variable across sessions:

setx CODEX4LESS_API_KEY "sk-..."

setx only affects new terminals — open one after running it.

Note: the Windows commands above use the standard PowerShell environment-variable syntax; the end-to-end setup in this guide was tested on Linux with codex-cli 0.163.0. If your PowerShell version expects anything different, follow the official installation page.

Which models can I use? Codex4Less exposes its current model list through the OpenAI-compatible GET /v1/models endpoint and in the dashboard. At the time of writing, gpt-6.1-sol and gpt-5.6-sol were verified against the Responses API. If you pick a different model id, make sure it appears in /v1/models first.

Advanced: you can keep this configuration completely isolated from your default Codex setup by pointing the CODEX_HOME environment variable at a different directory (e.g. CODEX_HOME=~/.codex-codex4less codex). This was verified during testing.

Step 4 — Send Your First Request

Open a terminal in a project directory and start Codex:

codex

Then describe a task, or try the non-interactive one-shot mode, which is the quickest way to test the connection:

codex exec "Reply with exactly: CONNECTED"

If you run this outside a Git repository, Codex asks for confirmation to work in an untrusted directory; pass --skip-git-repo-check to allow it in scripts:

codex exec --skip-git-repo-check "Reply with exactly: CONNECTED"

A working setup prints a session header that includes the provider and the model, followed by the model's answer:

model: gpt-6.1-sol
provider: codex4less
...
codex
CONNECTED

The exact wording of the header differs between CLI versions; the important part is that provider: shows your codex4less entry and the answer comes back without authentication errors.

Step 5 — Verify the Connection

A reply from the model proves the request succeeded, but it does not by itself prove it went through Codex4Less. Three independent checks:

1. Session header. The CLI prints the active provider and model at session start (provider: codex4less).
2. Dashboard usage. After your request, open codex4less.com/dashboard/usage — the request appears with the model name, token counts and cost, and your balance decreases. This is the strongest proof: it shows the request was processed and billed on Codex4Less infrastructure.
3. Direct API check. With the same key, ask the API for its model list:

curl https://api.codex4less.com/v1/models -H "Authorization: Bearer $CODEX4LESS_API_KEY"

You should receive the current model catalog in OpenAI's {"object":"list", ...} format.

Troubleshooting

401 — invalid API key

• The key must include the full sk- prefix exactly as issued in the dashboard.
• Environment variables are per-terminal: a key exported in one terminal is not visible in another. Verify with echo $CODEX4LESS_API_KEY (avoid printing the full value on shared screens).
• A key deleted or revoked in the dashboard stops working immediately — create a new one.

404 — wrong base URL or path

• base_url must be exactly https://api.codex4less.com/v1.
• A common mistake is adding the endpoint to the base URL (https://api.codex4less.com/v1/responses): Codex appends /responses itself, so the resulting request becomes /v1/responses/responses and returns 404.

The selected model is unavailable

• Check GET /v1/models for the current list and use an id copied from it.
• Model availability can change over time. If the id you configured is not listed, or stops responding while other models work, switch model to one of the ids currently listed and restart Codex.

wire_api mismatch

• Current Codex CLI supports only wire_api = "responses". If you try "chat", the CLI fails at startup with a message pointing to the migration discussion.
• If a provider advertises Responses support but requests fail right after startup, confirm that {base_url}/responses actually responds — for Codex4Less this endpoint was verified with both streaming and non-streaming requests.

Configuration file ignored / wrong location

• Provider definitions live in the user-level ~/.codex/config.toml. Project-local .codex/config.toml files cannot define or override model_providers — Codex ignores those keys by design (see the configuration reference).
• If you use CODEX_HOME, make sure the same value is set in the terminal where Codex runs.

Environment variable not read

• Export the variable in the same terminal session where you launch Codex, or restart the terminal after editing your shell profile / running setx.
• Variable names are case-sensitive on macOS/Linux.

FAQ

Can I use a custom API provider with Codex CLI? Yes. Codex CLI reads a list of model_providers from its user-level config file, and a custom provider entry can point the CLI at any endpoint that implements the wire API the CLI requires. This is exactly what the setup above does; see the official configuration reference.

Where should I store my API key? In an environment variable referenced by env_key. The config file then contains only the variable name (CODEX4LESS_API_KEY), so it is safe to back up or share. Never commit the real key to a repository or paste it into screenshots.

Which API format does the endpoint support? Codex4Less serves OpenAI-compatible APIs. For Codex CLI the relevant piece is the Responses API — POST https://api.codex4less.com/v1/responses — which was verified working, including streaming. The classic POST /v1/chat/completions endpoint is available as well, for other tools and SDKs; see the API documentation.

What should I do if my selected model is unavailable? List the models with GET /v1/models (or the dashboard) and switch model in your config to one of the ids shown. Model availability can change; Codex4Less adds and retires models over time.

Does this work on Windows? Yes — Codex CLI ships for Windows as well (see the official installation page). Use the PowerShell syntax shown above for the environment variable, and place config.toml in C:\Users\<you>\.codex\config.toml.

Conclusion and CTA

You have pointed the official Codex CLI at Codex4Less with a custom provider, sent a first request and verified it on the dashboard. From here, use Codex as you normally would — the only change is the provider entry in your config.

Ready to get started?

Create your Codex4Less account, generate an API key and follow the setup steps to try a supported model.

Create your account →