Codex CLI with AIXHUB

Use this guide to connect the Codex command-line client to AIXHUB through the OpenAI Responses interface. Provider settings belong in config.toml, while the API key belongs in the separate user-level auth.json file.

What you will accomplish

By the end of this guide, you will have:

1. Installed Codex CLI through npm and confirmed its version.
2. Added a minimal AIXHUB provider that uses the Responses wire API.
3. Stored the AIXHUB credential separately from provider settings.
4. Completed a read-only request and matched it with AIXHUB Usage.
5. Kept backups that can restore the previous provider and authentication state.

System requirements

• Windows, macOS, or Linux with a supported Node.js installation and npm available on PATH.
• Permission to install a global npm package for the current user or Node.js environment.
• An AIXHUB account, an AIXHUB API key, and a Responses-compatible model ID copied from Available channels. This guide uses panel-model-id for every model field.
• A text editor that preserves TOML and JSON syntax.

Codex reads the user configuration from:

• Windows: %USERPROFILE%\.codex\config.toml
• macOS and Linux: ~/.codex/config.toml

The credential file is next to it as %USERPROFILE%\.codex\auth.json on Windows or ~/.codex/auth.json on macOS and Linux. Back up both existing files before editing either one.

Install

Install the official npm package:

npm install -g @openai/codex

Open a new terminal and confirm which version is loaded:

codex --version

If the command is missing, inspect npm's global executable directory and the current PATH before changing any AIXHUB configuration.

AIXHUB configuration

Create the minimal connection configuration

Back up the current user-level config.toml, then write or merge the following complete minimum. Keep the provider identifier AIXHUB consistent in both locations:

model_provider = "AIXHUB"
model = "panel-model-id"

[model_providers.AIXHUB]
name = "AIXHUB"
base_url = "https://api.aixhub.org/v1"
wire_api = "responses"
requires_openai_auth = true

For Codex CLI, the Base URL includes exactly one /v1. wire_api = "responses" selects the Responses request format, and requires_openai_auth = true tells Codex to obtain the standard API key field from its authentication store.

Store the credential separately

Back up any existing auth.json. If it contains other sign-in data, merge the property instead of replacing the complete file. The minimum AIXHUB credential file is:

{ "OPENAI_API_KEY":"sk-your-key" }

Save it as %USERPROFILE%\.codex\auth.json on Windows or ~/.codex/auth.json on macOS and Linux. The provider name and model stay in config.toml; the secret stays in auth.json.

On macOS and Linux, restrict the credential file after saving it:

chmod 600 ~/.codex/auth.json

On Windows, keep the file under your user profile and verify that its access control list does not grant unrelated accounts read access.

Common optional settings, after the connection works

Connection testing does not require a review model, reasoning effort, response-storage preference, sandbox network access, or other desktop preferences. After the minimal provider succeeds, merge only the options you need. Keep the top-level lines before [model_providers.AIXHUB] in the real file, and keep the sandbox table as its own table:

review_model = "panel-model-id"
model_reasoning_effort = "high"
disable_response_storage = true
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = "enabled"

sandbox_mode = "workspace-write" is the context for the shown network_access table. Keep approval, notification, and other desktop or interface preferences separate: they are workflow choices rather than connection requirements.

First run

Change to a small test repository and start Codex CLI:

codex

Confirm that the displayed model is panel-model-id, then submit a bounded, read-only task:

Inspect the current directory without changing any file. Reply with OK only.

Do not approve file writes or state-changing commands during this first request. If the client opens an official login flow instead of using auth.json, stop and use the authentication troubleshooting steps below.

Verification

A successful response should contain this actual output:

OK

Open AIXHUB Usage and confirm that a new Responses request appears with panel-model-id. Match its time to the test, and verify that https://api.aixhub.org/v1 is the configured provider Base URL.

Troubleshooting

401 or missing API key

Confirm that the active Codex home contains auth.json, that the JSON property is exactly OPENAI_API_KEY, and that its value is sk-your-key. Validate the JSON syntax and file permissions, then restart Codex CLI.

Official OpenAI login appears

Check that the loaded user config.toml contains model_provider = "AIXHUB" and requires_openai_auth = true, and that the adjacent auth.json already contains the API key. Do not complete an unrelated official account login to hide a missing local credential.

model not found

Copy the exact model ID again from Available channels and keep model = "panel-model-id". If you added the optional review_model, confirm separately that panel-model-id is available for review work. The main route must support Responses requests.

Incorrect Base URL

Use https://api.aixhub.org/v1 with one /v1. A missing version segment or a duplicated /v1/v1 can produce routing or endpoint errors. Do not reuse the Claude Code Base URL on this page because the two clients construct requests differently.

Project-level settings override the user file

Check the repository and trusted parent directories for .codex/config.toml, and check whether CODEX_HOME points somewhere other than the expected user directory. CLI flags, selected profiles, and project settings can also replace the user model or provider. Remove the conflicting override or make it use the same AIXHUB values. For 403, 429, 502, and 503 responses, continue with the error code reference.

Upgrade and restore

Upgrade the npm package and verify the resulting executable:

npm install -g @openai/codex@latest
codex --version

To restore the previous setup, close Codex CLI and restore the backups of config.toml and auth.json. If no backup is available, first remove the [model_providers.AIXHUB] block and the top-level model_provider and model values added by this guide. Remove optional review, reasoning, storage, or sandbox settings only if you added them solely for this setup and no longer need them.

OPENAI_API_KEY in auth.json is a generic credential field. Delete it only after confirming that its current value is the dedicated AIXHUB key created for this setup. If the value belongs to another provider or official account, keep the property and reconfigure the matching official login or API key before the next start. Do not erase unrelated sign-in data.

Start a new terminal after restoration. Confirm codex --version, then inspect the active provider before allowing any write operation.

Security

• Treat sk-your-key as a stand-in for a secret. Never commit the real auth.json, paste the key into a prompt, or include it in logs.
• Keep auth.json in the user profile with restrictive permissions, and keep it separate from config.toml backups that may be shared for support.
• Use a dedicated AIXHUB key for Codex CLI so it can be rotated or revoked independently.
• Review project-level .codex/config.toml before trusting a repository; it can alter model, approval, and sandbox behavior.
• Enable optional network_access only when the task needs it, and continue reviewing command approvals.

Official sources

• Codex CLI
• Codex configuration reference

Last verified: 2026-07-14