Unteragenten

• Arbeit für „Recherche / lange Aufgabe / langsames Tool“ parallelisieren, ohne den Hauptlauf zu blockieren.
• Unteragenten standardmäßig isoliert halten (Sitzungstrennung + optionales Sandboxing).
• Die Tool-Oberfläche schwer missbrauchbar halten: Unteragenten erhalten standardmäßig keine Sitzungstools.
• Konfigurierbare Verschachtelungstiefe für Orchestrator-Muster unterstützen.

​

Slash-Befehl

/subagents list
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>

​

Steuerung der Thread-Bindung

/focus <subagent-label|session-key|session-id|session-label>
/unfocus
/agents
/session idle <duration|off>
/session max-age <duration|off>

​

Startverhalten

​

Kontextmodi

​

Tool: sessions_spawn

• Modell: Native Unteragenten erben den Aufrufer, sofern Sie nicht agents.defaults.subagents.model (oder agentenspezifisch agents.list[].subagents.model) festlegen. Starts der ACP-Laufzeit verwenden dasselbe konfigurierte Unteragentenmodell, wenn vorhanden; andernfalls behält das ACP-Harness seinen eigenen Standard. Ein explizites sessions_spawn.model hat weiterhin Vorrang.
• Thinking: Native Unteragenten erben den Aufrufer, sofern Sie nicht agents.defaults.subagents.thinking (oder agentenspezifisch agents.list[].subagents.thinking) festlegen. Starts der ACP-Laufzeit wenden außerdem agents.defaults.models["provider/model"].params.thinking für das ausgewählte Modell an. Ein explizites sessions_spawn.thinking hat weiterhin Vorrang.
• Lauf-Timeout: OpenClaw verwendet agents.defaults.subagents.runTimeoutSeconds, wenn gesetzt; andernfalls fällt es auf 0 zurück (kein Timeout). sessions_spawn akzeptiert keine Timeout-Overrides pro Aufruf.
• Aufgabenzustellung: Native Unteragenten erhalten die delegierte Aufgabe in ihrer ersten sichtbaren [Subagent Task]-Nachricht. Der Systemprompt des Unteragenten trägt Laufzeitregeln und Routing-Kontext, kein verstecktes Duplikat der Aufgabe.

​

Delegations-Prompt-Modus

• suggest (Standard): den standardmäßigen Prompt-Hinweis beibehalten, Unteragenten für größere oder langsamere Arbeit zu verwenden.
• prefer: den Hauptagenten anweisen, reaktionsfähig zu bleiben und alles, was aufwendiger als eine direkte Antwort ist, über sessions_spawn zu delegieren.

{
  agents: {
    defaults: {
      subagents: {
        delegationMode: "prefer",
        maxConcurrent: 4,
      },
    },
    list: [
      {
        id: "coordinator",
        subagents: { delegationMode: "prefer" },
      },
    ],
  },
}

​

Tool-Parameter

​

Aufgabennamen und Targeting

​

Tool: sessions_yield

​

Tool: subagents

​

Thread-gebundene Sitzungen

​

Channels mit Thread-Unterstützung

​

Schnellablauf

​

Manuelle Steuerungen

​

Konfigurationsschalter

• Globaler Standard: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Channel-Override und Schlüssel für automatisches Binden beim Start sind adapterspezifisch. Siehe Channels mit Thread-Unterstützung oben.

​

Allowlist

​

Erkennung

​

Automatisches Archivieren

• Sub-Agent-Sitzungen werden automatisch nach agents.defaults.subagents.archiveAfterMinutes archiviert (Standard 60).
• Das Archivieren verwendet sessions.delete und benennt das Transkript in *.deleted.<timestamp> um (gleicher Ordner).
• cleanup: "delete" archiviert unmittelbar nach der Ankündigung (behält das Transkript weiterhin durch Umbenennen bei).
• Automatisches Archivieren erfolgt nach bestem Bemühen; ausstehende Timer gehen verloren, wenn der Gateway neu startet.
• Konfigurierte Laufzeit-Timeouts archivieren nicht automatisch; sie stoppen nur den Lauf. Die Sitzung bleibt bis zum automatischen Archivieren bestehen.
• Automatisches Archivieren gilt gleichermaßen für Sitzungen der Tiefe 1 und Tiefe 2.
• Browser-Bereinigung ist von Archivbereinigung getrennt: Nachverfolgte Browser-Tabs/-Prozesse werden nach bestem Bemühen geschlossen, wenn der Lauf endet, auch wenn das Transkript/der Sitzungsdatensatz beibehalten wird.

​

Verschachtelte Sub-Agents

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
        maxConcurrent: 8, // global concurrency lane cap (default: 8)
        runTimeoutSeconds: 900, // default timeout for sessions_spawn (0 = no timeout)
        announceTimeoutMs: 120000, // per-call gateway announce timeout
      },
    },
  },
}

​

Tiefenstufen

​

Ankündigungskette

1. Worker der Tiefe 2 beendet seine Arbeit → kündigt dies seinem Parent (Orchestrator der Tiefe 1) an.
2. Orchestrator der Tiefe 1 empfängt die Ankündigung, synthetisiert Ergebnisse, beendet seine Arbeit → kündigt dies Main an.
3. Main-Agent empfängt die Ankündigung und liefert sie an den Benutzer.

​

Tool-Richtlinie nach Tiefe

• Rolle und Kontrollumfang werden beim Spawn-Zeitpunkt in die Session-Metadaten geschrieben. Dadurch können flache oder wiederhergestellte Session-Schlüssel nicht versehentlich Orchestrator-Privilegien zurückerlangen.
• Tiefe 1 (Orchestrator, wenn maxSpawnDepth >= 2): erhält sessions_spawn, subagents, sessions_list, sessions_history, damit er Children spawnen und ihren Status prüfen kann. Andere Session-/System-Tools bleiben verweigert.
• Tiefe 1 (Leaf, wenn maxSpawnDepth == 1): keine Session-Tools (aktuelles Standardverhalten).
• Tiefe 2 (Leaf-Worker): keine Session-Tools — sessions_spawn wird in Tiefe 2 immer verweigert. Kann keine weiteren Children spawnen.

​

Spawn-Limit pro Agent

​

Kaskadierender Stopp

• /stop im Main-Chat stoppt alle Agenten der Tiefe 1 und kaskadiert zu deren Children der Tiefe 2.

​

Authentifizierung

• Der Sub-Agent-Session-Schlüssel ist agent:<agentId>:subagent:<uuid>.
• Der Auth-Store wird aus dem agentDir dieses Agenten geladen.
• Die Auth-Profile des Main-Agenten werden als Fallback eingebunden; Agent-Profile überschreiben Main-Profile bei Konflikten.

​

Ankündigung

• Der Ankündigungsschritt läuft innerhalb der Sub-Agent-Session (nicht in der Requester-Session).
• Wenn der Sub-Agent exakt ANNOUNCE_SKIP antwortet, wird nichts gepostet.
• Wenn der neueste Assistant-Text das exakte stille Token NO_REPLY / no_reply ist, wird die Ankündigungsausgabe unterdrückt, auch wenn zuvor sichtbarer Fortschritt vorhanden war.

• Top-Level-Requester-Sessions verwenden einen Follow-up-agent-Aufruf mit externer Zustellung (deliver=true).
• Verschachtelte Requester-Subagent-Sessions erhalten eine interne Follow-up-Injektion (deliver=false), damit der Orchestrator Child-Ergebnisse innerhalb der Session synthetisieren kann.
• Wenn eine verschachtelte Requester-Subagent-Session nicht mehr vorhanden ist, fällt OpenClaw, sofern verfügbar, auf den Requester dieser Session zurück.

​

Ankündigungskontext

​

Statistikzeile

• Runtime (z. B. runtime 5m12s).
• Token-Nutzung (Input/Output/Gesamt).
• Geschätzte Kosten, wenn Modellpreise konfiguriert sind (models.providers.*.models[].cost).
• sessionKey, sessionId und Transkriptpfad, damit der Main-Agent den Verlauf über sessions_history abrufen oder die Datei auf dem Datenträger prüfen kann.

​

Warum sessions_history bevorzugen

• Assistant-Recall wird zuerst normalisiert: Thinking-Tags entfernt; <relevant-memories>- / <relevant_memories>-Scaffolding entfernt; Plain-Text-Tool-Call-XML-Payload-Blöcke (<tool_call>, <function_call>, <tool_calls>, <function_calls>) entfernt, einschließlich abgeschnittener Payloads, die nie sauber schließen; herabgestuftes Tool-Call-/Result-Scaffolding und Historical-Context-Marker entfernt; geleakte Modell-Steuerungstokens (<|assistant|>, andere ASCII-<|...|>, Full-Width-<｜...｜>) entfernt; fehlerhaftes MiniMax-Tool-Call-XML entfernt.
• Zugangsdaten-/Token-ähnlicher Text wird redigiert.
• Lange Blöcke können gekürzt werden.
• Sehr große Verläufe können ältere Zeilen verwerfen oder eine übergroße Zeile durch [sessions_history omitted: message too large] ersetzen.
• Verwenden Sie nextOffset, wenn vorhanden, um rückwärts durch ältere Transkriptfenster zu blättern.
• Die rohe Prüfung des Transkripts auf dem Datenträger ist der Fallback, wenn Sie das vollständige bytegenaue Transkript benötigen.

​

Tool-Richtlinie

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn
• message

​

Override per Konfiguration

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny wins
        deny: ["gateway", "cron"],
        // if allow is set, it becomes allow-only (deny still wins)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

​

Parallelität

• Lane-Name: subagent
• Parallelität: agents.defaults.subagents.maxConcurrent (Standard 8)

​

Liveness und Wiederherstellung

​

Stoppen

• Das Senden von /stop im Requester-Chat bricht die Requester-Session ab und stoppt alle aktiven Sub-Agent-Runs, die daraus gespawnt wurden, mit Kaskadierung zu verschachtelten Children.

​

Einschränkungen

• Sub-Agent-Ankündigung ist Best-Effort. Wenn der Gateway neu startet, geht ausstehende „announce back“-Arbeit verloren.
• Sub-Agenten teilen weiterhin dieselben Gateway-Prozessressourcen; behandeln Sie maxConcurrent als Sicherheitsventil.
• sessions_spawn ist immer nicht blockierend: Es gibt sofort { status: "accepted", runId, childSessionKey } zurück.
• Sub-Agent-Kontext injiziert nur AGENTS.md und TOOLS.md (kein SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md oder BOOTSTRAP.md). Codex-native Subagents folgen derselben Grenze: TOOLS.md bleibt in geerbten Codex-Thread-Anweisungen, während Parent-only-Persona-, Identitäts- und Benutzerdateien als turn-scoped Kollaborationsanweisungen injiziert werden, damit Children sie nicht klonen.
• Maximale Verschachtelungstiefe ist 5 (maxSpawnDepth-Bereich: 1–5). Tiefe 2 wird für die meisten Anwendungsfälle empfohlen.
• maxChildrenPerAgent begrenzt aktive Children pro Session (Standard 5, Bereich 1–20).

​

Verwandt

• ACP-Agenten
• Agent senden
• Hintergrund-Tasks
• Multi-Agent-Sandbox-Tools