DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio Token Plan Connect AI tools Codex

Codex

Updated at:
Copy as MD
Product
My Favorites

Use Alibaba Cloud Model Studio models in Codex.

Quick Start

  1. 1

    Open or create the configuration file

    • macOS / Linux: ~/.codex/config.toml
    • Windows: C:\Users\<username>\.codex\config.toml
  2. 2

    Configure the model

    Token Plan

    Replace OPENAI_API_KEY with your Token Plan API Key:

    model_provider = "Token_Plan"
model = "auto"

[model_providers.Token_Plan]
name = "Token_Plan"
base_url = "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

    Pay-as-you-go

    Replace OPENAI_API_KEY with your Alibaba Cloud Model Studio API Key, and replace {WorkspaceId} with your actual Workspace ID. The following example uses China North 2 (Beijing).

    model_provider = "Model_Studio"
model = "qwen3.7-max"

[model_providers.Model_Studio]
name = "Model_Studio"
base_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

    Coding Plan

    Replace OPENAI_API_KEY with your Coding Plan API Key. Coding Plan uses the Chat Completions API and requires Codex 0.93.0 or an earlier version:

    npm install -g @openai/codex@0.93.0

    model_provider = "Coding_Plan"
model = "qwen3.7-plus"

[model_providers.Coding_Plan]
name = "Coding_Plan"
base_url = "https://coding.dashscope.aliyuncs.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"
  3. 3

    Verify

    Run the following command in your project directory:

    codex exec "Hello"

Chat Completions configuration

Codex 0.94.0 and later support only the Responses API. If you use Codex 0.93.0 or an earlier version, or your model supports only Chat Completions, use the following configuration.

  1. 1

    Open or create the configuration file

    • macOS / Linux: ~/.codex/config.toml
    • Windows: C:\Users\<username>\.codex\config.toml
  2. 2

    Write the configuration

    Token Plan

    Replace OPENAI_API_KEY with your Token Plan API Key:

    model_provider = "Token_Plan"
model = "auto"

[model_providers.Token_Plan]
name = "Token_Plan"
base_url = "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

    Pay-as-you-go

    Replace OPENAI_API_KEY with your Alibaba Cloud Model Studio API Key, and replace {WorkspaceId} with your actual Workspace ID. The following example uses China North 2 (Beijing):

    model_provider = "Model_Studio"
model = "qwen3.8-max"

[model_providers.Model_Studio]
name = "Model_Studio"
base_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

    Coding Plan

    Replace OPENAI_API_KEY with your Coding Plan API Key.

    model_provider = "Coding_Plan"
model = "qwen3.7-plus"

[model_providers.Coding_Plan]
name = "Coding_Plan"
base_url = "https://coding.dashscope.aliyuncs.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

Use CC Switch

CC Switch is a community open-source desktop GUI that switches between API Keys or billing plans.

Add a provider

  1. 1

    In the CC Switch toolbar, select the Codex icon, click + to open Add provider, select the tab for your billing plan, fill in the configuration, and click Add.

    Token Plan

    • Provider name: Bailian-Token Plan
    • API Key: Get from console
    • Endpoint: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

    Pay-as-you-go

    • Provider name: Bailian-Pay-as-you-go
    • API Key: Get from console
    • Endpoint: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

    Coding Plan

    • Provider name: Bailian-Coding Plan
    • API Key: Get from console
    • Endpoint: https://coding.dashscope.aliyuncs.com/v1
  2. 2

    Expand Advanced options and enter a model from the supported models for your plan, such as qwen3.8-max.

  3. 3

    Click Enable next to the provider, then reopen the terminal and run codex for the configuration to take effect.

Error Codes

If you encounter errors during configuration, refer to the FAQ documentation for your billing plan:

FAQ

How do I use savings plans and resource plans with pay-as-you-go?

The pay-as-you-go setup remains the same: use your general Model Studio API key and Base URL. After you purchase a savings plan or resource plan, it takes effect automatically and eligible usage is deducted automatically. See Savings plans and resource plans.

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 or connection test probe when switching providers. The probe format differs from the request format Codex actually uses, so the Model Studio gateway may return 400 Bad request, and the tool reports "domestic models not supported". This message only indicates that the probe failed; it does not mean Model Studio lacks support for China (mainland) models, nor does it affect actual Codex usage.

Solution: Configure Codex directly in ~/.codex/config.toml as described in Quick Start, without relying on the third-party tool's health check. After configuration, follow Verify to start Codex; a normal response means China (mainland) models are working.

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

Cause: Codex 0.94.0 and later 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 base_url.
  • Error unknown configuration field wire_api: Remove wire_api from the corresponding provider section in ~/.codex/config.toml.
  • To continue using Chat Completions, install Codex 0.93.0 or an earlier version (such as 0.80.0).

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

Cause:

  • The API Key belongs to another plan (Token Plan, Coding Plan, and Pay-as-you-go keys are not interchangeable).
  • The subscription has expired.
  • The API Key was copied incorrectly (incomplete, extra spaces, or typo).

Solution:

  • Confirm that you are using the API Key for the selected plan.
  • Check the plan management page for subscription expiration.
  • Re-copy the API Key and make sure it is complete with no spaces.
  • If the error persists, reset the API Key on the plan management page and configure the new key.

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

Cause: base_url or wire_api in the configuration file is incorrect.

Solution: Make sure base_url and wire_api match the configuration for your plan. See Quick Start.

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 closed before the response completed. Common causes:

  • The conversation thread is too long and context compaction fails.
  • The network is unstable and the SSE or WebSocket connection drops.
  • The server is overloaded or rate limiting terminates the connection early.

Solution:

  • Start a new conversation thread to avoid excessive context accumulation.
  • Check network stability. Disable VPN or proxy and retry.
  • Wait and retry. Codex has a built-in retry mechanism that resolves most transient failures.

What should I do if I get a 429 rate limit or quota error?

Cause: A 429 error has two common causes:

  • Request rate limit (429 Requests rate limit exceeded): too many requests in a short period.
  • Quota exhausted (429 Allocated quota exceeded or Your token-plan quota has been exhausted): the monthly Token Plan quota is used up.

Solution:

  • Request rate limit: wait one minute and reduce the request rate.
  • Quota exhausted: wait for the next subscription month, purchase a usage package (quota automatically deducts from the package after the monthly quota is used up), or upgrade the plan. The reset time in the error message (such as The quota will reset at HH:MM:SS UTC) is in UTC; add 8 hours to convert to Beijing time (CST).
Previous：Claude CodeNext：Qwen Code