OpenCode Permissions richtig einstellen, so behaltet ihr den Coding Agent im Griff

Von Roland Golla
0 Kommentar
Ockerfarbene Dalí-Wüste, Frau mit Schlüssel am Tor, Elefant wartet davor

Ein Coding Agent ist schnell. Er liest Dateien, schreibt Code und startet Befehle im Terminal. Genau deshalb braucht er Grenzen. Mit den OpenCode Permissions legt ihr fest, was der Agent einfach tun darf, wo er fragen muss und was komplett tabu ist. Wir arbeiten täglich mit OpenCode. Hier steht, wie wir die Rechte einstellen und warum.

NCA KI Workshop für Developer: Euer Team lernt Agentic Coding für die Produktion, mit Regeln, Rechten und Quality Gates, die im Alltag wirklich greifen. Zum KI Workshop für Developer

Warum ein Coding Agent klare Grenzen braucht

Ohne eigene Einstellungen ist OpenCode sehr großzügig. Die Grundregel erlaubt alles. Das ist bequem, solange alles gut läuft. Kritisch wird es bei Befehlen, die sich nicht zurückholen lassen. Ein git push auf den falschen Branch. Ein rm im falschen Ordner. Ein Zugriff auf einen Ordner, der gar nicht zum Projekt gehört.

Permissions sind die erste Leitplanke. Sie wirken, bevor etwas passiert. Tests und Reviews greifen erst danach. Beides gehört zusammen. Warum Leitplanken mit jedem besseren Modell wichtiger werden, steht im Beitrag KI Guardrails und bessere Modelle.

Die drei Werte allow, ask und deny

Eine Regel besteht aus drei Teilen. Die action nennt das Werkzeug, zum Beispiel shell, read oder edit. Die resource ist das Ziel, also ein Befehl, ein Pfad, eine URL oder die ID eines Skills oder Agents. Der effect ist einer von drei Werten:

  • allow: Der Agent darf die Aktion ohne Rückfrage ausführen.
  • ask: OpenCode fragt euch vorher um Erlaubnis.
  • deny: Die Aktion ist gesperrt.

Ohne eigene Konfiguration gelten die Standardwerte. Die Grundregel erlaubt alles. Vor dem Lesen von .env Dateien und ihren Varianten fragt OpenCode nach, .env.example ist erlaubt. Pfade außerhalb des Projekts sind standardmäßig erlaubt. Die eingebauten Agents bringen eigene Grenzen mit. Der Plan Agent darf keine Projektdateien ändern, der Explore Agent ist auf Shell, Lesen, Suchen und Web begrenzt.

Eine sichere Grundkonfiguration für den Alltag

Die Rechte stehen als geordnete Liste unter permissions in der opencode.json im Projekt. So sieht eine Grundkonfiguration aus, mit der man gut arbeiten kann:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "npm run *", "effect": "allow" },
    { "action": "shell", "resource": "npm test *", "effect": "allow" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git log *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "shell", "resource": "rm *", "effect": "deny" },
    { "action": "webfetch", "resource": "*", "effect": "ask" },
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ]
}

Build, Tests und lesende Git Befehle laufen ohne Rückfrage. Alles andere im Terminal fragt nach. Push und Löschen sind gesperrt. Den Push macht ihr selbst, nachdem ihr den Diff gelesen habt. Das kostet ein paar Sekunden und spart im Ernstfall Stunden.

Die eigentliche Sicherung ist die erste Zeile. Shell Befehle laufen mit allen Rechten eures Benutzers. Eine kurze Liste erlaubter Befehle ist deshalb sicherer als der Versuch, jeden gefährlichen Befehl einzeln zu sperren. Das deny für rm ist nur ein zusätzliches Netz.

Wer das Lesen von Secrets ganz sperren will, statt nur zu fragen, ergänzt drei Regeln:

{ "action": "read", "resource": "*.env", "effect": "deny" },
{ "action": "read", "resource": "*.env.*", "effect": "deny" },
{ "action": "read", "resource": "*.env.example", "effect": "allow" }

Wie OpenCode die Regeln auswertet

Bei mehreren passenden Regeln gewinnt die letzte passende Regel. Deshalb steht die allgemeine Regel mit * immer oben. Die speziellen Regeln folgen darunter. Passt gar keine Regel, fragt OpenCode nach. Für die Muster gibt es zwei Platzhalter:

  • * passt auf beliebig viele Zeichen, auch auf keins und auch auf Schrägstriche in Pfaden.
  • ? passt auf genau ein Zeichen.

Ein Shell Muster, das mit * endet, erfasst auch den Befehl ohne Argumente. git status * gilt also für git status und für git status --short. Drei weitere Punkte helfen beim Lesen eurer Regeln:

  • Verkettete Befehle. OpenCode zerlegt einen Shell Befehl und prüft jeden Teilbefehl und jedes Ziel von cd einzeln. Lässt sich ein Befehl nicht sauber zerlegen, gibt es einen Fehler statt einer Ausführung.
  • Mehrere Ziele. Prüft eine Aktion mehrere Ressourcen, blockiert ein einziges deny alles. Sonst führt ein einziges ask zur Rückfrage.
  • Home Verzeichnis. ~ und $HOME werden bei read, edit und external_directory aufgelöst, bei shell nicht.

Rechte pro Agent vergeben

Ihr könnt Rechte für einzelne Agents ergänzen. Die Regeln eines Agents ersetzen die globalen Regeln nicht, sie werden dahinter gehängt. Weil die letzte passende Regel gewinnt, setzt sich bei einem Konflikt die Regel des Agents durch. So bekommt der Build Agent eigene Regeln für Git:

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "build": {
      "permissions": [
        { "action": "shell", "resource": "git *", "effect": "allow" },
        { "action": "shell", "resource": "git commit *", "effect": "ask" },
        { "action": "shell", "resource": "git push *", "effect": "deny" }
      ]
    }
  }
}

Einen eigenen Review Agent legt ihr als Markdown Datei an, zum Beispiel unter ~/.config/opencode/agents/review.md. Im Frontmatter steht, dass er nichts ändern darf. Der Text darunter wird zum System Prompt des Agents:

---
description: Code Review ohne Änderungen
mode: subagent
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: ask
  - action: webfetch
    resource: "*"
    effect: deny
---
Analysiere den Code und schlage Änderungen vor. Ändere selbst nichts.

Eigene Subagents nutzen ihre eigenen Regeln. Sie erben keinen Ausschnitt der Rechte des Agents, der sie startet. Prüft deshalb jede Agent Datei für sich.

Was once, always und reject bedeuten

Steht eine Regel auf ask, zeigt OpenCode drei Antworten. Mit once erlaubt ihr genau diese eine Anfrage. Mit always erlaubt ihr sie und OpenCode speichert die vorgeschlagenen Muster für das Projekt. Ein deny überstimmt das nie. Mit reject lehnt ihr ab, und zwar diese Anfrage und alle weiteren, die in der Session gerade warten. Lest bei always deshalb genau, welches Muster OpenCode vorschlägt. Was das ganze Team dauerhaft erlauben soll, gehört in die opencode.json im Repository.

Fremde Ordner mit external_directory absichern

Greift der Agent auf einen Pfad außerhalb des Projekts zu, prüft OpenCode zuerst die Aktion external_directory. Erst danach kommen die Regeln für read und edit. Der Standard ist allow. Für Rechner mit mehreren Repositories, SSH Keys oder lokalen Daten ist das zu offen. Stellt die Aktion auf ask und gebt nur gezielt Ordner frei. Wollt ihr dort nur lesen, sperrt ihr edit für denselben Pfad:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "external_directory", "resource": "~/projects/shared/*", "effect": "allow" },
    { "action": "edit", "resource": "~/projects/shared/*", "effect": "deny" }
  ]
}

Policies und Regeln für die Pipeline

Normale Regeln kann jeder im Projekt ändern. Wer etwas für alle erzwingen will, nutzt eine Policy. Sie läuft nach den Regeln und nach euren Freigaben. Eine Policy kann nur hart verbieten, sie erlaubt nie etwas. Globale Policies und Policies aus der OpenCode Console stehen über der Konfiguration im Projekt.

In der Pipeline sitzt niemand, der eine Rückfrage beantwortet. Dort helfen Regeln mit ask nicht weiter. Setzt für die CI klare Verbote mit deny. Wie das im Workflow aussieht, zeigt OpenCode GitHub Action einrichten.

Eine Lücke solltet ihr kennen. Shell Blöcke in Commands laufen, sobald OpenCode den Command auswertet, und zwar außerhalb der Permissions des Agents. Welche Folgen das hat, steht in OpenCode Commands erstellen. Auch Skills lassen sich über Permissions steuern. Wie das geht, zeigt der Vergleich OpenCode Skills vs Commands.

Alle wichtigen Permissions im Überblick

ActionWofürUnsere Empfehlung
shellBefehle im Terminalask als Standard, Build und Tests auf allow, Push und Löschen auf deny
editDateien ändern und anlegenallow im Projekt, deny in geteilten Ordnern
readDateien lesenallow, bei .env fragt OpenCode nach oder ihr sperrt es mit deny
webfetchWebseiten abrufenask oder Freigabe für bekannte Doku Seiten
websearchSuche im Webask, in der Pipeline deny
subagentSubagents starten, Ressource ist die ID des Agentsallow für bekannte Agents
skillSkills laden, Ressource ist die ID des Skillsallow, ask für neue oder fremde Skills
external_directoryPfade außerhalb des Projektsask, nur gezielte Ordner freigeben
MCP ToolsTools eines MCP Servers, geschrieben als Name des Servers, Unterstrich, Name des Toolsask für alles, was schreibt

Die vollständige Liste steht in der OpenCode Doku zu Permissions. Wie Agents sich unterscheiden, erklärt die OpenCode Doku zu Agents. Wie ihr Verbote für alle festlegt, steht in der OpenCode Doku zu Policies.

Was sich bei den OpenCode Permissions geändert hat

Wer seine Rechte nach älteren Anleitungen eingerichtet hat, sollte diese Punkte prüfen.

ThemaFrüherHeute
Schlüssel in der Konfigurationpermission pro Werkzeugpermissions als geordnete Liste
Terminalbashshell
Subagentstasksubagent
Dateien schreibenwrite und patchedit
Agentsagentagents
Pfade außerhalb des ProjektsRückfrage als StandardErlaubt als Standard
doom_loopEigene SchutzregelKeine eingebaute Aktion mehr

OpenCode liest das alte Format weiter ein. Wie ihr sauber umstellt, steht im Artikel zum Umstieg auf OpenCode 2.

Wie wir Teams beim Einrichten von OpenCode helfen

OpenCode ist bei uns der Coding Agent im Alltag, mit Open Weight Modellen aus den Familien GLM und Qwen. Gute Rechte sind nur ein Teil. Dazu kommen Regeln in der AGENTS.md, Quality Gates in der Pipeline und Tests mit Cypress. Den Überblick über Astro, GitHub Pages und OpenCode findet ihr in unseren Vibe Coding Tipps und Tricks. Warum das Werkzeug um das Modell so viel ausmacht, steht im Artikel zum Agent Harness. Welche Modelle sich eignen, vergleichen wir bei den Vibe Coding Modellen.

Begleitung im Projekt gibt es in der Vibe Coding Beratung. Pipelines für KI Code beschreiben wir bei den Vibe Coding CI/CD Pipelines. Wer Git Kontext direkt im Agent will, schaut sich den GitKraken MCP Server für OpenCode an. Und warum Tests die zweite Leitplanke sind, steht in End to End Tests für jedes Webprojekt. Das Vorgespräch ist kostenlos, abgerechnet wird transparent nach Minuten.

Häufige Fragen zu OpenCode Permissions

Was darf OpenCode 2026 ohne eigene Permissions?

Ohne eigene Konfiguration erlaubt die Grundregel alles. Der Agent darf also lesen, schreiben und Befehle starten, auch außerhalb des Projekts. Nur vor dem Lesen von .env Dateien fragt OpenCode nach. Für echte Projekte solltet ihr die Rechte deshalb selbst festlegen, zuerst für shell und external_directory.

Wo stehen die OpenCode Permissions 2026?

Die Rechte stehen als Liste unter permissions in der opencode.json. Die Datei liegt im Projekt oder global unter ~/.config/opencode. Jede Regel hat action, resource und effect. Rechte für einzelne Agents setzt ihr unter agents oder im Frontmatter einer Agent Datei in Markdown. Sie werden hinter die globalen Regeln gehängt.

Welche Regel gewinnt bei OpenCode 2026?

Bei mehreren passenden Regeln gewinnt immer die letzte. Schreibt deshalb die allgemeine Regel mit Sternchen zuerst und die speziellen Regeln danach. So steht shell auf ask, npm run auf allow und git push auf deny, und jede Regel greift genau dort, wo sie soll. Passt keine Regel, fragt OpenCode nach.

Wie sichere ich 2026 Ordner außerhalb des Projekts ab?

Mit einer Regel für external_directory. Der Standard erlaubt Pfade außerhalb des Projekts. Stellt die Aktion mit dem Muster Sternchen auf ask und gebt danach nur die Ordner frei, die der Agent wirklich braucht. Soll er dort nur lesen, sperrt ihr edit für denselben Pfad mit deny.

Kann OpenCode 2026 meine .env Datei lesen?

Nur nach Rückfrage. Im Standard fragt OpenCode, bevor es .env Dateien und ihre Varianten liest. Nur .env.example ist ohne Rückfrage erlaubt. Wer sicher gehen will, sperrt das Lesen mit einer eigenen Regel auf deny. Secrets gehören weder in den Kontext eines Modells noch in einen Prompt. Lokal arbeitet ihr am besten mit Testdaten.

Was bedeutet always bei einer Rückfrage in OpenCode?

Mit always erlaubt ihr die Anfrage und OpenCode speichert die vorgeschlagenen Muster für das Projekt. Ähnliche Anfragen laufen danach ohne Rückfrage. Eine Regel mit deny bleibt trotzdem stärker. Lest das vorgeschlagene Muster deshalb genau, bevor ihr zustimmt. Für eine einzelne Ausnahme reicht once.

Gibt es die Regel doom_loop in OpenCode noch?

Nein. In der aktuellen Version ist doom_loop keine eingebaute Aktion mehr. Eine alte Regel dafür hat keine eingebaute Wirkung. Verlasst euch stattdessen auf einen engen Rahmen für shell, auf Tests und auf ein Limit für die Schritte eines Agents. Das Feld steps begrenzt, wie viele Schritte ein Agent machen darf.

OpenCode mit sicheren Rechten für euer Team

Wir richten OpenCode mit Permissions, Regeln und Quality Gates für euer Team ein, oder eure Developer lernen es im KI Workshop selbst. Das Vorgespräch ist kostenlos, abgerechnet wird transparent nach Minuten.

0 Kommentar

Tutorials und Top Posts

Gib uns Feedback

Diese Seite benutzt Cookies. Ein Akzeptieren hilft uns die Seite zu verbessern. Ok Mehr dazu