Skip to main content

openclaw path

Доступ з оболонки до схеми адресації oc://: єдиний синтаксис шляхів із диспетчеризацією за типом для перевірки та редагування адресованих файлів робочого простору (markdown, jsonc, jsonl, yaml/yml/lobster). Користувачі самостійно розгорнутих систем, автори плагінів і розширень редакторів використовують його, щоб читати, знаходити або оновлювати вузько визначене місце без написання окремого парсера для кожного типу файлу. path надає вбудований необов’язковий плагін oc-path. Увімкніть його перед першим використанням:
Дієслова CLI відповідають моделі адресації:
  • resolve працює з конкретним шляхом і єдиним збігом.
  • find — дієслово для кількох збігів із символами підстановки, об’єднаннями, предикатами та позиційним розгортанням.
  • set приймає лише конкретні шляхи або маркери вставлення; шаблони із символами підстановки відхиляються до запису.
  • validate аналізує шлях без доступу до файлової системи.
  • emit виконує повний цикл аналізу й виведення файлу (діагностика побайтової відповідності).

Навіщо це використовувати

Стан OpenClaw розподілено між редагованими вручну файлами markdown, конфігурацією JSONC із коментарями, журналами JSONL лише для дописування та файлами робочих процесів і специфікацій YAML. Скриптам, хукам і агентам часто потрібне одне невелике значення з цих файлів: ключ frontmatter, налаштування плагіна, поле запису журналу, крок YAML або елемент маркованого списку в іменованому розділі. openclaw path надає таким викликачам стабільну адресу замість одноразового grep, регулярного виразу або окремого парсера для кожного типу файлу. Той самий шлях oc:// можна перевірити, розв’язати, знайти, попередньо виконати без запису та записати з термінала, завдяки чому вузько спрямовану автоматизацію можна перевіряти й повторювати. Решта файлу зберігається, тому запис одного кінцевого значення не порушує коментарі, завершення рядків або форматування поруч. Використовуйте його, коли потрібний об’єкт має логічну адресу, але структура файлу різниться:
  • Хук читає одне налаштування з JSONC із коментарями, не втрачаючи коментарів під час зворотного запису значення.
  • Скрипт обслуговування знаходить усі відповідні поля подій у журналі JSONL, не завантажуючи весь журнал у спеціально створений парсер.
  • Редактор переходить до розділу markdown або елемента маркованого списку за слагом, а потім відображає точний розв’язаний рядок.
  • Агент попередньо виконує невелике редагування робочого простору без запису перед його застосуванням, а змінені байти доступні для перевірки.
Не використовуйте openclaw path для звичайного редагування цілих файлів, складних міграцій конфігурації або записів, пов’язаних із пам’яттю; для них слід використовувати команду чи плагін власника. path призначено для невеликих операцій з адресованими файлами, де повторювана команда термінала краща за ще один спеціалізований парсер.

Використання

Прочитайте одне значення з редагованого вручну конфігураційного файлу:
Перегляньте запис без змін на диску:
Знайдіть відповідні записи в журналі JSONL лише для дописування:
Адресуйте інструкцію в markdown за розділом і елементом, а не за номером рядка:
Перевірте шлях у CI або скрипті попередньої перевірки до того, як скрипт виконає читання чи запис:
Ці команди призначено для копіювання в скрипти оболонки. Використовуйте --json, коли викликачу потрібне структуроване виведення, і --human, коли результат переглядає людина.

Принцип роботи

  1. Аналізує адресу oc:// і розділяє її на позиції: файл, розділ, елемент, поле та необов’язковий запит сеансу.
  2. Вибирає адаптер типу файлу за розширенням цільового файлу (.md, .jsonc, .json, .jsonl, .ndjson, .yaml, .yml, .lobster).
  3. Розв’язує позиції відповідно до структури цього типу файлу: заголовки й елементи markdown, ключі об’єктів та індекси масивів JSONC, рядкові записи JSONL або вузли відображень і послідовностей YAML.
  4. Для set виводить відредаговані байти через той самий адаптер, щоб незмінені частини файлу зберігали коментарі, завершення рядків і форматування поруч, якщо тип файлу це підтримує.
resolve і set потребують однієї конкретної цілі. find — дієслово для дослідження: воно розгортає символи підстановки, об’єднання, предикати й порядкові номери в конкретні збіги, які можна перевірити перед вибором цілі для запису.

Підкоманди

Глобальні прапорці

validate приймає лише --json / --human; ця команда не звертається до файлової системи, тому --cwd і --file не застосовуються.

Синтаксис oc://

Правила позицій: field потребує item, а item потребує section. Для всіх чотирьох позицій:
  • Сегменти в лапках"a/b.c" не розділяється за / і .. Вміст є побайтовим літералом; " і \ у лапках заборонені. Позиція файлу також ураховує лапки: oc://"skills/email-drafter"/Tools/$last розглядає skills/email-drafter як єдиний шлях до файлу.
  • Предикати[k=v], [k!=v], [k<v], [k<=v], [k>v], [k>=v]. Числові оператори потребують, щоб обидві сторони можна було перетворити на скінченні числа.
  • Об’єднання{a,b,c} відповідає будь-якій з альтернатив.
  • Символи підстановки* (один підсегмент) і ** (нуль або більше, рекурсивно). find приймає їх; resolve і set відхиляють їх як неоднозначні.
  • Позиційні маркери$first / $last розв’язуються в перший / останній індекс або оголошений ключ.
  • Порядковий номер#N для N-го збігу в порядку документа.
  • Маркери вставлення+, +key, +nnn для вставлення за ключем / індексом (використовуйте з set).
  • Область сеансу?session=cron-daily тощо. Не залежить від вкладеності позицій. Значення сеансу необроблені й не декодуються у відсотковому форматі; вони не можуть містити керівні символи або зарезервовані роздільники запиту (?, &, %).
Зарезервовані символи (?, &, %) поза сегментами в лапках, предикатами або об’єднаннями відхиляються. Керівні символи (U+0000–U+001F, U+007F) відхиляються всюди, зокрема у значенні запиту session. Для канонічних шляхів гарантовано formatOcPath(parseOcPath(path)) === path. Неканонічні параметри запиту ігноруються, крім першого непорожнього значення session=. Жорсткі обмеження: шлях має не більше 4096 байтів, не більше 4 позицій (файл/розділ/елемент/поле), не більше 64 підсегментів, розділених крапками, у кожній позиції та не більше 256 рівнів вкладеного обходу для глибоких шляхів JSON. Окремо вхідні файли JSONC/JSON розміром понад 16 МіБ не аналізуються для жодного дієслова, що завантажує такий файл; натомість повертається діагностичне повідомлення про помилку аналізу.

Адресація за типом файлу

resolve повертає структурований збіг: root, node, leaf або insertion-point, із номером рядка, що починається з 1. Кінцеві значення надаються як текст разом із leafType, щоб автори плагінів могли відображати попередній перегляд без залежності від форми AST конкретного типу файлу.

Контракт змінення

set записує одну конкретну ціль:
  • Значення frontmatter markdown і поля елементів - key: value є рядковими кінцевими значеннями. Вставлення в markdown додають розділи, ключі frontmatter або елементи розділу та формують канонічну структуру markdown для зміненого файлу. Тіла розділів не можна записувати цілком через set.
  • Запис кінцевого значення JSONC перетворює рядкове значення на тип наявного кінцевого значення (string, скінченне number, true/false або null). Використовуйте --value-json, коли заміна кінцевого значення JSONC/JSON/JSONL має аналізувати <value> як JSON і може змінити структуру, наприклад замінити скорочене рядкове посилання на секрет об’єктом. Вставлення в об’єкти й масиви JSONC аналізують <value> як JSON і використовують шлях редагування jsonc-parser для звичайного запису кінцевих значень, зберігаючи коментарі та форматування поруч.
  • Записи кінцевих значень JSONL усередині рядка виконують перетворення так само, як JSONC. Заміна цілого рядка й дописування аналізують <value> як JSON. Сформований JSONL зберігає переважну в файлі угоду про завершення рядків LF/CRLF (за більшістю всіх завершень рядків у файлі, тому файл, де переважає CRLF, залишиться з CRLF навіть за наявності кількох випадкових LF).
  • Записи кінцевих значень YAML перетворюються на тип наявного скалярного значення (string, скінченне number, true/false або null). Вставлення YAML використовують API документа вбудованого пакета yaml для оновлення відображень і послідовностей. Некоректні документи YAML із помилками парсера відхиляються до зміни з помилкою parse-error.
Використовуйте --dry-run перед видимими користувачеві записами, коли важливі точні байти. Редагування JSONC і YAML змінює наявний документ (через jsonc-parser або API документа yaml), тому незмінені байти зазвичай зберігаються; markdown перебудовує файл з його проаналізованої структури за будь-якого редагування, що може нормалізувати другорядне форматування поза зміненим кінцевим значенням. Додайте --diff, якщо хочете отримати попередній перегляд як зосереджену різницю до/після замість повного сформованого файлу.

Приклади

Додаткові приклади граматики:

Рецепти за типами файлів

Ті самі п’ять дієслів працюють для всіх типів; схема адресації вибирає обробник за розширенням файлу.

Markdown

Предикат [frontmatter] адресує блок вступних даних YAML; tools зіставляється із заголовком ## Tools через слаг, а листові елементи зберігають форму слага, навіть якщо джерело використовує символи підкреслення (send_email перетворюється на send-email).

JSONC

Редагування JSONC виконується через jsonc-parser, тому коментарі та пробіли зберігаються після set. Спочатку запустіть команду з --dry-run, щоб перевірити байти перед застосуванням змін. Файли .json використовують той самий адаптер і шлях редагування, що й .jsonc.

JSONL

Кожен рядок є записом. Адресуйте його за предикатом ([event=action]), якщо номер рядка невідомий, або за канонічним сегментом LN, якщо він відомий. Файли .ndjson використовують той самий адаптер, що й .jsonl.

YAML

YAML використовує API Document пакета yaml замість самописного парсера, тому звичайні цикли розбору та виведення зберігають коментарі й авторську структуру, а вирішені шляхи використовують ту саму модель ключів мапи та індексів послідовності, що й JSONC. Той самий адаптер обробляє файли .yaml, .yml і .lobster.

Довідник підкоманд

resolve <oc-path>

Читає один листовий елемент або вузол. Шаблони не підтримуються — для них використовуйте find. Завершується з кодом 0 у разі збігу, 1 у разі коректної відсутності збігу, 2 у разі помилки розбору або відхиленого шаблону.

find <pattern>

Перелічує всі збіги для шаблону із символами узагальнення, предикатом або об’єднанням. Завершується з кодом 0, якщо знайдено принаймні один збіг, і 1, якщо збігів немає. Символи узагальнення в позиції файлу відхиляються з кодом OC_PATH_FILE_WILDCARD_UNSUPPORTED — передайте конкретний файл (підтримка шаблонів для кількох файлів буде додана пізніше).

set <oc-path> <value>

Записує листовий елемент. Використовуйте разом із --dry-run, щоб попередньо переглянути байти, які буде записано, не змінюючи файл. Додайте --diff, щоб переглянути уніфіковану різницю. Завершується з кодом 0 після успішного запису, 1, якщо базовий шар відхиляє операцію (наприклад, спрацював захист сигнального значення), і 2 у разі помилки розбору.
Маркер вставлення +key створює дочірній елемент із заданою назвою, якщо він ще не існує; +nnn і окремий + використовуються відповідно для вставлення за індексом і додавання в кінець.

validate <oc-path>

Перевірка лише синтаксичного розбору. Без доступу до файлової системи. Корисна, коли потрібно переконатися, що шлях шаблону сформовано правильно, перш ніж підставляти змінні, або отримати структурну декомпозицію для налагодження:
Завершується з кодом 0, якщо шлях коректний, 1, якщо некоректний (зі структурованими полями code і message), та 2 у разі помилок аргументів.

emit <file>

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

Коди завершення

Режим виведення

openclaw path враховує TTY: у терміналі виводить зручний для читання текст, а коли стандартний вивід передано через канал або перенаправлено — JSON. Параметри --json і --human перевизначають автоматичне визначення.

Примітки

  • set записує байти через шлях виведення базового шару, який автоматично застосовує захист сигнального значення редагування. Запис листового елемента, що містить __OPENCLAW_REDACTED__ (дослівно або як підрядок), відхиляється під час запису.
  • Для розбору JSONC і редагування листових елементів використовується локальна для Plugin залежність jsonc-parser, тому коментарі та форматування зберігаються під час звичайного запису листових елементів замість проходження через самописний шлях розбору та повторного відтворення.
  • path не враховує відстеження або відновлення останньої відомої коректної конфігурації (LKG); цим життєвим циклом керує інший компонент. Якщо файл, відредагований через path, також відстежується як LKG, наступне читання конфігурації визначить, чи прийняти його, чи відновити; ставтеся до редагування через path так само, як до будь-якого іншого прямого запису в цей файл.

Пов’язане