Referenzen

Fügen Sie lokale Verzeichnisse und Git-Repositories als Projektreferenzen hinzu.

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 per 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 materialisiert das Repository in seinem lokalen Repository-Cache und stellt die ausgecheckte Quelle als Referenzverzeichnis zur Verfügung.

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

repository akzeptiert Git-URLs, Host/Pfad-Referenzen und die GitHub-Kurzschreibweise owner/repo. Das optionale Feld branch wählt einen Branch oder eine 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 oder andere Optionen benötigen:

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

Hinweis: Git-Referenzen werden asynchron aktualisiert. Bei einem neu konfigurierten Repository kann es einen Moment dauern, bis das Klonen oder Aktualisieren abgeschlossen ist.

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 präzise genug sein, um Referenzen mit ähnlichem Inhalt zu unterscheiden. Referenzen ohne Beschreibung bleiben über Autovervollständigung und direkte Verwendung verfügbar, werden Agenten aber nicht aktiv angezeigt.

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 Wurzelverzeichnis der Referenz anzuhängen, oder @alias/, um darin nach Dateien zu suchen.

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

Agenten erhalten außerdem die aufgelösten Pfade und Beschreibungen konfigurierter Referenzen mit Beschreibung in ihrem Systemkontext, sodass sie eine Referenz bei Bedarf einsehen können, ohne dass Sie sie manuell anhängen müssen.

OpenCode erlaubt Referenzverzeichnisse automatisch über die Grenze der External-Directory-Berechtigung. Normale Tool-Berechtigungen gelten weiterhin; ein Agent, der keine Dateien bearbeiten darf, erhält beispielsweise keinen Bearbeitungszugriff, nur weil ein Verzeichnis als Referenz konfiguriert ist.

Konfigurationsfelder

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