> ## 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.

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

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

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

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

* `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` для сообщений инструментов.
* При выполнении в **изолированной (sandboxed)** сессии агента инструменты сессий по умолчанию используют **видимость только порождённых** (см. ниже).

Форма строки (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` (путь по принципу best‑effort, производный от каталога хранилища + sessionId)
* `messages?` (только когда `messageLimit > 0`)

## sessions\_history

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

Параметры:

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

Поведение:

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

## 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 }`.
* Объявление о доставке выполняется после завершения основного запуска и является best‑effort; `status: "ok"` не гарантирует доставку объявления.
* Ожидание выполняется через `agent.wait` шлюза (на стороне сервера), поэтому переподключения не прерывают ожидание.
* Для основного запуска внедряется контекст сообщения «агент‑к‑агенту».
* Межсессионные сообщения сохраняются с `message.provenance.kind = "inter_session"`, чтобы средства чтения транскриптов могли отличать маршрутизированные инструкции агента от внешнего пользовательского ввода.
* После завершения цикла OpenClaw выполняет **шаг объявления агент‑к‑агенту** (только целевой агент):
  * Раунды 2+ чередуются между агентом‑запросчиком и целевым агентом.
  * Ответьте ровно `REPLY_SKIP`, чтобы остановить «пинг‑понг».
  * Максимальное число ходов — `session.agentToAgent.maxPingPongTurns` (0–5, по умолчанию 5).
* После завершения основного запуска OpenClaw выполняет **цикл обратных ответов**:
  * Ответьте ровно `ANNOUNCE_SKIP`, чтобы сохранить тишину.
  * Любой другой ответ отправляется в целевой канал.
  * Шаг объявления включает исходный запрос + ответ раунда 1 + последний ответ «пинг‑понга».

## Поле канала

* Для групп `channel` — это канал, записанный в записи сессии.
* Для прямых чатов `channel` сопоставляется из `lastChannel`.
* Для cron/хуков/узлов `channel` — это `internal`.
* Если отсутствует, `channel` — это `unknown`.

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

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "session": {
    "sendPolicy": {
      "rules": [
        {
          "match": { "channel": "discord", "chatType": "group" },
          "action": "deny"
        }
      ],
      "default": "allow"
    }
  }
}
```

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

* `sendPolicy: "allow" | "deny"` (unset = наследовать конфиг)
* Устанавливается через `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` (`["*"]` — разрешить любые). По умолчанию: только агент‑запросчик.

Discovery:

* Используйте `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, путь к транскрипту и необязательную стоимость).

## Видимость сессий в Sandbox

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

Конфиг:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      sandbox: {
        // default: "spawned"
        sessionToolsVisibility: "spawned", // or "all"
      },
    },
  },
}
```