> ## 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. # תצורה > פורמט קובץ קונפיגורציה, מערכת בעלת שלוש הערכות, וכללי מיזוג failproofai משתמש בקבצי JSON של תצורה לשליטה בכללים פעילים, בהתנהגותם, ובמקום טעינת כללים מותאמים. התצורה מעוצבת להיות קלה לשיתוף עם הצוות שלך - עמוד אותה בריפו שלך וכל מפתח יקבל את אותו רשת בטיחות לסוכן. *** ## היקפי תצורה ישנם שלוש היקפי תצורה, המוערכים לפי סדר עדיפויות: | Scope | File path | Purpose | | ----------- | ----------------------------------------- | ------------------------------------- | | **project** | `.failproofai/policies-config.json` | הגדרות לפי ריפו, תופסות בשליטה גרסאות | | **local** | `.failproofai/policies-config.local.json` | דריסות אישיות לפי ריפו, gitignored | | **global** | `~/.failproofai/policies-config.json` | ברירות מחדל ברמת משתמש בכל הפרויקטים | כאשר failproofai מקבל אירוע hook, הוא טוען ומוזג את כל שלושת הקבצים שקיימים עבור ספריית העבודה הנוכחית. ### כללי מיזוג **`enabledPolicies`** - איחוד של כל שלושת ההיקפים. כלל שמופעל בכל רמה פעיל. ```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"] ← deduplicated union ``` **`policyParams`** - ההיקף הראשון שמגדיר פרמטרים לכלל מסוים מנצח לחלוטין. אין מיזוג עמוק של ערכים בתוך פרמטרים של כלל. ```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 wins, global ignored ``` ```text theme={null} project: (no block-sudo entry) local: (no block-sudo entry) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← falls through to global ``` **`customPoliciesPath`** - ההיקף הראשון שמגדיר אותו מנצח. **`llm`** - ההיקף הראשון שמגדיר אותו מנצח. *** ## פורמט קובץ קונפיגורציה ```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" } ``` *** ## הפניה לשדות ### `enabledPolicies` Type: `string[]` רשימת שמות כללים להפעלה. השמות חייבים להתאים בדיוק למזהי הכללים המוצגים על ידי `failproofai policies`. ראה [Built-in Policies](/he/built-in-policies) לקבלת הרשימה המלאה. כללים שאינם ב-`enabledPolicies` אינם פעילים, גם אם יש להם ערכים ב-`policyParams`. ### `policyParams` Type: `Record>` דריסות פרמטרים לפי כלל. המפתח החיצוני הוא שם הכלל; המפתחות הפנימיים הם ספציפיים לכלל. כל כלל מתעד את הפרמטרים הזמינים שלו ב-[Built-in Policies](/he/built-in-policies). אם לכלל יש פרמטרים אך אתה לא מציין אותם, משתמשים בברירות המחדל המובנות של הכלל. משתמשים שלא מגדירים `policyParams` בכלל מקבלים התנהגות זהה לגרסאות קודמות. מפתחות לא ידועים בתוך בלוק פרמטרים של כלל מתעלמים בשקט בעת הפעלת hook אך מסומנים כאזהרות כאשר אתה מריץ `failproofai policies`. #### `hint` (cross-cutting) Type: `string` (optional) הודעה שמצורפת לסיבה כאשר כלל מחזיר `deny` או `instruct`. השתמש בה כדי להדריך את Claude עם הנחיות ניתנות לפעולה מבלי לשנות את הכלל עצמו. עובד עם כל סוג כלל — מובנה, מותאם (`custom/`), קונבנציה של פרויקט (`.failproofai-project/`), או קונבנציה של משתמש (`.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." } } } ``` כאשר `block-force-push` מסרב, Claude רואה: *"Force-pushing is blocked. Try creating a fresh branch instead."* ערכים שאינם string ומחרוזות ריקות מתעלמים בשקט. אם `hint` אינו מוגדר, ההתנהגות לא משתנית (תואמת לאחור). ### `customPoliciesPath` Type: `string` (absolute path) נתיב לקובץ JavaScript המכיל כללים מותאמים לחטיפה. זה מוגדר באופן אוטומטי על ידי `failproofai policies --install --custom ` (הנתיב מומר להנחלה מוחלטת לפני שהוא מאוחסן). הקובץ נטען מחדש בכל אירוע hook - אין קשימון. ראה [Custom Policies](/he/custom-policies) לפרטי יצירה. ### כללים מבוססי קונבנציה בנוסף ל-`customPoliciesPath` המפורש, failproofai גם גילוי ותיקטון באופן אוטומטי קבצי כללים מספריות `.failproofai/policies/`: | Level | Directory | Scope | | ------- | -------------------------- | ------------------------------ | | Project | `.failproofai/policies/` | משותף עם הצוות דרך בקרת גרסאות | | User | `~/.failproofai/policies/` | אישי, חל על כל הפרויקטים | **התאמת קבצים:** רק קבצים התואמים `*policies.{js,mjs,ts}` נטענים (למשל `security-policies.mjs`, `workflow-policies.js`). קבצים אחרים בספרייה מתעלמים. **אין צורך בקונפיגורציה:** כללי קונבנציה אינם דורשים ערכים ב-`policies-config.json`. פשוט צניח קבצים לתוך הספרייה והם יילקחו בחדוות אירוע hook הבא. **טעינת איחוד:** גם ספריות קונבנציה של פרויקט וגם משתמש נסרקות. כל הקבצים המתאימים משתי הרמות נטענים (בניגוד ל-`customPoliciesPath` שמשתמש בניצחון ההיקף הראשון). ראה [Custom Policies](/he/custom-policies) לפרטים ודוגמאות נוספים. ### `llm` Type: `object` (optional) תצורת לקוח LLM לכללים העורכים קריאות AI. לא נדרש לרוב ההגדרות. ```json theme={null} { "llm": { "model": "claude-sonnet-4-6", "apiKey": "sk-ant-..." } } ``` *** ## ניהול תצורה מה-CLI הפקודות `policies --install` ו-`policies --uninstall` כותבות לקובץ הגדרות hook של ה-CLI של הסוכן שלך (נקודות הכניסה של hook), בעוד `policies-config.json` הוא הקובץ שאתה מנהל ישירות. השניים נפרדים: * **הגדרות סוכן CLI** — אומר לסוכן להתקשר `failproofai --hook ` בכל שימוש בכלי: * **Claude Code**: `~/.claude/settings.json` (user), `/.claude/settings.json` (project), `/.claude/settings.local.json` (local) * **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — Codex אין לו היקף `local` * **GitHub Copilot CLI *(beta)***: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot אין לו היקף `local`. ערכי Hook משתמשים בשדות הפקודה `bash`/`powershell` של Copilot עם `timeoutSec`; הקובץ נושא סימן `version: 1` ברמה עליונה. תמיכת Copilot CLI היא **beta** בזמן שאנו מאמתים את סכמת רשומות `events.jsonl` (שהתיעוד הציבורי אינו מציין) מול יותר הפעלות בעולם האמיתי. * **Cursor Agent *(beta)***: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor אין לו היקף `local`. ערכי Hook משתמשים בצורה `{type, command, timeout}` בצורת Claude (אין חלוקה `bash`/`powershell`), אך מאוחסנים תחת מפתחות אירוע camelCase (`preToolUse`, `beforeSubmitPrompt`, …) במערך שטוח לפי [סכמת hooks](https://cursor.com/docs/hooks) של Cursor; הקובץ נושא סימן `version: 1` ברמה עליונה. המטפל קנוני camelCase → PascalCase דרך `CURSOR_EVENT_MAP` כך שכללים מובנים קיימים יורים ללא שינוי. תמיכת Cursor Agent היא **beta** בזמן שאנו מאמתים את תמלול של Cursor על דיסק (לא מצוין בתיעוד הציבורי) מול יותר התקנות בעולם האמיתי. * **OpenCode *(beta)***: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode אין לו היקף `local`. בניגוד לשישת ה-CLIs האחרים, OpenCode **אין לו מערכת hook חיצונית**: הוא טוען בתהליך JS/TS plugins שנרשמו במפורש דרך המערך `plugin: []` ב-`opencode.json` (auto-discovery מ-`.opencode/plugins/` אינו כיצד plugins טוענים ב-opencode v1.14.33). Install טוען קובץ זעיר שנוצר של plugin שקורא subprocess לבינארי failproofai ותורגם את התגובה JSON של הבינארי חזרה לסמנטיקה של plugin: `throw new Error()` להכחשת אירוע כלי (מבטל את קריאת הכלי), `client.session.prompt(...)` עבור instruct וגם עבור `Stop` / `SubagentStop` deny (שולח את סיבת ההכחשה כהודעת המשתמש הבאה — ערוץ force-retry היחיד מאז `session.idle` הוא notification-only והשלכת זה אינו פעולה), ו-no-op לאפשרות. קובץ קנוני שם של כלי (lowercase → PascalCase דרך `OPENCODE_TOOL_MAP`) וקלידי arg של כניסת כלי (camelCase → snake\_case דרך `OPENCODE_TOOL_INPUT_MAP` עבור `Read` / `Write` / `Edit`, למשל `filePath` → `file_path`, `oldString` → `old_string`) לפני שידור לבינארי, כך שבנויים של בדיקת נתיב כמו `block-read-outside-cwd`, `block-env-files`, ו-`block-secrets-write` יורים ללא שינוי על קריאות כלי OpenCode. הפעלות חיות בבסיס נתונים SQLite של opencode ב-`~/.local/share/opencode/opencode.db`; מערכת הדפים של הלוח קוראת אותם דרך `opencode db --format json` ו-`opencode export `. תמיכת OpenCode היא **beta** בזמן שאנו מאמתים התנהגות בחדוות וגרסאות מול יותר הפעלות בעולם האמיתי. ראה את [תיעוד plugins של OpenCode](https://opencode.ai/docs/plugins/). * **Pi *(beta)***: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi אין לו היקף `local`. Pi טוען חבילות הרחבה TypeScript בעת ההפעלה; הקובץ הגדרות הוא מערך string שטוח `{"packages": ["./relative/path", …]}`. failproofai כותב ערך מערך packages אחד המצביע על ספרייה `pi-extension/` משובצת שלו. ההרחבה מבחינים פנימיים במחזור subscriptions של Pi כדי `tool_call` / `user_bash` / `input` / `session_start` ופירות לתוך `failproofai --hook --cli pi`; המטפל קנוני underscore\_lower\_snake\_case → PascalCase דרך `PI_EVENT_MAP` כך שכללים מובנים קיימים יורים ללא שינוי. קלידי arg של כניסת כלי גם קנוניים דרך `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit מסירה `path` רמוק מאשר `file_path`; קלידי המפתח העליון מאפשר `block-env-files` ו-`block-secrets-write` לירות — `block-read-outside-cwd` כבר היה `path` fallback). תמיכת Pi היא **beta** בזמן שעומדת ל-stabilize. * **Gemini CLI *(beta)***: `~/.gemini/settings.json` (user), `/.gemini/settings.json` (project) — Gemini אין לו היקף `local` (הוא מתעד היקף `system` ב-`/etc/gemini-cli/settings.json` אשר failproofai לא חשוף). Hook entries משתמשים בצורה `{type, command, timeout}` של Claude עטופה בסכמת matcher של Gemini `{matcher, hooks: [...]}` עם `matcher: "*"` כברירת מחדל. אירועים הם PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); המטפל ממפה לשמות קנוניים של Claude דרך `GEMINI_EVENT_MAP`. שמות כלים הם snake\_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — המטפל מקנוני דרך `GEMINI_TOOL_MAP` כך שכללים מובנים קיימים יורים ללא שינוי. משקיף מדיניות משיג צורה שטוחה של Gemini `{decision: "deny", reason}` (מועדפת לכל Golden Rule exit-0 של Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` להזרקת הקשר ב-BeforeAgent / AfterTool / SessionStart, ו-`{decision: "block", reason}` ב-AfterAgent לסמנטיקה force-retry. תמיכת Gemini CLI היא **beta** בזמן שאנו מגדילים כיסוי בעולם האמיתי. ראה את [תיעוד hooks של Gemini CLI](https://geminicli.com/docs/hooks/). * **`policies-config.json`** — אומר ל-failproofai אילו כללים להעריך וויים פרמטרים (משותף בכל סוכני CLI) עבור `--cli claude|codex|copilot|cursor|opencode|pi|gemini` למטרה סוכן ספציפי (space-separated או חוזר לכל תת-קבוצה): ```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 ``` כאשר `--cli` מושמט, `failproofai` מגלה אילו סוכני CLI מותקנים (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): * **CLI אחד detected** — בחר אוטומטי את זה CLI ללא הנמקה. * **מספר CLIs detected** בטרמינל אינטראקטיבי — מציג בחירה יחידה במקלדת בחצים מקובצת לחלק `Detected (N)` (עם שורה מצטברת `Install for all N detected` + כל CLI detected בנפרד) וחלק `Not installed (M) · install hooks ahead of time` רשימה כל CLI שלא detected כאפשרות forward-install (↑↓ להעברה, Enter לבחירה, ^C לצאת). זרימת ה-uninstall מציגה רק את חלק Detected. * **מספר CLIs detected** בריצה לא אינטראקטיבית (CI, no TTY) — מתקן להמון detected CLIs ללא הנמקה. * **None detected** — חוזר ל-`claude`, עם אזהרה שלא binary agent נמצא ב-PATH; פקודת hook עדיין כתובה כך היא מופעלת ברגע שאתה מתקן אחד. אתה יכול לערוך `policies-config.json` ישירות בכל עת; שינויים ישפיעו מיד על אירוע hook הבא ללא צורך בהפעלה מחדש. *** ## דוגמה: תצורה ברמת פרויקט עם ברירות מחדל של צוות Commit `.failproofai/policies-config.json` לריפו שלך: ```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"] } } } ``` כל מפתח יכול ליצור `.failproofai/policies-config.local.json` (gitignored) עבור דריסות אישיות ללא הפרעה לעמיתים.