OpenCode-Berechtigungskonfiguration

Das Berechtigungssystem von OpenCode steuert, welche Operationen automatisch ausgeführt werden können, welche Ihre manuelle Genehmigung erfordern und welche direkt blockiert werden. Eine ordnungsgemäße Konfiguration der Berechtigungen ermöglicht es der KI, Aufgaben effizient zu erledigen, und verhindert gleichzeitig versehentliche Operationen, die Code beschädigen oder vertrauliche Dateien preisgeben könnten.

Ab v1.1.1 wurde die altetoolsboolean-Konfiguration als veraltet markiert und inpermission. Die alte Konfiguration wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt, aber es wird empfohlen, zur neuenpermissionSyntax.

Drei Berechtigungsaktionen

Jede Berechtigungsregel führt letztendlich zu einer der folgenden drei Aktionen:

Aktion Wirkung Anwendbare Szenarien
"allow" Wird automatisch ohne Genehmigung ausgeführt Risikoarme, hochfrequente Operationen, wie das Lesen von Dateien und das Ausführen von Tests
"ask" Zeigt eine Genehmigungsaufforderung an, damit Sie entscheiden können, ob zugelassen werden soll Operationen mit gewissem Risiko, wie das Schreiben von Dateien und das Ausführen von Skripten
"deny" Direkt blockiert, weder ausgeführt noch nachgefragt Gefährliche Operationen, die ausdrücklich nicht erlaubt sind, wie das Löschen von Dateien und das Pushen von Code

Basiskonfiguration

Die Berechtigungskonfiguration wird unter dem Repository-Stammverzeichnis (oder Benutzerkonfigurationsverzeichnis) in deropencode.jsonDatei geschrieben, wobeipermissionFeld zum Konfigurieren verwendet wird.

1. Alle Berechtigungen global festlegen

Der einfachste Weg: Verwenden Sie eine einzelne Zeichenkette, um Berechtigungen für alle Vorgänge auf einmal festzulegen. Geeignet für den Schnellstart oder temporäres Debugging:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
"permission": "allow" // Alle Vorgänge werden automatisch ohne Aufforderungen ausgeführt (geeignet für lokale Entwicklung, wenn man der KI voll vertraut)
}

2. Nach Werkzeugnamen konfigurieren

Mit der Objektsyntax können Sie Berechtigungen für verschiedene Werkzeuge separat angeben."*"ist ein Platzhalter, das heißt, er stimmt mit allen Vorgängen überein, wird normalerweise als Fallback-Standardwert verwendet:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask", // Fallback-Regel: Alle Werkzeuge, die nicht einzeln konfiguriert sind, zeigen standardmäßig eine Aufforderung an.
"bash": "allow", // bash (Ausführen von Shell-Befehlen): direkt erlauben, keine Aufforderung
"edit": "deny" // edit (Dateien ändern): direkt blockieren
  }
}

Feingranulare Regeln (Objekt-Syntax)

Für die meisten Berechtigungen können Sie zusätzlich zum Festlegen einer einheitlichen Aktion auchObjekt-Syntaxverwenden, um je nach spezifischer Eingabe des Tools unterschiedliche Regeln anzuwenden. Zum Beispiel fürbashTools können Sie unterscheiden, welche Befehle erlaubt sind, welche genehmigt werden müssen und welche direkt abgelehnt werden:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
"*": "ask", // Fallback: Alle Bash-Befehle erfordern standardmäßig eine Genehmigung
"git *": "allow", // Befehle, die mit git beginnen (z. B. git status, git log), sind direkt erlaubt
"npm *": "allow", // Befehle, die mit npm beginnen (z. B. npm install, npm run build), sind direkt erlaubt
"grep *": "allow", // grep-Suchbefehle sind direkt erlaubt
"rm *": "deny" // rm-Löschbefehle werden direkt blockiert (um versehentliches Löschen von Dateien zu verhindern)
    },
    "edit": {
"*": "deny", // Alle Dateibearbeitungen standardmäßig blockieren
"packages/web/src/content/docs/*.mdx": "allow" // Nur das Bearbeiten von .mdx-Dateien unter dem docs-Verzeichnis erlauben
    }
  }
}

Reihenfolge der Regelübereinstimmung: Die zuletzt übereinstimmende Regel hat Vorrang.Es wird empfohlen, die Wildcard-"*"Regel an den Anfang als Standardwert zu setzen und spezifischere Regeln danach zu platzieren, um sie zu überschreiben. Auf diese Weise gilt: Je spezifischer eine Regel ist, desto höher ist ihre Priorität, was die Logik klar und weniger fehleranfällig macht.

Wildcard-Regeln

Berechtigungsmuster unterstützen einfache Wildcard-Übereinstimmung mit den folgenden Regeln:

Platzhalter Bedeutung Beispiel
* Entspricht null oder mehr beliebigen Zeichen (ohne Verzeichnisgrenzen zu überschreiten) git *Übereinstimmungengit status、git log --onelinewarten
** Entspricht jedem Pfad über Verzeichnisse hinweg ~/projects/**Entspricht allen Dateien und Unterverzeichnissen unter projects
? Entspricht genau einem beliebigen Zeichen file?.txtÜbereinstimmungenfile1.txt、fileA.txt
Andere Zeichen Entspricht exakt dem Literalwert git statusEntspricht nurgit status, stimmt nicht mit Varianten mit Parametern überein

Hinweis:Bei Befehlen mit Parametern unbedingt am Ende anhängen*. Zum Beispiel"grep *"kann übereinstimmengrep pattern file.txt, während man es allein schreibt"grep"stimmt nur mit bloßen Befehlen ohne Parameter überein, die bei der tatsächlichen Ausführung fast nie übereinstimmen werden.

Erweiterung des Home-Verzeichnisses

Am Anfang eines Musters können Sie~oder$HOMEum auf das Home-Verzeichnis des aktuellen Benutzers zu verweisen, und OpenCode erweitert es automatisch zum vollständigen Pfad:

Beispiel

// Die folgenden drei Formen haben dieselbe Wirkung, alle werden zu /Users/username/projects/* erweitert (Pfad variiert je nach System)
"~/projects/*"
"$HOME/projects/*"
"/Users/username/projects/*" // Das direkte Schreiben des absoluten Pfads funktioniert ebenfalls, wird aber nicht empfohlen (nicht portabel genug)

Berechtigungen für externe Verzeichnisse (external_directory)

Standardmäßig erlaubt OpenCode Werkzeugen nur den Zugriff aufdas Arbeitsverzeichnis beim Startund dessen Unterverzeichnisse. Wenn Sie auf Pfade außerhalb des Projektverzeichnisses zugreifen müssen (z. B. ein anderes Projekt oder ein gemeinsam genutztes Konfigurationsverzeichnis), müssen Sieexternal_directoryexplizite Autorisierung verwenden.

Erweiterung des Home-Verzeichnisses (~/...) ist nur eine PfadKurzschreibweiseund autorisiert nicht automatisch den Zugriff auf diesen Pfad. Pfade außerhalb des Arbeitsverzeichnisses müssen weiterhin durchlaufen werden,external_directoryum erlaubt zu werden.

1. Zugriff auf externe Verzeichnisse erlauben

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow" // Zugriff auf alle Dateien und Unterverzeichnisse unter ~/projects/personal/ erlauben
// ** stimmt mit Unterpfaden auf jeder Ebene überein
    }
  }
}

2. Lesen erlauben, aber Bearbeiten verbieten

Durchexternal_directoryAutorisierte Verzeichnisse erben die Standardberechtigungen des aktuellen Arbeitsbereichs. Dareadstandardmäßig auf"allow", können nach der Autorisierung Dateien unter diesem Verzeichnis gelesen werden. Wenn Sie eine bestimmte Operation weiter einschränken möchten (z. B. Lesen erlauben, aber Bearbeiten verbieten), können Sie zusätzliche Regeln hinzufügen:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow" // Schritt 1: Zugriff auf dieses externe Verzeichnis gewähren
    },
    "edit": {
"~/projects/personal/**": "deny" // Schritt 2: Eine überschreibende Regel für dieses Verzeichnis hinzufügen, die Lesen erlaubt, aber Bearbeiten verbietet
    }
  }
}

Alle verfügbaren Berechtigungselemente

Die Berechtigungen von OpenCode verwenden Tool-Namen als Schlüssel und decken alle Typen ab, einschließlich Dateioperationen, Befehlsausführung und Netzwerkzugriff:

Berechtigungselement Gesteuerte Operation Inhalt für Musterabgleich Standardwert
read Dateiinhalte lesen Dateipfad (z. B.,src/index.js） allow（.envDateien ausgeschlossen)
edit Alle Dateiänderungen, einschließlich edit, write, patch und multiedit Dateipfad allow
glob Glob-Suche nach Dateien (z. B. finde alle.tsDateien) Glob-Muster (z. B.**/*.ts） allow
grep Text im Dateiinhalt suchen Muster für regulären Ausdruck allow
list Dateien in einem Verzeichnis auflisten Verzeichnispfad allow
bash Shell-Befehl ausführen Vollständig geparster Befehl (z. B.git status --porcelain） allow
task Sub-Agent starten Sub-Agent-Typname allow
skill Skill laden Skill-Name allow
lsp LSP-Sprachdienstabfrage ausführen Feingranulare Konfiguration wird derzeit nicht unterstützt allow
webfetch Inhalt der Netzwerk-URL abrufen Vollständige URL (z. B.,https://example.com/api） allow
websearch Websuche Suchabfrage-Zeichenfolge allow
codesearch Code-Suche Suchabfrage-Zeichenfolge allow
external_directory Auf Pfade außerhalb des Arbeitsverzeichnisses zugreifen Externer Verzeichnispfad ask
doom_loop Wird ausgelöst, wenn dasselbe Tool 3 Mal wiederholt mit derselben Eingabe aufgerufen wird (verhindert, dass die KI in einer Schleife festhängt) — ask

Standard-Berechtigungsbeschreibung

Wenn Sie keine Berechtigungen konfiguriert haben, verwendet OpenCode die folgenden integrierten Standardwerte:

  • Die meisten Werkzeugberechtigungen sind standardmäßig auf"allow", was bedeutet, dass sie automatisch ohne Nachfrage ausgeführt werden
  • doom_loopundexternal_directoryStandardwert ist"ask", was eine manuelle Genehmigung erfordert
  • readDas Lesen aller Dateien ist standardmäßig erlaubt, aber.envzugehörige Dateien haben integrierten Schutz:

Beispiel

// Integrierte Standard-Leseregeln von OpenCode (keine manuelle Konfiguration erforderlich, nur als Referenz)
{
  "permission": {
    "read": {
"*": "allow", // Erlaubt standardmäßig das Lesen aller Dateien
"*.env": "deny", // Blockiert das Lesen von .env-Dateien (verhindert das Offenlegen von Datenbankpasswörtern, API-Schlüsseln usw.)
"*.env.*": "deny", // Blockiert das Lesen von Varianten wie .env.local, .env.production
"*.env.example": "allow" // Erlaube das Lesen von .env.example (Beispieldatei, keine echten Geheimnisse)
    }
  }
}

Drei Optionen in der Genehmigungsaufforderung

Wenn die Berechtigung einer Operation"ask", öffnet OpenCode eine Genehmigungsaufforderung mit den folgenden drei Auswahlmöglichkeiten:

Option Wirkung Anwendungsszenario
einmal (nur dieses Mal) Nur diese Anfrage genehmigen; dieselbe Operation wird beim nächsten Mal trotzdem abgefragt Eine Operation vorübergehend erlauben, ohne sie dauerhaft zu aktivieren
immer (immer erlauben) Das passende Muster der Operation zur Whitelist hinzufügen; keine weiteren Aufforderungen mehr für den Rest der aktuellen Sitzung Bestätigen, dass ein Operationstyp sicher ist, und ihn in dieser Sitzung automatisch durchlassen wollen
ablehnen (verweigern) Diese Anfrage ablehnen; die Operation wird nicht ausgeführt Die Operation erscheint riskant und Sie möchten ausdrücklich nicht, dass sie ausgeführt wird

Wenn Sieimmerdanach auswählen, wird OpenCode dafür sorgen, dass das Tool automatisch ein vorgeschlagenes Whitelist-Muster bereitstellt (z. B. nach der Genehmigunggit status, wird es normalerweisegit status*zur Whitelist hinzufügen).Die Whitelist ist nur für die aktuelle Sitzung gültig und wird nach einem Neustart von OpenCode zurückgesetzt.

Berechtigungen separat für Agenten konfigurieren

Wenn Ihr Workflow mehrere Agenten verwendet, können Sie die Berechtigungskonfiguration für jeden Agenten einzeln überschreiben. Agentenberechtigungen werden mit der globalen Konfiguration zusammengeführt, undAgentenregeln haben Vorrang vor globalen Regeln。

1. Agentenberechtigungen in opencode.json konfigurieren

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
// Globale Berechtigungen: git-Operationen erlaubt, aber commit und push verboten
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny",
      "grep *": "allow"
    }
  },
  "agent": {
"build": { // Agent namens build
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
"git commit *": "ask", // Überschreibt global: build-Agent erlaubt Commit, erfordert aber Genehmigung
"git push *": "deny", // Erbt global: push weiterhin verboten
          "grep *": "allow"
        }
      }
    }
  }
}

2. Agent-Berechtigungen in Markdown-Dateien konfigurieren

Agenten können auch über Markdown-Dateien konfiguriert werden, wobei die Berechtigungen im YAML-Front-Matter oben in der Datei geschrieben werden (---der Teil dazwischen):

Beispiel

# Dateipfad: ~/.config/opencode/agents/review.md
---
description: Code-Review-Agent (analysiert nur Code, nimmt keine Änderungen vor)
mode: subagent
permission:
  edit: deny        # Alle Dateibearbeitungen verbieten
  bash: ask         # bash-Befehle erfordern Genehmigung
  webfetch: deny    # Zugriff auf externe URLs verbieten
---

Nur Code analysieren und Änderungen vorschlagen.
# Nachfolgend steht der System-Prompt des Agenten, der seine Verantwortlichkeiten und Verhaltensnormen beschreibt

Praktische Konfigurationsbeispiele

Beispiel 1: Konservativer Modus (alle Operationen erfordern eine Genehmigung)

Geeignet für Einsteiger in OpenCode oder bei der Arbeit an wichtigen Projekten; alle Operationen erfordern eine manuelle Bestätigung:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask" // Alle Operationen aller Tools lösen Genehmigungsaufforderungen aus
  }
}

Beispiel 2: Gängige Entwicklungskonfiguration (Lesevorgänge erlaubt, Schreibvorgänge erfordern Genehmigung)

Geeignet für die tägliche Entwicklung: erlaubt der KI das freie Lesen und Durchsuchen von Code, erfordert jedoch eine Bestätigung beim Ändern von Dateien und Ausführen von Befehlen:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask", // Fallback: Nicht einzeln konfigurierte Tools erfordern standardmäßig eine Genehmigung
"read": "allow", // Dateien lesen: direkt erlauben
"glob": "allow", // Datei-Glob-Suche: direkt erlauben
"grep": "allow", // Inhaltssuche: direkt erlauben
"list": "allow", // Verzeichnisse auflisten: direkt erlauben
    "bash": {
"*": "ask", // Bash-Befehle erfordern standardmäßig Genehmigung
"git status *": "allow", // Git-Status anzeigen: erlauben
"git log *": "allow", // Git-Log anzeigen: erlauben
"git diff *": "allow", // Git-Diff anzeigen: erlauben
"npm run *": "allow", // npm-Skripte ausführen: erlauben
"npm test *": "allow", // Tests ausführen: erlauben
"rm *": "deny" // Dateien löschen: direkt blockieren
    }
  }
}

Beispiel 3: Zugriff auf mehrere Projektverzeichnisse erlauben

Wenn die KI über mehrere Projektverzeichnisse hinweg arbeiten muss, gewähren Sie Zugriff auf externe Verzeichnisse:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow", // Zugriff auf persönliche Projektverzeichnisse erlauben
"~/projects/work/**": "allow", // Zugriff auf Arbeitsprojektverzeichnisse erlauben
"~/dotfiles/**": "allow" // Zugriff auf das dotfiles-Verzeichnis erlauben
    },
    "edit": {
"~/dotfiles/**": "deny" // Selbst wenn der Zugriff auf Dotfiles erlaubt ist, ist das Bearbeiten verboten (schreibgeschützt)
    }
  }
}
Weitere Erweiterungen