---
read_when:
- Відповіді на поширені запитання щодо налаштування, встановлення, початкового налаштування або підтримки під час виконання
- Первинне опрацювання проблем, про які повідомили користувачі, перед глибшим налагодженням
summary: Поширені запитання про налаштування, конфігурацію та використання OpenClaw
title: Поширені запитання
x-i18n:
generated_at: "2026-07-03T17:41:42Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: 4d55385d187c20dfce05022b76fcaa054c19fc22e46da66d4a24e2538dd95708
source_path: help/faq.md
workflow: 16
---
Швидкі відповіді та глибше усунення несправностей для реальних конфігурацій (локальна розробка, VPS, багато агентів, OAuth/API-ключі, перемикання моделей після збою). Для діагностики runtime див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник конфігурації див. у [Конфігурація](/uk/gateway/configuration).
## Перші 60 секунд, якщо щось зламалося
1. **Швидкий стан (перша перевірка)**
```bash
openclaw status
```
Швидке локальне зведення: ОС + оновлення, доступність gateway/сервісу, агенти/сеанси, конфігурація провайдера + проблеми runtime (коли gateway доступний).
2. **Звіт для вставлення (безпечно ділитися)**
```bash
openclaw status --all
```
Діагностика лише для читання з хвостом журналу (токени редагуються).
3. **Стан демона + порту**
```bash
openclaw gateway status
```
Показує runtime супервізора порівняно з доступністю RPC, цільову URL-адресу проби та яку конфігурацію сервіс, імовірно, використав.
4. **Глибокі проби**
```bash
openclaw status --deep
```
Запускає живу health-пробу 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
```
Виправляє/мігрує конфігурацію/стан + запускає health-перевірки. Див. [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).
## Швидкий старт і налаштування першого запуску
Питання й відповіді щодо першого запуску — встановлення, onboarding, маршрути авторизації, підписки, початкові збої —
розміщені в [FAQ першого запуску](/uk/help/faq-first-run).
## Що таке OpenClaw?
OpenClaw — це персональний AI-асистент, який ви запускаєте на власних пристроях. Він відповідає в середовищах обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і вбудовані Plugin каналів, як-от QQ Bot), а також може працювати з голосом + живим Canvas на підтримуваних платформах. **Gateway** — це постійно ввімкнена площина керування; асистент — це продукт.
OpenClaw — це не «просто обгортка Claude». Це **локально-орієнтована площина керування**, яка дає змогу запускати
здібного асистента на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, зі
станом сеансів, пам’яттю та інструментами — без передавання контролю над вашими робочими процесами хостинговому
SaaS.
Основне:
- **Ваші пристрої, ваші дані:** запускайте Gateway там, де хочете (Mac, Linux, VPS), і зберігайте
workspace + історію сеансів локально.
- **Справжні канали, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/тощо,
плюс мобільний голос і Canvas на підтримуваних платформах.
- **Незалежність від моделей:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією
і failover для кожного агента.
- **Опція лише локально:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо ви цього хочете.
- **Маршрутизація багатьох агентів:** окремі агенти для кожного каналу, облікового запису або завдання, кожен зі своїм
workspace і типовими налаштуваннями.
- **Відкритий код і можливість змінювати:** переглядайте, розширюйте та самостійно хостіть без прив’язки до постачальника.
Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Багато агентів](/uk/concepts/multi-agent),
[Пам’ять](/uk/concepts/memory).
Добрі перші проєкти:
- Створити вебсайт (WordPress, Shopify або простий статичний сайт).
- Прототипувати мобільний застосунок (структура, екрани, план API).
- Організувати файли й папки (очищення, іменування, тегування).
- Під’єднати Gmail і автоматизувати зведення або подальші дії.
Він може виконувати великі завдання, але найкраще працює, коли ви ділите їх на фази та
використовуєте субагентів для паралельної роботи.
Повсякденні виграші зазвичай виглядають так:
- **Персональні брифінги:** зведення inbox, календаря та новин, які вас цікавлять.
- **Дослідження й чернетки:** швидкі дослідження, зведення та перші чернетки для електронних листів або документів.
- **Нагадування та подальші дії:** підказки й контрольні списки, керовані Cron або Heartbeat.
- **Автоматизація браузера:** заповнення форм, збирання даних і повторення вебзавдань.
- **Координація між пристроями:** надішліть завдання з телефона, дозвольте Gateway виконати його на сервері й отримайте результат назад у чаті.
Так, для **дослідження, кваліфікації та підготовки чернеток**. Він може сканувати сайти, формувати короткі списки,
підсумовувати потенційних клієнтів і писати чернетки outreach або рекламних текстів.
Для **outreach або запусків реклами** залишайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і
політик платформ, а також перевіряйте все перед надсиланням. Найбезпечніший шаблон — дозволити
OpenClaw підготувати чернетку, а вам її затвердити.
Документація: [Безпека](/uk/gateway/security).
OpenClaw — це **персональний асистент** і координаційний шар, а не заміна IDE. Використовуйте
Claude Code або Codex для найшвидшого прямого циклу програмування всередині репозиторію. Використовуйте OpenClaw, коли вам
потрібні тривала пам’ять, доступ із різних пристроїв і оркестрація інструментів.
Переваги:
- **Постійна пам’ять + workspace** між сеансами
- **Доступ із багатьох платформ** (WhatsApp, Telegram, TUI, WebChat)
- **Оркестрація інструментів** (браузер, файли, планування, hooks)
- **Постійно ввімкнений Gateway** (запускайте на VPS, взаємодійте звідусіль)
- **Вузли** для локального браузера/екрана/камери/exec
Showcase: [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` для кожного завдання.
- **Агенти**: маршрутизуйте завдання до окремих агентів із різними типовими моделями, рівнями мислення та параметрами stream.
- **Перемикання на вимогу**: використовуйте `/model`, щоб будь-коли змінити модель поточного сеансу.
Наприклад, використовуйте ту саму модель із різними налаштуваннями для кожного агента:
```json5
{
agents: {
list: [
{
id: "coder",
model: "xiaomi/mimo-v2.5-pro",
thinkingDefault: "high",
params: { temperature: 0.1 },
},
{
id: "chat",
model: "xiaomi/mimo-v2.5-pro",
thinkingDefault: "off",
params: { temperature: 0.8 },
},
],
},
}
```
Розмістіть спільні типові налаштування для кожної моделі в `agents.defaults.models["provider/model"].params`, а специфічні для агента перевизначення — у пласкому `agents.list[].params`. Не визначайте окремі вкладені записи `agents.list[].models["provider/model"].params` для тієї самої моделі; `agents.list[].models` призначено для каталогу моделей і runtime-перевизначень на рівні агента.
Див. [Cron-завдання](/uk/automation/cron-jobs), [Маршрутизація багатьох агентів](/uk/concepts/multi-agent), [Конфігурація](/uk/gateway/config-agents) і [Slash-команди](/uk/tools/slash-commands).
Використовуйте **субагентів** для довгих або паралельних завдань. Субагенти запускаються у власному сеансі,
повертають зведення та залишають основний чат чуйним.
Попросіть бота «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"` для постійного follow-up).
- Або вручну прив’яжіть через `/focus `.
- Використовуйте `/agents`, щоб переглянути стан прив’язки.
- Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокуса.
- Використовуйте `/unfocus`, щоб від’єднати thread.
Обов’язкова конфігурація:
- Глобальні типові значення: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
- Перевизначення Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`.
- Автоматична прив’язка під час spawn: `channels.discord.threadBindings.spawnSessions` типово дорівнює `true`; встановіть `false`, щоб вимкнути spawn прив’язаних до thread сеансів.
Документація: [Субагенти](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник конфігурації](/uk/gateway/configuration-reference), [Slash-команди](/uk/tools/slash-commands).
Спочатку перевірте розв’язаний маршрут requester:
- Доставка субагента в режимі completion віддає перевагу будь-якому прив’язаному thread або маршруту розмови, коли він існує.
- Якщо джерело completion містить лише канал, OpenClaw повертається до збереженого маршруту сеансу requester (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все ще могла спрацювати.
- Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може завершитися невдало, і результат натомість повернеться до чергової доставки сеансу, а не буде негайно опублікований у чаті.
- Недійсні або застарілі цілі все ще можуть примусити fallback до черги або остаточний збій доставки.
- Якщо остання видима відповідь асистента дочірнього сеансу є точним silent token `NO_REPLY` / `no_reply` або точно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує announce замість публікації застарілого попереднього прогресу.
- Вивід tool/toolResult не підвищується до тексту результату дочірнього сеансу; результатом є остання видима відповідь асистента дочірнього сеансу.
Налагодження:
```bash
openclaw tasks show
```
Документація: [Підагенти](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструменти сеансу](/uk/concepts/session-tool).
Cron виконується всередині процесу Gateway. Якщо Gateway не працює безперервно,
заплановані завдання не виконуватимуться.
Контрольний список:
- Переконайтеся, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не задано.
- Перевірте, що Gateway працює цілодобово (без сну/перезапусків).
- Перевірте налаштування часового поясу для завдання (`--tz` порівняно з часовим поясом хоста).
Налагодження:
```bash
openclaw cron run
openclaw cron runs --id --limit 50
```
Документація: [Завдання Cron](/uk/automation/cron-jobs), [Автоматизація](/uk/automation).
Спочатку перевірте режим доставки:
- `--no-deliver` / `delivery.mode: "none"` означає, що резервне надсилання раннером не очікується.
- Відсутня або недійсна ціль оголошення (`channel` / `to`) означає, що раннер пропустив вихідну доставку.
- Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що раннер спробував доставити повідомлення, але облікові дані це заблокували.
- Тихий ізольований результат (лише `NO_REPLY` / `no_reply`) вважається навмисно недоставним, тому раннер також пригнічує резервну доставку з черги.
Для ізольованих завдань Cron агент усе одно може надсилати напряму за допомогою інструмента `message`,
коли доступний маршрут чату. `--announce` керує лише резервним шляхом раннера
для фінального тексту, який агент ще не надіслав.
Налагодження:
```bash
openclaw cron runs --id --limit 50
openclaw tasks show
```
Документація: [Завдання Cron](/uk/automation/cron-jobs), [Фонові завдання](/uk/automation/tasks).
Зазвичай це шлях перемикання live-моделі, а не дублювання планування.
Ізольований 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 @owner/
openclaw skills install @owner/ --version
openclaw skills install @owner/ --force
openclaw skills install @owner/ --global
openclaw skills update --all
openclaw skills update --all --global
openclaw skills list --eligible
openclaw skills check
```
Нативна команда `openclaw skills install` за замовчуванням записує в каталог `skills/`
активної робочої області. Додайте `--global`, щоб установити в спільний керований
каталог Skills для всіх локальних агентів. Установлюйте окремий CLI `clawhub`
лише якщо хочете публікувати або синхронізувати власні Skills. Використовуйте
`agents.defaults.skills` або `agents.list[].skills`, якщо хочете обмежити,
які агенти можуть бачити спільні Skills.
Так. Використовуйте планувальник Gateway:
- **Завдання Cron** для запланованих або повторюваних завдань (зберігаються після перезапусків).
- **Heartbeat** для періодичних перевірок "основного сеансу".
- **Ізольовані завдання** для автономних агентів, які публікують підсумки або доставляють повідомлення в чати.
Документація: [Завдання Cron](/uk/automation/cron-jobs), [Автоматизація](/uk/automation),
[Heartbeat](/uk/gateway/heartbeat).
Не напряму. Skills для macOS обмежуються `metadata.openclaw.os` плюс потрібними бінарними файлами, і Skills з’являються в системному промпті лише тоді, коли вони придатні на **хості 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`. Якщо ви виберете "Завжди запитувати", схвалення "Завжди дозволяти" в запиті додає цю команду до списку дозволених.
**Варіант 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 @owner/
openclaw skills update --all
```
Нативні встановлення потрапляють у каталог `skills/` активної робочої області. Для спільних Skills для всіх локальних агентів використовуйте `openclaw skills install @owner/ --global` (або вручну помістіть їх у `~/.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, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або raw CDP-профілю
## Ізоляція та пам’ять
Так. Див. [Ізоляція](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний Gateway у Docker або образи ізоляції), див. [Docker](/uk/install/docker).
Стандартний образ орієнтований передусім на безпеку й запускається як користувач `node`, тому він не
містить системних пакетів, Homebrew або вбудованих браузерів. Для повнішого налаштування:
- Зберігайте `/home/node` з `OPENCLAW_HOME_VOLUME`, щоб кеші не втрачалися.
- Додайте системні залежності в образ за допомогою `OPENCLAW_IMAGE_APT_PACKAGES`.
- Установіть браузери Playwright через вбудований CLI:
`node /app/node_modules/playwright-core/cli.js install chromium`
- Задайте `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що шлях зберігається.
Документація: [Docker](/uk/install/docker), [Браузер](/uk/tools/browser).
Так - якщо ваш приватний трафік це **особисті повідомлення**, а публічний трафік це **групи**.
Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб групові/канальні сеанси (ключі не-main) виконувалися в налаштованому бекенді ізоляції, тоді як основний сеанс особистих повідомлень залишався на хості. Docker є стандартним бекендом, якщо ви не виберете інший. Потім обмежте, які інструменти доступні в ізольованих сеансах, через `tools.sandbox.tools`.
Покрокове налаштування + приклад конфігурації: [Групи: особисті повідомлення + публічні групи](/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"`). Глобальні та агентські bind-монтування об’єднуються; агентські bind-монтування ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що bind-монтування обходять файлові стіни ізоляції.
OpenClaw перевіряє джерела bind-монтувань і за нормалізованим шляхом, і за канонічним шляхом, розв’язаним через найглибшого наявного предка. Це означає, що виходи через батьківські symlink усе одно fail closed, навіть коли останній сегмент шляху ще не існує, а перевірки дозволеного кореня все ще застосовуються після розв’язання 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**. Codex OAuth покриває чат/завершення й
**не** надає доступ до ембеддингів, тому **вхід через Codex (OAuth або
вхід через Codex CLI)** не допоможе для семантичного пошуку в пам’яті. Ембеддингам OpenAI
усе одно потрібен справжній API-ключ (`OPENAI_API_KEY` або `models.providers.openai.apiKey`).
Якщо ви явно не задаєте постачальника, OpenClaw використовує ембеддинги OpenAI. Застарілі
конфіги, у яких досі вказано `memorySearch.provider = "auto"`, також резолвляться в OpenAI.
Якщо ключ OpenAI API недоступний, семантичний пошук у пам’яті залишається недоступним,
доки ви не налаштуєте ключ або явно не виберете іншого постачальника.
Якщо ви хочете залишатися локально, задайте `memorySearch.provider = "local"` (і, за бажанням,
`memorySearch.fallback = "none"`). Якщо вам потрібні ембеддинги Gemini, задайте
`memorySearch.provider = "gemini"` і надайте `GEMINI_API_KEY` (або
`memorySearch.remote.apiKey`). Ми підтримуємо моделі ембеддингів **OpenAI, сумісні з OpenAI, Gemini,
Voyage, Mistral, Bedrock, Ollama, LM Studio, GitHub Copilot, DeepInfra або локальні** -
подробиці налаштування див. у [Пам’ять](/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).
Так. `SOUL.md` - це один із початкових файлів робочого простору, що ін’єктується в
контекст агента. Ліміт ін’єкції за замовчуванням для одного файла становить `20000` символів,
а загальний початковий бюджет для всіх файлів - `60000` символів.
Змініть спільні значення за замовчуванням у вашому конфігу OpenClaw:
```json5
{
agents: {
defaults: {
bootstrapMaxChars: 50000,
bootstrapTotalMaxChars: 300000,
},
},
}
```
Або перевизначте одного агента:
```json5
{
agents: {
list: [
{
id: "main",
bootstrapMaxChars: 50000,
bootstrapTotalMaxChars: 300000,
},
],
},
}
```
Використовуйте `/context`, щоб перевірити сирі й ін’єктовані розміри та чи сталося обрізання.
Тримайте `SOUL.md` сфокусованим на голосі, позиції та особистості; операційні правила
кладіть у `AGENTS.md`, а довговічні факти - у пам’ять.
Див. [Контекст](/uk/concepts/context) і [Конфіг агента](/uk/gateway/config-agents).
Розмістіть ваш **робочий простір агента** у **приватному** git-репозиторії та створюйте резервні копії десь
приватно (наприклад, приватний GitHub). Це охоплює пам’ять + файли AGENTS/SOUL/USER
і дає змогу пізніше відновити "розум" асистента.
**Не** комітьте нічого з `~/.openclaw` (облікові дані, сесії, токени або зашифровані секретні навантаження).
Якщо вам потрібне повне відновлення, окремо створіть резервні копії і робочого простору, і каталогу стану
(див. питання про міграцію вище).
Документація: [Робочий простір агента](/uk/concepts/agent-workspace).
Див. окремий посібник: [Видалення](/uk/install/uninstall).
Так. Робочий простір - це **default cwd** і якір пам’яті, а не жорстка пісочниця.
Відносні шляхи резолвляться всередині робочого простору, але абсолютні шляхи можуть отримувати доступ до інших
розташувань хоста, якщо пісочницю не ввімкнено. Якщо вам потрібна ізоляція, використовуйте
[`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування пісочниці для окремого агента. Якщо ви
хочете, щоб репозиторій був робочим каталогом за замовчуванням, вкажіть для `workspace`
цього агента корінь репозиторію. Репозиторій OpenClaw - це лише вихідний код; тримайте
робочий простір окремо, якщо ви навмисно не хочете, щоб агент працював усередині нього.
Приклад (репозиторій як default 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**. На практиці це означає:
- автентифікація shared-secret: токен або пароль
- `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse 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).
- Налаштування shared-secret Control UI автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігається в налаштуваннях застосунку/UI). Режими з ідентичністю, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запиту. Уникайте розміщення shared secrets в URL.
- З `gateway.auth.mode: "trusted-proxy"` same-host loopback reverse proxies потребують явного `gateway.auth.trustedProxy.allowLoopback = true` і loopback-запису в `gateway.trustedProxies`.
OpenClaw за замовчуванням примусово застосовує автентифікацію gateway, зокрема для loopback. У звичайному типовому шляху це означає автентифікацію токеном: якщо явний шлях автентифікації не налаштовано, запуск gateway резолвиться в режим токена й генерує runtime-only токен для цього запуску, тому **локальні WS-клієнти мають автентифікуватися**. Явно налаштуйте `gateway.auth.token`, `gateway.auth.password`, `OPENCLAW_GATEWAY_TOKEN` або `OPENCLAW_GATEWAY_PASSWORD`, коли клієнтам потрібен стабільний секрет між перезапусками. Це блокує інші локальні процеси від виклику Gateway.
Якщо ви віддаєте перевагу іншому шляху автентифікації, можна явно вибрати режим пароля (або, для identity-aware reverse proxy, `trusted-proxy`). Якщо ви **дійсно** хочете відкритий loopback, явно задайте `gateway.auth.mode: "none"` у своїй конфігурації. Doctor може будь-коли згенерувати для вас токен: `openclaw doctor --generate-gateway-token`.
Gateway стежить за конфігурацією та підтримує гаряче перезавантаження:
- `gateway.reload.mode: "hybrid"` (типово): безпечно застосовує зміни на льоту, перезапускається для критичних
- `hot`, `restart`, `off` також підтримуються
Задайте `cli.banner.taglineMode` у конфігурації:
```json5
{
cli: {
banner: {
taglineMode: "off", // random | default | off
},
},
}
```
- `off`: приховує текст слогана, але залишає рядок із назвою банера/версією.
- `default`: щоразу використовує `All your chats, one OpenClaw.`.
- `random`: ротаційні жартівливі/сезонні слогани (типова поведінка).
- Якщо ви взагалі не хочете банер, задайте env `OPENCLAW_HIDE_BANNER=1`.
`web_fetch` працює без API-ключа. `web_search` залежить від вибраного
провайдера:
- Провайдери з API, як-от Brave, Exa, Firecrawl, Gemini, Kimi, MiniMax Search, Perplexity і Tavily, потребують свого звичного налаштування API-ключа.
- Grok може повторно використовувати xAI OAuth з автентифікації моделі або fallback до `XAI_API_KEY` / конфігурації вебпошуку Plugin.
- Ollama Web Search не потребує ключа, але використовує налаштований вами хост Ollama і потребує `ollama signin`.
- DuckDuckGo не потребує ключа, але це неофіційна HTML-інтеграція.
- SearXNG не потребує ключа/самостійно розгортається; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`.
**Рекомендовано:** запустіть `openclaw configure --section web` і виберіть провайдера.
Альтернативи через середовище:
- Brave: `BRAVE_API_KEY`
- Exa: `EXA_API_KEY`
- Firecrawl: `FIRECRAWL_API_KEY`
- Gemini: `GEMINI_API_KEY`
- Grok: xAI OAuth, `XAI_API_KEY`
- Kimi: `KIMI_API_KEY` або `MOONSHOT_API_KEY`
- MiniMax Search: `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY` або `MINIMAX_API_KEY`
- Perplexity: `PERPLEXITY_API_KEY` або `OPENROUTER_API_KEY`
- SearXNG: `SEARXNG_BASE_URL`
- Tavily: `TAVILY_API_KEY`
```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.*` тимчасово все ще завантажуються для сумісності, але їх не слід використовувати для нових конфігурацій.
Конфігурація fallback для Firecrawl web-fetch живе в `plugins.entries.firecrawl.config.webFetch.*`.
Примітки:
- Якщо ви використовуєте allowlist, додайте `web_search`/`web_fetch`/`x_search` або `group:web`.
- `web_fetch` увімкнено типово (якщо його явно не вимкнено).
- Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично виявляє першого готового fallback-провайдера fetch з доступних облікових даних. Офіційний Firecrawl Plugin надає цей fallback.
- Демони читають env vars з `~/.openclaw/.env` (або середовища сервісу).
Документація: [Вебінструменти](/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`.
- Якщо у вас немає останньої відомої справної конфігурації або відхиленого payload, відновіть із резервної копії або повторно запустіть `openclaw doctor` і заново налаштуйте канали/моделі.
- Якщо це було неочікувано, створіть bug report і додайте останню відому конфігурацію або будь-яку резервну копію.
- Локальний coding agent часто може реконструювати робочу конфігурацію з логів або історії.
Як уникнути:
- Використовуйте `openclaw config set` для малих змін.
- Використовуйте `openclaw configure` для інтерактивного редагування.
- Спочатку використовуйте `config.schema.lookup`, якщо не впевнені щодо точного шляху або форми поля; він повертає неглибокий вузол схеми плюс короткі описи безпосередніх дочірніх елементів для заглиблення.
- Використовуйте `config.patch` для часткових RPC-редагувань; залишайте `config.apply` лише для заміни всієї конфігурації.
- Якщо ви використовуєте agent-facing інструмент `gateway` з agent run, він усе одно відхилятиме записи до `tools.exec.ask` / `tools.exec.security` (зокрема застарілі псевдоніми `tools.bash.*`, які нормалізуються до тих самих захищених exec-шляхів).
Документація: [Конфігурація](/uk/cli/config), [Налаштування](/uk/cli/configure), [Усунення неполадок Gateway](/uk/gateway/troubleshooting#gateway-rejected-invalid-config), [Doctor](/uk/gateway/doctor).
Поширений шаблон: **один Gateway** (наприклад, Raspberry Pi) плюс **вузли** та **агенти**:
- **Gateway (центральний):** володіє каналами (Signal/WhatsApp), маршрутизацією та сесіями.
- **Вузли (пристрої):** Macs/iOS/Android підключаються як периферія та надають локальні інструменти (`system.run`, `canvas`, `camera`).
- **Агенти (workers):** окремі brains/workspaces для спеціальних ролей (наприклад, "Hetzner ops", "Personal data").
- **Субагенти:** породжують фонову роботу з головного агента, коли потрібен паралелізм.
- **TUI:** підключайтеся до Gateway і перемикайте агентів/сесії.
Документація: [Вузли](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Субагенти](/uk/tools/subagents), [TUI](/uk/web/tui).
Так. Це опція конфігурації:
```json5
{
browser: { headless: true },
agents: {
defaults: {
sandbox: { browser: { headless: true } },
},
},
}
```
Типово `false` (headful). Headless з більшою ймовірністю викликає anti-bot перевірки на деяких сайтах. Див. [Браузер](/uk/tools/browser).
Headless використовує **той самий рушій Chromium** і працює для більшості автоматизації (форми, кліки, scraping, входи). Основні відмінності:
- Немає видимого вікна браузера (використовуйте screenshots, якщо потрібна візуалізація).
- Деякі сайти суворіші до автоматизації в headless-режимі (CAPTCHA, anti-bot).
Наприклад, X/Twitter часто блокує headless-сесії.
Задайте `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
Вузли не бачать вхідний трафік провайдера; вони лише отримують node RPC calls.
Коротка відповідь: **спаріть свій комп'ютер як вузол**. Gateway працює в іншому місці, але може
викликати інструменти `node.*` (екран, камера, system) на вашій локальній машині через Gateway WebSocket.
Типове налаштування:
1. Запустіть Gateway на always-on хості (VPS/домашньому сервері).
2. Помістіть хост Gateway і ваш комп'ютер в одну tailnet.
3. Переконайтеся, що Gateway WS доступний (tailnet bind або SSH-тунель).
4. Відкрийте застосунок macOS локально й підключіться в режимі **Remote over SSH** (або напряму через tailnet),
щоб він міг зареєструватися як вузол.
5. Схваліть вузол на Gateway:
```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-тунель, підтвердьте, що локальний тунель працює й вказує на правильний порт.
- Підтвердьте, що ваші allowlist (DM або group) містять ваш обліковий запис.
Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Канали](/uk/channels).
Так. Вбудованого моста "bot-to-bot" немає, але це можна надійно з'єднати кількома
способами:
**Найпростіше:** використовуйте звичайний канал чату, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp).
Нехай Bot A надішле повідомлення Bot B, а потім Bot B відповість як зазвичай.
**CLI-міст (generic):** запустіть скрипт, який викликає інший 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
```
Порада: додайте guardrail, щоб два боти не зациклювалися безкінечно (лише згадки, channel
allowlist або правило "не відповідати на повідомлення ботів").
Документація: [Віддалений доступ](/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 хоста Node](/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**. Вузли підключаються через той самий Gateway WS endpoint.
Рекомендоване налаштування:
1. **Переконайтеся, що VPS + Mac перебувають в одному tailnet**.
2. **Використовуйте застосунок macOS у віддаленому режимі** (ціллю SSH може бути hostname tailnet).
Застосунок прокладе тунель до порту Gateway і підключиться як вузол.
3. **Підтвердьте вузол** на gateway:
```bash
openclaw devices list
openclaw devices approve
```
Документація: [Протокол Gateway](/uk/gateway/protocol), [Discovery](/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 читає змінні середовища з батьківського процесу (оболонка, launchd/systemd, CI тощо) і додатково завантажує:
- `.env` з поточного робочого каталогу
- глобальний резервний `.env` з `~/.openclaw/.env` (також відомий як `$OPENCLAW_STATE_DIR/.env`)
Жоден файл `.env` не перевизначає наявні змінні середовища.
Змінні облікових даних провайдерів є винятком для робочого `.env`: ключі на кшталт
`GEMINI_API_KEY`, `XAI_API_KEY` або `MISTRAL_API_KEY` ігноруються з робочого
`.env` і мають бути в середовищі процесу, `~/.openclaw/.env` або config `env`.
Ви також можете визначити inline-змінні середовища в конфігурації (застосовуються лише якщо їх немає в середовищі процесу):
```json5
{
env: {
OPENROUTER_API_KEY: "sk-or-...",
vars: { GROQ_API_KEY: "gsk-..." },
},
}
```
Див. [/environment](/uk/help/environment) для повного порядку пріоритетів і джерел.
Два поширені виправлення:
1. Покладіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися навіть тоді, коли сервіс не успадковує середовище вашої оболонки.
2. Увімкніть імпорт оболонки (зручність за явним вибором):
```json5
{
env: {
shellEnv: {
enabled: true,
timeoutMs: 15000,
},
},
}
```
Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає). Еквіваленти змінних середовища:
`OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`.
`openclaw models status` повідомляє, чи ввімкнено **імпорт середовища оболонки**. "Shell env: off"
**не** означає, що ваші змінні середовища відсутні - це лише означає, що OpenClaw не завантажуватиме
вашу login shell автоматично.
Якщо Gateway працює як сервіс (launchd/systemd), він не успадковуватиме середовище вашої оболонки.
Виправте це одним із таких способів:
1. Покладіть токен у `~/.openclaw/.env`:
```
COPILOT_GITHUB_TOKEN=...
```
2. Або увімкніть імпорт оболонки (`env.shellEnv.enabled: true`).
3. Або додайте його до блоку config `env` (застосовується лише якщо відсутній).
Потім перезапустіть gateway і перевірте знову:
```bash
openclaw models status
```
Токени 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**).
Установіть додатне значення, щоб увімкнути завершення через бездіяльність. Коли ввімкнено, **наступне**
повідомлення після періоду бездіяльності починає новий id сесії для цього ключа чату.
Це не видаляє transcript - це лише починає нову сесію.
```json5
{
session: {
idleMinutes: 240,
},
}
```
Так, через **маршрутизацію кількох агентів** і **субагентів**. Ви можете створити одного координувального
агента і кількох робочих агентів із власними робочими просторами та моделями.
Водночас це найкраще сприймати як **цікавий експеримент**. Він потребує багато токенів і часто
менш ефективний, ніж використання одного бота з окремими сесіями. Типова модель, яку ми
уявляємо, - це один бот, з яким ви спілкуєтеся, з різними сесіями для паралельної роботи. Цей
бот також може запускати субагентів за потреби.
Документація: [Маршрутизація кількох агентів](/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 також пропонує **Reset**, якщо бачить наявну конфігурацію. Див. [Onboarding (CLI)](/uk/start/wizard).
- Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен state dir (типові значення - `~/.openclaw-`).
- Dev reset: `openclaw gateway --dev --reset` (лише для розробки; стирає dev-конфігурацію + облікові дані + сесії + робочий простір).
Використайте один із цих варіантів:
- **Compact** (зберігає розмову, але підсумовує старіші ходи):
```
/compact
```
або `/compact `, щоб скерувати підсумок.
- **Reset** (новий ID сесії для того самого ключа чату):
```
/new
/reset
```
Якщо це продовжується:
- Увімкніть або налаштуйте **обрізання сесій** (`agents.defaults.contextPruning`), щоб скоротити старий вивід інструментів.
- Використовуйте модель із більшим вікном контексту.
Документація: [Compaction](/uk/concepts/compaction), [Обрізання сесій](/uk/concepts/session-pruning), [Керування сесіями](/uk/concepts/session).
Це помилка перевірки провайдера: модель видала блок `tool_use` без обов'язкового
`input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих потоків
або зміни інструмента/схеми).
Виправлення: почніть нову сесію за допомогою `/new` (окреме повідомлення).
Heartbeat запускається кожні **30m** за замовчуванням (**1h** під час використання OAuth auth). Налаштуйте або вимкніть їх:
```json5
{
agents: {
defaults: {
heartbeat: {
every: "2h", // or "0m" to disable
},
},
},
}
```
If `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки,
Markdown/HTML-коментарі, Markdown-заголовки на кшталт `# Heading`, маркери блоків коду
або порожні заготовки контрольних списків), OpenClaw пропускає запуск Heartbeat, щоб заощадити API-виклики.
Якщо файл відсутній, Heartbeat все одно запускається, а модель вирішує, що робити.
Перевизначення для окремих агентів використовують `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 (якщо вже налаштовано/додано до списку дозволених): виведіть список груп із конфігурації:
```bash
openclaw directory groups list --channel whatsapp
```
Документація: [WhatsApp](/uk/channels/whatsapp), [Каталог](/uk/cli/directory), [Журнали](/uk/cli/logs).
Дві поширені причини:
- Увімкнено обмеження за згадуванням (за замовчуванням). Потрібно @згадати бота (або збігтися з `mentionPatterns`).
- Ви налаштували `channels.whatsapp.groups` без `"*"`, і групу не додано до списку дозволених.
Див. [Групи](/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: порти, "already running" і віддалений режим
`gateway.port` керує єдиним мультиплексованим портом для WebSocket + HTTP (Control UI, хуки тощо).
Пріоритет:
```
--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789
```
Тому що "running" — це погляд **супервізора** (launchd/systemd/schtasks). Перевірка з’єднання — це фактичне підключення CLI до WebSocket Gateway.
Використовуйте `openclaw gateway status` і довіряйте цим рядкам:
- `Probe target:` (URL, який перевірка фактично використала)
- `Listening:` (що фактично прив’язано до порту)
- `Last gateway error:` (поширена першопричина, коли процес живий, але порт не слухає)
Ви редагуєте один файл конфігурації, тоді як сервіс працює з іншим (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`).
Виправлення:
```bash
openclaw gateway install --force
```
Запустіть це з тим самим `--profile` / середовищем, яке має використовувати сервіс.
OpenClaw забезпечує блокування виконання, негайно прив’язуючи слухач WebSocket під час запуску (за замовчуванням `ws://127.0.0.1:18789`). Якщо прив’язування завершується помилкою `EADDRINUSE`, він викидає `GatewayLockError`, що вказує, що інший екземпляр уже слухає.
Виправлення: зупиніть інший екземпляр, звільніть порт або запустіть із `openclaw gateway --port `.
Установіть `gateway.mode: "remote"` і вкажіть віддалений WebSocket URL, за потреби зі спільними секретними віддаленими обліковими даними:
```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 із кодом налаштування повертає токен пристрою вузла з `scopes: []` плюс обмежений токен передавання оператору для довіреного мобільного onboarding. Передавання оператору може читати нативну конфігурацію під час налаштування, але не надає областей мутації сполучення або `operator.admin`.
Виправлення:
- Найшвидше: `openclaw dashboard` (друкує + копіює URL панелі, намагається відкрити; показує підказку SSH, якщо середовище без дисплея).
- Якщо у вас ще немає токена: `openclaw doctor --generate-gateway-token`.
- Якщо віддалено, спочатку створіть тунель: `ssh -N -L 18789:127.0.0.1:18789 user@host`, потім відкрийте `http://127.0.0.1:18789/`.
- Режим спільного секрету: установіть `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` або `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, потім вставте відповідний секрет у налаштування Control UI.
- Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено й ви відкриваєте Serve URL, а не сирий loopback/tailnet URL, який обходить заголовки ідентичності Tailscale.
- Режим довіреного проксі: переконайтеся, що ви заходите через налаштований identity-aware proxy, а не сирий URL gateway. Проксі local loopback на тому самому хості також потребують `gateway.auth.trustedProxy.allowLoopback = true`.
- Якщо невідповідність зберігається після однієї повторної спроби, виконайте ротацію/повторне схвалення токена сполученого пристрою:
- `openclaw devices list`
- `openclaw devices rotate --device --role operator`
- Якщо цей виклик ротації каже, що його відхилено, перевірте дві речі:
- сесії сполучених пристроїв можуть ротувати лише **власний** пристрій, якщо вони також не мають `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 може запускати кілька каналів обміну повідомленнями й агентів. Використовуйте кілька Gateways лише коли потрібна надлишковість (наприклад, резервний бот) або жорстка ізоляція.
Так, але потрібно ізолювати:
- `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 ()`).
Повний посібник: [Кілька gateways](/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):
- stdout macOS launchd: `~/Library/Logs/openclaw/gateway.log` (профілі використовують `gateway-.log`; stderr приглушено)
- 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) Локальне налаштування Windows Hub:** нативний застосунок керує локальним Gateway у WSL, що належить застосунку.
Відкрийте **OpenClaw Companion** з меню Start або системного трея, потім скористайтеся
**Gateway Setup** або вкладкою Connections.
**2) Ручний Gateway у WSL2:** Gateway працює всередині Linux.
Відкрийте PowerShell, увійдіть у WSL, потім перезапустіть:
```powershell
wsl
openclaw gateway status
openclaw gateway restart
```
Якщо ви ніколи не встановлювали службу, запустіть її у foreground:
```bash
openclaw gateway run
```
**3) Нативний Windows CLI/Gateway:** Gateway працює безпосередньо у Windows.
Відкрийте PowerShell і виконайте:
```powershell
openclaw gateway status
openclaw gateway restart
```
Якщо ви запускаєте його вручну (без служби), використовуйте:
```powershell
openclaw gateway run
```
Документація: [Windows](/uk/platforms/windows), [інструкція з експлуатації служби Gateway](/uk/gateway).
Почніть зі швидкої перевірки стану:
```bash
openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow
```
Поширені причини:
- Автентифікацію моделі не завантажено на **хості gateway** (перевірте `models status`).
- Спарювання каналу/список дозволених блокує відповіді (перевірте конфігурацію каналу + журнали).
- 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?
Потім перегляньте журнали в режимі tail:
```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 і повторює спробу з меншою кількістю команд, але деякі записи меню все одно потрібно прибрати. Зменште кількість команд плагінів/навичок/користувацьких команд або вимкніть `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), [слеш-команди](/uk/tools/slash-commands).
Якщо ви встановили службу:
```bash
openclaw gateway stop
openclaw gateway start
```
Це зупиняє/запускає **керовану службу** (launchd на macOS, systemd на Linux).
Використовуйте це, коли Gateway працює у фоні як демон.
Якщо ви запускаєте у foreground, зупиніть через Ctrl-C, потім:
```bash
openclaw gateway run
```
Документація: [інструкція з експлуатації служби Gateway](/uk/gateway).
- `openclaw gateway restart`: перезапускає **фонову службу** (launchd/systemd).
- `openclaw gateway`: запускає gateway **у foreground** для цього сеансу термінала.
Якщо ви встановили службу, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли
потрібен одноразовий запуск у foreground.
Запустіть Gateway із `--verbose`, щоб отримати більше деталей у консолі. Потім перевірте файл журналу на помилки автентифікації каналів, маршрутизації моделей і RPC.
## Медіа та вкладення
Вихідні вкладення від агента мають використовувати структуровані поля медіа, як-от `media`, `mediaUrl`, `path` або `filePath`. Див. [налаштування асистента OpenClaw](/uk/start/openclaw) і [надсилання агентом](/uk/tools/agent-send).
Надсилання через CLI:
```bash
openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png
```
Також перевірте:
- Цільовий канал підтримує вихідні медіа і не заблокований списками дозволених.
- Файл не перевищує ліміти розміру провайдера (зображення змінюються до максимуму 2048px).
- `tools.fs.workspaceOnly=true` обмежує надсилання з локальних шляхів робочою областю, temp/media-store і файлами, перевіреними sandbox.
- `tools.fs.workspaceOnly=false` дозволяє структурованим локальним медіанадсиланням використовувати локальні файли хоста, які агент уже може читати, але лише для медіа та безпечних типів документів (зображення, аудіо, відео, PDF, документи Office і перевірені текстові документи, як-от Markdown/MD, TXT, JSON, YAML і YML). Це не сканер секретів: доступний агенту `secret.txt` або `config.json` може бути прикріплений, якщо розширення і перевірка вмісту збігаються. Тримайте чутливі файли поза шляхами, доступними агенту, або залишайте `tools.fs.workspaceOnly=true` для суворішого надсилання з локальних шляхів.
Див. [Зображення](/uk/nodes/images).
## Безпека та контроль доступу
Ставтеся до вхідних особистих повідомлень як до ненадійного вводу. Типові налаштування розроблено для зменшення ризику:
- Типова поведінка на каналах із підтримкою особистих повідомлень - **спарювання**:
- Невідомі відправники отримують код спарювання; бот не обробляє їхнє повідомлення.
- Схвалити можна так: `openclaw pairing approve --channel [--account ] `
- Очікувані запити обмежено **3 на канал**; перевірте `openclaw pairing list --channel [--account ]`, якщо код не надійшов.
- Публічне відкриття особистих повідомлень потребує явного ввімкнення (`dmPolicy: "open"` і список дозволених `"*"`).
Запустіть `openclaw doctor`, щоб виявити ризиковані політики особистих повідомлень.
Ні. Prompt injection стосується **ненадійного вмісту**, а не лише того, хто може писати боту в особисті повідомлення.
Якщо ваш асистент читає зовнішній вміст (вебпошук/отримання сторінок, сторінки браузера, електронні листи,
документи, вкладення, вставлені журнали), цей вміст може містити інструкції, які намагаються
перехопити модель. Це може статися навіть якщо **ви єдиний відправник**.
Найбільший ризик виникає, коли інструменти ввімкнено: модель можна обманом змусити
вивести контекст назовні або викликати інструменти від вашого імені. Зменшіть радіус ураження так:
- використовуйте агента-"читача" лише для читання або без інструментів, щоб підсумовувати ненадійний вміст
- тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з увімкненими інструментами
- також вважайте декодований текст файлів/документів ненадійним: OpenResponses
`input_file` і витягування медіавкладень обгортають витягнутий текст у
явні маркери межі зовнішнього вмісту замість передавання сирого тексту файлу
- використовуйте sandbox і суворі списки дозволених інструментів
Докладніше: [Безпека](/uk/gateway/security).
Мова й середовище виконання мають значення, але вони не є головним ризиком для персонального
агента. Практичні ризики OpenClaw - це доступність gateway, хто може писати
боту, prompt injection, область дії інструментів, обробка облікових даних, доступ браузера, доступ exec
і довіра до сторонніх навичок або плагінів.
Rust і WASM можуть забезпечити сильнішу ізоляцію для деяких класів коду, але
вони не вирішують prompt injection, погані списки дозволених, публічну доступність gateway,
надто широкі інструменти або профіль браузера, який уже ввійшов у чутливі
облікові записи. Розглядайте це як основні засоби контролю:
- тримайте Gateway приватним або автентифікованим
- використовуйте спарювання та списки дозволених для особистих повідомлень і груп
- забороняйте або ізолюйте в sandbox ризиковані інструменти для ненадійних вхідних даних
- встановлюйте лише довірені плагіни та навички
- запускайте `openclaw security audit --deep` після змін конфігурації
Докладніше: [Безпека](/uk/gateway/security), [Sandboxing](/uk/gateway/sandboxing).
Спершу перевірте ваше фактичне розгортання:
```bash
openclaw security audit --deep
openclaw gateway status
```
Безпечніший базовий стан:
- Gateway прив'язаний до `loopback` або відкритий лише через автентифікований приватний
доступ, як-от приватна мережа tailnet, SSH-тунель, автентифікація токеном/паролем або правильно
налаштований довірений проксі
- особисті повідомлення в режимі `pairing` або `allowlist`
- групи внесені до списку дозволених і вимагають згадки, якщо не кожному учаснику можна довіряти
- інструменти високого ризику (`exec`, `browser`, `gateway`, `cron`) заборонені або жорстко
обмежені для агентів, які читають ненадійний вміст
- sandbox увімкнено там, де виконання інструментів потребує меншого радіуса ураження
Публічні прив'язки без автентифікації, відкриті особисті повідомлення/групи з інструментами та відкритий
контроль браузера - це знахідки, які потрібно виправити першими. Докладніше:
[контрольний список аудиту безпеки](/uk/gateway/security#security-audit-checklist).
Ставтеся до сторонніх навичок і плагінів як до коду, якому ви вирішуєте довіряти.
Сторінки навичок ClawHub показують стан сканування перед встановленням, але сканування не є
повною межею безпеки. OpenClaw не запускає вбудоване локальне
блокування небезпечного коду під час встановлення/оновлення плагінів або навичок; використовуйте
керовану оператором `security.installPolicy` для локальних рішень дозволу/блокування.
Безпечніший підхід:
- віддавайте перевагу довіреним авторам і зафіксованим версіям
- прочитайте навичку або плагін перед увімкненням
- тримайте списки дозволених плагінів і навичок вузькими
- запускайте робочі процеси з ненадійними вхідними даними в sandbox із мінімальними інструментами
- уникайте надання сторонньому коду широкого доступу до файлової системи, exec, браузера або секретів
Деталі: [Skills](/uk/tools/skills), [Plugin](/uk/tools/plugin),
[Безпека](/uk/gateway/security).
Так, для більшості налаштувань. Ізоляція бота в окремих облікових записах і номерах телефону
зменшує радіус ураження, якщо щось піде не так. Це також полегшує ротацію
облікових даних або відкликання доступу без впливу на ваші особисті облікові записи.
Починайте з малого. Надавайте доступ лише до інструментів і облікових записів, які справді потрібні, і розширюйте
його пізніше, якщо буде потрібно.
Документація: [Безпека](/uk/gateway/security), [Сполучення](/uk/channels/pairing).
Ми **не** рекомендуємо повну автономію над вашими особистими повідомленнями. Найбезпечніший шаблон:
- Тримайте особисті повідомлення в **режимі сполучення** або в суворому списку дозволених.
- Використовуйте **окремий номер або обліковий запис**, якщо хочете, щоб він надсилав повідомлення від вашого імені.
- Дозвольте йому підготувати чернетку, а потім **підтверджуйте перед надсиланням**.
Якщо хочете експериментувати, робіть це в спеціальному обліковому записі й тримайте його ізольованим. Див.
[Безпека](/uk/gateway/security).
Так, **якщо** агент працює лише як чат і вхідні дані є довіреними. Менші рівні
більш уразливі до перехоплення інструкцій, тому уникайте їх для агентів з увімкненими інструментами
або під час читання недовіреного вмісту. Якщо вам потрібно використовувати меншу модель, жорстко обмежте
інструменти й запускайте її в пісочниці. Див. [Безпека](/uk/gateway/security).
Коди сполучення надсилаються **лише** коли невідомий відправник пише боту і
`dmPolicy: "pairing"` увімкнено. `/start` сам по собі не генерує код.
Перевірте запити в очікуванні:
```bash
openclaw pairing list telegram
```
Якщо хочете негайний доступ, додайте id відправника до списку дозволених або встановіть `dmPolicy: "open"`
для цього облікового запису.
Ні. Стандартна політика особистих повідомлень WhatsApp — **сполучення**. Невідомі відправники отримують лише код сполучення, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише в чатах, з яких отримує повідомлення, або на явні надсилання, які ви запускаєте.
Підтвердьте сполучення за допомогою:
```bash
openclaw pairing approve whatsapp
```
Перелічіть запити в очікуванні:
```bash
openclaw pairing list whatsapp
```
Запит номера телефону в майстрі: він використовується для налаштування вашого **списку дозволених/власника**, щоб ваші власні особисті повідомлення були дозволені. Він не використовується для автоматичного надсилання. Якщо ви запускаєте на своєму особистому номері 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).
Надішліть будь-яке з наведеного **як окреме повідомлення** (без скісної риски):
```
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
```
Це тригери переривання (не команди зі скісною рискою).
Для фонових процесів (з інструмента exec) ви можете попросити агента виконати:
```
process action:kill sessionId:XXX
```
Огляд команд зі скісною рискою: див. [Команди зі скісною рискою](/uk/tools/slash-commands).
Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`, але кілька скорочень (наприклад, `/status`) також працюють у рядку для відправників зі списку дозволених.
OpenClaw стандартно блокує обмін повідомленнями **між провайдерами**. Якщо виклик інструмента прив'язаний
до Telegram, він не надішле в Discord, якщо ви явно цього не дозволите.
Увімкніть обмін повідомленнями між провайдерами для агента:
```json5
{
tools: {
message: {
crossContext: {
allowAcrossProviders: true,
marker: { enabled: true, prefix: "[from {channel}] " },
},
},
},
}
```
Перезапустіть gateway після редагування конфігурації.
Підказки під час виконання стандартно спрямовуються в активний запуск. Використовуйте `/queue`, щоб вибрати поведінку активного запуску:
- `steer` - скеровувати активний запуск на наступній межі моделі
- `followup` - поставити повідомлення в чергу й виконувати їх по одному після завершення поточного запуску
- `collect` - поставити сумісні повідомлення в чергу й відповісти один раз після завершення поточного запуску
- `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) — діагностика за симптомами