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.

Lo workspace è la casa dell’agente. È l’unica directory di lavoro usata per gli strumenti sui file e per il contesto dello workspace. Mantienilo privato e trattalo come memoria. Questo è separato da ~/.openclaw/, che archivia configurazione, credenziali e sessioni.
Lo workspace è la cwd predefinita, non una sandbox rigida. Gli strumenti risolvono i percorsi relativi rispetto allo workspace, ma i percorsi assoluti possono comunque raggiungere altre posizioni sull’host, a meno che la sandbox non sia abilitata. Se ti serve isolamento, usa agents.defaults.sandbox (e/o la configurazione sandbox per agente).Quando la sandbox è abilitata e workspaceAccess non è "rw", gli strumenti operano dentro uno workspace sandbox sotto ~/.openclaw/sandboxes, non nel tuo workspace host.

​
Posizione predefinita

  • Predefinita: ~/.openclaw/workspace
  • Se OPENCLAW_PROFILE è impostato e non è "default", il valore predefinito diventa ~/.openclaw/workspace-<profile>.
  • Sovrascrivi in ~/.openclaw/openclaw.json:
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}
openclaw onboard, openclaw configure o openclaw setup creeranno lo workspace e inizializzeranno i file bootstrap se mancano.
Le copie seed della sandbox accettano solo normali file interni allo workspace; gli alias symlink/hardlink che si risolvono fuori dallo workspace sorgente vengono ignorati.
Se gestisci già autonomamente i file dello workspace, puoi disabilitare la creazione dei file bootstrap: 
{ agents: { defaults: { skipBootstrap: true } } }

​
Cartelle workspace aggiuntive

Le installazioni più vecchie potrebbero aver creato ~/openclaw. Tenere più directory workspace può causare confusione con autenticazione o deriva dello stato, perché solo uno workspace è attivo alla volta.
Raccomandazione: mantieni un solo workspace attivo. Se non usi più le cartelle aggiuntive, archiviale o spostale nel Cestino (per esempio trash ~/openclaw). Se mantieni intenzionalmente più workspace, assicurati che agents.defaults.workspace punti a quello attivo.openclaw doctor avvisa quando rileva directory workspace aggiuntive.

​
Mappa dei file dello workspace

Questi sono i file standard che OpenClaw si aspetta dentro lo workspace:
Istruzioni operative per l’agente e su come dovrebbe usare la memoria. Caricate all’inizio di ogni sessione. Buon posto per regole, priorità e dettagli su “come comportarsi”.
Persona, tono e limiti. Caricato a ogni sessione. Guida: guida alla personalità SOUL.md.
Chi è l’utente e come rivolgersi a lui. Caricato a ogni sessione.
Nome, stile ed emoji dell’agente. Creato/aggiornato durante il rituale di bootstrap.
Note sui tuoi strumenti locali e sulle convenzioni. Non controlla la disponibilità degli strumenti; è solo una guida.
Piccola checklist opzionale per le esecuzioni Heartbeat. Mantienila breve per evitare consumo di token.
Checklist di avvio opzionale eseguita automaticamente al riavvio del Gateway (quando gli hook interni sono abilitati). Mantienila breve; usa lo strumento messaggio per gli invii in uscita.
Rituale una tantum della prima esecuzione. Creato solo per uno workspace completamente nuovo. Eliminalo dopo il completamento del rituale.
Registro giornaliero della memoria (un file al giorno). Consigliato leggere oggi + ieri all’avvio della sessione.
Memoria a lungo termine curata: fatti durevoli, preferenze, decisioni e brevi riepiloghi. Mantieni i log dettagliati in memory/YYYY-MM-DD.md così gli strumenti di memoria possono recuperarli su richiesta senza iniettarli in ogni prompt. Carica MEMORY.md solo nella sessione principale e privata (non in contesti condivisi/di gruppo). Vedi Memoria per il workflow e lo svuotamento automatico della memoria.
Skills specifiche dello workspace. Posizione delle Skills con precedenza massima per quello workspace. Sovrascrive le Skills dell’agente di progetto, le Skills personali dell’agente, le Skills gestite, le Skills incluse e skills.load.extraDirs quando i nomi coincidono.
File dell’interfaccia Canvas per le visualizzazioni dei nodi (per esempio canvas/index.html).
Se manca un file bootstrap, OpenClaw inietta un marcatore “file mancante” nella sessione e continua. I file bootstrap grandi vengono troncati quando vengono iniettati; regola i limiti con agents.defaults.bootstrapMaxChars (predefinito: 12000) e agents.defaults.bootstrapTotalMaxChars (predefinito: 60000). openclaw setup può ricreare i valori predefiniti mancanti senza sovrascrivere i file esistenti.

​
Cosa NON si trova nello workspace

Questi elementi risiedono sotto ~/.openclaw/ e NON dovrebbero essere sottoposti a commit nel repo dello workspace:
  • ~/.openclaw/openclaw.json (configurazione)
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (profili di autenticazione del modello: OAuth + chiavi API)
  • ~/.openclaw/agents/<agentId>/agent/codex-home/ (account runtime Codex per agente, configurazione, Skills, plugin e stato nativo del thread)
  • ~/.openclaw/credentials/ (stato di canali/provider più dati legacy di importazione OAuth)
  • ~/.openclaw/agents/<agentId>/sessions/ (trascrizioni di sessione + metadati)
  • ~/.openclaw/skills/ (Skills gestite)
Se devi migrare sessioni o configurazione, copiale separatamente e tienile fuori dal controllo versione.

​
Backup Git (consigliato, privato)

Tratta lo workspace come memoria privata. Inseriscilo in un repo git privato così viene salvato e può essere recuperato. Esegui questi passaggi sulla macchina dove gira il Gateway (cioè dove risiede lo workspace).
1

Inizializza il repo

Se git è installato, gli workspace completamente nuovi vengono inizializzati automaticamente. Se questo workspace non è già un repo, esegui:
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"
2

Aggiungi un remote privato

  1. Crea un nuovo repository privato su GitHub.
  2. Non inizializzarlo con un README (evita conflitti di merge).
  3. Copia l’URL remote HTTPS.
  4. Aggiungi il remote ed esegui il push:
git branch -M main
git remote add origin <https-url>
git push -u origin main
3

Aggiornamenti continui

git status
git add .
git commit -m "Update memory"
git push

​
Non committare segreti

Anche in un repo privato, evita di archiviare segreti nello workspace:
  • Chiavi API, token OAuth, password o credenziali private.
  • Qualsiasi cosa sotto ~/.openclaw/.
  • Dump grezzi di chat o allegati sensibili.
Se devi archiviare riferimenti sensibili, usa placeholder e conserva il vero segreto altrove (gestore di password, variabili d’ambiente o ~/.openclaw/).
Starter .gitignore suggerito: 
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

​
Spostare lo workspace su una nuova macchina

1

Clona il repo

Clona il repo nel percorso desiderato (predefinito ~/.openclaw/workspace).
2

Aggiorna la configurazione

Imposta agents.defaults.workspace su quel percorso in ~/.openclaw/openclaw.json.
3

Inizializza i file mancanti

Esegui openclaw setup --workspace <path> per inizializzare eventuali file mancanti.
4

Copia le sessioni (opzionale)

Se ti servono le sessioni, copia separatamente ~/.openclaw/agents/<agentId>/sessions/ dalla vecchia macchina.

​
Note avanzate

  • Il routing multi-agente può usare workspace diversi per agente. Vedi routing dei canali per la configurazione del routing.
  • Se agents.defaults.sandbox è abilitato, le sessioni non principali possono usare workspace sandbox per sessione sotto agents.defaults.sandbox.workspaceRoot.

​
Correlati