Ligar modelos externos ao Codex

Este guia abrange dois métodos de integração para modelos alojados de terceiros:

Existe uma limitação importante que deve compreender primeiro:

Este guia aplica-se a clientes Codex executados localmente, incluindo o Codex CLI, a extensão Codex para IDE e clientes de ambiente de trabalho que leem o mesmo config.toml. Atualmente, as conversas na nuvem do Codex não podem mudar para um modelo personalizado através desta configuração.

Antes de começar

Instalar ou atualizar o Codex CLI

npm install -g @openai/codex@latest
codex --version

Após a primeira instalação, execute o Codex pelo menos uma vez:

codex

Esta ação inicializa o diretório de configuração do utilizador.

Localizações do ficheiro de configuração do Codex

macOS e Linux:

~/.codex/config.toml

Windows:

%USERPROFILE%\.codex\config.toml

Crie uma cópia de segurança do ficheiro antes de efetuar alterações.

macOS / Linux:

mkdir -p ~/.codex/backup
cp ~/.codex/config.toml \
  ~/.codex/backup/config.toml.$(date +%Y%m%d-%H%M%S) \
  2>/dev/null || true

PowerShell:

$codexDir = Join-Path $HOME ".codex"
$backupDir = Join-Path $codexDir "backup"
New-Item -ItemType Directory -Force -Path $backupDir | Out-Null

$configFile = Join-Path $codexDir "config.toml"
if (Test-Path $configFile) {
  $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
  Copy-Item $configFile (Join-Path $backupDir "config.toml.$timestamp")
}

Fornecedores, MCP e gateways de modelos são diferentes

Estes conceitos resolvem problemas diferentes:

• model_provider determina para onde o Codex envia os pedidos ao modelo;
• o MCP adiciona ferramentas e contexto, como GitHub, navegadores ou bases de dados;
• um gateway de modelos gere a conversão de protocolo, a autenticação, o encaminhamento, os registos ou a limitação de frequência entre o Codex e um modelo a montante.

Para alterar o modelo subjacente, configure um fornecedor em vez do MCP.

Proteger API keys

Não submeta API keys reais para um repositório Git nem exponha chaves completas em capturas de ecrã, registos ou pedidos de suporte.

Para fornecedores configurados manualmente, dê preferência a variáveis de ambiente:

[model_providers.example]
env_key = "EXAMPLE_API_KEY"

O CC Switch armazena localmente a configuração dos fornecedores e modifica a configuração local do Codex quando alterna entre fornecedores. É uma ferramenta de código aberto de terceiros, não um produto da OpenAI. Instale-a apenas a partir do site oficial ou do repositório GitHub do CC Switch e proteja a respetiva base de dados local, configuração e cópias de segurança.

1. Ligar modelos de terceiros com o CC Switch

O CC Switch é a opção mais simples para a maioria dos modelos de terceiros. Gere fornecedores, API keys, listas de modelos e encaminhamento local, podendo também traduzir protocolos a montante incompatíveis.

1.1 O que o CC Switch resolve

Os clientes Codex modernos enviam pedidos da Responses API, enquanto muitos serviços de terceiros disponibilizam uma das seguintes opções:

• OpenAI Chat Completions;
• Anthropic Messages;
• IDs de modelos que o Codex não apresenta por predefinição;
• parâmetros de raciocínio ou formatos de eventos de transmissão específicos do fornecedor.

O CC Switch pode traduzir o percurso do pedido da seguinte forma:

Codex
  │  Responses API
  ▼
CC Switch local route
  │  Converts the protocol and model name when required
  ▼
Third-party model API
  │
  ▼
CC Switch converts JSON, SSE, reasoning data, and tool calls back to Responses
  │
  ▼
Codex

Um fornecedor que suporte Responses de forma nativa não necessita de conversão do protocolo Chat. Um fornecedor de Chat Completions ou Anthropic Messages requer encaminhamento local.

1.2 Instalar o CC Switch

Utilize apenas os canais de distribuição oficiais:

• Site oficial do CC Switch
• Repositório GitHub do CC Switch
• Versões do CC Switch

No macOS, recomenda-se o Homebrew:

brew install --cask cc-switch

Para atualizar:

brew upgrade --cask cc-switch

No Windows, transfira o instalador .msi ou o ficheiro portátil a partir de Releases.

No Linux, transfira o pacote .deb, .rpm ou AppImage a partir de Releases. As designações podem mudar ligeiramente entre versões, pelo que deve utilizar a versão estável mais recente e considerar as opções apresentadas na aplicação como a referência oficial.

1.3 Pré-requisitos

Prepare o seguinte:

1. o Codex está instalado e já foi iniciado pelo menos uma vez;
2. o CC Switch está instalado e inicia corretamente;
3. possui uma API key para o serviço do modelo de destino;
4. confirmou o Base URL, o ID do modelo e o protocolo a montante na documentação do fornecedor;
5. se necessitar de funcionalidades oficiais da conta Codex, conclua primeiro um início de sessão oficial.

Verifique o estado atual do início de sessão no Codex:

codex login status

Inicie sessão quando necessário:

codex login

Também está disponível o início de sessão através de código de dispositivo:

codex login --device-auth

1.4 Opcional: preservar o início de sessão oficial ao utilizar um fornecedor de terceiros

Esta opção é útil sobretudo quando pretende manter funcionalidades de ambiente de trabalho, plugins oficiais ou funcionalidades de controlo remoto enquanto os pedidos ao modelo são enviados para um fornecedor de terceiros. Os utilizadores exclusivos da CLI que não dependam de funcionalidades da conta oficial podem ignorá-la.

Ordem recomendada:

1. selecione OpenAI Official no painel Codex do CC Switch;
2. inicie o Codex e inicie sessão com uma conta oficial;
3. abra Settings → General → Codex App Enhancements no CC Switch;
4. ative Keep official login when switching third-party providers;
5. adicione ou mude para o fornecedor de terceiros.

Com esta opção ativada, o CC Switch tenta manter:

• ~/.codex/auth.json para o estado do início de sessão oficial;
• ~/.codex/config.toml para o fornecedor de terceiros ativo, o modelo, o endpoint e a configuração de autenticação.

auth.json contém dados confidenciais de início de sessão. Não os partilhe nem os submeta para controlo de versões.

1.5 Adicionar um fornecedor de terceiros

Abra o CC Switch, mude para o painel Codex de nível superior e clique no botão de adição no canto superior direito.

Dar preferência a uma predefinição integrada

Quando existir uma predefinição, utilize-a e introduza apenas a API key e quaisquer valores específicos da conta que sejam necessários. Normalmente, uma predefinição configura:

• o Base URL;
• o modelo predefinido;
• o protocolo a montante;
• se é necessário encaminhamento local;
• os mapeamentos de modelos;
• os parâmetros de raciocínio selecionados.

A lista de predefinições muda à medida que o CC Switch evolui. A documentação de longa duração não deve fixar o ID atual do modelo de um fornecedor; utilize a lista da aplicação e a documentação oficial do fornecedor.

Criar um fornecedor personalizado

Quando não estiver disponível uma predefinição, escolha uma configuração personalizada e forneça:

A definição mais importante é Upstream Format:

Não selecione Responses apenas porque um fornecedor anuncia «compatibilidade com a OpenAI». Muitas API compatíveis com a OpenAI implementam apenas Chat Completions.

1.6 Introduzir corretamente o Base URL

Por predefinição, o CC Switch acrescenta o caminho da API adequado ao Base URL. Na maioria dos casos, introduza a raiz da API indicada na documentação do fornecedor, em vez de repetir /chat/completions ou /responses.

Por exemplo, se o fornecedor documentar:

POST https://api.example.com/v1/chat/completions

poderá ter de introduzir:

https://api.example.com

ou, consoante a predefinição e a documentação do fornecedor:

https://api.example.com/v1

A inclusão de /v1 no Base URL depende do fornecedor e da predefinição do CC Switch. Utilize a verificação de conectividade integrada ou os registos de encaminhamento para confirmar o URL final do pedido.

Utilize Full URL Mode apenas quando o fornecedor exigir um caminho completo de endpoint não padrão.

1.7 Configurar Needs Local Routing e o mapeamento de modelos

Ative Needs Local Routing quando o fornecedor utilizar Chat Completions, Anthropic Messages ou nomes de modelos que o Codex não reconheça por predefinição.

Normalmente, as predefinições orientadas para Chat ativam esta opção automaticamente. Verifique-a nos fornecedores personalizados.

Depois de ativada, fica disponível uma tabela de mapeamento de modelos. Os campos comuns incluem:

Pontos importantes:

• utilize o ID exato do modelo indicado na documentação do fornecedor;
• não tente adivinhar a dimensão do contexto;
• reinicie o Codex após alterar a lista de modelos;
• o CC Switch gera o catálogo de modelos do Codex a partir destes mapeamentos;
• se um retransmissor alterar o domínio ou o nome do modelo, a deteção automática da capacidade de raciocínio poderá estar incorreta e deverá ser revista nas definições avançadas.

1.8 Ativar o encaminhamento local e a assunção do controlo do Codex

No CC Switch, abra:

Settings → Routing → Local Routing

Em seguida:

1. ative o interruptor principal de encaminhamento local;
2. ative Codex em Routing Enabled;
3. confirme a definição Needs Local Routing do fornecedor;
4. mantenha o CC Switch em execução enquanto o fornecedor estiver a ser utilizado.

Por norma, a rota local predefinida é:

http://127.0.0.1:15721

Após assumir o controlo, a configuração ativa do Codex aponta para a rota local do CC Switch. Em seguida, o CC Switch reencaminha os pedidos para o fornecedor a montante atualmente selecionado.

Para um serviço a montante de Chat Completions, o fluxo é normalmente:

Codex POST /responses
  → CC Switch converts it to POST /chat/completions
  → the provider returns JSON or SSE
  → CC Switch rebuilds Responses JSON or SSE
  → Codex continues the tool-call loop

1.9 Alternar entre fornecedores e reiniciar o Codex

Regresse à lista de fornecedores Codex do CC Switch, selecione o fornecedor que configurou e ative-o.

Reinicie totalmente o Codex depois de mudar de fornecedor porque:

• o Codex lê config.toml durante o arranque;
• normalmente, o menu /model carrega o respetivo catálogo no arranque;
• a extensão para IDE ou o cliente de ambiente de trabalho pode manter o fornecedor anterior em cache;
• as sessões existentes podem conservar metadados antigos do modelo.

Os utilizadores da CLI podem simplesmente iniciar um novo processo:

codex

1.10 Verificar a integração

No Codex, execute:

/status

Reveja o modelo ativo, o fornecedor, as permissões e as informações de contexto.

Abra o seletor de modelos:

/model

Inspecione as camadas de configuração:

/debug-config

Verifique também:

• o fornecedor Codex ativo no CC Switch;
• os registos ou as estatísticas de encaminhamento local do CC Switch;
• o histórico de pedidos e as alterações de saldo no painel do fornecedor;
• se ~/.codex/config.toml aponta atualmente para a rota local.

Não valide a configuração apenas com uma saudação simples. Execute pelo menos um teste de capacidades de agente:

1. peça ao Codex para listar os ficheiros do projeto atual;
2. peça-lhe para ler e resumir um ficheiro;
3. peça-lhe para modificar um ficheiro pequeno;
4. peça-lhe para executar os testes;
5. deixe uma falha simples por corrigir e verifique se consegue utilizar o resultado do teste para continuar a corrigir o projeto.

A geração de texto bem-sucedida não demonstra que a chamada de ferramentas e os fluxos de trabalho de agente com vários turnos são compatíveis.

1.11 Voltar ao fornecedor oficial da OpenAI

Selecione OpenAI Official no CC Switch e reinicie o Codex.

Verifique o estado do início de sessão:

codex login status

Se necessário, inicie sessão novamente:

codex login

Quando necessitar simultaneamente do estado de início de sessão oficial e de pedidos a modelos de terceiros, confirme que Keep official login when switching third-party providers continua ativado.

1.12 Limitações e considerações operacionais

O CC Switch simplifica a configuração, mas não elimina as limitações do serviço a montante:

• o CC Switch tem de permanecer em execução para a conversão de Chat ou Messages;
• a conversão de protocolo não consegue reproduzir todas as funcionalidades específicas de cada fornecedor;
• alguns modelos conseguem conversar, mas não executam chamadas de ferramentas de forma fiável;
• Web Search, entrada de imagens, WebSockets ou armazenamento de respostas podem não estar disponíveis;
• continuam a aplicar-se os limites de frequência, a faturação e as políticas de retenção de dados do fornecedor a montante;
• um retransmissor de API pode voltar a modificar os pedidos e as respostas;
• as configurações devem ser novamente testadas após atualizações do CC Switch, do Codex ou do fornecedor.

O CC Switch é mais adequado para desenvolvimento local em ambiente de trabalho. Para servidores, CI ou automação sem interface gráfica de longa duração, dê preferência a um fornecedor nativo de Responses ou a um gateway autoalojado.

2. Ligar uma API alojada com um fornecedor de modelos personalizado

Configure diretamente um fornecedor apenas quando o serviço suportar de forma nativa a Responses API exigida pelo Codex.

Se o serviço disponibilizar apenas /chat/completions ou Anthropic Messages, utilize o fluxo de trabalho do CC Switch na secção 1. Não tente resolver a incompatibilidade com wire_api = "chat".

2.1 Capacidades obrigatórias da API

Um fornecedor adequado para integração direta com o Codex deve suportar, pelo menos:

• POST /responses;
• objetos JSON de Responses;
• eventos de transmissão SSE de Responses;
• chamada de funções ou ferramentas;
• parâmetros de ferramentas em JSON Schema;
• continuação após a devolução dos resultados das ferramentas;
• pedidos com vários turnos ou um equivalente a previous_response_id;
• um contexto suficientemente grande e pedidos prolongados estáveis;
• autenticação, limites de frequência e respostas de erro documentados.

A geração de texto comum, por si só, não é suficiente para um agente Codex fiável.

2.2 Configuração genérica

Edite a configuração ao nível do utilizador:

~/.codex/config.toml

Adicione:

model_provider = "third_party"
model = "provider-model-id"

# Set this only when the model explicitly supports it.
model_reasoning_effort = "high"

# Optional: use the real value published by the provider when no catalog exists.
# model_context_window = 131072

[model_providers.third_party]
name = "My Responses-compatible Provider"
base_url = "https://provider.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

Não utilize estes IDs de fornecedor reservados:

openai
ollama
lmstudio

Utilize antes um ID personalizado, como third_party ou company_gateway.

2.3 Campos de configuração

A inclusão de /v1 em base_url depende da documentação do fornecedor. Um endpoint final comum é:

https://provider.example.com/v1/responses

2.4 Definir a API key

Sessão bash / zsh atual:

export THIRD_PARTY_API_KEY="your API key"

fish:

set -gx THIRD_PARTY_API_KEY "your API key"

Sessão PowerShell atual:

$env:THIRD_PARTY_API_KEY = "your API key"

Para a tornar persistente para o utilizador atual do Windows:

[Environment]::SetEnvironmentVariable(
  "THIRD_PARTY_API_KEY",
  "your API key",
  [EnvironmentVariableTarget]::User
)

Reinicie o terminal, a IDE ou o cliente de ambiente de trabalho depois de definir uma variável de ambiente persistente.

2.5 Testar primeiro o endpoint Responses

Antes de iniciar o Codex, chame diretamente o fornecedor:

export PROVIDER_BASE_URL="https://provider.example.com/v1"

curl "$PROVIDER_BASE_URL/responses" \
  -H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider-model-id",
    "input": "Reply with exactly: PROVIDER_OK",
    "stream": false
  }'

Verifique se:

• o endpoint não devolve 404;
• a resposta tem uma estrutura do tipo Responses, e não apenas uma matriz choices de Chat Completions;
• o ID do modelo é aceite;
• a autenticação está correta;
• os erros contêm informações de diagnóstico úteis.

Em seguida, teste separadamente:

• stream: true;
• chamadas de ferramentas;
• continuação após os resultados das ferramentas;
• vários turnos;
• contexto longo;
• simultaneidade e limites de frequência.

2.6 Validar a configuração do Codex

Inicie no modo estrito:

codex --strict-config

--strict-config trata chaves de configuração desconhecidas como erros, o que ajuda a identificar campos copiados de guias desatualizados.

No Codex, execute:

/status

Para inspecionar as origens da configuração, execute:

/debug-config

Substitua o fornecedor e o modelo numa única execução sem alterar a configuração predefinida:

codex \
  -c 'model_provider="third_party"' \
  -m 'provider-model-id'

2.7 Catálogos de modelos e Unknown model

Um catálogo de modelos do Codex pode descrever:

• a dimensão do contexto;
• os níveis de raciocínio suportados;
• as modalidades de entrada;
• as capacidades de chamada de ferramentas;
• o comportamento de truncagem;
• as versões mínimas do cliente.

Quando o fornecedor disponibilizar um catálogo de modelos compatível com o Codex, guarde-o localmente e configure:

model_catalog_json = "~/.codex/provider-models.json"

Quando não existir um catálogo, defina uma dimensão do contexto apenas depois de confirmar o valor real:

model_context_window = 131072

Não copie metadados de um modelo não relacionado apenas para eliminar um aviso. Metadados incorretos de capacidades ou contexto podem causar truncagem prematura, erros de limites a montante ou falhas nas chamadas de ferramentas.

2.8 Lista completa de verificação de compatibilidade

Antes da utilização em produção, teste:

• texto /responses sem transmissão;
• transmissão SSE de Responses;
• uma chamada de ferramenta;
• várias chamadas de ferramentas sequenciais ou paralelas;
• parâmetros em JSON Schema;
• continuação após os resultados das ferramentas;
• contexto longo e compactação automática;
• parâmetros de raciocínio;
• imagens ou outras modalidades de entrada;
• limites de frequência e comportamento das novas tentativas;
• se um proxy coloca SSE em memória intermédia;
• se o fornecedor elimina ou reescreve campos de ferramentas;
• políticas de retenção de dados, registo e privacidade.

2.9 Onde deve ficar a configuração do fornecedor

Coloque model_provider, model_providers e a autenticação do fornecedor no ficheiro ao nível do utilizador:

~/.codex/config.toml

Não os coloque no ficheiro ao nível do repositório:

<project>/.codex/config.toml

O Codex ignora campos locais do projeto que possam redirecionar pedidos ao modelo ou alterar a autenticação do fornecedor. Isto impede que um repositório clonado não fidedigno encaminhe silenciosamente os pedidos para outro servidor.

3. Gerir vários fornecedores de terceiros com perfis

Normalmente, os utilizadores do CC Switch podem alternar entre fornecedores na aplicação e não necessitam de perfis do Codex.

Os perfis são úteis quando configura manualmente vários fornecedores nativos de Responses. Mantenha as definições dos fornecedores na configuração base e utilize ficheiros de perfil separados para selecionar um fornecedor e um modelo.

~/.codex/config.toml base:

[model_providers.provider_a]
name = "Provider A"
base_url = "https://api.provider-a.example/v1"
env_key = "PROVIDER_A_API_KEY"
wire_api = "responses"

[model_providers.provider_b]
name = "Provider B"
base_url = "https://api.provider-b.example/v1"
env_key = "PROVIDER_B_API_KEY"
wire_api = "responses"

Crie:

~/.codex/fast.config.toml

model_provider = "provider_a"
model = "provider-a-fast-model"
model_reasoning_effort = "medium"

Crie outro perfil:

~/.codex/quality.config.toml

model_provider = "provider_b"
model = "provider-b-quality-model"
model_reasoning_effort = "high"

Selecione um perfil ao iniciar o Codex:

codex --profile fast
codex --profile quality

Modo não interativo:

codex exec --profile quality "Review the current changes"

Os ficheiros de perfil encontram-se em:

$CODEX_HOME/<profile-name>.config.toml

O CODEX_HOME predefinido é ~/.codex.

As versões recentes do Codex utilizam ficheiros de perfil separados e deixaram de ler tabelas [profiles.<name>] antigas. Migre cada perfil antigo para o seu próprio ficheiro <name>.config.toml.

4. Cabeçalhos personalizados e autenticação avançada

4.1 Tokens bearer padrão

A maioria dos serviços de terceiros funciona com:

[model_providers.third_party]
env_key = "THIRD_PARTY_API_KEY"

O Codex lê a chave do ambiente e aplica a autenticação bearer do fornecedor.

4.2 Cabeçalhos de API key personalizados

Alguns serviços exigem:

x-api-key: <key>

Utilize env_http_headers:

model_provider = "custom_header_provider"
model = "provider-model-id"

[model_providers.custom_header_provider]
name = "Custom Header Provider"
base_url = "https://provider.example.com/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "VENDOR_API_KEY" }

O valor VENDOR_API_KEY é o nome de uma variável de ambiente, não o segredo propriamente dito.

export VENDOR_API_KEY="your API key"

4.3 Cabeçalhos estáticos e parâmetros de consulta

Adicione cabeçalhos estáticos não confidenciais:

http_headers = { "X-Client-Name" = "codex", "X-Environment" = "development" }

Adicione parâmetros de consulta:

query_params = { "api-version" = "2026-08-01" }

Não coloque segredos reais em http_headers.

4.4 Autenticação baseada em comandos

Um ambiente empresarial pode obter tokens de curta duração a partir de um porta-chaves, de um auxiliar de credenciais da nuvem ou de um comando interno:

[model_providers.corporate]
name = "Corporate Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.corporate.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

O comando deve imprimir apenas o token na saída padrão.

Não combine estes métodos de autenticação:

• [model_providers.<id>.auth];
• env_key;
• experimental_bearer_token;
• requires_openai_auth.

4.5 Reutilizar a autenticação da OpenAI através de um proxy

Defina o seguinte apenas quando o proxy continuar a aceder a modelos da OpenAI e o Codex dever utilizar a autenticação oficial da OpenAI:

requires_openai_auth = true

Esta não é a definição correta para uma API key normal de um modelo de terceiros. Quando está ativada, o Codex ignora o env_key do fornecedor.

5. Resolução de problemas

5.1 O CC Switch muda de fornecedor, mas o Codex continua a utilizar o modelo antigo

Verifique cada ponto:

1. o fornecedor Codex pretendido está ativado no CC Switch;
2. o interruptor principal de encaminhamento local está ligado;
3. Codex está ativado em Routing Enabled;
4. os fornecedores de Chat ou Messages têm Needs Local Routing ativado;
5. o CC Switch continua em execução;
6. o Codex, a IDE ou o cliente de ambiente de trabalho foi totalmente reiniciado;
7. /debug-config apresenta a origem de configuração esperada.

Reinicie o Codex depois de alterar os mapeamentos de modelos, para que o menu /model possa voltar a carregar o respetivo catálogo.

5.2 404, 400 ou ausência de um endpoint /responses

As causas comuns incluem:

• tratar um fornecedor de Chat Completions como um fornecedor nativo de Responses;
• adicionar ou remover /v1 incorretamente;
• acrescentar /chat/completions duas vezes;
• não ativar Full URL Mode para um endpoint não padrão;
• o encaminhamento local não assumir o controlo do Codex;
• uma implementação incompleta de Responses no gateway de terceiros.

Os utilizadores do CC Switch devem inspecionar Upstream Format e os registos de encaminhamento. Os utilizadores de fornecedores diretos devem chamar <base_url>/responses com curl.

5.3 401 Unauthorized ou 403 Forbidden

Verifique:

• se a API key é válida;
• se pertence à região, ao projeto ou ao plano correto;
• se a conta tem saldo e permissões suficientes;
• se o serviço espera um token bearer ou x-api-key;
• se o nome da variável de ambiente corresponde exatamente a env_key;
• se o CC Switch guardou a chave correta;
• se um proxy removeu o cabeçalho de autenticação.

Não imprima uma chave completa em registos partilhados.

bash / zsh:

printenv THIRD_PARTY_API_KEY

PowerShell:

$env:THIRD_PARTY_API_KEY

5.4 O modelo não aparece em /model

Verifique:

• se Model Mapping no CC Switch contém o ID exato do modelo a montante;
• se o fornecedor foi guardado e ativado;
• se o Codex foi reiniciado;
• se um fornecedor manual tem um model_catalog_json válido;
• se o JSON do catálogo é válido;
• se o fornecedor mudou o nome do modelo ou o descontinuou.

5.5 O texto funciona, mas o Codex não consegue ler ficheiros, editar código ou executar comandos

Causas possíveis:

• o modelo tem fraco desempenho na chamada de ferramentas;
• o serviço a montante não implementa a chamada de funções;
• um retransmissor elimina os IDs das chamadas de ferramentas;
• os fragmentos transmitidos das chamadas de ferramentas não são novamente agregados de forma correta;
• o JSON Schema é reescrito;
• os resultados das ferramentas não são devolvidos no turno seguinte;
• o contexto do modelo é demasiado curto;
• o catálogo de modelos anuncia capacidades incorretas.

Teste um ciclo real de «ler → editar → executar testes → inspecionar falha → corrigir», em vez de um simples pedido de conversa.

5.6 A transmissão desliga-se frequentemente

Os utilizadores do CC Switch devem começar por inspecionar os registos de encaminhamento local e as respostas a montante. As causas comuns incluem:

• colocação em fila a montante ou raciocínio demorado;
• um gateway que não emite SSE prontamente;
• utilização de memória intermédia pela CDN, pelo proxy inverso ou pela rede empresarial;
• eventos a montante não padrão;
• problemas de compatibilidade numa versão específica do CC Switch ou do fornecedor.

Para um fornecedor direto, pode aumentar:

request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

Tempos limite mais longos podem atenuar problemas de rede ou de inferência lenta, mas não conseguem corrigir uma implementação incorreta do protocolo.

5.7 wire_api = "chat" impede o arranque do Codex

Este valor aparece em guias antigos. A configuração atual do Codex suporta apenas:

wire_api = "responses"

Utilize o CC Switch quando o serviço a montante disponibilizar apenas Chat Completions.

Procure outros campos obsoletos com:

codex --strict-config

5.8 Editar a configuração do projeto não altera o fornecedor

As definições do fornecedor devem estar em:

~/.codex/config.toml

Um .codex/config.toml ao nível do projeto não pode substituir campos que redirecionem pedidos ou alterem a autenticação do fornecedor, incluindo model_provider e model_providers.

5.9 O terminal funciona, mas a extensão para IDE não consegue encontrar a API key

Frequentemente, as aplicações gráficas não herdam variáveis exportadas temporariamente num terminal existente.

As opções incluem:

• iniciar a IDE a partir do terminal onde a variável está definida;
• tornar a variável persistente no ambiente de utilizador do sistema operativo;
• encerrar completamente e voltar a abrir a IDE;
• utilizar o CC Switch para gerir a configuração do fornecedor local.

5.10 O início de sessão oficial ou as funcionalidades oficiais deixam de funcionar depois de uma mudança

Verifique:

• se OpenAI Official foi novamente selecionado;
• se Keep official login when switching third-party providers está ativado;
• se um fluxo de trabalho antigo substituiu ~/.codex/auth.json;
• se codex login status é concluído com êxito.

Quando necessário, inicie sessão novamente:

codex login

Não partilhe nem edite manualmente um ficheiro auth.json que contenha tokens de acesso.

5.11 Web Search, imagens ou outras capacidades avançadas não funcionam

Um fornecedor que suporte texto e chamadas de ferramentas não implementa necessariamente todas as capacidades do Codex.

Os fornecedores personalizados não anunciam Web Search autónomo por predefinição. Defina o seguinte apenas quando o fornecedor, o modelo e o endpoint o suportarem efetivamente:

supports_standalone_web_search = true

A ativação incorreta apenas faz com que o Codex envie pedidos que o serviço a montante não consegue processar. Valide separadamente a entrada de imagens, WebSockets, o armazenamento de respostas e outras funcionalidades avançadas.

6. Escolher um método de integração

Valide cada integração em três níveis:

1. Conectividade: devolve texto de forma fiável;
2. Utilização de ferramentas: consegue ler ficheiros, executar comandos e continuar a partir dos resultados das ferramentas;
3. Conclusão de tarefas: consegue concluir um ciclo de edição, teste e correção.

Reveja também:

• os preços de terceiros;
• os limites de frequência;
• se o código-fonte e os pedidos são registados;
• as regiões de armazenamento de dados;
• os requisitos de conformidade da equipa ou da empresa;
• se as atualizações de modelos exigem testes de regressão.

Quando utiliza uma API key de terceiros, a utilização é faturada por esse fornecedor ou retransmissor. Não consome nem partilha automaticamente os limites incluídos no ChatGPT Plus, Pro ou numa subscrição do Codex.

Referências

• Noções básicas da configuração do Codex
• Configuração avançada do Codex
• Referência da configuração do Codex
• Autenticação do Codex
• Comandos para programadores do Codex
• Modelos do Codex
• CC Switch no GitHub
• Manual do utilizador do CC Switch
• CC Switch: adicionar um fornecedor
• CC Switch: preservar o início de sessão oficial do Codex