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:
resolvejest konkretny i zwraca pojedyncze dopasowanie.findjest czasownikiem wielu dopasowań dla symboli wieloznacznych, unii, predykatów i rozwijania pozycyjnego.setakceptuje 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:
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.
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:--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:
- Parsuje adres
oc://na sloty: plik, sekcja, element, pole i opcjonalna sesja. - Wybiera adapter rodzaju pliku na podstawie rozszerzenia celu (
.md,.jsonc,.jsonl,.yaml,.yml,.lobsteroraz powiązanych aliasów). - 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.
- Dla
setemituje 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
| Podpolecenie | Cel |
|---|---|
resolve <oc-path> | Wypisz konkretne dopasowanie pod ścieżką (albo „nie znaleziono”). |
find <pattern> | Wylicz dopasowania dla ścieżki z symbolem wieloznacznym / unią / predykatem. |
set <oc-path> <value> | Zapisz liść lub cel wstawiania pod konkretną ścieżką. Obsługuje --dry-run. |
validate <oc-path> | Tylko parsowanie; wypisz rozbicie strukturalne (plik / sekcja / element / pole). |
emit <file> | Przepuść plik w obie strony przez parseXxx + emitXxx (diagnostyka wierności bajtowej). |
Flagi globalne
| Flaga | Cel |
|---|---|
--cwd <dir> | Rozwiąż slot pliku względem tego katalogu (domyślnie: process.cwd()). |
--file <path> | Nadpisz rozwiązaną ścieżkę slotu pliku (dostęp bezwzględny). |
--json | Wymuś wyjście JSON (domyślne, gdy stdout nie jest TTY). |
--human | Wymuś wyjście dla człowieka (domyślne, gdy stdout jest TTY). |
--dry-run | (tylko dla set) wypisz bajty, które zostałyby zapisane, bez zapisywania. |
--diff | (z set --dry-run) wypisz zunifikowany diff zamiast pełnych bajtów. |
Składnia oc://
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/$lasttraktujeskills/email-drafterjako 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).findje akceptuje;resolveisetodrzucają je jako niejednoznaczne. - Pozycyjne —
$first/$lastrozwiązują się do pierwszego / ostatniego indeksu albo zadeklarowanego klucza. - Porządkowe —
#Ndla N-tego dopasowania według kolejności w dokumencie. - Znaczniki wstawiania —
+,+key,+nnndla wstawiania z kluczem / indeksem (używaj zset). - Zakres sesji —
?session=cron-dailyitd. 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 (?,&,%).
?, &, %) 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
| Rodzaj | Model adresowania |
|---|---|
| Markdown | Sekcje H2 według sluga, elementy listy według sluga lub #N, frontmatter przez [frontmatter]. |
| JSONC/JSON | Klucze obiektów i indeksy tablic; kropki dzielą zagnieżdżone podsegmenty, chyba że są cytowane. |
| JSONL | Adresy linii najwyższego poziomu (L1, L2, $first, $last), potem zejście w stylu JSONC wewnątrz linii. |
| YAML/YML/.lobster | Klucze map i indeksy sekwencji; komentarze i styl flow są obsługiwane przez API dokumentu YAML. |
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: valuesą 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ńczonynumber,true/falsealbonull). 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 edycjijsonc-parserdla 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ńczonynumber,true/falsealbonull). Wstawienia YAML używają API dokumentu dołączonego pakietuyamldo aktualizacji map/sekwencji. Niepoprawne dokumenty YAML z błędami parsera są odrzucane przed mutacją zparse-error.
--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
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] 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
jsonc-parser, więc komentarze i odstępy przetrwają operację set. Najpierw uruchom z --dry-run, aby sprawdzić bajty przed zatwierdzeniem.
JSONL
[event=action]), gdy nie znasz numeru linii, albo przez kanoniczny segment LN, gdy go znasz.
YAML
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.
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).
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.
+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:
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.
Kody wyjścia
| Kod | Znaczenie |
|---|---|
0 | Sukces. (resolve / find: co najmniej jedno dopasowanie. set: zapis się powiódł.) |
1 | Brak dopasowania albo set odrzucony przez substrat (bez błędu na poziomie systemu). |
2 | Błąd argumentu lub parsowania. |
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
setzapisuje 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-parserlokalnej 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. pathnie wie o LKG. Jeśli plik jest śledzony przez LKG, następne wywołanie observe decyduje, czy wykonać promowanie / odzyskiwanie.set --batchdla atomowego wielokrotnego ustawiania przez cykl życia promowania/odzyskiwania LKG jest planowane razem z substratem odzyskiwania LKG.