OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

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.

Opciones raíz

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="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

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

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:

bash
openclaw config get agents.defaults.workspaceopenclaw config get agents.entries.mainopenclaw config get agents.entriesopenclaw 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.

bash
openclaw config get browser.executablePathopenclaw 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.

bash
openclaw config schemaopenclaw config schema > openclaw.schema.json

config validate

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

bash
openclaw config validateopenclaw config validate --json

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.

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

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

Modos de config set

Modo de valor

bash
openclaw config set <path> <value>

Modo de creación de SecretRef

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

Modo de creación de proveedores

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

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 por lotes

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

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

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:

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

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 &lt;ENV_VAR&gt; (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 &lt;KEY=VALUE&gt; (repetible)
  • --provider-pass-env &lt;ENV_VAR&gt; (repetible)
  • --provider-trusted-dir <path> (repetible)
  • --provider-allow-insecure-path
  • --provider-allow-symlink-command

Ejemplo de proveedor de ejecución reforzado:

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

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.

bash
openclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw 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:

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

Ejemplo de parche:

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

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

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

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

Ejemplo correcto

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

Ejemplo de error

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

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

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

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

bash
CONFIG="$(openclaw config file)"ls -lt "$CONFIG".rejected.* 2>/dev/null | headopenclaw 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:

bash
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):

text
!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.

    • Relacionado

    Was this useful?
    On this page

    On this page