Bundled plugin guides

Plugin OC Path

Укомплектований Plugin oc-path додає CLI openclaw path для схеми адресації файлів робочої області oc://. Він постачається в репозиторії OpenClaw у extensions/oc-path/, але є опціональним — install/build залишає його неактивним, доки ви його не ввімкнете.

Адреси oc:// вказують на один кінцевий елемент (або wildcard-набір кінцевих елементів) усередині файлу робочої області. Сьогодні Plugin розуміє три види файлів:

markdown (.md, .mdx): frontmatter, розділи, елементи, поля
jsonc (.jsonc, .json5, .json): коментарі та форматування зберігаються
jsonl (.jsonl, .ndjson): записи, орієнтовані на рядки

Ті, хто розгортає власні інстанси, та розширення редакторів використовують CLI, щоб читати або записувати один кінцевий елемент без написання скриптів безпосередньо проти SDK; агенти й hooks розглядають його як детерміновану основу, щоб byte-fidelity round-trips і захист redaction sentinel застосовувалися однаково для всіх видів.

Навіщо його вмикати

Увімкніть oc-path, коли хочете, щоб scripts, hooks або локальні інструменти агентів вказували на точну частину стану робочої області без створення окремого парсера для кожної форми файлу. Одна адреса oc:// може називати ключ frontmatter у markdown, елемент розділу, кінцевий елемент конфігурації JSONC або поле події JSONL.

Це важливо для workflows супровідників, де зміна має бути невеликою, аудитованою та повторюваною: перевірити одне значення, знайти відповідні записи, dry-run запис, а потім застосувати лише цей кінцевий елемент, не змінюючи коментарі, закінчення рядків і сусіднє форматування. Збереження цього як опціонального Plugin дає досвідченим користувачам основу адресації без додавання залежностей парсерів або CLI-поверхні в core для інсталяцій, яким це ніколи не потрібно.

Поширені причини ввімкнути його:

Локальна автоматизація: shell scripts можуть визначити або оновити одне значення робочої області через openclaw path … --json замість підтримки окремого коду парсингу markdown, JSONC і JSONL.
Редагування, видимі агенту: агент може показати diff dry-run для одного адресованого кінцевого елемента перед записом, що простіше переглядати, ніж довільне переписування файлу.
Інтеграції з редакторами: редактор може зіставити oc://AGENTS.md/tools/gh з точним вузлом markdown і номером рядка без здогадок за текстом заголовка.
Діагностика: emit пропускає файл через parser і emitter у round-trip, тож можна перевірити, чи є вид файлу byte-stable, перш ніж покладатися на автоматизовані редагування.

Конкретні приклади:

bash

# 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

Plugin навмисно не є власником семантики вищого рівня. Memory plugins і далі володіють записами пам’яті, config commands і далі володіють повним керуванням config, а логіка LKG і далі володіє відновленням/просуванням. oc-path — це вузький шар адресації та byte-preserving файлових операцій, навколо якого ці інструменти вищого рівня можуть будуватися.

Де він працює

Plugin працює в процесі всередині CLI openclaw на host, де ви викликаєте команду. Йому не потрібен запущений Gateway, і він не відкриває жодних мережевих сокетів — кожне дієслово є чистим перетворенням файлу, на який ви вказали.

Метадані Plugin містяться в extensions/oc-path/openclaw.plugin.json:

json

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

onStartup: false не допускає Plugin до hot path Gateway. onCommands: ["path"] повідомляє CLI, що Plugin треба ледаче завантажити під час першого запуску openclaw path …, тому інсталяції, які ніколи не використовують це дієслово, не несуть витрат.

Увімкнення

bash

openclaw plugins enable oc-path

Перезапустіть Gateway (якщо ви його запускаєте), щоб snapshot маніфесту підхопив новий стан. Прості виклики openclaw path працюють негайно на тому самому host — CLI завантажує Plugin за потреби.

Вимкнути можна так:

bash

openclaw plugins disable oc-path

Залежності

Усі залежності parser є локальними для Plugin — увімкнення oc-path не додає нові пакети до core runtime:

Залежність	Призначення
`commander`	Підключення підкоманд для `resolve`, `find`, `set`, `validate`, `emit`.
`jsonc-parser`	Парсинг JSONC + редагування кінцевих елементів зі збереженням коментарів і кінцевих ком.
`markdown-it`	Токенізація Markdown для моделі section / item / field.

JSONL залишається реалізованим вручну — line-oriented parsing простіший за будь-яку залежність, а per-line парсинг JSONC уже проходить через jsonc-parser.

Що він надає

Поверхня	Надається через
CLI `openclaw path`	`extensions/oc-path/cli-registration.ts`
Parser / formatter `oc://`	`extensions/oc-path/src/oc-path/oc-path.ts`
Per-kind parse / emit / edit	`extensions/oc-path/src/oc-path/{md,jsonc,jsonl}`
Universal resolve / find / set	`extensions/oc-path/src/oc-path/{resolve,find,edit}.ts`
Захист redaction-sentinel	`extensions/oc-path/src/oc-path/sentinel.ts`

Сьогодні CLI є єдиною публічною поверхнею. Дієслова substrate є приватними для Plugin; споживачі використовують CLI (або створюють власний Plugin на основі SDK).

Відношення до інших Plugin

memory-*: записи пам’яті проходять через memory plugins, а не oc-path. oc-path — це generic file substrate; memory plugins накладають власну семантику поверх нього.
LKG: path не знає про відновлення Last-Known-Good config. Якщо файл відстежується LKG, наступний виклик observe вирішує, чи просувати, чи відновлювати; set --batch для атомарного multi-set через життєвий цикл promote/recover LKG заплановано разом із LKG-recovery substrate.

Безпека

set записує raw bytes через emit path substrate, який автоматично застосовує захист redaction-sentinel. Кінцевий елемент, що містить __OPENCLAW_REDACTED__ (буквально або як substring), відхиляється під час запису з OC_EMIT_SENTINEL. CLI також вилучає буквальний sentinel з будь-якого human або JSON output, який друкує, замінюючи його на [REDACTED], щоб terminal captures і pipelines ніколи не розкривали marker.

Пов’язано

Was this useful?