# 配置参考

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

## 顶层字段

通过[Agent 配置](https://facadecode.com/zh-cn/docs/settings/)打开文件。它接受 JSON 注释和末尾逗号，写一个空对象就全部使用默认值。

| 字段 | 值 | 默认 |
| --- | --- | --- |
| `yolo` | 布尔值，控制 CLI 审批和 Agent 访问范围。 | `true` |
| `names` | 非空白名字组成的列表，作为 Agent 的建议名字。 | 内置名字列表 |
| `clis` | 对象，包含内置条目的覆盖和新增的命名条目。 | `{}`，内置 CLI 仍然可用 |
| `$schema` | 字符串，供编辑器读取 schema。 | 省略 |

## CLI 条目字段

| 字段 | 值 | 默认 |
| --- | --- | --- |
| `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 不受影响。

## 环境变量

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

- 字符串会设置变量，`null` 会删除变量，没写的变量沿用原值。
- `${env:NAME}` 读取编辑器宿主的环境，不读同一个对象里的其他键。
- 引用的变量不存在时，这个条目不可用。引用只在 `env` 的值里展开一次，不在 `args` 里展开。
- 直接写的值会留在 facade.json 里。用环境引用可以让值不进这个文件，但 CLI 拿到的仍是展开后的值。

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

## 优先级与启动选项

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 不会悄悄改用旧配置。常见的启动和模型服务错误见[排查问题](https://facadecode.com/zh-cn/docs/troubleshooting/)。