Skip to main content
Швидкі відповіді та глибше усунення несправностей для реальних конфігурацій (локальна розробка, VPS, багато агентів, OAuth/API-ключі, перемикання моделей після збою). Для діагностики runtime див. Усунення несправностей. Повний довідник конфігурації див. у Конфігурація.

Перші 60 секунд, якщо щось зламалося

  1. Швидкий стан (перша перевірка)
    Швидке локальне зведення: ОС + оновлення, доступність gateway/сервісу, агенти/сеанси, конфігурація провайдера + проблеми runtime (коли gateway доступний).
  2. Звіт для вставлення (безпечно ділитися)
    Діагностика лише для читання з хвостом журналу (токени редагуються).
  3. Стан демона + порту
    Показує runtime супервізора порівняно з доступністю RPC, цільову URL-адресу проби та яку конфігурацію сервіс, імовірно, використав.
  4. Глибокі проби
    Запускає живу health-пробу gateway, включно з пробами каналів, коли вони підтримуються (потрібен доступний gateway). Див. Справність.
  5. Перегляньте хвіст останнього журналу
    Якщо RPC недоступний, скористайтеся запасним варіантом:
    Файлові журнали відокремлені від журналів сервісу; див. Журналювання і Усунення несправностей.
  6. Запустіть doctor (ремонти)
    Виправляє/мігрує конфігурацію/стан + запускає health-перевірки. Див. Doctor.
  7. Знімок Gateway
    Запитує в запущеного gateway повний знімок (лише WS). Див. Справність.

Швидкий старт і налаштування першого запуску

Питання й відповіді щодо першого запуску — встановлення, onboarding, маршрути авторизації, підписки, початкові збої — розміщені в FAQ першого запуску.

Що таке OpenClaw?

OpenClaw — це персональний AI-асистент, який ви запускаєте на власних пристроях. Він відповідає в середовищах обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і вбудовані Plugin каналів, як-от QQ Bot), а також може працювати з голосом + живим Canvas на підтримуваних платформах. Gateway — це постійно ввімкнена площина керування; асистент — це продукт.
OpenClaw — це не «просто обгортка Claude». Це локально-орієнтована площина керування, яка дає змогу запускати здібного асистента на вашому власному обладнанні, доступного з чат-застосунків, якими ви вже користуєтеся, зі станом сеансів, пам’яттю та інструментами — без передавання контролю над вашими робочими процесами хостинговому SaaS.Основне:
  • Ваші пристрої, ваші дані: запускайте Gateway там, де хочете (Mac, Linux, VPS), і зберігайте workspace + історію сеансів локально.
  • Справжні канали, а не веб-пісочниця: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/тощо, плюс мобільний голос і Canvas на підтримуваних платформах.
  • Незалежність від моделей: використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією і failover для кожного агента.
  • Опція лише локально: запускайте локальні моделі, щоб усі дані могли залишатися на вашому пристрої, якщо ви цього хочете.
  • Маршрутизація багатьох агентів: окремі агенти для кожного каналу, облікового запису або завдання, кожен зі своїм workspace і типовими налаштуваннями.
  • Відкритий код і можливість змінювати: переглядайте, розширюйте та самостійно хостіть без прив’язки до постачальника.
Документація: Gateway, Канали, Багато агентів, Пам’ять.
Добрі перші проєкти:
  • Створити вебсайт (WordPress, Shopify або простий статичний сайт).
  • Прототипувати мобільний застосунок (структура, екрани, план API).
  • Організувати файли й папки (очищення, іменування, тегування).
  • Під’єднати Gmail і автоматизувати зведення або подальші дії.
Він може виконувати великі завдання, але найкраще працює, коли ви ділите їх на фази та використовуєте субагентів для паралельної роботи.
Повсякденні виграші зазвичай виглядають так:
  • Персональні брифінги: зведення inbox, календаря та новин, які вас цікавлять.
  • Дослідження й чернетки: швидкі дослідження, зведення та перші чернетки для електронних листів або документів.
  • Нагадування та подальші дії: підказки й контрольні списки, керовані Cron або Heartbeat.
  • Автоматизація браузера: заповнення форм, збирання даних і повторення вебзавдань.
  • Координація між пристроями: надішліть завдання з телефона, дозвольте Gateway виконати його на сервері й отримайте результат назад у чаті.
Так, для дослідження, кваліфікації та підготовки чернеток. Він може сканувати сайти, формувати короткі списки, підсумовувати потенційних клієнтів і писати чернетки outreach або рекламних текстів.Для outreach або запусків реклами залишайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і політик платформ, а також перевіряйте все перед надсиланням. Найбезпечніший шаблон — дозволити OpenClaw підготувати чернетку, а вам її затвердити.Документація: Безпека.
OpenClaw — це персональний асистент і координаційний шар, а не заміна IDE. Використовуйте Claude Code або Codex для найшвидшого прямого циклу програмування всередині репозиторію. Використовуйте OpenClaw, коли вам потрібні тривала пам’ять, доступ із різних пристроїв і оркестрація інструментів.Переваги:
  • Постійна пам’ять + workspace між сеансами
  • Доступ із багатьох платформ (WhatsApp, Telegram, TUI, WebChat)
  • Оркестрація інструментів (браузер, файли, планування, hooks)
  • Постійно ввімкнений Gateway (запускайте на VPS, взаємодійте звідусіль)
  • Вузли для локального браузера/екрана/камери/exec
Showcase: https://openclaw.ai/showcase

Skills та автоматизація

Використовуйте керовані перевизначення замість редагування копії в репозиторії. Помістіть свої зміни в ~/.openclaw/skills/<name>/SKILL.md (або додайте папку через skills.load.extraDirs у ~/.openclaw/openclaw.json). Пріоритет такий: <workspace>/skills<workspace>/.agents/skills~/.agents/skills~/.openclaw/skills → вбудовані → skills.load.extraDirs, тому керовані перевизначення все одно мають перевагу над вбудованими Skills без торкання git. Якщо вам потрібно встановити skill глобально, але зробити його видимим лише для деяких агентів, тримайте спільну копію в ~/.openclaw/skills і керуйте видимістю через agents.defaults.skills та agents.list[].skills. Лише зміни, варті upstream, мають жити в репозиторії та виходити як PR.
Так. Додайте додаткові каталоги через skills.load.extraDirs у ~/.openclaw/openclaw.json (найнижчий пріоритет). Типовий пріоритет: <workspace>/skills<workspace>/.agents/skills~/.agents/skills~/.openclaw/skills → вбудовані → skills.load.extraDirs. clawhub типово встановлює в ./skills, що OpenClaw трактує як <workspace>/skills у наступному сеансі. Якщо skill має бути видимим лише певним агентам, поєднайте це з agents.defaults.skills або agents.list[].skills.
Наразі підтримувані шаблони такі:
  • Cron-завдання: ізольовані завдання можуть встановлювати перевизначення model для кожного завдання.
  • Агенти: маршрутизуйте завдання до окремих агентів із різними типовими моделями, рівнями мислення та параметрами stream.
  • Перемикання на вимогу: використовуйте /model, щоб будь-коли змінити модель поточного сеансу.
Наприклад, використовуйте ту саму модель із різними налаштуваннями для кожного агента:
Розмістіть спільні типові налаштування для кожної моделі в agents.defaults.models["provider/model"].params, а специфічні для агента перевизначення — у пласкому agents.list[].params. Не визначайте окремі вкладені записи agents.list[].models["provider/model"].params для тієї самої моделі; agents.list[].models призначено для каталогу моделей і runtime-перевизначень на рівні агента.Див. Cron-завдання, Маршрутизація багатьох агентів, Конфігурація і Slash-команди.
Використовуйте субагентів для довгих або паралельних завдань. Субагенти запускаються у власному сеансі, повертають зведення та залишають основний чат чуйним.Попросіть бота «spawn a sub-agent for this task» або використовуйте /subagents. Використовуйте /status у чаті, щоб побачити, що Gateway робить саме зараз (і чи він зайнятий).Порада щодо токенів: довгі завдання й субагенти обидва споживають токени. Якщо вартість має значення, встановіть дешевшу модель для субагентів через agents.defaults.subagents.model.Документація: Субагенти, Фонові завдання.
Використовуйте прив’язки thread. Ви можете прив’язати thread Discord до субагента або цілі сеансу, щоб подальші повідомлення в цьому thread залишалися в цьому прив’язаному сеансі.Базовий потік:
  • Створіть через sessions_spawn з thread: true (і за бажанням mode: "session" для постійного follow-up).
  • Або вручну прив’яжіть через /focus <target>.
  • Використовуйте /agents, щоб переглянути стан прив’язки.
  • Використовуйте /session idle <duration|off> і /session max-age <duration|off>, щоб керувати автоматичним зняттям фокуса.
  • Використовуйте /unfocus, щоб від’єднати thread.
Обов’язкова конфігурація:
  • Глобальні типові значення: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
  • Перевизначення Discord: channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours.
  • Автоматична прив’язка під час spawn: channels.discord.threadBindings.spawnSessions типово дорівнює true; встановіть false, щоб вимкнути spawn прив’язаних до thread сеансів.
Документація: Субагенти, Discord, Довідник конфігурації, Slash-команди.
Спочатку перевірте розв’язаний маршрут requester:
  • Доставка субагента в режимі completion віддає перевагу будь-якому прив’язаному thread або маршруту розмови, коли він існує.
  • Якщо джерело completion містить лише канал, OpenClaw повертається до збереженого маршруту сеансу requester (lastChannel / lastTo / lastAccountId), щоб пряма доставка все ще могла спрацювати.
  • Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може завершитися невдало, і результат натомість повернеться до чергової доставки сеансу, а не буде негайно опублікований у чаті.
  • Недійсні або застарілі цілі все ще можуть примусити fallback до черги або остаточний збій доставки.
  • Якщо остання видима відповідь асистента дочірнього сеансу є точним silent token NO_REPLY / no_reply або точно ANNOUNCE_SKIP, OpenClaw навмисно пригнічує announce замість публікації застарілого попереднього прогресу.
  • Вивід tool/toolResult не підвищується до тексту результату дочірнього сеансу; результатом є остання видима відповідь асистента дочірнього сеансу.
Налагодження:
Документація: Підагенти, Фонові завдання, Інструменти сеансу.
Cron виконується всередині процесу Gateway. Якщо Gateway не працює безперервно, заплановані завдання не виконуватимуться.Контрольний список:
  • Переконайтеся, що cron увімкнено (cron.enabled) і OPENCLAW_SKIP_CRON не задано.
  • Перевірте, що Gateway працює цілодобово (без сну/перезапусків).
  • Перевірте налаштування часового поясу для завдання (--tz порівняно з часовим поясом хоста).
Налагодження:
Документація: Завдання Cron, Автоматизація.
Спочатку перевірте режим доставки:
  • --no-deliver / delivery.mode: "none" означає, що резервне надсилання раннером не очікується.
  • Відсутня або недійсна ціль оголошення (channel / to) означає, що раннер пропустив вихідну доставку.
  • Помилки автентифікації каналу (unauthorized, Forbidden) означають, що раннер спробував доставити повідомлення, але облікові дані це заблокували.
  • Тихий ізольований результат (лише NO_REPLY / no_reply) вважається навмисно недоставним, тому раннер також пригнічує резервну доставку з черги.
Для ізольованих завдань Cron агент усе одно може надсилати напряму за допомогою інструмента message, коли доступний маршрут чату. --announce керує лише резервним шляхом раннера для фінального тексту, який агент ще не надіслав.Налагодження:
Документація: Завдання Cron, Фонові завдання.
Зазвичай це шлях перемикання live-моделі, а не дублювання планування.Ізольований Cron може зберегти передачу runtime-моделі та повторити спробу, коли активний запуск викидає LiveSessionModelSwitchError. Повторна спроба зберігає перемкненого провайдера/модель, а якщо перемикання містило нове перевизначення профілю автентифікації, Cron також зберігає його перед повторною спробою.Пов’язані правила вибору:
  • Перевизначення моделі хуком Gmail має пріоритет, коли застосовне.
  • Потім model для окремого завдання.
  • Потім будь-яке збережене перевизначення моделі cron-сеансу.
  • Потім звичайний вибір моделі агента/за замовчуванням.
Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторних спроби перемикання Cron переривається замість нескінченного циклу.Налагодження:
Документація: Завдання Cron, CLI cron.
Використовуйте нативні команди openclaw skills або помістіть Skills у свою робочу область. Інтерфейс Skills для macOS недоступний у Linux. Переглядайте Skills на https://clawhub.ai.
Нативна команда openclaw skills install за замовчуванням записує в каталог skills/ активної робочої області. Додайте --global, щоб установити в спільний керований каталог Skills для всіх локальних агентів. Установлюйте окремий CLI clawhub лише якщо хочете публікувати або синхронізувати власні Skills. Використовуйте agents.defaults.skills або agents.list[].skills, якщо хочете обмежити, які агенти можуть бачити спільні Skills.
Так. Використовуйте планувальник Gateway:
  • Завдання Cron для запланованих або повторюваних завдань (зберігаються після перезапусків).
  • Heartbeat для періодичних перевірок “основного сеансу”.
  • Ізольовані завдання для автономних агентів, які публікують підсумки або доставляють повідомлення в чати.
Документація: Завдання Cron, Автоматизація, Heartbeat.
Не напряму. Skills для macOS обмежуються metadata.openclaw.os плюс потрібними бінарними файлами, і Skills з’являються в системному промпті лише тоді, коли вони придатні на хості Gateway. У Linux Skills лише для darwin (наприклад, apple-notes, apple-reminders, things-mac) не завантажаться, якщо ви не перевизначите обмеження.Підтримуються три шаблони:Варіант A - запустіть Gateway на Mac (найпростіше). Запустіть Gateway там, де є бінарні файли macOS, а потім підключіться з Linux у віддаленому режимі або через Tailscale. Skills завантажуються звичайно, оскільки хост Gateway працює на macOS.Варіант B - використовуйте вузол macOS (без SSH). Запустіть Gateway у Linux, спарте вузол macOS (програму в рядку меню) і встановіть Команди запуску Node на “Завжди запитувати” або “Завжди дозволяти” на Mac. OpenClaw може вважати Skills лише для macOS придатними, коли потрібні бінарні файли існують на вузлі. Агент запускає ці Skills через інструмент nodes. Якщо ви виберете “Завжди запитувати”, схвалення “Завжди дозволяти” в запиті додає цю команду до списку дозволених.Варіант C - проксіюйте бінарні файли macOS через SSH (розширено). Залиште Gateway у Linux, але зробіть так, щоб потрібні CLI-бінарники розв’язувалися в SSH-обгортки, які запускаються на Mac. Потім перевизначте Skill, щоб дозволити Linux і зберегти його придатним.
  1. Створіть SSH-обгортку для бінарного файла (приклад: memo для Apple Notes):
  2. Розмістіть обгортку в PATH на хості Linux (наприклад, ~/bin/memo).
  3. Перевизначте метадані Skill (робоча область або ~/.openclaw/skills), щоб дозволити Linux:
  4. Запустіть новий сеанс, щоб знімок Skills оновився.
На сьогодні вбудованої немає.Варіанти:
  • Користувацький Skill / Plugin: найкраще для надійного доступу до API (Notion/HeyGen обидва мають API).
  • Автоматизація браузера: працює без коду, але повільніша й крихкіша.
Якщо потрібно зберігати контекст для кожного клієнта (агентські робочі процеси), простий шаблон такий:
  • Одна сторінка Notion на клієнта (контекст + уподобання + активна робота).
  • Попросіть агента отримувати цю сторінку на початку сеансу.
Якщо потрібна нативна інтеграція, відкрийте запит на функцію або створіть Skill, спрямований на ці API.Установлення Skills:
Нативні встановлення потрапляють у каталог skills/ активної робочої області. Для спільних Skills для всіх локальних агентів використовуйте openclaw skills install @owner/<skill-slug> --global (або вручну помістіть їх у ~/.openclaw/skills/<name>/SKILL.md). Якщо лише деякі агенти мають бачити спільне встановлення, налаштуйте agents.defaults.skills або agents.list[].skills. Деякі Skills очікують бінарні файли, встановлені через Homebrew; у Linux це означає Linuxbrew (див. запис FAQ Homebrew для Linux вище). Див. Skills, Конфігурація Skills і ClawHub.
Використовуйте вбудований браузерний профіль user, який підключається через Chrome DevTools MCP:
Якщо потрібна користувацька назва, створіть явний профіль MCP:
Цей шлях може використовувати локальний браузер хоста або підключений браузерний вузол. Якщо Gateway працює в іншому місці, запустіть хост вузла на машині з браузером або використовуйте віддалений CDP.Поточні обмеження existing-session / user:
  • дії керуються ref, а не CSS-селекторами
  • завантаження файлів вимагає ref / inputRef і наразі підтримує один файл за раз
  • responsebody, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або raw CDP-профілю

Ізоляція та пам’ять

Так. Див. Ізоляція. Для налаштування, специфічного для Docker (повний Gateway у Docker або образи ізоляції), див. Docker.
Стандартний образ орієнтований передусім на безпеку й запускається як користувач node, тому він не містить системних пакетів, Homebrew або вбудованих браузерів. Для повнішого налаштування:
  • Зберігайте /home/node з OPENCLAW_HOME_VOLUME, щоб кеші не втрачалися.
  • Додайте системні залежності в образ за допомогою OPENCLAW_IMAGE_APT_PACKAGES.
  • Установіть браузери Playwright через вбудований CLI: node /app/node_modules/playwright-core/cli.js install chromium
  • Задайте PLAYWRIGHT_BROWSERS_PATH і переконайтеся, що шлях зберігається.
Документація: Docker, Браузер.
Так - якщо ваш приватний трафік це особисті повідомлення, а публічний трафік це групи.Використовуйте agents.defaults.sandbox.mode: "non-main", щоб групові/канальні сеанси (ключі не-main) виконувалися в налаштованому бекенді ізоляції, тоді як основний сеанс особистих повідомлень залишався на хості. Docker є стандартним бекендом, якщо ви не виберете інший. Потім обмежте, які інструменти доступні в ізольованих сеансах, через tools.sandbox.tools.Покрокове налаштування + приклад конфігурації: Групи: особисті повідомлення + публічні групиОсновна довідка з конфігурації: Конфігурація Gateway
Задайте agents.defaults.sandbox.docker.binds як ["host:path:mode"] (наприклад, "/home/user/src:/src:ro"). Глобальні та агентські bind-монтування об’єднуються; агентські bind-монтування ігноруються, коли scope: "shared". Використовуйте :ro для всього чутливого й пам’ятайте, що bind-монтування обходять файлові стіни ізоляції.OpenClaw перевіряє джерела bind-монтувань і за нормалізованим шляхом, і за канонічним шляхом, розв’язаним через найглибшого наявного предка. Це означає, що виходи через батьківські symlink усе одно fail closed, навіть коли останній сегмент шляху ще не існує, а перевірки дозволеного кореня все ще застосовуються після розв’язання symlink.Див. Ізоляція і Ізоляція проти політики інструментів проти підвищених прав для прикладів і приміток щодо безпеки.
Пам’ять OpenClaw - це просто Markdown-файли в робочій області агента:
  • Щоденні нотатки в memory/YYYY-MM-DD.md
  • Кураторські довгострокові нотатки в MEMORY.md (лише основні/приватні сеанси)
OpenClaw також виконує тихе скидання пам’яті перед Compaction, щоб нагадати моделі записати довговічні нотатки перед автоматичною Compaction. Це виконується лише тоді, коли робоча область доступна для запису (ізоляції лише для читання пропускають це). Див. Пам’ять.
Попросіть бота записати факт у пам’ять. Довгострокові нотатки мають бути в MEMORY.md, короткостроковий контекст іде в memory/YYYY-MM-DD.md.Це все ще область, яку ми покращуємо. Допомагає нагадати моделі зберігати спогади; вона знатиме, що робити. Якщо вона й далі забуває, перевірте, що Gateway використовує той самий робочий простір під час кожного запуску.Документація: Пам’ять, Робочий простір агента.
Файли пам’яті зберігаються на диску й залишаються там, доки ви їх не видалите. Обмеженням є ваше сховище, а не модель. Контекст сесії усе ще обмежений вікном контексту моделі, тому довгі розмови можуть стискатися або обрізатися. Саме тому існує пошук у пам’яті - він повертає в контекст лише релевантні частини.Документація: Пам’ять, Контекст.
Лише якщо ви використовуєте ембеддинги OpenAI. Codex OAuth покриває чат/завершення й не надає доступ до ембеддингів, тому вхід через Codex (OAuth або вхід через Codex CLI) не допоможе для семантичного пошуку в пам’яті. Ембеддингам OpenAI усе одно потрібен справжній API-ключ (OPENAI_API_KEY або models.providers.openai.apiKey).Якщо ви явно не задаєте постачальника, OpenClaw використовує ембеддинги OpenAI. Застарілі конфіги, у яких досі вказано memorySearch.provider = "auto", також резолвляться в OpenAI. Якщо ключ OpenAI API недоступний, семантичний пошук у пам’яті залишається недоступним, доки ви не налаштуєте ключ або явно не виберете іншого постачальника.Якщо ви хочете залишатися локально, задайте memorySearch.provider = "local" (і, за бажанням, memorySearch.fallback = "none"). Якщо вам потрібні ембеддинги Gemini, задайте memorySearch.provider = "gemini" і надайте GEMINI_API_KEY (або memorySearch.remote.apiKey). Ми підтримуємо моделі ембеддингів OpenAI, сумісні з OpenAI, Gemini, Voyage, Mistral, Bedrock, Ollama, LM Studio, GitHub Copilot, DeepInfra або локальні - подробиці налаштування див. у Пам’ять.

Де речі зберігаються на диску

Ні - стан OpenClaw є локальним, але зовнішні сервіси все одно бачать те, що ви їм надсилаєте.
  • Локально за замовчуванням: сесії, файли пам’яті, конфіг і робочий простір зберігаються на хості Gateway (~/.openclaw + каталог вашого робочого простору).
  • Віддалено за необхідністю: повідомлення, які ви надсилаєте постачальникам моделей (Anthropic/OpenAI/тощо), ідуть до їхніх API, а чат-платформи (WhatsApp/Telegram/Slack/тощо) зберігають дані повідомлень на своїх серверах.
  • Ви контролюєте слід: використання локальних моделей зберігає промпти на вашій машині, але трафік каналів усе одно проходить через сервери каналу.
Пов’язано: Робочий простір агента, Пам’ять.
Усе зберігається під $OPENCLAW_STATE_DIR (за замовчуванням: ~/.openclaw):Застарілий шлях для одного агента: ~/.openclaw/agent/* (мігрується через openclaw doctor).Ваш робочий простір (AGENTS.md, файли пам’яті, skills тощо) є окремим і налаштовується через agents.defaults.workspace (за замовчуванням: ~/.openclaw/workspace).
Ці файли зберігаються в робочому просторі агента, а не в ~/.openclaw.
  • Робочий простір (на агента): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, необов’язковий HEARTBEAT.md. Кореневий memory.md у нижньому регістрі є лише вхідними даними для застарілого ремонту; openclaw doctor --fix може об’єднати його в MEMORY.md, коли існують обидва файли.
  • Каталог стану (~/.openclaw): конфіг, стан каналу/постачальника, профілі автентифікації, сесії, журнали та спільні skills (~/.openclaw/skills).
Робочий простір за замовчуванням - ~/.openclaw/workspace, налаштовується через:
Якщо бот “забуває” після перезапуску, підтвердьте, що Gateway використовує той самий робочий простір під час кожного запуску (і пам’ятайте: віддалений режим використовує робочий простір хоста gateway, а не вашого локального ноутбука).Порада: якщо вам потрібна довговічна поведінка або налаштування, попросіть бота записати це в AGENTS.md або MEMORY.md, а не покладатися на історію чату.Див. Робочий простір агента і Пам’ять.
Так. SOUL.md - це один із початкових файлів робочого простору, що ін’єктується в контекст агента. Ліміт ін’єкції за замовчуванням для одного файла становить 20000 символів, а загальний початковий бюджет для всіх файлів - 60000 символів.Змініть спільні значення за замовчуванням у вашому конфігу OpenClaw:
Або перевизначте одного агента:
Використовуйте /context, щоб перевірити сирі й ін’єктовані розміри та чи сталося обрізання. Тримайте SOUL.md сфокусованим на голосі, позиції та особистості; операційні правила кладіть у AGENTS.md, а довговічні факти - у пам’ять.Див. Контекст і Конфіг агента.
Розмістіть ваш робочий простір агента у приватному git-репозиторії та створюйте резервні копії десь приватно (наприклад, приватний GitHub). Це охоплює пам’ять + файли AGENTS/SOUL/USER і дає змогу пізніше відновити “розум” асистента.Не комітьте нічого з ~/.openclaw (облікові дані, сесії, токени або зашифровані секретні навантаження). Якщо вам потрібне повне відновлення, окремо створіть резервні копії і робочого простору, і каталогу стану (див. питання про міграцію вище).Документація: Робочий простір агента.
Див. окремий посібник: Видалення.
Так. Робочий простір - це default cwd і якір пам’яті, а не жорстка пісочниця. Відносні шляхи резолвляться всередині робочого простору, але абсолютні шляхи можуть отримувати доступ до інших розташувань хоста, якщо пісочницю не ввімкнено. Якщо вам потрібна ізоляція, використовуйте agents.defaults.sandbox або налаштування пісочниці для окремого агента. Якщо ви хочете, щоб репозиторій був робочим каталогом за замовчуванням, вкажіть для workspace цього агента корінь репозиторію. Репозиторій OpenClaw - це лише вихідний код; тримайте робочий простір окремо, якщо ви навмисно не хочете, щоб агент працював усередині нього.Приклад (репозиторій як default cwd):
Стан сесій належить хосту gateway. Якщо ви у віддаленому режимі, потрібне вам сховище сесій розташоване на віддаленій машині, а не на вашому локальному ноутбуці. Див. Керування сесіями.

Основи конфігу

OpenClaw читає необов’язковий конфіг JSON5 із $OPENCLAW_CONFIG_PATH (за замовчуванням: ~/.openclaw/openclaw.json):
Якщо файла немає, використовуються відносно безпечні значення за замовчуванням (зокрема робочий простір за замовчуванням ~/.openclaw/workspace).
Прив’язки не до loopback вимагають дійсний шлях автентифікації gateway. На практиці це означає:
  • автентифікація shared-secret: токен або пароль
  • gateway.auth.mode: "trusted-proxy" за правильно налаштованим identity-aware reverse proxy
Примітки:
  • gateway.remote.token / .password самі по собі не вмикають локальну автентифікацію gateway.
  • Локальні шляхи виклику можуть використовувати gateway.remote.* як fallback лише коли gateway.auth.* не задано.
  • Для автентифікації паролем натомість задайте gateway.auth.mode: "password" плюс gateway.auth.password (або OPENCLAW_GATEWAY_PASSWORD).
  • Якщо gateway.auth.token / gateway.auth.password явно налаштовано через SecretRef і не резолвиться, резолюція завершується закрито (без маскування через віддалений fallback).
  • Налаштування shared-secret Control UI автентифікуються через connect.params.auth.token або connect.params.auth.password (зберігається в налаштуваннях застосунку/UI). Режими з ідентичністю, як-от Tailscale Serve або trusted-proxy, натомість використовують заголовки запиту. Уникайте розміщення shared secrets в URL.
  • З gateway.auth.mode: "trusted-proxy" same-host loopback reverse proxies потребують явного gateway.auth.trustedProxy.allowLoopback = true і loopback-запису в gateway.trustedProxies.
OpenClaw за замовчуванням примусово застосовує автентифікацію gateway, зокрема для loopback. У звичайному типовому шляху це означає автентифікацію токеном: якщо явний шлях автентифікації не налаштовано, запуск gateway резолвиться в режим токена й генерує runtime-only токен для цього запуску, тому локальні WS-клієнти мають автентифікуватися. Явно налаштуйте gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN або OPENCLAW_GATEWAY_PASSWORD, коли клієнтам потрібен стабільний секрет між перезапусками. Це блокує інші локальні процеси від виклику Gateway.Якщо ви віддаєте перевагу іншому шляху автентифікації, можна явно вибрати режим пароля (або, для identity-aware reverse proxy, trusted-proxy). Якщо ви дійсно хочете відкритий loopback, явно задайте gateway.auth.mode: "none" у своїй конфігурації. Doctor може будь-коли згенерувати для вас токен: openclaw doctor --generate-gateway-token.
Gateway стежить за конфігурацією та підтримує гаряче перезавантаження:
  • gateway.reload.mode: "hybrid" (типово): безпечно застосовує зміни на льоту, перезапускається для критичних
  • hot, restart, off також підтримуються
Задайте cli.banner.taglineMode у конфігурації:
  • off: приховує текст слогана, але залишає рядок із назвою банера/версією.
  • default: щоразу використовує All your chats, one OpenClaw..
  • random: ротаційні жартівливі/сезонні слогани (типова поведінка).
  • Якщо ви взагалі не хочете банер, задайте env OPENCLAW_HIDE_BANNER=1.
web_fetch працює без API-ключа. web_search залежить від вибраного провайдера:
  • Провайдери з API, як-от Brave, Exa, Firecrawl, Gemini, Kimi, MiniMax Search, Perplexity і Tavily, потребують свого звичного налаштування API-ключа.
  • Grok може повторно використовувати xAI OAuth з автентифікації моделі або fallback до XAI_API_KEY / конфігурації вебпошуку Plugin.
  • Ollama Web Search не потребує ключа, але використовує налаштований вами хост Ollama і потребує ollama signin.
  • DuckDuckGo не потребує ключа, але це неофіційна HTML-інтеграція.
  • SearXNG не потребує ключа/самостійно розгортається; налаштуйте SEARXNG_BASE_URL або plugins.entries.searxng.config.webSearch.baseUrl.
Рекомендовано: запустіть openclaw configure --section web і виберіть провайдера. Альтернативи через середовище:
  • Brave: BRAVE_API_KEY
  • Exa: EXA_API_KEY
  • Firecrawl: FIRECRAWL_API_KEY
  • Gemini: GEMINI_API_KEY
  • Grok: xAI OAuth, XAI_API_KEY
  • Kimi: KIMI_API_KEY або MOONSHOT_API_KEY
  • MiniMax Search: MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY або MINIMAX_API_KEY
  • Perplexity: PERPLEXITY_API_KEY або OPENROUTER_API_KEY
  • SearXNG: SEARXNG_BASE_URL
  • Tavily: TAVILY_API_KEY
Конфігурація вебпошуку для конкретного провайдера тепер живе в plugins.entries.<plugin>.config.webSearch.*. Застарілі шляхи провайдера tools.web.search.* тимчасово все ще завантажуються для сумісності, але їх не слід використовувати для нових конфігурацій. Конфігурація fallback для Firecrawl web-fetch живе в plugins.entries.firecrawl.config.webFetch.*.Примітки:
  • Якщо ви використовуєте allowlist, додайте web_search/web_fetch/x_search або group:web.
  • web_fetch увімкнено типово (якщо його явно не вимкнено).
  • Якщо tools.web.fetch.provider пропущено, OpenClaw автоматично виявляє першого готового fallback-провайдера fetch з доступних облікових даних. Офіційний Firecrawl Plugin надає цей fallback.
  • Демони читають env vars з ~/.openclaw/.env (або середовища сервісу).
Документація: Вебінструменти.
config.apply замінює всю конфігурацію. Якщо надіслати частковий об’єкт, усе інше буде видалено.Поточний OpenClaw захищає від багатьох випадкових перезаписів:
  • Записи конфігурації, що належать OpenClaw, перевіряють повну конфігурацію після зміни перед записом.
  • Недійсні або руйнівні записи, що належать OpenClaw, відхиляються й зберігаються як openclaw.json.rejected.*.
  • Якщо пряме редагування ламає запуск або гаряче перезавантаження, Gateway закривається безпечно або пропускає перезавантаження; він не перезаписує openclaw.json.
  • openclaw doctor --fix відповідає за відновлення і може повернути останню відому справну конфігурацію, зберігши відхилений файл як openclaw.json.clobbered.*.
Відновлення:
  • Перевірте openclaw logs --follow на Invalid config at, Config write rejected: або config reload skipped (invalid config).
  • Перегляньте найновіший openclaw.json.clobbered.* або openclaw.json.rejected.* поруч з активною конфігурацією.
  • Запустіть openclaw config validate і openclaw doctor --fix.
  • Скопіюйте назад лише потрібні ключі через openclaw config set або config.patch.
  • Якщо у вас немає останньої відомої справної конфігурації або відхиленого payload, відновіть із резервної копії або повторно запустіть openclaw doctor і заново налаштуйте канали/моделі.
  • Якщо це було неочікувано, створіть bug report і додайте останню відому конфігурацію або будь-яку резервну копію.
  • Локальний coding agent часто може реконструювати робочу конфігурацію з логів або історії.
Як уникнути:
  • Використовуйте openclaw config set для малих змін.
  • Використовуйте openclaw configure для інтерактивного редагування.
  • Спочатку використовуйте config.schema.lookup, якщо не впевнені щодо точного шляху або форми поля; він повертає неглибокий вузол схеми плюс короткі описи безпосередніх дочірніх елементів для заглиблення.
  • Використовуйте config.patch для часткових RPC-редагувань; залишайте config.apply лише для заміни всієї конфігурації.
  • Якщо ви використовуєте agent-facing інструмент gateway з agent run, він усе одно відхилятиме записи до tools.exec.ask / tools.exec.security (зокрема застарілі псевдоніми tools.bash.*, які нормалізуються до тих самих захищених exec-шляхів).
Документація: Конфігурація, Налаштування, Усунення неполадок Gateway, Doctor.
Поширений шаблон: один Gateway (наприклад, Raspberry Pi) плюс вузли та агенти:
  • Gateway (центральний): володіє каналами (Signal/WhatsApp), маршрутизацією та сесіями.
  • Вузли (пристрої): Macs/iOS/Android підключаються як периферія та надають локальні інструменти (system.run, canvas, camera).
  • Агенти (workers): окремі brains/workspaces для спеціальних ролей (наприклад, “Hetzner ops”, “Personal data”).
  • Субагенти: породжують фонову роботу з головного агента, коли потрібен паралелізм.
  • TUI: підключайтеся до Gateway і перемикайте агентів/сесії.
Документація: Вузли, Віддалений доступ, Маршрутизація Multi-Agent, Субагенти, TUI.
Так. Це опція конфігурації:
Типово false (headful). Headless з більшою ймовірністю викликає anti-bot перевірки на деяких сайтах. Див. Браузер.Headless використовує той самий рушій Chromium і працює для більшості автоматизації (форми, кліки, scraping, входи). Основні відмінності:
  • Немає видимого вікна браузера (використовуйте screenshots, якщо потрібна візуалізація).
  • Деякі сайти суворіші до автоматизації в headless-режимі (CAPTCHA, anti-bot). Наприклад, X/Twitter часто блокує headless-сесії.
Задайте browser.executablePath на ваш бінарний файл Brave (або будь-який браузер на базі Chromium) і перезапустіть Gateway. Див. повні приклади конфігурації в Браузер.

Віддалені Gateway та вузли

Повідомлення Telegram обробляє gateway. gateway запускає агента і лише потім викликає вузли через Gateway WebSocket, коли потрібен інструмент вузла:Telegram → Gateway → Агент → node.* → Вузол → Gateway → TelegramВузли не бачать вхідний трафік провайдера; вони лише отримують node RPC calls.
Коротка відповідь: спаріть свій комп’ютер як вузол. Gateway працює в іншому місці, але може викликати інструменти node.* (екран, камера, system) на вашій локальній машині через Gateway WebSocket.Типове налаштування:
  1. Запустіть Gateway на always-on хості (VPS/домашньому сервері).
  2. Помістіть хост Gateway і ваш комп’ютер в одну tailnet.
  3. Переконайтеся, що Gateway WS доступний (tailnet bind або SSH-тунель).
  4. Відкрийте застосунок macOS локально й підключіться в режимі Remote over SSH (або напряму через tailnet), щоб він міг зареєструватися як вузол.
  5. Схваліть вузол на Gateway:
Окремий TCP-міст не потрібен; вузли підключаються через Gateway WebSocket.Нагадування про безпеку: спарювання вузла macOS дозволяє system.run на цій машині. Спарюйте лише пристрої, яким довіряєте, і перегляньте Безпека.Документація: Вузли, Протокол Gateway, Віддалений режим macOS, Безпека.
Перевірте базові речі:
  • Gateway запущено: openclaw gateway status
  • Стан Gateway: openclaw status
  • Стан каналу: openclaw channels status
Потім перевірте автентифікацію та маршрутизацію:
  • Якщо ви використовуєте Tailscale Serve, переконайтеся, що gateway.auth.allowTailscale задано правильно.
  • Якщо підключаєтеся через SSH-тунель, підтвердьте, що локальний тунель працює й вказує на правильний порт.
  • Підтвердьте, що ваші allowlist (DM або group) містять ваш обліковий запис.
Документація: Tailscale, Віддалений доступ, Канали.
Так. Вбудованого моста “bot-to-bot” немає, але це можна надійно з’єднати кількома способами:Найпростіше: використовуйте звичайний канал чату, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). Нехай Bot A надішле повідомлення Bot B, а потім Bot B відповість як зазвичай.CLI-міст (generic): запустіть скрипт, який викликає інший Gateway через openclaw agent --message ... --deliver, націлюючись на чат, де слухає інший бот. Якщо один бот на віддаленому VPS, націльте свій CLI на той віддалений Gateway через SSH/Tailscale (див. Віддалений доступ).Приклад шаблону (запускати з машини, яка може дістатися цільового Gateway):
Порада: додайте guardrail, щоб два боти не зациклювалися безкінечно (лише згадки, channel allowlist або правило “не відповідати на повідомлення ботів”).Документація: Віддалений доступ, CLI агента, Надсилання агентом.
Ні. Один Gateway може розміщувати кілька агентів, кожен зі своїм робочим простором, типовими моделями та маршрутизацією. Це нормальне налаштування, і воно значно дешевше та простіше, ніж запускати по одному VPS на агента.Використовуйте окремі VPS лише тоді, коли потрібна жорстка ізоляція (межі безпеки) або дуже різні конфігурації, які ви не хочете спільно використовувати. В іншому разі залиште один Gateway і використовуйте кілька агентів або субагентів.
Так - вузли є першокласним способом отримати доступ до вашого ноутбука з віддаленого Gateway, і вони відкривають більше можливостей, ніж доступ до оболонки. Gateway працює на macOS/Linux (Windows через WSL2) і є легким (невеликий VPS або пристрій класу Raspberry Pi цілком підходить; 4 ГБ RAM більш ніж достатньо), тому поширена схема - постійно ввімкнений хост плюс ваш ноутбук як вузол.
  • Вхідний SSH не потрібен. Вузли підключаються назовні до Gateway WebSocket і використовують сполучення пристроїв.
  • Безпечніші засоби контролю виконання. system.run обмежується списками дозволів/підтвердженнями вузла на цьому ноутбуці.
  • Більше інструментів пристрою. Вузли надають canvas, camera і screen на додачу до system.run.
  • Автоматизація локального браузера. Тримайте Gateway на VPS, але запускайте Chrome локально через хост вузла на ноутбуці або підключайтеся до локального Chrome на хості через Chrome MCP.
SSH підходить для разового доступу до оболонки, але вузли простіші для постійних агентських робочих процесів і автоматизації пристроїв.Документація: Вузли, CLI вузлів, Браузер.
Ні. На одному хості має працювати лише один gateway, якщо ви навмисно не запускаєте ізольовані профілі (див. Кілька gateway). Вузли - це периферійні компоненти, які підключаються до gateway (вузли iOS/Android або “режим вузла” macOS у застосунку в рядку меню). Для безголових хостів вузлів і керування через CLI див. CLI хоста Node.Повний перезапуск потрібен для змін gateway, discovery і поверхні розміщених plugin.
Так.
  • config.schema.lookup: переглянути одне піддерево конфігурації з його неглибоким вузлом схеми, відповідною підказкою UI та короткими описами безпосередніх дочірніх елементів перед записом
  • config.get: отримати поточний знімок + хеш
  • config.patch: безпечне часткове оновлення (бажано для більшості RPC-редагувань); гаряче перезавантажує, коли можливо, і перезапускає, коли потрібно
  • config.apply: перевірити + замінити повну конфігурацію; гаряче перезавантажує, коли можливо, і перезапускає, коли потрібно
  • Звернений до агента runtime-інструмент gateway досі відмовляється переписувати tools.exec.ask / tools.exec.security; застарілі псевдоніми tools.bash.* нормалізуються до тих самих захищених exec-шляхів
Це задає ваш робочий простір і обмежує, хто може запускати бота.
Мінімальні кроки:
  1. Встановіть + увійдіть на VPS
  2. Встановіть + увійдіть на вашому Mac
    • Використайте застосунок Tailscale і ввійдіть у той самий tailnet.
  3. Увімкніть MagicDNS (рекомендовано)
    • У консолі адміністратора Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я.
  4. Використовуйте hostname tailnet
    • SSH: ssh user@your-vps.tailnet-xxxx.ts.net
    • Gateway WS: ws://your-vps.tailnet-xxxx.ts.net:18789
Якщо вам потрібен Control UI без SSH, використайте Tailscale Serve на VPS:
Це залишає gateway прив’язаним до loopback і відкриває HTTPS через Tailscale. Див. Tailscale.
Serve відкриває Gateway Control UI + WS. Вузли підключаються через той самий Gateway WS endpoint.Рекомендоване налаштування:
  1. Переконайтеся, що VPS + Mac перебувають в одному tailnet.
  2. Використовуйте застосунок macOS у віддаленому режимі (ціллю SSH може бути hostname tailnet). Застосунок прокладе тунель до порту Gateway і підключиться як вузол.
  3. Підтвердьте вузол на gateway:
Документація: Протокол Gateway, Discovery, Віддалений режим macOS.
Якщо вам потрібні лише локальні інструменти (screen/camera/exec) на другому ноутбуці, додайте його як вузол. Це зберігає один Gateway і уникає дублювання конфігурації. Локальні інструменти вузла наразі доступні лише для macOS, але ми плануємо поширити їх на інші ОС.Встановлюйте другий Gateway лише тоді, коли вам потрібна жорстка ізоляція або два повністю окремі боти.Документація: Вузли, CLI вузлів, Кілька gateway.

Змінні середовища та завантаження .env

OpenClaw читає змінні середовища з батьківського процесу (оболонка, launchd/systemd, CI тощо) і додатково завантажує:
  • .env з поточного робочого каталогу
  • глобальний резервний .env з ~/.openclaw/.env (також відомий як $OPENCLAW_STATE_DIR/.env)
Жоден файл .env не перевизначає наявні змінні середовища. Змінні облікових даних провайдерів є винятком для робочого .env: ключі на кшталт GEMINI_API_KEY, XAI_API_KEY або MISTRAL_API_KEY ігноруються з робочого .env і мають бути в середовищі процесу, ~/.openclaw/.env або config env.Ви також можете визначити inline-змінні середовища в конфігурації (застосовуються лише якщо їх немає в середовищі процесу):
Див. /environment для повного порядку пріоритетів і джерел.
Два поширені виправлення:
  1. Покладіть відсутні ключі в ~/.openclaw/.env, щоб вони підхоплювалися навіть тоді, коли сервіс не успадковує середовище вашої оболонки.
  2. Увімкніть імпорт оболонки (зручність за явним вибором):
Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає). Еквіваленти змінних середовища: OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.
openclaw models status повідомляє, чи ввімкнено імпорт середовища оболонки. “Shell env: off” не означає, що ваші змінні середовища відсутні - це лише означає, що OpenClaw не завантажуватиме вашу login shell автоматично.Якщо Gateway працює як сервіс (launchd/systemd), він не успадковуватиме середовище вашої оболонки. Виправте це одним із таких способів:
  1. Покладіть токен у ~/.openclaw/.env:
  2. Або увімкніть імпорт оболонки (env.shellEnv.enabled: true).
  3. Або додайте його до блоку config env (застосовується лише якщо відсутній).
Потім перезапустіть gateway і перевірте знову:
Токени Copilot читаються з COPILOT_GITHUB_TOKEN (також GH_TOKEN / GITHUB_TOKEN). Див. /concepts/model-providers і /environment.

Сесії та кілька чатів

Надішліть /new або /reset як окреме повідомлення. Див. Керування сесіями.
Сесії можуть завершуватися після session.idleMinutes, але це вимкнено за замовчуванням (типово 0). Установіть додатне значення, щоб увімкнути завершення через бездіяльність. Коли ввімкнено, наступне повідомлення після періоду бездіяльності починає новий id сесії для цього ключа чату. Це не видаляє transcript - це лише починає нову сесію.
Так, через маршрутизацію кількох агентів і субагентів. Ви можете створити одного координувального агента і кількох робочих агентів із власними робочими просторами та моделями.Водночас це найкраще сприймати як цікавий експеримент. Він потребує багато токенів і часто менш ефективний, ніж використання одного бота з окремими сесіями. Типова модель, яку ми уявляємо, - це один бот, з яким ви спілкуєтеся, з різними сесіями для паралельної роботи. Цей бот також може запускати субагентів за потреби.Документація: Маршрутизація кількох агентів, Субагенти, CLI агентів.
Контекст сесії обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато файлів можуть спричинити Compaction або обрізання.Що допомагає:
  • Попросіть бота підсумувати поточний стан і записати його у файл.
  • Використовуйте /compact перед довгими завданнями і /new під час зміни теми.
  • Тримайте важливий контекст у робочому просторі й попросіть бота перечитати його.
  • Використовуйте субагентів для довгої або паралельної роботи, щоб головний чат залишався меншим.
  • Виберіть модель із більшим вікном контексту, якщо це трапляється часто.
Використайте команду reset:
Повне скидання без інтерактиву:
Потім знову запустіть налаштування:
Примітки:
  • Onboarding також пропонує Reset, якщо бачить наявну конфігурацію. Див. Onboarding (CLI).
  • Якщо ви використовували профілі (--profile / OPENCLAW_PROFILE), скиньте кожен state dir (типові значення - ~/.openclaw-<profile>).
  • Dev reset: openclaw gateway --dev --reset (лише для розробки; стирає dev-конфігурацію + облікові дані + сесії + робочий простір).
Використайте один із цих варіантів:
  • Compact (зберігає розмову, але підсумовує старіші ходи):
    або /compact <instructions>, щоб скерувати підсумок.
  • Reset (новий ID сесії для того самого ключа чату):
Якщо це продовжується:
  • Увімкніть або налаштуйте обрізання сесій (agents.defaults.contextPruning), щоб скоротити старий вивід інструментів.
  • Використовуйте модель із більшим вікном контексту.
Документація: Compaction, Обрізання сесій, Керування сесіями.
Це помилка перевірки провайдера: модель видала блок tool_use без обов’язкового input. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих потоків або зміни інструмента/схеми).Виправлення: почніть нову сесію за допомогою /new (окреме повідомлення).
Heartbeat запускається кожні 30m за замовчуванням (1h під час використання OAuth auth). Налаштуйте або вимкніть їх:
If HEARTBEAT.md існує, але фактично порожній (лише порожні рядки, Markdown/HTML-коментарі, Markdown-заголовки на кшталт # Heading, маркери блоків коду або порожні заготовки контрольних списків), OpenClaw пропускає запуск Heartbeat, щоб заощадити API-виклики. Якщо файл відсутній, Heartbeat все одно запускається, а модель вирішує, що робити.Перевизначення для окремих агентів використовують agents.list[].heartbeat. Документація: Heartbeat.
Ні. OpenClaw працює у вашому власному обліковому записі, тому якщо ви є в групі, OpenClaw може її бачити. За замовчуванням відповіді в групах заблоковані, доки ви не дозволите відправників (groupPolicy: "allowlist").Якщо ви хочете, щоб лише ви могли запускати відповіді в групі:
Варіант 1 (найшвидший): переглядайте журнали в реальному часі й надішліть тестове повідомлення в групі:
Шукайте chatId (або from), що закінчується на @g.us, наприклад: 1234567890-1234567890@g.us.Варіант 2 (якщо вже налаштовано/додано до списку дозволених): виведіть список груп із конфігурації:
Документація: WhatsApp, Каталог, Журнали.
Дві поширені причини:
  • Увімкнено обмеження за згадуванням (за замовчуванням). Потрібно @згадати бота (або збігтися з mentionPatterns).
  • Ви налаштували channels.whatsapp.groups без "*", і групу не додано до списку дозволених.
Див. Групи і Групові повідомлення.
Прямі чати за замовчуванням згортаються до основної сесії. Групи/канали мають власні ключі сесій, а теми Telegram / треди Discord є окремими сесіями. Див. Групи і Групові повідомлення.
Жорстких обмежень немає. Десятки (навіть сотні) — нормально, але стежте за:
  • Зростанням диска: сесії + транскрипти зберігаються в ~/.openclaw/agents/<agentId>/sessions/.
  • Вартістю токенів: більше агентів означає більше одночасного використання моделей.
  • Операційними накладними витратами: профілі автентифікації, робочі простори й маршрутизація каналів для кожного агента.
Поради:
  • Тримайте один активний робочий простір на агента (agents.defaults.workspace).
  • Очищуйте старі сесії (видаляйте JSONL або записи сховища), якщо диск зростає.
  • Використовуйте openclaw doctor, щоб виявляти зайві робочі простори й невідповідності профілів.
Так. Використовуйте маршрутизацію кількох агентів, щоб запускати кілька ізольованих агентів і маршрутизувати вхідні повідомлення за каналом/обліковим записом/співрозмовником. Slack підтримується як канал і може бути прив’язаний до конкретних агентів.Доступ до браузера потужний, але це не “можливість робити все, що може людина” — захист від ботів, CAPTCHA й MFA усе ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості або CDP на машині, яка фактично запускає браузер.Рекомендоване налаштування:
  • Постійно ввімкнений хост Gateway (VPS/Mac mini).
  • Один агент на роль (прив’язки).
  • Канал(и) Slack, прив’язані до цих агентів.
  • Локальний браузер через Chrome MCP або вузол, коли потрібно.
Документація: Маршрутизація кількох агентів, Slack, Браузер, Вузли.

Моделі, перемикання після збоїв і профілі автентифікації

Запитання й відповіді про моделі — значення за замовчуванням, вибір, псевдоніми, перемикання, перемикання після збоїв, профілі автентифікації — розміщені в FAQ щодо моделей.

Gateway: порти, “already running” і віддалений режим

gateway.port керує єдиним мультиплексованим портом для WebSocket + HTTP (Control UI, хуки тощо).Пріоритет:
Тому що “running” — це погляд супервізора (launchd/systemd/schtasks). Перевірка з’єднання — це фактичне підключення CLI до WebSocket Gateway.Використовуйте openclaw gateway status і довіряйте цим рядкам:
  • Probe target: (URL, який перевірка фактично використала)
  • Listening: (що фактично прив’язано до порту)
  • Last gateway error: (поширена першопричина, коли процес живий, але порт не слухає)
Ви редагуєте один файл конфігурації, тоді як сервіс працює з іншим (часто через невідповідність --profile / OPENCLAW_STATE_DIR).Виправлення:
Запустіть це з тим самим --profile / середовищем, яке має використовувати сервіс.
OpenClaw забезпечує блокування виконання, негайно прив’язуючи слухач WebSocket під час запуску (за замовчуванням ws://127.0.0.1:18789). Якщо прив’язування завершується помилкою EADDRINUSE, він викидає GatewayLockError, що вказує, що інший екземпляр уже слухає.Виправлення: зупиніть інший екземпляр, звільніть порт або запустіть із openclaw gateway --port <port>.
Установіть gateway.mode: "remote" і вкажіть віддалений WebSocket URL, за потреби зі спільними секретними віддаленими обліковими даними:
Нотатки:
  • openclaw gateway запускається лише коли gateway.mode має значення local (або якщо ви передали прапорець перевизначення).
  • Застосунок macOS відстежує файл конфігурації та перемикає режими наживо, коли ці значення змінюються.
  • gateway.remote.token / .password — це лише клієнтські віддалені облікові дані; самі собою вони не вмикають локальну автентифікацію gateway.
Ваш шлях автентифікації gateway і метод автентифікації UI не збігаються.Факти (з коду):
  • Control UI зберігає токен у sessionStorage для поточної сесії вкладки браузера й вибраного URL gateway, тому оновлення тієї самої вкладки продовжують працювати без відновлення довготривалого збереження токена в localStorage.
  • У разі AUTH_TOKEN_MISMATCH довірені клієнти можуть спробувати одну обмежену повторну спробу з кешованим токеном пристрою, коли gateway повертає підказки для повтору (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
  • Ця повторна спроба з кешованим токеном тепер повторно використовує кешовані схвалені області, збережені з токеном пристрою. Викликачі з явним deviceToken / явними scopes і далі зберігають запитаний набір областей замість успадкування кешованих областей.
  • Поза цим шляхом повторної спроби пріоритет автентифікації підключення такий: спочатку явний спільний токен/пароль, потім явний deviceToken, потім збережений токен пристрою, потім bootstrap-токен.
  • Вбудований bootstrap із кодом налаштування повертає токен пристрою вузла з scopes: [] плюс обмежений токен передавання оператору для довіреного мобільного onboarding. Передавання оператору може читати нативну конфігурацію під час налаштування, але не надає областей мутації сполучення або operator.admin.
Виправлення:
  • Найшвидше: openclaw dashboard (друкує + копіює URL панелі, намагається відкрити; показує підказку SSH, якщо середовище без дисплея).
  • Якщо у вас ще немає токена: openclaw doctor --generate-gateway-token.
  • Якщо віддалено, спочатку створіть тунель: ssh -N -L 18789:127.0.0.1:18789 user@host, потім відкрийте http://127.0.0.1:18789/.
  • Режим спільного секрету: установіть gateway.auth.token / OPENCLAW_GATEWAY_TOKEN або gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD, потім вставте відповідний секрет у налаштування Control UI.
  • Режим Tailscale Serve: переконайтеся, що gateway.auth.allowTailscale увімкнено й ви відкриваєте Serve URL, а не сирий loopback/tailnet URL, який обходить заголовки ідентичності Tailscale.
  • Режим довіреного проксі: переконайтеся, що ви заходите через налаштований identity-aware proxy, а не сирий URL gateway. Проксі local loopback на тому самому хості також потребують gateway.auth.trustedProxy.allowLoopback = true.
  • Якщо невідповідність зберігається після однієї повторної спроби, виконайте ротацію/повторне схвалення токена сполученого пристрою:
    • openclaw devices list
    • openclaw devices rotate --device <id> --role operator
  • Якщо цей виклик ротації каже, що його відхилено, перевірте дві речі:
    • сесії сполучених пристроїв можуть ротувати лише власний пристрій, якщо вони також не мають operator.admin
    • явні значення --scope не можуть перевищувати поточні операторські області викликача
  • Досі застрягли? Запустіть openclaw status --all і дотримуйтеся усунення несправностей. Див. Панель для подробиць автентифікації.
Прив’язка tailnet вибирає IP Tailscale з ваших мережевих інтерфейсів (100.64.0.0/10). Якщо машина не в Tailscale (або інтерфейс вимкнений), прив’язуватися немає до чого.Виправлення:
  • Запустіть Tailscale на цьому хості (щоб він мав адресу 100.x), або
  • Перемкніться на gateway.bind: "loopback" / "lan".
Примітка: tailnet є явним. auto віддає перевагу loopback; використовуйте gateway.bind: "tailnet", коли потрібна прив’язка лише до tailnet.
Зазвичай ні — один Gateway може запускати кілька каналів обміну повідомленнями й агентів. Використовуйте кілька Gateways лише коли потрібна надлишковість (наприклад, резервний бот) або жорстка ізоляція.Так, але потрібно ізолювати:
  • OPENCLAW_CONFIG_PATH (конфігурація для кожного екземпляра)
  • OPENCLAW_STATE_DIR (стан для кожного екземпляра)
  • agents.defaults.workspace (ізоляція робочого простору)
  • gateway.port (унікальні порти)
Швидке налаштування (рекомендовано):
  • Використовуйте openclaw --profile <name> ... для кожного екземпляра (автоматично створює ~/.openclaw-<name>).
  • Установіть унікальний gateway.port у конфігурації кожного профілю (або передайте --port для ручних запусків).
  • Установіть сервіс для кожного профілю: openclaw --profile <name> gateway install.
Профілі також додають суфікс до імен сервісів (ai.openclaw.<profile>; застарілі com.openclaw.*, openclaw-gateway-<profile>.service, OpenClaw Gateway (<profile>)). Повний посібник: Кілька gateways.
Gateway — це WebSocket-сервер, і він очікує, що найперше повідомлення буде кадром connect. Якщо він отримує щось інше, він закриває з’єднання з кодом 1008 (порушення політики).Поширені причини:
  • Ви відкрили HTTP URL у браузері (http://...) замість WS-клієнта.
  • Ви використали неправильний порт або шлях.
  • Проксі або тунель видалив заголовки автентифікації або надіслав не-Gateway запит.
Швидкі виправлення:
  1. Використовуйте WS URL: ws://<host>:18789 (або wss://..., якщо HTTPS).
  2. Не відкривайте WS-порт у звичайній вкладці браузера.
  3. Якщо автентифікацію ввімкнено, додайте токен/пароль у кадр connect.
Якщо ви використовуєте CLI або TUI, URL має виглядати так:
Подробиці протоколу: Протокол Gateway.

Журналювання й налагодження

Файлові журнали (структуровані):
Ви можете задати стабільний шлях через logging.file. Рівень файлового журналу контролюється logging.level. Докладність консолі контролюється --verbose і logging.consoleLevel.Найшвидше відстеження журналу:
Журнали служби/супервізора (коли gateway працює через launchd/systemd):
  • stdout macOS launchd: ~/Library/Logs/openclaw/gateway.log (профілі використовують gateway-<profile>.log; stderr приглушено)
  • Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
  • Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST
Докладніше див. Усунення несправностей.
Використовуйте допоміжні команди gateway:
Якщо ви запускаєте gateway вручну, openclaw gateway --force може повернути порт. Див. Gateway.
Є три режими встановлення Windows:1) Локальне налаштування Windows Hub: нативний застосунок керує локальним Gateway у WSL, що належить застосунку.Відкрийте OpenClaw Companion з меню Start або системного трея, потім скористайтеся Gateway Setup або вкладкою Connections.2) Ручний Gateway у WSL2: Gateway працює всередині Linux.Відкрийте PowerShell, увійдіть у WSL, потім перезапустіть:
Якщо ви ніколи не встановлювали службу, запустіть її у foreground:
3) Нативний Windows CLI/Gateway: Gateway працює безпосередньо у Windows.Відкрийте PowerShell і виконайте:
Якщо ви запускаєте його вручну (без служби), використовуйте:
Документація: Windows, інструкція з експлуатації служби Gateway.
Почніть зі швидкої перевірки стану:
Поширені причини:
  • Автентифікацію моделі не завантажено на хості gateway (перевірте models status).
  • Спарювання каналу/список дозволених блокує відповіді (перевірте конфігурацію каналу + журнали).
  • WebChat/Dashboard відкрито без правильного токена.
Якщо ви працюєте віддалено, підтвердьте, що тунель/з’єднання Tailscale активне і що WebSocket Gateway доступний.Документація: Канали, Усунення несправностей, Віддалений доступ.
Зазвичай це означає, що UI втратив з’єднання WebSocket. Перевірте:
  1. Чи запущено Gateway? openclaw gateway status
  2. Чи справний Gateway? openclaw status
  3. Чи має UI правильний токен? openclaw dashboard
  4. Якщо віддалено, чи активне з’єднання тунелю/Tailscale?
Потім перегляньте журнали в режимі tail:
Документація: Dashboard, Віддалений доступ, Усунення несправностей.
Почніть із журналів і стану каналу:
Потім зіставте помилку:
  • BOT_COMMANDS_TOO_MUCH: у меню Telegram забагато записів. OpenClaw уже обрізає їх до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі записи меню все одно потрібно прибрати. Зменште кількість команд плагінів/навичок/користувацьких команд або вимкніть channels.telegram.commands.native, якщо меню вам не потрібне.
  • TypeError: fetch failed, Network request for 'setMyCommands' failed! або подібні мережеві помилки: якщо ви на VPS або за проксі, підтвердьте, що вихідний HTTPS дозволено і DNS працює для api.telegram.org.
Якщо Gateway віддалений, переконайтеся, що ви переглядаєте журнали на хості Gateway.Документація: Telegram, Усунення несправностей каналів.
Спершу підтвердьте, що Gateway доступний і агент може запускатися:
У TUI використовуйте /status, щоб побачити поточний стан. Якщо ви очікуєте відповіді в чат-каналі, переконайтеся, що доставку ввімкнено (/deliver on).Документація: TUI, слеш-команди.
Якщо ви встановили службу:
Це зупиняє/запускає керовану службу (launchd на macOS, systemd на Linux). Використовуйте це, коли Gateway працює у фоні як демон.Якщо ви запускаєте у foreground, зупиніть через Ctrl-C, потім:
Документація: інструкція з експлуатації служби Gateway.
  • openclaw gateway restart: перезапускає фонову службу (launchd/systemd).
  • openclaw gateway: запускає gateway у foreground для цього сеансу термінала.
Якщо ви встановили службу, використовуйте команди gateway. Використовуйте openclaw gateway, коли потрібен одноразовий запуск у foreground.
Запустіть Gateway із --verbose, щоб отримати більше деталей у консолі. Потім перевірте файл журналу на помилки автентифікації каналів, маршрутизації моделей і RPC.

Медіа та вкладення

Вихідні вкладення від агента мають використовувати структуровані поля медіа, як-от media, mediaUrl, path або filePath. Див. налаштування асистента OpenClaw і надсилання агентом.Надсилання через CLI:
Також перевірте:
  • Цільовий канал підтримує вихідні медіа і не заблокований списками дозволених.
  • Файл не перевищує ліміти розміру провайдера (зображення змінюються до максимуму 2048px).
  • tools.fs.workspaceOnly=true обмежує надсилання з локальних шляхів робочою областю, temp/media-store і файлами, перевіреними sandbox.
  • tools.fs.workspaceOnly=false дозволяє структурованим локальним медіанадсиланням використовувати локальні файли хоста, які агент уже може читати, але лише для медіа та безпечних типів документів (зображення, аудіо, відео, PDF, документи Office і перевірені текстові документи, як-от Markdown/MD, TXT, JSON, YAML і YML). Це не сканер секретів: доступний агенту secret.txt або config.json може бути прикріплений, якщо розширення і перевірка вмісту збігаються. Тримайте чутливі файли поза шляхами, доступними агенту, або залишайте tools.fs.workspaceOnly=true для суворішого надсилання з локальних шляхів.
Див. Зображення.

Безпека та контроль доступу

Ставтеся до вхідних особистих повідомлень як до ненадійного вводу. Типові налаштування розроблено для зменшення ризику:
  • Типова поведінка на каналах із підтримкою особистих повідомлень - спарювання:
    • Невідомі відправники отримують код спарювання; бот не обробляє їхнє повідомлення.
    • Схвалити можна так: openclaw pairing approve --channel <channel> [--account <id>] <code>
    • Очікувані запити обмежено 3 на канал; перевірте openclaw pairing list --channel <channel> [--account <id>], якщо код не надійшов.
  • Публічне відкриття особистих повідомлень потребує явного ввімкнення (dmPolicy: "open" і список дозволених "*").
Запустіть openclaw doctor, щоб виявити ризиковані політики особистих повідомлень.
Ні. Prompt injection стосується ненадійного вмісту, а не лише того, хто може писати боту в особисті повідомлення. Якщо ваш асистент читає зовнішній вміст (вебпошук/отримання сторінок, сторінки браузера, електронні листи, документи, вкладення, вставлені журнали), цей вміст може містити інструкції, які намагаються перехопити модель. Це може статися навіть якщо ви єдиний відправник.Найбільший ризик виникає, коли інструменти ввімкнено: модель можна обманом змусити вивести контекст назовні або викликати інструменти від вашого імені. Зменшіть радіус ураження так:
  • використовуйте агента-”читача” лише для читання або без інструментів, щоб підсумовувати ненадійний вміст
  • тримайте web_search / web_fetch / browser вимкненими для агентів з увімкненими інструментами
  • також вважайте декодований текст файлів/документів ненадійним: OpenResponses input_file і витягування медіавкладень обгортають витягнутий текст у явні маркери межі зовнішнього вмісту замість передавання сирого тексту файлу
  • використовуйте sandbox і суворі списки дозволених інструментів
Докладніше: Безпека.
Мова й середовище виконання мають значення, але вони не є головним ризиком для персонального агента. Практичні ризики OpenClaw - це доступність gateway, хто може писати боту, prompt injection, область дії інструментів, обробка облікових даних, доступ браузера, доступ exec і довіра до сторонніх навичок або плагінів.Rust і WASM можуть забезпечити сильнішу ізоляцію для деяких класів коду, але вони не вирішують prompt injection, погані списки дозволених, публічну доступність gateway, надто широкі інструменти або профіль браузера, який уже ввійшов у чутливі облікові записи. Розглядайте це як основні засоби контролю:
  • тримайте Gateway приватним або автентифікованим
  • використовуйте спарювання та списки дозволених для особистих повідомлень і груп
  • забороняйте або ізолюйте в sandbox ризиковані інструменти для ненадійних вхідних даних
  • встановлюйте лише довірені плагіни та навички
  • запускайте openclaw security audit --deep після змін конфігурації
Докладніше: Безпека, Sandboxing.
Спершу перевірте ваше фактичне розгортання:
Безпечніший базовий стан:
  • Gateway прив’язаний до loopback або відкритий лише через автентифікований приватний доступ, як-от приватна мережа tailnet, SSH-тунель, автентифікація токеном/паролем або правильно налаштований довірений проксі
  • особисті повідомлення в режимі pairing або allowlist
  • групи внесені до списку дозволених і вимагають згадки, якщо не кожному учаснику можна довіряти
  • інструменти високого ризику (exec, browser, gateway, cron) заборонені або жорстко обмежені для агентів, які читають ненадійний вміст
  • sandbox увімкнено там, де виконання інструментів потребує меншого радіуса ураження
Публічні прив’язки без автентифікації, відкриті особисті повідомлення/групи з інструментами та відкритий контроль браузера - це знахідки, які потрібно виправити першими. Докладніше: контрольний список аудиту безпеки.
Ставтеся до сторонніх навичок і плагінів як до коду, якому ви вирішуєте довіряти. Сторінки навичок ClawHub показують стан сканування перед встановленням, але сканування не є повною межею безпеки. OpenClaw не запускає вбудоване локальне блокування небезпечного коду під час встановлення/оновлення плагінів або навичок; використовуйте керовану оператором security.installPolicy для локальних рішень дозволу/блокування.Безпечніший підхід:
  • віддавайте перевагу довіреним авторам і зафіксованим версіям
  • прочитайте навичку або плагін перед увімкненням
  • тримайте списки дозволених плагінів і навичок вузькими
  • запускайте робочі процеси з ненадійними вхідними даними в sandbox із мінімальними інструментами
  • уникайте надання сторонньому коду широкого доступу до файлової системи, exec, браузера або секретів
Деталі: Skills, Plugin, Безпека.
Так, для більшості налаштувань. Ізоляція бота в окремих облікових записах і номерах телефону зменшує радіус ураження, якщо щось піде не так. Це також полегшує ротацію облікових даних або відкликання доступу без впливу на ваші особисті облікові записи.Починайте з малого. Надавайте доступ лише до інструментів і облікових записів, які справді потрібні, і розширюйте його пізніше, якщо буде потрібно.Документація: Безпека, Сполучення.
Ми не рекомендуємо повну автономію над вашими особистими повідомленнями. Найбезпечніший шаблон:
  • Тримайте особисті повідомлення в режимі сполучення або в суворому списку дозволених.
  • Використовуйте окремий номер або обліковий запис, якщо хочете, щоб він надсилав повідомлення від вашого імені.
  • Дозвольте йому підготувати чернетку, а потім підтверджуйте перед надсиланням.
Якщо хочете експериментувати, робіть це в спеціальному обліковому записі й тримайте його ізольованим. Див. Безпека.
Так, якщо агент працює лише як чат і вхідні дані є довіреними. Менші рівні більш уразливі до перехоплення інструкцій, тому уникайте їх для агентів з увімкненими інструментами або під час читання недовіреного вмісту. Якщо вам потрібно використовувати меншу модель, жорстко обмежте інструменти й запускайте її в пісочниці. Див. Безпека.
Коди сполучення надсилаються лише коли невідомий відправник пише боту і dmPolicy: "pairing" увімкнено. /start сам по собі не генерує код.Перевірте запити в очікуванні:
Якщо хочете негайний доступ, додайте id відправника до списку дозволених або встановіть dmPolicy: "open" для цього облікового запису.
Ні. Стандартна політика особистих повідомлень WhatsApp — сполучення. Невідомі відправники отримують лише код сполучення, а їхнє повідомлення не обробляється. OpenClaw відповідає лише в чатах, з яких отримує повідомлення, або на явні надсилання, які ви запускаєте.Підтвердьте сполучення за допомогою:
Перелічіть запити в очікуванні:
Запит номера телефону в майстрі: він використовується для налаштування вашого списку дозволених/власника, щоб ваші власні особисті повідомлення були дозволені. Він не використовується для автоматичного надсилання. Якщо ви запускаєте на своєму особистому номері WhatsApp, використовуйте цей номер і ввімкніть channels.whatsapp.selfChatMode.

Команди чату, переривання завдань і «він не зупиняється»

Більшість внутрішніх повідомлень або повідомлень інструментів з’являються лише тоді, коли для цього сеансу ввімкнено verbose, trace або reasoning.Виправте це в чаті, де бачите проблему:
Якщо шум усе ще є, перевірте налаштування сеансу в Control UI і встановіть verbose на inherit. Також переконайтеся, що ви не використовуєте профіль бота з verboseDefault, встановленим на on у конфігурації.Документація: Мислення та verbose, Безпека.
Надішліть будь-яке з наведеного як окреме повідомлення (без скісної риски):
Це тригери переривання (не команди зі скісною рискою).Для фонових процесів (з інструмента exec) ви можете попросити агента виконати:
Огляд команд зі скісною рискою: див. Команди зі скісною рискою.Більшість команд потрібно надсилати як окреме повідомлення, що починається з /, але кілька скорочень (наприклад, /status) також працюють у рядку для відправників зі списку дозволених.
OpenClaw стандартно блокує обмін повідомленнями між провайдерами. Якщо виклик інструмента прив’язаний до Telegram, він не надішле в Discord, якщо ви явно цього не дозволите.Увімкніть обмін повідомленнями між провайдерами для агента:
Перезапустіть gateway після редагування конфігурації.
Підказки під час виконання стандартно спрямовуються в активний запуск. Використовуйте /queue, щоб вибрати поведінку активного запуску:
  • steer - скеровувати активний запуск на наступній межі моделі
  • followup - поставити повідомлення в чергу й виконувати їх по одному після завершення поточного запуску
  • collect - поставити сумісні повідомлення в чергу й відповісти один раз після завершення поточного запуску
  • interrupt - перервати поточний запуск і почати заново
Стандартний режим — steer. Для режимів із чергою можна додати параметри на кшталт debounce:0.5s cap:25 drop:summarize. Див. Черга команд і Черга скерування.

Різне

В OpenClaw облікові дані та вибір моделі розділені. Встановлення ANTHROPIC_API_KEY (або збереження API-ключа Anthropic у профілях автентифікації) вмикає автентифікацію, але фактична стандартна модель — це та, яку ви налаштували в agents.defaults.model.primary (наприклад, anthropic/claude-sonnet-4-6 або anthropic/claude-opus-4-6). Якщо ви бачите No credentials found for profile "anthropic:default", це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному auth-profiles.json для агента, який виконується.

Досі не виходить? Запитайте в Discord або відкрийте обговорення GitHub.

Пов’язані матеріали