Инструменты сеанса

OpenClaw предоставляет агентам инструменты для работы между сеансами, проверки состояния и оркестрации субагентов.

Доступные инструменты

На эти инструменты по-прежнему распространяются активный профиль инструментов и политика разрешений и запретов. tools.profile: "coding" включает полный набор средств оркестрации сеансов, в том числе sessions_spawn, sessions_yield и subagents. tools.profile: "messaging" включает инструменты обмена сообщениями между сеансами (sessions_list, sessions_history, sessions_send, session_status), но не включает создание субагентов. Чтобы сохранить профиль обмена сообщениями и при этом разрешить встроенное делегирование, добавьте:

{  tools: {    profile: "messaging",    alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],  },}

Политики групп, провайдеров, песочницы и отдельных агентов всё ещё могут удалить эти инструменты после применения профиля. Используйте /tools в затронутом сеансе, чтобы проверить фактический список инструментов.

Просмотр списка и чтение сеансов

sessions_list возвращает сеансы с их ключом, agentId, типом, каналом, моделью, количеством токенов и временными метками. Фильтровать можно по kinds (массив; допустимые значения: main, group, cron, hook, node, other), точному значению label, точному значению agentId, тексту search или давности (activeMinutes). По умолчанию возвращаются активные сеансы; передайте archived: true, чтобы вместо них просмотреть архивные сеансы. Строки содержат состояние pinned и archived. Задайте includeDerivedTitles, includeLastMessage или messageLimit (не более 20), когда требуется разбор в стиле почтового ящика: производный заголовок с учётом области видимости, фрагмент предварительного просмотра последнего сообщения или ограниченный набор недавних сообщений в каждой строке. Производные заголовки и предварительные просмотры создаются только для сеансов, которые вызывающая сторона уже может видеть согласно настроенной политике видимости инструментов сеанса, поэтому посторонние сеансы остаются скрытыми. При ограниченной видимости sessions_list возвращает необязательные метаданные visibility, показывающие фактический режим и предупреждение о том, что результаты могут быть ограничены областью видимости.

sessions_history получает расшифровку разговора для конкретного сеанса. По умолчанию результаты инструментов исключаются; передайте includeTools: true, чтобы увидеть их. Используйте limit для получения ограниченного фрагмента с самыми новыми записями. Передайте offset: 0, если нужны метаданные пагинации, а затем передавайте возвращённые значения nextOffset, чтобы постранично перемещаться назад по более старым окнам расшифровки OpenClaw без чтения необработанных файлов расшифровок. Страницы с явно заданным смещением не объединяются с резервными импортами из внешнего CLI; когда требуется объединённая отображаемая история, используйте стандартное представление с новейшим фрагментом (без offset).

Возвращаемое представление намеренно ограничено и проходит фильтрацию безопасности:

• текст ассистента нормализуется перед повторным использованием:
  • теги размышлений удаляются
  • служебные блоки <relevant-memories> / <relevant_memories> удаляются
  • XML-блоки полезной нагрузки вызовов инструментов в виде обычного текста, например <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls> и <function_calls>...</function_calls>, удаляются, включая усечённые полезные нагрузки без корректного закрытия
  • служебные конструкции вызовов и результатов инструментов пониженного формата, например [Tool Call: ...], [Tool Result ...] и [Historical context ...], удаляются
  • утёкшие управляющие токены модели, например <|assistant|>, другие ASCII-токены <|...|> и полноширинные варианты <｜...｜>, удаляются
  • некорректный XML вызовов инструментов MiniMax, например <invoke ...> / </minimax:tool_call>, удаляется
• текст, похожий на учётные данные или токены, скрывается перед возвратом
• длинные текстовые блоки усекаются
• в очень больших историях старые строки могут быть отброшены, а чрезмерно большая строка — заменена на [sessions_history omitted: message too large]
• инструмент сообщает итоговые флаги, например truncated, droppedMessages, contentTruncated, contentRedacted, bytes, а также метаданные пагинации

Оба инструмента принимают либо ключ сеанса (например, "main"), либо идентификатор сеанса из предыдущего вызова списка.

Если нужна точная необработанная расшифровка, изучите строки расшифровки в SQLite с соответствующей областью видимости, а не рассматривайте sessions_history как нефильтрованный дамп.

Отправка сообщений между сеансами

sessions_send доставляет сообщение в другой сеанс и при необходимости ожидает ответа:

• Отправка без ожидания: задайте timeoutSeconds: 0, чтобы поставить сообщение в очередь и немедленно продолжить работу.
• Ожидание ответа: задайте время ожидания и получите ответ непосредственно в результате.

Сеансы чатов, привязанные к веткам, например с ключами, оканчивающимися на :thread:<id>, нельзя использовать в качестве целей sessions_send. Для координации между агентами используйте ключ родительского сеанса канала, чтобы сообщения, направляемые инструментами, не появлялись внутри активной ветки, предназначенной для взаимодействия с человеком.

Сообщения и последующие ответы A2A помечаются как межсеансовые данные во входном запросе получающего агента ([Inter-session message ... isUser=false]) и в данных о происхождении расшифровки. Получающий агент должен рассматривать их как данные, направленные инструментом, а не как инструкцию, написанную непосредственно конечным пользователем.

После ответа целевого агента OpenClaw может запустить цикл ответной переписки, в котором агенты поочерёдно обмениваются сообщениями (до session.agentToAgent.maxPingPongTurns, диапазон 0–20, по умолчанию 5). Целевой агент может ответить REPLY_SKIP, чтобы завершить цикл досрочно.

Передайте watch: true, чтобы также зарегистрировать отправителя как наблюдателя за изменениями состояния целевого сеанса: когда другой участник позднее отправляет целевому сеансу прямое сообщение от человека или изменяет его цель, отправитель получает системное уведомление, указывающее на session_status changesSince. Регистрация происходит после успешной отправки, относится к сеансу, фактически получившему сообщение, и начинается с его текущей версии состояния, поэтому уведомления создаются только для последующих изменений. Результат содержит watched: true, если регистрация прошла успешно. См. Осведомлённость о состоянии сеанса.

Вспомогательные средства состояния и оркестрации

session_status — облегчённый инструмент, эквивалентный /status, для текущего или другого видимого сеанса. Он сообщает сведения об использовании, времени, состоянии модели и среды выполнения, а также контекст связанных фоновых задач при его наличии. Как и /status, он может дополнить неполные счётчики токенов и кеша данными из последней записи об использовании в расшифровке, а model=default удаляет переопределение для отдельного сеанса. Используйте sessionKey="current" для текущего сеанса вызывающей стороны; видимые клиентские метки, например openclaw-tui, не являются ключами сеансов.

При наличии метаданных маршрута session_status также включает видимый JSON-блок Route context и соответствующие структурированные поля details. Эти поля позволяют отличить ключ сеанса от маршрута, который в данный момент обслуживает активный запуск:

• origin указывает, где был создан сеанс, либо провайдера, определённого по префиксу ключа сеанса, допускающего доставку, если в старом состоянии отсутствуют сохранённые метаданные происхождения.
• active — текущий маршрут активного запуска. Он сообщается только для активного или текущего сеанса, обрабатываемого сейчас.
• deliveryContext — сохранённый маршрут доставки сеанса, который OpenClaw может повторно использовать для последующей доставки, даже если активная поверхность отличается.

Изменения состояния сеанса

OpenClaw ведёт долговечный журнал сигналов о существенных изменениях состояния сеансов (прямые сообщения от людей наблюдаемым сеансам, результаты дочерних запусков, изменения целей, Compaction). Строки sessions_list и session_status предоставляют stateVersion сеанса, а session_status принимает changesSince: <version>, чтобы вернуть типизированные события после этой версии, причём historyGap точно указывает, что запрошенная версия предшествует сохранённой истории. Наблюдатели — автоматически родители созданных субагентов и явно зарегистрированные через sessions_send watch: true — получают одно объединённое уведомление об устаревшем состоянии, когда другой участник изменяет наблюдаемый сеанс.

Полная модель описана в разделе Осведомлённость о состоянии сеанса: типы событий, регистрация наблюдателей, протокол уведомлений с защитой от спама, процесс согласования и текущие ограничения.

sessions_yield намеренно завершает текущий ход, чтобы следующим сообщением могло стать ожидаемое последующее событие. Используйте его после создания субагентов, если хотите, чтобы результаты завершения пришли следующим сообщением, вместо построения циклов опроса.

subagents — вспомогательное средство видимости для уже созданных субагентов OpenClaw. Оно поддерживает action: "list" для проверки активных и недавних запусков.

Создание субагентов

sessions_spawn по умолчанию создаёт изолированный сеанс для фоновой задачи. Он всегда работает неблокирующим образом и немедленно возвращает runId и childSessionKey. Встроенные запуски субагентов получают делегированную задачу в первом видимом сообщении [Subagent Task] дочернего сеанса, а системный запрос содержит только правила среды выполнения субагента и контекст маршрутизации.

Основные параметры:

• runtime: "subagent" (по умолчанию) или "acp" для агентов внешней среды.
• Переопределения model и thinking для дочернего сеанса.
• thread: true для привязки созданного сеанса к ветке чата (Discord, Slack и т. д.).
• sandbox: "require" для обязательного использования песочницы дочерним сеансом.
• context: "fork" для встроенных субагентов, когда дочернему сеансу нужна расшифровка текущего инициатора запроса; не указывайте этот параметр или используйте context: "isolated", чтобы создать чистый дочерний сеанс. context: "fork" допустим только вместе с runtime: "subagent". Встроенные субагенты, привязанные к ветке, по умолчанию используют context: "fork", если threadBindings.defaultSpawnContext не указывает иное.

Конечные субагенты по умолчанию не получают инструменты сеанса. При maxSpawnDepth >= 2 субагенты-оркестраторы глубины 1 дополнительно получают sessions_spawn, subagents, sessions_list и sessions_history, чтобы управлять собственными дочерними агентами. Конечные запуски по-прежнему не получают инструменты рекурсивной оркестрации.

После завершения этап объявления публикует результат в канале инициатора запроса. Доставка результата сохраняет привязку к ветке или теме, если она доступна, а если источник результата определяет только канал, OpenClaw всё равно может повторно использовать сохранённый маршрут сеанса инициатора (lastChannel / lastTo) для прямой доставки.

Особенности поведения ACP описаны в разделе Агенты ACP.

Видимость

Область действия инструментов сеанса ограничивает доступные агенту данные:

По умолчанию используется tree. Для сеансов в песочнице область видимости ограничивается значением tree независимо от конфигурации.

Дополнительные материалы

• Управление сеансами: маршрутизация, жизненный цикл, обслуживание
• Субагенты: жизненный цикл дочерних сеансов и доставка
• Агенты ACP: запуск внешних сред выполнения
• Мультиагентная система: мультиагентная архитектура
• Конфигурация Gateway: параметры конфигурации инструментов сеанса

Связанные материалы

• Управление сеансами
• Очистка сеансов