Facade Code設定參考
查詢 facade.json 的欄位、預設值，以及 Facade 套用這些設定的方式。
最上層欄位
透過Agent 設定開啟這個檔案。它接受 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。
環境變數值
{
"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 不會默默改用舊設定。常見的啟動與供應商錯誤請見疑難排解。