Восстановление после перезапуска

Перезапуск Gateway не приводит к потере состояния агента. Диалоги, транскрипты, запланированные задания, записи фоновых задач и исходящие сообщения в очереди хранятся на диске, а работа, прерванная во время хода, обнаруживается и автоматически возобновляется после повторного запуска Gateway. Ручное вмешательство не требуется, и настраивать ничего не нужно: восстановление включено всегда.

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

Что сохраняется после перезапуска

При корректном перезапуске сначала ожидается завершение работы

Запрошенный перезапуск (openclaw gateway restart, изменение конфигурации, требующее перезапуска, или обновление Gateway) не прерывает выполняющуюся работу немедленно. Gateway прекращает принимать новую работу, а затем ожидает завершения активных ходов агента и фоновых задач в пределах периода ожидания (по умолчанию 5 минут). Поэтому в большинстве случаев при перезапуске ничего не прерывается.

Прерывается только работа, которую невозможно завершить за период ожидания (либо любой запуск, прерванный принудительным перезапуском или сбоем), — и перед этим каждый затронутый сеанс помечается для восстановления.

Как обнаруживается прерванная работа

Сеансы с незавершённым ходом помечаются тремя взаимодополняющими механизмами:

• При допуске хода: для обычного текстового хода в существующем основном сеансе Gateway добавляет сообщение пользователя, помечает сеанс как выполняющийся и записывает заявку на доставку при восстановлении в одной транзакции SQLite до выполнения модели или перехватчика before_agent_reply. Control UI делает это до возврата подтверждения started; диспетчеризация канала — когда подготовленный ход принимает запуск агента. Команды, вложения, переопределения для отдельного хода, ожидающие доставки, предыдущие признаки прерывания, сеансы, принадлежащие плагинам, и ходы с перехватчиками выполнения сохраняют свои специализированные пути допуска. Если установлен перехватчик before_agent_reply, при допуске также записывается его фаза. Восстановление никогда не воспроизводит перехватчик, прерванный во время вызова. После завершения необработанного перехватчика его контрольная точка фиксирует результат, но восстановление по-прежнему завершается безопасным отказом, пока этот перехватчик активен: контрольная точка не может подтвердить, что после перезапуска загружены тот же код и та же конфигурация плагина. Обработанные текстовые результаты и результаты без вывода сохраняются в отдельных контрольных точках для детерминированного завершения. Постоянные заявки на восстановление, записанные старыми версиями, не содержат маркера принадлежности источнику, поэтому при обновлении к ним применяется та же проверка перехватчика с безопасным отказом.
• При завершении работы: во время ожидания перед перезапуском каждый сеанс с активным запуском получает маркер восстановления в хранилище сеансов до прерывания запуска.
• При запуске: Gateway сканирует хранилища сеансов на наличие сеансов, которые всё ещё считаются выполняющимися, но не имеют активного владельца в новом процессе. Это позволяет обнаружить аварийные завершения и принудительные остановки, при которых код завершения работы не выполнялся. Одновременно удаляются устаревшие файлы блокировки транскриптов.

Автоматическое возобновление

Через несколько секунд после запуска Gateway повторно диспетчеризует каждый помеченный сеанс с синтетическим системным сообщением, которое уведомляет агента, что его предыдущий ход был прерван перезапуском и работу следует продолжить с существующего транскрипта. Если окончательный ответ уже был создан, но не доставлен, его текст включается в сообщение, чтобы агент мог доставить его вместо повторного выполнения работы. Восстановление выполняет до 3 попыток с экспоненциальной задержкой. Для каждой попытки повторно используется один постоянный идентификатор диспетчеризации, поэтому неоднозначный сбой подключения не может дважды запустить одно и то же восстановление. Для завершённых и невозобновляемых ходов Control UI также сохраняются ограниченные по сроку постоянные маркеры идемпотентности, позволяющие повторно подключившейся очереди исходящих сообщений удалить их без повторного выполнения запроса.

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

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

Перед возобновлением Gateway проверяет, можно ли безопасно продолжить с конца транскрипта. Если нельзя (например, ход завершился на устаревшем ожидающем подтверждении), сеанс не запускается повторно вслепую; вместо этого агент публикует краткое уведомление с просьбой повторно отправить последний запрос. Для WebChat это уведомление записывается непосредственно в историю сеанса, чтобы оно оставалось видимым после повторного подключения.

OpenClaw также может реконструировать прерванную работу Code Mode, доступную только для чтения. Code Mode помечает такие запуски как безопасные при перезапуске и отклоняет инструменты каталога или пространства имён плагинов с побочными эффектами до их выполнения. Если перезапуск происходит на элементе управления wait, новый Gateway реконструирует ход по его транскрипту и принудительно сохраняет безопасность реконструированного выполнения при перезапуске, даже если модель опускает или сбрасывает этот флаг. Хост ограничивает весь реконструированный ход проверенными основными инструментами только для чтения и инструментами плагинов, явно безопасными для повторного выполнения, в том числе если Code Mode отключён после перезапуска. Работа с побочными эффектами по-прежнему защищается уведомлением о необходимости повторной отправки, чтобы не допустить дублирующую запись.

Субагенты

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

• Запуски, прерванные более 2 часов назад, завершаются вместо возобновления, чтобы Gateway, не работавший всю ночь, не возобновлял устаревшую работу.
• Сеанс, который многократно не удаётся восстановить, помечается постоянным маркером как зависший, чтобы восстановление не зациклилось навсегда.

Фоновые задачи

Реестр фоновых задач использует SQLite и согласуется при загрузке и через регулярные интервалы: постоянные результаты, записанные завершёнными запусками, восстанавливаются, а запуски, процесс-владелец которых исчез, после льготного периода помечаются как утраченные, а не остаются зависшими навсегда.

Перезапуски по запросу агента

Когда агент сам инициирует перезапуск (применяя изменение конфигурации, обновляя Gateway или явно запрашивая перезапуск), перед завершением процесса в SQLite записывается маркер перезапуска. После загрузки Gateway публикует результат в исходном чате и диспетчеризует одноразовый ход продолжения, чтобы агент продолжил точно с места остановки в том же канале и ветке.

Предохранительные механизмы и наблюдаемость

• Прерыватель цикла сбоев: 3 некорректных загрузки в течение 5 минут активируют прерыватель, который подавляет автоматический запуск вспомогательных служб при следующей загрузке, чтобы сбой Gateway не усиливал сам себя. Нормальная работа восстанавливается после истечения окна некорректных загрузок.
• Метрики: активность восстановления экспортируется через Prometheus как openclaw_session_recovery_total и openclaw_session_recovery_age_seconds.
• Журналы: решения о восстановлении записываются в подсистемах main-session-restart-recovery и subagent-interrupted-resume.

Что не возобновляется

• Сеансы, исключённые из восстановления основного сеанса, поскольку ими уже управляет другой владелец: сеансы субагентов (восстановление субагентов), сеансы cron (планировщик повторно запускает их по расписанию) и сеансы под управлением ACP (возобновлением управляет подключённая IDE или клиент).
• Сеансы, которые невозможно безопасно продолжить с конца транскрипта; вместо скрытого повторного запуска они получают описанное выше уведомление о необходимости повторной отправки.
• Работа, которая так и не была допущена: сообщения, поступающие в период ожидания перед перезапуском, отклоняются с явной ошибкой перезапуска, а не молча помещаются в очередь завершающегося процесса.