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

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

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

Основне:

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

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

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

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

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

Повсякденна користь зазвичай виглядає так:

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

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

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

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

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

Переваги:

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

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

Використовуйте керовані перевизначення замість редагування копії в репозиторії. Покладіть зміни в ~/.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 для кожного завдання.
• Субагенти: маршрутизуйте завдання до окремих агентів із різними типовими моделями.
• Перемикання на вимогу: використовуйте /model, щоб будь-коли змінити модель поточного сеансу.

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

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

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

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

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

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

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

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

Обов'язкова конфігурація:

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

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

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

• Доставка субагента в режимі завершення надає перевагу будь-якому прив'язаному thread або маршруту розмови, якщо він існує.
• Якщо джерело завершення містить лише канал, OpenClaw використовує резервний маршрут, збережений у сеансі запитувача (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 50openclaw tasks show <runId-or-sessionKey>

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

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

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

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

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

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

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

openclaw cron runs --id <jobId> --limit 50openclaw 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 20openclaw skills install <skill-slug>openclaw skills install <skill-slug> --version <version>openclaw skills install <skill-slug> --forceopenclaw skills update --allopenclaw skills list --eligibleopenclaw 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. Якщо вибрати "Завжди запитувати", схвалення "Завжди дозволяти" у prompt додає цю команду до списку дозволених.

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

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

   #!/usr/bin/env bashset -euo pipefailexec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"

2. Додайте обгортку до PATH на хості Linux (наприклад ~/bin/memo).

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

   ---name: apple-notesdescription: 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 tabsopenclaw browser --browser-profile user snapshot

Якщо вам потрібна власна назва, створіть явний профіль MCP:

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

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

Поточні обмеження для existing-session / user:

• дії керуються ref, а не CSS-селекторами
• завантаження файлів потребує ref / inputRef і наразі підтримує один файл за раз
• responsebody, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого профілю 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) виконувалися в налаштованому бекенді пісочниці, тоді як основна DM-сесія залишалася на хості. Docker є стандартним бекендом, якщо ви не виберете інший. Потім обмежте, які інструменти доступні в сесіях пісочниці, через tools.sandbox.tools.

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

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

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

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

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

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

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

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

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

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

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

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

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

Лише якщо ви використовуєте 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 або local - див. Пам’ять, щоб дізнатися деталі налаштування.

Ні - стан 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; його можна налаштувати через:

{  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" за правильно налаштованим реверс-проксі з урахуванням ідентичності

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

Примітки:

• 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).
• Налаштування Control UI зі спільним секретом автентифікуються через connect.params.auth.token або connect.params.auth.password (зберігається в налаштуваннях застосунку/UI). Режими з ідентичністю, як-от Tailscale Serve або trusted-proxy, натомість використовують заголовки запиту. Уникайте розміщення спільних секретів в URL.
• З gateway.auth.mode: "trusted-proxy" реверс-проксі loopback на тому самому хості потребують явного 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.

Якщо ви віддаєте перевагу іншому шляху автентифікації, можете явно вибрати режим пароля (або, для реверс-проксі з урахуванням ідентичності, 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: ротаційні жартівливі/сезонні слогани (типова поведінка).
• Якщо ви взагалі не хочете банер, задайте змінну середовища 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.
• Якщо у вас немає останньої відомої робочої версії або відхиленого вмісту, відновіть із резервної копії або повторно запустіть openclaw doctor і заново налаштуйте канали/моделі.
• Якщо це було неочікувано, створіть звіт про помилку й додайте останню відому конфігурацію або будь-яку резервну копію.
• Локальний агент кодування часто може відновити робочу конфігурацію з журналів або історії.

Як уникнути:

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

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

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

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

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

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

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

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

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

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

Установіть browser.executablePath на двійковий файл 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 локально й підключіться в режимі Віддалено через SSH (або напряму через tailnet), щоб він міг зареєструватися як вузол.

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

   openclaw devices listopenclaw 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, Віддалений доступ, Канали.

Так. Вбудованого мосту "бот-до-бота" немає, але ви можете налаштувати це кількома надійними способами:

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

Повний перезапуск потрібен для змін 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

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

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

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

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

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

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

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

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

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

4. Використовуйте hostname 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 у Remote mode (ціль SSH може бути hostname tailnet). Застосунок створить тунель до порту Gateway і підключиться як вузол.

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

   openclaw devices listopenclaw devices approve <requestId>

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

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

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

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

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

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

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

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

{  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. Помістіть token у ~/.openclaw/.env:

   COPILOT_GITHUB_TOKEN=...

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

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

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

openclaw models status

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

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

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

{  session: {    idleMinutes: 240,  },}

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

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

Документація: маршрутизація між кількома агентами, субагенти, CLI агентів.

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

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

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

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

openclaw reset

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

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

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

openclaw onboard --install-daemon

Примітки:

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

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

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

  /compact

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

• Reset (нова session ID для того самого ключа чату):

  /new/reset

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

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

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

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

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

Heartbeats за замовчуванням запускаються кожні 30m (1h під час використання OAuth auth). Налаштуйте або вимкніть їх:

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

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

Перевизначення для окремих agent використовують 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 (якщо вже налаштовано/allowlisted): виведіть список груп із конфігурації:

openclaw directory groups list --channel whatsapp

Документація: WhatsApp, Directory, Logs.

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

• Увімкнено mention gating (типово). Ви маєте @mention бота (або збігтися з 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 або вузол за потреби.

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

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

Пріоритет:

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

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

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

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

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

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

openclaw gateway install --force

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

OpenClaw забезпечує блокування середовища виконання, негайно прив'язуючи слухач 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 і метод автентифікації UI не збігаються.

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

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

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

• Найшвидше: 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 увімкнено і ви відкриваєте URL Serve, а не сирий URL loopback/tailnet, який обходить заголовки ідентичності Tailscale.
• Режим довіреного проксі: переконайтеся, що ви проходите через налаштований проксі з урахуванням ідентичності, а не через сирий URL gateway. Проксі same-host loopback також потребують gateway.auth.trustedProxy.allowLoopback = true.
• Якщо невідповідність зберігається після однієї повторної спроби, поверніть/повторно затвердьте спарений токен пристрою:
  • openclaw devices list
  • openclaw devices rotate --device <id> --role operator
• Якщо цей виклик rotate каже, що його відхилено, перевірте дві речі:
  • сеанси спарених пристроїв можуть повертати лише власний пристрій, якщо вони також не мають 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 statusopenclaw gateway restart

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

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

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

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

wslopenclaw gateway statusopenclaw gateway restart

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

openclaw gateway run

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

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

openclaw gateway statusopenclaw gateway restart

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

openclaw gateway run

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

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

openclaw statusopenclaw models statusopenclaw channels statusopenclaw logs --follow

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

• Автентифікацію моделі не завантажено на хості Gateway (перевірте models status).
• Сполучення каналу/allowlist блокує відповіді (перевірте конфігурацію каналу та журнали).
• 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 statusopenclaw 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 statusopenclaw models statusopenclaw logs --follow

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

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

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

openclaw gateway stopopenclaw gateway start

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

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

openclaw gateway run

Документація: Runbook служби 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

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

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

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

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

• Типова поведінка в каналах із підтримкою DM — сполучення:
  • Невідомі відправники отримують код сполучення; бот не обробляє їхнє повідомлення.
  • Схвалити через: openclaw pairing approve --channel <channel> [--account <id>] <code>
  • Запити в очікуванні обмежені 3 на канал; перевірте openclaw pairing list --channel <channel> [--account <id>], якщо код не надійшов.
• Публічне відкриття DM потребує явного ввімкнення (dmPolicy: "open" і allowlist "*").

Запустіть openclaw doctor, щоб виявити ризикові політики DM.

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

Найбільший ризик виникає, коли інструменти ввімкнено: модель можна обманом змусити ексфільтрувати контекст або викликати інструменти від вашого імені. Зменште зону ураження так:

• використовуйте read-only або з вимкненими інструментами агента-"читача" для підсумовування недовіреного вмісту
• тримайте web_search / web_fetch / browser вимкненими для агентів із увімкненими інструментами
• також вважайте декодований текст файлів/документів недовіреним: OpenResponses input_file і витягнення медіавкладень обгортають витягнутий текст у явні маркери межі зовнішнього вмісту замість передавання сирого тексту файлу
• використовуйте sandbox і суворі allowlist для інструментів

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

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

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

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

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

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

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

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

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

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

openclaw pairing list telegram

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

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

Схваліть сполучення через:

openclaw pairing approve whatsapp <code>

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

openclaw pairing list whatsapp

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

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

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

/verbose off/trace off/reasoning off

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

Документація: Мислення та verbose, Безпека.

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

stopstop actionstop current actionstop runstop current runstop agentstop the agentstop openclawopenclaw stopstop don't do anythingstop do not do anythingstop doing anythingplease stopstop pleaseabortescwaitexitinterrupt

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

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

process action:kill sessionId:XXX

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

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

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

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

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

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

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

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