English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

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, перш ніж покладатися на автоматизовані редагування.

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

# 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:

{
  "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 …, тому інсталяції, які ніколи не використовують це дієслово, не несуть витрат.

Увімкнення

openclaw plugins enable oc-path

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

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

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.

Пов’язано