Plugin OC Path

Il Plugin oc-path incluso aggiunge la CLI openclaw path per lo schema di indirizzamento dei file dell'area di lavoro oc://. È distribuito nel repository OpenClaw in extensions/oc-path/, ma è facoltativo: dopo l'installazione o la compilazione rimane inattivo finché non viene abilitato.

Gli indirizzi oc:// puntano a una singola foglia (o a un insieme di foglie definito tramite caratteri jolly) all'interno di un file dell'area di lavoro. Il Plugin riconosce quattro tipi di file:

• markdown (.md): frontmatter, sezioni, elementi, campi
• jsonc (.jsonc, .json): commenti e formattazione preservati
• jsonl (.jsonl, .ndjson): record organizzati per riga
• yaml (.yaml, .yml, .lobster): nodi mappa, sequenza e scalari tramite l'API Document del pacchetto yaml

Chi gestisce un'installazione autonoma e le estensioni degli editor usa la CLI per leggere o scrivere una singola foglia senza interagire direttamente con l'SDK tramite script; gli agenti e gli hook la trattano come un substrato deterministico, così i round trip con fedeltà a livello di byte e la protezione della sentinella di oscuramento si applicano uniformemente a tutti i tipi. Consulta il riferimento della CLI per la grammatica completa, l'elenco dei flag per ogni verbo e gli esempi svolti per ciascun tipo di file; questa pagina spiega perché e come abilitare il Plugin.

Perché abilitarlo

Abilita oc-path quando script, hook o strumenti locali degli agenti devono puntare a una parte precisa dello stato dell'area di lavoro senza richiedere un parser dedicato per ogni struttura di file. Un singolo indirizzo oc:// può identificare una chiave del frontmatter markdown, un elemento di sezione, una foglia di configurazione JSONC, un campo evento JSONL o un passaggio di un flusso di lavoro YAML.

Questo è importante per i flussi di lavoro dei manutentori, nei quali la modifica deve rimanere contenuta, verificabile e ripetibile: esaminare un valore, trovare i record corrispondenti, simulare una scrittura, quindi applicare la modifica soltanto a quella foglia lasciando invariati commenti, terminazioni di riga e formattazione circostante.

Motivi comuni per abilitarlo:

• Automazione locale: gli script di shell risolvono o aggiornano un singolo valore dell'area di lavoro con openclaw path … --json, anziché includere codice di analisi separato per markdown, JSONC, JSONL e YAML.
• Modifiche visibili agli agenti: prima della scrittura, un agente mostra la differenza di una simulazione per una sola foglia indirizzata, più semplice da esaminare rispetto alla riscrittura libera di un file.
• Integrazioni con gli editor: un editor associa oc://AGENTS.md/tools/gh al nodo markdown e al numero di riga esatti, senza dedurli dal testo dell'intestazione.
• Diagnostica: emit esegue un round trip di un file attraverso il parser e l'emettitore, consentendo di verificare se un tipo di file è stabile a livello di byte prima di fare affidamento sulle modifiche automatiche.

# Il plugin GitHub è abilitato in questa configurazione?openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json # Quali nomi di chiamate agli strumenti compaiono nel registro di questa sessione?openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json # Quali byte scriverebbe questa piccola modifica alla configurazione?openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

oc-path non è intenzionalmente responsabile della semantica di livello superiore. I Plugin di memoria continuano a gestire le scritture in memoria, i comandi di configurazione continuano a gestire l'intera configurazione e il ripristino dell'ultima configurazione valida nota (LKG) continua a gestire il ripristino e la promozione. oc-path è il livello ristretto di indirizzamento e di operazioni sui file con preservazione dei byte attorno al quale possono essere costruiti tali strumenti di livello superiore.

Dove viene eseguito

Il Plugin viene eseguito all'interno del processo della CLI openclaw sull'host nel quale viene invocato il comando. Non richiede un Gateway in esecuzione e non apre alcun socket di rete; ogni verbo è una trasformazione pura applicata al file indicato.

I metadati del Plugin si trovano in extensions/oc-path/openclaw.plugin.json:

{  "id": "oc-path",  "name": "OC Path",  "activation": {    "onStartup": false,    "onCommands": ["path"]  },  "commandAliases": [{ "name": "path", "kind": "cli" }]}

onStartup: false esclude il Plugin dal percorso di avvio del Gateway. commandAliases e activation.onCommands indicano alla CLI di caricare il Plugin in modo differito la prima volta che viene eseguito openclaw path …, quindi le installazioni che non usano mai il verbo non sostengono alcun costo.

Abilitazione

openclaw plugins enable oc-path

Riavvia il Gateway, se ne esegui uno, affinché l'istantanea del manifesto acquisisca il nuovo stato. Le invocazioni dirette di openclaw path funzionano immediatamente sullo stesso host; la CLI carica il Plugin su richiesta.

Disabilitalo con:

openclaw plugins disable oc-path

Dipendenze

Tutte le dipendenze dei parser sono locali al Plugin; l'abilitazione di oc-path non aggiunge nuovi pacchetti al runtime principale:

JSONL rimane implementato manualmente: l'analisi per riga è più semplice di qualsiasi dipendenza e l'analisi di ogni riga passa già attraverso jsonc-parser.

Funzionalità fornite

Attualmente la CLI è l'unica superficie pubblica. I verbi del substrato sono privati del Plugin; i consumatori usano la CLI oppure creano il proprio Plugin basato sull'SDK.

Relazione con altri Plugin

• memory-*: le scritture in memoria passano attraverso i Plugin di memoria, non attraverso oc-path. oc-path è un substrato generico per i file; i Plugin di memoria vi sovrappongono la propria semantica.
• LKG: path non gestisce il ripristino dell'ultima configurazione valida nota. Se un file modificato tramite path è anche monitorato da LKG, il ciclo successivo di osservazione della configurazione decide se promuoverlo o ripristinarlo; considera una modifica tramite path come qualsiasi altra scrittura diretta sullo stesso file.

Sicurezza

set scrive byte non elaborati attraverso il percorso di emissione del substrato, che applica automaticamente la protezione della sentinella di oscuramento. La scrittura di una foglia contenente __OPENCLAW_REDACTED__, in forma esatta o come sottostringa, viene rifiutata con OC_EMIT_SENTINEL. La CLI rimuove inoltre la sentinella letterale da ogni output leggibile o JSON che stampa, sostituendola con [REDACTED], affinché le acquisizioni del terminale e le pipeline non espongano mai il marcatore.

Contenuti correlati

• Riferimento della CLI openclaw path
• Gestire i Plugin
• Creare Plugin