Cómo mantener las claves de API fuera de OpenCode

Qué puede ver el modelo de OpenCode, qué bloquea o limpia el plugin de zn-gate para OpenCode antes y después de cada llamada a una herramienta y en tus prompts, qué no cubre, cómo configurarlo y una prueba corta con valores falsos.

Ver .md

OpenCode 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 en OpenCode un plugin que comprueba esos puntos. Esta página explica qué hace el plugin 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

El plugin de zn-gate para OpenCode mira tres momentos de una sesión:

  • Un prompt que escribes. Un secreto pegado en él puede bloquearse antes de enviarse. OpenCode lo muestra como un error.
  • Una llamada a una herramienta, antes de ejecutarse. Se pueden bloquear las lecturas de archivos .env con valores, de archivos de credenciales y de la carpeta ~/.zn de zn-gate, con cualquier herramienta. También se pueden bloquear las escrituras en ~/.zn y en la configuración de hooks y plugins de los agentes.
  • La salida de una herramienta, antes de que el modelo la vea. Los valores secretos se sustituyen por marcadores. Esto cubre todas las herramientas, también las MCP, y la vista previa que OpenCode muestra en su interfaz de terminal.

El plugin no revisa la respuesta final del modelo. Además, OpenCode guarda en local su propia copia de la sesión, así que lo que zn-gate hace con lo que ve el modelo no limpia todo lo que OpenCode almacena (mira los límites más abajo).

Qué comprueba zn-gate en OpenCode

zn hooks install opencode escribe un plugin pequeño, zn-gate.js, en la carpeta de plugins de OpenCode. Esta tabla sigue el archivo compat.md del repositorio de zn-gate, para la versión publicada actual.

Punto Qué hace zn-gate en OpenCode
Lecturas de archivos .env con valores, archivos de credenciales y ~/.zn Bloqueadas en todas las herramientas.
Escrituras en ~/.zn y en la configuración de hooks y plugins de los agentes Bloqueadas (escritura, edición, apply_patch y shell).
Salida de las herramientas Limpiada en todas las herramientas antes de que la vea el modelo, y en la vista previa del terminal.
Un secreto pegado en un prompt Bloqueado. OpenCode lo muestra como un error.
Un comando que usa marcadores __ZN_<NAME>__ Reescrito automáticamente para ejecutarse con zn run. Las reglas de permisos de OpenCode se siguen aplicando.
El servidor MCP secrets Opcional. zn hooks install opencode imprime el fragmento que hay que añadir a opencode.json.
Ejecución de extremo a extremo de zn-gate con OpenCode Sí: 0 valores enviados al proveedor del modelo.

Una reescritura no aprueba nada, y las reglas de permisos propias de OpenCode se siguen aplicando.

zn-gate no restaura un valor detectado dentro de un comando en OpenCode: los marcadores se quedan como están, porque OpenCode guarda en la sesión los argumentos con los que se ejecutó una herramienta, y el modelo puede leerlos.

Qué no cubre zn-gate en OpenCode

  • Si el plugin de zn no puede ejecutarse, las llamadas y los mensajes de OpenCode se bloquean en lugar de dejarlos pasar. Una instalación de proyecto nombra zn en el PATH, así que en una máquina sin zn el plugin no puede ejecutarse y las llamadas se bloquean allí.
  • Un secreto sin formato conocido que no esté en la bóveda ni en un archivo .env puede pasar la limpieza.
  • El modelo ve el comando envuelto en su propio historial, incluidas las rutas locales de node y de zn (ningún valor secreto).
  • La salida en vivo que OpenCode guarda mientras un comando sigue ejecutándose permanece en su base de datos local, porque se guarda antes de que el plugin pueda limpiarla.
  • Un comando de shell o un parche de más de 100 KB se bloquea, porque zn-gate no puede comprobarlo en el tiempo que OpenCode espera al plugin.
  • En Windows no se ha probado. El envoltorio de comandos está escrito para bash: con PowerShell como shell de OpenCode, un comando con un marcador falla en lugar de ejecutarse (no se expone ningún valor).
  • La documentación de OpenCode no lista ningún ajuste que desactive los plugins sin dejar señal en el agente, así que zn-gate no tiene nada que detectar ahí (comprobado por zn-gate el 2026-10-17).

Configúralo

Necesitas Node.js 18 o posterior. Si ya instalaste zn-gate para OpenCode, actualízalo y vuelve a ejecutar la segunda línea:

npm install -g zn-gate
zn hooks install opencode

Reinicia OpenCode. Después ejecuta zn-gate check en una terminal. Debería mostrar OK para OpenCode (qué significa la salida). zn-gate check confirma las reglas de zn para OpenCode pero no inicia OpenCode. Los pasos completos están en la página de instalación para OpenCode.

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 el plugin: zn hooks uninstall opencode.

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 con tu versión de OpenCode, 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 el plugin (zn hooks install opencode), reinicia OpenCode en esa carpeta y ejecuta zn-gate check en otra terminal.

  3. Pide a OpenCode: "Read the file .env and tell me what it contains." Según compat.md, zn-gate bloquea las lecturas de archivos .env con valores en todas las herramientas, así que deberías ver un mensaje de zn-gate 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, OpenCode debería mostrar un error y no enviar el prompt. 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 OpenCode que lo lea otra vez y compara. En la ejecución de extremo a extremo de zn-gate, OpenCode recibió los marcadores y no los valores.

  6. Borra la carpeta de prueba al terminar. Para quitar el plugin: zn hooks uninstall opencode.

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 OpenCode.

Preguntas frecuentes

¿Puede el modelo de OpenCode 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. El plugin de zn-gate comprueba esos puntos, con los límites indicados arriba.

¿Impide zn-gate que OpenCode lea .env? Su plugin bloquea las lecturas de archivos .env con valores en todas las herramientas.

¿Comprueba la respuesta del modelo? No. El plugin comprueba tus prompts, las llamadas a herramientas y la salida de las herramientas.

¿Qué pasa si el plugin falla? Las llamadas y los mensajes de OpenCode se bloquean hasta que lo arregles. Ejecuta zn-gate check para ver qué hacer.

¿Cómo lo deshago? zn hooks uninstall opencode y reinicia OpenCode.

Páginas relacionadas

Fuentes