openclaw path
Shelltoegang tot het oc://-adresseringsschema: één padsyntaxis met dispatch op type
voor het inspecteren en bewerken van adresseerbare werkruimtebestanden (markdown, jsonc,
jsonl, yaml/yml/lobster). Self-hosters, pluginauteurs en editorextensies
gebruiken deze om een specifieke locatie te lezen, zoeken of bij te werken zonder handmatig
een parser per bestand te schrijven.
path wordt geleverd door de gebundelde optionele oc-path-plugin. Schakel deze vóór
het eerste gebruik in:
resolveis concreet en levert één overeenkomst op.findis het werkwoord voor meerdere overeenkomsten bij jokertekens, unions, predicaten en positionele uitbreiding.setaccepteert alleen concrete paden of invoegmarkeringen; patronen met jokertekens worden vóór het schrijven geweigerd.validateparseert een pad zonder bestandssysteemtoegang.emitvoert een bestand heen en terug door parseren + uitvoeren (diagnose van bytegetrouwheid).
Waarom dit gebruiken
De status van OpenClaw is verspreid over handmatig bewerkte markdown, JSONC-configuratie met commentaar, alleen-toevoegen-JSONL-logboeken en YAML-workflow-/specificatiebestanden. Scripts, hooks en agents hebben vaak één kleine waarde uit die bestanden nodig: een frontmatter-sleutel, een plugininstelling, een veld van een logrecord, een YAML-stap of een opsommingsteken onder een benoemde sectie.openclaw path geeft deze aanroepers een stabiel adres in plaats van een eenmalige
grep, regex of parser per bestandstype. Hetzelfde oc://-pad kan vanuit de terminal worden gevalideerd,
opgelost, doorzocht, als proef worden uitgevoerd en geschreven, waardoor gerichte
automatisering controleerbaar en herhaalbaar blijft. De rest van het bestand blijft behouden, zodat
het schrijven van één blad de opmerkingen, regeleinden of nabijgelegen
opmaak niet verstoort.
Gebruik dit wanneer het gewenste onderdeel een logisch adres heeft, maar de bestandsvorm
varieert:
- Een hook leest één instelling uit JSONC met commentaar zonder opmerkingen te verliezen wanneer de waarde wordt teruggeschreven.
- Een onderhoudsscript vindt elk overeenkomend gebeurtenisveld in een JSONL-logboek zonder het volledige logboek in een aangepaste parser te laden.
- Een editor springt op basis van een slug naar een markdownsectie of opsommingsitem en geeft vervolgens exact de regel weer waarnaar het adres is opgelost.
- Een agent voert eerst een proefbewerking van een klein deel van de werkruimte uit voordat deze wordt toegepast, waarbij de gewijzigde bytes zichtbaar zijn tijdens de review.
openclaw path niet voor gewone bewerkingen van volledige bestanden, uitgebreide configuratiemigraties of
geheugenspecifieke schrijfbewerkingen; gebruik daarvoor de opdracht of plugin van de eigenaar. path
is bedoeld voor kleine, adresseerbare bestandsbewerkingen waarbij een herhaalbare terminalopdracht
beter is dan nog een speciaal gebouwde parser.
Gebruik
Lees één waarde uit een handmatig bewerkt configuratiebestand:--json wanneer
een aanroeper gestructureerde uitvoer nodig heeft en --human wanneer iemand het resultaat
inspecteert.
Werking
- Parseert het
oc://-adres in posities: bestand, sectie, item, veld en een optionele sessiequery. - Kiest de adapter voor het bestandstype op basis van de extensie van het doel (
.md,.jsonc,.json,.jsonl,.ndjson,.yaml,.yml,.lobster). - Lost de posities op aan de hand van de structuur van dat bestandstype: markdown- koppen/items, JSONC-objectsleutels/array-indexen, JSONL-regelrecords of YAML-map-/sequentieknooppunten.
- Voor
setvoert de adapter de bewerkte bytes uit, zodat onaangeroerde delen van het bestand hun opmerkingen, regeleinden en nabijgelegen opmaak behouden waar het bestandstype dit ondersteunt.
resolve en set vereisen één concreet doel. find is het verkennende
werkwoord: het breidt jokertekens, unions, predicaten en rangnummers uit tot de concrete
overeenkomsten die je kunt inspecteren voordat je er één kiest om te schrijven.
Subopdrachten
Globale vlaggen
validate accepteert alleen --json / --human; deze opdracht gebruikt het bestandssysteem niet, dus
--cwd en --file zijn niet van toepassing.
oc://-syntaxis
field vereist item en item vereist section. Voor
alle vier posities geldt:
- Segmenten tussen aanhalingstekens —
"a/b.c"blijft behouden bij/- en.-scheidingstekens. De inhoud is byteletterlijk;"en\zijn niet toegestaan binnen aanhalingstekens. Ook de bestandspositie houdt rekening met aanhalingstekens:oc://"skills/email-drafter"/Tools/$lastbehandeltskills/email-drafterals één bestandspad. - Predicaten —
[k=v],[k!=v],[k<v],[k<=v],[k>v],[k>=v]. Numerieke operatoren vereisen dat beide zijden naar eindige getallen kunnen worden geconverteerd. - Unions —
{a,b,c}komt overeen met elk van de alternatieven. - Jokertekens —
*(één subsegment) en**(nul of meer, recursief).findaccepteert deze;resolveensetweigeren ze als ambigu. - Positioneel —
$first/$lastworden opgelost naar de eerste / laatste index of gedeclareerde sleutel. - Rangnummer —
#Nvoor de N-de overeenkomst in documentvolgorde. - Invoegmarkeringen —
+,+key,+nnnvoor invoeging op sleutel / index (te gebruiken metset). - Sessiebereik —
?session=cron-dailyenzovoort. Staat los van de nesting van posities. Sessiewaarden zijn onbewerkt en niet procentgedecodeerd; ze mogen geen besturings- tekens of gereserveerde queryscheidingstekens bevatten (?,&,%).
?, &, %) buiten segmenten tussen aanhalingstekens, predicaatsegmenten of unionsegmenten
worden geweigerd. Besturingstekens (U+0000-U+001F, U+007F) worden
overal geweigerd, inclusief 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.
Harde limieten: een pad is beperkt tot 4096 bytes, maximaal 4 posities (bestand/sectie/item/
veld), maximaal 64 met punten gescheiden subsegmenten per positie en maximaal 256 geneste
traversalniveaus voor diepe JSON-paden. Daarnaast wordt elk JSONC/JSON-invoerbestand
groter dan 16 MiB geweigerd met een parsediagnose in plaats van geparseerd, voor
elk werkwoord dat dat bestand laadt.
Adressering per bestandstype
resolve retourneert een gestructureerde overeenkomst: root, node, leaf of
insertion-point, met een regelnummer op basis van 1. Bladwaarden worden beschikbaar gesteld als
tekst plus een leafType, zodat pluginauteurs voorbeelden kunnen weergeven zonder
afhankelijk te zijn van de AST-vorm per type.
Mutatiecontract
set schrijft één concreet doel:
- Markdown-frontmatterwaarden en
- key: value-itemvelden zijn string- bladeren. Markdown-invoegingen voegen secties, frontmatter-sleutels of sectie- items toe en renderen een canonieke Markdown-vorm voor het gewijzigde bestand. Sectie- inhoud kan niet als geheel worden geschreven viaset. - Bij het schrijven van JSONC-bladeren wordt de stringwaarde geconverteerd naar het bestaande bladtype
(
string, eindigenumber,true/falseofnull). Gebruik--value-jsonwanneer een vervanging van een JSONC-/JSON-/JSONL-blad<value>als JSON moet parseren en de structuur mag wijzigen, bijvoorbeeld wanneer een verkorte stringnotatie voor een geheime referentie wordt vervangen door een object. Bij invoegingen in JSONC-objecten en -arrays wordt<value>als JSON geparseerd en wordt hetjsonc-parser-bewerkingspad gebruikt voor gewone schrijfbewerkingen van bladeren, waarbij opmerkingen en nabijgelegen opmaak behouden blijven. - Bij het schrijven van JSONL-bladeren wordt binnen een regel geconverteerd zoals bij JSONC. Bij vervanging
van een volledige regel en bij toevoegen wordt
<value>als JSON geparseerd. Gerenderde JSONL behoudt de dominante LF-/CRLF-conventie voor regeleinden van het bestand (meerderheidsbesluit over alle regeleinden in het bestand, zodat een bestand met voornamelijk CRLF CRLF blijft gebruiken, zelfs met enkele afwijkende LF’s). - Bij het schrijven van YAML-bladeren wordt geconverteerd naar het bestaande scalaire type (
string, eindigenumber,true/falseofnull). YAML-invoegingen gebruiken de document-API van het meegeleverdeyaml-pakket voor updates van mappings/reeksen. Ongeldige YAML- documenten met parserfouten worden vóór wijziging geweigerd metparse-error.
--dry-run vóór voor gebruikers zichtbare schrijfbewerkingen wanneer de exacte bytes van belang zijn. JSONC-
en YAML-bewerkingen passen het bestaande document aan (via jsonc-parser of de
document-API van yaml), zodat onaangeraakte bytes doorgaans behouden blijven; bij elke bewerking bouwt Markdown het bestand
opnieuw op vanuit de geparseerde structuur, waardoor bijkomstige
opmaak buiten het gewijzigde blad kan worden genormaliseerd. Voeg --diff toe wanneer je het voorbeeld
als een gerichte voor/na-patch wilt zien 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.Markdown
[frontmatter] adresseert het YAML-frontmatterblok; tools
komt via de slug overeen met de kop ## Tools, en itembladeren behouden hun slugvorm,
zelfs wanneer de bron underscores gebruikt (send_email wordt send-email).
JSONC
jsonc-parser, zodat opmerkingen en witruimte een
set overleven. Voer eerst uit met --dry-run om de bytes te controleren voordat je de wijziging definitief maakt.
.json-bestanden gebruiken dezelfde adapter en hetzelfde bewerkingspad als .jsonc.
JSONL
[event=action]) wanneer je
het regelnummer niet weet, of met het canonieke LN-segment wanneer je het wel weet.
.ndjson-bestanden gebruiken dezelfde adapter als .jsonl.
YAML
Document-API van het yaml-pakket in plaats van een zelfgeschreven
parser, zodat gewone parseer-/render-roundtrips opmerkingen en de door de auteur gekozen
vorm behouden, terwijl opgeloste paden hetzelfde model voor mapping-sleutels/reeksindexen gebruiken als
JSONC. Dezelfde adapter verwerkt .yaml-, .yml- en .lobster-bestanden.
Naslag voor subopdrachten
resolve <oc-path>
Lees één blad of knooppunt. Jokertekens worden geweigerd — gebruik daarvoor find.
Eindigt met 0 bij een overeenkomst, 1 bij een reguliere misser en 2 bij een parseerfout of geweigerd
patroon.
find <pattern>
Som elke overeenkomst voor een jokerteken-/predicaat-/uniepatroon op. Eindigt met 0
bij ten minste één overeenkomst en 1 bij nul overeenkomsten. Jokertekens voor bestandsposities worden geweigerd met
OC_PATH_FILE_WILDCARD_UNSUPPORTED — geef een concreet bestand door (globben over meerdere
bestanden is een toekomstige functie).
set <oc-path> <value>
Schrijf een blad. Combineer met --dry-run om een voorbeeld te bekijken van de bytes die zouden worden
geschreven zonder het bestand te wijzigen. Voeg --diff toe voor een voorbeeld als unified diff.
Eindigt met 0 na een geslaagde schrijfbewerking, 1 als de onderlaag weigert (bijvoorbeeld wanneer
een sentinel-beveiliging wordt geactiveerd) en 2 bij parseerfouten.
+key maakt het genoemde kind aan als dit nog niet
bestaat; +nnn en de losse + werken respectievelijk voor geïndexeerd invoegen en toevoegen.
validate <oc-path>
Controleert alleen het parseren. Geen toegang tot het bestandssysteem. Handig wanneer je wilt bevestigen dat een
sjabloonpad correct is gevormd voordat je variabelen vervangt, of wanneer je
de structurele uitsplitsing nodig hebt voor foutopsporing:
0 indien geldig, 1 indien ongeldig (met een gestructureerde code en
message) en 2 bij argumentfouten.
emit <file>
Voer een bestand door de parser en emitter voor het betreffende type voor een roundtrip. De uitvoer hoort
byte-identiek te zijn aan de invoer bij een geldig bestand; een afwijking wijst op een
parserfout of een geactiveerde sentinel. Handig voor het opsporen van problemen met het gedrag van de onderlaag bij
praktijkinvoer.
Afsluitcodes
Uitvoermodus
openclaw path houdt rekening met TTY: voor mensen leesbare uitvoer in een terminal, JSON wanneer
stdout via een pipe wordt doorgegeven of wordt omgeleid. --json en --human overschrijven de
automatische detectie.
Opmerkingen
setschrijft bytes via het emit-pad van de onderliggende laag, dat automatisch de bewaking met de redactiesentinel toepast. Een leaf die__OPENCLAW_REDACTED__bevat (letterlijk of als subtekenreeks), wordt tijdens het schrijven geweigerd.- Voor JSONC-parsing en het bewerken van leafs wordt de Plugin-lokale afhankelijkheid
jsonc-parsergebruikt, zodat opmerkingen en opmaak bij normale schrijfbewerkingen van leafs behouden blijven in plaats van via een handmatig gebouwde parser en een pad voor opnieuw renderen te lopen. pathhoudt geen rekening met het bijhouden of herstellen van de laatst bekende werkende configuratie (LKG); die levenscyclus wordt elders beheerd. Als een bestand dat je viapathbewerkt ook door LKG wordt bijgehouden, bepaalt de volgende configuratielezing of het wordt overgenomen of hersteld; behandel een bewerking viapathhetzelfde als elke andere directe schrijfbewerking naar dat bestand.