Cómo mantener las claves de API fuera de Codex CLI

Qué puede ver el modelo de Codex CLI, qué comprueban los hooks de zn-gate en Codex antes y después de cada paso y en tus prompts, qué no pueden hacer, cómo configurarlos y una prueba corta con valores falsos.

Ver .md

Codex CLI envía a su modelo todo lo que entra en la conversación: los prompts que escribes, los archivos que lee el agente, la salida de los comandos de shell y los resultados de las herramientas MCP. Una clave de API en cualquiera de esos puntos puede llegar al modelo. zn-gate instala hooks en Codex que comprueban esos puntos. Esta página explica qué hace cada hook según la documentación de zn-gate, qué no puede hacer, y te da una prueba para hacer tú mismo.

Por dónde puede llegar una clave al modelo

Los hooks de zn-gate para Codex miran cuatro puntos de una sesión:

  • Un prompt que escribes. Un secreto pegado en él puede bloquearse antes de enviarse.
  • Un comando de shell o un parche (apply_patch). Se pueden bloquear las lecturas de archivos .env con valores y de archivos de credenciales.
  • La salida de una herramienta. Se puede limpiar antes de que el modelo la vea.

El registro de sesión del propio Codex conserva la salida original, haga lo que haga zn-gate con lo que ve el modelo.

Qué comprueba zn-gate en Codex

zn hooks install codex escribe el hooks.json de Codex. Esta tabla sigue el archivo compat.md del repositorio de zn-gate, que lista cada evento de hook de Codex y si se ha probado con un Codex real.

Evento de hook Qué hace zn-gate
PreToolUse Comprueba los comandos de shell y los parches (Bash, apply_patch) antes de que se ejecuten, y deniega la llamada con un motivo cuando encuentra un secreto, un archivo de credenciales o ~/.zn. No comprueba las llamadas a herramientas MCP. Comprobado con Codex CLI 0.163.0.
PostToolUse Limpia la salida de la herramienta: el resultado se sustituye por su texto limpio. Comprobado con Codex CLI 0.163.0.

Un tercer evento, UserPromptSubmit, bloquea un secreto pegado en un prompt (comprobado con Codex CLI 0.163.0).

En PreToolUse, zn-gate no responde allow, así que tu propia política de aprobación de Codex sigue aplicándose.

Qué no cubre zn-gate en Codex

  • Codex describe sus hooks como "a guardrail, not an enforcement boundary" (una protección, no un límite de obligado cumplimiento). Si el hook de zn no puede ejecutarse, Codex lo registra como fallido y la llamada o el prompt siguen adelante.
  • La limpieza tiene pérdidas. Codex no tiene ningún campo que reescriba el resultado de una herramienta, así que el resultado se sustituye por el texto limpio de zn-gate y el modelo recibe texto en lugar del resultado estructurado.
  • El registro de sesión del propio Codex conserva la salida original.
  • Un secreto sin formato conocido que no esté en la bóveda ni en un archivo .env puede pasar la limpieza.
  • Un servidor definido en la línea de comandos de Codex con -c mcp_servers.secrets..., o en un perfil, no es visible para el hook.
  • La comprobación PreToolUse de zn-gate cubre comandos de shell y parches, no las llamadas a herramientas MCP, y zn-gate no usa los demás eventos de hook de Codex.
  • En Windows, el comando del hook se ejecutó a mano desde PowerShell y desde el Símbolo del sistema, no en las pruebas automáticas.

Configúralo

Necesitas Node.js 18 o posterior:

npm install -g zn-gate
zn hooks install codex

Abre Codex y revisa los hooks nuevos o modificados con /hooks. Codex ejecuta los hooks nuevos solo después de que confíes en ellos ahí. Después ejecuta zn-gate check en una terminal. Debería mostrar OK para Codex CLI (qué significa la salida). Los pasos completos están en la página de instalación para Codex CLI.

Para sacar por completo los valores reales de tu .env, guárdalos en la bóveda de zn-gate. Tu .env pasa a contener marcadores como __ZN_STRIPE_KEY__:

zn unlock
zn env shadow .env

Más en Scrubber. Para deshacer los hooks: zn hooks uninstall codex.

Pruébalo en tu propia máquina

Esta prueba usa valores falsos. Partes de ella siguen lo que dice la documentación que debería ocurrir y no las hemos ejecutado de principio a fin en Codex, así que comprueba cada paso tú mismo.

  1. En una carpeta nueva y vacía, crea un archivo .env solo con valores falsos:

    EXAMPLE_API_KEY=sk-test-EXAMPLE-not-a-real-key
EXAMPLE_URL=https://example.com

  2. Instala los hooks (zn hooks install codex), abre Codex en esa carpeta, confía en los hooks con /hooks y ejecuta zn-gate check en otra terminal.

  3. Pide a Codex: "Run cat .env and tell me what it prints." Según compat.md, el hook PreToolUse de zn-gate bloqueó cat .env con Codex CLI 0.163.0, y deberías ver un mensaje del hook en lugar de los valores.

  4. Pega en el prompt la clave de ejemplo de la documentación de AWS AKIAIOSFODNN7EXAMPLE. Si zn-gate reconoce el formato, el prompt debería bloquearse. Si no se bloquea, puede que el formato no sea uno de los que zn-gate detecta.

  5. Opcional: ejecuta zn unlock y zn env shadow .env, abre el archivo y comprueba que contiene marcadores. Pide a Codex que lo lea otra vez y compara.

  6. Borra la carpeta de prueba al terminar. Para quitar los hooks: zn hooks uninstall codex.

Aquí solo cuentan tus propios resultados. Si algún paso se comporta distinto de lo que dice esta página, escríbenos e incluye tu versión de Codex CLI.

Preguntas frecuentes

¿Puede el modelo de Codex ver mis claves de API? Todo lo que el agente lee, ejecuta o recibe puede llegar al modelo: archivos, salida de shell, resultados MCP y prompts. Los hooks de zn-gate comprueban esos puntos, con los límites indicados arriba.

¿Impide zn-gate que Codex lea .env? Sus hooks bloquean las lecturas de archivos .env con valores en comandos de shell y parches. Codex llama a los hooks una protección, no un límite de obligado cumplimiento.

¿Por qué la salida limpia es texto plano? Codex no tiene ningún campo que reescriba el resultado de una herramienta, así que zn-gate sustituye el resultado entero por su texto limpio.

¿Cómo lo deshago? zn hooks uninstall codex.

Páginas relacionadas

Fuentes