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://. Viene distribuito nel repository OpenClaw sotto extensions/oc-path/, ma è facoltativo: installazione/build lo lascia inattivo finché non lo abiliti.

Gli indirizzi oc:// puntano a una singola foglia (o a un insieme di foglie con caratteri jolly) all'interno di un file dell'area di lavoro. Il Plugin comprende oggi tre tipi di file:

• markdown (.md, .mdx): frontmatter, sezioni, elementi, campi
• jsonc (.jsonc, .json5, .json): commenti e formattazione preservati
• jsonl (.jsonl, .ndjson): record orientati alle righe

Chi usa self-hosting e le estensioni per editor usano la CLI per leggere o scrivere una singola foglia senza usare direttamente script contro l'SDK; gli agenti e gli hook lo trattano come un substrato deterministico, così i round-trip con fedeltà ai byte e la protezione del sentinel di redazione si applicano uniformemente a tutti i tipi.

# Perché abilitarlo

Abilita oc-path quando vuoi che script, hook o strumenti locali per agenti puntino a una porzione precisa dello stato dell'area di lavoro senza inventare un parser per ogni forma di file. Un singolo indirizzo oc:// può nominare una chiave del frontmatter markdown, un elemento di sezione, una foglia di configurazione JSONC o un campo evento JSONL.

Questo conta per i flussi di lavoro dei maintainer in cui la modifica deve essere piccola, verificabile e ripetibile: ispeziona un valore, trova record corrispondenti, esegui una dry-run di una scrittura, poi applica solo quella foglia lasciando invariati commenti, terminazioni di riga e formattazione vicina. Mantenerlo come Plugin facoltativo offre agli utenti avanzati il substrato di indirizzamento senza inserire dipendenze di parser o superficie CLI nel core per le installazioni che non ne hanno bisogno.

Motivi comuni per abilitarlo:

• Automazione locale: gli script shell possono risolvere o aggiornare un valore dell'area di lavoro con openclaw path … --json invece di includere codice di parsing separato per markdown, JSONC e JSONL.
• Modifiche visibili all'agente: un agente può mostrare una diff dry-run per una foglia indirizzata prima di scrivere, più facile da revisionare rispetto a una riscrittura libera del file.
• Integrazioni con editor: un editor può mappare oc://AGENTS.md/tools/gh al nodo markdown e al numero di riga esatti senza indovinare dal testo dell'intestazione.
• Diagnostica: emit esegue il round-trip di un file attraverso parser ed emitter, così puoi verificare se un tipo di file è stabile a livello di byte prima di affidarti a modifiche automatizzate.

Esempi concreti:

# Is the GitHub plugin enabled in this config?
openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json

# Which tool-call names appear in this session log?
openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json

# What bytes would this tiny config edit write?
openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

Il Plugin non è intenzionalmente il proprietario della semantica di livello superiore. I Plugin di memoria continuano a possedere le scritture della memoria, i comandi di configurazione continuano a possedere la gestione completa della configurazione, e la logica LKG continua a possedere ripristino/promozione. oc-path è il livello ristretto di indirizzamento e operazioni su file con preservazione dei byte attorno al quale questi strumenti di livello superiore possono costruire.

# Dove viene eseguito

Il Plugin viene eseguito in-process dentro la CLI openclaw sull'host da cui invochi il comando. Non richiede un Gateway in esecuzione e non apre socket di rete: ogni verbo è una trasformazione pura su un file che gli indichi.

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 tiene il Plugin fuori dal percorso caldo del Gateway. onCommands: ["path"] indica alla CLI di caricare il Plugin in modo lazy la prima volta che esegui openclaw path …, quindi le installazioni che non usano mai il verbo non pagano alcun costo.

# Abilitazione

openclaw plugins enable oc-path

Riavvia il Gateway (se ne esegui uno) affinché lo snapshot del manifest acquisisca il nuovo stato. Le invocazioni dirette di openclaw path funzionano immediatamente sullo stesso host: la CLI carica il Plugin su richiesta.

Disabilita con:

openclaw plugins disable oc-path

# Dipendenze

Tutte le dipendenze dei parser sono locali al Plugin: abilitare oc-path non introduce nuovi pacchetti nel runtime core:

Dipendenza	Scopo
commander	Cablaggio dei sottocomandi per resolve, find, set, validate, emit.
jsonc-parser	Parsing JSONC + modifiche di foglie preservando commenti e virgole finali.
markdown-it	Tokenizzazione Markdown per il modello sezione / elemento / campo.

JSONL resta implementato a mano: il parsing orientato alle righe è più semplice di qualsiasi dipendenza, e il parsing JSONC per riga passa già attraverso jsonc-parser.

# Cosa fornisce

Superficie	Fornita da
CLI openclaw path	extensions/oc-path/cli-registration.ts
Parser / formatter oc://	extensions/oc-path/src/oc-path/oc-path.ts
Parse / emit / edit per tipo	extensions/oc-path/src/oc-path/{md,jsonc,jsonl}
Resolve / find / set universali	extensions/oc-path/src/oc-path/{resolve,find,edit}.ts
Protezione sentinel di redazione	extensions/oc-path/src/oc-path/sentinel.ts

La CLI è oggi l'unica superficie pubblica. I verbi del substrato sono privati del Plugin; i consumatori usano la CLI (o costruiscono il proprio Plugin sull'SDK).

# Relazione con altri Plugin

• memory-*: le scritture della memoria passano attraverso i Plugin di memoria, non oc-path. oc-path è un substrato di file generico; i Plugin di memoria applicano sopra la propria semantica.
• LKG: path non conosce il ripristino della configurazione Last-Known-Good. Se un file è tracciato da LKG, la successiva chiamata observe decide se promuovere o recuperare; set --batch per multi-set atomico attraverso il ciclo di vita di promozione/recupero LKG è pianificato insieme al substrato di recupero LKG.

# Sicurezza

set scrive byte grezzi attraverso il percorso emit del substrato, che applica automaticamente la protezione del sentinel di redazione. Una foglia che contiene __OPENCLAW_REDACTED__ (alla lettera o come sottostringa) viene rifiutata al momento della scrittura con OC_EMIT_SENTINEL. La CLI rimuove inoltre il sentinel letterale da qualsiasi output umano o JSON che stampa, sostituendolo con [REDACTED], così catture del terminale e pipeline non fanno mai trapelare il marker.

# Correlati

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