Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Für die Übersicht, das Operator-Runbook und die Konzepte siehe ACP-Agenten. Die folgenden Abschnitte behandeln 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 Runtime-Konfiguration des Codex-App-Servers verwenden Sie Codex-Harness. Für OpenAI-API-Schlüssel oder die Codex-OAuth-Modell-Provider-Konfiguration verwenden Sie OpenAI. Codex hat zwei OpenClaw-Routen:
RouteKonfiguration/BefehlEinrichtungsseite
Nativer Codex-App-Server/codex ..., openai/gpt-* agent refsCodex-Harness
Expliziter Codex-ACP-Adapter/acp spawn codex, runtime: "acp", agentId: "codex"Diese Seite
Bevorzugen Sie die native Route, sofern Sie nicht ausdrücklich ACP/acpx-Verhalten benötigen.

​
Unterstützung für den acpx-Harness (aktuell)

Aktuelle integrierte acpx-Harness-Aliasse:
  • claude
  • codex
  • copilot
  • cursor (Cursor-CLI: cursor-agent acp)
  • droid
  • gemini
  • iflow
  • kilocode
  • kimi
  • kiro
  • openclaw
  • opencode
  • pi
  • qwen
Wenn OpenClaw das acpx-Backend verwendet, bevorzugen Sie diese Werte für agentId, sofern Ihre acpx-Konfiguration keine benutzerdefinierten Agent-Aliasse definiert. Wenn Ihre lokale Cursor-Installation ACP weiterhin als agent acp bereitstellt, überschreiben Sie den Befehl des cursor-Agents in Ihrer acpx-Konfiguration, anstatt den integrierten Standard zu ändern. Die direkte Verwendung der acpx-CLI kann über --agent <command> auch beliebige Adapter ansprechen, aber diese rohe Ausweichmöglichkeit ist eine acpx-CLI-Funktion (nicht der normale OpenClaw-agentId-Pfad). Die Modellsteuerung hängt von den Adapter-Fähigkeiten ab. Codex-ACP-Modell-Refs werden vor dem Start von OpenClaw normalisiert. Andere Harnesses benötigen ACP-models sowie Unterstützung für session/set_model; wenn ein Harness weder diese ACP-Fähigkeit noch ein eigenes Startmodell-Flag bereitstellt, kann OpenClaw/acpx keine Modellauswahl erzwingen.

​
Erforderliche Konfiguration

ACP-Core-Baseline: 
{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    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,
    },
  },
}
Die Thread-Binding-Konfiguration ist spezifisch für den Channel-Adapter. Beispiel für Discord: 
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnSessions: true,
      },
    },
  },
}
Wenn threadgebundenes ACP-Spawn nicht funktioniert, prüfen Sie zuerst das Feature-Flag des Adapters:
  • Discord: channels.discord.threadBindings.spawnSessions=true
Bindings für die aktuelle Unterhaltung erfordern keine Erstellung von Child-Threads. Sie erfordern einen aktiven Unterhaltungskontext und einen Channel-Adapter, der ACP-Unterhaltungs-Bindings bereitstellt. Siehe Konfigurationsreferenz.

​
Plugin-Einrichtung für das acpx-Backend

Paketierte Installationen verwenden das offizielle Runtime-Plugin @openclaw/acpx für ACP. Installieren und aktivieren Sie es, bevor Sie ACP-Harness-Sitzungen verwenden: 
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
Source-Checkouts können nach pnpm install auch das lokale Workspace-Plugin verwenden. Beginnen Sie mit: 
/acp doctor
Wenn Sie acpx deaktiviert haben, es über plugins.allow / plugins.deny verweigert haben oder zurück zum paketierten Plugin wechseln möchten, verwenden Sie den expliziten Paketpfad: 
openclaw plugins install @openclaw/acpx
openclaw 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 die Backend-Gesundheit: 
/acp doctor

​
acpx-Befehl und Versionskonfiguration

Standardmäßig prüft das acpx-Plugin das eingebettete ACP-Backend während des Gateway-Starts und wartet auf diese Prüfung, bevor das Gateway-ready-Signal gesendet wird. Setzen Sie OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0, um die Startprüfung zu überspringen und das Backend stattdessen verzögert zu registrieren. Führen Sie /acp doctor für eine explizite bedarfsorientierte Prüfung aus. Überschreiben Sie den Befehl oder die Version in der Plugin-Konfiguration: 
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}
  • command akzeptiert einen absoluten Pfad, relativen Pfad (aufgelöst vom OpenClaw-Workspace) oder Befehlsnamen.
  • expectedVersion: "any" deaktiviert strikte Versionsübereinstimmung.
  • Benutzerdefinierte command-Pfade deaktivieren die Plugin-lokale automatische Installation.
Überschreiben Sie einen einzelnen ACP-Agent-Befehl mit strukturierten Argumenten, wenn ein Pfad oder Flag-Wert ein einzelnes argv-Token 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-Agent.
  • agents.<id>.args ist optional. Jedes Array-Element wird Shell-gequotet, bevor OpenClaw es über die aktuelle acpx-Befehlszeichenfolgen-Registry weitergibt.
Siehe Plugins.

​
Automatische Installation von Abhängigkeiten

Wenn Sie OpenClaw global mit npm install -g openclaw installieren, werden die acpx-Runtime-Abhängigkeiten (plattformspezifische Binärdateien) automatisch über einen Postinstall-Hook installiert. Wenn die automatische Installation fehlschlägt, startet das Gateway weiterhin normal und meldet die fehlende Abhängigkeit über openclaw acp doctor.

​
MCP-Bridge für Plugin-Tools

Standardmäßig stellen ACPX-Sitzungen dem ACP-Harness keine von OpenClaw-Plugins registrierten Tools bereit. Wenn Sie möchten, dass ACP-Agenten wie Codex oder Claude Code installierte OpenClaw-Plugin-Tools wie Memory Recall/Store aufrufen, aktivieren Sie die dedizierte Bridge: 
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
Was dies bewirkt:
  • Fügt einen integrierten MCP-Server namens openclaw-plugin-tools in den Bootstrap der ACPX-Sitzung ein.
  • Stellt Plugin-Tools bereit, die bereits von installierten und aktivierten OpenClaw-Plugins registriert wurden.
  • Hält die Funktion explizit und standardmäßig deaktiviert.
Sicherheits- und Vertrauenshinweise:
  • Dies erweitert die Tool-Oberfläche des ACP-Harness.
  • ACP-Agenten erhalten nur Zugriff auf Plugin-Tools, die bereits im Gateway aktiv sind.
  • Behandeln Sie dies als dieselbe Vertrauensgrenze, als würden Sie diese Plugins in OpenClaw selbst ausführen lassen.
  • Prüfen Sie installierte Plugins, bevor Sie dies aktivieren.
Benutzerdefinierte mcpServers funktionieren weiterhin wie zuvor. Die integrierte Plugin-Tools-Bridge ist eine zusätzliche Opt-in-Komfortfunktion, kein Ersatz für generische MCP-Server-Konfiguration.

​
MCP-Bridge für OpenClaw-Tools

Standardmäßig stellen ACPX-Sitzungen integrierte OpenClaw-Tools ebenfalls nicht über MCP bereit. Aktivieren Sie die separate Core-Tools-Bridge, wenn ein ACP-Agent ausgewählte integrierte Tools wie cron benötigt: 
openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true
Was dies bewirkt:
  • Fügt einen integrierten MCP-Server namens openclaw-tools in den Bootstrap der ACPX-Sitzung ein.
  • Stellt ausgewählte integrierte OpenClaw-Tools bereit. Der anfängliche Server stellt cron bereit.
  • Hält die Core-Tool-Bereitstellung explizit und standardmäßig deaktiviert.

​
Runtime-Timeout-Konfiguration

Das acpx-Plugin setzt für eingebettete Runtime-Turns standardmäßig ein Timeout von 120 Sekunden. Dies gibt langsameren Harnesses wie Gemini CLI genug Zeit, ACP-Start und Initialisierung abzuschließen. Überschreiben Sie den Wert, wenn Ihr Host ein anderes Runtime-Limit benötigt: 
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
Starten Sie das Gateway neu, nachdem Sie diesen Wert geändert haben.

​
Konfiguration des Health-Probe-Agents

Wenn /acp doctor oder die Startprüfung das Backend prüft, prüft das gebündelte acpx-Plugin einen Harness-Agent. Wenn acp.allowedAgents gesetzt ist, wird standardmäßig der erste erlaubte Agent verwendet; andernfalls ist der Standard codex. Wenn Ihre Bereitstellung einen anderen ACP-Agent für Health Checks benötigt, setzen Sie den Probe-Agent explizit: 
openclaw config set plugins.entries.acpx.config.probeAgent claude
Starten Sie das Gateway neu, nachdem Sie diesen Wert geändert haben.

​
Berechtigungskonfiguration

ACP-Sitzungen laufen nicht interaktiv; es gibt kein TTY, um Berechtigungsabfragen für Dateischreibvorgänge und Shell-Ausführung zu genehmigen oder abzulehnen. Das acpx-Plugin stellt zwei Konfigurationsschlüssel bereit, die steuern, wie Berechtigungen behandelt werden: Diese ACPX-Harness-Berechtigungen sind getrennt von OpenClaw-Exec-Genehmigungen und getrennt von Bypass-Flags der CLI-Backend-Vendoren wie Claude CLI --permission-mode bypassPermissions. ACPX approve-all ist der Harness-Level-Notfallschalter für ACP-Sitzungen.

​
permissionMode

Steuert, welche Operationen der Harness-Agent ohne Abfrage ausführen kann.
WertVerhalten
approve-allAlle Dateischreibvorgänge und Shell-Befehle automatisch genehmigen.
approve-readsNur Lesevorgänge automatisch genehmigen; Schreibvorgänge und Exec erfordern Abfragen.
deny-allAlle Berechtigungsabfragen ablehnen.

​
nonInteractivePermissions

Steuert, was passiert, wenn eine Berechtigungsabfrage angezeigt würde, aber kein interaktives TTY verfügbar ist (was bei ACP-Sitzungen immer der Fall ist).
WertVerhalten
failSitzung mit AcpRuntimeError abbrechen. (Standard)
denyBerechtigung stillschweigend verweigern und fortfahren (graceful degradation).

​
Konfiguration

Über die Plugin-Konfiguration setzen: 
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
Starten Sie das Gateway neu, nachdem Sie diese Werte geändert haben.
OpenClaw verwendet standardmäßig permissionMode=approve-reads und nonInteractivePermissions=fail. In nicht interaktiven ACP-Sitzungen kann jeder Schreib- oder Exec-Vorgang, der eine Berechtigungsabfrage auslöst, mit AcpRuntimeError: Permission prompt unavailable in non-interactive mode fehlschlagen.Wenn Sie Berechtigungen einschränken müssen, setzen Sie nonInteractivePermissions auf deny, damit Sitzungen graceful degradieren, anstatt abzustürzen.

​
Verwandt