Plugin OC Path

Le plugin oc-path fourni ajoute la CLI openclaw path pour le schéma d’adressage des fichiers d’espace de travail oc://. Il est livré dans le dépôt OpenClaw sous extensions/oc-path/, mais il est optionnel : l’installation/la compilation le laisse inactif jusqu’à ce que vous l’activiez.

Les adresses oc:// pointent vers une seule feuille (ou un ensemble de feuilles avec joker) dans un fichier d’espace de travail. Le plugin comprend aujourd’hui trois types de fichiers :

• markdown (.md, .mdx) : frontmatter, sections, éléments, champs
• jsonc (.jsonc, .json5, .json) : commentaires et mise en forme préservés
• jsonl (.jsonl, .ndjson) : enregistrements orientés ligne

Les auto-hébergeurs et les extensions d’éditeur utilisent la CLI pour lire ou écrire une seule feuille sans scripter directement contre le SDK ; les agents et les hooks la traitent comme un substrat déterministe afin que les allers-retours avec fidélité des octets et la garde de sentinelle de caviardage s’appliquent uniformément à tous les types.

# Pourquoi l’activer

Activez oc-path lorsque vous voulez que des scripts, des hooks ou des outils d’agent locaux pointent vers une portion précise de l’état de l’espace de travail sans inventer un analyseur pour chaque forme de fichier. Une seule adresse oc:// peut nommer une clé de frontmatter markdown, un élément de section, une feuille de configuration JSONC ou un champ d’événement JSONL.

C’est important pour les workflows de mainteneurs où le changement doit être petit, auditable et reproductible : inspecter une valeur, trouver les enregistrements correspondants, simuler une écriture, puis appliquer seulement cette feuille tout en laissant les commentaires, les fins de ligne et la mise en forme voisine intacts. Garder cela comme plugin optionnel donne aux utilisateurs avancés le substrat d’adressage sans placer les dépendances d’analyse ou la surface CLI dans le cœur pour les installations qui n’en ont jamais besoin.

Raisons courantes de l’activer :

• Automatisation locale : les scripts shell peuvent résoudre ou mettre à jour une valeur d’espace de travail avec openclaw path … --json au lieu d’embarquer du code d’analyse markdown, JSONC et JSONL séparé.
• Modifications visibles par l’agent : un agent peut afficher une diff de simulation pour une feuille adressée avant d’écrire, ce qui est plus facile à relire qu’une réécriture de fichier libre.
• Intégrations d’éditeur : un éditeur peut mapper oc://AGENTS.md/tools/gh vers le nœud markdown et le numéro de ligne exacts sans deviner à partir du texte de titre.
• Diagnostics : emit fait passer un fichier par l’analyseur et l’émetteur, afin que vous puissiez vérifier si un type de fichier est stable au niveau des octets avant de compter sur des modifications automatisées.

Exemples concrets :

# Is the GitHub plugin enabled in this config?
openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json

# Which tool-call names appear in this session log?
openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json

# What bytes would this tiny config edit write?
openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

Le plugin n’est intentionnellement pas propriétaire des sémantiques de plus haut niveau. Les plugins de mémoire restent propriétaires des écritures mémoire, les commandes de configuration restent propriétaires de la gestion complète de la configuration, et la logique LKG reste propriétaire de la restauration/promotion. oc-path est la couche étroite d’adressage et d’opérations de fichier préservant les octets autour de laquelle ces outils de plus haut niveau peuvent construire.

# Où il s’exécute

Le plugin s’exécute dans le processus de la CLI openclaw sur l’hôte où vous invoquez la commande. Il n’a pas besoin d’un Gateway en cours d’exécution et n’ouvre aucun socket réseau : chaque verbe est une transformation pure sur un fichier que vous indiquez.

Les métadonnées du plugin vivent dans extensions/oc-path/openclaw.plugin.json :

{
  "id": "oc-path",
  "name": "OC Path",
  "activation": {
    "onStartup": false,
    "onCommands": ["path"]
  },
  "commandAliases": [{ "name": "path", "kind": "cli" }]
}

onStartup: false garde le plugin hors du chemin chaud du Gateway. onCommands: ["path"] indique à la CLI de charger le plugin paresseusement la première fois que vous exécutez openclaw path …, de sorte que les installations qui n’utilisent jamais le verbe ne paient aucun coût.

# Activer

openclaw plugins enable oc-path

Redémarrez le Gateway (si vous en exécutez un) afin que l’instantané de manifeste prenne en compte le nouvel état. Les invocations brutes de openclaw path fonctionnent immédiatement sur le même hôte : la CLI charge le plugin à la demande.

Désactivez avec :

openclaw plugins disable oc-path

# Dépendances

Toutes les dépendances d’analyse sont locales au plugin : activer oc-path n’ajoute pas de nouveaux paquets au runtime cœur :

Dépendance	Objectif
commander	Câblage des sous-commandes pour resolve, find, set, validate, emit.
jsonc-parser	Analyse JSONC + modifications de feuilles avec commentaires et virgules finales conservés.
markdown-it	Tokenisation Markdown pour le modèle section / élément / champ.

JSONL reste fait à la main : l’analyse orientée ligne est plus simple que n’importe quelle dépendance, et l’analyse JSONC ligne par ligne passe déjà par jsonc-parser.

# Ce qu’il fournit

Surface	Fourni par
CLI openclaw path	extensions/oc-path/cli-registration.ts
Analyseur / formateur oc://	extensions/oc-path/src/oc-path/oc-path.ts
Analyse / émission / modification par type	extensions/oc-path/src/oc-path/{md,jsonc,jsonl}
Résolution / recherche / définition universelles	extensions/oc-path/src/oc-path/{resolve,find,edit}.ts
Garde de sentinelle de caviardage	extensions/oc-path/src/oc-path/sentinel.ts

La CLI est aujourd’hui la seule surface publique. Les verbes du substrat sont privés au plugin ; les consommateurs utilisent la CLI (ou construisent leur propre plugin contre le SDK).

# Relation avec les autres plugins

• memory-* : les écritures mémoire passent par les plugins de mémoire, pas par oc-path. oc-path est un substrat de fichier générique ; les plugins de mémoire superposent leurs propres sémantiques par-dessus.
• LKG : path ne connaît pas la restauration de configuration Last-Known-Good. Si un fichier est suivi par LKG, le prochain appel observe décide s’il faut promouvoir ou récupérer ; set --batch pour un multi-set atomique via le cycle de vie de promotion/récupération LKG est prévu avec le substrat de récupération LKG.

# Sécurité

set écrit des octets bruts 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 avec OC_EMIT_SENTINEL. La CLI nettoie également la sentinelle littérale de toute sortie humaine ou JSON qu’elle imprime, en la remplaçant par [REDACTED] afin que les captures de terminal et les pipelines ne divulguent jamais le marqueur.

# Associé

• Référence de la CLI openclaw path
• Gérer les plugins
• Créer des plugins