openclaw path
Accesso shell fornito da Plugin al substrato di indirizzamento oc://: uno
schema di percorsi con dispatch per tipo per ispezionare e modificare file
dello spazio di lavoro indirizzabili (markdown, jsonc, jsonl, yaml/yml/lobster).
Chi esegue hosting autonomo, gli autori di plugin e le estensioni per editor lo
usano per leggere, trovare o aggiornare una posizione ristretta senza creare
parser specifici per ogni file.
La CLI rispecchia i verbi pubblici del substrato:
resolveè concreto e a corrispondenza singola.findè il verbo multi-corrispondenza per wildcard, unioni, predicati ed espansione posizionale.setaccetta solo percorsi concreti o marcatori di inserimento; i pattern wildcard vengono rifiutati prima della scrittura.
path è fornito dal plugin opzionale in bundle oc-path. Abilitalo prima del
primo utilizzo:
Perché usarlo
Lo stato di OpenClaw è distribuito tra markdown modificato da esseri umani, configurazione JSONC commentata, log JSONL append-only e file YAML di workflow o specifiche. Script shell, hook e agenti spesso hanno bisogno di un piccolo valore da quei file: una chiave frontmatter, un’impostazione di plugin, il campo di un record di log, uno step YAML o un elemento elenco sotto una sezione con nome.openclaw path offre a quei chiamanti un indirizzo stabile invece di un grep,
una regex o un parser ad hoc per ogni tipo di file. Lo stesso percorso oc://
può essere validato, risolto, cercato, provato in dry-run e scritto dal
terminale, rendendo le automazioni ristrette più facili da revisionare e più
sicure da rieseguire. È particolarmente utile quando vuoi aggiornare una sola
foglia preservando il resto dei commenti del file, i fine riga e la
formattazione circostante.
Usalo quando ciò che cerchi ha un indirizzo logico, ma la forma fisica del file
varia:
- Un hook vuole leggere un’impostazione da JSONC commentato senza perdere i commenti quando riscrive il valore.
- Uno script di manutenzione vuole trovare ogni campo evento corrispondente in un log JSONL senza caricare l’intero log in un parser personalizzato.
- Un’estensione per editor vuole passare a una sezione markdown o a un elemento elenco per slug, poi renderizzare la riga esatta a cui è stata risolta.
- Un agente vuole provare in dry-run una piccola modifica allo spazio di lavoro prima di applicarla, con i byte modificati visibili in revisione.
openclaw path per normali modifiche di interi
file, migrazioni di configurazione complesse o scritture specifiche della
memoria. Queste dovrebbero usare il comando o il plugin proprietario. path è
per operazioni su file piccole e indirizzabili, dove un comando terminale
ripetibile è più chiaro di un altro parser su misura.
Come viene usato
Leggi un valore da un file di configurazione modificato da esseri umani:--json quando un chiamante ha bisogno di output strutturato e --human
quando una persona sta ispezionando il risultato.
Come funziona
openclaw path fa quattro cose:
- Analizza l’indirizzo
oc://in slot: file, sezione, elemento, campo e sessione opzionale. - Sceglie l’adapter per tipo di file dall’estensione di destinazione (
.md,.jsonc,.jsonl,.yaml,.yml,.lobstere alias correlati). - Risolve gli slot rispetto all’AST di quel tipo di file: intestazioni/elementi markdown, chiavi oggetto/indici array JSONC, record di riga JSONL o nodi mappa/sequenza YAML.
- Per
set, emette i byte modificati tramite lo stesso adapter, così le parti intatte del file mantengono commenti, fine riga e formattazione vicina dove il tipo lo supporta.
resolve e set richiedono un solo target concreto. find è il verbo
esplorativo: espande wildcard, unioni, predicati e ordinali nelle corrispondenze
concrete che puoi ispezionare prima di sceglierne una da scrivere.
Sottocomandi
| Sottocomando | Scopo |
|---|---|
resolve <oc-path> | Stampa la corrispondenza concreta al percorso (o “non trovato”). |
find <pattern> | Elenca le corrispondenze per un percorso wildcard / unione / predicato. |
set <oc-path> <value> | Scrive una foglia o un target di inserimento a un percorso concreto. Supporta --dry-run. |
validate <oc-path> | Solo parsing; stampa la scomposizione strutturale (file / sezione / elemento / campo). |
emit <file> | Fa round-trip di un file tramite parseXxx + emitXxx (diagnostica di fedeltà dei byte). |
Flag globali
| Flag | Scopo |
|---|---|
--cwd <dir> | Risolve lo slot file rispetto a questa directory (predefinito: process.cwd()). |
--file <path> | Sovrascrive il percorso risolto dello slot file (accesso assoluto). |
--json | Forza l’output JSON (predefinito quando stdout non è un TTY). |
--human | Forza l’output leggibile da persone (predefinito quando stdout è un TTY). |
--dry-run | (solo su set) stampa i byte che verrebbero scritti senza scrivere. |
--diff | (con set --dry-run) stampa un diff unificato invece dei byte completi. |
Sintassi oc://
field richiede item e item richiede section. Su tutti
e quattro gli slot:
- Segmenti tra virgolette —
"a/b.c"sopravvive ai separatori/e.. Il contenuto è letterale a livello di byte;"e\non sono ammessi dentro le virgolette. Anche lo slot file riconosce le virgolette:oc://"skills/email-drafter"/Tools/$lasttrattaskills/email-draftercome un singolo percorso file. - Predicati —
[k=v],[k!=v],[k<v],[k<=v],[k>v],[k>=v]. Gli operatori numerici richiedono che entrambi i lati possano convertirsi in numeri finiti. - Unioni —
{a,b,c}corrisponde a una qualsiasi delle alternative. - Wildcard —
*(singolo sotto-segmento) e**(zero o più, ricorsivo).findle accetta;resolveesetle rifiutano perché ambigue. - Posizionale —
$first/$lastsi risolvono al primo / ultimo indice o alla prima / ultima chiave dichiarata. - Ordinale —
#Nper l’ennesima corrispondenza in ordine di documento. - Marcatori di inserimento —
+,+key,+nnnper inserimento con chiave / indicizzato (da usare conset). - Ambito sessione —
?session=cron-dailyecc. Ortogonale all’annidamento degli slot. I valori di sessione sono grezzi, non percent-decoded; non possono contenere caratteri di controllo o delimitatori di query riservati (?,&,%).
?, &, %) fuori da segmenti tra virgolette, di
predicato o di unione vengono rifiutati. I caratteri di controllo
(U+0000-U+001F, U+007F) vengono rifiutati ovunque, incluso il valore di query
session.
formatOcPath(parseOcPath(path)) === path è garantito per i percorsi canonici.
I parametri di query non canonici vengono ignorati, tranne il primo valore
session= non vuoto.
Indirizzamento per tipo di file
| Tipo | Modello di indirizzamento |
|---|---|
| Markdown | Sezioni H2 per slug, elementi elenco per slug o #N, frontmatter tramite [frontmatter]. |
| JSONC/JSON | Chiavi oggetto e indici array; i punti separano sotto-segmenti annidati salvo se tra virgolette. |
| JSONL | Indirizzi di riga di primo livello (L1, L2, $first, $last), poi discesa stile JSONC dentro la riga. |
| YAML/YML/.lobster | Chiavi mappa e indici sequenza; commenti e stile flow sono gestiti dall’API documento YAML. |
resolve restituisce una corrispondenza strutturata: root, node, leaf o
insertion-point, con un numero di riga basato su 1. I valori foglia vengono
esposti come testo più un leafType, così gli autori di plugin possono
renderizzare anteprime senza dipendere dalla forma dell’AST specifica del tipo.
Contratto di mutazione
set scrive un target concreto:
- I valori frontmatter markdown e i campi elemento
- key: valuesono foglie stringa. Gli inserimenti markdown aggiungono sezioni, chiavi frontmatter o elementi di sezione e renderizzano una forma markdown canonica per il file modificato. - Le scritture di foglie JSONC convertono il valore stringa nel tipo della
foglia esistente (
string,numberfinito,true/falseonull). Usa--value-jsonquando una sostituzione di foglia JSONC/JSON/JSONL dovrebbe analizzare<value>come JSON e può cambiare forma, ad esempio sostituendo una scorciatoia stringa SecretRef con un oggetto. Gli inserimenti di oggetti e array JSONC analizzano<value>come JSON e usano il percorso di modificajsonc-parserper le normali scritture di foglie, preservando commenti e formattazione vicina. - Le scritture di foglie JSONL convertono come JSONC dentro una riga. La
sostituzione di un’intera riga e l’append analizzano
<value>come JSON. Il JSONL renderizzato preserva la convenzione dominante del file per i fine riga LF/CRLF. - Le scritture di foglie YAML convertono al tipo scalare esistente (
string,numberfinito,true/falseonull). Gli inserimenti YAML usano l’API documento del pacchettoyamlin bundle per aggiornamenti di mappe/sequenze. I documenti YAML malformati con errori del parser vengono rifiutati prima della mutazione conparse-error.
--dry-run prima di scritture visibili all’utente quando i byte esatti
contano. Il substrato preserva output byte-identico per round-trip parse/emit,
ma una mutazione può canonicalizzare la regione modificata o il file a seconda
del tipo. Aggiungi --diff quando vuoi l’anteprima come patch prima/dopo
focalizzata invece del file renderizzato completo.
Esempi
Ricette per tipo di file
Gli stessi cinque verbi funzionano tra i vari tipi; lo schema di indirizzamento esegue il dispatch in base all’estensione del file. Gli esempi seguenti usano le fixture dalla descrizione della PR.Markdown
[frontmatter] indirizza il blocco YAML frontmatter; tools corrisponde all’intestazione ## Tools tramite slug, e le foglie degli elementi mantengono la loro forma slug anche quando il sorgente usa underscore (send_email → send-email).
JSONC
jsonc-parser, quindi commenti e spazi vengono conservati dopo un set. Esegui prima con --dry-run per ispezionare i byte prima di confermare.
JSONL
[event=action]) quando non conosci il numero di riga, oppure tramite il segmento canonico LN quando lo conosci.
YAML
Document del pacchetto yaml invece di un parser artigianale, quindi i normali cicli parse/emit conservano commenti e forma di authoring mentre i percorsi risolti usano lo stesso modello map-key / sequence-index di JSONC. Lo stesso adattatore gestisce file .yaml, .yml e .lobster.
Riferimento dei sottocomandi
resolve <oc-path>
Legge una singola foglia o un singolo nodo. I wildcard vengono rifiutati: usa find per quelli. Esce con 0 in caso di corrispondenza, 1 in caso di mancata corrispondenza pulita, 2 in caso di errore di parsing o pattern rifiutato.
find <pattern>
Enumera ogni corrispondenza per un pattern wildcard / predicato / unione. Esce con 0 con almeno una corrispondenza, 1 con zero corrispondenze. I wildcard nello slot del file vengono rifiutati con OC_PATH_FILE_WILDCARD_UNSUPPORTED: passa un file concreto (il globbing multi-file è una funzionalità futura).
set <oc-path> <value>
Scrive una foglia. Abbinalo a --dry-run per visualizzare in anteprima i byte che verrebbero scritti senza toccare il file. Aggiungi --diff per un’anteprima diff unificata. Esce con 0 in caso di scrittura riuscita, 1 se il substrato rifiuta (per esempio, se viene raggiunta una guardia sentinella), 2 in caso di errori di parsing.
+key crea il figlio nominato se non esiste già; +nnn e il semplice + funzionano rispettivamente per l’inserimento indicizzato e per l’append.
validate <oc-path>
Controllo di solo parsing. Nessun accesso al filesystem. Utile quando vuoi confermare che un percorso template sia ben formato prima di sostituire variabili, oppure quando vuoi la scomposizione strutturale per il debug:
0 quando valido, 1 quando non valido (con code e message strutturati), 2 in caso di errori negli argomenti.
emit <file>
Esegue un round-trip di un file attraverso parser ed emitter per tipo. L’output dovrebbe essere byte-identico all’input su un file corretto: una divergenza indica un bug del parser o il raggiungimento di una sentinella. Utile per il debug del comportamento del substrato su input reali.
Codici di uscita
| Codice | Significato |
|---|---|
0 | Successo. (resolve / find: almeno una corrispondenza. set: scrittura riuscita.) |
1 | Nessuna corrispondenza, oppure set rifiutato dal substrato (nessun errore a livello di sistema). |
2 | Errore di argomento o di parsing. |
Modalità di output
openclaw path è consapevole del TTY: output leggibile da umani su terminale, JSON quando stdout viene inviato a una pipe o reindirizzato. --json e --human sovrascrivono il rilevamento automatico.
Note
setscrive byte attraverso il percorso emit del substrato, che applica automaticamente la guardia della sentinella di redazione. Una foglia che contiene__OPENCLAW_REDACTED__(alla lettera o come sottostringa) viene rifiutata al momento della scrittura.- Il parsing JSONC e le modifiche alle foglie usano la dipendenza
jsonc-parserlocale del Plugin, quindi commenti e formattazione vengono conservati nelle normali scritture di foglie invece di passare attraverso un percorso di parser/re-render artigianale. pathnon conosce LKG. Se il file è tracciato da LKG, la chiamata observe successiva decide se promuovere / recuperare.set --batchper multi-set atomico attraverso il ciclo di vita promuovi/recupera di LKG è pianificato insieme al substrato di recupero LKG.