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)

Ambiente do processo (o que o processo do Gateway já recebeu do shell/daemon pai).
.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).
.env global em ~/.openclaw/.env (também conhecido como $OPENCLAW_STATE_DIR/.env; recomendado para chaves de API de provedores; não sobrescreve).
Bloco env da configuração em ~/.openclaw/openclaw.json (aplicado somente se o valor estiver ausente).
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

Variável	Finalidade
`OPENCLAW_HOME`	Substitui o diretório inicial usado para os caminhos internos padrão do OpenClaw (`~/.openclaw/`, diretórios de agentes, sessões, credenciais, integração inicial do instalador e o checkout de desenvolvimento padrão). Útil ao executar o OpenClaw como um usuário de serviço dedicado.
`OPENCLAW_STATE_DIR`	Substitui o diretório de estado (padrão: `~/.openclaw`).
`OPENCLAW_CONFIG_PATH`	Substitui o caminho do arquivo de configuração (padrão: `~/.openclaw/openclaw.json`).
`OPENCLAW_INCLUDE_ROOTS`	Lista de caminhos de diretórios nos quais as diretivas `$include` podem resolver arquivos fora do diretório de configuração (padrão: nenhum — `$include` fica restrito ao diretório de configuração). Expande til.

Registro em log

Variável	Finalidade
`OPENCLAW_LOG_LEVEL`	Substitui o nível de log tanto para arquivo quanto para console (por exemplo, `debug`, `trace`). Tem precedência sobre `logging.level` e `logging.consoleLevel` na configuração. Valores inválidos são ignorados com um aviso.
`OPENCLAW_DEBUG_MODEL_TRANSPORT`	Emite diagnósticos específicos de temporização de solicitação/resposta do modelo no nível `info` sem habilitar logs de depuração globais.
`OPENCLAW_DEBUG_MODEL_PAYLOAD`	Diagnósticos da carga útil do modelo: `summary`, `tools` ou `full-redacted`. `full-redacted` tem tamanho limitado e é submetido a ocultação, mas pode incluir texto de prompts/mensagens.
`OPENCLAW_DEBUG_SSE`	Diagnósticos de streaming: `events` para a temporização do primeiro evento/conclusão, `peek` para incluir os cinco primeiros eventos SSE com dados ocultados.
`OPENCLAW_DEBUG_CODE_MODE`	Diagnósticos da superfície do modelo no modo de código, incluindo ocultação de ferramentas do provedor e aplicação compacta de controles/diretivas.

`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.crt
openclaw 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.

Start here

FAQ

Testing

Diagnostics

Community and meta

Variáveis de ambiente

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

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

Bloco `env` da configuração

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

Instantâneos do shell de execução

Variáveis de ambiente injetadas pelo runtime

Variáveis de ambiente da interface

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

Referências de segredos versus strings `${ENV}`

Variáveis de ambiente relacionadas a caminhos

Registro em log

`OPENCLAW_HOME`

Usuários do nvm: falhas de TLS no web_fetch

Variáveis de ambiente legadas

Relacionados

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

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

​Bloco env da configuração

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

​Instantâneos do shell de execução

​Variáveis de ambiente injetadas pelo runtime

​Variáveis de ambiente da interface

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

​Referências de segredos versus strings ${ENV}

​Variáveis de ambiente relacionadas a caminhos

​Registro em log

​OPENCLAW_HOME

​Usuários do nvm: falhas de TLS no web_fetch

​Variáveis de ambiente legadas

​Relacionados

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

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

Bloco `env` da configuração

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

Instantâneos do shell de execução

Variáveis de ambiente injetadas pelo runtime

Variáveis de ambiente da interface

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

Referências de segredos versus strings `${ENV}`

Variáveis de ambiente relacionadas a caminhos

Registro em log

`OPENCLAW_HOME`

Usuários do nvm: falhas de TLS no web_fetch

Variáveis de ambiente legadas

Relacionados