Skip to main content

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:
De CLI-werkwoorden weerspiegelen het adresseringsmodel:
  • resolve is concreet en levert één overeenkomst op.
  • find is het werkwoord voor meerdere overeenkomsten bij jokertekens, unions, predicaten en positionele uitbreiding.
  • set accepteert alleen concrete paden of invoegmarkeringen; patronen met jokertekens worden vóór het schrijven geweigerd.
  • validate parseert een pad zonder bestandssysteemtoegang.
  • emit voert 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.
Gebruik 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:
Bekijk een schrijfbewerking zonder de schijf te wijzigen:
Zoek overeenkomende records in een alleen-toevoegen-JSONL-logboek:
Adresseer een instructie in markdown op sectie en item in plaats van op regelnummer:
Valideer een pad in CI of een preflightscript voordat het script leest of schrijft:
Deze opdrachten zijn bedoeld om naar shellscripts te kunnen worden gekopieerd. Gebruik --json wanneer een aanroeper gestructureerde uitvoer nodig heeft en --human wanneer iemand het resultaat inspecteert.

Werking

  1. Parseert het oc://-adres in posities: bestand, sectie, item, veld en een optionele sessiequery.
  2. Kiest de adapter voor het bestandstype op basis van de extensie van het doel (.md, .jsonc, .json, .jsonl, .ndjson, .yaml, .yml, .lobster).
  3. 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.
  4. Voor set voert 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

Regels voor posities: 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/$last behandelt skills/email-drafter als éé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). find accepteert deze; resolve en set weigeren ze als ambigu.
  • Positioneel$first / $last worden opgelost naar de eerste / laatste index of gedeclareerde sleutel.
  • Rangnummer#N voor de N-de overeenkomst in documentvolgorde.
  • Invoegmarkeringen+, +key, +nnn voor invoeging op sleutel / index (te gebruiken met set).
  • Sessiebereik?session=cron-daily enzovoort. Staat los van de nesting van posities. Sessiewaarden zijn onbewerkt en niet procentgedecodeerd; ze mogen geen besturings- tekens of gereserveerde queryscheidingstekens bevatten (?, &, %).
Gereserveerde tekens (?, &, %) 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 via set.
  • Bij het schrijven van JSONC-bladeren wordt de stringwaarde geconverteerd naar het bestaande bladtype (string, eindige number, true/false of null). Gebruik --value-json wanneer 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 het jsonc-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, eindige number, true/false of null). YAML-invoegingen gebruiken de document-API van het meegeleverde yaml-pakket voor updates van mappings/reeksen. Ongeldige YAML- documenten met parserfouten worden vóór wijziging geweigerd met parse-error.
Gebruik --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

Meer grammaticavoorbeelden:

Recepten per bestandstype

Dezelfde vijf werkwoorden werken voor alle typen; het adresseringsschema kiest op basis van de bestandsextensie.

Markdown

Het predicaat [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-bewerkingen verlopen via 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

Elke regel is een record. Adresseer met een predicaat ([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

YAML gebruikt de 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.
De invoegmarkering +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:
Eindigt met 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

  • set schrijft 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-parser gebruikt, 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.
  • path houdt geen rekening met het bijhouden of herstellen van de laatst bekende werkende configuratie (LKG); die levenscyclus wordt elders beheerd. Als een bestand dat je via path bewerkt ook door LKG wordt bijgehouden, bepaalt de volgende configuratielezing of het wordt overgenomen of hersteld; behandel een bewerking via path hetzelfde als elke andere directe schrijfbewerking naar dat bestand.

Gerelateerd