Configuração

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).

Opções raiz

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="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 fileopenclaw config --section modelopenclaw config --section gateway --section daemonopenclaw config schemaopenclaw config get browser.executablePathopenclaw 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 --mergeopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKENopenclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode jsonopenclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config unset plugins.entries.brave.config.webSearch.apiKeyopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-runopenclaw config validateopenclaw config validate --json

config schema

Imprime o esquema JSON gerado para openclaw.json em stdout como JSON.

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.workspaceopenclaw config get 'agents.list[0].id'

Use o índice da lista de agents para direcionar um agent específico:

openclaw config get agents.listopenclaw 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-jsonopenclaw 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.

Use --merge ao adicionar entradas a esses mapas:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw 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>

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

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-timeout-ms 5000

openclaw config set --batch-json '[  {    "path": "secrets.providers.default",    "provider": { "source": "env" }  },  {    "path": "channels.discord.token",    "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }  }]'

openclaw config set --batch-file ./config-set.batch.json --dry-run

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-runopenclaw 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.json5ssh 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.

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

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}

{  "ok": false,  "operations": 1,  "configPath": "~/.openclaw/openclaw.json",  "inputModes": ["builder"],  "checks": {    "schema": false,    "resolvability": true,    "resolvabilityComplete": true  },  "refsChecked": 1,  "skippedExecRefs": 0,  "errors": [    {      "kind": "resolvability",      "message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",      "ref": "env:default:MISSING_TEST_SECRET"    }  ]}

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.*.

Prefira gravações pela CLI para pequenas edições:

openclaw config set gateway.reload.mode hybrid --dry-runopenclaw config set gateway.reload.mode hybridopenclaw 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 | headopenclaw 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 validateopenclaw 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:

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:

Relacionado

• Referência da CLI
• Configuração