He pegado una clave de API en mi agente de código. ¿Y ahora qué?

Rota o revoca primero la clave, después ocúpate de las copias en el historial de tu agente y por último configura zn-gate para que la próxima se bloquee o se sustituya por un marcador antes de que el modelo la vea.

Ver .md

Has escrito o pegado una clave de API en el chat de un agente de código, o el agente la ha leído de un archivo. La clave está ahora en la conversación que se envió al modelo, y probablemente en el historial del agente en tu disco. Esta página da los pasos en el orden que importa: rotar la clave, limpiar las copias y evitar que vuelva a pasar.

1. Rota o revoca primero la clave

Haz esto antes que nada. Borrar un chat o un archivo de historial no deshace una copia que ya se envió a un proveedor de modelos o que quedó en una copia de seguridad. Solo revocar la clave inutiliza el valor filtrado.

  1. Abre la consola del servicio que emitió la clave. Busca la clave en su lista de claves de API, tokens o claves de acceso.
  2. Crea una clave nueva si algo depende de la antigua. Si un servicio en producción usa la clave y no puedes permitirte una caída, crea primero la sustituta, cambia tu aplicación para que la use, actualiza todos los demás sitios donde se usa la clave (secretos de CI, ajustes de despliegue, compañeros de equipo) y después revoca la antigua. AWS, GitHub y Google Cloud describen este orden en sus propias páginas. Si nada depende de la clave, revócala de inmediato.
  3. Revoca o elimina la clave antigua. No la dejes activa "por ahora".
  4. Dale a la clave nueva los permisos mínimos que necesite.
  5. Guarda la clave nueva donde el agente no la lea. No en el chat ni en un archivo .env normal que el agente pueda abrir. Mira el paso 3 más abajo.
  6. Revisa el registro de uso o de acceso del proveedor para la clave antigua. Si ves peticiones que no reconoces, trata la cuenta como comprometida y sigue las indicaciones del proveedor.

Dónde revocar, según la documentación de cada proveedor:

Proveedor Qué dice su documentación
AWS Updating IAM user access keys: crea una segunda clave, cambia tus aplicaciones para que la usen, desactiva la primera y elimínala cuando nada la necesite.
GitHub Remediating a leaked secret: una guía paso a paso que incluye revocar el secreto, encontrar los servicios que lo usan y comprobar accesos no autorizados. Los tokens se gestionan en Managing your personal access tokens.
Google Cloud API keys: la página explica cómo rotar una clave, lo que crea una clave nueva con las mismas restricciones, y cómo eliminar la antigua cuando tus aplicaciones ya usan la nueva.
Stripe API keys: cómo renovar (roll) una clave y cuándo caduca la antigua.
Anthropic API key best practices: si sospechas que una clave está comprometida, revócala desde la página de claves de API de la Claude Console con "Delete API key".

Para un servicio que no aparece aquí, abre su propia documentación y busca cómo revocar, rotar o renovar una clave. Solo enlazamos páginas que pudimos abrir y leer.

2. Limpia las copias que quedan en tu equipo

Claude Code, Codex CLI, Cursor y OpenCode guardan un historial de tus conversaciones, y una clave que escribiste o que pasó por una herramienta puede estar en él. Claude Code guarda además cada prompt que escribes en un archivo de historial de prompts aparte. Cada agente guarda su historial en un sitio distinto y tiene controles distintos, y en algunos la documentación no dice nada sobre la ruta local ni la retención.

Lo tenemos en una sola guía para que se mantenga correcto en un único sitio: ¿Guardan los agentes de código tus claves de API en sus transcripciones? Indica dónde guarda su historial cada uno de los cuatro agentes según la documentación de su fabricante, cuánto tiempo lo conserva, qué dice cada fabricante sobre las subidas, cómo encontrar los archivos que contienen una clave y borrarlos, y las copias que es fácil olvidar, como las copias de seguridad y la sincronización en la nube de tu carpeta personal.

Hazlo después del paso 1, no en su lugar.

3. Evita la próxima con zn-gate

zn-gate es una capa local entre tu agente de código y sus herramientas. Funciona en tu equipo, sin cuenta. Su Scrubber de secretos está disponible desde zn-gate 1.5.0 (en Windows, desde la 1.5.1) y funciona con Claude Code, Codex CLI, Cursor (IDE) y OpenCode. Lo que puede modificar depende de cada agente.

Qué hace con una clave que estás a punto de pegar

Según la página Scrubber y bóveda de secretos:

  • Los prompts pegados, las lecturas de archivos, la salida de comandos, las búsquedas y los resultados de herramientas MCP pasan por el Scrubber antes de llegar al modelo. Los valores que conoce (de la bóveda y de tus archivos .env) y más de 60 formatos de secretos se convierten en marcadores estables como __ZN_AWS_KEY_1__, de modo que, donde el agente deja que zn-gate los reescriba, el modelo recibe el marcador en lugar del valor (mira los límites más abajo).
  • Los hooks bloquean la lectura de archivos .env que contienen valores reales y de archivos de credenciales como ~/.aws/credentials o ~/.ssh/id_*. La documentación lo describe como una barrera de protección, no como un sandbox.
  • Los valores reales viven en una bóveda cifrada en tu equipo. El agente trabaja con marcadores y un valor solo se rellena donde tú lo permitiste.

Un secreto pegado en un prompt se bloquea en los cuatro agentes, así que el prompt no llega al modelo. El bloqueo no borra lo que escribiste de tu propio equipo: el agente puede guardar el prompt en local (Claude Code lo guarda en texto claro en su transcripción). Los marcadores solo aparecen en la salida de herramientas que zn-gate limpió.

Los tokens que están en el env o los headers de un servidor MCP son otro caso: Tokens en texto plano en tu configuración MCP: cómo sacarlos explica cómo sacarlos del archivo de configuración.

Configúralo

Necesitas Node.js 18 o posterior. Ejecuta esto en tu propia terminal:

npx -y zn-gate init
npx -y zn-gate unlock
npx -y zn-gate env shadow .env
npx -y zn-gate check
  • init encuentra los cuatro agentes en tu equipo, muestra la configuración de cada uno que aún no está protegido y ejecuta cada paso después de que lo confirmes.
  • unlock crea la bóveda la primera vez. Con el llavero del sistema necesita una terminal interactiva.
  • env shadow .env mueve los valores de tu archivo .env a la bóveda. El archivo conserva marcadores como __ZN_STRIPE_KEY__.
  • check prueba con un secreto falso en una carpeta temporal y te dice qué agente no está protegido. No se envía nada a ningún sitio. Qué significa la salida.

Para añadir un solo secreto sin pegarlo en un chat ni ponerlo en una línea de comandos, escríbelo en un aviso oculto: zn secret set GITHUB_TOKEN --host api.github.com. La documentación indica que nunca se pase un secreto como argumento.

Para probarlo con un valor falso, abre tu agente en una carpeta vacía y pega en el prompt la clave de ejemplo de la documentación de AWS AKIAIOSFODNN7EXAMPLE. Si zn-gate reconoce el formato, el prompt se bloquea. Si no se bloquea, puede que ese formato no sea uno de los que zn-gate detecta, y esta prueba no dice nada sobre tus claves reales.

Lo que zn-gate no hace

Estos límites proceden de la página Scrubber y bóveda de secretos y del modelo de amenazas de zn-gate.

  • No limpia las transcripciones escritas antes de instalarlo. La clave que pegaste hoy sigue en ellas hasta que las borres (paso 2).
  • No revoca nada y no controla lo que un fabricante de agentes guarda en sus servidores. La rotación es siempre el paso 1.
  • El Scrubber encuentra valores conocidos y formatos reconocibles. Un secreto sin formato conocido que no esté en la bóveda ni en un archivo .env puede pasar.
  • En Cursor solo se puede reescribir la salida de herramientas MCP. La salida de shell y el contenido de los archivos no se depuran allí.
  • Algunos agentes guardan sus propias copias locales. El registro de sesión de Codex conserva la salida original.
  • En Claude Code, un prompt que zn-gate bloqueó permanece en la transcripción en texto claro, como dice la propia documentación de Claude Code.

Preguntas frecuentes

¿Tengo que rotar la clave si borré la conversación? Sí. Borrar archivos locales no elimina una copia que se envió al proveedor del modelo o que quedó en una copia de seguridad. Revoca primero la clave.

¿Puedo borrar la transcripción y quedarme con la clave? No es seguro. La clave se envió al modelo como parte de la conversación, así que considérala expuesta.

¿zn-gate elimina una clave que ya está en mi historial? No. Actúa sobre los prompts y la salida de herramientas nuevos. Los archivos de historial existentes se quedan como están.

¿zn-gate me impedirá pegar una clave? Bloquea un secreto pegado en un prompt cuando reconoce el formato, en Claude Code, Codex CLI, Cursor y OpenCode. Un secreto con un formato que no conoce puede pasar, así que mantén las claves fuera de los chats de todos modos.

¿Cómo quito los hooks de zn-gate? zn hooks uninstall <agente>, por ejemplo zn hooks uninstall codex.

Páginas relacionadas

Fuentes