OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

macOS companion app

Configurazione di sviluppo per macOS

Configurazione per sviluppatori macOS

Compilare ed eseguire l'applicazione OpenClaw per macOS dal codice sorgente.

Prerequisiti

  • Xcode 26.2+ (toolchain Swift 6.2), sull'ultima versione di macOS disponibile in Software Update.
  • Node.js 24.15+ e pnpm per il Gateway, la CLI e gli script di pacchettizzazione. È supportato anche Node 22.22.3+.

1. Installare le dipendenze

bash
pnpm install

2. Compilare e pacchettizzare l'app

bash
./scripts/package-mac-app.sh

Genera dist/OpenClaw.app. Senza un certificato Apple Developer ID, lo script ricorre alla firma ad hoc.

Per le modalità di esecuzione per lo sviluppo, i flag di firma e la risoluzione dei problemi relativi al Team ID, consultare apps/macos/README.md. Ciclo di sviluppo rapido dalla radice del repository: scripts/restart-mac.sh (aggiungere --no-sign per la firma ad hoc; le autorizzazioni TCC non persistono con --no-sign).

3. Installare la CLI e il Gateway

L'app pacchettizzata incorpora il programma di installazione canonico scripts/install-cli.sh. In un profilo nuovo, scegliere This Mac durante la configurazione iniziale; l'app installa la CLI in spazio utente e il runtime corrispondenti prima di avviare la procedura guidata del Gateway.

Per il ripristino manuale dell'ambiente di sviluppo, installare autonomamente la CLI corrispondente:

bash
npm install -g openclaw@<version>

Sono supportati anche pnpm add -g openclaw@<version> e bun add -g openclaw@<version>. Node rimane il runtime consigliato per il Gateway stesso.

Risoluzione dei problemi

Compilazione non riuscita: toolchain o SDK non corrispondente

La compilazione dell'app per macOS richiede l'SDK macOS più recente e la toolchain Swift 6.2 (Xcode 26.2+).

bash
xcodebuild -versionxcrun swift --version

Se le versioni non corrispondono, aggiornare macOS/Xcode ed eseguire nuovamente la compilazione.

Arresto anomalo dell'app durante la concessione delle autorizzazioni

Se l'app si arresta in modo anomalo quando si tenta di consentire l'accesso a Speech Recognition o Microphone, la causa potrebbe essere una cache TCC danneggiata o una firma non corrispondente.

  1. Reimpostare le autorizzazioni TCC per l'ID bundle di debug:

    bash
    tccutil reset All ai.openclaw.mac.debug

  2. Se l'operazione non riesce, modificare temporaneamente BUNDLE_ID in scripts/package-mac-app.sh per forzare una configurazione pulita in macOS.

Gateway bloccato indefinitamente su "Starting..."

Verificare se un processo zombie occupa la porta:

bash
openclaw gateway statusopenclaw gateway stop # Se non si utilizza un LaunchAgent (modalità sviluppo / esecuzioni manuali), individuare il listener:lsof -nP -iTCP:18789 -sTCP:LISTEN

Se la porta è occupata da un'esecuzione manuale, arrestarla (Ctrl+C) oppure, come ultima risorsa, terminare il PID individuato sopra.

Risorse correlate

Was this useful?
On this page

On this page