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.

Questa è una guida per contributor per gli sviluppatori core di OpenClaw. Se stai creando un plugin esterno, consulta invece Creare plugin. Per il riferimento approfondito sull’architettura (modello delle capacità, proprietà, pipeline di caricamento, helper di runtime), consulta Interni dei plugin.
Usa questa guida quando OpenClaw ha bisogno di un nuovo dominio condiviso, come la generazione di immagini, la generazione di video o qualche futura area funzionale supportata da un fornitore. La regola:
  • plugin = confine di proprietà
  • capability = contratto core condiviso
Non iniziare collegando direttamente un fornitore a un canale o a uno strumento. Inizia definendo la capacità.

​
Quando creare una capacità

Crea una nuova capacità quando tutte queste condizioni sono vere:
  1. Più di un fornitore potrebbe plausibilmente implementarla.
  2. Canali, strumenti o plugin di funzionalità dovrebbero consumarla senza preoccuparsi del fornitore.
  3. Il core deve possedere fallback, policy, configurazione o comportamento di consegna.
Se il lavoro riguarda solo un fornitore e non esiste ancora un contratto condiviso, fermati e definisci prima il contratto.

​
La sequenza standard

  1. Definisci il contratto core tipizzato.
  2. Aggiungi la registrazione dei plugin per quel contratto.
  3. Aggiungi un helper di runtime condiviso.
  4. Collega un vero plugin di fornitore come prova.
  5. Sposta i consumer di funzionalità/canali sull’helper di runtime.
  6. Aggiungi test del contratto.
  7. Documenta la configurazione rivolta all’operatore e il modello di proprietà.

​
Cosa va dove

Core:
  • Tipi di richiesta/risposta.
  • Registro dei provider + risoluzione.
  • Comportamento di fallback.
  • Schema di configurazione con metadati documentali title / description propagati su nodi oggetto annidati, wildcard, elementi di array e composizione.
  • Superficie dell’helper di runtime.
Plugin del fornitore:
  • Chiamate API del fornitore.
  • Gestione dell’autenticazione del fornitore.
  • Normalizzazione delle richieste specifica del fornitore.
  • Registrazione dell’implementazione della capacità.
Plugin di funzionalità/canale:
  • Chiama api.runtime.* o l’helper corrispondente plugin-sdk/*-runtime.
  • Non chiama mai direttamente un’implementazione del fornitore.

​
Giunzioni di provider e harness

Usa gli hook del provider quando il comportamento appartiene al contratto del provider del modello invece che al ciclo agente generico. Gli esempi includono parametri di richiesta specifici del provider dopo la selezione del trasporto, preferenza del profilo di autenticazione, overlay dei prompt e instradamento di fallback di follow-up dopo failover di modello/profilo. Usa gli hook dell’harness dell’agente quando il comportamento appartiene al runtime che esegue un turno. Gli harness possono classificare risultati di tentativi riusciti ma inutilizzabili, come risposte vuote, solo di ragionamento o solo di pianificazione, così la policy di fallback del modello esterno può prendere la decisione di riprovare. Mantieni entrambe le giunzioni ristrette:
  • Il core possiede la policy di retry/fallback.
  • I plugin provider possiedono suggerimenti specifici del provider per richiesta/autenticazione/instradamento.
  • I plugin harness possiedono la classificazione dei tentativi specifica del runtime.
  • I plugin di terze parti restituiscono suggerimenti, non mutazioni dirette dello stato del core.

​
Checklist dei file

Per una nuova capacità, aspettati di toccare queste aree:
  • src/<capability>/types.ts
  • src/<capability>/...registry/runtime.ts
  • src/plugins/types.ts
  • src/plugins/registry.ts
  • src/plugins/captured-registration.ts
  • src/plugins/contracts/registry.ts
  • src/plugins/runtime/types-core.ts
  • src/plugins/runtime/index.ts
  • src/plugin-sdk/<capability>.ts
  • src/plugin-sdk/<capability>-runtime.ts
  • Uno o più pacchetti di plugin inclusi.
  • Configurazione, documentazione, test.

​
Esempio pratico: generazione di immagini

La generazione di immagini segue la forma standard:
  1. Il core definisce ImageGenerationProvider.
  2. Il core espone registerImageGenerationProvider(...).
  3. Il core espone runtime.imageGeneration.generate(...).
  4. I plugin openai, google, fal e minimax registrano implementazioni supportate da fornitori.
  5. I fornitori futuri registrano lo stesso contratto senza modificare canali/strumenti.
La chiave di configurazione è intenzionalmente separata dall’instradamento dell’analisi visiva:
  • agents.defaults.imageModel analizza immagini.
  • agents.defaults.imageGenerationModel genera immagini.
Mantienile separate affinché fallback e policy restino espliciti.

​
Checklist di revisione

Prima di distribuire una nuova capacità, verifica:
  • Nessun canale/strumento importa direttamente codice del fornitore.
  • L’helper di runtime è il percorso condiviso.
  • Almeno un test del contratto asserisce la proprietà inclusa.
  • La documentazione di configurazione nomina il nuovo modello/la nuova chiave di configurazione.
  • La documentazione dei plugin spiega il confine di proprietà.
Se una PR salta il livello della capacità e codifica direttamente il comportamento del fornitore in un canale/strumento, rimandala indietro e definisci prima il contratto.

​
Correlati