Eseguire Kimi K3.1 Pro in Claude Code e Codex: la configurazione, i fallimenti silenziosi e l'interruttore a una riga

Kimi K3.1 Pro parla tre protocolli: OpenAI Chat Completions, OpenAI Responses e Anthropic Messages. È proprio per questo che può inserirsi in Claude Code e Codex senza un proxy di traduzione — ciascuno strumento parla già uno dei tre, e Moonshot serve quel protocollo nativamente. La configurazione consiste in una manciata di variabili d'ambiente in un caso e in un blocco TOML di cinque righe nell'altro. La parte che costa un pomeriggio alle persone non è la configurazione; è la modalità di errore. Claude Code usa quattro diversi livelli di modello per compiti diversi, e qualsiasi livello lasciato non impostato fallisce in modo silenzioso anziché evidente.

Questa guida è redatta sulla base della documentazione di integrazione di Moonshot stessa, verificata il 24 ottobre 2026, con le avvertenze che la documentazione nasconde. Laddove un valore differisca quando si indirizzano gli stessi strumenti verso un gateway di routing anziché direttamente a Moonshot, ciò viene segnalato.

Perché non serve alcun proxy

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.

Una conseguenza merita di essere dichiarata prima della configurazione: il modello ragiona sempre. Non esiste un interruttore per il pensiero e la profondità viene impostata con un campo di primo livello reasoning_effort che accetta low, high e max, con valore predefinito max. I parametri di campionamento sono fissi — temperature 1.0, top-p 0.95, n a 1 — e il passaggio di altri valori restituisce un errore. Se la configurazione precedente regolava la temperature, tale regolazione non sopravvive al passaggio.

Claude Code: il blocco ambiente

Claude Code legge la propria configurazione dal blocco env di ~/.claude/settings.json. Le variabili scritte lì sovrascrivono gli stessi nomi esportati nella tua shell, il che è sia una funzionalità sia una trappola: un export obsoleto nel tuo terminale non ti salverà se il file dice qualcos'altro.

• 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 — la tua chiave API Kimi. È la variabile che Claude Code usa effettivamente per il token bearer; una chiave API inserita invece in ANTHROPIC_API_KEY è il motivo più comune per cui una configurazione dall'aspetto corretto restituisce 401.

• ANTHROPIC_MODEL — il modello principale della conversazione: kimi-k3.1-pro.

• ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL — uno per livello. Imposta almeno i primi tre e punta HAIKU su un modello economico e veloce anziché sul flagship; l'esempio di Moonshot stesso associa quel livello al suo modello di coding.

• CLAUDE_CODE_SUBAGENT_MODEL — cosa usano i sub-agenti. Se non impostata, il lavoro dei sub-agenti si degrada o fallisce.

• CLAUDE_CODE_AUTO_COMPACT_WINDOW — impostato a 1000000, in linea con la finestra di contesto. Se troppo piccolo, compatta in anticipo e getta via contesto; se troppo grande, produce errori di lunghezza del contesto.

• CLAUDE_CODE_EFFORT_LEVEL — La guida di Moonshot lo imposta su max, che è anche il valore predefinito del modello. Abbassarlo riduce la qualità sulle attività complesse, e modificarlo a metà sessione invalida gli hit della cache dei prefissi.

I quattro livelli che falliscono silenziosamente

Questo è il tipo di errore per cui vale la pena pianificare. Claude Code usa modelli diversi per la conversazione principale, la sintesi in background, i sub-agenti e le piccole chiamate di utilità. Configura solo ANTHROPIC_MODEL e gli altri percorsi non danno errore — in silenzio non fanno nulla di utile, oppure ricadono su comportamenti che fanno sembrare lo strumento rotto senza indicarne la causa. La tabella di riferimento di Moonshot è esplicita sul fatto che ogni livello non impostato causa il fallimento dell'attività corrispondente, e i sintomi sembrano quelli di un agente lento o confuso piuttosto che di un errore di configurazione.

La checklist pratica consiste nell'impostare tutte e quattro le variabili di livello e la variabile del sub-agente in un'unica modifica, riavviare Claude Code e poi verificare in una sessione che un sub-agente venga effettivamente eseguito. Se si blocca, la prima cosa da controllare è il livello, non il modello.

Codex: un blocco 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.

La chiave stessa deve risiedere nell'ambiente, non nel file. Codex la legge dalla variabile indicata in env_key, quindi mantieni config.toml privo di segreti e imposta la variabile nel profilo della shell o nell'ambiente di sistema.

Due limiti da conoscere prima di segnalare un bug. Codex CLI non accetta video come input anche se il modello lo fa — è un limite dello strato di input di Codex, quindi il lavoro sui video deve passare direttamente dall'API. E la gestione del contesto propria di Codex vale comunque: una finestra da 1M di token non significa che ogni sessione debba usarne una.

Puntando invece entrambi gli strumenti su un unico gateway

Tutto quanto sopra funziona senza modifiche se sostituisci gli URL di base di Moonshot con quelli di un gateway, il che è utile quando lo stesso codice chiama anche modelli di altri fornitori. OrcaRouter espone tutte e tre le superfici per Kimi K3.1 Pro — /v1/chat/completions, /v1/responses e /v1/messages — e pubblica il modello con l'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.

In cambio della sostituzione ottieni un'unica credenziale per ogni modello del catalogo e una policy di routing capace di spostare una richiesta da un fornitore all'altro senza modificare il codice dell'applicazione — ciò che rende possibile un piano di fallback quando l'endpoint di un nuovo modello va in rate-limit nella settimana di lancio. Quello a cui rinunci sono la console del fornitore stesso e qualsiasi superficie beta specifica del fornitore. I prezzi vengono applicati al listino del provider: $2.00 per milione di token di input e $10.00 per milione di token di output per Kimi K3.1 Pro, senza alcun ricarico aggiunto.

Una verifica di cinque minuti

• Chiama l'endpoint direttamente prima di toccare il client: una POST alla route Messages o Chat Completions con una richiesta da un solo token dovrebbe restituire JSON, e un 401 significa che la chiave è sbagliata o appartiene all'altra piattaforma.

• In Claude Code, poni una domanda che costringa un sub-agente — una ricerca su più file — e osserva se viene completata. È il test più rapido della configurazione del tier.

• In Codex, avvia una sessione su un repository di piccole dimensioni e verifica che il modello riporti la finestra da 1M; se riporta un valore predefinito più piccolo, model_context_window non ha avuto effetto.

• Imposta il livello di impegno in modo deliberato, una volta, all'inizio della sessione: {{1}}max{{/1}} per il debug difficile, {{2}}alto{{/2}} per le modifiche ordinarie, {{3}}basso{{/3}} per estrazione e formattazione. Il valore predefinito è {{4}}max{{/4}}, e su questo modello è la scelta costosa.