ACP-Agenten — Einrichtung

Eine Übersicht, das Betriebshandbuch und die Konzepte finden Sie unter ACP-Agenten.

Diese Seite behandelt die acpx-Harness-Konfiguration, die Plugin-Einrichtung für die MCP-Bridges und die Berechtigungskonfiguration.

Verwenden Sie diese Seite nur, wenn Sie die ACP/acpx-Route einrichten. Für die native Codex- App-Server-Laufzeitkonfiguration verwenden Sie Codex-Harness. Für OpenAI-API-Schlüssel oder die Codex-OAuth-Konfiguration des Modell-Providers verwenden Sie OpenAI.

Codex verfügt über zwei OpenClaw-Routen:

Bevorzugen Sie die native Route, sofern Sie nicht ausdrücklich ACP/acpx-Verhalten benötigen.

acpx-Harness-Unterstützung (aktuell)

Integrierte acpx-Harness-Aliasse (aus der festgelegten acpx-Abhängigkeit):

factory-droid und factorydroid werden ebenfalls zum integrierten droid-Adapter aufgelöst.

Wenn OpenClaw das acpx-Backend verwendet, bevorzugen Sie diese Werte für agentId, sofern Ihre acpx-Konfiguration keine benutzerdefinierten Agentenaliase definiert. Falls Ihre lokale Cursor-Installation ACP weiterhin als agent acp bereitstellt, überschreiben Sie den Befehl des cursor-Agenten in Ihrer acpx-Konfiguration, anstatt den integrierten Standard zu ändern.

Bei der direkten Verwendung der acpx-CLI können über --agent <command> auch beliebige Adapter angegeben werden. Dieser direkte Ausweg ist jedoch eine Funktion der acpx-CLI und nicht der normale agentId-Pfad von OpenClaw.

Die Modellsteuerung hängt von den Fähigkeiten des Adapters ab. Codex-ACP-Modellreferenzen werden vor dem Start von OpenClaw normalisiert. Andere Harnesses benötigen die ACP-Fähigkeit models sowie Unterstützung für session/set_model. Wenn ein Harness weder diese ACP-Fähigkeit noch ein eigenes Startflag für das Modell bereitstellt, kann OpenClaw/acpx keine Modellauswahl erzwingen.

Erforderliche Konfiguration

ACP-Kernbasis:

{  acp: {    enabled: true,    // Optional. Standardwert ist true; auf false setzen, um die ACP-Weiterleitung zu pausieren und die /acp-Steuerung beizubehalten.    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "codex",    allowedAgents: [      "claude",      "codex",      "copilot",      "cursor",      "droid",      "gemini",      "iflow",      "kilocode",      "kimi",      "kiro",      "openclaw",      "opencode",      "qwen",    ],    maxConcurrentSessions: 8,    stream: {      // Standardwerte sind coalesceIdleMs: 350, maxChunkChars: 1800; hier ausdrücklich angegeben.      coalesceIdleMs: 350,      maxChunkChars: 1800,    },    runtime: {      ttlMinutes: 120,    },  },}

Die Konfiguration der Thread-Bindung ist vom Kanaladapter abhängig. Beispiel für Discord:

{  session: {    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },  },  channels: {    discord: {      threadBindings: {        enabled: true,        // Der Standardwert ist bereits true; hier ausdrücklich angegeben.        spawnSessions: true,      },    },  },}

Wenn das Starten einer Thread-gebundenen ACP-Sitzung nicht funktioniert, prüfen Sie zuerst das Feature-Flag des Adapters:

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

Bindungen an die aktuelle Unterhaltung erfordern keine Erstellung eines untergeordneten Threads. Sie erfordern einen aktiven Unterhaltungskontext und einen Kanaladapter, der ACP-Unterhaltungsbindungen bereitstellt.

Siehe Konfigurationsreferenz.

Plugin-Einrichtung für das acpx-Backend

Paketinstallationen verwenden das offizielle Laufzeit-Plugin @openclaw/acpx für ACP. Installieren und aktivieren Sie es, bevor Sie ACP-Harness-Sitzungen verwenden:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Quellcode-Checkouts können nach pnpm install auch das lokale Workspace-Plugin verwenden.

Beginnen Sie mit:

/acp doctor

Wenn Sie acpx deaktiviert, es über plugins.allow / plugins.deny abgelehnt haben oder zum paketierten Plugin zurückwechseln möchten, verwenden Sie den ausdrücklichen Paketpfad:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Lokale Workspace-Installation während der Entwicklung:

openclaw plugins install ./path/to/local/acpx-plugin

Prüfen Sie anschließend den Zustand des Backends:

/acp doctor

Startprüfung der acpx-Laufzeit

Das acpx-Plugin bettet die ACP-Laufzeit direkt ein (es gibt keine separate acpx-Binärdatei oder zu konfigurierende Version). Standardmäßig registriert es das eingebettete Backend während des Gateway-Starts und wartet vor dem Gateway-Signal ready auf eine Startprüfung. Setzen Sie OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 oder OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 nur für Skripte oder Umgebungen, in denen die Startprüfung absichtlich deaktiviert bleiben soll. Führen Sie /acp doctor für eine ausdrückliche Prüfung bei Bedarf aus.

Überschreiben Sie einen einzelnen ACP-Agentenbefehl mit strukturierten Argumenten, wenn ein Pfad oder Flagwert als einzelnes argv-Token erhalten bleiben soll:

{  "plugins": {    "entries": {      "acpx": {        "enabled": true,        "config": {          "agents": {            "claude": {              "command": "node",              "args": ["/path/to/custom adapter.mjs", "--verbose"]            }          }        }      }    }  }}

• agents.<id>.command ist die ausführbare Datei oder vorhandene Befehlszeichenfolge für diesen ACP-Agenten.
• agents.<id>.args ist optional. Jedes Array-Element wird für die Shell maskiert, bevor OpenClaw es an die aktuelle acpx-Befehlszeichenfolgen-Registry weitergibt.

Siehe Plugins.

Automatischer Adapter-Download

acpx lädt ACP-Adapter (beispielsweise die ACP-Bridges für Claude und Codex) bei der ersten Verwendung automatisch über npx herunter. Sie müssen Adapterpakete nicht manuell installieren, und für OpenClaw selbst gibt es keinen separaten Postinstall-Schritt. Wenn der Download oder Start eines Adapters fehlschlägt, meldet /acp doctor den Fehler.

MCP-Bridge für Plugin-Werkzeuge

Standardmäßig stellen ACPX-Sitzungen die von OpenClaw-Plugins registrierten Werkzeuge dem ACP-Harness nicht bereit.

Wenn ACP-Agenten wie Codex oder Claude Code installierte OpenClaw-Plugin-Werkzeuge wie das Abrufen oder Speichern von Erinnerungen aufrufen sollen, aktivieren Sie die dafür vorgesehene Bridge:

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

Dies bewirkt Folgendes:

• Fügt während der Initialisierung der ACPX-Sitzung einen integrierten MCP-Server namens openclaw-plugin-tools ein.
• Stellt Plugin-Werkzeuge bereit, die bereits von installierten und aktivierten OpenClaw- Plugins registriert wurden.
• Hält die Funktion ausdrücklich optional und standardmäßig deaktiviert.

Hinweise zu Sicherheit und Vertrauen:

• Dadurch wird die Werkzeugoberfläche des ACP-Harness erweitert.
• ACP-Agenten erhalten nur Zugriff auf Plugin-Werkzeuge, die bereits im Gateway aktiv sind.
• Behandeln Sie dies als dieselbe Vertrauensgrenze, als würden Sie diesen Plugins die Ausführung direkt in OpenClaw erlauben.
• Prüfen Sie die installierten Plugins, bevor Sie die Funktion aktivieren.

Benutzerdefinierte mcpServers funktionieren weiterhin wie zuvor. Die integrierte Bridge für Plugin-Werkzeuge ist eine zusätzliche optionale Komfortfunktion und kein Ersatz für die allgemeine MCP-Server-Konfiguration.

MCP-Bridge für OpenClaw-Werkzeuge

Standardmäßig stellen ACPX-Sitzungen integrierte OpenClaw-Werkzeuge ebenfalls nicht über MCP bereit. Aktivieren Sie die separate Bridge für Kernwerkzeuge, wenn ein ACP-Agent ausgewählte integrierte Werkzeuge wie cron benötigt:

openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true

Dies bewirkt Folgendes:

• Fügt während der Initialisierung der ACPX-Sitzung einen integrierten MCP-Server namens openclaw-tools ein.
• Stellt ausgewählte integrierte OpenClaw-Werkzeuge bereit. Der anfängliche Server stellt cron bereit.
• Hält die Bereitstellung von Kernwerkzeugen ausdrücklich optional und standardmäßig deaktiviert.

Konfiguration des Zeitlimits für Laufzeitvorgänge

Das acpx-Plugin gewährt eingebetteten Laufzeitstart- und Steuerungsvorgängen standardmäßig 120 Sekunden. Dadurch haben langsamere Harnesses wie Gemini CLI ausreichend Zeit, den ACP-Start und die Initialisierung abzuschließen. Überschreiben Sie den Wert, wenn Ihr Host ein anderes Vorgangslimit benötigt:

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

Laufzeitdurchläufe verwenden die OpenClaw-Zeitlimits für Agenten/Ausführungen, einschließlich /acp timeout. sessions_spawn akzeptiert keine Zeitlimitüberschreibungen pro Aufruf; der Betreiberpfad lautet agents.defaults.subagents.runTimeoutSeconds. Starten Sie das Gateway nach einer Änderung von timeoutSeconds neu.

Konfiguration des Agenten für Zustandsprüfungen

Wenn /acp doctor oder die Startprüfung das Backend prüft, testet das mitgelieferte acpx- Plugin einen Harness-Agenten. Wenn acp.allowedAgents festgelegt ist, wird standardmäßig der erste zugelassene Agent verwendet; andernfalls ist der Standardwert codex. Wenn Ihre Bereitstellung für Zustandsprüfungen einen anderen ACP-Agenten benötigt, legen Sie den Prüfagenten ausdrücklich fest:

openclaw config set plugins.entries.acpx.config.probeAgent claude

Starten Sie das Gateway nach einer Änderung dieses Werts neu.

Berechtigungskonfiguration

ACP-Sitzungen werden nicht interaktiv ausgeführt – es gibt keine TTY, über die Berechtigungsaufforderungen zum Schreiben von Dateien oder Ausführen von Shell-Befehlen genehmigt oder abgelehnt werden könnten. Das acpx-Plugin stellt zwei Konfigurationsschlüssel bereit, die steuern, wie Berechtigungen behandelt werden:

Diese ACPX-Harness-Berechtigungen sind von den OpenClaw-Ausführungsgenehmigungen und von Umgehungsflags der Anbieter für CLI-Backends wie --permission-mode bypassPermissions der Claude CLI getrennt. ACPX approve-all ist der Notfallschalter auf Harness-Ebene für ACP-Sitzungen.

Einen umfassenderen Vergleich zwischen OpenClaw tools.exec.mode, Codex-Guardian- Genehmigungen und ACPX-Harness-Berechtigungen finden Sie unter Berechtigungsmodi.

permissionMode

Steuert, welche Vorgänge der Harness-Agent ohne Rückfrage ausführen kann.

nonInteractivePermissions

Steuert, was geschieht, wenn eine Berechtigungsabfrage angezeigt werden müsste, aber keine interaktive TTY verfügbar ist (was bei ACP-Sitzungen immer der Fall ist).

Konfiguration

Über die Plugin-Konfiguration festlegen:

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

Starten Sie das Gateway neu, nachdem Sie diese Werte geändert haben.

Verwandte Themen

• ACP-Agenten — Übersicht, Betriebshandbuch, Konzepte
• Untergeordnete Agenten
• Multi-Agent-Routing