Integração da API do Codex: um guia completo de configuração

Conectar modelos externos ao Codex é um processo complexo. Este guia usa a API do Kimi como um exemplo prático para conduzir você pela configuração completa da API do Codex no macOS e no Windows.

O que é o Codex?

O Codex é o agent de codificação da OpenAI para trabalhos em repositórios e terminal. Ele pode:

• Escrever código: criar funções, testes, scripts e funcionalidades pontuais.

• Entender bases de código desconhecidas: buscar arquivos, rastrear chamadas e explicar componentes.

• Revisar código: identificar prováveis defeitos, suposições arriscadas, testes ausentes e questões de segurança.

• Depurar e corrigir problemas: reproduzir erros, propor mudanças e executar verificações.

• Automatizar tarefas rotineiras: atualizar arquivos e executar fluxos de trabalho documentados com sua aprovação.

Instale e faça login no Codex

Parte 1: instale o Codex CLI

1. Abra o Terminal no macOS ou o PowerShell no Windows.

2. Execute o comando correspondente ao seu sistema operacional:

macOS:

Windows:

1. Aguarde a instalação terminar, depois feche e reabra o Terminal ou o PowerShell.

2. Execute:

1. Selecione Sign in with ChatGPT, conclua o login pelo navegador e volte ao Terminal ou ao PowerShell.

Parte 2: instale o aplicativo desktop do Codex

1. Acesse a página oficial do aplicativo desktop do Codex.

2. Baixe o aplicativo desktop do ChatGPT para macOS ou Windows.

3. Instale e abra o aplicativo, depois faça login com sua conta do ChatGPT.

4. Crie uma tarefa ou abra um projeto e selecione Codex como modo de trabalho.

5. Digite Say hello in one sentence. e envie a mensagem.

Modelos de IA integrados vs. APIs de LLM externas

Depois de instalar o Codex, você pode usar seus modelos de IA integrados ou conectar uma API de LLM externa compatível. A melhor opção depende de quanta configuração, flexibilidade e gerenciamento de conta você deseja.

Use os modelos integrados do Codex

Os modelos integrados oferecem a experiência mais simples. Você pode selecionar um modelo disponível e começar a codificar sem executar outro serviço ou configurar uma chave de API separada.

Vantagens:

• Configuração rápida, sem etapas adicionais.

• Integração direta com as ferramentas e recursos do Codex

• Menos serviços e credenciais para gerenciar

Limitações:

• Você só pode escolher entre os modelos disponíveis para sua conta

• Menos flexibilidade caso queira usar um modelo de outro provedor

• Requer uma assinatura GPT, e o custo de uso é relativamente alto.

Usar uma API de LLM externa

Uma API externa oferece mais opções de modelos e permite usar uma conta já existente com outro provedor. No entanto, alguns modelos exigem configuração adicional ou uma ferramenta de compatibilidade local antes que o Codex possa usá-los.

Vantagens:

• Acesso a modelos de outros provedores

• Mais flexibilidade para diferentes tarefas de programação

• Controle separado sobre a conta e o uso da API externa

• Não exige assinatura GPT. Ideal para cenários sensíveis ao custo.

Limitações:

• Requer uma chave de API e configuração adicional

• Pode exigir um roteador local que precisa permanecer em execução

• Faturamento, compatibilidade, privacidade e solução de problemas dependem do provedor externo

Se você quer a configuração mais rápida, comece com um modelo integrado. Se já tem uma conta de API externa ou quer mais opções de modelos, continue com o passo a passo a seguir. Ele usa a Kimi API como exemplo prático de como conectar um modelo externo ao Codex.

Como conectar uma API de LLM externa ao Codex: exemplo com Kimi

Configuração no macOS

Passo 1: Abra o Terminal A e verifique o Node.js e o npm

Onde: Pressione Command+Space, digite Terminal e pressione Enter. Considere esta primeira janela como o Terminal A.

Execute:

Resultado esperado: Cada comando exibe uma versão. Saídas como v22.x.x para o Node.js e 10.x.x para o npm são apenas exemplos, não requisitos mínimos.

Se um comando não for encontrado: Abra um navegador, acesse https://nodejs.org/en/download, baixe o pacote .pkg LTS para macOS, abra Downloads no Finder, dê duplo clique no pacote e aceite as opções padrão do instalador. Feche o Terminal com Command+Q, reabra o Terminal A e execute novamente os dois comandos de versão. Não continue até que ambos os comandos retornem as versões.

Passo 2: Crie uma chave de API da Kimi

Abra a plataforma de API da Kimi. Crie uma chave de API pelo console e armazene-a em um gerenciador de senhas ou de segredos. Se o console exibir a chave completa apenas uma vez, copie-a antes de sair da página.

Passo 3: Defina MOONSHOT_API_KEY no Terminal A

Onde: Volte ao Terminal A.

Execute:

Substitua apenas YOUR_KIMI_API_KEY pela chave real da Kimi. Mantenha as aspas e o nome da variável MOONSHOT_API_KEY inalterados.

Resultado esperado: O comando export não exibe nenhuma saída. Verifique se um valor existe sem exibi-lo:

O Terminal deve exibir Kimi key is set.

Passo 4: Teste a Kimi diretamente pelo Terminal A

Onde: Continue usando o Terminal A, onde MOONSHOT_API_KEY está definido.

Execute:

Resultado esperado: Uma resposta em JSON aparece, contendo o texto gerado em choices[0].message.content.

Etapa 5: abra o Terminal B e inicie o roteador no Terminal A

Onde: com o Terminal A ativo, pressione Command+N para abrir uma segunda janela. Chame a nova janela de Terminal B. Volte ao Terminal A antes de executar o comando do roteador.

Execute no Terminal A:

Não substitua a URL base nem o modelo. $MOONSHOT_API_KEY deve permanecer como referência de variável, não uma segunda cópia colada da chave.

Possível prompt na primeira execução: o npx pode exibir Need to install ... Ok to proceed? (y). Revise o nome do pacote e a fonte de terceiros vinculada antes de continuar. Digite y e pressione Enter somente se você aceitar esse pacote. Nenhuma versão exata de pacote é declarada como testada aqui.

Resultado esperado: o processo continua em execução e informa que está escutando em 127.0.0.1:8787. Deixe o Terminal A aberto.

Se falhar: se o npm não conseguir baixar o pacote, confirme o acesso à internet e execute novamente node --version e npm --version. Se a porta 8787 já estiver em uso, encerre o outro processo local que está usando essa porta ou volte ao terminal dele e pressione Ctrl+C, depois execute novamente o comando do roteador.

Etapa 6: teste o localhost a partir do Terminal B

Onde: clique no Terminal B.

Execute:

Resultado esperado: o Terminal B imprime eventos de streaming semelhantes aos da Responses ou uma saída contendo uma saudação de uma frase. A sequência exata de eventos pode variar de acordo com a versão do roteador.

Se você ver Connection refused: observe o Terminal A. Se o roteador parou, execute novamente o comando da Etapa 5 e mantenha-o aberto. Se o Terminal A mostrar um 401 de upstream, redefina MOONSHOT_API_KEY ali e reinicie o roteador.

Etapa 7: crie e edite a configuração do Codex no macOS

Onde: continue usando o Terminal B.

Execute:

Esses comandos criam o arquivo de configuração em nível de usuário, se necessário, fazem backup de um arquivo existente e abrem ~/.codex/config.toml no TextEdit.

Se o arquivo estiver vazio

Cole a seguinte configuração completa:

Se o arquivo já contiver configurações

Não cole a configuração completa sobre o arquivo existente. Mantenha as configurações não relacionadas e atualize as linhas necessárias individualmente.

1. Encontre a linha que começa com model = e substitua a linha inteira por:

1. Encontre a linha que começa com model_provider = e substitua a linha inteira por:

1. Encontre a linha que começa com model_context_window = e substitua a linha inteira por:

1. Encontre a linha que começa com model_supports_reasoning_summaries = e substitua a linha inteira por:

Se alguma dessas quatro configurações ainda não existir, adicione a linha faltante próximo ao início do arquivo.

1. Encontre e exclua qualquer linha inteira que comece com:

Também encontre e exclua qualquer linha inteira que comece com:

1. Adicione a seção abaixo:

Não remova outras seções de provedor, como [model_providers.openai].

Mantenha as configurações existentes não relacionadas, incluindo preferências de notify, aprovação, sandbox, projeto e interface. Não copie a linha notify de outro usuário, pois ela pode conter um caminho absoluto específico do computador.

Pressione Command+S para salvar o arquivo e feche o TextEdit.

Etapa 8: reinicie o Codex e execute o teste completo no macOS

Onde: mantenha o roteador em execução no Terminal A. No Terminal B, encerre qualquer sessão existente do Codex com Ctrl+C e, em seguida, prepare uma pasta descartável.

Execute no Terminal B:

Teste: digite hello. e pressione Enter. Uma resposta de uma frase confirma um caminho básico de solicitação.

Configuração no Windows

Use duas janelas independentes do PowerShell. O PowerShell A armazena a chave Kimi da sessão atual e executa o roteador. O PowerShell B testa o localhost, edita a configuração e inicia o Codex. A variável de usuário persistente serve para futuras janelas; a atribuição na sessão atual disponibiliza a chave imediatamente no PowerShell A.

Etapa 1: abra o PowerShell A e verifique o Node.js e o npm

Onde: Pressione a tecla Windows, digite PowerShell e abra o Windows PowerShell. Chame esta janela de PowerShell A.

Execute:

Resultado esperado: Ambos os comandos exibem versões. Valores como v22.x.x e 10.x.x são apenas exemplos, não requisitos mínimos.

Se um comando não for reconhecido: Abra um navegador e acesse https://nodejs.org/en/download. Baixe o .msi LTS para Windows, abra Downloads no Explorador de Arquivos, dê duplo clique no instalador, aceite as opções padrão e certifique-se de que o instalador mantenha marcada a opção que adiciona o Node.js ao PATH. Feche todas as janelas do PowerShell, reabra o PowerShell A e execute novamente os dois comandos.

Etapa 2: crie uma chave de API da Kimi

Abra a plataforma de API da Kimi. Crie uma chave de API pelo console e depois guarde-a em um gerenciador de senhas ou de segredos. Se o console exibir a chave completa apenas uma vez, copie-a antes de sair da página.

Etapa 3: defina variáveis persistentes e da sessão atual no PowerShell A

Onde: Volte ao PowerShell A.

Execute:

Substitua apenas YOUR_KIMI_API_KEY nas duas linhas pela mesma chave da Kimi. Mantenha MOONSHOT_API_KEY, User, aspas e pontuação inalterados. A primeira linha armazena o valor para processos futuros. A segunda linha o disponibiliza imediatamente no PowerShell A.

Resultado esperado: Ambos os comandos não retornam saída. Verifique a presença sem exibir a chave:

O PowerShell deve exibir True.

Se exibir False: Execute novamente a atribuição da sessão atual usando aspas retas. Se a gravação em User tiver sido bloqueada por política, continue com o valor da sessão atual para este tutorial e pergunte ao seu administrador como as variáveis de ambiente de usuário devem ser armazenadas. Revogue qualquer chave exposta em logs ou textos compartilhados.

Etapa 4: teste a Kimi diretamente no PowerShell A

As referências de API podem exibir POST URL, mas nunca digite apenas POST https://... no PowerShell. Use Invoke-RestMethod -Method Post como mostrado aqui.

Onde: Permaneça no PowerShell A, onde $env:MOONSHOT_API_KEY está definida.

Execute:

Não substitua o endpoint, o modelo ou o nome da variável. O PowerShell lê a chave a partir de $env:MOONSHOT_API_KEY.

Resultado esperado: A última linha exibe uma saudação de uma frase vinda de choices[0].message.content.

Se você receber 401: Confirme se a chave veio do console global .ai, revogue-a e crie uma nova se necessário, execute novamente as duas atribuições da Etapa 3 e tente de novo. Se o modelo for rejeitado, confirme se o ID é exatamente kimi-k2.7-code e verifique o acesso ao modelo no console da Kimi.

Etapa 5: abra o PowerShell B e inicie o router no PowerShell A

Onde: Pressione a tecla Windows novamente, digite PowerShell e abra uma segunda janela do Windows PowerShell. Chame-a de PowerShell B. Volte ao PowerShell A para o comando do router.

Execute no PowerShell A:

Mantenha $env:MOONSHOT_API_KEY inalterada; não cole a chave diretamente no comando.

Possível prompt na primeira execução: o npx pode exibir Need to install ... Ok to proceed? (y). Analise o pacote e a fonte de terceiros. Digite y e pressione Enter somente se você aceitar. Nenhuma versão exata de pacote é apresentada como testada.

Resultado esperado: O processo permanece aberto e informa que está escutando em 127.0.0.1:8787. Mantenha o PowerShell A aberto.

Se falhar: Execute node --version e npm --version no PowerShell A. Se algum falhar, repita a Etapa 1. Se a porta 8787 estiver ocupada, interrompa o outro router com Ctrl+C na janela dele e execute o comando novamente.

Etapa 6: teste o localhost pelo PowerShell B

Onde: Clique no PowerShell B. Não interrompa o router no PowerShell A.

Execute:

Não substitua a URL de localhost. Ela aponta para o router no PowerShell A.

Resultado esperado: O PowerShell retorna um objeto semelhante a Responses ou uma saída contendo a saudação. Os campos exatos podem variar conforme a versão do router.

Se a conexão for recusada: Verifique o PowerShell A e reinicie o comando da Etapa 5 se o router tiver sido encerrado. Se o PowerShell A mostrar um erro de autenticação upstream, pressione Ctrl+C, redefina $env:MOONSHOT_API_KEY e reinicie o router. Não adicione um cabeçalho de autorização local para o início rápido padrão do @codeproxy/cli.

Etapa 7: crie e edite a configuração do Codex no Windows

Onde: Continue usando o PowerShell B. A configuração do provedor deve ficar em $HOME\.codex\config.toml, não dentro de uma pasta de projeto.

Execute:

Os comandos criam o diretório do usuário, fazem backup de uma configuração existente, criam o arquivo caso não exista e o abrem no Notepad.

No Notepad: Cole esta configuração padrão completa, removendo chaves de modelo ou provedor duplicadas e conflitantes se o arquivo já as contiver:

Não substitua kimi-proxy, a URL do localhost nem responses. Pressione Ctrl+S e feche o Bloco de Notas.

Confirme o nome do arquivo: Execute:

Resultado esperado: Name é exatamente config.toml, não config.toml.txt, e Length é maior que zero.

Se o Bloco de Notas adicionou .txt: No Bloco de Notas, escolha Arquivo → Salvar como, defina Salvar como tipo para Todos os Arquivos, digite config.toml e salve em $HOME\.codex. Execute Get-Item novamente. Se o Codex ignorar o provedor, verifique se você editou o caminho no nível de usuário e remova chaves TOML duplicadas.

Etapa 8: reinicie o Codex e execute o teste completo no Windows

Onde: Deixe o PowerShell A e seu roteador em execução. Feche completamente qualquer app ou sessão do Codex. Feche o PowerShell B, reabra-o pressionando a tecla Windows → digite PowerShell → abra Windows PowerShell e crie uma pasta descartável.

Execute no PowerShell B reaberto:

Teste: Digite hello. e pressione Enter. Uma resposta de uma frase confirma um caminho de requisição básico.

Usar o Kimi no app de desktop do Codex

Antes de continuar, conclua as etapas 1 a 7 da configuração do macOS ou Windows para o roteador local e o config.toml. Você não precisa concluir primeiro o teste da CLI, mas o roteador deve permanecer em execução enquanto você usa o Kimi no app de desktop.

Etapa 1: mantenha o roteador local em execução

Mantenha o Terminal A ou o PowerShell A aberto com @codeproxy/cli em execução em:

Etapa 2: confirme a configuração do provedor

Abra o arquivo de configuração do Codex no nível de usuário.

No macOS, execute:

No Windows, execute:

Confirme que o arquivo contém estas configurações de nível superior:

Etapa 3: reinicie completamente o app de desktop

No macOS, pressione Command+Q para fechar completamente o app de desktop. Apenas fechar a janela não é suficiente.

No Windows, feche todas as janelas do app de desktop e confirme que o app não está mais em execução na bandeja do sistema.

Reabra o app de desktop e abra uma pasta de projeto.

Etapa 4: mantenha o modelo Custom selecionado

O seletor de modelos do desktop pode exibir Custom em vez de Kimi K2.7 Code. Isso é esperado.

Provedores personalizados definidos em config.toml nem sempre são exibidos pelo nome na lista de modelos do desktop. Não selecione um modelo da OpenAI como o GPT-5.6 Sol quando quiser usar o provedor Kimi. Mantenha Custom selecionado.

Você também pode ver este aviso:

Isso é um aviso, não uma falha de conexão. As configurações a seguir já fornecem as informações importantes de modelo necessárias para o uso normal:

Etapa 5: verifique o caminho de requisição do desktop

Envie este prompt no app de desktop:

Observe o Terminal A ou o PowerShell A enquanto o app de desktop responde. Se a janela do Terminal A receber uma nova requisição e o app de desktop retornar uma resposta, o app de desktop está usando a rota local do Kimi.

Solução de erros comuns de integração

zsh: command not found: POST

POST URL é notação da documentação da API, não um comando. No macOS, copie o exemplo completo do curl. No Windows, copie o exemplo completo do Invoke-RestMethod -Method Post.

Conexão recusada na porta 8787

Volte ao Terminal A ou ao PowerShell A. Se nenhum processo de roteador estiver em execução, defina a variável do Kimi para a sessão atual e execute novamente o comando documentado npx @codeproxy/cli .... Mantenha essa janela aberta e repita o teste do localhost na janela B.

Uma resposta 401

Leia a janela do roteador para identificar o salto que está falhando. Um 401 de origem no Kimi geralmente significa que MOONSHOT_API_KEY é inválida, foi revogada ou pertence à conta regional errada. Revogue a chave no console global .ai, crie uma nova, redefina a variável da sessão atual e reinicie o roteador. O caminho padrão do roteador não tem verificação de bearer de entrada. Um 401 local com outro adaptador pode significar que sua CODEX_KIMI_PROXY_KEY opcional está ausente ou inválida.

Erros de parâmetro ou ferramenta não suportados

O roteador pode estar encaminhando um campo que o Kimi não aceita. Os campos de amostragem devem permanecer não definidos; se emitidos, devem usar os valores fixos aceitos. Confirme que tool_choice é auto ou none e que o adaptador preserva reasoning_content. Se o teste de múltiplas etapas ainda falhar, pare de usar essa versão do roteador e escolha ou atualize uma com suporte explícito ao Kimi.

O Codex ignora o provedor

Abra o arquivo do usuário diretamente: execute open -e "$HOME/.codex/config.toml" no macOS ou notepad "$HOME\.codex\config.toml" no Windows. Confirme que existe apenas um model_provider = "kimi-proxy" no nível superior, uma tabela de provider, a URL base do localhost e wire_api = "responses". Salve, saia completamente do Codex e inicie-o novamente. Não coloque a seleção de provider apenas em um .codex/config.toml de projeto.

O npx não consegue iniciar o router

Execute node --version e npm --version na janela A do router. Se algum dos comandos falhar, instale o pacote Node.js LTS em nodejs.org/download, feche e reabra o terminal e tente novamente. Se o npx pedir permissão para baixar o pacote, revise o pacote e a origem antes de digitar y.

Benefícios de usar a Kimi API

Usar o Kimi em fluxos de trabalho do Cursor API pode melhorar tarefas de codificação, depuração e desenvolvimento. Seus recursos avançados ajudam a gerar respostas precisas, lidar com instruções complexas e apoiar uma resolução de problemas mais rápida. Aqui estão os principais benefícios de usar o Kimi em fluxos de trabalho do Cursor para aumentar a produtividade e a eficiência.

• Compreensão de código com contexto longo

O Kimi pode processar grandes quantidades de código e informações de uma só vez. Ele reconhece relações entre diferentes arquivos e seções do projeto de forma mais eficaz. Como resultado, trabalhar com bases de código grandes ou complexas se torna muito mais fácil.

• Melhor análise de documentação e repositórios

Documentos de projeto, notas técnicas e repositórios podem ser revisados rapidamente com o Kimi. Detalhes importantes são mais fáceis de encontrar sem precisar percorrer manualmente cada arquivo. Os desenvolvedores conseguem ter uma compreensão mais clara de todo o projeto em menos tempo.

• Desenvolvimento de IA com bom custo-benefício

O Kimi oferece uma opção prática e acessível para lidar com muitas tarefas de desenvolvimento. Um suporte de IA poderoso fica disponível sem depender inteiramente de modelos mais caros. As equipes podem melhorar a produtividade geral mantendo as despesas sob controle.

• Recuperação de conhecimento mais rápida

Informações úteis podem ser localizadas rapidamente em bases de código, conjuntos de dados e arquivos de projeto extensos. Menos tempo é gasto procurando recursos em busca de respostas ou referências. Mais atenção pode ser dedicada à codificação, aos testes e à melhoria do projeto.

• Automação de fluxo de trabalho aprimorada

Tarefas repetitivas de desenvolvimento ficam mais fáceis de gerenciar e concluir com o Kimi. Ele pode ajudar na geração de código, na revisão de conteúdo e em atividades rotineiras do projeto. Os fluxos de trabalho diários se mantêm organizados, eficientes e mais produtivos ao longo do tempo.

Como o Codex melhora o fluxo de trabalho de desenvolvimento

Um fluxo de trabalho configurado do Codex CLI API conecta inspeção do repositório, edição, comandos e revisão em um único contexto. O Codex pode montar arquivos, explicar módulos desconhecidos, reproduzir falhas, propor testes e executar verificações aprovadas. O suporte a provedores externos amplia a escolha de modelo, mas não remove a responsabilidade da revisão.

Comece cada tarefa com um objetivo bem delimitado. Peça ao Codex para inspecionar antes de editar, revise as alterações propostas por ele, aprove apenas comandos que você entende, execute os testes do repositório e inspecione o diff final. Trate o código gerado como uma contribuição não confiável até que passe pela revisão e verificação.

Conclusão

O uso confiável do Codex API vem de testar cada camada em ordem: autenticar o Codex, chamar o Kimi diretamente, iniciar e testar o localhost, salvar a configuração de provider no nível do usuário, executar um prompt somente leitura e concluir uma tarefa envolvendo arquivos e ferramentas. Mantenha a chave real do Kimi com o router, mantenha segredos fora de arquivos compartilhados e pare o router ao terminar.