Connect Codex CLI to HeFu: Setup, Model Selection, and Troubleshooting

Codex CLI can connect to a custom provider through the OpenAI Responses API. This tutorial shows how to configure HeFu as that provider, load an API key through an environment variable, and test the connection with a small Python project.

1. Prerequisites

You will need:

• Codex CLI installed.
• A HeFu API key.
• A model ID enabled for Codex or Responses API use in your HeFu account.
• Python installed to run the example tests.

Check that Codex is available:

codex --version 

If you have not installed it, follow the official Codex CLI documentation.

2. Set Your API Key

Store your HeFu API key in an environment variable.

macOS, Linux, or WSL

export HEFUBAO_API_KEY="YOUR_HEFU_API_KEY" 

Windows PowerShell

$env:HEFUBAO_API_KEY = "YOUR_HEFU_API_KEY" 

Replace the placeholder with your actual key.

These commands set the variable for the current terminal session. Launch Codex from the same terminal so it can read the value.

Keep real API keys out of source files, screenshots, and Git commits.

3. Configure the HeFu Provider

Open your user-level Codex configuration file.

On macOS, Linux, or WSL:

~/.codex/config.toml 

On Windows:

%USERPROFILE%\.codex\config.toml 

Create the file and its parent directory if they do not exist. If you already have a configuration, back it up and merge these settings without duplicating existing keys or tables.

model = "YOUR_HEFU_CODEX_MODEL_ID" model_provider = "hefubao" web_search = "disabled" [model_providers.hefubao] name = "HeFu" base_url = "https://api.hefu.hk/v1" wire_api = "responses" env_key = "HEFUBAO_API_KEY" requires_openai_auth = false supports_websockets = false 

Replace YOUR_HEFU_CODEX_MODEL_ID with an exact model ID supported by your HeFu account for this integration.

Here is what each setting does:

• model selects the requested model.
• model_provider matches the provider table identifier, hefubao.
• base_url sets the API base address.
• wire_api selects the Responses protocol.
• env_key names the environment variable containing your API key.
• requires_openai_auth = false removes the requirement for OpenAI account authentication for this provider.
• supports_websockets = false disables WebSocket transport for this initial setup.

Web search is disabled to keep the initial test focused on model inference.

TOML placement matters: keep model, model_provider, and web_search above the provider table. Keys placed after a table header belong to that table.

Use the user-level configuration file for provider settings, rather than a project-local .codex/config.toml.

Use the Correct Base URL

For this configuration, use:

https://api.hefu.hk/v1 

The Responses request destination is:

https://api.hefu.hk/v1/responses 

Do not include /responses in the base_url value.

4. Verify the Connection

Create a small project directory:

mkdir hefu-codex-demo cd hefu-codex-demo git init 

Start Codex:

codex 

Inside the session, inspect the active configuration:

/status 

Then send a minimal prompt:

Reply with the word READY. Do not inspect files or run commands. 

A successful response checks basic communication. To confirm that the request passed through HeFu, compare the request time and selected model with your HeFu usage records.

For configuration diagnostics, you can also run this from your terminal:

codex doctor 

5. Test a Coding Workflow

A short text response does not establish that file editing and tool execution work correctly.

Try this prompt inside Codex:

Create dedupe.py with a function named unique_strings(values). Requirements: - Accept a list of strings. - Remove duplicates while preserving their first occurrence. - Treat uppercase and lowercase strings as different values. - Do not use external dependencies. Create test_dedupe.py using Python's unittest module. Cover empty input, repeated strings, preserved order, and case sensitivity. Run the tests and summarize the changes. 

Review any requested actions before approving them.

The function should behave like this:

unique_strings(["apple", "banana", "apple", "Apple"]) # Expected: ["apple", "banana", "Apple"] 

After Codex finishes, inspect the generated files and run the tests independently:

python -m unittest -v 

On Windows, you can use the Python launcher:

py -m unittest -v 

This checks a more complete workflow: interpreting requirements, creating files, running commands, and handling tool results.

6. Switch Models

To select another model for a new session:

codex --model "ANOTHER_HEFU_CODEX_MODEL_ID" 

This overrides the model while retaining the configured provider.

To make the change persistent, update the top-level model value in config.toml:

model = "ANOTHER_HEFU_CODEX_MODEL_ID" 

Choose a model explicitly supported for Codex through the gateway. A model working through Chat Completions does not automatically establish compatibility with Responses, streaming, and tool calls.

Custom model aliases may also require model metadata supplied by the gateway.

7. Troubleshooting

Missing API Key

Set HEFU_API_KEY in the same terminal session used to launch Codex.

Check that your configuration contains the variable name, not the key itself:

env_key = "HEFU_API_KEY" 

401 Unauthorized

Check that the key is valid and has the required permissions. Confirm that you supplied your HeFu API key.

404 or 405

Review the base URL and protocol:

base_url = "https://api.hefu.hk/v1" wire_api = "responses" 

Check that the gateway exposes the expected Responses route.

Model Rejected

Verify the exact model ID, your account's access, and whether the model is enabled for this integration.

Unexpected Provider

Check that model_provider = "hefubao" appears before the provider table. Review command-line overrides and other active configuration.

Simple Replies Work, but Coding Tasks Fail

Investigate streaming, tool calls, and multi-turn compatibility. Basic text generation and a complete coding session exercise different parts of the API integration.

Change one setting at a time so you can identify what resolves the issue.

Conclusion

Connecting Codex CLI to HeFu depends on three settings: the Responses base URL, the environment variable supplying the API key, and a supported model ID.

Verify the integration in stages: inspect the configuration, send a minimal request, confirm the route in your usage records, and test a small coding task before moving to a larger project.