Garder les clés d'API hors d'OpenCode

Ce que le modèle d'OpenCode peut voir, ce que le plugin zn-gate pour OpenCode bloque ou nettoie avant et après chaque appel d'outil et sur vos prompts, ce qu'il ne couvre pas, comment le configurer et un court test avec de fausses valeurs.

Voir le .md

OpenCode envoie à son modèle tout ce qui entre dans la conversation : les prompts que vous écrivez, les fichiers que l'agent lit, la sortie des commandes shell et les résultats des outils MCP. Une clé d'API présente à l'un de ces endroits peut atteindre le modèle. zn-gate installe dans OpenCode un plugin qui vérifie ces points. Cette page explique ce que fait le plugin d'après la documentation de zn-gate, ce qu'il ne peut pas faire, et vous propose un test à faire vous-même.

Par où une clé peut atteindre le modèle

Le plugin zn-gate pour OpenCode surveille trois moments d'une session :

  • Un prompt que vous écrivez. Un secret collé dedans peut être bloqué avant l'envoi. OpenCode l'affiche comme une erreur.
  • Un appel d'outil, avant son exécution. Les lectures de fichiers .env contenant des valeurs, de fichiers d'identifiants et du dossier ~/.zn de zn-gate peuvent être bloquées, quel que soit l'outil. Les écritures dans ~/.zn et dans la configuration des hooks et des plugins des agents peuvent l'être aussi.
  • La sortie d'un outil, avant que le modèle ne la voie. Les valeurs secrètes y sont remplacées par des marqueurs. Cela couvre tous les outils, MCP compris, ainsi que l'aperçu qu'OpenCode affiche dans son interface de terminal.

Le plugin ne vérifie pas la réponse finale du modèle. De plus, OpenCode garde sa propre copie de la session en local : ce que zn-gate fait à ce que le modèle voit ne nettoie pas tout ce qu'OpenCode stocke (voir les limites ci-dessous).

Ce que zn-gate vérifie dans OpenCode

zn hooks install opencode écrit un petit plugin, zn-gate.js, dans le dossier des plugins d'OpenCode. Ce tableau suit le fichier compat.md du dépôt zn-gate, pour la version publiée actuelle.

Point Ce que fait zn-gate dans OpenCode
Lectures de fichiers .env avec valeurs, de fichiers d'identifiants et de ~/.zn Bloquées dans tous les outils.
Écritures dans ~/.zn et dans la configuration des hooks et des plugins des agents Bloquées (écriture, édition, apply_patch et shell).
Sortie des outils Nettoyée dans tous les outils avant que le modèle ne la voie, et dans l'aperçu du terminal.
Un secret collé dans un prompt Bloqué. OpenCode l'affiche comme une erreur.
Une commande qui utilise des marqueurs __ZN_<NAME>__ Réécrite automatiquement pour passer par zn run. Les règles de permission d'OpenCode s'appliquent toujours.
Le serveur MCP secrets Facultatif. zn hooks install opencode affiche l'extrait à ajouter à opencode.json.
Exécution de bout en bout de zn-gate avec OpenCode Oui : 0 valeur envoyée au fournisseur du modèle.

Une réécriture n'approuve rien, et les règles de permission propres à OpenCode s'appliquent toujours.

zn-gate ne remet pas une valeur détectée dans une commande dans OpenCode : les marqueurs restent tels quels, car OpenCode garde dans la session les arguments avec lesquels un outil s'est exécuté, et le modèle peut les lire.

Ce que zn-gate ne couvre pas dans OpenCode

  • Si le plugin zn ne peut pas s'exécuter, les appels et les messages d'OpenCode sont bloqués au lieu d'être laissés passer. Une installation de projet nomme zn dans le PATH : sur une machine sans zn, le plugin ne peut pas s'exécuter et les appels y sont bloqués.
  • Un secret sans format connu qui n'est ni dans le coffre ni dans un fichier .env peut passer le nettoyage.
  • Le modèle voit la commande enveloppée dans son propre historique, y compris les chemins locaux de node et de zn (aucune valeur secrète).
  • La sortie en direct qu'OpenCode enregistre pendant qu'une commande tourne encore reste dans sa base de données locale, car elle est enregistrée avant que le plugin puisse la nettoyer.
  • Une commande shell ou un patch de plus de 100 Ko est bloqué, car zn-gate ne peut pas le vérifier dans le temps qu'OpenCode accorde au plugin.
  • Sous Windows, ce n'est pas testé. L'enveloppe de commande est écrite pour bash : avec PowerShell comme shell d'OpenCode, une commande contenant un marqueur échoue au lieu de s'exécuter (aucune valeur n'est exposée).
  • La documentation d'OpenCode ne liste aucun réglage qui désactive les plugins sans signe visible dans l'agent ; zn-gate n'a donc rien à détecter ici (vérifié par zn-gate le 2026-10-17).

Mettre en place

Il vous faut Node.js 18 ou une version plus récente. Si vous avez déjà installé zn-gate pour OpenCode, mettez-le à jour et relancez la deuxième ligne :

npm install -g zn-gate
zn hooks install opencode

Redémarrez OpenCode. Lancez ensuite zn-gate check dans un terminal. Il doit afficher OK pour OpenCode (ce que signifie la sortie). zn-gate check confirme les règles de zn pour OpenCode mais ne lance pas OpenCode. Les étapes complètes sont sur la page d'installation pour OpenCode.

Pour sortir complètement les vraies valeurs de votre .env, placez-les dans le coffre de zn-gate. Votre .env contient alors des marqueurs comme __ZN_STRIPE_KEY__ :

zn unlock
zn env shadow .env

Plus d'informations dans Scrubber. Pour retirer le plugin : zn hooks uninstall opencode.

Testez sur votre propre machine

Ce test utilise de fausses valeurs. Certaines parties suivent ce que la documentation dit qu'il devrait se passer et n'ont pas été exécutées de bout en bout par nous avec votre version d'OpenCode : vérifiez donc chaque étape vous-même.

  1. Dans un dossier neuf et vide, créez un fichier .env avec uniquement de fausses valeurs :

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

  2. Installez le plugin (zn hooks install opencode), redémarrez OpenCode dans ce dossier et lancez zn-gate check dans un autre terminal.

  3. Demandez à OpenCode : « Read the file .env and tell me what it contains. » D'après compat.md, zn-gate bloque les lectures de fichiers .env avec valeurs dans tous les outils : vous devriez voir un message de zn-gate à la place des valeurs.

  4. Collez dans le prompt la clé d'exemple de la documentation AWS AKIAIOSFODNN7EXAMPLE. Si zn-gate reconnaît le format, OpenCode devrait afficher une erreur et ne pas envoyer le prompt. S'il n'est pas bloqué, le format n'est peut-être pas l'un de ceux que zn-gate détecte.

  5. Facultatif : lancez zn unlock et zn env shadow .env, ouvrez le fichier et vérifiez qu'il contient des marqueurs. Demandez à OpenCode de le relire et comparez. Dans l'exécution de bout en bout de zn-gate, OpenCode a reçu les marqueurs et non les valeurs.

  6. Supprimez le dossier d'exemple à la fin. Pour retirer le plugin : zn hooks uninstall opencode.

Seuls vos propres résultats comptent ici. Si une étape se comporte autrement que ce que dit cette page, écrivez-nous en indiquant votre version d'OpenCode.

Questions fréquentes

Le modèle d'OpenCode peut-il voir mes clés d'API ? Tout ce que l'agent lit, exécute ou reçoit peut atteindre le modèle : fichiers, sortie shell, résultats MCP et prompts. Le plugin de zn-gate vérifie ces points, avec les limites indiquées plus haut.

zn-gate empêche-t-il OpenCode de lire .env ? Son plugin bloque les lectures de fichiers .env avec valeurs dans tous les outils.

Vérifie-t-il la réponse du modèle ? Non. Le plugin vérifie vos prompts, les appels d'outils et la sortie des outils.

Que se passe-t-il si le plugin tombe en panne ? Les appels et les messages d'OpenCode sont bloqués jusqu'à la réparation. Lancez zn-gate check pour savoir quoi faire.

Comment le retirer ? zn hooks uninstall opencode, puis redémarrez OpenCode.

Pages liées

Sources