Налаштування

Коротко

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

• Персональні налаштування зберігаються поза репозиторієм: зберігайте конфігурацію та робочий простір у ~/.openclaw/openclaw.json і ~/.openclaw/workspace/, щоб оновлення репозиторію їх не зачіпали.
• Стабільний процес (рекомендовано для більшості): установіть застосунок macOS і дозвольте йому запускати вбудований Gateway.
• Процес із найновішими змінами (для розробки): самостійно запустіть Gateway через pnpm gateway:watch, а потім під’єднайте застосунок macOS у локальному режимі.

Передумови (для запуску з вихідного коду)

• Рекомендовано Node 24.15+ (Node 22 LTS, наразі 22.22.3+, усе ще підтримується)
• Для робочих копій вихідного коду потрібен pnpm. У режимі розробки OpenClaw завантажує вбудовані плагіни з пакетів робочого простору pnpm extensions/*, тому коренева команда npm install не готує повне дерево вихідного коду.
• Docker (необов’язково; лише для контейнеризованого налаштування та наскрізного тестування — див. Docker)

Стратегія персоналізації (щоб оновлення нічого не зламали)

Якщо вам потрібне налаштування, «на 100% адаптоване для мене», і прості оновлення, зберігайте свої зміни тут:

• Конфігурація: ~/.openclaw/openclaw.json (JSON або подібний до JSON5 формат)
• Робочий простір: ~/.openclaw/workspace (навички, запити, спогади; зробіть його приватним git-репозиторієм)

Одноразово створіть початкову структуру каталогів конфігурації та робочого простору, не запускаючи повний майстер початкового налаштування:

openclaw setup --baseline

Ще немає глобального встановлення? Натомість запустіть команду з цього репозиторію:

pnpm openclaw setup --baseline

(Команда openclaw setup без --baseline є псевдонімом для openclaw onboard і запускає повний інтерактивний майстер.)

Запуск Gateway із цього репозиторію

Після pnpm build можна безпосередньо запустити упакований CLI:

node openclaw.mjs gateway --port 18789 --verbose

Стабільний процес (спочатку застосунок macOS)

1. Установіть і запустіть OpenClaw.app (у смузі меню).
2. Виконайте контрольний список початкового налаштування та надання дозволів (запити TCC).
3. Переконайтеся, що Gateway працює в режимі Local (ним керує застосунок).
4. Під’єднайте канали (наприклад, WhatsApp):

openclaw channels login

5. Перевірка справності:

openclaw health

Якщо початкове налаштування недоступне у вашій збірці:

• Запустіть openclaw setup, потім openclaw channels login, а після цього запустіть Gateway вручну (openclaw gateway).

Процес із найновішими змінами (Gateway у терміналі)

Мета: працювати над Gateway на TypeScript, використовувати гаряче перезавантаження та тримати інтерфейс застосунку macOS під’єднаним.

0) (Необов’язково) Також запустіть застосунок macOS із вихідного коду

Якщо для застосунку macOS також потрібні найновіші зміни:

./scripts/restart-mac.sh

1) Запустіть Gateway для розробки

pnpm install# Лише під час першого запуску (або після скидання локальної конфігурації чи робочого простору OpenClaw)pnpm openclaw setuppnpm gateway:watch

gateway:watch запускає або перезапускає процес спостереження Gateway в іменованому сеансі tmux (openclaw-gateway-watch-main) та автоматично під’єднується до нього з інтерактивних терміналів. Неінтерактивні оболонки залишаються від’єднаними й виводять tmux attach -t openclaw-gateway-watch-main; використовуйте OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch, щоб інтерактивний запуск залишався від’єднаним, або pnpm gateway:watch:raw для режиму спостереження на передньому плані. Перш ніж зайняти налаштований або типовий порт активного профілю, спостерігач зупиняє встановлену службу Gateway, щоб диспетчер служб не замінив процес, запущений із вихідного коду. Служба залишається встановленою; після завершення спостереження запустіть pnpm openclaw gateway start. Панель tmux залишається доступною після помилки запуску, щоб інший термінал або агент міг під’єднатися чи зібрати журнали. Спостерігач перезавантажується за відповідних змін вихідного коду, конфігурації та метаданих вбудованих плагінів. Якщо Gateway, за яким ведеться спостереження, завершує роботу під час запуску, gateway:watch одноразово запускає openclaw doctor --fix --non-interactive і повторює спробу; установіть OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0, щоб вимкнути це відновлення, призначене лише для розробки. pnpm gateway:watch не перебудовує dist/control-ui, тому повторно запускайте pnpm ui:build після змін у ui/ або використовуйте pnpm ui:dev під час розроблення інтерфейсу керування.

2) Спрямуйте застосунок macOS на запущений Gateway

У OpenClaw.app:

• Connection Mode: Local Застосунок під’єднається до запущеного Gateway на налаштованому порту.

3) Перевірте

• Стан Gateway у застосунку має відображатися як "Using existing gateway …"
• Або через CLI:

openclaw health

Поширені помилки

• Неправильний порт: типовим портом WebSocket для Gateway є ws://127.0.0.1:18789; використовуйте в застосунку та CLI однаковий порт.
• Де зберігається стан:
  • Стан каналів і провайдерів: ~/.openclaw/credentials/
  • Профілі автентифікації моделей: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Сеанси та стенограми: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
  • Застарілі й архівні артефакти сеансів: ~/.openclaw/agents/<agentId>/sessions/
  • Журнали: /tmp/openclaw/

Карта зберігання облікових даних

Використовуйте її під час налагодження автентифікації або визначення даних для резервного копіювання:

• WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Токен бота Telegram: конфігурація, змінна середовища або channels.telegram.tokenFile (лише звичайний файл; символічні посилання відхиляються)
• Токен бота Discord: конфігурація, змінна середовища або SecretRef (провайдери env/file/exec)
• Токени Slack: конфігурація або змінна середовища (channels.slack.*)
• Списки дозволених для сполучення:
  • ~/.openclaw/credentials/<channel>-allowFrom.json (типовий обліковий запис)
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (облікові записи, що не є типовими)
• Профілі автентифікації моделей: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Корисне навантаження секретів у файлі (необов’язково): ~/.openclaw/secrets.json
• Імпорт застарілих даних OAuth: ~/.openclaw/credentials/oauth.json Докладніше: Безпека.

Оновлення (без руйнування налаштувань)

• Вважайте ~/.openclaw/workspace і ~/.openclaw/ «своїми даними»; не додавайте особисті запити чи конфігурацію до репозиторію openclaw.
• Оновлення вихідного коду: git pull + pnpm install; продовжуйте використовувати pnpm gateway:watch.

Linux (користувацька служба systemd)

У Linux використовується користувацька служба systemd. Типово systemd зупиняє користувацькі служби після виходу користувача або під час бездіяльності, через що Gateway завершує роботу. Під час початкового налаштування система намагається ввімкнути збереження користувацьких служб після виходу (може з’явитися запит sudo). Якщо цю функцію досі вимкнено, запустіть:

sudo loginctl enable-linger $USER

Для постійно ввімкнених або багатокористувацьких серверів варто натомість використовувати системну службу (збереження після виходу не потрібне). Примітки щодо systemd див. у посібнику з експлуатації Gateway.

Пов’язана документація

• Посібник з експлуатації Gateway (прапорці, керування процесом, порти)
• Конфігурація Gateway (схема конфігурації та приклади)
• Discord і Telegram (теги відповіді та налаштування replyToMode)
• Налаштування помічника OpenClaw
• Застосунок macOS (життєвий цикл Gateway)