> ## 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.

# Configuration

title: التكوين
description: "تنسيق ملف الإعدادات، ونظام النطاقات الثلاثة، وقواعد الدمج"
icon: gear
----------

يستخدم failproofai ملفات إعدادات JSON للتحكم في السياسات المفعلة وكيفية عملها ومن أين يتم تحميل السياسات المخصصة. صُمم التكوين ليكون سهل المشاركة مع فريقك - التزمه في مستودعك وسيحصل كل مطور على نفس شبكة الأمان للوكيل.

***

## نطاقات التكوين

هناك ثلاثة نطاقات للتكوين، يتم تقييمها بترتيب الأولوية:

| النطاق      | مسار الملف                                | الغرض                                                     |
| ----------- | ----------------------------------------- | --------------------------------------------------------- |
| **المشروع** | `.failproofai/policies-config.json`       | إعدادات خاصة بكل مستودع، مرتبطة بمراقبة الإصدار           |
| **محلي**    | `.failproofai/policies-config.local.json` | تجاوزات شخصية لكل مستودع، مستبعدة من git                  |
| **عام**     | `~/.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"]  ← اتحاد منقى من التكرارات
```

**`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"] }   ← المشروع يفوز، يتم تجاهل العام
```

```text theme={null}
project:  (لا توجد إدخالة block-sudo)
local:    (لا توجد إدخالة block-sudo)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← ينتقل إلى العام
```

**`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`

النوع: `string[]`

قائمة أسماء السياسات المراد تفعيلها. يجب أن تطابق الأسماء بالضبط معرفات السياسات التي تظهر من خلال `failproofai policies`. انظر [السياسات المدمجة](/ar/built-in-policies) للحصول على القائمة الكاملة.

السياسات غير الموجودة في `enabledPolicies` تكون غير نشطة، حتى لو كان لديها إدخالات في `policyParams`.

### `policyParams`

النوع: `Record<string, Record<string, unknown>>`

تجاوزات المعاملات لكل سياسة. المفتاح الخارجي هو اسم السياسة؛ والمفاتيح الداخلية خاصة بكل سياسة. تتوثق كل سياسة معاملاتها المتاحة في [السياسات المدمجة](/ar/built-in-policies).

إذا كانت السياسة لها معاملات ولم تحددها، يتم استخدام الإعدادات المدمجة الافتراضية للسياسة. المستخدمون الذين لا يقومون بتكوين `policyParams` على الإطلاق يحصلون على سلوك متطابق مع الإصدارات السابقة.

المفاتيح غير المعروفة داخل كتلة معاملات السياسة يتم تجاهلها بصمت في وقت حدث الخطاف ولكن يتم الإشارة إليها كتحذيرات عند تشغيل `failproofai policies`.

#### `hint` (شامل)

النوع: `string` (اختياري)

رسالة يتم إلحاقها بالسبب عندما تعيد السياسة `deny` أو `instruct`. استخدمها لإعطاء Claude إرشادات قابلة للتنفيذ دون تعديل السياسة نفسها.

يعمل مع أي نوع سياسة — مدمجة، مخصصة (`custom/`)، اتفاقية المشروع (`.failproofai-project/`)، أو اتفاقية المستخدم (`.failproofai-user/`).

```json theme={null}
{
  "policyParams": {
    "block-force-push": {
      "hint": "حاول إنشاء فرع جديد بدلاً من ذلك."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "استخدم apt-get مباشرة بدون sudo."
    },
    "custom/my-policy": {
      "hint": "اطلب موافقة المستخدم أولاً."
    }
  }
}
```

عندما ترفض `block-force-push`، يرى Claude: *"فرض الدفع محظور. حاول إنشاء فرع جديد بدلاً من ذلك."*

القيم غير النصية والنصوص الفارغة يتم تجاهلها بصمت. إذا لم يتم تعيين `hint`، السلوك لا يتغير (متوافق مع الإصدارات السابقة).

### `customPoliciesPath`

النوع: `string` (مسار مطلق)

مسار ملف JavaScript يحتوي على سياسات خطاف مخصصة. يتم تعيينه تلقائياً بواسطة `failproofai policies --install --custom <path>` (يتم حل المسار إلى مطلق قبل التخزين).

يتم تحميل الملف مجدداً في كل حدث خطاف - لا يوجد تخزين مؤقت. انظر [السياسات المخصصة](/ar/custom-policies) لتفاصيل الإنشاء.

### سياسات قائمة على الاتفاقية

بالإضافة إلى `customPoliciesPath` الصريح، يقوم failproofai تلقائياً باكتشاف وتحميل ملفات السياسات من دلائل `.failproofai/policies/`:

| المستوى  | الدليل                     | النطاق                              |
| -------- | -------------------------- | ----------------------------------- |
| المشروع  | `.failproofai/policies/`   | مشاركة مع الفريق عبر مراقبة الإصدار |
| المستخدم | `~/.failproofai/policies/` | شخصي، ينطبق على جميع المشاريع       |

**مطابقة الملفات:** يتم تحميل الملفات فقط التي تتطابق مع `*policies.{js,mjs,ts}` (مثلاً `security-policies.mjs`, `workflow-policies.js`). تُتجاهل الملفات الأخرى في الدليل.

**لا حاجة لإعدادات:** سياسات الاتفاقية لا تتطلب إدخالات في `policies-config.json`. فقط ضع ملفات في الدليل وسيتم التقاطها في حدث الخطاف التالي.

**تحميل الاتحاد:** يتم البحث في دلائل الاتفاقية للمشروع والمستخدم. يتم تحميل جميع الملفات المطابقة من كلا المستويين (على عكس `customPoliciesPath` الذي يستخدم أول نطاق يفوز).

انظر [السياسات المخصصة](/ar/custom-policies) لمزيد من التفاصيل والأمثلة.

### `llm`

النوع: `object` (اختياري)

إعدادات عميل LLM للسياسات التي تقوم بعمليات استدعاء ذكية. غير مطلوبة لمعظم الإعدادات.

```json theme={null}
{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}
```

***

## إدارة الإعدادات من سطر الأوامر

تقوم أوامر `policies --install` و `policies --uninstall` بالكتابة إلى ملف إعدادات خطاف عميل الوكيل (نقاط دخول الخطاف)، بينما `policies-config.json` هو الملف الذي تديره مباشرة. الاثنان منفصلان:

* **إعدادات عميل الوكيل** — يخبر الوكيل باستدعاء `failproofai --hook <event>` في كل استخدام أداة:
  * **Claude Code**: `~/.claude/settings.json` (مستخدم), `<cwd>/.claude/settings.json` (مشروع), `<cwd>/.claude/settings.local.json` (محلي)
  * **OpenAI Codex**: `~/.codex/hooks.json` (مستخدم), `<cwd>/.codex/hooks.json` (مشروع) — Codex ليس له نطاق محلي
  * **GitHub Copilot CLI *(نسخة تجريبية)***: `~/.copilot/hooks/failproofai.json` (مستخدم), `<cwd>/.github/hooks/failproofai.json` (مشروع) — Copilot ليس له نطاق محلي. إدخالات الخطاف تستخدم حقول أوامر Copilot المفتاحة بنظام التشغيل `bash`/`powershell` مع `timeoutSec`؛ يحمل الملف علامة `version: 1` على المستوى الأعلى. دعم GitHub Copilot CLI **نسخة تجريبية** بينما نتحقق من مخطط سجل `events.jsonl` (الذي لا تحدده المستندات العامة) مقابل جلسات حقيقية أكثر.
  * **Cursor Agent *(نسخة تجريبية)***: `~/.cursor/hooks.json` (مستخدم), `<cwd>/.cursor/hooks.json` (مشروع) — Cursor ليس له نطاق محلي. إدخالات الخطاف تستخدم نموذج `{type, command, timeout}` على شكل Claude (لا انقسام `bash`/`powershell`)، لكن يتم تخزينها تحت مفاتيح أحداث camelCase (`preToolUse`, `beforeSubmitPrompt`, …) في مصفوفة مسطحة وفقاً [لمخطط الخطافات](https://cursor.com/docs/hooks) الخاص بـ Cursor؛ يحمل الملف علامة `version: 1` على المستوى الأعلى. يقوم المعالج بتحويل camelCase → PascalCase عبر `CURSOR_EVENT_MAP` بحيث تعمل السياسات المدمجة الموجودة بدون تغيير. دعم Cursor Agent **نسخة تجريبية** بينما نتحقق من نسخة Cursor على القرص (غير محددة في المستندات العامة) مقابل عمليات تثبيت حقيقية أكثر.
  * **OpenCode *(نسخة تجريبية)***: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (مستخدم), `<cwd>/.opencode/opencode.json` + `<cwd>/.opencode/plugins/failproofai.mjs` (مشروع) — OpenCode ليس له نطاق محلي. على عكس المحررات الخمسة الأخرى، OpenCode **ليس له نظام خطاف أوامر خارجية**: يحمل في الذاكرة مكوّنات JavaScript/TypeScript مسجلة بشكل صريح عبر مصفوفة `plugin: []` في `opencode.json` (الاكتشاف التلقائي من `.opencode/plugins/` **ليس** كيف يتم تحميل المكونات على opencode v1.14.33). التثبيت ينقط مكون شيم صغير يستدعي ثنائي failproofai عبر subprocess ويترجم استجابة JSON على شكل Claude الخاصة بالثنائي إلى دلالات المكون: `throw new Error()` لرفض حدث الأداة (يلغي استدعاء الأداة)، `client.session.prompt(...)` للتعليمات **و** لرفض `Stop` / `SubagentStop` (يرسل سبب الرفض كرسالة المستخدم التالية — القناة الوحيدة للإعادة القسرية منذ أن `session.idle` إخطار فقط والرمي منه لا يعمل)، بدون عملية للسماح. يقوم الشيم بتحويل أسماء الأدوات (lowercase → PascalCase عبر `OPENCODE_TOOL_MAP`) ومفاتيح حجج إدخال الأداة (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. الجلسات تعيش في قاعدة بيانات OpenCode SQLite في `~/.local/share/opencode/opencode.db`؛ عارض الجلسات في لوحة التحكم يقرأها عبر `opencode db --format json` و `opencode export <id>`. دعم OpenCode **نسخة تجريبية** بينما نتحقق من السلوك عبر الإصدارات ومقابل جلسات حقيقية أكثر. انظر [مستندات مكونات OpenCode](https://opencode.ai/docs/plugins/).
  * **Pi *(نسخة تجريبية)***: `~/.pi/agent/settings.json` (مستخدم), `<cwd>/.pi/settings.json` (مشروع) — Pi ليس له نطاق محلي. يحمل Pi حزم ملحقات TypeScript عند البدء؛ ملف الإعدادات مصفوفة نصية مسطحة `{"packages": ["./relative/path", …]}`. يكتب failproofai إدخالة مصفوفة حزم واحدة تشير إلى دليل `pi-extension/` المجمع الخاص به. يشترك الملحق داخلياً في أحداث Pi `tool_call` / `user_bash` / `input` / `session_start` ويقذف إلى `failproofai --hook <Event> --cli pi`؛ يقوم المعالج بتحويل underscore\_lower\_snake\_case → PascalCase عبر `PI_EVENT_MAP` بحيث تعمل السياسات المدمجة الموجودة بدون تغيير. يتم أيضاً تحويل حجج إدخال الأداة عبر `PI_TOOL_INPUT_MAP` (تسليم Pi للقراءة / الكتابة / التحرير `path` بدلاً من `file_path`؛ تعيين المفتاح على المستوى الأعلى يسمح بتشغيل `block-env-files` و `block-secrets-write` — `block-read-outside-cwd` كان لديه بالفعل بديل `path`). دعم Pi **نسخة تجريبية** بينما تستقر ملحقات Pi API وتخطيط سجل الجلسة.
  * **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**نطاق المستخدم فقط** — Hermes ليس له إعدادات المشروع/المحلي). Hermes هو **بوابة** Slack/Telegram، لذلك تثبيت واحد يعترض استدعاءات الأدوات من كل منصة (Slack/Telegram/cli/cron) **و** الوكلاء الفرعيين الداخليين. إدخالات الخطاف هي زوج `{command, timeout}` (المهلة الزمنية **بالثواني**) تحت خريطة `hooks:` مفتاحها بأحداث snake\_case من Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); يقوم المعالج بتحويل الأحداث عبر `HERMES_EVENT_MAP` وأسماء الأدوات عبر `HERMES_TOOL_MAP` بحيث تعمل السياسات المدمجة بدون تغيير. يتم تحرير الإعدادات من خلال استدارة YAML `Document` حفاظاً على التعليقات بحيث تبقى الإعدادات الأخرى للمشغل، والتثبيت يعيّن `hooks_auto_accept: true` بحيث تعمل بوابة بدون رأس (لا TTY) الخطافات بدون موجه موافقة. يصدر المقيّم عقد stdout الخاص بـ Hermes `{"decision":"block","reason"}` (يتجاهل Hermes أكواد الخروج). **القيود:** Hermes ليس له حدث نهاية الدور `Stop`، لذا فإن المدمجات `require-*-before-stop` لن تعمل أبداً لـ Hermes (غير قابلة للتطبيق، وليس كسر)؛ `instruct` تنخفض إلى السماح مع ملاحظة مسجلة (لا قناة سياق إضافية)؛ وإعادة تسمية سرية الإخراج (`sanitize-*`) لا يمكن إعادة كتابة إخراج الأداة على عقد shell-hook. Hermes هو **أيضاً** مصدر **تدقيق** غير متصل — لوحة التحكم تقرأ جلسات بوابتها مباشرة من `~/.hermes/state.db`.
* **`policies-config.json`** — يخبر failproofai بالسياسات التي يجب تقييمها وبأية معاملات (مشاركة عبر جميع عملاء الوكيل)

مرر `--cli claude|codex|copilot|cursor|opencode|pi|hermes` لاستهداف وكيل محدد (مفصول بمسافات أو متكرر لأي مجموعة فرعية):

```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`، يكتشف failproofai عملاء الوكيل المثبتة (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`):

* **تم اكتشاف عميل واحد** — يختار ذلك العميل تلقائياً بدون فور.
* **عملاء متعددة مكتشفة** في محطة طرفية تفاعلية — يعرض موجه اختيار مفرد بمفاتيح الأسهم مجمع في قسم `Detected (N)` (مع صف إجمالي للتثبيت لكل عميل مكتشفة N + كل عميل مكتشفة بشكل فردي) وقسم `Not installed (M) · install hooks ahead of time` يسرد كل عميل مكتشفة مدعومة كخيار تثبيت آجل (↑↓ للتحريك، أدخل للاختيار، ^C للخروج). يعرض تدفق الإلغاء قسم Detected فقط.
* **عملاء متعددة مكتشفة** في تشغيل غير تفاعلي (CI، لا TTY) — يثبت لجميع العملاء المكتشفة بدون فور.
* **لم يتم اكتشاف أي** — ينخفض إلى `claude`، مع تحذير بأنه لم يتم العثور على ثنائي وكيل في PATH؛ أمر الخطاف لا يزال مكتوباً بحيث ينشط بمجرد تثبيت واحد.

يمكنك تحرير `policies-config.json` مباشرة في أي وقت؛ التغييرات تصبح نافذة فوراً في حدث الخطاف التالي بدون حاجة إلى إعادة تشغيل.

***

## مثال: إعدادات على مستوى المشروع مع إعدادات افتراضية للفريق

التزم `.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` (مستبعد من git) لتجاوزات شخصية بدون التأثير على زملائك.