opencode.jsonc konfigurieren: 7 Checks vor dem Commit

Die wichtigste Antwort ist nicht nur der Speicherort. Nutze opencode.jsonc für überprüfbare, nicht geheime OpenCode-Einstellungen, halte Zugangsdaten außerhalb des Repos, verstehe die Zusammenführung von globaler und Projektkonfiguration und prüfe Provider, Modelle, Berechtigungen und Rollback.

Die offizielle Dokumentation nennt JSON- und JSONC-Unterstützung. Kommentare sollten deshalb erklären, warum eine Einstellung existiert, wem sie gehört und welcher Befehl sie verifiziert.

Speichere keine Geheimnisse. Modelle, Shell, Tools, Berechtigungen und Projektpfade gehören in die Konfiguration; API Keys, Tokens, private URLs und Proxy-Zugangsdaten bleiben außerhalb des Repos.

OpenCode führt Konfigurationsdateien zusammen, statt sie vollständig zu ersetzen. Globale Präferenzen und Projektregeln können sich also kombinieren, solange keine Schlüssel kollidieren.

Globale Konfiguration passt für persönliche Gewohnheiten. Projektkonfiguration passt für Teamregeln: Modell, ignorierte Pfade, Befehle, MCP und Berechtigungen.

Kopiere Modell-IDs aus aktuellen Docs oder Provider-Dashboards. Gültiges JSON reicht nicht, wenn der Modellname nur ein Marketingname ist.

Nutze Hauptmodell und kleines Modell nur mit klarer Begründung: Kosten, Latenz, Kontextfenster, lokale Verfügbarkeit oder Compliance. Ändert sich die Begründung, wird die Datei geprüft.

Berechtigungen sind der riskanteste Bereich. Bearbeitungen und Shell-Befehle bleiben zunächst auf ask, bis wiederholbare und reversible Aktionen bewiesen sind.

Installationen, Löschungen, Migrationen, Deployments, Pushes, Secrets und externe Ordner bleiben deny oder explizite Rückfrage. Ausnahmen für Agents oder MCP gehören zum jeweiligen Kontext.

Füge die offizielle Schema-URL hinzu, damit der Editor validiert und vervollständigt. Das ersetzt keine Sicherheitsprüfung, findet aber falsche Schlüssel und veraltete Formen.

Prüfe danach jede Einstellung: nicht geheim, repository-relevant, kommentiert und mit der aktuellen Version vereinbar.

Teste vor dem Commit in einem risikoarmen Repo. Starte OpenCode, liste Modelle, lies eine Datei, mache eine kleine Änderung, führe einen erwarteten Befehl aus und prüfe eine blockierte Aktion.

Notiere OS, Shell, Provider, Modell, Testbefehl und Rollback. Dadurch wird die Datei zu einer reproduzierbaren Basis.

Prüfe zusätzlich, ob das Repository generierte Ordner, alte lokale Notizen oder mehrere Einstiegspunkte enthält. Eine Konfiguration, die in einem kleinen Beispiel sauber wirkt, kann in einem gewachsenen Projekt andere Pfade treffen. Ein kurzer Test mit einer echten, aber ungefährlichen Dokumentationsänderung zeigt schneller, ob Modell, Berechtigungen und Shell zusammenpassen.

1. Minimale Datei erstellenMit Schema, Modell und geprüfter Berechtigungshaltung starten.
2. Syntax validierenEditor-Schema oder JSONC-fähige Werkzeuge nutzen.
3. Schichten auflösenPrüfen, ob global, Projekt, eigener Pfad oder verwaltet gewinnt.
4. Kleine Aufgabe ausführenDatei lesen, harmlose Änderung machen und bekannten Befehl ausführen.
5. deny testenEine blockierte Aktion probieren und Stopp bestätigen.
6. Rollback notierenBeschreiben, wie Regel oder Datei entfernt wird.

Bei Fehlern trenne die Schichten: JSONC-Syntax, Arbeitsordner, Git-Root, globale Overrides, Projekt-Overrides, Umgebungsvariablen, Provider und Berechtigungen.

Unter Windows sind Dateipfad und Shell getrennte Themen. Eine gültige Konfiguration scheitert, wenn das Terminal Variablen nicht sieht oder die konfigurierte Shell fehlt.

Wenn mehrere Entwickler verschiedene globale Einstellungen nutzen, dokumentiere die erwarteten Projektwerte explizit. So wird klar, welche Abweichungen erlaubt sind und welche Unterschiede eine Fehlersuche auslösen sollten.

Für die Übergabe im Team reicht oft eine kurze Checkliste: Datei geändert, Schema geprüft, Modellliste geladen, erlaubter Befehl getestet, blockierter Befehl getestet und Rollback notiert. Diese Liste ist wichtiger als eine lange Erklärung, weil sie bei späteren OpenCode-Updates sofort zeigt, welcher Teil neu geprüft werden muss.

Plane außerdem eine regelmäßige erneute Prüfung, wenn Provider-Namen, Modell-IDs, Shell-Versionen oder Sicherheitsvorgaben wechseln. Dadurch bleibt opencode.jsonc ein lebendes Team-Artefakt und keine veraltete lokale Ausnahme mit versteckten Annahmen.