Variables de entorno

OpenClaw obtiene variables de entorno de multiples fuentes. La regla es nunca sobreescribir valores existentes.

Precedencia (mayor a menor)

1. Entorno del proceso (lo que el proceso del Gateway ya tiene del shell/daemon padre).
2. .env en el directorio de trabajo actual (comportamiento por defecto de dotenv; no sobreescribe).
3. .env global en ~/.openclaw/.env (alias $OPENCLAW_STATE_DIR/.env; no sobreescribe).
4. Bloque env en la configuracion en ~/.openclaw/openclaw.json (aplicado solo si falta).
5. Importacion opcional del shell de login (env.shellEnv.enabled o OPENCLAW_LOAD_SHELL_ENV=1), aplicado solo para claves esperadas faltantes.

Si el archivo de configuracion no existe, el paso 4 se omite; la importacion del shell aun se ejecuta si esta habilitada.

Bloque env en la configuracion

Dos formas equivalentes de establecer variables de entorno en linea (ambas son no sobreescribientes):

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

Importacion de env del shell

env.shellEnv ejecuta tu shell de login e importa solo las claves esperadas faltantes:

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

Equivalentes con variables de entorno:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Variables de entorno inyectadas en tiempo de ejecucion

OpenClaw tambien inyecta marcadores de contexto en los procesos hijos generados:

• OPENCLAW_SHELL=exec: establecido para comandos ejecutados a traves de la herramienta exec.
• OPENCLAW_SHELL=acp: establecido para spawns de procesos backend ACP (por ejemplo acpx).
• OPENCLAW_SHELL=acp-client: establecido para openclaw acp client cuando genera el proceso puente ACP.
• OPENCLAW_SHELL=tui-local: establecido para comandos shell locales ! del TUI.

Estos son marcadores de tiempo de ejecucion (no configuracion de usuario requerida). Pueden usarse en logica de shell/perfil para aplicar reglas especificas del contexto.

Variables de entorno de UI

• OPENCLAW_THEME=light: forzar la paleta clara del TUI cuando tu terminal tiene fondo claro.
• OPENCLAW_THEME=dark: forzar la paleta oscura del TUI.
• COLORFGBG: si tu terminal lo exporta, OpenClaw usa la pista de color de fondo para auto-seleccionar la paleta del TUI.

Sustitucion de variables de entorno en la configuracion

Puedes referenciar variables de entorno directamente en valores de cadena de la configuracion usando la sintaxis ${VAR_NAME}:

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

Consulta Configuracion: Sustitucion de variables de entorno para detalles completos.

SecretRef vs cadenas ${ENV}

OpenClaw soporta dos patrones basados en env:

• Sustitucion de cadenas ${VAR} en valores de configuracion.
• Objetos SecretRef ({ source: "env", provider: "default", id: "VAR" }) para campos que soportan referencias de secretos.

Ambos se resuelven desde el env del proceso en el momento de activacion. Los detalles de SecretRef estan documentados en Gestion de Secretos.

Variables de entorno relacionadas con rutas

Logging

OPENCLAW_HOME

Cuando se establece, OPENCLAW_HOME reemplaza el directorio home del sistema ($HOME / os.homedir()) para toda la resolucion interna de rutas. Esto permite el aislamiento completo del sistema de archivos para cuentas de servicio headless.

Precedencia: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

Ejemplo (macOS LaunchDaemon):

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

OPENCLAW_HOME tambien puede establecerse como una ruta con tilde (ej. ~/svc), que se expande usando $HOME antes de usarse.

Relacionado

• Configuracion del Gateway
• FAQ: variables de entorno y carga de .env
• Resumen de modelos