​

Agenti ACP

​

Quale pagina mi serve?

​

Funziona subito?

• Le installazioni nuove ora includono il plugin runtime acpx incluso e abilitato per default.
• Il plugin acpx incluso preferisce il proprio binario acpx locale al plugin.
• All’avvio, OpenClaw verifica quel binario e lo ripara automaticamente se necessario.
• Inizia con /acp doctor se vuoi un rapido controllo di disponibilità.

• Un adapter del harness di destinazione può essere scaricato on demand con npx la prima volta che usi quel harness.
• L’autenticazione del vendor deve comunque esistere sull’host per quel harness.
• Se l’host non ha accesso a npm/rete, il primo download dell’adapter può 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 download iniziale.
• /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 associato (oppure punta esplicitamente a quella chiave di sessione).
3. Controlla lo stato del runtime:
   • /acp status
4. Regola le opzioni del runtime secondo necessità:
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. Dai un indirizzo a una sessione attiva senza sostituire il contesto:
   • /acp steer tighten logging and continue
6. Interrompi il lavoro:
   • /acp cancel (ferma il turno corrente), oppure
   • /acp close (chiude la sessione + rimuove le associazioni)

​

Avvio rapido per gli utenti

• “Collega questo canale Discord a Codex.”
• “Avvia una sessione Codex persistente in un thread qui e mantienila focalizzata.”
• “Esegui questo come sessione ACP one-shot di Claude Code e riassumi il risultato.”
• “Collega 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 nello stesso thread.”

1. Scegliere runtime: "acp".
2. Risolvere la destinazione harness richiesta (agentId, per esempio codex).
3. Se viene richiesta l’associazione alla conversazione corrente e il canale attivo la supporta, associare la sessione ACP a quella conversazione.
4. Altrimenti, se viene richiesta l’associazione al thread e il canale corrente la supporta, associare la sessione ACP al thread.
5. Instradare i messaggi successivi associati a quella stessa sessione ACP finché non viene sfocata/chiusa/scaduta.

​

ACP rispetto ai sottoagenti

​

Come ACP esegue Claude Code

1. Piano di controllo della sessione ACP di OpenClaw
2. plugin runtime acpx incluso
3. adapter Claude ACP
4. meccanismo runtime/sessione lato Claude

• Claude ACP non è la stessa cosa del runtime di fallback diretto claude-cli/....
• Claude ACP è una sessione harness con controlli ACP, ripresa della sessione, tracciamento delle attività in background e associazione opzionale a conversazione/thread.
• claude-cli/... è un backend CLI locale solo testo. Vedi Backend CLI.

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

​

Sessioni associate

​

Associazioni alla conversazione corrente

• OpenClaw continua a gestire il trasporto del canale, l’autenticazione, la sicurezza e la consegna.
• La conversazione corrente viene fissata alla chiave della sessione ACP avviata.
• I messaggi successivi in quella conversazione vengono instradati alla stessa sessione ACP.
• /new e /reset reimpostano sul posto la stessa sessione ACP associata.
• /acp close chiude la sessione e rimuove l’associazione della 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. L’associazione 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 su un agente ACP diverso e non passi --cwd, OpenClaw eredita per default il workspace dell’agente di destinazione, non quello del richiedente.
• Se quel percorso del workspace ereditato manca (ENOENT/ENOTDIR), OpenClaw torna al cwd predefinito del backend invece di riutilizzare silenziosamente l’albero sbagliato.
• Se il workspace ereditato esiste ma non è accessibile (per esempio EACCES), l’avvio restituisce il reale errore di accesso invece di eliminare cwd.

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

• /acp spawn codex --bind here: mantieni questa chat, avvia o collega una sessione Codex ACP 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: stessa associazione di chat di cui sopra, ma Codex gira in /workspace/repo

• I canali/chat che dichiarano il supporto all’associazione alla conversazione corrente possono usare --bind here tramite il percorso condiviso di associazione della conversazione.
• I canali con semantica personalizzata di thread/topic possono comunque fornire una canonizzazione specifica del canale dietro la stessa interfaccia condivisa.
• --bind here significa sempre “associa sul posto la conversazione corrente”.
• Le associazioni generiche alla conversazione corrente usano l’archivio di associazioni 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 associazioni ACP alla conversazione corrente, OpenClaw restituisce un chiaro messaggio di operazione non supportata.
• resume e le domande “nuova sessione” riguardano la sessione ACP, non il canale. Puoi riutilizzare o sostituire lo stato runtime senza cambiare la superficie di chat corrente.

​

Sessioni associate al thread

• OpenClaw associa un thread a una sessione ACP di destinazione.
• I messaggi successivi in quel thread vengono instradati alla sessione ACP associata.
• L’output ACP viene consegnato allo stesso thread.
• Sfocatura/chiusura/archiviazione/scadenza per timeout di inattività o età massima rimuovono l’associazione.

• acp.enabled=true
• acp.dispatch.enabled è attivo per default (imposta false per mettere in pausa il dispatch ACP)
• Flag di avvio sessioni ACP su thread dell’adapter di canale abilitato (specifico per adapter)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

​

Canali che supportano i thread

• Qualsiasi adapter di canale che espone la capacità di associazione 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 associazione.

​

Impostazioni specifiche del canale

​

Modello di associazione

• bindings[].type="acp" indica un’associazione 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/gruppo BlueBubbles: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Preferisci chat_id:* o chat_identifier:* per associazioni stabili dei gruppi.
  • Chat DM/gruppo iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Preferisci chat_id:* per associazioni stabili dei gruppi.
• bindings[].agentId è l’id dell’agente OpenClaw proprietario.
• Le sostituzioni ACP opzionali si trovano in bindings[].acp:
  • mode (persistent o oneshot)
  • label
  • cwd
  • backend

​

Valori predefiniti del runtime per agente

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent (id harness, per 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 (per 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 assicura che la sessione ACP configurata esista prima dell’uso.
• I messaggi in quel canale o topic vengono instradati alla sessione ACP configurata.
• Nelle conversazioni associate, /new e /reset reimpostano sul posto la stessa chiave della sessione ACP.
• Le associazioni runtime temporanee (per esempio create 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 di workspace ereditati mancanti tornano al cwd predefinito del backend; i veri errori di accesso su percorsi esistenti vengono mostrati come errori di avvio.

​

Avviare sessioni ACP (interfacce)

​

Da sessions_spawn

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

• runtime è predefinito su 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 associata persistente.

• task (obbligatorio): prompt iniziale inviato alla sessione ACP.
• runtime (obbligatorio per ACP): deve essere "acp".
• agentId (opzionale): id harness ACP di destinazione. Torna a acp.defaultAgent se impostato.
• thread (opzionale, predefinito false): richiede il flusso di associazione al thread quando supportato.
• mode (opzionale): run (one-shot) o session (persistente).
  • il predefinito è run
  • se thread: true e mode è omesso, OpenClaw può scegliere un comportamento persistente per default a seconda del percorso runtime
  • mode: "session" richiede thread: true
• cwd (opzionale): directory di lavoro runtime richiesta (validata 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 reali errori di accesso vengono restituiti.
• label (opzionale): etichetta visibile all’operatore usata nel testo di sessione/banner.
• resumeSessionId (opzionale): riprende una sessione ACP esistente invece di crearne una nuova. L’agente ricarica la cronologia della conversazione tramite session/load. Richiede runtime: "acp".
• streamTo (opzionale): "parent" inoltra riepiloghi di avanzamento della sessione ACP iniziale alla sessione richiedente come eventi di sistema.
  • Quando disponibile, le risposte accettate includono streamLogPath che punta a un log JSONL con ambito di sessione (<sessionId>.acp-stream.jsonl) che puoi seguire per l’intera cronologia dell’inoltro.

​

Riprendere una sessione esistente

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

• Passare una sessione Codex dal portatile al telefono — chiedi al tuo agente di riprendere da dove avevi lasciato
• Continuare una sessione di coding che hai iniziato in modo interattivo nella CLI, ora in modo headless tramite il tuo agente
• Riprendere 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 dei sottoagenti.
• resumeSessionId ripristina la cronologia della conversazione ACP upstream; thread e mode continuano comunque ad applicarsi normalmente alla nuova sessione OpenClaw che stai creando, quindi mode: "session" richiede ancora thread: true.
• L’agente di destinazione deve supportare session/load (Codex e Claude Code lo supportano).
• Se l’id della 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 linea ACP in src/gateway/sessions-patch.ts (subagent:* or acp:* sessions).
3. Apri una sessione bridge ACPX temporanea verso un agente live (per 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 riporti:
   • accepted=yes
   • una vera childSessionKey
   • nessun errore del validatore
6. Pulisci la sessione bridge ACPX temporanea.

Usa subito lo strumento sessions_spawn con runtime: "acp", agentId: "codex" e mode: "run".
Imposta task su: "Reply with exactly LIVE-ACP-SPAWN-OK".
Poi riporta solo: 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 intenzionalmente testando sessioni ACP persistenti associate ai thread.
• Non richiedere streamTo: "parent" per il gate di base. Quel percorso dipende da capacità del richiedente/sessione ed è un controllo di integrazione separato.
• Considera il test di mode: "session" associato a thread come un secondo passaggio di integrazione più ricco da un vero thread Discord o topic Telegram.

​

Compatibilità con la sandbox

• Se la sessione richiedente è in sandbox, gli avvii ACP sono 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 sessione di destinazione

1. Argomento di destinazione esplicito (o --session per /acp steer)
   • prova la chiave
   • poi l’id sessione in formato UUID
   • poi l’etichetta
2. Associazione del thread corrente (se questa conversazione/thread è associata a una sessione ACP)
3. Fallback alla sessione del richiedente corrente

​

Modalità di associazione 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 di associazione alla conversazione corrente.
• --bind e --thread non possono essere combinati nella stessa chiamata /acp spawn.

​

Modalità thread all’avvio

• Su superfici senza associazione ai thread, il comportamento predefinito è di fatto off.
• L’avvio associato al thread richiede 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 la sostituzione cwd del runtime.
• /acp set <key> <value> è il percorso generico.
  • Caso speciale: key=cwd usa il percorso di sostituzione cwd.
• /acp reset-options cancella tutte le sostituzioni 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,
    // Opzionale. 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 è predefinito sul node_modules/.bin/acpx locale al plugin all’interno del pacchetto plugin ACPX.
2. La versione attesa è predefinita sul pin dell’estensione.
3. All’avvio, OpenClaw registra subito 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 del workspace OpenClaw.
• expectedVersion: "any" disabilita il controllo rigoroso della versione.
• Quando command punta a un binario/percorso personalizzato, l’installazione automatica locale al plugin viene disabilitata.
• L’avvio di OpenClaw resta non bloccante mentre viene eseguito il controllo di stato del backend.

​

Installazione automatica delle dipendenze

​

Bridge MCP degli strumenti 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 gli strumenti plugin già registrati dai plugin OpenClaw installati e abilitati.
• Mantiene la funzionalità esplicita e disattivata per default.

• Questo amplia la superficie degli strumenti dell’harness ACP.
• Gli agenti ACP ottengono accesso solo agli strumenti plugin già attivi nel gateway.
• Consideralo come lo stesso confine di fiducia dell’autorizzare quei plugin a essere eseguiti in OpenClaw stesso.
• Esamina i plugin installati prima di abilitarlo.

​

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 default permissionMode=approve-reads e nonInteractivePermissions=fail. Nelle sessioni ACP non interattive, qualsiasi scrittura o exec che attiva una richiesta 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 bloccarsi.

​

Risoluzione dei problemi