Zmienne środowiskowe

OpenClaw pobiera zmienne środowiskowe z wielu źródeł. Zasada brzmi: nigdy nie nadpisuj istniejących wartości.

Priorytet (najwyższy → najniższy)

1. Środowisko procesu (to, co proces Gateway ma już z nadrzędnej powłoki/demona).
2. .env w bieżącym katalogu roboczym (domyślne dotenv; nie nadpisuje).
3. Globalny .env w ~/.openclaw/.env (czyli $OPENCLAW_STATE_DIR/.env; nie nadpisuje).
4. Blok env w konfiguracji w ~/.openclaw/openclaw.json (stosowany tylko wtedy, gdy brakuje wartości).
5. Opcjonalny import z powłoki logowania (env.shellEnv.enabled lub OPENCLAW_LOAD_SHELL_ENV=1), stosowany tylko dla brakujących oczekiwanych kluczy.

W świeżych instalacjach Ubuntu używających domyślnego katalogu stanu OpenClaw traktuje też ~/.config/openclaw/gateway.env jako zapasową ścieżkę zgodności po globalnym .env. Jeśli oba pliki istnieją i są ze sobą sprzeczne, OpenClaw zachowuje ~/.openclaw/.env i wyświetla ostrzeżenie.

Jeśli plik konfiguracyjny w ogóle nie istnieje, krok 4 jest pomijany; import z powłoki nadal działa, jeśli jest włączony.

Blok env w konfiguracji

Dwa równoważne sposoby ustawiania wbudowanych zmiennych env (oba nie nadpisują istniejących wartości):

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

Import env z powłoki

env.shellEnv uruchamia powłokę logowania i importuje tylko brakujące oczekiwane klucze:

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

Odpowiedniki jako zmienne env:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Zmienne env wstrzykiwane w czasie działania

OpenClaw wstrzykuje też znaczniki kontekstu do uruchamianych procesów podrzędnych:

• OPENCLAW_SHELL=exec: ustawiane dla poleceń uruchamianych przez narzędzie exec.
• OPENCLAW_SHELL=acp: ustawiane dla uruchomień procesów zaplecza środowiska uruchomieniowego ACP (na przykład acpx).
• OPENCLAW_SHELL=acp-client: ustawiane dla openclaw acp client, gdy uruchamia proces mostka ACP.
• OPENCLAW_SHELL=tui-local: ustawiane dla lokalnych poleceń powłoki TUI !.

Są to znaczniki czasu działania (nie wymagana konfiguracja użytkownika). Można ich używać w logice powłoki/profilu do stosowania reguł zależnych od kontekstu.

Zmienne env UI

• OPENCLAW_THEME=light: wymusza jasną paletę TUI, gdy terminal ma jasne tło.
• OPENCLAW_THEME=dark: wymusza ciemną paletę TUI.
• COLORFGBG: jeśli terminal ją eksportuje, OpenClaw używa wskazówki koloru tła do automatycznego wyboru palety TUI.

Podstawianie zmiennych env w konfiguracji

Możesz odwoływać się do zmiennych env bezpośrednio w wartościach ciągów konfiguracji przy użyciu składni ${VAR_NAME}:

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

Pełne szczegóły znajdziesz w sekcji Konfiguracja: podstawianie zmiennych env.

Odwołania do sekretów a ciągi ${ENV}

OpenClaw obsługuje dwa wzorce oparte na env:

• Podstawianie ciągów ${VAR} w wartościach konfiguracji.
• Obiekty SecretRef ({ source: "env", provider: "default", id: "VAR" }) dla pól, które obsługują odwołania do sekretów.

Oba są rozwiązywane ze środowiska procesu w momencie aktywacji. Szczegóły SecretRef są udokumentowane w sekcji Zarządzanie sekretami.

Zmienne env związane ze ścieżkami

Logowanie

OPENCLAW_HOME

Gdy jest ustawione, OPENCLAW_HOME zastępuje systemowy katalog domowy ($HOME / os.homedir()) dla całego wewnętrznego rozwiązywania ścieżek. Umożliwia to pełną izolację systemu plików dla bezgłowych kont usługowych.

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

Przykład (macOS LaunchDaemon):

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

OPENCLAW_HOME można też ustawić na ścieżkę z tyldą (np. ~/svc), która przed użyciem zostanie rozwinięta przy użyciu $HOME.

Użytkownicy nvm: błędy TLS w web_fetch

Jeśli Node.js został zainstalowany przez nvm (a nie systemowego menedżera pakietów), wbudowane fetch() używa dołączonego magazynu CA z nvm, w którym może brakować nowoczesnych głównych CA (ISRG Root X1/X2 dla Let's Encrypt, DigiCert Global Root G2 itd.). Powoduje to niepowodzenie web_fetch z błędem "fetch failed" w większości witryn HTTPS.

W systemie Linux OpenClaw automatycznie wykrywa nvm i stosuje poprawkę w rzeczywistym środowisku startowym:

• openclaw gateway install zapisuje NODE_EXTRA_CA_CERTS w środowisku usługi systemd
• punkt wejścia CLI openclaw ponownie uruchamia sam siebie z ustawionym NODE_EXTRA_CA_CERTS przed startem Node

Ręczna poprawka (dla starszych wersji lub bezpośrednich uruchomień node ...):

Wyeksportuj zmienną przed uruchomieniem OpenClaw:

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

Nie polegaj na zapisaniu tej zmiennej wyłącznie w ~/.openclaw/.env; Node odczytuje NODE_EXTRA_CA_CERTS przy starcie procesu.

Starsze zmienne środowiskowe

OpenClaw odczytuje tylko zmienne środowiskowe OPENCLAW_*. Starsze prefiksy CLAWDBOT_* i MOLTBOT_* z wcześniejszych wersji są po cichu ignorowane.

Jeśli którekolwiek z nich nadal są ustawione w procesie Gateway podczas startu, OpenClaw emituje pojedyncze ostrzeżenie o wycofaniu Node (OPENCLAW_LEGACY_ENV_VARS) z listą wykrytych prefiksów i łączną liczbą. Zmień nazwę każdej wartości, zastępując starszy prefiks prefiksem OPENCLAW_ (na przykład CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN); stare nazwy nie mają żadnego efektu.

Powiązane

• Konfiguracja Gateway
• FAQ: zmienne env i ładowanie .env
• Omówienie modeli