Skip to main content

Codex

Use modelos do Alibaba Cloud Model Studio no Codex.

Início rápido

  1. 1

    Abra ou crie o arquivo de configuração

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

    Configure o modelo

    Para alternar entre modelos, consulte Configurar metadados do modelo.
    • Token Plan
    • Pagamento conforme o uso
    • Coding Plan
    Substitua OPENAI_API_KEY pela sua API Key do Token Plan:
    model_provider = "Token_Plan"
    model = "auto"
    
    [model_providers.Token_Plan]
    name = "Token_Plan"
    base_url = "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
    env_key = "OPENAI_API_KEY"
    wire_api = "responses"
    
  3. 3

    Verifique

    Execute o comando a seguir no diretório do seu projeto:
    codex exec "Hello"
    

Configurar metadados do modelo

Os metadados do modelo são usados para alternar entre modelos no Codex. Sem essa configuração, o modelo especificado em config.toml continua funcionando, mas o Codex exibe o aviso Model metadata ... not found na inicialização e usa metadados padrão. Depois de configurar, alterne entre modelos com codex -m ou /model no TUI.
  • Token Plan Personal Edition
  • Token Plan Team Edition
  • Pagamento conforme o uso
Crie ~/.codex/model-catalog.local.json com o seguinte conteúdo:
{
  "models": [
    {
      "slug": "auto",
      "display_name": "auto",
      "description": "DashScope model: auto",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "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
      }
    },
    {
      "slug": "qwen4-max-preview",
      "display_name": "qwen4-max-preview",
      "description": "DashScope model: qwen4-max-preview",
      "default_reasoning_level": "xhigh",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "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": 2,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen4-max",
      "display_name": "qwen4-max",
      "description": "DashScope model: qwen4-max",
      "default_reasoning_level": "high",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "high",
          "description": "Balances speed and reasoning depth"
        },
        {
          "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": 2,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "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": "Balances speed and reasoning depth"
        },
        {
          "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": 3,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen3.8-flash",
      "display_name": "qwen3.8-flash",
      "description": "DashScope model: qwen3.8-flash",
      "default_reasoning_level": "xhigh",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "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": 4,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen3.7-max",
      "display_name": "qwen3.7-max",
      "description": "DashScope model: qwen3.7-max",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 5,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen3.7-plus",
      "display_name": "qwen3.7-plus",
      "description": "DashScope model: qwen3.7-plus",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "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": 6,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen3.6-flash",
      "display_name": "qwen3.6-flash",
      "description": "DashScope model: qwen3.6-flash",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "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": 7,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "glm-5.3",
      "display_name": "glm-5.3",
      "description": "DashScope model: glm-5.3",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 8,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "glm-5.2",
      "display_name": "glm-5.2",
      "description": "DashScope model: glm-5.2",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 9,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "deepseek-v4.1-flash",
      "display_name": "deepseek-v4.1-flash",
      "description": "DashScope model: deepseek-v4.1-flash",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "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": 10,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "deepseek-v4.1-flash-1017",
      "display_name": "deepseek-v4.1-flash-1017",
      "description": "DashScope model: deepseek-v4.1-flash-1017",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "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": 11,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "deepseek-v4-pro",
      "display_name": "deepseek-v4-pro",
      "description": "DashScope model: deepseek-v4-pro",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 12,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "deepseek-v4-pro-0813",
      "display_name": "deepseek-v4-pro-0813",
      "description": "DashScope model: deepseek-v4-pro-0813",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 13,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "deepseek-v4-flash-0731",
      "display_name": "deepseek-v4-flash-0731",
      "description": "DashScope model: deepseek-v4-flash-0731",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 14,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    }
  ]
}
Adicione o seguinte ao ~/.codex/config.toml:
model_catalog_json = "~/.codex/model-catalog.local.json"
Após a configuração, especifique um modelo com codex -m (por exemplo, codex -m qwen3.8-flash) ou insira /model no TUI para alternar entre os modelos configurados.
qwen4-max tem contexto de 1 M de tokens. A saída máxima é de 131.072 tokens no modo sem pensamento e de 262.144 tokens para pensamento e resposta final combinados. Os padrões são reasoning_effort=high e thinking_budget=131072. Use codex -m qwen4-max para selecionar o modelo.

Configuração do Chat Completions

O Codex 0.94.0 e versões posteriores são compatíveis apenas com a API Responses. Se você usar o Codex 0.93.0 ou uma versão anterior, ou se o seu modelo for compatível apenas com Chat Completions, use a configuração a seguir. Para o caminho do arquivo de configuração, consulte Início rápido.
  • Token Plan
  • Pagamento conforme o uso
  • Coding Plan
Substitua OPENAI_API_KEY pela sua API Key do Token Plan:
model_provider = "Token_Plan"
model = "auto"

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

Usar o CC Switch

O CC Switch é uma GUI desktop de código aberto da comunidade que permite alternar entre API Keys ou planos de cobrança.

Adicionar um provedor

  1. 1
    Na barra de ferramentas do CC Switch, selecione o ícone do Codex, clique em + para abrir Add provider, selecione a aba do seu plano de cobrança, preencha a configuração e clique em Add.
    • Token Plan
    • Pagamento conforme o uso
    • Coding Plan
    • Nome do provedor: Bailian-Token Plan
    • API Key: Obter no console
    • Endpoint: https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
  2. 2
    Expanda Advanced options e insira um modelo dos modelos compatíveis para o seu plano, como qwen3.8-max.
  3. 3
    Clique em Enable ao lado do provedor, reabra o terminal e execute codex para que a configuração passe a valer.

Códigos de erro

Se você encontrar erros durante a configuração, consulte a documentação de perguntas frequentes do seu plano de cobrança:

Perguntas frequentes

Este aviso aparece quando os metadados do modelo não estão configurados. O Codex usa metadados padrão para o modelo, e as chamadas não são afetadas. Para alternar entre modelos, consulte Configurar metadados do modelo.
A configuração de pagamento conforme o uso permanece a mesma: use a chave de API geral do Model Studio e a Base URL. Após comprar um plano de economia, ele entra em vigor automaticamente e o uso elegível é deduzido automaticamente. Consulte Planos de economia.
Causa: Algumas ferramentas de gerenciamento de terceiros (como o CC-Switch) enviam uma verificação de integridade ou um teste de conexão ao alternar de provedor. O formato do teste é diferente do formato de requisição que o Codex realmente usa, portanto o gateway do Model Studio pode retornar 400 Bad request, e a ferramenta relata "domestic models not supported". Essa mensagem indica apenas que o teste falhou; não significa que o Model Studio não tenha suporte a modelos da China (continental), nem afeta o uso real do Codex.Solução: Configure o Codex diretamente em ~/.codex/config.toml conforme descrito em Início rápido, sem depender da verificação de integridade da ferramenta de terceiros. Após a configuração, siga Verifique para iniciar o Codex; uma resposta normal indica que os modelos da China (continental) estão funcionando.
Causa: O Codex 0.94.0 e versões posteriores não são mais compatíveis com wire_api = "chat". Dependendo da versão, você pode ver um dos seguintes erros:
  • wire_api = "chat" is no longer supported
  • unknown configuration field wire_api
Solução:
  • Erro wire_api = "chat" is no longer supported: altere wire_api para responses e verifique base_url.
  • Erro unknown configuration field wire_api: remova wire_api da seção do provedor correspondente em ~/.codex/config.toml.
  • Para continuar usando o Chat Completions, instale o Codex 0.93.0 ou uma versão anterior (como 0.80.0).
Causa:
  • A API Key pertence a outro plano (as chaves do Token Plan, do Coding Plan e do Pagamento conforme o uso não são intercambiáveis).
  • A assinatura expirou.
  • A API Key foi copiada incorretamente (incompleta, com espaços extras ou com erro de digitação).
Solução:
  • Confirme que você está usando a API Key do plano selecionado.
  • Verifique a página de gerenciamento do plano para saber se a assinatura expirou.
  • Copie novamente a API Key e certifique-se de que ela esteja completa e sem espaços.
  • Se o erro persistir, redefina a API Key na página de gerenciamento do plano e configure a nova chave.
Causa: base_url ou wire_api no arquivo de configuração está incorreto.Solução: Certifique-se de que base_url e wire_api correspondam à configuração do seu plano. Consulte Início rápido.
Causa: A conexão de streaming entre o Codex e o servidor foi encerrada antes da conclusão da resposta. Causas comuns:
  • A conversa está muito longa e a compactação de contexto falha.
  • A rede está instável e a conexão SSE ou WebSocket cai.
  • O servidor está sobrecarregado ou o limite de taxa encerra a conexão antecipadamente.
Solução:
  • Inicie uma nova conversa para evitar acúmulo excessivo de contexto.
  • Verifique a estabilidade da rede. Desative a VPN ou o proxy e tente novamente.
  • Aguarde e tente novamente. O Codex tem um mecanismo de nova tentativa integrado que resolve a maioria das falhas temporárias.
Causa: Um erro 429 tem duas causas comuns:
  • Limite de taxa de requisições (429 Requests rate limit exceeded): muitas requisições em um curto período.
  • Cota esgotada (429 Allocated quota exceeded ou Your token-plan quota has been exhausted): a cota mensal do Token Plan foi usada por completo.
Solução:
  • Limite de taxa de requisições: aguarde um minuto e reduza a taxa de requisições.
  • Cota esgotada: aguarde o próximo mês de assinatura, compre um pacote de uso (a cota é deduzida automaticamente do pacote depois que a cota mensal é usada por completo) ou faça upgrade do plano. O horário de redefinição na mensagem de erro (como The quota will reset at HH:MM:SS UTC) está em UTC; adicione 8 horas para converter para o horário de Singapura (CST).