Агентный цикл (OpenClaw)¶

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

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

Точки входа¶

• RPC шлюза Gateway: agent и agent.wait.
• CLI: команда agent.

Как это работает (в общих чертах)¶

1. RPC agent проверяет параметры, разрешает сеанс (sessionKey/sessionId), сохраняет метаданные сеанса и немедленно возвращает { runId, acceptedAt }.
2. agentCommand запускает агента: - разрешает модель и значения по умолчанию для thinking/verbose - загружает снимок Skills - вызывает runEmbeddedPiAgent (рантайм pi-agent-core) - испускает lifecycle end/error, если встроенный цикл сам его не испустил
3. runEmbeddedPiAgent: - сериализует прогоны через очереди на уровне сеанса и глобальную очередь - разрешает модель и профиль аутентификации и строит сеанс pi - подписывается на события pi и стримит дельты ассистента/инструментов - применяет тайм-аут → прерывает прогон при превышении - возвращает полезные данные и метаданные использования
4. subscribeEmbeddedPiSession связывает события pi-agent-core с потоком OpenClaw agent: - события инструментов => stream: "tool" - дельты ассистента => 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), которые подпитывают эту систему полос. См. Command Queue.

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

• Рабочее пространство разрешается и создаётся; изолированные (sandboxed) прогоны могут перенаправляться в корень рабочего пространства sandbox.
• Skills загружаются (или переиспользуются из снимка) и внедряются в env и prompt.
• Bootstrap/контекстные файлы разрешаются и внедряются в отчёт системного prompt.
• Захватывается блокировка записи сеанса; SessionManager открывается и подготавливается до начала стриминга.

Сборка prompt и системный prompt¶

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

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

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

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

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

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

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

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

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

• before_agent_start: внедряет контекст или переопределяет системный prompt до начала прогона.
• 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: события жизненного цикла шлюза.

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

Потоковое и частичные ответы¶

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

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

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

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

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

Компакт + повторы¶

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

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

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

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

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

Тайм-ауты¶

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

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

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