---
read_when:
    - Ви хочете переглянути або відредагувати окремий кінцевий елемент у файлі робочого простору з термінала
    - Ви створюєте скрипти для роботи зі станом робочого простору й потребуєте стабільної схеми адресації, незалежної від типу об’єкта
    - Ви вирішуєте, чи вмикати необов’язковий Plugin `oc-path` на самостійно розміщеному Gateway
summary: 'Вбудований plugin `oc-path`: постачається з CLI `openclaw path` для схеми адресації файлів робочого простору `oc://`'
title: Plugin OC Path
x-i18n:
    generated_at: "2026-07-12T13:28:32Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: eb7bb1aacd37e5cc9c391372b871dc519f4048232d93a0016138ae00a6985a59
    source_path: plugins/oc-path.md
    workflow: 16
---

Вбудований плагін `oc-path` додає CLI [`openclaw path`](/uk/cli/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](/uk/cli/path); на цій сторінці пояснено, навіщо і як вмикати
плагін.

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

Увімкніть `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]`, щоб записи
термінала й конвеєри ніколи не розкривали маркер.

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

- [Довідник CLI `openclaw path`](/uk/cli/path)
- [Керування плагінами](/uk/plugins/manage-plugins)
- [Створення плагінів](/uk/plugins/building-plugins)