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

Цель: небольшой набор инструментов, который трудно неправильно использовать, чтобы агенты могли перечислять сессии, получать историю и отправлять в другую сессию.

Имена инструментов

  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn

Ключевая модель

  • Основной бакет прямого чата всегда буквальный ключ "main" (разрешается в основной ключ текущего агента).
  • Групповые чаты используют agent:<agentId>:<channel>:group:<id> или agent:<agentId>:<channel>:channel:<id> (передайте полный ключ).
  • Задания Cron используют cron:<job.id>.
  • Хуки используют hook:<uuid>, если явно не установлено.
  • Сессии узлов используют node-<nodeId>, если явно не установлено.

global и unknown - зарезервированные значения и никогда не перечисляются. Если session.scope = "global", мы делаем псевдоним для main для всех инструментов, чтобы вызывающие никогда не видели global.

sessions_list

Перечислите сессии как массив строк.

Параметры:

  • kinds?: string[] фильтр: любой из "main" | "group" | "cron" | "hook" | "node" | "other"
  • limit?: number максимум строк (по умолчанию: значение по умолчанию сервера, ограничение например 200)
  • activeMinutes?: number только сессии, обновленные в пределах N минут
  • messageLimit?: number 0 = без сообщений (по умолчанию 0); >0 = включить последние N сообщений

Поведение:

  • messageLimit > 0 получает chat.history для каждой сессии и включает последние N сообщений.
  • Результаты инструментов отфильтровываются в выводе списка; используйте sessions_history для сообщений инструментов.
  • При запуске в изолированной сессии агента инструменты сессии по умолчанию имеют видимость только порожденных (см. ниже).

Форма строки (JSON):

  • key: ключ сессии (string)
  • kind: main | group | cron | hook | node | other
  • channel: whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown
  • displayName (метка отображения группы, если доступна)
  • updatedAt (мс)
  • sessionId
  • model, contextTokens, totalTokens
  • thinkingLevel, verboseLevel, systemSent, abortedLastRun
  • sendPolicy (переопределение сессии, если установлено)
  • lastChannel, lastTo
  • deliveryContext (нормализованный \{ channel, to, accountId \}, когда доступен)
  • transcriptPath (путь наилучшего усилия, полученный из директории хранилища + sessionId)
  • messages? (только когда messageLimit > 0)

sessions_history

Получить транскрипт для одной сессии.

Параметры:

  • sessionKey (обязательно; принимает ключ сессии или sessionId из sessions_list)
  • limit?: number максимум сообщений (сервер ограничивает)
  • includeTools?: boolean (по умолчанию false)

Поведение:

  • includeTools=false фильтрует сообщения role: "toolResult".
  • Возвращает массив сообщений в формате необработанного транскрипта.
  • При указании sessionId OpenClaw разрешает его в соответствующий ключ сессии (отсутствующие ids ошибка).

sessions_send

Отправить сообщение в другую сессию.

Параметры:

  • sessionKey (обязательно; принимает ключ сессии или sessionId из sessions_list)
  • message (обязательно)
  • timeoutSeconds?: number (по умолчанию >0; 0 = fire-and-forget)

Поведение:

  • timeoutSeconds = 0: поставить в очередь и вернуть \{ runId, status: "accepted" \}.
  • timeoutSeconds > 0: ждать до N секунд завершения, затем вернуть \{ runId, status: "ok", reply \}.
  • Если ожидание истекает: \{ runId, status: "timeout", error \}. Запуск продолжается; вызовите sessions_history позже.
  • Если запуск не работает: \{ runId, status: "error", error \}.
  • Запуски доставки объявлений завершаются после завершения основного запуска и являются наилучшим усилием; status: "ok" не гарантирует, что объявление было доставлено.
  • Ожидает через gateway agent.wait (на стороне сервера), поэтому переподключения не сбрасывают ожидание.
  • Контекст сообщения агент-агент внедряется для основного запуска.
  • После завершения основного запуска OpenClaw запускает цикл ответа-обратно:
    • Раунд 2+ чередуется между агентами-запросчиками и целевыми агентами.
    • Ответьте точно REPLY_SKIP, чтобы остановить пинг-понг.
    • Максимум ходов - session.agentToAgent.maxPingPongTurns (0–5, по умолчанию 5).
  • Когда цикл заканчивается, OpenClaw запускает шаг объявления агент-агент (только целевой агент):
    • Ответьте точно ANNOUNCE_SKIP, чтобы остаться молчаливым.
    • Любой другой ответ отправляется в целевой канал.
    • Шаг объявления включает исходный запрос + ответ раунда 1 + последний ответ пинг-понга.

Поле канала

  • Для групп channel - это канал, записанный в записи сессии.
  • Для прямых чатов channel отображается из lastChannel.
  • Для cron/hook/node channel - это internal.
  • Если отсутствует, channel - это unknown.

Безопасность / Политика отправки

Блокировка на основе политики по каналу/типу чата (не по id сессии).

{
  "session": {
    "sendPolicy": {
      "rules": [
        {
          "match": { "channel": "discord", "chatType": "group" },
          "action": "deny"
        }
      ],
      "default": "allow"
    }
  }
}

Переопределение времени выполнения (для каждой записи сессии):

  • sendPolicy: "allow" | "deny" (не установлено = наследовать конфигурацию)
  • Устанавливается через sessions.patch или только для владельца /send on|off|inherit (автономное сообщение).

Точки принудительного применения:

  • chat.send / agent (gateway)
  • логика доставки автоответа

sessions_spawn

Запустите запуск субагента в изолированной сессии и объявите результат обратно в канал чата запросчика.

Параметры:

  • task (обязательно)
  • label? (необязательно; используется для журналов/UI)
  • agentId? (необязательно; запустить под другим id агента, если разрешено)
  • model? (необязательно; переопределяет модель субагента; недопустимые значения ошибка)
  • runTimeoutSeconds? (по умолчанию 0; когда установлено, прерывает запуск субагента через N секунд)
  • cleanup? (delete|keep, по умолчанию keep)

Список разрешений:

  • agents.list[].subagents.allowAgents: список id агентов, разрешенных через agentId (["*"], чтобы разрешить любой). По умолчанию: только агент-запросчик.

Обнаружение:

  • Используйте agents_list, чтобы обнаружить, какие id агентов разрешены для sessions_spawn.

Поведение:

  • Запускает новую сессию agent:<agentId>:subagent:<uuid> с deliver: false.
  • Субагенты по умолчанию имеют полный набор инструментов минус инструменты сессии (настраивается через tools.subagents.tools).
  • Субагентам не разрешено вызывать sessions_spawn (без порождения субагент → субагент).
  • Всегда неблокирующий: немедленно возвращает \{ status: "accepted", runId, childSessionKey \}.
  • После завершения OpenClaw запускает шаг объявления субагента и публикует результат в канал чата запросчика.
  • Ответьте точно ANNOUNCE_SKIP во время шага объявления, чтобы остаться молчаливым.
  • Ответы объявлений нормализуются в Status/Result/Notes; Status берется из результата времени выполнения (не текста модели).
  • Сессии субагентов автоматически архивируются после agents.defaults.subagents.archiveAfterMinutes (по умолчанию: 60).
  • Ответы объявлений включают строку статистики (время выполнения, токены, sessionKey/sessionId, путь транскрипта и необязательную стоимость).

Видимость сессии песочницы

Изолированные сессии могут использовать инструменты сессии, но по умолчанию они видят только сессии, которые они породили через sessions_spawn.

Конфигурация:

{
  agents: {
    defaults: {
      sandbox: {
        // по умолчанию: "spawned"
        sessionToolsVisibility: "spawned" // или "all"
      }
    }
  }
}
← Назад к документации