​

Agenti ACP

​

Quale pagina mi serve?

​

Funziona immediatamente?

• Le installazioni nuove ora includono il plugin runtime acpx integrato abilitato per impostazione predefinita.
• Il plugin acpx integrato preferisce il proprio binario acpx locale al plugin e bloccato a una versione specifica.
• All’avvio, OpenClaw verifica quel binario e lo autoripara se necessario.
• Inizia con /acp doctor se vuoi un rapido controllo di disponibilità.

• Un adapter harness di destinazione può essere recuperato on demand con npx la prima volta che usi quell’harness.
• L’autenticazione del vendor deve comunque esistere sull’host per quell’harness.
• Se l’host non ha accesso a npm/rete, i recuperi dell’adapter al primo avvio possono fallire finché le cache non vengono preriscaldate o l’adapter non viene installato in un altro modo.

• /acp spawn codex: OpenClaw dovrebbe essere pronto a inizializzare acpx, ma l’adapter ACP di Codex potrebbe comunque richiedere un recupero al primo avvio.
• /acp spawn claude: stessa situazione per l’adapter ACP di Claude, più l’autenticazione lato Claude su quell’host.

​

Flusso operativo rapido

1. Avvia una sessione:
   • /acp spawn codex --bind here
   • /acp spawn codex --mode persistent --thread auto
2. Lavora nella conversazione o nel thread vincolato (oppure indirizza esplicitamente quella session key).
3. Controlla lo stato runtime:
   • /acp status
4. Regola le opzioni runtime secondo necessità:
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. Dai un’indicazione a una sessione attiva senza sostituire il contesto:
   • /acp steer restringi il logging e continua
6. Interrompi il lavoro:
   • /acp cancel (interrompe il turno corrente), oppure
   • /acp close (chiude la sessione + rimuove i binding)

​

Avvio rapido per le persone

• “Associa questo canale Discord a Codex.”
• “Avvia una sessione Codex persistente in un thread qui e mantienila focalizzata.”
• “Esegui questo come sessione ACP Claude Code one-shot e riassumi il risultato.”
• “Associa questa chat iMessage a Codex e mantieni i follow-up nello stesso workspace.”
• “Usa Gemini CLI per questo compito in un thread, poi mantieni i follow-up in quello stesso thread.”

1. Scegliere runtime: "acp".
2. Risolvere il target harness richiesto (agentId, ad esempio codex).
3. Se viene richiesto il binding alla conversazione corrente e il canale attivo lo supporta, associare la sessione ACP a quella conversazione.
4. Altrimenti, se viene richiesto il binding al thread e il canale corrente lo supporta, associare la sessione ACP al thread.
5. Instradare i messaggi di follow-up vincolati alla stessa sessione ACP finché non viene tolto il focus/chiusa/scaduta.

​

ACP rispetto ai sub-agent

​

Come ACP esegue Claude Code

1. Piano di controllo della sessione ACP di OpenClaw
2. Plugin runtime acpx integrato
3. Adapter ACP Claude
4. Runtime/meccanismo di sessione lato Claude

• ACP Claude è una sessione harness con controlli ACP, ripresa della sessione, tracciamento delle attività in background e binding opzionale a conversazione/thread.
• I CLI backend sono runtime di fallback locali separati solo testuali. Vedi CLI Backends.

• vuoi /acp spawn, sessioni associabili, controlli runtime o lavoro harness persistente: usa ACP
• vuoi un semplice fallback testuale locale tramite la CLI grezza: usa i CLI backend

​

Sessioni vincolate

​

Binding alla conversazione corrente

• OpenClaw continua a gestire il trasporto del canale, auth, sicurezza e consegna.
• La conversazione corrente viene fissata alla session key ACP generata.
• I messaggi di follow-up in quella conversazione vengono instradati alla stessa sessione ACP.
• /new e /reset reimpostano sul posto la stessa sessione ACP vincolata.
• /acp close chiude la sessione e rimuove il binding alla conversazione corrente.

• --bind here mantiene la stessa superficie di chat. Su Discord, il canale corrente resta il canale corrente.
• --bind here può comunque creare una nuova sessione ACP se stai avviando nuovo lavoro. Il bind collega quella sessione alla conversazione corrente.
• --bind here non crea da solo un thread figlio Discord o un topic Telegram.
• Il runtime ACP può comunque avere la propria directory di lavoro (cwd) o un workspace su disco gestito dal backend. Quel workspace runtime è separato dalla superficie di chat e non implica un nuovo thread di messaggistica.
• Se avvii verso un agente ACP diverso e non passi --cwd, OpenClaw eredita per impostazione predefinita il workspace dell’agente di destinazione, non quello del richiedente.
• Se quel percorso workspace ereditato è mancante (ENOENT/ENOTDIR), OpenClaw torna al cwd predefinito del backend invece di riutilizzare silenziosamente l’albero sbagliato.
• Se il workspace ereditato esiste ma non è accessibile (ad esempio EACCES), l’avvio restituisce il vero errore di accesso invece di scartare cwd.

• superficie di chat: dove le persone continuano a parlare (canale Discord, topic Telegram, chat iMessage)
• sessione ACP: lo stato runtime durevole di Codex/Claude/Gemini verso cui OpenClaw instrada
• thread/topic figlio: una superficie di messaggistica aggiuntiva facoltativa creata solo da --thread ...
• workspace runtime: la posizione del filesystem in cui l’harness viene eseguito (cwd, checkout del repo, workspace backend)

• /acp spawn codex --bind here: mantieni questa chat, avvia o collega una sessione ACP Codex e instrada qui i messaggi futuri
• /acp spawn codex --thread auto: OpenClaw può creare un thread/topic figlio e associare lì la sessione ACP
• /acp spawn codex --bind here --cwd /workspace/repo: stesso binding di chat dell’esempio sopra, ma Codex viene eseguito in /workspace/repo

• I canali chat/messaggi che dichiarano il supporto al binding della conversazione corrente possono usare --bind here tramite il percorso condiviso di conversation-binding.
• I canali con semantiche personalizzate di thread/topic possono comunque fornire una canonicalizzazione specifica del canale dietro la stessa interfaccia condivisa.
• --bind here significa sempre “associa la conversazione corrente sul posto”.
• I binding generici alla conversazione corrente usano lo store di binding condiviso di OpenClaw e sopravvivono ai normali riavvii del gateway.

• --bind here e --thread ... si escludono a vicenda in /acp spawn.
• Su Discord, --bind here associa sul posto il canale o thread corrente. spawnAcpSessions è richiesto solo quando OpenClaw deve creare un thread figlio per --thread auto|here.
• Se il canale attivo non espone binding ACP alla conversazione corrente, OpenClaw restituisce un chiaro messaggio di non supportato.
• resume e le domande su “nuova sessione” riguardano la sessione ACP, non il canale. Puoi riutilizzare o sostituire lo stato runtime senza cambiare la superficie di chat corrente.

​

Sessioni vincolate al thread

• OpenClaw associa un thread a una sessione ACP di destinazione.
• I messaggi di follow-up in quel thread vengono instradati alla sessione ACP associata.
• L’output ACP viene consegnato di nuovo allo stesso thread.
• La rimozione del focus/chiusura/archiviazione/scadenza per inattività o per età massima rimuove il binding.

• acp.enabled=true
• acp.dispatch.enabled è attivo per impostazione predefinita (imposta false per mettere in pausa il dispatch ACP)
• Feature flag di spawn ACP thread del channel-adapter abilitato (specifico dell’adapter)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

​

Canali che supportano thread

• Qualsiasi adapter di canale che espone la capacità di binding sessione/thread.
• Supporto integrato attuale:
  • thread/canali Discord
  • topic Telegram (topic del forum in gruppi/supergruppi e topic DM)
• I canali plugin possono aggiungere supporto tramite la stessa interfaccia di binding.

​

Impostazioni specifiche del canale

​

Modello di binding

• bindings[].type="acp" contrassegna un binding persistente di conversazione ACP.
• bindings[].match identifica la conversazione di destinazione:
  • Canale o thread Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Topic forum Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • Chat DM/di gruppo BlueBubbles: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Preferisci chat_id:* o chat_identifier:* per binding di gruppo stabili.
  • Chat DM/di gruppo iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Preferisci chat_id:* per binding di gruppo stabili.
• bindings[].agentId è l’ID dell’agente OpenClaw proprietario.
• Gli override ACP facoltativi si trovano sotto bindings[].acp:
  • mode (persistent o oneshot)
  • label
  • cwd
  • backend

​

Valori predefiniti runtime per agente

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent (ID harness, ad esempio codex o 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. valori predefiniti ACP globali (ad esempio 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 garantisce che la sessione ACP configurata esista prima dell’uso.
• I messaggi in quel canale o topic vengono instradati alla sessione ACP configurata.
• Nelle conversazioni vincolate, /new e /reset reimpostano sul posto la stessa session key ACP.
• I binding runtime temporanei (ad esempio creati dai flussi di focus del thread) si applicano comunque quando presenti.
• Per avvii ACP cross-agent senza un cwd esplicito, OpenClaw eredita il workspace dell’agente di destinazione dalla configurazione dell’agente.
• I percorsi workspace ereditati mancanti tornano al cwd predefinito del backend; i veri errori di accesso su percorsi esistenti emergono come errori di avvio.

​

Avviare sessioni ACP (interfacce)

​

Da sessions_spawn

{
  "task": "Apri il repository e riassumi i test che falliscono",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

• runtime ha come valore predefinito subagent, quindi imposta esplicitamente runtime: "acp" per le sessioni ACP.
• Se agentId viene omesso, OpenClaw usa acp.defaultAgent quando configurato.
• mode: "session" richiede thread: true per mantenere una conversazione persistente associata.

• task (obbligatorio): prompt iniziale inviato alla sessione ACP.
• runtime (obbligatorio per ACP): deve essere "acp".
• agentId (facoltativo): ID dell’harness ACP di destinazione. Usa acp.defaultAgent come fallback se impostato.
• thread (facoltativo, predefinito false): richiede il flusso di binding al thread quando supportato.
• mode (facoltativo): run (one-shot) o session (persistente).
  • il valore predefinito è run
  • se thread: true e il mode viene omesso, OpenClaw può usare come predefinito il comportamento persistente in base al percorso runtime
  • mode: "session" richiede thread: true
• cwd (facoltativo): directory di lavoro runtime richiesta (convalidata dalla policy backend/runtime). Se omesso, l’avvio ACP eredita il workspace dell’agente di destinazione quando configurato; i percorsi ereditati mancanti tornano ai valori predefiniti del backend, mentre i veri errori di accesso vengono restituiti.
• label (facoltativo): etichetta visibile all’operatore usata nel testo di sessione/banner.
• resumeSessionId (facoltativo): riprende una sessione ACP esistente invece di crearne una nuova. L’agente riproduce la propria cronologia di conversazione tramite session/load. Richiede runtime: "acp".
• streamTo (facoltativo): "parent" inoltra i riepiloghi del progresso iniziale dell’esecuzione ACP alla sessione richiedente come eventi di sistema.
  • Quando disponibile, le risposte accettate includono streamLogPath che punta a un log JSONL con scope di sessione (<sessionId>.acp-stream.jsonl) che puoi seguire per la cronologia completa del relay.

​

Riprendere una sessione esistente

{
  "task": "Continua da dove ci eravamo fermati — correggi i test rimanenti che falliscono",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

• Passare una sessione Codex dal laptop al telefono — chiedi al tuo agente di riprendere da dove avevi lasciato
• Continuare una sessione di coding iniziata in modo interattivo nella CLI, ora in modalità headless tramite il tuo agente
• Riprendere un lavoro interrotto da un riavvio del gateway o da un timeout di inattività

• resumeSessionId richiede runtime: "acp" — restituisce un errore se usato con il runtime sub-agent.
• resumeSessionId ripristina la cronologia della conversazione ACP upstream; thread e mode continuano ad applicarsi normalmente alla nuova sessione OpenClaw che stai creando, quindi mode: "session" richiede comunque thread: true.
• L’agente di destinazione deve supportare session/load (Codex e Claude Code lo fanno).
• Se l’ID sessione non viene trovato, l’avvio fallisce con un errore chiaro — nessun fallback silenzioso a una nuova sessione.

​

Smoke test per operatori

1. Verifica la versione/commit del gateway distribuito sull’host di destinazione.
2. Conferma che il sorgente distribuito includa l’accettazione della lineage ACP in src/gateway/sessions-patch.ts (subagent:* or acp:* sessions).
3. Apri una sessione bridge ACPX temporanea verso un agente live (ad esempio razor(main) su jpclawhq).
4. Chiedi a quell’agente di chiamare sessions_spawn con:
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • task: Reply with exactly LIVE-ACP-SPAWN-OK
5. Verifica che l’agente segnali:
   • accepted=yes
   • una childSessionKey reale
   • nessun errore di validazione
6. Pulisci la sessione bridge ACPX temporanea.

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

• Mantieni questo smoke test su mode: "run" a meno che tu non stia testando intenzionalmente sessioni ACP persistenti associate a thread.
• Non richiedere streamTo: "parent" per il gate di base. Quel percorso dipende da capacità del richiedente/sessione ed è un controllo di integrazione separato.
• Tratta il test di mode: "session" associato a thread come un secondo passaggio di integrazione più ricco da un thread Discord reale o un topic Telegram.

​

Compatibilità con il sandbox

• Se la sessione richiedente è in sandbox, gli avvii ACP vengono bloccati sia per sessions_spawn({ runtime: "acp" }) sia per /acp spawn.
  • Errore: Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
• sessions_spawn con runtime: "acp" non supporta sandbox: "require".
  • Errore: sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

​

Dal comando /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>

​

Risoluzione della destinazione della sessione

1. Argomento target esplicito (o --session per /acp steer)
   • prova prima la key
   • poi l’ID sessione in forma UUID
   • poi l’etichetta
2. Binding del thread corrente (se questa conversazione/thread è associata a una sessione ACP)
3. Fallback alla sessione richiedente corrente

​

Modalità di bind all’avvio

• --bind here è il percorso operativo più semplice per “rendere questo canale o chat supportato da Codex”.
• --bind here non crea un thread figlio.
• --bind here è disponibile solo sui canali che espongono il supporto al binding della conversazione corrente.
• --bind e --thread non possono essere combinati nella stessa chiamata /acp spawn.

​

Modalità thread all’avvio

• Sulle superfici che non supportano thread binding, il comportamento predefinito è di fatto off.
• L’avvio con binding al thread richiede il supporto della policy del canale:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true
• Usa --bind here quando vuoi fissare la conversazione corrente senza creare un thread figlio.

​

Controlli ACP

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

​

Ricettario dei comandi ACP

​

Mappatura delle opzioni runtime

• /acp model <id> corrisponde alla chiave di configurazione runtime model.
• /acp permissions <profile> corrisponde alla chiave di configurazione runtime approval_policy.
• /acp timeout <seconds> corrisponde alla chiave di configurazione runtime timeout.
• /acp cwd <path> aggiorna direttamente l’override cwd runtime.
• /acp set <key> <value> è il percorso generico.
  • Caso speciale: key=cwd usa il percorso di override cwd.
• /acp reset-options cancella tutti gli override runtime per la sessione di destinazione.

​

Supporto harness acpx (attuale)

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

​

Configurazione richiesta

{
  acp: {
    enabled: true,
    // Facoltativo. Il valore predefinito è true; imposta false per mettere in pausa il dispatch ACP mantenendo i controlli /acp.
    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

​

Configurazione del plugin per il backend acpx

/acp doctor

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

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

/acp doctor

​

Configurazione del comando e della versione di acpx

1. Il comando usa per impostazione predefinita node_modules/.bin/acpx locale al plugin all’interno del pacchetto plugin ACPX.
2. La versione prevista usa per impostazione predefinita il pin dell’estensione.
3. All’avvio, OpenClaw registra immediatamente il backend ACP come non pronto.
4. Un job di verifica in background controlla acpx --version.
5. Se il binario locale al plugin manca o non corrisponde, esegue: npm install --omit=dev --no-save acpx@<pinned> e verifica di nuovo.

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

• command accetta un percorso assoluto, un percorso relativo o un nome comando (acpx).
• I percorsi relativi vengono risolti dalla directory workspace OpenClaw.
• expectedVersion: "any" disabilita il controllo rigoroso della versione.
• Quando command punta a un binario/percorso personalizzato, l’auto-installazione locale al plugin viene disabilitata.
• L’avvio di OpenClaw resta non bloccante mentre viene eseguito il controllo di integrità del backend.

​

Installazione automatica delle dipendenze

​

Bridge MCP dei tool plugin

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

• Inietta un server MCP integrato chiamato openclaw-plugin-tools nel bootstrap della sessione ACPX.
• Espone i tool plugin già registrati dai plugin OpenClaw installati e abilitati.
• Mantiene la funzionalità esplicita e disattivata per impostazione predefinita.

• Questo espande la superficie dei tool dell’harness ACP.
• Gli agenti ACP ottengono accesso solo ai tool plugin già attivi nel gateway.
• Tratta questo come lo stesso confine di trust che consentire a quei plugin di eseguire all’interno di OpenClaw stesso.
• Controlla i plugin installati prima di abilitarlo.

​

Configurazione del timeout runtime

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

​

Configurazione dei permessi

​

permissionMode

​

nonInteractivePermissions

​

Configurazione

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

Importante: OpenClaw attualmente usa per impostazione predefinita permissionMode=approve-reads e nonInteractivePermissions=fail. Nelle sessioni ACP non interattive, qualsiasi scrittura o exec che attiva un prompt di permesso può fallire con AcpRuntimeError: Permission prompt unavailable in non-interactive mode. Se devi limitare i permessi, imposta nonInteractivePermissions su deny in modo che le sessioni degradino in modo graduale invece di andare in crash.

​

Risoluzione dei problemi