Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Installa OpenClaw in modo dichiarativo con nix-openclaw, il modulo Home Manager ufficiale con tutto incluso.
Il repo nix-openclaw è la fonte autorevole per l’installazione con Nix. Questa pagina è una panoramica rapida.

​
Cosa ottieni

  • Gateway + app macOS + strumenti (whisper, spotify, cameras) — tutti bloccati a versioni specifiche
  • Servizio launchd che sopravvive ai riavvii
  • Sistema Plugin con configurazione dichiarativa
  • Rollback immediato: home-manager switch --rollback

​
Avvio rapido

1

Installa Determinate Nix

Se Nix non è già installato, segui le istruzioni del programma di installazione Determinate Nix.
2

Crea una flake locale

Usa il template agent-first dal repo nix-openclaw:
mkdir -p ~/code/openclaw-local
# Copy templates/agent-first/flake.nix from the nix-openclaw repo
3

Configura i segreti

Configura il token del tuo bot di messaggistica e la chiave API del provider di modelli. I file di testo semplice in ~/.secrets/ vanno benissimo.
4

Compila i segnaposto del template ed esegui lo switch

home-manager switch
5

Verifica

Conferma che il servizio launchd sia in esecuzione e che il tuo bot risponda ai messaggi.
Consulta il README di nix-openclaw per le opzioni complete del modulo e gli esempi.

​
Comportamento runtime in modalità Nix

Quando OPENCLAW_NIX_MODE=1 è impostato (automatico con nix-openclaw), OpenClaw entra in una modalità deterministica per le installazioni gestite da Nix. Anche altri pacchetti Nix possono impostare la stessa modalità; nix-openclaw è il riferimento ufficiale. Puoi anche impostarlo manualmente: 
export OPENCLAW_NIX_MODE=1
Su macOS, l’app GUI non eredita automaticamente le variabili d’ambiente della shell. Abilita invece la modalità Nix tramite defaults: 
defaults write ai.openclaw.mac openclaw.nixMode -bool true

​
Cosa cambia in modalità Nix

  • I flussi di installazione automatica e auto-mutazione sono disabilitati
  • openclaw.json è trattato come immutabile. I valori predefiniti derivati dall’avvio restano solo runtime, e gli strumenti che scrivono la configurazione, come setup, onboarding, openclaw update mutante, installazione/aggiornamento/disinstallazione/abilitazione di Plugin, doctor --fix, doctor --generate-gateway-token e openclaw config set, rifiutano di modificare il file.
  • Gli agenti dovrebbero invece modificare la sorgente Nix. Per nix-openclaw, usa l’Avvio rapido agent-first e imposta la configurazione sotto programs.openclaw.config o instances.<name>.config.
  • Le dipendenze mancanti mostrano messaggi di correzione specifici per Nix
  • L’interfaccia utente mostra un banner di modalità Nix in sola lettura

​
Percorsi di configurazione e stato

OpenClaw legge la configurazione JSON5 da OPENCLAW_CONFIG_PATH e archivia i dati mutabili in OPENCLAW_STATE_DIR. Quando è in esecuzione sotto Nix, impostali esplicitamente su posizioni gestite da Nix, così lo stato runtime e la configurazione restano fuori dallo store immutabile.
VariabilePredefinito
OPENCLAW_HOMEHOME / USERPROFILE / os.homedir()
OPENCLAW_STATE_DIR~/.openclaw
OPENCLAW_CONFIG_PATH$OPENCLAW_STATE_DIR/openclaw.json

​
Rilevamento del PATH del servizio

Il servizio Gateway launchd/systemd rileva automaticamente i binari del profilo Nix, così i Plugin e gli strumenti che eseguono comandi shell verso eseguibili installati con nix funzionano senza configurazione manuale del PATH:
  • Quando NIX_PROFILES è impostato, ogni voce viene aggiunta al PATH del servizio con precedenza da destra a sinistra (corrisponde alla precedenza della shell Nix: vince la voce più a destra).
  • Quando NIX_PROFILES non è impostato, ~/.nix-profile/bin viene aggiunto come fallback.
Questo si applica sia agli ambienti di servizio launchd su macOS sia a quelli systemd su Linux.

​
Correlati

nix-openclaw

Modulo Home Manager fonte autorevole e guida completa alla configurazione.

Procedura guidata di configurazione

Procedura dettagliata di configurazione CLI non Nix.

Docker

Configurazione containerizzata come alternativa non Nix.

Aggiornamento

Aggiornamento delle installazioni gestite da Home Manager insieme al pacchetto.