openclaw path
透過 Shell 存取 oc:// 定址機制：一種依類型分派的路徑語法，
用於檢查及編輯可定址的工作區檔案（markdown、jsonc、
jsonl、yaml/yml/lobster）。自行託管者、外掛作者及編輯器擴充功能
可使用它讀取、尋找或更新特定位置，而無須為每種檔案
自行編寫剖析器。
path 由隨附的選用 oc-path 外掛提供。首次
使用前請先啟用：
resolve是具體且僅比對單一結果的動詞。find是用於萬用字元、聯集、述詞及 位置展開的多重比對動詞。set僅接受具體路徑或插入標記；萬用字元模式 會在寫入前遭到拒絕。validate會剖析路徑，但不存取檔案系統。emit會讓檔案經過剖析與輸出往返處理（位元組保真度診斷）。
為何使用它
OpenClaw 狀態分散於人工編輯的 markdown、帶註解的 JSONC 設定、僅附加的 JSONL 記錄，以及 YAML 工作流程／規格檔案中。指令碼、鉤子 及代理程式通常只需要這些檔案中的一個小值：frontmatter 鍵、 外掛設定、記錄欄位、YAML 步驟，或具名章節下的項目符號 項目。openclaw path 為這些呼叫端提供穩定的位址，而不必針對每種檔案類型
使用臨時的 grep、規則運算式或剖析器。同一個 oc:// 路徑可從終端機進行驗證、
解析、搜尋、試執行及寫入，讓小範圍的
自動化易於審查及重播。它會保留檔案的其餘部分，因此
寫入一個葉節點不會擾動其註解、換行字元或鄰近
格式。
當所需項目有邏輯位址，但檔案結構
各異時，請使用它：
- 鉤子從帶註解的 JSONC 讀取一項設定，並在 寫回值時保留註解。
- 維護指令碼尋找 JSONL 記錄中每個相符的事件欄位， 而不必將整份記錄載入自訂剖析器。
- 編輯器依 slug 跳至 markdown 章節或項目符號項目，接著呈現 解析所得的確切行。
- 代理程式在套用小型工作區編輯前先試執行，並在 審查中顯示變更的位元組。
openclaw path；這些作業應使用擁有者命令或外掛。path
適用於小型、可定址的檔案作業，此時可重複執行的終端機命令
比再製作一個專用剖析器更合適。
使用方式
從人工編輯的設定檔讀取一個值：--json；人員檢查結果時則使用 --human。
運作方式
- 將
oc://位址剖析成欄位：檔案、章節、項目、欄位及 選用的工作階段查詢。 - 依目標副檔名選擇檔案類型配接器（
.md、.jsonc、.json、.jsonl、.ndjson、.yaml、.yml、.lobster）。 - 依該檔案類型的結構解析欄位：markdown 標題／項目、JSONC 物件鍵／陣列索引、JSONL 行紀錄，或 YAML 對應／序列節點。
- 針對
set，透過同一個配接器輸出已編輯的位元組，使檔案中 未變更的部分在該類型支援時保留其註解、換行字元及鄰近 格式。
resolve 與 set 需要單一具體目標。find 是探索用
動詞：它會將萬用字元、聯集、述詞及序數展開成具體
比對結果，讓你在選擇要寫入的目標前先行檢查。
子命令
全域旗標
validate 僅接受 --json／--human；它不會存取檔案系統，因此
--cwd 與 --file 不適用。
oc:// 語法
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 個以點分隔的子區段，而深層 JSON 路徑最多
256 層巢狀周遊。另外，對於任何會載入 JSONC/JSON 檔案的動詞，
超過 16 MiB 的檔案輸入都會遭到拒絕並傳回剖析診斷，而不會進行剖析。
依檔案類型定址
resolve 會傳回結構化比對結果：root、node、leaf 或
insertion-point，並包含從 1 起算的行號。葉節點值會以
文字加上 leafType 的形式呈現，讓外掛作者無須依賴
各檔案類型的 AST 結構即可呈現預覽。
變更合約
set 會寫入一個具體目標：
- Markdown frontmatter 值和
- key: value項目欄位都是字串 葉節點。Markdown 插入會附加章節、frontmatter 鍵或章節 項目，並為已變更的檔案呈現標準 Markdown 形式。無法透過set將章節本文當作整體寫入。 - JSONC 葉節點寫入會將字串值強制轉換為現有葉節點型別
（
string、有限number、true/false或null）。當 JSONC/JSON/JSONL 葉節點替換應將<value>剖析為 JSON， 並且可能改變結構時（例如以物件取代字串形式的 secret-ref 簡寫），請使用--value-json。 JSONC 物件和陣列插入會將<value>剖析為 JSON，並對一般葉節點寫入使用jsonc-parser編輯路徑，以保留註解 和鄰近格式。 - JSONL 葉節點寫入會在單行內比照 JSONC 進行強制轉換。整行替換
和附加會將
<value>剖析為 JSON。呈現後的 JSONL 會保留檔案的 主要 LF/CRLF 行尾慣例（依檔案中的換行採多數決， 因此主要使用 CRLF 的檔案即使夾雜少數 LF，仍會維持 CRLF）。 - YAML 葉節點寫入會強制轉換為現有純量型別（
string、有限number、true/false或null）。YAML 插入會使用隨附的yaml套件文件 API 更新對應表／序列。若 YAML 文件格式錯誤且剖析器回報錯誤，系統會在變更前拒絕操作並回傳parse-error。
--dry-run。JSONC
和 YAML 編輯會修補現有文件（透過 jsonc-parser 或 yaml
文件 API），因此未變更的位元組通常會保留；Markdown 則會在任何編輯時
依剖析後的結構重建檔案，這可能會將已變更葉節點以外的非必要
格式標準化。若希望預覽聚焦於變更前後的修補內容，而非完整呈現的檔案，
請加上 --diff。
範例
依檔案種類分類的作法
相同的五個動詞適用於所有種類；定址配置會依 副檔名分派。Markdown
[frontmatter] 述詞會定址 YAML frontmatter 區塊；tools
會透過 slug 比對 ## Tools 標題，而項目葉節點即使原始內容使用底線，
仍會保留其 slug 形式（send_email 會變成 send-email）。
JSONC
jsonc-parser，因此執行 set
後仍會保留註解和空白。請先搭配 --dry-run 執行，以便在提交前檢查位元組。
.json 檔案使用與 .jsonc 相同的配接器和編輯路徑。
JSONL
[event=action]）定址；
知道行號時，則使用標準 LN 區段。
.ndjson 檔案使用與 .jsonl 相同的配接器。
YAML
yaml 套件的 Document API，而不是自行編寫的
剖析器，因此一般的剖析／輸出往返轉換會保留註解和撰寫
形式，而解析後的路徑則使用與 JSONC 相同的對應表鍵／序列索引模型。
相同的配接器會處理 .yaml、.yml 和 .lobster 檔案。
子命令參考
resolve <oc-path>
讀取單一葉節點或節點。不接受萬用字元，請改用 find。
相符時以 0 結束，確定無相符項目時以 1 結束，遇到剖析錯誤或遭拒絕的
模式時則以 2 結束。
find <pattern>
列舉萬用字元／述詞／聯集模式的每個相符項目。至少有一個相符項目時以 0
結束，零個時以 1 結束。檔案位置萬用字元會以
OC_PATH_FILE_WILDCARD_UNSUPPORTED 拒絕，請傳入具體檔案（多檔案
glob 是後續功能）。
set <oc-path> <value>
寫入葉節點。搭配 --dry-run 可預覽將寫入的位元組，
而不會變更檔案。加上 --diff 可預覽統一差異。
成功寫入時以 0 結束；基底拒絕時（例如觸發
哨兵防護）以 1 結束；發生剖析錯誤時以 2 結束。
+key 插入標記會建立該節點；
+nnn 和單獨的 + 則分別用於索引插入和附加插入。
validate <oc-path>
僅進行剖析檢查。不存取檔案系統。適合用於在替換變數前確認
範本路徑格式正確，或在偵錯時查看
結構分解：
0 結束；無效時以 1 結束（並附帶結構化的 code 和
message）；發生引數錯誤時以 2 結束。
emit <file>
讓檔案通過各種類型的剖析器和輸出器進行往返轉換。對於格式正確的檔案，輸出應與輸入
逐位元組完全相同；若有差異，表示存在
剖析器錯誤或觸發了哨兵。適合用於使用
真實輸入偵錯基底行為。
結束代碼
輸出模式
openclaw path 會感知 TTY：在終端機上輸出人類可讀的內容，stdout
透過管線傳送或重新導向時則輸出 JSON。--json 和 --human 會覆寫
自動偵測。
注意事項
set會透過底層基礎的 emit 路徑寫入位元組，該路徑會自動套用 遮蔽哨兵防護。若葉節點包含__OPENCLAW_REDACTED__（完整原文或作為子字串），則會在寫入 時遭拒絕。- JSONC 解析與葉節點編輯使用外掛本機的
jsonc-parser相依套件，因此一般葉節點寫入會保留註解與格式， 而不會經過自行實作的剖析器／重新呈現路徑。 path不會感知最後已知良好（LKG）設定的追蹤或復原； 該生命週期由其他位置負責。如果透過path編輯的檔案 同時也受 LKG 追蹤，下一次讀取設定時會決定要提升還是 復原該檔案；請將path編輯視為對該檔案的任何其他直接寫入。