Codex com endpoints Responses e profiles

O contrato atual

O arquivo-fonte oficial config_toml.rs expõe model_provider, a tabela model_providers e profiles. A definição do provedor usa base_url, env_key e wire_api. Na linha atual do Codex, wire_api = "responses" é o caminho suportado; Chat não deve ser configurado como se fosse Responses.

Isso é sensível à versão. Antes de copiar a configuração, execute:

codex --version
codex --help

Valide a sintaxe contra a versão instalada. Em algumas versões, -p seleciona uma camada de configuração em vez da tabela TOML histórica; o override -c 'profile="..."' abaixo torna a intenção explícita, mas também deve ser testado localmente.

Configuração segura de ~/.codex/config.toml

O exemplo usa nomes de variáveis, nunca os segredos. Substitua os modelos entre <...> por identificadores confirmados na região e no plano. O gateway local deve implementar a API Responses de ponta a ponta.

profile = "deepseek"

[model_providers.deepseek]
name = "DeepSeek Responses"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

[model_providers.qwen_singapore]
name = "Alibaba Model Studio Singapore Responses"
base_url = "https://<WORKSPACE_ID>.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"
wire_api = "responses"

[model_providers.minimax_international]
name = "MiniMax International Responses"
base_url = "https://api.minimax.io/v1"
env_key = "MINIMAX_API_KEY"
wire_api = "responses"

[model_providers.local_responses_gateway]
name = "Local Responses Gateway"
base_url = "http://127.0.0.1:8787/v1"
env_key = "LOCAL_GATEWAY_TOKEN"
wire_api = "responses"

[profiles.deepseek]
model_provider = "deepseek"
model = "deepseek-v4-flash"

[profiles.qwen_singapore]
model_provider = "qwen_singapore"
model = "<QWEN_RESPONSES_MODEL_IN_SINGAPORE>"

[profiles.minimax_international]
model_provider = "minimax_international"
model = "MiniMax-M3"

[profiles.kimi_via_gateway]
model_provider = "local_responses_gateway"
model = "kimi-k3"

[profiles.glm_via_gateway]
model_provider = "local_responses_gateway"
model = "glm-5.2"

Por que env_key importa: ele diz ao Codex qual variável ler. O valor da chave continua fora do TOML. Não use campos que armazenem bearer tokens literais só porque aparecem em um tutorial antigo.

O exemplo separa perfis por região e protocolo. Se você também usa MiniMax China ou Alibaba Beijing, crie provedores diferentes; não reutilize o mesmo nome mudando a URL manualmente.

Smoke tests do Codex

codex --strict-config -c 'profile="deepseek"' exec \
  'Reply exactly: codex-text-ok'

codex --strict-config -s read-only -c 'profile="deepseek"' exec \
  'Use the shell once to run pwd, change no files, then reply exactly: codex-tool-ok'

Repita para cada perfil. Para Kimi e GLM, registre também a versão do gateway e confirme que ele preserva IDs de chamada, resultados, erros, streaming e cancelamento. Um adaptador que apenas converte o primeiro prompt não suporta um agente.

Toy versus produção

O salto principal não é de volume; é de observabilidade. Sem saber qual modelo, protocolo, região e versão responderam, você não consegue reproduzir uma falha nem atribuir custo.

Quatro falhas reais e como diagnosticá-las

1. 401, 403 ou “invalid key” depois de copiar uma URL

Diagnóstico: a chave pertence a outra região, plano ou produto; o header esperado difere; ou o secret não chegou ao processo.

Ação: verifique apenas presença e origem da variável, nunca imprima seu valor. Compare host, região e plano na console do provedor. Gere uma credencial de menor privilégio e repita o smoke test.

Evidência de correção: autenticação funciona no endpoint contratado e a telemetria registra região e perfil sem registrar o header.

2. Texto funciona, mas a primeira ferramenta quebra

Diagnóstico: compatibilidade superficial. O endpoint aceita mensagens, mas ignora tools, altera IDs ou não devolve eventos que o runtime espera.

Ação: capture um transcript redigido, compare request/response com a documentação e teste uma ferramenta read-only antes de patch. No DeepSeek Responses, confira explicitamente a lista de ferramentas e campos suportados.

Evidência de correção: chamada, resultado e continuação usam o mesmo ID; o agente observa o resultado e conclui a tarefa.

3. 404, modelo inexistente ou erro só em uma conta

Diagnóstico: endpoint certo no protocolo errado, modelo ausente naquela região, WorkspaceId incorreto ou plano sem Responses.

Ação: liste modelos quando o provedor oferecer esse endpoint, confira a documentação regional e trate cada combinação região+plano como um perfil distinto.

Evidência de correção: o modelo resolvido aparece no log e corresponde ao catálogo da mesma região e conta.

4. O agente degrada em contexto longo ou fica caro sem aviso

Diagnóstico: janela anunciada confundida com contexto útil; cache, compactação, reasoning tokens, fila ou retries não foram medidos.

Ação: execute a mesma tarefa em faixas crescentes de contexto, inclua uma informação-agulha e registre recuperação, primeiro token, duração total, tokens, ferramentas, retries e custo faturado.

Evidência de correção: existem limites operacionais por perfil e fallback antes de ultrapassá-los.

Logs e telemetria sem vazar o trabalho

Registre por execução:

• timestamp, ambiente e ID interno da tarefa;
• versão do Claude Code ou Codex e, quando houver, do gateway;
• provider solicitado, provider efetivo, modelo, protocolo, plano e região;
• request ID do provedor, status e classe de erro;
• tempo até o primeiro evento, duração total e cancelamento;
• tokens de entrada, saída, cache e raciocínio quando o provedor os reportar;
• número e tipo de ferramentas, retries, fallback e resultado do critério de sucesso;
• estimativa e valor faturado quando a API de billing permitir reconciliar.

Não registre tokens, headers, prompts brutos, código proprietário ou saída de ferramentas por padrão. Debug do cliente pode conter material sensível. Ative-o por tempo limitado, em diretório protegido, com redaction e retenção curta.

Latência média esconde filas e valores extremos. Compare pelo menos p50 e p95, separando tempo do provedor, do gateway e das ferramentas locais.

Custo por milhão de tokens também pode enganar. Para agentes, acompanhe custo por tarefa aceita, incluindo novas tentativas e chamadas de ferramenta.

Rollback: desenhe antes do rollout

Para Claude Code, o wrapper por processo oferece rollback simples: encerre a sessão e remova as variáveis. Para configuração persistente, mantenha uma cópia anterior com permissões restritas e não inclua segredos nela.

Para Codex:

1. preserve o config.toml funcional antes da mudança;
2. adicione novos provedores e perfis sem remover o perfil anterior;
3. valide com --strict-config e sandbox read-only;
4. faça um teste canário com tarefas não sensíveis;
5. em falha, volte profile ao provedor anterior ou restaure o arquivo preservado;
6. revogue tokens temporários e encerre o gateway, se usado.

Rollback não está completo até ser testado. O critério é restaurar uma tarefa conhecida sem editar novamente URLs ou segredos durante o incidente.

Critérios de sucesso para promover uma rota

Falhar em um gate não significa abandonar o modelo. Significa manter a rota em laboratório ou restringi-la ao tipo de tarefa que passou.

Exercícios

Exercício 1: prove o protocolo

Escolha um provedor e execute o teste de texto e o de ferramenta. Salve somente metadados redigidos. Explique qual evidência demonstra Responses ou Anthropic Messages, em vez de apenas “OpenAI-compatible”.

Exercício 2: encontre a fronteira de contexto

Crie documentos sintéticos de 32K, 128K e uma faixa maior suportada pelo plano. Coloque um nonce no início, meio e fim. Meça recuperação, latência, tokens e compactação. Defina o limite em que seu agente deve resumir ou trocar de rota.

Exercício 3: ensaie a queda

Em ambiente descartável, simule credencial inválida, 429, timeout e gateway indisponível. Confirme que não há fallback silencioso, que nenhum segredo aparece no log e que o perfil anterior volta a operar.

Checklist de adoção

• Data da documentação e nomes dos modelos foram reconfirmados.
• Endpoint corresponde à região, conta e plano contratados.
• Claude Code usa rota Anthropic documentada para aquela oferta.
• Codex usa Responses direto ou gateway Responses explicitamente testado.
• A versão instalada dos dois CLIs foi registrada e validada.
• Segredos ficam em secret manager ou sessão, nunca no Markdown/TOML.
• Texto, tool call, patch, erro, contexto e cancelamento passaram.
• Compatibilidade parcial e campos ignorados estão inventariados.
• Logs registram rota efetiva sem prompt, código ou credencial.
• Custo e p50/p95 foram medidos na carga real.
• DPA, retenção, treino, suboperadores e região foram aprovados.
• Fallback é explícito e auditável.
• Rollback foi executado, não apenas documentado.

Fontes oficiais verificadas

Todas foram consultadas em 12 de agosto de 2026.

• DeepSeek: coding agents e integrações
• DeepSeek: Anthropic-compatible API
• DeepSeek: listar modelos
• DeepSeek: Responses API e limites de compatibilidade
• DeepSeek: política de privacidade
• Alibaba Cloud: o que é Model Studio
• Alibaba Cloud: Qwen Code
• Alibaba Cloud: Claude Code
• Alibaba Cloud: Codex
• Z.AI: GLM-5.2
• Z.AI: Claude Code
• Z.AI: outras ferramentas e protocolos
• Z.AI: política de privacidade
• Kimi: visão geral da API
• Kimi: Claude Code
• Kimi: Codex e roteador
• Kimi: política de privacidade
• MiniMax: outras ferramentas
• MiniMax: visão geral da API
• MiniMax: Claude Code
• MiniMax: Codex
• OpenAI Codex: estrutura de config.toml
• OpenAI Codex: definição de providers e wire_api

Conclusão

LLMs chinesas já são opções práticas para engenharia e agentes, mas não formam uma categoria tecnicamente uniforme. DeepSeek, Qwen, GLM, Kimi e MiniMax oferecem combinações diferentes de protocolo, região, plano e semântica de ferramentas.

A escolha robusta não começa por um ranking. Começa perguntando: qual contrato o cliente exige, qual endpoint a região oferece, o que acontece com os dados e como provar que uma ferramenta completou o ciclo?

Com perfis separados, segredos fora de arquivos, smoke tests que usam ferramentas, telemetria redigida e rollback ensaiado, trocar de modelo deixa de ser uma aposta. Torna-se uma mudança operacional controlada.