> ## Documentation Index > Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260624-1149.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Конфигурация > Формат файла конфигурации, трехуровневая система области действия и правила слияния failproofai использует JSON файлы конфигурации для управления активными политиками, их поведением и местом загрузки пользовательских политик. Конфигурация разработана так, чтобы её было легко делиться с командой — закоммитьте её в ваш репозиторий, и каждый разработчик получит одинаковую сеть безопасности агента. *** ## Области действия конфигурации Существует три области действия конфигурации, оцениваемые по приоритету: | Область | Путь файла | Назначение | | ----------- | ----------------------------------------- | ------------------------------------------------------------------------ | | **project** | `.failproofai/policies-config.json` | Параметры для одного репозитория, закоммичены в систему контроля версий | | **local** | `.failproofai/policies-config.local.json` | Личные переопределения для одного репозитория, игнорируются в .gitignore | | **global** | `~/.failproofai/policies-config.json` | Пользовательские значения по умолчанию для всех проектов | Когда failproofai получает событие хука, он загружает и объединяет все три файла, которые существуют для текущего рабочего каталога. ### Правила слияния **`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"] } ← побеждает project, global игнорируется ``` ```text theme={null} project: (нет записи block-sudo) local: (нет записи block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← переходит на 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` Тип: `string[]` Список имён политик для включения. Имена должны точно совпадать с идентификаторами политик, показанными `failproofai policies`. См. [Built-in Policies](/ru/built-in-policies) для полного списка. Политики, не указанные в `enabledPolicies`, неактивны, даже если у них есть записи в `policyParams`. ### `policyParams` Тип: `Record>` Переопределения параметров для каждой политики. Внешний ключ — имя политики; внутренние ключи — специфичны для политики. Каждая политика документирует свои доступные параметры в [Built-in Policies](/ru/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 видит: *"Force-pushing заблокирован. Попробуйте создать новую ветку вместо этого."* Не строковые значения и пустые строки молча игнорируются. Если `hint` не установлен, поведение не изменяется (обратно совместимо). ### `customPoliciesPath` Тип: `string` (абсолютный путь) Путь к файлу JavaScript, содержащему пользовательские политики хука. Этот путь устанавливается автоматически с помощью `failproofai policies --install --custom ` (путь преобразуется в абсолютный перед сохранением). Файл загружается заново при каждом событии хука — кэширование отсутствует. Подробности разработки см. в [Custom Policies](/ru/custom-policies). ### Политики на основе конвенций В дополнение к явному `customPoliciesPath`, failproofai автоматически обнаруживает и загружает файлы политик из каталогов `.failproofai/policies/`: | Уровень | Каталог | Область | | ------------ | -------------------------- | ------------------------------------------------ | | Проект | `.failproofai/policies/` | Делится с командой через систему контроля версий | | Пользователь | `~/.failproofai/policies/` | Личное, применяется ко всем проектам | **Соответствие файлов:** Загружаются только файлы, соответствующие `*policies.{js,mjs,ts}` (например `security-policies.mjs`, `workflow-policies.js`). Другие файлы в каталоге игнорируются. **Конфигурация не требуется:** Политики конвенций не требуют записей в `policies-config.json`. Просто поместите файлы в каталог, и они будут обнаружены при следующем событии хука. **Объединённая загрузка:** Сканируются оба каталога конвенций проекта и пользователя. Все соответствующие файлы с обоих уровней загружаются (в отличие от `customPoliciesPath`, который использует принцип первой области-победителя). Подробности и примеры см. в [Custom Policies](/ru/custom-policies). ### `llm` Тип: `object` (опционально) Конфигурация LLM клиента для политик, которые выполняют вызовы AI. Не требуется для большинства установок. ```json theme={null} { "llm": { "model": "claude-sonnet-4-6", "apiKey": "sk-ant-..." } } ``` *** ## Управление конфигурацией из CLI Команды `policies --install` и `policies --uninstall` записывают в файл параметров хука вашего CLI агента (точки входа хука), а `policies-config.json` — это файл, которым вы управляете напрямую. Это два отдельных файла: * **Параметры CLI агента** — указывает агенту вызывать `failproofai --hook ` при каждом использовании инструмента: * **Claude Code**: `~/.claude/settings.json` (пользователь), `/.claude/settings.json` (проект), `/.claude/settings.local.json` (локально) * **OpenAI Codex**: `~/.codex/hooks.json` (пользователь), `/.codex/hooks.json` (проект) — Codex не имеет локальной области * **GitHub Copilot CLI *(beta)***: `~/.copilot/hooks/failproofai.json` (пользователь), `/.github/hooks/failproofai.json` (проект) — Copilot не имеет локальной области. Записи хука используют поля команды `bash`/`powershell` Copilot с ключом `timeoutSec`; файл содержит маркер уровня верхнего уровня `version: 1`. Поддержка Copilot CLI находится в **beta**, пока мы проверяем схему записи `events.jsonl` (которую не указывает официальная документация) против более реальных сессий. * **Cursor Agent *(beta)***: `~/.cursor/hooks.json` (пользователь), `/.cursor/hooks.json` (проект) — Cursor не имеет локальной области. Записи хука используют форму в стиле Claude `{type, command, timeout}` (без разделения `bash`/`powershell`), но сохраняются под ключами событий в camelCase (`preToolUse`, `beforeSubmitPrompt`, …) в плоском массиве согласно [схеме хуков](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` (пользователь), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (проект) — OpenCode не имеет локальной области. В отличие от других шести CLI, OpenCode имеет **отсутствие системы внешних командных хуков**: он загружает встроенные плагины JS/TS, явно зарегистрированные через массив `plugin: []` в `opencode.json` (автообнаружение из `.opencode/plugins/` **не** является способом загрузки плагинов в opencode v1.14.33). Установка помещает небольшой созданный шим плагина, который вызывает двоичный файл failproofai в подпроцессе и переводит ответ JSON двоичного файла в семантику плагина: `throw new Error()` для отклонения события инструмента (отменяет вызов инструмента), `client.session.prompt(...)` для instruct И для отклонения `Stop` / `SubagentStop` (отправляет причину отклонения в качестве следующего сообщения пользователя — единственный канал принудительного повторного попытки, так как `session.idle` доступна только для уведомлений и выброс из неё не работает), и no-op для allow. Шим канонизирует как имена инструментов (нижний регистр → 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. Сессии живут в БД SQLite OpenCode в `~/.local/share/opencode/opencode.db`; средство просмотра сессий панели управления читает их через `opencode db --format json` и `opencode export `. Поддержка OpenCode находится в **beta**, пока мы проверяем поведение в разных версиях и против более реальных сессий. См. [документацию плагинов OpenCode](https://opencode.ai/docs/plugins/). * **Pi *(beta)***: `~/.pi/agent/settings.json` (пользователь), `/.pi/settings.json` (проект) — Pi не имеет локальной области. Pi загружает пакеты расширений TypeScript при запуске; файл параметров — это плоский массив строк `{"packages": ["./relative/path", …]}`. failproofai записывает единственную запись массива пакетов, указывающую на свой встроенный каталог `pi-extension/`. Расширение внутри подписывается на события `tool_call` / `user_bash` / `input` / `session_start` Pi и запускает `failproofai --hook --cli pi`; обработчик канонизирует underscore\_lower\_snake\_case → PascalCase через `PI_EVENT_MAP`, поэтому существующие встроенные политики срабатывают без изменений. Аргументы входа инструмента также канонизируются через `PI_TOOL_INPUT_MAP` (Read / Write / Edit Pi доставляют `path` вместо `file_path`; отображение верхнего уровня ключа позволяет `block-env-files` и `block-secrets-write` срабатывать — `block-read-outside-cwd` уже имел fallback `path`). Поддержка Pi находится в **beta**, пока стабилизируются API расширений Pi и макет журнала сессий. * **Gemini CLI *(beta)***: `~/.gemini/settings.json` (пользователь), `/.gemini/settings.json` (проект) — Gemini не имеет локальной области (документирует область `system` в `/etc/gemini-cli/settings.json`, которую failproofai не предоставляет). Записи хука используют форму Claude `{type, command, timeout}`, завёрнутую в схему сопоставителя 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" Gemini контракт exit-0), `{hookSpecificOutput: {hookEventName, additionalContext}}` для внедрения контекста на BeforeAgent / AfterTool / SessionStart и `{decision: "block", reason}` на AfterAgent для семантики принудительного повторного попытки. Поддержка Gemini CLI находится в **beta**, пока мы расширяем реальное покрытие. См. [документацию хуков Gemini CLI](https://geminicli.com/docs/hooks/). * **`policies-config.json`** — указывает failproofai, какие политики оценивать и с какими параметрами (общее для всех CLI агентов) Передайте `--cli claude|codex|copilot|cursor|opencode|pi|gemini` для целевого агента (разделённые пробелом или повторяемые для любого подмножества): ```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 обнаружен** — автоматически выбирает этот CLI без запроса. * **Несколько CLI обнаружены** в интерактивном терминале — показывает запрос одиночного выбора со стрелками, сгруппированный в раздел `Detected (N)` (с агрегированной строкой `Install for all N detected` + каждый обнаруженный CLI отдельно) и раздел `Not installed (M) · install hooks ahead of time`, перечисляющий каждый необнаруженный поддерживаемый CLI как опцию предварительной установки (↑↓ для перемещения, Enter для выбора, ^C для выхода). Поток удаления показывает только раздел Detected. * **Несколько CLI обнаружены** в неинтерактивном запуске (CI, нет TTY) — устанавливает для всех обнаруженных CLI без запроса. * **Ничего не обнаружено** — возвращается к `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` (игнорируется в gitignore) для личных переопределений без воздействия на товарищей по команде.