--- read_when: - Потрібно знати, які змінні середовища завантажуються і в якому порядку - Ви налагоджуєте проблему з відсутніми API-ключами в Gateway - Ви документуєте автентифікацію провайдера або середовища розгортання summary: Звідки OpenClaw завантажує змінні середовища та порядок пріоритетності title: Змінні середовища x-i18n: generated_at: "2026-05-11T20:40:47Z" model: gpt-5.5 provider: openai source_hash: b4b91e9bb3c386292f11a3ffe5ae718a74a800bd19fe95073da990d881e6069d source_path: help/environment.md workflow: 16 --- OpenClaw отримує змінні середовища з кількох джерел. Правило: **ніколи не перевизначати наявні значення**. ## Пріоритетність (найвища → найнижча) 1. **Середовище процесу** (те, що процес Gateway уже має від батьківської оболонки/демона). 2. **`.env` у поточному робочому каталозі** (типова поведінка dotenv; не перевизначає). 3. **Глобальний `.env`** у `~/.openclaw/.env` (також `$OPENCLAW_STATE_DIR/.env`; не перевизначає). 4. **Блок `env` у конфігурації** у `~/.openclaw/openclaw.json` (застосовується лише якщо значення відсутнє). 5. **Необов’язковий імпорт із логін-оболонки** (`env.shellEnv.enabled` або `OPENCLAW_LOAD_SHELL_ENV=1`), застосовується лише для відсутніх очікуваних ключів. У свіжих установках Ubuntu, які використовують типовий каталог стану, OpenClaw також розглядає `~/.config/openclaw/gateway.env` як сумісний резервний варіант після глобального `.env`. Якщо обидва файли існують і розходяться, OpenClaw залишає `~/.openclaw/.env` і виводить попередження. Якщо конфігураційний файл повністю відсутній, крок 4 пропускається; імпорт із оболонки все одно запускається, якщо його ввімкнено. ## Блок `env` у конфігурації Два рівнозначні способи задати вбудовані змінні середовища (обидва не перевизначають наявні значення): ```json5 { env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-...", }, }, } ``` ## Імпорт середовища оболонки `env.shellEnv` запускає вашу логін-оболонку й імпортує лише **відсутні** очікувані ключі: ```json5 { env: { shellEnv: { enabled: true, timeoutMs: 15000, }, }, } ``` Еквіваленти змінних середовища: - `OPENCLAW_LOAD_SHELL_ENV=1` - `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000` ## Змінні середовища, ін’єктовані під час виконання OpenClaw також ін’єктує маркери контексту в породжені дочірні процеси: - `OPENCLAW_SHELL=exec`: установлюється для команд, запущених через інструмент `exec`. - `OPENCLAW_SHELL=acp`: установлюється для породження процесів бекенда середовища виконання ACP (наприклад, `acpx`). - `OPENCLAW_SHELL=acp-client`: установлюється для `openclaw acp client`, коли він породжує процес моста ACP. - `OPENCLAW_SHELL=tui-local`: установлюється для локальних команд оболонки TUI `!`. Це маркери часу виконання (не обов’язкова користувацька конфігурація). Їх можна використовувати в логіці оболонки/профілю для застосування правил, специфічних для контексту. ## Змінні середовища UI - `OPENCLAW_THEME=light`: примусово використовувати світлу палітру TUI, коли ваш термінал має світлий фон. - `OPENCLAW_THEME=dark`: примусово використовувати темну палітру TUI. - `COLORFGBG`: якщо ваш термінал експортує її, OpenClaw використовує підказку кольору фону для автоматичного вибору палітри TUI. ## Підстановка змінних середовища в конфігурації Ви можете напряму посилатися на змінні середовища в рядкових значеннях конфігурації за допомогою синтаксису `${VAR_NAME}`: ```json5 { models: { providers: { "vercel-gateway": { apiKey: "${VERCEL_GATEWAY_API_KEY}", }, }, }, } ``` Повні подробиці див. у [Конфігурація: підстановка змінних середовища](/uk/gateway/configuration-reference#env-var-substitution). ## Secret refs проти рядків `${ENV}` OpenClaw підтримує два шаблони, керовані змінними середовища: - Рядкова підстановка `${VAR}` у значеннях конфігурації. - Об’єкти SecretRef (`{ source: "env", provider: "default", id: "VAR" }`) для полів, які підтримують посилання на секрети. Обидва розв’язуються із середовища процесу під час активації. Подробиці SecretRef задокументовано в [Керуванні секретами](/uk/gateway/secrets). ## Змінні середовища, пов’язані зі шляхами | Змінна | Призначення | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `OPENCLAW_HOME` | Перевизначити домашній каталог, що використовується для всього внутрішнього розв’язання шляхів (`~/.openclaw/`, каталоги агентів, сесії, облікові дані). Корисно під час запуску OpenClaw як окремого службового користувача. | | `OPENCLAW_STATE_DIR` | Перевизначити каталог стану (типово `~/.openclaw`). | | `OPENCLAW_CONFIG_PATH` | Перевизначити шлях до конфігураційного файлу (типово `~/.openclaw/openclaw.json`). | | `OPENCLAW_INCLUDE_ROOTS` | Список шляхів до каталогів, у яких директиви `$include` можуть розв’язувати файли поза каталогом конфігурації (типово: немає — `$include` обмежено каталогом конфігурації). Розгортає тильду. | ## Журналювання | Змінна | Призначення | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OPENCLAW_LOG_LEVEL` | Перевизначити рівень журналювання і для файлу, і для консолі (наприклад, `debug`, `trace`). Має пріоритет над `logging.level` і `logging.consoleLevel` у конфігурації. Некоректні значення ігноруються з попередженням. | | `OPENCLAW_DEBUG_MODEL_TRANSPORT` | Виводити цільову діагностику часу запиту/відповіді моделі на рівні `info` без увімкнення глобальних debug-журналів. | | `OPENCLAW_DEBUG_MODEL_PAYLOAD` | Діагностика корисного навантаження моделі: `summary`, `tools` або `full-redacted`. `full-redacted` обмежується й редагується, але може містити текст підказки/повідомлення. | | `OPENCLAW_DEBUG_SSE` | Діагностика потокової передачі: `events` для часу першої/завершальної події, `peek` для включення перших п’яти відредагованих подій SSE. | | `OPENCLAW_DEBUG_CODE_MODE` | Діагностика поверхні моделі в режимі коду, включно з приховуванням інструментів провайдера та примусовим дотриманням лише exec/wait. | ### `OPENCLAW_HOME` Якщо встановлено, `OPENCLAW_HOME` замінює системний домашній каталог (`$HOME` / `os.homedir()`) для всього внутрішнього розв’язання шляхів. Це забезпечує повну ізоляцію файлової системи для безголових службових облікових записів. **Пріоритетність:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > `os.homedir()` **Приклад** (macOS LaunchDaemon): ```xml EnvironmentVariables OPENCLAW_HOME /Users/user ``` `OPENCLAW_HOME` також можна встановити як шлях із тильдою (наприклад, `~/svc`), який перед використанням розгортається за допомогою `$HOME`. ## Користувачі nvm: збої TLS у web_fetch Якщо Node.js було встановлено через **nvm** (а не системний менеджер пакетів), вбудований `fetch()` використовує вбудоване сховище CA nvm, у якому можуть бути відсутні сучасні кореневі CA (ISRG Root X1/X2 для Let's Encrypt, DigiCert Global Root G2 тощо). Через це `web_fetch` завершується помилкою `"fetch failed"` на більшості HTTPS-сайтів. У Linux OpenClaw автоматично виявляє nvm і застосовує виправлення у фактичному середовищі запуску: - `openclaw gateway install` записує `NODE_EXTRA_CA_CERTS` у середовище служби systemd - вхідна точка CLI `openclaw` повторно запускає себе з установленою `NODE_EXTRA_CA_CERTS` перед запуском Node **Ручне виправлення (для старіших версій або прямих запусків `node ...`):** Експортуйте змінну перед запуском OpenClaw: ```bash export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt openclaw gateway run ``` Не покладайтеся на запис лише в `~/.openclaw/.env` для цієї змінної; Node читає `NODE_EXTRA_CA_CERTS` під час запуску процесу. ## Застарілі змінні середовища OpenClaw читає лише змінні середовища `OPENCLAW_*`. Застарілі префікси `CLAWDBOT_*` і `MOLTBOT_*` із попередніх випусків мовчки ігноруються. Якщо будь-які з них усе ще встановлено в процесі Gateway під час запуску, OpenClaw виводить одне попередження Node про застарівання (`OPENCLAW_LEGACY_ENV_VARS`) зі списком виявлених префіксів і загальною кількістю. Перейменуйте кожне значення, замінивши застарілий префікс на `OPENCLAW_` (наприклад, `CLAWDBOT_GATEWAY_TOKEN` → `OPENCLAW_GATEWAY_TOKEN`); старі назви не мають жодного ефекту. ## Пов’язане - [Конфігурація Gateway](/uk/gateway/configuration) - [Поширені запитання: змінні середовища та завантаження .env](/uk/help/faq#env-vars-and-env-loading) - [Огляд моделей](/uk/concepts/models)