Skip to main content
Qwen Cloud home page
Docs
Clients & tools

Codex

OpenAI's terminal AI coding assistant

Codex is a terminal AI coding assistant developed by OpenAI. Connect it to Qwen Cloud via Token Plan Personal Edition, Token Plan (Team Edition), Coding Plan, or pay-as-you-go billing.

Install Codex

  1. Install or update Node.js (v18.0 or later).
  2. Run the following command in a terminal to install Codex. 
npm install -g @openai/codex
Run the following command to verify the installation. 
codex --version

Configure access credentials

To connect, edit the configuration file ~/.codex/config.toml and configure the environment variable OPENAI_API_KEY. Replace the corresponding values based on your selected billing plan.

Configure Model Metadata

When using custom models such as qwen3.8-max-preview, you must configure the model metadata file so that Codex correctly recognizes the model's context window, reasoning depth, and other parameters.
  1. Create the file ~/.codex/model-catalog.local.json with the following content:
{
  "models": [
    {
      "slug": "qwen3.8-max-preview",
      "display_name": "qwen3.8-max-preview",
      "description": "DashScope model: qwen3.8-max-preview",
      "default_reasoning_level": "xhigh",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 983616,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": true,
      "input_modalities": ["text", "image"]
    }
  ]
}
  1. Add the following line to ~/.codex/config.toml to point to the metadata file:
model_catalog_json = "~/.codex/model-catalog.local.json"

Token Plan Personal Edition

For model, select a supported model. Available models include qwen3.8-max-preview, qwen3.7-max, qwen3.7-plus, qwen3.6-flash, glm-5.2, and deepseek-v4-pro. Set the OPENAI_API_KEY environment variable to the Token Plan Personal Edition dedicated API Key.

Responses API

Available models: qwen3.8-max-preview, qwen3.7-max, qwen3.7-plus, qwen3.6-flash, glm-5.2, deepseek-v4-pro. 
model_provider = "Model_Studio_Token_Plan_Personal"
model = "qwen3.8-max-preview"
[model_providers.Model_Studio_Token_Plan_Personal]
name = "Model_Studio_Token_Plan_Personal"
base_url = "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
qwen3.8-max-preview thinking mode:
  • thinking: Always enabled; cannot be turned off.
  • temperature: Defaults to 0.6 in thinking mode. Values below 0.6 are automatically adjusted to 0.6.
  • reasoning_effort: Controls reasoning depth. Options: xhigh, high, low. Default: xhigh.

Chat/Completions API (other models)

Other models require the Chat/Completions API. Install an older version of Codex, such as 0.80.0: 
npm install -g @openai/codex@0.80.0

model_provider = "Model_Studio_Token_Plan_Personal"
model = "glm-5"
[model_providers.Model_Studio_Token_Plan_Personal]
name = "Model_Studio_Token_Plan_Personal"
base_url = "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

Configure environment variables

Set the OPENAI_API_KEY environment variable to the Token Plan Personal Edition dedicated API Key.
  • macOS
  • Windows
  1. Run the following command in a terminal to check the default shell type.
echo $SHELL
  1. Set the environment variable based on your shell type:
  • Zsh
  • Bash
# Replace YOUR_API_KEY with the Token Plan Personal Edition API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
  1. Run the following command to apply the environment variable.
  • Zsh
  • Bash
source ~/.zshrc

Token Plan (Team Edition)

For model, select a supported model. Set the OPENAI_API_KEY environment variable to the Token Plan (Team Edition) dedicated API Key.

Responses API

Available models: qwen3.8-max-preview, qwen3.7-max, qwen3.7-plus, qwen3.6-flash, glm-5.2, deepseek-v4-pro. 
model_provider = "Model_Studio_Token_Plan"
model = "qwen3.8-max-preview"
[model_providers.Model_Studio_Token_Plan]
name = "Model_Studio_Token_Plan"
base_url = "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Chat/Completions API (other models)

Other models must be connected via the Chat/Completions API, which requires installing an older version of Codex, such as 0.80.0: 
model_provider = "Model_Studio_Token_Plan"
model = "glm-5"
[model_providers.Model_Studio_Token_Plan]
name = "Model_Studio_Token_Plan"
base_url = "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

Configure environment variables

Set the OPENAI_API_KEY environment variable to the Token Plan (Team Edition) dedicated API Key.
  • macOS
  • Windows
  1. Run the following command in a terminal to check the default shell type.
echo $SHELL
  1. Set the environment variable based on your shell type:
  • Zsh
  • Bash
# Replace YOUR_API_KEY with the Token Plan (Team Edition) API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
  1. Run the following command to apply the environment variable.
  • Zsh
  • Bash
source ~/.zshrc
qwen3.8-max-preview thinking mode:
  • thinking: Always enabled; cannot be turned off.
  • temperature: Defaults to 0.6 in thinking mode. Values below 0.6 are automatically adjusted to 0.6.
  • reasoning_effort: Controls reasoning depth. Options: xhigh, high, low. Default: xhigh.

Coding Plan

For model, select a supported model. Set the OPENAI_API_KEY environment variable to the Coding Plan dedicated API Key.

Chat/Completions API

Coding Plan only supports the Chat/Completions API. Install an older version of Codex, such as 0.80.0: 
model_provider = "Model_Studio_Coding_Plan"
model = "qwen3.7-plus"
[model_providers.Model_Studio_Coding_Plan]
name = "Model_Studio_Coding_Plan"
base_url = "https://coding-intl.dashscope.aliyuncs.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

Configure environment variables

Set the OPENAI_API_KEY environment variable to the Coding Plan dedicated API Key.
  • macOS
  • Windows
  1. Run the following command in a terminal to check the default shell type.
echo $SHELL
  1. Set the environment variable based on your shell type:
  • Zsh
  • Bash
# Replace YOUR_API_KEY with the Coding Plan API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
  1. Run the following command to apply the environment variable.
  • Zsh
  • Bash
source ~/.zshrc

Pay-as-you-go

Set the OPENAI_API_KEY environment variable to your Qwen Cloud API Key. For available models, see supported models. Pay-as-you-go supports both the Responses API and Chat/Completions API. Choose the appropriate one based on the model you are using:

Responses API

Applicable to models that support the OpenAI Responses API (such as qwen3.7-max, qwen3.7-plus, qwen3.6-plus, and qwen3.6-flash), compatible with the latest Codex version. 
model_provider = "Model_Studio"
model = "qwen3.7-max"
[model_providers.Model_Studio]
name = "Model_Studio"
base_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Chat/Completions API

Applicable to models that only support the Chat/Completions API. Requires installing Codex 0.80.0: 
model_provider = "Model_Studio"
model = "qwen3.6-plus"
[model_providers.Model_Studio]
name = "Model_Studio"
base_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

Configure environment variables

Set the OPENAI_API_KEY environment variable to your Qwen Cloud API Key.
  • macOS
  • Windows
  1. Run the following command in a terminal to check the default shell type.
echo $SHELL
  1. Set the environment variable based on your shell type:
  • Zsh
  • Bash
# Replace YOUR_API_KEY with the Qwen Cloud API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
  1. Run the following command to apply the environment variable.
  • Zsh
  • Bash
source ~/.zshrc

Verify configuration

After the configuration is complete, open a new terminal window and run the following command to start Codex: 
codex
If the chat interface launches successfully, the configuration is correct.

FAQ

What should I do if a third-party tool reports "domestic models not supported" or "check rejected / Bad request (400)"?

Cause: Some third-party management tools (such as CC-Switch) send a "health check / connection test" probe request when switching providers. The format of this probe differs from the request format Codex actually uses, so the Qwen Cloud gateway may reject it with 400 Bad request, and the tool then reports "domestic models not supported". This message only indicates that the health check probe failed; it does not mean Qwen Cloud lacks support for domestic models, nor does it affect actual Codex usage. Note: Qwen Cloud supports using domestic models such as qwen3.7-max, qwen3.7-plus, qwen3.6-plus, qwen3.6-flash, and glm-5 through Codex. For configuration details, see Configure access credentials above. Solution: Configure Codex directly in ~/.codex/config.toml as described in Configure access credentials, without relying on the third-party tool's health check result. After configuration, start Codex as described in Verify configuration; if the chat interface launches normally, domestic models are working.

What should I do if I get a wire_api configuration error?

Cause: Newer versions of Codex no longer support wire_api = "chat". Depending on the version, you may see one of the following errors:
  • wire_api = "chat" is no longer supported
  • unknown configuration field wire_api
Solution:
  • Error wire_api = "chat" is no longer supported: Change wire_api to responses and verify that base_url is correct. See Configure access credentials for configuration examples.
  • Error unknown configuration field wire_api: Remove the wire_api line from the corresponding provider section in ~/.codex/config.toml.

What should I do if I get the error "unexpected status 401 Unauthorized"?

Cause:
  • Using an API Key from a different plan (API Keys for Token Plan Personal Edition, Token Plan (Team Edition), Coding Plan, and pay-as-you-go are not interchangeable)
  • Subscription expired
  • API Key was copied incompletely, contains spaces, or has a typo
Solution:
  • Verify that you are using the dedicated API Key for your selected plan.
  • Go to the management page of your selected plan and check whether the subscription has expired.
  • Re-copy the API Key and make sure it is complete and has no spaces.
  • If the error persists after verifying the above, reset the API Key on the management page of your selected plan. After resetting, use the new API Key for configuration.

What should I do if I get the error "unexpected status 404 Not Found"?

Cause: The base_url or wire_api in the configuration file is incorrect. Solution: Verify that base_url and wire_api match the configuration for your selected plan. See the configuration examples for your plan in Configure access credentials above.

What should I do if I get the error "stream disconnected before completion: stream closed before response.completed"?

Cause: The streaming connection between Codex and the server was interrupted before the response completed. This commonly occurs in the following scenarios:
  • The conversation thread is too long, causing a context compaction request to fail
  • Unstable network causing the SSE or WebSocket connection to drop mid-stream
  • Server overload or rate limiting that terminates the connection early
Solution:
  • Start a new conversation thread to avoid excessive context accumulation in a single thread.
  • Check your network connection. Try disabling VPN or proxy and retry.
  • Wait and retry. Codex has a built-in retry mechanism that resolves most transient failures automatically.