Цикл агента (OpenClaw)

Агентский цикл — это полный "настоящий" запуск агента: прием → сборка контекста → вывод модели → выполнение инструментов → потоковые ответы → сохранение. Это авторитетный путь, который превращает сообщение в действия и финальный ответ, сохраняя консистентность состояния сессии.

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

Точки входа

• Gateway RPC: agent и agent.wait.
• CLI: команда agent.

Как это работает (высокоуровнево)

1. RPC agent валидирует параметры, определяет сессию (sessionKey/sessionId), сохраняет метаданные сессии, немедленно возвращает { runId, acceptedAt }.
2. agentCommand запускает агента:
   • определяет модель + значения thinking/verbose по умолчанию
   • загружает снапшот навыков
   • вызывает runEmbeddedPiAgent (среда выполнения pi-agent-core)
   • генерирует lifecycle end/error, если встроенный цикл не сгенерировал его
3. runEmbeddedPiAgent:
   • сериализует запуски через очереди на уровне сессии и глобальные очереди
   • определяет модель + профиль аутентификации и строит pi-сессию
   • подписывается на pi-события и передает дельты assistant/tool
   • применяет таймаут -> прерывает запуск при превышении
   • возвращает пейлоады + метаданные использования
4. subscribeEmbeddedPiSession связывает события pi-agent-core с потоком OpenClaw agent:
   • события инструментов => stream: "tool"
   • дельты assistant => stream: "assistant"
   • события жизненного цикла => stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait использует waitForAgentJob:
   • ожидает lifecycle end/error для runId
   • возвращает { status: ok|error|timeout, startedAt, endedAt, error? }

Очереди + конкуренция

• Запуски сериализуются по ключу сессии (линия сессии) и опционально через глобальную линию.
• Это предотвращает гонки инструментов/сессий и сохраняет консистентность истории сессии.
• Каналы сообщений могут выбирать режимы очереди (collect/steer/followup), которые питают эту систему линий. См. Очередь команд.

Подготовка сессии + рабочего пространства

• Рабочее пространство определяется и создается; песочные запуски могут перенаправляться в корень рабочего пространства песочницы.
• Навыки загружаются (или используются из снапшота) и внедряются в env и промпт.
• Файлы bootstrap/context определяются и внедряются в отчет системного промпта.
• Получается блокировка записи сессии; SessionManager открывается и подготавливается перед потоковой передачей.

Сборка промпта + системный промпт

• Системный промпт строится из базового промпта OpenClaw, промпта навыков, контекста bootstrap и переопределений для конкретного запуска.
• Применяются лимиты для конкретной модели и резервные токены для компактификации.
• См. Системный промпт для того, что видит модель.

Точки перехвата (где можно перехватить)

OpenClaw имеет две системы хуков:

• Внутренние хуки (Gateway hooks): скрипты, управляемые событиями для команд и событий жизненного цикла.
• Хуки плагинов: точки расширения внутри жизненного цикла агента/инструментов и конвейера gateway.

Внутренние хуки (Gateway hooks)

• agent:bootstrap: выполняется при создании файлов bootstrap перед финализацией системного промпта. Используйте это для добавления/удаления файлов контекста bootstrap.
• Хуки команд: /new, /reset, /stop и другие события команд (см. документацию Hooks).

См. Hooks для настройки и примеров.

Хуки плагинов (жизненный цикл агента + gateway)

Они выполняются внутри цикла агента или конвейера gateway:

• before_agent_start: внедрение контекста или переопределение системного промпта перед началом запуска.
• agent_end: проверка финального списка сообщений и метаданных запуска после завершения.
• before_compaction / after_compaction: наблюдение или аннотирование циклов компактификации.
• before_tool_call / after_tool_call: перехват параметров/результатов инструментов.
• tool_result_persist: синхронное преобразование результатов инструментов перед записью в транскрипт сессии.
• message_received / message_sending / message_sent: хуки входящих + исходящих сообщений.
• session_start / session_end: границы жизненного цикла сессии.
• gateway_start / gateway_stop: события жизненного цикла gateway.

См. Плагины для API хуков и деталей регистрации.

Потоковая передача + частичные ответы

• Дельты assistant передаются из pi-agent-core и генерируются как события assistant.
• Потоковая передача блоков может генерировать частичные ответы либо на text_end, либо на message_end.
• Потоковая передача reasoning может быть отправлена как отдельный поток или как блочные ответы.
• См. Потоковая передача для поведения чанкинга и блочных ответов.

Выполнение инструментов + инструменты сообщений

• События начала/обновления/завершения инструментов генерируются в потоке tool.
• Результаты инструментов санитизируются по размеру и пейлоадам изображений перед логированием/генерацией.
• Отправки инструментов сообщений отслеживаются для подавления дубликатов подтверждений assistant.

Формирование ответа + подавление

• Финальные пейлоады собираются из:
  • текста assistant (и опциональных рассуждений)
  • встроенных сводок инструментов (когда verbose + разрешено)
  • текста ошибки assistant при ошибке модели
• NO_REPLY обрабатывается как тихий токен и фильтруется из исходящих пейлоадов.
• Дубликаты инструментов сообщений удаляются из финального списка пейлоадов.
• Если не осталось рендерируемых пейлоадов и инструмент выдал ошибку, генерируется резервный ответ об ошибке инструмента (если только инструмент сообщений уже не отправил видимый пользователю ответ).

Компактификация + повторы

• Автокомпактификация генерирует события потока compaction и может вызвать повтор.
• При повторе буферы в памяти и сводки инструментов сбрасываются, чтобы избежать дублирования вывода.
• См. Компактификация для конвейера компактификации.

Потоки событий (на сегодня)

• lifecycle: генерируется subscribeEmbeddedPiSession (и как резерв agentCommand)
• assistant: потоковые дельты из pi-agent-core
• tool: потоковые события инструментов из pi-agent-core

Обработка чат-канала

• Дельты assistant буферизуются в чат-сообщения delta.
• Чат-сообщение final генерируется на lifecycle end/error.

Таймауты

• agent.wait по умолчанию: 30с (только ожидание). Параметр timeoutMs переопределяет.
• Среда выполнения агента: agents.defaults.timeoutSeconds по умолчанию 600с; применяется в таймере прерывания runEmbeddedPiAgent.

Где может завершиться рано

• Таймаут агента (прерывание)
• AbortSignal (отмена)
• Отключение Gateway или таймаут RPC
• Таймаут agent.wait (только ожидание, не останавливает агента)