CLI commands

Шлях

`openclaw path`

Доступ з оболонки до схеми адресації oc://: єдиний синтаксис шляхів із диспетчеризацією за типом для перевірки та редагування адресованих файлів робочого простору (markdown, jsonc, jsonl, yaml/yml/lobster). Користувачі самостійно розгорнутих систем, автори плагінів і розширень редакторів використовують його, щоб читати, знаходити або оновлювати вузько визначене місце без написання окремого парсера для кожного типу файлу.

path надає вбудований необов’язковий плагін oc-path. Увімкніть його перед першим використанням:

bash

openclaw plugins enable 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 призначено для невеликих операцій з адресованими файлами, де повторювана команда термінала краща за ще один спеціалізований парсер.

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

Прочитайте одне значення з редагованого вручну конфігураційного файлу:

bash

openclaw path resolve 'oc://config.jsonc/plugins/github/enabled'

Перегляньте запис без змін на диску:

bash

openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

Знайдіть відповідні записи в журналі JSONL лише для дописування:

bash

openclaw path find 'oc://session.jsonl/[event=tool_call]/name'

Адресуйте інструкцію в markdown за розділом і елементом, а не за номером рядка:

bash

openclaw path resolve 'oc://AGENTS.md/runtime-safety/openclaw-gateway'

Перевірте шлях у CI або скрипті попередньої перевірки до того, як скрипт виконає читання чи запис:

bash

openclaw path validate 'oc://AGENTS.md/tools/$last/risk'

Ці команди призначено для копіювання в скрипти оболонки. Використовуйте --json, коли викликачу потрібне структуроване виведення, і --human, коли результат переглядає людина.

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

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

resolve і set потребують однієї конкретної цілі. find — дієслово для дослідження: воно розгортає символи підстановки, об’єднання, предикати й порядкові номери в конкретні збіги, які можна перевірити перед вибором цілі для запису.

Підкоманди

Підкоманда	Призначення
`resolve <oc-path>`	Вивести конкретний збіг за шляхом (або «не знайдено»).
`find <pattern>`	Перелічити збіги для шляху із символом підстановки, об’єднанням або предикатом.
`set <oc-path> <value>`	Записати кінцеве значення або ціль вставлення за конкретним шляхом. Підтримує `--dry-run`.
`validate <oc-path>`	Лише аналіз; вивести структурний поділ (файл / розділ / елемент / поле).
`emit <file>`	Виконати повний цикл аналізу й виведення файлу (діагностика побайтової відповідності).

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

Прапорець	Застосовується до	Призначення
`--cwd <dir>`	`resolve`, `find`, `set`, `emit`	Розв’язувати позицію файлу відносно цього каталогу (типово: `process.cwd()`).
`--file <path>`	`resolve`, `find`, `set`, `emit`	Перевизначити розв’язаний шлях позиції файлу (абсолютний доступ).
`--json`	усіх	Примусово використовувати виведення JSON (типово, коли stdout не є TTY).
`--human`	усіх	Примусово використовувати зручне для людини виведення (типово, коли stdout є TTY).
`--value-json`	`set`	Аналізувати `<value>` як JSON для заміни кінцевого значення JSON/JSONC/JSONL.
`--dry-run`	`set`	Вивести байти, які було б записано, без запису.
`--diff`	`set` (потребує `--dry-run`)	Вивести уніфіковану різницю замість повного набору байтів.

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

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

text

oc://FILE/SECTION/ITEM/FIELD?session=SCOPE

Правила позицій: 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 МіБ не аналізуються для жодного дієслова, що завантажує такий файл; натомість повертається діагностичне повідомлення про помилку аналізу.

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

Тип	Розширення файлів	Модель адресації
Markdown	`.md`	Розділи H2 за слагом, елементи маркованого списку за слагом або `#N`, frontmatter через `[frontmatter]`.
JSONC/JSON	`.jsonc`, `.json`	Ключі об’єктів та індекси масивів; крапки розділяють вкладені підсегменти, якщо їх не взято в лапки.
JSONL	`.jsonl`, `.ndjson`	Адреси рядків верхнього рівня (`L1`, `L2`, `$first`, `$last`), потім спуск усередині рядка у стилі JSONC.
YAML/.lobster	`.yaml`, `.yml`, `.lobster`	Ключі відображень та індекси послідовностей; коментарі й потоковий стиль обробляє API документа YAML.

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, якщо хочете отримати попередній перегляд як зосереджену різницю до/після замість повного сформованого файлу.

Приклади

bash

# Перевірити шлях (без доступу до файлової системи)openclaw path validate 'oc://AGENTS.md/Tools/$last/risk' # Прочитати кінцеве значенняopenclaw path resolve 'oc://gateway.jsonc/version' # Пошук із символом підстановкиopenclaw path find 'oc://session.jsonl/*/event' --file ./logs/session.jsonl # Попередньо виконати запис без змінopenclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run # Попередньо виконати запис як уніфіковану різницюopenclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run --diff # Застосувати записopenclaw path set 'oc://gateway.jsonc/version' '2.0' # Повний цикл із побайтовою відповідністю (діагностика)openclaw path emit ./AGENTS.md

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

bash

# Quote keys containing / or .openclaw path resolve 'oc://config.jsonc/agents.defaults.models/"anthropic/claude-opus-4-7"/alias' # Deep JSON/JSONC paths can use slash segments; they normalize to dotted subsegmentsopenclaw path set 'oc://openclaw.json/agents/list/0/tools/exec/security' 'allowlist' --dry-run # Replace a JSONC leaf with a parsed objectopenclaw path set 'oc://openclaw.json/gateway/auth/token' '{"source":"file","provider":"secrets","id":"/test"}' --value-json --dry-run # Predicate search over JSONC childrenopenclaw path find 'oc://config.jsonc/plugins/[enabled=true]/id' # Insert into a JSONC arrayopenclaw path set 'oc://config.jsonc/items/+1' '{"id":"new","enabled":true}' --dry-run # Insert a JSONC object keyopenclaw path set 'oc://config.jsonc/plugins/+github' '{"enabled":true}' --dry-run # Append a JSONL eventopenclaw path set 'oc://session.jsonl/+' '{"event":"checkpoint","ok":true}' --file ./logs/session.jsonl # Resolve the last JSONL value lineopenclaw path resolve 'oc://session.jsonl/$last/event' --file ./logs/session.jsonl # Resolve a YAML workflow stepopenclaw path resolve 'oc://workflow.yaml/steps/0/id' # Update a YAML scalaropenclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --dry-run # Address markdown frontmatteropenclaw path resolve 'oc://AGENTS.md/[frontmatter]/name' # Insert markdown frontmatteropenclaw path set 'oc://AGENTS.md/[frontmatter]/+description' 'Agent instructions' --dry-run # Find markdown item fieldsopenclaw path find 'oc://SKILL.md/Tools/*/send_email' # Validate a session-scoped pathopenclaw path validate 'oc://AGENTS.md/Tools/$last/risk?session=cron-daily'

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

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

Markdown

text

<!-- frontmatter.md -->---name: drafterdescription: email drafting agenttier: core---## Tools- gh: GitHub CLI- curl: HTTP client- send_email: enabled

bash

$ openclaw path resolve 'oc://x.md/[frontmatter]/tier' --file frontmatter.md --humanleaf @ L4: "core" (string) $ openclaw path resolve 'oc://x.md/tools/gh/gh' --file frontmatter.md --humanleaf @ L9: "GitHub CLI" (string) $ openclaw path find 'oc://x.md/tools/*' --file frontmatter.md --human3 matches for oc://x.md/tools/*:  oc://x.md/tools/gh           →  node @ L9 [md-item]  oc://x.md/tools/curl         →  node @ L10 [md-item]  oc://x.md/tools/send-email   →  node @ L11 [md-item]

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

JSONC

text

// config.jsonc{  "plugins": {    "github": {"enabled": true, "role": "vcs"},    "slack":  {"enabled": false, "role": "chat"}  }}

bash

$ openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --file config.jsonc --humanleaf @ L4: "true" (boolean) $ openclaw path set 'oc://config.jsonc/plugins/slack/enabled' 'true' --file config.jsonc --dry-run--dry-run: would write 142 bytes to /…/config.jsonc{  "plugins": {    "github": {"enabled": true, "role": "vcs"},    "slack":  {"enabled": true, "role": "chat"}  }}

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

JSONL

text

{"event":"start","userId":"u1","ts":1}{"event":"action","userId":"u1","ts":2}{"event":"end","userId":"u1","ts":3}

bash

$ openclaw path find 'oc://session.jsonl/[event=action]/userId' --file session.jsonl --human1 match for oc://session.jsonl/[event=action]/userId:  oc://session.jsonl/L2/userId  →  leaf @ L2: "u1" (string) $ openclaw path resolve 'oc://session.jsonl/L2/ts' --file session.jsonl --humanleaf @ L2: "2" (number)

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

YAML

text

# workflow.yamlname: inbox-triagesteps:  - id: fetch    command: gmail.search  - id: classify    command: openclaw.invoke

bash

$ openclaw path resolve 'oc://workflow.yaml/steps/0/id' --file workflow.yaml --humanleaf @ L3: "fetch" (string) $ openclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --file workflow.yaml --dry-run--dry-run: would write 99 bytes to /…/workflow.yamlname: inbox-triagesteps:  - id: fetch    command: gmail.search  - id: classify-renamed    command: openclaw.invoke

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

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

`resolve <oc-path>`

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

bash

openclaw path resolve 'oc://AGENTS.md/tools/gh/risk' --humanopenclaw path resolve 'oc://gateway.jsonc/server/port' --json

`find <pattern>`

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

bash

openclaw path find 'oc://AGENTS.md/tools/**/risk'openclaw path find 'oc://session.jsonl/[event=action]/userId'openclaw path find 'oc://config.jsonc/plugins/{github,slack}/enabled'

`set <oc-path> <value>`

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

bash

openclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-runopenclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run --diffopenclaw path set 'oc://gateway.jsonc/version' '2.0'openclaw path set 'oc://AGENTS.md/Tools/+gh/risk' 'low'

Маркер вставлення +key створює дочірній елемент із заданою назвою, якщо він ще не існує; +nnn і окремий + використовуються відповідно для вставлення за індексом і додавання в кінець.

`validate <oc-path>`

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

bash

$ openclaw path validate 'oc://AGENTS.md/tools/gh' --humanvalid: oc://AGENTS.md/tools/gh  file:    AGENTS.md  section: tools  item:    gh

Завершується з кодом 0, якщо шлях коректний, 1, якщо некоректний (зі структурованими полями code і message), та 2 у разі помилок аргументів.

`emit <file>`

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

bash

openclaw path emit ./AGENTS.mdopenclaw path emit ./gateway.jsonc --json

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

Код	Значення
`0`	Успіх. (`resolve` / `find`: принаймні один збіг. `set`: запис виконано успішно.)
`1`	Немає збігу або `set` відхилено базовим шаром (без помилки на рівні системи).
`2`	Помилка аргументів або синтаксичного розбору.

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

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

Примітки

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

Пов’язане

Довідник CLI

Was this useful?

На цій сторінці

Шлях

`openclaw path`

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

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

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

Підкоманди

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

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

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

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

Приклади

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

Markdown

JSONC

JSONL

YAML

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

`resolve <oc-path>`

`find <pattern>`

`set <oc-path> <value>`

`validate <oc-path>`

`emit <file>`

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

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

Примітки

Пов’язане

Molty

На цій сторінці

openclaw path

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

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

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

Підкоманди

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

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

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

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

Приклади

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

Markdown

JSONC

JSONL

YAML

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

resolve <oc-path>

find <pattern>

set <oc-path> <value>

validate <oc-path>

emit <file>

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

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

Примітки

Пов’язане

`openclaw path`

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

`resolve <oc-path>`

`find <pattern>`

`set <oc-path> <value>`

`validate <oc-path>`

`emit <file>`