--- read_when: - Ви хочете прочитати або записати кінцевий елемент у файлі робочого простору з термінала - Ви створюєте сценарій для роботи зі станом робочого простору й потребуєте стабільної схеми адресації, незалежної від типу - Ви налагоджуєте шлях `oc://` (перевірте синтаксис і з’ясуйте, на що він розгортається) summary: Довідник CLI для `openclaw path` (перегляд і редагування файлів робочого простору за допомогою схеми адресації `oc://`) title: Шлях x-i18n: generated_at: "2026-07-12T13:09:00Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 7afe5bd1c3a5fca8dd22c7d807e390e751ae7e895c54bf0e10e2734f3889436c source_path: cli/path.md workflow: 16 --- # `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`, коли результат переглядає людина. ## Принцип роботи 1. Аналізує адресу `oc://` і розділяє її на позиції: файл, розділ, елемент, поле та необов’язковий запит сеансу. 2. Вибирає адаптер типу файлу за розширенням цільового файлу (`.md`, `.jsonc`, `.json`, `.jsonl`, `.ndjson`, `.yaml`, `.yml`, `.lobster`). 3. Розв’язує позиції відповідно до структури цього типу файлу: заголовки й елементи markdown, ключі об’єктів та індекси масивів JSONC, рядкові записи JSONL або вузли відображень і послідовностей YAML. 4. Для `set` виводить відредаговані байти через той самий адаптер, щоб незмінені частини файлу зберігали коментарі, завершення рядків і форматування поруч, якщо тип файлу це підтримує. `resolve` і `set` потребують однієї конкретної цілі. `find` — дієслово для дослідження: воно розгортає символи підстановки, об’єднання, предикати й порядкові номери в конкретні збіги, які можна перевірити перед вибором цілі для запису. ## Підкоманди | Підкоманда | Призначення | | ----------------------- | --------------------------------------------------------------------------- | | `resolve ` | Вивести конкретний збіг за шляхом (або «не знайдено»). | | `find ` | Перелічити збіги для шляху із символом підстановки, об’єднанням або предикатом. | | `set ` | Записати кінцеве значення або ціль вставлення за конкретним шляхом. Підтримує `--dry-run`. | | `validate ` | Лише аналіз; вивести структурний поділ (файл / розділ / елемент / поле). | | `emit ` | Виконати повний цикл аналізу й виведення файлу (діагностика побайтової відповідності). | ## Глобальні прапорці | Прапорець | Застосовується до | Призначення | | --------------- | --------------------------------- | ------------------------------------------------------------------------ | | `--cwd ` | `resolve`, `find`, `set`, `emit` | Розв’язувати позицію файлу відносно цього каталогу (типово: `process.cwd()`). | | `--file ` | `resolve`, `find`, `set`, `emit` | Перевизначити розв’язаний шлях позиції файлу (абсолютний доступ). | | `--json` | усіх | Примусово використовувати виведення JSON (типово, коли stdout не є TTY). | | `--human` | усіх | Примусово використовувати зручне для людини виведення (типово, коли stdout є TTY). | | `--value-json` | `set` | Аналізувати `` як 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]`, `[kv]`, `[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 має аналізувати `` як JSON і може змінити структуру, наприклад замінити скорочене рядкове посилання на секрет об’єктом. Вставлення в об’єкти й масиви JSONC аналізують `` як JSON і використовують шлях редагування `jsonc-parser` для звичайного запису кінцевих значень, зберігаючи коментарі та форматування поруч. - Записи кінцевих значень JSONL усередині рядка виконують перетворення так само, як JSONC. Заміна цілого рядка й дописування аналізують `` як 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 subsegments openclaw path set 'oc://openclaw.json/agents/list/0/tools/exec/security' 'allowlist' --dry-run # Replace a JSONC leaf with a parsed object openclaw path set 'oc://openclaw.json/gateway/auth/token' '{"source":"file","provider":"secrets","id":"/test"}' --value-json --dry-run # Predicate search over JSONC children openclaw path find 'oc://config.jsonc/plugins/[enabled=true]/id' # Insert into a JSONC array openclaw path set 'oc://config.jsonc/items/+1' '{"id":"new","enabled":true}' --dry-run # Insert a JSONC object key openclaw path set 'oc://config.jsonc/plugins/+github' '{"enabled":true}' --dry-run # Append a JSONL event openclaw path set 'oc://session.jsonl/+' '{"event":"checkpoint","ok":true}' --file ./logs/session.jsonl # Resolve the last JSONL value line openclaw path resolve 'oc://session.jsonl/$last/event' --file ./logs/session.jsonl # Resolve a YAML workflow step openclaw path resolve 'oc://workflow.yaml/steps/0/id' # Update a YAML scalar openclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --dry-run # Address markdown frontmatter openclaw path resolve 'oc://AGENTS.md/[frontmatter]/name' # Insert markdown frontmatter openclaw path set 'oc://AGENTS.md/[frontmatter]/+description' 'Agent instructions' --dry-run # Find markdown item fields openclaw path find 'oc://SKILL.md/Tools/*/send_email' # Validate a session-scoped path openclaw path validate 'oc://AGENTS.md/Tools/$last/risk?session=cron-daily' ``` ## Рецепти за типами файлів Ті самі п’ять дієслів працюють для всіх типів; схема адресації вибирає обробник за розширенням файлу. ### Markdown ```text --- name: drafter description: email drafting agent tier: core --- ## Tools - gh: GitHub CLI - curl: HTTP client - send_email: enabled ``` ```bash $ openclaw path resolve 'oc://x.md/[frontmatter]/tier' --file frontmatter.md --human leaf @ L4: "core" (string) $ openclaw path resolve 'oc://x.md/tools/gh/gh' --file frontmatter.md --human leaf @ L9: "GitHub CLI" (string) $ openclaw path find 'oc://x.md/tools/*' --file frontmatter.md --human 3 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 --human leaf @ 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 --human 1 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 --human leaf @ L2: "2" (number) ``` Кожен рядок є записом. Адресуйте його за предикатом (`[event=action]`), якщо номер рядка невідомий, або за канонічним сегментом `LN`, якщо він відомий. Файли `.ndjson` використовують той самий адаптер, що й `.jsonl`. ### YAML ```text # workflow.yaml name: inbox-triage steps: - id: fetch command: gmail.search - id: classify command: openclaw.invoke ``` ```bash $ openclaw path resolve 'oc://workflow.yaml/steps/0/id' --file workflow.yaml --human leaf @ 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.yaml name: inbox-triage steps: - id: fetch command: gmail.search - id: classify-renamed command: openclaw.invoke ``` YAML використовує API `Document` пакета `yaml` замість самописного парсера, тому звичайні цикли розбору та виведення зберігають коментарі й авторську структуру, а вирішені шляхи використовують ту саму модель ключів мапи та індексів послідовності, що й JSONC. Той самий адаптер обробляє файли `.yaml`, `.yml` і `.lobster`. ## Довідник підкоманд ### `resolve ` Читає один листовий елемент або вузол. Шаблони не підтримуються — для них використовуйте `find`. Завершується з кодом `0` у разі збігу, `1` у разі коректної відсутності збігу, `2` у разі помилки розбору або відхиленого шаблону. ```bash openclaw path resolve 'oc://AGENTS.md/tools/gh/risk' --human openclaw path resolve 'oc://gateway.jsonc/server/port' --json ``` ### `find ` Перелічує всі збіги для шаблону із символами узагальнення, предикатом або об’єднанням. Завершується з кодом `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 ` Записує листовий елемент. Використовуйте разом із `--dry-run`, щоб попередньо переглянути байти, які буде записано, не змінюючи файл. Додайте `--diff`, щоб переглянути уніфіковану різницю. Завершується з кодом `0` після успішного запису, `1`, якщо базовий шар відхиляє операцію (наприклад, спрацював захист сигнального значення), і `2` у разі помилки розбору. ```bash 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 set 'oc://AGENTS.md/Tools/+gh/risk' 'low' ``` Маркер вставлення `+key` створює дочірній елемент із заданою назвою, якщо він ще не існує; `+nnn` і окремий `+` використовуються відповідно для вставлення за індексом і додавання в кінець. ### `validate ` Перевірка лише синтаксичного розбору. Без доступу до файлової системи. Корисна, коли потрібно переконатися, що шлях шаблону сформовано правильно, перш ніж підставляти змінні, або отримати структурну декомпозицію для налагодження: ```bash $ openclaw path validate 'oc://AGENTS.md/tools/gh' --human valid: oc://AGENTS.md/tools/gh file: AGENTS.md section: tools item: gh ``` Завершується з кодом `0`, якщо шлях коректний, `1`, якщо некоректний (зі структурованими полями `code` і `message`), та `2` у разі помилок аргументів. ### `emit ` Пропускає файл через парсер і засіб виведення для відповідного типу. Для коректного файлу результат має бути побайтно ідентичним вхідним даним; розбіжність указує на помилку парсера або спрацювання сигнального значення. Корисно для налагодження поведінки базового шару на реальних вхідних даних. ```bash openclaw path emit ./AGENTS.md openclaw 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](/uk/cli)