Настройка

Кратко

Выберите процесс настройки в зависимости от того, как часто вы хотите получать обновления и хотите ли самостоятельно запускать 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 работает в режиме Локальный (им управляет приложение).
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:

• Режим подключения: Локальный Приложение подключится к запущенному 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>/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)