Variaveis de ambiente

O OpenClaw obtem variaveis de ambiente de multiplas fontes. A regra e nunca sobrescrever valores existentes.

Precedencia (maior para menor)

Ambiente do processo (o que o processo do Gateway ja tem do shell/daemon pai).
.env no diretorio de trabalho atual (padrao do dotenv; nao sobrescreve).
.env global em ~/.openclaw/.env (alias $OPENCLAW_STATE_DIR/.env; nao sobrescreve).
Bloco env na configuracao em ~/.openclaw/openclaw.json (aplicado somente se ausente).
Importacao opcional do shell de login (env.shellEnv.enabled ou OPENCLAW_LOAD_SHELL_ENV=1), aplicada somente para chaves esperadas ausentes.

Se o arquivo de configuracao estiver completamente ausente, o passo 4 e pulado; a importacao do shell ainda executa se habilitada.

Bloco `env` na configuracao

Duas formas equivalentes de definir variaveis de ambiente inline (ambas nao sobrescrevem):

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

Importacao do env do shell

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

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

Equivalentes em variaveis de ambiente:

OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Variaveis de ambiente injetadas em tempo de execucao

O OpenClaw tambem injeta marcadores de contexto em processos filhos:

OPENCLAW_SHELL=exec: definido para comandos executados pela ferramenta exec.
OPENCLAW_SHELL=acp: definido para spawns de processos backend ACP (por exemplo acpx).
OPENCLAW_SHELL=acp-client: definido para openclaw acp client ao gerar o processo ponte ACP.
OPENCLAW_SHELL=tui-local: definido para comandos shell locais ! do TUI.

Esses sao marcadores de tempo de execucao (nao configuracao de usuario obrigatoria). Podem ser usados em logica de shell/perfil para aplicar regras especificas do contexto.

Variaveis de ambiente da UI

OPENCLAW_THEME=light: forcar a paleta clara do TUI quando seu terminal tem fundo claro.
OPENCLAW_THEME=dark: forcar a paleta escura do TUI.
COLORFGBG: se seu terminal exportar, o OpenClaw usa a dica de cor de fundo para selecionar automaticamente a paleta do TUI.

Substituicao de variaveis de ambiente na configuracao

Voce pode referenciar variaveis de ambiente diretamente em valores de string da configuracao usando a sintaxe ${VAR_NAME}:

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

Veja Configuracao: Substituicao de variaveis de ambiente para detalhes completos.

SecretRef vs strings `${ENV}`

O OpenClaw suporta dois padroes baseados em env:

Substituicao de strings ${VAR} em valores de configuracao.
Objetos SecretRef ({ source: "env", provider: "default", id: "VAR" }) para campos que suportam referencias de segredos.

Ambos resolvem do env do processo no momento da ativacao. Detalhes de SecretRef estao documentados em Gerenciamento de Segredos.

Variaveis de ambiente relacionadas a caminhos

Variavel	Proposito
`OPENCLAW_HOME`	Sobrescrever o diretorio home usado para toda resolucao interna de caminhos (`~/.openclaw/`, diretorios de agentes, sessoes, credenciais). Util ao executar OpenClaw como usuario de servico dedicado.
`OPENCLAW_STATE_DIR`	Sobrescrever o diretorio de estado (padrao `~/.openclaw`).
`OPENCLAW_CONFIG_PATH`	Sobrescrever o caminho do arquivo de configuracao (padrao `~/.openclaw/openclaw.json`).

Logging

Variavel	Proposito
`OPENCLAW_LOG_LEVEL`	Sobrescrever o nivel de log para arquivo e console (ex. `debug`, `trace`). Tem precedencia sobre `logging.level` e `logging.consoleLevel` na configuracao. Valores invalidos sao ignorados com aviso.

`OPENCLAW_HOME`

Quando definido, OPENCLAW_HOME substitui o diretorio home do sistema ($HOME / os.homedir()) para toda resolucao interna de caminhos. Isso permite isolamento completo do sistema de arquivos para contas de servico headless.

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

Exemplo (macOS LaunchDaemon):

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

OPENCLAW_HOME tambem pode ser definido como um caminho com til (ex. ~/svc), que e expandido usando $HOME antes do uso.