Codex CLI + Codex App Integration Example
Codex is OpenAI's programming assistant, available in two forms:
- Codex CLI: An open-source command-line tool that runs in your local terminal. It can read, modify, and run code within a directory you choose. Built with Rust, it is fast and efficient, and is continuously improved on GitHub.
- Codex App: A graphical application (desktop / IDE plugin) that works out of the box—ideal for users who prefer a visual interface. See the official Codex App page for details.
Both share the same configuration approach: they read the same ~/.codex/config.toml file and the same environment variables. As a result, the configuration below applies to both Codex CLI and Codex App—configure once and use it on both. By integrating with 开桥, you gain access to more model options instead of being limited to the official OpenAI API.
Compatibility Notes
OpenAI has explicitly positioned Responses as the next-generation unified interface. Chat Completions is still available, but it is no longer the preferred choice for new projects. Codex will follow this direction as well—treating Chat Completions as a compatibility option and gradually migrating to Responses (the configuration in this article uses Responses).
Note the OpenAI-compatible setting: base_url=https://openqiao.com/api/v1.
Configuration Options
Configure once, use everywhere
Codex CLI and Codex App read the same ~/.codex/config.toml file and environment variables. Once you complete the steps below, both forms will automatically use 开桥.
Install Codex
# Install with pnpm (recommended)
pnpm install -g @openai/codex
# Or install with npm
npm install -g @openai/codex# Download and install Codex App (desktop / IDE plugin) from the official page:
# https://developers.openai.com/codex/app
# No extra setup entry is needed—the App automatically reads the
# ~/.codex/config.toml described below.Configure Environment Variables
Add your 开桥 API Key to your shell configuration file:
# Edit ~/.zshrc or ~/.bashrc depending on the terminal you use
export OPENQIAO_API_KEY="sk-ai-v1-xxx"Important
Make sure to replace sk-ai-v1-xxx with your actual 开桥 API Key. You can obtain an API Key in the 开桥 Console.
Configure Codex
Create or modify the Codex configuration file ~/.codex/config.toml:
model_provider = "openqiao"
model = "gpt-5.2-codex"
[model_providers.openqiao]
name = "开桥"
base_url = "https://openqiao.com/api/v1"
env_key = "OPENQIAO_API_KEY"
wire_api = "responses"
[features.multi_agent_v2]
tool_namespace = "agents"Configuration Notes
model_provider: Use 开桥 as the model providermodel: The model to use; can be any model supported by 开桥. For GPT-series models, we recommend using the native name directly (例如,gpt-5.2-codex)—see the Supported Models section belowbase_url: The base URL of the 开桥 APIenv_key: The name of the environment variable that stores the API Keywire_api: Use the Responses protocol (recommended)features.multi_agent_v2.tool_namespace: Sets theagentsnamespace for multi-agent tools; keep this setting when using the GPT-5.6 models listed below
Start Using It Immediately
Once configured, you can start Codex:
# Reload configuration
source ~/.zshrc # or source ~/.bashrc
# Enter your project directory
cd my-project
# Start Codex CLI
codex# Just open Codex App—it automatically reads ~/.codex/config.toml.
# If the App is already running, restart it once to load the latest configuration.First launch of Codex App
If Codex App prompts you to enter an API Key on first launch, simply enter your 开桥 API Key (sk-ai-v1-xxx), then close the App. Next, edit ~/.codex/config.toml as described in Configure Codex above, save it, and reopen Codex App for the changes to take effect.
Convenience
After adding the environment variable to your shell configuration file, you won’t need to set it manually each time. The configuration applies automatically every time you open a new terminal, and both Codex CLI and Codex App will read it.
Supported Models
You can freely switch the model field in config.toml to any model supported by 开桥.
For the complete, continuously updated model list, visit the 开桥 model list (Responses protocol) ↗. Just put the model name in the model field of config.toml.
Use Native Aliases for GPT-Series Models
For OpenAI GPT-series models, we recommend using the native name directly (例如, gpt-5.2-codex, gpt-5.5) rather than the prefixed full 开桥 model ID (例如, openai/gpt-5.2-codex, openai/gpt-5.5).
# ✅ Recommended: use the native alias for maximum feature support
model = "gpt-5.2-codex"
# ⚠️ Not recommended: the prefixed full ID may prevent some native features from being enabled
model = "openai/gpt-5.2-codex"Why use the native alias?
Codex validates model names against hardcoded strings to enable the corresponding native features (such as reasoning under the Responses protocol and codex-specific capabilities). When Codex sees a native name like gpt-5.2-codex, those features are activated correctly; when it sees a prefixed ID like openai/gpt-5.2-codex, validation may fail and the features silently fall back.
开桥's model alias feature makes gpt-5.2-codex fully equivalent to openai/gpt-5.2-codex, so Codex's validation passes and all downstream features work as expected. For the full alias list and more details, see Model Alias.
Multi-Agent Configuration for GPT-5.6 Luna, Terra, and Sol
Important
When using the latest gpt-5.6-luna, gpt-5.6-terra, or gpt-5.6-sol, you may encounter the following error:
{"error":{"code":"400","type":"invalid_params","message":"Invalid Value: 'tools'. Namespace 'collaboration' is reserved for encrypted tool use by this model."}}Add the following configuration to ~/.codex/config.toml (it is already included in the default example above):
[features.multi_agent_v2]
tool_namespace = "agents"If you configure model_catalog_json, also add the following field to the corresponding model entry:
"multi_agent_version": "v2"Starting with Codex v0.144.1, multi_agent is a new feature. When Codex defines multi-agent tools, it uses the special collaboration field. gpt-5.6-sol reserves collaboration as a namespace for encrypted tool use, which causes the conflict and the error above.
This switches multi-agent tools to the agents namespace, avoiding the namespace conflict. Restart Codex after saving the configuration.
How to use other models
- GPT series: use the native name directly (例如,
gpt-5.2-codex,gpt-5.5) - Models from other providers: use the prefixed full slug (例如,
anthropic/claude-opus-4-8,deepseek/deepseek-v4-pro); filter for Responses-protocol models in the 开桥 model list and copy their slugs - To target a specific provider, see the Provider Routing documentation
Troubleshooting
Common Issues
API Key Error
Issue: You are told the API Key is invalid or unauthorized.
Solutions:
- Check whether the environment variable
OPENQIAO_API_KEYis set correctly - Use
echo $OPENQIAO_API_KEYto verify the environment variable value - Confirm the API Key is active and that you have sufficient balance
- Verify the API Key format starts with
sk-ai-v1-
Connection Failure
Issue: Codex CLI cannot connect to the 开桥 service.
Solutions:
- Check that your network connection is working
- Verify that
base_urlinconfig.tomlis correctly set tohttps://openqiao.com/api/v1 - Confirm your firewall settings are not blocking outbound connections
- Try
curl https://openqiao.com/api/v1/modelsto test connectivity
Environment Variable Not Taking Effect
Issue: Even after setting the API Key, it still says it is not configured.
Solutions:
- Reopen the terminal window, or run
source ~/.zshrcorsource ~/.bashrcto reload the configuration - Confirm the environment variable is set correctly:
echo $OPENQIAO_API_KEY - Make sure you added the environment variable to the correct shell configuration file (
.zshrcfor zsh users,.bashrcfor bash users)
Configuration File Path Issue
Issue: Changes to the configuration file do not take effect.
Solutions:
- Confirm the configuration file path is
~/.codex/config.toml - If the directory does not exist, create it first:
mkdir -p ~/.codex - Check that the configuration file syntax is correct (TOML format)
- Use
cat ~/.codex/config.tomlto verify the file contents
Model Unavailable
Issue: A model is reported as unavailable or unsupported.
Solutions:
- Visit the 开桥 model list to confirm the model is available
- Check that the model slug is spelled correctly
- Try another recommended model to test
- Confirm your account has permission to access the model
codex-auto-review Model Not Found
Issue: When using 开桥 as the model provider, Codex reports that the codex-auto-review model cannot be found or is not supported, for example:
The supported API model names are ..., but you passed codex-auto-review.Cause: Codex's automatic approval review (auto-review) uses a model named codex-auto-review by default to evaluate requests. This model only exists on OpenAI's official backend; 开桥 and any other third-party or self-hosted provider do not have it, so the call sends a non-existent model ID upstream and is rejected. See openai/codex#31255.
Solution: Route approval requests to manual user confirmation instead of the auto-review model:
# ~/.codex/config.toml
approvals_reviewer = "user"Advanced Configuration
Configure Different Models
To switch to any model supported by 开桥, just change the model field in config.toml—everything else stays the same. The examples below show how to specify different models:
model_provider = "openqiao"
model = "anthropic/claude-opus-4-8"
[model_providers.openqiao]
name = "开桥"
base_url = "https://openqiao.com/api/v1"
env_key = "OPENQIAO_API_KEY"
wire_api = "responses"model_provider = "openqiao"
model = "deepseek/deepseek-v4-pro"
[model_providers.openqiao]
name = "开桥"
base_url = "https://openqiao.com/api/v1"
env_key = "OPENQIAO_API_KEY"
wire_api = "responses"model_provider = "openqiao"
model = "moonshotai/kimi-k2.6"
[model_providers.openqiao]
name = "开桥"
base_url = "https://openqiao.com/api/v1"
env_key = "OPENQIAO_API_KEY"
wire_api = "responses"Note
Use the actual slug from the 开桥 model list in the model field.