2026: миграция OpenClaw и runbook холодного старта — от копирования каталогов до первого линка шлюза (systemd и launchd)

1. Болевые точки: скопированные деревья сами по себе не исполняются

Команды, переносящие OpenClaw с ноутбука инженера или со старого VPS, нередко исходят из тихого предположения: если список файлов совпадает, поведение тоже совпадёт. На практике OpenClaw опирается на четыре связанных слоя: какой бинарник openclaw выигрывает гонку на PATH, дерево конфигурации на диске в ~/.openclaw, ресурсы, зависящие от корня рабочего пространства, и контекст супервизора, который создают systemd или launchd. Если выпасть хотя бы из одного слоя, вы получите симптомы, которые трудно воспроизвести дословно: шлюз, который уверенно работает внутри интерактивной SSH-сессии, исчезает после отключения клиента или перезагрузки, хотя «ничего не меняли».

Первая задача приёмки после миграции — перестать смешивать человеческий интерактивный шелл и сервисный контекст. Оператор видит рабочий openclaw, потому что его login-скрипты дописали nvm или Homebrew в PATH, а фоновый агент стартует без этих строк и тихо падает на первом же обращении к отсутствующей библиотеке. Вторая задача — зафиксировать носитель установки до копирования деревьев: глобальный npm, pnpm из исходников, статический install.sh или контейнер с фиксированным digest. Смешение двух носителей на одной машине — частый источник «одинаковых» версий с разными путями динамического загрузчика.

1. Дрейф интерфейса командной строки между машинами: на старом хосте всё могло крутиться вокруг глобального npm, а на новом образе Mac cloud в PATH остались только префиксы Homebrew или раскладка статического установщика. JSON-файлы не ставят бинарники. В монорепозиториях на pnpm плюс глобальные пакеты встречаются ситуации, когда строки версий совпадают, а реальные пути к разделяемым объектам — нет.
2. Сломанный контекст демона: на Linux пользовательские unit-файлы systemd --user нередко явно задают Environment=HOME=.... На macOS LaunchAgents не наследуют rc-файлы login-shell, поэтому префиксы в стиле nvm исчезают, если вы не зашили абсолютные пути или тонкую обёртку-скрипт. Неверный WorkingDirectory бесшумно направляет логи и поиск учётных данных не туда, и вы часами крутите канал, хотя корень проблемы — каталог процесса.
3. Неверный порядок триажа: прыжок к сопряжению каналов до проверки синтаксиса openclaw.json и порта 18789 расточительно сжигает время команды. Локальные пробы должны стать зелёными раньше, чем вы трогаете внешние поверхности обмена сообщениями.
4. Владение файлами после rsync: деревья, скопированные под root и затем переданные прикладному пользователю, иногда остаются читаемыми, но не пригодными для записи stderr, что выглядит как «зависание без объяснений». Проверяйте uid, gid и ACL так же придирчиво, как checksum критичных файлов.

Когда эти четыре пункта вынесены в чеклист изменения, инцидент-менеджер получает язык, на котором можно согласовать продолжение работ или откат без споров о границах задачи. Для ночных окон обслуживания полезно заранее прикинуть минуты на каждый шаг ниже и записать их в тикет: это снижает давление «сделать любой ценой» в три часа ночи.

2. Матрица окружения: systemd и launchd

Таблица ниже годится как приложение к заявке на изменение. Колонка «первая остановка» подсказывает, что именно должен проверить дежурный на хосте, прежде чем обвинять чат-провайдера или сетевой периметр.

Если целевая площадка — долгоживущий инстанс Mac cloud, разумно сначала зафиксировать абсолютные пути и файлы логов в launchd, а уже затем решать, стоит ли Docker-разделения дополнительного тома и сопоставления uid. На Linux, если под systemd --user уже крутятся соседние демоны, выровняйте OpenClaw с теми же лимитами slice, чтобы тяжёлый сосед вроде xcodebuild не вытеснял ответы шлюза.

Отдельно стоит проговорить культуру журналирования: на systemd привыкли к journalctl как к единому входу, на macOS чаще приходится явно проектировать файлы StandardOutPath и StandardErrorPath и следить за ротацией. Если логи лежат в каталоге, куда сервисный пользователь не может дописать, вы получите пустые файлы и ложное ощущение «ничего не происходит». Матрица помогает не пропустить этот класс ошибок при переносе runbook между ОС.

На практике команды копируют таблицу в внутреннюю wiki и дополняют ссылками на конкретные unit-файлы и plist-ярлыки своей организации. Так постмортемы перестают путать «не стартовал launchd» с «не отвечает Slack», потому что у каждого слоя есть явный владелец и критерий готовности.

3. Семь шагов холодного старта до первого успешного линка

Шаги специально выстраиваются от сигналов, которые человек может прочитать без внешних учётных записей, и откладывают всё, что требует аккаунта у провайдера сообщений. Для ночных переключений добавьте к каждому шагу оценку минут в окне работ: это позволяет лиду инцидента выбрать продолжение или откат без спонтанного расширения области изменений.

1. Зафиксировать версию и носитель: запишите вывод openclaw --version, выбор между npm, pnpm, install.sh или digest образа на старом хосте. На новой машине выберите один входной путь, опираясь на материал про пути установки, ещё до копирования деревьев, чтобы случайно не запускать два разных бинарника.
2. Синхронизировать каталоги: используйте rsync -aH или эквивалент для ~/.openclaw и рабочего пространства, с уважением к исключениям команды для тяжёлых кэшей. Сразу сравните время модификации и размеры критичных файлов, чтобы поймать частичные передачи на ранней стадии.
3. Права и доступность секретов: выполните ls -la ~/.openclaw. Для Docker-потоков заново проверьте bind mount и сопоставление uid по разделу про контейнеры в руководстве по установке.
4. Описать unit сервиса: на Linux — пользовательский unit systemd --user с явными строками окружения; на macOS — LaunchAgent, где ProgramArguments указывают абсолютные пути к openclaw. Явно кодируйте адрес прослушивания и порт, если значения по умолчанию менялись между релизами.
5. Загрузить и выполнить холодный старт: systemctl --user daemon-reload && restart или launchctl bootstrap с последующим kickstart. Убедитесь, что родительский процесс — systemd или launchd, а не сессия SSH.
6. Локальные пробы: lsof -i :18789, минимальная валидация JSON, затем openclaw doctor по лестнице из статьи про status и doctor. Пока пробы красные, не вращайте токены каналов.
7. Дымовой тест канала: только когда логи шлюза выглядят здоровыми, чините сопряжение. Сохраните транскрипты команд в записи изменения для аудиторов.

После седьмого шага имеет смысл зафиксировать «зелёный снимок»: версию, хэш конфигурации, первые строки лога и отметку времени первого ответа канала. Этот снимок становится опорной точкой для следующей миграции и для учебных прогонов, когда новые инженеры повторяют процедуру на стенде.

4. Справочный блок: пути, порт 18789, поля аудита

Этот раздел — вики-приложение; нумерованные шаги выше дают повествование. Вместе они дают и последовательность, и глубину чеклиста для постмортемов, не смешивая уровни абстракции.

• Единый источник правды для JSON: задокументируйте, какая машина владеет каноническим openclaw.json и как делаются резервные копии. После миграции сравните старый и новый файлы до старта сервисов, чтобы не запустить полуслитые правки.
• Конкуренция за порт: несколько лабораторных шлюзов на одном Mac cloud должны использовать разные порты или остановленные метки. Конкуренция часто маскируется под «рваную» связность.
• Минимум аудита: носитель, semver, unit или метка plist, digest образа при контейнеризации, первое зелёное резюме doctor, идентификатор аккаунта канала, время сопряжения, идентификаторы операторов для регулируемых сред.
• Откат: храните последний заведомо исправный unit-файл и тег пакета или образа на старом хосте. Квартальные учения гарантируют, что ключи, сменённые после снимка, всё ещё укладываются в целевое время восстановления.
• Внешние риски: когда слои установки и супервизора пройдены, цепочки поставки навыков ClawHub разбирают отдельным чеклистом аудита апреля 2026 года — не смешивайте эти темы с чисто инфраструктурным холодным стартом в одном тикете.
• Часовые пояса: коррелируя файловые логи между регионами, сначала выровняйте NTP и отображаемые часовые пояса, иначе причинно-следственные цепочки окажутся сдвинутыми.

Поле аудита «порт 18789» особенно важно в средах, где балансировщики и пробросы портов меняются чаще, чем конфигурация самого OpenClaw. Зафиксируйте, кто утверждает проброс, какая сторона отвечает за TLS-терминацию и где лежит актуальная схема маршрутизации. Это снимает класс инцидентов, когда шлюз слушает локально корректно, а внешний мир стучится в устаревший upstream.

5. Вопросы и ответы

В: Я скопировал только рабочее пространство, без ~/.openclaw. Шлюз всё равно может стартовать?
Скорее всего нет в полном смысле: ключи и локальное состояние живут под ~/.openclaw. Либо мигрируйте оба дерева, либо сознательно пересоберите секреты по контрольному экспорту со старого хоста.

В: launchctl показывает loaded, но на 18789 никто не слушает?
Проверьте StandardErrorPath, WorkingDirectory и PATH в plist. Пустые файлы ошибок иногда означают, что логи направлены в путь без прав на запись.

В: Можно ли переиспользовать Linux unit systemd на macOS?
Нет. Перепишите как LaunchAgent и заново проверьте переменные окружения и пути логов построчно.

В: Канал молчит, но 18789 отвечает локально?
Сначала читайте логи шлюза, затем сеть upstream и allow list. Не уничтожайте целые конфигурации, пока не исключили несовпадение bind-адреса после свежих правок.

В: Хочу параллельно держать старый инстанс для сравнения?
Используйте разные порты и метки и запретите лабораторному unit записывать продакшен JSON, чтобы избежать повреждения от двойной записи.

Если ответы кажутся слишком краткими, разверните их в полноценные подпункты runbook: для каждого «да или нет» добавьте конкретную команду, ожидаемый вывод и ссылку на артефакт в системе тикетов. Так дежурные меньше полагаются на устную память и быстрее входят в роль.

6. От пилота к продакшену на нативном Mac cloud

Сложность runbook растёт там, где SSH-доступ в эксплуатацию не совпадает с реальным контекстом процесса. Вложенная виртуализация усиливает сюрпризы с PATH, томами и правами. Выделенный Mac cloud с launchd, выровненным под руководство по установке, — короткий путь к холодным стартам, которые можно аудировать. Песочницы Docker добавляйте только после того, как нативный путь стал «скучно надёжным», а не в первое окно миграции.

Относитесь к долгоживущим шлюзам OpenClaw как к инфраструктурным пэрам CI-раннеров: резервируйте диск, ротируйте логи, маркируйте узлы и подключайте аудит входа. Когда каждый участник команды следует одному и тому же контракту на plist и каталоги, следующие миграции повторяют известный сценарий вместо импровизации на каждом ноутбуке.

Наконец, свяжите эксплуатационную зрелость с бизнес-метриками: время восстановления после перезагрузки, доля успешных дымовых тестов канала в течение первого часа, число ложных эскалаций из-за пустых логов. Эти цифры убеждают руководство инвестировать в автоматизацию проверок, а не только в скорость первичной установки.