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

# Коротко

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

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

# Передумови (з вихідного коду)

• Рекомендовано Node 24 (Node 22 LTS, наразі 22.14+, усе ще підтримується)
• pnpm потрібен для копій вихідного коду. OpenClaw завантажує вбудовані plugins із pnpm-пакетів робочого простору extensions/* у режимі розробки, тому кореневий npm install не готує повне дерево вихідного коду.
• Docker (необов'язково; лише для контейнеризованого налаштування/e2e - див. Docker)

# Стратегія персоналізації (щоб оновлення не шкодили)

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

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

Один раз виконайте початкове налаштування:

openclaw setup

Зсередини цього репозиторію використовуйте локальну точку входу CLI:

openclaw setup

Якщо у вас ще немає глобального встановлення, запустіть через pnpm openclaw setup.

# Запуск 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 у терміналі)

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

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

Якщо ви також хочете macOS-застосунок на передньому краї:

./scripts/restart-mac.sh

# 1) Запустіть dev Gateway

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

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

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

В OpenClaw.app:

• Режим підключення: Local Застосунок під'єднається до запущеного Gateway на налаштованому порту.

# 3) Перевірте

• Статус Gateway у застосунку має показувати "Використовується наявний Gateway …"
• Або через CLI:

openclaw health

# Поширені пастки

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

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

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

• WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Токен бота Telegram: конфігурація/env або channels.telegram.tokenFile (лише звичайний файл; символічні посилання відхиляються)
• Токен бота Discord: конфігурація/env або SecretRef (провайдери env/file/exec)
• Токени Slack: конфігурація/env (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. Початкове налаштування намагається ввімкнути lingering для вас (може попросити sudo). Якщо він усе ще вимкнений, виконайте:

sudo loginctl enable-linger $USER

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

# Пов'язані документи

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