​

ACP-Agenten

​

Welche Seite brauche ich?

​

Funktioniert das sofort?

• Neue Installationen liefern jetzt das gebündelte Runtime-Plugin acpx standardmäßig aktiviert aus.
• Das gebündelte acpx-Plugin bevorzugt seine pluginlokale gepinnte acpx-Binärdatei.
• Beim Start prüft OpenClaw diese Binärdatei und repariert sie bei Bedarf selbst.
• Starte mit /acp doctor, wenn du eine schnelle Bereitschaftsprüfung möchtest.

• Ein Ziel-Harness-Adapter kann beim ersten Verwenden dieses Harnesses bei Bedarf mit npx abgerufen werden.
• Vendor-Auth muss auf dem Host für dieses Harness weiterhin vorhanden sein.
• Wenn der Host keinen npm-/Netzwerkzugriff hat, können Adapter-Abrufe beim ersten Lauf fehlschlagen, bis Caches vorgewärmt sind oder der Adapter auf andere Weise installiert wurde.

• /acp spawn codex: OpenClaw sollte bereit sein, acpx zu bootstrappen, aber der Codex-ACP-Adapter muss möglicherweise dennoch beim ersten Lauf abgerufen werden.
• /acp spawn claude: dieselbe Situation für den Claude-ACP-Adapter, plus Claude-seitige Auth auf diesem Host.

​

Schneller Operator-Ablauf

1. Eine Sitzung erzeugen:
   • /acp spawn codex --bind here
   • /acp spawn codex --mode persistent --thread auto
2. In der gebundenen Konversation oder dem Thread arbeiten (oder diesen Sitzungsschlüssel explizit ansprechen).
3. Runtime-Status prüfen:
   • /acp status
4. Runtime-Optionen bei Bedarf anpassen:
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. Eine 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

• „Binde diesen Discord-Channel an Codex.“
• „Starte hier eine persistente Codex-Sitzung in einem Thread und halte den Fokus darauf.“
• „Führe das als One-shot-Claude-Code-ACP-Sitzung aus und fasse das Ergebnis zusammen.“
• „Binde diesen iMessage-Chat an Codex und behalte Follow-ups im selben Workspace.“
• „Verwende für diese Aufgabe Gemini CLI in einem Thread und behalte Follow-ups dann in diesem Thread.“

1. runtime: "acp" auswählen.
2. Das angeforderte Harness-Ziel (agentId, zum Beispiel codex) auflösen.
3. Wenn eine Bindung an die aktuelle Konversation angefordert wird und der aktive Channel sie unterstützt, die ACP-Sitzung an diese Konversation binden.
4. Andernfalls, wenn eine Thread-Bindung angefordert wird und der aktuelle Channel sie unterstützt, die ACP-Sitzung an den Thread binden.
5. Nachfolgende gebundene Nachrichten an dieselbe ACP-Sitzung routen, bis der Fokus aufgehoben, die Sitzung geschlossen oder sie abgelaufen ist.

​

ACP versus Sub-Agenten

​

Wie ACP Claude Code ausführt

1. ACP-Sitzungs-Control-Plane von OpenClaw
2. gebündeltes Runtime-Plugin acpx
3. Claude-ACP-Adapter
4. Claude-seitige Runtime-/Sitzungsmechanik

• ACP Claude ist eine Harness-Sitzung mit ACP-Kontrollen, Sitzungs-Fortsetzung, background-task-Tracking und optionaler Konversations-/Thread-Bindung.
• CLI-Backends sind separate reine Text-Laufzeiten als lokale Fallbacks. Siehe CLI Backends.

• wenn du /acp spawn, bindbare Sitzungen, Runtime-Kontrollen oder persistente Harness-Arbeit möchtest: verwende ACP
• wenn du einfaches lokales Text-Fallback über die rohe CLI möchtest: verwende CLI-Backends

​

Gebundene Sitzungen

​

Bindungen an die aktuelle Konversation

• OpenClaw behält Eigentümerschaft über Channel-Transport, Auth, Sicherheit und Zustellung.
• Die aktuelle Konversation wird auf den erzeugten ACP-Sitzungsschlüssel gepinnt.
• Nachfolgende Nachrichten in dieser Konversation werden an dieselbe ACP-Sitzung geroutet.
• /new und /reset setzen dieselbe gebundene ACP-Sitzung direkt zurück.
• /acp close schließt die Sitzung und entfernt die Bindung an die aktuelle Konversation.

• --bind here behält dieselbe Chat-Oberfläche bei. Auf Discord bleibt der aktuelle Channel der aktuelle Channel.
• --bind here kann dennoch eine neue ACP-Sitzung erstellen, wenn du neue Arbeit erzeugst. Die Bindung hängt diese Sitzung an die aktuelle Konversation.
• --bind here erstellt nicht von selbst einen Child-Discord-Thread oder ein Telegram-Topic.
• Die ACP-Runtime kann weiterhin ihr eigenes Arbeitsverzeichnis (cwd) oder einen vom Backend verwalteten Workspace auf der Festplatte haben. Dieser Runtime-Workspace ist getrennt von der Chat-Oberfläche und impliziert keinen neuen Messaging-Thread.
• Wenn du zu einem anderen ACP-Agenten spawnst und --cwd nicht übergibst, übernimmt OpenClaw standardmäßig den Workspace des Ziel-Agenten, nicht den des Anfragenden.
• Wenn dieser übernommene Workspace-Pfad fehlt (ENOENT/ENOTDIR), greift OpenClaw auf das Standard-cwd des Backend zurück, statt stillschweigend den falschen Baum wiederzuverwenden.
• Wenn der übernommene Workspace existiert, aber nicht zugänglich ist (zum Beispiel EACCES), gibt der Spawn den tatsächlichen Zugriffsfehler zurück, statt cwd zu verwerfen.

• Chat-Oberfläche: wo Menschen weiterreden (Discord channel, Telegram topic, iMessage chat)
• ACP-Sitzung: der dauerhafte Codex-/Claude-/Gemini-Runtime-Status, an den OpenClaw routet
• Child-Thread/-Topic: eine optionale zusätzliche Messaging-Oberfläche, die nur durch --thread ... erstellt wird
• Runtime-Workspace: der Dateisystemort, an dem das Harness läuft (cwd, Repo-Checkout, Backend-Workspace)

• /acp spawn codex --bind here: diesen Chat behalten, eine Codex-ACP-Sitzung erzeugen oder anhängen und zukünftige Nachrichten hierhin an sie routen
• /acp spawn codex --thread auto: OpenClaw kann einen Child-Thread/ein Child-Topic erstellen und die ACP-Sitzung dort binden
• /acp spawn codex --bind here --cwd /workspace/repo: dieselbe Chat-Bindung wie oben, aber Codex läuft in /workspace/repo

• Chat-/Message-Channels, die Unterstützung für Bindungen an die aktuelle Konversation ausweisen, können --bind here über den gemeinsamen Konversations-Bindungspfad verwenden.
• Channels mit benutzerdefinierter Thread-/Topic-Semantik können weiterhin channelspezifische Kanonisierung hinter derselben gemeinsamen Schnittstelle bereitstellen.
• --bind here bedeutet immer „die aktuelle Konversation direkt binden“.
• Generische Bindungen an die aktuelle Konversation verwenden den gemeinsamen OpenClaw-Bindungsspeicher und überstehen normale Gateway-Neustarts.

• --bind here und --thread ... schließen sich bei /acp spawn gegenseitig aus.
• Auf Discord bindet --bind here den aktuellen Channel oder Thread direkt. spawnAcpSessions ist nur erforderlich, wenn OpenClaw einen Child-Thread für --thread auto|here erstellen muss.
• Wenn der aktive Channel keine ACP-Bindungen an die aktuelle Konversation bereitstellt, gibt OpenClaw eine klare Meldung aus, dass dies nicht unterstützt wird.
• resume und Fragen zu „neuer Sitzung“ sind ACP-Sitzungsfragen, keine Channel-Fragen. Du kannst Runtime-Status wiederverwenden oder ersetzen, ohne die aktuelle Chat-Oberfläche zu ändern.

​

Thread-gebundene Sitzungen

• OpenClaw bindet einen Thread an eine Ziel-ACP-Sitzung.
• Nachfolgende Nachrichten in diesem Thread werden an die gebundene ACP-Sitzung geroutet.
• ACP-Ausgaben werden an denselben Thread zurückgeliefert.
• Das Aufheben des Fokus, Schließen, Archivieren, der Idle-Timeout oder das Erreichen des Maximalalters entfernt die Bindung.

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

​

Channels mit Thread-Unterstützung

• Jeder Channel-Adapter, der Sitzung-/Thread-Bindungsfähigkeit bereitstellt.
• Aktuelle integrierte Unterstützung:
  • Discord-Threads/-Channels
  • Telegram-Topics (Forum-Topics in Gruppen/Supergroups und DM-Topics)
• Plugin-Channels können über dieselbe Bindungsschnittstelle Unterstützung hinzufügen.

​

Channelspezifische Einstellungen

​

Bindungsmodell

• bindings[].type="acp" markiert eine persistente ACP-Konversationsbindung.
• bindings[].match identifiziert die Zielkonversation:
  • Discord-Channel oder -Thread: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Telegram-Forum-Topic: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • BlueBubbles-DM/Gruppenchat: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Bevorzuge chat_id:* oder chat_identifier:* für stabile Gruppenbindungen.
  • iMessage-DM/Gruppenchat: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Bevorzuge chat_id:* für stabile Gruppenbindungen.
• bindings[].agentId ist die zugehörige OpenClaw-Agent-ID.
• Optionale ACP-Overrides befinden sich unter bindings[].acp:
  • mode (persistent oder oneshot)
  • label
  • cwd
  • backend

​

Runtime-Standardwerte pro Agent

• 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

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

{
  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 } },
        },
      },
    },
  },
}

• OpenClaw stellt vor der Verwendung sicher, dass die konfigurierte ACP-Sitzung existiert.
• Nachrichten in diesem Channel oder Topic werden an die konfigurierte ACP-Sitzung geroutet.
• In gebundenen Konversationen setzen /new und /reset denselben ACP-Sitzungsschlüssel direkt zurück.
• Temporäre Runtime-Bindungen (zum Beispiel erstellt durch Thread-Fokus-Abläufe) gelten weiterhin, wo vorhanden.
• Bei agentübergreifenden ACP-Spawns ohne explizites cwd übernimmt OpenClaw den Workspace des Ziel-Agenten aus der Agent-Konfiguration.
• Fehlende übernommene Workspace-Pfade fallen auf das Standard-cwd des Backend zurück; echte Zugriffsfehler auf vorhandene Pfade werden als Spawn-Fehler ausgegeben.

​

ACP-Sitzungen starten (Schnittstellen)

​

Von sessions_spawn

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

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

• task (erforderlich): initialer Prompt, der an die ACP-Sitzung gesendet wird.
• runtime (für ACP erforderlich): muss "acp" sein.
• agentId (optional): ACP-Ziel-Harness-ID. Fällt auf acp.defaultAgent zurück, wenn gesetzt.
• thread (optional, Standard false): Thread-Bindungsablauf anfordern, wo unterstützt.
• mode (optional): run (one-shot) oder session (persistent).
  • Standard ist run
  • wenn thread: true und mode weggelassen wird, kann OpenClaw je nach Runtime-Pfad standardmäßig persistentes Verhalten verwenden
  • mode: "session" erfordert thread: true
• cwd (optional): angefordertes Arbeitsverzeichnis der Runtime (validiert durch Backend-/Runtime-Richtlinie). Wenn es weggelassen wird, übernimmt ACP-Spawn bei vorhandener Konfiguration den Workspace des Ziel-Agenten; fehlende übernommene Pfade fallen auf Backend-Standardwerte zurück, während echte Zugriffsfehler zurückgegeben werden.
• label (optional): operatorseitiges Label, das in Sitzungs-/Banner-Text verwendet wird.
• resumeSessionId (optional): eine bestehende ACP-Sitzung fortsetzen, statt eine neue zu erstellen. Der Agent spielt den Konversationsverlauf über session/load erneut ab. Erfordert runtime: "acp".
• streamTo (optional): "parent" streamt Zusammenfassungen des Fortschritts des initialen ACP-Laufs als Systemevents zurück an die anfordernde Sitzung.
  • Wenn verfügbar, enthalten akzeptierte Antworten streamLogPath, das auf ein sitzungsspezifisches JSONL-Log (<sessionId>.acp-stream.jsonl) verweist, das du für den vollständigen Relay-Verlauf mitverfolgen kannst.

​

Zustellungsmodell

​

Interaktive ACP-Sitzungen

• /acp spawn ... --bind here bindet die aktuelle Konversation an die ACP-Sitzung.
• /acp spawn ... --thread ... bindet einen Channel-Thread/ein Topic an die ACP-Sitzung.
• Persistente konfigurierte bindings[].type="acp" routen passende Konversationen an dieselbe ACP-Sitzung.

​

Vom Parent kontrollierte One-shot-ACP-Sitzungen

• Der Parent fordert Arbeit mit sessions_spawn({ runtime: "acp", mode: "run" }) an.
• Das Child läuft in seiner eigenen ACP-Harness-Sitzung.
• Der Abschluss meldet sich über den internen Ankündigungspfad für Task-Abschlüsse zurück.
• Der Parent formuliert das Child-Ergebnis in normaler Assistant-Stimme um, wenn eine benutzerseitige Antwort sinnvoll ist.

​

sessions_send und A2A-Zustellung

• auf die Antwort der Ziel-Sitzung warten
• optional dem Anfragenden und dem Ziel erlauben, eine begrenzte Zahl an Folge-Turns auszutauschen
• das Ziel auffordern, eine Ankündigungsnachricht zu erzeugen
• diese Ankündigung an den sichtbaren Channel oder Thread zustellen

​

Eine bestehende Sitzung fortsetzen

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

• Eine Codex-Sitzung vom Laptop an das Handy übergeben — deinem Agenten sagen, er soll dort weitermachen, wo du aufgehört hast
• Eine Coding-Sitzung fortsetzen, die du interaktiv in der CLI gestartet hast, jetzt headless über deinen Agenten
• Arbeit wieder aufnehmen, die durch einen Gateway-Neustart oder Idle-Timeout unterbrochen wurde

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

​

Smoke-Test für Operatoren

1. Die Version/den Commit des bereitgestellten Gateway auf dem Ziel-Host prüfen.
2. Bestätigen, dass der bereitgestellte Quellcode die ACP-Lineage-Akzeptanz in src/gateway/sessions-patch.ts enthält (subagent:* or acp:* sessions).
3. Eine temporäre ACPX-Bridge-Sitzung zu einem Live-Agenten öffnen (zum Beispiel razor(main) auf jpclawhq).
4. Diesen Agenten bitten, sessions_spawn aufzurufen mit:
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • task: Reply with exactly LIVE-ACP-SPAWN-OK
5. Verifizieren, dass der Agent meldet:
   • accepted=yes
   • einen echten childSessionKey
   • keinen Validator-Fehler
6. Die temporäre ACPX-Bridge-Sitzung bereinigen.

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>.

• Halte diesen Smoke-Test auf mode: "run", außer du testest absichtlich threadgebundene persistente ACP-Sitzungen.
• Verlange für dieses Basis-Gate nicht streamTo: "parent". Dieser Pfad hängt von Fähigkeiten des Anfragenden/der Sitzung ab und ist eine separate Integrationsprüfung.
• Behandle threadgebundenes mode: "session"-Testing als zweiten, reichhaltigeren Integrations- Durchlauf aus einem echten Discord-Thread oder Telegram-Topic.

​

Sandbox-Kompatibilität

• Wenn die anfordernde Sitzung sandboxed 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".

​

Über den Befehl /acp

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

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

​

Auflösung von Sitzungszielen

1. Explizites Zielargument (oder --session für /acp steer)
   • versucht zuerst den Schlüssel
   • dann eine UUID-förmige Sitzungs-ID
   • dann das Label
2. Aktuelle Thread-Bindung (wenn diese Konversation/dieser Thread an eine ACP-Sitzung gebunden ist)
3. Fallback auf die aktuelle anfordernde Sitzung

​

Spawn-Bind-Modi

• --bind here ist der einfachste Operator-Pfad für „mach diesen Channel oder Chat zu Codex-gestützt“.
• --bind here erstellt keinen Child-Thread.
• --bind here ist nur auf Channels verfügbar, die Unterstützung für Bindungen an die aktuelle Konversation bereitstellen.
• --bind und --thread können nicht im selben /acp spawn-Aufruf kombiniert werden.

​

Spawn-Thread-Modi

• Auf Oberflächen ohne Thread-Bindung ist das Standardverhalten effektiv off.
• Thread-gebundener Spawn erfordert Unterstützung durch die Channel-Richtlinie:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true
• Verwende --bind here, wenn du die aktuelle Konversation pinnen möchtest, ohne einen Child-Thread zu erstellen.

​

ACP-Kontrollen

• /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-Befehls-Kochbuch

​

Zuordnung der Runtime-Optionen

• /acp model <id> wird auf den Runtime-Konfigurationsschlüssel model abgebildet.
• /acp permissions <profile> wird auf den Runtime-Konfigurationsschlüssel approval_policy abgebildet.
• /acp timeout <seconds> wird auf den Runtime-Konfigurationsschlüssel timeout abgebildet.
• /acp cwd <path> aktualisiert den cwd-Override der Runtime direkt.
• /acp set <key> <value> ist der generische Pfad.
  • Sonderfall: key=cwd verwendet den Pfad für den cwd-Override.
• /acp reset-options entfernt alle Runtime-Overrides für die Zielsitzung.

​

Unterstützung für acpx-Harnesses (aktuell)

• claude
• codex
• copilot
• cursor (Cursor CLI: cursor-agent acp)
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• pi
• qwen

​

Erforderliche Konfiguration

{
  acp: {
    enabled: true,
    // Optional. Standard ist true; setze false, um den ACP-Dispatch zu pausieren und /acp-Kontrollen beizubehalten.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

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

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

​

Plugin-Einrichtung für das acpx-Backend

/acp doctor

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

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

/acp doctor

​

Konfiguration von acpx-Befehl und -Version

1. Der Befehl ist standardmäßig das pluginlokale node_modules/.bin/acpx innerhalb des ACPX-Plugin-Pakets.
2. Die erwartete Version ist standardmäßig der Pin der Extension.
3. Beim Start registriert sich das ACP-Backend sofort als nicht bereit.
4. Ein Hintergrund-Ensure-Job prüft acpx --version.
5. Wenn die pluginlokale Binärdatei fehlt oder nicht passt, wird Folgendes ausgeführt: npm install --omit=dev --no-save acpx@<pinned> und danach erneut geprüft.

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

• command akzeptiert einen absoluten Pfad, relativen Pfad oder Befehlsnamen (acpx).
• Relative Pfade werden vom OpenClaw-Workspace-Verzeichnis aus aufgelöst.
• expectedVersion: "any" deaktiviert strikte Versionsabgleiche.
• Wenn command auf eine benutzerdefinierte Binärdatei/einen benutzerdefinierten Pfad zeigt, wird die pluginlokale Auto-Installation deaktiviert.
• Der OpenClaw-Start bleibt nicht blockierend, während die Backend-Zustandsprüfung läuft.

​

Automatische Installation von Abhängigkeiten

​

MCP-Bridge für Plugin-Tools

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

• Injiziert einen integrierten MCP-Server mit dem Namen openclaw-plugin-tools in den Bootstrap der ACPX-Sitzung.
• Stellt Plugin-Tools bereit, die bereits von installierten und aktivierten OpenClaw- Plugins registriert wurden.
• Hält die Funktion explizit und standardmäßig deaktiviert.

• Dadurch wird die Tool-Oberfläche des ACP-Harness erweitert.
• ACP-Agenten erhalten nur Zugriff auf Plugin-Tools, die im Gateway bereits aktiv sind.
• Behandle dies als dieselbe Vertrauensgrenze, wie wenn diese Plugins in OpenClaw selbst ausgeführt werden dürften.
• Prüfe installierte Plugins, bevor du dies aktivierst.

​

Konfiguration des Runtime-Timeouts

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

​

Konfiguration des Probe-Agenten für Health Checks

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

​

Konfiguration von Berechtigungen

​

permissionMode

​

nonInteractivePermissions

​

Konfiguration

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

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 Genehmigungsaufforderung 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 degradiert werden, statt abzustürzen.

​

Fehlerbehebung