English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Fundamentals

Area di lavoro dell'agente

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.

Posizione predefinita

  • Predefinita: ~/.openclaw/workspace
  • Se OPENCLAW_PROFILE è impostato e non è "default", il valore predefinito diventa ~/.openclaw/workspace-<profile>.
  • Sovrascrivi in ~/.openclaw/openclaw.json:
json5
{  agents: {    defaults: {      workspace: "~/.openclaw/workspace",    },  },}

openclaw onboard, openclaw configure o openclaw setup creeranno lo workspace e inizializzeranno i file bootstrap se mancano.

Se gestisci già autonomamente i file dello workspace, puoi disabilitare la creazione dei file bootstrap:

json5
{ 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.

Mappa dei file dello workspace

Questi sono i file standard che OpenClaw si aspetta dentro lo workspace:

AGENTS.md - istruzioni operative

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".

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

Nome, stile ed 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 opzionale per le esecuzioni Heartbeat. Mantienila breve per evitare consumo di token.

BOOT.md - checklist di avvio

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.

BOOTSTRAP.md - rituale della prima esecuzione

Rituale una tantum della prima esecuzione. Creato solo per uno workspace completamente nuovo. Eliminalo dopo il completamento del rituale.

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

Registro giornaliero della memoria (un file al giorno). Consigliato leggere oggi + ieri all'avvio della sessione.

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

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/ - Skills dello workspace (opzionale)

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.

canvas/ - file dell'interfaccia Canvas (opzionale)

File dell'interfaccia Canvas per le visualizzazioni dei nodi (per esempio canvas/index.html).

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).

  • Inizializza il repo

    Se git è installato, gli workspace completamente nuovi vengono inizializzati automaticamente. Se questo workspace non è già un repo, esegui:

    bash
    cd ~/.openclaw/workspacegit initgit add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/git commit -m "Add agent workspace"

  • Aggiungi un remote privato

    Interfaccia web GitHub

    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:
    bash
    git branch -M maingit remote add origin <https-url>git push -u origin main

    GitHub CLI (gh)

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

    Interfaccia web GitLab

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

  • Aggiornamenti continui

    bash
    git statusgit add .git commit -m "Update memory"git push

    • Non committare segreti

    Starter .gitignore suggerito:

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

    Spostare lo workspace su una nuova macchina

  • Clona il repo

    Clona il repo 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 (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

    Was this useful?