openclaw path
Vom Plugin bereitgestellter Shell-Zugriff auf das oc://-Adressierungssubstrat: ein nach Art dispatchtes Pfadschema zum Prüfen und Bearbeiten adressierbarer Workspace-Dateien (markdown, jsonc, jsonl, yaml/yml/lobster). Self-Hoster, Plugin-Autoren und Editor-Erweiterungen verwenden es, um einen eng umrissenen Speicherort zu lesen, zu finden oder zu aktualisieren, ohne pro Dateityp eigene Parser zu schreiben.
Die CLI spiegelt die öffentlichen Verben des Substrats:
resolveist konkret und liefert genau einen Treffer.findist das Mehrfachtreffer-Verb für Platzhalter, Vereinigungen, Prädikate und positionale Erweiterung.setakzeptiert nur konkrete Pfade oder Einfügemarker; Platzhaltermuster werden vor dem Schreiben abgelehnt.
path wird vom gebündelten optionalen oc-path-Plugin bereitgestellt. Aktivieren Sie es vor der ersten Verwendung:
Warum Sie es verwenden sollten
OpenClaw-Zustand ist über von Menschen bearbeitetes Markdown, kommentierte JSONC-Konfiguration, nur angehängte JSONL-Logs und YAML-Workflow-/Spezifikationsdateien verteilt. Shell-Skripte, Hooks und Agenten benötigen aus diesen Dateien häufig einen einzelnen kleinen Wert: einen Frontmatter-Schlüssel, eine Plugin-Einstellung, ein Log-Datensatzfeld, einen YAML-Schritt oder einen Aufzählungspunkt unter einem benannten Abschnitt.openclaw path gibt diesen Aufrufern eine stabile Adresse statt eines einmaligen grep, Regex oder Parsers für jeden Dateityp. Derselbe oc://-Pfad kann im Terminal validiert, aufgelöst, gesucht, als Trockenlauf ausgeführt und geschrieben werden. Dadurch wird eng umrissene Automatisierung leichter zu prüfen und sicherer erneut auszuführen. Besonders nützlich ist es, wenn Sie ein einzelnes Blatt aktualisieren möchten, während die übrigen Kommentare, Zeilenenden und umgebende Formatierung der Datei erhalten bleiben.
Verwenden Sie es, wenn das gewünschte Objekt eine logische Adresse hat, die physische Dateiform aber variiert:
- Ein Hook möchte eine Einstellung aus kommentiertem JSONC lesen, ohne beim Zurückschreiben des Werts Kommentare zu verlieren.
- Ein Wartungsskript möchte jedes passende Ereignisfeld in einem JSONL-Log finden, ohne das gesamte Log in einen eigenen Parser zu laden.
- Eine Editor-Erweiterung möchte per Slug zu einem Markdown-Abschnitt oder Aufzählungspunkt springen und dann die exakt aufgelöste Zeile rendern.
- Ein Agent möchte eine kleine Workspace-Bearbeitung vor der Anwendung als Trockenlauf ausführen, wobei die geänderten Bytes in der Prüfung sichtbar sind.
openclaw path wahrscheinlich nicht. Diese sollten den zuständigen Befehl oder das zuständige Plugin verwenden. path ist für kleine, adressierbare Dateioperationen gedacht, bei denen ein wiederholbarer Terminalbefehl klarer ist als ein weiterer spezieller Parser.
Verwendung
Einen Wert aus einer von Menschen bearbeiteten Konfigurationsdatei lesen:--json, wenn ein Aufrufer strukturierte Ausgabe benötigt, und --human, wenn eine Person das Ergebnis prüft.
Funktionsweise
openclaw path erledigt vier Dinge:
- Es parst die
oc://-Adresse in Slots: Datei, Abschnitt, Element, Feld und optionale Sitzung. - Es wählt den Dateityp-Adapter anhand der Zielerweiterung (
.md,.jsonc,.jsonl,.yaml,.yml,.lobsterund zugehörige Aliase). - Es löst die Slots gegen den AST dieses Dateityps auf: Markdown-Überschriften/-Elemente, JSONC-Objektschlüssel/-Array-Indizes, JSONL-Zeilendatensätze oder YAML-Map-/Sequenzknoten.
- Für
setgibt es bearbeitete Bytes über denselben Adapter aus, sodass unveränderte Teile der Datei ihre Kommentare, Zeilenenden und nahe Formatierung behalten, sofern der Typ dies unterstützt.
resolve und set erfordern ein konkretes Ziel. find ist das erkundende Verb: Es erweitert Platzhalter, Vereinigungen, Prädikate und Ordinale zu konkreten Treffern, die Sie prüfen können, bevor Sie einen zum Schreiben auswählen.
Unterbefehle
| Unterbefehl | Zweck |
|---|---|
resolve <oc-path> | Den konkreten Treffer am Pfad ausgeben (oder „nicht gefunden“). |
find <pattern> | Treffer für einen Platzhalter-/Vereinigungs-/Prädikatpfad aufzählen. |
set <oc-path> <value> | Ein Blatt oder Einfügeziel an einem konkreten Pfad schreiben. Unterstützt --dry-run. |
validate <oc-path> | Nur parsen; strukturelle Aufschlüsselung ausgeben (Datei / Abschnitt / Element / Feld). |
emit <file> | Eine Datei durch parseXxx + emitXxx roundtrippen (Byte-Treue-Diagnose). |
Globale Flags
| Flag | Zweck |
|---|---|
--cwd <dir> | Den Datei-Slot relativ zu diesem Verzeichnis auflösen (Standard: process.cwd()). |
--file <path> | Den aufgelösten Pfad des Datei-Slots überschreiben (absoluter Zugriff). |
--json | JSON-Ausgabe erzwingen (Standard, wenn stdout kein TTY ist). |
--human | Menschlich lesbare Ausgabe erzwingen (Standard, wenn stdout ein TTY ist). |
--dry-run | (nur bei set) die Bytes ausgeben, die geschrieben würden, ohne zu schreiben. |
--diff | (mit set --dry-run) einen Unified Diff statt der vollständigen Bytes ausgeben. |
oc://-Syntax
field erfordert item, und item erfordert section. Über alle vier Slots hinweg:
- Quoted segments —
"a/b.c"übersteht/- und.-Trennzeichen. Inhalt ist byte-literal;"und\sind innerhalb von Anführungszeichen nicht erlaubt. Auch der Datei-Slot beachtet Anführungszeichen:oc://"skills/email-drafter"/Tools/$lastbehandeltskills/email-drafterals einzelnen Dateipfad. - Prädikate —
[k=v],[k!=v],[k<v],[k<=v],[k>v],[k>=v]. Numerische Operationen erfordern, dass beide Seiten in endliche Zahlen umwandelbar sind. - Vereinigungen —
{a,b,c}passt auf jede der Alternativen. - Platzhalter —
*(einzelnes Untersegment) und**(null oder mehr, rekursiv).findakzeptiert diese;resolveundsetlehnen sie als mehrdeutig ab. - Positional —
$first/$lastlösen zum ersten / letzten Index oder deklarierten Schlüssel auf. - Ordinal —
#Nfür den N-ten Treffer nach Dokumentreihenfolge. - Einfügemarker —
+,+key,+nnnfür schlüsselbasierte / indexbasierte Einfügung (mitsetverwenden). - Sitzungsbereich —
?session=cron-dailyusw. Orthogonal zur Slot- Verschachtelung. Sitzungswerte sind roh, nicht prozent-dekodiert; sie dürfen keine Steuerzeichen oder reservierten Query-Trennzeichen enthalten (?,&,%).
?, &, %) außerhalb von zitierten, Prädikat- oder Vereinigungssegmenten werden abgelehnt. Steuerzeichen (U+0000-U+001F, U+007F) werden überall abgelehnt, einschließlich des session-Query-Werts.
formatOcPath(parseOcPath(path)) === path ist für kanonische Pfade garantiert. Nicht-kanonische Query-Parameter werden ignoriert, außer dem ersten nicht leeren session=-Wert.
Adressierung nach Dateityp
| Typ | Adressierungsmodell |
|---|---|
| Markdown | H2-Abschnitte nach Slug, Aufzählungspunkte nach Slug oder #N, Frontmatter über [frontmatter]. |
| JSONC/JSON | Objektschlüssel und Array-Indizes; Punkte teilen verschachtelte Untersegmente, sofern nicht zitiert. |
| JSONL | Top-Level-Zeilenadressen (L1, L2, $first, $last), dann JSONC-artiger Abstieg innerhalb der Zeile. |
| YAML/YML/.lobster | Map-Schlüssel und Sequenzindizes; Kommentare und Flow-Style werden von der YAML-Dokument-API verarbeitet. |
resolve gibt einen strukturierten Treffer zurück: root, node, leaf oder
insertion-point, mit einer 1-basierten Zeilennummer. Blattwerte werden als Text
plus leafType bereitgestellt, damit Plugin-Autoren Vorschauen rendern können, ohne von der AST-Form des jeweiligen Typs abhängig zu sein.
Mutationsvertrag
set schreibt ein konkretes Ziel:
- Markdown-Frontmatter-Werte und
- key: value-Elementfelder sind String-Blätter. Markdown-Einfügungen hängen Abschnitte, Frontmatter-Schlüssel oder Abschnittselemente an und rendern eine kanonische Markdown-Form für die geänderte Datei. - JSONC-Blattschreibvorgänge wandeln den String-Wert in den bestehenden Blatttyp um
(
string, endlichenumber,true/falseodernull). Verwenden Sie--value-json, wenn ein JSONC/JSON/JSONL-Blattersatz<value>als JSON parsen soll und die Form ändern darf, etwa beim Ersetzen einer String-SecretRef-Kurzform durch ein Objekt. JSONC-Objekt- und Array-Einfügungen parsen<value>als JSON und verwenden denjsonc-parser-Bearbeitungspfad für gewöhnliche Blattschreibvorgänge, wobei Kommentare und nahe Formatierung erhalten bleiben. - JSONL-Blattschreibvorgänge wandeln wie JSONC innerhalb einer Zeile um. Ganzzeilenersatz und
Anhängen parsen
<value>als JSON. Gerendertes JSONL bewahrt die dominierende LF/CRLF-Zeilenende-Konvention der Datei. - YAML-Blattschreibvorgänge wandeln in den bestehenden Skalartyp um (
string, endlichenumber,true/falseodernull). YAML-Einfügungen verwenden die Dokument-API des gebündeltenyaml-Pakets für Map-/Sequenzaktualisierungen. Fehlerhafte YAML-Dokumente mit Parserfehlern werden vor der Mutation mitparse-errorabgelehnt.
--dry-run vor benutzersichtbaren Schreibvorgängen, wenn die exakten Bytes wichtig sind. Das Substrat bewahrt byte-identische Ausgabe für Parse-/Emit-Roundtrips, aber eine Mutation kann je nach Typ die bearbeitete Region oder Datei kanonisieren.
Fügen Sie --diff hinzu, wenn Sie die Vorschau als fokussierten Vorher/Nachher-Patch statt als vollständig gerenderte Datei wünschen.
Beispiele
Rezepte nach Dateiart
Dieselben fünf Verben funktionieren dateiartübergreifend; das Adressierungsschema leitet anhand der Dateiendung weiter. Die folgenden Beispiele verwenden die Fixtures aus der PR-Beschreibung.Markdown
[frontmatter] adressiert den YAML-Frontmatter-Block; tools entspricht der Überschrift ## Tools über den Slug, und Item-Blätter behalten ihre Slug-Form auch dann, wenn die Quelle Unterstriche verwendet (send_email → send-email).
JSONC
jsonc-parser, sodass Kommentare und Leerraum ein set überstehen. Führen Sie zuerst mit --dry-run aus, um die Bytes vor dem Übernehmen zu prüfen.
JSONL
[event=action]), wenn Sie die Zeilennummer nicht kennen, oder über das kanonische Segment LN, wenn Sie sie kennen.
YAML
Document-API des Pakets yaml statt eines selbstgebauten Parsers, sodass gewöhnliche Parse/Emit-Roundtrips Kommentare und Autorenstruktur bewahren, während aufgelöste Pfade dasselbe Map-Key-/Sequence-Index-Modell wie JSONC verwenden. Derselbe Adapter verarbeitet Dateien mit .yaml, .yml und .lobster.
Subcommand-Referenz
resolve <oc-path>
Liest ein einzelnes Blatt oder einen einzelnen Knoten. Wildcards werden abgelehnt — verwenden Sie dafür find. Beendet mit 0 bei einem Treffer, 1 bei einem sauberen Fehltreffer, 2 bei einem Parse-Fehler oder verweigerten Muster.
find <pattern>
Listet jeden Treffer für ein Wildcard-/Prädikat-/Union-Muster auf. Beendet mit 0 bei mindestens einem Treffer, 1 bei null Treffern. Datei-Slot-Wildcards werden mit OC_PATH_FILE_WILDCARD_UNSUPPORTED abgelehnt — übergeben Sie eine konkrete Datei (Multi-File-Globbing ist ein Folge-Feature).
set <oc-path> <value>
Schreibt ein Blatt. Kombinieren Sie dies mit --dry-run, um die Bytes vorzuschauen, die geschrieben würden, ohne die Datei zu berühren. Fügen Sie --diff für eine Vorschau als Unified Diff hinzu. Beendet mit 0 bei erfolgreichem Schreiben, 1, wenn das Substrat verweigert (zum Beispiel bei ausgelöstem Sentinel-Schutz), 2 bei Parse-Fehlern.
+key erstellt das benannte Kind, wenn es noch nicht existiert; +nnn und das bloße + funktionieren für indexiertes beziehungsweise anhängendes Einfügen.
validate <oc-path>
Nur-Parse-Prüfung. Kein Dateisystemzugriff. Nützlich, wenn Sie bestätigen möchten, dass ein Template-Pfad wohlgeformt ist, bevor Variablen eingesetzt werden, oder wenn Sie die strukturelle Zerlegung zum Debuggen benötigen:
0, wenn gültig, 1, wenn ungültig (mit strukturiertem code und message), 2 bei Argumentfehlern.
emit <file>
Führt eine Datei durch den Parser und Emitter der jeweiligen Art als Roundtrip. Die Ausgabe sollte bei einer intakten Datei byteidentisch mit der Eingabe sein — Abweichungen deuten auf einen Parser-Bug oder einen Sentinel-Treffer hin. Nützlich zum Debuggen des Substratverhaltens bei realen Eingaben.
Exit-Codes
| Code | Bedeutung |
|---|---|
0 | Erfolg. (resolve / find: mindestens ein Treffer. set: Schreiben erfolgreich.) |
1 | Kein Treffer, oder set wurde vom Substrat abgelehnt (kein Fehler auf Systemebene). |
2 | Argument- oder Parse-Fehler. |
Ausgabemodus
openclaw path ist TTY-bewusst: menschenlesbare Ausgabe in einem Terminal, JSON, wenn stdout gepiped oder umgeleitet wird. --json und --human überschreiben die automatische Erkennung.
Hinweise
setschreibt Bytes über den Emit-Pfad des Substrats, der den Redaction-Sentinel-Schutz automatisch anwendet. Ein Blatt, das__OPENCLAW_REDACTED__trägt (wörtlich oder als Teilzeichenfolge), wird beim Schreiben verweigert.- JSONC-Parsing und Blatt-Bearbeitungen verwenden die Plugin-lokale Abhängigkeit
jsonc-parser, sodass Kommentare und Formatierung bei gewöhnlichen Blatt-Schreibvorgängen erhalten bleiben, statt über einen selbstgebauten Parser/Re-Render-Pfad zu laufen. pathkennt LKG nicht. Wenn die Datei per LKG verfolgt wird, entscheidet der nächste Observe-Aufruf, ob promote / recover ausgeführt wird.set --batchfür atomare Multi-Set-Vorgänge durch den LKG-promote/recover-Lebenszyklus ist zusammen mit dem LKG-Recovery-Substrat geplant.