# 設定リファレンス

facade.json のフィールド、既定値、Facade による適用方法を確認します。

## トップレベルのフィールド

ファイルは[エージェント設定](https://facadecode.com/ja/docs/settings/)から開きます。JSON のコメントと末尾のカンマを受け付けます。空のオブジェクトを書くと既定値が使われます。

| フィールド | 値 | 既定値 |
| --- | --- | --- |
| `yolo` | CLI の承認とエージェントのアクセスを制御する真偽値。 | `true` |
| `names` | 空でないエージェント名の候補リスト。 | 組み込みの名前リスト |
| `clis` | 組み込みの上書きと、追加した名前付きエントリーを含むオブジェクト。 | `{}`。組み込み CLI は引き続き利用可能 |
| `$schema` | エディターのスキーマメタデータ用の文字列。 | 省略 |

## CLI エントリーのフィールド

| フィールド | 値 | 既定値 |
| --- | --- | --- |
| `type` | `claude`、`codex`、`agy`、`muse`、`opencode`、`pi`、または `custom`。 | エントリー名が組み込み ID と完全一致する場合は自動的に決まります。追加したエントリーでは必須です。 |
| `command` | 実行ファイル名またはパスを 1 つ。 | PATH 上のタイプ標準のコマンド。custom では必須です。 |
| `args` | 引数を表す文字列の配列。 | `[]` |
| `env` | 変数名を文字列または null にマッピングしたもの。 | `{}` |
| `model` | 空でないモデル ID。 | CLI が決定します。OpenCode と custom では使用できません。 |
| `effort` | CLI とモデルがサポートする空でない effort。 | CLI が決定します。OpenCode と custom では使用できません。 |
| `enabled` | 今後の起動と復元を制御する真偽値。 | `true` |
| `icon` | 組み込み CLI の ID または対応するロボットアイコン。 | タイプのアイコン。custom では `facade-pearl`。 |

`codex` のような組み込みエントリーを設定するには、正確な小文字の ID を使用します。新しいエントリーには、大文字と小文字を区別せず、すべての組み込み ID および表示名と異なる名前を付ける必要があります。たとえば `Codex` ではなく `Codex · work` を使用します。追加したエントリーは、同じタイプの組み込みエントリーの設定を継承しません。

`enabled: false` を設定すると、有効なエントリーが非表示になり、今後の起動や復元が拒否されます。実行中のエージェントは停止しません。

## 環境変数の値

```json
{
  "clis": {
    "codex": {
      "env": {
        "WORK_API_KEY": "${env:WORK_API_KEY}",
        "OLD_TOKEN": null
      }
    }
  }
}
```

- 文字列を指定すると変数が設定されます。`null` を指定すると削除されます。省略した変数は継承されます。
- `${env:NAME}` はエディターホストの環境を読み取ります。同じオブジェクト内の別のキーは読み取りません。
- 参照先が見つからない場合、そのエントリーは利用できなくなります。参照は `env` の値で 1 回だけ展開され、`args` では展開されません。
- リテラル値を書くと facade.json に残ります。環境変数の参照を使えばその値をファイルに残さずに済みますが、CLI には展開後の値が渡されます。

すでに開いている統合ターミナルで変数を設定しても、エディターホストの環境は更新されません。エディターを起動する前に変数を利用できるようにしてください。

## 優先順位と起動オプション

Facade はまず新しいエージェントに指定されたモデルと effort を使い、次にエントリーの既定値を使います。どちらにも値がない場合は CLI が決定します。OpenCode はどちらの選択も独自の設定で管理します。

組み込みタイプでは、モデルと effort に専用のフィールドを使用します。Facade は権限、会話 ID、作業フォルダー、独自のツールも設定します。これらの選択と競合する引数や、対話セッションの起動を妨げる引数は拒否されます。

Facade は Facade ホームで facade.json を探します。優先順位は VS Code 設定の **Facade: Home**（設定されている場合）、`FACADE_HOME`、`~/.facade` の順です。現在使用している設定ファイルを確認するには、対象のプロジェクトから Open Settings を開きます。

## ファイルのエラーとエントリーのエラー

JSON が無効、キーの重複、未知のトップレベルフィールドなど、ファイル全体のエラーが発生すると、新しい起動と復元ができなくなります。CLI エントリー内のエラーは、そのエントリーだけが利用できなくなります。実行中のエージェントは動き続けます。

エラーが示す設定パスに従って、その値を修正してください。Facade が古い設定を黙って代用することはありません。よくある起動エラーとプロバイダーのエラーについては、[トラブルシューティング](https://facadecode.com/ja/docs/troubleshooting/)を参照してください。