Variáveis de ambiente

OpenClaw carrega variáveis de ambiente de várias fontes. A regra é nunca sobrescrever valores existentes.

Precedência (maior → menor)

1. Ambiente do processo (o que o processo do Gateway já recebeu 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 env da configuração em ~/.openclaw/openclaw.json (aplicado somente se estiver ausente).
5. Importação opcional do shell de login (env.shellEnv.enabled ou OPENCLAW_LOAD_SHELL_ENV=1), aplicada somente para chaves esperadas ausentes.

Em instalações novas no Ubuntu que usam o diretório de estado padrão, o OpenClaw também trata ~/.config/openclaw/gateway.env como fallback de compatibilidade após o .env global. Se ambos os arquivos existirem e divergirem, o OpenClaw mantém ~/.openclaw/.env e imprime um aviso.

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

Bloco env da configuração

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 do ambiente do shell

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

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

Equivalentes em variáveis de ambiente:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Variáveis de ambiente injetadas em tempo de execução

O OpenClaw também injeta marcadores de contexto em processos filhos gerados:

• OPENCLAW_SHELL=exec: definido para comandos executados por meio da ferramenta exec.
• OPENCLAW_SHELL=acp: definido para spawns de processos de backend de runtime ACP (por exemplo, acpx).
• OPENCLAW_SHELL=acp-client: definido para openclaw acp client quando ele gera o processo de ponte ACP.
• OPENCLAW_SHELL=tui-local: definido para comandos de shell ! da TUI local.

Estes são marcadores de runtime (não são configuração obrigatória do usuário). Eles podem ser usados na lógica de shell/perfil para aplicar regras específicas de contexto.

Variáveis de ambiente da UI

• OPENCLAW_THEME=light: força a paleta clara da TUI quando seu terminal tem fundo claro.
• OPENCLAW_THEME=dark: força a paleta escura da TUI.
• COLORFGBG: se seu terminal a exportar, o OpenClaw usa a dica de cor de fundo para escolher automaticamente a paleta da TUI.

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}",      },    },  },}

Consulte Configuração: substituição de variáveis de ambiente para detalhes completos.

Referências secretas vs strings ${ENV}

O OpenClaw oferece suporte a dois padrões baseados em variáveis de ambiente:

• Substituição de strings ${VAR} em valores de configuração.
• Objetos SecretRef ({ source: "env", provider: "default", id: "VAR" }) para campos que oferecem suporte a referências de segredos.

Ambos são resolvidos a partir do ambiente do processo no momento da ativação. Os detalhes de SecretRef estão documentados em Gerenciamento de segredos.

Variáveis de ambiente relacionadas a caminhos

Logging

OPENCLAW_HOME

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

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

Exemplo (macOS LaunchDaemon):

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

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

usuários de nvm: falhas de TLS no web_fetch

Se o Node.js foi instalado via nvm (não pelo gerenciador de pacotes do sistema), o fetch() integrado usa o armazenamento de CAs empacotado do nvm, que pode não conter CAs raiz modernas (ISRG Root X1/X2 para Let's Encrypt, DigiCert Global Root G2 etc.). Isso faz com que web_fetch falhe com "fetch failed" na maioria dos sites HTTPS.

No Linux, o OpenClaw detecta automaticamente o nvm e aplica a correção no ambiente real de inicialização:

• openclaw gateway install grava NODE_EXTRA_CA_CERTS no ambiente do serviço systemd
• o ponto de entrada da CLI openclaw executa novamente a si próprio com NODE_EXTRA_CA_CERTS definido antes da inicialização do Node

Correção manual (para versões mais antigas ou inicializações diretas com node ...):

Exporte a variável antes de iniciar o OpenClaw:

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crtopenclaw gateway run

Não dependa de gravar somente em ~/.openclaw/.env para essa variável; o Node lê NODE_EXTRA_CA_CERTS na inicialização do processo.

Variáveis de ambiente legadas

O OpenClaw lê somente variáveis de ambiente OPENCLAW_*. Os prefixos legados CLAWDBOT_* e MOLTBOT_* de versões anteriores são ignorados silenciosamente.

Se alguma ainda estiver definida no processo do Gateway durante a inicialização, o OpenClaw emite um único aviso de depreciação do Node (OPENCLAW_LEGACY_ENV_VARS) listando os prefixos detectados e a contagem total. Renomeie cada valor substituindo o prefixo legado por OPENCLAW_ (por exemplo, CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN); os nomes antigos não têm efeito.

Relacionados

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