Cómo usar Kimi K3 con Claude Code: guía de configuración completa
Qué es Kimi K3 y por qué meterlo en Claude Code
Kimi K3 es el modelo insignia de Moonshot AI, lanzado el 16 de julio de 2026. Es un modelo Mixture of Experts de 2,8 billones de parámetros con una ventana de contexto de 1.048.576 tokens y visión nativa. Moonshot lo vende como el primer modelo abierto de la clase 3T y dice que los pesos completos salen antes del 27 de julio de 2026.
El detalle que más se nota en el día a día es que K3 razona siempre. Ahora mismo reasoning_effort solo acepta max y no existe una variante sin razonamiento. Moonshot ha dicho que llegarán modos de esfuerzo bajo y alto, pero de salida cada petición piensa a fondo. Eso lo hace fuerte en problemas difíciles y lento y caro en los fáciles.
El precio por token es de 0,30 dólares por millón de tokens en aciertos de caché, 3,00 en fallos de caché y 15,00 de salida, plano en todo el contexto de 1M y sin recargo por contexto largo. Ese descuento de 10x por acierto de caché importa mucho en un agente que reenvía el contexto de un repo grande en cada turno.
¿Y por qué ejecutarlo con Claude Code en vez de con la CLI propia de Moonshot? Porque Claude Code ya lo tienes configurado. Tus hooks, tus servidores MCP, tu CLAUDE.md, tus skills y tus comandos siguen funcionando. Cambiar el modelo es una variable de entorno. Cambiar de herramienta es un fin de semana.
No confundas el modelo con la CLI. Kimi K3 es el modelo. Kimi Code CLI es el agente de terminal propio de Moonshot, un producto aparte que compite con Claude Code. Esta guía va de ejecutar el modelo K3 dentro de Claude Code, que no necesita ninguna CLI nueva.
Elige endpoint primero: suscripción o pago por token
Este es el paso que la gente se salta y es la causa de casi todos los fallos de configuración. Moonshot tiene dos endpoints compatibles con Anthropic separados. Tienen hosts distintos, nombres de variable de autenticación distintos e ids de modelo distintos. Una clave de uno devuelve 401 en el otro. Decide en cuál estás antes de copiar ninguna config.
Opción A: la suscripción de Kimi Code
Pagas una cuota mensual fija y tienes un cupo. El endpoint es https://api.kimi.com/coding/, te autenticas con ANTHROPIC_API_KEY usando una clave de la consola de Kimi Code, y el id de modelo es k3[1m]. El cupo se renueva cada 7 días desde la fecha de tu suscripción y no se acumula, y encima hay una ventana rodante de 5 horas, así que puedes chocarte contra un límite aunque te quede cupo.
Opción B: la Open Platform de Moonshot
Pagas por token sin compromiso mensual. El endpoint es https://api.moonshot.ai/anthropic, te autenticas con ANTHROPIC_AUTH_TOKEN usando una clave de platform.kimi.ai, y el id de modelo es kimi-k3. Los límites van por niveles según cuánto has recargado en total, y el nivel de entrada es directamente inusable para trabajo agéntico: en el Tier 0 tienes 1 petición concurrente y 3 peticiones por minuto. Necesitas al menos 10 dólares de recarga acumulada para llegar al Tier 1 y sus 50 concurrentes.
La variable de autenticación es distinta a propósito y se pelean entre ellas. El endpoint de plataforma usa ANTHROPIC_AUTH_TOKEN, y Moonshot dice explícitamente que quites ANTHROPIC_API_KEY si la tienes puesta, porque las dos entran en conflicto. Si alguna vez exportaste una clave de Anthropic en tu perfil de shell, quítala antes de probar.
Configuración A: Kimi K3 en Claude Code con suscripción de Kimi Code
Saca una clave de la consola de Kimi Code y exporta esto antes de lanzar Claude Code:
export ANTHROPIC_BASE_URL=https://api.kimi.com/coding/
export ANTHROPIC_API_KEY=tu_clave_de_kimi_code
export ANTHROPIC_MODEL="k3[1m]"
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=1048576
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=1048576
export CLAUDE_CODE_EFFORT_LEVEL=maxLuego ejecuta claude y escribe /status. La base URL que muestre debería ser https://api.kimi.com/coding/. Si sigue apareciendo la de Anthropic, tus exports no llegaron al proceso, y eso casi siempre significa que los pusiste en un shell distinto del que lanzó la CLI.
El contexto de 1M está limitado por tu plan. K3 te da 256k en Moderato y el 1M completo solo en Allegretto o superior. Si estás en el plan barato y copias CLAUDE_CODE_MAX_CONTEXT_TOKENS=1048576 igualmente, le estás diciendo a Claude Code que tiene una ventana que tu plan no te da, y Moonshot avisa de que eso provoca compactación prematura y errores. En Moderato usa 262144.
Ese límite conviene entenderlo antes de suscribirte, porque el contexto de 1M es el argumento de venta principal y no está en el plan de entrada. Las propias páginas de Moonshot se contradicen ahora mismo sobre si el acceso a Kimi Code empieza en Moderato o en Allegretto, así que mira qué incluye tu plan en el momento de pagar en vez de fiarte de ninguna tabla que leas en un post, incluido este.
Configuración B: Kimi K3 en Claude Code pagando por token
Saca una clave en platform.kimi.ai, asegúrate de que no hay ninguna ANTHROPIC_API_KEY puesta y exporta esto:
unset ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic
export ANTHROPIC_AUTH_TOKEN=tu_clave_de_plataforma
export ANTHROPIC_MODEL=kimi-k3
export ANTHROPIC_DEFAULT_OPUS_MODEL=kimi-k3
export ANTHROPIC_DEFAULT_SONNET_MODEL=kimi-k3
export ANTHROPIC_DEFAULT_HAIKU_MODEL=kimi-k3
export CLAUDE_CODE_SUBAGENT_MODEL=kimi-k3
export ENABLE_TOOL_SEARCH=false
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=1048576Las tres líneas de ANTHROPIC_DEFAULT_* importan más de lo que parece. Claude Code elige modelos distintos para trabajos distintos, y si solo pones ANTHROPIC_MODEL puede seguir intentando tirar de un id de Haiku o de Sonnet que no existe en el endpoint de Moonshot. Apuntarlos todos a kimi-k3, más CLAUDE_CODE_SUBAGENT_MODEL para los subagentes, mantiene todas las llamadas internas en el mismo modelo.
Cuando arranque, recuerda que la escalera de niveles va según tu recarga acumulada, no según un plan que elijas. El Tier 0 con 3 peticiones por minuto hace que una sesión agéntica parezca rota más que lenta, así que si vas a probar esto en serio, recarga hasta el Tier 1 primero.
Qué deja de funcionar: la lista honesta
Un endpoint compatible con Anthropic es compatible, no idéntico. Algunas funciones de Claude Code no sobreviven al cambio, y es mejor saberlo ahora que depurarlo a medianoche.
Tool Search, mejor apagado
La documentación de Moonshot del endpoint de plataforma dice literalmente que el endpoint de Kimi todavía no soporta esta función y que hay que poner ENABLE_TOOL_SEARCH=false porque, si no, las tool calls se comportan mal. En la práctica no suele hacer falta tocar nada: Claude Code ya desactiva Tool Search por defecto cuando ANTHROPIC_BASE_URL apunta a un host que no es de Anthropic. El peligro real es forzar ENABLE_TOOL_SEARCH=true a mano: hay un reporte abierto y sin respuesta en el tracker de Moonshot según el cual, en el endpoint de suscripción, los bloques tool_reference dejan la sesión devolviendo HTTP 400 en todas las peticiones siguientes, y la única salida práctica es abrir una sesión nueva. Es un reporte de un solo usuario sin confirmar, pero no hay motivo para jugársela. El false explícito de la configuración de arriba es cinturón y tirantes.
WebFetch da error
WebFetch no funciona ahora mismo en el endpoint de Kimi. Al llamarlo, o devuelve un error de "temporarily unavailable" o vuelve sin contenido. Moonshot lo reconoce en su FAQ: es una limitación de su plataforma, no de tu configuración, y funcionará cuando añadan soporte. Mientras tanto, el workaround oficial es pegar el contenido de la página en el chat o usar un MCP de scraping. Ojo, no lo confundas con WebSearch, que sí funciona con kimi-k3.
Las imágenes dependen del endpoint que elegiste
Esto es más turbio de lo que la mayoría de posts da a entender. Hay una petición abierta pidiendo que el endpoint de suscripción soporte imágenes desde herramientas de terceros, y menciona a Claude Code, Roo Code y Cursor como afectados. Pero es la petición de un solo usuario, sin respuesta oficial, y la evidencia real desmiente que haya un bloqueo total: hay sesiones documentadas de ese mismo endpoint decodificando PNG y JPEG en base64 sin problema, y solo rechaza webp y gif. Cuando un cliente de terceros no consigue pasarle imágenes, el problema suele estar en el lado del cliente, no en que el endpoint rechace imágenes sin más.
El endpoint de plataforma de pago por token sí documenta visión, porque K3 es multimodal de forma nativa. Pero de momento solo acepta imágenes en base64 o ficheros subidos por file id (ids ms://), no URLs públicas de imagen.
Si las capturas son parte de cómo trabajas, prueba el pegado de imágenes con tu propio cliente en el endpoint que elijas antes de comprometerte. El de plataforma tiene la visión documentada; el de suscripción es donde los reportes de terceros se vuelven turbios.
Cada petición piensa, y lo pagas
Como K3 hoy solo admite esfuerzo de razonamiento máximo, las preguntas baratas cuestan dinero de verdad. La prueba de Simon Willison el día del lanzamiento gastó 13.241 tokens de razonamiento para producir 3.417 tokens de respuesta, y lo señaló como caro. Para un agente de código que dispara muchas llamadas pequeñas a herramientas, esto suma de una forma que una comparación de precio por token esconde.
Ejecuta Kimi K3 y Claude a la vez en vez de elegir
La respuesta honesta a "¿es Kimi K3 mejor que Claude para lo mío?" es que nadie lo sabe todavía. K3 tiene días, toda la señal de calidad que circula son primeras impresiones, y lo que de verdad importa en un agente de código, llamar a herramientas de forma fiable según se alarga la conversación, no tiene ningún dato público detrás. Willison señaló justo eso en el lanzamiento: los benchmarks que circulan ni lo tocan.
O sea que la única prueba útil es tu repo, tus tareas, los dos modelos, a la vez. Eso es incómodo con un solo terminal, porque la configuración es un puñado de variables de entorno que tienes que ir cambiando. Deja de ser incómodo cuando cada terminal tiene su propio agente y su propio entorno.
Eso es lo que hace CodeAgentSwarm. Le das a un terminal el entorno de Kimi y a otro tu configuración normal de Claude, apuntas los dos a la misma tarea y miras. Cada terminal tiene diffs en vivo de lo que tocó su agente, una notificación de escritorio cuando te necesita, e historial buscable después, así que comparar dos ejecuciones es leer dos historiales en vez de fiarte de lo que recuerdas de hace veinte minutos.
Si quieres el panorama completo, la comparación Claude Code vs Cursor vs Codex cubre en qué se diferencian las herramientas, y ejecutar varias sesiones de Claude Code cubre el flujo en paralelo sobre el que se apoya esto.
Resolver problemas de la configuración
- 401 Unauthorized: casi seguro estás usando una clave de la plataforma equivocada. Las claves de platform.kimi.ai y platform.kimi.com son completamente independientes, y una clave de una devuelve 401 en la otra. Lo mismo si mezclas una clave de la consola de Kimi Code con el endpoint de plataforma.
- /status sigue mostrando la base URL de Anthropic: tus exports no llegaron al proceso. Expórtalos en el mismo shell que lanza la CLI, o ponlos en tu perfil de shell y abre un terminal nuevo.
- HTTP 400 permanente que no se recupera: mira si algo en tu configuración forzó ENABLE_TOOL_SEARCH=true (Claude Code lo desactiva por defecto en hosts que no son de Anthropic). Hay un reporte sin confirmar de bloques tool_reference dejando sesiones del endpoint de suscripción clavadas en 400. Ponlo en false y empieza una sesión nueva.
- El contexto se compacta demasiado pronto: tu ajuste de contexto no cuadra con lo que te da tu plan. En Moderato usa 262144, no 1048576.
- Tienes puestas a la vez una API key y un auth token: en el endpoint de plataforma, quita ANTHROPIC_API_KEY. Moonshot documenta el conflicto de forma explícita.
Preguntas frecuentes
Sí. Moonshot publica un endpoint compatible con Anthropic, así que Claude Code habla con Kimi K3 solo con variables de entorno y sin ninguna CLI nueva. Pon ANTHROPIC_BASE_URL a https://api.kimi.com/coding/ con una clave de suscripción de Kimi Code, o a https://api.moonshot.ai/anthropic con una clave de plataforma de pago por token, y luego pon ANTHROPIC_MODEL a k3[1m] o a kimi-k3 respectivamente.
Casi siempre porque la clave y el endpoint no coinciden. Moonshot tiene dos plataformas independientes, y una clave de platform.kimi.ai devuelve 401 en platform.kimi.com y al revés. Además el endpoint de suscripción usa ANTHROPIC_API_KEY mientras que el de pago por token usa ANTHROPIC_AUTH_TOKEN, y Moonshot dice que quites ANTHROPIC_API_KEY en el endpoint de plataforma porque las dos entran en conflicto.
Solo con el plan adecuado. K3 da 256k de contexto en Moderato y los 1.048.576 tokens completos en Allegretto o superior. Poner CLAUDE_CODE_MAX_CONTEXT_TOKENS=1048576 en un plan que solo da 256k provoca compactación prematura y errores, así que usa 262144 en el plan inferior.
Tool Search tiene que quedarse apagado: Claude Code ya lo desactiva por defecto en hosts que no son de Anthropic, y Moonshot documenta que el endpoint todavía no lo soporta. WebFetch no está disponible en el endpoint de Kimi y devuelve un error visible de "temporarily unavailable" (WebSearch sí funciona). El soporte de imágenes desde clientes de terceros en el endpoint de suscripción es inconsistente, y en el de pago por token la visión funciona solo como base64 o ids de fichero ms://, no URLs públicas.
Por token parece mucho más barato: 0,30 dólares por millón en aciertos de caché, 3,00 en fallos y 15,00 de salida. Pero K3 ahora mismo solo admite esfuerzo de razonamiento máximo, así que cada petición piensa a fondo y quema tokens de razonamiento incluso en preguntas simples. El coste real depende de tu carga de trabajo, y por eso tenerlo unos días en un terminal al lado de tu configuración normal te dice más que cualquier tabla de precios.
No. Kimi K3 es el modelo, y lo puedes ejecutar dentro de Claude Code como describe esta guía. Kimi Code CLI es el agente de terminal propio de Moonshot, un producto aparte que compite con Claude Code y que tiene su propia configuración, sus hooks y sus sesiones. No lo necesitas para usar K3.
Tener Kimi K3 en un terminal y Claude en otro es la forma más rápida de descubrir qué modelo encaja en cada trabajo. CodeAgentSwarm ejecuta los dos a la vez, cada uno en su terminal, con diffs en vivo, notificaciones de escritorio e historial buscable en todos.
Probar CodeAgentSwarm