Skip to content
BotServBotServ
OpenClawConfiguraciónopenclaw.jsonSeguridadProxmox

Configuración de OpenClaw

Archivos de configuración OpenClaw, variables de entorno y opciones clave. JSON5, Hot Reload y seguridad.

S

schutzgeist

5 min read
Configuración de OpenClaw

Configuración de OpenClaw

Internet Relay Chat und Linux-FAQs

IRC-Mania Die Seite rund um Sicherheit und Programmierung

Internet, Sicherheit , Internet Relay Chat

Qué cubre este artículo sobre configuración de OpenClaw

  • Dónde se almacena la configuración de OpenClaw.
  • Cómo está estructurado openclaw.json.
  • Áreas de configuración clave como agentes, modelos, gateway y seguridad.
  • Variables de entorno y hot reload.
  • Consejos para un setup seguro y limpio.

Introducción: Configuración de OpenClaw

OpenClaw se controla a través de un archivo de configuración JSON5 centralizado. En él se definen agentes, modelos, proveedores, el gateway, canales, skills, plugins y parámetros de seguridad. El archivo puede editarse directamente o administrarse mediante la CLI con openclaw config. En configuraciones locales de IA sobre Proxmox, una configuración limpia es fundamental para que OpenClaw funcione correctamente con Claude, Ollama y otras herramientas.

Este artículo muestra la estructura, las áreas de configuración más importantes y ejemplos típicos para openclaw.json.

Términos clave

  • JSON5: JSON extendido con comentarios y comas finales.
  • openclaw.json: Archivo de configuración central.
  • Directorio de estado: Ruta ~/.openclaw, que contiene la configuración, logs y datos de trabajo.
  • Hot reload: El gateway carga los cambios de configuración automáticamente.
  • Perfiles: Posibilidad de usar diferentes conjuntos de configuración.
  • SecretRef: Referencia a un secreto en lugar del valor en texto plano.
  • Esquema: Estructura contra la cual OpenClaw valida la configuración.

Archivo de configuración

La ruta estándar es:

~/.openclaw/openclaw.json

Se puede establecer una ruta diferente mediante la variable de entorno:

export OPENCLAW_CONFIG_PATH=/ruta/a/openclaw.json

La ruta se puede mostrar con openclaw config file.

Formato

openclaw.json utiliza JSON5. Se permiten comentarios y comas finales. Todos los campos son opcionales, OpenClaw utiliza valores por defecto seguros cuando falta algo.

{
  // Comportamiento predeterminado de agentes
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },

  // Modelos y proveedores
  models: {
    default: {
      primary: "anthropic/claude-opus-4-8",
      fallbacks: ["ollama/llama3.1:8b"],
    },
    providers: {
      anthropic: {
        apiKey: { $secretRef: "anthropic-api-key" },
      },
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://127.0.0.1:11434",
      },
    },
  },

  // Configuración del gateway
  gateway: {
    bind: "127.0.0.1",
    port: 8080,
  },

  // Logging
  logging: {
    level: "info",
  },
}

Áreas de configuración importantes

agents

Aquí se definen valores predeterminados para agentes como workspace, comportamiento o herramientas. Los agentes individuales pueden sobrescribir estos valores.

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
    entries: {
      AgentSmith: {
        // Configuraciones específicas del agente
      },
    },
  },
}

models

models define los proveedores disponibles, modelos predeterminados y fallbacks.

{
  models: {
    default: {
      primary: "anthropic/claude-opus-4-8",
      fallbacks: ["ollama/llama3.1:8b"],
    },
    providers: {
      anthropic: {
        apiKey: { $secretRef: "anthropic-api-key" },
      },
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://127.0.0.1:11434",
      },
    },
  },
}

Importante para Ollama: el endpoint nativo es http://host:11434, no /v1.

gateway

El gateway controla el acceso de red a OpenClaw.

{
  gateway: {
    bind: "127.0.0.1",
    port: 8080,
    auth: {
      token: { $secretRef: "gateway-token" },
    },
  },
}

Consejo de seguridad: Mantén bind en 127.0.0.1 si es posible. Para Tailscale o acceso interno, usa una IP privada apropiada, pero no 0.0.0.0 sin protección adicional.

channels

Los canales conectan OpenClaw con mensajeros u otros servicios. Ejemplos incluyen Slack, Discord, Telegram o Matrix. Cada canal tiene sus propios campos de configuración.

{
  channels: {
    slack: {
      token: { $secretRef: "slack-token" },
    },
  },
}

skills

Los skills son capacidades prefabricadas que los agentes pueden utilizar. Su configuración depende del skill específico.

plugins

Los plugins extienden OpenClaw con funcionalidades adicionales. Los plugins instalados pueden activarse o desactivarse aquí.

security

Configuraciones de seguridad como reglas de auditoría, manejo de tokens u opciones de sandbox.

{
  security: {
    audit: {
      enabled: true,
    },
  },
}

logging

{
  logging: {
    level: "info",
  },
}

Los niveles posibles son trace, debug, info, warn, error y fatal.

env

Variables de entorno inline o instrucciones para importar secretos desde el entorno del shell.

{
  env: {
    ANTHROPIC_API_KEY: { $secretRef: "anthropic-api-key" },
  },
}

Secretos en la configuración

OpenClaw soporta SecretRefs para evitar almacenar valores reales en texto plano en la configuración. Los secretos pueden proporcionarse desde un archivo separado o a través de un gestor de secretos.

{
  models: {
    providers: {
      anthropic: {
        apiKey: { $secretRef: "anthropic-api-key" },
      },
    },
  },
}

Variables de entorno

Variables de entorno importantes:

  • OPENCLAW_CONFIG_PATH: Ruta al archivo de configuración.
  • OPENCLAW_STATE_DIR: Ruta al directorio de estado.
  • OPENCLAW_PROFILE: Nombre del perfil.
  • OPENCLAW_NIX_MODE: Protección de escritura para instalaciones Nix.

Hot reload

El gateway de OpenClaw observa openclaw.json y carga los cambios automáticamente. Aún así, debes verificar después de cambios mayores:

openclaw config validate
openclaw doctor

Configuración desde CLI

Los valores pueden establecerse directamente desde la línea de comandos:

openclaw config set models.default.primary "anthropic/claude-opus-4-8"
openclaw config set models.providers.ollama.baseUrl "http://127.0.0.1:11434"
openclaw config get models.default.primary
openclaw config unset models.default.primary

Validación

La configuración debe verificarse antes de reiniciar:

openclaw config validate
openclaw doctor --lint

Errores comunes

  • Errores de sintaxis JSON5: Los comentarios están permitidos, pero las llaves deben coincidir.
  • Claves desconocidas: OpenClaw no inicia si hay claves desconocidas presentes.
  • Endpoint incorrecto de Ollama: /v1 es incorrecto, http://host:11434 es correcto.
  • Gateway en 0.0.0.0: Riesgo de seguridad sin protección adicional.
  • Secretos en texto plano: Usa SecretRefs.
  • Los cambios de configuración no tienen efecto: Reinicia el gateway o verifica el hot reload.

Enlaces e información complementaria

Preguntas frecuentes: Configuración de OpenClaw

¿Dónde está el archivo de configuración? De forma predeterminada, en ~/.openclaw/openclaw.json.

¿Puedo escribir comentarios en la configuración? Sí, JSON5 permite comentarios.

¿Debo reiniciar después de hacer cambios? El gateway generalmente carga los cambios automáticamente. Si hay problemas, reinicia.

¿Cómo protejo las claves API? Con SecretRefs o variables de entorno.

¿Qué sucede con una configuración inválida? OpenClaw se niega a iniciarse. openclaw config validate muestra los errores.

Referencias y lecturas complementarias

Resumen: Configuración de OpenClaw

VPS Hosting Angebot

Premium VPS Hosting

Schnelle und sichere VPS Server

OpenClaw se configura centralmente a través de ~/.openclaw/openclaw.json. El archivo JSON5 permite comentarios y define agentes, modelos, proveedores, gateway, canales, skills, plugins, seguridad y logging. Lo importante es usar endpoints de modelos correctos, aprovechar SecretRefs, configurar un binding seguro del gateway y validar regularmente. Con una configuración limpia, obtienes una operación estable y segura de OpenClaw en tu propia red.

Volver al blog
Share:

Entradas relacionadas