openclaw path

Dostęp powłoki dostarczany przez Plugin do podłoża adresowania oc://: jeden schemat ścieżek rozdzielany według rodzaju do inspekcji i edycji adresowalnych plików obszaru roboczego (markdown, jsonc, jsonl, yaml/yml/lobster). Osoby self-hostujące, autorzy Pluginów i rozszerzenia edytorów używają go do odczytu, wyszukiwania lub aktualizowania wąskiej lokalizacji bez ręcznego tworzenia parserów dla każdego typu pliku.

CLI odzwierciedla publiczne czasowniki podłoża:

• resolve jest konkretny i zwraca pojedyncze dopasowanie.
• find jest czasownikiem wielu dopasowań dla symboli wieloznacznych, unii, predykatów i rozwijania pozycyjnego.
• set akceptuje tylko konkretne ścieżki lub znaczniki wstawiania; wzorce wieloznaczne są odrzucane przed zapisem.

path jest dostarczany przez dołączony opcjonalny Plugin oc-path. Włącz go przed pierwszym użyciem:

openclaw plugins enable oc-path

Dlaczego warto go używać

Stan OpenClaw jest rozproszony między edytowanym przez ludzi markdownem, komentowaną konfiguracją JSONC, dopisywanymi tylko na końcu logami JSONL oraz plikami przepływów pracy/specyfikacji YAML. Skrypty powłoki, hooki i agenci często potrzebują jednej małej wartości z tych plików: klucza frontmatter, ustawienia Pluginu, pola rekordu logu, kroku YAML albo elementu listy pod nazwaną sekcją.

openclaw path daje takim wywołującym stabilny adres zamiast jednorazowego grepa, regexu lub parsera dla każdego rodzaju pliku. Tę samą ścieżkę oc:// można zweryfikować, rozwiązać, przeszukać, uruchomić próbnie i zapisać z terminala, dzięki czemu wąska automatyzacja jest łatwiejsza do przeglądu i bezpieczniejsza do ponownego wykonania. Jest to szczególnie przydatne, gdy chcesz zaktualizować jeden liść, zachowując resztę komentarzy pliku, zakończenia linii i otaczające formatowanie.

Użyj go, gdy potrzebna rzecz ma logiczny adres, ale fizyczny kształt pliku się różni:

• Hook chce odczytać jedno ustawienie z komentowanego JSONC bez utraty komentarzy przy zapisie wartości z powrotem.
• Skrypt konserwacyjny chce znaleźć każde pasujące pole zdarzenia w logu JSONL bez ładowania całego logu do niestandardowego parsera.
• Rozszerzenie edytora chce przeskoczyć do sekcji markdown lub elementu listy według sluga, a następnie wyrenderować dokładną linię, do której ścieżka została rozwiązana.
• Agent chce próbnie uruchomić drobną edycję obszaru roboczego przed jej zastosowaniem, z bajtami zmian widocznymi w przeglądzie.

Prawdopodobnie nie potrzebujesz openclaw path do zwykłych edycji całych plików, bogatych migracji konfiguracji ani zapisów specyficznych dla pamięci. Powinny one używać polecenia lub Pluginu właściciela. path służy do małych, adresowalnych operacji na plikach, gdzie powtarzalne polecenie terminala jest czytelniejsze niż kolejny dedykowany parser.

Jak jest używany

Odczytaj jedną wartość z pliku konfiguracji edytowanego przez ludzi:

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

Podejrzyj zapis bez dotykania dysku:

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

Znajdź pasujące rekordy w logu JSONL dopisywanym tylko na końcu:

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

Zaadresuj instrukcję w markdownie według sekcji i elementu zamiast numeru linii:

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

Zweryfikuj ścieżkę w CI lub skrypcie preflight, zanim skrypt zacznie czytać albo pisać:

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

Te polecenia mają nadawać się do kopiowania do skryptów powłoki. Użyj --json, gdy wywołujący potrzebuje ustrukturyzowanego wyjścia, oraz --human, gdy wynik ogląda człowiek.

Jak to działa

openclaw path robi cztery rzeczy:

1. Parsuje adres oc:// na sloty: plik, sekcja, element, pole i opcjonalna sesja.
2. Wybiera adapter rodzaju pliku na podstawie rozszerzenia celu (.md, .jsonc, .jsonl, .yaml, .yml, .lobster oraz powiązanych aliasów).
3. Rozwiązuje sloty względem AST tego rodzaju pliku: nagłówków/elementów markdown, kluczy obiektów/indeksów tablic JSONC, rekordów linii JSONL albo węzłów map/sekwencji YAML.
4. Dla set emituje zmienione bajty przez ten sam adapter, dzięki czemu nietknięte części pliku zachowują swoje komentarze, zakończenia linii i pobliskie formatowanie tam, gdzie dany rodzaj to obsługuje.

resolve i set wymagają jednego konkretnego celu. find jest czasownikiem eksploracyjnym: rozwija symbole wieloznaczne, unie, predykaty i liczebniki porządkowe do konkretnych dopasowań, które możesz sprawdzić przed wybraniem jednego do zapisu.

Podpolecenia

Flagi globalne

Składnia oc://

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

Reguły slotów: field wymaga item, a item wymaga section. We wszystkich czterech slotach:

• Cytowane segmenty — "a/b.c" zachowuje separatory / i .. Zawartość jest dosłowna bajtowo; " i \ nie są dozwolone wewnątrz cudzysłowów. Slot pliku również obsługuje cudzysłowy: oc://"skills/email-drafter"/Tools/$last traktuje skills/email-drafter jako jedną ścieżkę pliku.
• Predykaty — [k=v], [k!=v], [k<v], [k<=v], [k>v], [k>=v]. Operacje numeryczne wymagają, aby obie strony dały się przekształcić do skończonych liczb.
• Unie — {a,b,c} dopasowuje dowolną z alternatyw.
• Symbole wieloznaczne — * (pojedynczy podsegment) i ** (zero lub więcej, rekurencyjnie). find je akceptuje; resolve i set odrzucają je jako niejednoznaczne.
• Pozycyjne — $first / $last rozwiązują się do pierwszego / ostatniego indeksu albo zadeklarowanego klucza.
• Porządkowe — #N dla N-tego dopasowania według kolejności w dokumencie.
• Znaczniki wstawiania — +, +key, +nnn dla wstawiania z kluczem / indeksem (używaj z set).
• Zakres sesji — ?session=cron-daily itd. Niezależny od zagnieżdżenia slotów. Wartości sesji są surowe, nie dekodowane procentowo; nie mogą zawierać znaków kontrolnych ani zarezerwowanych separatorów zapytania (?, &, %).

Zarezerwowane znaki (?, &, %) poza cytowanymi, predykatowymi lub unijnymi segmentami są odrzucane. Znaki kontrolne (U+0000-U+001F, U+007F) są odrzucane wszędzie, również w wartości zapytania session.

formatOcPath(parseOcPath(path)) === path jest gwarantowane dla ścieżek kanonicznych. Niekanoniczne parametry zapytania są ignorowane z wyjątkiem pierwszej niepustej wartości session=.

Adresowanie według rodzaju pliku

resolve zwraca ustrukturyzowane dopasowanie: root, node, leaf albo insertion-point, z 1-indeksowanym numerem linii. Wartości liści są udostępniane jako tekst plus leafType, aby autorzy Pluginów mogli renderować podglądy bez zależności od kształtu AST danego rodzaju pliku.

Kontrakt mutacji

set zapisuje jeden konkretny cel:

• Wartości frontmatter markdown i pola elementów - key: value są liśćmi tekstowymi. Wstawienia markdown dopisują sekcje, klucze frontmatter albo elementy sekcji i renderują kanoniczny kształt markdown dla zmienionego pliku.
• Zapisy liści JSONC przekształcają wartość tekstową do istniejącego typu liścia (string, skończony number, true/false albo null). Użyj --value-json, gdy zamiana liścia JSONC/JSON/JSONL powinna sparsować <value> jako JSON i może zmienić kształt, na przykład zastępując tekstowy skrót SecretRef obiektem. Wstawienia obiektów i tablic JSONC parsują <value> jako JSON i używają ścieżki edycji jsonc-parser dla zwykłych zapisów liści, zachowując komentarze i pobliskie formatowanie.
• Zapisy liści JSONL przekształcają jak JSONC wewnątrz linii. Zamiana całej linii i dopisanie parsują <value> jako JSON. Renderowany JSONL zachowuje dominującą w pliku konwencję zakończeń linii LF/CRLF.
• Zapisy liści YAML przekształcają do istniejącego typu skalarnego (string, skończony number, true/false albo null). Wstawienia YAML używają API dokumentu dołączonego pakietu yaml do aktualizacji map/sekwencji. Niepoprawne dokumenty YAML z błędami parsera są odrzucane przed mutacją z parse-error.

Użyj --dry-run przed zapisami widocznymi dla użytkownika, gdy dokładne bajty mają znaczenie. Podłoże zachowuje bajtowo identyczne wyjście dla rund parse/emit, ale mutacja może skanonizować edytowany region lub plik zależnie od rodzaju. Dodaj --diff, gdy chcesz podgląd jako skupioną łatkę przed/po zamiast pełnego wyrenderowanego pliku.

Przykłady

# Validate a path (no filesystem access)openclaw path validate 'oc://AGENTS.md/Tools/$last/risk' # Read a leafopenclaw path resolve 'oc://gateway.jsonc/version' # Wildcard searchopenclaw path find 'oc://session.jsonl/*/event' --file ./logs/session.jsonl # Dry-run a writeopenclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run # Dry-run a write as a unified diffopenclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run --diff # Apply the writeopenclaw path set 'oc://gateway.jsonc/version' '2.0' # Byte-fidelity round-trip (diagnostic)openclaw path emit ./AGENTS.md

Więcej przykładów gramatyki:

# 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'

Przepisy według rodzaju pliku

Te same pięć czasowników działa we wszystkich rodzajach; schemat adresowania wybiera obsługę na podstawie rozszerzenia pliku. Poniższe przykłady używają fixture’ów z opisu PR.

Markdown

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

$ 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]

Predykat [frontmatter] adresuje blok frontmatter YAML; tools dopasowuje nagłówek ## Tools przez slug, a liście elementów zachowują formę sluga nawet wtedy, gdy źródło używa podkreśleń (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 --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"}  }}

Edycje JSONC przechodzą przez jsonc-parser, więc komentarze i odstępy przetrwają operację set. Najpierw uruchom z --dry-run, aby sprawdzić bajty przed zatwierdzeniem.

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 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)

Każda linia jest rekordem. Adresuj przez predykat ([event=action]), gdy nie znasz numeru linii, albo przez kanoniczny segment LN, gdy go znasz.

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 --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 używa API Document pakietu yaml, a nie ręcznie pisanego parsera, więc zwykłe cykle parsowania i emitowania zachowują komentarze oraz kształt autorski, podczas gdy rozwiązane ścieżki używają tego samego modelu klucza mapy / indeksu sekwencji co JSONC. Ten sam adapter obsługuje pliki .yaml, .yml i .lobster.

Dokumentacja podkomend

resolve <oc-path>

Odczytaj pojedynczy liść lub węzeł. Symbole wieloznaczne są odrzucane — do nich użyj find. Kończy z kodem 0 przy dopasowaniu, 1 przy czystym braku trafienia, 2 przy błędzie parsowania lub odrzuconym wzorcu.

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

find <pattern>

Wylicz każde dopasowanie dla wzorca z symbolem wieloznacznym / predykatem / unią. Kończy z kodem 0 przy co najmniej jednym dopasowaniu, 1 przy zerze dopasowań. Symbole wieloznaczne w slocie pliku są odrzucane z OC_PATH_FILE_WILDCARD_UNSUPPORTED — przekaż konkretny plik (globowanie wielu plików to przyszła funkcja).

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>

Zapisz liść. Połącz z --dry-run, aby podejrzeć bajty, które zostałyby zapisane bez dotykania pliku. Dodaj --diff, aby uzyskać podgląd zunifikowanego diffu. Kończy z kodem 0 przy udanym zapisie, 1, jeśli substrat odmawia (na przykład po trafieniu osłony sentinel), 2 przy błędach parsowania.

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'

Znacznik wstawienia +key tworzy nazwane dziecko, jeśli jeszcze nie istnieje; +nnn i samo + działają odpowiednio dla wstawiania indeksowanego i dopisywania.

validate <oc-path>

Kontrola wyłącznie parsowania. Bez dostępu do systemu plików. Przydatne, gdy chcesz potwierdzić, że ścieżka szablonu jest poprawnie uformowana przed podstawieniem zmiennych, albo gdy potrzebujesz strukturalnego rozbicia do debugowania:

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

Kończy z kodem 0, gdy jest poprawne, 1, gdy jest niepoprawne (ze strukturalnym code i message), 2 przy błędach argumentów.

emit <file>

Przepuść plik w obie strony przez parser i emiter właściwe dla danego rodzaju. Wynik powinien być identyczny bajtowo z wejściem dla poprawnego pliku — rozbieżność wskazuje błąd parsera lub trafienie sentinel. Przydatne do debugowania zachowania substratu na rzeczywistych danych wejściowych.

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

Kody wyjścia

Tryb wyjścia

openclaw path rozpoznaje TTY: na terminalu zwraca wyjście czytelne dla człowieka, a JSON, gdy stdout jest potokowany lub przekierowany. --json i --human nadpisują automatyczne wykrywanie.

Uwagi

• set zapisuje bajty przez ścieżkę emitowania substratu, która automatycznie stosuje osłonę sentinel redakcji. Liść zawierający __OPENCLAW_REDACTED__ (dosłownie lub jako podciąg) jest odrzucany podczas zapisu.
• Parsowanie JSONC i edycje liści używają zależności jsonc-parser lokalnej dla Pluginu, więc komentarze i formatowanie są zachowywane przy zwykłych zapisach liści zamiast przechodzić przez ręcznie napisany parser / ścieżkę ponownego renderowania.
• path nie wie o LKG. Jeśli plik jest śledzony przez LKG, następne wywołanie observe decyduje, czy wykonać promowanie / odzyskiwanie. set --batch dla atomowego wielokrotnego ustawiania przez cykl życia promowania/odzyskiwania LKG jest planowane razem z substratem odzyskiwania LKG.

Powiązane

• Dokumentacja CLI