Основы

Цикл агента

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

Точки входа

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

Как это работает (общий обзор)

  1. RPC agent проверяет параметры, разрешает сессию (sessionKey/sessionId), сохраняет метаданные сессии и немедленно возвращает { runId, acceptedAt }.
  2. agentCommand запускает агента:
    • определяет модель и значения по умолчанию для мышления/подробного вывода
    • загружает снимок навыков
    • вызывает 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), которые питают эту систему полос. См. Очередь команд.

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

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

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

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

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

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

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

Внутренние хуки (хуки шлюза)

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

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

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

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

  • before_model_resolve: выполняется до создания сессии (без messages), чтобы детерминированно переопределить провайдера/модель перед разрешением модели.
  • before_prompt_build: выполняется после загрузки сессии (с messages), чтобы внедрить prependContext, systemPrompt, prependSystemContext или appendSystemContext перед отправкой промпта. Используйте prependContext для динамического текста на каждый ход, а поля system-context — для стабильных инструкций, которые должны находиться в пространстве системного промпта.
  • 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: события жизненного цикла шлюза.

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

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

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

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

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

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

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

Сжатие и повторные попытки

  • Автосжатие генерирует события потока 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 (отмена)
  • Отключение шлюза или таймаут RPC
  • Таймаут agent.wait (только ожидание, не останавливает агента)

Среда выполнения агентаСистемный промпт