Referenzen

Referenzen geben OpenCode Zugriff auf Verzeichnisse außerhalb des aktuellen Projekts. Verwenden Sie sie, um Dokumentation, gemeinsam genutzte Bibliotheken, Beispiele oder ein anderes Repository während der Arbeit verfügbar zu machen.

Referenzen werden über einen Alias in opencode.json oder opencode.jsonc konfiguriert.

{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and documentation conventions",
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "Use for JavaScript SDK implementation details",
    },
  },
}

Lokale Verzeichnisse

Verwenden Sie path, um auf ein lokales Verzeichnis zu verweisen.

{
  "references": {
    "docs": {
      "path": "../docs",
    },
  },
}

Pfade können sein:

• Relativ zur Konfigurationsdatei, die die Referenz definiert
• Absolut, z. B. /home/user/docs
• Relativ zu Ihrem Home-Verzeichnis, z. B. ~/docs

Sie können auch eine Kurzschreibweise als String verwenden:

{
  "references": {
    "docs": "../docs",
  },
}

Git-Repositories

Verwenden Sie repository, um auf ein Git-Repository zu verweisen. OpenCode legt das Repository in seinem lokalen Repository-Cache an und stellt den ausgecheckten Quellcode als Referenzverzeichnis bereit.

{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}

repository akzeptiert Git-URLs, host/path-Referenzen und die GitHub-Kurzform owner/repo. Das optionale Feld branch wählt einen Branch oder Ref aus. Ohne branch verwendet OpenCode den Standard-Branch des Repositorys.

Sie können die Kurzschreibweise als String verwenden, wenn Sie keinen Branch, keine Beschreibung und keine weiteren Optionen benötigen:

{
  "references": {
    "effect": "Effect-TS/effect",
  },
}

Verwendung beschreiben

Fügen Sie description hinzu, um zu erklären, wann ein Agent eine Referenz verwenden soll.

{
  "references": {
    "design-system": {
      "path": "../design-system",
      "description": "Use when implementing UI components or design tokens",
    },
  },
}

OpenCode nimmt Referenzen mit Beschreibungen in den Agentenkontext auf. Beschreibungen sollten kurz und so spezifisch sein, dass sich Referenzen mit ähnlichem Inhalt unterscheiden lassen. Referenzen ohne Beschreibung bleiben über die Autovervollständigung und direkte Verwendung verfügbar, werden Agenten aber nicht angeboten.

Autovervollständigungseinträge ausblenden

Setzen Sie hidden auf true, um eine Referenz aus der @-Autovervollständigung in der TUI auszublenden.

{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true,
    },
  },
}

hidden wirkt sich nur auf die Autovervollständigung aus. Eine ausgeblendete Referenz mit Beschreibung bleibt im Agentenkontext enthalten.

Referenzen verwenden

Konfigurierte Referenzen erscheinen in der @-Autovervollständigung der TUI. Geben Sie @alias ein, um das Stammverzeichnis der Referenz anzuhängen, oder @alias/, um darin nach Dateien zu suchen.

Compare this implementation with @sdk/src/client.ts

Agenten erhalten in ihrem Systemkontext außerdem die aufgelösten Pfade und Beschreibungen konfigurierter Referenzen, die eine Beschreibung haben. So können sie eine Referenz untersuchen, wenn sie relevant ist, ohne dass Sie sie manuell anhängen müssen.

OpenCode erlaubt Referenzverzeichnisse automatisch über seine Berechtigungsgrenze für externe Verzeichnisse. Die normalen Tool-Berechtigungen gelten weiterhin; ein Agent, der keine Dateien bearbeiten darf, erhält zum Beispiel keinen Bearbeitungszugriff, nur weil ein Verzeichnis als Referenz konfiguriert ist.

Felder konfigurieren

Referenz-Aliase dürfen nicht leer sein und keine /, Leerzeichen, Backticks oder Kommas enthalten.