openclaw path
Доступ з оболонки до схеми адресації oc://: єдиний синтаксис шляхів із диспетчеризацією за типом для перевірки та редагування адресованих файлів робочого простору (markdown, jsonc, jsonl, yaml/yml/lobster). Користувачі самостійно розгорнутих систем, автори плагінів і розширень редакторів використовують його, щоб читати, знаходити або оновлювати вузько визначене місце без написання окремого парсера для кожного типу файлу.
path надає вбудований необов’язковий плагін oc-path. Увімкніть його перед першим використанням:
resolveпрацює з конкретним шляхом і єдиним збігом.find— дієслово для кількох збігів із символами підстановки, об’єднаннями, предикатами та позиційним розгортанням.setприймає лише конкретні шляхи або маркери вставлення; шаблони із символами підстановки відхиляються до запису.validateаналізує шлях без доступу до файлової системи.emitвиконує повний цикл аналізу й виведення файлу (діагностика побайтової відповідності).
Навіщо це використовувати
Стан OpenClaw розподілено між редагованими вручну файлами markdown, конфігурацією JSONC із коментарями, журналами JSONL лише для дописування та файлами робочих процесів і специфікацій YAML. Скриптам, хукам і агентам часто потрібне одне невелике значення з цих файлів: ключ frontmatter, налаштування плагіна, поле запису журналу, крок YAML або елемент маркованого списку в іменованому розділі.openclaw path надає таким викликачам стабільну адресу замість одноразового grep, регулярного виразу або окремого парсера для кожного типу файлу. Той самий шлях oc:// можна перевірити, розв’язати, знайти, попередньо виконати без запису та записати з термінала, завдяки чому вузько спрямовану автоматизацію можна перевіряти й повторювати. Решта файлу зберігається, тому запис одного кінцевого значення не порушує коментарі, завершення рядків або форматування поруч.
Використовуйте його, коли потрібний об’єкт має логічну адресу, але структура файлу різниться:
- Хук читає одне налаштування з JSONC із коментарями, не втрачаючи коментарів під час зворотного запису значення.
- Скрипт обслуговування знаходить усі відповідні поля подій у журналі JSONL, не завантажуючи весь журнал у спеціально створений парсер.
- Редактор переходить до розділу markdown або елемента маркованого списку за слагом, а потім відображає точний розв’язаний рядок.
- Агент попередньо виконує невелике редагування робочого простору без запису перед його застосуванням, а змінені байти доступні для перевірки.
openclaw path для звичайного редагування цілих файлів, складних міграцій конфігурації або записів, пов’язаних із пам’яттю; для них слід використовувати команду чи плагін власника. path призначено для невеликих операцій з адресованими файлами, де повторювана команда термінала краща за ще один спеціалізований парсер.
Використання
Прочитайте одне значення з редагованого вручну конфігураційного файлу:--json, коли викликачу потрібне структуроване виведення, і --human, коли результат переглядає людина.
Принцип роботи
- Аналізує адресу
oc://і розділяє її на позиції: файл, розділ, елемент, поле та необов’язковий запит сеансу. - Вибирає адаптер типу файлу за розширенням цільового файлу (
.md,.jsonc,.json,.jsonl,.ndjson,.yaml,.yml,.lobster). - Розв’язує позиції відповідно до структури цього типу файлу: заголовки й елементи markdown, ключі об’єктів та індекси масивів JSONC, рядкові записи JSONL або вузли відображень і послідовностей YAML.
- Для
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-parser, тому коментарі та пробіли
зберігаються після set. Спочатку запустіть команду з --dry-run, щоб перевірити
байти перед застосуванням змін. Файли .json використовують той самий адаптер
і шлях редагування, що й .jsonc.
JSONL
[event=action]), якщо
номер рядка невідомий, або за канонічним сегментом LN, якщо він відомий.
Файли .ndjson використовують той самий адаптер, що й .jsonl.
YAML
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так само, як до будь-якого іншого прямого запису в цей файл.