---
read_when:
- Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки середовища виконання
- Попереднє оцінювання проблем, про які повідомили користувачі, перед глибшим налагодженням
summary: Поширені запитання про налаштування, конфігурацію та використання OpenClaw
title: Поширені запитання
x-i18n:
generated_at: "2026-05-12T00:59:03Z"
model: gpt-5.5
provider: openai
source_hash: 57e42ea34d4f53cb9e6f0e9c175fd553a67e70aaca08a09be28f0bde43414bc8
source_path: help/faq.md
workflow: 16
---
Швидкі відповіді та глибше усунення несправностей для реальних налаштувань (локальна розробка, VPS, мультиагентність, OAuth/API-ключі, аварійне перемикання моделей). Для діагностики середовища виконання див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник конфігурації див. у [Конфігурація](/uk/gateway/configuration).
## Перші 60 секунд, якщо щось не працює
1. **Швидкий статус (перша перевірка)**
```bash
openclaw status
```
Швидкий локальний підсумок: ОС + оновлення, доступність gateway/служби, агенти/сеанси, конфігурація провайдера + проблеми середовища виконання (коли gateway доступний).
2. **Звіт для вставлення (безпечно ділитися)**
```bash
openclaw status --all
```
Діагностика лише для читання з хвостом журналу (токени приховано).
3. **Стан демона + порту**
```bash
openclaw gateway status
```
Показує середовище виконання супервізора порівняно з доступністю RPC, цільову URL-адресу перевірки та яку конфігурацію, ймовірно, використала служба.
4. **Глибокі перевірки**
```bash
openclaw status --deep
```
Запускає live-перевірку справності gateway, зокрема перевірки каналів, коли це підтримується
(потрібен доступний gateway). Див. [Справність](/uk/gateway/health).
5. **Перегляд останнього журналу**
```bash
openclaw logs --follow
```
Якщо RPC недоступний, скористайтеся резервним варіантом:
```bash
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"
```
Файлові журнали відокремлені від журналів служби; див. [Журналювання](/uk/logging) і [Усунення несправностей](/uk/gateway/troubleshooting).
6. **Запустіть doctor (виправлення)**
```bash
openclaw doctor
```
Виправляє/мігрує конфігурацію/стан + запускає перевірки справності. Див. [Doctor](/uk/gateway/doctor).
7. **Знімок Gateway**
```bash
openclaw health --json
openclaw health --verbose # shows the target URL + config path on errors
```
Запитує у запущеного gateway повний знімок (лише WS). Див. [Справність](/uk/gateway/health).
## Швидкий старт і початкове налаштування
Питання й відповіді для першого запуску — встановлення, онбординг, маршрути автентифікації, підписки, початкові збої —
розміщені в [FAQ першого запуску](/uk/help/faq-first-run).
## Що таке OpenClaw?
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](/uk/gateway), [Канали](/uk/channels), [Мультиагентність](/uk/concepts/multi-agent),
[Пам'ять](/uk/concepts/memory).
Хороші перші проєкти:
- Створіть вебсайт (WordPress, Shopify або простий статичний сайт).
- Зробіть прототип мобільного застосунку (структура, екрани, план API).
- Упорядкуйте файли й папки (очищення, назви, теги).
- Підключіть Gmail і автоматизуйте підсумки або подальші дії.
Він може виконувати великі завдання, але працює найкраще, коли ви розбиваєте їх на етапи й
використовуєте субагентів для паралельної роботи.
Повсякденна користь зазвичай виглядає так:
- **Персональні брифінги:** підсумки вхідних повідомлень, календаря та новин, які вам важливі.
- **Дослідження й чернетки:** швидкі дослідження, підсумки та перші чернетки для листів або документів.
- **Нагадування та подальші дії:** підказки й чеклісти, керовані cron або heartbeat.
- **Автоматизація браузера:** заповнення форм, збирання даних і повторення вебзавдань.
- **Координація між пристроями:** надішліть завдання з телефона, дайте Gateway виконати його на сервері й отримайте результат назад у чаті.
Так, для **дослідження, кваліфікації та підготовки чернеток**. Він може сканувати сайти, створювати короткі списки,
підсумовувати потенційних клієнтів і писати чернетки outreach-повідомлень або рекламних текстів.
Для **outreach або рекламних запусків** тримайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і
політик платформ, а також переглядайте все перед надсиланням. Найбезпечніший шаблон — дати
OpenClaw підготувати чернетку, а вам затвердити її.
Документація: [Безпека](/uk/gateway/security).
OpenClaw — це **персональний асистент** і координаційний шар, а не заміна IDE. Використовуйте
Claude Code або Codex для найшвидшого прямого циклу програмування всередині репозиторію. Використовуйте OpenClaw, коли вам
потрібні стала пам'ять, доступ між пристроями й оркестрація інструментів.
Переваги:
- **Постійна пам'ять + робочий простір** між сеансами
- **Доступ із кількох платформ** (WhatsApp, Telegram, TUI, WebChat)
- **Оркестрація інструментів** (браузер, файли, планування, hooks)
- **Завжди ввімкнений Gateway** (запускайте на VPS, взаємодійте звідусіль)
- **Nodes** для локального браузера/екрана/камери/exec
Демонстрація: [https://openclaw.ai/showcase](https://openclaw.ai/showcase)
## Skills і автоматизація
Використовуйте керовані перевизначення замість редагування копії в репозиторії. Покладіть зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.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` (найнижчий пріоритет). Типовий пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`. `clawhub` за замовчуванням встановлює в `./skills`, що OpenClaw під час наступного сеансу трактує як `/skills`. Якщо skill має бути видимий лише певним агентам, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`.
Сьогодні підтримувані шаблони такі:
- **Cron-завдання**: ізольовані завдання можуть задавати перевизначення `model` для кожного завдання.
- **Субагенти**: маршрутизуйте завдання до окремих агентів із різними типовими моделями.
- **Перемикання на вимогу**: використовуйте `/model`, щоб будь-коли змінити модель поточного сеансу.
Див. [Cron-завдання](/uk/automation/cron-jobs), [Мультиагентна маршрутизація](/uk/concepts/multi-agent) і [Slash-команди](/uk/tools/slash-commands).
Використовуйте **субагентів** для довгих або паралельних завдань. Субагенти працюють у власному сеансі,
повертають підсумок і зберігають основний чат responsive.
Попросіть бота "spawn a sub-agent for this task" або використайте `/subagents`.
Використовуйте `/status` у чаті, щоб побачити, що Gateway робить зараз (і чи він зайнятий).
Порада щодо токенів: довгі завдання й субагенти споживають токени. Якщо вартість має значення, задайте
дешевшу модель для субагентів через `agents.defaults.subagents.model`.
Документація: [Субагенти](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks).
Використовуйте прив'язки thread. Ви можете прив'язати thread Discord до субагента або цільового сеансу, щоб подальші повідомлення в цьому thread залишалися в прив'язаному сеансі.
Базовий потік:
- Створіть через `sessions_spawn` з `thread: true` (і необов'язково `mode: "session"` для постійних подальших повідомлень).
- Або прив'яжіть вручну через `/focus `.
- Використовуйте `/agents`, щоб переглянути стан прив'язки.
- Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям 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.
Документація: [Субагенти](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник конфігурації](/uk/gateway/configuration-reference), [Slash-команди](/uk/tools/slash-commands).
Спершу перевірте визначений маршрут запитувача:
- Доставка субагента в режимі завершення надає перевагу будь-якому прив'язаному thread або маршруту розмови, якщо він існує.
- Якщо джерело завершення містить лише канал, OpenClaw використовує резервний маршрут, збережений у сеансі запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все ще могла спрацювати.
- Якщо немає ні прив'язаного маршруту, ні придатного збереженого маршруту, пряма доставка може не вдатися, і результат повертається до доставки через чергу сеансу замість негайної публікації в чат.
- Недійсні або застарілі цілі все ще можуть примусити резервну чергу або остаточний збій доставки.
- Якщо остання видима відповідь асистента в дочірньому сеансі — точний silent token `NO_REPLY` / `no_reply`, або точно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує оголошення замість публікації застарілого попереднього прогресу.
- Якщо дочірній сеанс перевищив час очікування лише після викликів інструментів, оголошення може згорнути це в короткий підсумок часткового прогресу замість повторного відтворення сирого виводу інструментів.
Налагодження:
```bash
openclaw tasks show
```
Документація: [Субагенти](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструменти сеансів](/uk/concepts/session-tool).
Cron працює всередині процесу Gateway. Якщо Gateway не працює безперервно,
заплановані завдання не виконуватимуться.
Чекліст:
- Переконайтеся, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не встановлено.
- Перевірте, що Gateway працює 24/7 (без сну/перезапусків).
- Перевірте налаштування часового поясу для завдання (`--tz` порівняно з часовим поясом хоста).
Налагодження:
```bash
openclaw cron run
openclaw cron runs --id --limit 50
```
Документація: [Cron-завдання](/uk/automation/cron-jobs), [Автоматизація](/uk/automation).
Спершу перевірте режим доставки:
- `--no-deliver` / `delivery.mode: "none"` означає, що резервне надсилання runner не очікується.
- Відсутня або недійсна ціль оголошення (`channel` / `to`) означає, що runner пропустив вихідну доставку.
- Помилки авторизації каналу (`unauthorized`, `Forbidden`) означають, що runner спробував доставити повідомлення, але облікові дані це заблокували.
- Тихий ізольований результат (лише `NO_REPLY` / `no_reply`) вважається навмисно непридатним для доставки, тому runner також пригнічує резервну доставку з черги.
Для ізольованих завдань cron агент усе ще може надсилати напряму за допомогою інструмента `message`,
коли доступний маршрут чату. `--announce` керує лише резервним шляхом runner
для фінального тексту, який агент ще не надіслав.
Налагодження:
```bash
openclaw cron runs --id --limit 50
openclaw tasks show
```
Документація: [Завдання Cron](/uk/automation/cron-jobs), [Фонові завдання](/uk/automation/tasks).
Зазвичай це шлях перемикання моделі в реальному часі, а не дубльоване планування.
Ізольований cron може зберегти передавання runtime-моделі та повторити спробу, коли активний
запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкнутого
провайдера/модель, а якщо перемикання містило нове перевизначення профілю авторизації, cron
також зберігає його перед повторною спробою.
Пов’язані правила вибору:
- Перевизначення моделі Gmail-хука має пріоритет, коли застосовне.
- Потім `model` для конкретного завдання.
- Потім будь-яке збережене перевизначення моделі cron-сесії.
- Потім звичайний вибір моделі агента/за замовчуванням.
Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторів перемикання
cron переривається замість нескінченного циклу.
Налагодження:
```bash
openclaw cron runs --id --limit 50
openclaw tasks show
```
Документація: [Завдання Cron](/uk/automation/cron-jobs), [CLI cron](/uk/cli/cron).
Використовуйте нативні команди `openclaw skills` або додайте Skills до свого робочого простору. Інтерфейс Skills для macOS недоступний у Linux.
Переглядайте Skills на [https://clawhub.ai](https://clawhub.ai).
```bash
openclaw skills search "calendar"
openclaw skills search --limit 20
openclaw skills install
openclaw skills install --version
openclaw skills install --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](/uk/automation/cron-jobs), [Автоматизація](/uk/automation),
[Heartbeat](/uk/gateway/heartbeat).
Не напряму. Skills для macOS обмежуються `metadata.openclaw.os` разом із потрібними бінарними файлами, і Skills з’являються в системному prompt лише тоді, коли вони придатні на **хості Gateway**. У Linux Skills лише для `darwin` (наприклад `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не перевизначите обмеження.
Є три підтримувані шаблони:
**Варіант A - запустіть Gateway на Mac (найпростіше).**
Запустіть Gateway там, де існують бінарні файли macOS, а потім підключіться з Linux у [віддаленому режимі](#gateway-ports-already-running-and-remote-mode) або через 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):
```bash
#!/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:
```markdown
---
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:
```bash
openclaw skills install
openclaw skills update --all
```
Нативні встановлення потрапляють у каталог `skills/` активного робочого простору. Для спільних Skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі агенти, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують бінарні файли, встановлені через Homebrew; у Linux це означає Linuxbrew (див. запис FAQ Homebrew Linux вище). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/clawhub).
Використовуйте вбудований профіль браузера `user`, який підключається через Chrome DevTools MCP:
```bash
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot
```
Якщо вам потрібна власна назва, створіть явний профіль MCP:
```bash
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, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого профілю CDP
## Пісочниця та пам’ять
Так. Див. [Пісочниця](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або образи пісочниці), див. [Docker](/uk/install/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](/uk/install/docker), [Браузер](/uk/tools/browser).
Так - якщо ваш приватний трафік це **DM**, а публічний трафік це **групи**.
Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб групові/канальні сесії (ключі не main) виконувалися в налаштованому бекенді пісочниці, тоді як основна DM-сесія залишалася на хості. Docker є стандартним бекендом, якщо ви не виберете інший. Потім обмежте, які інструменти доступні в сесіях пісочниці, через `tools.sandbox.tools`.
Покрокове налаштування + приклад конфігурації: [Групи: особисті DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent)
Довідка з ключової конфігурації: [Конфігурація Gateway](/uk/gateway/config-agents#agentsdefaultssandbox)
Встановіть `agents.defaults.sandbox.docker.binds` у `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки й прив’язки для окремого агента об’єднуються; прив’язки для окремого агента ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що прив’язки обходять файлові межі пісочниці.
OpenClaw перевіряє джерела прив’язок за нормалізованим шляхом і за канонічним шляхом, розв’язаним через найглибшого наявного предка. Це означає, що виходи через батьківський symlink усе одно закрито відхиляються, навіть коли останній сегмент шляху ще не існує, а перевірки дозволеного кореня все ще застосовуються після розв’язання symlink.
Див. [Пісочниця](/uk/gateway/sandboxing#custom-bind-mounts) і [Пісочниця проти політики інструментів проти підвищених прав](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) для прикладів і нотаток з безпеки.
Пам’ять OpenClaw - це просто Markdown-файли в робочому просторі агента:
- Щоденні нотатки в `memory/YYYY-MM-DD.md`
- Відібрані довгострокові нотатки в `MEMORY.md` (лише основні/приватні сесії)
OpenClaw також виконує **тихе скидання пам’яті перед Compaction**, щоб нагадати моделі
записати довговічні нотатки перед автоматичним Compaction. Це виконується лише коли робочий простір
доступний для запису (пісочниці лише для читання це пропускають). Див. [Пам’ять](/uk/concepts/memory).
Попросіть бота **записати факт у пам’ять**. Довгострокові нотатки належать до `MEMORY.md`,
короткостроковий контекст переходить у `memory/YYYY-MM-DD.md`.
Це все ще напрям, який ми вдосконалюємо. Допомагає нагадувати моделі зберігати спогади;
вона знатиме, що робити. Якщо вона продовжує забувати, перевірте, що Gateway використовує той самий
робочий простір у кожному запуску.
Документація: [Пам’ять](/uk/concepts/memory), [Робочий простір агента](/uk/concepts/agent-workspace).
Файли пам’яті живуть на диску й зберігаються, доки ви їх не видалите. Обмеженням є ваше
сховище, а не модель. **Контекст сесії** все одно обмежений контекстним вікном моделі,
тому довгі розмови можуть стискатися або обрізатися. Саме тому існує пошук у пам’яті - він повертає в контекст лише релевантні частини.
Документація: [Пам’ять](/uk/concepts/memory), [Контекст](/uk/concepts/context).
Лише якщо ви використовуєте **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** -
див. [Пам’ять](/uk/concepts/memory), щоб дізнатися деталі налаштування.
## Де речі розміщуються на диску
Ні - **стан OpenClaw є локальним**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**.
- **Локально за замовчуванням:** сеанси, файли пам’яті, конфігурація та робочий простір розміщуються на хості Gateway
(`~/.openclaw` + каталог вашого робочого простору).
- **Віддалено за необхідністю:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI/тощо), йдуть до
їхніх API, а чат-платформи (WhatsApp/Telegram/Slack/тощо) зберігають дані повідомлень на своїх
серверах.
- **Ви контролюєте обсяг сліду:** використання локальних моделей залишає промпти на вашому комп’ютері, але трафік каналів
усе одно проходить через сервери відповідного каналу.
Пов’язано: [Робочий простір агента](/uk/concepts/agent-workspace), [Пам’ять](/uk/concepts/memory).
Усе розміщується в `$OPENCLAW_STATE_DIR` (за замовчуванням: `~/.openclaw`):
| Шлях | Призначення |
| --------------------------------------------------------------- | ------------------------------------------------------------------ |
| `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) |
| `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Застарілий імпорт OAuth (копіюється в профілі автентифікації під час першого використання) |
| `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Профілі автентифікації (OAuth, API-ключі та необов’язкові `keyRef`/`tokenRef`) |
| `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове файлове таємне навантаження для провайдерів SecretRef `file` |
| `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл застарілої сумісності (статичні записи `api_key` очищено) |
| `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад, `whatsapp//creds.json`) |
| `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного агента (agentDir + сеанси) |
| `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) |
| `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сеансів (для кожного агента) |
Застарілий шлях для одного агента: `~/.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`; його можна налаштувати через:
```json5
{
agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}
```
Якщо бот «забуває» після перезапуску, переконайтеся, що Gateway використовує той самий
робочий простір під час кожного запуску (і пам’ятайте: віддалений режим використовує **робочий простір хоста gateway**,
а не вашого локального ноутбука).
Порада: якщо вам потрібна стійка поведінка або вподобання, попросіть бота **записати це в
AGENTS.md або MEMORY.md**, а не покладатися на історію чату.
Див. [Робочий простір агента](/uk/concepts/agent-workspace) і [Пам’ять](/uk/concepts/memory).
Розмістіть свій **робочий простір агента** в **приватному** git-репозиторії та створюйте його резервну копію десь
приватно (наприклад, GitHub private). Це збереже пам’ять + файли AGENTS/SOUL/USER
і дасть змогу пізніше відновити «розум» асистента.
**Не** комітьте нічого з `~/.openclaw` (облікові дані, сеанси, токени або зашифровані таємні навантаження).
Якщо вам потрібно повне відновлення, створіть резервні копії і робочого простору, і каталогу стану
окремо (див. запитання про міграцію вище).
Документація: [Робочий простір агента](/uk/concepts/agent-workspace).
Див. окремий посібник: [Видалення](/uk/install/uninstall).
Так. Робочий простір є **типовим cwd** і якорем пам’яті, а не жорсткою пісочницею.
Відносні шляхи розв’язуються всередині робочого простору, але абсолютні шляхи можуть отримувати доступ до інших
розташувань хоста, якщо не ввімкнено ізоляцію. Якщо вам потрібна ізоляція, використовуйте
[`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування пісочниці для окремого агента. Якщо ви
хочете, щоб репозиторій був типовим робочим каталогом, вкажіть для `workspace` цього агента
корінь репозиторію. Репозиторій OpenClaw - це лише вихідний код; тримайте
робочий простір окремо, якщо ви навмисно не хочете, щоб агент працював усередині нього.
Приклад (репозиторій як типовий cwd):
```json5
{
agents: {
defaults: {
workspace: "~/Projects/my-repo",
},
},
}
```
Стан сеансу належить **хосту gateway**. Якщо ви у віддаленому режимі, потрібне вам сховище сеансів розміщується на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування сеансами](/uk/concepts/session).
## Основи конфігурації
OpenClaw читає необов’язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (за замовчуванням: `~/.openclaw/openclaw.json`):
```
$OPENCLAW_CONFIG_PATH
```
Якщо файл відсутній, використовуються відносно безпечні типові значення (зокрема типовий робочий простір `~/.openclaw/workspace`).
Прив’язки не до loopback **потребують чинного шляху автентифікації gateway**. На практиці це означає:
- автентифікація спільним секретом: токен або пароль
- `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим реверс-проксі з урахуванням ідентичності
```json5
{
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` у конфігурації:
```json5
{
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`
```json5
{
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..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` (або із середовища служби).
Документація: [Вебінструменти](/uk/tools/web).
`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.*`, що нормалізуються до тих самих захищених шляхів виконання).
Документація: [Конфігурація](/uk/cli/config), [Налаштування](/uk/cli/configure), [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-rejected-invalid-config), [Doctor](/uk/gateway/doctor).
Типовий шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **вузли** й **агенти**:
- **Gateway (центральний):** керує каналами (Signal/WhatsApp), маршрутизацією та сеансами.
- **Вузли (пристрої):** Mac/iOS/Android підключаються як периферійні пристрої та надають локальні інструменти (`system.run`, `canvas`, `camera`).
- **Агенти (працівники):** окремі «мізки»/робочі простори для спеціальних ролей (наприклад, "Hetzner ops", "Personal data").
- **Субагенти:** запускають фонову роботу з основного агента, коли потрібен паралелізм.
- **TUI:** підключайтеся до Gateway і перемикайте агентів/сеанси.
Документація: [Вузли](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Багатоагентна маршрутизація](/uk/concepts/multi-agent), [Субагенти](/uk/tools/subagents), [TUI](/uk/web/tui).
Так. Це параметр конфігурації:
```json5
{
browser: { headless: true },
agents: {
defaults: {
sandbox: { browser: { headless: true } },
},
},
}
```
За замовчуванням значення `false` (з графічним інтерфейсом). Режим без графічного інтерфейсу частіше може спричиняти антибот-перевірки на деяких сайтах. Див. [Браузер](/uk/tools/browser).
Режим без графічного інтерфейсу використовує **той самий рушій Chromium** і працює для більшості автоматизації (форми, кліки, скрейпінг, входи). Основні відмінності:
- Немає видимого вікна браузера (використовуйте знімки екрана, якщо потрібна візуалізація).
- Деякі сайти суворіше ставляться до автоматизації в режимі без графічного інтерфейсу (CAPTCHA, антибот).
Наприклад, X/Twitter часто блокує такі сеанси.
Установіть `browser.executablePath` на двійковий файл Brave (або будь-який браузер на основі Chromium) і перезапустіть Gateway.
Повні приклади конфігурації див. у [Браузер](/uk/tools/browser#use-brave-or-another-chromium-based-browser).
## Віддалені 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:
```bash
openclaw devices list
openclaw devices approve
```
Окремий TCP-міст не потрібен; вузли підключаються через Gateway WebSocket.
Нагадування про безпеку: спарювання вузла macOS дозволяє `system.run` на цій машині. Спарюйте
лише пристрої, яким довіряєте, і перегляньте [Безпека](/uk/gateway/security).
Документація: [Вузли](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [Віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security).
Перевірте основне:
- Gateway працює: `openclaw gateway status`
- Стан Gateway: `openclaw status`
- Стан каналу: `openclaw channels status`
Потім перевірте автентифікацію та маршрутизацію:
- Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` налаштовано правильно.
- Якщо підключаєтеся через SSH-тунель, підтвердьте, що локальний тунель запущено й він вказує на правильний порт.
- Підтвердьте, що ваші списки дозволів (DM або група) містять ваш обліковий запис.
Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Канали](/uk/channels).
Так. Вбудованого мосту "бот-до-бота" немає, але ви можете налаштувати це кількома
надійними способами:
**Найпростіше:** використовуйте звичайний чат-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp).
Нехай бот A надішле повідомлення боту B, а потім бот B відповість як зазвичай.
**CLI-міст (загальний):** запустіть скрипт, який викликає інший Gateway через
`openclaw agent --message ... --deliver`, націлюючись на чат, де слухає інший бот.
Якщо один бот працює на віддаленому VPS, спрямуйте свій CLI на той віддалений Gateway
через SSH/Tailscale (див. [Віддалений доступ](/uk/gateway/remote)).
Приклад шаблону (запускайте з машини, яка може дістатися цільового Gateway):
```bash
openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to
```
Порада: додайте запобіжник, щоб два боти не зациклювалися нескінченно (лише згадування, списки дозволів
каналів або правило "не відповідати на повідомлення ботів").
Документація: [Віддалений доступ](/uk/gateway/remote), [CLI агента](/uk/cli/agent), [Надсилання агентом](/uk/tools/agent-send).
Ні. Один 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 підходить для разового доступу до оболонки, але вузли простіші для постійних робочих процесів агента та
автоматизації пристрою.
Документація: [Вузли](/uk/nodes), [CLI вузлів](/uk/cli/nodes), [Браузер](/uk/tools/browser).
Ні. На кожному хості має працювати лише **один gateway**, якщо ви навмисно не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Вузли — це периферійні пристрої, які підключаються
до gateway (вузли iOS/Android або "режим вузла" macOS у застосунку рядка меню). Для безголових хостів вузлів
і керування через CLI див. [CLI хоста вузла](/uk/cli/node).
Повний перезапуск потрібен для змін `gateway`, `discovery` і поверхні розміщеного Plugin.
Так.
- `config.schema.lookup`: перевіряє одне піддерево конфігурації з його поверхневим вузлом схеми, відповідною підказкою UI та короткими описами безпосередніх дочірніх елементів перед записом
- `config.get`: отримує поточний знімок + хеш
- `config.patch`: безпечне часткове оновлення (бажане для більшості редагувань RPC); виконує гаряче перезавантаження, коли це можливо, і перезапускає, коли потрібно
- `config.apply`: перевіряє + замінює всю конфігурацію; виконує гаряче перезавантаження, коли це можливо, і перезапускає, коли потрібно
- Runtime-інструмент `gateway`, доступний лише власнику, досі відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec
```json5
{
agents: { defaults: { workspace: "~/.openclaw/workspace" } },
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
```
Це задає ваш робочий простір і обмежує, хто може запускати бота.
Мінімальні кроки:
1. **Установіть + увійдіть на VPS**
```bash
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
```
2. **Установіть + увійдіть на своєму Mac**
- Використайте застосунок Tailscale і ввійдіть у ту саму tailnet.
3. **Увімкніть MagicDNS (рекомендовано)**
- У консолі адміністратора Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім'я.
4. **Використовуйте hostname tailnet**
- SSH: `ssh user@your-vps.tailnet-xxxx.ts.net`
- Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789`
Якщо вам потрібен Control UI без SSH, використайте Tailscale Serve на VPS:
```bash
openclaw gateway --tailscale serve
```
Це залишає gateway прив'язаним до loopback і відкриває HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale).
Serve відкриває **Gateway Control UI + WS**. Вузли підключаються через той самий endpoint Gateway WS.
Рекомендоване налаштування:
1. **Переконайтеся, що VPS + Mac перебувають в одній tailnet**.
2. **Використовуйте застосунок macOS у Remote mode** (ціль SSH може бути hostname tailnet).
Застосунок створить тунель до порту Gateway і підключиться як вузол.
3. **Схваліть вузол** на gateway:
```bash
openclaw devices list
openclaw devices approve
```
Документація: [протокол Gateway](/uk/gateway/protocol), [виявлення](/uk/gateway/discovery), [віддалений режим macOS](/uk/platforms/mac/remote).
Якщо вам потрібні лише **локальні інструменти** (screen/camera/exec) на другому ноутбуці, додайте його як
**вузол**. Це зберігає один Gateway і уникає дублювання конфігурації. Інструменти локального вузла
наразі доступні лише для macOS, але ми плануємо поширити їх на інші ОС.
Установлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти.
Документація: [вузли](/uk/nodes), [CLI вузлів](/uk/cli/nodes), [кілька gateway](/uk/gateway/multiple-gateways).
## Змінні середовища та завантаження .env
OpenClaw читає змінні середовища з батьківського процесу (shell, launchd/systemd, CI тощо) і додатково завантажує:
- `.env` з поточного робочого каталогу
- глобальний резервний `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`)
Жоден файл `.env` не перевизначає наявні змінні середовища.
Ви також можете визначити inline-змінні середовища в конфігурації (застосовуються лише якщо їх немає в process env):
```json5
{
env: {
OPENROUTER_API_KEY: "sk-or-...",
vars: { GROQ_API_KEY: "gsk-..." },
},
}
```
Див. [/environment](/uk/help/environment) для повного порядку пріоритетів і джерел.
Два поширені виправлення:
1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб їх було підхоплено навіть тоді, коли сервіс не успадковує ваше середовище shell.
2. Увімкніть імпорт із shell (зручність за явної згоди):
```json5
{
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 і перевірте знову:
```bash
openclaw models status
```
Tokens Copilot читаються з `COPILOT_GITHUB_TOKEN` (також `GH_TOKEN` / `GITHUB_TOKEN`).
Див. [/concepts/model-providers](/uk/concepts/model-providers) і [/environment](/uk/help/environment).
## Сесії та кілька чатів
Надішліть `/new` або `/reset` як окреме повідомлення. Див. [керування сесіями](/uk/concepts/session).
Сесії можуть завершуватися після `session.idleMinutes`, але це **вимкнено за замовчуванням** (типово **0**).
Установіть додатне значення, щоб увімкнути завершення через неактивність. Коли це увімкнено, **наступне**
повідомлення після періоду неактивності запускає новий ідентифікатор сесії для цього ключа чату.
Це не видаляє транскрипти - лише починає нову сесію.
```json5
{
session: {
idleMinutes: 240,
},
}
```
Так, через **маршрутизацію між кількома агентами** та **субагентів**. Ви можете створити одного координатора
agent і кількох робочих agents із власними робочими просторами та моделями.
Водночас це найкраще сприймати як **цікавий експеримент**. Він витрачає багато tokens і часто
менш ефективний, ніж використання одного бота з окремими сесіями. Типова модель, яку ми
уявляємо, - це один бот, з яким ви спілкуєтеся, і різні сесії для паралельної роботи. Цей
бот також може створювати субагентів за потреби.
Документація: [маршрутизація між кількома агентами](/uk/concepts/multi-agent), [субагенти](/uk/tools/subagents), [CLI агентів](/uk/cli/agents).
Контекст сесії обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато
файлів можуть спричинити Compaction або обрізання.
Що допомагає:
- Попросіть бота підсумувати поточний стан і записати його у файл.
- Використовуйте `/compact` перед довгими завданнями та `/new` під час зміни теми.
- Зберігайте важливий контекст у робочому просторі та просіть бота прочитати його назад.
- Використовуйте субагентів для довгої або паралельної роботи, щоб основний чат лишався меншим.
- Виберіть модель із більшим контекстним вікном, якщо це трапляється часто.
Використайте команду reset:
```bash
openclaw reset
```
Повне неінтерактивне скидання:
```bash
openclaw reset --scope full --yes --non-interactive
```
Потім повторно запустіть налаштування:
```bash
openclaw onboard --install-daemon
```
Примітки:
- Onboarding також пропонує **скидання**, якщо бачить наявну конфігурацію. Див. [Onboarding (CLI)](/uk/start/wizard).
- Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен каталог стану (типові значення: `~/.openclaw-`).
- Dev reset: `openclaw gateway --dev --reset` (лише для dev; стирає dev-конфігурацію + credentials + сесії + workspace).
Використайте один із цих варіантів:
- **Compact** (зберігає розмову, але підсумовує старіші ходи):
```
/compact
```
або `/compact `, щоб спрямувати підсумок.
- **Reset** (нова session ID для того самого ключа чату):
```
/new
/reset
```
Якщо це продовжує траплятися:
- Увімкніть або налаштуйте **обрізання сесії** (`agents.defaults.contextPruning`), щоб скоротити старий вивід інструментів.
- Використовуйте модель із більшим контекстним вікном.
Документація: [Compaction](/uk/concepts/compaction), [обрізання сесії](/uk/concepts/session-pruning), [керування сесіями](/uk/concepts/session).
Це помилка перевірки provider: модель видала блок `tool_use` без обов'язкового
`input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих тредів
або зміни tool/schema).
Виправлення: почніть нову сесію через `/new` (окреме повідомлення).
Heartbeats за замовчуванням запускаються кожні **30m** (**1h** під час використання OAuth auth). Налаштуйте або вимкніть їх:
```json5
{
agents: {
defaults: {
heartbeat: {
every: "2h", // or "0m" to disable
},
},
},
}
```
Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown
заголовки на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити API-виклики.
Якщо файл відсутній, heartbeat усе одно запускається, і модель вирішує, що робити.
Перевизначення для окремих agent використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat).
Ні. OpenClaw працює у **вашому власному акаунті**, тож якщо ви в групі, OpenClaw може її бачити.
За замовчуванням відповіді в групах заблоковані, доки ви не дозволите відправників (`groupPolicy: "allowlist"`).
Якщо ви хочете, щоб лише **ви** могли запускати відповіді в групі:
```json5
{
channels: {
whatsapp: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
},
},
}
```
Варіант 1 (найшвидший): стежте за логами й надішліть тестове повідомлення в групу:
```bash
openclaw logs --follow --json
```
Шукайте `chatId` (або `from`), що закінчується на `@g.us`, наприклад:
`1234567890-1234567890@g.us`.
Варіант 2 (якщо вже налаштовано/allowlisted): виведіть список груп із конфігурації:
```bash
openclaw directory groups list --channel whatsapp
```
Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/uk/cli/directory), [Logs](/uk/cli/logs).
Дві поширені причини:
- Увімкнено mention gating (типово). Ви маєте @mention бота (або збігтися з `mentionPatterns`).
- Ви налаштували `channels.whatsapp.groups` без `"*"`, і група не внесена до allowlist.
Див. [групи](/uk/channels/groups) і [групові повідомлення](/uk/channels/group-messages).
Прямі чати за замовчуванням згортаються до основної сесії. Групи/канали мають власні ключі сесій, а теми Telegram / треди Discord є окремими сесіями. Див. [групи](/uk/channels/groups) і [групові повідомлення](/uk/channels/group-messages).
Жорстких обмежень немає. Десятки (навіть сотні) — нормально, але стежте за:
- **Зростанням диска:** сеанси + транскрипти зберігаються в `~/.openclaw/agents//sessions/`.
- **Вартістю токенів:** більше агентів означає більше одночасного використання моделі.
- **Операційними накладними витратами:** профілі автентифікації, робочі простори та маршрутизація каналів для кожного агента.
Поради:
- Тримайте один **активний** робочий простір на агента (`agents.defaults.workspace`).
- Очищайте старі сеанси (видаляйте JSONL або записи сховища), якщо диск зростає.
- Використовуйте `openclaw doctor`, щоб знайти зайві робочі простори й невідповідності профілів.
Так. Використовуйте **маршрутизацію кількох агентів**, щоб запускати кілька ізольованих агентів і маршрутизувати вхідні повідомлення за
каналом/обліковим записом/співрозмовником. Slack підтримується як канал і може бути прив'язаний до конкретних агентів.
Доступ через браузер потужний, але це не "може робити все, що може людина" — антибот-захист, CAPTCHA та MFA все ще можуть
блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості
або CDP на машині, яка фактично запускає браузер.
Рекомендоване налаштування:
- Постійно ввімкнений хост Gateway (VPS/Mac mini).
- Один агент на роль (прив'язки).
- Канал(и) Slack, прив'язані до цих агентів.
- Локальний браузер через Chrome MCP або вузол за потреби.
Документація: [маршрутизація кількох агентів](/uk/concepts/multi-agent), [Slack](/uk/channels/slack),
[браузер](/uk/tools/browser), [вузли](/uk/nodes).
## Моделі, резервне перемикання та профілі автентифікації
Запитання й відповіді про моделі — типові параметри, вибір, псевдоніми, перемикання, резервне перемикання, профілі автентифікації —
розміщені в [FAQ щодо моделей](/uk/help/faq-models).
## Gateway: порти, "уже запущено" та віддалений режим
`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`).
Виправлення:
```bash
openclaw gateway install --force
```
Запускайте це з того самого `--profile` / середовища, яке має використовувати служба.
OpenClaw забезпечує блокування середовища виконання, негайно прив'язуючи слухач WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо прив'язування завершується помилкою `EADDRINUSE`, виникає `GatewayLockError`, що вказує, що інший екземпляр уже слухає.
Виправлення: зупиніть інший екземпляр, звільніть порт або запустіть з `openclaw gateway --port `.
Установіть `gateway.mode: "remote"` і вкажіть віддалений URL WebSocket, за потреби зі спільними секретними віддаленими обліковими даними:
```json5
{
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 --role operator`
- Якщо цей виклик rotate каже, що його відхилено, перевірте дві речі:
- сеанси спарених пристроїв можуть повертати лише **власний** пристрій, якщо вони також не мають `operator.admin`
- явні значення `--scope` не можуть перевищувати поточні операторські області доступу викликача
- Все ще застрягли? Запустіть `openclaw status --all` і дотримуйтеся [усунення несправностей](/uk/gateway/troubleshooting). Див. [панель керування](/uk/web/dashboard) для деталей автентифікації.
Прив'язка `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 ...` для кожного екземпляра (автоматично створює `~/.openclaw-`).
- Установіть унікальний `gateway.port` у конфігурації кожного профілю (або передайте `--port` для ручних запусків).
- Установіть службу для кожного профілю: `openclaw --profile gateway install`.
Профілі також додають суфікси до назв служб (`ai.openclaw.`; застарілі `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`).
Повний посібник: [кілька gateway](/uk/gateway/multiple-gateways).
Gateway — це **сервер WebSocket**, і він очікує, що найперше повідомлення
буде фреймом `connect`. Якщо він отримує щось інше, він закриває з'єднання
з **кодом 1008** (порушення політики).
Поширені причини:
- Ви відкрили **HTTP** URL у браузері (`http://...`) замість WS-клієнта.
- Ви використали неправильний порт або шлях.
- Проксі або тунель видалив заголовки автентифікації чи надіслав не-Gateway запит.
Швидкі виправлення:
1. Використовуйте WS URL: `ws://:18789` (або `wss://...`, якщо HTTPS).
2. Не відкривайте WS-порт у звичайній вкладці браузера.
3. Якщо автентифікацію ввімкнено, додайте токен/пароль у фрейм `connect`.
Якщо ви використовуєте CLI або TUI, URL має виглядати так:
```
openclaw tui --url ws://:18789 --token
```
Деталі протоколу: [протокол Gateway](/uk/gateway/protocol).
## Журналювання та налагодження
Файлові журнали (структуровані):
```
/tmp/openclaw/openclaw-YYYY-MM-DD.log
```
Ви можете встановити стабільний шлях через `logging.file`. Рівень файлового журналу керується `logging.level`. Докладність консолі керується `--verbose` і `logging.consoleLevel`.
Найшвидший перегляд журналу:
```bash
openclaw logs --follow
```
Журнали служби/супервізора (коли gateway працює через launchd/systemd):
- macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` і `gateway.err.log` (типово: `~/.openclaw/logs/...`; профілі використовують `~/.openclaw-/logs/...`)
- Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager`
- Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST`
Див. [усунення несправностей](/uk/gateway/troubleshooting) для подробиць.
Використовуйте допоміжні команди gateway:
```bash
openclaw gateway status
openclaw gateway restart
```
Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може повернути порт. Див. [Gateway](/uk/gateway).
Є **два режими встановлення Windows**:
**1) WSL2 (рекомендовано):** Gateway працює всередині Linux.
Відкрийте PowerShell, увійдіть у WSL, потім перезапустіть:
```powershell
wsl
openclaw gateway status
openclaw gateway restart
```
Якщо ви ніколи не встановлювали службу, запустіть її на передньому плані:
```bash
openclaw gateway run
```
**2) Нативний Windows (не рекомендовано):** Gateway працює безпосередньо у Windows.
Відкрийте PowerShell і запустіть:
```powershell
openclaw gateway status
openclaw gateway restart
```
Якщо ви запускаєте його вручну (без служби), використовуйте:
```powershell
openclaw gateway run
```
Документація: [Windows (WSL2)](/uk/platforms/windows), [ранбук служби Gateway](/uk/gateway).
Почніть зі швидкої перевірки стану:
```bash
openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow
```
Поширені причини:
- Автентифікацію моделі не завантажено на **хості Gateway** (перевірте `models status`).
- Сполучення каналу/allowlist блокує відповіді (перевірте конфігурацію каналу та журнали).
- WebChat/Dashboard відкрито без правильного токена.
Якщо ви працюєте віддалено, підтвердьте, що тунель/з’єднання Tailscale активне і що
WebSocket Gateway доступний.
Документація: [Канали](/uk/channels), [Усунення несправностей](/uk/gateway/troubleshooting), [Віддалений доступ](/uk/gateway/remote).
Зазвичай це означає, що UI втратив WebSocket-з’єднання. Перевірте:
1. Чи запущено Gateway? `openclaw gateway status`
2. Чи справний Gateway? `openclaw status`
3. Чи має UI правильний токен? `openclaw dashboard`
4. Якщо віддалено, чи активне з’єднання тунелю/Tailscale?
Потім перегляньте журнали:
```bash
openclaw logs --follow
```
Документація: [Dashboard](/uk/web/dashboard), [Віддалений доступ](/uk/gateway/remote), [Усунення несправностей](/uk/gateway/troubleshooting).
Почніть із журналів і статусу каналу:
```bash
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](/uk/channels/telegram), [Усунення несправностей каналів](/uk/channels/troubleshooting).
Спочатку підтвердьте, що Gateway доступний і агент може запускатися:
```bash
openclaw status
openclaw models status
openclaw logs --follow
```
У TUI використайте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в чат-каналі,
переконайтеся, що доставку ввімкнено (`/deliver on`).
Документація: [TUI](/uk/web/tui), [Slash-команди](/uk/tools/slash-commands).
Якщо ви встановили службу:
```bash
openclaw gateway stop
openclaw gateway start
```
Це зупиняє/запускає **службу під наглядом** (launchd у macOS, systemd у Linux).
Використовуйте це, коли Gateway працює у фоновому режимі як daemon.
Якщо ви запускаєте у передньому плані, зупиніть за допомогою Ctrl-C, потім:
```bash
openclaw gateway run
```
Документація: [Runbook служби Gateway](/uk/gateway).
- `openclaw gateway restart`: перезапускає **фонову службу** (launchd/systemd).
- `openclaw gateway`: запускає gateway **у передньому плані** для цього термінального сеансу.
Якщо ви встановили службу, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли
потрібен одноразовий запуск у передньому плані.
Запустіть Gateway з `--verbose`, щоб отримати більше деталей у консолі. Потім перевірте файл журналу на помилки автентифікації каналу, маршрутизації моделі та RPC.
## Медіа та вкладення
Вихідні вкладення від агента мають містити рядок `MEDIA:` (окремим рядком). Див. [Налаштування помічника OpenClaw](/uk/start/openclaw) і [Надсилання агентом](/uk/tools/agent-send).
Надсилання через CLI:
```bash
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). Звичайний текст і файли, схожі на секрети, усе одно блокуються.
Див. [Зображення](/uk/nodes/images).
## Безпека та контроль доступу
Розглядайте вхідні DM як недовірений ввід. Типові налаштування розроблені для зменшення ризику:
- Типова поведінка в каналах із підтримкою DM — **сполучення**:
- Невідомі відправники отримують код сполучення; бот не обробляє їхнє повідомлення.
- Схвалити через: `openclaw pairing approve --channel [--account ] `
- Запити в очікуванні обмежені **3 на канал**; перевірте `openclaw pairing list --channel [--account ]`, якщо код не надійшов.
- Публічне відкриття DM потребує явного ввімкнення (`dmPolicy: "open"` і allowlist `"*"`).
Запустіть `openclaw doctor`, щоб виявити ризикові політики DM.
Ні. Prompt injection стосується **недовіреного вмісту**, а не лише того, хто може писати боту в DM.
Якщо ваш помічник читає зовнішній вміст (вебпошук/отримання, сторінки браузера, електронні листи,
документи, вкладення, вставлені журнали), цей вміст може містити інструкції, які намагаються
перехопити керування моделлю. Це може статися навіть якщо **ви єдиний відправник**.
Найбільший ризик виникає, коли інструменти ввімкнено: модель можна обманом змусити
ексфільтрувати контекст або викликати інструменти від вашого імені. Зменште зону ураження так:
- використовуйте read-only або з вимкненими інструментами агента-"читача" для підсумовування недовіреного вмісту
- тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів із увімкненими інструментами
- також вважайте декодований текст файлів/документів недовіреним: OpenResponses
`input_file` і витягнення медіавкладень обгортають витягнутий текст у
явні маркери межі зовнішнього вмісту замість передавання сирого тексту файлу
- використовуйте sandbox і суворі allowlist для інструментів
Деталі: [Безпека](/uk/gateway/security).
Так, для більшості налаштувань. Ізоляція бота окремими акаунтами та номерами телефонів
зменшує зону ураження, якщо щось піде не так. Це також полегшує ротацію
облікових даних або відкликання доступу без впливу на ваші особисті акаунти.
Почніть з малого. Надавайте доступ лише до інструментів і акаунтів, які справді потрібні, і розширюйте
пізніше за потреби.
Документація: [Безпека](/uk/gateway/security), [Сполучення](/uk/channels/pairing).
Ми **не** рекомендуємо повну автономію над вашими особистими повідомленнями. Найбезпечніший шаблон:
- Тримайте DM у **режимі сполучення** або в суворому allowlist.
- Використовуйте **окремий номер або акаунт**, якщо хочете, щоб він надсилав повідомлення від вашого імені.
- Дозвольте йому підготувати чернетку, а потім **схвалюйте перед надсиланням**.
Якщо хочете експериментувати, робіть це на виділеному акаунті й тримайте його ізольованим. Див.
[Безпека](/uk/gateway/security).
Так, **якщо** агент лише для чату, а ввід є довіреним. Менші рівні
більш вразливі до перехоплення інструкцій, тому уникайте їх для агентів із увімкненими інструментами
або під час читання недовіреного вмісту. Якщо ви мусите використовувати меншу модель, жорстко обмежте
інструменти й запускайте всередині sandbox. Див. [Безпека](/uk/gateway/security).
Коди сполучення надсилаються **лише** коли невідомий відправник пише боту і
`dmPolicy: "pairing"` увімкнено. `/start` сам по собі не генерує код.
Перевірте запити в очікуванні:
```bash
openclaw pairing list telegram
```
Якщо потрібен негайний доступ, додайте свій sender id до allowlist або встановіть `dmPolicy: "open"`
для цього акаунта.
Ні. Типова політика WhatsApp DM — **сполучення**. Невідомі відправники лише отримують код сполучення, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише в чатах, які отримує, або на явні надсилання, які ви запускаєте.
Схваліть сполучення через:
```bash
openclaw pairing approve whatsapp
```
Перелічіть запити в очікуванні:
```bash
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](/uk/tools/thinking), [Безпека](/uk/gateway/security/index#reasoning-and-verbose-output-in-groups).
Надішліть будь-яке з цього **як окреме повідомлення** (без 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-команди](/uk/tools/slash-commands).
Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`, але кілька скорочень (наприклад `/status`) також працюють inline для відправників із allowlist.
OpenClaw типово блокує обмін повідомленнями **між провайдерами**. Якщо виклик інструмента прив’язаний
до Telegram, він не надішле в Discord, якщо ви явно цього не дозволите.
Увімкніть обмін повідомленнями між провайдерами для агента:
```json5
{
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`. Див. [чергу команд](/uk/concepts/queue) і [чергу керування](/uk/concepts/queue-steering).
## Різне
В OpenClaw облікові дані та вибір моделі відокремлені. Налаштування `ANTHROPIC_API_KEY` (або збереження API-ключа Anthropic у профілях автентифікації) вмикає автентифікацію, але фактична модель за замовчуванням — це та, яку ви налаштуєте в `agents.defaults.model.primary` (наприклад, `anthropic/claude-sonnet-4-6` або `anthropic/claude-opus-4-6`). Якщо ви бачите `No credentials found for profile "anthropic:default"`, це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному `auth-profiles.json` для агента, який виконується.
---
Досі застрягли? Запитайте в [Discord](https://discord.com/invite/clawd) або відкрийте [обговорення GitHub](https://github.com/openclaw/openclaw/discussions).
## Пов’язане
- [FAQ першого запуску](/uk/help/faq-first-run) — встановлення, початкове налаштування, автентифікація, підписки, ранні збої
- [FAQ щодо моделей](/uk/help/faq-models) — вибір моделі, аварійне перемикання, профілі автентифікації
- [Усунення несправностей](/uk/help/troubleshooting) — діагностика насамперед за симптомами