--- read_when: - Вы хотите прочитать или записать конечный элемент в файле рабочей области из терминала - Вы пишете скрипт для работы с состоянием рабочего пространства и хотите использовать стабильную схему адресации, не зависящую от типа объекта - Вы отлаживаете путь `oc://` (проверьте синтаксис и посмотрите, во что он разрешается) summary: Справочник по CLI для `openclaw path` (просмотр и редактирование файлов рабочего пространства с помощью схемы адресации `oc://`) title: Путь x-i18n: generated_at: "2026-07-13T19:39:30Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 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. Скриптам, хукам и агентам часто требуется одно небольшое значение из этих файлов: ключ метаданных, настройка плагина, поле записи журнала, шаг 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 MiB отклоняется с диагностикой разбора вместо выполнения разбора для любой команды, загружающей этот файл. ## Адресация по типу файла | Тип | Расширения файлов | Модель адресации | | ------------- | --------------------------- | --------------------------------------------------------------------------------------------------- | | Markdown | `.md` | Разделы H2 по слагу, элементы маркированного списка по слагу или `#N`, метаданные через `[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 # Заключайте в кавычки ключи, содержащие / или . openclaw path resolve 'oc://config.jsonc/agents.defaults.models/"anthropic/claude-opus-4-7"/alias' # Глубокие пути JSON/JSONC могут использовать сегменты с косой чертой; они нормализуются в точечные подсегменты openclaw path set 'oc://openclaw.json/agents/list/0/tools/exec/security' 'allowlist' --dry-run # Заменить лист JSONC разобранным объектом openclaw path set 'oc://openclaw.json/gateway/auth/token' '{"source":"file","provider":"secrets","id":"/test"}' --value-json --dry-run # Поиск по предикату среди дочерних элементов JSONC openclaw path find 'oc://config.jsonc/plugins/[enabled=true]/id' # Вставить элемент в массив JSONC openclaw path set 'oc://config.jsonc/items/+1' '{"id":"new","enabled":true}' --dry-run # Вставить ключ объекта JSONC openclaw path set 'oc://config.jsonc/plugins/+github' '{"enabled":true}' --dry-run # Добавить событие JSONL openclaw path set 'oc://session.jsonl/+' '{"event":"checkpoint","ok":true}' --file ./logs/session.jsonl # Разрешить последнюю строку значений JSONL openclaw path resolve 'oc://session.jsonl/$last/event' --file ./logs/session.jsonl # Разрешить шаг рабочего процесса YAML openclaw path resolve 'oc://workflow.yaml/steps/0/id' # Обновить скаляр YAML openclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --dry-run # Обратиться к frontmatter Markdown openclaw path resolve 'oc://AGENTS.md/[frontmatter]/name' # Вставить frontmatter Markdown openclaw path set 'oc://AGENTS.md/[frontmatter]/+description' 'Agent instructions' --dry-run # Найти поля элементов Markdown openclaw path find 'oc://SKILL.md/Tools/*/send_email' # Проверить путь в области сеанса openclaw path validate 'oc://AGENTS.md/Tools/$last/risk?session=cron-daily' ``` ## Рецепты по типам файлов Для всех типов работают одни и те же пять команд; схема адресации выбирает обработчик по расширению файла. ### Markdown ```text --- name: составитель description: агент составления электронных писем tier: основной --- ## Инструменты - gh: CLI GitHub - curl: клиент HTTP - send_email: включено ``` ```bash $ openclaw path resolve 'oc://x.md/[frontmatter]/tier' --file frontmatter.md --human лист @ L4: "основной" (строка) $ openclaw path resolve 'oc://x.md/tools/gh/gh' --file frontmatter.md --human лист @ L9: "CLI GitHub" (строка) $ openclaw path find 'oc://x.md/tools/*' --file frontmatter.md --human 3 совпадения для oc://x.md/tools/*: oc://x.md/tools/gh → узел @ L9 [md-item] oc://x.md/tools/curl → узел @ L10 [md-item] oc://x.md/tools/send-email → узел @ L11 [md-item] ``` Предикат `[frontmatter]` адресует блок 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 лист @ L4: "true" (логическое значение) $ openclaw path set 'oc://config.jsonc/plugins/slack/enabled' 'true' --file config.jsonc --dry-run --dry-run: будет записано 142 байта в /…/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 совпадение для oc://session.jsonl/[event=action]/userId: oc://session.jsonl/L2/userId → лист @ L2: "u1" (строка) $ openclaw path resolve 'oc://session.jsonl/L2/ts' --file session.jsonl --human лист @ L2: "2" (число) ``` Каждая строка является записью. Если номер строки неизвестен, обращайтесь по предикату (`[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 лист @ L3: "fetch" (строка) $ openclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --file workflow.yaml --dry-run --dry-run: будет записано 99 байт в /…/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 корректно: oc://AGENTS.md/tools/gh файл: AGENTS.md раздел: tools элемент: 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: в терминале используется удобочитаемый вывод, а при передаче stdout через канал или перенаправлении — JSON. `--json` и `--human` переопределяют автоматическое определение. ## Примечания - `set` записывает байты через путь отправки базового слоя, который автоматически применяет защиту с помощью маркера редактирования. Листовое значение, содержащее `__OPENCLAW_REDACTED__` (дословно или как подстроку), отклоняется во время записи. - Для разбора JSONC и редактирования листовых значений используется локальная для плагина зависимость `jsonc-parser`, поэтому при обычной записи листовых значений комментарии и форматирование сохраняются, а сам процесс не проходит через самописный путь разбора и повторного рендеринга. - `path` не отслеживает конфигурацию с последним известным рабочим состоянием (LKG) и не выполняет её восстановление; за этот жизненный цикл отвечает другой компонент. Если файл, редактируемый через `path`, также отслеживается как LKG, при следующем чтении конфигурации определяется, следует ли принять его как актуальный или восстановить; рассматривайте редактирование через `path` так же, как любую другую прямую запись в этот файл. ## Связанные материалы - [Справочник CLI](/ru/cli)