openclaw path
Accès shell fourni par un plugin au substrat d’adressage oc:// : un schéma de chemin
réparti par type pour inspecter et modifier les fichiers adressables de l’espace de travail
(markdown, jsonc, jsonl, yaml/yml/lobster). Les personnes qui auto-hébergent, les auteurs de
plugins et les extensions d’éditeur l’utilisent pour lire, trouver ou mettre à jour un emplacement
précis sans écrire à la main des parseurs propres à chaque type de fichier.
La CLI reflète les verbes publics du substrat :
resolveest concret et correspond à un seul résultat.findest le verbe à correspondances multiples pour les jokers, unions, prédicats et expansions positionnelles.setn’accepte que les chemins concrets ou les marqueurs d’insertion ; les motifs avec joker sont rejetés avant l’écriture.
path est fourni par le plugin optionnel inclus oc-path. Activez-le avant la
première utilisation :
Pourquoi l’utiliser
L’état d’OpenClaw est réparti entre du markdown modifié par des humains, de la configuration JSONC commentée, des journaux JSONL en ajout seul et des fichiers de workflow/spécification YAML. Les scripts shell, hooks et agents ont souvent besoin d’une petite valeur dans ces fichiers : une clé de frontmatter, un paramètre de plugin, un champ d’enregistrement de journal, une étape YAML ou un élément de liste sous une section nommée.openclaw path donne à ces appelants une adresse stable au lieu d’un grep,
d’une regex ou d’un parseur ponctuel pour chaque type de fichier. Le même chemin oc:// peut être validé,
résolu, recherché, testé à blanc et écrit depuis le terminal, ce qui rend l’automatisation ciblée
plus facile à relire et plus sûre à rejouer. Il est particulièrement utile lorsque
vous voulez mettre à jour une seule feuille tout en préservant le reste des commentaires du fichier,
ses fins de ligne et la mise en forme environnante.
Utilisez-le lorsque ce que vous voulez a une adresse logique, mais que la forme physique du fichier
varie :
- Un hook veut lire un paramètre dans du JSONC commenté sans perdre les commentaires lorsqu’il réécrit la valeur.
- Un script de maintenance veut trouver tous les champs d’événements correspondants dans un journal JSONL sans charger tout le journal dans un parseur personnalisé.
- Une extension d’éditeur veut accéder à une section markdown ou à un élément de liste par slug, puis afficher la ligne exacte vers laquelle il a été résolu.
- Un agent veut tester à blanc une minuscule modification de l’espace de travail avant de l’appliquer, avec les octets modifiés visibles lors de la revue.
openclaw path pour les modifications ordinaires de fichiers entiers, les migrations
riches de configuration ou les écritures propres à la mémoire. Celles-ci doivent utiliser la commande
ou le plugin propriétaire. path sert aux petites opérations de fichiers adressables où une
commande terminal répétable est plus claire qu’un autre parseur sur mesure.
Comment il est utilisé
Lire une valeur dans un fichier de configuration modifié par des humains :--json lorsqu’un
appelant a besoin d’une sortie structurée et --human lorsqu’une personne inspecte le
résultat.
Fonctionnement
openclaw path fait quatre choses :
- Analyse l’adresse
oc://en emplacements : fichier, section, élément, champ et session facultative. - Choisit l’adaptateur de type de fichier à partir de l’extension cible (
.md,.jsonc,.jsonl,.yaml,.yml,.lobsteret alias associés). - Résout les emplacements par rapport à l’AST de ce type de fichier : titres/éléments markdown, clés d’objet/index de tableau JSONC, enregistrements de lignes JSONL ou nœuds de mappage/séquence YAML.
- Pour
set, émet les octets modifiés via le même adaptateur afin que les parties intactes du fichier conservent leurs commentaires, fins de ligne et mise en forme proche lorsque le type le prend en charge.
resolve et set exigent une cible concrète unique. find est le verbe exploratoire :
il développe les jokers, unions, prédicats et ordinaux en correspondances concrètes
que vous pouvez inspecter avant d’en choisir une à écrire.
Sous-commandes
| Sous-commande | Objectif |
|---|---|
resolve <oc-path> | Afficher la correspondance concrète au chemin (ou « not found »). |
find <pattern> | Énumérer les correspondances d’un chemin avec joker / union / prédicat. |
set <oc-path> <value> | Écrire une feuille ou une cible d’insertion à un chemin concret. Prend en charge --dry-run. |
validate <oc-path> | Analyse seule ; afficher la décomposition structurelle (fichier / section / élément / champ). |
emit <file> | Faire un aller-retour d’un fichier via parseXxx + emitXxx (diagnostic de fidélité des octets). |
Options globales
| Option | Objectif |
|---|---|
--cwd <dir> | Résoudre l’emplacement fichier par rapport à ce répertoire (par défaut : process.cwd()). |
--file <path> | Remplacer le chemin résolu de l’emplacement fichier (accès absolu). |
--json | Forcer la sortie JSON (par défaut lorsque stdout n’est pas un TTY). |
--human | Forcer la sortie humaine (par défaut lorsque stdout est un TTY). |
--dry-run | (uniquement sur set) afficher les octets qui seraient écrits sans écrire. |
--diff | (avec set --dry-run) afficher un diff unifié au lieu des octets complets. |
Syntaxe oc://
field exige item, et item exige section. Sur les
quatre emplacements :
- Segments entre guillemets —
"a/b.c"préserve les séparateurs/et.. Le contenu est littéral au niveau des octets ;"et\ne sont pas autorisés dans les guillemets. L’emplacement fichier tient aussi compte des guillemets :oc://"skills/email-drafter"/Tools/$lasttraiteskills/email-draftercomme un seul chemin de fichier. - Prédicats —
[k=v],[k!=v],[k<v],[k<=v],[k>v],[k>=v]. Les opérations numériques exigent que les deux côtés se convertissent en nombres finis. - Unions —
{a,b,c}correspond à n’importe laquelle des alternatives. - Jokers —
*(un seul sous-segment) et**(zéro ou plus, récursif).findles accepte ;resolveetsetles rejettent comme ambigus. - Positionnel —
$first/$lastse résolvent au premier / dernier index ou à la clé déclarée. - Ordinal —
#Npour la Nième correspondance selon l’ordre du document. - Marqueurs d’insertion —
+,+key,+nnnpour l’insertion avec clé / index (à utiliser avecset). - Portée de session —
?session=cron-daily, etc. Orthogonale à l’imbrication des emplacements. Les valeurs de session sont brutes, non décodées en pourcentage ; elles ne peuvent pas contenir de caractères de contrôle ni de délimiteurs de requête réservés (?,&,%).
?, &, %) hors des segments entre guillemets, de prédicat ou d’union
sont rejetés. Les caractères de contrôle (U+0000-U+001F, U+007F) sont rejetés
partout, y compris dans la valeur de requête session.
formatOcPath(parseOcPath(path)) === path est garanti pour les chemins canoniques.
Les paramètres de requête non canoniques sont ignorés, sauf pour la première valeur
session= non vide.
Adressage par type de fichier
| Type | Modèle d’adressage |
|---|---|
| Markdown | Sections H2 par slug, éléments de liste par slug ou #N, frontmatter via [frontmatter]. |
| JSONC/JSON | Clés d’objet et index de tableau ; les points découpent les sous-segments imbriqués sauf guillemets. |
| JSONL | Adresses de lignes de premier niveau (L1, L2, $first, $last), puis descente de style JSONC dans la ligne. |
| YAML/YML/.lobster | Clés de mappage et index de séquence ; les commentaires et le style en flux sont gérés par l’API de document YAML. |
resolve renvoie une correspondance structurée : root, node, leaf ou
insertion-point, avec un numéro de ligne basé sur 1. Les valeurs feuilles sont exposées sous forme de texte
plus un leafType afin que les auteurs de plugins puissent afficher des prévisualisations sans dépendre
de la forme d’AST propre à chaque type.
Contrat de mutation
set écrit une cible concrète unique :
- Les valeurs de frontmatter markdown et les champs d’élément
- key: valuesont des feuilles de chaîne. Les insertions markdown ajoutent des sections, des clés de frontmatter ou des éléments de section et produisent une forme markdown canonique pour le fichier modifié. - Les écritures de feuilles JSONC convertissent la valeur chaîne vers le type de feuille existant
(
string,numberfini,true/falseounull). Utilisez--value-jsonlorsqu’un remplacement de feuille JSONC/JSON/JSONL doit analyser<value>comme JSON et peut changer de forme, par exemple le remplacement d’un raccourci SecretRef sous forme de chaîne par un objet. Les insertions d’objet et de tableau JSONC analysent<value>comme JSON et utilisent le chemin d’éditionjsonc-parserpour les écritures ordinaires de feuilles, en préservant les commentaires et la mise en forme proche. - Les écritures de feuilles JSONL se convertissent comme JSONC à l’intérieur d’une ligne. Le remplacement de ligne entière et
l’ajout analysent
<value>comme JSON. Le JSONL rendu préserve la convention dominante de fins de ligne LF/CRLF du fichier. - Les écritures de feuilles YAML convertissent vers le type scalaire existant (
string,numberfini,true/falseounull). Les insertions YAML utilisent l’API de document du paquetyamlinclus pour les mises à jour de mappage/séquence. Les documents YAML mal formés avec erreurs de parseur sont refusés avant mutation avecparse-error.
--dry-run avant les écritures visibles par l’utilisateur lorsque les octets exacts comptent. Le
substrat préserve une sortie identique au niveau des octets pour les allers-retours parse/emit, mais une
mutation peut canonicaliser la région modifiée ou le fichier selon le type.
Ajoutez --diff lorsque vous voulez la prévisualisation sous forme de patch avant/après ciblé plutôt
que le fichier rendu complet.
Exemples
Recettes par type de fichier
Les cinq mêmes verbes fonctionnent pour tous les types ; le schéma d’adressage se répartit selon l’extension du fichier. Les exemples ci-dessous utilisent les fixtures de la description de la PR.Markdown
[frontmatter] adresse le bloc YAML frontmatter ; tools
correspond à l’en-tête ## Tools via le slug, et les feuilles d’éléments conservent leur forme de slug
même lorsque la source utilise des underscores (send_email → send-email).
JSONC
jsonc-parser, donc les commentaires et les espaces survivent à un
set. Exécutez d’abord avec --dry-run pour inspecter les octets avant de valider.
JSONL
[event=action]) lorsque vous ne
connaissez pas le numéro de ligne, ou par le segment canonique LN lorsque vous le connaissez.
YAML
Document du package yaml plutôt qu’un analyseur écrit à la main,
donc les allers-retours ordinaires analyse/émission préservent les commentaires et la forme de rédaction tandis que
les chemins résolus utilisent le même modèle clé de map / index de séquence que JSONC. Le même
adaptateur gère les fichiers .yaml, .yml et .lobster.
Référence des sous-commandes
resolve <oc-path>
Lit une seule feuille ou un seul nœud. Les jokers sont rejetés — utilisez find pour ceux-ci.
Se termine avec 0 en cas de correspondance, 1 en cas d’absence propre, 2 en cas d’erreur d’analyse ou de motif refusé.
find <pattern>
Énumère chaque correspondance pour un motif joker / prédicat / union. Se termine avec 0
s’il y a au moins une correspondance, 1 s’il n’y en a aucune. Les jokers d’emplacement de fichier sont rejetés avec
OC_PATH_FILE_WILDCARD_UNSUPPORTED — passez un fichier concret (le globbing multifichier
est une fonctionnalité ultérieure).
set <oc-path> <value>
Écrit une feuille. Associez avec --dry-run pour prévisualiser les octets qui seraient
écrits sans toucher au fichier. Ajoutez --diff pour une prévisualisation en diff unifié.
Se termine avec 0 après une écriture réussie, 1 si le substrat refuse (par exemple, si une
garde sentinelle est déclenchée), 2 en cas d’erreurs d’analyse.
+key crée l’enfant nommé s’il n’existe pas déjà ;
+nnn et + seul fonctionnent respectivement pour l’insertion indexée et l’ajout.
validate <oc-path>
Vérification d’analyse uniquement. Aucun accès au système de fichiers. Utile lorsque vous voulez confirmer qu’un
chemin de modèle est bien formé avant de substituer des variables, ou lorsque vous voulez
la décomposition structurelle pour le débogage :
0 lorsque c’est valide, 1 lorsque c’est invalide (avec un code et un
message structurés), 2 en cas d’erreurs d’arguments.
emit <file>
Fait passer un fichier en aller-retour par l’analyseur et l’émetteur propres à son type. La sortie doit
être identique octet pour octet à l’entrée sur un fichier sain — une divergence indique un
bogue d’analyseur ou une sentinelle déclenchée. Utile pour déboguer le comportement du substrat sur
des entrées réelles.
Codes de sortie
| Code | Signification |
|---|---|
0 | Succès. (resolve / find : au moins une correspondance. set : écriture réussie.) |
1 | Aucune correspondance, ou set rejeté par le substrat (pas d’erreur au niveau système). |
2 | Erreur d’argument ou d’analyse. |
Mode de sortie
openclaw path détecte le TTY : sortie lisible par un humain dans un terminal, JSON lorsque
stdout est redirigé ou envoyé dans un pipe. --json et --human remplacent
l’auto-détection.
Notes
setécrit les octets via le chemin d’émission du substrat, qui applique automatiquement la garde de sentinelle de caviardage. Une feuille contenant__OPENCLAW_REDACTED__(verbatim ou comme sous-chaîne) est refusée au moment de l’écriture.- L’analyse JSONC et les modifications de feuilles utilisent la dépendance
jsonc-parserlocale au Plugin, donc les commentaires et la mise en forme sont préservés lors des écritures de feuilles ordinaires au lieu de passer par un chemin analyseur/rendu écrit à la main. pathne connaît pas LKG. Si le fichier est suivi par LKG, le prochain appel observe décide s’il faut promouvoir / récupérer.set --batchpour des ensembles multiples atomiques via le cycle de vie de promotion/récupération LKG est prévu avec le substrat de récupération LKG.