Appunti dal laboratorio
Come pensiamo agli agenti che vivono nelle tue app di messaggistica, cosa abbiamo imparato costruendoli e gli aspetti pratici che puoi usare già oggi.
329 post
Tutti i post
Cosa invia OpenClaw ai suoi server
Per impostazione predefinita OpenClaw fa una richiesta in uscita al giorno, e la documentazione dice esattamente cosa contiene: versione, sistema operativo, versione di Node.js, architettura e superficie, senza alcun identificativo di installazione. Ecco il quadro completo, compresa la posizione ricavata da Cloudflare e conservata per tre mesi, più ogni interruttore che ferma le richieste.
La Control UI di OpenClaw
Il Gateway espone una dashboard nel browser sulla porta 18789, e la prima cosa che mostra è un unico campo Gateway secret. Cosa accetta quel campo, perché anche un browser sulla stessa macchina deve compilarlo, cosa fanno l’elenco degli agenti e la modalità team, e cosa eseguire quando l’URL LAN è bloccato.
Failed to start Chrome CDP on port 18800
L’errore ti dà una sola riga e nessun indizio. Su un server Linux la causa è quasi sempre il browser: apt install chromium ti consegna un wrapper snap il cui confinamento rompe il modo in cui OpenClaw avvia e sorveglia Chrome. Ecco le soluzioni, le sei impostazioni che contano e il controllo che distingue un errore di avvio CDP da un blocco della navigazione.
Il relay del browser di OpenClaw
OpenClaw può pilotare un browser che non si trova sulla macchina del Gateway: un node host inoltra le azioni, oppure un cdpUrl si collega a un Chromium ospitato. Ecco come si comportano instradamento, profili e credenziali.
Agenti ACP di OpenClaw
OpenClaw esegue harness di programmazione esterni tramite l’Agent Client Protocol: Claude Code, Gemini CLI, Cursor, Copilot, Droid, OpenCode e altri undici, avviati da un messaggio in chat e monitorati come attività in background. L’installazione di acpx in due comandi, le insidie del primo avvio, compresa la trappola di plugins.allow, la checklist dei prerequisiti che decide se il percorso viene proposto o meno, e i diciassette ID di destinazione degli harness.
Attivare OpenClaw da Gmail
Gli eventi della casella Gmail arrivano a OpenClaw tramite un topic Google Pub/Sub, un processo watcher e l’hook HTTP del Gateway, e il preset integrato dà a ogni email una propria sessione senza limitare nient’altro. Ecco la configurazione del topic e del watch con gcloud, il modello a due token, l’agente mail_reader limitato e in sandbox raccomandato dalla documentazione e il test del confine che ti dice se il lettore è davvero contenuto.
Uscire dalla sandbox di proposito
La modalità elevated permette a un agente OpenClaw in sandbox di eseguire comandi fuori dalla sandbox, sotto gate di approvazione che restano configurabili. Non fa nulla per un agente che non è mai stato in sandbox, e non può scavalcare la policy degli strumenti né un ruolo che richiedeva la sandbox fin dall’inizio. Questo articolo tratta le quattro direttive, l’ordine di risoluzione, i gate e le allowlist che devono passare tutti, e ciò che l’elevazione lascia volutamente com’è.
Motori di contesto di OpenClaw
Un motore di contesto decide quali messaggi raggiungono il modello, come viene riassunta la cronologia più vecchia e come il contesto attraversa i confini dei sub-agent; OpenClaw include un motore legacy e lo usa per impostazione predefinita, un motore plugin si seleziona tramite uno slot di configurazione, l’interfaccia richiede ingest, assemble e compact con hook facoltativi per bootstrap, maintain, ingest in batch e sub-agent, un motore plugin che fallisce viene messo in quarantena per il processo e il lavoro ripiega sul legacy, e un ownsCompaction impostato su false non ripristina il percorso di compattazione legacy.
Exec in background e strumento process in OpenClaw
Un comando che supera il ritardo di rilascio restituisce un ID di sessione e una breve coda dell’output invece di bloccarsi; l’output resta in memoria fino al limite aggregato, le sessioni terminate scadono dopo una durata misurata dal completamento, con al massimo 50 sessioni terminate e due milioni di caratteri conservati, gli ambienti worker basati su nodo mantengono vivi i comandi in background tra un turno e l’altro, e lo strumento process esegue il polling, legge log paginati, scrive su stdin, invia tasti, conferma, incolla, termina e ripulisce.
Lo strumento exec di OpenClaw
Exec esegue comandi shell nello spazio di lavoro e può creare, modificare o eliminare file ovunque l’host scelto lo consenta, quindi disattivare gli strumenti per i file non lo rende di sola lettura; il parametro host si risolve nella sandbox quando è attivo un runtime di sandbox e nel gateway negli altri casi, la chiave mode imposta deny, allowlist, ask, auto o full, il revisore automatico restituisce allow, deny o ask per i comandi idonei non coperti dall’elenco, con l’intera catena di dispatch vincolata e ricontrollata prima dell’avvio, e i comandi di sessione possono solo rendere la policy più restrittiva.
L’API OpenResponses di OpenClaw
Il gateway espone un endpoint responses compatibile con OpenResponses una volta attivato gateway.http.endpoints.responses, con le stesse regole di autenticazione, scope e agente di destinazione delle chat completions; l’input è una stringa o un elenco di elementi, i risultati degli strumenti tornano come function_call_output, previous_response_id riutilizza una sessione all’interno dello stesso ambito di agente, utente e sessione, i file vengono decodificati nel prompt di sistema come contenuto non attendibile, con i PDF rasterizzati quando il testo è scarso, e lo streaming emette eventi response tipizzati che terminano con DONE.
Autenticazione tramite proxy attendibile in OpenClaw
In modalità trusted-proxy il gateway si fida di un header con l’identità dell’utente solo se proviene da indirizzi sorgente elencati come proxy attendibili, rifiuta le sorgenti loopback a meno che l’opzione non sia attivata deliberatamente, rifiuta le sorgenti che corrispondono alle sue stesse interfacce, richiede gli header configurati e una corrispondenza nell’allowlist, si rifiuta di avviarsi quando è configurato anche un token condiviso, e l’audit di sicurezza segnala di proposito la modalità come critica; gli scope per identità concedono agli utenti verificati scope validi solo per la sessione, l’approvazione automatica dei dispositivi può trasformare l’identità del proxy nel confine di registrazione, e l’header degli scope può solo restringere.
Approvazioni exec avanzate in OpenClaw
I safe bin come cut, head, tail, tr, uniq e wc girano in modalità allowlist senza voci perché rifiutano argomenti di file e token simili a percorsi; grep e sort vanno abilitati esplicitamente, awk, sed e jq non sono mai safe bin, gli interpreti non vi appartengono mai, i safe bin devono essere risolti dalle directory di sistema predefinite a meno che non se ne dichiarino fidate altre, la concatenazione è consentita quando ogni segmento passa, le esecuzioni di interpreti vincolano l’intera catena di dispatch prima della revisione, risolvere un’approvazione richiede lo scope dedicato approvals e non write, e le richieste possono essere inoltrate a Slack, Telegram, Discord e altri.
Risoluzione dei problemi del gateway OpenClaw
Il runbook approfondito del gateway parte sempre dagli stessi cinque comandi in ordine, si aspetta un runtime in esecuzione, una sonda di connettività ok e una riga delle capacità, poi smista per sintomo verso sei pagine: aggiornamenti e rollback, skill e provider di modelli, risposte dell’agente e interfaccia di controllo, servizio e processo del gateway, validazione della configurazione e sonde, consegna sui canali e strumenti; la maggior parte dei guasti dopo un aggiornamento è una deriva della configurazione o valori predefiniti più rigidi, da verificare tramite la modalità del gateway e l’URL remoto, i bind non loopback che ora richiedono un vero percorso di autenticazione e le approvazioni di abbinamento in sospeso per dispositivi o messaggi diretti.
L’API HTTP di OpenClaw compatibile con OpenAI
Il gateway può servire chat completions, models ed embeddings sulla propria porta una volta abilitato gateway.http.endpoints.chatCompletions; un token valido è un accesso da proprietario, quindi la documentazione lo tiene su loopback, tailnet o ingress privato; il campo model indica un agente come openclaw/default anziché un modello del provider, la stringa user ricava una chiave di sessione stabile, x-openclaw-model sovrascrive il modello del backend, e function tool, tool_choice e streaming SSE seguono i formati di OpenAI con limiti documentati.
Gli scope dell’operatore in OpenClaw
Gli scope limitano ciò che un client del gateway può fare dopo l’autenticazione, come salvaguardia all’interno di un unico dominio operatore attendibile e non come isolamento multi-tenant contro utenti ostili; operator.write implica read e talk, operator.admin implica tutto, i ruoli con nome pongono un tetto agli scope e possono richiedere la sandbox per ogni creatore, le concessioni per identità associano scope a un’identità verificata di proxy o di Tailscale, ogni RPC ha uno scope di metodo a privilegio minimo, e approvare la richiesta di un dispositivo può concedere solo scope che chi approva possiede già.
Controllo degli accessi Matrix in OpenClaw
Chi può raggiungere OpenClaw tramite Matrix e cosa conserva attorno a un messaggio: i messaggi provenienti da altri account Matrix di OpenClaw configurati, ignorati per impostazione predefinita, e l’impostazione allow-bots con true o mentions più gli override per stanza, la protezione condivisa dai loop e la sua precedenza, la regola sul proprio ID, la definizione di “scritto da un bot” su una piattaforma senza flag per i bot, le tre modalità di visibilità del contesto che filtrano le risposte recuperate, le radici dei thread e la cronologia in sospeso senza decidere cosa attiva una risposta, l’esempio di policy per messaggi diretti e stanze con allowlist e una stanza che richiede la menzione, la disattivazione completa dei messaggi diretti, i comandi di abbinamento e il codice in sospeso riutilizzato con un promemoria dopo un tempo di attesa, e i comandi slash riconosciuti nelle stanze quando sono preceduti dalla menzione del bot stesso, pur restando soggetti alla stessa autorizzazione.
Le regole push di Matrix in OpenClaw per le anteprime silenziose
La configurazione lato homeserver che fa suonare lo streaming quiet di Matrix al momento giusto: anteprime inviate come notice senza notifica, con la modifica finale che porta un marcatore, client che notificano solo quando una regola push per utente vi corrisponde, la modalità progress che finalizza attraverso lo stesso percorso, i prerequisiti (un utente destinatario, un utente bot, il token del destinatario, l’ID completo del bot come mittente e pusher funzionanti), i sei passaggi dall’attivazione della modalità quiet alla generazione o al riuso di un token, l’elenco dei pusher, l’installazione della regola override con le sue quattro condizioni e le azioni notify, la sua verifica e il test di una risposta in streaming, l’eliminazione, ID di regola univoci per bot e per destinatario con le riesecuzioni che aggiornano sul posto, le regole override dell’utente inserite prima delle regole suppress del server, le modifiche solo testuali su cui agisce la regola mentre media, fallback per anteprime obsolete e risposte finali che attivano menzioni notificano normalmente, Synapse che richiede la condizione event-property-is del 2023 con le release più vecchie che silenziosamente non trovano mai corrispondenze, e l’opzione di Tuwunel che sopprime le notifiche quando un dispositivo è attivo.
Configurazione di Microsoft Teams in OpenClaw
Le impostazioni di Teams nel blocco del canale: le otto chiavi di autenticazione che le variabili d’ambiente possono sostituire, mentre tutto il resto esiste solo nella configurazione, il limite di cronologia con i suoi fallback e il contesto dei thread tramite Graph, che aggiunge il messaggio padre e fino a cinquanta risposte impedendo l’esecuzione dei comandi citati, le modalità di visibilità all, allowlist e allowlist-quote, i limiti di cronologia dei messaggi diretti per utente, le chiavi del cloud e dell’URL del servizio per i cloud pubblico, US government, DoD e Cina, la porta e il percorso del webhook, le quattro policy dei messaggi diretti con gli ID oggetto AAD consigliati, la destinazione predefinita, l’interruttore di emergenza per la corrispondenza dei nomi, il tetto di 4000 caratteri per blocco, la suddivisione per righe, le allowlist degli host multimediali e il fallback multimediale di Graph, l’obbligo di menzione e lo stile di risposta con override per team e per canale, incluse le policy degli strumenti, il sito SharePoint per i caricamenti nei gruppi, le schede di benvenuto e di benvenuto nei gruppi con prompt iniziali, il prefisso delle risposte, il feedback con i pollici e la riflessione, e l’SSO con scope Graph delegati.
Configurare Telegram in OpenClaw
Collegare da zero un bot Telegram a OpenClaw: i flussi via chat e via web in BotFather che terminano entrambi con un token, il comando channels add che lo scrive nella configurazione, l’alternativa modificata a mano con una policy DM pairing e una voce di gruppo con carattere jolly, il fallback d’ambiente che serve solo l’account predefinito, perché non esiste un comando di login per Telegram, la verifica dello stato con il ricaricamento a caldo, i comandi pairing list e approve con codici che scadono dopo un’ora, i due ID di cui ha bisogno un gruppo e dove va ciascuno, la precedenza dei token che tiene conto dell’account e la cache dell’identità di 24 ore, la modalità privacy e lo stato di amministratore lato Telegram con la regola del rimuovere e riaggiungere, le opzioni utili di BotFather, e la scelta del trasporto tra il long polling con la sua posizione di ripresa durevole e la modalità webhook con il suo segreto, i valori predefiniti del listener, il percorso di health riservato e l’header di accettazione durevole.
Grafici, tabelle e approvazioni Slack in OpenClaw
Le superfici Block Kit che OpenClaw rende in modo nativo in Slack: il blocco grafico portabile mappato sul blocco di visualizzazione dei dati di Slack senza scope aggiuntivi, i limiti imposti su titoli, segmenti, serie e categorie, la rappresentazione testuale che ogni grafico porta con sé, il ripristino quando Slack rifiuta dei blocchi, il limite non documentato di due grafici per messaggio e il modo in cui i grafici in più passano ai messaggi successivi, il blocco tabella portabile mappato sulla tabella di dati attuale con celle di testo grezzo e di numero grezzo e intestazioni di riga, il perimetro di 20 colonne, 100 righe e 10.000 caratteri, il fallback a testo completo e l’errore di dimensione esplicito in modifica, perché le tabelle Markdown con barre verticali restano testo e i blocchi grezzi passano ancora, le tabelle incollate in entrata trattate come TSV, i due schemi di instradamento per gli invii di finestre modali gestiti dai plugin e l’evento compatto e oscurato che vede l’agente, e Slack come client di approvazione nativo per le richieste exec e dei plugin, con i suoi approvatori, destinazioni, filtri e la conservazione dello spazio di lavoro in Enterprise Grid.
Thread e sessioni Slack in OpenClaw
Dove arriva un messaggio Slack in OpenClaw e dove va la risposta: i messaggi diretti come direct, i canali come channel e i messaggi diretti di gruppo come group, i binding di instradamento che accettano i formati di destinazione Slack, l’ambito main dei messaggi diretti che riunisce i messaggi diretti ordinari, le sessioni per canale e il suffisso di thread preso dal timestamp del messaggio padre, la radice inizializzata che mantiene una menzione e il suo thread su un’unica sessione, l’ambito della cronologia, il padre ereditato e il recupero iniziale della cronologia, i due flag di menzione implicita e la chiave di menzione esplicita migrata, le modalità di risposta per canale, per tipo di chat e con il fallback legacy per i messaggi diretti, i tag di risposta manuali, il broadcast delle risposte per testo e Block Kit, l’opzione top-level, perché off su Slack disattiva anche i tag espliciti a differenza di Telegram, e i messaggi diretti Agent View, dove ogni radice del composer è una conversazione a sé e il marcatore viene appreso da tre segnali e conservato per account, spazio di lavoro e app.
Messaggi avanzati e approvazioni Telegram in OpenClaw
Le superfici avanzate che un bot Telegram di OpenClaw può usare: l’HTML standard di Telegram per impostazione predefinita, con grassetto, corsivo, link, codice, spoiler e citazioni, il flag dei messaggi avanzati che rende il Markdown come blocchi tipizzati della Bot API 10.3, come titoli, tabelle, dettagli, checklist e formule, con le didascalie ancora in HTML e le tabelle oltre le 20 colonne che ripiegano sul codice, perché resta disattivato per compatibilità con i client, le anteprime dei link, i cinque ambiti dei pulsanti inline con allowlist come valore predefinito, il blocco dei pulsanti con azioni callback e web-app e il limite delle Mini App alle chat private, come le callback non rivendicate raggiungono l’agente come testo, la conferma con la ricezione persistente, le sei azioni sui messaggi con i loro alias e i loro interruttori disattivati per impostazione predefinita, l’ispezione dell’elenco di emoji e le approvazioni exec con i loro approvatori, destinazioni, scadenza e il requisito dei pulsanti inline.
Cifratura e verifica di Matrix in OpenClaw
Come un account Matrix di OpenClaw ottiene la cifratura end-to-end e resta attendibile: il comando di configurazione che inizializza l’archiviazione dei segreti, la firma incrociata e un backup delle chiavi delle stanze, perché le chiavi di recupero passano da stdin, i tre segnali di fiducia indipendenti e la regola per cui solo la verifica tramite firma incrociata conta come verificato dal proprietario, la verifica del dispositivo e l’auto-verifica, il comando di bootstrap o riparazione e i suoi fallback UIA, stato, ripristino e reset del backup, i comandi di verifica SAS, le note sugli account multipli, l’auto-verifica all’avvio con il suo periodo di attesa, gli avvisi di verifica e cosa fare quando il dispositivo è stato eliminato.
Visualizzati 24 post su 50
Il resto del blog è in inglese. Leggilo in inglese
Basta leggere, creane uno tuo
Configura un agente, scegli un canale e fallo lavorare dentro l’app che tieni già aperta.