openclaw path

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

path предоставляется встроенным необязательным плагином oc-path. Включите его перед первым использованием:

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

Использование

Считайте одно значение из редактируемого вручную файла конфигурации:

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

Предварительно просмотрите результат записи, не изменяя данные на диске:

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

Найдите совпадающие записи в журнале JSONL только для добавления:

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

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

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

Проверьте путь в CI или предварительном скрипте до того, как скрипт выполнит чтение или запись:

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 — команда для исследования: она раскрывает подстановочные знаки, объединения, предикаты и порядковые номера в конкретные совпадения, которые можно просмотреть перед выбором одного из них для записи.

Подкоманды

Глобальные флаги

validate принимает только --json / --human; эта команда не обращается к файловой системе, поэтому --cwd и --file к ней неприменимы.

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

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 MiB отклоняется с диагностикой разбора вместо выполнения разбора для любой команды, загружающей этот файл.

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

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, чтобы получить предварительный просмотр в виде сфокусированного патча до/после вместо полного сформированного файла.

Примеры

# Проверить путь (без доступа к файловой системе)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

Дополнительные примеры грамматики:

# Заключайте в кавычки ключи, содержащие / или .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 # Поиск по предикату среди дочерних элементов JSONCopenclaw path find 'oc://config.jsonc/plugins/[enabled=true]/id' # Вставить элемент в массив JSONCopenclaw path set 'oc://config.jsonc/items/+1' '{"id":"new","enabled":true}' --dry-run # Вставить ключ объекта JSONCopenclaw path set 'oc://config.jsonc/plugins/+github' '{"enabled":true}' --dry-run # Добавить событие JSONLopenclaw path set 'oc://session.jsonl/+' '{"event":"checkpoint","ok":true}' --file ./logs/session.jsonl # Разрешить последнюю строку значений JSONLopenclaw path resolve 'oc://session.jsonl/$last/event' --file ./logs/session.jsonl # Разрешить шаг рабочего процесса YAMLopenclaw path resolve 'oc://workflow.yaml/steps/0/id' # Обновить скаляр YAMLopenclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --dry-run # Обратиться к frontmatter Markdownopenclaw path resolve 'oc://AGENTS.md/[frontmatter]/name' # Вставить frontmatter Markdownopenclaw path set 'oc://AGENTS.md/[frontmatter]/+description' 'Agent instructions' --dry-run # Найти поля элементов Markdownopenclaw path find 'oc://SKILL.md/Tools/*/send_email' # Проверить путь в области сеансаopenclaw path validate 'oc://AGENTS.md/Tools/$last/risk?session=cron-daily'

Рецепты по типам файлов

Для всех типов работают одни и те же пять команд; схема адресации выбирает обработчик по расширению файла.

Markdown

<!-- frontmatter.md -->---name: составительdescription: агент составления электронных писемtier: основной---## Инструменты- gh: CLI GitHub- curl: клиент HTTP- send_email: включено

$ 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 --human3 совпадения для 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

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

$ 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

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

$ openclaw path find 'oc://session.jsonl/[event=action]/userId' --file session.jsonl --human1 совпадение для 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

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

$ 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.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 при ошибке разбора или отклонённом шаблоне.

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 — передайте конкретный файл (поддержка шаблонов для нескольких файлов будет добавлена позже).

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 при ошибках разбора.

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>

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

$ openclaw path validate 'oc://AGENTS.md/tools/gh' --humanкорректно: oc://AGENTS.md/tools/gh  файл:    AGENTS.md  раздел:  tools  элемент: gh

Завершается с кодом 0 для корректного пути, 1 для некорректного (со структурированными code и message) и 2 при ошибках аргументов.

emit <file>

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

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

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

Режим вывода

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

Примечания

• set записывает байты через путь отправки базового слоя, который автоматически применяет защиту с помощью маркера редактирования. Листовое значение, содержащее __OPENCLAW_REDACTED__ (дословно или как подстроку), отклоняется во время записи.
• Для разбора JSONC и редактирования листовых значений используется локальная для плагина зависимость jsonc-parser, поэтому при обычной записи листовых значений комментарии и форматирование сохраняются, а сам процесс не проходит через самописный путь разбора и повторного рендеринга.
• path не отслеживает конфигурацию с последним известным рабочим состоянием (LKG) и не выполняет её восстановление; за этот жизненный цикл отвечает другой компонент. Если файл, редактируемый через path, также отслеживается как LKG, при следующем чтении конфигурации определяется, следует ли принять его как актуальный или восстановить; рассматривайте редактирование через path так же, как любую другую прямую запись в этот файл.

Связанные материалы

• Справочник CLI