Перейти к основному содержанию

​
title: Конфигурация description: “Формат файла конфигурации, трёхуровневая система и правила слияния” icon: gear

failproofai использует JSON файлы конфигурации для управления активными политиками, их поведением и источниками пользовательских политик. Конфигурация разработана так, чтобы её было легко делиться с командой — закоммитьте её в репозиторий, и каждый разработчик получит одинаковую защиту агента.

​
Уровни конфигурации

Существует три уровня конфигурации, оцениваемые в порядке приоритета:
УровеньПуть файлаНазначение
project.failproofai/policies-config.jsonНастройки репозитория, коммитятся в систему контроля версий
local.failproofai/policies-config.local.jsonЛичные переопределения на уровне репозитория, в .gitignore
global~/.failproofai/policies-config.jsonПользовательские стандартные значения для всех проектов
Когда failproofai получает событие hook, он загружает и объединяет все три существующих файла для текущей директории.

​
Правила слияния

enabledPolicies — объединение всех трёх уровней. Политика, активированная на любом уровне, работает. 
project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← объединение без дубликатов
policyParams — первый уровень, определивший параметры для данной политики, полностью выигрывает. Нет глубокого слияния значений в параметрах политики. 
project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← выигрывает project, global игнорируется

project:  (нет записи block-sudo)
local:    (нет записи block-sudo)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← переходит на global
customPoliciesPath — первый уровень, определивший его, выигрывает. llm — первый уровень, определивший его, выигрывает.

​
Формат файла конфигурации

{
  "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. Политики, отсутствующие в enabledPolicies, неактивны, даже если у них есть записи в policyParams.

​
policyParams

Тип: Record<string, Record<string, unknown>> Переопределения параметров для каждой политики. Внешний ключ — имя политики; внутренние ключи — специфичны для политики. Каждая политика документирует свои доступные параметры в разделе Built-in Policies. Если политика имеет параметры, но вы их не указали, используются встроенные значения по умолчанию политики. Пользователи, которые вообще не конфигурируют policyParams, получают идентичное поведение с предыдущими версиями. Неизвестные ключи в блоке параметров политики молча игнорируются при срабатывании hook, но отмечаются как предупреждения при выполнении failproofai policies.

​
hint (кросс-функциональный)

Тип: string (опционально) Сообщение, добавляемое к причине, когда политика возвращает deny или instruct. Используйте его, чтобы дать Claude практические рекомендации без изменения самой политики. Работает с любым типом политики — встроенной, пользовательской (custom/), проектной конвенции (.failproofai-project/) или пользовательской конвенции (.failproofai-user/). 
{
  "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 файлу, содержащему пользовательские hook политики. Устанавливается автоматически командой failproofai policies --install --custom <path> (путь преобразуется в абсолютный перед сохранением). Файл загружается заново при каждом события hook — кеширования нет. Детали разработки см. в разделе Custom Policies.

​
Политики на основе конвенций

В дополнение к явному customPoliciesPath, failproofai автоматически обнаруживает и загружает файлы политик из директорий .failproofai/policies/:
УровеньДиректорияУровень
Project.failproofai/policies/Общая с командой через систему контроля версий
User~/.failproofai/policies/Личная, применяется ко всем проектам
Соответствие файлов: Загружаются только файлы, соответствующие маске *policies.{js,mjs,ts} (например, security-policies.mjs, workflow-policies.js). Другие файлы в директории игнорируются. Конфигурация не требуется: Политики на основе конвенций не требуют записей в policies-config.json. Просто поместите файлы в директорию, и они будут обнаружены при следующем событии hook. Загрузка объединением: Сканируются обе директории конвенций — проектная и пользовательская. Загружаются все соответствующие файлы с обоих уровней (в отличие от customPoliciesPath, который использует first-scope-wins). Детали и примеры см. в разделе Custom Policies.

​
llm

Тип: object (опционально) Конфигурация LLM клиента для политик, делающих AI вызовы. Не требуется для большинства установок. 
{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​
Управление конфигурацией через CLI

Команды policies --install и policies --uninstall записывают в settings.json Claude Code (точки входа для hook), в то время как policies-config.json — это файл, который вы управляете напрямую. Это два отдельных файла:
  • settings.json — указывает Claude Code вызывать failproofai --hook <event> при каждом использовании инструмента
  • policies-config.json — указывает failproofai, какие политики оценивать и с какими параметрами
Вы можете редактировать policies-config.json напрямую в любое время; изменения вступают в силу на следующем события hook без необходимости перезагрузки.

​
Пример: конфигурация на уровне проекта с командными стандартами

Закоммитьте .failproofai/policies-config.json в ваш репозиторий: 
{
  "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) для личных переопределений без влияния на коллег.