Executando o Kimi K3.1 Pro no Claude Code e no Codex: a configuração, as falhas silenciosas e a troca de uma linha

O Kimi K3.1 Pro fala três protocolos: OpenAI Chat Completions, OpenAI Responses e Anthropic Messages. É exatamente por isso que ele pode ser encaixado no Claude Code e no Codex sem um proxy de tradução — cada ferramenta já fala um dos três, e a Moonshot serve esse protocolo nativamente. A configuração é um punhado de variáveis de ambiente em um caso e um bloco TOML de cinco linhas no outro. A parte que custa uma tarde às pessoas não é a configuração; é o modo de falha. O Claude Code usa quatro níveis diferentes de modelo para tarefas diferentes, e qualquer nível deixado sem definição falha silenciosamente, em vez de ruidosamente.

Este guia foi escrito a partir da documentação de integração da própria Moonshot, verificada em 24 de outubro de 2026, com as ressalvas que a documentação omite. Onde um valor difere ao apontar as mesmas ferramentas para um gateway de roteamento em vez de diretamente para a Moonshot, isso é destacado.

Por que nenhum proxy é necessário

Claude Code talks to Anthropic's Messages API; Codex talks to the Responses API. Moonshot exposes both. Its Anthropic-compatible surface lives at https://api.moonshot.ai/anthropic and its Responses API at https://api.moonshot.ai/v1, and the model id is kimi-k3.1-pro on both. Nothing in either client needs to know it is not talking to the vendor it was built for.

Uma consequência merece ser mencionada antes da configuração: o modelo sempre raciocina. Não há alternância de pensamento, e a profundidade é definida com um campo reasoning_effort de nível superior que aceita low, high e max, com padrão max. Os parâmetros de amostragem são fixos — temperature 1.0, top-p 0.95, n em 1 — e passar outros valores retorna um erro. Se sua configuração anterior ajustou a temperature, esse ajuste não sobrevive à troca.

Claude Code: o bloco de ambiente

O Claude Code lê a sua configuração do bloco env de ~/.claude/settings.json. As variáveis lá escritas substituem os mesmos nomes exportados na sua shell, o que é tanto uma vantagem como uma armadilha: uma exportação obsoleta no seu terminal não o salvará se o ficheiro disser outra coisa.

• ANTHROPIC_BASE_URL — the Kimi endpoint root. Set it to https://api.moonshot.ai/anthropic. If you leave it unset, requests go to Anthropic and fail authentication.

• ANTHROPIC_AUTH_TOKEN — sua chave de API do Kimi. Esta é a variável que o Claude Code realmente usa para o token bearer; uma chave de API colocada em ANTHROPIC_API_KEY em vez desta é o motivo mais comum de uma configuração aparentemente correta retornar 401.

• ANTHROPIC_MODEL — o modelo principal de conversa: kimi-k3.1-pro.

• ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL — um por nível. Defina pelo menos os três primeiros e aponte o HAIKU para um modelo barato e rápido em vez do principal; o próprio exemplo da Moonshot mapeia esse nível para o seu modelo de programação.

• CLAUDE_CODE_SUBAGENT_MODEL — o que os subagentes usam. Se não definido, o trabalho dos subagentes degrada ou falha.

• CLAUDE_CODE_AUTO_COMPACT_WINDOW — defina como 1000000, correspondendo à janela de contexto. Um valor muito pequeno compacta cedo demais e descarta contexto; um valor muito grande produz erros de comprimento de contexto.

• CLAUDE_CODE_EFFORT_LEVEL — o guia da Moonshot define isso como max, que também é o padrão do modelo. Reduzi-lo diminui a qualidade em tarefas complexas, e alterá-lo no meio da sessão invalida os acertos do cache de prefixo.

As quatro camadas que falham silenciosamente

Esta é a falha para a qual vale a pena se planejar. O Claude Code usa modelos diferentes para a conversa principal, a sumarização em segundo plano, os subagentes e as pequenas chamadas utilitárias. Configure apenas ANTHROPIC_MODEL e os outros caminhos não geram erro — eles silenciosamente não fazem nada útil, ou recorrem a alternativas que fazem a ferramenta parecer quebrada sem indicar a causa. A tabela de referência da Moonshot é explícita ao afirmar que cada nível não definido faz com que a tarefa correspondente falhe, e os sintomas parecem um agente lento ou confuso, em vez de um erro de configuração.

A lista de verificação prática é definir as quatro variáveis de nível mais a variável de subagente em uma única edição, reiniciar o Claude Code e, em seguida, confirmar em uma sessão que um subagente realmente é executado. Se travar, o nível é a primeira coisa a verificar, não o modelo.

Codex: um bloco TOML

Codex reads ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml). The connection is defined by four values in a provider block: the model id kimi-k3.1-pro, a provider named kimi, base_url pointing at https://api.moonshot.ai/v1, the environment-variable name that holds the key, and — the setting that makes the direct connection work — wire_api = "responses". Set model_context_window to 1048576 as well; without it Codex falls back to default model metadata, which degrades behaviour on long inputs.

A própria chave pertence ao ambiente, não ao ficheiro. O Codex lê-a a partir da variável indicada em env_key, portanto mantenha config.toml livre de segredos e defina a variável no perfil da shell ou no ambiente do sistema.

Dois limites que você precisa conhecer antes de abrir um bug. O Codex CLI não aceita vídeo como entrada, embora o modelo aceite — isso é uma limitação da camada de entrada do Codex, então o trabalho com vídeo precisa passar diretamente pela API. E o gerenciamento de contexto do próprio Codex continua valendo: uma janela de 1M de tokens não significa que toda sessão deva usar uma.

Em vez disso, apontar as duas ferramentas para um único gateway

Tudo o que foi descrito acima funciona sem alterações se substituir os URLs base da Moonshot pelos de um gateway, o que é útil quando a mesma base de código também chama modelos de outros fornecedores. O OrcaRouter expõe as três interfaces para o Kimi K3.1 Pro — /v1/chat/completions, /v1/responses e /v1/messages — e publica o modelo com o id kimi/kimi-k3.1-pro.

For Claude Code, that means ANTHROPIC_BASE_URL set to the gateway root (https://api.orcarouter.ai) with the provider-prefixed model id in the four tier variables. For Codex, the same TOML block with the base URL pointing at https://api.orcarouter.ai/v1 and the model id kimi/kimi-k3.1-pro. The key variable stays the same shape; it just holds a gateway key instead of a vendor key.

O que você ganha com a substituição é uma credencial para cada modelo do catálogo e uma política de roteamento capaz de mover uma requisição entre fornecedores sem alterar o código da aplicação — é isso que torna possível um plano de fallback quando o endpoint de um novo modelo passa a limitar a taxa de requisições na semana de lançamento. O que você abre mão é do console próprio do fornecedor e de qualquer interface beta específica dele. Os preços são repassados conforme a tabela do provedor: US$ 2,00 por milhão de tokens de entrada e US$ 10,00 por milhão de tokens de saída para o Kimi K3.1 Pro, sem nenhuma margem adicionada.

Uma verificação de cinco minutos

• Acesse o endpoint diretamente antes de mexer no cliente: um POST para a rota Messages ou Chat Completions com uma requisição de um token deve retornar JSON, e um 401 significa que a chave está errada ou pertence à outra plataforma.

• No Claude Code, faça uma pergunta que force um subagente — uma busca em vários arquivos — e observe se ele é concluído. Esse é o teste mais rápido da configuração de níveis.

• No Codex, inicie uma sessão em um repositório pequeno e verifique se o modelo reporta a janela de 1M; se ele reportar um padrão menor, model_context_window não entrou em vigor.

Defina o esforço deliberadamente, uma única vez, no início da sessão: máximo para depuração difícil, alto para edições comuns, baixo para extração e formatação. O padrão é máximo e, neste modelo, essa é a escolha cara.