openclaw path
Door Plugin geleverde shelltoegang tot de oc://-adresseringslaag: één
op soort gedispatcht padschema voor het inspecteren en bewerken van adresseerbare werkruimtebestanden
(markdown, jsonc, jsonl, yaml/yml/lobster). Zelfhosters, Plugin-auteurs
en editor-extensies gebruiken het om een smalle locatie te lezen, vinden of bij te werken
zonder per bestandstype eigen parsers te schrijven.
De CLI weerspiegelt de openbare werkwoorden van de laag:
resolveis concreet en levert één match op.findis het werkwoord voor meerdere matches bij jokertekens, unions, predicaten en positionele uitbreiding.setaccepteert alleen concrete paden of invoegmarkeringen; jokertekenpatronen worden vóór het schrijven geweigerd.
path wordt geleverd door de meegeleverde optionele oc-path-Plugin. Schakel deze in vóór
het eerste gebruik:
Waarom dit gebruiken
OpenClaw-status is verspreid over door mensen bewerkte markdown, JSONC-configuratie met opmerkingen, alleen-toevoegen JSONL-logboeken en YAML-workflow-/specificatiebestanden. Shellscripts, hooks en agents hebben vaak één kleine waarde uit die bestanden nodig: een frontmatter-sleutel, een Plugin-instelling, een logrecordveld, een YAML-stap of een opsommingitem onder een benoemde sectie.openclaw path geeft die aanroepers een stabiel adres in plaats van een eenmalige grep,
regex of parser voor elk bestandstype. Hetzelfde oc://-pad kan vanuit de terminal worden
gevalideerd, opgelost, doorzocht, droog uitgevoerd en geschreven, waardoor smalle
automatisering eenvoudiger te beoordelen en veiliger opnieuw af te spelen is. Het is vooral
nuttig wanneer je één blad wilt bijwerken terwijl de rest van de opmerkingen, regeleinden
en omringende opmaak van het bestand behouden blijven.
Gebruik het wanneer wat je wilt een logisch adres heeft, maar de fysieke bestandsvorm
varieert:
- Een hook wil één instelling lezen uit JSONC met opmerkingen zonder opmerkingen te verliezen wanneer de waarde wordt teruggeschreven.
- Een onderhoudsscript wil elk overeenkomend eventveld in een JSONL-logboek vinden zonder het hele logboek in een aangepaste parser te laden.
- Een editor-extensie wil naar een markdownsectie of opsommingitem springen op basis van slug, en daarna de exacte regel weergeven waarnaar het is opgelost.
- Een agent wil een kleine werkruimtebewerking droog uitvoeren voordat die wordt toegepast, met de gewijzigde bytes zichtbaar in de beoordeling.
openclaw path waarschijnlijk niet nodig voor gewone bewerkingen van hele bestanden, uitgebreide
configuratiemigraties of geheugenspecifieke schrijfacties. Die moeten de eigenaarsopdracht
of Plugin gebruiken. path is bedoeld voor kleine, adresseerbare bestandsbewerkingen waarbij een
herhaalbare terminalopdracht duidelijker is dan nog een specifieke parser.
Hoe het wordt gebruikt
Lees één waarde uit een door mensen bewerkt configuratiebestand:--json wanneer een
aanroeper gestructureerde uitvoer nodig heeft en --human wanneer een persoon het
resultaat inspecteert.
Hoe het werkt
openclaw path doet vier dingen:
- Parseert het
oc://-adres naar slots: bestand, sectie, item, veld en optionele sessie. - Kiest de adapter voor het bestandstype op basis van de doelextensie (
.md,.jsonc,.jsonl,.yaml,.yml,.lobsteren gerelateerde aliassen). - Lost de slots op tegen de AST van dat bestandstype: markdownkoppen/-items, JSONC-objectsleutels/array-indexen, JSONL-regelrecords of YAML-map-/sequencenodes.
- Voor
setgeeft het bewerkte bytes uit via dezelfde adapter, zodat de onaangeraakte delen van het bestand hun opmerkingen, regeleinden en nabije opmaak behouden waar het type dat ondersteunt.
resolve en set vereisen één concreet doel. find is het verkennende
werkwoord: het breidt jokertekens, unions, predicaten en rangnummers uit naar de concrete
matches die je kunt inspecteren voordat je er één kiest om te schrijven.
Subopdrachten
| Subopdracht | Doel |
|---|---|
resolve <oc-path> | Druk de concrete match op het pad af (of “niet gevonden”). |
find <pattern> | Som matches op voor een jokerteken-/union-/predicaatpad. |
set <oc-path> <value> | Schrijf een blad- of invoegdoel op een concreet pad. Ondersteunt --dry-run. |
validate <oc-path> | Alleen parseren; druk structurele uitsplitsing af (bestand / sectie / item / veld). |
emit <file> | Laat een bestand heen en terug gaan via parseXxx + emitXxx (diagnose voor bytegetrouwheid). |
Globale vlaggen
| Vlag | Doel |
|---|---|
--cwd <dir> | Los de bestandsslot op tegen deze directory (standaard: process.cwd()). |
--file <path> | Overschrijf het opgeloste pad van de bestandsslot (absolute toegang). |
--json | Forceer JSON-uitvoer (standaard wanneer stdout geen TTY is). |
--human | Forceer menselijke uitvoer (standaard wanneer stdout een TTY is). |
--dry-run | (alleen op set) druk de bytes af die zouden worden geschreven zonder te schrijven. |
--diff | (met set --dry-run) druk een unified diff af in plaats van de volledige bytes. |
oc://-syntaxis
field vereist item, en item vereist section. Over alle
vier slots:
- Gequote segmenten —
"a/b.c"overleeft/- en.-scheidingstekens. Inhoud is byte-letterlijk;"en\zijn niet toegestaan binnen quotes. De bestandsslot is ook quote-bewust:oc://"skills/email-drafter"/Tools/$lastbehandeltskills/email-drafterals één bestandspad. - Predicaten —
[k=v],[k!=v],[k<v],[k<=v],[k>v],[k>=v]. Numerieke bewerkingen vereisen dat beide kanten naar eindige getallen kunnen worden geconverteerd. - Unions —
{a,b,c}matcht een van de alternatieven. - Jokertekens —
*(één subsegment) en**(nul of meer, recursief).findaccepteert deze;resolveensetweigeren ze als ambigu. - Positioneel —
$first/$lastlossen op naar de eerste / laatste index of gedeclareerde sleutel. - Rangnummer —
#Nvoor de N-de match in documentvolgorde. - Invoegmarkeringen —
+,+key,+nnnvoor invoeging op sleutel / index (gebruik metset). - Sessiebereik —
?session=cron-dailyenz. Orthogonaal aan slotnesting. Sessiewaarden zijn onbewerkt, niet percent-gedecodeerd; ze mogen geen besturingstekens of gereserveerde queryscheidingstekens bevatten (?,&,%).
?, &, %) buiten gequote, predicaat- of unionsegmenten
worden geweigerd. Besturingstekens (U+0000-U+001F, U+007F) worden overal geweigerd,
ook in de session-querywaarde.
formatOcPath(parseOcPath(path)) === path is gegarandeerd voor canonieke paden.
Niet-canonieke queryparameters worden genegeerd, behalve de eerste niet-lege
session=-waarde.
Adressering per bestandstype
| Type | Adresseringsmodel |
|---|---|
| Markdown | H2-secties op slug, opsommingitems op slug of #N, frontmatter via [frontmatter]. |
| JSONC/JSON | Objectsleutels en array-indexen; punten splitsen geneste subsegmenten tenzij gequote. |
| JSONL | Top-level regeladressen (L1, L2, $first, $last), daarna JSONC-achtige afdaling binnen de regel. |
| YAML/YML/.lobster | Mapsleutels en sequence-indexen; opmerkingen en flowstijl worden afgehandeld door de YAML-document-API. |
resolve retourneert een gestructureerde match: root, node, leaf of
insertion-point, met een 1-gebaseerd regelnummer. Bladwaarden worden als tekst
plus een leafType aangeboden, zodat Plugin-auteurs previews kunnen renderen zonder afhankelijk te zijn van
de AST-vorm per type.
Mutatiecontract
set schrijft één concreet doel:
- Markdown-frontmatterwaarden en
- key: value-itemvelden zijn stringbladeren. Markdown-invoegingen voegen secties, frontmatter-sleutels of sectie-items toe en renderen een canonieke markdownvorm voor het gewijzigde bestand. - JSONC-bladschrijfacties converteren de stringwaarde naar het bestaande bladtype
(
string, eindigenumber,true/falseofnull). Gebruik--value-jsonwanneer een JSONC/JSON/JSONL-bladvervanging<value>als JSON moet parsen en van vorm mag veranderen, zoals het vervangen van een string-SecretRef-shorthand door een object. JSONC-object- en array-invoegingen parsen<value>als JSON en gebruiken hetjsonc-parser-bewerkpad voor gewone bladschrijfacties, waarbij opmerkingen en nabije opmaak behouden blijven. - JSONL-bladschrijfacties converteren zoals JSONC binnen een regel. Vervanging van hele regels en
toevoegen parsen
<value>als JSON. Gerenderde JSONL behoudt de dominante LF/CRLF-regeleindconventie van het bestand. - YAML-bladschrijfacties converteren naar het bestaande scalaire type (
string, eindigenumber,true/falseofnull). YAML-invoegingen gebruiken de meegeleverde document-API van hetyaml-pakket voor map-/sequence-updates. Misvormde YAML- documenten met parserfouten worden vóór mutatie geweigerd metparse-error.
--dry-run vóór gebruikerszichtbare schrijfacties wanneer de exacte bytes ertoe doen. De
laag behoudt byte-identieke uitvoer voor parse-/emit-rondreizen, maar een
mutatie kan het bewerkte gebied of bestand canoniseren, afhankelijk van het type.
Voeg --diff toe wanneer je de preview als een gerichte voor/na-patch wilt
in plaats van het volledige gerenderde bestand.
Voorbeelden
Recepten per bestandstype
Dezelfde vijf werkwoorden werken voor alle typen; het adresseringsschema kiest op basis van de bestandsextensie. De voorbeelden hieronder gebruiken de fixtures uit de PR-beschrijving.Markdown
[frontmatter] adresseert het YAML-frontmatterblok; tools
komt overeen met de kop ## Tools via de slug, en itembladen behouden hun slugvorm
zelfs wanneer de bron underscores gebruikt (send_email → send-email).
JSONC
jsonc-parser, waardoor opmerkingen en witruimte een
set overleven. Voer eerst uit met --dry-run om de bytes te inspecteren voordat je vastlegt.
JSONL
[event=action]) wanneer je het
regelnummer niet kent, of via het canonieke LN-segment wanneer je dat wel weet.
YAML
Document-API van het yaml-pakket in plaats van een zelfgebouwde parser,
zodat gewone parseer-/emit-rondgangen opmerkingen en schrijfstructuur behouden, terwijl
opgeloste paden hetzelfde model met mapsleutel / reeksindex gebruiken als JSONC. Dezelfde
adapter verwerkt .yaml-, .yml- en .lobster-bestanden.
Subcommando-overzicht
resolve <oc-path>
Lees één blad of knooppunt. Jokertekens worden geweigerd — gebruik daarvoor find.
Sluit af met 0 bij een overeenkomst, 1 bij een nette misser, 2 bij een parseerfout of geweigerd
patroon.
find <pattern>
Som elke overeenkomst op voor een jokerteken- / predicaat- / union-patroon. Sluit af met 0
bij minstens één overeenkomst, 1 bij nul. Jokertekens voor bestandsposities worden geweigerd met
OC_PATH_FILE_WILDCARD_UNSUPPORTED — geef een concreet bestand door (globbing over meerdere bestanden
is een vervolgfuntie).
set <oc-path> <value>
Schrijf een blad. Combineer met --dry-run om vooraf de bytes te bekijken die zouden worden
geschreven zonder het bestand aan te raken. Voeg --diff toe voor een voorbeeldweergave als unified diff.
Sluit af met 0 bij een geslaagde schrijfopdracht, 1 als het substraat weigert (bijvoorbeeld als een
sentinelbewaking wordt geraakt), 2 bij parsefouten.
+key maakt het genoemde kind aan als het nog niet
bestaat; +nnn en kale + werken respectievelijk voor geïndexeerde invoeging en invoeging achteraan.
validate <oc-path>
Controle met alleen parsen. Geen bestandssysteemtoegang. Nuttig wanneer je wilt bevestigen dat een
sjabloonpad correct is opgebouwd voordat je variabelen vervangt, of wanneer je
de structurele opsplitsing wilt voor foutopsporing:
0 wanneer geldig, 1 wanneer ongeldig (met een gestructureerde code en
message), 2 bij argumentfouten.
emit <file>
Voer een bestand heen en terug door de soortspecifieke parser en uitvoergenerator. De uitvoer hoort
byte-identiek te zijn aan de invoer bij een correct bestand — afwijking wijst op een
parserbug of een geraakte sentinel. Nuttig voor foutopsporing van substraatgedrag op
praktijkinvoer.
Afsluitcodes
| Code | Betekenis |
|---|---|
0 | Succes. (resolve / find: minstens één overeenkomst. set: schrijven geslaagd.) |
1 | Geen overeenkomst, of set geweigerd door het substraat (geen fout op systeemniveau). |
2 | Argument- of parsefout. |
Uitvoermodus
openclaw path is TTY-bewust: menselijk leesbare uitvoer op een terminal, JSON wanneer
stdout wordt doorgesluisd of omgeleid. --json en --human overschrijven de
automatische detectie.
Opmerkingen
setschrijft bytes via het uitvoerpad van het substraat, dat de redactie-sentinelbewaking automatisch toepast. Een blad dat__OPENCLAW_REDACTED__bevat (letterlijk of als deeltekenreeks), wordt tijdens het schrijven geweigerd.- JSONC-parsing en bladbewerkingen gebruiken de plugin-lokale afhankelijkheid
jsonc-parser, zodat opmerkingen en opmaak behouden blijven bij gewone bladschrijfacties in plaats van via een handgeschreven parser-/her-renderpad te gaan. pathweet niets van LKG. Als het bestand door LKG wordt gevolgd, bepaalt de volgende observe-aanroep of er wordt gepromoveerd / hersteld.set --batchvoor atomaire multi-set via de LKG-promotie-/herstellevenscyclus staat gepland naast het LKG-herstelsubstraat.