openclaw path
Akses shell yang disediakan Plugin ke substrat pengalamatan oc://: satu
skema path berbasis jenis untuk memeriksa dan mengedit file ruang kerja yang
dapat dialamati (markdown, jsonc, jsonl, yaml/yml/lobster). Pengelola
self-hosting, penulis Plugin, dan ekstensi editor menggunakannya untuk membaca,
menemukan, atau memperbarui lokasi sempit tanpa membuat parser per jenis file
secara manual.
CLI mencerminkan verba publik substrat:
resolvebersifat konkret dan cocok tunggal.findadalah verba cocok jamak untuk wildcard, union, predikat, dan ekspansi posisional.sethanya menerima path konkret atau penanda penyisipan; pola wildcard ditolak sebelum penulisan.
path disediakan oleh Plugin opsional bawaan oc-path. Aktifkan sebelum
penggunaan pertama:
Mengapa menggunakannya
State OpenClaw tersebar di markdown yang diedit manusia, konfigurasi JSONC berkomentar, log JSONL append-only, dan file workflow/spesifikasi YAML. Skrip shell, hook, dan agen sering membutuhkan satu nilai kecil dari file tersebut: kunci frontmatter, pengaturan Plugin, field rekaman log, langkah YAML, atau item bullet di bawah section bernama.openclaw path memberi pemanggil tersebut alamat stabil alih-alih grep,
regex, atau parser sekali pakai untuk setiap jenis file. Path oc:// yang sama
dapat divalidasi, di-resolve, dicari, disimulasikan, dan ditulis dari terminal,
sehingga automasi sempit lebih mudah ditinjau dan lebih aman diulang. Ini
sangat berguna ketika Anda ingin memperbarui satu leaf sambil mempertahankan
komentar, akhiran baris, dan pemformatan sekitar dari sisa file.
Gunakan ketika hal yang Anda inginkan memiliki alamat logis, tetapi bentuk file
fisiknya bervariasi:
- Sebuah hook ingin membaca satu pengaturan dari JSONC berkomentar tanpa kehilangan komentar saat menulis nilainya kembali.
- Skrip pemeliharaan ingin menemukan setiap field peristiwa yang cocok dalam log JSONL tanpa memuat seluruh log ke parser khusus.
- Ekstensi editor ingin melompat ke section markdown atau item bullet berdasarkan slug, lalu merender baris persis yang di-resolve.
- Agen ingin menyimulasikan edit ruang kerja kecil sebelum menerapkannya, dengan byte yang berubah terlihat dalam tinjauan.
openclaw path untuk edit seluruh file biasa,
migrasi konfigurasi kaya, atau penulisan khusus memori. Itu sebaiknya
menggunakan perintah atau Plugin pemilik. path ditujukan untuk operasi file
kecil yang dapat dialamati ketika perintah terminal yang dapat diulang lebih
jelas daripada parser kustom lainnya.
Cara penggunaannya
Baca satu nilai dari file konfigurasi yang diedit manusia:--json ketika pemanggil membutuhkan output terstruktur dan --human ketika
seseorang sedang memeriksa hasilnya.
Cara kerjanya
openclaw path melakukan empat hal:
- Mengurai alamat
oc://menjadi slot: file, section, item, field, dan session opsional. - Memilih adapter jenis file dari ekstensi target (
.md,.jsonc,.jsonl,.yaml,.yml,.lobster, dan alias terkait). - Meresolusi slot terhadap AST jenis file tersebut: heading/item markdown, kunci objek/indeks array JSONC, rekaman baris JSONL, atau node map/sequence YAML.
- Untuk
set, menghasilkan byte yang diedit melalui adapter yang sama agar bagian file yang tidak disentuh tetap mempertahankan komentar, akhiran baris, dan pemformatan di sekitarnya jika jenis file mendukungnya.
resolve dan set memerlukan satu target konkret. find adalah kata kerja
eksploratif: ia memperluas wildcard, union, predikat, dan ordinal menjadi
kecocokan konkret yang dapat Anda periksa sebelum memilih satu untuk ditulis.
Subperintah
| Subperintah | Tujuan |
|---|---|
resolve <oc-path> | Mencetak kecocokan konkret pada path (atau “tidak ditemukan”). |
find <pattern> | Mengenumerasi kecocokan untuk path wildcard / union / predikat. |
set <oc-path> <value> | Menulis leaf atau target penyisipan pada path konkret. Mendukung --dry-run. |
validate <oc-path> | Hanya mengurai; mencetak uraian struktural (file / section / item / field). |
emit <file> | Round-trip file melalui parseXxx + emitXxx (diagnostik fidelitas byte). |
Flag global
| Flag | Tujuan |
|---|---|
--cwd <dir> | Meresolusi slot file terhadap direktori ini (default: process.cwd()). |
--file <path> | Menimpa path hasil resolusi slot file (akses absolut). |
--json | Memaksa output JSON (default saat stdout bukan TTY). |
--human | Memaksa output manusiawi (default saat stdout adalah TTY). |
--dry-run | (hanya pada set) mencetak byte yang akan ditulis tanpa menulis. |
--diff | (dengan set --dry-run) mencetak diff terpadu alih-alih byte lengkap. |
Sintaks oc://
field memerlukan item, dan item memerlukan section. Di
keempat slot:
- Segmen berkutip —
"a/b.c"tetap melewati pemisah/dan.. Konten bersifat byte-literal;"dan\tidak diizinkan di dalam kutip. Slot file juga sadar kutip:oc://"skills/email-drafter"/Tools/$lastmemperlakukanskills/email-draftersebagai satu path file. - Predikat —
[k=v],[k!=v],[k<v],[k<=v],[k>v],[k>=v]. Operasi numerik mengharuskan kedua sisi dapat dikonversi menjadi angka finite. - Union —
{a,b,c}cocok dengan salah satu alternatif. - Wildcard —
*(satu sub-segmen) dan**(nol-atau-lebih, rekursif).findmenerima ini;resolvedansetmenolaknya karena ambigu. - Posisional —
$first/$lastmeresolusi ke indeks pertama / terakhir atau kunci yang dideklarasikan. - Ordinal —
#Nuntuk kecocokan ke-N menurut urutan dokumen. - Penanda penyisipan —
+,+key,+nnnuntuk penyisipan berkunci / berindeks (gunakan denganset). - Cakupan session —
?session=cron-dailydll. Ortogonal terhadap penyarangan slot. Nilai session bersifat mentah, tidak di-decode persen; nilainya tidak boleh berisi karakter kontrol atau delimiter query yang dicadangkan (?,&,%).
?, &, %) di luar segmen berkutip, predikat,
atau union ditolak. Karakter kontrol (U+0000-U+001F, U+007F) ditolak
di mana pun, termasuk nilai query session.
formatOcPath(parseOcPath(path)) === path dijamin untuk path kanonis.
Parameter query non-kanonis diabaikan kecuali nilai session= pertama yang
tidak kosong.
Pengalamatan berdasarkan jenis file
| Jenis | Model pengalamatan |
|---|---|
| Markdown | Section H2 berdasarkan slug, item bullet berdasarkan slug atau #N, frontmatter melalui [frontmatter]. |
| JSONC/JSON | Kunci objek dan indeks array; titik memisahkan sub-segmen bertingkat kecuali dikutip. |
| JSONL | Alamat baris tingkat atas (L1, L2, $first, $last), lalu penurunan gaya JSONC di dalam baris. |
| YAML/YML/.lobster | Kunci map dan indeks sequence; komentar dan gaya flow ditangani oleh API dokumen YAML. |
resolve mengembalikan kecocokan terstruktur: root, node, leaf, atau
insertion-point, dengan nomor baris berbasis 1. Nilai leaf ditampilkan sebagai teks
plus leafType agar penulis plugin dapat merender pratinjau tanpa bergantung pada
bentuk AST per jenis.
Kontrak mutasi
set menulis satu target konkret:
- Nilai frontmatter Markdown dan field item
- key: valueadalah leaf string. Penyisipan Markdown menambahkan section, kunci frontmatter, atau item section dan merender bentuk markdown kanonis untuk file yang berubah. - Penulisan leaf JSONC mengonversi nilai string ke jenis leaf yang ada
(
string,numberfinite,true/false, ataunull). Gunakan--value-jsonsaat penggantian leaf JSONC/JSON/JSONL harus mengurai<value>sebagai JSON dan dapat mengubah bentuk, seperti mengganti shorthand SecretRef string dengan objek. Penyisipan objek dan array JSONC mengurai<value>sebagai JSON dan menggunakan jalur editjsonc-parseruntuk penulisan leaf biasa, mempertahankan komentar dan pemformatan di sekitarnya. - Penulisan leaf JSONL mengonversi seperti JSONC di dalam satu baris. Penggantian
seluruh baris dan append mengurai
<value>sebagai JSON. JSONL yang dirender mempertahankan konvensi akhiran baris LF/CRLF dominan file. - Penulisan leaf YAML mengonversi ke jenis scalar yang ada (
string,numberfinite,true/false, ataunull). Penyisipan YAML menggunakan API dokumen paketyamlyang dibundel untuk pembaruan map/sequence. Dokumen YAML yang rusak dengan error parser ditolak sebelum mutasi denganparse-error.
--dry-run sebelum penulisan yang terlihat pengguna saat byte persisnya penting. Substrat
mempertahankan output identik byte untuk round-trip parse/emit, tetapi
mutasi dapat mengkanoniskan wilayah atau file yang diedit tergantung jenisnya.
Tambahkan --diff saat Anda menginginkan pratinjau sebagai patch sebelum/sesudah yang terfokus
alih-alih file lengkap yang dirender.
Contoh
Resep berdasarkan jenis file
Lima verba yang sama bekerja di berbagai jenis; skema pengalamatan melakukan dispatch berdasarkan ekstensi file. Contoh di bawah menggunakan fixture dari deskripsi PR.Markdown
[frontmatter] mengalamatkan blok frontmatter YAML; tools mencocokkan heading ## Tools melalui slug, dan leaf item mempertahankan bentuk slug-nya meskipun sumber memakai garis bawah (send_email → send-email).
JSONC
jsonc-parser, sehingga komentar dan whitespace tetap bertahan setelah set. Jalankan dengan --dry-run lebih dulu untuk memeriksa byte sebelum melakukan commit.
JSONL
[event=action]) saat Anda tidak mengetahui nomor barisnya, atau dengan segmen kanonis LN saat Anda mengetahuinya.
YAML
Document dari paket yaml, bukan parser buatan sendiri, sehingga round-trip parse/emit biasa mempertahankan komentar dan bentuk penulisan sementara path yang di-resolve menggunakan model map-key / sequence-index yang sama seperti JSONC. Adapter yang sama menangani file .yaml, .yml, dan .lobster.
Referensi subperintah
resolve <oc-path>
Baca satu leaf atau node. Wildcard ditolak — gunakan find untuk itu. Keluar dengan 0 pada kecocokan, 1 pada miss yang bersih, 2 pada error parse atau pola yang ditolak.
find <pattern>
Enumerasi setiap kecocokan untuk pola wildcard / predikat / union. Keluar dengan 0 jika ada setidaknya satu kecocokan, 1 jika nol. Wildcard slot file ditolak dengan OC_PATH_FILE_WILDCARD_UNSUPPORTED — berikan file konkret (globbing multi-file adalah fitur lanjutan).
set <oc-path> <value>
Tulis sebuah leaf. Pasangkan dengan --dry-run untuk meninjau byte yang akan ditulis tanpa menyentuh file. Tambahkan --diff untuk pratinjau unified diff. Keluar dengan 0 pada penulisan yang berhasil, 1 jika substrate menolak (misalnya, sentinel guard terkena), 2 pada error parse.
+key membuat child bernama jika belum ada; +nnn dan + polos masing-masing berfungsi untuk penyisipan berindeks dan append.
validate <oc-path>
Pemeriksaan parse saja. Tidak ada akses filesystem. Berguna saat Anda ingin memastikan path template sudah berbentuk benar sebelum mengganti variabel, atau saat Anda menginginkan uraian struktural untuk debugging:
0 saat valid, 1 saat tidak valid (dengan code dan message terstruktur), 2 pada error argumen.
emit <file>
Round-trip file melalui parser dan emitter per jenis. Output seharusnya identik byte demi byte dengan input pada file yang sehat — perbedaan menunjukkan bug parser atau sentinel yang terkena. Berguna untuk debugging perilaku substrate pada input dunia nyata.
Kode keluar
| Kode | Makna |
|---|---|
0 | Berhasil. (resolve / find: setidaknya satu kecocokan. set: penulisan berhasil.) |
1 | Tidak ada kecocokan, atau set ditolak oleh substrate (tanpa error tingkat sistem). |
2 | Error argumen atau parse. |
Mode keluaran
openclaw path sadar TTY: output yang dapat dibaca manusia di terminal, JSON saat stdout di-pipe atau dialihkan. --json dan --human menimpa deteksi otomatis.
Catatan
setmenulis byte melalui path emit substrate, yang menerapkan guard sentinel redaksi secara otomatis. Leaf yang membawa__OPENCLAW_REDACTED__(verbatim atau sebagai substring) ditolak pada waktu tulis.- Parsing JSONC dan edit leaf menggunakan dependensi
jsonc-parserlokal Plugin, sehingga komentar dan pemformatan dipertahankan pada penulisan leaf biasa alih-alih melewati path parser/render ulang buatan sendiri. pathtidak mengetahui LKG. Jika file dilacak LKG, panggilan observe berikutnya memutuskan apakah akan promote / recover.set --batchuntuk multi-set atomik melalui siklus hidup promote/recover LKG direncanakan bersama substrate pemulihan LKG.