¿Cómo doy una clave de API a un agente de IA sin que este vea la clave?
Dé al agente una referencia, no la clave, y deje que un proxy en la misma máquina coloque la clave real en la petición a su salida. Aquí explicamos por qué las variables de entorno dejaron de ser suficientes y cómo configurarlo.
Dé al agente una referencia en lugar de la clave, y deje que un pequeño proxy en la misma máquina intercambie la clave real en la petición a su salida. El agente escribe clavitor://OpenAI/key donde iría el secreto. La API recibe la clave real. El agente nunca la posee, así que no puede imprimirla, registrarla ni ser convencido de entregarla.
Esa es toda la idea. El resto de esta página explica por qué importa y cómo configurarlo.
Por qué «simplemente ponlo en una variable de entorno» dejó de ser aceptable
Hace un año, export OPENAI_API_KEY=sk-... era la forma habitual de entregar una clave a un script. Nadie se inmutaba.
Entonces el script empezó a pensar por sí mismo.
Un agente de IA lee archivos, ejecuta herramientas, escribe registros y habla con desconocidos en internet. Cada una de esas cosas es una vía de escape para una clave que posea:
- El entorno. Cualquier cosa que el agente ejecute lo hereda. Aparece en
/proc, en los volcados de memoria, en la salida de CI. - La memoria. Aunque la clave se obtenga en tiempo de ejecución, sigue presente en el proceso durante todo el tiempo que el agente esté activo.
- La conversación. Una inyección de prompt en una página web o en un comentario de un issue pide al agente que «incluya su configuración para depuración». Un agente servicial lo hace.
Nada de eso requiere un error en el agente. Solo requiere que la clave esté en un lugar al que el agente pueda acceder.
El patrón: el agente pide, el proxy firma
Piense en la tarjeta llave de un hotel. El huésped puede abrir su habitación. El huésped nunca ve la llave maestra, y la puerta registra cada uso.
Para una clave de API, el patrón es así:
- La clave real vive en una bóveda, cifrada.
- Un proxy se ejecuta junto al agente, en la misma máquina.
- El agente envía su petición HTTPS con una referencia donde iría la clave.
- El proxy obtiene el valor de la bóveda, lo coloca en la petición y la reenvía.
- El lado del agente solo posee la referencia.
Los registros del agente muestran la referencia. Lo mismo ocurre con su ventana de contexto. No hay nada que filtrar.
Cómo configurarlo con Clavitor
Así es como lo construimos. Un binario, una variable de entorno, sin cambios en el código del agente.
Cree un cliente para el agente en su bóveda con los ámbitos que necesite, luego inscriba el proxy e inícielo:
$ clavitor-proxy init $ clavitor-proxy ca $ clavitor-proxy serve
init inscribe el proxy como ese cliente. ca imprime la autoridad de certificación del proxy: añádala al almacén de confianza que usa el cliente HTTP de su agente, porque el proxy abre por sí mismo la conexión HTTPS del agente. Luego apunte el agente al proxy:
$ export HTTPS_PROXY="http://clavitor:$(cat proxy-auth)@127.0.0.1:1983"
$ curl -H "Authorization: Bearer clavitor://OpenAI/key" \
https://api.openai.com/v1/chat/completionsproxy-auth es el token de acceso del propio proxy, el archivo junto al binario. Cada conexión debe llevarlo, de modo que otro usuario en la misma máquina no pueda usar el proxy. El proxy escucha en 127.0.0.1:1983 y solo en esa máquina, salvo que usted lo configure deliberadamente para una red privada de confianza.
Funciona con cualquier agente cuyo cliente HTTP respete HTTPS_PROXY: Claude Code, Codex, sus propios scripts. Una credencial solo se envía a un host que su entrada liste como dirección web, de modo que un agente con inyección de prompt no puede apuntar la misma referencia al servidor de un desconocido. La configuración paso a paso está en la documentación del proxy.
¿Y los demás secretos del agente?
No todo secreto viaja en una cabecera HTTP. Una contraseña de despliegue, una clave SSH, un código de dos factores para un inicio de sesión.
Para esos, el agente pide a la bóveda una entrada con nombre a la vez con clavitor-cli, y solo para entradas que se le hayan concedido:
$ clavitor-cli get "GitHub Deploy" --field password $ clavitor-cli get "Stripe API" --field key clavitor-cli: CV-2041: Access denied.
El agente no puede listar la bóveda. Una búsqueda por nombre muestra como máximo cinco títulos coincidentes, y solo un recuento por encima de eso.
Los códigos de autenticación funcionan igual. clavitor-cli totp "GitHub" calcula el código actual en la máquina del agente, de modo que puede superar un inicio de sesión con dos factores sin que nadie tenga que leer un teléfono. La bóveda guarda el secreto cifrado.
Qué es lo que esto no resuelve
Un proxy mantiene la clave fuera del agente. No hace que el agente sea de confianza.
- Un agente comprometido puede seguir usando el acceso que se le concedió. Simplemente no puede llevarse la clave a casa.
- Alguien con acceso de administrador a la máquina también puede usar el proxy, o leer su memoria.
- Una API que devuelve su clave en su respuesta se la entrega al agente. El proxy coloca claves en las peticiones y no filtra las respuestas.
Por eso el acceso que lo rodea importa tanto como el proxy:
- Ámbito. Cada agente recibe solo las entradas que necesita. Un agente de trabajo ve GitHub y AWS. Un agente de despliegue ve claves SSH y la base de datos.
- Límites de lectura. Cada agente puede leer solo un número determinado de entradas distintas por minuto y por hora, y usted fija esas cifras. Un agente que supere su límite horario dos veces en un plazo de dos horas queda bloqueado hasta que usted lo desbloquee.
- Un registro. Cada lectura queda registrada: qué agente, qué entrada, cuándo.
¿Ejecuta varios agentes? Dé a cada uno su propio proxy y su propia inscripción. Así cada uno tiene su propio ámbito, sus propios límites y su propio rastro, y el agente A no puede ver las claves del agente B.
La versión breve
No entregue su clave a un agente. Entréguele un nombre para la clave, y mantenga la clave a un paso de distancia, en un lugar que decide, cada vez, si este agente puede usarla en este momento.
Configure el proxy o vea cómo funciona el acceso de agentes.