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

Plugin guides

Плагин 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}
Универсальные разрешение, поиск и установка 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