Supervisore Claw

Obiettivo

Claw Supervisor consente a un'istanza OpenClaw sempre attiva di monitorare e guidare una flotta di sessioni Codex senza modificare la normale esperienza utente di Codex. Un utente può accedere a un host tramite SSH, avviare Codex, lavorare nella TUI e avere comunque il supervisore che legge la sessione, la guida, la interrompe, genera sessioni correlate e accetta passaggi di consegne. Le sessioni Codex possono anche richiamare OpenClaw tramite MCP.

Modello di prodotto

Codex resta la superficie di lavoro principale. OpenClaw supervisiona Codex invece di nascondere Codex dentro un sottoagente OpenClaw opaco.

Il Plugin OpenClaw si chiama codex-supervisor. crabfleet resta il profilo di distribuzione e flotta di host per le macchine CRAB invece del nome del Plugin riutilizzabile.

Il modello ha tre ruoli:

• Codex collegato a un umano: una normale TUI Codex interattiva avviata tramite un app-server condiviso.
• Codex autonomo: un thread app-server Codex generato dal supervisore a cui un umano può collegarsi in seguito.
• Claw supervisore: un agente OpenClaw sempre attivo con strumenti per stato della flotta, letture delle trascrizioni, guida, interruzione, generazione e passaggio di consegne.

OpenClaw può usare internamente il proprio meccanismo di sottoagenti esistente, ma il contratto esterno è una sessione Codex collegabile con un ID thread Codex.

Architettura

user SSH session  -> codex --remote unix://... or ws://...      -> local codex app-server daemon          <-> host sidecar / supervisor connector              <-> OpenClaw fleet supervisor                  <-> supervisor MCP exposed back to Codex

Ogni host compatibile con Codex esegue:

• Daemon app-server Codex.
• Un launcher che avvia sempre Codex interattivo con --remote.
• Un connettore che registra endpoint app-server e thread attivi presso il supervisore.

Il supervisore esegue:

• Registro degli endpoint.
• Registro delle sessioni.
• Pool di client JSON-RPC per app-server Codex.
• Server MCP per chiamate da Codex a Claw.
• Strumenti OpenClaw per il controllo da Claw a Codex.
• Motore di policy per azioni autonome, approvazioni e prevenzione dei loop.

Contratto app-server Codex

Usa le API app-server Codex come piano di controllo canonico:

• initialize, initialized
• thread/loaded/list
• thread/list
• thread/read
• thread/resume
• thread/start
• turn/start
• turn/steer
• turn/interrupt
• model/list

Codex interattivo deve essere avviato con codex --remote <endpoint> in modo che la TUI e il supervisore si connettano allo stesso app-server. codex exec autonomo oggi non è una sessione condivisa in tempo reale; usa le API app-server per il lavoro autonomo finché Codex non supporta exec --remote.

Registro delle sessioni

Il supervisore archivia un record per ogni thread Codex osservato:

{  "sessionId": "codex-thread-id",  "endpointId": "host-a",  "host": "host-a.example",  "workspace": "/workspace/repo",  "repo": "owner/repo",  "branch": "feature/example",  "source": "vscode",  "status": "idle",  "humanAttached": true,  "lastSeenAt": "2026-05-28T10:00:00.000Z",  "summary": "Short working-state summary"}

L'implementazione locale può derivare la maggior parte dei campi dai metadati del thread Codex. La distribuzione della flotta dovrebbe arricchire i record con identità dell'host, stato di collegamento dell'utente, stato git e salute del sidecar.

Superficie MCP per Codex

Ogni Codex supervisionato riceve un server MCP chiamato openclaw-codex-supervisor.

Strumenti:

• codex_sessions_list: elenca le sessioni Codex visibili.
• codex_session_read: legge una trascrizione.
• codex_session_send: invia un messaggio a un thread inattivo o guida un thread attivo.
• codex_session_interrupt: interrompe il turno attivo.
• codex_endpoint_probe: verifica la connettività dell'endpoint.
• claw_report_progress: pubblica lo stato dell'attività corrente al supervisore.
• claw_ask: chiede aiuto o delega al supervisore.
• codex_spawn: crea una nuova sessione Codex autonoma.
• codex_handoff: richiede la presa in carico da parte di un umano o di un pari.

Risorse:

• codex://sessions
• codex://sessions/{sessionId}
• codex://sessions/{sessionId}/transcript

Superficie di controllo Claw

Il Claw sempre attivo riceve le stesse primitive degli strumenti interni:

• elencare sessioni ed endpoint
• leggere trascrizioni
• inviare/guidare testo
• interrompere il lavoro attivo
• generare nuove sessioni
• riassumere e assegnare sessioni
• trasmettere istruzioni a un gruppo filtrato
• contrassegnare le sessioni come bloccate, completate o abbandonate

Comportamento degli strumenti:

• Se un thread di destinazione è inattivo, codex_session_send viene mappato a turn/start.
• Se un thread di destinazione è attivo e un ID turno in corso è visibile, viene mappato a turn/steer.
• Se non è possibile identificare il turno attivo, lo strumento fallisce in modo chiuso invece di creare un turno non correlato.
• I controlli di scrittura MCP esposti da Codex restano disabilitati a meno che una policy attendibile riservata al supervisore non li abiliti.
• Le letture grezze delle trascrizioni restano disabilitate a meno che una policy attendibile riservata al supervisore non le abiliti.
• Le approvazioni autonome negano per impostazione predefinita le approvazioni di strumenti/file a meno che una policy esplicita non dica diversamente.

Flusso di avvio

Accesso interattivo all'host:

1. L'utente accede a un host CRAB tramite SSH.
2. Il servizio SSH avvia o verifica codex app-server daemon start.
3. Il wrapper di login avvia codex --remote unix:// --cd <workspace>.
4. Il connettore dell'host registra endpoint e thread caricato.
5. Il supervisore emette un evento di flotta ad alta priorità: nuova sessione Codex, workspace, stato collegato a un umano, anteprima dell'attività corrente.
6. Il Claw supervisore può leggere e guidare immediatamente.

Generazione autonoma:

1. Il supervisore seleziona host e workspace.
2. Il connettore dell'host apre o riprende un thread app-server Codex.
3. Il supervisore avvia il primo turno con testo dell'attività e configurazione MCP.
4. Il registro delle sessioni lo contrassegna come autonomo e collegabile.
5. Un umano può collegarsi in seguito con codex --remote <endpoint> resume <threadId> quando Codex supporterà quella UX esatta, oppure tramite il flusso di ripresa attuale sullo stesso app-server.

Distribuzione

Piano di controllo preferito:

• I connettori degli host mantengono connessioni WebSocket in uscita verso il supervisore.
• Lo stato del supervisore risiede nello storage del Gateway OpenClaw.
• L'app-server Codex resta locale a ciascun host; non esporre mai un app-server grezzo non autenticato a Internet pubblico.

Idoneità di Cloudflare:

• Buono per registro, oggetti durevoli, aggregazione WebSocket, routing leggero degli eventi ed endpoint MCP/Gateway pubblici.
• Non sufficiente da solo per il controllo diretto di host privati perché i Worker non possono chiamare socket Unix privati arbitrari o app-server local loopback.
• Usa Cloudflare quando ogni connettore host chiama casa tramite WebSocket in uscita.

Fallback VPS:

• Usa un servizio Hetzner quando sono necessari controllo di processi di lunga durata, tunnel SSH, routing di rete privata o accesso al filesystem locale.
• Mantieni lo stesso protocollo: connettori host in uscita, registro supervisore centrale, app-server Codex locale.

Sicurezza

• Il bind predefinito è un socket Unix locale.
• L'app-server remoto usa autenticazione con token o bearer firmato.
• Il connettore host si autentica al supervisore con un token host con ambito.
• Gli strumenti del supervisore applicano policy per sessione: lettura, guida, interruzione, generazione, approvazione.
• I messaggi tra agenti includono originSessionId; l'eco verso sé stessi viene scartata.
• La trasmissione richiede un filtro esplicito e un numero di destinatari limitato.
• Le letture delle trascrizioni oscurano i segreti al confine OpenClaw.
• Le richieste di approvazione sono negate per impostazione predefinita per i turni originati dal supervisore, salvo se la policy le consente.

Piano di implementazione

Fase 1: MVP supervisore locale

• Aggiungere client JSON-RPC app-server Codex per proxy stdio ed endpoint WebSocket.
• Aggiungere registro endpoint/sessioni del supervisore.
• Aggiungere strumenti MCP: elenco, lettura, invio, interruzione, probe.
• Aggiungere configurazione env locale per gli endpoint.
• Aggiungere test con app-server finto e uno smoke test locale live dell'app-server.

Fase 2: Integrazione OpenClaw

• Registrare gli strumenti del supervisore nel Plugin codex-supervisor.
• Iniettare MCP del supervisore nella configurazione del thread Codex.
• Aggiungere riassunti delle sessioni al contesto dell'agente.
• Aggiungere notifiche di eventi quando compaiono nuovi thread Codex.
• Aggiungere configurazione di policy per invio/interruzione/generazione autonomi.

Fase 3: Connettore di flotta

• Il sidecar dell'host registra endpoint app-server, metadati host, metadati git/workspace e stato di collegamento umano.
• Aggiungere connettore WebSocket in uscita per piano di controllo Cloudflare o VPS.
• Aggiungere riconnessione, Heartbeat e pulizia delle sessioni obsolete.
• Aggiungere wrapper launcher SSH CRAB.

Fase 4: Operazione autonoma

• Aggiungere flussi di generazione/ripresa/presa in carico.
• Aggiungere trasmissione e delega.
• Aggiungere report di avanzamento e riassunti dello stato delle attività.
• Aggiungere prevenzione dei loop e limiti di frequenza.
• Aggiungere viste dashboard.

Fase 5: Multi-Claw

• Partizionare le sessioni per gruppo.
• Aggiungere leadership/lease per ogni sessione.
• Aggiungere log di audit e replay.
• Aggiungere escalation tra gruppi Claw.

Test di accettazione

• Un umano avvia la TUI Codex tramite un app-server condiviso.
• Il supervisore elenca il thread live tramite thread/loaded/list.
• Il supervisore legge la trascrizione tramite thread/read.
• Il supervisore invia testo a un thread inattivo tramite turn/start.
• Il supervisore guida un thread attivo tramite turn/steer.
• L'interruzione del supervisore ferma un turno attivo tramite turn/interrupt.
• Codex chiama l'MCP del supervisore ed elenca le sessioni pari.
• Un Codex autonomo viene generato e in seguito collegato a un umano.
• Un connettore host perso contrassegna le sessioni come obsolete senza eliminare la cronologia.

Domande aperte

• UX esatta di collegamento della TUI Codex per un thread app-server generato senza TUI.
• Se Codex debba aggiungere exec --remote per esecuzioni headless condivise live.
• Proprietario dello stato durevole: DB del Gateway OpenClaw, Cloudflare Durable Object o database VPS.
• Granularità della policy di approvazione per turni originati dal supervisore.
• Quanta parte del riassunto della trascrizione debba essere iniettata nel contesto del Claw sempre attivo rispetto a essere mantenuta come strumento/risorsa.