Codex CLI

Codex CLI can use custom model providers through the user-level config.toml. For HiLinkup, use the OpenAI-compatible base URL and the Responses wire API.

Codex configuration uses ~/.codex/config.toml for user-level settings. A named profile loads ~/.codex/config.toml first, then overlays ~/.codex/<profile>.config.toml. Provider settings should be kept in user-level config or a profile, not in project .codex/config.toml.

Examples use the HiLinkup platform model aliyun/kimi-k3, a Chinese model example. Confirm available code models with /v1/models and the console.

Codex uses Responses only

For current Codex CLI custom providers, responses is the only supported wire_api value and is also the default when omitted.

Do not configure wire_api = "chat". It is not a supported current Codex protocol and does not make a Chat-Completions-only model usable in Codex. Verify that the selected model and HiLinkup channel support POST /v1/responses.

Verify the API first

macOS / Linux
Windows PowerShell

export HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY"

curl https://api.hilinkup.com/v1/models \
  -H "Authorization: Bearer $HILINKUP_API_KEY"

$env:HILINKUP_API_KEY = "YOUR_HILINKUP_API_KEY"

curl.exe https://api.hilinkup.com/v1/models `
  -H "Authorization: Bearer $env:HILINKUP_API_KEY"

Option 1: edit user config

Recommended for long-term use.

macOS
Linux
Windows PowerShell

mkdir -p ~/.codex
nano ~/.codex/config.toml

Paste:

model = "aliyun/kimi-k3"
model_provider = "hilinkup"

[model_providers.hilinkup]
name = "HiLinkup"
base_url = "https://api.hilinkup.com/v1"
env_key = "HILINKUP_API_KEY"
wire_api = "responses"
request_max_retries = 2
stream_max_retries = 5
stream_idle_timeout_ms = 300000

Save with Ctrl + O, press Enter, then exit with Ctrl + X.Store the key:

nano ~/.zshrc

Add:

export HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY"

Reload:

source ~/.zshrc

mkdir -p ~/.codex
nano ~/.codex/config.toml

Paste:

model = "aliyun/kimi-k3"
model_provider = "hilinkup"

[model_providers.hilinkup]
name = "HiLinkup"
base_url = "https://api.hilinkup.com/v1"
env_key = "HILINKUP_API_KEY"
wire_api = "responses"
request_max_retries = 2
stream_max_retries = 5
stream_idle_timeout_ms = 300000

Save with Ctrl + O, press Enter, then exit with Ctrl + X.Store the key in your shell profile:

nano ~/.bashrc

or:

nano ~/.zshrc

Add:

export HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY"

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\config.toml"

Paste and save:

model = "aliyun/kimi-k3"
model_provider = "hilinkup"

[model_providers.hilinkup]
name = "HiLinkup"
base_url = "https://api.hilinkup.com/v1"
env_key = "HILINKUP_API_KEY"
wire_api = "responses"
request_max_retries = 2
stream_max_retries = 5
stream_idle_timeout_ms = 300000

Store the API key:

[Environment]::SetEnvironmentVariable(
  "HILINKUP_API_KEY",
  "YOUR_HILINKUP_API_KEY",
  "User"
)

Restart PowerShell, or set it for the current window:

$env:HILINKUP_API_KEY = "YOUR_HILINKUP_API_KEY"

Run:

codex

Option 2: profile config

macOS / Linux
Windows PowerShell

mkdir -p ~/.codex
nano ~/.codex/hilinkup.config.toml

Paste:

model = "aliyun/kimi-k3"
model_provider = "hilinkup"

[model_providers.hilinkup]
name = "HiLinkup"
base_url = "https://api.hilinkup.com/v1"
env_key = "HILINKUP_API_KEY"
wire_api = "responses"

Run:

export HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY"
codex --profile hilinkup

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\hilinkup.config.toml"

Paste:

model = "aliyun/kimi-k3"
model_provider = "hilinkup"

[model_providers.hilinkup]
name = "HiLinkup"
base_url = "https://api.hilinkup.com/v1"
env_key = "HILINKUP_API_KEY"
wire_api = "responses"

Run:

$env:HILINKUP_API_KEY = "YOUR_HILINKUP_API_KEY"
codex --profile hilinkup

Option 3: one-off command

macOS / Linux
Windows PowerShell

HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY" \
codex \
  -c model='"aliyun/kimi-k3"' \
  -c model_provider='"hilinkup"' \
  -c model_providers.hilinkup.name='"HiLinkup"' \
  -c model_providers.hilinkup.base_url='"https://api.hilinkup.com/v1"' \
  -c model_providers.hilinkup.env_key='"HILINKUP_API_KEY"' \
  -c model_providers.hilinkup.wire_api='"responses"'

$env:HILINKUP_API_KEY = "YOUR_HILINKUP_API_KEY"

codex `
  -c model='"aliyun/kimi-k3"' `
  -c model_provider='"hilinkup"' `
  -c model_providers.hilinkup.name='"HiLinkup"' `
  -c model_providers.hilinkup.base_url='"https://api.hilinkup.com/v1"' `
  -c model_providers.hilinkup.env_key='"HILINKUP_API_KEY"' `
  -c model_providers.hilinkup.wire_api='"responses"'

Verify

codex doctor
codex exec --profile hilinkup "Only read the current directory and summarize the project structure."

Common issues

Codex still does not use HiLinkup

Check that model_provider = "hilinkup" is in the active user-level config. When using --profile hilinkup, the file must be ~/.codex/hilinkup.config.toml, or %USERPROFILE%\.codex\hilinkup.config.toml on Windows.

Codex cannot find the API key

Confirm env_key = "HILINKUP_API_KEY" and verify that the same terminal can read it. Use echo $HILINKUP_API_KEY on macOS/Linux or echo $env:HILINKUP_API_KEY in PowerShell.

Responses does not work

Codex custom providers use Responses. Verify https://api.hilinkup.com/v1/responses with the Responses example. If a model only supports Chat Completions, select a model that supports Responses; do not set wire_api to "chat".

Do not put provider settings in project .codex/config.toml

Codex project-level .codex/config.toml cannot override model_provider, model_providers, and provider authentication settings. Put them in user-level ~/.codex/config.toml or ~/.codex/hilinkup.config.toml.

Do not override the built-in openai provider

Do not define [model_providers.openai]. openai is a reserved built-in provider ID. Use a custom ID such as hilinkup.

Overview

Developer tools

Chat clients

Application frameworks

Codex uses Responses only

Verify the API first

Option 1: edit user config

Option 2: profile config

Option 3: one-off command

Verify

Common issues

​Codex uses Responses only

​Verify the API first

​Option 1: edit user config

​Option 2: profile config

​Option 3: one-off command

​Verify

​Common issues

Codex uses Responses only

Verify the API first

Option 1: edit user config

Option 2: profile config

Option 3: one-off command

Verify

Common issues