Windows

OpenClaw include un'app companion nativa Windows Hub più il supporto CLI per Windows. Usa Windows Hub quando vuoi un'app desktop con configurazione, stato nella tray, chat, diagnostica del Centro comandi e funzionalità di nodo Windows. Usa l'installer PowerShell quando vuoi direttamente la CLI/Gateway. Usa WSL2 quando vuoi il runtime Gateway più compatibile con Linux.

Consigliato: Windows Hub

Windows Hub è l'app companion nativa WinUI per Windows 10 20H2+ e Windows 11. Si installa senza privilegi di amministratore ed è pubblicata con installer x64 e ARM64 firmati nelle release di OpenClaw.

Scarica l'ultimo installer stabile dalla pagina delle release di OpenClaw:

• OpenClawCompanion-Setup-x64.exe
• OpenClawCompanion-Setup-arm64.exe
• Checksum

Se un link di download sopra restituisce un 404, visita la pagina delle release e cerca gli asset OpenClawCompanion-Setup-* nell'ultima release.

Dopo l'installazione, avvia OpenClaw Companion dal menu Start o dalla tray di sistema. L'installer aggiunge anche scorciatoie per Configurazione Gateway, Chat, Impostazioni, Verifica aggiornamenti e disinstallazione.

Cosa include Windows Hub

• stato nella tray di sistema e avvio all'accesso
• configurazione al primo avvio per un Gateway WSL locale di proprietà dell'app
• impostazioni di connessione per Gateway locali, remoti e con tunnel SSH
• finestra chat nativa più accesso alla Control UI del browser
• diagnostica del Centro comandi per sessioni, utilizzo, canali, nodi, associazione e comandi di riparazione
• modalità nodo Windows per canvas controllato dall'agente, schermo, fotocamera, notifiche, stato del dispositivo, sintesi vocale, riconoscimento vocale e system.run controllato
• modalità server MCP locale per client MCP come Claude Desktop, Claude Code e Cursor

Primo avvio

Al primo avvio, Windows Hub apre la configurazione quando non esiste un Gateway salvato utilizzabile. Il percorso più rapido è Configura localmente, che crea una distro WSL OpenClawGateway di proprietà dell'app, installa il Gateway al suo interno e associa l'app. Questo non esporta né modifica la tua distro Ubuntu esistente.

Scegli Configurazione avanzata oppure apri la scheda Connessioni quando hai già un Gateway. Puoi connetterti a:

• un Gateway locale su questo PC
• un Gateway WSL su questo PC
• un Gateway remoto tramite URL e token o codice di configurazione
• un Gateway raggiunto tramite tunnel SSH

Al termine della configurazione, l'icona nella tray diventa verde. Apri Centro comandi dalla tray per confermare connessione, associazione, stato del nodo e salute del canale.

Modalità nodo Windows

Windows Hub può registrarsi come nodo OpenClaw di prima classe. L'agente può quindi usare le funzionalità native di Windows dichiarate tramite il Gateway.

I comandi comuni includono:

• canvas.present, canvas.hide, canvas.navigate, canvas.eval, canvas.snapshot
• screen.snapshot e, con consenso esplicito, screen.record
• camera.list e, con consenso esplicito, camera.snap, camera.clip
• system.notify, system.run, system.run.prepare, system.which
• location.get, device.info, device.status
• stt.transcribe, tts.speak

La modalità nodo richiede l'associazione al Gateway. Se l'app mostra una richiesta di associazione, approvala dall'host Gateway:

openclaw devices listopenclaw devices approve <request-id>openclaw nodes status

Il Gateway inoltra solo i comandi dichiarati dal nodo e consentiti dalla policy del server. I comandi sensibili per la privacy come screen.record, camera.snap e camera.clip richiedono un consenso esplicito in gateway.nodes.allowCommands.

Modalità MCP locale

Windows Hub può esporre lo stesso registro di funzionalità native di Windows come server MCP locale su loopback. È utile quando vuoi che client MCP locali controllino funzionalità Windows senza un Gateway OpenClaw in esecuzione.

Abilitalo nelle Impostazioni di Windows Hub nella sezione sviluppatore/avanzata. L'app mostra l'endpoint loopback e il bearer token dopo l'abilitazione del server.

Matrice delle modalità:

CLI e Gateway nativi per Windows

Per un uso orientato al terminale, installa OpenClaw da PowerShell:

iwr -useb https://openclaw.ai/install.ps1 | iex

Verifica:

openclaw --versionopenclaw doctoropenclaw gateway status --json

I flussi CLI e Gateway nativi per Windows sono supportati e continuano a migliorare. L'avvio gestito usa le Attività pianificate di Windows quando disponibili. L'attività mantiene lo script leggibile gateway.cmd nella directory di stato di OpenClaw, ma lo avvia tramite un wrapper WScript gateway.vbs generato, così il Gateway in background non apre una finestra console visibile. Se la creazione dell'attività viene negata, OpenClaw ripiega su un elemento di accesso nella cartella Esecuzione automatica per utente.

Per installare il servizio Gateway:

openclaw gateway installopenclaw gateway status --json

Se vuoi usare solo la CLI senza un servizio Gateway gestito:

openclaw onboard --non-interactive --skip-healthopenclaw gateway run

Gateway WSL2

WSL2 rimane il runtime Gateway più compatibile con Linux su Windows. Windows Hub può configurare per te un Gateway WSL di proprietà dell'app, oppure puoi installarlo manualmente nella tua distro.

Configurazione manuale:

wsl --install# Or pick a distro explicitly:wsl --list --onlinewsl --install -d Ubuntu-24.04

Abilita systemd dentro WSL:

sudo tee /etc/wsl.conf >/dev/null <<'EOF'[boot]systemd=trueEOF

Riavvia WSL da PowerShell:

wsl --shutdown

Poi installa OpenClaw dentro WSL con il quickstart Linux:

curl -fsSL https://openclaw.ai/install.sh | bashopenclaw gateway status

Avvio automatico del Gateway prima dell'accesso a Windows

Per configurazioni WSL headless, assicurati che l'intera catena di avvio venga eseguita anche quando nessuno accede a Windows.

Dentro WSL:

sudo apt-get install -y dbus-x11sudo loginctl enable-linger "$(whoami)"openclaw gateway install

In PowerShell come amministratore:

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec dbus-launch true" /sc onstart /ru "$env:USERNAME"

Sostituisci Ubuntu con il nome della tua distro da:

wsl --list --verbose

Nota: Due modifiche rispetto alle ricette precedenti:

• dbus-launch true invece di /bin/true — Su WSL ≥ 2.6.1.0 una regressione (microsoft/WSL #13416) fa sì che la distro venga terminata per inattività 15-20 secondi dopo l'uscita dell'ultimo client, anche con linger abilitato. dbus-launch true mantiene vivo un processo figlio di init come soluzione alternativa (discussione della community, microsoft/WSL #9245).
• /ru "$env:USERNAME" invece di /ru SYSTEM — Le distro WSL per utente (la configurazione predefinita) non sono visibili all'account SYSTEM; l'attività sembra eseguirsi, ma la distro non viene mai avviata. L'esecuzione con il tuo account evita questo problema. Windows chiederà la tua password quando l'attività viene creata.

Dopo il riavvio, verifica da WSL:

systemctl --user is-enabled openclaw-gateway.servicesystemctl --user status openclaw-gateway.service --no-pager

Esporre servizi WSL sulla LAN

WSL ha una propria rete virtuale. Se un'altra macchina deve raggiungere un servizio dentro WSL, inoltra una porta Windows all'IP WSL corrente. L'IP WSL può cambiare dopo i riavvii, quindi aggiorna la regola di inoltro quando necessario.

Esempio in PowerShell come amministratore:

$Distro = "Ubuntu-24.04"$ListenPort = 2222$TargetPort = 22 $WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]if (-not $WslIp) { throw "WSL IP not found." } netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `  connectaddress=$WslIp connectport=$TargetPort New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `  -Protocol TCP -LocalPort $ListenPort -Action Allow

Note:

• SSH da un'altra macchina usa come destinazione l'IP dell'host Windows, per esempio ssh user@windows-host -p 2222.
• I nodi remoti devono puntare a un URL Gateway raggiungibile, non a 127.0.0.1.
• Usa listenaddress=0.0.0.0 per l'accesso LAN. Usa 127.0.0.1 per l'accesso solo locale.

Risoluzione dei problemi

L'icona nella tray non appare

Controlla Gestione attività per OpenClaw.Tray.WinUI.exe. Se è in esecuzione, apri l'area delle icone nascoste della tray e fissala. Se non è in esecuzione, avvia OpenClaw Companion dal menu Start.

La configurazione locale non riesce

Apri il log di configurazione da Windows Hub oppure controlla:

notepad "$env:LOCALAPPDATA\OpenClawTray\Logs\Setup\easy-setup-latest.txt"

Le cause comuni sono WSL disabilitato, virtualizzazione bloccata, stato WSL di proprietà dell'app obsoleto o un errore di rete durante l'installazione del pacchetto Gateway.

L'app dice che è richiesta l'associazione

Approva la richiesta dell'operatore o del nodo dal Gateway:

openclaw devices listopenclaw devices approve <request-id>

Se il dispositivo aveva già un token, riconnettiti dalla scheda Connessioni dopo l'approvazione.

La chat web non riesce a raggiungere un Gateway remoto

La chat web remota richiede HTTPS o localhost. Per certificati autofirmati, considera attendibile il certificato in Windows oppure usa un tunnel SSH verso un URL localhost.

screen.snapshot, fotocamera o comandi audio non riescono

Conferma le autorizzazioni Windows per fotocamera, microfono, acquisizione dello schermo e notifiche. Le installazioni pacchettizzate dichiarano le funzionalità protette, ma Windows potrebbe comunque mostrare una richiesta la prima volta che un comando le usa.

La connettività Git o GitHub non riesce

Alcune reti bloccano o limitano HTTPS verso GitHub. Se git clone o gh auth login non riesce, prova un'altra rete, una VPN o un proxy HTTP/HTTPS.

Per autenticazione gh basata su token nella sessione corrente:

$env:GH_TOKEN="<your-token>"gh auth statusgh auth setup-git

Non commettere mai token né incollarli in issue o pull request.

Correlati

• Panoramica dell'installazione
• Configurazione di Node.js
• Nodi
• Control UI
• Configurazione Gateway