OpenCode und der unvollständige PATH: Warum deine Tools nicht im Shell des Agents waren

Es war ein Dienstagabend. Ich hatte gerade installierthttps://opencode.ai[OpenCode], l’agent IA qui promettait de transformer ma façon de coder. Premier test : lui demander de lister mes dépôts GitHub.

Seltsam.`gh`funktionierte perfekt in meinem Terminal. Ich versuche etwas anderes:

Dann:

Java, Gradle, Node,gh— Alles war für den Agenten unsichtbar. Mein Terminal selbst sah alles. Als ob der Agent und ich in zwei parallelen Welten lebten.

Ich habe Stunden gebraucht, um es zu verstehen. Stunden von`echo $PATH`, de which java, wachsender Frustration. Ich habe schließlich verstanden, dass das Problem nicht die Tools waren — es war dasSchale. OpenCode, wie jeder Agent, der Unterprozesse startet, arbeitet in Shellsnicht-interaktiv. Und Zsh, in diesen Shells, ignoriert einfach nur Ihr`.zshrc`.

Das Folgende ist der vollständige Bericht über diese Diagnose, die Lösung und die Lektion, die ich gelernt habe. Wenn Sie einen KI-Agenten verwenden — OpenCode, Aider, Cursor oder sogar Cron-Skripte — wird Sie dieses Problem eines Tages betreffen.

Wenn Sie ein Terminal öffnen, behandelt Zsh es wie eine Shellinteraktiv. Er lädt`.zshrc`, das alles initialisiert: SDKMAN, NVM, pnpm, die Aliase, dein schöner Prompt. Deine Umgebung ist vollständig.

Aber wenn OpenCode einen Befehl ausführt, startet es kein interaktives Terminal. Es startet eine Shell.nicht-interaktiv— ein Aufgaben-Shell, ohne Mensch hinter dem Bildschirm. Und Zsh, in diesem Kontext, springt`.zshrc`. Er liest nur`.zshenv`.

Warum existiert diese Unterscheidung? Weil eine nicht-interaktive Shell dafür ausgelegt ist, Skripte auszuführen, nicht um einen menschlichen Nutzer zu bedienen. Das Laden von Aliases, dem Prompt und den Vervollständigungen in einem Skript, das im Hintergrund läuft, wäre eine Verschwendung. Das Problem ist, dass dein PATH — die wichtigste Information zum Auffinden von Ausführbaren — oft initialisiert in`.zshrc`, nicht in`.zshenv`.

Die Wurzel des Problems:Zsh source .zshrc nur für interaktive Shells. OpenCode, wie jeder KI-Agent, der Unterprozesse startet, verwendet nicht-interaktive Shells. Diese Shells lesen nur`.zshenv`.

Zsh verfügt übervier Initialisierungsdateien, jeder mit einer bestimmten Rolle. Das ist ein elegantes Design — aber das ist auch das Knackpunkt des Problems:

Die Tabelle gibt einen Hinweis, aber sie muss tiefgehend verstanden werden. Denke daran wie die Zimmer eines Hauses:

Das Drama ist, dass die meisten von uns das PATH ins Wohnzimmer stellen. Und der KI-Agent hat niemals das Recht, hineinzugehen.

Das Problem in einem Diagramm :

Wenn Sie ein Terminal öffnen, ist Zsh interaktiv: es liest`.zshrc`, alles funktioniert. Wenn OpenCode eine Shell startet, um einen Befehl auszuführen, ist Zsh nicht-interaktiv: es springt`.zshrc`, liest nur`.zshenv`. Et si `.zshenv`existiert nicht oder enthält nicht den PATH — es ist die Wüste.

Bevor du korrigierst, musst du genau verstehen, was fehlt. Hier ist eine reproduzierbare Diagnosemethode — lege sie in deine Lesezeichen, wenn du mit KI-Agenten arbeitest.

Die Strategie ist einfach, aber sie erfordert Präzision: hineinzulegen`.zshenv` nurdie wesentlichen Pfade, ohne das Sourcen der schweren Initialisierungsskripte. Man verschiebt nicht`.zshrc`in`.zshenv`— Wir extrahieren das Wesentliche.

Bevor du zu den Fallen übergehst, eine visuelle Zusammenfassung der Transformation. Auf der linken Seite, was du hattest (alles in`.zshrc`, unsichtbar für den Agenten). Auf der rechten Seite, was du jetzt hast (die wesentlichen Pfade innerhalb`.zshenv`, überall sichtbar).

Nicht alles ist mit diesem Ansatz perfekt. Hier sind die Probleme, auf die ich gestoßen bin, und wie man sie umgehen kann.

Nach dem Erstellen`.zshenv`und prüfen Sie, dass alles beim NVM‑Symlink funktioniert — in beiden Kontexten:

Beide müssen erfolgreich sein. Wenn ja, wird Ihr KI-Agent die gleichen Tools sehen wie Sie. Wenn nein, kehren Sie zur schrittweisen Diagnose zurück — Sie haben wahrscheinlich einen Pfad vergessen oder der NVM-Symlink ist nicht auf dem neuesten Stand.

__ Ein nicht interaktiver Shell ist wie ein stiller Gast: er liest nur das, was an der Haustür angezeigt wird. Ist das PATH im Wohnzimmer, sieht er es niemals. [No output]