Area di lavoro dell'agente

L’area di lavoro è la home dell’agente. È l’unica directory di lavoro usata per gli strumenti sui file e per il contesto dell’area di lavoro. Mantienila privata e trattala come memoria. È separata da ~/.openclaw/, che archivia configurazione, credenziali e sessioni.

L’area di lavoro è la cwd predefinita, non una sandbox rigida. Gli strumenti risolvono i percorsi relativi rispetto all’area di lavoro, ma i percorsi assoluti possono comunque raggiungere altre posizioni sull’host, a meno che la sandbox non sia abilitata. Se hai bisogno di isolamento, usa agents.defaults.sandbox (e/o la configurazione sandbox per agente).Quando la sandbox è abilitata e workspaceAccess non è "rw", gli strumenti operano dentro un’area di lavoro sandbox in ~/.openclaw/sandboxes, non nella tua area di lavoro 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 l’area di lavoro e inizializzeranno i file di bootstrap se mancano.

Le copie seed della sandbox accettano solo file regolari interni all’area di lavoro; gli alias symlink/hardlink che si risolvono fuori dall’area di lavoro sorgente vengono ignorati.

Se gestisci già autonomamente i file dell’area di lavoro, puoi disabilitare la creazione dei file di bootstrap:

{ agents: { defaults: { skipBootstrap: true } } }

Cartelle aggiuntive dell’area di lavoro

Installazioni meno recenti potrebbero aver creato ~/openclaw. Mantenere più directory di area di lavoro può causare confusione nell’autenticazione o deriva dello stato, perché solo una area di lavoro è attiva alla volta.

Consiglio: mantieni una sola area di lavoro attiva. Se non usi più le cartelle aggiuntive, archiviale o spostale nel Cestino (per esempio trash ~/openclaw). Se mantieni intenzionalmente più aree di lavoro, assicurati che agents.defaults.workspace punti a quella attiva.openclaw doctor avvisa quando rileva directory di area di lavoro aggiuntive.

Mappa dei file dell’area di lavoro

Questi sono i file standard che OpenClaw si aspetta dentro l’area di lavoro:

AGENTS.md - istruzioni operative

Istruzioni operative per l’agente e per come deve usare la memoria. Caricate all’inizio di ogni sessione. Un buon posto per regole, priorità e dettagli su “come comportarsi”.

SOUL.md - persona e tono

Persona, tono e limiti. Caricato a ogni sessione. Guida: guida alla personalità SOUL.md.

USER.md - chi è l'utente

Chi è l’utente e come rivolgersi a lui. Caricato a ogni sessione.

IDENTITY.md - nome, stile, emoji

Il nome, lo stile e l’emoji dell’agente. Creato/aggiornato durante il rituale di bootstrap.

TOOLS.md - convenzioni degli strumenti locali

Note sui tuoi strumenti locali e sulle convenzioni. Non controlla la disponibilità degli strumenti; è solo una guida.

HEARTBEAT.md - checklist heartbeat

Piccola checklist facoltativa per le esecuzioni Heartbeat. Tienila breve per evitare consumo di token.

BOOT.md - checklist di avvio

Checklist di avvio facoltativa eseguita automaticamente al riavvio del Gateway (quando gli hook interni sono abilitati). Tienila breve; usa lo strumento messaggi per gli invii in uscita.

BOOTSTRAP.md - rituale di primo avvio

Rituale di primo avvio una tantum. Creato solo per una area di lavoro completamente nuova. Eliminalo dopo il completamento del rituale.

memory/YYYY-MM-DD.md - registro giornaliero della memoria

Registro giornaliero della memoria (un file al giorno). Si consiglia di leggere oggi + ieri all’avvio della sessione.

MEMORY.md - memoria a lungo termine curata (facoltativa)

Memoria a lungo termine curata: fatti durevoli, preferenze, decisioni e brevi riepiloghi. Tieni i log dettagliati in memory/YYYY-MM-DD.md così gli strumenti di memoria possono recuperarli su richiesta senza inserirli in ogni prompt. Carica MEMORY.md solo nella sessione principale e privata (non nei contesti condivisi/di gruppo). Vedi Memoria per il flusso di lavoro e il flush automatico della memoria.

skills/ - Skills dell'area di lavoro (facoltative)

Skills specifiche dell’area di lavoro. Posizione delle skill con precedenza più alta per quell’area di lavoro. Sovrascrive le skill dell’agente di progetto, le skill personali dell’agente, le skill gestite, le skill in bundle e skills.load.extraDirs quando i nomi coincidono.

canvas/ - file della UI Canvas (facoltativi)

File della UI Canvas per le visualizzazioni dei nodi (per esempio canvas/index.html).

Se manca un file di bootstrap, OpenClaw inserisce un marcatore “file mancante” nella sessione e continua. I file di bootstrap grandi vengono troncati quando inseriti; regola i limiti con agents.defaults.bootstrapMaxChars (predefinito: 20000) e agents.defaults.bootstrapTotalMaxChars (predefinito: 60000). openclaw setup può ricreare i valori predefiniti mancanti senza sovrascrivere i file esistenti.

Cosa NON è nell’area di lavoro

Questi elementi si trovano sotto ~/.openclaw/ e NON devono essere committati nel repository dell’area di lavoro:

~/.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, skill, plugin e stato dei thread nativo)
~/.openclaw/credentials/ (stato di canali/provider più dati di importazione OAuth legacy)
~/.openclaw/agents/<agentId>/sessions/ (trascrizioni di sessione + metadati)
~/.openclaw/skills/ (skill gestite)

Se devi migrare sessioni o configurazione, copiale separatamente e tienile fuori dal controllo versione.

Backup Git (consigliato, privato)

Tratta l’area di lavoro come memoria privata. Inseriscila in un repository git privato così viene sottoposta a backup ed è recuperabile. Esegui questi passaggi sulla macchina in cui gira il Gateway (cioè dove si trova l’area di lavoro).

Inizializza il repository

Se git è installato, le aree di lavoro appena create vengono inizializzate automaticamente. Se questa area di lavoro non è già un repository, 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"

Aggiungi un remote privato

UI web GitHub
GitHub CLI (gh)
UI web GitLab

Crea un nuovo repository privato su GitHub.
Non inizializzarlo con un README (evita conflitti di merge).
Copia l’URL remote HTTPS.
Aggiungi il remote ed esegui il push:

git branch -M main
git remote add origin <https-url>
git push -u origin main

gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push

Crea un nuovo repository privato su GitLab.
Non inizializzarlo con un README (evita conflitti di merge).
Copia l’URL remote HTTPS.
Aggiungi il remote ed esegui il push:

git branch -M main
git remote add origin <https-url>
git push -u origin main

Aggiornamenti continui

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

Non committare segreti

Anche in un repository privato, evita di archiviare segreti nell’area di lavoro:

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 segnaposto e conserva il segreto reale altrove (gestore password, variabili d’ambiente o ~/.openclaw/).

Starter .gitignore suggerito:

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

Spostare l’area di lavoro su una nuova macchina

Clona il repository

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

Aggiorna la configurazione

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

Inizializza i file mancanti

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

Copia le sessioni (facoltativo)

Se hai bisogno delle sessioni, copia separatamente ~/.openclaw/agents/<agentId>/sessions/ dalla vecchia macchina.

Note avanzate

Il routing multi-agente può usare aree di lavoro diverse per agente. Vedi Routing dei canali per la configurazione del routing.
Se agents.defaults.sandbox è abilitato, le sessioni non principali possono usare aree di lavoro sandbox per sessione sotto agents.defaults.sandbox.workspaceRoot.

Correlati

Heartbeat - file dell’area di lavoro HEARTBEAT.md
Sandboxing - accesso all’area di lavoro in ambienti sandbox
Sessione - percorsi di archiviazione delle sessioni
Ordini permanenti - istruzioni persistenti nei file dell’area di lavoro

Fundamentals

Sessions and memory

Multi-agent

Messages and delivery

Area di lavoro dell'agente

Posizione predefinita

Cartelle aggiuntive dell’area di lavoro

Mappa dei file dell’area di lavoro

Cosa NON è nell’area di lavoro

Backup Git (consigliato, privato)

Non committare segreti

Spostare l’area di lavoro su una nuova macchina

Note avanzate

Correlati

​Posizione predefinita

​Cartelle aggiuntive dell’area di lavoro

​Mappa dei file dell’area di lavoro

​Cosa NON è nell’area di lavoro

​Backup Git (consigliato, privato)

​Non committare segreti

​Spostare l’area di lavoro su una nuova macchina

​Note avanzate

​Correlati

Posizione predefinita

Cartelle aggiuntive dell’area di lavoro

Mappa dei file dell’area di lavoro

Cosa NON è nell’area di lavoro

Backup Git (consigliato, privato)

Non committare segreti

Spostare l’area di lavoro su una nuova macchina

Note avanzate

Correlati