​

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

​

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

• 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>, если явно не задано иное.

​

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

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

​

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

{
  "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 (["*"] — разрешить любые). По умолчанию: только агент‑запросчик.

• Используйте 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

{
  agents: {
    defaults: {
      sandbox: {
        // default: "spawned"
        sessionToolsVisibility: "spawned", // or "all"
      },
    },
  },
}