Alibaba Cloud Model Studio:Codex

O Codex é o assistente de codificação por IA para terminal da OpenAI. Conecte-o ao Alibaba Cloud Model Studio por meio do Token Plan Personal Edition, Token Plan Team Edition, Coding Plan ou pagamento conforme o uso.

Instalar o Codex

1. Instale ou atualize o Node.js (v18.0 ou posterior).
2. Instale o Codex:

npm install -g @openai/codex

Verifique a instalação:

codex --version

Configurar credenciais de acesso

Edite o arquivo ~/.codex/config.toml e defina a variável de ambiente OPENAI_API_KEY de acordo com seu plano de faturamento:

Configurar metadados do modelo

Ao usar modelos personalizados como qwen3,8-max, configure o arquivo de metadados do modelo para que o Codex reconheça corretamente a janela de contexto, a profundidade de raciocínio e outros parâmetros.

1. Crie o arquivo ~/.codex/model-catalog.local.json com o seguinte conteúdo:

{
  "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
      }
    }  ]
}

2. Adicione a linha abaixo ao arquivo ~/.codex/config.toml para apontar para o arquivo de metadados:

model_catalog_json = "~/.codex/model-catalog.local.json"

Token Plan Personal Edition

Para model, selecione um supported model. Defina a variável de ambiente OPENAI_API_KEY como a API Key dedicada do Token Plan Personal Edition.

Responses API

Se o modelo selecionado for compatível com a OpenAI Responses API, use a versão mais recente do Codex.

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 (outros modelos)

Os demais modelos exigem a Chat/Completions API. Instale uma versão anterior do Codex, como a 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"

Configurar variáveis de ambiente

Defina a variável de ambiente OPENAI_API_KEY como a API Key dedicada do Token Plan Personal Edition.

echo $SHELL

REM Replace YOUR_API_KEY with the Token Plan Personal Edition API Key
setx OPENAI_API_KEY "YOUR_API_KEY"

echo %OPENAI_API_KEY%

# Replace YOUR_API_KEY with the Token Plan Personal Edition API Key
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)

echo $env:OPENAI_API_KEY

Token Plan Team Edition

Para model, selecione um supported model. Defina a variável de ambiente OPENAI_API_KEY como a API Key dedicada do Token Plan Team Edition.

Responses API

Se o modelo escolhido for compatível com a OpenAI Responses API, use a versão mais recente do Codex.

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 (outros modelos)

Outros modelos exigem a Chat/Completions API. Instale uma versão anterior do Codex, como a 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"

Configurar variáveis de ambiente

Defina a variável de ambiente OPENAI_API_KEY como a API Key dedicada do Token Plan Team Edition.

echo $SHELL

REM Replace YOUR_API_KEY with the Token Plan Team Edition API Key
setx OPENAI_API_KEY "YOUR_API_KEY"

echo %OPENAI_API_KEY%

# Replace YOUR_API_KEY with the Token Plan Team Edition API Key
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)

echo $env:OPENAI_API_KEY

Coding Plan

Para model, selecione um supported model. Defina a variável de ambiente OPENAI_API_KEY como a API Key dedicada do Coding Plan.

Chat/Completions API

O Coding Plan oferece suporte apenas à Chat/Completions API. Instale uma versão anterior do Codex, como a 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"

Configurar variáveis de ambiente

Defina a variável de ambiente OPENAI_API_KEY como a API Key dedicada do Coding Plan.

echo $SHELL

REM Replace YOUR_API_KEY with the Coding Plan API Key
setx OPENAI_API_KEY "YOUR_API_KEY"

echo %OPENAI_API_KEY%

# Replace YOUR_API_KEY with the Coding Plan API Key
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)

echo $env:OPENAI_API_KEY

Pagamento conforme o uso

Defina OPENAI_API_KEY como sua Model Studio API Key e escolha entre os supported models.

Configure base_url para sua região. A API Key deve corresponder à região selecionada; substitua {WorkspaceId} na URL pelo seu Workspace ID real:

• 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

O pagamento conforme o uso é compatível tanto com a Responses API quanto com a Chat/Completions API. Escolha de acordo com o seu modelo:

Responses API

Use esta opção para modelos compatíveis com a OpenAI Responses API (como qwen3,7-max), compatíveis com a versão mais recente do Codex.

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

Use esta opção para modelos que oferecem suporte apenas à Chat/Completions API. Instale o 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"

Configurar variáveis de ambiente

Defina a variável de ambiente OPENAI_API_KEY como a Model Studio API Key.

echo $SHELL

REM Replace YOUR_API_KEY with the Model Studio API Key
setx OPENAI_API_KEY "YOUR_API_KEY"

echo %OPENAI_API_KEY%

# Replace YOUR_API_KEY with the Model Studio API Key
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)

echo $env:OPENAI_API_KEY

Verificar configuração

Abra um novo terminal e inicie o Codex:

codex

Se a interface de chat iniciar, a configuração estará correta.

FAQ

O que fazer se uma ferramenta de terceiros relatar "modelos domésticos não suportados" ou "verificação rejeitada / Bad request (400)"?

Causa: Algumas ferramentas de gerenciamento de terceiros (como CC-Switch) enviam uma solicitação de sondagem de "verificação de integridade / teste de conexão" ao trocar de provedor. O formato dessa sondagem difere do formato de solicitação usado pelo Codex, o que pode levar o gateway do Model Studio a rejeitá-la com 400 Bad request. Consequentemente, a ferramenta relata "modelos domésticos não suportados". Essa mensagem indica apenas falha na sondagem de verificação de integridade; não significa que o Model Studio não ofereça suporte a modelos domésticos, nem afeta o uso real do Codex.

Nota: O Model Studio permite o uso de modelos da china continental por meio do Codex. Para detalhes de configuração, consulte Configure Access Credentials acima.

Solução: Configure o Codex diretamente em ~/.codex/config.toml conforme descrito em Configurar credenciais de acesso, sem depender do resultado da verificação de integridade da ferramenta de terceiros. Após configurar, inicie o Codex conforme descrito em Verify Configuration; se a interface de chat iniciar normalmente, os modelos domésticos estarão funcionando.

O que fazer em caso de erro de configuração wire_api?

Causa: Versões mais recentes do Codex não oferecem mais suporte a wire_api = "chat". Dependendo da versão, você poderá 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 se base_url está correto. Consulte Configure Access Credentials para exemplos de configuração.
• Erro unknown configuration field wire_api: Remova a linha wire_api da seção do provedor correspondente em ~/.codex/config.toml.

O que fazer ao receber o erro unexpected status 401 Unauthorized?

Causa:

• Incompatibilidade de API Key (as chaves do Token Plan, Coding Plan e pagamento conforme o uso não são intercambiáveis)
• Assinatura expirada
• API Key copiada incorretamente (incompleta, contém espaços ou possui erro de digitação)

Solução:

• Confirme se está usando a API Key correta para o seu plano.
• Verifique a página de gerenciamento do seu plano quanto à expiração da assinatura.
• Copie novamente a API Key sem espaços extras.
• Se o erro persistir, redefina a API Key na página de gerenciamento do seu plano e reconfigure com a nova chave.

O que fazer ao receber o erro unexpected status 404 Not Found?

Causa: O base_url ou wire_api no arquivo de configuração está incorreto.

Solução: Garanta que base_url e wire_api correspondam à configuração do seu plano em Configure Access Credentials acima.

O que fazer ao receber o erro "stream disconnected before completion: stream closed before response.completed"?

Causa: A conexão de streaming entre o Codex e o servidor foi interrompida antes da conclusão da resposta. Isso ocorre frequentemente nos seguintes cenários:

• Thread de conversa muito longo, causando falha na solicitação de compactação de contexto
• Rede instável causando queda da conexão SSE ou WebSocket durante a transmissão
• Sobrecarga do servidor ou limitação de taxa encerrando a conexão prematuramente

Solução:

• Inicie um novo thread de conversa para evitar acúmulo excessivo de contexto em um único thread.
• Verifique sua conexão de rede. Tente desativar VPN ou proxy e tente novamente.
• Aguarde e tente novamente. O Codex possui um mecanismo de nova tentativa integrado que resolve a maioria das falhas transitórias automaticamente.