Codex CLI Tutorial

Codex CLI is OpenAI's command-line coding assistant. This guide shows how to install Codex, configure ApiPass as the model provider, and start an interactive coding session from your terminal.

Before You Start

Make sure you have:

Node.js LTS and npm installed
An ApiPass API key from the API Keys page
A terminal where you can edit Codex user configuration files

Supported terminal choices:

macOS or Linux shell
Windows PowerShell
Windows WSL2 shell, such as Ubuntu on WSL2

If Node.js is not installed yet, install the LTS version from https://nodejs.org/ first.

Step 1: Install Codex

macOS and Linux

Install the latest Codex CLI package globally:

1npm install -g @openai/codex@latest

On macOS or Linux, use sudo only if your npm global directory requires elevated permissions:

1sudo npm install -g @openai/codex@latest

Verify the installation:

1codex --version

Windows PowerShell

Install Node.js LTS first. You can download it from https://nodejs.org/ or install it with Windows Package Manager:

1winget install OpenJS.NodeJS.LTS

If you use Chocolatey or Scoop instead, install Node.js LTS with your package manager:

1choco install nodejs-lts

1scoop install nodejs-lts

Open a new PowerShell window and verify Node.js and npm:

1node --version
2npm --version

Install Codex globally:

1npm install -g @openai/codex@latest

Verify the installation:

1codex --version

If PowerShell reports that codex is not recognized, close and reopen PowerShell or Windows Terminal so the updated npm global binary path is loaded.

Windows WSL2

If you prefer WSL2, install Node.js and Codex inside the WSL2 Linux distribution, then use the macOS/Linux commands in this guide from the WSL shell.

Use WSL2 instead of WSL1. Codex configuration inside WSL2 is stored under the Linux home directory, for example ~/.codex, and is separate from the native Windows directory %USERPROFILE%\.codex.

Step 2: Create Configuration Files

Codex reads user-level settings from ~/.codex/config.toml and API-key credentials from ~/.codex/auth.json.

macOS and Linux

Create the Codex configuration directory:

1mkdir -p ~/.codex

Create ~/.codex/config.toml:

1cat > ~/.codex/config.toml << 'EOF'
2model_provider = "apipass"
3model = "gpt-5.3-codex"
4model_reasoning_effort = "high"
5disable_response_storage = true
6preferred_auth_method = "apikey"
7
8[model_providers.apipass]
9name = "apipass"
10base_url = "https://api.apipass.dev/codex/v1"
11wire_api = "responses"
12requires_openai_auth = true
13EOF

Create ~/.codex/auth.json:

1cat > ~/.codex/auth.json << 'EOF'
2{
3  "OPENAI_API_KEY": "YOUR_API_KEY"
4}
5EOF

Windows PowerShell Configuration

Create the Codex configuration directory:

1New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"

Create %USERPROFILE%\.codex\config.toml:

1@'
2model_provider = "apipass"
3model = "gpt-5.3-codex"
4model_reasoning_effort = "high"
5disable_response_storage = true
6preferred_auth_method = "apikey"
7
8[model_providers.apipass]
9name = "apipass"
10base_url = "https://api.apipass.dev/codex/v1"
11wire_api = "responses"
12requires_openai_auth = true
13'@ | Set-Content -Encoding UTF8 "$env:USERPROFILE\.codex\config.toml"

Create %USERPROFILE%\.codex\auth.json:

1@'
2{
3  "OPENAI_API_KEY": "YOUR_API_KEY"
4}
5'@ | Set-Content -Encoding UTF8 "$env:USERPROFILE\.codex\auth.json"

Replace YOUR_API_KEY with the API key copied from your ApiPass API Keys page.

Windows WSL2 Configuration

When using WSL2, run the macOS/Linux configuration commands inside the WSL shell. Do not create the files in %USERPROFILE%\.codex unless you are running native Windows PowerShell.

Your WSL2 files should be:

~/.codex/config.toml
~/.codex/auth.json

Endpoint Notes

Use https://api.apipass.dev/codex/v1 as the Codex base_url. Codex appends the Responses API path automatically, so requests are sent to:

https://api.apipass.dev/codex/v1/responses
https://api.apipass.dev/codex/v1/responses/compact

Do not use https://api.apipass.dev alone unless your deployment explicitly proxies /v1/responses to the Codex service.

Step 3: Start Using Codex

Start an interactive session:

1codex

Or send a one-off prompt:

1codex "help me review this project"

Cost and Credits

ApiPass deducts credits when Codex sends requests through https://api.apipass.dev/codex/v1. The exact amount depends on the selected Codex-compatible model, token usage, and the active ApiPass pricing rule.

Use these pages to inspect cost and usage:

Pricing for the current Codex rate table
API Logs for each request's credit deduction and token usage
API Usage for aggregate usage and trends
Codex Accounts if you manage connected Codex accounts in ApiPass

In the logs table, the Credits column shows the deduction for each request. Opening a row's details shows the request payload and token usage when the response includes token accounting.

If you also want to use Claude Code through ApiPass, open the related guide in the sidebar or go directly to Claude Code Tutorial.

Troubleshooting

`codex: command not found` or `codex is not recognized`

Confirm that npm installed Codex globally:

1npm list -g @openai/codex

Then restart your terminal and check that the npm global binary directory is in PATH.

On Windows PowerShell, find the npm global prefix:

1npm config get prefix

If codex is still not recognized, restart Windows Terminal or add the returned npm global prefix directory to the user Path environment variable. You can also check whether the Codex command shim exists:

1where.exe codex

npm Permission Errors on Windows

If global installation fails in PowerShell because of permissions, open PowerShell or Windows Terminal as Administrator and run:

1npm install -g @openai/codex@latest

If you installed Node.js through a version manager or package manager, use the same shell environment for both Node.js and Codex.

PowerShell Blocks npm Scripts

If PowerShell shows an error such as npm.ps1 cannot be loaded because running scripts is disabled, use npm.cmd:

1npm.cmd install -g @openai/codex@latest

Or, if your organization policy allows it, enable local user script execution:

1Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Windows Configuration File Location

Native Windows PowerShell uses:

1%USERPROFILE%\.codex\config.toml
2%USERPROFILE%\.codex\auth.json

WSL2 uses:

1~/.codex/config.toml
2~/.codex/auth.json

These are different locations. If Codex still asks for authentication, confirm that you created auth.json in the same environment where you run the codex command.

Windows Encoding Issues

If Codex cannot read the configuration file created in PowerShell, inspect the file content:

1Get-Content "$env:USERPROFILE\.codex\config.toml"
2Get-Content "$env:USERPROFILE\.codex\auth.json"

If the content looks incorrect, recreate the files with the PowerShell commands above. They use Set-Content -Encoding UTF8 to avoid encoding issues.

Authentication Fails

Check that ~/.codex/auth.json contains a valid ApiPass key:

1{
2  "OPENAI_API_KEY": "YOUR_API_KEY"
3}

Also confirm that preferred_auth_method = "apikey" is present in config.toml.

404 Not Found

If you see a 404 error, verify that base_url includes /codex/v1:

1base_url = "https://api.apipass.dev/codex/v1"

Without /codex, Codex will call https://api.apipass.dev/v1/responses, which is not the ApiPass Codex endpoint.

Model Unavailable

If a model returns an availability error, switch the model value in config.toml to another Codex-compatible model enabled for your ApiPass account.

Cookie Preferences

Codex CLI Tutorial