openclaw path
Akses shell ke skema pengalamatan oc://: satu sintaks jalur yang didispatch berdasarkan jenis untuk memeriksa dan mengedit berkas ruang kerja yang dapat dialamatkan (markdown, jsonc, jsonl, yaml/yml/lobster). Pengelola hosting mandiri, pembuat plugin, dan ekstensi editor menggunakannya untuk membaca, menemukan, atau memperbarui lokasi spesifik tanpa harus membuat parser tersendiri untuk setiap jenis berkas.
path disediakan oleh plugin opsional bawaan oc-path. Aktifkan sebelum penggunaan pertama:
resolvebersifat konkret dan hanya menghasilkan satu kecocokan.findadalah verba untuk banyak kecocokan bagi wildcard, union, predikat, dan perluasan posisi.sethanya menerima jalur konkret atau penanda penyisipan; pola wildcard ditolak sebelum penulisan.validatemengurai jalur tanpa mengakses sistem berkas.emitmelakukan perjalanan pulang-pergi berkas melalui penguraian + pengeluaran (diagnostik ketepatan bita).
Mengapa menggunakannya
Status OpenClaw tersebar di markdown yang diedit manusia, konfigurasi JSONC berkomentar, log JSONL yang hanya dapat ditambahkan, serta berkas alur kerja/spesifikasi YAML. Skrip, hook, dan agen sering kali hanya memerlukan satu nilai kecil dari berkas-berkas tersebut: kunci frontmatter, pengaturan plugin, bidang catatan log, langkah YAML, atau butir daftar di bawah bagian bernama.openclaw path memberi pemanggil tersebut alamat yang stabil, alih-alih grep, regex, atau parser sekali pakai untuk setiap jenis berkas. Jalur oc:// yang sama dapat divalidasi, di-resolve, dicari, disimulasikan, dan ditulis dari terminal, sehingga automasi spesifik tetap dapat ditinjau dan dijalankan ulang. Bagian berkas lainnya dipertahankan, sehingga menulis satu leaf tidak mengganggu komentar, akhir baris, atau pemformatan di sekitarnya.
Gunakan saat sesuatu yang Anda inginkan memiliki alamat logis, tetapi bentuk berkasnya beragam:
- Hook membaca satu pengaturan dari JSONC berkomentar tanpa kehilangan komentar saat menuliskan kembali nilainya.
- Skrip pemeliharaan menemukan setiap bidang peristiwa yang cocok dalam log JSONL tanpa memuat seluruh log ke parser khusus.
- Editor berpindah ke bagian atau butir daftar markdown berdasarkan slug, lalu merender baris persis yang di-resolve.
- Agen menyimulasikan pengeditan kecil pada ruang kerja sebelum menerapkannya, dengan bita yang berubah terlihat dalam peninjauan.
openclaw path untuk pengeditan seluruh berkas biasa, migrasi konfigurasi yang kompleks, atau penulisan khusus memori; gunakan perintah atau plugin pemiliknya. path ditujukan untuk operasi berkas kecil yang dapat dialamatkan, ketika perintah terminal yang dapat diulang lebih baik daripada parser khusus lainnya.
Cara menggunakannya
Baca satu nilai dari berkas konfigurasi yang diedit manusia:--json saat pemanggil memerlukan keluaran terstruktur dan --human saat seseorang memeriksa hasilnya.
Cara kerjanya
- Mengurai alamat
oc://menjadi slot: berkas, bagian, butir, bidang, dan kueri sesi opsional. - Memilih adaptor jenis berkas berdasarkan ekstensi target (
.md,.jsonc,.json,.jsonl,.ndjson,.yaml,.yml,.lobster). - Me-resolve slot terhadap struktur jenis berkas tersebut: judul/butir markdown, kunci objek/indeks larik JSONC, catatan baris JSONL, atau simpul peta/urutan YAML.
- Untuk
set, menghasilkan bita yang diedit melalui adaptor yang sama agar bagian berkas yang tidak disentuh tetap mempertahankan komentar, akhir baris, dan pemformatan di sekitarnya jika didukung oleh jenis tersebut.
resolve dan set memerlukan satu target konkret. find adalah verba eksploratif: verba ini memperluas wildcard, union, predikat, dan ordinal menjadi kecocokan konkret yang dapat Anda periksa sebelum memilih satu untuk ditulis.
Subperintah
Flag global
validate hanya menerima --json / --human; perintah ini tidak mengakses sistem berkas, sehingga --cwd dan --file tidak berlaku.
Sintaks oc://
field memerlukan item, dan item memerlukan section. Di keempat slot:
- Segmen bertanda kutip —
"a/b.c"tidak terpengaruh oleh pemisah/dan.. Kontennya bersifat literal-bita;"dan\tidak diizinkan di dalam tanda kutip. Slot berkas juga memahami tanda kutip:oc://"skills/email-drafter"/Tools/$lastmemperlakukanskills/email-draftersebagai satu jalur berkas. - Predikat —
[k=v],[k!=v],[k<v],[k<=v],[k>v],[k>=v]. Operator numerik mengharuskan kedua sisi dapat dikonversi menjadi bilangan terbatas. - Union —
{a,b,c}cocok dengan alternatif mana pun. - Wildcard —
*(satu subsegmen) dan**(nol atau lebih, rekursif).findmenerimanya;resolvedansetmenolaknya karena ambigu. - Posisional —
$first/$lastdi-resolve menjadi indeks atau kunci yang dideklarasikan pertama / terakhir. - Ordinal —
#Nuntuk kecocokan ke-N berdasarkan urutan dokumen. - Penanda penyisipan —
+,+key,+nnnuntuk penyisipan berdasarkan kunci / indeks (gunakan denganset). - Cakupan sesi —
?session=cron-dailydan sebagainya. Independen dari penyarangan slot. Nilai sesi bersifat mentah, tidak didekode persen; nilai tersebut tidak boleh berisi karakter kontrol atau pembatas kueri yang dicadangkan (?,&,%).
?, &, %) di luar segmen bertanda kutip, predikat, atau union ditolak. Karakter kontrol (U+0000-U+001F, U+007F) ditolak di mana pun, termasuk dalam nilai kueri session.
formatOcPath(parseOcPath(path)) === path dijamin untuk jalur kanonis. Parameter kueri nonkanonis diabaikan, kecuali nilai session= pertama yang tidak kosong.
Batas ketat: panjang jalur dibatasi hingga 4096 bita, paling banyak 4 slot (berkas/bagian/butir/bidang), paling banyak 64 subsegmen bertitik per slot, dan paling banyak 256 tingkat penelusuran bertingkat untuk jalur JSON dalam. Secara terpisah, setiap masukan berkas JSONC/JSON yang melebihi 16 MiB ditolak dengan diagnostik penguraian alih-alih diurai, untuk semua verba yang memuat berkas tersebut.
Pengalamatan berdasarkan jenis berkas
resolve mengembalikan kecocokan terstruktur: root, node, leaf, atau insertion-point, dengan nomor baris berbasis 1. Nilai leaf disajikan sebagai teks ditambah leafType, sehingga pembuat plugin dapat merender pratinjau tanpa bergantung pada bentuk AST masing-masing jenis.
Kontrak mutasi
set menulis satu target konkret:
- Nilai frontmatter markdown dan bidang butir
- key: valuemerupakan leaf string. Penyisipan markdown menambahkan bagian, kunci frontmatter, atau butir bagian dan merender bentuk markdown kanonis untuk berkas yang diubah. Isi bagian tidak dapat ditulis secara keseluruhan melaluiset. - Penulisan leaf JSONC mengonversi nilai string ke jenis leaf yang ada (
string,numberterbatas,true/false, ataunull). Gunakan--value-jsonsaat penggantian leaf JSONC/JSON/JSONL harus mengurai<value>sebagai JSON dan dapat mengubah bentuk, seperti mengganti bentuk singkat referensi rahasia berupa string dengan objek. Penyisipan objek dan larik JSONC mengurai<value>sebagai JSON dan menggunakan jalur pengeditanjsonc-parseruntuk penulisan leaf biasa, dengan mempertahankan komentar dan pemformatan di sekitarnya. - Penulisan leaf JSONL mengonversi nilai seperti JSONC di dalam baris. Penggantian seluruh baris dan penambahan mengurai
<value>sebagai JSON. JSONL yang dirender mempertahankan konvensi akhir baris LF/CRLF yang dominan pada berkas (berdasarkan mayoritas seluruh baris baru dalam berkas, sehingga berkas yang sebagian besar menggunakan CRLF tetap menggunakan CRLF meskipun terdapat beberapa LF yang menyimpang). - Penulisan leaf YAML mengonversi nilai ke jenis skalar yang ada (
string,numberterbatas,true/false, ataunull). Penyisipan YAML menggunakan API dokumen paketyamlbawaan untuk pembaruan peta/urutan. Dokumen YAML yang rusak dan memiliki kesalahan parser ditolak sebelum mutasi denganparse-error.
--dry-run sebelum penulisan yang terlihat oleh pengguna jika bita persisnya penting. Pengeditan JSONC dan YAML menambal dokumen yang ada (melalui jsonc-parser atau API dokumen yaml), sehingga bita yang tidak disentuh biasanya tetap dipertahankan; markdown membangun ulang berkas dari struktur hasil penguraiannya pada setiap pengeditan, yang dapat menormalkan pemformatan insidental di luar leaf yang diubah. Tambahkan --diff jika Anda menginginkan pratinjau sebagai tambalan sebelum/sesudah yang terfokus, bukan seluruh berkas hasil render.
Contoh
Resep berdasarkan jenis berkas
Lima verba yang sama dapat digunakan untuk semua jenis; skema pengalamatan memilih penangan berdasarkan ekstensi berkas.Markdown
[frontmatter] mengalamatkan blok frontmatter YAML; tools
mencocokkan judul ## Tools melalui slug, dan daun item mempertahankan bentuk
slug meskipun sumber menggunakan garis bawah (send_email menjadi send-email).
JSONC
jsonc-parser, sehingga komentar dan spasi
tetap dipertahankan setelah operasi set. Jalankan terlebih dahulu dengan
--dry-run untuk memeriksa bita sebelum menerapkan perubahan. Berkas .json
menggunakan adaptor dan jalur pengeditan yang sama seperti .jsonc.
JSONL
[event=action]) jika Anda tidak mengetahui nomor barisnya, atau berdasarkan
segmen kanonis LN jika Anda mengetahuinya. Berkas .ndjson menggunakan
adaptor yang sama seperti .jsonl.
YAML
Document dari paket yaml, bukan pengurai buatan
sendiri, sehingga proses penguraian/pemancaran bolak-balik biasa mempertahankan
komentar dan bentuk penulisan, sementara path yang dihasilkan menggunakan model
kunci-peta / indeks-urutan yang sama seperti JSONC. Adaptor yang sama menangani
berkas .yaml, .yml, dan .lobster.
Referensi subperintah
resolve <oc-path>
Membaca satu daun atau simpul. Karakter pengganti ditolak—gunakan find untuk
itu. Keluar dengan kode 0 jika ditemukan kecocokan, 1 jika tidak ditemukan
kecocokan tanpa galat, dan 2 jika terjadi galat penguraian atau pola ditolak.
find <pattern>
Mencantumkan setiap kecocokan untuk pola karakter pengganti / predikat /
gabungan. Keluar dengan kode 0 jika terdapat setidaknya satu kecocokan, dan
1 jika tidak ada. Karakter pengganti pada slot berkas ditolak dengan
OC_PATH_FILE_WILDCARD_UNSUPPORTED—berikan berkas konkret (pencocokan pola
multi-berkas merupakan fitur lanjutan).
set <oc-path> <value>
Menulis sebuah daun. Gunakan bersama --dry-run untuk melihat pratinjau bita
yang akan ditulis tanpa menyentuh berkas. Tambahkan --diff untuk pratinjau
diff terpadu. Keluar dengan kode 0 jika penulisan berhasil, 1 jika substrat
menolak (misalnya, pemicu pelindung sentinel), dan 2 jika terjadi galat
penguraian.
+key membuat anak bernama tersebut jika belum ada; +nnn
dan + saja masing-masing digunakan untuk penyisipan berdasarkan indeks dan
penambahan di akhir.
validate <oc-path>
Pemeriksaan penguraian saja. Tidak ada akses sistem berkas. Berguna ketika Anda
ingin memastikan path templat memiliki bentuk yang benar sebelum mengganti
variabel, atau ketika Anda memerlukan rincian struktural untuk penelusuran
galat:
0 jika valid, 1 jika tidak valid (dengan code dan
message terstruktur), dan 2 jika terjadi galat argumen.
emit <file>
Memproses berkas secara bolak-balik melalui pengurai dan pemancar khusus
jenisnya. Keluarannya seharusnya identik secara bita dengan masukan pada berkas
yang valid; perbedaan menunjukkan bug pengurai atau pemicu sentinel. Berguna
untuk menelusuri perilaku substrat pada masukan dunia nyata.
Kode keluar
Mode keluaran
openclaw path mengenali TTY: keluaran yang mudah dibaca manusia pada terminal,
dan JSON ketika stdout disalurkan atau dialihkan. --json dan --human
mengesampingkan deteksi otomatis.
Catatan
setmenulis bita melalui jalur pemancaran substrat, yang secara otomatis menerapkan pelindung sentinel penyuntingan. Daun yang memuat__OPENCLAW_REDACTED__(secara persis atau sebagai substring) ditolak saat penulisan.- Penguraian JSONC dan pengeditan daun menggunakan dependensi
jsonc-parserlokal Plugin, sehingga komentar dan pemformatan tetap dipertahankan pada penulisan daun biasa, alih-alih melewati jalur pengurai/perender ulang buatan sendiri. pathtidak mengetahui pelacakan atau pemulihan konfigurasi terakhir yang diketahui baik (LKG); siklus hidup tersebut dimiliki di tempat lain. Jika berkas yang Anda edit melaluipathjuga dilacak oleh LKG, pembacaan konfigurasi berikutnya menentukan apakah berkas tersebut dipromosikan atau dipulihkan; perlakukan pengeditanpathsama seperti penulisan langsung lainnya ke berkas tersebut.