Erro 401 do Codex CLI: corrija a rota de autenticação correta

Um 401 do Codex CLI significa que a autenticação foi rejeitada pelo servidor que processa a solicitação. A verificação útil mais rápida combina o host de destino, o provedor selecionado e a origem da credencial. Uma variável de ambiente vazia é uma possibilidade; não é a explicação para todo 401. Siga o caminho correspondente à sua configuração.

Primeiro identifique qual conexão falhou

Salve o status, o texto do erro, o horário e o ID da solicitação quando disponíveis. Remova cabeçalhos de autorização, chaves e tokens antes de compartilhar os detalhes. Não cole auth.json em um chamado de suporte: ele pode conter credenciais. Um erro em uma integração não prova que a conexão com o modelo está quebrada.

1. Verifique a CLI e o método de login

codex --version
codex login status

# POSIX shell: report presence only, without printing the secret
if [ -n "${KUNAVO_API_KEY:-}" ]; then
  printf 'KUNAVO_API_KEY is set\n'
else
  printf 'KUNAVO_API_KEY is missing or empty\n'
fi

Execute as verificações no mesmo terminal que inicia o Codex. Substitua o nome da variável na verificação de presença se o seu provedor usar uma diferente env_key. “Definida” apenas confirma que existe um valor; não prova que o valor está atualizado ou é aceito pelo destino.

Para um login pessoal do ChatGPT que parou de atualizar, use codex logout seguido de codex login, depois conclua o fluxo do navegador para a conta pretendida. Isso altera o estado de login armazenado; não é uma etapa obrigatória para todo erro de provedor personalizado. Em automação gerenciada, siga o método de autenticação do administrador. Consulte o guia oficial de autenticação.

2. Associe uma chave de API ao emissor e ao destino

Uma chave da OpenAI Platform pertence à rota da API da OpenAI. Uma chave do Kunavo pertence à rota do Kunavo. Um login bem-sucedido no navegador do ChatGPT não valida uma chave de gateway, e um saldo do gateway não é um saldo da OpenAI Platform. Verifique o host real no erro antes de substituir qualquer coisa.

No painel do emissor, confirme que a chave ainda existe e está ativa. Verifique o projeto associado e quaisquer restrições de acesso. A referência de erros da API da OpenAI inclui credenciais inválidas, associação à organização e falhas da lista de permissões de IP entre os erros de autenticação. Use a mensagem correspondente para escolher a correção; criar chaves repetidamente não corrige uma conta nem uma política de rede.

3. Verifique a configuração do provedor usada pelo Codex

# Compare these non-secret fields with your intended provider.
model = "gpt-5-6-sol"
model_provider = "kunavo"

[model_providers.kunavo]
name = "Kunavo"
base_url = "https://api.kunavo.com/v1"
env_key = "KUNAVO_API_KEY"
wire_api = "responses"

O model_provider selecionado deve corresponder ao bloco do provedor. O campo env_key nomeia a variável; ele não contém o segredo. Verifique a configuração ativa e qualquer substituição de perfil ou linha de comando; depois, reinicie o Codex após corrigi-la. Evite copiar um bloco de provedor não relacionado sobre sua configuração funcional.

A referência de configuração da OpenAI documenta o protocolo Responses. Uma URL base que termina em /v1 é diferente de uma URL de solicitação /v1/responses completa. Um caminho incorreto geralmente exige diagnóstico do endpoint mesmo depois que a autenticação funciona. Verifique também requires_openai_auth: quando ativada, a autenticação da OpenAI tem precedência sobre env_key, conforme descrito no guia de autenticação.

4. Altere uma coisa e tente novamente uma tarefa pequena

1. Preserve os detalhes do erro e identifique a rota selecionada.
2. Corrija o login, a credencial ou o campo do provedor indicado pelas evidências.
3. Reinicie o processo da CLI ou do editor afetado para que ele receba a nova configuração.
4. Execute uma solicitação pequena antes de reiniciar uma tarefa longa de programação.
5. Se a falha persistir, envie ao provedor um erro sem dados sensíveis e o ID da solicitação, não a credencial.

Um 429 posterior, aviso de saldo ou erro de modelo ausente é um novo ramo de diagnóstico. Mantenha a correção de autenticação e trate o próximo problema, em vez de desfazer todas as configurações. O guia de limites do Codex separa esses casos. Para uma configuração do Kunavo, use a integração completa do Codex e gerencie as chaves no seu painel.

Perguntas frequentes

Documentação oficial e ajuda local da CLI verificadas em 17 de setembro de 2026. Nenhuma credencial precisa ser compartilhada para seguir estas verificações.