--- read_when: - Потрібно знати, які змінні середовища завантажуються і в якому порядку - Ви налагоджуєте проблему з відсутніми ключами API у Gateway - Ви документуєте автентифікацію провайдера або середовища розгортання summary: Де OpenClaw завантажує змінні середовища та порядок пріоритетності title: Змінні середовища x-i18n: generated_at: "2026-06-27T17:38:08Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 7e36f93efe29f9cc0e9942659c323a635d21fcaa436427dcb21f5694e5d0458b source_path: help/environment.md workflow: 16 --- OpenClaw отримує змінні середовища з кількох джерел. Правило: **ніколи не перевизначати наявні значення**. Файли `.env` робочої області є джерелом із нижчим рівнем довіри: OpenClaw ігнорує облікові дані провайдерів і захищені елементи керування середовищем виконання з `.env` робочої області перед застосуванням пріоритету. ## Пріоритет (найвищий → найнижчий) 1. **Середовище процесу** (те, що процес Gateway уже має з батьківської оболонки/демона). 2. **`.env` у поточному робочому каталозі** (типово для dotenv; не перевизначає; облікові дані провайдерів і захищені елементи керування середовищем виконання ігноруються). 3. **Глобальний `.env`** у `~/.openclaw/.env` (також `$OPENCLAW_STATE_DIR/.env`; рекомендовано для API-ключів провайдерів; не перевизначає). 4. **Блок `env` конфігурації** у `~/.openclaw/openclaw.json` (застосовується лише якщо значення відсутнє). 5. **Необов’язковий імпорт із login shell** (`env.shellEnv.enabled` або `OPENCLAW_LOAD_SHELL_ENV=1`), застосовується лише для відсутніх очікуваних ключів. У свіжих установках Ubuntu, які використовують типовий каталог стану, OpenClaw також розглядає `~/.config/openclaw/gateway.env` як резервний варіант сумісності після глобального `.env`. Якщо обидва файли існують і не збігаються, OpenClaw залишає `~/.openclaw/.env` і виводить попередження. Якщо конфігураційний файл повністю відсутній, крок 4 пропускається; імпорт з оболонки все одно виконується, якщо його ввімкнено. ## Облікові дані провайдерів і `.env` робочої області Не зберігайте API-ключі провайдерів лише в `.env` робочої області. OpenClaw ігнорує змінні середовища облікових даних провайдерів із файлів `.env` робочої області, зокрема поширені ключі, як-от `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`. Використовуйте одне з цих довірених джерел для облікових даних провайдерів: - Середовище процесу Gateway, наприклад оболонку, unit launchd/systemd, секрет контейнера або секрет CI. - Глобальний файл dotenv середовища виконання у `~/.openclaw/.env` або `$OPENCLAW_STATE_DIR/.env`. - Блок `env` конфігурації у `~/.openclaw/openclaw.json`. - Необов’язковий імпорт із login shell, коли ввімкнено `env.shellEnv.enabled` або `OPENCLAW_LOAD_SHELL_ENV=1`. Якщо раніше ви зберігали ключі провайдерів лише в `.env` робочої області, перемістіть їх до одного з довірених джерел вище. `.env` робочої області все ще може надавати звичайні змінні проєкту, які не є обліковими даними, перенаправленнями endpoint, перевизначеннями host або елементами керування середовищем виконання `OPENCLAW_*`. Див. [Файли `.env` робочої області](/uk/gateway/security#workspace-env-files) для пояснення міркувань безпеки. ## Блок `env` конфігурації Два рівноцінні способи встановити inline-змінні середовища (обидва не перевизначають): ```json5 { env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-...", }, }, } ``` Блок `env` конфігурації приймає лише буквальні рядкові значення. Він не розгортає значення `file:...`; наприклад, `XAI_API_KEY: "file:secrets/xai-api-key.txt"` передається провайдерам саме як цей рядок. Для ключів провайдерів, що зберігаються у файлах, використовуйте SecretRef у полі облікових даних, яке це підтримує: ```json5 { 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" }, }, }, }, } ``` Див. [Керування секретами](/uk/gateway/secrets) і [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) щодо підтримуваних полів. ## Імпорт середовища оболонки `env.shellEnv` запускає вашу login shell і імпортує лише **відсутні** очікувані ключі: ```json5 { env: { shellEnv: { enabled: true, timeoutMs: 15000, }, }, } ``` Еквіваленти змінних середовища: - `OPENCLAW_LOAD_SHELL_ENV=1` - `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000` ## Знімки exec-оболонки На хостах Gateway не Windows команди bash і zsh `exec` типово використовують стартовий знімок. Установіть `OPENCLAW_EXEC_SHELL_SNAPSHOT=0` у середовищі процесу Gateway, щоб вимкнути цей шлях. Значення `false`, `no` і `off` також його вимикають. Значення `exec.env` для окремого виклику не можуть перемикати знімки або перенаправляти кеш знімків. ## Змінні середовища, ін’єктовані середовищем виконання OpenClaw також ін’єктує контекстні маркери в породжені дочірні процеси: - `OPENCLAW_SHELL=exec`: установлюється для команд, запущених через інструмент `exec`. - `OPENCLAW_SHELL=acp`: установлюється для породжень процесів backend середовища виконання ACP (наприклад `acpx`). - `OPENCLAW_SHELL=acp-client`: установлюється для `openclaw acp client`, коли він породжує процес мосту ACP. - `OPENCLAW_SHELL=tui-local`: установлюється для локальних shell-команд TUI `!`. - `OPENCLAW_CLI=1`: установлюється для дочірніх процесів, породжених точкою входу CLI. Це маркери середовища виконання (не обов’язкова користувацька конфігурація). Їх можна використовувати в логіці shell/profile для застосування контекстно-специфічних правил. ## Змінні середовища 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). Сам блок `env` конфігурації не розв’язує SecretRefs або скорочені значення `file:...`. ## Змінні середовища, пов’язані зі шляхами | Змінна | Призначення | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OPENCLAW_HOME` | Перевизначає домашній каталог, який використовується для внутрішніх типових шляхів OpenClaw (`~/.openclaw/`, каталоги агентів, сесії, облікові дані, installer onboarding і типовий dev checkout). Корисно під час запуску OpenClaw як окремого service user. | | `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` | Діагностика payload моделі: `summary`, `tools` або `full-redacted`. `full-redacted` обмежується за розміром і редагується, але може містити текст prompt/повідомлення. | | `OPENCLAW_DEBUG_SSE` | Діагностика streaming: `events` для таймінгу first/done, `peek` для включення перших п’яти відредагованих подій SSE. | | `OPENCLAW_DEBUG_CODE_MODE` | Діагностика model-surface для code-mode, зокрема приховування provider-tool і забезпечення режиму лише exec/wait. | ### `OPENCLAW_HOME` Коли встановлено, `OPENCLAW_HOME` замінює системний домашній каталог (`$HOME` / `os.homedir()`) для внутрішніх типових шляхів OpenClaw. Це охоплює типовий каталог стану, шлях конфігурації, каталоги агентів, облікові дані, робочу область installer onboarding і типовий dev checkout, який використовується `openclaw update --channel dev`. **Пріоритет:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > резервний home Termux `PREFIX` на Android > `os.homedir()` **Приклад** (macOS LaunchDaemon): ```xml EnvironmentVariables OPENCLAW_HOME /Users/user ``` `OPENCLAW_HOME` також можна встановити як шлях із тильдою (наприклад `~/svc`), який перед використанням розгортається за тим самим ланцюжком резервного home ОС. Явні змінні шляхів, як-от `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH` і `OPENCLAW_GIT_DIR`, все ще мають пріоритет. Завдання облікового запису ОС, як-от виявлення стартового файлу оболонки, налаштування package-manager і розгортання `~` на хості, все ще можуть використовувати справжній системний home. ## Користувачі nvm: збої TLS у web_fetch Якщо Node.js було встановлено через **nvm** (а не системний package manager), вбудований `fetch()` використовує пакетне сховище CA від nvm, у якому можуть бути відсутні сучасні root 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) - [FAQ: змінні середовища та завантаження .env](/uk/help/faq#env-vars-and-env-loading) - [Огляд моделей](/uk/concepts/models)