​

Агентный цикл (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 (только ожидание, агент не останавливается)