Herramientas de sesión

OpenClaw proporciona a los agentes herramientas para trabajar entre sesiones, inspeccionar el estado y orquestar subagentes.

Herramientas disponibles

Estas herramientas siguen sujetas al perfil de herramientas activo y a la política de permitir/denegar. tools.profile: "coding" incluye el conjunto completo de orquestación de sesiones, incluidos sessions_spawn, sessions_yield y subagents. tools.profile: "messaging" incluye herramientas de mensajería entre sesiones (sessions_list, sessions_history, sessions_send, session_status), pero no incluye la generación de subagentes. Para mantener un perfil de mensajería y aun así permitir delegación nativa, agrega:

{  tools: {    profile: "messaging",    alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],  },}

Las políticas de grupo, proveedor, sandbox y por agente aún pueden quitar esas herramientas después de la etapa de perfil. Usa /tools desde la sesión afectada para inspeccionar la lista efectiva de herramientas.

Enumerar y leer sesiones

sessions_list devuelve sesiones con su clave, agentId, tipo, canal, modelo, recuentos de tokens y marcas de tiempo. Filtra por tipo (main, group, cron, hook, node), label exacta, agentId exacto, texto de búsqueda o actualidad (activeMinutes). Las sesiones activas se devuelven de forma predeterminada; pasa archived: true para inspeccionar sesiones archivadas. Las filas incluyen su estado fijado y archivado. Cuando necesites una triaje de estilo buzón, también puede solicitar un título derivado con alcance de visibilidad, un fragmento de vista previa del último mensaje o mensajes recientes acotados en cada fila. Los títulos derivados y las vistas previas se producen solo para las sesiones que el llamador ya puede ver según la política configurada de visibilidad de herramientas de sesión, por lo que las sesiones no relacionadas permanecen ocultas. Cuando la visibilidad está restringida, sessions_list devuelve metadatos opcionales de visibility que muestran el modo efectivo y una advertencia de que los resultados pueden estar limitados por alcance.

sessions_history obtiene la transcripción de conversación de una sesión específica. De forma predeterminada, los resultados de herramientas se excluyen: pasa includeTools: true para verlos. Usa limit para la cola acotada más reciente. Pasa offset: 0 cuando necesites metadatos de paginación y luego pasa los valores nextOffset devueltos para retroceder por ventanas de transcripción antiguas de OpenClaw sin leer archivos de transcripción sin procesar. Las páginas con desplazamiento explícito no combinan importaciones de respaldo de CLI externas; usa la vista predeterminada de cola más reciente cuando necesites ese historial de visualización combinado. La vista devuelta está acotada y filtrada por seguridad de forma intencional:

• el texto del asistente se normaliza antes de recordarlo:
  • se eliminan las etiquetas de razonamiento
  • se eliminan los bloques de andamiaje <relevant-memories> / <relevant_memories>
  • se eliminan los bloques de carga XML de llamadas de herramientas en texto plano, como <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls> y <function_calls>...</function_calls>, incluidas las cargas truncadas que nunca cierran correctamente
  • se elimina el andamiaje degradado de llamadas/resultados de herramientas, como [Tool Call: ...], [Tool Result ...] y [Historical context ...]
  • se eliminan los tokens de control de modelo filtrados, como <|assistant|>, otros tokens ASCII <|...|> y variantes de ancho completo <｜...｜>
  • se elimina XML de llamadas de herramientas MiniMax mal formado, como <invoke ...> / </minimax:tool_call>
• el texto similar a credenciales o tokens se redacta antes de devolverse
• los bloques de texto largos se truncan
• los historiales muy grandes pueden descartar filas antiguas o reemplazar una fila sobredimensionada por [sessions_history omitted: message too large]
• la herramienta informa indicadores de resumen, como truncated, droppedMessages, contentTruncated, contentRedacted, bytes y metadatos de paginación

Ambas herramientas aceptan una clave de sesión (como "main") o un ID de sesión de una llamada de lista anterior.

Si necesitas la transcripción exacta byte por byte, inspecciona el archivo de transcripción en disco en lugar de tratar sessions_history como un volcado sin procesar.

Enviar mensajes entre sesiones

sessions_send entrega un mensaje a otra sesión y, opcionalmente, espera la respuesta:

• Enviar y continuar: establece timeoutSeconds: 0 para encolar y devolver inmediatamente.
• Esperar respuesta: establece un tiempo de espera y recibe la respuesta en línea.

Las sesiones de chat con alcance de hilo, como claves de Slack o Discord que terminan en :thread:<id>, no son destinos válidos de sessions_send. Usa la clave de sesión del canal principal para la coordinación entre agentes, de modo que los mensajes enrutados por herramienta no aparezcan dentro de un hilo activo orientado a humanos.

Los mensajes y las respuestas de seguimiento A2A se marcan como datos entre sesiones en el prompt receptor ([Inter-session message ... isUser=false]) y en la procedencia de la transcripción. El agente receptor debe tratarlos como datos enrutados por herramienta, no como una instrucción directa escrita por el usuario final.

Después de que el destino responde, OpenClaw puede ejecutar un bucle de respuesta de vuelta donde los agentes alternan mensajes (hasta session.agentToAgent.maxPingPongTurns, rango 0-20, valor predeterminado 5). El agente destino puede responder REPLY_SKIP para detenerse antes.

Ayudantes de estado y orquestación

session_status es la herramienta ligera equivalente a /status para la sesión actual u otra sesión visible. Informa uso, hora, estado del modelo/runtime y contexto de tareas en segundo plano vinculadas cuando está presente. Al igual que /status, puede rellenar contadores dispersos de tokens/caché desde la entrada de uso de transcripción más reciente, y model=default borra una anulación por sesión. Usa sessionKey="current" para la sesión actual del llamador; las etiquetas visibles de cliente como openclaw-tui no son claves de sesión.

Cuando hay metadatos de ruta disponibles, session_status también incluye un bloque JSON visible de Route context y campos estructurados details coincidentes. Estos campos desambiguan la clave de sesión de la ruta que está manejando actualmente la ejecución en vivo:

• origin es donde se creó la sesión, o el proveedor inferido a partir de un prefijo de clave de sesión entregable cuando el estado antiguo carece de metadatos de origen almacenados.
• active es la ruta actual de ejecución en vivo. Solo se informa para la sesión en vivo o actual que se está manejando ahora.
• deliveryContext es la ruta de entrega persistida almacenada en la sesión, que OpenClaw puede reutilizar para entregas posteriores incluso cuando la superficie activa difiere.

sessions_yield finaliza intencionalmente el turno actual para que el siguiente mensaje pueda ser el evento de seguimiento que estás esperando. Úsalo después de generar subagentes cuando quieras que los resultados de finalización lleguen como el siguiente mensaje en lugar de crear bucles de sondeo.

subagents es el ayudante de visibilidad para subagentes de OpenClaw ya generados. Admite action: "list" para inspeccionar ejecuciones activas/recientes.

Generar subagentes

sessions_spawn crea de forma predeterminada una sesión aislada para una tarea en segundo plano. Siempre es no bloqueante: devuelve inmediatamente un runId y childSessionKey. Las ejecuciones nativas de subagentes reciben la tarea delegada en el primer mensaje visible [Subagent Task] de la sesión hija, mientras que el prompt del sistema lleva solo reglas de runtime de subagente y contexto de enrutamiento.

Opciones clave:

• runtime: "subagent" (valor predeterminado) o "acp" para agentes de arnés externos.
• Anulaciones de model y thinking para la sesión hija.
• thread: true para vincular la generación a un hilo de chat (Discord, Slack, etc.).
• sandbox: "require" para exigir sandboxing en el hijo.
• context: "fork" para subagentes nativos cuando el hijo necesita la transcripción actual del solicitante; omítelo o usa context: "isolated" para un hijo limpio. Los subagentes nativos vinculados a hilo usan context: "fork" de forma predeterminada, salvo que threadBindings.defaultSpawnContext indique lo contrario.

Los subagentes hoja predeterminados no reciben herramientas de sesión. Cuando maxSpawnDepth >= 2, los subagentes orquestadores de profundidad 1 reciben además sessions_spawn, subagents, sessions_list y sessions_history para que puedan gestionar sus propios hijos. Las ejecuciones hoja siguen sin recibir herramientas de orquestación recursiva.

Tras la finalización, un paso de anuncio publica el resultado en el canal del solicitante. La entrega de finalización preserva el enrutamiento de hilo/tema vinculado cuando está disponible, y si el origen de finalización solo identifica un canal, OpenClaw aún puede reutilizar la ruta almacenada de la sesión del solicitante (lastChannel / lastTo) para entrega directa.

Para comportamiento específico de ACP, consulta Agentes ACP.

Visibilidad

Las herramientas de sesión tienen alcance para limitar lo que el agente puede ver:

El valor predeterminado es tree. Las sesiones en sandbox se limitan a tree independientemente de la configuración.

Lecturas adicionales

• Gestión de sesiones -- enrutamiento, ciclo de vida, mantenimiento
• Agentes ACP -- generación de arneses externos
• Multiagente -- arquitectura multiagente
• Configuración de Gateway -- controles de configuración de herramientas de sesión

Relacionado

• Gestión de sesiones
• Poda de sesiones