Prompt di sistema

OpenClaw crea un prompt di sistema personalizzato per ogni esecuzione dell'agente. Il prompt è di proprietà di OpenClaw e non usa un prompt predefinito di runtime.

Il prompt viene assemblato da OpenClaw e iniettato in ogni esecuzione dell'agente.

L'assemblaggio del prompt ha tre livelli:

• buildAgentSystemPrompt genera il prompt da input espliciti. Deve restare un renderer puro e non deve leggere direttamente la configurazione globale.
• resolveAgentSystemPromptConfig risolve le opzioni del prompt basate sulla configurazione, come visualizzazione del proprietario, suggerimenti TTS, alias dei modelli, modalità di citazione della memoria e modalità di delega dei sotto-agenti per un agente specifico.
• Gli adattatori di runtime (embedded, CLI, anteprime comando/esportazione, Compaction) raccolgono fatti live come strumenti, stato della sandbox, capacità del canale, file di contesto e contributi al prompt del provider, quindi chiamano la facade del prompt configurata.

Questo mantiene le superfici di prompt esportate/di debug allineate con le esecuzioni live senza trasformare ogni dettaglio specifico del runtime in un unico builder monolitico.

I Plugin provider possono contribuire con indicazioni per il prompt attente alla cache senza sostituire l'intero prompt di proprietà di OpenClaw. Il runtime del provider può:

• sostituire un piccolo insieme di sezioni core con nome (interaction_style, tool_call_style, execution_bias)
• iniettare un prefisso stabile sopra il limite della cache del prompt
• iniettare un suffisso dinamico sotto il limite della cache del prompt

Usa i contributi di proprietà del provider per la regolazione specifica della famiglia di modelli. Mantieni la mutazione legacy del prompt before_prompt_build per compatibilità o modifiche davvero globali del prompt, non per il normale comportamento del provider.

L'overlay della famiglia OpenAI GPT-5 mantiene piccola la regola di esecuzione core e aggiunge indicazioni specifiche del modello per aggancio della persona, output conciso, disciplina degli strumenti, ricerca parallela, copertura dei deliverable, verifica, contesto mancante e igiene degli strumenti da terminale.

Struttura

Il prompt è volutamente compatto e usa sezioni fisse:

• Strumenti: promemoria sulla fonte di verità degli strumenti strutturati più indicazioni runtime sull'uso degli strumenti.
• Bias di esecuzione: indicazioni compatte di completamento: agire nel turno sulle richieste azionabili, continuare finché completato o bloccato, recuperare da risultati deboli degli strumenti, controllare live lo stato mutabile e verificare prima di finalizzare.
• Sicurezza: breve promemoria di guardrail per evitare comportamenti di ricerca di potere o l'elusione della supervisione.
• Skills (quando disponibili): indica al modello come caricare le istruzioni delle skill su richiesta.
• Controllo OpenClaw: indica al modello di preferire lo strumento gateway per configurazione/riavvio e di evitare di inventare comandi CLI.
• Auto-aggiornamento OpenClaw: come ispezionare la configurazione in sicurezza con config.schema.lookup, applicare patch alla configurazione con config.patch, sostituire l'intera configurazione con config.apply ed eseguire update.run solo su richiesta esplicita dell'utente. Anche lo strumento gateway rivolto all'agente rifiuta di riscrivere tools.exec.ask / tools.exec.security, inclusi gli alias legacy tools.bash.* che si normalizzano in quei percorsi exec protetti.
• Workspace: directory di lavoro (agents.defaults.workspace).
• Documentazione: percorso locale alla documentazione/sorgente di OpenClaw e quando leggerla.
• File del workspace (iniettati): indica che i file bootstrap sono inclusi sotto.
• Sandbox (quando abilitata): indica runtime in sandbox, percorsi della sandbox e se è disponibile exec elevato.
• Data e ora correnti: solo fuso orario (stabile in cache; l'orologio live proviene da session_status).
• Direttive di output dell'assistente: sintassi compatta per allegati, note vocali e tag di risposta.
• Heartbeats: prompt Heartbeat e comportamento di ack, quando gli Heartbeat sono abilitati per l'agente predefinito.
• Runtime: host, OS, node, modello, radice del repo (quando rilevata), livello di ragionamento (una riga).
• Ragionamento: livello di visibilità corrente + suggerimento toggle /reasoning.

OpenClaw mantiene i contenuti stabili di grandi dimensioni, incluso Contesto del progetto, sopra il limite interno della cache del prompt. Le sezioni volatili di canale/sessione, come le indicazioni embed della Control UI, Messaggistica, Voce, Contesto chat di gruppo, Reazioni, Heartbeats e Runtime, vengono aggiunte sotto quel limite così i backend locali con cache di prefisso possono riutilizzare il prefisso stabile del workspace tra i turni del canale. Anche le descrizioni degli strumenti dovrebbero evitare di incorporare nomi di canale correnti quando lo schema accettato contiene già quel dettaglio di runtime.

La sezione Strumenti include anche indicazioni runtime per lavori di lunga durata:

• usa Cron per follow-up futuri (check back later, promemoria, lavoro ricorrente) invece di cicli sleep con exec, trucchi di ritardo yieldMs o polling ripetuto di process
• usa exec / process solo per comandi che iniziano ora e continuano a essere eseguiti in background
• quando il risveglio automatico al completamento è abilitato, avvia il comando una sola volta e affidati al percorso di risveglio push-based quando emette output o fallisce
• usa process per log, stato, input o intervento quando devi ispezionare un comando in esecuzione
• se l'attività è più grande, preferisci sessions_spawn; il completamento dei sotto-agenti è push-based e si auto-annuncia al richiedente
• non fare polling di subagents list / sessions_list in un ciclo solo per attendere il completamento

agents.defaults.subagents.delegationMode può rafforzare queste indicazioni. La modalità predefinita suggest mantiene il suggerimento di base. prefer aggiunge una sezione dedicata Delega ai sotto-agenti che indica all'agente principale di agire come coordinatore reattivo e inoltrare qualsiasi cosa più complessa di una risposta diretta tramite sessions_spawn. Questo riguarda solo il prompt; la policy degli strumenti controlla comunque se sessions_spawn è disponibile.

Quando lo strumento sperimentale update_plan è abilitato, Strumenti indica anche al modello di usarlo solo per lavoro multi-step non banale, mantenere esattamente un passaggio in_progress ed evitare di ripetere l'intero piano dopo ogni aggiornamento.

I guardrail di sicurezza nel prompt di sistema sono consultivi. Guidano il comportamento del modello ma non applicano policy. Usa policy degli strumenti, approvazioni exec, sandboxing e allowlist dei canali per l'applicazione rigida; gli operatori possono disabilitarli per progettazione.

Sui canali con schede/pulsanti di approvazione nativi, il prompt di runtime ora indica all'agente di affidarsi prima a quella UI di approvazione nativa. Deve includere un comando manuale /approve solo quando il risultato dello strumento dice che le approvazioni via chat non sono disponibili o che l'approvazione manuale è l'unico percorso.

Modalità del prompt

OpenClaw può generare prompt di sistema più piccoli per i sotto-agenti. Il runtime imposta un promptMode per ogni esecuzione (non una configurazione visibile all'utente):

• full (predefinita): include tutte le sezioni sopra.
• minimal: usata per i sotto-agenti; omette Richiamo memoria, Auto-aggiornamento OpenClaw, Alias dei modelli, Identità utente, Direttive di output dell'assistente, Messaggistica, Risposte silenziose e Heartbeats. Strumenti, Sicurezza, Skills quando fornite, Workspace, Sandbox, Data e ora correnti (quando note), Runtime e contesto iniettato restano disponibili.
• none: restituisce solo la riga di identità di base.

Quando promptMode=minimal, i prompt extra iniettati sono etichettati Contesto sotto-agente invece di Contesto chat di gruppo.

Per le esecuzioni di risposta automatica del canale, OpenClaw omette la sezione generica Risposte silenziose quando il contesto diretto, di gruppo o solo tramite strumento di messaggio possiede il contratto di risposta visibile. Solo la vecchia modalità automatica di gruppo/canale dovrebbe mostrare NO_REPLY; le chat dirette e le risposte solo tramite strumento di messaggio non ricevono indicazioni sul token silenzioso.

Snapshot del prompt

OpenClaw mantiene snapshot del prompt versionati per il percorso felice del runtime Codex sotto test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/. Generano parametri selezionati di thread/turno dell'app-server più uno stack di livelli prompt associato al modello ricostruito per turni diretti Telegram, gruppi Discord e Heartbeat. Quello stack include una fixture del prompt del modello Codex gpt-5.5 fissata generata dalla forma catalogo/cache dei modelli di Codex, il testo developer dei permessi del percorso felice Codex, le istruzioni developer di OpenClaw, le istruzioni collaboration-mode con ambito di turno quando OpenClaw le fornisce, l'input del turno utente e riferimenti alle specifiche dinamiche degli strumenti.

Aggiorna la fixture del prompt del modello Codex fissata con pnpm prompt:snapshots:sync-codex-model. Per impostazione predefinita, lo script cerca la cache runtime di Codex in $CODEX_HOME/models_cache.json, poi in ~/.codex/models_cache.json e solo dopo ripiega sulla convenzione del checkout Codex del maintainer in ~/code/codex/codex-rs/models-manager/models.json. Se nessuna di queste sorgenti esiste, il comando termina senza modificare la fixture versionata. Passa --catalog <path> per aggiornare da un file models_cache.json o models.json specifico.

Questi snapshot non sono ancora una cattura raw byte per byte della richiesta OpenAI. Codex può aggiungere contesto del workspace di proprietà del runtime, come AGENTS.md, contesto dell'ambiente, memorie, istruzioni di app/plugin e istruzioni collaboration-mode Default integrate dentro il runtime Codex dopo che OpenClaw invia i parametri di thread e turno.

Rigenerali con pnpm prompt:snapshots:gen e verifica la deriva con pnpm prompt:snapshots:check. La CI esegue il controllo della deriva nello shard boundary aggiuntivo così le modifiche al prompt e gli aggiornamenti degli snapshot restano collegati alla stessa PR.

Iniezione bootstrap del workspace

I file bootstrap vengono risolti dal workspace attivo, poi instradati alla superficie del prompt che corrisponde alla loro durata:

• AGENTS.md
• SOUL.md
• TOOLS.md
• IDENTITY.md
• USER.md
• HEARTBEAT.md
• BOOTSTRAP.md (solo su workspace nuovissimi)
• MEMORY.md quando presente

Sull'harness Codex nativo, OpenClaw evita di ripetere i file stabili del workspace in ogni turno utente. Codex carica AGENTS.md tramite la propria scoperta dei documenti di progetto. SOUL.md, IDENTITY.md, TOOLS.md e USER.md vengono inoltrati come istruzioni developer Codex. Anche l'elenco compatto delle Skills di OpenClaw viene inoltrato come istruzioni developer di collaborazione con ambito di turno. Il contenuto di HEARTBEAT.md non viene iniettato; i turni Heartbeat ricevono una nota collaboration-mode che punta al file quando esiste e non è vuoto. Il contenuto di MEMORY.md dal workspace dell'agente configurato non viene incollato in ogni turno Codex nativo; quando gli strumenti di memoria sono disponibili per quel workspace, i turni Codex ricevono una piccola nota sulla memoria del workspace nelle istruzioni developer di collaborazione con ambito di turno e dovrebbero usare memory_search o memory_get quando la memoria durevole è rilevante. Se gli strumenti sono disabilitati, la ricerca di memoria non è disponibile o il workspace attivo differisce dal workspace di memoria dell'agente, MEMORY.md ricade nel normale percorso di contesto del turno delimitato. Il contenuto attivo di BOOTSTRAP.md mantiene per ora il normale ruolo di contesto del turno.

Sugli harness non Codex, i file bootstrap continuano a essere composti nel prompt OpenClaw secondo i loro gate esistenti. HEARTBEAT.md viene omesso nelle esecuzioni normali quando gli Heartbeat sono disabilitati per l'agente predefinito o agents.defaults.heartbeat.includeSystemPromptSection è false. Mantieni concisi i file iniettati, specialmente MEMORY.md non Codex. MEMORY.md è pensato per restare un riepilogo curato a lungo termine; le note giornaliere dettagliate appartengono a memory/*.md, dove memory_search e memory_get possono recuperarle su richiesta. File MEMORY.md non Codex sovradimensionati aumentano l'uso del prompt e possono essere iniettati parzialmente a causa dei limiti dei file bootstrap sotto.

I file di grandi dimensioni vengono troncati con un marcatore. La dimensione massima per file è controllata da agents.defaults.bootstrapMaxChars (predefinito: 20000). Il contenuto bootstrap totale iniettato tra i file è limitato da agents.defaults.bootstrapTotalMaxChars (predefinito: 60000). I file mancanti iniettano un breve marcatore di file mancante. Quando si verifica il troncamento, OpenClaw può iniettare un avviso conciso nel prompt di sistema; controllalo con agents.defaults.bootstrapPromptTruncationWarning (off, once, always; predefinito: always). I conteggi grezzi/iniettati dettagliati restano nella diagnostica, ad esempio /context, /status, doctor e log.

Per i file di memoria, il troncamento non è perdita di dati: il file resta integro sul disco. Su Codex nativo, MEMORY.md viene letto su richiesta tramite gli strumenti di memoria quando disponibili, con fallback del prompt limitato quando gli strumenti non possono essere eseguiti. Sugli altri harness, il modello vede solo la copia iniettata abbreviata finché non legge o cerca direttamente nella memoria. Se MEMORY.md viene troncato ripetutamente lì, distillalo in un riepilogo durevole più breve e sposta la cronologia dettagliata in memory/*.md, oppure aumenta intenzionalmente i limiti di bootstrap.

Le sessioni dei sotto-agenti iniettano solo AGENTS.md e TOOLS.md (gli altri file di bootstrap vengono filtrati per mantenere piccolo il contesto del sotto-agente).

Gli hook interni possono intercettare questo passaggio tramite agent:bootstrap per modificare o sostituire i file di bootstrap iniettati (ad esempio sostituendo SOUL.md con una persona alternativa).

Se vuoi rendere il tono dell'agente meno generico, inizia da Guida alla personalità SOUL.md.

Per controllare quanto contribuisce ciascun file iniettato (grezzo rispetto a iniettato, troncamento, più overhead dello schema degli strumenti), usa /context list o /context detail. Vedi Contesto.

Gestione del tempo

Il prompt di sistema include una sezione dedicata Data e ora correnti quando il fuso orario dell'utente è noto. Per mantenere stabile la cache del prompt, ora include solo il fuso orario (nessun orologio dinamico o formato dell'ora).

Usa session_status quando l'agente ha bisogno dell'ora corrente; la scheda di stato include una riga con timestamp. Lo stesso strumento può facoltativamente impostare un override del modello per sessione (model=default lo cancella).

Configura con:

• agents.defaults.userTimezone
• agents.defaults.timeFormat (auto | 12 | 24)

Vedi Data e ora per i dettagli completi sul comportamento.

Skills

Quando esistono Skills idonee, OpenClaw inietta un elenco compatto di Skills disponibili (formatSkillsForPrompt) che include il percorso del file e il marcatore <version> derivato dal contenuto per ciascuna skill. Il prompt istruisce il modello a usare read per caricare il file SKILL.md nella posizione elencata (workspace, gestita o incorporata), e a rileggere una skill quando il suo <version> differisce da un turno precedente. Se nessuna Skills è idonea, la sezione Skills viene omessa.

I turni di Codex nativo ricevono questo elenco come istruzioni developer di collaborazione con ambito di turno invece che come input utente per turno, eccetto i turni cron leggeri che preservano esattamente il prompt pianificato. Gli altri harness mantengono la normale sezione del prompt.

La posizione può puntare a una skill annidata, ad esempio skills/personal/foo/SKILL.md. L'annidamento è solo organizzativo; il prompt usa comunque il nome piatto della skill dal frontmatter di SKILL.md.

L'idoneità include gate dei metadati della skill, controlli di ambiente/configurazione runtime, e l'allowlist effettiva delle Skills dell'agente quando agents.defaults.skills o agents.list[].skills è configurato.

Le Skills incorporate nei Plugin sono idonee solo quando il Plugin proprietario è abilitato. Questo consente ai Plugin di strumenti di esporre guide operative più approfondite senza incorporare tutta quella guida direttamente in ogni descrizione dello strumento.

<available_skills>  <skill>    <name>...</name>    <description>...</description>    <location>...</location>    <version>sha256:...</version>  </skill></available_skills>

Questo mantiene piccolo il prompt di base pur abilitando l'uso mirato delle Skills.

Il budget dell'elenco Skills è di proprietà del sottosistema Skills:

• Predefinito globale: skills.limits.maxSkillsPromptChars
• Override per agente: agents.list[].skillsLimits.maxSkillsPromptChars

Gli estratti runtime generici limitati usano una superficie diversa:

• agents.defaults.contextLimits.*
• agents.list[].contextLimits.*

Questa separazione mantiene il dimensionamento delle Skills distinto dal dimensionamento di lettura/iniezione runtime, ad esempio memory_get, risultati degli strumenti live e aggiornamenti di AGENTS.md dopo la Compaction.

Documentazione

Il prompt di sistema include una sezione Documentazione. Quando la documentazione locale è disponibile, punta alla directory locale della documentazione di OpenClaw (docs/ in un checkout Git o la documentazione del pacchetto npm incorporata). Se la documentazione locale non è disponibile, passa a https://docs.openclaw.ai.

La stessa sezione include anche la posizione del sorgente OpenClaw. I checkout Git espongono la radice sorgente locale così l'agente può ispezionare direttamente il codice. Le installazioni da pacchetto includono l'URL sorgente GitHub e indicano all'agente di esaminare il sorgente lì ogni volta che la documentazione è incompleta o obsoleta. Il prompt segnala anche il mirror pubblico della documentazione, il Discord della community e ClawHub (https://clawhub.ai) per la scoperta delle Skills. Presenta la documentazione come autorità per l'autoconoscenza di OpenClaw prima che il modello comprenda come funziona OpenClaw, incluse memoria/note giornaliere, sessioni, strumenti, Gateway, configurazione, comandi o contesto di progetto. Il prompt indica al modello di usare prima la documentazione locale (o il mirror della documentazione quando la documentazione locale non è disponibile), e di trattare AGENTS.md, contesto di progetto, note di workspace/profilo/memoria e memory_search come contesto di istruzioni o memoria utente piuttosto che come conoscenza di progettazione o implementazione di OpenClaw. Se la documentazione tace o è obsoleta, il modello dovrebbe dirlo e ispezionare il sorgente. Il prompt indica anche al modello di eseguire autonomamente openclaw status quando possibile, chiedendo all'utente solo quando non ha accesso. Per la configurazione in particolare, indirizza gli agenti all'azione dello strumento gateway config.schema.lookup per documentazione e vincoli esatti a livello di campo, poi a docs/gateway/configuration.md e docs/gateway/configuration-reference.md per indicazioni più ampie.

Correlati

• Runtime dell'agente
• Workspace dell'agente
• Motore di contesto