> ## Documentation Index > Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260623-1106.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Konfiguration > Konfigurationsdateiformat, Drei-Scope-System und Merge-Regeln failproofai verwendet JSON-Konfigurationsdateien, um festzulegen, welche Richtlinien aktiv sind, wie sie sich verhalten und woher benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist so gestaltet, dass sie einfach im Team geteilt werden kann – committen Sie sie in Ihr Repository und jeder Entwickler erhält dasselbe Sicherheitsnetz für den Agenten. *** ## Konfigurationsbereiche Es gibt drei Konfigurationsbereiche, die in Prioritätsreihenfolge ausgewertet werden: | Bereich | Dateipfad | Zweck | | ----------- | ----------------------------------------- | ---------------------------------------------------------------------------------- | | **project** | `.failproofai/policies-config.json` | Repository-spezifische Einstellungen, in die Versionsverwaltung eingecheckt | | **local** | `.failproofai/policies-config.local.json` | Persönliche, repository-spezifische Überschreibungen, per gitignore ausgeschlossen | | **global** | `~/.failproofai/policies-config.json` | Benutzerweite Standardwerte für alle Projekte | Wenn failproofai ein Hook-Ereignis empfängt, lädt und merged es alle drei Dateien, die für das aktuelle Arbeitsverzeichnis vorhanden sind. ### Merge-Regeln **`enabledPolicies`** – die Vereinigung aller drei Bereiche. Eine Richtlinie, die auf irgendeiner Ebene aktiviert ist, ist aktiv. ```text theme={null} project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← deduplizierte Vereinigung ``` **`policyParams`** – der erste Bereich, der Parameter für eine bestimmte Richtlinie definiert, gewinnt vollständig. Es gibt kein tiefes Mergen von Werten innerhalb der Parameter einer Richtlinie. ```text theme={null} project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo apt-get update"] } ← project gewinnt, global wird ignoriert ``` ```text theme={null} project: (kein block-sudo-Eintrag) local: (kein block-sudo-Eintrag) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← fällt auf global zurück ``` **`customPoliciesPath`** – der erste Bereich, der diesen Wert definiert, gewinnt. **`llm`** – der erste Bereich, der diesen Wert definiert, gewinnt. *** ## Konfigurationsdateiformat ```json theme={null} { "enabledPolicies": [ "block-sudo", "block-rm-rf", "block-push-master", "sanitize-api-keys", "sanitize-jwt", "block-env-files", "block-read-outside-cwd" ], "policyParams": { "block-sudo": { "allowPatterns": ["sudo systemctl status", "sudo journalctl"] }, "block-push-master": { "protectedBranches": ["main", "release", "prod"] }, "block-rm-rf": { "allowPaths": ["/tmp"] }, "block-read-outside-cwd": { "allowPaths": ["/shared/data", "/opt/company"] }, "sanitize-api-keys": { "additionalPatterns": [ { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" } ] }, "warn-large-file-write": { "thresholdKb": 512 } }, "customPoliciesPath": "/home/alice/myproject/my-policies.js" } ``` *** ## Feldreferenz ### `enabledPolicies` Typ: `string[]` Liste der zu aktivierenden Richtliniennamen. Die Namen müssen exakt mit den Richtlinienbezeichnern übereinstimmen, die von `failproofai policies` angezeigt werden. Eine vollständige Liste finden Sie unter [Integrierte Richtlinien](/de/built-in-policies). Richtlinien, die nicht in `enabledPolicies` enthalten sind, sind inaktiv, auch wenn sie Einträge in `policyParams` haben. ### `policyParams` Typ: `Record>` Parameterüberschreibungen pro Richtlinie. Der äußere Schlüssel ist der Richtlinienname; die inneren Schlüssel sind richtlinienspezifisch. Jede Richtlinie dokumentiert ihre verfügbaren Parameter unter [Integrierte Richtlinien](/de/built-in-policies). Wenn eine Richtlinie Parameter hat, Sie diese aber nicht angeben, werden die eingebauten Standardwerte der Richtlinie verwendet. Benutzer, die `policyParams` gar nicht konfigurieren, erhalten ein identisches Verhalten wie in früheren Versionen. Unbekannte Schlüssel innerhalb des Parameterblocks einer Richtlinie werden zum Zeitpunkt der Hook-Ausführung stillschweigend ignoriert, werden jedoch als Warnungen markiert, wenn Sie `failproofai policies` ausführen. #### `hint` (übergreifend) Typ: `string` (optional) Eine Meldung, die an den Grund angehängt wird, wenn eine Richtlinie `deny` oder `instruct` zurückgibt. Verwenden Sie sie, um Claude handlungsrelevante Hinweise zu geben, ohne die Richtlinie selbst zu ändern. Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom/`), Projektkonvention (`.failproofai-project/`) oder Benutzerkonvention (`.failproofai-user/`). ```json theme={null} { "policyParams": { "block-force-push": { "hint": "Try creating a fresh branch instead." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], "hint": "Use apt-get directly without sudo." }, "custom/my-policy": { "hint": "Ask the user for approval first." } } } ``` Wenn `block-force-push` ablehnt, sieht Claude: *„Force-Pushing ist blockiert. Try creating a fresh branch instead."* Nicht-String-Werte und leere Strings werden stillschweigend ignoriert. Wenn `hint` nicht gesetzt ist, bleibt das Verhalten unverändert (abwärtskompatibel). ### `customPoliciesPath` Typ: `string` (absoluter Pfad) Pfad zu einer JavaScript-Datei mit benutzerdefinierten Hook-Richtlinien. Dieser wird automatisch von `failproofai policies --install --custom ` gesetzt (der Pfad wird vor der Speicherung in einen absoluten Pfad aufgelöst). Die Datei wird bei jedem Hook-Ereignis neu geladen – es gibt kein Caching. Weitere Informationen zur Erstellung finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies). ### Konventionsbasierte Richtlinien Zusätzlich zum expliziten `customPoliciesPath` erkennt und lädt failproofai automatisch Richtliniendateien aus `.failproofai/policies/`-Verzeichnissen: | Ebene | Verzeichnis | Bereich | | -------- | -------------------------- | -------------------------------------------- | | Projekt | `.failproofai/policies/` | Mit dem Team über Versionsverwaltung geteilt | | Benutzer | `~/.failproofai/policies/` | Persönlich, gilt für alle Projekte | **Dateiabgleich:** Es werden nur Dateien geladen, die `*policies.{js,mjs,ts}` entsprechen (z. B. `security-policies.mjs`, `workflow-policies.js`). Andere Dateien im Verzeichnis werden ignoriert. **Keine Konfiguration erforderlich:** Konventionsrichtlinien benötigen keine Einträge in `policies-config.json`. Legen Sie einfach Dateien in das Verzeichnis und sie werden beim nächsten Hook-Ereignis aufgenommen. **Vereinigtes Laden:** Sowohl Projekt- als auch Benutzerkonventionsverzeichnisse werden durchsucht. Alle passenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu `customPoliciesPath`, das das Prinzip „erster Bereich gewinnt" verwendet). Weitere Details und Beispiele finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies). ### `llm` Typ: `object` (optional) LLM-Client-Konfiguration für Richtlinien, die KI-Aufrufe durchführen. Für die meisten Setups nicht erforderlich. ```json theme={null} { "llm": { "model": "claude-sonnet-4-6", "apiKey": "sk-ant-..." } } ``` *** ## Konfiguration über die CLI verwalten Die Befehle `policies --install` und `policies --uninstall` schreiben in die Hook-Einstellungsdatei Ihres Agenten-CLIs (die Hook-Einstiegspunkte), während `policies-config.json` die Datei ist, die Sie direkt verwalten. Beide sind voneinander getrennt: * **Agenten-CLI-Einstellungen** — weist den Agenten an, bei jeder Werkzeugnutzung `failproofai --hook ` aufzurufen: * **Claude Code**: `~/.claude/settings.json` (Benutzer), `/.claude/settings.json` (Projekt), `/.claude/settings.local.json` (lokal) * **OpenAI Codex**: `~/.codex/hooks.json` (Benutzer), `/.codex/hooks.json` (Projekt) — Codex hat keinen `local`-Bereich * **GitHub Copilot CLI *(beta)***: `~/.copilot/hooks/failproofai.json` (Benutzer), `/.github/hooks/failproofai.json` (Projekt) — Copilot hat keinen `local`-Bereich. Hook-Einträge verwenden die betriebssystemabhängigen `bash`/`powershell`-Befehlsfelder von Copilot mit `timeoutSec`; die Datei enthält einen `version: 1`-Marker auf oberster Ebene. Die Unterstützung für Copilot CLI ist **beta**, während wir das `events.jsonl`-Aufzeichnungsschema (das in den öffentlichen Docs nicht spezifiziert ist) anhand weiterer realer Sitzungen verifizieren. * **Cursor Agent *(beta)***: `~/.cursor/hooks.json` (Benutzer), `/.cursor/hooks.json` (Projekt) — Cursor hat keinen `local`-Bereich. Hook-Einträge verwenden die Claude-ähnliche Form `{type, command, timeout}` (keine `bash`/`powershell`-Aufteilung), werden aber unter camelCase-Ereignisschlüsseln (`preToolUse`, `beforeSubmitPrompt`, …) in einem flachen Array gemäß Cursors [Hooks-Schema](https://cursor.com/docs/hooks) gespeichert; die Datei trägt einen `version: 1`-Marker auf oberster Ebene. Der Handler kanonisiert camelCase → PascalCase über `CURSOR_EVENT_MAP`, sodass bestehende eingebaute Richtlinien unverändert ausgelöst werden. Die Unterstützung für Cursor Agent ist **beta**, während wir Cursors On-Disk-Transkriptformat (in den öffentlichen Docs nicht spezifiziert) anhand weiterer realer Installationen verifizieren. * **OpenCode *(beta)***: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (Benutzer), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (Projekt) — OpenCode hat keinen `local`-Bereich. Im Gegensatz zu den anderen sechs CLIs verfügt OpenCode über **kein externes Befehlshook-System**: Es lädt In-Process-JS/TS-Plugins, die explizit über das `plugin: []`-Array in `opencode.json` registriert werden (Auto-Discovery aus `.opencode/plugins/` ist **nicht** der Weg, wie Plugins in opencode v1.14.33 geladen werden). Die Installation legt einen kleinen generierten Plugin-Shim ab, der die failproofai-Binärdatei als Subprocess aufruft und die Claude-ähnliche JSON-Antwort der Binärdatei zurück in Plugin-Semantik übersetzt: `throw new Error()` für Tool-Event-deny (bricht den Tool-Aufruf ab), `client.session.prompt(...)` für instruct UND für `Stop`/`SubagentStop`-deny (sendet den Ablehnungsgrund als nächste Benutzernachricht – der einzige Force-Retry-Kanal, da `session.idle` nur benachrichtigend ist und ein Throw daraus ein No-Op ist), und No-Op für allow. Der Shim kanonisiert sowohl Werkzeugnamen (Kleinbuchstaben → PascalCase über `OPENCODE_TOOL_MAP`) als auch Tool-Input-Argumentschlüssel (camelCase → snake\_case über `OPENCODE_TOOL_INPUT_MAP` für `Read`/`Write`/`Edit`, z. B. `filePath` → `file_path`, `oldString` → `old_string`), bevor es an die Binärdatei weitergeleitet wird, sodass pfadprüfende Builtins wie `block-read-outside-cwd`, `block-env-files` und `block-secrets-write` bei OpenCode-Tool-Aufrufen unverändert ausgelöst werden. Sitzungen werden in OpenCodes SQLite-Datenbank unter `~/.local/share/opencode/opencode.db` gespeichert; der Sitzungs-Viewer des Dashboards liest sie über `opencode db --format json` und `opencode export `. Die Unterstützung für OpenCode ist **beta**, während wir das Verhalten über verschiedene Versionen und mehr reale Sitzungen hinweg verifizieren. Siehe die [OpenCode-Plugins-Dokumentation](https://opencode.ai/docs/plugins/). * **Pi *(beta)***: `~/.pi/agent/settings.json` (Benutzer), `/.pi/settings.json` (Projekt) — Pi hat keinen `local`-Bereich. Pi lädt TypeScript-Erweiterungspakete beim Start; die Einstellungsdatei ist ein flaches String-Array `{"packages": ["./relative/path", …]}`. failproofai schreibt einen einzelnen packages-Array-Eintrag, der auf sein gebündeltes `pi-extension/`-Verzeichnis verweist. Die Erweiterung abonniert intern Pis `tool_call`/`user_bash`/`input`/`session_start`-Ereignisse und ruft `failproofai --hook --cli pi` als Shell-Prozess auf; der Handler kanonisiert underscore\_lower\_snake\_case → PascalCase über `PI_EVENT_MAP`, sodass bestehende eingebaute Richtlinien unverändert ausgelöst werden. Tool-Input-Argumente werden ebenfalls über `PI_TOOL_INPUT_MAP` kanonisiert (Pis Read/Write/Edit liefern `path` statt `file_path`; die Abbildung des Top-Level-Schlüssels lässt `block-env-files` und `block-secrets-write` auslösen – `block-read-outside-cwd` hatte bereits einen `path`-Fallback). Die Pi-Unterstützung ist **beta**, während sich Pis Erweiterungs-API und das Sitzungsprotokoll-Layout stabilisieren. * **Gemini CLI *(beta)***: `~/.gemini/settings.json` (Benutzer), `/.gemini/settings.json` (Projekt) — Gemini hat keinen `local`-Bereich (es dokumentiert einen `system`-Bereich unter `/etc/gemini-cli/settings.json`, den failproofai nicht bereitstellt). Hook-Einträge verwenden Claudes `{type, command, timeout}`-Form, eingebettet in Geminis `{matcher, hooks: [...]}`-Matcher-Schema mit standardmäßig `matcher: "*"`. Ereignisse sind PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); der Handler bildet sie über `GEMINI_EVENT_MAP` auf kanonische Claude-Namen ab. Werkzeugnamen sind snake\_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) – der Handler kanonisiert über `GEMINI_TOOL_MAP`, sodass bestehende eingebaute Richtlinien unverändert ausgelöst werden. Der Richtlinienauswerter gibt Geminis flache `{decision: "deny", reason}`-Form aus (bevorzugt gemäß Geminis „Golden Rule" exit-0-Vertrag), `{hookSpecificOutput: {hookEventName, additionalContext}}` für Kontexteinschleusung bei BeforeAgent/AfterTool/SessionStart, und `{decision: "block", reason}` bei AfterAgent für Force-Retry-Semantik. Die Unterstützung für Gemini CLI ist **beta**, während wir die reale Abdeckung ausweiten. Siehe die [Gemini CLI Hooks-Dokumentation](https://geminicli.com/docs/hooks/). * **`policies-config.json`** — teilt failproofai mit, welche Richtlinien ausgewertet werden sollen und mit welchen Parametern (gilt für alle Agenten-CLIs) Übergeben Sie `--cli claude|codex|copilot|cursor|opencode|pi|gemini`, um einen bestimmten Agenten auszuwählen (leerzeichen-getrennt oder mehrfach für eine beliebige Teilmenge): ```bash theme={null} failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` Wenn `--cli` weggelassen wird, erkennt `failproofai` automatisch, welche Agenten-CLIs installiert sind (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): * **Eine CLI erkannt** — wählt diese CLI automatisch ohne Nachfrage aus. * **Mehrere CLIs erkannt** in einem interaktiven Terminal — zeigt eine Pfeilauswahl-Eingabeaufforderung an, gruppiert in einen Abschnitt `Erkannt (N)` (mit einer aggregierten Zeile `Für alle N erkannten installieren` + jede erkannte CLI einzeln) und einen Abschnitt `Nicht installiert (M) · Hooks vorab installieren`, der jede nicht erkannte unterstützte CLI als Vorab-Installationsoption aufführt (↑↓ zum Bewegen, Enter zum Auswählen, ^C zum Beenden). Der Deinstallationsablauf zeigt nur den Abschnitt „Erkannt". * **Mehrere CLIs erkannt** in einer nicht-interaktiven Ausführung (CI, kein TTY) — installiert für alle erkannten CLIs ohne Nachfrage. * **Keine erkannt** — fällt auf `claude` zurück, mit einer Warnung, dass keine Agenten-Binärdatei im PATH gefunden wurde; der Hook-Befehl wird dennoch geschrieben, sodass er aktiviert wird, sobald Sie eine installieren. Sie können `policies-config.json` jederzeit direkt bearbeiten; Änderungen treten sofort beim nächsten Hook-Ereignis in Kraft, ohne dass ein Neustart erforderlich ist. *** ## Beispiel: Konfiguration auf Projektebene mit Team-Standardwerten Committen Sie `.failproofai/policies-config.json` in Ihr Repository: ```json theme={null} { "enabledPolicies": [ "block-sudo", "block-rm-rf", "block-push-master", "sanitize-api-keys", "block-env-files" ], "policyParams": { "block-push-master": { "protectedBranches": ["main", "release", "hotfix"] } } } ``` Jeder Entwickler kann dann `.failproofai/policies-config.local.json` (per gitignore ausgeschlossen) für persönliche Überschreibungen erstellen, ohne Teamkollegen zu beeinflussen.