> ## 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. # 設定 > 設定ファイルのフォーマット、3つのスコープ、マージルール failproofai は JSON 設定ファイルを使用して、どのポリシーを有効にするか、それらの動作、カスタムポリシーのロード元を制御します。設定はチームと共有しやすい設計になっています。リポジトリにコミットすれば、すべての開発者が同じエージェントの安全網を利用できます。 *** ## 設定スコープ 設定には3つのスコープがあり、優先順位の高い順に評価されます： | スコープ | ファイルパス | 目的 | | ----------- | ----------------------------------------- | ------------------------------ | | **project** | `.failproofai/policies-config.json` | リポジトリごとの設定。バージョン管理にコミット | | **local** | `.failproofai/policies-config.local.json` | 個人用のリポジトリごとの上書き設定。gitignore 対象 | | **global** | `~/.failproofai/policies-config.json` | すべてのプロジェクトに適用されるユーザーレベルのデフォルト | failproofai がフックイベントを受信すると、現在の作業ディレクトリに存在する3つのファイルすべてをロードしてマージします。 ### マージルール **`enabledPolicies`** — 3つのスコープの和集合。いずれかのレベルで有効になっているポリシーはアクティブになります。 ```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` で表示されるポリシー識別子と完全に一致する必要があります。完全なリストは[組み込みポリシー](/ja/built-in-policies)を参照してください。 `enabledPolicies` に含まれていないポリシーは、`policyParams` にエントリがあっても無効です。 ### `policyParams` 型: `Record>` ポリシーごとのパラメーター上書き設定。外側のキーはポリシー名、内側のキーはポリシー固有のものです。各ポリシーで使用可能なパラメーターは[組み込みポリシー](/ja/built-in-policies)に記載されています。 ポリシーにパラメーターがある場合でも指定しなければ、そのポリシーの組み込みデフォルト値が使用されます。`policyParams` を設定しないユーザーは、以前のバージョンと同じ動作になります。 ポリシーのパラメーターブロック内の未知のキーは、フック実行時には無視されますが、`failproofai policies` を実行すると警告として表示されます。 #### `hint`（横断的設定） 型: `string`（省略可能） ポリシーが `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.」* 文字列以外の値や空文字列は無視されます。`hint` が設定されていない場合は従来の動作と変わりません（後方互換性あり）。 ### `customPoliciesPath` 型: `string`（絶対パス） カスタムフックポリシーを含む JavaScript ファイルへのパス。`failproofai policies --install --custom ` によって自動的に設定されます（パスは保存前に絶対パスに解決されます）。 ファイルはフックイベントのたびに再読み込みされます。キャッシュは行われません。作成方法の詳細は[カスタムポリシー](/ja/custom-policies)を参照してください。 ### 規約ベースのポリシー 明示的な `customPoliciesPath` に加えて、failproofai は `.failproofai/policies/` ディレクトリからポリシーファイルを自動的に検出してロードします： | レベル | ディレクトリ | スコープ | | ------ | -------------------------- | ----------------- | | プロジェクト | `.failproofai/policies/` | バージョン管理を通じてチームと共有 | | ユーザー | `~/.failproofai/policies/` | 個人用。すべてのプロジェクトに適用 | **ファイルのマッチング:** `*policies.{js,mjs,ts}` に一致するファイルのみロードされます（例：`security-policies.mjs`、`workflow-policies.js`）。ディレクトリ内のその他のファイルは無視されます。 **設定不要:** 規約ポリシーは `policies-config.json` へのエントリが不要です。ディレクトリにファイルを置くだけで、次のフックイベント時に自動的に読み込まれます。 **ユニオンロード:** プロジェクトとユーザーの規約ディレクトリが両方スキャンされます。両方のレベルから一致したすべてのファイルがロードされます（`customPoliciesPath` が最初のスコープ優先なのとは異なります）。 詳細と例は[カスタムポリシー](/ja/custom-policies)を参照してください。 ### `llm` 型: `object`（省略可能） AI 呼び出しを行うポリシーのための LLM クライアント設定。ほとんどの環境では不要です。 ```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 には `local` スコープがありません * **GitHub Copilot CLI *(beta)***: `~/.copilot/hooks/failproofai.json`（ユーザー）、`/.github/hooks/failproofai.json`（プロジェクト）— Copilot には `local` スコープがありません。フックエントリは Copilot の OS キー付き `bash`/`powershell` コマンドフィールドと `timeoutSec` を使用し、ファイルにはトップレベルの `version: 1` マーカーが付きます。`events.jsonl` レコードスキーマ（公開ドキュメントに記載なし）を実際の使用環境で検証中のため、Copilot CLI のサポートは**ベータ版**です。 * **Cursor Agent *(beta)***: `~/.cursor/hooks.json`（ユーザー）、`/.cursor/hooks.json`（プロジェクト）— Cursor には `local` スコープがありません。フックエントリは Claude 形式の `{type, command, timeout}` を使用しますが、Cursor の[フックスキーマ](https://cursor.com/docs/hooks)に従いキャメルケースのイベントキー（`preToolUse`、`beforeSubmitPrompt` など）のフラット配列として保存され、ファイルにはトップレベルの `version: 1` マーカーが付きます。ハンドラーは `CURSOR_EVENT_MAP` を通じてキャメルケース → PascalCase に正規化するため、既存の組み込みポリシーはそのまま動作します。Cursor のトランスクリプトのオンディスクフォーマット（公開ドキュメントに未記載）を実際の環境で検証中のため、Cursor Agent のサポートは**ベータ版**です。 * **OpenCode *(beta)***: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs`（ユーザー）、`/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs`（プロジェクト）— OpenCode には `local` スコープがありません。他の5つの CLI とは異なり、OpenCode には**外部コマンドフックシステムがありません**。`opencode.json` の `plugin: []` 配列で明示的に登録された JS/TS プラグインをインプロセスでロードします（`.opencode/plugins/` からの自動検出は opencode v1.14.33 でのプラグインロード方法では**ありません**）。インストール時に小さな生成プラグインシムが配置され、failproofai バイナリをサブプロセスで呼び出し、バイナリの Claude 形式 JSON レスポンスをプラグインセマンティクスに変換します：ツールイベントの deny には `throw new Error()`（ツール呼び出しをキャンセル）、instruct および `Stop` / `SubagentStop` の deny には `client.session.prompt(...)`（deny の理由を次のユーザーメッセージとして送信 — `session.idle` が通知専用で例外をスローしても無効なため、強制リトライの唯一のチャネル）、allow には no-op を使用します。シムはツール名（小文字 → `OPENCODE_TOOL_MAP` を通じた PascalCase）とツール入力引数のキー（`OPENCODE_TOOL_INPUT_MAP` を通じたキャメルケース → スネークケース：`Read` / `Write` / `Edit` の `filePath` → `file_path`、`oldString` → `old_string` など）を正規化してからバイナリに転送するため、`block-read-outside-cwd`、`block-env-files`、`block-secrets-write` などのパスチェック組み込みポリシーは OpenCode のツール呼び出しでもそのまま動作します。セッションは `~/.local/share/opencode/opencode.db` の OpenCode の SQLite DB に保存され、ダッシュボードのセッションビューアーは `opencode db --format json` と `opencode export ` を通じて読み取ります。バージョン間の動作や実際の使用環境での検証中のため、OpenCode のサポートは**ベータ版**です。[OpenCode プラグインドキュメント](https://opencode.ai/docs/plugins/)を参照してください。 * **Pi *(beta)***: `~/.pi/agent/settings.json`（ユーザー）、`/.pi/settings.json`（プロジェクト）— Pi には `local` スコープがありません。Pi は起動時に TypeScript 拡張パッケージをロードします。設定ファイルはフラットな文字列配列 `{"packages": ["./relative/path", …]}` です。failproofai はバンドルされた `pi-extension/` ディレクトリを指す単一の packages 配列エントリを書き込みます。拡張機能は内部で Pi の `tool_call` / `user_bash` / `input` / `session_start` イベントを購読し、`failproofai --hook --cli pi` をシェルアウトします。ハンドラーは `PI_EVENT_MAP` を通じてアンダースコア付き小文字スネークケース → PascalCase に正規化するため、既存の組み込みポリシーはそのまま動作します。ツール入力引数も `PI_TOOL_INPUT_MAP` を通じて正規化されます（Pi の Read / Write / Edit は `file_path` ではなく `path` を使用。トップレベルキーのマッピングにより `block-env-files` と `block-secrets-write` が動作します — `block-read-outside-cwd` にはすでに `path` フォールバックがあります）。Pi の拡張 API とセッションログのレイアウトが安定化するまで Pi のサポートは**ベータ版**です。 * **Hermes (hermes-agent)**: `~/.hermes/config.yaml`（**ユーザースコープのみ** — Hermes にはプロジェクト/ローカル設定がありません）。Hermes は Slack/Telegram の**ゲートウェイ**であるため、1回のインストールでSlack/Telegram/cli/cron など全プラットフォームからのツール呼び出しと内部サブエージェントを傍受します。フックエントリは Hermes のスネークケースイベント（`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`）をキーとする `hooks:` マップ下の `{command, timeout}` ペア（タイムアウトは**秒**単位）です。ハンドラーは `HERMES_EVENT_MAP` でイベントを、`HERMES_TOOL_MAP` でツール名を正規化するため、組み込みポリシーはそのまま動作します。設定はコメントを保持する YAML `Document` のラウンドトリップで編集されるため、オペレーターの他の設定は保持されます。インストール時に `hooks_auto_accept: true` が設定されるため、ヘッドレスゲートウェイ（TTY なし）は同意プロンプトなしでフックを実行します。評価器は Hermes の `{"decision":"block","reason"}` stdout 契約を出力します（Hermes は終了コードを無視）。**制限事項:** Hermes にはターン終了の `Stop` イベントがないため、`require-*-before-stop` 組み込みポリシーは動作しません（非適用、バグではありません）。`instruct` は allow-with-logged-note に降格します（追加コンテキストチャネルなし）。出力シークレットのリダクション（`sanitize-*`）はシェルフックの契約上ツール出力を書き換えられません。Hermes は**オフライン監査**ソースでもあり、ダッシュボードはゲートウェイセッションを `~/.hermes/state.db` から直接読み取ります。 * **`policies-config.json`** — failproofai が評価するポリシーとそのパラメーターを指定します（すべてのエージェント CLI で共有） 特定のエージェントを対象にするには `--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` はインストール済みのエージェント CLI を自動検出します（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`）： * **CLI が1つ検出された場合** — プロンプトなしでその 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 にインストールします。 * **何も検出されない場合** — エージェントバイナリが PATH に見つからないという警告とともに `claude` にフォールバックします。フックコマンドは書き込まれるため、インストール後すぐに有効になります。 `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 対象）を作成できます。