ACP-Agenten in OpenClaw

Sie möchten Claude Code oder Gemini CLI aus einer Telegram-Nachricht statt aus einem Terminal steuern, und OpenClaw kann das über das Agent Client Protocol. Eine ACP-Sitzung startet das echte externe Harness als Prozess auf dem Gateway-Host, verfolgt jeden Start als Hintergrundaufgabe und kann eine Unterhaltung oder einen Thread binden, damit Folgenachrichten weiterhin dasselbe Harness erreichen. Dafür braucht es zuerst ein Runtime-Plugin, und eine kurze Liste von Bedingungen entscheidet, ob Ihr Agent überhaupt erfährt, dass es diesen Weg gibt.

Das acpx-Runtime-Plugin installieren

• Paketierte Installationen verwenden das offizielle acpx-Runtime-Plugin, das unter dem openclaw-Scope auf npm veröffentlicht ist, und es sind zwei Befehle: openclaw plugins install mit dem Namen dieses Pakets mit Scope, dann openclaw config set plugins.entries.acpx.enabled true. Source-Checkouts können stattdessen nach pnpm install das lokale Workspace-Plugin extensions/acpx verwenden. Führen Sie danach /acp doctor für eine Bereitschaftsprüfung aus, oder /acp install, damit OpenClaw die deterministischen Installations- und Aktivierungsschritte ausgibt.
• Wenn plugins.allow gesetzt ist, ist es ein restriktives Plugin-Inventar und kein Hinweis, und es muss acpx enthalten, sonst wird das installierte ACP-Backend absichtlich blockiert. Das ist der Fehler beim ersten Start, der am häufigsten als kaputte Installation missverstanden wird; er zeigt sich als Fehlermeldung, dass das ACP-Runtime-Backend nicht konfiguriert ist. /acp doctor meldet den fehlenden Zulassungslisten-Eintrag, statt Sie raten zu lassen.
• Das acpx-Plugin bettet die ACP-Runtime direkt ein, daher gibt es kein separates acpx-Binary und keine Version zu konfigurieren. Es registriert das eingebettete Backend beim Start des Gateways und wartet auf eine Health-Probe, bevor das Gateway sein Ready-Signal gibt; diese Probe liefert auch die Fehlerdiagnose. Sie ist durch plugins.entries.acpx.config.timeoutSeconds begrenzt, das standardmäßig 120 Sekunden beträgt, damit langsamere Harnesses wie Gemini CLI den ACP-Start und die Initialisierung abschließen können.
• Der Codex-ACP-Adapter wird mit dem acpx-Plugin ausgeliefert und startet nach Möglichkeit lokal, mit einem isolierten CODEX_HOME, in das OpenClaw vertrauenswürdige Projekt-Trust-Einträge sowie sichere Konfiguration für Modell- und Anbieter-Routing kopiert, während Authentifizierung, Benachrichtigungen und Hooks ausschließlich in der Host-Konfiguration bleiben. Andere Harness-Adapter werden bei der ersten Nutzung unter Umständen bei Bedarf mit npx geladen, sodass ein Host ohne npm oder Netzwerkzugang an diesen Downloads scheitert, bis die Caches vorgewärmt sind oder der Adapter auf anderem Weg installiert ist.

Wenn eine Bedingung nicht erfüllt ist, bleiben die ACP-Skills und die ACP-Hinweise von sessions_spawn verborgen, damit der Agent kein nicht verfügbares Backend vorschlägt.

Warum die ACP-Skills unsichtbar sein können

Die Bedingungen sind vollständig aufgeführt: ACP muss aktiviert sein, Dispatch darf nicht deaktiviert sein, die aktuelle Sitzung darf nicht durch die Sandbox blockiert sein, und ein Runtime-Backend muss geladen und funktionsfähig sein. Ein Agent, der noch nie einen ACP-Start angeboten hat, gibt in der Regel seine eigene Konfiguration korrekt wieder, statt Sie zu ignorieren. Die beiden Hälften scheitern unterschiedlich: acp.dispatch.enabled=false pausiert den automatischen ACP-Thread-Dispatch, ohne einen expliziten sessions_spawn-Aufruf mit runtime acp zu verbergen oder zu blockieren, während ein Anfragender in einer Sandbox rundweg abgewiesen wird, weil die ACP-Runtime auf dem Host läuft. Aus einer Sandbox-Sitzung heraus ist die dokumentierte Antwort die Subagent-Runtime.

Die Checkliste der Voraussetzungen

• Bevor Sie OpenClaw die Schuld geben, prüfen Sie, dass /acp doctor ein aktiviertes und funktionsfähiges Backend meldet, dass die Ziel-ID von acp.allowedAgents erlaubt ist, wenn diese Zulassungsliste gesetzt ist, und dass der Harness-Befehl auf dem Gateway-Host tatsächlich starten kann. Jeder dieser Punkte hat seine eigene Fehlermeldung statt eines generischen Fehlers, sodass die Meldung, die Sie erhalten, die Ursache bereits eingrenzt.
• Die Anbieter-Authentifizierung für das Harness, das Sie ansprechen, muss bereits auf dem Host vorhanden sein: claude, codex, gemini, opencode, droid und die übrigen haben jeweils ihre eigene Anmeldung. Ein Authentifizierungsfehler des Anbieters bedeutet, dass OpenClaw funktioniert und die Ziel-CLI oder der Anbieter schlicht nicht angemeldet ist; das beheben Sie, indem Sie sich anmelden oder den Anbieterschlüssel in der Umgebung des Gateway-Hosts bereitstellen, nicht durch Änderungen an der OpenClaw-Konfiguration.
• Das gewählte Modell muss für dieses Harness existieren, denn Modell-IDs sind nicht zwischen Harnesses übertragbar, und die Modellsteuerung hängt von den Fähigkeiten des Adapters ab: Ein Harness, das weder die ACP-Fähigkeit models noch ein eigenes Start-Flag für das Modell anbietet, lässt sich überhaupt nicht auf ein Modell festlegen. Das angeforderte cwd muss existieren und zugänglich sein, oder Sie lassen es weg und überlassen dem Backend seinen Standardwert.

Eine Sache entscheidet die Wahl, bevor Sie irgendeine Konfiguration schreiben: OpenClaw-Plugin-Tools und integrierte OpenClaw-Tools werden ACP-Harnesses standardmäßig nicht bereitgestellt, und die beiden MCP-Bridges, die das ändern, sind explizit und standardmäßig deaktiviert. Wenn Sie einen OpenClaw-nativen delegierten Lauf mit den eigenen Tools von OpenClaw wollen, ist das ein Lauf über die Sub-Agenten von OpenClaw, mit eigenem Sitzungs-Schlüssel und eigenem Slash-Befehl; wenn Sie nur eine lokale KI-CLI als reines Text-Fallback-Modell wollen, sind die CLI-Backends von OpenClaw weder ACP noch eine Harness-Runtime, ohne OpenClaw-Tools und ohne ACP-Steuerung.

Die siebzehn Harness-Ziel-IDs

Mit dem acpx-Backend sind dies die IDs, die Sie an /acp spawn oder an sessions_spawn als agentId übergeben: claude, codex, copilot, cursor, droid, fast-agent, gemini, iflow, kilocode, kimi, kiro, mux, opencode, openclaw, qoder, qwen und trae. claude braucht eine Claude-Code-Authentifizierung auf dem Host, copilot eine Anmeldung bei der Copilot CLI oder Runtime, cursor führt cursor-agent acp aus, droid braucht eine Factory- oder Droid-Authentifizierung oder FACTORY_API_KEY in der Harness-Umgebung, gemini eine Gemini-CLI-Authentifizierung oder einen eingerichteten API-Schlüssel, opencode eine OpenCode-CLI- oder Anbieter-Authentifizierung, und openclaw ist die Gateway-Bridge, über die ein ACP-fähiges Harness mit einer OpenClaw-Gateway-Sitzung kommunizieren kann. codex ist der explizite ACP-Fallback, der nur verwendet wird, wenn der native /codex-Pfad nicht verfügbar ist oder ACP ausdrücklich angefordert wird. pi ist ebenfalls im acpx-Backend registriert, ist aber kein Coding-Harness im selben Sinn. Jeder Start landet in den Hintergrundaufgaben von OpenClaw, und bei den Berechtigungsmodi von OpenClaw liegen die Einstellungen auf Harness-Ebene neben den Exec-Freigaben von OpenClaw: Eine ACP-Sitzung hat kein interaktives TTY, daher braucht schreib- und ausführungsintensives Coding in der Regel ein Profil, das ohne Interaktion weiterarbeiten kann.

Bei Diali

Diali hostet OpenClaw für Sie, und jeder Kunde betreibt seinen eigenen Assistenten statt eines Stücks von einem geteilten. Die Runtime-Konfiguration wird aus dem Dashboard erzeugt und bei jedem Release ersetzt, sodass Richtlinienschlüssel für Sie geschrieben werden, statt von Hand auf einer Maschine bearbeitet zu werden, an die Sie denken müssen. Der Zustand liegt auf einem persistenten Volume, das eine Sitzung und ihren Verlauf über ein Upgrade hinweg erhält; tägliche Snapshots und Wiederherstellung mit einem Klick gibt es über das Add-on Backups (in Max enthalten). Gehostetes OpenClaw bei Diali erklärt, was die gehostete Runtime abdeckt, und die Preisseite von Diali listet die Tarife auf.

• Zwei Befehle installieren acpx, danach vor allem anderen /acp doctor.
• Verborgene ACP-Hinweise bedeuten eine nicht erfüllte Bedingung, keine fehlende Funktion.
• Siebzehn Harness-IDs, jede mit eigener Anmeldung auf dem Host.