Herramientas de Sesión

Objetivo: conjunto de herramientas pequeño y difícil de usar incorrectamente para que los agentes puedan listar sesiones, obtener historial y enviar a otra sesión.

- ''sessions_list''

- ''sessions_history''

- ''sessions_send''

- ''sessions_spawn''

- El bucket principal de chat directo siempre es la clave literal ''"main"'' (resuelta a la clave principal del agente actual).

- Los chats grupales usan ''agent:<agentId>:<channel>:group:<id>'' o ''agent:<agentId>:<channel>:channel:<id>'' (pasa la clave completa).

- Los trabajos cron usan ''cron:<job.id>''.

- Los hooks usan ''hook:<uuid>'' a menos que se establezca explícitamente.

- Las sesiones de nodo usan ''node-<nodeId>'' a menos que se establezca explícitamente.

''global'' y ''unknown'' son valores reservados y nunca se listan. Si ''session.scope = "global"'', lo aliasamos a ''main'' para todas las herramientas para que los llamadores nunca vean ''global''.

Lista sesiones como un array de filas.

Parámetros:

- ''kinds?: string[]'' filtro: cualquiera de ''"main" | "group" | "cron" | "hook" | "node" | "other"''

- ''limit?: number'' máx filas (predeterminado: predeterminado del servidor, límite ej. 200)

- ''activeMinutes?: number'' solo sesiones actualizadas dentro de N minutos

- ''messageLimit?: number'' 0 = sin mensajes (predeterminado 0); >0 = incluir últimos N mensajes

Comportamiento:

- ''messageLimit > 0'' obtiene ''chat.history'' por sesión e incluye los últimos N mensajes.

- Los resultados de herramientas se filtran en la salida de lista; usa ''sessions_history'' para mensajes de herramientas.

- Cuando se ejecuta en una sesión de agente en sandbox, las herramientas de sesión por defecto tienen visibilidad solo de spawned (ver abajo).

Forma de fila (JSON):

- ''key'': clave de sesión (string)

- ''kind''：''main | group | cron | hook | node | other''

- ''channel''：''whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown''

- ''displayName'' (etiqueta de visualización grupal si disponible)

- ''updatedAt'' (ms)

- ''sessionId''

- ''model''、''contextTokens''、''totalTokens''

- ''thinkingLevel''、''verboseLevel''、''systemSent''、''abortedLastRun''

- ''sendPolicy'' (anulación de sesión si está establecida)

- ''lastChannel''、''lastTo''

- deliveryContext ('{ channel, to, accountId }' normalizado cuando disponible)

- ''transcriptPath'' (ruta de mejor esfuerzo derivada del directorio de almacenamiento + sessionId)

- ''messages?'' (solo cuando ''messageLimit > 0'')

Obtiene la transcripción para una sesión.

Parámetros:

- ''sessionKey'' (requerido; acepta clave de sesión o ''sessionId'' de ''sessions_list'')

- ''limit?: number'' máx mensajes (el servidor limita)

- ''includeTools?: boolean'' (predeterminado false)

Comportamiento:

- ''includeTools=false'' filtra mensajes ''role: "toolResult"''.

- Retorna array de mensajes en el formato de transcripción crudo.

- Cuando se da un ''sessionId'', OpenClaw lo resuelve a la clave de sesión correspondiente (ids faltantes dan error).

Envía un mensaje a otra sesión.

Parámetros:

- ''sessionKey'' (requerido; acepta clave de sesión o ''sessionId'' de ''sessions_list'')

- ''message'' (requerido)

- ''timeoutSeconds?: number'' (predeterminado >0; 0 = disparar-y-olvidar)

Comportamiento:

- timeoutSeconds = 0: encolar y retornar '{ runId, status: "accepted" }'.

- timeoutSeconds > 0: esperar hasta N segundos para completar, luego retornar '{ runId, status: "ok", reply }'.

- Si la espera expira: '{ runId, status: "timeout", error }'. La ejecución continúa; llama sessions_history después.

- Si la ejecución falla: '{ runId, status: "error", error }'.

- La ejecución de anuncio de entrega ocurre después de que la ejecución principal completa y es de mejor esfuerzo; ''status: "ok"'' no garantiza que el anuncio fue entregado.

- Espera via gateway ''agent.wait'' (lado servidor) para que las reconexiones no pierdan la espera.

- El contexto de mensaje agente-a-agente se inyecta para la ejecución principal.

- Después de que la ejecución principal completa, OpenClaw ejecuta un bucle de respuesta:

- Las rondas 2+ alternan entre agentes solicitante y objetivo.

- Responde exactamente ''REPLY_SKIP'' para detener el ping-pong.

- Máx turnos es ''session.agentToAgent.maxPingPongTurns'' (0–5, predeterminado 5).

- Una vez que el bucle termina, OpenClaw ejecuta el paso de anuncio agente-a-agente (solo agente objetivo):

- Responde exactamente ''ANNOUNCE_SKIP'' para permanecer silencioso.

- Cualquier otra respuesta se envía al canal objetivo.

- El paso de anuncio incluye la solicitud original + respuesta de ronda-1 + última respuesta de ping-pong.

- Para grupos, ''channel'' es el canal registrado en la entrada de sesión.

- Para chats directos, ''channel'' se mapea desde ''lastChannel''.

- Para cron/hook/nodo, ''channel'' es ''internal''.

- Si falta, ''channel'' es ''unknown''.

Bloqueo basado en política por tipo de canal/chat (no por id de sesión).

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

Anulación en runtime (por entrada de sesión):

- ''sendPolicy: "allow" | "deny"'' (sin establecer = heredar config)

- Configurable via ''sessions.patch'' o ''/send on|off|inherit'' solo propietario (mensaje independiente).

Puntos de aplicación:

- ''chat.send'' / ''agent'' (gateway)

- lógica de entrega de auto-respuesta

Genera una ejecución de sub-agente en una sesión aislada y anuncia el resultado de vuelta al canal de chat del solicitante.

Parámetros:

- ''task'' (requerido)

- ''label?'' (opcional; usado para logs/UI)

- ''agentId?'' (opcional; genera bajo otro id de agente si está permitido)

- ''model?'' (opcional; anula el modelo del sub-agente; valores inválidos dan error)

- ''runTimeoutSeconds?'' (predeterminado 0; cuando está establecido, aborta la ejecución del sub-agente después de N segundos)

- ''cleanup?'' (''delete|keep'', predeterminado ''keep'')

Lista permitida:

- ''agents.list[].subagents.allowAgents'': lista de ids de agente permitidos via ''agentId'' (''["*"]'' para permitir cualquiera). Predeterminado: solo el agente solicitante.

Descubrimiento:

- Usa ''agents_list'' para descubrir qué ids de agente están permitidos para ''sessions_spawn''.

Comportamiento:

- Inicia una nueva sesión ''agent:<agentId>:subagent:<uuid>'' con ''deliver: false''.

- Los sub-agentes por defecto tienen el conjunto completo de herramientas ''menos herramientas de sesión'' (configurable via ''tools.subagents.tools'').

- Los sub-agentes no tienen permitido llamar ''sessions_spawn'' (no generación de sub-agente → sub-agente).

- Siempre no bloqueante: retorna '{ status: "accepted", runId, childSessionKey }' inmediatamente.

- Después de completar, OpenClaw ejecuta un paso de anuncio de sub-agente y publica el resultado al canal de chat del solicitante.

- Responde exactamente ''ANNOUNCE_SKIP'' durante el paso de anuncio para permanecer silencioso.

- Las respuestas de anuncio se normalizan a ''Status''/''Result''/''Notes''; ''Status'' viene del resultado de runtime (no texto del modelo).

- Las sesiones de sub-agente se auto-archivan después de ''agents.defaults.subagents.archiveAfterMinutes'' (predeterminado: 60).

- Las respuestas de anuncio incluyen una línea de estadísticas (runtime, tokens, sessionKey/sessionId, ruta de transcripción, y costo opcional).

Las sesiones en sandbox pueden usar herramientas de sesión, pero por defecto solo ven sesiones que generaron via ''sessions_spawn''.

Configurar:

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