ACP

Documentation Index

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

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

​

Ce que ce n’est pas

• OpenClaw agit comme serveur ACP
• un IDE ou client ACP se connecte à OpenClaw
• OpenClaw transmet ce travail à une session Gateway

• l’éditeur/client veut parler ACP à OpenClaw : utilisez openclaw acp
• OpenClaw doit lancer Codex/Claude/Gemini comme harnais ACP : utilisez /acp spawn et agents ACP

​

Matrice de compatibilité

​

Limitations connues

• loadSession ne peut rejouer l’historique complet du registre d’événements ACP que pour les sessions créées par le pont. Les sessions plus anciennes/sans registre utilisent toujours le repli sur la transcription et ne reconstruisent pas les appels d’outils historiques ni les avis système.
• Si plusieurs clients ACP partagent la même clé de session Gateway, le routage des événements et des annulations est au mieux approximatif plutôt que strictement isolé par client. Préférez les sessions isolées par défaut acp:<uuid> lorsque vous avez besoin de tours propres locaux à l’éditeur.
• Les états d’arrêt du Gateway sont traduits en raisons d’arrêt ACP, mais ce mappage est moins expressif qu’un runtime entièrement natif ACP.
• Les contrôles de session initiaux exposent actuellement un sous-ensemble ciblé de réglages Gateway : niveau de pensée, verbosité des outils, raisonnement, détail d’utilisation et actions élevées. La sélection de modèle et les contrôles d’hôte d’exécution ne sont pas encore exposés comme options de configuration ACP.
• session_info_update et usage_update sont dérivés d’instantanés de session Gateway, et non d’une comptabilité de runtime native ACP en direct. L’utilisation est approximative, ne contient aucune donnée de coût et n’est émise que lorsque le Gateway marque les données de total de jetons comme fraîches.
• Les données de suivi d’outils sont au mieux approximatives. Le pont peut exposer les chemins de fichiers qui apparaissent dans des arguments/résultats d’outils connus, mais il n’émet pas encore de terminaux ACP ni de diffs de fichiers structurés.
• Le relais d’approbation d’exécution est limité au tour d’invite ACP actif ; les approbations provenant d’autres sessions Gateway sont ignorées.

​

Utilisation

openclaw acp

# Remote Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>

# Remote Gateway (token from file)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Attach to an existing session key
openclaw acp --session agent:main:main

# Attach by label (must already exist)
openclaw acp --session-label "support inbox"

# Reset the session key before the first prompt
openclaw acp --session agent:main:main --reset-session

​

Client ACP (débogage)

openclaw acp client

# Point the spawned bridge at a remote Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Override the server command (default: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

• L’approbation automatique repose sur une liste d’autorisation et s’applique uniquement aux identifiants d’outils principaux approuvés.
• L’approbation automatique de read est limitée au répertoire de travail actuel (--cwd lorsqu’il est défini).
• ACP n’approuve automatiquement que des classes étroites en lecture seule : les appels read limités sous le cwd actif ainsi que les outils de recherche en lecture seule (search, web_search, memory_search). Les outils inconnus/non principaux, les lectures hors périmètre, les outils capables d’exécution, les outils de plan de contrôle, les outils modificateurs et les flux interactifs nécessitent toujours une approbation explicite de l’invite.
• toolCall.kind fourni par le serveur est traité comme une métadonnée non fiable (pas comme une source d’autorisation).
• Cette politique de pont ACP est distincte des permissions de harnais ACPX. Si vous exécutez OpenClaw via le backend acpx, plugins.entries.acpx.config.permissionMode=approve-all est le commutateur d’urgence « yolo » pour cette session de harnais.

​

Test rapide du protocole

{
  "initialize": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "list": {},
        "resume": {},
        "close": {}
      }
    }
  },
  "listSessions": {
    "sessions": [
      {
        "sessionId": "agent:main:acp-smoke",
        "cwd": "/path/to/workspace",
        "_meta": {
          "sessionKey": "agent:main:acp-smoke",
          "kind": "direct"
        }
      }
    ],
    "nextCursor": null
  },
  "notifications": ["session_info_update", "available_commands_update", "usage_update"],
  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]
}

​

Comment l’utiliser

1. Assurez-vous que le Gateway est en cours d’exécution (local ou distant).
2. Configurez la cible Gateway (configuration ou indicateurs).
3. Pointez votre IDE pour exécuter openclaw acp sur stdio.

openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>

openclaw acp --url wss://gateway-host:18789 --token <token>
# preferred for local process safety
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

​

Sélection des agents

openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123

​

Utilisation depuis acpx (Codex, Claude, autres clients ACP)

1. Exécutez le Gateway et assurez-vous que le pont ACP peut l’atteindre.
2. Pointez acpx openclaw vers openclaw acp.
3. Ciblez la clé de session OpenClaw que vous voulez que l’agent de codage utilise.

# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."

# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Ask my OpenClaw work agent for recent context relevant to this repo."

{
  "agents": {
    "openclaw": {
      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
    }
  }
}

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

​

Configuration de l’éditeur Zed

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url",
        "wss://gateway-host:18789",
        "--token",
        "<token>",
        "--session",
        "agent:design:main"
      ],
      "env": {}
    }
  }
}

​

Correspondance des sessions

• --session <key> : utiliser une clé de session Gateway spécifique.
• --session-label <label> : résoudre une session existante par libellé.
• --reset-session : émettre un nouvel identifiant de session pour cette clé (même clé, nouveau transcript).

{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}

​

Options

• --url <url> : URL WebSocket du Gateway (par défaut, gateway.remote.url lorsqu’elle est configurée).
• --token <token> : jeton d’authentification du Gateway.
• --token-file <path> : lire le jeton d’authentification du Gateway depuis un fichier.
• --password <password> : mot de passe d’authentification du Gateway.
• --password-file <path> : lire le mot de passe d’authentification du Gateway depuis un fichier.
• --session <key> : clé de session par défaut.
• --session-label <label> : libellé de session par défaut à résoudre.
• --require-existing : échouer si la clé ou le libellé de session n’existe pas.
• --reset-session : réinitialiser la clé de session avant la première utilisation.
• --no-prefix-cwd : ne pas préfixer les prompts avec le répertoire de travail.
• --provenance <off|meta|meta+receipt> : inclure les métadonnées ou reçus de provenance ACP.
• --verbose, -v : journalisation détaillée vers stderr.

• --token et --password peuvent être visibles dans les listes de processus locales sur certains systèmes.
• Préférez --token-file/--password-file ou les variables d’environnement (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
• La résolution d’authentification Gateway suit le contrat partagé utilisé par les autres clients Gateway :
  • mode local : env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> solution de repli gateway.remote.* uniquement lorsque gateway.auth.* n’est pas défini (les SecretRefs locaux configurés mais non résolus échouent en mode fermé)
  • mode distant : gateway.remote.* avec repli env/config selon les règles de précédence distantes
  • --url est sûr comme remplacement et ne réutilise pas les identifiants implicites config/env ; transmettez explicitement --token/--password (ou les variantes par fichier)
• Les processus enfants du backend d’exécution ACP reçoivent OPENCLAW_SHELL=acp, qui peut être utilisé pour des règles de shell/profil propres au contexte.
• openclaw acp client définit OPENCLAW_SHELL=acp-client sur le processus de pont lancé.

​

Options de acp client

• --cwd <dir> : répertoire de travail pour la session ACP.
• --server <command> : commande du serveur ACP (par défaut : openclaw).
• --server-args <args...> : arguments supplémentaires transmis au serveur ACP.
• --server-verbose : activer la journalisation détaillée sur le serveur ACP.
• --verbose, -v : journalisation détaillée du client.

​

Connexe

• Référence CLI
• Agents ACP