OpenCode 2: Berechtigungen aus V1 migrieren und externe Zugriffe bestätigen

Füge eine ausdrückliche external_directory-Regel mit effect: "ask" hinzu, damit OpenCode 2 externe Verzeichniszugriffe wieder bestätigen lässt. Mit Stand 2026-10-31 nennt die offizielle Migrationsanleitung für V2 den Standardwert allow, während V1 ask verwendet. Behalte unterstützte V1-Konfigurationen, bis du ihre Berechtigungsregeln in das geordnete V2-Array permissions umwandeln kannst.

Diese Anleitung enthält eine Basiskonfiguration für interaktive Entwicklungsarbeit und einen Prüfablauf mit OpenCode v2.2.0 als Referenz. Die erwarteten Ergebnisse beruhen auf der Dokumentation und dem Quellcode mit diesem Versions-Tag, nicht auf einem Test einer laufenden Installation.

Warum erlaubt V2 externe Pfade, obwohl Prüfungen ohne Treffer ask verwenden?

Auch eingebaute Regeln werden ausgewertet. Eine fehlende eigene Regel bedeutet daher nicht, dass die Berechtigungsprüfung keinen Treffer findet.

Laut dem offiziellen Abschnitt Defaults für V2 beginnt jeder Agent mit einer allgemeinen Freigaberegel mit Platzhaltern. Diese enthält action: "*", resource: "*" und effect: "allow". Spätere Basisregeln verlangen eine Bestätigung für das Lesen von *.env und *.env.* und erlauben danach *.env.example. Mitgelieferte Agenten können weitere Einschränkungen hinzufügen.

Für gewöhnliche Lesezugriffe, Änderungen, Shell-Befehle und Prüfungen externer Verzeichnisse gibt es somit bereits eine passende Basisregel. Der Rückfallwert ask greift nur, wenn im gesamten ausgewerteten Regelsatz keine Regel passt. Fehlende eigene Einstellungen für read oder edit erzwingen deshalb keine Bestätigung.

Die Freigabe eines externen Verzeichnisses und die Freigabe einer Dateioperation bleiben getrennte Prüfungen. OpenCode berücksichtigt die aktive Location und den Arbeitsbaum des Projekts, sofern dieser nicht die Wurzel des Dateisystems ist. Bei Pfaden außerhalb beider Bereiche prüft es external_directory vor read oder edit. Location bezeichnet hier den aktiven Arbeitsort. Eine externe Datei kann daher die Grenzprüfung bestehen und trotzdem einer Lese- oder Änderungssperre unterliegen.

Diese Reihenfolge legt der Mechanismus zur Verzeichnisprüfung fest, nicht die Position unterschiedlich benannter Aktionen im Array. Eine external_directory-Regel vor eine read-Regel zu verschieben, erzeugt diese Prüfreihenfolge nicht.

Kannst du V1-Konfigurationen behalten, und welche Namen ändern sich?

Ja. Das native V2-Format ist optional. OpenCode normalisiert unterstützte V1-Konfigurationen, ohne dass du ihre Quelldateien neu schreiben musst. Die Migrationsanleitung empfiehlt, zunächst vorhandene Modelle, Zugangsdaten, Agenten, Berechtigungen und MCP-Server zu prüfen.

V1 gruppiert Berechtigungsentscheidungen nach Werkzeug:

{
  "permission": {
    "bash": {
      "git push *": "ask"
    },
    "edit": "allow"
  },
  "tools": {
    "websearch": false
  }
}

Die dokumentierte V2-Umwandlung bildet diese ausdrücklichen Einstellungen als geordnete Regeln ab:

{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

Jede Regel benötigt drei Zeichenkettenfelder: action, resource und effect. allow lässt die Operation ohne Nachfrage weiterlaufen, deny sperrt sie und ask wartet auf eine Entscheidung im Client.

Dieses Beispiel wandelt nur die gezeigten Einstellungen um. Es ist nicht die weiter unten empfohlene Basiskonfiguration. Es erlaubt weiterhin Änderungen und stellt Rückfragen für externe Verzeichnisse nicht wieder her.

Die Aktionsnamen ändern sich von bash zu shell, von task zu subagent und von write/patch zu edit. In V2 kontrolliert edit die Zielpfade der Operationen edit, write und patch. subagent gleicht eine Agenten-ID ab; shell gleicht die vom Scanner erzeugten Befehlszeichenketten ab. Die Aktionsreferenz weist außerdem darauf hin, dass doom_loop und lsp keine aktuellen Berechtigungsaktionen von V2 Core sind.

Prüfe Einstellungen auf oberster Ebene, Agentendefinitionen und Skripte, die Konfigurationen erzeugen. Ersetze diese Wörter nicht pauschal in unbeteiligten Dateien. Vermeide nach einer gezielten Umwandlung konkurrierende V1- und V2-Berechtigungsdefinitionen.

Verwende eine zurückhaltende V2-Basiskonfiguration

Lass bei interaktiver Entwicklungsarbeit externe Zugriffe, Shell-Befehle und Dateiänderungen bestätigen. Erlaube übliche Git-Abfragen, sperre passende Push-Befehle und verweigere das Lesen von Umgebungsdateien mit Ausnahme von Beispieldateien.

Verwende opencode.jsonc im Projektstamm für Repository-spezifische Einstellungen. Die benutzerweite Konfiguration liegt unter ~/.config/opencode/opencode.jsonc. OpenCode akzeptiert auch die Varianten mit .json; die Konfigurationsreferenz beschreibt die unterstützten Speicherorte.

Füge dieses Array in die vorhandene Konfiguration ein. Behalte Anbietereinstellungen, Agentendefinitionen und bestehende Einschränkungen, statt die ganze Datei zu ersetzen.

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "edit", "resource": "*", "effect": "ask" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" }
  ]
}

Die Ausnahme für .env.example steht absichtlich hinter beiden Lesesperren. Verwende sie nur für Beispieldateien ohne geheime Werte.

Nicht aufgeführte Aktionen erben weiterhin ihre wirksamen Standardeinstellungen. Diese Basiskonfiguration sperrt nicht jedes MCP-Werkzeug, verhindert nicht jeden möglichen Push-Weg und isoliert das Dateisystem des Hosts nicht. Ihre read-Beschränkungen verbieten auch nicht, dieselben Dateien über Shell-Befehle zu lesen.

Die Shell-Warnung von OpenCode erklärt, dass Shell-Befehle mit den Rechten des Host-Benutzers laufen. Der Scanner kann nicht garantiert alle betroffenen Verzeichnisse erkennen. Prüfe Befehle vor der Freigabe und verwende separate Shell-Regeln, wenn Regeln für Dateioperationen nicht ausreichen.

Für einen anderen Client hilft die Anleitung zu Claude-Code-Berechtigungen für Geheimnisse und Git. Übernimm dort nicht die Konfigurationssyntax von OpenCode.

Setze Ausnahmen hinter die Regeln, die sie überschreiben

Die Reihenfolge zählt bei Regeln, die auf dieselbe Aktion und dieselbe Ressource passen. Eine spätere passende Regel ersetzt die vorherige Entscheidung. Ein Platzhalter im Aktionsfeld kann mehrere Aktionsnamen abdecken.

In der Basiskonfiguration verlangt shell: "*" zunächst eine Bestätigung. Die späteren Regeln git status * und git diff * erlauben diese Befehle. Die Regel git push * sperrt passende Push-Befehle.

Ein Shell-Muster mit der Endung * passt auch auf den Befehl ohne Argumente. Deshalb deckt git status * sowohl git status als auch git status --short ab.

Die Referenz zum Regelabgleich definiert Platzhalter, die mit dem gesamten Wert verglichen werden. * steht für null oder mehr Zeichen einschließlich /; ? steht für ein Zeichen. Pfadtrenner werden zu Schrägstrichen normalisiert. Unter Windows ignoriert der Abgleich die Groß- und Kleinschreibung.

Bei Operationen mit mehreren Ressourcen folgt ein weiterer Schritt. Ermittle zunächst für jede Ressource die letzte passende Regel. Sobald eines dieser Ergebnisse eine Sperre ist, wird die Operation abgelehnt. Andernfalls führt jede erforderliche Bestätigung zu einer Rückfrage. Zusammengesetzte Shell-Befehle können mehrere Ressourcen erzeugen. Ein erlaubter Git-Befehl gibt daher nicht den gesamten zusammengesetzten Befehl frei.

Ergänze ein vertrauenswürdiges externes Verzeichnis vorsichtig

Erlaube den Zugriff über die Verzeichnisgrenze getrennt von den Dateioperationen. Diese optionalen Regeln ergänzen die Basiskonfiguration und ersetzen sie nicht:

[
  { "action": "external_directory", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "read", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "edit", "resource": "~/projects/reference/*", "effect": "deny" }
]

Setze die externe Freigabe hinter die allgemeine external_directory-Regel mit ask. Setze die Lesefreigabe vor die Sperren für Umgebungsdateien, damit diese weiterhin greifen. Setze die Änderungssperre hinter die allgemeine Regel, die Änderungen bestätigen lässt.

Die Verzeichnisregeln unterstützen bei diesen Pfadaktionen Verweise auf das Home-Verzeichnis am Pfadanfang, etwa ~/. Shell-Ressourcen bleiben unveränderter Befehlstext. Beim Laden der Konfiguration wird diese Erweiterung darauf nicht angewendet.

Die Änderungssperre blockiert Operationen, die von edit kontrolliert werden, einschließlich der Werkzeuge write und patch. Änderungen über die Shell blockiert sie nicht. Behalte separate Shell-Beschränkungen und prüfe jede Freigabe, die Änderungen an diesen Dateien ermöglichen könnte.

Migriere die Einstellungen und prüfe sie mit harmlosen Testdateien

Sichere die tatsächlich verwendeten Dateien, fordere einen Änderungsvorschlag an und prüfe die akzeptierte Konfiguration in einem Wegwerfprojekt. Voraussetzung sind ein installierter V2-Client und eine funktionierende Verbindung zum Anbieter und Modell.

Prüfe die vorgeschlagene Migration vor dem Anwenden

Sichere globale und projektspezifische Konfigurationen einschließlich der Agentendefinitionen unter .opencode/agents/. Die offiziellen Agenten-Speicherorte umfassen außerdem benutzerweite Definitionen unter ~/.config/opencode/agents/.

Behandle Plugins, Server-API-Integrationen und Terminaleinstellungen getrennt. Die Migrationsanleitung nennt für diese Bereiche inkompatible Änderungen.

Gib OpenCode diesen Prompt. Er verlangt zuerst eine Prüfung und untersagt Dateiänderungen bis zur Freigabe:

Read the official OpenCode V1 migration and V2 permissions documentation.

Inspect my global, project, and agent permission configuration.
Do not modify any files yet.

Propose native V2 permissions rules.
Preserve unrelated settings and existing restrictions.
Map bash to shell, task to subagent, and write and patch to edit where applicable.
Identify unsupported fields and competing V1/V2 definitions.
Restore external_directory approval without weakening existing deny rules.
Use the baseline's shell and edit approval rules unless existing rules are stricter.
Put environment-file denies before the .env.example exception.
Show the complete proposed diff and explain every behavior change.
Wait for approval before applying it.

Prüfe das zusammengeführte Ergebnis und nicht nur die Projektdatei. Agentenspezifische Berechtigungen folgen auf die aufgelösten Regeln der obersten Ebene. Eine spätere Agentenfreigabe kann daher eine gewöhnliche Sperre auf oberster Ebene überschreiben.

Für Einschränkungen, die eine Organisation erzwingen muss, siehe OpenCode-Richtlinien. Sie können eine Operation nach der Auswertung von Agentenregeln und gespeicherten Freigaben verbindlich sperren. Ein gewöhnliches Berechtigungsarray ersetzt keine administrativ erzwungene Einschränkung.

Lade nach dem Akzeptieren der Änderungen die Konfiguration mit opencode reload neu. Die CLI-Referenz dokumentiert diesen Befehl. Prüfe Konfigurationswarnungen, bevor du fortfährst.

Führe einen vollständigen Prüfdurchlauf durch

Verwende v2.2.0 mit dem eingebauten Agenten build als Referenz für die erwarteten Ergebnisse. Die Tabelle setzt voraus, dass die Basiskonfiguration wirksam ist und keine widersprechenden Agentenregeln, gespeicherten Freigaben oder zusätzlichen Richtlinien bestehen.

Erstelle in Bash harmlose Testdateien:

lab=$(mktemp -d)
mkdir -p "$lab/project" "$lab/outside"
git -C "$lab/project" init -q
printf 'ordinary fixture\n' > "$lab/project/README.md"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env.example"
printf 'outside fixture\n' > "$lab/outside/fixture.txt"
cd "$lab/project"

Speichere die Basiskonfiguration als opencode.jsonc dieses Projekts und starte opencode. Wähle mit /agents den Agenten build, wie im Leitfaden zur Terminaloberfläche beschrieben.

Bitte den Agenten, jede Operation einzeln mit dem angegebenen Werkzeug zu versuchen. Manuell im Terminal ausgeführte Befehle ersetzen keine Berechtigungsprüfung des Agenten.

Operation des Agenten	Erwartetes Berechtigungsergebnis
README.md mit read lesen	Durch die Basisregel für Lesezugriffe erlaubt
../outside/fixture.txt mit read lesen	Bestätigung für das externe Verzeichnis erforderlich; danach ist der gewöhnliche Lesezugriff erlaubt
.env mit read lesen	Gesperrt
.env.example mit read lesen	Erlaubt
README.md mit edit, write oder patch ändern	Bestätigung über edit erforderlich
git status, git status --short oder git diff über shell ausführen	Erlaubt
git push über shell ausführen	Durch die passende Shell-Regel gesperrt
pwd über shell ausführen	Bestätigung erforderlich

Führe vor dem Push-Test selbst git remote aus und prüfe, dass keine Namen angezeigt werden. Füge kein Remote hinzu. Ein Git-Fehler wegen eines fehlenden Remotes beweist nicht, dass die Berechtigungsregel den Befehl gesperrt hat.

Wähle bei Bestätigungstests Allow once („Einmal erlauben“) statt Allow always („Immer erlauben“). Gespeicherte Freigaben bleiben für das Projekt erhalten und können spätere Rückfragen unterdrücken. Konfigurierte Sperren überschreiben sie nicht. Lass automatische Freigaben ausgeschaltet.

Prüfe die tatsächliche Werkzeuganfrage, die Berechtigungsentscheidung und die Dateiänderungen. Die Zusage des Modells, keinen Push auszuführen oder eine Datei nicht zu lesen, belegt keine Sperre durch das Berechtigungssystem.

Kläre Abweichungen, bevor du eine Regel lockerst

Prüfe zuerst die geladene Konfiguration und den ausgewählten Agenten. Zu den CLI-Debugbefehlen gehören opencode debug config und opencode debug agents. Untersuche ihre Ausgabe lokal und teile keine Zugangsdaten oder vertraulichen Einstellungen.

Fehlt eine Rückfrage für einen externen Zugriff, muss das Ziel außerhalb der Location und des Projektarbeitsbaums liegen. Prüfe danach gespeicherte Freigaben und automatische Bestätigungen. Bei einem unerwarteten Leseergebnis kontrolliere, ob der Agent read und nicht shell verwendet hat.

Bei einem gesperrten Git-Befehl prüfe die vom Scanner erzeugte Ressource und zusätzliche Teilbefehle. Wird .env.example abgelehnt, suche nach einer späteren *.env.*-Regel oder einer zusätzlichen Richtlinie, die die Ausnahme überschreibt.

Prüfe vorhandenen Anbieter, Modell-ID, Authentifizierung und Base URL getrennt. Die OpenCode-Integrationsanleitung von BetterToken beschreibt eine benutzerdefinierte OpenAI-kompatible Verbindung mit https://www.bettertoken.ai/v1. Diese Verbindung ersetzt nicht die Berechtigungskonfiguration von OpenCode.

Wenn die Migration auch eine Werkzeugentscheidung umfasst, vergleiche die Konfiguration und Zugangswege von Cursor und OpenCode. Teste für einen anderen Terminal-Arbeitsablauf dieselbe Wegwerfaufgabe mit Aider oder OpenCode in einem Git-Projekt.

Was ändert die Dateisystemkorrektur in v2.2.0?

Die Korrektur verändert, wie Prüfungen externer Verzeichnisse Projektdateien auflösen. Die Empfehlung, eine ausdrückliche Bestätigungsregel zu setzen, bleibt unverändert.

Die Versionshinweise zu v2.2.0 nennen die Umstellung auf das Projektdateisystem. PR #59089 erklärt, dass bei entfernten oder im Speicher liegenden Projekten zuvor die Festplatte des Hosts geprüft wurde. Laut dem Autor sind gewöhnliche lokale Projekte nicht betroffen.

Wiederhole bei entfernten Projekten die Prüfung des externen Verzeichnisses auf dem tatsächlichen Dateisystem dieses Projekts. Die mit Stand 2026-10-31 dokumentierten V2-Standardregeln erfordern weiterhin ein ausdrückliches external_directory mit ask oder deny, wenn du diese Grenze durchsetzen möchtest.