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

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, типом, каналом, моделью, счетчиками токенов и временными метками. Фильтруйте по типу (main, group, cron, hook, node), точному label, точному agentId, тексту поиска или давности (activeMinutes). Когда нужна сортировка в стиле почтового ящика, инструмент также может запросить производный заголовок в рамках области видимости, фрагмент предпросмотра последнего сообщения или ограниченное число недавних сообщений в каждой строке. Производные заголовки и предпросмотры создаются только для сеансов, которые вызывающий уже может видеть согласно настроенной политике видимости инструментов сеанса, поэтому несвязанные сеансы остаются скрытыми. Когда видимость ограничена, sessions_list возвращает необязательные метаданные visibility, показывающие фактический режим и предупреждение о том, что результаты могут быть ограничены областью видимости.

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

• текст ассистента нормализуется перед восстановлением:
  • теги размышлений удаляются
  • служебные блоки <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"), либо ID сеанса из предыдущего вызова списка.

Если нужна точная побайтовая стенограмма, проверяйте файл стенограммы на диске, а не рассматривайте sessions_history как необработанный дамп.

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

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

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

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

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

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

Помощники статуса и координации

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

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

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

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", если threadBindings.defaultSpawnContext не задает иное.

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

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

О поведении, специфичном для ACP, см. Агенты ACP.

Видимость

Инструменты сеанса ограничены областью видимости того, что агент может видеть:

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

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

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

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

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