Configuración detallada de OpenClaw: guía completa y mejores prácticas para openclaw.json

Actualización 2026-06-08: revisé campos, dmPolicy, comandos de auditoría de seguridad y la guía sobre CVE-2026-25253 con la documentación oficial del Gateway de OpenClaw, y añadí lecturas relacionadas de la misma serie. Las claves de configuración siguen la documentación oficial.

Después de que se esté ejecutando el servicio OpenClaw, abra ~/.openclaw/openclaw.json y vea una pantalla completa de parámetros de configuración: puerta de enlace, canal, habilidades, proveedor… También hay un montón de opciones anidadas debajo de cada campo. ¿Debería establecerse “dmPolicy” en “emparejamiento” o “lista de permitidos”? ¿Es gateway.auth.token solo la contraseña? ¿Necesito habilitar todas las habilidades?

Lo que es aún más preocupante es que a finales de enero de 2026, OpenClaw acaba de solucionar una grave vulnerabilidad de seguridad (CVE-2026-25253, puntuación CVSS 8,8). Un atacante puede robar el token de autenticación a través de parámetros de URL y luego ejecutar comandos arbitrarios. Si se configura incorrectamente, el asistente de IA puede convertirse en una puerta trasera para otros.

Este artículo era la guía que más quería ver en ese momento. Desmantelaré sistemáticamente todos los módulos de configuración de openclaw.json y le diré qué significa cada parámetro, por qué es necesario y cómo se debe configurar en un entorno de producción. También compartiré algunos errores que he encontrado y una lista de verificación de configuraciones de seguridad.

Guía de “OpenClaw simplificado” de bajo costo: ArkClaw hace que agente de IA sea verdaderamente civil

¿El recientemente popular OpenClaw (langosta) es fácil de usar pero la configuración es demasiado desalentadora? ArkClaw de Byte Volcano Engine llega al umbral directamente al suelo. No es necesario jugar con la configuración del servidor y del token. Con un clic, puede tener un “asistente de IA” que está en línea las 24 horas del día, puede controlar navegadores, ejecutar scripts y administrar calendarios.

El punto clave es que es realmente barato: la tarifa mensual es de solo 9,9 yuanes y usar mi código de invitación ZLKUK54M (haga clic aquí para registrarse) solo cuesta 8,9 yuanes. Si es programador, puede obtener acceso gratuito a Coding Plan Pro directamente.

Comprensión básica de los archivos de configuración.

¿Dónde está el archivo y qué aspecto tiene?

El archivo de configuración de OpenClaw se guarda en ~/.openclaw/openclaw.json de forma predeterminada. Si lo configura a través del asistente de instalación, este archivo se generará automáticamente; Si lo instala manualmente, es posible que deba crearlo usted mismo. Los nombres de los campos, los niveles de anidamiento y los valores predeterminados están sujetos al [Documento oficial de configuración de la puerta de enlace] (https://docs.openclaw.ai/gateway/configuration). Los siguientes ejemplos se utilizan para comprender la estructura. Verifique el documento después de actualizar a una versión más grande.

Ábrelo y verás cinco módulos principales:

• Puerta de enlace: puerto de servicio de puerta de enlace, autenticación, registro y otras configuraciones
• Canal: Configuración de canales de comunicación (WhatsApp, Telegram, etc.)
• Habilidades: Gestión y permisos de módulos de habilidades
• Proveedor: proveedor de modelo de IA (Anthropic, OpenAI, modelo local, etc.)
• Seguridad: Política de seguridad y control de acceso

En realidad, esta estructura es bastante razonable: la puerta de enlace gestiona la entrada, el canal gestiona la comunicación, las habilidades gestionan las capacidades, el proveedor gestiona el cerebro y la seguridad gestiona la protección.

Método de configuración y prioridad

OpenClaw admite cuatro métodos de configuración:

1. Asistente interactivo: selección paso a paso durante la instalación, adecuado para principiantes
2. Edite JSON directamente: use vim o nano para cambiar archivos directamente, adecuado para personas que están familiarizadas con la configuración
3. Variables de entorno: adecuado para implementación en contenedores o sobrescritura temporal de ciertos parámetros
4. Automatización de scripts: use scripts para generar configuraciones durante la implementación por lotes

Aquí está el punto clave: estos métodos tienen prioridades. Variables de entorno > Archivos de configuración > Valores predeterminados.

¿Cuál es el significado? Por ejemplo, si configura gateway.port: 18789 en el archivo de configuración, pero también configura la variable de entorno OPENCLAW_GATEWAY_PORT=9000, el valor final será 9000. Este diseño es particularmente útil durante la depuración; puede realizar pruebas configurando variables de entorno temporalmente sin cambiar el archivo de configuración.

La versión 2026 también agrega soporte para el servidor MCP (Protocolo de contexto modelo), que puede proporcionar acceso unificado a múltiples motores y herramientas de búsqueda. Además, el comando “openclaw doctor” ahora puede verificar automáticamente el estado de la configuración y proporcionar sugerencias de reparación si se encuentran problemas.

Explicación detallada de la configuración de la puerta de enlace

Gateway es la entrada a OpenClaw y es responsable del acceso a la interfaz web y las conexiones de clientes remotos.

Configuración básica: puerto y autenticación

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token-here"
    },
    "remote": {
      "token": "your-remote-token-here"
    }
  }
}

• port: Puerto de acceso de la interfaz web, predeterminado 18789. Visite http://localhost:18789 para ver el panel de control de OpenClaw. Si este puerto está ocupado, simplemente cámbielo por otro (como 19000).

• auth.token: Este es el token de autenticación de la puerta de enlace, equivalente a la contraseña. Cualquiera que obtenga este token puede controlar completamente su instancia de OpenClaw. La vulnerabilidad CVE-2026-25253 se debe a que el token se puede filtrar a través de parámetros de URL.

• remote.token: el token utilizado por clientes remotos (como aplicaciones móviles o clientes de escritorio) para conectarse. Está separado de auth.token para que se pueda rotar por separado.

Consejo de seguridad: La versión del 29 de enero de 2026 eliminó la opción "auth: none". En el pasado, se podía desactivar la autenticación para facilitar el desarrollo, pero ahora es obligatorio utilizar un token o una contraseña. Esta es una solución difícil para una falla de seguridad.

Configuración avanzada: Registro y WebSocket

{
  "gateway": {
    "logging": {
      "redactSensitive": true
    }
  }
}

Después de que “redactSensitive” se establezca en verdadero, los registros se desensibilizarán automáticamente; la información confidencial, como claves API y tokens, se reemplazará con ”***”. Al verificar los registros y solucionar problemas, no tiene que preocuparse por copiar accidentalmente la clave en una edición pública.

El comando para iniciar el servicio de puerta de enlace es “openclaw gateway”. Una vez que se esté ejecutando el servicio, verá un resultado similar a este:

[Gateway] Listening on http://localhost:18789
[Gateway] Authentication: Token-based

Estrategia de configuración del canal de canal

El módulo Canal determina las plataformas a través de las cuales OpenClaw puede comunicarse con usted.

Tipos de canales admitidos

Actualmente se admiten cuatro canales principales:

1. WhatsApp: Escanea el código QR para que coincida, el más utilizado
2. Telegram: API de bot, adecuada para escenarios grupales
3. Discord: adecuado para comunidades técnicas
4. Lo más importante: colaboración en equipo empresarial

Cada canal está configurado de manera diferente. WhatsApp utiliza un proceso de coincidencia de códigos QR, Telegram requiere Bot Token y Discord requiere la creación de una aplicación.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Configuración de la política DM (mensaje privado)

Esta es la parte que mucha gente no entiende. dmPolicy determina si extraños pueden enviar mensajes a su asistente de IA.

Hay cuatro modos:

1. emparejamiento (modo predeterminado)

{
  "channel": {
    "dmPolicy": "pairing"
  }
}

Los remitentes desconocidos necesitan primero una verificación de emparejamiento. OpenClaw generará un código de emparejamiento de 6 dígitos, válido por 1 hora. Debe aprobar manualmente:

openclaw pairing approve whatsapp ABC123

Este modelo equilibra seguridad y usabilidad: cuando un amigo acude a tu asistente de IA por primera vez, lo revisas y todo sale bien.

2. lista de permitidos (modo de lista blanca)

{
  "channel": {
    "dmPolicy": "allowlist",
    "allowFrom": [
      "+1234567890",
      "telegram:@username"
    ]
  }
}

Sólo las personas de la lista blanca pueden enviar mensajes, los demás quedan directamente bloqueados. Adecuado para escenarios en los que sabes exactamente quién lo utilizará.

3. open (modo abierto)

{
  "channel": {
    "dmPolicy": "open",
    "allowFrom": ["*"]
  }
}

Cualquiera puede enviar mensajes. Para ser honesto, este modelo es muy arriesgado. No recomendado a menos que esté realizando demostraciones o pruebas públicas.

4. disabled (modo deshabilitado)

Desactiva completamente los mensajes privados y acepta solo mensajes grupales.

Aislamiento de sesión para escenarios multiusuario

Si su servicio OpenClaw va a ser utilizado por varias personas (por ejemplo, compartido por un equipo), el aislamiento de la sesión es importante:

{
  "channel": {
    "session": {
      "dmScope": "per-channel-peer"
    }
  }
}

De esta forma, el historial de conversaciones de cada persona es independiente y no habrá conversaciones cruzadas.

Configuración de política de grupo de grupo

La configuración del grupo es relativamente simple, pero hay una configuración clave: mentionGating (@mention gating).

{
  "channel": {
    "groupPolicy": "mention",
    "mentionGating": true
  }
}

Después de encenderlo, el asistente de IA solo responderá a sus mensajes en lugar de monitorear cada mensaje del grupo. Evite convertirse en un robot “siempre activo”, ya sabes, del tipo que desliza la pantalla como loco en un grupo.

Configuración del módulo de habilidades

Las habilidades son la parte más interesante de OpenClaw: determinan lo que puede hacer el asistente de IA.

Conceptos básicos de Habilidades

Las habilidades son extensiones de habilidades modulares. OpenClaw viene con algunas habilidades integradas y hay más de 700 habilidades disponibles en la tienda de habilidades de ClawHub:

• Gestión de calendario (Google Calendar, Outlook)
• Navegación web (habilidades de navegación)
• Gestión de archivos (file_manager)
• Comando de terminal (habilidad ejecutiva)
• Ejecución de código (python, nodo)

La ruta de instalación de las habilidades es ~/.openclaw/skills/. Reglas de prioridad: Habilidades en el espacio de trabajo > Habilidades de usuario > Habilidades incorporadas.

¿Cuál es el significado? Si coloca una habilidad de “navegador” personalizada en el directorio del proyecto, anulará la versión instalada globalmente. Este diseño le permite personalizar capacidades para proyectos específicos.

Configuración y gestión de habilidades

Cada habilidad tiene un archivo SKILL.md, que define metadatos en formato YAML:

---
name: google-calendar
description: Manage Google Calendar events
requirements:
  bins:
    - gcalcli
  env:
    - GOOGLE_CALENDAR_API_KEY
---

El campo bins enumera los binarios dependientes. Por ejemplo, esta habilidad de calendario requiere la herramienta de línea de comando gcalcli. Si no está instalado en el sistema, la habilidad no se cargará.

Tres métodos de instalación:

1. Instalación GUI: haga clic en “Agregar habilidad” en la interfaz web, busque e instale
2. Instalación CLI: openclaw skills install google-calendar
3. Instalación manual: Copie el directorio de habilidades a ~/.openclaw/skills/

Solución de problemas de habilidades

La falla en la carga de habilidades es un problema común. Verifique las dependencias con este comando:

openclaw skill check google-calendar

Le dirá qué dependencias faltan, si las variables de entorno están configuradas y si la configuración del sistema operativo coincide.

Si aún tiene problemas, consulte el registro de la puerta de enlace:

openclaw gateway --verbose

El registro mostrará el proceso detallado de carga de habilidades y quedará claro de un vistazo qué paso salió mal.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Optimización de escenas de modelos pequeños.

Si está utilizando un modelo local con una ventana de contexto pequeña (como un modelo cuantificado con parámetros 7B), es posible que deba desactivar algunas habilidades para controlar el tamaño del contexto. Cuantas más habilidades tengas, más largas serán las palabras del sistema, dejando menos espacio para el diálogo.

Restricciones a habilidades de alto riesgo

Algunas habilidades tienen permisos muy altos y deben usarse con precaución:

• exec: ejecuta cualquier comando de shell
• browser: accede a cualquier página web
• web_fetch: recuperar contenido externo
• web_search: consulta del motor de búsqueda

Se puede abusar de estas habilidades en caso de entradas maliciosas. Si no es necesario, se recomienda desactivarlo.

Configuración del proveedor del modelo de proveedor

El proveedor determina qué cerebro de IA utiliza OpenClaw.

Proveedores de IA compatibles

1. Anthropic (Claude): Recomendado principalmente por el funcionario, con API estable y funciones de seguridad completas.
2. OpenAI: pronto será compatible (GPT-5 y otros modelos)
3. Modelo local: LM Studio, Ollama, etc.
4. OpenRouter: interfaz de acceso multimodelo unificada, una clave API puede usar todos los modelos
5. Servidor MCP: nueva característica en 2026, admite protocolo de contexto modelo

Parámetros de configuración del proveedor

Configuración más simple (usando Anthropic):

{
  "provider": {
    "type": "anthropic",
    "apiKey": "sk-ant-..."
  }
}

Pero recomiendo no escribir la clave API directamente en el archivo de configuración, sino utilizar variables de entorno:

export ANTHROPIC_API_KEY="sk-ant-..."

De esta manera, el archivo de configuración se puede enviar al control de versiones de forma segura y no se filtrará la clave API.

Configuración del modelo local

{
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "kimi-k2.5-chat"
  }
}

• baseURL: dirección del servidor de modelo local (puerto predeterminado de LM Studio 1234)
• modelId: especifica el nombre del modelo utilizado

Configuración del servidor MCP (nueva característica)

{
  "provider": {
    "mcpServers": {
      "onesearch": {
        "command": "npx",
        "args": ["-y", "@onesearch/mcp-server"]
      }
    }
  }
}

OneSearch MCP le permite acceder a múltiples motores de búsqueda (Google, Bing, Brave, etc.) a través de una interfaz unificada sin tener que asignar claves API independientes a cada motor de búsqueda.

Notas sobre modelos locales

Para ser honesto, el modelo local tiene sus ventajas: privacidad, costo y disponibilidad fuera de línea. Pero las características de seguridad son ciertamente más débiles que las del modelo comercial:

• El riesgo de inyección de punta es mayor: los modelos pequeños tienen más probabilidades de ser engañados por entradas maliciosas
• Ventana de contexto pequeña: las funciones de seguridad requieren más palabras de aviso del sistema, pero los modelos pequeños no caben en ellas.
• Limitaciones del modelo cuantificado: después de la cuantificación de 4 bits, la capacidad del modelo para seguir instrucciones disminuirá.

Si debe utilizar un modelo local, se recomienda:

• Restringir estrictamente los permisos de habilidades
• Habilitar el modo sandbox
• No ejecutar en máquinas con datos confidenciales

Mejores prácticas de configuración de seguridad

La configuración de seguridad es siempre la primera prioridad. La lección de la vulnerabilidad CVE-2026-25253 nos dice que las consecuencias de una configuración incorrecta pueden ser graves.

Lista de configuración de seguridad

Seguridad básica (imprescindible)

• ✅ Nunca comparta el token de puerta de enlace; al igual que su clave de inicio, nunca se la dé a otros
• ✅ Utilice un firewall para exponer solo los puertos necesarios (18789)
• ✅ SSH utiliza autenticación de clave en lugar de contraseña
• ✅ Restringir el acceso a la interfaz web (VPN o lista blanca de IP)
• ✅ Estrategia DM: priorice el uso de “emparejamiento” o “lista de permitidos”
• ✅ Política de grupo: habilitar la puerta de menciones

Seguridad avanzada (altamente recomendada)

• ✅ Rotar tokens regularmente (al menos una vez por trimestre)
• ✅ Habilitar la desensibilización de información de registro confidencial
• ✅ Restringir habilidades de alto riesgo (ejecutivo, navegador)
• ✅ Utiliza un servidor dedicado (no lo mezcles con tu máquina de trabajo principal)

Ingrese a Seguridad y Sandbox

Existe una regla estricta: tratar todas las entradas externas como maliciosas.

Enlaces, archivos adjuntos, instrucciones pegadas: todo podría ser un ataque cuidadosamente elaborado. La función sandbox de OpenClaw (opt-in) puede aislar operaciones de alto riesgo:

{
  "security": {
    "sandbox": {
      "enabled": true,
      "skills": ["exec", "browser"]
    }
  }
}

De esta manera, las habilidades ejecutivas y del navegador se ejecutarán en un entorno aislado e incluso si se ven comprometidas, no afectarán al sistema principal.

Gestión de secretos

Gestión de información sensible como claves API y tokens:

1. Solución básica: use SCP para transferir archivos .env al servidor para evitar pegarlos en el chat
2. Solución avanzada: utilice administradores de secretos profesionales como Doppler y HashiCorp Vault

Cosas que no se deben hacer:

• ❌ Enviar clave API en mensaje de Telegram
• ❌ Enviar secretos al repositorio de Git
• ❌ Publicar registros en ediciones públicas (puede incluir token)

Auditoría y mantenimiento de seguridad

OpenClaw tiene comandos de auditoría de seguridad integrados:

# cheque básico
openclaw security audit

# inspección profunda
openclaw security audit --deep

# Protección automática de seguridad de aplicaciones
openclaw security audit --fix

Este comando comprobará:

• ¿Es suficiente la fuerza del Token?
• Si el puerto está expuesto a la red pública.
• ¿Son correctos los permisos del archivo (~/.openclaw debe ser 700 y el archivo de configuración debe ser 600)?
• Si se habilitan habilidades de alto riesgo
• ¿Es segura la estrategia DM?

Permisos de archivos locales

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

De esta manera, sólo usted puede leer y escribir el archivo de configuración y otros usuarios ni siquiera pueden verlo.

Cosas que no se deben hacer

• ❌ Exponer el puerto 18789 a la red pública
• ❌ Otorgar acceso al shell sin comprender los riesgos
• ❌ Instalar habilidades de fuentes no verificadas
• ❌ Utilice dmPolicy: "open" sin incluir en la lista blanca
• ❌ Ejecute OpenClaw en la máquina donde está almacenado su correo electrónico/información bancaria principal

Caso de configuración real

Ahora que la teoría ha terminado, veamos las configuraciones completas de varios escenarios reales.

Escenario 1: uso personal, solo WhatsApp, modo de emparejamiento

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "generate-a-strong-random-token"
    },
    "logging": {
      "redactSensitive": true
    }
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "pairing",
    "session": {
      "dmScope": "per-channel-peer"
    }
  },
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "file_manager"
    ],
    "disabled": [
      "exec",
      "browser"
    ]
  },
  "provider": {
    "type": "anthropic"
  },
  "security": {
    "sandbox": {
      "enabled": true
    }
  }
}

Esta configuración es adecuada para usuarios individuales comunes: la seguridad es buena, las funciones están disponibles y las habilidades de alto riesgo están deshabilitadas.

Escenario 2: colaboración en equipo, multicanal, modo de lista blanca

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "team-gateway-token"
    },
    "remote": {
      "token": "team-remote-token"
    }
  },
  "channel": [
    {
      "type": "telegram",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "telegram:@alice",
        "telegram:@bob",
        "telegram:@carol"
      ],
      "groupPolicy": "mention",
      "mentionGating": true
    },
    {
      "type": "discord",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "discord:123456789"
      ]
    }
  ],
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "github",
      "jira"
    ]
  },
  "provider": {
    "type": "anthropic"
  }
}

La configuración multicanal se realiza en forma de matriz y cada canal administra la lista blanca de forma independiente. Habilite la selección de menciones en el grupo para evitar el spam en la pantalla.

Escenario 3: modelo local, uso fuera de línea, habilidades optimizadas

{
  "gateway": {
    "port": 19000
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "allowlist",
    "allowFrom": ["+1234567890"]
  },
  "skills": {
    "enabled": [
      "calculator",
      "file_manager"
    ]
  },
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "llama-3.1-8b"
  }
}

En el escenario del modelo local, las habilidades deben mantenerse lo más optimizadas posible: la ventana de contexto de un modelo pequeño no puede contener demasiadas palabras de indicaciones del sistema.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Errores de configuración comunes y soluciones

Error 1: la falta de coincidencia del token provoca que no se pueda conectar

Síntoma: La interfaz web muestra “Error de autenticación”

Solución: compruebe si gateway.auth.token es completamente coherente con el token que ingresó (preste atención a los espacios y las nuevas líneas)

Error 2: La falta de dependencias de habilidades provoca un error en la carga

Síntoma: el registro muestra “Error al cargar la habilidad ‘google-calendar’”

Solución: ejecute openclaw skills check google-calendar y siga las instrucciones para instalar las dependencias que faltan.

Error 3: El conflicto de puerto impide que se inicie Gateway

Síntoma: Error: escuche EADDRINUSE :::18789

Solución: utilice otro puerto o busque el proceso que ocupa 18789 y elimínelo

Error 4: formato de archivo de configuración incorrecto

Síntoma: SyntaxError: token inesperado} en JSON

Solución: utilice la herramienta de validación JSON para comprobar el formato. Los problemas comunes son comas adicionales o comillas que no coinciden.

Comandos de solución de problemas

# Consultar estado del servicio
openclaw status

# chequeo de salud
openclaw doctor

# Registro detallado
openclaw gateway --verbose

Lectura relacionada

• Guía completa de instalación de OpenClaw: de la preparación a la primera ejecución
• Arquitectura de OpenClaw en detalle: diseño en tres capas
• OpenClaw vs ChatGPT: arquitectura, costo y privacidad

En conclusión

Dicho todo esto, hay tres puntos centrales:

Primero, los archivos de configuración son el corazón de OpenClaw. El significado de cada parámetro merece una comprensión profunda: no para mostrar habilidades, sino para localizar rápidamente el problema cuando algo sale mal.

En segundo lugar, la configuración de seguridad es siempre la primera prioridad. La vulnerabilidad CVE-2026-25253 demuestra que el riesgo de una configuración incorrecta es real. Los tokens deben mantenerse confidenciales, los puertos deben restringirse, las políticas de DM deben endurecerse y las habilidades de alto riesgo deben habilitarse con precaución.

En tercer lugar, la configuración no es un trabajo de una sola vez. A medida que cambian los escenarios de uso, los miembros del equipo aumentan o disminuyen y aparecen nuevas habilidades en línea, las configuraciones deben optimizarse continuamente. Revise su configuración de vez en cuando y ejecute una “auditoría de seguridad de openclaw” para asegurarse de que todo esté bajo control.

Ahora, haz tres cosas inmediatamente:

1. Ejecute auditoría de seguridad de openclaw --deep para verificar la configuración actual
2. Optimice su configuración elemento por elemento de acuerdo con la lista de mejores prácticas de este artículo.
3. Haga una copia de seguridad de la configuración optimizada en un lugar seguro (pero no haga una copia de seguridad del token juntos)

Si encuentra problemas durante el proceso de configuración, la comunidad OpenClaw está activa y hay personas disponibles en los canales de Discusiones y Discord de GitHub para ayudar. También puede compartir su experiencia de configuración: todos la han descubierto paso a paso.