Variáveis de ambiente¶

O OpenClaw obtém variáveis de ambiente de múltiplas fontes. A regra é nunca sobrescrever valores existentes.

Precedência (mais alta → mais baixa)¶

1. Ambiente do processo (o que o processo do Gateway já possui do shell/daemon pai).
2. .env no diretório de trabalho atual (padrão do dotenv; não sobrescreve).
3. .env global em ~/.openclaw/.env (também conhecido como $OPENCLAW_STATE_DIR/.env; não sobrescreve).
4. Bloco de Configuração env em ~/.openclaw/openclaw.json (aplicado apenas se estiver ausente).
5. Importação opcional do shell de login (env.shellEnv.enabled ou OPENCLAW_LOAD_SHELL_ENV=1), aplicada apenas para chaves esperadas ausentes.

Se o arquivo de configuração estiver totalmente ausente, a etapa 4 é ignorada; a importação do shell ainda é executada se estiver habilitada.

Bloco de Configuração env¶

Duas formas equivalentes de definir variáveis de ambiente inline (ambas não sobrescrevem):

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

Importação de env do shell¶

env.shellEnv executa seu shell de login e importa apenas chaves esperadas ausentes:

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

Inserir equivalentes:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Substituição de variáveis de ambiente na configuração¶

Você pode referenciar variáveis de ambiente diretamente em valores de string da configuração usando a sintaxe ${VAR_NAME}:

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

Veja Configuração: Substituição de variáveis de ambiente para todos os detalhes.

Variáveis de ambiente relacionadas a caminhos¶

OPENCLAW_HOME¶

Quando definido, OPENCLAW_HOME substitui o diretório home do sistema ($HOME / os.homedir()) para toda a resolução interna de caminhos. Isso habilita isolamento completo do sistema de arquivos para contas de serviço headless.

Precedência: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

Exemplo (LaunchDaemon no macOS):

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

OPENCLAW_HOME também pode ser definido como um caminho com til (por exemplo, ~/svc), que é expandido usando $HOME antes do uso.

Relacionados¶

• Configuração do Gateway
• Perguntas frequentes: variáveis de ambiente e carregamento de .env
• Visão geral de modelos