Si trabajas con modelos de varios proveedores, seguramente tienes un cajón de claves parecido al mío: la de Anthropic para Claude, la de OpenAI de aquel proyecto que ya casi ni recuerdas, la de Gemini que sacaste de AI Studio para probar algo rápido, la de xAI para trastear con Grok y alguna de OpenRouter, todas repartidas entre ficheros .env y variables de entorno de varias máquinas. El problema llega el día que algo falla, que suele ser en el peor momento posible, en producción, en mitad de una demo o justo antes de empezar una clase, y toca abrir cinco consolas distintas para averiguar cuál de todas se ha quedado sin saldo, cuál ha caducado y cuál sigue funcionando como si nada.

Para eso he construido Mecha, un panel local y open source que reúne todas tus claves en un mismo sitio y te dice de un vistazo, con un semáforo, cuál está bien, cuál te va a dar problemas pronto y cuál ya está rota, sin que ninguna salga de tu ordenador salvo para hablar con su propio proveedor. El nombre viene de la mecha que se va consumiendo, que es justo lo que le pasa a una clave con el tiempo que le queda hasta caducar o con el saldo que se va quemando, y también, por qué no decirlo, de los robots gigantes del anime. Puedes probarlo ahora mismo con un solo comando y sin dar ninguna clave, porque trae un modo demo con datos inventados.

Qué es Mecha y qué te enseña

Cada clave aparece como una tarjeta con su proveedor, la etiqueta que le hayas puesto, la clave redactada (solo el principio y los cuatro últimos caracteres, del estilo de sk-ant-api03-Qm7…x2Pa) y una insignia que dice de qué tipo es: API key normal, admin key, clave de gestión o token OAuth. Encima de todo eso va el semáforo, que en verde significa que la clave funciona y no hay nada que vigilar, en ámbar que caduca pronto, que le queda poco saldo o que algo no termina de encajar, en rojo que está rota (inválida, revocada, bloqueada, caducada o sin saldo) y en gris que Mecha no ha podido comprobarla, por ejemplo porque no había red, en cuyo caso te enseña también el último estado que conoce y de cuándo es. Los tokens OAuth de las suscripciones tienen un estado aparte, «solo local», porque Mecha nunca los usa para llamar a ninguna API.

Debajo está la mecha que da nombre al proyecto, una barra que se va consumiendo según el tiempo que le queda a la clave hasta caducar, medida siempre sobre el mismo horizonte de 90 días para que dos claves a las que les queda lo mismo se vean igual aunque las dieras de alta en fechas distintas. Cuando la fecha entra en la zona de aviso, la barra cambia de color, y si no se sabe cuándo caduca, en lugar de inventarse una fecha la deja punteada y lo dice.

Esto último es una de las reglas que más me importaban al diseñarlo: «desconocido» es un estado válido, y cada dato que ves lleva una etiqueta que dice de dónde ha salido, ya sea la API del proveedor, una cabecera de la respuesta, un JWT decodificado en local, un fichero de sesión, un dato que has puesto tú a mano o una estimación. Mecha no se inventa un saldo cuando el proveedor no lo da, y cuando estima algo, te lo dice.

Para dar de alta una clave basta con pegarla: Mecha detecta el proveedor y el tipo por su prefijo, sin conectarse a nada, y antes de guardarla te explica qué va a poder saber de ella, porque no es lo mismo una clave normal de OpenAI que una admin key. Y si prefieres la terminal, todo lo que hace el panel se puede hacer también desde la línea de comandos, con códigos de salida pensados para meterlo en un cron o en un pipeline de CI.

Qué se puede saber de cada proveedor (y qué no)

Lo que más me sorprendió al documentarme para construir Mecha es lo poco que cuentan las APIs sobre el saldo. Comprobar si una clave es válida es fácil y gratis en los cinco proveedores, porque basta con pedir la lista de modelos o un endpoint parecido, pero saber cuánto dinero te queda es otra historia: ni Anthropic, ni OpenAI, ni Google tienen un endpoint para consultarlo, y solo xAI, con una clave de gestión, y OpenRouter te lo dicen directamente. Esta es la foto completa:

Para los proveedores en los que la falta de saldo solo se descubre cuando una petición falla, Mecha tiene una sonda activa opcional que se activa clave a clave: hace la petición más pequeña posible, un único token de salida con el modelo más barato de cada proveedor, y si la cuenta no tiene saldo, el error lo delata. Cuesta tan poco que el precio se mide por miles de sondas, entre 0,00002 y 0,015 dólares por cada mil según el proveedor, no se lanza más de una vez por hora y nunca se reintenta sola, porque una petición de pago que se queda sin respuesta puede haberse cobrado igualmente.

Con la caducidad pasa algo parecido. Anthropic y OpenAI permiten que las claves caduquen, pero solo lo cuentan a través de sus APIs de administración, así que si das de alta una admin key, Mecha la usa para leer la lista de claves de tu organización y rellenar la fecha de caducidad y el estado de las claves normales que tengas guardadas, y en OpenAI también su último uso. Como una admin key puede gestionar las claves de toda la organización, Mecha solo le permite hacer las lecturas concretas que necesita, y cualquier otra petición se bloquea antes de salir de tu máquina. En OpenAI, además, puedes indicar cuánto saldo compraste y en qué fecha, y Mecha calcula lo que te queda restándole lo que dice su API de costes, siempre marcado como estimación.

Con Gemini hay un detalle que conviene conocer: desde el 28 de mayo de 2026, AI Studio solo crea claves del tipo auth key, las que empiezan por AQ., y Google ha anunciado que irá abandonando las standard keys de siempre, las que empiezan por AIza, después de empezar a rechazar las que no tienen restricciones. Por eso Mecha marca en ámbar cualquier clave AIza aunque siga funcionando, para que tengas tiempo de cambiarla antes de que deje de hacerlo.

Por último están los tokens OAuth de las suscripciones, los que usan Claude Code, Codex o Gemini CLI cuando inicias sesión con tu cuenta. Mecha nunca los usa para llamar a ninguna API, entre otras cosas porque Anthropic no permite que herramientas de terceros enruten peticiones con las credenciales de los planes Free, Pro o Max, pero sí puede leer en local los ficheros de sesión de esas herramientas para enseñarte lo que cuentan, como tu plan, hasta cuándo está activa la suscripción o cuándo caduca la sesión, sin copiar nunca los tokens a su base de datos. En macOS, Claude Code guarda sus credenciales en el Llavero, y esa parte se ha quedado fuera de esta primera versión.

Seguridad: tus claves no salen de tu máquina

Un programa que guarda las claves de todos tus proveedores es un objetivo muy goloso, así que buena parte del trabajo ha ido aquí. Mecha corre solo en tu ordenador y escucha únicamente en 127.0.0.1; cada vez que arranca genera un token de sesión sin el cual la API local no responde a nada, rechaza cualquier petición que llegue con otro nombre de host para que una web maliciosa no pueda colarse con trucos de DNS rebinding, y sirve la interfaz con una política de seguridad de contenidos estricta. Las claves se guardan cifradas con AES-256-GCM, con la clave maestra en el llavero del sistema o protegida con una frase de paso, y una vez que das de alta un secreto el navegador no lo vuelve a ver nunca, porque solo recibe la forma redactada y una huella.

Además, cada tipo de clave tiene una lista cerrada de peticiones permitidas, con su método, su host y su ruta, de modo que una clave solo puede llegar al endpoint oficial de su propio proveedor y una admin key solo puede hacer las lecturas que Mecha necesita. Las copias de seguridad también van cifradas, con una frase de paso propia de al menos doce caracteres, porque lo normal es que ese fichero acabe en alguna carpeta sincronizada con la nube.

También he querido ser claro con lo que no protege, y está explicado en el README. Mecha protege tus secretos en reposo, es decir, en el disco, en las copias de seguridad, en la sincronización con la nube y en un portátil que se pierde apagado, y también frente a otras webs abiertas en tu navegador y a otros usuarios del mismo ordenador, pero no puede hacer nada frente a código que ya se está ejecutando con tu usuario, porque ese código podría leer tus claves exactamente igual que lee tus ficheros .env.

Cómo lo he construido con Claude Code

Mecha lo he desarrollado con Claude Code siguiendo el mismo método que cuento en mi libro Del vibe coding al Spec-Driven Development: antes de escribir una línea de código redacté una especificación completa, con el modelo de estados y lo que expone cada proveedor contrastado con su documentación oficial, marcando como «verificar» todo lo que no estaba claro, y a partir de ahí Claude Code la fue implementando en seis fases, cada una en su propia rama y su propio pull request, con sus criterios de aceptación y un CI que la prueba en Linux, macOS y Windows. Yo revisaba el plan de cada fase antes de que empezara y cada PR antes de mergearlo, y es en esas revisiones donde aparecieron las cosas más interesantes.

La primera fue un problema que habría filtrado tus claves sin que nadie se diera cuenta. Cuando una petición no pasa la validación, FastAPI devuelve por defecto un error 422 que incluye el dato que ha fallado y, si lo que falta es un campo obligatorio, el cuerpo entero de la petición, así que un alta mal formada habría devuelto la clave en la respuesta y la interfaz podría haber acabado mostrándola en un aviso. Lo cambiamos por un error que nunca repite lo que recibe, y los tests que buscan una clave «canario» en todas las salidas de la aplicación, desde las respuestas de la API hasta los logs y la propia base de datos, lanzan también peticiones mal formadas a propósito.

La segunda tiene que ver con el navegador, y es fácil que te afecte también en tus propias aplicaciones: los correctores ortográficos mejorados de Chrome y de Edge pueden enviar a sus servidores el texto que escribes en los campos de un formulario, así que el campo donde pegas la clave tiene desactivados la corrección ortográfica y el autocompletado.

La tercera era un fallo de diseño de los que solo ves cuando piensas en el uso real. La comprobación gratuita no sabe nada del saldo, así que, tal como estaba planteado, cada vez que el planificador la lanzaba habría borrado el «sin saldo» que había detectado antes la sonda activa, y una tarjeta en rojo habría vuelto a verde al cabo de unas horas sin que hubieras recargado nada. La solución fue guardar lo que descubre cada comprobación como un dato de la credencial, con su fecha y su fuente, de forma que solo una prueba más reciente pueda cambiarlo.

El resultado es la versión 0.1.0, con más de 400 tests, pruebas de extremo a extremo con Playwright sobre el modo demo y una publicación en PyPI que se hace desde GitHub Actions con Trusted Publishing, sin tokens guardados en ningún sitio y con attestations que puedes verificar tú mismo.

Cómo probarlo

La forma más rápida de verlo es el modo demo, que arranca el panel con una veintena de claves inventadas en todos los estados posibles, sin red y sin tocar nada tuyo. Solo necesitas tener uv instalado:

uvx mecha-keys serve --demo

Cuando quieras usarlo con tus claves de verdad, instálalo como herramienta y lanza el panel, que se abre en tu navegador en 127.0.0.1:7878 y, mientras el servidor esté en marcha, vuelve a comprobar todas las claves cada seis horas:

uv tool install mecha-keys
mecha serve

Desde la terminal tienes los mismos datos. mecha add te pide la clave sin mostrarla en pantalla (Mecha nunca acepta una clave como argumento, para que no acabe en el historial de tu shell), mecha ls te enseña la tabla con el semáforo y mecha check comprueba todas las claves y sale con un código que sigue la convención de Nagios, así que meterlo en un cron o en un pipeline que te avise es cuestión de una línea; en un servidor sin llavero del sistema, la frase de paso del almacén se lee de un fichero con permisos 0600.

mecha add          # pega la clave; no se muestra
mecha check        # 0 todo bien, 1 algún ámbar, 2 algún rojo, 3 si algo ha fallado

Y si ya tienes tus claves en un .env, mecha import .env te enseña las que detecta, ya redactadas, para que elijas cuáles importar, mientras que mecha link codex vincula la sesión de Codex CLI en modo de solo lectura para que veas tu plan y hasta cuándo tienes la suscripción.

Una alfa abierta a contribuciones

Mecha está en versión alfa, es open source con licencia MIT y tienes todo el código en github.com/JoaquinRuiz/mecha. Si lo pruebas y algo no cuadra con lo que ves en la consola de tu proveedor, me ayudarías mucho abriendo un issue, porque varios mensajes de error y algunos formatos de los ficheros de sesión no están documentados oficialmente y la única forma de afinarlos es con casos reales; y si quieres añadir un proveedor nuevo, cada uno es un módulo independiente con sus propias pruebas, así que no hace falta tocar el núcleo. Si te resulta útil, una estrella en el repositorio me ayuda a que llegue a más gente, y si te interesan este tipo de herramientas que funcionan en local, echa también un vistazo a SpecJudge, que te recomienda qué modelo usar según las tareas de tu spec.

¡Que la IA te acompañe!