> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Агентный цикл

# Агентный цикл (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](/concepts/queue).

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

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

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

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

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

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

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

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

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

См. [Hooks](/automation/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](/tools/plugin#plugin-hooks) для API хуков и деталей регистрации.

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

* Дельты ассистента стримятся из pi-agent-core и испускаются как события `assistant`.
* Потоковая передача блоками может испускать частичные ответы либо на `text_end`, либо на `message_end`.
* Стриминг рассуждений может испускаться как отдельный поток или как ответы блоками.
* См. [Streaming](/concepts/streaming) для поведения чанков и блоковых ответов.

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

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

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

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

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

* Автоуплотнение испускает события потока `compaction` и может инициировать повтор.
* При повторе буферы в памяти и сводки инструментов сбрасываются, чтобы избежать дублирования вывода.
* [Compaction](/concepts/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` (только ожидание, агент не останавливается)