Перейти до основного вмісту
Пакетний Plugin oc-path додає CLI openclaw path для схеми адресації файлів робочої області oc://. Він постачається в репозиторії OpenClaw у extensions/oc-path/, але є опційним — встановлення/збирання залишає його неактивним, доки ви не ввімкнете його. Адреси oc:// вказують на один кінцевий елемент (або wildcard-набір кінцевих елементів) усередині файлу робочої області. Нині Plugin розуміє чотири типи файлів:
  • markdown (.md, .mdx): frontmatter, розділи, елементи, поля
  • jsonc (.jsonc, .json5, .json): коментарі та форматування зберігаються
  • jsonl (.jsonl, .ndjson): записи, орієнтовані на рядки
  • yaml (.yaml, .yml, .lobster): вузли мап/послідовностей/скалярів через API документа YAML
Ті, хто self-hostить, і розширення редакторів використовують CLI, щоб читати або записувати один кінцевий елемент без прямого скриптування проти SDK; агенти й хуки сприймають його як детерміновану основу, щоб byte-fidelity round-trip і захист через sentinel редагування застосовувалися однаково для всіх типів.

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

Увімкніть oc-path, коли потрібно, щоб скрипти, хуки або локальні інструменти агентів вказували на точну частину стану робочої області без вигадування парсера для кожної форми файлу. Одна адреса oc:// може називати ключ frontmatter у markdown, елемент розділу, кінцевий елемент конфігурації JSONC, поле події JSONL або крок workflow YAML. Це важливо для workflow мейнтейнерів, де зміна має бути малою, придатною до аудиту й повторюваною: перевірити одне значення, знайти відповідні записи, dry-run запису, а потім застосувати лише цей кінцевий елемент, залишивши коментарі, закінчення рядків і сусіднє форматування без змін. Збереження цього як опційного Plugin дає досвідченим користувачам основу адресації без додавання залежностей парсерів або CLI-поверхні в ядро для інсталяцій, яким це ніколи не потрібно. Поширені причини ввімкнути його:
  • Локальна автоматизація: shell-скрипти можуть розв’язувати або оновлювати одне значення робочої області за допомогою openclaw path … --json замість того, щоб містити окремий код парсингу markdown, JSONC, JSONL і YAML.
  • Редагування, видимі агенту: агент може показати dry-run diff для одного адресованого кінцевого елемента перед записом, що легше переглядати, ніж вільне переписування файлу.
  • Інтеграції редактора: редактор може зіставити oc://AGENTS.md/tools/gh з точним вузлом markdown і номером рядка без здогадок за текстом заголовка.
  • Діагностика: emit пропускає файл через parser і emitter в обидва боки, тож можна перевірити, чи тип файлу є byte-stable, перш ніж покладатися на автоматизовані редагування.
Конкретні приклади: 
# 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 Plugin-и й далі володіють записами пам’яті, команди конфігурації й далі володіють повним керуванням конфігурацією, а логіка LKG й далі володіє відновленням/просуванням. oc-path — це вузький шар адресації та файлових операцій зі збереженням байтів, навколо якого ці інструменти вищого рівня можуть будуватися.

​
Де він виконується

Plugin виконується в процесі всередині CLI openclaw на хості, де ви викликаєте команду. Йому не потрібен запущений Gateway, і він не відкриває жодних мережевих сокетів — кожна дія є чистим перетворенням над файлом, на який ви вказуєте. Метадані Plugin розташовані в extensions/oc-path/openclaw.plugin.json: 
{
  "id": "oc-path",
  "name": "OC Path",
  "activation": {
    "onStartup": false,
    "onCommands": ["path"]
  },
  "commandAliases": [{ "name": "path", "kind": "cli" }]
}
onStartup: false тримає Plugin поза гарячим шляхом Gateway. onCommands: ["path"] повідомляє CLI, що Plugin треба завантажувати ліниво першого разу, коли ви запускаєте openclaw path …, тож інсталяції, які ніколи не використовують цю дію, не платять жодної вартості.

​
Увімкнення

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

​
Залежності

Усі залежності парсерів є локальними для Plugin — увімкнення oc-path не додає нові пакети до runtime ядра:
ЗалежністьПризначення
commanderЗв’язування підкоманд для resolve, find, set, validate, emit.
jsonc-parserПарсинг JSONC + редагування кінцевих елементів зі збереженням коментарів і кінцевих ком.
markdown-itТокенізація Markdown для моделі розділ / елемент / поле.
yamlПарсинг / emit / редагування Document YAML зі збереженням коментарів і flow style.
JSONL лишається ручною реалізацією — парсинг, орієнтований на рядки, простіший за будь-яку залежність, а JSONC-парсинг кожного рядка вже проходить через jsonc-parser.

​
Що він надає

ПоверхняНадається через
CLI openclaw pathextensions/oc-path/cli-registration.ts
Parser / formatter oc://extensions/oc-path/src/oc-path/oc-path.ts
Парсинг / emit / редагування за типамиextensions/oc-path/src/oc-path/{md,jsonc,jsonl,yaml}
Універсальні resolve / find / setextensions/oc-path/src/oc-path/{resolve,find,edit}.ts
Захист redaction-sentinelextensions/oc-path/src/oc-path/sentinel.ts
CLI нині є єдиною публічною поверхнею. Базові дії є приватними для Plugin; споживачі використовують CLI (або створюють власний Plugin на SDK).

​
Зв’язок з іншими Plugin-и

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

​
Безпека

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

​
Пов’язане