参考

配置参考

facade.json 接受哪些字段、默认值是什么，以及 Facade 怎么应用它们。

顶层字段

通过Agent 配置打开文件。它接受 JSON 注释和末尾逗号，写一个空对象就全部使用默认值。

字段	值	默认
`type`	`claude`、`codex`、`agy`、`muse`、`opencode`、`pi` 或 `custom`。	条目名与内置 ID 完全相同时可省略；新增条目必填。
`command`	一个可执行程序名或路径。	该 type 在 PATH 中的命令；custom 必填。
`args`	原样传入的参数字符串数组。	`[]`
`env`	变量名对应字符串或 `null`。	`{}`
`model`	非空白的模型 ID。	由 CLI 决定。OpenCode 和 custom 不接受。
`effort`	CLI 和模型支持的非空白 effort。	由 CLI 决定。OpenCode 和 custom 不接受。
`enabled`	布尔值，控制以后的启动和恢复。	`true`
`icon`	内置 CLI ID 或受支持的机器人图标。	对应 type 的图标；custom 用 `facade-pearl`。

配置内置条目要用它精确的小写 ID，比如 codex。新条目的名字不能和任何内置 ID 或显示名称相同，仅大小写不同也算重复；例如用 Codex · work，不要用 Codex。新增条目不会继承同类型内置条目的设置。

enabled: false 会让一个本来有效的条目不显示，也不允许再启动或恢复它。已经在运行的 Agent 不受影响。

facade.json

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

在已经打开的集成终端里设置变量，不会更新编辑器宿主的环境。要在打开编辑器之前就让它可用。

Facade 先看这次启动指定的模型和 effort，再看条目的默认值。两处都没有，就由 CLI 决定。OpenCode 的这两项都在它自己的配置里。

内置 type 的模型和 effort 要用专用字段。Facade 还会设置审批、对话 ID、工作目录和自己的工具；与这些冲突、或者会妨碍交互式启动的参数，它都会拒绝。

Facade 在 Facade home 里找 facade.json：先看 VS Code 的 Facade: Home 设置，再看 FACADE_HOME，最后是 ~/.facade。从某个项目打开 Open Settings，看到的就是它实际用的文件。

整个文件出错，比如 JSON 无效、键重复或顶层字段不认识，会阻止新的启动和恢复。单个 CLI 条目出错，只有这个条目不可用。运行中的 Agent 继续运行。

按报错给出的设置路径改那个值。Facade 不会悄悄改用旧配置。常见的启动和模型服务错误见排查问题。