OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugin guides

Plugin OC Path

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

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

  • markdown (.md): frontmatter, розділи, елементи, поля
  • jsonc (.jsonc, .json): зі збереженням коментарів і форматування
  • jsonl (.jsonl, .ndjson): записи, орієнтовані на рядки
  • yaml (.yaml, .yml, .lobster): вузли відображень, послідовностей і скалярів через API Document пакета yaml

Користувачі власних серверів і розширення редакторів використовують CLI, щоб читати або записувати один кінцевий елемент без безпосереднього написання сценаріїв для SDK; агенти та хуки використовують його як детерміновану основу, щоб цикли читання й запису з точним збереженням байтів та захист сентинела редагування однаково застосовувалися до всіх типів. Повну граматику, перелік прапорців для кожної команди та практичні приклади для кожного типу файлів див. у довіднику CLI; на цій сторінці пояснено, навіщо і як вмикати плагін.

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

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

Це важливо для робочих процесів супроводу, де зміна має залишатися невеликою, придатною для аудиту та повторюваною: перевірити одне значення, знайти відповідні записи, виконати пробний запис, а потім застосувати зміну лише до цього кінцевого елемента, не змінюючи коментарі, закінчення рядків і сусіднє форматування.

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

  • Локальна автоматизація: сценарії оболонки визначають або оновлюють одне значення робочого простору за допомогою openclaw path … --json, замість того щоб містити окремий код синтаксичного аналізу Markdown, JSONC, JSONL і YAML.
  • Редагування, видимі агенту: агент показує різницю пробного запису для одного адресованого кінцевого елемента перед записуванням, що легше перевірити, ніж довільне переписування файлу.
  • Інтеграції з редакторами: редактор зіставляє oc://AGENTS.md/tools/gh із точним вузлом Markdown і номером рядка без припущень на основі тексту заголовка.
  • Діагностика: emit виконує цикл синтаксичного аналізу та виведення файлу, тож можна перевірити, чи зберігає тип файлу точні байти, перш ніж покладатися на автоматизоване редагування.
bash
# Чи ввімкнено плагін GitHub у цій конфігурації?openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json # Які назви викликів інструментів наявні в журналі цього сеансу?openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json # Які байти запише ця невелика зміна конфігурації?openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

oc-path навмисно не відповідає за семантику вищого рівня. Плагіни пам’яті й надалі відповідають за записи пам’яті, команди конфігурації — за повне керування конфігурацією, а відновлення останньої відомої справної конфігурації (LKG) — за відновлення та просування. oc-path — це вузький шар адресації та операцій із файлами зі збереженням байтів, навколо якого можуть будуватися ці інструменти вищого рівня.

Де він працює

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

Метадані плагіна містяться в 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 виключає плагін зі шляху запуску Gateway. commandAliases і activation.onCommands указують CLI завантажувати плагін відкладено під час першого запуску openclaw path …, тому встановлення, які ніколи не використовують цю команду, не несуть жодних витрат.

Увімкнення

bash
openclaw plugins enable oc-path

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

Щоб вимкнути:

bash
openclaw plugins disable oc-path

Залежності

Усі залежності синтаксичних аналізаторів є локальними для плагіна; ввімкнення oc-path не додає нових пакетів до основного середовища виконання:

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

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

Що він надає

Поверхня Реалізація
CLI openclaw path extensions/oc-path/cli-registration.ts
Аналізатор і форматувальник oc:// extensions/oc-path/src/oc-path/oc-path.ts
Аналіз, виведення та редагування за типами extensions/oc-path/src/oc-path/{md,jsonc,jsonl,yaml}
Універсальні resolve / find / set extensions/oc-path/src/oc-path/{resolve,find,edit}.ts
Захист сентинела редагування extensions/oc-path/src/oc-path/sentinel.ts

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

Зв’язок з іншими плагінами

  • memory-*: записи пам’яті виконуються через плагіни пам’яті, а не oc-path. oc-path є універсальною файловою основою; плагіни пам’яті додають поверх неї власну семантику.
  • LKG: path нічого не знає про відновлення останньої відомої справної конфігурації. Якщо файл, який ви редагуєте через path, також відстежується LKG, наступний цикл спостереження за конфігурацією визначить, чи просувати його або відновлювати; розглядайте редагування через path так само, як будь-який інший безпосередній запис у цей файл.

Безпека

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

Пов’язані матеріали

Was this useful?
On this page

On this page