Предполетная подготовка · врач · Матрица ошибок · Воспроизводимое развертывание
Строители прокладывают свой первый каналобычно глохнет на "Шлюз не запускается" - модели неслабые. Версии узлов, права доступа к каталогам,.envпротив дрейфа YAML, занятости портов, прокси и DNS — каждый из них может превратиться в красные журналы. Это руководство даетпредполетный контрольный список, аминимальный против многоканальногосравнение,шесть диагностических шагов(включаяopenclaw doctor), анМатрица признаков ошибокисамопроверка миграции в облако. Информацию о базовых показателях pm2 и постоянном включении см.Руководство по развертыванию постоянного облака; для контекста цен откройтестоимость аренды.
Скрипты установки выглядят короткими; Самая затратная часть — написание предположений во время выполнения: какой пользователь запускает шлюз, где разрешаются конфигурации, пути к журналам по умолчанию, какие порты должны быть свободными и кому принадлежит прокси/DNS. Многие инциденты «Шлюз не запускается» связаны с взаимодействием разрешений Node и macOS, а не с логикой OpenClaw. Пять пробелов, приведенных ниже, постоянно появляются в обсуждениях сообщества — запишите их в Runbook, чтобы не переустанавливать трижды, прежде чем заметите смещение PATH.
Если вы планируете использовать Slack или Telegram, решитеротация токеновикаталоги с наименьшими привилегиямирано; Успех первого канала с устаревшими переменными окружения делает вторую ротацию болезненной.
Сдвиг узла и менеджера пакетов:OpenClaw ожидает современный Node LTS. Смешение nvm, fnm и системного узла часто дает правильный результат.node -vв терминале, но в старом двоичном файле под вашим руководителем процесса. Закрепите один золотой вызов и проверьте настоящий двоичный файл в выводе доктора.
Рабочий каталог и границы разрешений:Клонирование в папки на рабочем столе или в iCloud может привести к блокировкам или неожиданностям с разрешениями. Сохраняйте производственные деревья в выделенном поддереве в домашнем каталоге пользователя службы и документируйте доступные для записи пути AgentSkill.
Порты и настройки брандмауэра по умолчанию:Слушатели Dashboard и Gateway, которые сталкиваются с другими демонами, немедленно завершают работу; корпоративные прокси-серверы или межсетевые экраны хостов могут блокировать исходящие вызовы LLM. Добавьте к предполетной проверке сканирование портов и однострочный исходящий дымовой тест.
Несколько источников конфигурации: .env, профили оболочки, блоки env launchd/pm2 и наложения YAML вместе создают ошибки «Я отредактировал неправильный файл». Выберите один источник правды и приоритет документов.
Пробелы в журналировании и наблюдаемости:Без адресатов стандартного вывода и ротации первый длительный запуск заполняет диски или прокручивает реальную ошибку. Исправление путей и сохранение во время установки — на порядок дешевле, чем модернизация мониторов.
Проверьте список, затем выберите путь установки в следующем разделе: только минимальный шлюз или многоканальная производственная топология.
Включение Slack, почты и веб-перехватчиков в первый же день разрушает матрицу неудач. Безопаснее:загрузите шлюз на самом маленьком профиле с работоспособными журналами, затем добавьте по одному адаптеру канала в каждое окно изменений, чтобы откаты оставались очевидными. Таблица соответствует ожиданиям от вашего первого отзыва.
| Измерение | Минимальный (шлюз + один канал или CLI) | Многоканальный инкрементный |
|---|---|---|
| Цель | Проверка процесса, анализ конфигурации, выход LLM, базовые навыки | Проверка маршрутизации, ротации токенов, изоляции одновременных сеансов |
| Поверхность конфигурации | Мало переменных окружения, неглубокий YAML | Множество вебхуков/токенов; поверхность ошибок быстро растет |
| Порядок сортировки | Сначала журналы шлюза и доктор, затем модель API | Отделяйте ошибки канала от ошибок агента |
| Стоимость отката | Низкий — прокомментируйте один адаптер и дифф | Высокий — сохранять снимки для каждого канала. |
| Лучшее для | Строители-новички и небольшие команды | Команды с Runbooks отправляются в производство |
Стабилизировать простаивающий шлюз перед адаптерами; изменение порядка объединяет три класса ошибок в один поток журнала.
Эти шаги изолируютсбой на уровне процесса(выход при загрузке, плохая конфигурация, занятые порты). Если процесс работоспособен, но сообщения не приходят, адаптеры отлаживают только после того, как шлюз станет зеленым. Интерфейсы командной строки сообщества часто поставляютсяopenclaw doctor(или вариант исправления) — замените точную подкоманду из примечаний к выпуску.
Заморозьте команду воспроизведения:Запишите в заявке сценарий npm, глобальный CLI, pm2 и cwd.
Запустите самопроверку среды:Выполнятьopenclaw doctor, заархивируйте полный вывод и обведите пути к узлам, отказы в разрешениях, отсутствующие данные и ошибки схемы.
Проверка конфигураций по слоям:Проанализируйте YAML/JSON, затем убедитесь, что переменные env не переопределяются профилями оболочки.
Проверьте слушателей:Убедитесь, что порты Dashboard и Gateway свободны; обратите внимание на особенности VPN при обратной связи.
Запишите первые 200 строк журнала:Идите вверх от первой ОШИБКИ — основные причины часто появляются раньше в виде предупреждений.
Минимальный тест отката:Отключите дополнительные адаптеры и сторонние навыки, сохраните один официальный образец, а затем восстановите пополам.
cd /path/to/openclaw node -v npm -v openclaw doctor openclaw doctor --fix npm run start 2>&1 | tee /tmp/openclaw-boot.log lsof -nP -iTCP -sTCP:LISTEN | grep -E '3000|8787'
Кончик: doctor --fixизменяет локальные файлы конфигурации — снимки или запускает контроль изменений перед использованием на производственных узлах.
Используйте это как дежурную чит-карту: сопоставьте симптом, выполните первое действие и только потом расширяйте поиск. Если три прохода не увенчались успехом, вернитесь к третьему разделу для получения полных бревен и разделите их пополам.
| Симптом | Вероятная причина | Первое действие |
|---|---|---|
| Немедленный выход, без стека | Несоответствие узла или неправильный двоичный файл в PATH | Выровняйте узел nvm/pm2; повторный прием врача |
| Ошибки анализа YAML/JSON | Отступы, кодирование, слияние мусора | Проверить синтаксис; восстановить минимальную конфигурацию |
| Порт уже используется | Зомби-процесс или конфликтующий демон | lsof, освободи порт или измени его |
| Тайм-ауты LLM/ошибки TLS | Прокси, DNS, корпоративный MITM | выходной тест скручивания; цепочка доверия / HTTPS_PROXY |
| Аутентификация канала не удалась, пока процесс существует | Токен с истекшим сроком действия или URL-адрес веб-перехватчика смещаются. | Ротация секретов; проверить хост обратного вызова |
| AgentSkill EACCES | Разрешения файловой системы или песочница | Фиксировать право собственности; сценарии аудита навыков |
Предупреждение:Избегайте повторяющихсяsudo npm install -gбез понимания модели процесса — глобальные переменные могут сообщать об «установленном», в то время как среда выполнения по-прежнему разрешает неправильное дерево модулей.
Пожаротушение установок и долгосрочная надежность — смежные дисциплины: первая оптимизирует воспроизводимый холодный запуск, вторая оптимизирует восстановление после сбоев и возможность проверки. Эти измеримые подсказки помогают проверять, не заменяя исходную документацию.
Когда ноутбуки не могут встретитьсябез присмотраинулевой диалогтребования, самопроверка в облаке, добавление политики перезапуска Guardian, доступ к информационной панели и ротация журналов — скопируйте рабочие привязки изруководство по постоянному облаку.
Напоминание о безопасности:Никогда не вставляйте полностью.envфайлы в чат; использовать истекающие секретные каналы и отзыв документов.
Ноутбуки, совмещающие спящий режим, обновления и общие сеансы, вносят случайность, которую рабочие установки не могут исправить. Выделенные облачные узлы Mac, расположенные в разных регионах, упрощают «загрузку каждый день», чем «загрузку при открытой крышке». Для команд, внедряющих OpenClaw в стандарты доставки:Аренда облака VpsMesh Mac Mini обычно предпочтительнее.: родной Apple Silicon, металл 24/7, гибкие окна аренды — тратьте циклы на логику шлюза, а не на состояние машины.
Обычноcwd дрифтилипереопределения окружения: pm2/systemd загружает другой путь, чем ваша интерактивная оболочка. Захватите argv и cwd из третьего раздела, прежде чем снова довериться врачу.
Heartbeat и автоматические соглашения об уровне обслуживания редко переживают ноутбуки. Прочтитеруководство по постоянному развертыванию, затем используйтестраница заказаистраница цендля регионов.
Начните сСправочный центрдля тем SSH/VNC; сохраняйте выходные данные врача и журналы загрузки для дальнейшего развития.