A Plataforma do Kimi oferece suporte nativo à API Responses usada pelo Codex, portanto o Codex pode usar modelos Kimi diretamente — sem conversão de protocolo nem proxy local. Este guia apresenta a configuração completa no macOS e no Windows.
O que é o Codex?
O Codex é o agent de programação da OpenAI para trabalhar em repositórios e no terminal. Ele pode:
Escrever código: Criar funções, testes, scripts e recursos específicos.
Entender bases de código desconhecidas: Pesquisar arquivos, rastrear chamadas e explicar componentes.
Revisar código: Identificar possíveis defeitos, suposições arriscadas, testes ausentes e questões de segurança.
Depurar e corrigir problemas: Reproduzir erros, propor alterações e executar verificações.
Automatizar tarefas rotineiras: Atualizar arquivos e executar fluxos de trabalho documentados com sua aprovação.
Instale e entre no Codex
Parte 1: instale o Codex CLI
Abra o Terminal no macOS ou o PowerShell no Windows.
Execute o comando referente ao seu sistema operacional:
macOS:
Windows:
Aguarde a instalação terminar e feche e abra novamente o Terminal ou o PowerShell.
Execute:
Selecione Entrar com o ChatGPT, conclua o login no navegador e volte ao Terminal ou ao PowerShell. Uma conta gratuita do ChatGPT é suficiente para esse login; não é necessária uma assinatura paga. A rota externa do Kimi que você configurará depois não usa a cobrança da OpenAI.
Parte 2: instale o aplicativo desktop do Codex
Acesse a página oficial de download em https://chatgpt.com/download e baixe o aplicativo desktop para macOS ou Windows. O Codex está incluído como um modo de trabalho no aplicativo desktop do ChatGPT — o aplicativo baixado se chama ChatGPT.
Instale e abra o aplicativo, depois entre com sua conta do ChatGPT.
Crie uma tarefa ou abra um projeto e selecione Codex como modo de trabalho.
Digite
Diga olá em uma frase.e envie a mensagem.
Modelos de IA integrados vs. APIs externas de LLM
Depois de instalar o Codex, você pode usar os modelos de IA integrados ou conectar uma API externa de LLM compatível. A melhor opção depende de quanto você deseja investir em configuração, flexibilidade e gerenciamento de contas.
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 programar sem executar outro serviço nem configurar uma chave de API separada.
Vantagens:
Configuração rápida, sem etapas adicionais.
Integração direta com 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 se quiser usar um modelo de outro provedor
Exige login com uma conta do ChatGPT. Os planos gratuitos incluem acesso limitado ao Codex, mas o uso regular geralmente exige um plano pago do ChatGPT (como Plus ou Pro) ou uma chave da API da OpenAI cobrada conforme o uso.
Use uma API de LLM externa
Uma API externa oferece mais opções de modelos e permite usar uma conta existente de outro provedor. A Plataforma Aberta do Kimi oferece suporte nativo à Responses API usada pelo Codex, portanto a conexão é direta — não é necessário um roteador local.
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 do GPT. Ideal para cenários sensíveis a custo.
Limitações:
Exige uma chave de API e uma pequena alteração na configuração
Cobrança, compatibilidade, privacidade e solução de problemas dependem do provedor externo
Se quiser a configuração mais rápida, comece com um modelo integrado. Se já tiver uma conta de API externa ou quiser mais opções de modelos, continue com o passo a passo a seguir.
Como conectar uma API de LLM externa ao Codex: exemplo com Kimi
Etapa 1: crie uma chave da API do Kimi
Abra a plataforma da API do Kimi. Crie uma chave de API no console e guarde-a em um gerenciador de senhas ou de segredos. A chave completa é exibida apenas uma vez — copie-a antes de sair da página.
Observação: a API do Kimi é um serviço pago conforme o uso. Antes de testar, verifique se sua conta tem saldo disponível — confira ou adicione saldo em Billing no console. Uma nova chave de API, por si só, não permite fazer chamadas se o saldo da conta for zero.
Etapa 2: defina a variável de ambiente KIMI_API_KEY
O Codex lê a chave de API de uma variável de ambiente. Não escreva a chave em config.toml.
macOS e Linux:
Para evitar que a chave fique no histórico do shell, informe-a da seguinte forma:
Isso vale apenas para a sessão atual do terminal. Para mantê-la, adicione o comando export ao ~/.zshrc (ou ao ~/.bashrc, se usar bash no Linux). O arquivo armazena a chave em texto simples — defina as permissões adequadamente.
Windows (PowerShell):
Substitua YOUR_KIMI_API_KEY pela chave copiada na Etapa 1. Para mantê-la entre sessões, adicione KIMI_API_KEY em Settings > System > About > Advanced system settings > Environment Variables.
Etapa 3: adicione o Kimi como provedor de modelos
Abra o arquivo de configuração do Codex no nível de usuário: ~/.codex/config.toml no macOS e Linux (no Windows: %USERPROFILE%\.codex\config.toml). Se o arquivo ainda não existir, crie-o.
Adicione a configuração a seguir. Se model ou model_provider já existirem, substitua os valores deles e exclua qualquer linha que comece com model_catalog_json = ou service_tier = (linhas restantes de outras configurações podem substituir os metadados ou o roteamento do seu modelo):
Se sua chave de API foi criada na plataforma da China (platform.moonshot.cn), use https://api.moonshot.cn/v1 como valor de base_url — as chaves não são intercambiáveis entre as duas plataformas.
Mantenha inalteradas as configurações existentes não relacionadas (como preferências de notify, aprovação, sandbox, projeto e interface) e não remova outras seções de provedores, como [model_providers.openai].
O que cada configuração faz:
| Configuração | Tipo | Finalidade |
|---|---|---|
wire_api = "responses" | string | Conecta-se ao Kimi pela Responses API nativa — a configuração principal para a conexão direta |
env_key = "KIMI_API_KEY" | string | Nome da variável de ambiente da qual o Codex lê a chave de API |
model_context_window = 1048576 | integer | Corresponde à janela de contexto de 1M do kimi-k3; sem isso, o Codex recorre aos metadados padrão do modelo, o que pode prejudicar o desempenho |
Etapa 4: Reinicie o Codex e verifique a conexão
O Codex lê config.toml apenas na inicialização; portanto, encerre completamente qualquer sessão do Codex em execução. Em seguida, acesse o diretório do seu projeto e inicie o Codex:
Após a inicialização, confirme que o Codex CLI mostra kimi-k3 como o modelo atual:
Envie uma solicitação simples (por exemplo, hello). Uma resposta normal confirma que o Codex está conectado pela Kimi Responses API.
Para confirmar que a resposta realmente veio pelo Kimi, verifique se a sessão mostra kimi como provedor — por exemplo, digitando /status na sessão do Codex. Internamente, o Codex envia solicitações para POST https://api.moonshot.ai/v1/responses.
Use o Kimi no aplicativo de desktop do Codex
O aplicativo de desktop compartilha a mesma configuração de nível de usuário da CLI. Primeiro, conclua as Etapas 1–3 acima e, em seguida:
Etapa 1: Reinicie completamente o aplicativo de desktop
No macOS, pressione Command+Q para encerrar completamente o aplicativo de desktop. Apenas fechar a janela não é suficiente.
No Windows, feche todas as janelas do aplicativo de desktop e confirme que ele não está mais em execução na bandeja do sistema.
Abra novamente o aplicativo de desktop para que ele recarregue ~/.codex/config.toml e abra uma pasta de projeto.
Etapa 2: Mantenha o modelo Custom selecionado
Abra o seletor de modelos e escolha kimi-k3. A interface pode mostrar Custom em vez do nome do modelo — isso é esperado. Nem sempre os provedores personalizados definidos em config.toml são exibidos pelo nome na lista de modelos do aplicativo de desktop, mas as solicitações continuam usando o kimi-k3 configurado.
Etapa 3: Verifique o caminho da solicitação no desktop
Envie uma solicitação simples, como hi — uma resposta normal indica que a conexão básica está funcionando:
Em seguida, envie uma tarefa que use os recursos de agent do Codex:
Se o Desktop continuar gerando uma resposta final depois que os resultados das ferramentas retornarem, as chamadas ao modelo e o uso de ferramentas estão funcionando corretamente.
Solução de erros comuns de integração
Ainda aparece "Missing environment variable" depois de configurá-la
As sessões do Codex se conectam a um daemon app-server em segundo plano, cujo ambiente é capturado quando o daemon é iniciado — não quando você inicia uma sessão. Se o daemon já estava em execução quando você definiu KIMI_API_KEY, ele não verá a variável, mesmo que o terminal atual a mostre como definida. No macOS, grave a variável no ambiente de sessão da GUI e reinicie o daemon:
Em seguida, inicie o Codex novamente. No Windows, saia e entre novamente na conta (ou reinicie completamente o aplicativo de desktop) depois de definir a variável em todo o sistema.
401 Não autorizado
A chave de API é inválida, ou a chave e o base_url pertencem a plataformas diferentes — chaves de API criadas em platform.kimi.ai funcionam apenas com https://api.moonshot.ai/v1, e chaves criadas em platform.moonshot.cn funcionam apenas com https://api.moonshot.cn/v1. Confirme também que KIMI_API_KEY está disponível no ambiente usado para iniciar o Codex ou o Desktop. Na CLI, verifique isso no terminal em que você inicia o Codex:
400 web_search.search_context_size não é compatível
A solicitação inclui o parâmetro search_context_size, que ainda não é compatível — remova-o. O Codex não envia esse parâmetro por padrão, e a ferramenta web_search integrada funciona imediatamente.
404 em /v1/responses
base_url está incorreto — verifique se ele é exatamente https://api.moonshot.ai/v1 (com o sufixo /v1). Se você se conectou anteriormente pelo CC Switch ou outro roteador local, confirme também que base_url não aponta mais para um endereço local, como http://127.0.0.1:....
429 Limite de taxa
Você atingiu um limite de taxa ou de simultaneidade. Verifique as cotas do seu nível em Limits no console da plataforma Kimi API.
Aviso: metadados do modelo para kimi-k3 não encontrados
kimi-k3 não está no catálogo de modelos integrado do Codex. Este aviso é esperado e não afeta o uso — o model_context_window = 1048576 da Etapa 3 já garante que a janela de contexto seja tratada como 1M.
As alterações de configuração não entram em vigor
O Codex só lê config.toml na inicialização — feche-o e reinicie-o. Confirme também que você editou o próprio arquivo ~/.codex/config.toml no nível do usuário e que nenhuma flag -c ou perfil está substituindo essa configuração. Se você se conectou anteriormente pelo CC Switch, desative também o Codex em Settings > Routing — caso contrário, ele continuará regravando config.toml e substituirá a nova configuração.
Benefícios de usar a API do Kimi
Usar o Kimi em fluxos de trabalho da API do Codex pode aprimorar tarefas de programação, depuração e desenvolvimento. Seus recursos avançados ajudam a gerar respostas precisas, lidar com instruções complexas e resolver problemas com mais rapidez. Veja os principais benefícios de usar o Kimi em fluxos de trabalho do Codex para aumentar a produtividade e a eficiência.
Compreensão de código com contexto extenso
O Kimi pode processar grandes volumes de código e informações de uma só vez. Ele reconhece com mais eficácia as relações entre diferentes arquivos e seções do projeto. 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 analisados rapidamente com o Kimi. Fica mais fácil encontrar detalhes importantes sem examinar manualmente cada arquivo. Os desenvolvedores conseguem entender melhor o projeto inteiro em menos tempo.
Desenvolvimento com IA econômico
O Kimi oferece uma opção prática e acessível para lidar com diversas tarefas de desenvolvimento. Há suporte avançado de IA disponível sem depender inteiramente de modelos mais caros. As equipes podem aumentar a produtividade geral e manter melhor controle sobre os custos.
Recuperação mais rápida de informações
Informações úteis podem ser localizadas rapidamente em grandes bases de código, conjuntos de dados e arquivos de projeto. Menos tempo é gasto buscando respostas ou referências nesses recursos. Assim, é possível dedicar mais atenção à programação, aos testes e ao aprimoramento do projeto.
Automação de fluxos de trabalho aprimorada
Tarefas repetitivas de desenvolvimento se tornam 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 permanecem organizados, eficientes e mais produtivos ao longo do tempo.
Como o Codex aprimora o fluxo de trabalho de desenvolvimento
Um fluxo de trabalho da API do Codex CLI configurado conecta a inspeção do repositório, a edição, os comandos e a revisão em um único contexto. O Codex pode criar a estrutura de arquivos, explicar módulos desconhecidos, reproduzir falhas, propor testes e executar verificações aprovadas. O suporte a provedores externos amplia as opções de modelo, mas não elimina a responsabilidade pela revisão.
Comece cada tarefa com um objetivo específico. Peça ao Codex que inspecione antes de editar, revise as alterações propostas, aprove apenas comandos que você entende, execute os testes do repositório e examine o diff final. Trate o código gerado como uma contribuição não confiável até que ele passe pela revisão e pela verificação.
Conclusão
O uso confiável da API do Codex depende de testar cada etapa na ordem certa: crie e adicione créditos à sua conta do Kimi, defina a chave de API no ambiente, salve a configuração do provedor no nível do usuário, reinicie o Codex e verifique com um prompt simples antes de passar para tarefas de agent. Mantenha a chave na variável de ambiente, e não em config.toml, e nunca publique uma chave real.