Codex CLI Integration Guide for Unified Model API Gateway
2026-09-27 · 原创·接入指南
Codex CLI Integration Guide for Unified Model API Gateway
Tool Overview
Codex CLI is an open-source terminal coding assistant developed by OpenAI. It enables developers to interact with large language models directly from the command line for code generation, completion, and Q&A tasks. By configuring a custom model provider, Codex CLI can connect to a unified model API gateway, allowing a single API Key to call all available models.
Preparation
1. Register and Create an API Key: After registering on the platform console, navigate to the console to create an API Key. Record the generated key (formatted as `sk-...`). You can also check your account balance and usage details in the console.
2. Retrieve Integration Information: Go to the platform integration documentation page to obtain the Base URL and target model ID (e.g., `gpt-5.3-codex`). The platform is compatible with both OpenAI and Anthropic API specifications, supporting text chat, image generation, video generation, and vector endpoints, billed by token usage.
Integration Steps
Step 1: Edit the Configuration File
Open or create `~/.codex/config.toml` and write the following configuration:
model = "gpt-5.3-codex"
model_provider = "hefubao"
[model_providers.hefubao]
name = "hefubao"
base_url = "https://your-base-url"
wire_api = "responses"
env_key = "HEFUBAO_API_KEY"
> Note: The configuration block name is `[model_providers.hefubao]`, where `model_providers` is plural. Do not write `model_provider`. Use the actual Base URL from the platform integration documentation page.
Step 2: Set the Environment Variable
Execute the following command in your terminal to export the API Key as an environment variable:
export HEFUBAO_API_KEY=sk-your-actual-key
It is recommended to add this command to `~/.bashrc` or `~/.zshrc` so it takes effect automatically on each terminal startup.
Step 3: Launch Codex CLI
After completing the above configuration, run Codex CLI directly in the terminal. The tool will automatically read the provider configuration from `config.toml`, obtain the API Key via the environment variable, and send requests to the specified Base URL.
Practical Use Cases
Use Case 1: Multi-Model Code Q&A in Terminal
Once connected, you can ask the model code-related questions directly in the terminal, such as function implementation, bug analysis, and refactoring suggestions. Since the platform supports calling all available models with a single key, developers can switch between different model IDs in `config.toml` for comparative testing and select the model best suited for their task.
Use Case 2: Combining Image Generation and Vector Endpoints
The platform supports not only text chat but also image generation, video generation, and vector endpoints. Developers can use the same API Key to first generate requirement descriptions or code frameworks with a text model, then call the image generation endpoint for visual materials, or use vector endpoints for semantic search, building an end-to-end development workflow.
Common Troubleshooting
| Error Code | Meaning | Troubleshooting Tips |
|------------|---------|---------------------|
| 401 | Authentication failure | Verify that the environment variable `HEFUBAO_API_KEY` is set correctly, the key starts with `sk-` and has no extra spaces. Confirm the key has not been deleted or disabled in the console. |
| 404 | Model not found | Check that the `model` value in `config.toml` exactly matches the model ID listed on the platform integration documentation page, paying attention to case sensitivity and version suffixes. |
| 402 | Insufficient balance | Log in to the console to check your account balance. Recharge and retry when balance is depleted. Use usage details to monitor consumption trends. |
---
After completing the integration, visit the model marketplace to browse all available models, or try Codex CLI in your terminal for a hands-on coding assistant experience.