> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Yapılandırma > Yapılandırma dosyası formatı, üç kapsamlı sistem ve birleştirme kuralları failproofai, hangi politikaların aktif olduğunu, nasıl davrandıklarını ve özel politikaların nereden yüklendiğini kontrol etmek için JSON yapılandırma dosyalarını kullanır. Yapılandırma, ekibinizle paylaşmak için tasarlanmıştır - bunu repo'nuza kaydedin ve her geliştirici aynı ajan güvenlik ağını alır. *** ## Yapılandırma kapsamları Üç yapılandırma kapsamı vardır ve öncelik sırasına göre değerlendirilir: | Kapsam | Dosya yolu | Amaç | | --------- | ----------------------------------------- | ------------------------------------------------------- | | **proje** | `.failproofai/policies-config.json` | Her repo için ayarlar, sürüm kontrolüne kaydedilir | | **yerel** | `.failproofai/policies-config.local.json` | Kişisel her repo geçersiz kılmaları, gitignore'da | | **genel** | `~/.failproofai/policies-config.json` | Tüm projeler arasında kullanıcı düzeyinde varsayılanlar | failproofai bir hook olayı aldığında, mevcut çalışma dizini için mevcut olan üç dosyanın tümünü yükler ve birleştirir. ### Birleştirme kuralları **`enabledPolicies`** - üç kapsamın tümünün birleşimi. Herhangi bir seviyede etkinleştirilen bir politika etkindir. ```text theme={null} proje: ["block-sudo"] yerel: ["block-rm-rf"] genel: ["block-sudo", "sanitize-api-keys"] çözüm: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← yinelenenden arındırılmış birleşim ``` **`policyParams`** - belirli bir politika için parametreleri tanımlayan ilk kapsam tamamen kazanır. Bir politikanın parametreleri içindeki değerlerin derin birleştirilmesi yoktur. ```text theme={null} proje: block-sudo → { allowPatterns: ["sudo apt-get update"] } genel: block-sudo → { allowPatterns: ["sudo systemctl status"] } çözüm: { allowPatterns: ["sudo apt-get update"] } ← proje kazanır, genel yok sayılır ``` ```text theme={null} proje: (block-sudo girişi yok) yerel: (block-sudo girişi yok) genel: block-sudo → { allowPatterns: ["sudo systemctl status"] } çözüm: { allowPatterns: ["sudo systemctl status"] } ← genel'e düşer ``` **`customPoliciesPath`** - bunu tanımlayan ilk kapsam kazanır. **`llm`** - bunu tanımlayan ilk kapsam kazanır. *** ## Yapılandırma dosyası formatı ```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" } ``` *** ## Alan referansı ### `enabledPolicies` Tür: `string[]` Etkinleştirilecek politika adlarının listesi. Adlar, `failproofai policies` tarafından gösterilen politika tanımlayıcılarıyla tam olarak eşleşmelidir. Tam liste için [Yerleşik Politikalar](/tr/built-in-policies) bölümüne bakın. `enabledPolicies` içinde olmayan politikalar, `policyParams` içinde girdileri olsa bile etkindir değildir. ### `policyParams` Tür: `Record>` Politikaya özgü parametre geçersiz kılmaları. Dış anahtar politika adıdır; iç anahtarlar politikaya özgüdür. Her politika, [Yerleşik Politikalar](/tr/built-in-policies) içinde mevcut parametrelerini belgelendirmektedir. Bir politikanın parametreleri varsa ancak siz bunları belirtmezseniz, politikanın yerleşik varsayılanları kullanılır. `policyParams` hiç yapılandırmayan kullanıcılar önceki sürümlerle özdeş davranış alır. Bir politikanın params bloğu içindeki bilinmeyen anahtarlar hook çalıştırırken sessizce yok sayılır ancak `failproofai policies` çalıştırdığınızda uyarı olarak işaretlenir. #### `hint` (çapraz kesme) Tür: `string` (isteğe bağlı) Bir politika `deny` veya `instruct` döndürdüğünde nedene eklenen mesaj. Politikanın kendisini değiştirmeden Claude'a uygulanabilir rehberlik vermek için kullanın. Herhangi bir politika türüyle çalışır — yerleşik, özel (`custom/`), proje kuralı (`.failproofai-project/`) veya kullanıcı kuralı (`.failproofai-user/`). ```json theme={null} { "policyParams": { "block-force-push": { "hint": "Bunun yerine yeni bir dal oluşturmayı deneyin." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], "hint": "sudo olmadan doğrudan apt-get kullanın." }, "custom/my-policy": { "hint": "Önce kullanıcıdan onay isteyin." } } } ``` `block-force-push` reddettiğinde, Claude şunu görür: *"Zorla itme engellendi. Bunun yerine yeni bir dal oluşturmayı deneyin."* Dize olmayan değerler ve boş dizeler sessizce yok sayılır. `hint` ayarlanmadıysa, davranış değişmez (geriye dönük uyumlu). ### `customPoliciesPath` Tür: `string` (mutlak yol) Özel hook politikaları içeren JavaScript dosyasının yolu. Bu, `failproofai policies --install --custom ` tarafından otomatik olarak ayarlanır (yol saklanmadan önce mutlak olarak çözümlenir). Dosya her hook olayında yeni yüklenir - hiçbir önbellek yoktur. Yazma ayrıntıları için [Özel Politikalar](/tr/custom-policies) bölümüne bakın. ### Kural tabanlı politikalar Açık `customPoliciesPath`'e ek olarak, failproofai `.failproofai/policies/` dizinlerinden politika dosyalarını otomatik olarak keşfeder ve yükler: | Düzey | Dizin | Kapsam | | --------- | -------------------------- | --------------------------------------------- | | Proje | `.failproofai/policies/` | Sürüm kontrolü aracılığıyla ekiple paylaşılır | | Kullanıcı | `~/.failproofai/policies/` | Kişisel, tüm projelere uygulanır | **Dosya eşleşmesi:** Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir (örn. `security-policies.mjs`, `workflow-policies.js`). Dizindeki diğer dosyalar yok sayılır. **Yapılandırma gerekmez:** Kural politikaları `policies-config.json` içinde giriş gerektirmez. Dosyaları dizine bırakın ve bir sonraki hook olayında seçilirler. **Birleşim yükleme:** Hem proje hem de kullanıcı kural dizinleri taranır. Her iki seviyedeki tüm eşleşen dosyalar yüklenir (`customPoliciesPath` ilk kapsam kazanır'dan farklı olarak). Daha fazla ayrıntı ve örnekler için [Özel Politikalar](/tr/custom-policies) bölümüne bakın. ### `llm` Tür: `object` (isteğe bağlı) AI çağrıları yapan politikalar için LLM istemci yapılandırması. Çoğu kurulum için gerekli değildir. ```json theme={null} { "llm": { "model": "claude-sonnet-4-6", "apiKey": "sk-ant-..." } } ``` *** ## CLI'dan yapılandırma yönetimi `policies --install` ve `policies --uninstall` komutları, ajan CLI'nizin hook ayarları dosyasına (hook giriş noktaları) yazarken `policies-config.json`, doğrudan yönettiğiniz dosyadır. İkisi ayrıdır: * **Ajan CLI ayarları** — ajanı her araç kullanımında `failproofai --hook ` çağırması için söyler: * **Claude Code**: `~/.claude/settings.json` (kullanıcı), `/.claude/settings.json` (proje), `/.claude/settings.local.json` (yerel) * **OpenAI Codex**: `~/.codex/hooks.json` (kullanıcı), `/.codex/hooks.json` (proje) — Codex yerel kapsamı yok * **GitHub Copilot CLI *(beta)***: `~/.copilot/hooks/failproofai.json` (kullanıcı), `/.github/hooks/failproofai.json` (proje) — Copilot yerel kapsamı yok. Hook girdileri Copilot'un OS anahtarlı `bash`/`powershell` komut alanlarını `timeoutSec` ile kullanır; dosya üst düzey `version: 1` işaretçisini taşır. Copilot CLI desteği **beta** durumundadır ve `events.jsonl` kayıt şemasını (halk belgeleri belirtmez) daha fazla gerçek dünya oturumuna karşı doğrularız. * **Cursor Agent *(beta)***: `~/.cursor/hooks.json` (kullanıcı), `/.cursor/hooks.json` (proje) — Cursor yerel kapsamı yok. Hook girdileri Claude şeklinde `{type, command, timeout}` formunu kullanır (`bash`/`powershell` bölümü yok) ancak camelCase olay anahtarları (`preToolUse`, `beforeSubmitPrompt`, …) altında depolanır, Cursor'un [hooks şemasına](https://cursor.com/docs/hooks) göre düz dizi halinde; dosya üst düzey `version: 1` işaretçisini taşır. İşleyici, `CURSOR_EVENT_MAP` aracılığıyla camelCase → PascalCase'i kanonikleştirir, böylece mevcut yerleşik politikalar değişmeden çalışır. Cursor Agent desteği **beta** durumundadır ve Cursor'un disk üzerindeki transkripti (açık belgelerde belirtilmez) daha fazla gerçek dünya kurulumuna karşı doğrularız. * **OpenCode *(beta)***: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (kullanıcı), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (proje) — OpenCode yerel kapsamı yok. Diğer beş CLI'den farklı olarak, OpenCode **harici komut hook sistemi olmaz**: `plugin: []` dizisi aracılığıyla açıkça kaydedilen işlem içi JS/TS eklentilerini yükler (`opencode.json` içinde) (`.opencode/plugins/` dan otomatik keşif opencode v1.14.33'de eklentilerin nasıl yüklendiği **değildir**). Kurulum, ikili failproofai'yi subprocess olarak çağıran ve ikili'nin Claude şekli JSON yanıtını eklenti semantiğine geri çeviren küçük bir oluşturulan eklenti parçacığını bırakır: araç olayı reddi için `throw new Error()` (araç çağrısını iptal eder), `instruct` VE `Stop` / `SubagentStop` reddi için `client.session.prompt(...)` (reddi nedeni bir sonraki kullanıcı iletisi olarak gönderir — `session.idle` yalnızca bildirimdir ve bundan atmak no-op olduğundan tek zorla yeniden deneme kanalı), allow için no-op. Parçacık hem araç adlarını (küçük harf → PascalCase, `OPENCODE_TOOL_MAP` aracılığıyla) hem de araç giriş arg anahtarlarını (camelCase → snake\_case, `OPENCODE_TOOL_INPUT_MAP` aracılığıyla `Read` / `Write` / `Edit` için, örn. `filePath` → `file_path`, `oldString` → `old_string`) kanonikleştirir, ikili'ye iletmeden önce, yol kontrol yerleşikleri gibi `block-read-outside-cwd`, `block-env-files` ve `block-secrets-write` OpenCode araç çağrılarında değişmeden çalışır. Oturumlar opencode'un SQLite DB'sinde yaşar `~/.local/share/opencode/opencode.db`; pano'nun oturum görüntüleyicisi onları `opencode db --format json` ve `opencode export ` aracılığıyla okur. OpenCode desteği **beta** durumundadır ve sürümler arasında ve daha fazla gerçek dünya oturumlarına karşı davranışı doğrularız. [OpenCode eklentileri belgeleri](https://opencode.ai/docs/plugins/) başlıklı sayfaya bakın. * **Pi *(beta)***: `~/.pi/agent/settings.json` (kullanıcı), `/.pi/settings.json` (proje) — Pi yerel kapsamı yok. Pi başlangıçta TypeScript uzantı paketlerini yükler; ayarlar dosyası düz dize dizisidir `{"packages": ["./relative/path", …]}`. failproofai, paketlenmiş `pi-extension/` dizinine işaret eden tek bir packages-dizisi girişi yazar. Uzantı dahili olarak Pi'nin `tool_call` / `user_bash` / `input` / `session_start` olaylarına abone olur ve `failproofai --hook --cli pi`'ye shell çıkışı verir; işleyici underscore\_lower\_snake\_case → PascalCase'i `PI_EVENT_MAP` aracılığıyla kanonikleştirir, böylece mevcut yerleşik politikalar değişmeden çalışır. Araç giriş argları da `PI_TOOL_INPUT_MAP` aracılığıyla kanonikleştirilir (Pi'nin Read / Write / Edit `file_path` yerine `path` iletir; üst düzey anahtarı eşlemek `block-env-files` ve `block-secrets-write`'in çalışmasını sağlar — `block-read-outside-cwd` zaten bir `path` geri dönüşü içeriyordu). Pi desteği **beta** durumundadır, Pi'nin uzantı API'si ve oturum günlüğü düzeni stabilize olurken. * **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**yalnızca kullanıcı kapsamı** — Hermes proje/yerel yapılandırması yok). Hermes bir Slack/Telegram **ağ geçididir**, bu nedenle bir kurulum her platformdan (Slack/Telegram/cli/cron) araç çağrılarını **ve** iç alt ajanları yakalar. Hook girdileri, Hermes'in snake\_case olayları (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) tarafından anahtarlanan `hooks:` eşlemesi altında `{command, timeout}` çiftidir; işleyici `HERMES_EVENT_MAP` aracılığıyla olayları ve `HERMES_TOOL_MAP` aracılığıyla araç adlarını kanonikleştirir, böylece yerleşik politikalar değişmeden çalışır. Yapılandırma, yorum koruyan YAML `Document` turuna göre düzenlendiğinden işletmenin diğer ayarları kalır ve kurulum, başsız ağ geçidinin (TTY yok) hookları onay istemi olmadan çalıştırması için `hooks_auto_accept: true` ayarlar. Değerlendirici Hermes'in `{"decision":"block","reason"}` stdout sözleşmesini yayar (Hermes çıkış kodlarını yok sayar). **Sınırlamalar:** Hermes'in bir `Stop` olay sonu yoktur, bu nedenle `require-*-before-stop` yerleşikleri bunun için hiçbir zaman çalışmaz (uygulanamaz, kırık değil); `instruct` izin-not-ile-günlüğe-kaydedil'e degrades (ek bağlam kanalı yok); ve çıkış gizli redaksiyonu (`sanitize-*`) shell-hook sözleşmesi üzerinde araç çıkışını yeniden yazamaz. Hermes aynı zamanda çevrimdışı bir **denetim** kaynağıdır — pano, ağ geçidi oturumlarını doğrudan `~/.hermes/state.db`'den okur. * **`policies-config.json`** — failproofai'ye hangi politikaları değerlendireceğini ve hangi parametrelerle (tüm ajan CLI'ler arasında paylaşılan) söyler Belirli bir ajanı hedeflemek için `--cli claude|codex|copilot|cursor|opencode|pi|hermes` geçin (boşlukla ayrılmış veya herhangi bir altküme için tekrarlanan): ```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 hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi ``` `--cli` atlandığında, `failproofai` hangi ajan CLI'lerin yüklendiğini algılar (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): * **Bir CLI algılandı** — sor olmadan o CLI'yi otomatik seçer. * **Etkileşimli bir terminalde birden fazla CLI algılandı** — `Detected (N)` bölümüne gruplandırılmış ok tuşu tek seçim istemi gösterir (algılanan tüm CLI'ler için bir `Tüm N tespit edileni yükle` toplu satırı + her algılanan CLI bireysel olarak) ve her desteklenen CLI'nin yüklenmemiş olan listesini gösteren `Yüklü olmayan (M) · hookları önceden kurma` bölümü (↑↓ taşımak, Enter seçmek, ^C bırakmak için). Kaldırma akışı yalnızca Algılanan bölümü gösterir. * **Etkileşimli olmayan çalıştırmada birden fazla CLI algılandı** (CI, TTY yok) — sor olmadan tüm algılanan CLI'ler için yükler. * **Hiçbiri algılanmadı** — `claude`'ye geri döner, PATH'de ajan ikili bulunamadığı konusunda bir uyarı ile; hook komutu hala yazılır, böylece biri yüklendiğin anda etkinleşir. `policies-config.json`'u doğrudan istediğiniz zaman düzenleyebilirsiniz; değişiklikler bir sonraki hook olayında yeniden başlatma gerekmeden hemen etkili olur. *** ## Örnek: takım varsayılanları ile proje düzeyinde yapılandırma `.failproofai/policies-config.json`'u repo'nuza kaydedin: ```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"] } } } ``` Her geliştirici daha sonra, takım arkadaşlarını etkilemeden kişisel geçersiz kılmalar için `.failproofai/policies-config.local.json` (gitignore'da) oluşturabilir.