OpenClaw читає необов’язкову конфігурацію зDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
~/.openclaw/openclaw.json.
Активний шлях конфігурації має бути звичайним файлом. Макети openclaw.json
із символічними посиланнями не підтримуються для записів, якими володіє OpenClaw; атомарний запис може замінити
шлях замість збереження символічного посилання. Якщо ви зберігаєте конфігурацію поза
типовим каталогом стану, вкажіть OPENCLAW_CONFIG_PATH безпосередньо на реальний файл.
Якщо файл відсутній, OpenClaw використовує безпечні типові значення. Поширені причини додати конфігурацію:
- Підключити канали й керувати тим, хто може надсилати повідомлення боту
- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, hooks)
- Налаштувати сесії, медіа, мережу або UI
config.schema.lookup для точних
документів на рівні полів перед редагуванням конфігурації. Використовуйте цю сторінку для орієнтованих на завдання вказівок і
Довідник конфігурації для ширшої
карти полів і типових значень.
Мінімальна конфігурація
Редагування конфігурації
- Interactive wizard
- CLI (one-liners)
- Control UI
- Direct edit
Сувора перевірка
openclaw config schema виводить канонічну JSON Schema, яку використовують Control UI
і перевірка. config.schema.lookup отримує один вузол у межах шляху плюс
зведення дочірніх елементів для інструментів деталізації. Метадані документації полів title/description
передаються через вкладені об’єкти, wildcard (*), елемент масиву ([]) і гілки anyOf/
oneOf/allOf. Схеми runtime plugin і каналів об’єднуються, коли завантажено
реєстр маніфестів.
Коли перевірка не проходить:
- Gateway не завантажується
- Працюють лише діагностичні команди (
openclaw doctor,openclaw logs,openclaw health,openclaw status) - Запустіть
openclaw doctor, щоб побачити точні проблеми - Запустіть
openclaw doctor --fix(або--yes), щоб застосувати виправлення
openclaw.json
не проходить перевірку (включно з локальною перевіркою plugin), запуск Gateway завершується помилкою або
перезавантаження пропускається, а поточний runtime зберігає останню прийняту конфігурацію.
Запустіть openclaw doctor --fix (або --yes), щоб відремонтувати конфігурацію з префіксами/перезаписану конфігурацію або
відновити останню відому справну копію. Просування до останньої відомої справної версії пропускається, коли
кандидат містить замасковані заповнювачі секретів, як-от ***.
Поширені завдання
Set up a channel (WhatsApp, Telegram, Discord, etc.)
Set up a channel (WhatsApp, Telegram, Discord, etc.)
channels.<provider>. Перегляньте окрему сторінку каналу для кроків налаштування:- WhatsApp -
channels.whatsapp - Telegram -
channels.telegram - Discord -
channels.discord - Feishu -
channels.feishu - Google Chat -
channels.googlechat - Microsoft Teams -
channels.msteams - Slack -
channels.slack - Signal -
channels.signal - iMessage -
channels.imessage - Mattermost -
channels.mattermost
Choose and configure models
Choose and configure models
agents.defaults.modelsвизначає каталог моделей і діє як allowlist для/model; записиprovider/*фільтрують/model,/modelsі засоби вибору моделей до вибраних провайдерів, водночас продовжуючи використовувати динамічне виявлення моделей.- Використовуйте
openclaw config set agents.defaults.models '<json>' --strict-json --merge, щоб додати записи allowlist без видалення наявних моделей. Звичайні заміни, які видаляли б записи, відхиляються, якщо не передати--replace. - Посилання на моделі використовують формат
provider/model(наприклад,anthropic/claude-opus-4-6). agents.defaults.imageMaxDimensionPxкерує зменшенням розміру зображень transcript/tool (типово1200); нижчі значення зазвичай зменшують використання vision-токенів у запусках із великою кількістю скріншотів.- Див. CLI моделей для перемикання моделей у чаті та Відмовостійкість моделей для ротації автентифікації й поведінки резервних варіантів.
- Для користувацьких/самостійно розміщених провайдерів див. Користувацькі провайдери у довіднику.
Control who can message the bot
Control who can message the bot
dmPolicy:"pairing"(типово): невідомі відправники отримують одноразовий код сполучення для схвалення"allowlist": лише відправники вallowFrom(або у сховищі дозволених сполучених)"open": дозволити всі вхідні DM (потрібноallowFrom: ["*"])"disabled": ігнорувати всі DM
groupPolicy + groupAllowFrom або allowlist, специфічні для каналу.Див. повний довідник для деталей за каналами.Set up group chat mention gating
Set up group chat mention gating
- Згадки в метаданих: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо)
- Текстові шаблони: безпечні regex-шаблони в
mentionPatterns - Видимі відповіді:
messages.visibleRepliesможе вимагати надсилання через message-tool глобально;messages.groupChat.visibleRepliesперевизначає це для груп/каналів. - Див. повний довідник для режимів видимих відповідей, перевизначень за каналами та режиму self-chat.
Restrict skills per agent
Restrict skills per agent
agents.defaults.skills для спільної базової конфігурації, а потім перевизначайте конкретних
агентів за допомогою agents.list[].skills:- Пропустіть
agents.defaults.skills, щоб типово не обмежувати skills. - Пропустіть
agents.list[].skills, щоб успадкувати типові значення. - Встановіть
agents.list[].skills: [], щоб не мати skills. - Див. Skills, Конфігурація Skills і Довідник конфігурації.
Tune gateway channel health monitoring
Tune gateway channel health monitoring
- Встановіть
gateway.channelHealthCheckMinutes: 0, щоб глобально вимкнути перезапуски health-monitor. channelStaleEventThresholdMinutesмає бути більшим або дорівнювати інтервалу перевірки.- Використовуйте
channels.<provider>.healthMonitor.enabledабоchannels.<provider>.accounts.<id>.healthMonitor.enabled, щоб вимкнути автоматичні перезапуски для одного каналу чи облікового запису без вимкнення глобального монітора. - Див. Перевірки стану для операційного налагодження і повний довідник для всіх полів.
Tune gateway WebSocket handshake timeout
Tune gateway WebSocket handshake timeout
- Типове значення —
15000мілісекунд. OPENCLAW_HANDSHAKE_TIMEOUT_MSі надалі має пріоритет для одноразових перевизначень сервісу або shell.- Спочатку бажано виправити затримки запуску/event-loop; цей параметр призначений для хостів, які справні, але повільні під час прогріву.
Configure sessions and resets
Configure sessions and resets
dmScope:main(спільний) |per-peer|per-channel-peer|per-account-channel-peerthreadBindings: глобальні типові значення для маршрутизації сеансів, прив’язаних до потоку (Discord підтримує/focus,/unfocus,/agents,/session idleі/session max-age).- Див. Керування сеансами для областей дії, зв’язків ідентичностей і політики надсилання.
- Див. повний довідник для всіх полів.
Увімкнути ізоляцію
Увімкнути ізоляцію
scripts/sandbox-setup.sh, або для встановлення з npm див. вбудовану команду docker build у Ізоляція § Образи та налаштування.Див. Ізоляція для повного посібника та повний довідник для всіх параметрів.Увімкнути push через реле для офіційних збірок iOS
Увімкнути push через реле для офіційних збірок iOS
openclaw.json.Задайте це в конфігурації gateway:- Дозволяє gateway надсилати
push.test, імпульси пробудження та пробудження повторного підключення через зовнішнє реле. - Використовує дозвіл на надсилання з областю реєстрації, пересланий спарованим застосунком iOS. Gateway не потребує токена реле для всього розгортання.
- Прив’язує кожну реєстрацію через реле до ідентичності gateway, з яким спаровано застосунок iOS, тому інший gateway не може повторно використати збережену реєстрацію.
- Залишає локальні/ручні збірки iOS на прямому APNs. Надсилання через реле застосовується лише до офіційних розповсюджених збірок, зареєстрованих через реле.
- Має збігатися з базовою URL-адресою реле, вбудованою в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання доходив до того самого розгортання реле.
- Установіть офіційну/TestFlight збірку iOS, скомпільовану з тією самою базовою URL-адресою реле.
- Налаштуйте
gateway.push.apns.relay.baseUrlна gateway. - Спаруйте застосунок iOS із gateway і дозвольте підключитися як сеансам вузла, так і сеансам оператора.
- Застосунок iOS отримує ідентичність gateway, реєструється в реле за допомогою App Attest і квитанції застосунку, а потім публікує payload
push.apns.registerчерез реле до спарованого gateway. - Gateway зберігає handle реле та дозвіл на надсилання, а потім використовує їх для
push.test, імпульсів пробудження та пробуджень повторного підключення.
- Якщо ви перемикаєте застосунок iOS на інший gateway, повторно підключіть застосунок, щоб він міг опублікувати нову реєстрацію реле, прив’язану до цього gateway.
- Якщо ви випускаєте нову збірку iOS, яка вказує на інше розгортання реле, застосунок оновлює кешовану реєстрацію реле замість повторного використання старого джерела реле.
OPENCLAW_APNS_RELAY_BASE_URLіOPENCLAW_APNS_RELAY_TIMEOUT_MSусе ще працюють як тимчасові перевизначення env.OPENCLAW_APNS_RELAY_ALLOW_HTTP=trueзалишається лише для розробки через local loopback; не зберігайте HTTP URL-адреси реле в конфігурації.
Налаштувати Heartbeat (періодичні відмітки)
Налаштувати Heartbeat (періодичні відмітки)
every: рядок тривалості (30m,2h). Задайте0m, щоб вимкнути.target:last|none|<channel-id>(наприкладdiscord,matrix,telegramабоwhatsapp)directPolicy:allow(типово) абоblockдля цілей heartbeat у стилі DM- Див. Heartbeat для повного посібника.
Налаштувати завдання Cron
Налаштувати завдання Cron
sessionRetention: очищає завершені ізольовані сеанси запуску зsessions.json(типово24h; задайтеfalse, щоб вимкнути).runLog: очищаєcron/runs/<jobId>.jsonlза розміром і кількістю збережених рядків.- Див. Завдання Cron для огляду функції та прикладів CLI.
Налаштувати Webhook (хуки)
Налаштувати Webhook (хуки)
- Сприймайте весь вміст payload hook/webhook як недовірені вхідні дані.
- Використовуйте окремий
hooks.token; не використовуйте повторно спільний токен Gateway. - Автентифікація hook працює лише через заголовки (
Authorization: Bearer ...абоx-openclaw-token); токени в query string відхиляються. hooks.pathне може бути/; тримайте вхідний webhook на окремому підшляху, наприклад/hooks.- Тримайте прапорці обходу небезпечного вмісту вимкненими (
hooks.gmail.allowUnsafeExternalContent,hooks.mappings[].allowUnsafeExternalContent), якщо не виконуєте чітко обмежене налагодження. - Якщо ви вмикаєте
hooks.allowRequestSessionKey, також задайтеhooks.allowedSessionKeyPrefixes, щоб обмежити ключі сеансів, вибрані викликачем. - Для агентів, керованих hook, віддавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де можливо).
Налаштувати маршрутизацію кількох агентів
Налаштувати маршрутизацію кількох агентів
Розділити конфігурацію на кілька файлів ($include)
Розділити конфігурацію на кілька файлів ($include)
$include, щоб упорядкувати великі конфігурації:- Один файл: замінює об’єкт, що його містить
- Масив файлів: глибоко об’єднується за порядком (пізніший має перевагу)
- Сусідні ключі: об’єднуються після include (перевизначають включені значення)
- Вкладені include: підтримуються до 10 рівнів углиб
- Відносні шляхи: розв’язуються відносно файлу, що виконує include
- Записи, що належать OpenClaw: коли запис змінює лише один розділ верхнього рівня,
підтриманий include одного файлу, наприклад
plugins: { $include: "./plugins.json5" }, OpenClaw оновлює цей включений файл і залишаєopenclaw.jsonбез змін - Непідтримуваний наскрізний запис: кореневі include, масиви include та include із сусідніми перевизначеннями fail closed для записів, що належать OpenClaw, замість сплющення конфігурації
- Обмеження: шляхи
$includeмають розв’язуватися в межах каталогу, що міститьopenclaw.json. Щоб спільно використовувати дерево між машинами або користувачами, задайтеOPENCLAW_INCLUDE_ROOTSяк список шляхів (:на POSIX,;на Windows) додаткових каталогів, на які можуть посилатися include. Символічні посилання розв’язуються й перевіряються повторно, тому шлях, який лексично міститься в каталозі конфігурації, але чия реальна ціль виходить за межі кожного дозволеного кореня, усе одно відхиляється. - Обробка помилок: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних include
Гаряче перезавантаження конфігурації
Gateway спостерігає за~/.openclaw/openclaw.json і застосовує зміни автоматично: для більшості налаштувань ручний перезапуск не потрібен.
Прямі редагування файлу вважаються недовіреними, доки не пройдуть валідацію. Спостерігач чекає,
доки завершаться тимчасові записи/перейменування редактора, читає фінальний файл і відхиляє
некоректні зовнішні редагування без перезапису openclaw.json. Записи конфігурації,
що належать OpenClaw, використовують той самий schema gate перед записом; руйнівні перезаписи, як-от
видалення gateway.mode або зменшення файлу більш ніж наполовину, відхиляються та
зберігаються як .rejected.* для перевірки.
Якщо ви бачите config reload skipped (invalid config) або під час запуску повідомляється Invalid config, перевірте конфігурацію, запустіть openclaw config validate, а потім запустіть openclaw doctor --fix для виправлення. Див. Усунення несправностей Gateway
для контрольного списку.
Режими перезавантаження
| Режим | Поведінка |
|---|---|
hybrid (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускає для критичних. |
hot | Гаряче застосовує лише безпечні зміни. Логує попередження, коли потрібен перезапуск: ви обробляєте це. |
restart | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. |
off | Вимикає спостереження за файлами. Зміни набувають чинності після наступного ручного перезапуску. |
Що застосовується гаряче, а що потребує перезапуску
Більшість полів застосовуються гаряче без простою. У режиміhybrid зміни, що потребують перезапуску, обробляються автоматично.
| Категорія | Поля | Потрібен перезапуск? |
|---|---|---|
| Канали | channels.*, web (WhatsApp) - усі вбудовані канали та канали Plugin | Ні |
| Агент і моделі | agent, agents, models, routing | Ні |
| Автоматизація | hooks, cron, agent.heartbeat | Ні |
| Сеанси й повідомлення | session, messages | Ні |
| Інструменти й медіа | tools, browser, skills, mcp, audio, talk | Ні |
| UI та інше | ui, logging, identity, bindings | Ні |
| Сервер Gateway | gateway.* (port, bind, auth, tailscale, TLS, HTTP) | Так |
| Інфраструктура | discovery, plugins | Так |
gateway.reload і gateway.remote є винятками - їх зміна не запускає перезапуск.Планування перезавантаження
Коли ви редагуєте вихідний файл, на який є посилання через$include, OpenClaw планує
перезавантаження на основі авторської структури джерела, а не вирівняного подання в пам’яті.
Це зберігає передбачуваність рішень гарячого перезавантаження (гаряче застосування чи перезапуск) навіть коли
один розділ верхнього рівня міститься у власному включеному файлі, наприклад
plugins: { $include: "./plugins.json5" }. Планування перезавантаження завершується закритою відмовою, якщо
структура джерела неоднозначна.
Config RPC (програмні оновлення)
Для інструментів, які записують конфігурацію через API Gateway, надавайте перевагу такому потоку:config.schema.lookup, щоб переглянути одне піддерево (поверхневий вузол схеми + зведення дочірніх елементів)config.get, щоб отримати поточний знімок разом ізhashconfig.patchдля часткових оновлень (JSON merge patch: об’єкти об’єднуються,nullвидаляє, масиви замінюються)config.applyлише коли ви маєте намір замінити всю конфігураціюupdate.runдля явного самооновлення з перезапуском; додайтеcontinuationMessage, коли після перезапуску сеанс має виконати один наступний хідupdate.status, щоб переглянути останній sentinel перезапуску оновлення та перевірити запущену версію після перезапуску
config.schema.lookup як першу зупинку для точних
документів і обмежень на рівні поля. Використовуйте Довідник конфігурації,
коли їм потрібна ширша карта конфігурації, стандартні значення або посилання на спеціалізовані
довідники підсистем.
config.apply, config.patch, update.run)
обмежені за частотою до 3 запитів за 60 секунд на deviceId+clientIp. Запити на перезапуск
об’єднуються, а потім застосовують 30-секундний період очікування між циклами перезапуску.
update.status доступний лише для читання, але обмежений адміністративною областю, оскільки sentinel перезапуску може
містити зведення кроків оновлення та хвости виводу команд.config.apply, і config.patch приймають raw, baseHash, sessionKey,
note і restartDelayMs. baseHash потрібен для обох методів, коли
конфігурація вже існує.
Змінні середовища
OpenClaw читає змінні середовища з батьківського процесу, а також із:.envз поточного робочого каталогу (якщо є)~/.openclaw/.env(глобальний резервний варіант)
Імпорт середовища shell (необов'язково)
Імпорт середовища shell (необов'язково)
OPENCLAW_LOAD_SHELL_ENV=1Підстановка змінних середовища у значеннях конфігурації
Підстановка змінних середовища у значеннях конфігурації
${VAR_NAME}:- Зіставляються лише назви у верхньому регістрі:
[A-Z_][A-Z0-9_]* - Відсутні або порожні змінні спричиняють помилку під час завантаження
- Екрануйте за допомогою
$${VAR}для буквального виводу - Працює всередині файлів
$include - Вбудована підстановка:
"${BASE}/v1"→"https://api.example.com/v1"
Посилання на секрети (env, file, exec)
Посилання на секрети (env, file, exec)
secrets.providers для env/file/exec) наведено в Керування секретами.
Підтримувані шляхи облікових даних перелічено в Поверхня облікових даних SecretRef.Повний довідник
Повний довідник за кожним полем див. у Довіднику конфігурації.Пов’язано: Приклади конфігурації · Довідник конфігурації · Doctor