ACP

​

Ce que ce n’est pas

• si l’éditeur ou le client doit communiquer avec OpenClaw via ACP : utilisez openclaw acp
• si OpenClaw doit lancer Codex, Claude ou Gemini comme environnement ACP : utilisez /acp spawn et les agents ACP

​

Matrice de compatibilité

​

Limitations connues

• loadSession ne relit l’intégralité de l’historique du registre d’événements ACP que pour les sessions créées par la passerelle. Les sessions plus anciennes ou dépourvues de registre utilisent l’historique de conversation comme solution de repli et ne reconstituent pas les appels d’outils ni les notifications système historiques.
• Si plusieurs clients ACP partagent la même clé de session du Gateway, le routage des événements et des annulations s’effectue dans la mesure du possible, sans isolation stricte par client. Préférez les sessions isolées acp-bridge:<uuid> par défaut lorsque vous avez besoin de tours locaux à l’éditeur clairement séparés.
• Les états d’arrêt du Gateway sont convertis en motifs d’arrêt ACP, mais cette correspondance est moins expressive que celle d’un environnement d’exécution entièrement natif ACP.
• Les contrôles de session exposent un sous-ensemble ciblé des paramètres du Gateway : niveau de réflexion, verbosité des outils, raisonnement, détail de l’utilisation et actions avec privilèges élevés. La sélection du modèle et les contrôles de l’hôte d’exécution ne sont pas exposés comme options de configuration ACP.
• session_info_update et usage_update proviennent d’instantanés de session du Gateway, et non d’une comptabilisation en direct propre à un environnement d’exécution natif ACP. L’utilisation est approximative, ne comporte aucune donnée de coût et n’est émise que lorsque le Gateway indique que les données sur le nombre total de jetons sont à jour.
• Les données de suivi des outils sont fournies dans la mesure du possible : la passerelle expose les chemins de fichiers présents dans les arguments ou résultats d’outils connus, mais n’émet ni terminaux ACP ni différences de fichiers structurées.
• Le relais des approbations d’exécution est limité au tour de requête ACP actif ; les approbations provenant d’autres sessions du 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 ne s’applique qu’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 catégories restreintes en lecture seule : les appels read limités au répertoire de travail actif, ainsi que les outils de recherche en lecture seule (search, web_search, memory_search). Les outils inconnus ou non principaux, les lectures hors périmètre, les outils capables d’exécuter des commandes, les outils du plan de contrôle, les outils effectuant des modifications et les flux interactifs exigent toujours une approbation explicite de la requête.
• La valeur toolCall.kind fournie par le serveur est traitée comme une métadonnée non fiable, et non comme une source d’autorisation.
• Cette politique de passerelle ACP est distincte des autorisations de l’environnement ACPX. Si vous exécutez OpenClaw via le moteur acpx, plugins.entries.acpx.config.permissionMode=approve-all est l’interrupteur d’urgence « yolo » pour cette session d’environnement.

​

Test de bon fonctionnement 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. Vérifiez que le Gateway est en cours d’exécution, localement ou à distance.
2. Configurez la cible du Gateway à l’aide de la configuration ou des options.
3. Configurez 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 et autres clients ACP)

1. Exécutez le Gateway et vérifiez que le pont ACP peut y accéder.
2. Faites pointer acpx openclaw vers openclaw acp.
3. Ciblez la clé de session OpenClaw que l’agent de programmation doit utiliser.

# 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> : rechercher une session existante par son libellé.
• --reset-session : générer un nouvel identifiant de session pour cette clé (même clé, nouvelle transcription).

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

​

Options

• --url <url> : URL WebSocket du Gateway (utilise par défaut gateway.remote.url lorsque cette valeur 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 à rechercher.
• --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 invites avec le répertoire de travail.
• --provenance <off|meta|meta+receipt> : inclure les métadonnées de provenance ACP ou les reçus.
• --verbose, -v : journalisation détaillée sur stderr.

• --token et --password peuvent apparaître dans les listes de processus locaux 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 de l’authentification du Gateway suit le contrat commun utilisé par les autres clients Gateway :
  • mode local : variables d’environnement (OPENCLAW_GATEWAY_*), puis gateway.auth.*, avec repli sur gateway.remote.* uniquement lorsque gateway.auth.* n’est pas défini (une SecretRef locale configurée mais non résolue provoque un échec fermé au lieu d’un repli silencieux)
  • mode distant : gateway.remote.*, avec repli sur les variables d’environnement ou la configuration conformément aux règles de priorité du mode distant
  • --url permet un remplacement sûr et ne réutilise pas les identifiants implicites issus de la configuration ou des variables d’environnement ; transmettez explicitement --token/--password (ou leurs variantes utilisant un fichier)

​

Options de acp client

• --cwd <dir> : répertoire de travail de la session ACP.
• --server <command> : commande du serveur ACP (valeur 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.
• openclaw acp client définit OPENCLAW_SHELL=acp-client sur le processus de pont lancé, ce qui permet d’appliquer des règles d’interpréteur de commandes ou de profil propres au contexte.

​

Pages connexes

• Référence de la CLI
• Agents ACP