Configuración de variables de entorno en OpenClaw

Gestionar llaves de API y configuraciones en diferentes entornos suele ser un caos. A veces terminas con datos sensibles expuestos o pierdes tiempo intentando entender por qué una configuración no se aplica debido a un archivo oculto que olvidaste.

Para evitar estos problemas, OpenClaw sigue una regla de oro: nunca sobrescribir valores existentes. Aquí te explico cómo manejar tus variables de forma limpia y eficiente.

Requisitos previos

• Tener OpenClaw instalado.
• Un archivo de configuración openclaw.json.
• Un archivo .env (opcional).

Inicio rápido

Configura tus variables en 5 minutos siguiendo estos pasos:

1. Define tus variables: Crea un archivo .env en tu directorio de trabajo o usa el bloque env en tu openclaw.json.
2. Usa la sustitución: En tu openclaw.json, referencia las variables usando la sintaxis ${VAR_NAME}.
3. Verifica la prioridad: Asegúrate de que no existan variables con el mismo nombre en tu shell, ya que OpenClaw no las sobrescribirá.
4. Inicia el Gateway: OpenClaw cargará automáticamente los valores desde las fuentes disponibles.

Orden de prioridad

OpenClaw busca variables en varios lugares. El orden de prioridad (de mayor a menor) es el siguiente:

1. Proceso del entorno: Lo que el proceso del Gateway ya tiene de la shell o daemon padre.
2. .env en el directorio actual: Carga valores por defecto pero no sobrescribe.
3. .env global: Ubicado en ~/.openclaw/.env (o $OPENCLAW_STATE_DIR/.env).
4. Bloque env en el config: Definido en ~/.openclaw/openclaw.json.
5. Importación de shell: Solo para llaves faltantes si env.shellEnv.enabled es true.

Configuración del bloque env

Tienes dos formas equivalentes de definir variables dentro de tu JSON (ambas respetan la regla de no sobrescribir):

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

Importación de entorno de la shell

Si necesitas importar llaves desde tu shell de login, usa env.shellEnv. Esto solo traerá las llaves que falten:

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

También puedes usar estas variables de entorno equivalentes:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Sustitución de variables en el config

Puedes insertar variables de entorno directamente en los valores de cadena de tu configuración:

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}

Variables de entorno para rutas

Variable	Propósito
OPENCLAW_HOME	Cambia el directorio base para todas las rutas internas (~/.openclaw/, agentes, sesiones).
OPENCLAW_STATE_DIR	Cambia solo el directorio de estado (por defecto ~/.openclaw).
OPENCLAW_CONFIG_PATH	Cambia la ruta del archivo de configuración.
OPENCLAW_HOME (Prioridad)	Tiene prioridad sobre $HOME, USERPROFILE y os.homedir().

Ejemplo para un LaunchDaemon en macOS:

<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/kira</string>
</dict>

Solución de problemas

Mi variable de entorno no cambia

OpenClaw nunca sobrescribe valores que ya están definidos. Si una variable está configurada en tu shell (proceso del entorno), ignorará lo que pongas en el archivo .env o en el bloque env de tu openclaw.json. Revisa tu entorno actual antes de buscar errores en los archivos de configuración.

---

¿Necesitas ayuda específica con tu configuración? Prueba el AI Setup Assistant.

Próximos pasos

• Gateway configuration
• FAQ: env vars and .env loading
• Models overview
• Env var substitution in config