2026 Codex CLI Installation Guide: macOS, Windows, Linux Walkthrough with OfoxIO Gateway Fixes

Last week, a friend reached out struggling with Codex CLI installation—after hours of troubleshooting errors, they still couldn’t get it to work. Having faced similar pitfalls myself, I decided to compile a detailed guide covering macOS, Windows, and Linux, plus fixes for common connection problems.

Codex isn’t a single product; it’s a suite of programming tools rebooted by OpenAI in late 2025, including desktop apps, IDE plugins, CLI tools, and cloud-based browser versions. For developers, the CLI version offers the most flexibility, but direct connections to api.openai.com often suffer from DNS delays or timeouts. A reliable workaround is forwarding requests to an OpenAI-compatible gateway like OfoxIO.

Before installing Codex CLI, complete two prep steps:
1. Ensure Node.js version ≥22.22.0 (check with node -v; upgrade via nvm for macOS/Linux or nvm-windows for Windows).
2. Obtain an OfoxIO API key: Register at ofox.io, navigate to the console → API Keys → Create new key, and save it (it only displays once).

macOS Installation
Three options are available:
- Homebrew (recommended): brew install --cask codex
- npm global install: npm install -g @openai/codex
- Desktop app: Download the .dmg file from developers.openai.com/codex.

Windows Installation
Install via npm: Run npm install -g @openai/codex in PowerShell. If the command isn’t found, add the npm global directory (retrieved via npm prefix -g) to the system PATH. The Microsoft Store offers a one-click install, but it’s not recommended as the primary method.

Linux Installation
Two options:
- npm global install: npm install -g @openai/codex
- Binary install: Create a local bin directory (mkdir -p ~/.local/bin), download the latest tar.gz from GitHub, extract to ~/.local/bin, and make executable (chmod +x ~/.local/bin/codex).

Critical Gateway Configuration
Configure Codex to use OfoxIO by editing or creating the config file:
- macOS/Linux: ~/.codex/config.toml
- Windows: %USERPROFILE%\.codex\config.toml
Add these lines:
model = "openai/gpt-5.3-codex"
model_provider = "ofoxio"
[model_providers.ofoxio]
name = "OfoxIO"
base_url = "https://api.ofox.io/v1"
env_key = "OFOXIO_API_KEY"
wire_api = "responses"

Set Environment Variable
- macOS/Linux: Add export OFOXIO_API_KEY="sk-ofox-xxxxxxxxxxxx" to ~/.zshrc or ~/.bashrc, then run source ~/.zshrc.
- Windows (PowerShell): [Environment]::SetEnvironmentVariable("OFOXIO_API_KEY", "sk-ofox-xxxxxxxxxxxx", "User").

Test Your Setup
Create a test folder: mkdir codex-test && cd codex-test, then run codex. In interactive mode, request a Python fibonacci(n) function with type annotations and unit tests. Valid code generation confirms success.

Troubleshooting Common Errors
- 401 Unauthorized: Re-source your config file or verify the API key.
- 404 Endpoint Not Found: Ensure base_url is https://api.ofox.io/v1 (no trailing slash).
- Model Not Found: Use the correct ID openai/gpt-5.3-codex (case-sensitive).

90-Second Quick Check
1. node -v ≥22.22.0
2. codex --version ≥0.130.0
3. cat ~/.codex/config.toml confirms wire_api = "responses"
4. echo $OFOXIO_API_KEY (or equivalent) is not empty
5. codex launches interactive mode.

Codex vs Claude Code
Codex integrates seamlessly with OpenAI models like GPT-5.3, ideal for GPT users. Claude Code excels at long-context tasks and cross-file understanding. Having both tools allows switching based on scenarios.

Sources

• Kuazhi Tech Post: Codex Official Website Access + Full Installation Tutorial (2026) - https://www.kuazhi.com/post/716407210.html