ACP-Agenten

Agent Client Protocol (ACP)-Sitzungen ermöglichen es OpenClaw, externe Coding-Harnesses (zum Beispiel Pi, Claude Code, Codex, OpenCode und Gemini CLI) über ein ACP-Backend-Plugin auszuführen.

Wenn du OpenClaw in natürlicher Sprache bittest, etwas „in Codex auszuführen” oder „Claude Code in einem Thread zu starten”, leitet OpenClaw diese Anfrage an die ACP-Laufzeit weiter (nicht an die native Sub-Agent-Laufzeit).

Schneller Operator-Ablauf

Nutze dies, wenn du ein praktisches /acp-Runbook brauchst:

1. Sitzung starten:
   • /acp spawn codex --mode persistent --thread auto
2. Im gebundenen Thread arbeiten (oder den Session-Key explizit angeben).
3. Laufzeitstatus prüfen:
   • /acp status
4. Laufzeitoptionen bei Bedarf anpassen:
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. Aktive Sitzung anstoßen, ohne den Kontext zu ersetzen:
   • /acp steer tighten logging and continue
6. Arbeit beenden:
   • /acp cancel (aktuellen Turn stoppen), oder
   • /acp close (Sitzung schließen + Bindungen entfernen)

Schnellstart für Menschen

Beispiele für natürliche Anfragen:

• „Starte eine persistente Codex-Sitzung in einem Thread hier und halte sie fokussiert.”
• „Führe das als einmalige Claude Code ACP-Sitzung aus und fasse das Ergebnis zusammen.”
• „Nutze Gemini CLI für diese Aufgabe in einem Thread und behalte Follow-ups im selben Thread.”

Was OpenClaw tun sollte:

1. runtime: "acp" wählen.
2. Das angeforderte Harness-Ziel auflösen (agentId, zum Beispiel codex).
3. Wenn Thread-Bindung gewünscht und der aktuelle Kanal dies unterstützt, die ACP-Sitzung an den Thread binden.
4. Folgenachrichten im Thread an dieselbe ACP-Sitzung weiterleiten, bis unfokussiert/geschlossen/abgelaufen.

ACP versus Sub-Agenten

Verwende ACP, wenn du eine externe Harness-Laufzeit möchtest. Verwende Sub-Agenten, wenn du native delegierte OpenClaw-Läufe möchtest.

Siehe auch Sub-Agenten.

Thread-gebundene Sitzungen (kanalunabhängig)

Wenn Thread-Bindungen für einen Kanaladapter aktiviert sind, können ACP-Sitzungen an Threads gebunden werden:

• OpenClaw bindet einen Thread an eine Ziel-ACP-Sitzung.
• Folgenachrichten in diesem Thread werden an die gebundene ACP-Sitzung weitergeleitet.
• ACP-Ausgaben werden im selben Thread zurückgeliefert.
• Unfokussierung/Schließen/Archivierung/Idle-Timeout oder Max-Age-Ablauf entfernt die Bindung.

Thread-Bindungsunterstützung ist adapterspezifisch. Wenn der aktive Kanaladapter keine Thread-Bindungen unterstützt, gibt OpenClaw eine klare Meldung „nicht unterstützt/nicht verfügbar” zurück.

Erforderliche Feature-Flags für Thread-gebundenes ACP:

• acp.enabled=true
• acp.dispatch.enabled ist standardmäßig aktiviert (auf false setzen, um ACP-Dispatch zu pausieren)
• Kanaladapter-ACP-Thread-Spawn-Flag aktiviert (adapterspezifisch)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

Kanäle mit Thread-Unterstützung

• Jeder Kanaladapter, der Session-/Thread-Bindungsfähigkeit bietet.
• Aktuelle integrierte Unterstützung:
  • Discord-Threads/Kanäle
  • Telegram-Topics (Forum-Topics in Gruppen/Supergruppen und DM-Topics)
• Plugin-Kanäle können Unterstützung über die gleiche Bindungsschnittstelle hinzufügen.

Kanalspezifische Einstellungen

Für nicht-ephemere Workflows konfiguriere persistente ACP-Bindungen in den bindings[]-Einträgen auf oberster Ebene.

Bindungsmodell

• bindings[].type="acp" markiert eine persistente ACP-Gesprächsbindung.
• bindings[].match identifiziert die Zielkonversation:
  • Discord-Kanal oder -Thread: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Telegram-Forum-Topic: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
• bindings[].agentId ist die zugehörige OpenClaw-Agent-ID.
• Optionale ACP-Überschreibungen unter bindings[].acp:
  • mode (persistent oder oneshot)
  • label
  • cwd
  • backend

Laufzeit-Standardwerte pro Agent

Verwende agents.list[].runtime, um ACP-Standardwerte einmal pro Agent zu definieren:

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent (Harness-ID, zum Beispiel codex oder claude)
• agents.list[].runtime.acp.backend
• agents.list[].runtime.acp.mode
• agents.list[].runtime.acp.cwd

Überschreibungs-Reihenfolge für ACP-gebundene Sitzungen:

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. Globale ACP-Standardwerte (zum Beispiel acp.backend)

Beispiel:

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
      {
        id: "claude",
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}

Verhalten:

• OpenClaw stellt sicher, dass die konfigurierte ACP-Sitzung vor der Nutzung existiert.
• Nachrichten in diesem Kanal oder Topic werden an die konfigurierte ACP-Sitzung weitergeleitet.
• In gebundenen Konversationen setzen /new und /reset den gleichen ACP-Session-Key vor Ort zurück.
• Temporäre Laufzeit-Bindungen (zum Beispiel durch Thread-Focus-Flows erstellt) gelten weiterhin, wo vorhanden.

ACP-Sitzungen starten (Schnittstellen)

Über sessions_spawn

Verwende runtime: "acp", um eine ACP-Sitzung aus einem Agent-Turn oder Tool-Aufruf zu starten.

{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

Hinweise:

• runtime ist standardmäßig subagent, setze also runtime: "acp" explizit für ACP-Sitzungen.
• Wenn agentId weggelassen wird, verwendet OpenClaw acp.defaultAgent, sofern konfiguriert.
• mode: "session" erfordert thread: true, um eine persistente gebundene Konversation aufrechtzuerhalten.

Schnittstellendetails:

• task (erforderlich): Initialer Prompt, der an die ACP-Sitzung gesendet wird.
• runtime (erforderlich für ACP): muss "acp" sein.
• agentId (optional): ACP-Ziel-Harness-ID. Fällt auf acp.defaultAgent zurück, wenn gesetzt.
• thread (optional, Standard false): Thread-Bindungs-Flow anfordern, wo unterstützt.
• mode (optional): run (einmalig) oder session (persistent).
  • Standard ist run
  • wenn thread: true und mode weggelassen, kann OpenClaw je nach Laufzeitpfad standardmäßig persistentes Verhalten verwenden
  • mode: "session" erfordert thread: true
• cwd (optional): Gewünschtes Laufzeit-Arbeitsverzeichnis (vom Backend/der Laufzeit-Richtlinie validiert).
• label (optional): Operator-sichtbares Label für Session-/Banner-Text.
• resumeSessionId (optional): Eine bestehende ACP-Sitzung fortsetzen, anstatt eine neue zu erstellen. Der Agent spielt seinen Gesprächsverlauf über session/load ab. Erfordert runtime: "acp".
• streamTo (optional): "parent" streamt initiale ACP-Lauffortschrittszusammenfassungen als Systemereignisse an die Anforderersitzung zurück.
  • Wenn verfügbar, enthalten akzeptierte Antworten streamLogPath, der auf ein sitzungsbezogenes JSONL-Log (<sessionId>.acp-stream.jsonl) zeigt, das du für die vollständige Relay-Historie verfolgen kannst.

Bestehende Sitzung fortsetzen

Verwende resumeSessionId, um eine vorherige ACP-Sitzung fortzusetzen, anstatt neu zu beginnen. Der Agent spielt seinen Gesprächsverlauf über session/load ab, sodass er mit dem vollständigen Kontext des Vorherigen fortfährt.

{
  "task": "Continue where we left off — fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

Häufige Anwendungsfälle:

• Eine Codex-Sitzung von deinem Laptop auf dein Telefon übergeben — sage deinem Agenten, er soll dort weitermachen, wo du aufgehört hast
• Eine Coding-Sitzung fortsetzen, die du interaktiv in der CLI begonnen hast, jetzt kopflos über deinen Agenten
• Arbeit wieder aufnehmen, die durch einen Gateway-Neustart oder Idle-Timeout unterbrochen wurde

Hinweise:

• resumeSessionId erfordert runtime: "acp" — gibt einen Fehler zurück, wenn es mit der Sub-Agent-Laufzeit verwendet wird.
• resumeSessionId stellt den vorgelagerten ACP-Gesprächsverlauf wieder her; thread und mode gelten weiterhin normal für die neue OpenClaw-Sitzung, die du erstellst, also erfordert mode: "session" weiterhin thread: true.
• Der Ziel-Agent muss session/load unterstützen (Codex und Claude Code tun dies).
• Wenn die Session-ID nicht gefunden wird, schlägt der Spawn mit einem klaren Fehler fehl — kein stiller Fallback auf eine neue Sitzung.

Operator-Smoke-Test

Verwende dies nach einem Gateway-Deploy, wenn du einen schnellen Live-Check möchtest, ob ACP-Spawn tatsächlich durchgängig funktioniert und nicht nur Unit-Tests besteht.

Empfohlener Gate-Check:

1. Verifiziere die deployte Gateway-Version/den Commit auf dem Zielhost.
2. Bestätige, dass der deployte Quellcode die ACP-Lineage-Akzeptanz in src/gateway/sessions-patch.ts (subagent:* or acp:* sessions) enthält.
3. Öffne eine temporäre ACPX-Bridge-Sitzung zu einem Live-Agenten (zum Beispiel razor(main) auf jpclawhq).
4. Bitte diesen Agenten, sessions_spawn aufzurufen mit:
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • task: Reply with exactly LIVE-ACP-SPAWN-OK
5. Verifiziere, dass der Agent meldet:
   • accepted=yes
   • einen echten childSessionKey
   • keinen Validierungsfehler
6. Räume die temporäre ACPX-Bridge-Sitzung auf.

Beispiel-Prompt an den Live-Agenten:

Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.

Hinweise:

• Halte diesen Smoke-Test auf mode: "run", es sei denn, du testest bewusst Thread-gebundene persistente ACP-Sitzungen.
• Fordere nicht streamTo: "parent" für den Basis-Gate-Check an. Dieser Pfad hängt von Requester-/Session-Fähigkeiten ab und ist ein separater Integrationscheck.
• Behandle Thread-gebundenes mode: "session"-Testing als zweiten, umfangreicheren Integrationspass von einem echten Discord-Thread oder Telegram-Topic aus.

Sandbox-Kompatibilität

ACP-Sitzungen laufen derzeit auf der Host-Laufzeit, nicht innerhalb der OpenClaw-Sandbox.

Aktuelle Einschränkungen:

• Wenn die Anforderersitzung gesandboxt ist, werden ACP-Spawns sowohl für sessions_spawn({ runtime: "acp" }) als auch für /acp spawn blockiert.
  • Fehler: Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
• sessions_spawn mit runtime: "acp" unterstützt sandbox: "require" nicht.
  • Fehler: sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

Verwende runtime: "subagent", wenn du Sandbox-erzwungene Ausführung benötigst.

Über den /acp-Befehl

Verwende /acp spawn für explizite Operator-Kontrolle aus dem Chat, wenn nötig.

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --thread here

Wichtige Flags:

• --mode persistent|oneshot
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

Siehe Slash-Befehle.

Session-Zielauflösung

Die meisten /acp-Aktionen akzeptieren ein optionales Sitzungsziel (session-key, session-id oder session-label).

Auflösungsreihenfolge:

1. Explizites Zielargument (oder --session für /acp steer)
   • versucht Key
   • dann UUID-förmige Session-ID
   • dann Label
2. Aktuelle Thread-Bindung (wenn diese Konversation/dieser Thread an eine ACP-Sitzung gebunden ist)
3. Fallback auf aktuelle Anforderersitzung

Wenn kein Ziel aufgelöst werden kann, gibt OpenClaw einen klaren Fehler zurück (Unable to resolve session target: ...).

Spawn-Thread-Modi

/acp spawn unterstützt --thread auto|here|off.

Hinweise:

• Auf Oberflächen ohne Thread-Bindung ist das Standardverhalten effektiv off.
• Thread-gebundener Spawn erfordert Kanalrichtlinien-Unterstützung:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

ACP-Steuerungen

Verfügbare Befehlsfamilie:

• /acp spawn
• /acp cancel
• /acp steer
• /acp close
• /acp status
• /acp set-mode
• /acp set
• /acp cwd
• /acp permissions
• /acp timeout
• /acp model
• /acp reset-options
• /acp sessions
• /acp doctor
• /acp install

/acp status zeigt die effektiven Laufzeitoptionen und, wenn verfügbar, sowohl Laufzeit- als auch Backend-Level-Sitzungskennungen.

Einige Steuerungen hängen von Backend-Fähigkeiten ab. Wenn ein Backend eine Steuerung nicht unterstützt, gibt OpenClaw einen klaren Fehler „nicht unterstützte Steuerung” zurück.

ACP-Befehlskochbuch

/acp sessions liest den Store für die aktuell gebundene oder anfordernde Sitzung. Befehle, die session-key-, session-id- oder session-label-Token akzeptieren, lösen Ziele über die Gateway-Session-Discovery auf, einschließlich benutzerdefinierter session.store-Roots pro Agent.

Laufzeitoptionen-Zuordnung

/acp hat Komfortbefehle und einen generischen Setter.

Äquivalente Operationen:

• /acp model <id> wird auf den Laufzeit-Konfigurationsschlüssel model abgebildet.
• /acp permissions <profile> wird auf den Laufzeit-Konfigurationsschlüssel approval_policy abgebildet.
• /acp timeout <seconds> wird auf den Laufzeit-Konfigurationsschlüssel timeout abgebildet.
• /acp cwd <path> aktualisiert die Laufzeit-cwd-Überschreibung direkt.
• /acp set <key> <value> ist der generische Pfad.
  • Sonderfall: key=cwd verwendet den cwd-Überschreibungspfad.
• /acp reset-options löscht alle Laufzeitüberschreibungen für die Zielsitzung.

acpx-Harness-Unterstützung (aktuell)

Aktuelle integrierte acpx-Harness-Aliase:

• pi
• claude
• codex
• opencode
• gemini
• kimi

Wenn OpenClaw das acpx-Backend verwendet, bevorzuge diese Werte für agentId, es sei denn, deine acpx-Konfiguration definiert benutzerdefinierte Agent-Aliase.

Direkte acpx-CLI-Nutzung kann auch beliebige Adapter über --agent <command> ansprechen, aber diese Escape-Hatch ist ein acpx-CLI-Feature (nicht der normale OpenClaw-agentId-Pfad).

Erforderliche Konfiguration

Grundlegende ACP-Basiskonfiguration:

{
  acp: {
    enabled: true,
    // Optional. Standard ist true; auf false setzen, um ACP-Dispatch zu pausieren, während /acp-Steuerungen erhalten bleiben.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

Thread-Bindungskonfiguration ist kanaladapterspezifisch. Beispiel für Discord:

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

Wenn Thread-gebundener ACP-Spawn nicht funktioniert, überprüfe zuerst das Adapter-Feature-Flag:

• Discord: channels.discord.threadBindings.spawnAcpSessions=true

Siehe Konfigurationsreferenz.

Plugin-Einrichtung für das acpx-Backend

Plugin installieren und aktivieren:

openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

Lokale Workspace-Installation während der Entwicklung:

openclaw plugins install ./extensions/acpx

Dann Backend-Gesundheit überprüfen:

/acp doctor

acpx-Befehl und Versionskonfiguration

Standardmäßig verwendet das acpx-Plugin (veröffentlicht als @openclaw/acpx) die plugin-lokal gepinnte Binary:

1. Befehl wird standardmäßig auf extensions/acpx/node_modules/.bin/acpx gesetzt.
2. Erwartete Version wird standardmäßig auf den Extension-Pin gesetzt.
3. Beim Start wird das ACP-Backend sofort als nicht bereit registriert.
4. Ein Hintergrund-Ensure-Job überprüft acpx --version.
5. Wenn die plugin-lokale Binary fehlt oder nicht übereinstimmt, wird ausgeführt: npm install --omit=dev --no-save acpx@<pinned> und erneut überprüft.

Du kannst Befehl/Version in der Plugin-Konfiguration überschreiben:

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

Hinweise:

• command akzeptiert einen absoluten Pfad, relativen Pfad oder Befehlsnamen (acpx).
• Relative Pfade werden vom OpenClaw-Workspace-Verzeichnis aufgelöst.
• expectedVersion: "any" deaktiviert den strikten Versionsabgleich.
• Wenn command auf eine benutzerdefinierte Binary/einen Pfad zeigt, wird die plugin-lokale Auto-Installation deaktiviert.
• Der OpenClaw-Start bleibt nicht-blockierend, während der Backend-Gesundheitscheck läuft.

Siehe Plugins.

Berechtigungskonfiguration

ACP-Sitzungen laufen nicht-interaktiv — es gibt kein TTY, um Datei-Schreib- und Shell-Exec-Berechtigungsanfragen zu genehmigen oder abzulehnen. Das acpx-Plugin bietet zwei Konfigurationsschlüssel, die steuern, wie Berechtigungen behandelt werden:

permissionMode

Steuert, welche Operationen der Harness-Agent ohne Aufforderung durchführen kann.

nonInteractivePermissions

Steuert, was passiert, wenn eine Berechtigungsanfrage angezeigt würde, aber kein interaktives TTY verfügbar ist (was bei ACP-Sitzungen immer der Fall ist).

Konfiguration

Per Plugin-Konfiguration setzen:

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Starte das Gateway nach dem Ändern dieser Werte neu.

Wichtig: OpenClaw verwendet derzeit standardmäßig permissionMode=approve-reads und nonInteractivePermissions=fail. In nicht-interaktiven ACP-Sitzungen kann jeder Schreib- oder Exec-Vorgang, der eine Berechtigungsanfrage auslöst, mit AcpRuntimeError: Permission prompt unavailable in non-interactive mode fehlschlagen.

Wenn du Berechtigungen einschränken musst, setze nonInteractivePermissions auf deny, damit Sitzungen graceful degradieren, anstatt abzustürzen.

Fehlerbehebung