Configuração

Auxiliares de configuração para edições não interativas em openclaw.json: obtenha/defina/aplique patch/remova/arquivo/esquema/valide valores por caminho e imprima o arquivo de configuração ativo. Execute sem um subcomando para abrir o assistente de configuração (igual a openclaw configure).

# Opções raiz

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="string"> Filtro repetível de seção de configuração guiada quando você executa 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.

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 por ponto ou colchetes:

openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id

Use o índice da lista de agentes para mirar um agente específico:

openclaw config get agents.list
openclaw config set agents.list[1].tools.exec.node "node-id-or-name"

# Valores

Valores são analisados como JSON5 quando possível; caso contrário, são tratados como strings. Use --strict-json para exigir análise como JSON5. --json continua compatível como alias legado.

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

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 --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 oferece suporte a 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 o payload 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 pipe via 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

Patch de exemplo:

{
  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 recursivo:

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 baseadas em exec são ignoradas por padrão durante dry-run; adicione --allow-exec quando você intencionalmente quiser 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 de construtor de provedor

Destinos de 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", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "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 após a alteração antes de salvá-la em disco. Se o novo payload falhar na validação de schema ou parecer uma substituição destrutiva, a configuração ativa é deixada 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-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 completo da configuração:

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 impedem a inicialização ou são ignoradas pelo hot reload; o Gateway não reescreve openclaw.json. Execute openclaw doctor --fix para reparar configurações prefixadas/sobrescritas ou restaurar a última cópia válida conhecida. Consulte solução de problemas do Gateway.

A recuperação do arquivo inteiro é reservada para reparo pelo doctor. Alterações de schema de Plugin ou divergência de minHostVersion permanecem explícitas 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.

# Subcomandos

• config file: Imprime o caminho do arquivo de configuração ativa (resolvido a partir de OPENCLAW_CONFIG_PATH ou do local padrão). O caminho deve nomear 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 schema 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:

openclaw chat

Em seguida, dentro da TUI:

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

Loop de reparo típico:

# Relacionado

• Referência da CLI
• Configuração