Поширені запитання

OpenClaw — це персональний AI-асистент, який ви запускаєте на власних пристроях. Він відповідає в середовищах обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і bundled channel plugins, як-от QQ Bot), а також може працювати з голосом + live Canvas на підтримуваних платформах. Gateway — це постійно активна площина керування; асистент — це продукт.

OpenClaw — це не "просто обгортка Claude". Це локально-орієнтована площина керування, яка дає змогу запускати спроможного асистента на вашому власному обладнанні, доступного з чат-застосунків, якими ви вже користуєтеся, зі stateful-сеансами, пам’яттю та інструментами — без передачі контролю над вашими робочими процесами hosted SaaS.

Основне:

• Ваші пристрої, ваші дані: запускайте Gateway будь-де (Mac, Linux, VPS) і зберігайте workspace + історію сеансів локально.
• Справжні канали, а не веб-пісочниця: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/тощо, плюс мобільний голос і Canvas на підтримуваних платформах.
• Незалежність від моделей: використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією для кожного агента та аварійним перемиканням.
• Опція лише локально: запускайте локальні моделі, щоб усі дані могли залишатися на вашому пристрої, якщо хочете.
• Маршрутизація кількох агентів: окремі агенти для кожного каналу, облікового запису або завдання, кожен зі своїм workspace і типовими параметрами.
• Відкритий код і придатність до модифікації: перевіряйте, розширюйте та self-host без прив’язки до постачальника.

Документація: Gateway, Канали, Кілька агентів, Пам’ять.

Хороші перші проєкти:

• Створіть вебсайт (WordPress, Shopify або простий статичний сайт).
• Створіть прототип мобільного застосунку (структура, екрани, план API).
• Упорядкуйте файли й папки (очищення, іменування, тегування).
• Під’єднайте Gmail і автоматизуйте зведення або подальші дії.

Він може виконувати великі завдання, але працює найкраще, коли ви ділите їх на етапи та використовуєте субагентів для паралельної роботи.

Щоденні переваги зазвичай виглядають так:

• Особисті брифінги: зведення пошти, календаря та важливих для вас новин.
• Дослідження й чернетки: швидкі дослідження, зведення та перші чернетки електронних листів або документів.
• Нагадування та подальші дії: підказки й контрольні списки, керовані Cron або Heartbeat.
• Автоматизація браузера: заповнення форм, збирання даних і повторювані вебзавдання.
• Координація між пристроями: надішліть завдання з телефона, дайте Gateway виконати його на сервері й отримайте результат назад у чаті.

Так, для дослідження, кваліфікації та створення чернеток. Він може сканувати сайти, формувати короткі списки, підсумовувати потенційних клієнтів і писати чернетки outreach або рекламних текстів.

Для outreach або рекламних запусків залишайте людину в процесі. Уникайте спаму, дотримуйтеся місцевих законів і політик платформ, а також перевіряйте все перед надсиланням. Найбезпечніший підхід — дозволити OpenClaw підготувати чернетку, а вам затвердити її.

Документація: Безпека.

OpenClaw — це персональний асистент і координаційний шар, а не заміна IDE. Використовуйте Claude Code або Codex для найшвидшого прямого циклу кодування всередині репозиторію. Використовуйте OpenClaw, коли вам потрібні довготривала пам’ять, доступ між пристроями та оркестрація інструментів.

Переваги:

• Постійна пам’ять + workspace між сеансами
• Доступ із кількох платформ (WhatsApp, Telegram, TUI, WebChat)
• Оркестрація інструментів (браузер, файли, планування, hooks)
• Постійно активний Gateway (запуск на VPS, взаємодія звідусіль)
• Nodes для локального браузера/екрана/камери/exec

Демонстрація: https://openclaw.ai/showcase

Використовуйте керовані override замість редагування копії в репозиторії. Розмістіть свої зміни в ~/.openclaw/skills/<name>/SKILL.md (або додайте папку через skills.load.extraDirs у ~/.openclaw/openclaw.json). Пріоритет такий: <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → bundled → skills.load.extraDirs, тому керовані override все одно мають перевагу над bundled 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 → bundled → skills.load.extraDirs. clawhub типово встановлює в ./skills, що OpenClaw під час наступного сеансу трактує як <workspace>/skills. Якщо skill має бути видимим лише для певних агентів, поєднайте це з agents.defaults.skills або agents.list[].skills.

Нині підтримувані шаблони такі:

• Завдання Cron: ізольовані завдання можуть задавати override model для кожного завдання.
• Субагенти: спрямовуйте завдання до окремих агентів із різними типовими моделями.
• Перемикання на вимогу: використовуйте /model, щоб будь-коли перемкнути модель поточного сеансу.

Див. Завдання Cron, Маршрутизація кількох агентів і Slash-команди.

Використовуйте субагентів для довгих або паралельних завдань. Субагенти працюють у власному сеансі, повертають зведення та зберігають основний чат чуйним.

Попросіть бота "spawn a sub-agent for this task" або використайте /subagents. Використовуйте /status у чаті, щоб побачити, що Gateway робить зараз (і чи він зайнятий).

Порада щодо токенів: довгі завдання й субагенти споживають токени. Якщо вартість має значення, задайте дешевшу модель для субагентів через agents.defaults.subagents.model.

Документація: Субагенти, Фонові завдання.

Використовуйте прив’язки тредів. Ви можете прив’язати тред Discord до субагента або цільового сеансу, щоб подальші повідомлення в цьому треді залишалися в прив’язаному сеансі.

Базовий потік:

• Створіть через sessions_spawn з thread: true (і необов’язково mode: "session" для постійного follow-up).
• Або прив’яжіть вручну через /focus <target>.
• Використовуйте /agents, щоб переглянути стан прив’язки.
• Використовуйте /session idle <duration|off> і /session max-age <duration|off>, щоб керувати автоматичним скасуванням фокуса.
• Використовуйте /unfocus, щоб від’єднати тред.

Потрібна конфігурація:

• Глобальні типові параметри: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Override для Discord: channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours.
• Автоматична прив’язка під час створення: channels.discord.threadBindings.spawnSessions типово має значення true; установіть false, щоб вимкнути створення прив’язаних до тредів сеансів.

Документація: Субагенти, Discord, Довідник конфігурації, Slash-команди.

Спершу перевірте визначений маршрут requester:

• Доставка субагента в режимі завершення віддає перевагу будь-якому прив’язаному треду або маршруту розмови, якщо він існує.
• Якщо origin завершення містить лише канал, OpenClaw використовує запасний варіант — збережений маршрут сеансу requester (lastChannel / lastTo / lastAccountId), щоб пряма доставка все одно могла спрацювати.
• Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може не вдатися, і результат повернеться до доставки через чергу сеансу замість негайної публікації в чаті.
• Недійсні або застарілі цілі все ще можуть примусово перевести в запасну чергу або спричинити остаточний збій доставки.
• Якщо остання видима відповідь асистента дочірнього процесу — точний silent token NO_REPLY / no_reply або точно ANNOUNCE_SKIP, OpenClaw навмисно пригнічує оголошення замість публікації застарілого попереднього прогресу.
• Якщо дочірній процес перевищив час очікування після самих лише викликів інструментів, оголошення може згорнути це в коротке зведення часткового прогресу замість повторного відтворення сирого виводу інструментів.

Налагодження:

openclaw tasks show <runId-or-sessionKey>

Документація: Субагенти, Фонові завдання, Інструменти сеансу.

Cron працює всередині процесу Gateway. Якщо Gateway не працює безперервно, заплановані завдання не виконуватимуться.

Контрольний список:

• Переконайтеся, що cron увімкнено (cron.enabled) і OPENCLAW_SKIP_CRON не задано.
• Перевірте, що Gateway працює 24/7 (без сну/перезапусків).
• Перевірте налаштування часового поясу для завдання (--tz порівняно з часовим поясом хоста).

Налагодження:

openclaw cron run <jobId>
openclaw cron runs --id <jobId> --limit 50

Документація: Завдання Cron, Автоматизація та завдання.

Спершу перевірте режим доставлення:

• --no-deliver / delivery.mode: "none" означає, що резервне надсилання runner не очікується.
• Відсутня або недійсна ціль оголошення (channel / to) означає, що runner пропустив вихідне доставлення.
• Помилки автентифікації каналу (unauthorized, Forbidden) означають, що runner намагався доставити повідомлення, але облікові дані це заблокували.
• Тихий ізольований результат (лише NO_REPLY / no_reply) вважається навмисно недоставним, тому runner також пригнічує доставлення поставленого в чергу резервного повідомлення.

Для ізольованих завдань cron агент усе ще може надсилати напряму за допомогою інструмента message, коли доступний маршрут чату. --announce керує лише резервним шляхом runner для фінального тексту, який агент ще не надіслав.

Налагодження:

openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>

Документація: Завдання Cron, Фонові завдання.

Зазвичай це шлях перемикання живої моделі, а не дубльоване планування.

Ізольований cron може зберегти runtime-передавання моделі й повторити спробу, коли активний запуск викидає LiveSessionModelSwitchError. Повторна спроба зберігає перемкненого провайдера/модель, а якщо перемикання містило нове перевизначення профілю автентифікації, cron також зберігає його перед повторною спробою.

Пов’язані правила вибору:

• Перевизначення моделі Gmail hook має пріоритет, коли застосовне.
• Потім model для окремого завдання.
• Потім будь-яке збережене перевизначення моделі cron-сесії.
• Потім звичайний вибір моделі агента/типової моделі.

Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторних спроб перемикання cron переривається замість нескінченного циклу.

Налагодження:

openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>

Документація: Завдання Cron, CLI cron.

Використовуйте вбудовані команди openclaw skills або помістіть Skills у свій робочий простір. Інтерфейс Skills для macOS недоступний у Linux. Переглядайте Skills на https://clawhub.ai.

openclaw skills search "calendar"
openclaw skills search --limit 20
openclaw skills install <skill-slug>
openclaw skills install <skill-slug> --version <version>
openclaw skills install <skill-slug> --force
openclaw skills update --all
openclaw skills list --eligible
openclaw skills check

Вбудована команда openclaw skills install записує в каталог skills/ активного робочого простору. Установлюйте окремий CLI clawhub лише якщо хочете публікувати або синхронізувати власні Skills. Для спільних установлень між агентами розмістіть Skill у ~/.openclaw/skills і використовуйте agents.defaults.skills або agents.list[].skills, якщо хочете звузити, які агенти можуть його бачити.

Так. Використовуйте планувальник Gateway:

• Завдання Cron для запланованих або повторюваних завдань (зберігаються після перезапусків).
• Heartbeat для періодичних перевірок "головної сесії".
• Ізольовані завдання для автономних агентів, які публікують підсумки або доставляють повідомлення в чати.

Документація: Завдання Cron, Автоматизація та завдання, Heartbeat.

Не напряму. Skills для macOS обмежуються metadata.openclaw.os плюс потрібними бінарними файлами, і Skills з’являються в системному prompt лише тоді, коли вони придатні на хості 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. Якщо ви виберете "Завжди питати", схвалення "Завжди дозволяти" у запиті додає цю команду до allowlist.

Варіант C - проксіюйте бінарні файли macOS через SSH (розширено). Залиште Gateway у Linux, але зробіть так, щоб потрібні CLI-бінарники вирішувалися як SSH-обгортки, що запускаються на Mac. Потім перевизначте Skill, щоб дозволити Linux і він залишався придатним.

1. Створіть SSH-обгортку для бінарника (приклад: memo для Apple Notes):

   #!/usr/bin/env bash
   set -euo pipefail
   exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"
   

2. Помістіть обгортку в PATH на хості Linux (наприклад ~/bin/memo).

3. Перевизначте метадані Skill (у робочому просторі або ~/.openclaw/skills), щоб дозволити Linux:

   ---
   name: apple-notes
   description: Manage Apple Notes via the memo CLI on macOS.
   metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
   ---
   

4. Почніть нову сесію, щоб знімок Skills оновився.

Наразі вбудованої немає.

Варіанти:

• Користувацький Skill / Plugin: найкраще для надійного доступу до API (Notion/HeyGen обидва мають API).
• Автоматизація браузера: працює без коду, але повільніша й крихкіша.

Якщо ви хочете зберігати контекст для кожного клієнта (агентські робочі процеси), простий шаблон такий:

• Одна сторінка Notion на клієнта (контекст + уподобання + активна робота).
• Попросіть агента отримати цю сторінку на початку сесії.

Якщо хочете нативну інтеграцію, відкрийте запит на функцію або створіть Skill, націлений на ці API.

Установлення Skills:

openclaw skills install <skill-slug>
openclaw skills update --all

Вбудовані встановлення потрапляють у каталог skills/ активного робочого простору. Для спільних Skills між агентами розмістіть їх у ~/.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:

openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot

Якщо хочете власну назву, створіть явний профіль MCP:

openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser --browser-profile chrome-live tabs

Цей шлях може використовувати локальний браузер хоста або підключений браузерний вузол. Якщо 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_DOCKER_APT_PACKAGES.
• Установіть браузери Playwright через вбудований CLI: node /app/node_modules/playwright-core/cli.js install chromium
• Установіть PLAYWRIGHT_BROWSERS_PATH і переконайтеся, що шлях зберігається.

Документація: Docker, Браузер.

Так - якщо ваш приватний трафік це DM, а публічний трафік це групи.

Використовуйте agents.defaults.sandbox.mode: "non-main", щоб групові/канальні сесії (ключі не main) запускалися в налаштованому backend пісочниці, тоді як головна DM-сесія залишалася на хості. Docker є типовим backend, якщо ви не виберете інший. Потім обмежте, які інструменти доступні в сесіях пісочниці, через tools.sandbox.tools.

Покрокове налаштування + приклад конфігурації: Групи: особисті DM + публічні групи

Ключова довідка з конфігурації: Конфігурація Gateway

Установіть agents.defaults.sandbox.docker.binds на ["host:path:mode"] (наприклад, "/home/user/src:/src:ro"). Глобальні прив’язки та прив’язки окремого агента об’єднуються; прив’язки окремого агента ігноруються, коли scope: "shared". Використовуйте :ro для всього чутливого й пам’ятайте, що прив’язки обходять стіни файлової системи пісочниці.

OpenClaw перевіряє джерела прив’язок як за нормалізованим шляхом, так і за канонічним шляхом, розв’язаним через найглибшого наявного предка. Це означає, що виходи через батьківські симлінки все одно безпечно відхиляються, навіть коли останній сегмент шляху ще не існує, а перевірки дозволеного кореня все ще застосовуються після розв’язання симлінків.

Див. Пісочниця і Пісочниця проти політики інструментів проти підвищених прав для прикладів і приміток щодо безпеки.

Пам’ять OpenClaw - це просто Markdown-файли в робочому просторі агента:

• Щоденні нотатки в memory/YYYY-MM-DD.md
• Впорядковані довгострокові нотатки в MEMORY.md (лише головні/приватні сесії)

OpenClaw також запускає тихий скид пам’яті перед Compaction, щоб нагадати моделі записати довговічні нотатки перед автоматичним Compaction. Це запускається лише тоді, коли робочий простір доступний для запису (пісочниці лише для читання пропускають це). Див. Пам’ять.

Попросіть бота записати факт у пам’ять. Довгострокові нотатки належать до MEMORY.md, короткостроковий контекст іде в memory/YYYY-MM-DD.md.

Це все ще напрям, який ми вдосконалюємо. Корисно нагадати моделі зберегти спогади; вона знатиме, що робити. Якщо вона й далі забуває, перевірте, що Gateway використовує той самий робочий простір під час кожного запуску.

Документація: Пам’ять, Робочий простір агента.

Файли пам’яті живуть на диску й зберігаються, доки ви їх не видалите. Обмеженням є ваше сховище, а не модель. Контекст сесії все ще обмежується вікном контексту моделі, тому довгі розмови можуть compact або truncate. Саме тому існує пошук у пам’яті - він повертає в контекст лише релевантні частини.

Документація: Пам’ять, Контекст.

Лише якщо ви використовуєте OpenAI embeddings. Codex OAuth покриває чат/доповнення і не надає доступу до embeddings, тож вхід через Codex (OAuth або вхід у Codex CLI) не допомагає для семантичного пошуку в пам’яті. OpenAI embeddings все одно потребують справжнього ключа API (OPENAI_API_KEY або models.providers.openai.apiKey).

Якщо ви не задаєте провайдера явно, OpenClaw автоматично вибирає провайдера, коли може визначити ключ API (профілі автентифікації, models.providers.*.apiKey або змінні середовища). Він віддає перевагу OpenAI, якщо знаходить ключ OpenAI, інакше Gemini, якщо знаходить ключ Gemini, потім Voyage, потім Mistral. Якщо віддалений ключ недоступний, пошук у пам’яті залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштований і наявний шлях до локальної моделі, OpenClaw віддає перевагу local. Ollama підтримується, коли ви явно задаєте memorySearch.provider = "ollama".

Якщо ви хочете залишитися локально, задайте memorySearch.provider = "local" (і за бажанням memorySearch.fallback = "none"). Якщо вам потрібні Gemini embeddings, задайте memorySearch.provider = "gemini" і надайте GEMINI_API_KEY (або memorySearch.remote.apiKey). Ми підтримуємо моделі embeddings OpenAI, Gemini, Voyage, Mistral, Ollama або локальні - див. Пам’ять для деталей налаштування.

Ні - стан OpenClaw є локальним, але зовнішні сервіси все одно бачать те, що ви їм надсилаєте.

• Локально за замовчуванням: сеанси, файли пам’яті, конфігурація та робочий простір зберігаються на хості Gateway (~/.openclaw + каталог вашого робочого простору).
• Віддалено за потреби: повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI/тощо), потрапляють до їхніх API, а чат-платформи (WhatsApp/Telegram/Slack/тощо) зберігають дані повідомлень на своїх серверах.
• Ви контролюєте обсяг даних: використання локальних моделей утримує prompts на вашій машині, але трафік каналів все одно проходить через сервери каналу.

Див. також: Робочий простір агента, Пам’ять.

Усе зберігається в $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, налаштовується через:

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

Якщо бот "забуває" після перезапуску, переконайтеся, що Gateway використовує той самий робочий простір під час кожного запуску (і пам’ятайте: віддалений режим використовує робочий простір хоста Gateway, а не ваш локальний ноутбук).

Порада: якщо вам потрібна стабільна поведінка або вподобання, попросіть бота записати це в AGENTS.md або MEMORY.md, а не покладатися на історію чату.

Див. Робочий простір агента і Пам’ять.

Помістіть свій робочий простір агента в приватний репозиторій git і створюйте його резервні копії в приватному місці (наприклад, GitHub private). Це збереже пам’ять + файли AGENTS/SOUL/USER і дасть змогу пізніше відновити "свідомість" асистента.

Не комітьте нічого з ~/.openclaw (облікові дані, сеанси, токени або зашифровані таємні навантаження). Якщо вам потрібне повне відновлення, створюйте резервні копії і робочого простору, і каталогу стану окремо (див. запитання про міграцію вище).

Документація: Робочий простір агента.

Див. окремий посібник: Видалення.

Так. Робочий простір є cwd за замовчуванням і якорем пам’яті, а не жорсткою пісочницею. Відносні шляхи визначаються всередині робочого простору, але абсолютні шляхи можуть отримувати доступ до інших розташувань хоста, якщо не ввімкнено пісочницю. Якщо вам потрібна ізоляція, використовуйте agents.defaults.sandbox або налаштування пісочниці для окремого агента. Якщо ви хочете, щоб репозиторій був робочим каталогом за замовчуванням, вкажіть у workspace цього агента корінь репозиторію. Репозиторій OpenClaw - це лише вихідний код; тримайте робочий простір окремо, якщо ви не хочете навмисно, щоб агент працював усередині нього.

Приклад (репозиторій як cwd за замовчуванням):

{
  agents: {
    defaults: {
      workspace: "~/Projects/my-repo",
    },
  },
}

Стан сеансів належить хосту Gateway. Якщо ви у віддаленому режимі, потрібне вам сховище сеансів розташоване на віддаленій машині, а не на вашому локальному ноутбуці. Див. Керування сеансами.

OpenClaw читає необов’язкову конфігурацію JSON5 з $OPENCLAW_CONFIG_PATH (за замовчуванням: ~/.openclaw/openclaw.json):

$OPENCLAW_CONFIG_PATH

Якщо файл відсутній, використовуються відносно безпечні значення за замовчуванням (зокрема робочий простір за замовчуванням ~/.openclaw/workspace).

Прив’язки не до loopback потребують дійсного шляху автентифікації gateway. На практиці це означає:

• автентифікація через спільний секрет: токен або пароль
• gateway.auth.mode: "trusted-proxy" за правильно налаштованим reverse proxy з перевіркою ідентичності

{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me",
    },
  },
}

Примітки:

• gateway.remote.token / .password самі по собі не вмикають автентифікацію локального gateway.
• Локальні шляхи викликів можуть використовувати gateway.remote.* як резервний варіант лише тоді, коли gateway.auth.* не задано.
• Для автентифікації паролем натомість задайте gateway.auth.mode: "password" разом із gateway.auth.password (або OPENCLAW_GATEWAY_PASSWORD).
• Якщо gateway.auth.token / gateway.auth.password явно налаштовано через SecretRef і його не вдається визначити, визначення завершується закрито (без маскування віддаленим fallback).
• Налаштування Control UI зі спільним секретом автентифікуються через connect.params.auth.token або connect.params.auth.password (зберігається в налаштуваннях app/UI). Режими з ідентичністю, як-от Tailscale Serve або trusted-proxy, натомість використовують заголовки запитів. Не додавайте спільні секрети в URL.
• З gateway.auth.mode: "trusted-proxy" same-host loopback reverse proxies потребують явного gateway.auth.trustedProxy.allowLoopback = true і запису loopback у gateway.trustedProxies.

OpenClaw за замовчуванням примусово застосовує автентифікацію gateway, включно з loopback. У звичайному стандартному шляху це означає автентифікацію токеном: якщо явний шлях автентифікації не налаштовано, запуск gateway переходить у режим токена і генерує токен лише на час виконання для цього запуску, тож локальні клієнти WS мають автентифікуватися. Явно налаштуйте gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN або OPENCLAW_GATEWAY_PASSWORD, коли клієнтам потрібен стабільний секрет між перезапусками. Це блокує інші локальні процеси від викликів Gateway.

Якщо ви віддаєте перевагу іншому шляху автентифікації, можете явно вибрати режим пароля (або, для reverse proxies з перевіркою ідентичності, trusted-proxy). Якщо ви справді хочете відкритий loopback, явно задайте gateway.auth.mode: "none" у своїй конфігурації. Doctor може будь-коли згенерувати для вас токен: openclaw doctor --generate-gateway-token.

Gateway відстежує конфігурацію і підтримує гаряче перезавантаження:

• gateway.reload.mode: "hybrid" (за замовчуванням): гаряче застосування безпечних змін, перезапуск для критичних
• hot, restart, off також підтримуються

Задайте cli.banner.taglineMode у конфігурації:

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

• off: приховує текст слогана, але залишає рядок назви/версії банера.
• default: щоразу використовує All your chats, one OpenClaw..
• random: ротація кумедних/сезонних слоганів (поведінка за замовчуванням).
• Якщо ви взагалі не хочете банер, задайте env OPENCLAW_HIDE_BANNER=1.

web_fetch працює без ключа API. web_search залежить від вибраного вами провайдера:

• Провайдери з API, як-от Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують свого звичайного налаштування ключа API.
• 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_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: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
          },
        },
      },
    },
    },
    tools: {
      web: {
        search: {
          enabled: true,
          provider: "brave",
          maxResults: 5,
        },
        fetch: {
          enabled: true,
          provider: "firecrawl", // optional; omit for auto-detect
        },
      },
    },
}

Конфігурація веб-пошуку для конкретного провайдера тепер розміщується в plugins.entries.<plugin>.config.webSearch.*. Застарілі шляхи провайдерів tools.web.search.* досі тимчасово завантажуються для сумісності, але їх не слід використовувати для нових конфігурацій. Конфігурація резервного веб-отримання Firecrawl розміщується в plugins.entries.firecrawl.config.webFetch.*.

Примітки:

• Якщо ви використовуєте списки дозволеного, додайте web_search/web_fetch/x_search або group:web.
• web_fetch увімкнено за замовчуванням (якщо його явно не вимкнено).
• Якщо tools.web.fetch.provider не вказано, OpenClaw автоматично визначає першого готового резервного провайдера отримання з доступних облікових даних. Наразі вбудований провайдер — Firecrawl.
• Демони читають змінні середовища з ~/.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 і заново налаштуйте канали/моделі.
• Якщо це було неочікувано, створіть звіт про баг і додайте останню відому конфігурацію або будь-яку резервну копію.
• Локальний coding agent часто може відтворити робочу конфігурацію з журналів або історії.

Як уникнути:

• Використовуйте openclaw config set для невеликих змін.
• Використовуйте openclaw configure для інтерактивного редагування.
• Спершу використовуйте config.schema.lookup, якщо ви не впевнені щодо точного шляху або форми поля; він повертає поверхневий вузол схеми плюс короткі описи безпосередніх дочірніх елементів для заглиблення.
• Використовуйте config.patch для часткових RPC-редагувань; залишайте config.apply лише для повної заміни конфігурації.
• Якщо ви використовуєте owner-only інструмент gateway із запуску агента, він все одно відхилятиме записи до tools.exec.ask / tools.exec.security (включно із застарілими псевдонімами tools.bash.*, що нормалізуються до тих самих захищених exec-шляхів).

Документація: Конфігурація, Налаштування, Усунення несправностей Gateway, Doctor.

Поширений шаблон — один Gateway (наприклад, Raspberry Pi) плюс вузли й агенти:

• Gateway (центральний): володіє каналами (Signal/WhatsApp), маршрутизацією та сесіями.
• Вузли (пристрої): Macs/iOS/Android підключаються як периферійні пристрої та надають локальні інструменти (system.run, canvas, camera).
• Агенти (воркери): окремі brains/workspaces для спеціальних ролей (наприклад, "Hetzner ops", "Personal data").
• Субагенти: запускають фонову роботу з основного агента, коли потрібен паралелізм.
• TUI: підключайтеся до Gateway і перемикайте агентів/сесії.

Документація: Вузли, Віддалений доступ, Маршрутизація Multi-Agent, Субагенти, TUI.

Так. Це опція конфігурації:

{
  browser: { headless: true },
  agents: {
    defaults: {
      sandbox: { browser: { headless: true } },
    },
  },
}

За замовчуванням false (з графічним вікном). Headless-режим на деяких сайтах частіше запускає антибот-перевірки. Див. Браузер.

Headless використовує той самий рушій Chromium і працює для більшості автоматизації (форми, кліки, scraping, входи). Основні відмінності:

• Немає видимого вікна браузера (використовуйте знімки екрана, якщо потрібна візуальна перевірка).
• Деякі сайти суворіше ставляться до автоматизації в headless-режимі (CAPTCHA, антибот). Наприклад, X/Twitter часто блокує headless-сесії.

Установіть browser.executablePath на ваш binary Brave (або будь-який браузер на основі Chromium) і перезапустіть Gateway. Повні приклади конфігурації див. у Браузер.

Повідомлення Telegram обробляються gateway. Gateway запускає агента й лише потім викликає вузли через Gateway WebSocket, коли потрібен інструмент вузла:

Telegram → Gateway → Агент → node.* → Вузол → Gateway → Telegram

Вузли не бачать вхідний трафік провайдера; вони отримують лише RPC-виклики вузлів.

Коротка відповідь: спарте свій комп’ютер як вузол. Gateway працює в іншому місці, але може викликати інструменти node.* (екран, камеру, систему) на вашій локальній машині через Gateway WebSocket.

Типове налаштування:

1. Запустіть Gateway на постійно ввімкненому хості (VPS/домашній сервер).

2. Додайте хост Gateway і ваш комп’ютер до однієї tailnet.

3. Переконайтеся, що Gateway WS доступний (прив’язка tailnet або SSH-тунель).

4. Відкрийте застосунок macOS локально й підключіться в режимі Remote over SSH (або напряму через tailnet), щоб він міг зареєструватися як вузол.

5. Схваліть вузол на Gateway:

   openclaw devices list
   openclaw devices approve <requestId>
   

Окремий TCP-міст не потрібен; вузли підключаються через Gateway WebSocket.

Нагадування про безпеку: спарювання вузла macOS дозволяє system.run на цій машині. Спарюйте лише пристрої, яким довіряєте, і перегляньте Безпека.

Документація: Вузли, Протокол Gateway, Віддалений режим macOS, Безпека.

Перевірте основне:

• Gateway запущено: openclaw gateway status
• Стан Gateway: openclaw status
• Стан каналу: openclaw channels status

Потім перевірте автентифікацію та маршрутизацію:

• Якщо ви використовуєте Tailscale Serve, переконайтеся, що gateway.auth.allowTailscale налаштовано правильно.
• Якщо ви підключаєтеся через SSH-тунель, підтвердьте, що локальний тунель працює й указує на правильний порт.
• Переконайтеся, що ваші списки дозволеного (DM або група) містять ваш обліковий запис.

Документація: Tailscale, Віддалений доступ, Канали.

Так. Вбудованого мосту "bot-to-bot" немає, але ви можете з’єднати їх кількома надійними способами:

Найпростіше: використайте звичайний чат-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). Нехай Bot A надішле повідомлення Bot B, а потім Bot B відповість як зазвичай.

CLI-міст (загальний): запустіть скрипт, який викликає інший Gateway за допомогою openclaw agent --message ... --deliver, націлюючись на чат, де слухає інший бот. Якщо один бот розміщено на віддаленому VPS, спрямуйте CLI на той віддалений Gateway через SSH/Tailscale (див. Віддалений доступ).

Приклад шаблону (запустіть із машини, яка може досягти цільового Gateway):

openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>

Порада: додайте запобіжник, щоб два боти не зациклювалися без кінця (лише згадки, списки дозволеного каналів або правило "не відповідати на повідомлення ботів").

Документація: Віддалений доступ, CLI агента, Надсилання агентом.

Ні. Один Gateway може розміщувати кілька агентів, кожен із власним робочим простором, типовими моделями та маршрутизацією. Це нормальне налаштування, і воно значно дешевше та простіше, ніж запускати один VPS на агента.

Використовуйте окремі VPS лише тоді, коли потрібна жорстка ізоляція (межі безпеки) або дуже різні конфігурації, які ви не хочете спільно використовувати. В іншому разі залишайте один Gateway і використовуйте кілька агентів або субагентів.

Так - вузли є основним способом доступу до вашого ноутбука з віддаленого Gateway, і вони відкривають більше, ніж доступ до shell. 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 підходить для ситуативного доступу до shell, але вузли простіші для постійних workflows агентів і автоматизації пристроїв.

Документація: Вузли, CLI вузлів, Браузер.

Ні. На одному хості має працювати лише один gateway, якщо ви навмисно не запускаєте ізольовані профілі (див. Кілька gateway). Вузли — це периферійні пристрої, що підключаються до gateway (вузли iOS/Android або "node mode" macOS у застосунку в рядку меню). Для headless-хостів вузлів і керування через CLI див. CLI хоста вузла.

Повний перезапуск потрібен для змін поверхонь gateway, discovery і hosted plugin.

Так.

• config.schema.lookup: перевірте одне піддерево конфігурації з його неглибоким вузлом схеми, відповідною UI-підказкою та короткими описами безпосередніх дочірніх елементів перед записом
• config.get: отримати поточний знімок + хеш
• config.patch: безпечне часткове оновлення (бажане для більшості RPC-редагувань); гаряче перезавантаження, коли можливо, і перезапуск, коли потрібно
• config.apply: перевірити + замінити всю конфігурацію; гаряче перезавантаження, коли можливо, і перезапуск, коли потрібно
• Runtime-інструмент gateway, доступний лише власнику, усе ще відмовляється переписувати tools.exec.ask / tools.exec.security; застарілі псевдоніми tools.bash.* нормалізуються до тих самих захищених шляхів exec

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Це задає ваш робочий простір і обмежує, хто може запускати бота.

Мінімальні кроки:

1. Встановіть + увійдіть на VPS

   curl -fsSL https://tailscale.com/install.sh | sh
   sudo tailscale up
   

2. Встановіть + увійдіть на своєму Mac

   • Використайте застосунок Tailscale і ввійдіть у той самий tailnet.

3. Увімкніть MagicDNS (рекомендовано)

   • У консолі адміністратора Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я.

4. Використовуйте ім’я хоста tailnet

   • SSH: ssh [email protected]
   • Gateway WS: ws://your-vps.tailnet-xxxx.ts.net:18789

Якщо вам потрібен Control UI без SSH, використайте Tailscale Serve на VPS:

openclaw gateway --tailscale serve

Це залишає gateway прив’язаним до loopback і відкриває HTTPS через Tailscale. Див. Tailscale.

Serve відкриває Gateway Control UI + WS. Вузли підключаються через той самий endpoint Gateway WS.

Рекомендоване налаштування:

1. Переконайтеся, що VPS + Mac у тому самому tailnet.

2. Використайте macOS-застосунок у віддаленому режимі (ціль SSH може бути ім’ям хоста tailnet). Застосунок тунелюватиме порт Gateway і підключиться як вузол.

3. Схваліть вузол на gateway:

   openclaw devices list
   openclaw devices approve <requestId>
   

Документація: протокол Gateway, виявлення, віддалений режим macOS.

Якщо на другому ноутбуці вам потрібні лише локальні інструменти (екран/камера/exec), додайте його як вузол. Це зберігає один Gateway і дає змогу уникнути дублювання конфігурації. Інструменти локального вузла наразі доступні лише для macOS, але ми плануємо розширити їх на інші ОС.

Встановлюйте другий Gateway лише тоді, коли потрібна жорстка ізоляція або два повністю окремі боти.

Документація: вузли, CLI вузлів, кілька gateway.

OpenClaw читає змінні середовища з батьківського процесу (shell, launchd/systemd, CI тощо) і додатково завантажує:

• .env з поточного робочого каталогу
• глобальний резервний .env з ~/.openclaw/.env (також $OPENCLAW_STATE_DIR/.env)

Жоден файл .env не перевизначає наявні змінні середовища.

Також можна визначити inline-змінні середовища в конфігурації (застосовуються лише якщо їх немає в середовищі процесу):

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

Див. /environment для повного порядку пріоритетів і джерел.

Два поширені виправлення:

1. Помістіть відсутні ключі в ~/.openclaw/.env, щоб їх було підхоплено навіть тоді, коли сервіс не успадковує середовище вашого shell.
2. Увімкніть імпорт із shell (зручність за явним увімкненням):

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

Це запускає ваш login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає). Еквіваленти змінних середовища: OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.

openclaw models status повідомляє, чи ввімкнено імпорт середовища shell. "Shell env: off" не означає, що ваших змінних середовища бракує - це лише означає, що OpenClaw не завантажуватиме ваш login shell автоматично.

Якщо Gateway працює як сервіс (launchd/systemd), він не успадкує ваше середовище shell. Виправте це одним із таких способів:

1. Помістіть токен у ~/.openclaw/.env:

   COPILOT_GITHUB_TOKEN=...
   

2. Або ввімкніть імпорт із shell (env.shellEnv.enabled: true).

3. Або додайте його до блока env у вашій конфігурації (застосовується лише якщо відсутній).

Потім перезапустіть gateway і перевірте знову:

openclaw models status

Токени Copilot читаються з COPILOT_GITHUB_TOKEN (також GH_TOKEN / GITHUB_TOKEN). Див. /concepts/model-providers і /environment.

Надішліть /new або /reset як окреме повідомлення. Див. керування сесіями.

Термін дії сесій може спливати після session.idleMinutes, але це вимкнено за замовчуванням (типово 0). Задайте додатне значення, щоб увімкнути завершення через бездіяльність. Коли це ввімкнено, наступне повідомлення після періоду бездіяльності починає новий ідентифікатор сесії для цього ключа чату. Це не видаляє стенограми - це лише починає нову сесію.

{
  session: {
    idleMinutes: 240,
  },
}

Так, через багатоагентну маршрутизацію та субагентів. Ви можете створити одного координувального агента і кількох робочих агентів із власними робочими просторами та моделями.

Водночас це краще сприймати як цікавий експеримент. Це потребує багато токенів і часто менш ефективно, ніж використання одного бота з окремими сесіями. Типова модель, яку ми бачимо, — це один бот, з яким ви спілкуєтеся, і різні сесії для паралельної роботи. Цей бот також може створювати субагентів за потреби.

Документація: Багатоагентна маршрутизація, Субагенти, CLI агентів.

Контекст сесії обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато файлів можуть спричинити Compaction або обрізання.

Що допомагає:

• Попросіть бота підсумувати поточний стан і записати його у файл.
• Використовуйте /compact перед довгими завданнями, а /new — під час зміни теми.
• Тримайте важливий контекст у робочому просторі й попросіть бота прочитати його назад.
• Використовуйте субагентів для довгої або паралельної роботи, щоб основний чат залишався меншим.
• Виберіть модель із більшим контекстним вікном, якщо це трапляється часто.

Використайте команду скидання:

openclaw reset

Повне неінтерактивне скидання:

openclaw reset --scope full --yes --non-interactive

Потім запустіть налаштування знову:

openclaw onboard --install-daemon

Примітки:

• Онбординг також пропонує Скинути, якщо бачить наявну конфігурацію. Див. Онбординг (CLI).
• Якщо ви використовували профілі (--profile / OPENCLAW_PROFILE), скиньте кожен каталог стану (типові значення — ~/.openclaw-<profile>).
• Скидання для розробки: openclaw gateway --dev --reset (лише для розробки; стирає конфігурацію розробки + облікові дані + сесії + робочий простір).

Використайте один із цих варіантів:

• Compact (зберігає розмову, але підсумовує старіші репліки):

  /compact
  

  або /compact <instructions>, щоб спрямувати підсумок.

• Скидання (свіжий ID сесії для того самого ключа чату):

  /new
  /reset
  

Якщо це продовжує траплятися:

• Увімкніть або налаштуйте обрізання сесії (agents.defaults.contextPruning), щоб скоротити старий вивід інструментів.
• Використовуйте модель із більшим контекстним вікном.

Документація: Compaction, Обрізання сесії, Керування сесіями.

Це помилка валідації провайдера: модель згенерувала блок tool_use без обов’язкового input. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих гілок або зміни інструмента/схеми).

Виправлення: почніть свіжу сесію за допомогою /new (окремим повідомленням).

Heartbeat запускається кожні 30m за замовчуванням (1h під час використання автентифікації OAuth). Налаштуйте або вимкніть його:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "2h", // or "0m" to disable
      },
    },
  },
}

Якщо HEARTBEAT.md існує, але фактично порожній (лише порожні рядки та markdown заголовки на кшталт # Heading), OpenClaw пропускає запуск Heartbeat, щоб заощадити API-виклики. Якщо файл відсутній, Heartbeat все одно запускається, а модель вирішує, що робити.

Перевизначення для окремих агентів використовують agents.list[].heartbeat. Документація: Heartbeat.

Ні. OpenClaw працює на вашому власному обліковому записі, тож якщо ви є в групі, OpenClaw може її бачити. За замовчуванням відповіді в групах заблоковані, доки ви не дозволите відправників (groupPolicy: "allowlist").

Якщо ви хочете, щоб лише ви могли запускати відповіді в групі:

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

Варіант 1 (найшвидший): переглядайте логи в реальному часі й надішліть тестове повідомлення в групі:

openclaw logs --follow --json

Шукайте chatId (або from), що закінчується на @g.us, наприклад: [email protected].

Варіант 2 (якщо вже налаштовано/додано до allowlist): перелічіть групи з конфігурації:

openclaw directory groups list --channel whatsapp

Документація: WhatsApp, Каталог, Логи.

Дві поширені причини:

• Увімкнено обмеження за згадуванням (за замовчуванням). Ви маєте @згадати бота (або збігтися з mentionPatterns).
• Ви налаштували channels.whatsapp.groups без "*", і групу не додано до allowlist.

Див. Групи і Групові повідомлення.

Прямі чати за замовчуванням згортаються до основної сесії. Групи/канали мають власні ключі сесій, а теми 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 або Node за потреби.

Документація: Маршрутизація кількох агентів, Slack, Браузер, Nodes.

gateway.port керує єдиним мультиплексованим портом для WebSocket + HTTP (інтерфейс керування, hooks тощо).

Пріоритет:

--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789

Тому що "running" — це погляд супервізора (launchd/systemd/schtasks). Перевірка з’єднання — це фактичне підключення CLI до WebSocket Gateway.

Використовуйте openclaw gateway status і довіряйте цим рядкам:

• Probe target: (URL, який фактично використала перевірка)
• Listening: (що фактично прив’язано до порту)
• Last gateway error: (типова першопричина, коли процес живий, але порт не слухає)

Ви редагуєте один файл конфігурації, тоді як служба запускає інший (часто через невідповідність --profile / OPENCLAW_STATE_DIR).

Виправлення:

openclaw gateway install --force

Запустіть це з тим самим --profile / середовищем, яке має використовувати служба.

OpenClaw забезпечує runtime-блокування, негайно прив’язуючи слухач WebSocket під час запуску (типово ws://127.0.0.1:18789). Якщо прив’язка завершується помилкою EADDRINUSE, він кидає GatewayLockError, вказуючи, що інший екземпляр уже слухає.

Виправлення: зупиніть інший екземпляр, звільніть порт або запустіть з openclaw gateway --port <port>.

Установіть gateway.mode: "remote" і вкажіть віддалений URL WebSocket, за бажанням зі спільними секретними віддаленими обліковими даними:

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password",
    },
  },
}

Нотатки:

• openclaw gateway запускається лише коли gateway.mode має значення local (або якщо ви передали прапорець перевизначення).
• Застосунок macOS стежить за файлом конфігурації та перемикає режими наживо, коли ці значення змінюються.
• gateway.remote.token / .password — це лише клієнтські віддалені облікові дані; самі по собі вони не вмикають локальну автентифікацію Gateway.

Ваш шлях автентифікації Gateway і метод автентифікації інтерфейсу не збігаються.

Факти (з коду):

• Інтерфейс керування зберігає токен у sessionStorage для поточної сесії вкладки браузера та вибраного URL Gateway, тому оновлення тієї самої вкладки продовжують працювати без відновлення довготривалого збереження токена в localStorage.
• У разі AUTH_TOKEN_MISMATCH довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном пристрою, коли Gateway повертає підказки повтору (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
• Ця повторна спроба з кешованим токеном тепер повторно використовує кешовані схвалені області, збережені разом із токеном пристрою. Викликачі з явним deviceToken / явними scopes усе ще зберігають запитаний набір областей замість успадкування кешованих областей.
• Поза цим шляхом повторної спроби пріоритет автентифікації підключення такий: явний спільний токен/пароль спочатку, потім явний deviceToken, потім збережений токен пристрою, потім bootstrap-токен.
• Перевірки областей bootstrap-токена мають префікс ролі. Вбудований allowlist bootstrap-оператора задовольняє лише запити оператора; Node або інші неоператорські ролі все ще потребують областей під власним префіксом ролі.

Виправлення:

• Найшвидше: 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, потім вставте відповідний секрет у налаштування інтерфейсу керування.
• Режим Tailscale Serve: переконайтеся, що gateway.auth.allowTailscale увімкнено і ви відкриваєте URL Serve, а не сирий URL loopback/tailnet, який обходить заголовки ідентичності Tailscale.
• Режим довіреного проксі: переконайтеся, що ви заходите через налаштований проксі з урахуванням ідентичності, а не через сирий 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 може запускати кілька каналів повідомлень і агентів. Використовуйте кілька Gateway лише коли потрібна надлишковість (наприклад, резервний бот) або жорстка ізоляція.

Так, але потрібно ізолювати:

• 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>)). Повний посібник: Кілька gateway.

Gateway — це сервер WebSocket, і він очікує, що найперше повідомлення буде кадром connect. Якщо він отримує щось інше, він закриває з’єднання з кодом 1008 (порушення політики).

Поширені причини:

• Ви відкрили HTTP URL у браузері (http://...) замість клієнта WS.
• Ви використали неправильний порт або шлях.
• Проксі або тунель видалив заголовки автентифікації або надіслав не-Gateway-запит.

Швидкі виправлення:

1. Використовуйте WS URL: ws://<host>:18789 (або wss://..., якщо HTTPS).
2. Не відкривайте порт WS у звичайній вкладці браузера.
3. Якщо автентифікацію ввімкнено, додайте токен/пароль у кадр connect.

Якщо ви використовуєте CLI або TUI, URL має виглядати так:

openclaw tui --url ws://<host>:18789 --token <token>

Подробиці протоколу: Протокол Gateway.

Файлові журнали (структуровані):

/tmp/openclaw/openclaw-YYYY-MM-DD.log

Ви можете встановити стабільний шлях через logging.file. Рівень файлового журналу керується logging.level. Докладність консолі керується --verbose і logging.consoleLevel.

Найшвидше відстеження журналу:

openclaw logs --follow

Журнали служби/супервізора (коли gateway працює через launchd/systemd):

• macOS: $OPENCLAW_STATE_DIR/logs/gateway.log і gateway.err.log (типово: ~/.openclaw/logs/...; профілі використовують ~/.openclaw-<profile>/logs/...)
• Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
• Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

Див. усунення несправностей для більшого.

Використовуйте помічники gateway:

openclaw gateway status
openclaw gateway restart

Якщо ви запускаєте gateway вручну, openclaw gateway --force може повторно зайняти порт. Див. Gateway.

Є два режими встановлення Windows:

1) WSL2 (рекомендовано): Gateway працює всередині Linux.

Відкрийте PowerShell, увійдіть у WSL, потім перезапустіть:

wsl
openclaw gateway status
openclaw gateway restart

Якщо ви ніколи не встановлювали службу, запустіть її у передньому плані:

openclaw gateway run

2) Нативний Windows (не рекомендовано): Gateway працює безпосередньо у Windows.

Відкрийте PowerShell і запустіть:

openclaw gateway status
openclaw gateway restart

Якщо запускаєте вручну (без служби), використовуйте:

openclaw gateway run

Документація: Windows (WSL2), runbook служби Gateway.

Почніть зі швидкої перевірки стану:

openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow

Поширені причини:

• Автентифікацію моделі не завантажено на хості 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?

Потім перегляньте журнали в реальному часі:

openclaw logs --follow

Документація: Dashboard, Віддалений доступ, Усунення несправностей.

Почніть із журналів і стану каналу:

openclaw channels status
openclaw channels logs --channel telegram

Потім зіставте помилку:

• BOT_COMMANDS_TOO_MUCH: меню Telegram має забагато записів. OpenClaw уже обрізає їх до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі записи меню все одно потрібно прибрати. Зменште кількість команд plugin/skill/користувацьких команд або вимкніть channels.telegram.commands.native, якщо меню вам не потрібне.
• TypeError: fetch failed, Network request for 'setMyCommands' failed! або подібні мережеві помилки: якщо ви на VPS або за проксі, підтвердьте, що вихідний HTTPS дозволено й DNS працює для api.telegram.org.

Якщо Gateway віддалений, переконайтеся, що переглядаєте журнали на хості Gateway.

Документація: Telegram, Усунення несправностей каналів.

Спочатку підтвердьте, що Gateway доступний і агент може запускатися:

openclaw status
openclaw models status
openclaw logs --follow

У TUI використайте /status, щоб побачити поточний стан. Якщо очікуєте відповіді в чат-каналі, переконайтеся, що доставку ввімкнено (/deliver on).

Документація: TUI, Slash-команди.

Якщо ви встановили службу:

openclaw gateway stop
openclaw gateway start

Це зупиняє/запускає керовану службу (launchd на macOS, systemd на Linux). Використовуйте це, коли Gateway працює у фоні як демон.

Якщо ви запускаєте у передньому плані, зупиніть за допомогою Ctrl-C, потім:

openclaw gateway run

Документація: Операційний посібник служби Gateway.

• openclaw gateway restart: перезапускає фонову службу (launchd/systemd).
• openclaw gateway: запускає gateway у передньому плані для цього термінального сеансу.

Якщо ви встановили службу, використовуйте команди gateway. Використовуйте openclaw gateway, коли потрібен одноразовий запуск у передньому плані.

Запустіть Gateway з --verbose, щоб отримати більше деталей у консолі. Потім перевірте файл журналу на помилки автентифікації каналу, маршрутизації моделі та RPC.

Вихідні вкладення від агента мають містити рядок MEDIA:<path-or-url> (окремим рядком). Див. Налаштування помічника OpenClaw і Надсилання агентом.

Надсилання через CLI:

openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png

Також перевірте:

• Цільовий канал підтримує вихідні медіа й не заблокований списками дозволених.
• Файл у межах обмежень розміру провайдера (розмір зображень змінюється до максимум 2048px).
• tools.fs.workspaceOnly=true обмежує надсилання локальних шляхів робочою областю, temp/media-store і файлами, перевіреними sandbox.
• tools.fs.workspaceOnly=false дозволяє MEDIA: надсилати локальні файли хоста, які агент уже може читати, але лише для медіа та безпечних типів документів (зображення, аудіо, відео, PDF і документи Office). Звичайний текст і файли, схожі на секрети, усе ще блокуються.

Див. Зображення.

Сприймайте вхідні особисті повідомлення як недовірений ввід. Типові налаштування розроблені для зменшення ризику:

• Типова поведінка на каналах із підтримкою особистих повідомлень - зв’язування:
  • Невідомі відправники отримують код зв’язування; бот не обробляє їхнє повідомлення.
  • Підтвердіть за допомогою: 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 і суворі списки дозволених інструментів

Деталі: Безпека.

Так, для більшості налаштувань. Ізоляція бота за допомогою окремих облікових записів і номерів телефону зменшує зону впливу, якщо щось піде не так. Це також спрощує ротацію облікових даних або відкликання доступу без впливу на ваші особисті облікові записи.

Почніть з малого. Надавайте доступ лише до інструментів і облікових записів, які справді потрібні, і розширюйте пізніше за потреби.

Документація: Безпека, Зв’язування.

Ми не рекомендуємо повну автономію над вашими особистими повідомленнями. Найбезпечніший шаблон:

• Тримайте особисті повідомлення в режимі зв’язування або суворому списку дозволених.
• Використовуйте окремий номер або обліковий запис, якщо хочете, щоб він надсилав повідомлення від вашого імені.
• Дозвольте йому підготувати чернетку, а потім підтвердіть перед надсиланням.

Якщо хочете експериментувати, робіть це на спеціальному обліковому записі й тримайте його ізольованим. Див. Безпека.

Так, якщо агент лише для чату, а ввід довірений. Менші рівні більш вразливі до перехоплення інструкцій, тому уникайте їх для агентів з увімкненими інструментами або під час читання недовіреного вмісту. Якщо мусите використовувати меншу модель, заблокуйте інструменти й запускайте всередині sandbox. Див. Безпека.

Коди зв’язування надсилаються лише коли невідомий відправник пише боту і dmPolicy: "pairing" увімкнено. /start сам по собі не генерує код.

Перевірте очікувані запити:

openclaw pairing list telegram

Якщо хочете негайний доступ, додайте свій sender id до списку дозволених або встановіть dmPolicy: "open" для цього облікового запису.

Ні. Типова політика особистих повідомлень WhatsApp - зв’язування. Невідомі відправники лише отримують код зв’язування, а їхнє повідомлення не обробляється. OpenClaw відповідає лише на чати, які отримує, або на явні надсилання, які ви запускаєте.

Підтвердьте зв’язування за допомогою:

openclaw pairing approve whatsapp <code>

Перелічіть очікувані запити:

openclaw pairing list whatsapp

Запит номера телефону в майстрі: він використовується, щоб налаштувати ваш список дозволених/власника, щоб ваші власні особисті повідомлення були дозволені. Він не використовується для автоматичного надсилання. Якщо ви запускаєте на своєму особистому номері WhatsApp, використовуйте цей номер і ввімкніть channels.whatsapp.selfChatMode.

Більшість внутрішніх повідомлень або повідомлень інструментів з’являються лише коли verbose, trace або reasoning увімкнено для цього сеансу.

Виправте в чаті, де це бачите:

/verbose off
/trace off
/reasoning off

Якщо шум усе ще є, перевірте налаштування сеансу в Control UI і встановіть verbose на успадковувати. Також підтвердьте, що ви не використовуєте профіль бота з verboseDefault, встановленим на on у конфігурації.

Документація: Міркування й verbose, Безпека.

Надішліть будь-що з цього як окреме повідомлення (без slash):

stop
stop action
stop current action
stop run
stop current run
stop agent
stop the agent
stop openclaw
openclaw stop
stop don't do anything
stop do not do anything
stop doing anything
please stop
stop please
abort
esc
wait
exit
interrupt

Це тригери переривання (не slash-команди).

Для фонових процесів (з інструмента exec) ви можете попросити агента виконати:

process action:kill sessionId:XXX

Огляд slash-команд: див. Slash-команди.

Більшість команд потрібно надсилати як окреме повідомлення, що починається з /, але кілька скорочень (наприклад /status) також працюють inline для відправників зі списку дозволених.

OpenClaw блокує міжпровайдерське надсилання повідомлень за замовчуванням. Якщо виклик інструмента прив’язаний до Telegram, він не надсилатиме до Discord, якщо ви явно цього не дозволите.

Увімкніть міжпровайдерське надсилання повідомлень для агента:

{
  tools: {
    message: {
      crossContext: {
        allowAcrossProviders: true,
        marker: { enabled: true, prefix: "[from {channel}] " },
      },
    },
  },
}

Перезапустіть gateway після редагування конфігурації.

Режим черги керує тим, як нові повідомлення взаємодіють із запущеним виконанням. Використайте /queue, щоб змінити режими:

• steer - поставити все очікуване керування в чергу для наступної межі моделі в поточному виконанні
• queue - застаріле почергове керування
• followup - запускати повідомлення по одному
• collect - групувати повідомлення й відповісти один раз
• steer-backlog - скерувати зараз, потім обробити накопичену чергу
• 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 для агента, який виконується.