Cómo gestionar la configuración de openclaw desde la...

A veces, gestionar archivos de configuración complejos se convierte en un dolor de cabeza, especialmente cuando un error de sintaxis rompe todo el flujo de trabajo. Configurar tu entorno de forma manual puede ser propenso a errores, y por eso es fundamental contar con herramientas que validen tus cambios antes de aplicarlos.

Con OpenClaw, puedes gestionar tu configuración de forma eficiente y segura. Esta herramienta te permite realizar ajustes precisos en OpenClaw mediante comandos directos, asegurando que cada cambio en tu API o Gateway sea válido y funcional.

Ejemplos

Puedes usar estos comandos para interactuar con tu configuración de manera rápida y sencilla.

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 agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
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 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

Este comando imprime el esquema JSON generado para openclaw.json en la salida estándar.

Lo que incluye:

1. El esquema de configuración raíz actual, junto con un campo de cadena $schema para herramientas de edición.
2. Metadatos de documentación de title y description utilizados por la interfaz de control.
3. Nodos de objetos anidados, comodines (*) y elementos de matriz ([]) que heredan los mismos metadatos cuando existe documentación de campo coincidente.
4. Ramas anyOf / oneOf / allOf que también heredan los metadatos de documentación.
5. Metadatos de esquema de plugin + channel en tiempo real cuando se pueden cargar los manifiestos.
6. Un esquema de respaldo limpio incluso cuando la configuración actual no es válida.

openclaw config schema

Puedes redirigir la salida a un archivo si deseas inspeccionarlo o validarlo con otras herramientas:

openclaw config schema > openclaw.schema.json

Rutas

Las rutas utilizan notación de puntos o corchetes para acceder a los valores.

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

Usa el índice de la lista de agentes para apuntar a uno específico.

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

Valores

Los valores se analizan como JSON5 siempre que sea posible; de lo contrario, se tratan como cadenas. Usa --strict-json para exigir el análisis JSON5.

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 el valor sin formato como JSON en lugar de texto formateado para la terminal.

config set modes

openclaw config set admite cuatro estilos de asignación para tus configuraciones.

1. Modo de valor: openclaw config set <path> <value>
2. Modo de constructor SecretRef:

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

3. Modo de constructor de proveedor (solo para la ruta secrets.providers.<alias>):

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

4. Modo por lotes (--batch-json o --batch-file):

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

Nota de política:

1. Las asignaciones de SecretRef se rechazan en superficies mutables en tiempo de ejecución no compatibles.
2. El análisis por lotes siempre utiliza la carga útil del lote como fuente de verdad.

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

Provider Builder Flags

Los destinos del constructor de proveedores deben usar secrets.providers.<alias> como ruta.

Banderas comunes:

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

Ejemplo de proveedor exec reforzado:

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

Usa --dry-run para validar los cambios sin escribir en 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

Comportamiento de dry-run:

1. Modo constructor: ejecuta comprobaciones de resolución de SecretRef.
2. Modo JSON: ejecuta validación de esquema y comprobaciones de resolución.
3. Las comprobaciones de política evalúan la configuración completa posterior al cambio.
4. Las comprobaciones de SecretRef exec se omiten de forma predeterminada.

--dry-run --json imprime un informe legible por máquina.

Forma de salida 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
    },
  ],
}

Ejemplo de éxito:

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

Ejemplo de fallo:

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

Write safety

openclaw config set y otros escritores de configuración de OpenClaw validan la configuración completa antes de guardarla en el disco. Si la carga útil falla, la configuración activa permanece intacta.

Prefiere las escrituras mediante CLI para ediciones pequeñas:

openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate

Si una escritura es rechazada, inspecciona la carga útil guardada y corrige la forma de la configuración:

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate

Subcommands

1. config file: Imprime la ruta del archivo de configuración activo (resuelto desde OPENCLAW_CONFIG_PATH o la ubicación predeterminada).

Reinicia el Gateway después de realizar ediciones.

Validate

Valida la configuración actual contra el esquema activo sin iniciar el Gateway.

openclaw config validate
openclaw config validate --json

---

Siguientes pasos

• Gateway troubleshooting
• SecretRef Credential Surface

¿Necesitas ayuda adicional? Consulta nuestro AI Setup Assistant.