OpenCode et le PATH incomplet : pourquoi vos outils n'étaient pas dans le shell de l'agent

C’était un mardi soir. Je venais d’installer OpenCode, l’agent IA qui promettait de transformer ma façon de coder. Premier test : lui demander de lister mes dépôts GitHub.

Étrange. gh fonctionnait parfaitement dans mon terminal. J’essaie autre chose :

Puis :

Java, Gradle, Node, gh — tout était invisible pour l’agent. Mon terminal, lui, voyait tout. Comme si l’agent et moi vivions dans deux mondes parallèles.

J’ai mis des heures à comprendre. Des heures de echo $PATH, de which java, de frustration croissante. J’ai fini par comprendre que le problème n’était pas les outils — c’était le shell. OpenCode, comme tout agent qui lance des sous-processus, travaille dans des shells non-interactifs. Et Zsh, dans ces shells-là, ignore purement et simplement votre .zshrc.

Ce qui suit est le récit complet de ce diagnostic, de la résolution, et de la leçon que j’ai tirée. Si vous utilisez un agent IA — OpenCode, Aider, Cursor, ou même des scripts cron — ce problème vous concernera un jour.

Quand vous ouvrez un terminal, Zsh le traite comme un shell interactif. Il charge .zshrc, qui initialise tout : SDKMAN, NVM, pnpm, les aliases, votre joli prompt. Votre environnement est complet.

Mais quand OpenCode exécute une commande, il ne lance pas un terminal interactif. Il lance un shell non-interactif — un shell de tâche, sans humain derrière l’écran. Et Zsh, dans ce contexte, saute .zshrc. Il ne lit que .zshenv.

Pourquoi cette distinction existe-t-elle ? Parce qu’un shell non-interactif est conçu pour exécuter des scripts, pas pour servir un utilisateur humain. Charger les aliases, le prompt et les complétons dans un script qui tourne en background serait un gaspillage. Le problème, c’est que votre PATH — l’information la plus critique pour trouver les exécutables — est souvent initialisé dans .zshrc, pas dans .zshenv.

La racine du problème : Zsh ne source .zshrc que pour les shells interactifs. OpenCode, comme tout agent IA qui lance des sous-processus, utilise des shells non-interactifs. Ces shells ne lisent que .zshenv.

Zsh dispose de quatre fichiers d’initialisation, chacun avec un rôle précis. C’est un design élégant — mais c’est aussi le nœud du problème :

Le tableau donne un indice, mais il faut le comprendre en profondeur. Pensez-y comme les pièces d’une maison :

Le drame, c’est que la plupart d’entre nous mettons le PATH dans le salon. Et l’agent IA, lui, n’a jamais le droit d’y entrer.

Le problème en un diagramme :

Quand vous ouvrez un terminal, Zsh est interactif : il lit .zshrc, tout fonctionne. Quand OpenCode lance un shell pour exécuter une commande, Zsh est non-interactif : il saute .zshrc, ne lit que .zshenv. Et si .zshenv n’existe pas ou ne contient pas le PATH — c’est le désert.

Avant de corriger, il faut comprendre exactement ce qui manque. Voici une méthode de diagnostic reproductible — gardez-la en favoris si vous travaillez avec des agents IA.

La stratégie est simple, mais elle demande de la précision : mettre dans .zshenv uniquement les chemins essentiels, sans sourcer les scripts d’initialisation lourds. On ne déplace pas .zshrc dans .zshenv — on extrait l’essentiel.

Avant de passer aux pièges, un résumé visuel de la transformation. Sur la gauche, ce que vous aviez (tout dans .zshrc, invisible pour l’agent). Sur la droite, ce que vous avez maintenant (les chemins essentiels dans .zshenv, visibles partout).

Tout n’est pas parfait avec cette approche. Voici les problèmes que j’ai rencontrés, et comment les contourner.

Après avoir créé .zshenv et le symlink NVM, validez que tout fonctionne — dans les deux contextes :

Les deux doivent réussir. Si oui, votre agent IA verra les mêmes outils que vous. Si non, revenez au diagnostic pas à pas — vous avez probablement oublié un chemin ou le symlink NVM n’est pas à jour.