Ejecutar Kimi K3.1 Pro en Claude Code y Codex: la configuración, los fallos silenciosos y el cambio de una sola línea

Kimi K3.1 Pro habla tres protocolos: OpenAI Chat Completions, OpenAI Responses y Anthropic Messages. Esa es la razón principal por la que puede integrarse en Claude Code y Codex sin un proxy de traducción: cada herramienta ya habla uno de los tres, y Moonshot sirve ese protocolo de forma nativa. La configuración consiste en un puñado de variables de entorno en un caso y un bloque TOML de cinco líneas en el otro. Lo que hace perder una tarde a la gente no es la configuración, sino el modo de fallo. Claude Code utiliza cuatro niveles de modelo distintos para tareas distintas, y cualquier nivel que se deje sin definir falla en silencio en lugar de hacerlo de forma evidente.

Esta guía está escrita a partir de la propia documentación de integración de Moonshot, verificada el 24 de octubre de 2026, con las advertencias que la documentación entierra. Cuando un valor difiere al apuntar las mismas herramientas a una pasarela de enrutamiento en lugar de directamente a Moonshot, se señala.

Por qué no se necesita un 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.

Merece la pena señalar una consecuencia antes de la configuración: el modelo siempre razona. No hay un interruptor de pensamiento, y la profundidad se establece con un campo de nivel superior reasoning_effort que acepta low, high y max, con max como valor predeterminado. Los parámetros de muestreo son fijos —temperature 1.0, top-p 0.95, n en 1— y pasar otros valores devuelve un error. Si tu configuración anterior ajustaba la temperatura, ese ajuste no sobrevive al cambio.

Claude Code: el bloque de entorno

Claude Code lee su configuración del env bloque de ~/.claude/settings.json. Las variables escritas allí anulan los mismos nombres exportados en tu shell, lo cual es una ventaja y a la vez una trampa: una exportación obsoleta en tu terminal no te salvará si el archivo indica otra cosa.

• 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 — tu clave de API de Kimi. Esta es la variable que Claude Code usa realmente para el token de portador; una clave de API colocada en ANTHROPIC_API_KEY en su lugar es la causa más común de que una configuración que parece correcta devuelva un 401.

• ANTHROPIC_MODEL — el modelo principal de conversación: kimi-k3.1-pro.

• ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL — uno por nivel. Configure al menos los tres primeros y apunte HAIKU a un modelo barato y rápido en lugar del insignia; el propio ejemplo de Moonshot asigna ese nivel a su modelo de programación.

• CLAUDE_CODE_SUBAGENT_MODEL — lo que utilizan los subagentes. Si no se define, el trabajo de los subagentes se degrada o falla.

• CLAUDE_CODE_AUTO_COMPACT_WINDOW — configúralo en 1000000, coincidiendo con la ventana de contexto. Un valor demasiado pequeño compacta antes de tiempo y descarta contexto; uno demasiado grande produce errores de longitud de contexto.

• CLAUDE_CODE_EFFORT_LEVEL — la guía de Moonshot lo establece en max, que también es el valor predeterminado del modelo. Bajarlo reduce la calidad en tareas complejas, y cambiarlo a mitad de sesión invalida los aciertos de la caché de prefijos.

Los cuatro niveles que fallan en silencio

Este es el fallo para el que merece la pena prepararse. Claude Code utiliza modelos distintos para la conversación principal, la summarización en segundo plano, los subagentes y las pequeñas llamadas de utilidad. Configure únicamente ANTHROPIC_MODEL y las demás rutas no dan error: se quedan silenciosamente sin hacer nada útil, o recurren a alternativas que hacen que la herramienta parezca rota sin indicar la causa. La tabla de referencia de Moonshot indica explícitamente que cada nivel sin configurar provoca el fallo de la tarea correspondiente, y los síntomas parecen los de un agente lento o confundido en lugar de un error de configuración.

La lista de comprobación práctica consiste en establecer las cuatro variables de nivel junto con la variable de subagente en una única edición, reiniciar Claude Code y, a continuación, confirmar en una sesión que un subagente se ejecuta realmente. Si se queda atascado, lo primero que hay que revisar es el nivel, no el modelo.

Codex: un bloque 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 clave en sí debe estar en el entorno, no en el archivo. Codex la lee de la variable indicada en env_key, así que mantén config.toml libre de secretos y define la variable en el perfil de tu shell o en el entorno del sistema.

Dos límites que conviene conocer antes de reportar un error. Codex CLI no acepta video como entrada, aunque el modelo sí lo haga: eso es una limitación de la capa de entrada de Codex, así que el trabajo con video tiene que hacerse directamente a través de la API. Y la propia gestión de contexto de Codex sigue aplicándose: una ventana de 1M de tokens no significa que todas las sesiones deban usar una.

Hacer que ambas herramientas apunten a una misma puerta de enlace en su lugar

Todo lo anterior funciona sin cambios si reemplazas las URL base de Moonshot por las de una puerta de enlace, lo cual resulta útil cuando el mismo código base también llama a modelos de otros proveedores. OrcaRouter expone las tres interfaces para Kimi K3.1 Pro — /v1/chat/completions, /v1/responses y /v1/messages — y publica el modelo con el 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.

Lo que obtienes con la sustitución es una credencial para cada modelo del catálogo y una política de enrutamiento que puede mover una solicitud entre proveedores sin cambiar el código de la aplicación, lo que hace posible un plan de respaldo cuando el endpoint de un modelo nuevo aplica límites de tasa durante la semana de lanzamiento. Lo que pierdes es la consola propia del proveedor y cualquier superficie beta específica del proveedor. Los precios se trasladan según la lista del proveedor: 2,00 USD por millón de tokens de entrada y 10,00 USD por millón de salida para Kimi K3.1 Pro, sin ningún recargo añadido.

Una verificación de cinco minutos

• Prueba el endpoint directamente antes de tocar el cliente: un POST a la ruta de Messages o Chat Completions con una solicitud de un solo token debería devolver JSON, y un 401 significa que la clave es incorrecta o pertenece a la otra plataforma.

• En Claude Code, haz una pregunta que fuerce un subagente —una búsqueda en varios archivos— y observa si se completa. Esa es la prueba más rápida de la configuración de niveles.

• En Codex, inicia una sesión en un repositorio pequeño y comprueba que el modelo informa de la ventana de 1M; si informa de un valor predeterminado menor, model_context_window no surtió efecto.

• Configura el esfuerzo de forma deliberada, una sola vez, al inicio de la sesión: máximo para depuración difícil, alto para ediciones habituales, bajo para extracción y formato. El valor predeterminado es máximo y, en este modelo, esa es la opción costosa.