Quando usare un harness
Registrare un agent harness quando una famiglia di modelli dispone di un proprio runtime di sessione nativo e il normale trasporto del provider OpenClaw costituisce l’astrazione errata:- un server nativo per agenti di coding che gestisce thread e Compaction
- una CLI locale o un daemon che deve trasmettere in streaming eventi nativi di pianificazione/ragionamento/strumenti
- un runtime di modello che necessita di un proprio ID di ripresa oltre alla trascrizione della sessione OpenClaw
Cosa rimane sotto il controllo del core
Prima che venga selezionato un harness, OpenClaw ha già risolto:- provider e modello
- stato di autenticazione del runtime, salvo che l’harness dichiari di gestire il bootstrap dell’autenticazione
- livello di ragionamento e budget del contesto
- file di trascrizione/sessione OpenClaw
- area di lavoro, sandbox e criteri degli strumenti
- callback delle risposte del canale e callback di streaming
- criteri di fallback e cambio dinamico del modello
Bootstrap dell’autenticazione gestito dall’harness
Per impostazione predefinita, il core risolve le credenziali del provider prima di chiamare un harness. Un harness attendibile in grado di autenticarsi tramite il proprio runtime nativo può impostareauthBootstrap: "harness" nella propria registrazione statica AgentHarness. Il core quindi
ignora il bootstrap generico delle credenziali del provider e l’errore per credenziali mancanti
per ogni tentativo rivendicato da tale harness.
Il core inoltra comunque un profilo di autenticazione OpenClaw compatibile, selezionato
esplicitamente o ordinato, e il relativo archivio con ambito limitato, quando disponibili. L’harness deve risolvere
tale profilo o le proprie credenziali native prima di inviare richieste al modello, mantenere i segreti
limitati al tentativo e segnalare errori di autenticazione sui quali sia possibile intervenire. Non
impostare questa funzionalità su un harness che gestisce l’autenticazione solo in alcuni casi.
Artefatti verificati del runtime di configurazione
Un harness locale in grado di fornire inferenza per la configurazione iniziale deve attestare l’implementazione che ha completato il probe. Quandoparams.captureRuntimeArtifact è true, restituire un
result.runtimeArtifact opaco con un ID stabile e un’impronta digitale del contenuto. Registrare una
funzionalità runtimeArtifact.validate(...) corrispondente che verifichi nuovamente tale associazione
senza caricare un harness diverso o analizzare plugin non correlati.
Le continuazioni OpenClaw verificate trasmettono anche params.expectedRuntimeArtifact.
L’harness deve confrontarlo con l’esatto processo nativo acquisito e generare un errore
prima di avviare o riprendere un thread nativo se differiscono. I normali turni dell’agente
omettono entrambi i campi, quindi l’hashing del contenuto rimane escluso dal normale percorso critico
della richiesta. Gli harness remoti/WebSocket necessitano di un contratto di attestazione del server prima
di poter partecipare; una sola stringa di versione non costituisce l’identità di un artefatto.
Il tentativo preparato include anche params.runtimePlan, un pacchetto di criteri
gestito da OpenClaw per le decisioni del runtime che devono rimanere condivise tra OpenClaw e
gli harness nativi:
runtimePlan.tools.normalize(...)eruntimePlan.tools.logDiagnostics(...)per i criteri dello schema degli strumenti sensibili al providerruntimePlan.transcript.resolvePolicy(...)per la sanitizzazione della trascrizione e i criteri di riparazione delle chiamate agli strumentiruntimePlan.delivery.isSilentPayload(...)perNO_REPLYcondiviso e la soppressione della consegna dei contenuti multimedialiruntimePlan.outcome.classifyRunResult(...)per la classificazione del fallback del modelloruntimePlan.observabilityper i metadati risolti di provider/modello/harness
Contratto del trasporto delle richieste
supports(ctx) riceve il trasporto del modello risolto in ctx.modelProvider.
Due informazioni prive di segreti e gestite dal provider descrivono il percorso selezionato:
runtimePolicy.compatibleIdselenca gli ID di runtime che il provider dichiara compatibili con quello specifico percorso. L’assenza di criteri indica che il provider non ha dichiarato la compatibilità a livello di percorso; non autorizza a presupporre il supporto.requestTransportOverrides: "none"indica che non deve essere riprodotta alcuna sostituzione personalizzata della richiesta del provider/modello."present"indica che sono presenti intestazioni personalizzate, trasporto dell’autenticazione, proxy, TLS, comportamento del servizio locale o della rete privata oppure parametri della richiesta. Questa informazione non espone tali valori.
{ supported: false, reason } quando l’harness non può riprodurre il
trasporto preparato. Non dedurre il supporto leggendo la configurazione non elaborata dopo la selezione.
Quando la preparazione dell’autenticazione produce più percorsi di nuovo tentativo, un singolo harness deve supportarli
tutti prima dell’invio. La selezione implicita usa OpenClaw se nessun plugin può
gestire l’intero insieme; una selezione esplicita o persistente del plugin genera un errore in modo restrittivo.
Registrare un harness
Importazione:openclaw/plugin-sdk/agent-harness
authBootstrap è intenzionalmente assente da questo esempio generico. Aggiungere
authBootstrap: "harness" solo quando l’harness soddisfa il contratto precedente.
Esecuzione delegata
Il proprietario di un harness può impostaredelegatedExecutionPluginIds sugli ID dei plugin
attendibili che devono eseguire una sessione esistente vincolata al modello, ad esempio un trasporto
vocale che continua una conversazione basata su Codex. Si tratta del consenso statico del proprietario,
non di un elenco di autorizzazioni del core. Mantenerlo circoscritto.
I delegati ricevono soltanto l’ammissione del lavoro e l’esecuzione incorporata. OpenClaw richiede
l’esatta chiave di sessione archiviata, il percorso dell’archivio e l’ID della sessione; modelSelectionLocked: true; e valori agentHarnessId e agentHarnessRuntimeOverride corrispondenti.
L’esecuzione viene quindi circoscritta tramite il proprietario dell’harness. La creazione, la modifica,
la reimpostazione, l’eliminazione e l’archiviazione delle sessioni, nonché le modifiche al Gateway, rimangono riservate al proprietario.
Criteri di selezione
OpenClaw sceglie un harness dopo la risoluzione di provider/modello:- I criteri di runtime con ambito di modello hanno la precedenza.
- Seguono i criteri di runtime con ambito di provider.
autochiede agli harness registrati se supportano il percorso effettivo risolto. I soli prefissi di provider/modello non selezionano mai un harness.- Se nessun harness registrato corrisponde, OpenClaw usa il proprio runtime incorporato.
auto, il
fallback incorporato si applica solo quando nessun harness di plugin registrato supporta il
provider/modello risolto. Dopo che un harness di plugin ha rivendicato un’esecuzione, OpenClaw non
riproduce lo stesso turno tramite un altro runtime, poiché ciò può modificare
la semantica di autenticazione/runtime o duplicare gli effetti collaterali.
I criteri di runtime configurati rimangono determinanti per il runtime desiderato. Un
agentHarnessId di sessione persistente mantiene la proprietà della propria trascrizione nativa
mentre la preparazione del percorso/autenticazione è ancora in corso. Nessuno dei due rende compatibile un
percorso incompatibile: quando sono disponibili le informazioni preparate, l’harness selezionato o fissato
deve supportarle, altrimenti l’esecuzione genera un errore in modo restrittivo. /status mostra il runtime effettivo
selezionato in base ai criteri, alla proprietà persistente e al supporto del percorso.
Lo stato preparato è esplicito: un runtimePolicy mancante resta non dichiarato anziché
essere dedotto dai campi di trasporto eventualmente presenti.
Quando l’autenticazione gestita dall’harness lascia irrisolti più percorsi fisici, l’informazione
di supporto preparata è l’intersezione dei relativi ID di runtime compatibili e
segnala le sostituzioni della richiesta se un qualsiasi candidato le contiene. Un solo candidato non dichiarato
rende quindi vuota la compatibilità nativa; preparedAuth.source: "harness"
è un proprietario dell’autenticazione, non un’autorizzazione a dedurre il supporto del percorso.
Se l’harness selezionato è inatteso, abilitare il logging di debug agents/harness
e ispezionare il record strutturato agent harness selected del Gateway: include
l’ID dell’harness selezionato, il motivo della selezione, i criteri di runtime/fallback
e, in modalità auto, il risultato del supporto di ciascun candidato plugin.
Il plugin Codex integrato registra codex come ID del proprio harness. Il core lo tratta
come un normale ID di harness di plugin; gli alias specifici di Codex appartengono al plugin
o alla configurazione dell’operatore, non al selettore di runtime condiviso.
Associazione tra provider e harness
La maggior parte degli harness dovrebbe registrare anche un provider. Il provider rende visibili al resto di OpenClaw i riferimenti ai modelli, lo stato di autenticazione, i metadati dei modelli e la selezione/model. L’harness rivendica quindi tale provider in supports(...).
Il plugin Codex integrato segue questo schema:
- riferimenti ai modelli utente preferiti:
openai/gpt-5.6-sol - riferimenti di compatibilità: i riferimenti legacy
codex/gpt-*restano accettati, ma le nuove configurazioni non dovrebbero usarli come normali riferimenti provider/modello - ID harness:
codex - autenticazione: disponibilità sintetica del provider, perché l’harness Codex gestisce l’accesso e la sessione nativi di Codex
- richiesta all’app-server: OpenClaw invia a Codex l’ID del modello non elaborato e lascia che l’harness comunichi con il protocollo nativo dell’app-server
auto, OpenAI può
selezionare Codex solo quando il contratto del percorso gestito dal provider dichiara codex
compatibile: un percorso ufficiale HTTPS Platform Responses o ChatGPT Responses esatto
senza alcuna sostituzione personalizzata della richiesta. Il solo prefisso openai/* non
seleziona mai Codex. Endpoint personalizzati, adattatori Completions e comportamenti personalizzati
delle richieste restano su OpenClaw. Gli endpoint HTTP ufficiali in chiaro vengono rifiutati. I riferimenti codex/gpt-*
precedenti restano input di compatibilità. Vedere
Runtime implicito dell’agente OpenAI.
Per la configurazione da parte dell’operatore, esempi di prefissi dei modelli e configurazioni esclusivamente Codex, vedere
Harness Codex.
Il plugin Codex applica la versione minima dell’app-server documentata in
Harness Codex. Verifica l’handshake di inizializzazione e
blocca i server precedenti o privi di versione, in modo che OpenClaw venga eseguito solo sulla superficie
del protocollo che è stata verificata.
Middleware dei risultati degli strumenti
I plugin integrati e i plugin installati esplicitamente abilitati con contratti manifest corrispondenti possono collegare middleware dei risultati degli strumenti indipendente dal runtime tramiteapi.registerAgentToolResultMiddleware(...) quando il loro manifest dichiara gli
ID di runtime di destinazione in contracts.agentToolResultMiddleware. Questa superficie attendibile
serve per trasformazioni asincrone dei risultati degli strumenti che devono essere eseguite prima che OpenClaw o
Codex restituisca l’output degli strumenti al modello.
I Plugin legacy inclusi possono ancora usare
api.registerCodexAppServerExtensionFactory(...) per il middleware riservato all’app-server Codex, ma le nuove trasformazioni dei risultati devono usare l’API indipendente dal runtime. L’hook api.registerEmbeddedExtensionFactory(...), riservato al runner incorporato, è stato
rimosso; le trasformazioni incorporate dei risultati degli strumenti devono usare middleware indipendente dal runtime.
Classificazione dell’esito terminale
Gli harness nativi che gestiscono la propria proiezione del protocollo possono usareclassifyAgentHarnessTerminalOutcome(...) da
openclaw/plugin-sdk/agent-harness-runtime quando un turno completato non ha prodotto
testo visibile dell’assistente. L’helper restituisce empty, reasoning-only o
planning-only, affinché la politica di fallback di OpenClaw possa decidere se riprovare con un
modello diverso. planning-only richiede il campo planText esplicito
dell’harness; OpenClaw non lo deduce dal testo dell’assistente. L’helper
lascia intenzionalmente non classificati gli errori del prompt, i turni in corso e le risposte
intenzionalmente silenziose come NO_REPLY.
Effetti collaterali al termine dell’agente
Gli harness nativi devono chiamarerunAgentEndSideEffects(...) da
openclaw/plugin-sdk/agent-harness-runtime dopo aver finalizzato un tentativo. Questo
invia l’hook portabile agent_end e l’acquisizione delle ricerche di OpenClaw
senza ritardare le risposte interattive. Usare awaitAgentEndSideEffects(...) per
le esecuzioni locali non interattive nelle quali il tentativo non deve concludersi finché tali
effetti collaterali non sono terminati. Entrambi gli helper accettano lo stesso payload { event, ctx } di
runAgentHarnessAgentEndHook(...); i loro errori non modificano il risultato del
tentativo completato.
Input utente e superfici degli strumenti
Gli harness nativi che espongono una richiesta di input utente a livello di runtime devono usare gli helper per l’input utente daopenclaw/plugin-sdk/agent-harness-runtime per formattare
il prompt, recapitarlo tramite il percorso di risposta bloccante di OpenClaw e normalizzare
le risposte a scelta/libere nella forma di risposta nativa del runtime. L’helper
mantiene coerente la presentazione tra canale e TUI, mentre ogni harness conserva il proprio
parsing del protocollo e il ciclo di vita delle richieste in sospeso.
Gli harness nativi che necessitano di un instradamento compatto degli strumenti simile a PI devono usare
createAgentHarnessToolSurfaceRuntime(...) da
openclaw/plugin-sdk/agent-harness-tool-runtime. Questo gestisce
la selezione dei controlli per ricerca degli strumenti/modalità codice, le impostazioni predefinite essenziali per i modelli locali,
il filtraggio degli schemi compatibile con il runtime, l’esecuzione nascosta del catalogo, l’idratazione
delle directory e la pulizia del catalogo. Gli harness continuano a gestire la conversione degli strumenti
specifica del proprio SDK e il callback di esecuzione nativo.
Modalità harness Codex nativa
L’harnesscodex incluso è la modalità Codex nativa per i turni dell’agente OpenClaw
incorporato. Abilitare prima il Plugin codex incluso e includere codex in
plugins.allow se la configurazione usa un elenco consentito restrittivo. Le configurazioni native dell’app-server
devono usare openai/gpt-*; i turni dell’agente OpenAI selezionano l’harness Codex
solo quando il percorso effettivo dichiara la compatibilità con Codex. I riferimenti legacy ai modelli Codex
devono essere corretti con openclaw doctor --fix, mentre i riferimenti legacy ai modelli codex/*
rimangono alias di compatibilità per l’harness nativo.
Quando questa modalità è in esecuzione, Codex gestisce l’id del thread nativo, il comportamento di ripresa,
la Compaction e l’esecuzione dell’app-server. OpenClaw continua a gestire il canale di chat,
la copia visibile della trascrizione, la politica degli strumenti, le approvazioni, la distribuzione dei contenuti multimediali e la selezione
della sessione. Usare il provider/modello agentRuntime.id: "codex" quando è necessario
dimostrare che solo il percorso dell’app-server Codex può acquisire l’esecuzione. I runtime dei Plugin
espliciti adottano un comportamento fail-closed; gli errori di selezione e di runtime dell’app-server Codex
non vengono ritentati tramite un altro runtime.
Rigidità del runtime
Per impostazione predefinita, OpenClaw usa la politica di runtime provider/modelloauto: gli harness dei
Plugin registrati possono acquisire i percorsi effettivi compatibili e il runtime
incorporato gestisce il turno quando nessuno corrisponde. Il solo prefisso di provider/modello non
seleziona mai un harness. Usare un runtime Plugin provider/modello esplicito, come
agentRuntime.id: "codex", quando l’assenza di selezione dell’harness deve causare un errore
invece dell’instradamento tramite il runtime incorporato. La selezione esplicita non rende
compatibile un percorso incompatibile. Gli errori degli harness dei Plugin selezionati causano sempre
un errore irreversibile. Ciò non impedisce un
agentRuntime.id: "openclaw" provider/modello esplicito.
Per le esecuzioni incorporate riservate a Codex:
Sessioni native e copia della trascrizione
Un harness può mantenere un id sessione nativo, un id thread o un token di ripresa lato daemon. Mantenere tale associazione esplicitamente collegata alla sessione OpenClaw e continuare a copiare l’output visibile all’utente dell’assistente/degli strumenti nella trascrizione di OpenClaw. La trascrizione di OpenClaw rimane il livello di compatibilità per:- cronologia della sessione visibile nel canale
- ricerca e indicizzazione della trascrizione
- ritorno all’harness OpenClaw integrato in un turno successivo
- comportamento generico di
/new,/reseted eliminazione della sessione
reset(...) affinché OpenClaw
possa eliminarla quando viene reimpostata la sessione OpenClaw proprietaria.
Risultati di strumenti e contenuti multimediali
Il core costruisce l’elenco degli strumenti OpenClaw e lo passa al tentativo preparato. Quando un harness esegue una chiamata dinamica a uno strumento, restituire il risultato dello strumento tramite la forma del risultato dell’harness anziché inviare direttamente i contenuti multimediali al canale. In questo modo, gli output di testo, immagini, video, musica, TTS, approvazioni e strumenti di messaggistica seguono lo stesso percorso di distribuzione delle esecuzioni supportate da OpenClaw.Esiti terminali degli strumenti
AgentHarnessAttemptParams.observeToolTerminal è l’accumulatore degli esiti
terminali gestito dall’host. Un harness che esegue strumenti dinamici OpenClaw o strumenti
nativi deve chiamarlo quando ogni strumento raggiunge un singolo esito terminale, prima che il
risultato del tentativo venga finalizzato. Gli harness che non eseguono strumenti non devono
chiamarlo.
Riportare i fatti dal confine di esecuzione:
- Passare l’id della chiamata del protocollo quando esiste, il nome canonico dello strumento e gli argomenti che hanno effettivamente raggiunto lo strumento dopo la preparazione o le riscritture degli hook.
- Impostare
executionStarted: falsequando la convalida, l’approvazione o un altro controllo ha interrotto la chiamata prima dell’avvio dell’implementazione dello strumento. Quando l’invio potrebbe essere avvenuto, riportare prudentementetrue. - Riportare
outcome: "success"ooutcome: "failure". Includere i campi strutturati relativi all’errore disponibili nel runtime, anziché dedurre l’errore dal testo visualizzato. - Usare
nativeMutationsolo per gli strumenti nativi che non usano una definizione di strumento OpenClaw. Fornire in tale sede i dati sulla mutazione e sulla ripetizione gestiti dal protocollo; non copiare il classificatore delle mutazioni di OpenClaw nell’harness.
lastToolError in AgentHarnessAttemptResult e usare i relativi dati di esecuzione,
argomenti ed effetti collaterali nella proiezione dell’harness anziché derivare
uno stato parallelo. L’host conserva un errore di mutazione non risolto anche dopo il successo di strumenti
non correlati e lo elimina solo dopo il completamento dell’azione corrispondente.
Il callback rimane facoltativo per garantire la compatibilità del codice sorgente con gli harness sperimentali
precedenti. Facoltativo non significa trascurabile per un harness che esegue strumenti:
senza rapporti terminali, OpenClaw non può preservare l’effettivo errore degli strumenti con mutazioni
nelle chiamate successive agli strumenti, incluso il completamento silenzioso dell’Heartbeat.
Limitazioni attuali
- Il percorso di importazione pubblico è generico, ma alcuni alias dei tipi di tentativo/risultato conservano ancora nomi legacy per compatibilità.
- L’installazione di harness di terze parti è sperimentale. Preferire i Plugin dei provider finché non è necessario un runtime di sessione nativo.
- Il passaggio da un harness all’altro è supportato tra i turni. Non cambiare harness nel corso di un turno dopo l’avvio di strumenti nativi, approvazioni, testo dell’assistente o invii di messaggi.