HAI Gateway

What is Codex?

OpenAI Codex CLI is a locally-running coding agent that helps you write and debug code, understand project structure, and execute complex development tasks directly from your terminal.

Recommended: configure via CC Switch

If you would rather not edit ~/.codex/auth.json and ~/.codex/config.toml by hand, use CC Switch to switch Codex between HAI Gateway and other providers from a graphical UI — it writes the corresponding config files for you.

Prerequisites

Please confirm the following dependencies are ready before installation

Codex runs on Node.js. You must install Node.js and npm before proceeding. Git is recommended.

Dependency	Version	Required	Download
Node.js	v22+	Yes	nodejs.org
npm	Included with Node.js	Yes	-
Git	v2.23+	Recommended	git-scm.com

macOS Setup

Step 1: Install dependencies

# Install Node.js and Git via Homebrew (recommended)
brew install node git
 
# Or install Node.js via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.zshrc
nvm install --lts

Step 2: Install Codex

npm install -g @openai/codex

Step 3: Create config directory

mkdir -p ~/.codex

Step 4: Configure API key

cat > ~/.codex/auth.json << 'EOF'
{
  "OPENAI_API_KEY": "sk-pat-YOUR_ACCESS_TOKEN"
}
EOF

Step 5: Configure HAI Gateway

Write the following into ~/.codex/config.toml:

cat > ~/.codex/config.toml << 'EOF'
model_provider = "HaiGateway"
model = "gpt-5.5-2026-04-23"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
personality = "pragmatic"
 
[model_providers.HaiGateway]
name = "HaiGateway"
base_url = "https://api.hai.network/openai/v1"
wire_api = "responses"
EOF

Step 6: Verify installation

codex --version

Setup complete

If you see a version number, the installation was successful.

Windows Setup

About the command line

Most steps below run in PowerShell (each code block is labeled with the environment it uses). Open PowerShell as Administrator: search for PowerShell in the Start menu, right-click, and choose "Run as administrator".

Step 1: Install dependencies (PowerShell)

# Install Node.js and Git via winget (recommended)
winget install OpenJS.NodeJS.LTS
winget install Git.Git
 
# Restart the terminal after installation, then verify the versions
node --version
npm --version

No winget?

You can also download the Node.js v22+ installer from nodejs.org and the Git installer from git-scm.com, then follow the setup wizards.

Step 2: Install Codex (PowerShell)

npm install -g @openai/codex

Step 3: Create config directory (PowerShell)

mkdir ~/.codex

Step 4: Configure API key (PowerShell)

Write the key into %USERPROFILE%\.codex\auth.json:

$auth = @'
{
  "OPENAI_API_KEY": "sk-pat-YOUR_ACCESS_TOKEN"
}
'@
[System.IO.File]::WriteAllText("$env:USERPROFILE\.codex\auth.json", $auth)

Why not Out-File?

Windows PowerShell 5.1's Out-File -Encoding UTF8 writes a BOM at the start of the file, which causes Codex to fail parsing auth.json / config.toml. The WriteAllText call above writes UTF-8 without a BOM and works on both PowerShell 5.1 and 7.

Step 5: Configure HAI Gateway (PowerShell)

Write the following into %USERPROFILE%\.codex\config.toml:

$config = @'
model_provider = "HaiGateway"
model = "gpt-5.5-2026-04-23"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
personality = "pragmatic"
 
[model_providers.HaiGateway]
name = "HaiGateway"
base_url = "https://api.hai.network/openai/v1"
wire_api = "responses"
'@
[System.IO.File]::WriteAllText("$env:USERPROFILE\.codex\config.toml", $config)

Step 6: Verify installation (PowerShell or CMD)

codex --version

Setup complete

If you see a version number, the installation was successful.

Configuration Reference

Codex uses two config files, both located in the ~/.codex/ directory:

File	Purpose	Key Settings
`auth.json`	API keys	`OPENAI_API_KEY`
`config.toml`	Model and agent configuration	`base_url`, `model`

Troubleshooting

Issue	Solution
`command not found: codex` (macOS)	Restart terminal and verify that the npm global path is in your PATH
`codex is not recognized as ...` (Windows)	Restart terminal and verify that the npm global path is in your PATH
API key invalid	Check that the key in `~/.codex/auth.json` is correct
Model unavailable	Verify that the `model` in `config.toml` is supported by HAI Gateway
API connection timeout or error	Check that `base_url` in `~/.codex/config.toml` is correct
Config file fails to parse	On Windows, ensure `auth.json` / `config.toml` are UTF-8 without a BOM (use the `WriteAllText` commands from Steps 4 and 5)

Uninstall Codex

Uninstall Codex (macOS / Windows):

npm uninstall -g @openai/codex

Remove config files (macOS):

rm -rf ~/.codex

Remove config files (Windows · PowerShell):

Remove-Item -Recurse -Force ~/.codex