Pular para o conteúdo principal
Auxiliares de configuração para edições não interativas em openclaw.json: obtêm/definem/aplicam patch/removem/mostram arquivo/esquema/validam valores por caminho e imprimem o arquivo de configuração ativo. Execute sem um subcomando para abrir o assistente de configuração (o mesmo que openclaw configure).
Quando OPENCLAW_NIX_MODE=1, o OpenClaw trata openclaw.json como imutável. Comandos somente leitura, como config get, config file, config schema e config validate, ainda funcionam, mas gravadores de configuração recusam alterações. Agents devem editar a fonte Nix da instalação em vez disso; para a distribuição nix-openclaw oficial, use Início rápido do nix-openclaw e defina valores em programs.openclaw.config ou instances.<name>.config.

​
Opções raiz

​
--section <section>
string
Filtro repetível de seção de configuração guiada ao executar openclaw config sem um subcomando.
Seções guiadas compatíveis: workspace, model, web, gateway, daemon, channels, plugins, skills, health.

​
Exemplos

openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json

​
config schema

Imprime o esquema JSON gerado para openclaw.json em stdout como JSON.
  • O esquema de configuração raiz atual, além de um campo de string $schema raiz para ferramentas de editor.
  • Metadados de documentação title e description de campos usados pela Control UI.
  • Nós de objeto aninhado, curinga (*) e item de array ([]) herdam os mesmos metadados title / description quando existe documentação de campo correspondente.
  • Ramificações anyOf / oneOf / allOf também herdam os mesmos metadados de documentação quando existe documentação de campo correspondente.
  • Metadados de esquema de Plugin + canal ao vivo em melhor esforço quando os manifestos de runtime podem ser carregados.
  • Um esquema de fallback limpo mesmo quando a configuração atual é inválida.
config.schema.lookup retorna um caminho de configuração normalizado com um nó de esquema superficial (title, description, type, enum, const, limites comuns), metadados de dica de UI correspondentes e resumos dos filhos imediatos. Use-o para navegação detalhada com escopo de caminho na Control UI ou em clientes personalizados.
openclaw config schema
Redirecione para um arquivo quando quiser inspecionar ou validar com outras ferramentas: 
openclaw config schema > openclaw.schema.json

​
Caminhos

Caminhos usam notação com ponto ou colchetes. Coloque caminhos com notação de colchetes entre aspas nos exemplos de shell para que shells como zsh não expandam [0] como um glob antes que o OpenClaw receba o caminho: 
openclaw config get agents.defaults.workspace
openclaw config get 'agents.list[0].id'
Use o índice da lista de agents para direcionar um agent específico: 
openclaw config get agents.list
openclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"

​
Valores

Os valores são analisados como JSON5 quando possível; caso contrário, são tratados como strings. Use --strict-json para exigir análise JSON padrão sem fallback para string. --json continua compatível como um alias legado para --strict-json. 
openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
Quando --strict-json está ativado, sintaxe exclusiva de JSON5, como comentários, vírgulas finais ou chaves de objeto sem aspas, é rejeitada. Omita --strict-json para análise de valores JSON5 com fallback de string bruta. config get <path> --json imprime o valor bruto como JSON em vez de texto formatado para terminal.
A atribuição de objeto substitui o caminho de destino por padrão. Caminhos protegidos de mapas/listas que normalmente contêm entradas adicionadas pelo usuário, como agents.defaults.models, models.providers, models.providers.<id>.models, plugins.entries e auth.profiles, recusam substituições que removeriam entradas existentes, a menos que você passe --replace.
Use --merge ao adicionar entradas a esses mapas: 
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge
Use --replace somente quando você intencionalmente quiser que o valor fornecido se torne o valor de destino completo.

​
Modos de config set

openclaw config set é compatível com quatro estilos de atribuição: 
openclaw config set <path> <value>
Atribuições SecretRef são rejeitadas em superfícies mutáveis em runtime sem suporte (por exemplo, hooks.token, commands.ownerDisplaySecret, tokens de Webhook de vinculação de threads do Discord e JSON de credenciais do WhatsApp). Consulte Superfície de credenciais SecretRef.
A análise em lote sempre usa a carga em lote (--batch-json/--batch-file) como fonte da verdade. --strict-json / --json não alteram o comportamento de análise em lote.

​
config patch

Use config patch quando quiser colar ou enviar por pipe um patch com formato de configuração em vez de executar muitos comandos config set baseados em caminho. A entrada é um objeto JSON5. Objetos são mesclados recursivamente, arrays e valores escalares substituem o valor de destino, e null exclui o caminho de destino. 
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config patch --file ./openclaw.patch.json5
Você também pode enviar um patch por stdin, o que é útil para scripts de configuração remota: 
ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5
Exemplo de patch: 
{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
      groupPolicy: "open",
      requireMention: false,
    },
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
      dmPolicy: "disabled",
      dm: { enabled: false },
      groupPolicy: "allowlist",
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}
Use --replace-path <path> quando um objeto ou array deve se tornar exatamente o valor fornecido em vez de receber patch recursivamente: 
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'
--dry-run executa verificações de esquema e resolubilidade de SecretRef sem gravar. SecretRefs baseados em exec são ignorados por padrão durante dry-run; adicione --allow-exec quando quiser intencionalmente que o dry-run execute comandos de provedor. O modo de caminho/valor JSON continua compatível tanto para SecretRefs quanto para provedores: 
openclaw config set channels.discord.token \
  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
  --strict-json

openclaw config set secrets.providers.vaultfile \
  '{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
  --strict-json

​
Flags do construtor de provedor

Destinos do construtor de provedor devem usar secrets.providers.<alias> como caminho.
  • --provider-source <env|file|exec>
  • --provider-timeout-ms <ms> (file, exec)
  • --provider-allowlist <ENV_VAR> (repetível)
  • --provider-path <path> (obrigatório)
  • --provider-mode <singleValue|json>
  • --provider-max-bytes <bytes>
  • --provider-allow-insecure-path
  • --provider-command <path> (obrigatório)
  • --provider-arg <arg> (repetível)
  • --provider-no-output-timeout-ms <ms>
  • --provider-max-output-bytes <bytes>
  • --provider-json-only
  • --provider-env <KEY=VALUE> (repetível)
  • --provider-pass-env <ENV_VAR> (repetível)
  • --provider-trusted-dir <path> (repetível)
  • --provider-allow-insecure-path
  • --provider-allow-symlink-command
Exemplo de provedor exec reforçado: 
openclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/openclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-json-only \
  --provider-pass-env VAULT_TOKEN \
  --provider-trusted-dir /usr/local/bin \
  --provider-timeout-ms 5000

​
Dry run

Use --dry-run para validar alterações sem gravar openclaw.json. 
openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run \
  --json

openclaw config set channels.discord.token \
  --ref-provider vault \
  --ref-source exec \
  --ref-id discord/token \
  --dry-run \
  --allow-exec
  • Modo builder: executa verificações de resolubilidade de SecretRef para refs/provedores alterados.
  • Modo JSON (--strict-json, --json ou modo em lote): executa validação de esquema mais verificações de resolubilidade de SecretRef.
  • A validação de política também é executada para superfícies de destino de SecretRef conhecidamente incompatíveis.
  • As verificações de política avaliam a configuração completa pós-alteração, portanto gravações em objetos pai (por exemplo, definir hooks como um objeto) não podem contornar a validação de superfície incompatível.
  • As verificações de SecretRef exec são ignoradas por padrão durante a simulação para evitar efeitos colaterais de comandos.
  • Use --allow-exec com --dry-run para aceitar verificações de SecretRef exec (isso pode executar comandos do provedor).
  • --allow-exec é somente para simulação e gera erro se usado sem --dry-run.
--dry-run --json imprime um relatório legível por máquina:
  • ok: se a simulação passou
  • operations: número de atribuições avaliadas
  • checks: se as verificações de esquema/resolubilidade foram executadas
  • checks.resolvabilityComplete: se as verificações de resolubilidade foram executadas até a conclusão (false quando refs exec são ignoradas)
  • refsChecked: número de refs realmente resolvidas durante a simulação
  • skippedExecRefs: número de refs exec ignoradas porque --allow-exec não foi definido
  • errors: falhas estruturadas de caminho ausente, esquema ou resolubilidade quando ok=false

​
Formato da saída JSON

{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder" | "unset", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "missing-path" | "schema" | "resolvability",
      message: string,
      ref?: string, // present for resolvability errors
    },
  ],
}

{
  "ok": true,
  "operations": 1,
  "configPath": "~/.openclaw/openclaw.json",
  "inputModes": ["builder"],
  "checks": {
    "schema": false,
    "resolvability": true,
    "resolvabilityComplete": true
  },
  "refsChecked": 1,
  "skippedExecRefs": 0
}
  • config schema validation failed: o formato da sua configuração pós-alteração é inválido; corrija o caminho/valor ou o formato do objeto de provedor/ref.
  • Config policy validation failed: unsupported SecretRef usage: mova essa credencial de volta para entrada em texto simples/string e mantenha SecretRefs somente em superfícies compatíveis.
  • SecretRef assignment(s) could not be resolved: o provedor/ref referenciado atualmente não pode resolver (variável de ambiente ausente, ponteiro de arquivo inválido, falha do provedor exec ou incompatibilidade entre provedor/origem).
  • Dry run note: skipped <n> exec SecretRef resolvability check(s): a simulação ignorou refs exec; execute novamente com --allow-exec se você precisar validar a resolubilidade exec.
  • Para o modo em lote, corrija as entradas com falha e execute --dry-run novamente antes de gravar.

​
Segurança de gravação

openclaw config set e outros gravadores de configuração pertencentes ao OpenClaw validam a configuração completa pós-alteração antes de gravá-la no disco. Se o novo payload falhar na validação de esquema ou parecer uma substituição destrutiva, a configuração ativa fica intacta e o payload rejeitado é salvo ao lado dela como openclaw.json.rejected.*.
O caminho da configuração ativa deve ser um arquivo regular. Layouts de openclaw.json com symlink não são compatíveis para gravações; use OPENCLAW_CONFIG_PATH para apontar diretamente para o arquivo real.
Prefira gravações pela CLI para pequenas edições: 
openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate
Se uma gravação for rejeitada, inspecione o payload salvo e corrija o formato da configuração completa: 
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate
Gravações diretas pelo editor ainda são permitidas, mas o Gateway em execução as trata como não confiáveis até que sejam validadas. Edições diretas inválidas falham na inicialização ou são ignoradas pelo recarregamento a quente; o Gateway não regrava openclaw.json. Execute openclaw doctor --fix para reparar configuração prefixada/substituída ou restaurar a última cópia conhecida como válida. Consulte Solução de problemas do Gateway. A recuperação de arquivo inteiro é reservada ao reparo pelo doctor. Alterações no esquema do Plugin ou divergência de minHostVersion permanecem explícitas em vez de reverter configurações de usuário não relacionadas, como modelos, provedores, perfis de autenticação, canais, exposição do Gateway, ferramentas, memória, navegador ou configuração de cron.

​
Subcomandos

  • config file: imprime o caminho do arquivo de configuração ativo (resolvido a partir de OPENCLAW_CONFIG_PATH ou do local padrão). O caminho deve indicar um arquivo regular, não um symlink.
Reinicie o Gateway após as edições.

​
Validar

Valide a configuração atual em relação ao esquema ativo sem iniciar o Gateway. 
openclaw config validate
openclaw config validate --json
Depois que openclaw config validate estiver passando, você poderá usar a TUI local para que um agente incorporado compare a configuração ativa com a documentação enquanto você valida cada alteração no mesmo terminal:
Se a validação já estiver falhando, comece com openclaw configure ou openclaw doctor --fix. openclaw chat não contorna a proteção contra configuração inválida.
openclaw chat
Então, dentro da TUI: 
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor
Ciclo típico de reparo:
1

Comparar com a documentação

Peça ao agente para comparar sua configuração atual com a página relevante da documentação e sugerir a menor correção.
2

Aplicar edições direcionadas

Aplique edições direcionadas com openclaw config set ou openclaw configure.
3

Validar novamente

Execute openclaw config validate novamente após cada alteração.
4

Usar doctor para problemas de runtime

Se a validação passar, mas o runtime ainda não estiver íntegro, execute openclaw doctor ou openclaw doctor --fix para obter ajuda com migração e reparo.

​
Relacionado