# 設定參考

查詢 facade.json 的欄位、預設值，以及 Facade 套用這些設定的方式。

## 最上層欄位

透過[Agent 設定](https://facadecode.com/zh-tw/docs/settings/)開啟這個檔案。它接受 JSON 註解與尾端逗號。空物件代表使用預設值。

| 欄位 | 值 | 預設值 |
| --- | --- | --- |
| `yolo` | 控制 CLI 核准與 Agent 存取範圍的布林值。 | `true` |
| `names` | 建議的 Agent 名稱清單；名稱不可為空白。 | 內建名稱清單 |
| `clis` | 包含內建項目覆寫與其他具名項目的物件。 | `{}`；內建 CLI 仍可使用 |
| `$schema` | 供編輯器結構描述使用的字串。 | 省略 |

## CLI 項目欄位

| 欄位 | 值 | 預設值 |
| --- | --- | --- |
| `type` | `claude`、`codex`、`agy`、`muse`、`opencode`、`pi` 或 `custom`。 | 完全符合內建 ID 時可省略；新增項目則為必填。 |
| `command` | 一個執行檔名稱或路徑。 | 類型在 PATH 上的命令；custom 為必填。 |
| `args` | 原樣傳入的參數字串陣列。 | `[]` |
| `env` | 變數名稱對應到字串或 null。 | `{}` |
| `model` | 非空白的模型 ID。 | 由 CLI 決定。OpenCode 與 custom 不接受。 |
| `effort` | 非空白、且 CLI 與模型支援的 effort。 | 由 CLI 決定。OpenCode 與 custom 不接受。 |
| `enabled` | 控制之後能否啟動與還原的布林值。 | `true` |
| `icon` | 內建 CLI ID 或支援的機器人圖示。 | 類型圖示；custom 為 `facade-pearl`。 |

要設定內建項目，請使用完全一致的小寫 ID，例如 `codex`。新增項目的名稱不能與任何內建 ID 或顯示名稱重複，即使大小寫不同也不行。例如請用 `Codex · work`，不要用 `Codex`。新增的項目不會繼承同類型內建項目的設定。

`enabled: false` 會隱藏一個原本有效的項目，並拒絕之後的啟動或還原。它不會停止已在執行的 Agent。

## 環境變數值

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

- 字串代表設定變數。`null` 代表移除變數。未列出的變數會沿用繼承值。
- `${env:NAME}` 會讀取編輯器主機的環境變數，不會讀取同一個物件中的其他鍵。
- 參照的變數不存在時，該項目會變成無法使用。參照只會在 `env` 的值中展開一次，不會在 `args` 中展開。
- 直接寫入的值會留在 facade.json 中。使用環境變數參照可讓該值不寫進檔案，但 CLI 仍會收到展開後的值。

在已開啟的整合式終端機中設定變數，不會更新編輯器主機的環境。請在啟動編輯器之前就讓該變數可用。

## 優先順序與啟動選項

模型與 effort 都會先採用為新 Agent 指定的值，再使用項目的預設值；若某個欄位在這兩處都未設定，則由 CLI 決定。OpenCode 的這兩項選擇都放在它自己的設定中。

內建類型請使用專用的 model 與 effort 欄位。Facade 也會設定權限、對話 ID、工作資料夾以及自己的工具。Facade 也會拒絕與這些選擇衝突，或會導致互動式工作階段無法啟動的參數。

Facade 會在 Facade home 中尋找 facade.json：先看 VS Code 設定中的 **Facade: Home**，再看 `FACADE_HOME`，最後才是 `~/.facade`。請從專案開啟 Open Settings，找出目前生效的檔案。

## 檔案錯誤與項目錯誤

檔案層級的錯誤，例如 JSON 格式不正確、重複的鍵或未知的最上層欄位，會阻擋新的啟動與還原。單一 CLI 項目內的錯誤只會讓該項目無法使用。執行中的 Agent 不受影響。

請依照錯誤訊息指出的設定路徑修正該值。Facade 不會默默改用舊設定。常見的啟動與供應商錯誤請見[疑難排解](https://facadecode.com/zh-tw/docs/troubleshooting/)。