Skip to main content
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
Clients and Developer Tools

Codex

Codex is OpenAI's terminal AI coding assistant. Connect it to Alibaba Cloud Model Studio via Token Plan Personal Edition, Token Plan Team Edition, Coding Plan, or pay-as-you-go.

Install Codex

  1. Install or update Node.js (v18.0 or later).
  2. Install Codex:
npm install -g @openai/codex
Verify the installation: 
codex --version

Configure Access Credentials

Edit ~/.codex/config.toml and set the OPENAI_API_KEY environment variable for your billing plan:

Configure Model Metadata

When using custom models such as qwen3.8-max, 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",
      "display_name": "qwen3.8-max",
      "description": "DashScope model: qwen3.8-max",
      "default_reasoning_level": "xhigh",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "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"],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 1,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    }  ]
}
  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. Set the OPENAI_API_KEY environment variable to the Token Plan Personal Edition dedicated API Key.

Responses API

If the selected model supports the OpenAI Responses API, you can use the latest Codex version. 
model_provider = "Model_Studio_Token_Plan_Personal"
model = "qwen3.8-max"
[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"

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. Check your default shell:
echo $SHELL
  1. Set the environment variable based on your shell type:

    Zsh 

# Replace YOUR_API_KEY with the Token Plan Personal Edition API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc

Bash 

# Replace YOUR_API_KEY with the Token Plan Personal Edition API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.bash_profile
  1. Apply the change:

    Zsh 

source ~/.zshrc

Bash 

source ~/.bash_profile

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

If the selected model supports the OpenAI Responses API, you can use the latest Codex version. 
model_provider = "Model_Studio_Token_Plan"
model = "qwen3.8-max"
[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 require the Chat/Completions API. Install 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. Check your default shell:
echo $SHELL
  1. Set the environment variable based on your shell type:

    Zsh 

# Replace YOUR_API_KEY with the Token Plan Team Edition API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc

Bash 

# Replace YOUR_API_KEY with the Token Plan Team Edition API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.bash_profile
  1. Apply the change:

    Zsh 

source ~/.zshrc

Bash 

source ~/.bash_profile

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. Check your default shell:
echo $SHELL
  1. Set the environment variable based on your shell type:

    Zsh 

# Replace YOUR_API_KEY with the Coding Plan API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc

Bash 

# Replace YOUR_API_KEY with the Coding Plan API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.bash_profile
  1. Apply the change:

    Zsh 

source ~/.zshrc

Bash 

source ~/.bash_profile

Pay-as-you-go

Set OPENAI_API_KEY to your Model Studio API Key and choose from the supported models. Set base_url for your region. The API Key must match the selected region, replace {WorkspaceId} in the URL with your actual Workspace ID:
  • China North 2 (Beijing): https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
  • Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Pay-as-you-go supports both the Responses API and Chat/Completions API. Choose based on your model:

Responses API

For models supporting the OpenAI Responses API (such as qwen3.7-max), compatible with the latest Codex version. 
model_provider = "Model_Studio"
model = "qwen3.7-max"
[model_providers.Model_Studio]
name = "Model_Studio"
base_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Chat/Completions API

For models that only support the Chat/Completions API. Install Codex 0.80.0: 
model_provider = "Model_Studio"
model = "qwen3.6-plus"
[model_providers.Model_Studio]
name = "Model_Studio"
base_url = "https://{WorkspaceId}.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 Model Studio API Key.
  • macOS
  • Windows
  1. Check your default shell:
echo $SHELL
  1. Set the environment variable based on your shell type:

    Zsh 

# Replace YOUR_API_KEY with the Model Studio API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc

Bash 

# Replace YOUR_API_KEY with the Model Studio API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.bash_profile
  1. Apply the change:

    Zsh 

source ~/.zshrc

Bash 

source ~/.bash_profile

Verify Configuration

Open a new terminal and start Codex: 
codex
If the chat interface launches, 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 Model Studio 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 Model Studio lacks support for domestic models, nor does it affect actual Codex usage. Note: Model Studio supports using China (mainland) models 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:
  • API Key mismatch (Token Plan, Coding Plan, and pay-as-you-go keys are not interchangeable)
  • Subscription expired
  • API Key copied incorrectly (incomplete, contains spaces, or has a typo)
Solution:
  • Confirm you are using the correct API Key for your plan.
  • Check your plan's management page for subscription expiration.
  • Re-copy the API Key without extra spaces.
  • If the error persists, reset the API Key on your plan's management page and reconfigure with the new key.

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: Ensure base_url and wire_api match your plan's configuration 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.
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
Get Started
Billing
Token Plan
Model Playground
  • Music generation
Clients and Developer Tools
Model Inference
Fine-tuning
Deployment
Evaluation
Statistics and Monitoring
Security and Compliance
Best Practices
Support
Changelog
Codex - Alibaba Cloud Model Studio