openclaw path
由 Plugin 提供的 shell 存取，用於 oc:// 定址基底：一種依種類分派的路徑配置，可檢查與編輯可定址的工作區檔案（markdown、jsonc、jsonl）。自行託管者、Plugin 作者與編輯器擴充功能可用它讀取、尋找或更新狹窄位置，而不必為每種檔案手寫剖析器。
CLI 對應基底的公開動詞：
resolve是具體且單一符合項目。find是用於萬用字元、聯集、述詞與位置展開的多符合項目動詞。set只接受具體路徑或插入標記；萬用字元模式會在寫入前被拒絕。
path 由隨附的選用 oc-path Plugin 提供。首次使用前請先啟用：
為什麼使用它
OpenClaw 狀態分散在人類編輯的 markdown、帶註解的 JSONC 設定，以及僅附加的 JSONL 記錄中。shell 指令碼、hook 與代理通常只需要這些檔案中的一個小值：frontmatter 鍵、Plugin 設定、記錄欄位，或具名章節下的項目符號項目。openclaw path 會給這些呼叫者一個穩定地址，而不是為每種檔案種類使用一次性的 grep、regex 或剖析器。同一個 oc:// 路徑可以從終端機驗證、解析、搜尋、dry-run 與寫入，讓狹窄自動化更容易審閱，也更安全地重放。當你想更新單一葉節點，同時保留檔案其餘註解、換行符號與周邊格式時，它特別有用。
當你想要的項目有邏輯地址，但實體檔案形狀各不相同時，請使用它：
- hook 想從帶註解的 JSONC 讀取一項設定，並在寫回值時不失去註解。
- 維護指令碼想在 JSONL 記錄中尋找每個相符事件欄位，而不必把整個記錄載入自訂剖析器。
- 編輯器擴充功能想依 slug 跳至 markdown 章節或項目符號項目，然後呈現解析到的精確行。
- 代理想在套用前 dry-run 一個極小的工作區編輯，並在審閱中看見變更的位元組。
openclaw path。這些應該使用擁有者命令或 Plugin。path 適用於小型、可定址的檔案操作，且可重複的終端機命令比另一個特製剖析器更清楚。
如何使用
從人類編輯的設定檔讀取一個值：--json，人員檢查結果時使用 --human。
運作方式
openclaw path 做四件事：
- 將
oc://地址剖析成插槽：檔案、章節、項目、欄位與選用的工作階段。 - 從目標副檔名（
.md、.jsonc、.jsonl與相關別名）選擇檔案種類配接器。 - 依該檔案種類的 AST 解析插槽：markdown 標題/項目、JSONC 物件鍵/陣列索引，或 JSONL 行記錄。
- 對於
set，透過同一個配接器輸出已編輯的位元組，讓檔案未碰觸的部分在該種類支援時保留其註解、換行符號與鄰近格式。
resolve 與 set 需要一個具體目標。find 是探索用動詞：它會將萬用字元、聯集、述詞與序數展開成具體符合項目，讓你在選擇一個寫入前檢查。
子命令
| 子命令 | 目的 |
|---|---|
resolve <oc-path> | 列印路徑上的具體符合項目（或「找不到」）。 |
find <pattern> | 列舉萬用字元 / 聯集 / 述詞路徑的符合項目。 |
set <oc-path> <value> | 在具體路徑寫入葉節點或插入目標。支援 --dry-run。 |
validate <oc-path> | 僅剖析；列印結構拆解（檔案 / 章節 / 項目 / 欄位）。 |
emit <file> | 透過 parseXxx + emitXxx 來回處理檔案（位元組保真度診斷）。 |
全域旗標
| 旗標 | 目的 |
|---|---|
--cwd <dir> | 以此目錄解析檔案插槽（預設：process.cwd()）。 |
--file <path> | 覆寫檔案插槽解析出的路徑（絕對存取）。 |
--json | 強制 JSON 輸出（stdout 不是 TTY 時的預設）。 |
--human | 強制人類可讀輸出（stdout 是 TTY 時的預設）。 |
--dry-run | （僅限 set）列印原本會寫入的位元組，但不實際寫入。 |
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會因為 模稜兩可而拒絕。 - 位置 —
$last解析為最後一個索引 / 最後宣告的鍵。 - 序數 —
#N表示依文件順序的第 N 個符合項目。 - 插入標記 —
+、+key、+nnn，用於鍵控 / 索引插入 （與set搭配使用）。 - 工作階段範圍 —
?session=cron-daily等。與插槽巢狀正交。 工作階段值是原始值，不做百分比解碼；不得包含控制字元或保留的查詢分隔符（?、&、%）。
?、&、%）會被拒絕。控制字元（U+0000-U+001F、U+007F）在任何位置都會被拒絕，包括 session 查詢值。
formatOcPath(parseOcPath(path)) === path 對 canonical 路徑有保證。非 canonical 查詢參數會被忽略，但第一個非空的 session= 值除外。
依檔案種類定址
| 種類 | 定址模型 |
|---|---|
| Markdown | 依 slug 的 H2 章節、依 slug 或 #N 的項目符號項目、透過 [frontmatter] 的 frontmatter。 |
| JSONC/JSON | 物件鍵與陣列索引；除非加引號，否則點號會分割巢狀子片段。 |
| JSONL | 頂層行地址（L1、L2、$last），然後在該行內進行 JSONC 風格的向下巡覽。 |
resolve 會傳回結構化符合項目：root、node、leaf 或
insertion-point，並包含以 1 為基底的行號。葉節點值會以文字加上
leafType 呈現，讓 Plugin 作者可以呈現預覽，而不必依賴各種類 AST 形狀。
變更合約
set 會寫入一個具體目標：
- Markdown frontmatter 值與
- key: value項目欄位是字串葉節點。 Markdown 插入會附加章節、frontmatter 鍵或章節項目，並為變更後的檔案呈現 canonical markdown 形狀。 - JSONC 葉節點寫入會將字串值強制轉換為現有葉節點型別
（
string、有限number、true/false或null）。JSONC 物件與陣列 插入會將<value>剖析為 JSON，並對一般葉節點寫入使用jsonc-parser編輯路徑， 保留註解與鄰近格式。 - JSONL 葉節點寫入會像 JSONC 一樣在一行內強制轉換。整行取代與
附加會將
<value>剖析為 JSON。呈現後的 JSONL 會保留檔案主要的 LF/CRLF 換行慣例。
--dry-run。基底會為剖析/輸出來回處理保留位元組完全相同的輸出，但變更可能依種類 canonicalize 已編輯區域或檔案。
範例
依檔案種類的配方
相同五個動詞可跨種類運作；定址配置會依副檔名分派。以下範例使用 PR 說明中的 fixture。Markdown
[frontmatter] 述詞會定址 YAML frontmatter 區塊；tools
會透過 slug 符合 ## Tools 標題，而項目葉節點即使來源使用底線（send_email → send-email），也會保留其 slug 形式。
JSONC
jsonc-parser，因此註解與空白字元會在
set 後保留下來。請先搭配 --dry-run 執行，以便在提交前檢查位元組。
JSONL
[event=action]）定址，
知道時則使用標準 LN 區段定址。
子命令參考
resolve <oc-path>
讀取單一葉節點或節點。會拒絕萬用字元，請改用 find。
符合時結束代碼為 0，明確未命中時為 1，解析錯誤或拒絕的
模式時為 2。
find <pattern>
列舉萬用字元 / 述詞 / 聯集模式的所有符合項目。至少有一個符合項目時結束代碼為 0，
沒有符合項目時為 1。檔案槽位萬用字元會以
OC_PATH_FILE_WILDCARD_UNSUPPORTED 拒絕，請傳入具體檔案（多檔案
glob 是後續功能）。
set <oc-path> <value>
寫入葉節點。搭配 --dry-run 可預覽會寫入的位元組，
且不會碰觸檔案。成功寫入時結束代碼為 0，底層介面拒絕時（例如命中哨兵防護）為 1，
解析錯誤時為 2。
+key 插入標記會建立該子項目；
+nnn 與單獨的 + 則分別用於索引插入與附加插入。
validate <oc-path>
僅解析檢查。不存取檔案系統。適用於在替換變數前確認
範本路徑格式正確，或需要結構拆解以進行偵錯時：
0，無效時為 1（含結構化的 code 與
message），引數錯誤時為 2。
emit <file>
透過各類型的解析器與發射器來往返處理檔案。在健全檔案上，輸出應與輸入位元組完全一致；
若有差異，代表解析器錯誤或命中哨兵。這對偵錯真實輸入上的底層介面行為很有用。
結束代碼
| 代碼 | 意義 |
|---|---|
0 | 成功。（resolve / find：至少一個符合項目。set：寫入成功。） |
1 | 無符合項目，或 set 被底層介面拒絕（沒有系統層級錯誤）。 |
2 | 引數或解析錯誤。 |
輸出模式
openclaw path 具備 TTY 感知能力：在終端機上輸出人類可讀格式，
stdout 被管線傳送或重新導向時輸出 JSON。--json 與 --human 會覆寫
自動偵測。
注意事項
set會透過底層介面的發射路徑寫入位元組，該路徑會自動套用 遮蔽哨兵防護。帶有__OPENCLAW_REDACTED__的葉節點（逐字或作為子字串） 會在寫入時被拒絕。- JSONC 解析與葉節點編輯使用 Plugin 本機的
jsonc-parser相依性，因此一般葉節點寫入時會保留註解與格式，而不是經過手寫解析器/重新渲染路徑。 path不知道 LKG。如果檔案受到 LKG 追蹤，下一次 observe 呼叫會決定是否提升 / 復原。計劃中的set --batch會搭配 LKG 復原底層介面，透過 LKG 提升/復原生命週期執行原子多重設定。