OpenClaw recibe una guía completa en ruso sobre configuración JSON5, CLI y configuración segura

Se ha publicado en Habr una guía detallada sobre OpenClaw — una plataforma en la que prácticamente toda la configuración operativa gira en torno a un único archivo, openclaw.json, y un extenso CLI. El material reúne en un solo lugar lo que antes había que buscar en la documentación oficial, los GitHub issues y las publicaciones de la comunidad.

Qué hay en la configuración

El autor explica cómo está estructurado el nivel superior de la configuración y por qué OpenClaw exige cuidado al editarla manualmente. El archivo utiliza JSON5, lo que permite comentarios y comas finales, pero el esquema se valida de forma muy estricta al arrancar. Si se añade una clave desconocida, el gateway simplemente no arranca.

Se describen por separado gateway, env, agents, models, auth, channels, session, cron, tools, sandbox y logging, así como el funcionamiento del hot reload sin necesidad de un reinicio completo.

• gateway: puerto, modo bind, token de acceso y comportamiento del hot reload
• agents y models: configuración base, fallbacks y selección de proveedores
• auth y channels: cambio de perfiles, Telegram, Discord y otros canales
• session y cron: aislamiento de diálogos, reinicios por tiempo y tareas en segundo plano
• env y secrets: prioridad de variables, SecretRef y almacenamiento de datos sensibles

El principal valor del material reside en que va más allá de una simple lista de campos. El texto explica cómo se relacionan los distintos niveles de configuración, dónde se aplican los valores por defecto, cuándo los ajustes surten efecto sin reiniciar y qué parámetros es mejor no tocar manualmente.

Para quienes ejecutan OpenClaw no de forma local, sino en un VPS o en un entorno de trabajo, esto deja de ser una simple referencia y se convierte en un operational playbook completo.

Dónde falla la configuración

El bloque más útil está dedicado no al happy path, sino a los fallos típicos. La guía subraya que algunos parámetros solo funcionan en agents.defaults y se ignoran silenciosamente si se mueven a la configuración de un agente concreto. Por ello, la configuración puede parecer correcta pero el comportamiento deseado nunca llega a activarse.

La recomendación es sencilla: utilizar con más frecuencia los comandos openclaw config get, set y unset en lugar de editar directamente, y ejecutar el diagnóstico tras cada cambio.

openclaw doctor — el comando más útil de todo el CLI.

La guía también aborda el problema del desbordamiento de contexto. OpenClaw utiliza dos mecanismos distintos: pruning elimina los resultados antiguos de herramientas antes de llamar al modelo, mientras que compaction comprime el historial cuando la ventana de contexto está casi llena. Como ejemplo se cita un caso en el que 35 mensajes generaron un archivo de sesión de 2,9 MB y un contexto de 208.467 tokens, lo que provocó que el sistema dejase de responder con un límite de modelo de 200.000 tokens.

CLI para administradores

El CLI está organizado no por orden alfabético, sino por escenarios de trabajo, lo que hace que la guía sea práctica. En un solo lugar se agrupan los comandos para arrancar el gateway, comprobar el estado del daemon, gestionar canales, logs, tareas cron, plugins, skills, sesiones y actualizaciones.

Para los comandos de infraestructura se destacan por separado los modos seguros: health funciona incluso sin el daemon en ejecución, security audit comprueba la configuración en busca de riesgos y secrets audit ayuda a detectar fugas de credenciales antes de llegar a producción.

El último bloque importante cubre las variables de entorno y el control de versiones. La guía documenta el orden de prioridad: primero el entorno del proceso, luego el .env local, después el .env global en el directorio de OpenClaw y, finalmente, las env.vars integradas. Para los secretos se recomienda usar referencias a variables o SecretRef en lugar de valores directamente en openclaw.json, y hacer commit en el repositorio solo de una plantilla de configuración, excluyendo los archivos .env, las carpetas de sesión, los archivos de memoria y el estado temporal.

Qué significa esto

OpenClaw se está convirtiendo en una herramienta no solo para entusiastas dispuestos a leer el código fuente, sino también para equipos que necesitan un operational playbook claro. Si un proyecto depende de varios modelos, canales y automatizaciones, una guía como esta reduce el riesgo de fallos silenciosos, fugas de secretos y comportamiento inestable tras las actualizaciones.