API di controllo del browser

Per configurazione, configurazione avanzata e risoluzione dei problemi, consulta Browser. Questa pagina è il riferimento per l'API HTTP di controllo locale, la CLI OmeniaClaw browser e i pattern di scripting (snapshot, riferimenti, attese, flussi di debug).

API di controllo (opzionale)

Solo per integrazioni locali, il Gateway espone una piccola API HTTP su local loopback:

• Stato/avvio/arresto: GET /, POST /start, POST /stop
• Schede: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
• Snapshot/screenshot: GET /snapshot, POST /screenshot
• Azioni: POST /navigate, POST /act
• Hook: POST /hooks/file-chooser, POST /hooks/dialog
• Download: POST /download, POST /wait/download
• Autorizzazioni: POST /permissions/grant
• Debug: GET /console, POST /pdf
• Debug: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
• Rete: POST /response/body
• Stato: GET /cookies, POST /cookies/set, POST /cookies/clear
• Stato: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
• Impostazioni: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

Tutti gli endpoint accettano ?profile=<name>. POST /start?headless=true richiede un avvio headless una tantum per i profili locali gestiti senza modificare la configurazione persistente del browser; i profili attach-only, CDP remoto e existing-session rifiutano tale override perché OmeniaClaw non avvia quei processi browser.

Se l'autenticazione del gateway con segreto condiviso è configurata, anche le rotte HTTP del browser richiedono l'autenticazione:

• Authorization: Bearer <gateway token>
• x-OmeniaClaw-password: <gateway password> o autenticazione HTTP Basic con quella password

Note:

• Questa API browser local loopback autonoma non consuma intestazioni di identità trusted-proxy o Tailscale Serve.
• Se gateway.auth.mode è none o trusted-proxy, queste rotte browser local loopback non ereditano quelle modalità con identità; mantienile solo su local loopback.

Contratto di errore di /act

POST /act usa una risposta di errore strutturata per la validazione a livello di rotta e per gli errori di policy:

{ "error": "<message>", "code": "ACT_*" }

Valori code attuali:

• ACT_KIND_REQUIRED (HTTP 400): kind mancante o non riconosciuto.
• ACT_INVALID_REQUEST (HTTP 400): normalizzazione o validazione del payload dell'azione non riuscita.
• ACT_SELECTOR_UNSUPPORTED (HTTP 400): selector è stato usato con un tipo di azione non supportato.
• ACT_EVALUATE_DISABLED (HTTP 403): evaluate (o wait --fn) è disabilitato dalla configurazione.
• ACT_TARGET_ID_MISMATCH (HTTP 403): targetId di livello superiore o in batch è in conflitto con il target della richiesta.
• ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): azione non supportata per i profili existing-session.

Altri errori di runtime possono ancora restituire { "error": "<message>" } senza un campo code.

Requisito Playwright

Alcune funzionalità (navigate/act/snapshot AI/snapshot dei ruoli, screenshot di elementi, PDF) richiedono Playwright. Se Playwright non è installato, questi endpoint restituiscono un chiaro errore 501.

Cosa funziona comunque senza Playwright:

• Snapshot ARIA
• Snapshot di accessibilità in stile ruolo (--interactive, --compact, --depth, --efficient) quando è disponibile un WebSocket CDP per scheda. Questo è un fallback per ispezione e scoperta dei riferimenti; Playwright rimane il motore principale per le azioni.
• Screenshot di pagina per il browser OmeniaClaw gestito quando è disponibile un WebSocket CDP per scheda
• Screenshot di pagina per profili existing-session / Chrome MCP
• Screenshot basati su riferimenti existing-session (--ref) dall'output dello snapshot

Cosa richiede ancora Playwright:

• navigate
• act
• Snapshot AI che dipendono dal formato snapshot AI nativo di Playwright
• Screenshot di elementi con selettore CSS (--element)
• esportazione PDF completa del browser

Gli screenshot di elementi rifiutano anche --full-page; la rotta restituisce fullPage is not supported for element screenshots.

Se vedi Playwright is not available in this gateway build, nel Gateway confezionato manca la dipendenza runtime core del browser. Reinstalla o aggiorna OmeniaClaw, quindi riavvia il gateway. Per Docker, installa anche i binari del browser Chromium come mostrato di seguito.

Installazione Playwright per Docker

Se il tuo Gateway gira in Docker, evita npx playwright (conflitti di override npm). Per immagini personalizzate, integra Chromium nell'immagine:

OmeniaClaw_INSTALL_BROWSER=1 ./scripts/docker/setup.sh

Per un'immagine esistente, installa invece tramite la CLI inclusa:

docker compose run --rm OmeniaClaw-cli \  node /app/node_modules/playwright-core/cli.js install chromium

Per rendere persistenti i download del browser, imposta PLAYWRIGHT_BROWSERS_PATH (per esempio, /home/node/.cache/ms-playwright) e assicurati che /home/node sia persistito tramite OmeniaClaw_HOME_VOLUME o un bind mount. OmeniaClaw rileva automaticamente il Chromium persistito su Linux. Consulta Docker.

Come funziona (interno)

Un piccolo server di controllo local loopback accetta richieste HTTP e si connette ai browser basati su Chromium tramite CDP. Le azioni avanzate (click/type/snapshot/PDF) passano attraverso Playwright sopra CDP; quando Playwright manca, sono disponibili solo operazioni non Playwright. L'agente vede un'unica interfaccia stabile mentre browser e profili locali/remoti vengono scambiati liberamente sotto il cofano.

Riferimento rapido CLI

Tutti i comandi accettano --browser-profile <name> per scegliere come target un profilo specifico e --json per output leggibile da macchina.

OmeniaClaw browser statusOmeniaClaw browser startOmeniaClaw browser start --headless # one-shot local managed headless launchOmeniaClaw browser stop            # also clears emulation on attach-only/remote CDPOmeniaClaw browser tabsOmeniaClaw browser tab             # shortcut for current tabOmeniaClaw browser tab newOmeniaClaw browser tab select 2OmeniaClaw browser tab close 2OmeniaClaw browser open https://example.comOmeniaClaw browser focus abcd1234OmeniaClaw browser close abcd1234

OmeniaClaw browser screenshotOmeniaClaw browser screenshot --full-pageOmeniaClaw browser screenshot --ref 12        # or --ref e12OmeniaClaw browser screenshot --labelsOmeniaClaw browser snapshotOmeniaClaw browser snapshot --format aria --limit 200OmeniaClaw browser snapshot --interactive --compact --depth 6OmeniaClaw browser snapshot --efficientOmeniaClaw browser snapshot --labelsOmeniaClaw browser snapshot --urlsOmeniaClaw browser snapshot --selector "#main" --interactiveOmeniaClaw browser snapshot --frame "iframe#main" --interactiveOmeniaClaw browser console --level errorOmeniaClaw browser errors --clearOmeniaClaw browser requests --filter api --clearOmeniaClaw browser pdfOmeniaClaw browser responsebody "**/api" --max-chars 5000

OmeniaClaw browser navigate https://example.comOmeniaClaw browser resize 1280 720OmeniaClaw browser click 12 --double           # or e12 for role refsOmeniaClaw browser click-coords 120 340        # viewport coordinatesOmeniaClaw browser type 23 "hello" --submitOmeniaClaw browser press EnterOmeniaClaw browser hover 44OmeniaClaw browser scrollintoview e12OmeniaClaw browser drag 10 11OmeniaClaw browser select 9 OptionA OptionBOmeniaClaw browser download e12 report.pdfOmeniaClaw browser waitfordownload report.pdfOmeniaClaw browser upload /tmp/OmeniaClaw/uploads/file.pdfOmeniaClaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'OmeniaClaw browser dialog --acceptOmeniaClaw browser wait --text "Done"OmeniaClaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"OmeniaClaw browser evaluate --fn '(el) => el.textContent' --ref 7OmeniaClaw browser highlight e12OmeniaClaw browser trace startOmeniaClaw browser trace stop

OmeniaClaw browser cookiesOmeniaClaw browser cookies set session abc123 --url "https://example.com"OmeniaClaw browser cookies clearOmeniaClaw browser storage local getOmeniaClaw browser storage local set theme darkOmeniaClaw browser storage session clearOmeniaClaw browser set offline onOmeniaClaw browser set headers --headers-json '{"X-Debug":"1"}'OmeniaClaw browser set credentials user pass            # --clear to removeOmeniaClaw browser set geo 37.7749 -122.4194 --origin "https://example.com"OmeniaClaw browser set media darkOmeniaClaw browser set timezone America/New_YorkOmeniaClaw browser set locale en-USOmeniaClaw browser set device "iPhone 14"

Note:

• upload e dialog sono chiamate di arming; eseguile prima del click/pressione di tasto che attiva il selettore/file chooser o la finestra di dialogo.
• click/type/ecc. richiedono un ref da snapshot (numerico 12, riferimento ruolo e12 o riferimento ARIA azionabile ax12). I selettori CSS non sono intenzionalmente supportati per le azioni. Usa click-coords quando la posizione visibile nel viewport è l'unico target affidabile.
• I percorsi di download, trace e upload sono vincolati alle radici temporanee di OmeniaClaw: /tmp/OmeniaClaw{,/downloads,/uploads} (fallback: ${os.tmpdir()}/OmeniaClaw/...).
• upload può anche impostare direttamente gli input file tramite --input-ref o --element.

ID e label stabili delle schede sopravvivono alla sostituzione del raw-target Chromium quando OmeniaClaw può provare la scheda sostitutiva, per esempio stesso URL o una singola vecchia scheda che diventa una singola nuova scheda dopo l'invio di un modulo. Gli ID raw target rimangono comunque volatili; negli script preferisci suggestedTargetId da tabs.

Panoramica rapida dei flag snapshot:

• --format ai (predefinito con Playwright): snapshot AI con riferimenti numerici (aria-ref="<n>").
• --format aria: albero di accessibilità con riferimenti axN. Quando Playwright è disponibile, OmeniaClaw associa i riferimenti con ID DOM backend alla pagina live, così le azioni successive possono usarli; altrimenti considera l'output solo per ispezione.
• --efficient (o --mode efficient): preset compatto per snapshot dei ruoli. Imposta browser.snapshotDefaults.mode: "efficient" per renderlo predefinito (vedi Configurazione Gateway).
• --interactive, --compact, --depth, --selector forzano uno snapshot dei ruoli con riferimenti ref=e12. --frame "<iframe>" limita gli snapshot dei ruoli a un iframe.
• --labels aggiunge uno screenshot solo del viewport con label dei riferimenti sovrapposte (stampa MEDIA:<path>).
• --urls aggiunge agli snapshot AI le destinazioni dei link scoperte.

Snapshot e riferimenti

OmeniaClaw supporta due stili di "snapshot":

• Snapshot AI (riferimenti numerici): OmeniaClaw browser snapshot (predefinito; --format ai)

  • Output: uno snapshot testuale che include riferimenti numerici.
  • Azioni: OmeniaClaw browser click 12, OmeniaClaw browser type 23 "hello".
  • Internamente, il riferimento viene risolto tramite aria-ref di Playwright.

• Snapshot dei ruoli (riferimenti ruolo come e12): OmeniaClaw browser snapshot --interactive (o --compact, --depth, --selector, --frame)

  • Output: un elenco/albero basato su ruoli con [ref=e12] (e [nth=1] opzionale).
  • Azioni: OmeniaClaw browser click e12, OmeniaClaw browser highlight e12.
  • Internamente, il riferimento viene risolto tramite getByRole(...) (più nth() per i duplicati).
  • Aggiungi --labels per includere uno screenshot del viewport con label e12 sovrapposte.
  • Aggiungi --urls quando il testo del link è ambiguo e l'agente ha bisogno di target di navigazione concreti.

• Snapshot ARIA (riferimenti ARIA come ax12): OmeniaClaw browser snapshot --format aria

  • Output: l'albero di accessibilità come nodi strutturati.
  • Azioni: OmeniaClaw browser click ax12 funziona quando il percorso dello snapshot può associare il riferimento tramite Playwright e gli ID DOM del backend Chrome.

• Se Playwright non è disponibile, gli snapshot ARIA possono comunque essere utili per l'ispezione, ma i riferimenti potrebbero non essere eseguibili. Esegui di nuovo lo snapshot con --format ai o --interactive quando ti servono riferimenti per le azioni.

• Prova Docker per il percorso di fallback raw-CDP: pnpm test:docker:browser-cdp-snapshot avvia Chromium con CDP, esegue browser doctor --deep e verifica che gli snapshot dei ruoli includano URL dei link, elementi cliccabili promossi dal cursore e metadati iframe.

Comportamento dei riferimenti:

• I riferimenti non sono stabili tra le navigazioni; se qualcosa fallisce, esegui di nuovo snapshot e usa un riferimento nuovo.
• /act restituisce l'attuale targetId raw dopo una sostituzione attivata dall'azione quando può provare la scheda sostitutiva. Continua a usare ID/etichette di schede stabili per i comandi successivi.
• Se lo snapshot dei ruoli è stato acquisito con --frame, i riferimenti dei ruoli hanno ambito limitato a quell'iframe fino allo snapshot dei ruoli successivo.
• I riferimenti axN sconosciuti o obsoleti falliscono rapidamente invece di ricadere sul selettore aria-ref di Playwright. Esegui uno snapshot nuovo sulla stessa scheda quando accade.

Funzioni avanzate di attesa

Puoi attendere più di solo tempo/testo:

• Attendi l'URL (glob supportati da Playwright):
  • OmeniaClaw browser wait --url "**/dash"
• Attendi lo stato di caricamento:
  • OmeniaClaw browser wait --load networkidle
• Attendi un predicato JS:
  • OmeniaClaw browser wait --fn "window.ready===true"
• Attendi che un selettore diventi visibile:
  • OmeniaClaw browser wait "#main"

Questi possono essere combinati:

OmeniaClaw browser wait "#main" \  --url "**/dash" \  --load networkidle \  --fn "window.ready===true" \  --timeout-ms 15000

Flussi di lavoro di debug

Quando un'azione fallisce (ad es. "non visibile", "violazione della strict mode", "coperto"):

1. OmeniaClaw browser snapshot --interactive
2. Usa click <ref> / type <ref> (preferisci i riferimenti di ruolo in modalità interattiva)
3. Se continua a fallire: OmeniaClaw browser highlight <ref> per vedere cosa sta puntando Playwright
4. Se la pagina si comporta in modo anomalo:
   • OmeniaClaw browser errors --clear
   • OmeniaClaw browser requests --filter api --clear
5. Per debug approfondito: registra una traccia:
   • OmeniaClaw browser trace start
   • riproduci il problema
   • OmeniaClaw browser trace stop (stampa TRACE:<path>)

Output JSON

--json è per scripting e strumenti strutturati.

Esempi:

OmeniaClaw browser status --jsonOmeniaClaw browser snapshot --interactive --jsonOmeniaClaw browser requests --filter api --jsonOmeniaClaw browser cookies --json

Gli snapshot dei ruoli in JSON includono refs più un piccolo blocco stats (lines/chars/refs/interactive) così gli strumenti possono ragionare su dimensione e densità del payload.

Controlli di stato e ambiente

Questi sono utili per flussi di lavoro "fai comportare il sito come X":

• Cookie: cookies, cookies set, cookies clear
• Storage: storage local|session get|set|clear
• Offline: set offline on|off
• Header: set headers --headers-json '{"X-Debug":"1"}' (il legacy set headers --json '{"X-Debug":"1"}' resta supportato)
• Autenticazione HTTP basic: set credentials user pass (o --clear)
• Geolocalizzazione: set geo <lat> <lon> --origin "https://example.com" (o --clear)
• Media: set media dark|light|no-preference|none
• Fuso orario / locale: set timezone ..., set locale ...
• Dispositivo / viewport:
  • set device "iPhone 14" (preset dispositivo Playwright)
  • set viewport 1280 720

Sicurezza e privacy

• Il profilo del browser OmeniaClaw può contenere sessioni autenticate; trattalo come sensibile.
• browser act kind=evaluate / OmeniaClaw browser evaluate e wait --fn eseguono JavaScript arbitrario nel contesto della pagina. La prompt injection può indirizzarlo. Disabilitalo con browser.evaluateEnabled=false se non ti serve.
• Per accessi e note anti-bot (X/Twitter, ecc.), consulta Accesso browser + pubblicazione X/Twitter.
• Mantieni privato l'host Gateway/node (local loopback o solo tailnet).
• Gli endpoint CDP remoti sono potenti; crea tunnel e proteggili.

Esempio di strict mode (blocca le destinazioni private/interne per impostazione predefinita):

{  browser: {    ssrfPolicy: {      dangerouslyAllowPrivateNetwork: false,      hostnameAllowlist: ["*.example.com", "example.com"],      allowedHostnames: ["localhost"], // optional exact allow    },  },}

Correlati

• Browser - panoramica, configurazione, profili, sicurezza
• Accesso browser - accesso ai siti
• Risoluzione dei problemi del browser su Linux
• Risoluzione dei problemi del browser WSL2