CLI commands

Configuração

Auxiliares não interativos para openclaw.json: obtenha/defina/aplique patch/remova um valor por caminho, imprima o esquema, valide ou imprima o caminho do arquivo ativo. Execute openclaw config sem subcomando para abrir o mesmo assistente guiado de openclaw configure.

Opções raiz

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="string"> Filtro repetível de seção da configuração guiada ao executar openclaw config sem um subcomando.

Seções guiadas: workspace, model, web, gateway, daemon, channels, plugins, skills, health.

Exemplos

bash

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

Caminhos

Notação por pontos ou colchetes. Coloque caminhos com colchetes entre aspas nos exemplos de shell para que o zsh não expanda [0] como um padrão glob:

bash

openclaw config get agents.defaults.workspaceopenclaw config get 'agents.list[0].id'openclaw config get agents.listopenclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"

`config get`

Lê um valor do instantâneo censurado da configuração (segredos nunca são impressos). --json imprime o valor bruto como JSON; caso contrário, strings/números/booleanos são impressos sem formatação adicional, enquanto objetos/matrizes são impressos como JSON formatado.

bash

openclaw config get browser.executablePathopenclaw config get agents.defaults.model --json

`config file`

Imprime o caminho do arquivo de configuração ativo, resolvido com base em OPENCLAW_CONFIG_PATH ou no local padrão. O caminho identifica um arquivo comum, não um link simbólico; consulte Segurança de gravação.

`config schema`

Imprime no stdout o esquema JSON gerado para openclaw.json.

O que está incluído

O esquema atual da configuração raiz, além de um campo de string $schema na raiz para ferramentas do editor.
Metadados de documentação title / description dos campos usados pela interface de controle.
Nós de objetos aninhados, curingas (*) e itens de matriz ([]) herdam os mesmos metadados title / description quando existe documentação correspondente para os campos.
Ramificações anyOf / oneOf / allOf também herdam os mesmos metadados de documentação.
Metadados de esquema de plugins + canais ativos, obtidos por melhor esforço quando os manifestos de runtime podem ser carregados.
Um esquema alternativo limpo mesmo quando a configuração atual é inválida.

RPC de runtime relacionado

config.schema.lookup retorna um caminho normalizado da configuração com um nó de esquema superficial (title, description, type, enum, const, limites comuns), metadados correspondentes de dicas da interface e resumos dos filhos imediatos. Use-o para detalhamento com escopo de caminho na interface de controle ou em clientes personalizados.

bash

openclaw config schemaopenclaw config schema > openclaw.schema.json

`config validate`

Valida a configuração atual em relação ao esquema ativo sem iniciar o Gateway.

bash

openclaw config validateopenclaw config validate --json

Valores

Os valores são analisados como JSON5 quando possível; caso contrário, são tratados como strings brutas. Use --strict-json para exigir JSON padrão sem fallback para string (sintaxes exclusivas do JSON5, como comentários, vírgulas finais ou chaves sem aspas, serão rejeitadas). --json é um alias legado de --strict-json em config set.

bash

openclaw config set agents.defaults.heartbeat.every "0m"openclaw config set gateway.port 19001 --strict-jsonopenclaw config set channels.whatsapp.groups '["*"]' --strict-json

config get <path> --json imprime o valor bruto como JSON em vez de texto formatado para o terminal.

Use --merge ao adicionar entradas a esses mapas:

bash

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 o valor fornecido deva se tornar intencionalmente o valor completo do destino.

Modos de `config set`

Modo de valor

bash

openclaw config set <path> <value>

Modo construtor de SecretRef

bash

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

Modo construtor de provedor

Destina-se somente a caminhos secrets.providers.<alias>:

bash

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

Modo em lote

bash

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" }  }]'

bash

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

A análise em lote sempre usa a carga do lote (--batch-json/--batch-file) como fonte da verdade; --strict-json / --json não alteram o comportamento da análise em lote.

O modo de caminho/valor JSON também funciona diretamente para SecretRefs e provedores:

bash

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

Os destinos do construtor de provedor devem usar secrets.providers.<alias> como caminho.

Flags comuns

--provider-source <env|file|exec>
--provider-timeout-ms <ms> (file, exec)

Provedor de ambiente (--provider-source env)

--provider-allowlist <ENV_VAR> (repetível)

Provedor de arquivo (--provider-source file)

--provider-path <path> (obrigatório)
--provider-mode <singleValue|json>
--provider-max-bytes <bytes>
--provider-allow-insecure-path

Provedor de execução (--provider-source exec)

--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 de execução reforçado:

bash

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

`config patch`

Cole ou canalize um patch JSON5 com o formato da configuração em vez de executar vários comandos config set baseados em caminhos. Objetos são mesclados recursivamente; matrizes e valores escalares substituem o destino; null exclui o caminho de destino.

bash

openclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config patch --file ./openclaw.patch.json5

Canalize um patch pela entrada padrão para scripts de configuração remota:

bash

ssh user@gateway-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5ssh user@gateway-host 'openclaw config patch --stdin' < ./openclaw.patch.json5

Exemplo de patch:

json5

{  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.6-sol" },      models: {        "openai/gpt-5.6-sol": { params: { fastMode: true } },      },    },  },}

Use --replace-path <path> quando um objeto ou matriz precisar se tornar exatamente o valor fornecido em vez de receber um patch recursivo:

bash

openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'

--dry-run executa verificações do esquema e da capacidade de resolução de SecretRef sem gravar. SecretRefs baseadas em execução são ignoradas por padrão durante a simulação; adicione --allow-exec quando quiser intencionalmente que a simulação execute comandos do provedor.

Simulação

--dry-run valida as alterações sem gravar em openclaw.json. Disponível em config set, config patch e config unset.

bash

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

Comportamento da simulação

Modo construtor: executa verificações de resolução de SecretRef para referências/provedores alterados.
Modo JSON (--strict-json, --json ou modo em lote): executa a validação do esquema e verificações de resolução de SecretRef.
A validação de política é executada em relação à configuração completa após a alteração, portanto gravações de objetos pai (por exemplo, definir hooks como um objeto) não podem contornar a validação de superfícies não compatíveis.
As verificações de SecretRef de execução são ignoradas por padrão para evitar efeitos colaterais de comandos; passe --allow-exec para ativá-las (isso pode executar comandos do provedor). --allow-exec funciona apenas na simulação e gera um erro sem --dry-run.

Campos de --dry-run --json

ok: se a simulação foi aprovada
operations: número de atribuições avaliadas
checks: se as verificações de esquema/resolução foram executadas
checks.resolvabilityComplete: se as verificações de resolução foram executadas até a conclusão (falso quando referências de execução são ignoradas)
refsChecked: número de referências efetivamente resolvidas durante a simulação
skippedExecRefs: número de referências de execução ignoradas porque --allow-exec não foi definido
errors: falhas estruturadas de caminho ausente, esquema ou resolução quando ok=false

Estrutura da saída JSON

json5

{  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, // presente para erros de resolução    },  ],}

Exemplo de sucesso

json

{  "ok": true,  "operations": 1,  "configPath": "~/.openclaw/openclaw.json",  "inputModes": ["builder"],  "checks": {    "schema": false,    "resolvability": true,    "resolvabilityComplete": true  },  "refsChecked": 1,  "skippedExecRefs": 0}

Exemplo de falha

json

{  "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"    }  ]}

Se a simulação falhar

config schema validation failed: o formato da configuração após a alteração é inválido; corrija o caminho/valor ou o formato do objeto de provedor/referência.
Config policy validation failed: unsupported SecretRef usage: mova essa credencial de volta para uma entrada de texto simples/string; mantenha SecretRefs apenas em superfícies compatíveis.
SecretRef assignment(s) could not be resolved: o provedor/referência indicado não pode ser resolvido no momento (variável de ambiente ausente, ponteiro de arquivo inválido, falha do provedor de execução ou incompatibilidade entre provedor e origem).
Dry run note: skipped <n> exec SecretRef resolvability check(s): execute novamente com --allow-exec se precisar validar a resolução de execução.
No modo em lote, corrija as entradas com falha e execute novamente --dry-run antes de gravar.

Aplicação das alterações

Após cada execução bem-sucedida de config set / config patch / config unset, a CLI exibe uma destas três dicas para indicar se o Gateway precisa ser reiniciado:

Dica	Significado
`Restart the gateway to apply.`	O caminho alterado exige uma reinicialização completa.
`Change will apply without restarting the gateway.`	O recarregamento dinâmico aplica a alteração automaticamente.
`No gateway restart needed.`	Nada relevante para o tempo de execução foi alterado.

Gravações em plugins.entries (ou em qualquer subcaminho) sempre exigem uma reinicialização, pois a CLI não consegue confirmar se os metadados de recarregamento de cada plugin estão carregados.

Segurança da gravação

openclaw config set e outros gravadores de configuração do OpenClaw validam a configuração completa após a alteração antes de salvá-la no disco. Se a nova carga falhar na validação do esquema ou parecer uma sobrescrita destrutiva, a configuração ativa permanece inalterada e a carga rejeitada é salva ao lado dela como openclaw.json.rejected.*.

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

bash

openclaw config set gateway.reload.mode hybrid --dry-runopenclaw config set gateway.reload.mode hybridopenclaw config validate

Se uma gravação for rejeitada, inspecione a carga salva e corrija o formato completo da configuração:

bash

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 impedem a inicialização ou são ignoradas pelo recarregamento dinâmico; o Gateway não regrava openclaw.json. Execute openclaw doctor --fix para reparar uma configuração com prefixos/sobrescrita ou restaurar a última cópia válida conhecida. Consulte Solução de problemas do Gateway.

A recuperação do arquivo inteiro é reservada para o reparo do doctor. Alterações no esquema de plugins ou divergências de minHostVersion continuam gerando erros explícitos, em vez de reverter configurações não relacionadas do usuário, como modelos, provedores, perfis de autenticação, canais, exposição do Gateway, ferramentas, memória, navegador ou configuração de cron.

Ciclo de reparo

Depois que openclaw config validate for aprovado, use a TUI local para que um agente integrado compare a configuração ativa com a documentação enquanto você valida cada alteração no mesmo terminal:

bash

openclaw chat

Dentro da TUI, um ! inicial executa um comando literal no shell local (após uma solicitação de confirmação única por sessão):

text

!openclaw config file!openclaw docs gateway auth token secretref!openclaw config validate!openclaw doctor

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.

Aplicar edições direcionadas

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

Validar novamente

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

Usar o doctor para problemas de tempo de execução

Se a validação for aprovada, mas o tempo de execução continuar com problemas, execute openclaw doctor ou openclaw doctor --fix para obter ajuda com migração e reparo.

Relacionado

Was this useful?

Configuração

Opções raiz

Exemplos

Caminhos

`config get`

`config file`

`config schema`

`config validate`

Valores

Modos de `config set`

Modo de valor

Modo construtor de SecretRef

Modo construtor de provedor

Modo em lote

Flags do construtor de provedor

`config patch`

Simulação

Estrutura da saída JSON

Exemplo de sucesso

Exemplo de falha

Aplicação das alterações

Segurança da gravação

Ciclo de reparo

Comparar com a documentação

Aplicar edições direcionadas

Validar novamente

Usar o doctor para problemas de tempo de execução

Relacionado

On this page

Molty

Opções raiz

Exemplos

Caminhos

config get

config file

config schema

config validate

Valores

Modos de config set

Modo de valor

Modo construtor de SecretRef

Modo construtor de provedor

Modo em lote

Flags do construtor de provedor

config patch

Simulação

Estrutura da saída JSON

Exemplo de sucesso

Exemplo de falha

Aplicação das alterações

Segurança da gravação

Ciclo de reparo

Comparar com a documentação

Aplicar edições direcionadas

Validar novamente

Usar o doctor para problemas de tempo de execução

Relacionado

On this page

`config get`

`config file`

`config schema`

`config validate`

Modos de `config set`

`config patch`