agent:<agentId>:subagent:<uuid>) y,
cuando termina, anuncia su resultado de vuelta al canal de chat solicitante.
Cada ejecución de subagente se registra como una tarea en segundo plano.
Objetivos:
- Paralelizar investigación, tareas largas y trabajo lento con herramientas sin bloquear la ejecución principal.
- Mantener los subagentes aislados de forma predeterminada (separación de sesiones, aislamiento opcional).
- Mantener la superficie de herramientas difícil de usar incorrectamente: los subagentes no reciben herramientas de sesión ni de mensajes de forma predeterminada.
- Admitir profundidad de anidamiento configurable para patrones de orquestador.
Nota de coste: cada subagente tiene su propio contexto y uso de tokens de
forma predeterminada. Para tareas pesadas o repetitivas, configura un modelo más barato para los subagentes
y mantén tu agente principal en un modelo de mayor calidad mediante
agents.defaults.subagents.model o anulaciones por agente. Cuando un hijo
realmente necesita la transcripción actual del solicitante, genéralo con
context: "fork". Las sesiones de subagente vinculadas a hilos usan de forma predeterminada
context: "fork" porque ramifican la conversación actual en un
hilo de seguimiento.Comando de barra
/subagents inspecciona ejecuciones de subagentes para la sesión actual:
/subagents info muestra metadatos de ejecución (estado, marcas de tiempo, id de sesión,
ruta de transcripción, limpieza). /subagents log imprime turnos de chat recientes para una
ejecución; añade el token tools para incluir mensajes de llamadas/resultados de herramientas (omitidos
de forma predeterminada). Usa sessions_history para una vista de recuerdo acotada y filtrada por seguridad
desde dentro de un turno de agente, o inspecciona la ruta de transcripción en disco para
la transcripción completa sin procesar.
Controles de vinculación de hilos
Estos comandos funcionan en canales con vinculaciones de hilo persistentes. Consulta Canales compatibles con hilos abajo.Comportamiento de generación
Los agentes inician subagentes en segundo plano con la herramientasessions_spawn.
Las finalizaciones vuelven como eventos internos de la sesión principal; el agente principal/solicitante
decide si hace falta una actualización visible para el usuario.
Finalización no bloqueante basada en inserción
Finalización no bloqueante basada en inserción
sessions_spawnno bloquea; devuelve un id de ejecución inmediatamente.- Al completarse, el subagente informa de vuelta a la sesión principal/solicitante.
- Los turnos de agente que necesitan resultados de hijos deben llamar a
sessions_yielddespués de generar el trabajo necesario. Eso termina el turno actual y permite que el evento de finalización llegue como el siguiente mensaje visible para el modelo. - La finalización se basa en inserción. Una vez generado, no sondees
/subagents list,sessions_listnisessions_historyen un bucle solo para esperar a que termine; comprueba el estado bajo demanda solo al depurar. - La salida del hijo es un informe/evidencia para que el agente solicitante sintetice. No es texto de instrucción escrito por el usuario y no puede anular políticas del sistema, de desarrollador ni del usuario.
- Al completarse, OpenClaw cierra con el mejor esfuerzo las pestañas/procesos del navegador registrados abiertos por esa sesión de subagente antes de que continúe el flujo de limpieza del anuncio.
Entrega de finalización
Entrega de finalización
- OpenClaw devuelve las finalizaciones a la sesión solicitante mediante un turno
agentcon una clave de idempotencia estable. - Si la ejecución solicitante sigue activa, OpenClaw primero intenta despertar/dirigir esa ejecución en lugar de iniciar una segunda ruta de respuesta visible.
- Si no se puede despertar a un solicitante activo, OpenClaw recurre a una transferencia al agente solicitante con el mismo contexto de finalización en lugar de descartar el anuncio.
- Una transferencia principal correcta completa la entrega del subagente incluso cuando el principal decide que no hace falta una actualización visible para el usuario.
- Los subagentes nativos no reciben la herramienta de mensajes. Devuelven texto simple de asistente al agente principal/solicitante; las respuestas visibles para humanos siguen siendo propiedad de la política normal de entrega del agente principal/solicitante.
- Si no se puede usar la transferencia directa, la entrega recurre al enrutamiento de cola y luego a un breve reintento del anuncio con retroceso exponencial antes del abandono final.
- La entrega conserva la ruta solicitante resuelta: las rutas de finalización vinculadas a hilos o conversaciones tienen prioridad cuando están disponibles. Si el origen de la finalización solo proporciona un canal, OpenClaw completa el destino/cuenta faltante desde la ruta resuelta de la sesión solicitante (
lastChannel/lastTo/lastAccountId) para que la entrega directa siga funcionando.
Metadatos de transferencia de finalización
Metadatos de transferencia de finalización
La transferencia de finalización a la sesión solicitante es contexto interno
generado por el runtime (no texto escrito por el usuario) e incluye:
Result— el texto de la última respuesta visible deassistantdel hijo. La salida de herramienta/toolResult no se promociona a resultados del hijo. Las ejecuciones terminales fallidas no reutilizan texto de respuesta capturado.Status—completed; ready for parent review/failed/timed out/unknown.- Estadísticas compactas de runtime/tokens.
- Una instrucción de revisión que indica al agente solicitante que verifique el resultado antes de decidir si la tarea original está terminada.
- Guía de seguimiento que indica al agente solicitante que continúe la tarea o registre un seguimiento cuando el resultado del hijo deje más acciones.
- Una instrucción de actualización final para la ruta sin más acciones, escrita con voz normal de asistente sin reenviar metadatos internos sin procesar.
Modos y runtime ACP
Modos y runtime ACP
--modely--thinkinganulan los valores predeterminados para esa ejecución específica.- Usa
info/logpara inspeccionar detalles y salida después de la finalización. - Para sesiones persistentes vinculadas a hilos, usa
sessions_spawnconthread: trueymode: "session". - Si el canal solicitante no admite vinculaciones de hilo, usa
mode: "run"en lugar de reintentar una combinación vinculada a hilos imposible. - Para sesiones de arnés ACP (Claude Code, Gemini CLI, OpenCode o Codex ACP/acpx explícito), usa
sessions_spawnconruntime: "acp"cuando la herramienta anuncie ese runtime. Consulta el modelo de entrega ACP al depurar finalizaciones o bucles de agente a agente. Cuando el Plugincodexestá habilitado, el control de chat/hilo de Codex debe preferir/codex ...sobre ACP salvo que el usuario pida explícitamente ACP/acpx. - OpenClaw oculta
runtime: "acp"hasta que ACP esté habilitado, el solicitante no esté en aislamiento y se cargue un Plugin de backend comoacpx.runtime: "acp"espera un id de arnés ACP externo, o una entradaagents.list[]conruntime.type="acp"; usa el runtime de subagente predeterminado para agentes de configuración normales de OpenClaw desdeagents_list.
Modos de contexto
Los subagentes nativos comienzan aislados salvo que el llamador pida explícitamente bifurcar la transcripción actual.| Modo | Cuándo usarlo | Comportamiento |
|---|---|---|
isolated | Investigación nueva, implementación independiente, trabajo lento con herramientas o cualquier cosa que pueda resumirse en el texto de la tarea | Crea una transcripción hija limpia. Este es el valor predeterminado y mantiene menor el uso de tokens. |
fork | Trabajo que depende de la conversación actual, resultados previos de herramientas o instrucciones matizadas ya presentes en la transcripción solicitante | Ramifica la transcripción solicitante en la sesión hija antes de que el hijo comience. |
fork con moderación. Es para delegación sensible al contexto, no un
sustituto de escribir una instrucción de tarea clara.
Herramienta: sessions_spawn
Inicia una ejecución de subagente con deliver: false en el carril global subagent,
luego ejecuta un paso de anuncio y publica la respuesta de anuncio en el canal
de chat solicitante.
La disponibilidad depende de la política efectiva de herramientas del llamador. El perfil incorporado
coding incluye sessions_spawn; messaging y minimal no.
full permite todas las herramientas. Añade tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"], o usa tools.profile: "coding", para
agentes en un perfil más restringido que aun así deban delegar trabajo.
Las políticas de canal/grupo, proveedor, aislamiento y permitir/denegar por agente
todavía pueden quitar la herramienta después de la fase de perfil. Usa /tools desde la misma
sesión para confirmar la lista efectiva de herramientas.
Valores predeterminados:
- Modelo: los subagentes nativos heredan el llamador salvo que configures
agents.defaults.subagents.model(oagents.list[].subagents.modelpor agente). Las generaciones con runtime ACP usan el mismo modelo de subagente configurado cuando está presente; de lo contrario, el arnés ACP conserva su propio valor predeterminado. Unsessions_spawn.modelexplícito sigue teniendo prioridad. - Thinking: los subagentes nativos heredan el llamador salvo que configures
agents.defaults.subagents.thinking(oagents.list[].subagents.thinkingpor agente). Las generaciones con runtime ACP también aplicanagents.defaults.models["provider/model"].params.thinkingpara el modelo seleccionado. Unsessions_spawn.thinkingexplícito sigue teniendo prioridad. - Tiempo de espera de ejecución: OpenClaw usa
agents.defaults.subagents.runTimeoutSecondscuando está configurado; de lo contrario, recurre a0(sin tiempo de espera).sessions_spawnno acepta anulaciones de tiempo de espera por llamada. - Entrega de tareas: los subagentes nativos reciben la tarea delegada en su primer mensaje visible
[Subagent Task]. El prompt de sistema del subagente contiene reglas de runtime y contexto de enrutamiento, no un duplicado oculto de la tarea.
resolvedModel contiene la referencia de modelo aplicada y
resolvedProvider contiene el prefijo del proveedor cuando la referencia tiene uno.
Modo de prompt de delegación
agents.defaults.subagents.delegationMode controla solo la guía del prompt; no cambia la política de herramientas ni fuerza la delegación.
suggest(predeterminado): mantiene el empujón estándar del prompt para usar subagentes en trabajos más grandes o lentos.prefer: indica al agente principal que se mantenga receptivo y delegue cualquier cosa más compleja que una respuesta directa mediantesessions_spawn.
agents.list[].subagents.delegationMode.
Parámetros de herramienta
La descripción de la tarea para el subagente.
Identificador estable opcional para identificar un hijo específico en la salida de estado posterior. Debe coincidir con
[a-z][a-z0-9_-]{0,63} y no puede ser un destino reservado como last o all.Etiqueta opcional legible para humanos.
Genera bajo otro id de agente configurado cuando
subagents.allowAgents lo permita.Directorio de trabajo opcional de la tarea para la ejecución hija. Los subagentes nativos siguen cargando los archivos de arranque desde el espacio de trabajo del agente de destino;
cwd solo cambia dónde las herramientas de runtime y los arneses de CLI realizan el trabajo delegado.acp es solo para arneses ACP externos (claude, droid, gemini, opencode o Codex ACP/acpx solicitado explícitamente) y para entradas agents.list[] cuyo runtime.type sea acp.Solo ACP. Reanuda una sesión existente del arnés ACP cuando
runtime: "acp"; se ignora para generaciones de subagentes nativos.Solo ACP. Transmite la salida de la ejecución ACP a la sesión principal cuando
runtime: "acp"; omítelo para generaciones de subagentes nativos.Sobrescribe el modelo del subagente. Los valores no válidos se omiten y el subagente se ejecuta con el modelo predeterminado con una advertencia en el resultado de la herramienta.
Sobrescribe el nivel de razonamiento para la ejecución del subagente.
Cuando es
true, solicita la vinculación a un hilo de canal para esta sesión de subagente.Si
thread: true y se omite mode, el valor predeterminado pasa a ser session. mode: "session" requiere thread: true.
Si la vinculación a hilos no está disponible para el canal solicitante, usa mode: "run" en su lugar."delete" archiva la sesión inmediatamente después del anuncio (sigue conservando la transcripción mediante cambio de nombre).require rechaza la generación a menos que el runtime hijo de destino esté aislado.fork ramifica la transcripción actual del solicitante en la sesión hija. Solo subagentes nativos. Las generaciones vinculadas a hilos usan fork de forma predeterminada; las generaciones sin hilo usan isolated de forma predeterminada.Nombres de tareas y direccionamiento
taskName es un identificador orientado al modelo para orquestación, no una clave de sesión.
Úsalo para nombres de hijos estables como review_subagents,
linux_validation o docs_update cuando un coordinador pueda necesitar inspeccionar
ese hijo más adelante.
La resolución de destinos acepta coincidencias exactas de taskName y
prefijos inequívocos. La coincidencia está limitada a la misma ventana de destinos
activos/recientes que usan los destinos numerados de /subagents, por lo que un hijo
completado obsoleto no hace ambiguo un identificador reutilizado. Si dos hijos activos
o recientes comparten el mismo taskName, el destino es ambiguo; usa en su lugar
el índice de la lista, la clave de sesión o el id de ejecución.
Los destinos reservados last y all no son valores válidos de taskName
porque ya tienen significados de control.
Herramienta: sessions_yield
Finaliza el turno actual del modelo y espera a que los eventos de runtime,
principalmente eventos de finalización de subagentes, lleguen como el siguiente mensaje. Úsalo después
de generar trabajo hijo requerido cuando el solicitante no pueda producir una respuesta
final hasta que lleguen esas finalizaciones.
sessions_yield es la primitiva de espera. No la sustituyas por bucles de sondeo
sobre subagents, sessions_list, sessions_history, sleep de shell
o sondeo de procesos solo para detectar la finalización de un hijo.
Usa sessions_yield solo cuando la lista efectiva de herramientas de la sesión la incluya.
Algunos perfiles de herramientas mínimos o personalizados pueden exponer sessions_spawn y
subagents sin exponer sessions_yield; en ese caso, no inventes
un bucle de sondeo solo para esperar la finalización.
Cuando existen hijos activos, OpenClaw inyecta un bloque de prompt compacto generado por el runtime
Active Subagents en los turnos normales para que el solicitante pueda ver
las sesiones hijas actuales, ids de ejecución, estados, etiquetas, tareas y
alias taskName sin sondear. Los campos de tarea y etiqueta de ese
bloque se entrecomillan como datos, no como instrucciones, porque pueden originarse
en argumentos de generación proporcionados por el usuario/modelo.
Herramienta: subagents
Lista ejecuciones de subagentes generadas que pertenecen a la sesión solicitante. Está limitada
al solicitante actual; un hijo solo puede ver sus propios hijos controlados.
Usa subagents para estado bajo demanda y depuración. Usa sessions_yield para
esperar eventos de finalización.
Sesiones vinculadas a hilos
Cuando las vinculaciones a hilos están habilitadas para un canal, un subagente puede permanecer vinculado a un hilo para que los mensajes de seguimiento del usuario en ese hilo sigan enrutándose a la misma sesión de subagente.Canales compatibles con hilos
Un canal admite sesiones persistentes de subagente vinculadas a hilos (sessions_spawn con thread: true) cuando registra un adaptador de vinculación
de conversación. Canales incluidos con ese soporte: Discord,
iMessage, Matrix y Telegram. Discord y Matrix usan de forma predeterminada
la creación de un hilo hijo; Telegram e iMessage usan de forma predeterminada la vinculación de la
conversación actual. Usa las claves de configuración threadBindings por canal para
habilitación, tiempos de espera y spawnSessions.
Flujo rápido
Route follow-ups
Las respuestas y los mensajes de seguimiento en ese hilo se enrutan a la sesión vinculada.
Inspect timeouts
Usa
/session idle para inspeccionar/actualizar el desenfoque automático por inactividad y
/session max-age para controlar el límite estricto.Controles manuales
| Comando | Efecto |
|---|---|
/focus <target> | Vincula el hilo actual (o crea uno) a un destino de subagente/sesión |
/unfocus | Elimina la vinculación del hilo vinculado actual |
/agents | Lista ejecuciones activas y el estado de vinculación (binding:<id>, unbound o bindings unavailable) |
/session idle | Inspecciona/actualiza el desenfoque automático por inactividad (solo hilos vinculados enfocados) |
/session max-age | Inspecciona/actualiza el límite estricto (solo hilos vinculados enfocados) |
Interruptores de configuración
- Valor predeterminado global:
session.threadBindings.enabled,session.threadBindings.idleHours,session.threadBindings.maxAgeHours. - Las claves de sobrescritura de canal y vinculación automática al generar son específicas del adaptador. Consulta Canales compatibles con hilos arriba.
Lista de permitidos
Lista de ids de agentes configurados que pueden ser destino mediante
agentId explícito (["*"] permite cualquier destino configurado). Valor predeterminado: solo el agente solicitante. Si configuras una lista y aun así quieres que el solicitante se genere a sí mismo con agentId, incluye el id del solicitante en la lista.Lista de permitidos predeterminada de agentes de destino configurados que se usa cuando el agente solicitante no define su propio
subagents.allowAgents.Bloquea las llamadas a
sessions_spawn que omiten agentId (fuerza la selección explícita de perfil). Sobrescritura por agente: agents.list[].subagents.requireAgentId.Tiempo de espera por llamada para intentos de entrega de anuncios
agent del gateway. Los valores son milisegundos enteros positivos y se limitan al máximo de temporizador seguro para la plataforma. Los reintentos transitorios pueden hacer que la espera total del anuncio sea más larga que un tiempo de espera configurado.sessions_spawn rechaza destinos
que se ejecutarían sin aislamiento.
Descubrimiento
Usaagents_list para ver qué ids de agente están permitidos actualmente para
sessions_spawn. La respuesta incluye el modelo efectivo de cada agente listado
y metadatos de runtime incrustados para que los llamadores puedan distinguir OpenClaw, servidor de aplicación Codex
y otros runtimes nativos configurados.
Las entradas allowAgents deben apuntar a ids de agentes configurados en agents.list[].
["*"] significa cualquier agente de destino configurado más el solicitante. Si se elimina una configuración de agente
pero su id permanece en allowAgents, sessions_spawn rechaza ese id
y agents_list lo omite. Ejecuta openclaw doctor --fix para limpiar entradas obsoletas
de la lista de permitidos, o agrega una entrada mínima agents.list[] cuando el destino deba
seguir siendo generable mientras hereda los valores predeterminados.
Archivado automático
- Las sesiones de subagente se archivan automáticamente después de
agents.defaults.subagents.archiveAfterMinutes(valor predeterminado60). - El archivado usa
sessions.deletey cambia el nombre de la transcripción a*.deleted.<timestamp>(misma carpeta). cleanup: "delete"archiva inmediatamente después del anuncio (sigue conservando la transcripción mediante cambio de nombre).- El archivado automático es de mejor esfuerzo; los temporizadores pendientes se pierden si el gateway se reinicia.
- Los tiempos de espera de ejecución configurados no archivan automáticamente; solo detienen la ejecución. La sesión permanece hasta el archivado automático.
- El archivado automático se aplica por igual a sesiones de profundidad 1 y profundidad 2.
- La limpieza del navegador es independiente de la limpieza de archivo: las pestañas/procesos del navegador rastreados se cierran en modo de mejor esfuerzo cuando termina la ejecución, incluso si se conserva la transcripción/registro de sesión.
Subagentes anidados
De forma predeterminada, los subagentes no pueden generar sus propios subagentes (maxSpawnDepth: 1). Define maxSpawnDepth: 2 para habilitar un nivel de
anidamiento: el patrón de orquestador: principal → subagente orquestador →
sub-subagentes trabajadores.
Niveles de profundidad
| Profundidad | Forma de clave de sesión | Rol | ¿Puede generar? |
|---|---|---|---|
| 0 | agent:<id>:main | Agente principal | Siempre |
| 1 | agent:<id>:subagent:<uuid> | Subagente (orquestador cuando se permite profundidad 2) | Solo si maxSpawnDepth >= 2 |
| 2 | agent:<id>:subagent:<uuid>:subagent:<uuid> | Subsubagente (trabajador hoja) | Nunca |
Cadena de anuncios
Los resultados fluyen de vuelta hacia arriba por la cadena:- El trabajador de profundidad 2 termina → anuncia a su padre (orquestador de profundidad 1).
- El orquestador de profundidad 1 recibe el anuncio, sintetiza los resultados, termina → anuncia al principal.
- El agente principal recibe el anuncio y lo entrega al usuario.
Guía operativa: inicia el trabajo hijo una vez y espera los eventos de finalización
en lugar de construir bucles de sondeo alrededor de
sessions_list,
sessions_history, /subagents list o comandos de suspensión con exec.
sessions_list y /subagents list mantienen las relaciones de sesiones hijas
centradas en el trabajo activo: los hijos activos permanecen adjuntos, los hijos terminados siguen
visibles durante una breve ventana reciente, y los enlaces de hijos obsoletos solo en el almacén se
ignoran después de su ventana de frescura. Esto evita que los metadatos antiguos spawnedBy /
parentSessionKey resuciten hijos fantasma después de
reiniciar. Si un evento de finalización de hijo llega después de que ya enviaste la
respuesta final, el seguimiento correcto es el token silencioso exacto
NO_REPLY / no_reply.Política de herramientas por profundidad
- El rol y el alcance de control se escriben en los metadatos de sesión en el momento de la generación. Eso evita que claves de sesión planas o restauradas recuperen accidentalmente privilegios de orquestador.
- Profundidad 1 (orquestador, cuando
maxSpawnDepth >= 2): obtienesessions_spawn,subagents,sessions_list,sessions_historypara poder generar hijos e inspeccionar su estado. Otras herramientas de sesión/sistema permanecen denegadas. - Profundidad 1 (hoja, cuando
maxSpawnDepth == 1): sin herramientas de sesión (comportamiento predeterminado actual). - Profundidad 2 (trabajador hoja): sin herramientas de sesión;
sessions_spawnsiempre se deniega en profundidad 2. No puede generar más hijos.
Límite de generación por agente
Cada sesión de agente (a cualquier profundidad) puede tener como máximomaxChildrenPerAgent
(predeterminado 5) hijos activos a la vez. Esto evita una expansión descontrolada
desde un único orquestador.
Detención en cascada
Detener un orquestador de profundidad 1 detiene automáticamente todos sus hijos de profundidad 2:/stopen el chat principal detiene todos los agentes de profundidad 1 y se propaga a sus hijos de profundidad 2.
Autenticación
La autenticación de subagentes se resuelve por id de agente, no por tipo de sesión:- La clave de sesión del subagente es
agent:<agentId>:subagent:<uuid>. - El almacén de autenticación se carga desde el
agentDirde ese agente. - Los perfiles de autenticación del agente principal se fusionan como respaldo; los perfiles de agente anulan los perfiles principales en conflictos.
Anuncio
Los subagentes informan mediante un paso de anuncio:- El paso de anuncio se ejecuta dentro de la sesión del subagente (no en la sesión solicitante).
- Si el subagente responde exactamente
ANNOUNCE_SKIP, no se publica nada. - Si el texto más reciente del asistente es el token silencioso exacto
NO_REPLY/no_reply, la salida del anuncio se suprime aunque haya existido progreso visible anterior.
- Las sesiones solicitantes de nivel superior usan una llamada de seguimiento
agentcon entrega externa (deliver=true). - Las sesiones de subagente solicitante anidadas reciben una inyección interna de seguimiento (
deliver=false) para que el orquestador pueda sintetizar los resultados de los hijos dentro de la sesión. - Si una sesión de subagente solicitante anidada ya no existe, OpenClaw recurre al solicitante de esa sesión cuando está disponible.
Contexto de anuncio
El contexto de anuncio se normaliza a un bloque de evento interno estable:| Campo | Fuente |
|---|---|
| Origen | subagent o cron |
| Ids de sesión | Clave/id de sesión hija |
| Tipo | Tipo de anuncio + etiqueta de tarea |
| Estado | Derivado del resultado de runtime (ok, error, timeout o unknown), no inferido del texto del modelo |
| Contenido de resultado | Texto visible más reciente del asistente desde el hijo |
| Seguimiento | Instrucción que describe cuándo responder frente a permanecer en silencio |
Línea de estadísticas
Las cargas de anuncio incluyen una línea de estadísticas al final (incluso cuando están envueltas):- Runtime (p. ej.,
runtime 5m12s). - Uso de tokens (entrada/salida/total).
- Coste estimado cuando los precios del modelo están configurados (
models.providers.*.models[].cost). sessionKey,sessionIdy ruta de transcripción para que el agente principal pueda obtener historial mediantesessions_historyo inspeccionar el archivo en disco.
Por qué preferir sessions_history
sessions_history es la ruta de orquestación más segura para leer la
transcripción de un hijo desde dentro de un turno de agente:
- Redacta texto parecido a credenciales/tokens incluso cuando la redacción de registros de propósito general está deshabilitada.
- Trunca bloques de texto largos (4000 caracteres por bloque) y descarta firmas de pensamiento, cargas de reproducción de razonamiento y datos de imagen en línea.
- Aplica un límite de respuesta de 80 KB; las filas demasiado grandes se reemplazan por
[sessions_history omitted: message too large]. - Usa
nextOffsetcuando esté presente para paginar hacia atrás por ventanas de transcripción más antiguas. sessions_historyno elimina etiquetas de razonamiento, andamiaje<relevant-memories>ni XML de llamadas a herramientas del texto del mensaje; devuelve bloques de contenido estructurados cercanos a la forma de transcripción sin procesar, solo redactados y limitados en tamaño./subagents logaplica el saneador de prosa más pesado (elimina etiquetas de razonamiento, andamiaje de memoria y XML de llamadas a herramientas) porque renderiza líneas de chat simples en lugar de bloques estructurados.- La inspección de la transcripción sin procesar en disco es el respaldo cuando necesitas la transcripción completa byte por byte.
Política de herramientas
Los subagentes usan primero el mismo perfil y la misma canalización de política de herramientas que el agente padre o destino. Después, OpenClaw aplica la capa de restricciones de subagente. Los subagentes siempre pierdengateway, agents_list, session_status y
cron independientemente de la profundidad o el rol (herramientas de nivel de sistema/interactivas, o
herramientas que el agente principal debe coordinar). Los subagentes hoja (comportamiento predeterminado
de profundidad 1, y siempre en profundidad 2) además pierden subagents,
sessions_list, sessions_history y sessions_spawn. Los subagentes nunca
obtienen la herramienta message: se deshabilita en el momento de generación, no se filtra por
esta lista de denegación, y sessions_send permanece denegada para que los subagentes
se comuniquen solo mediante la cadena de anuncios.
sessions_history también sigue siendo aquí una vista de recuperación acotada y saneada; no
es un volcado de transcripción sin procesar.
Cuando maxSpawnDepth >= 2, los subagentes orquestadores de profundidad 1 además
reciben sessions_spawn, subagents, sessions_list y
sessions_history para poder gestionar sus hijos.
Sobrescribir mediante configuración
tools.subagents.tools.allow es un filtro final de solo permitidos. Puede estrechar
el conjunto de herramientas ya resuelto, pero no puede volver a añadir una herramienta eliminada
por tools.profile. Por ejemplo, tools.profile: "coding" incluye
web_search/web_fetch pero no la herramienta browser. Para permitir que
los subagentes con perfil de codificación usen automatización de navegador, añade browser en la
etapa de perfil:
agents.list[].tools.alsoAllow: ["browser"] por agente cuando solo un
agente deba obtener automatización de navegador.
Concurrencia
Los subagentes usan un carril de cola dedicado dentro del proceso:- Nombre del carril:
subagent - Concurrencia:
agents.defaults.subagents.maxConcurrent(predeterminado8)
Vivacidad y recuperación
OpenClaw no trata la ausencia deendedAt como prueba permanente de que un
subagente sigue activo. Las ejecuciones no finalizadas más antiguas que la ventana de ejecución obsoleta
(2 horas, o el tiempo de espera de ejecución configurado más un breve periodo de gracia,
lo que sea mayor) dejan de contar como activas/pendientes en /subagents list,
resúmenes de estado, bloqueo de finalización de descendientes y comprobaciones de
concurrencia por sesión.
Después de reiniciar un gateway, las ejecuciones restauradas no finalizadas obsoletas se podan a menos que
su sesión hija esté marcada como abortedLastRun: true. Esas
sesiones hijas abortadas por reinicio siguen siendo recuperables mediante el flujo de recuperación de
subagentes huérfanos, que envía un mensaje sintético de reanudación antes de
borrar el marcador de abortado.
La recuperación automática tras reinicio está acotada por sesión hija. Si el mismo
hijo subagente se acepta para recuperación de huérfano repetidamente dentro de la
ventana rápida de reacuñamiento, OpenClaw persiste una lápida de recuperación en esa
sesión y deja de reanudarla automáticamente en reinicios posteriores. Ejecuta
openclaw tasks maintenance --apply para reconciliar el registro de tarea, o
openclaw doctor --fix para borrar indicadores obsoletos de recuperación abortada en
sesiones con lápida.
Si la generación de un subagente falla con Gateway
PAIRING_REQUIRED /
scope-upgrade, revisa el llamador RPC antes de editar el estado de emparejamiento.
La coordinación interna sessions_spawn se despacha en proceso cuando el
llamador ya se está ejecutando dentro del contexto de solicitud del gateway, por lo que
no abre un WebSocket de loopback ni depende de la línea base de alcance de dispositivo emparejado de la CLI.
Los llamadores fuera del proceso de gateway aún usan el respaldo WebSocket
como client.id: "gateway-client" con client.mode: "backend"
sobre autenticación directa de token compartido/contraseña por loopback. Los llamadores remotos,
deviceIdentity explícito, rutas explícitas de token de dispositivo y clientes de navegador/node
aún necesitan aprobación normal del dispositivo para actualizaciones de alcance.Detención
- Enviar
/stopen el chat solicitante aborta la sesión solicitante y detiene cualquier ejecución de subagente activa generada desde ella, propagándose a los hijos anidados.
Limitaciones
- El anuncio de subagente es de mejor esfuerzo. Si el gateway se reinicia, se pierde el trabajo pendiente de “anunciar de vuelta”.
- Los subagentes siguen compartiendo los mismos recursos del proceso de gateway; trata
maxConcurrentcomo una válvula de seguridad. sessions_spawnsiempre es no bloqueante: devuelve{ status: "accepted", runId, childSessionKey }de inmediato.- El contexto de subagente solo inyecta
AGENTS.mdyTOOLS.md(noSOUL.md,IDENTITY.md,USER.md,MEMORY.md,HEARTBEAT.mdniBOOTSTRAP.md). Los subagentes nativos de Codex siguen el mismo límite:TOOLS.mdpermanece en las instrucciones heredadas del hilo de Codex, mientras que los archivos de personalidad, identidad y usuario solo del padre se inyectan como instrucciones de colaboración con alcance de turno para que los hijos no los clonen. - La profundidad máxima de anidamiento es 5 (rango de
maxSpawnDepth: 1-5). Se recomienda la profundidad 2 para la mayoría de los casos de uso. maxChildrenPerAgentlimita los hijos activos por sesión (valor predeterminado5, rango1-20).