# Referência de configuração

Consulte os campos de facade.json, seus padrões e como o Facade os aplica.

## Campos de nível superior

Abra o arquivo em [Configurações dos agentes](https://facadecode.com/pt-br/docs/settings/). Ele aceita comentários JSON e vírgulas finais. Um objeto vazio usa os padrões.

| Campo | Valor | Padrão |
| --- | --- | --- |
| `yolo` | Booleano que controla as aprovações da CLI e o acesso entre agentes. | `true` |
| `names` | Lista de nomes sugeridos para agentes, sem itens em branco. | Lista de nomes nativa |
| `clis` | Objeto com substituições das CLIs nativas e entradas adicionais nomeadas. | `{}`; as CLIs nativas continuam disponíveis |
| `$schema` | String para metadados de esquema do editor. | Omitido |

## Campos de uma entrada de CLI

| Campo | Valor | Padrão |
| --- | --- | --- |
| `type` | `claude`, `codex`, `agy`, `muse`, `opencode`, `pi` ou `custom`. | Implícito para IDs nativos exatos; obrigatório para entradas adicionadas. |
| `command` | Um nome de executável ou caminho. | Comando do tipo no PATH; obrigatório para custom. |
| `args` | Array de strings de argumentos literais. | `[]` |
| `env` | Nomes de variáveis mapeados para strings ou null. | `{}` |
| `model` | ID de modelo não vazio. | A CLI decide. Não aceito para OpenCode ou custom. |
| `effort` | Esforço não vazio com suporte na CLI e no modelo. | A CLI decide. Não aceito para OpenCode ou custom. |
| `enabled` | Booleano que controla inicializações futuras e a restauração. | `true` |
| `icon` | ID de CLI nativa ou ícone de robô compatível. | Ícone do tipo; `facade-pearl` para custom. |

Use o ID exato em minúsculas para configurar uma entrada nativa, como `codex`. Uma entrada nova precisa ter um nome diferente de todos os IDs e nomes de exibição nativos, independentemente de maiúsculas e minúsculas. Por exemplo, use `Codex · work` em vez de `Codex`. Entradas adicionadas não herdam configurações da entrada nativa do tipo delas.

`enabled: false` oculta uma entrada válida e impede inicializações futuras ou restaurações. Isso não para um agente que já está rodando.

## Valores de ambiente

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

- Uma string define uma variável. `null` a remove. Uma variável omitida é herdada.
- `${env:NAME}` lê o ambiente do host do editor. Ele não lê outra chave no mesmo objeto.
- Uma referência ausente torna essa entrada indisponível. Referências são expandidas uma vez nos valores de `env`, não em `args`.
- Um valor literal permanece no facade.json. Uma referência de ambiente mantém esse valor fora do arquivo, mas a CLI ainda recebe o valor expandido.

Definir uma variável em um terminal integrado que já está aberto não atualiza o ambiente do host do editor. Disponibilize-a antes de iniciar o editor.

## Precedência e opções de inicialização

O Facade usa primeiro qualquer modelo e esforço especificados para o novo agente e, depois, os padrões da entrada. Para cada campo, se nenhuma dessas fontes definir um valor, a CLI decide. O OpenCode mantém as duas escolhas na própria configuração.

Para tipos nativos, use os campos dedicados de modelo e esforço. O Facade também define permissões, IDs de conversa, pastas de trabalho e as próprias ferramentas. Ele recusa argumentos que conflitem com essas escolhas ou que impeçam o início de uma sessão interativa.

O Facade procura o facade.json na home do Facade: a configuração **Facade: Home** do VS Code, se definida, depois `FACADE_HOME` e então `~/.facade`. No projeto, execute Open Settings para localizar o arquivo em uso.

## Erros de arquivo e erros de entrada

Um erro no nível do arquivo, como JSON inválido, chave duplicada ou campo desconhecido no nível superior, bloqueia novas inicializações e a restauração. Um erro dentro de uma entrada de CLI torna apenas essa entrada indisponível. Agentes em execução continuam rodando.

Siga o caminho da configuração indicado no erro e corrija aquele valor. O Facade não substitui configurações antigas silenciosamente. Veja [Solução de problemas](https://facadecode.com/pt-br/docs/troubleshooting/) para erros comuns de inicialização e de provedor.