Configuración

Ayudas no interactivas para openclaw.json: obtener/establecer/aplicar un parche/eliminar un valor por ruta, imprimir el esquema, validar o imprimir la ruta del archivo activo. Ejecute openclaw config sin ningún subcomando para abrir el mismo asistente guiado que openclaw configure.

Cuando OPENCLAW_NIX_MODE=1, OpenClaw trata openclaw.json como inmutable. Los comandos de solo lectura (config get, config file, config schema, config validate) siguen funcionando; los comandos que escriben la configuración se niegan a hacerlo. En su lugar, edite la fuente de Nix de la instalación; para la distribución nix-openclaw oficial, consulte el Inicio rápido de nix-openclaw y establezca los valores en programs.openclaw.config o instances.<name>.config.

Opciones raíz

string

Filtro repetible de secciones de configuración guiada al ejecutar openclaw config sin un subcomando.

Secciones guiadas: workspace, model, web, gateway, daemon, channels, plugins, skills, health.

Ejemplos

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.entries.main.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

Rutas

Notación de puntos o corchetes. Ponga entre comillas las rutas con corchetes en los ejemplos de shell para que zsh no expanda [0] como un patrón glob:

openclaw config get agents.defaults.workspace
openclaw config get agents.entries.main
openclaw config get agents.entries
openclaw config set 'agents.entries.work.tools.exec.node' "node-id-or-name"

`config get`

Lee un valor de la instantánea censurada de la configuración (los secretos nunca se imprimen). --json imprime el valor sin procesar como JSON; de lo contrario, las cadenas, los números y los valores booleanos se imprimen sin formato, y los objetos y las matrices se imprimen como JSON con formato. Cuando falta la ruta, --json escribe { "error": "Config path not found: <path>" } en stdout y termina con el estado 1. Sin --json, el diagnóstico permanece en stderr.

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

`config file`

Imprime la ruta del archivo de configuración activo, resuelta a partir de OPENCLAW_CONFIG_PATH o de la ubicación predeterminada. La ruta identifica un archivo normal, no un enlace simbólico; consulte Seguridad de escritura.

`config schema`

Imprime en stdout el esquema JSON generado para openclaw.json.

Qué incluye

El esquema de configuración raíz actual, además de un campo de cadena raíz $schema para herramientas de edición.
Metadatos de documentación de los campos title / description utilizados por la interfaz de control.
Los nodos de objetos anidados, comodines (*) y elementos de matrices ([]) heredan los mismos metadatos title / description cuando existe documentación de campos coincidente.
Las ramas anyOf / oneOf / allOf también heredan los mismos metadatos de documentación.
Metadatos del esquema de plugins y canales activos, con el mejor esfuerzo posible, cuando se pueden cargar los manifiestos en tiempo de ejecución.
Un esquema alternativo limpio incluso cuando la configuración actual no es válida.

RPC de tiempo de ejecución relacionado

config.schema.lookup devuelve una ruta de configuración normalizada con un nodo de esquema superficial (title, description, type, enum, const, límites comunes), los metadatos de indicaciones de la interfaz de usuario coincidentes y resúmenes de los elementos secundarios inmediatos. Úselo para explorar en profundidad una ruta específica en la interfaz de control o en clientes personalizados.

openclaw config schema
openclaw config schema > openclaw.schema.json

`config validate`

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

openclaw config validate
openclaw config validate --json

Si la validación ya está fallando, comience con openclaw configure o openclaw doctor --fix. openclaw chat no omite la protección contra configuraciones no válidas.

Valores

Los valores se analizan como JSON5 cuando es posible; de lo contrario, se tratan como cadenas sin procesar. Use --strict-json para exigir JSON estándar sin recurrir a una cadena (en ese caso, se rechaza la sintaxis exclusiva de JSON5, como comentarios, comas finales o claves sin comillas). --json es un alias heredado de --strict-json en config set.

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 procesar como JSON en lugar de texto con formato para terminal. Cuando una escritura cambia agents.defaults.model o un agents.entries.*.model por agente, OpenClaw resuelve cada modelo principal o alternativo modificado mediante los catálogos de proveedores configurados antes de escribir. Las referencias a modelos desconocidos se rechazan sin cambiar la configuración activa; ejecute openclaw models list para ver los modelos disponibles.

La asignación de objetos reemplaza de forma predeterminada la ruta de destino. Las rutas protegidas que suelen contener entradas añadidas por el usuario rechazan los reemplazos que eliminarían entradas existentes, a menos que se especifique --replace: agents.defaults.models, agents.entries, models.providers, models.providers.<id>, models.providers.<id>.models, plugins.entries y auth.profiles.

Use --merge al añadir entradas a esos 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 solo cuando el valor proporcionado deba convertirse intencionadamente en el valor completo del destino.

Modos de `config set`

Modo de valor
Modo de creación de SecretRef
Modo de creación de proveedores
Modo por lotes

openclaw config set <path> <value>

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

Solo admite rutas secrets.providers.<alias> como destino:

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

Los archivos por lotes están limitados a 8 MiB.

Las asignaciones de SecretRef se rechazan en superficies mutables en tiempo de ejecución no compatibles (por ejemplo, hooks.token, commands.ownerDisplaySecret, los tokens de Webhook para vincular hilos de Discord y el JSON de credenciales de WhatsApp). Consulte Superficie de credenciales de SecretRef.

El análisis por lotes siempre utiliza la carga útil del lote (--batch-json/--batch-file) como fuente de verdad; --strict-json / --json no modifican el comportamiento del análisis por lotes. El modo de ruta/valor JSON también funciona directamente para SecretRefs y proveedores:

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

Opciones de creación de proveedores

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

Opciones comunes

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

Proveedor de entorno (--provider-source env)

--provider-allowlist <ENV_VAR> (repetible)

Proveedor de archivos (--provider-source file)

--provider-path <path> (obligatorio)
--provider-mode <singleValue|json>
--provider-max-bytes <bytes>
--provider-allow-insecure-path

Proveedor de ejecución (--provider-source exec)

--provider-command <path> (obligatorio)
--provider-arg <arg> (repetible)
--provider-no-output-timeout-ms <ms>
--provider-max-output-bytes <bytes>
--provider-json-only
--provider-env <KEY=VALUE> (repetible)
--provider-pass-env <ENV_VAR> (repetible)
--provider-trusted-dir <path> (repetible)
--provider-allow-insecure-path
--provider-allow-symlink-command

Ejemplo de proveedor de ejecución 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

`config patch`

Pegue o canalice un parche JSON5 con la forma de la configuración en lugar de ejecutar muchos comandos config set basados en rutas. Los objetos se combinan recursivamente; las matrices y los valores escalares reemplazan el destino; null elimina la ruta de destino.

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

Los archivos de parche están limitados a 8 MiB. Los parches --stdin canalizados están limitados a 1 MiB. Canalice un parche mediante stdin para los scripts de configuración remota:

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

Ejemplo de parche:

{
  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> cuando un objeto o una matriz deba convertirse exactamente en el valor proporcionado en lugar de recibir un parche recursivo:

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

--dry-run ejecuta comprobaciones del esquema y de la capacidad de resolución de SecretRef sin escribir. Las SecretRefs respaldadas por exec se omiten de forma predeterminada durante la simulación; añada --allow-exec cuando quiera expresamente que la simulación ejecute comandos del proveedor.

Simulación

--dry-run valida los cambios sin escribir openclaw.json. Está disponible en config set, config patch y config unset.

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 la simulación

Modo de constructor: ejecuta comprobaciones de la capacidad de resolución de SecretRef para las referencias y los proveedores modificados.
Modo JSON (--strict-json, --json o modo por lotes): ejecuta la validación del esquema y comprobaciones de la capacidad de resolución de SecretRef.
La validación de políticas se ejecuta con la configuración completa posterior al cambio, por lo que las escrituras de objetos principales (por ejemplo, establecer hooks como objeto) no pueden eludir la validación de superficies no compatibles.
Las comprobaciones de SecretRef de exec se omiten de forma predeterminada para evitar efectos secundarios de los comandos; pase --allow-exec para habilitarlas (esto puede ejecutar comandos del proveedor). --allow-exec es exclusivo de la simulación y genera un error sin --dry-run.

Campos de --dry-run --json

ok: indica si la simulación se realizó correctamente
operations: número de asignaciones evaluadas
checks: indica si se ejecutaron las comprobaciones del esquema y de la capacidad de resolución
checks.resolvabilityComplete: indica si las comprobaciones de la capacidad de resolución se ejecutaron hasta finalizar (es falso cuando se omiten referencias de exec)
refsChecked: número de referencias resueltas realmente durante la simulación
skippedExecRefs: número de referencias de exec omitidas porque no se estableció --allow-exec
errors: errores estructurados de rutas ausentes, esquema o capacidad de resolución cuando ok=false

Estructura de la salida 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" | "model",
      message: string,
      ref?: string, // presente para errores de capacidad de resolución
    },
  ],
}

Ejemplo correcto
Ejemplo de error

{
  "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: La variable de entorno \"MISSING_TEST_SECRET\" no está establecida.",
      "ref": "env:default:MISSING_TEST_SECRET"
    }
  ]
}

Si falla la simulación

config schema validation failed: la estructura de la configuración posterior al cambio no es válida; corrija la ruta, el valor o la estructura del objeto de proveedor o referencia.
Config policy validation failed: unsupported SecretRef usage: vuelva a introducir esa credencial como texto sin formato o cadena; mantenga las SecretRefs únicamente en superficies compatibles.
SecretRef assignment(s) could not be resolved: el proveedor o la referencia indicados no se pueden resolver actualmente (falta una variable de entorno, el puntero de archivo no es válido, se produjo un error del proveedor de exec o no coinciden el proveedor y el origen).
model reference validation failed: se desconoce un modelo de texto principal o de reserva modificado; ejecute openclaw models list y elija un modelo disponible.
Dry run note: skipped <n> exec SecretRef resolvability check(s): vuelva a ejecutar con --allow-exec si necesita validar la capacidad de resolución de exec.
En el modo por lotes, corrija las entradas con errores y vuelva a ejecutar --dry-run antes de escribir.

Aplicación de cambios

Después de cada ejecución correcta de config set / config patch / config unset, la CLI muestra una de estas tres indicaciones para informar de si es necesario reiniciar el Gateway:

Indicación	Significado
`Restart the gateway to apply.`	La ruta modificada requiere un reinicio completo.
`Change will apply without restarting the gateway.`	La recarga en caliente la aplica automáticamente.
`No gateway restart needed.`	No cambió nada relevante para el entorno de ejecución.

Las escrituras en plugins.entries (o en cualquier subruta) siempre requieren un reinicio, ya que la CLI no puede demostrar que se hayan cargado los metadatos de recarga de todos los plugins.

Seguridad de escritura

openclaw config set y otros procesos de escritura de configuración propiedad de OpenClaw validan la configuración completa posterior al cambio antes de guardarla en el disco. Si la nueva carga útil no supera la validación del esquema o parece una sobrescritura destructiva, la configuración activa se deja intacta y la carga útil rechazada se guarda junto a ella como openclaw.json.rejected.*. Las escrituras propiedad de OpenClaw vuelven a serializar JSON5 como JSON estándar. Cuando el origen contiene comentarios, el proceso de escritura avisa inmediatamente antes de eliminarlos; utilice un editor directamente cuando sea importante conservarlos.

La ruta de configuración activa debe ser un archivo normal. Las disposiciones de openclaw.json con enlaces simbólicos no son compatibles con las escrituras; utilice OPENCLAW_CONFIG_PATH para apuntar directamente al archivo real.

Para modificaciones pequeñas, es preferible escribir mediante la CLI:

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

Si se rechaza una escritura, inspeccione la carga útil guardada y corrija la estructura completa de la configuración:

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

Las escrituras directas con un editor siguen estando permitidas, pero el Gateway en ejecución las considera no fiables hasta que se validan. Las modificaciones directas no válidas impiden el inicio o se omiten durante la recarga en caliente; el Gateway no vuelve a escribir openclaw.json. Ejecute openclaw doctor --fix para reparar una configuración con prefijos o sobrescrita, o para restaurar la última copia válida conocida. Consulte Solución de problemas del Gateway. La recuperación del archivo completo está reservada para la reparación mediante doctor. Los cambios en el esquema de plugins o las discrepancias de minHostVersion siguen produciendo errores explícitos en lugar de revertir ajustes del usuario no relacionados, como la configuración de modelos, proveedores, perfiles de autenticación, canales, exposición del Gateway, herramientas, memoria, navegador o Cron.

Ciclo de reparación

Después de que openclaw config validate se complete correctamente, utilice la TUI local para que un agente integrado compare la configuración activa con la documentación mientras valida cada cambio desde el mismo terminal:

openclaw chat

Dentro de la TUI, un ! inicial ejecuta literalmente un comando del shell local (después de una solicitud de confirmación que aparece una sola vez por sesión):

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

Comparar con la documentación

Pida al agente que compare la configuración actual con la página pertinente de la documentación y sugiera la corrección mínima.

Aplicar modificaciones específicas

Aplique modificaciones específicas con openclaw config set o openclaw configure.

Volver a validar

Vuelva a ejecutar openclaw config validate después de cada cambio.

Usar doctor para problemas del entorno de ejecución

Si la validación se completa correctamente, pero el entorno de ejecución sigue sin funcionar correctamente, ejecute openclaw doctor o openclaw doctor --fix para obtener ayuda con la migración y la reparación.

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

Opciones raíz

Ejemplos

Rutas

`config get`

`config file`

`config schema`

`config validate`

Valores

Modos de `config set`

Opciones de creación de proveedores

`config patch`

Simulación

Estructura de la salida JSON

Aplicación de cambios

Seguridad de escritura

Ciclo de reparación

Relacionado

​Opciones raíz

​Ejemplos

​Rutas

​config get

​config file

​config schema

​config validate

​Valores

​Modos de config set

​Opciones de creación de proveedores

​config patch

​Simulación

​Estructura de la salida JSON

​Aplicación de cambios

​Seguridad de escritura

​Ciclo de reparación

​Relacionado

Opciones raíz

Ejemplos

Rutas

`config get`

`config file`

`config schema`

`config validate`

Valores

Modos de `config set`

Opciones de creación de proveedores

`config patch`

Simulación

Estructura de la salida JSON

Aplicación de cambios

Seguridad de escritura

Ciclo de reparación

Relacionado