Variáveis de ambiente

O OpenClaw obtém variáveis de ambiente de várias fontes. A regra é nunca sobrescrever valores existentes. Os arquivos .env do espaço de trabalho são uma fonte menos confiável: o OpenClaw ignora credenciais de provedores e controles de runtime protegidos provenientes do .env do espaço de trabalho antes de aplicar a precedência.

Precedência (da mais alta para a mais baixa)

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; credenciais de provedores e controles de runtime protegidos são ignorados).
3. .env global em ~/.openclaw/.env (também conhecido como $OPENCLAW_STATE_DIR/.env; recomendado para chaves de API de provedores; não sobrescreve).
4. Bloco env da configuração em ~/.openclaw/openclaw.json (aplicado somente se o valor estiver ausente).
5. Importação opcional do shell de login (env.shellEnv.enabled ou OPENCLAW_LOAD_SHELL_ENV=1), aplicada somente às chaves esperadas que estiverem ausentes.

Em instalações novas do Ubuntu que usam o diretório de estado padrão, o OpenClaw também trata ~/.config/openclaw/gateway.env como alternativa de compatibilidade após o .env global. Se os dois arquivos existirem e tiverem valores divergentes, o OpenClaw mantém ~/.openclaw/.env e exibe um aviso.

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

Credenciais de provedores e .env do espaço de trabalho

Não mantenha chaves de API de provedores somente em um .env do espaço de trabalho. O OpenClaw bloqueia nos arquivos .env do espaço de trabalho um grande conjunto de chaves de credenciais e redirecionamento de endpoints de provedores, incluindo todas as variáveis de ambiente conhecidas de autenticação de provedores (por exemplo, GEMINI_API_KEY, GOOGLE_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY, PERPLEXITY_API_KEY, BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY, FIRECRAWL_API_KEY), além de qualquer chave terminada em _API_HOST, _BASE_URL ou _HOMESERVER, bem como todos os namespaces OPENCLAW_*, CLAWHUB_*, ANTHROPIC_API_KEY_* e OPENAI_API_KEY_*.

Em vez disso, use uma destas fontes confiáveis para as credenciais de provedores:

• O ambiente do processo do Gateway, como um shell, uma unidade do launchd/systemd, um segredo de contêiner ou um segredo de CI.
• O arquivo dotenv global do runtime em ~/.openclaw/.env ou $OPENCLAW_STATE_DIR/.env.
• O bloco env da configuração em ~/.openclaw/openclaw.json.
• A importação opcional do shell de login quando env.shellEnv.enabled ou OPENCLAW_LOAD_SHELL_ENV=1 estiver habilitado.

Se você armazenava anteriormente chaves de provedores somente em um .env do espaço de trabalho, mova-as para uma das fontes confiáveis acima. O .env do espaço de trabalho ainda pode fornecer variáveis comuns do projeto que não sejam credenciais, redirecionamentos de endpoints, substituições de host ou controles de runtime OPENCLAW_*.

Consulte Arquivos .env do espaço de trabalho para entender a justificativa de segurança.

Bloco env da configuração

Duas formas equivalentes de definir variáveis de ambiente diretamente (nenhuma delas sobrescreve valores existentes):

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

O bloco env da configuração aceita somente valores de string literais. Ele não expande valores file:...; por exemplo, XAI_API_KEY: "file:secrets/xai-api-key.txt" é repassado aos provedores exatamente como essa string.

Para chaves de provedores armazenadas em arquivos, use uma SecretRef no campo de credencial que oferece suporte a ela:

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

Consulte Gerenciamento de segredos e a superfície de credenciais SecretRef para conhecer os campos compatíveis.

Importação de variáveis de ambiente do shell

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

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

Variáveis de ambiente equivalentes:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000 (padrão: 15000)

Instantâneos do shell de execução

Em hosts do Gateway que não usam Windows, os comandos exec do bash e zsh usam um instantâneo de inicialização por padrão. Defina OPENCLAW_EXEC_SHELL_SNAPSHOT=0 no ambiente do processo do Gateway para desabilitar esse caminho. Os valores false, no e off também o desabilitam. Os valores de exec.env de cada chamada não podem ativar ou desativar os instantâneos nem redirecionar o cache de instantâneos.

Variáveis de ambiente injetadas pelo runtime

O OpenClaw também injeta marcadores de contexto nos processos filhos iniciados:

• OPENCLAW_SHELL=exec: definido para comandos executados por meio da ferramenta exec.
• OPENCLAW_SHELL=acp-client: definido para openclaw acp client quando ele inicia o processo de ponte ACP.
• OPENCLAW_SHELL=tui-local: definido para comandos de shell ! locais da TUI.
• OPENCLAW_CLI=1: definido para processos filhos iniciados pelo ponto de entrada da CLI.

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

Variáveis de ambiente da interface

• OPENCLAW_THEME=light: força a paleta clara da TUI quando o terminal tem fundo claro.
• OPENCLAW_THEME=dark: força a paleta escura da TUI.
• COLORFGBG: se o terminal a exportar, o OpenClaw usará a indicação da cor de fundo para selecionar automaticamente a paleta da TUI.

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

Você pode referenciar variáveis de ambiente diretamente nos 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 obter todos os detalhes.

Referências de segredos versus strings ${ENV}

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

• Substituição de strings ${VAR} nos valores da configuração.
• Objetos SecretRef ({ source: "env", provider: "default", id: "VAR" }) para campos que aceitam 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. O próprio bloco env da configuração não resolve SecretRefs nem valores abreviados file:....

Variáveis de ambiente relacionadas a caminhos

Registro em log

OPENCLAW_HOME

Quando definido, OPENCLAW_HOME substitui o diretório inicial do sistema ($HOME / os.homedir()) nos caminhos internos padrão do OpenClaw. Isso inclui o diretório de estado padrão, o caminho da configuração, os diretórios de agentes, as credenciais, o espaço de trabalho de integração inicial do instalador e o checkout de desenvolvimento padrão usado por openclaw update --channel dev.

Precedência: OPENCLAW_HOME > $HOME > USERPROFILE > diretório inicial alternativo do PREFIX do Termux no Android > os.homedir()

Exemplo (LaunchDaemon do macOS):

<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 a mesma cadeia de alternativas para o diretório inicial do sistema operacional antes do uso.

Variáveis de caminho explícitas, como OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH e OPENCLAW_GIT_DIR, ainda têm precedência. Tarefas da conta do sistema operacional, como detecção do arquivo de inicialização do shell, configuração do gerenciador de pacotes e expansão de ~ no host, ainda podem usar o diretório inicial real do sistema.

Usuários do nvm: falhas de TLS no web_fetch

Se o Node.js foi instalado por meio do nvm (e não pelo gerenciador de pacotes do sistema), o fetch() integrado usa o repositório de CAs incluído no nvm, que pode não conter CAs raiz modernas (ISRG Root X1/X2 da 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 execuções diretas de 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 essa variável somente em ~/.openclaw/.env; 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 silenciosamente ignorados.

Se algum deles ainda estiver definido no processo do Gateway durante a inicialização, o OpenClaw emitirá um único aviso de descontinuação do Node (OPENCLAW_LEGACY_ENV_VARS) que lista os prefixos detectados e a contagem total. Renomeie cada valor substituindo o prefixo legado por OPENCLAW_ (por exemplo, de CLAWDBOT_GATEWAY_TOKEN para OPENCLAW_GATEWAY_TOKEN); os nomes antigos não têm efeito.

Relacionados

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