OpenClawoc-path插件用oc://統一尋址 markdown / JSONC / JSONL / YAML 工作區文件【免費下載鏈接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 項目地址: https://gitcode.com/GitHub_Trending/cl/openclawoc-path是 OpenClaw 內置bundled但默認不激活opt-in的 CLI 插件它為oc://工作區文件尋址方案提供openclaw path命令讓你在終端里用一套穩定、與文件類型無關kind-agnostic的地址語法精確讀取或改寫 markdown、JSONC、JSONL、YAML/.lobster文件中的單個葉子節點。讀完本文你將掌握oc://地址的完整語法、五個子命令resolve/find/set/validate/emit的用法與退出碼約定、逐文件類型的尋址與改寫語義以及插件背后的源碼實現原理解析器、哨兵守衛、字節保真契約。插件定位窄尋址層不做高層語義oc-path插件的元數據聲明在extensions/oc-path/openclaw.plugin.json它只做一件事把openclaw pathCLI 接入 CLI 體系。{ id: oc-path, name: OC Path, description: Adds the openclaw path CLI for oc:// workspace file addressing., cliCommands: [ { name: path, description: Inspect and edit workspace files via oc:// paths, hasSubcommands: true } ], activation: { onStartup: false, onCommands: [path] }, commandAliases: [ { name: path, kind: cli } ], configSchema: { type: object, additionalProperties: false, properties: {} } }插件入口extensions/oc-path/index.ts通過definePluginEntry注冊register(api)中調用registerOcPathCli(api)完成 CLI 接線。registerOcPathCli位于extensions/oc-path/cli-registration.ts它做兩件關鍵事懶加載真正的子命令實現通過動態import(./src/cli.js)引入CLI 在首次執行openclaw path …時才加載插件代碼機器輸出判定isPathMachineOutput決定默認輸出模式——顯式傳--json時輸出 JSON否則當 stdout 不是 TTY被管道/重定向時也輸出 JSON只有交互式終端且未傳--json/--human時才默認人類可讀輸出。onStartup: false保證插件不進 Gateway 啟動路徑commandAliases與activation.onCommands配合讓 CLI 在第一次運行path動詞時按需加載——從未用過該動詞的安裝不付出任何加載成本。為什么啟用它腳本、hooks 或本地 Agent 工具需要指向工作區狀態的精確片段、又不愿為每種文件形狀維護一套專屬解析器時就該啟用oc-path。一個oc://地址可以命名 markdown frontmatter 鍵、章節條目、JSONC 配置葉子、JSONL 事件字段或 YAML 工作流步驟。常見動機本地自動化shell 腳本用openclaw path … --json解析或更新一個工作區值免去分別維護 markdown、JSONC、JSONL、YAML 解析代碼Agent 可見的編輯Agent 寫入前先對一個被尋址的葉子展示 dry-run diff比自由格式的文件重寫更容易審查編輯器集成編輯器把oc://AGENTS.md/tools/gh映射到精確的 markdown 節點和行號無需靠標題文本猜測診斷emit把文件完整走一遍解析器 發射器在依賴自動化編輯前先確認某類文件是否字節穩定byte-stable。# 該配置中 GitHub 插件是否啟用 openclaw path resolve oc://config.jsonc/plugins/github/enabled --json # 這段會話日志里出現了哪些工具調用名 openclaw path find oc://session.jsonl/[eventtool_call]/name --json # 這次微小的配置編輯會寫出什么字節 openclaw path set oc://config.jsonc/plugins/github/enabled true --dry-run邊界聲明oc-path有意不擁有更高層語義。內存寫入歸 memory 插件完整配置管理歸 config 命令last-known-goodLKG配置恢復歸其自身的恢復/提升流程。oc-path是那些高層工具可以構建其上的窄尋址 字節保真文件操作層。它運行在哪里插件在調用命令的宿主機上、openclawCLI 進程內運行。它不需要正在運行的 Gateway不打開任何網絡 socket——每個動詞都是對指向文件的純變換pure transform。啟用與停用openclaw plugins enable oc-path啟用后如果運行 Gateway重啟它以便 manifest 快照拾取新狀態。裸的openclaw path調用在同一宿主機上立即生效——CLI 按需加載插件。停用openclaw plugins disable oc-path啟用oc-path不會給核心運行時拉入新包所有解析依賴都是插件局部的見extensions/oc-path/package.json。依賴清單如下依賴用途commanderresolve、find、set、validate、emit的子命令接線。jsonc-parserJSONC 解析與葉子編輯保留注釋與尾逗號。markdown-itmarkdown 分詞支撐 section / item / field 模型。yamlYAMLDocument的 parse / emit / edit保留注釋與 flow 風格。diffset --dry-run --diff的統一 diff 輸出源碼cli.ts引用structuredPatch/formatPatch。JSONL 保持手寫實現面向行的解析比任何依賴都簡單且逐行解析本身已經過jsonc-parser。插件提供的能力清單表面提供方openclaw pathCLIextensions/oc-path/cli-registration.ts注冊、extensions/oc-path/src/cli.ts子命令實現oc://解析器 / 格式化器extensions/oc-path/src/oc-path/oc-path.ts逐類型 parse / emit / editextensions/oc-path/src/oc-path/{md,jsonc,jsonl,yaml}通用 resolve / find / setextensions/oc-path/src/oc-path/{resolve,find,edit,universal}.ts紅action 哨兵守衛extensions/oc-path/src/oc-path/sentinel.ts目前 CLI 是唯一公開表面。底層的 substrate 動詞parseOcPath、resolveOcPath、setOcPath、findOcPaths、各類emit*等對插件私有消費者通過 CLI 使用或基于 SDK 構建自己的插件。extensions/oc-path/src/oc-path/index.ts這個 barrel 文件明確注釋“Keep this barrel limited to CLI imports”印證了內部面僅為 CLI 服務的定位。oc://地址語法oc://FILE/SECTION/ITEM/FIELD?sessionSCOPE槽位規則field依賴itemitem依賴section。跨全部四個槽位的語法要素引號段Quoted segmentsa/b.c內的/和.作為字面內容保留。引號內按字節原樣解釋且不允許包含與\。文件槽也感知引號oc://skills/email-drafter/Tools/$last把skills/email-drafter當作單一文件路徑。謂詞Predicates[kv]、[k!v]、[kv]、[kv]、[kv]、[kv]。數值運算符要求兩側都能轉成有限數值。聯合Unions{a,b,c}匹配任意一個候選項。通配符Wildcards*匹配單個子段**匹配零個或多個遞歸。find接受它們resolve與set拒絕并把它們視為有歧義。位置Positional$first/$last解析為第一個 / 最后一個索引或聲明鍵。序數Ordinal#N按文檔順序取第 N 個匹配。插入標記Insertion markers、key、nnn分別用于鍵控 / 索引插入配合set使用。會話作用域Session scope?sessioncron-daily等與槽位嵌套正交。會話值按原始文本處理、不做百分號解碼且不得包含控制字符或保留查詢分隔符?、、%。保留字符?、、%在引號、謂詞或聯合段之外會被拒絕。控制字符U0000–U001F、U007F在任何位置都被拒絕包括session查詢值。規范化往返契約formatOcPath(parseOcPath(path)) path對規范化路徑成立。非規范的查詢參數會被忽略只取第一個非空session值。硬上限源碼oc-path.ts中的常量路徑上限 4096 字節最多 4 個槽位file/section/item/field每個槽位最多 64 個點分dotted子段深層 JSON 路徑最多 256 層嵌套遍歷。另外任何會加載文件的動詞超過 16 MiB 的輸入文件在解析前一律拒絕——JSONC/JSON 報OC_JSONC_INPUT_TOO_LARGE其他文件類型報OC_PATH_INPUT_TOO_LARGECLI 側cli.ts中MAX_OC_PATH_INPUT_BYTES MAX_JSONC_INPUT_BYTES即所有解析器共用同一輸入上限。源碼中的安全校驗parseOcPath在入口處層層設防validateFileSlot拒絕絕對路徑/、\開頭或盤符:前綴錯誤碼OC_PATH_ABSOLUTE_FILE——oc://路徑是工作區相對的拒絕..父目錄逃逸段錯誤碼OC_PATH_PARENT_TRAVERSAL拒絕控制字符錯誤碼OC_PATH_CONTROL_CHAR。路徑先做 NFC 規范化兼容 macOS HFS 的 NFD 與 Unix/Windows 的 NFC并容忍 BOM 前綴因為 NFC 可能使字符串變長規范化后會重新檢查 4096 字節上限。formatOcPath還會做防御性檢查格式化結果若包含紅action 哨兵則直接拋OcEmitSentinelError見下文安全節防止哨兵經遙測/審計/錯誤消息流出。子命令一覽子命令用途resolve oc-path打印路徑處的具體匹配或 “not found”。find pattern枚舉通配符 / 聯合 / 謂詞路徑的所有匹配。set oc-path value在具體路徑寫入一個葉子或插入目標支持--dry-run。validate oc-path僅解析打印結構拆解file / section / item / field。emit file把文件完整跑一遍 parse emit字節保真診斷。全局標志標志適用命令用途--cwd dirresolve、find、set、emit相對該目錄解析文件槽默認process.cwd()。--file pathresolve、find、set、emit覆蓋文件槽解析出的路徑絕對訪問。--json全部強制 JSON 輸出stdout 非 TTY 時默認。--human全部強制人類可讀輸出stdout 為 TTY 時默認。--value-jsonset對 JSON/JSONC/JSONL 葉子替換把value當作 JSON 解析。--dry-runset只打印將要寫入的字節不實際寫入。--diffset需配合--dry-run打印統一 diff 而非完整字節。validate只接受--json/--human它不做任何文件系統訪問因此--cwd與--file不適用。退出碼約定碼含義0成功resolve/find至少一個匹配set寫入成功。1無匹配或set被 substrate 拒絕如哨兵守衛命中非系統級錯誤。2參數或解析錯誤。輸出模式openclaw path是 TTY 感知的終端上輸出人類可讀文本stdout 被管道或重定向時輸出 JSON。--json與--human覆蓋自動檢測。此外 CLI 在輸出前會把哨兵字面量替換為[REDACTED]cli.ts的scrubSentinel保證終端捕獲與管道不會泄漏標記。逐文件類型的尋址模型類型文件擴展名尋址模型Markdown.md按 slug 定位 H2 章節按 slug 或#N定位條目通過[frontmatter]訪問 frontmatter。JSONC/JSON.jsonc、.json對象鍵與數組索引點號拆分嵌套子段引號內除外。JSONL.jsonl、.ndjson頂層行地址L1、L2、$first、$last行內再按 JSONC 風格向下走。YAML/.lobster.yaml、.yml、.lobster映射鍵與序列索引注釋與 flow 風格由 YAML document API 處理。resolve返回結構化匹配root、node、leaf或insertion-point附 1 起始行號。葉子值以文本 leafType形式呈現讓插件作者無需依賴各類型 AST 形狀即可渲染預覽。改寫契約Mutation contractset只寫一個具體目標Markdownfrontmatter 值與- key: value條目字段是字符串葉子。值按字面寫入包括$1、$、$$。Markdown 插入會追加章節、frontmatter 鍵或章節條目并為變更后的文件渲染規范的 Markdown 形狀。章節正文不能整體通過set寫入。JSONC葉子寫入把字符串值強制轉換為既有葉子類型string、有限number、true/false或null。當 JSONC/JSON/JSONL 葉子替換需要把value當 JSON 解析、可能改變形狀時例如把字符串密鑰引用簡寫替換為對象使用--value-json。JSONC 對象與數組插入把value當 JSON 解析普通葉子寫入走jsonc-parser編輯路徑保留注釋與周邊格式。JSONL行內葉子寫入的強制轉換規則與 JSONC 一致。整行替換與追加把value當 JSON 解析。渲染時保留文件的主導 LF/CRLF 換行約定對文件內換行做多數投票所以以 CRLF 為主的文件即便混有零星 LF 也保持 CRLF。YAML葉子寫入強制轉換到既有標量類型string、有限number、true/false或null。YAML 插入使用內置yaml包的 document API 做 map/sequence 更新。帶解析錯誤的畸形 YAML 文檔在變更前即以parse-error拒絕。在字節精確重要的場景先跑--dry-run。JSONC 與 YAML 編輯是修補既有文檔經jsonc-parser或 YAML document API未觸及的字節通常原樣存活markdown 則在任何編輯時都會按解析出的結構重建文件可能規范化變更葉子之外的偶然格式。想要聚焦的前后補丁而非完整渲染文件時加--diff——補丁會記錄換行變化與缺失的結尾換行應用它產生的字節與真實寫入完全一致。逐類型實戰示例Markdown--human輸出!-- frontmatter.md -- --- name: drafter description: email drafting agent tier: core --- ## Tools - gh: GitHub CLI - curl: HTTP client - send_email: enabled$ openclaw path resolve oc://x.md/[frontmatter]/tier --file frontmatter.md --human leaf L4: core (string) $ openclaw path resolve oc://x.md/tools/gh/gh --file frontmatter.md --human leaf L9: GitHub CLI (string) $ openclaw path find oc://x.md/tools/* --file frontmatter.md --human 3 matches for oc://x.md/tools/*: oc://x.md/tools/gh → node L9 [md-item] oc://x.md/tools/curl → node L10 [md-item] oc://x.md/tools/send-email → node L11 [md-item][frontmatter]謂詞尋址 YAML frontmatter 塊tools通過 slug 匹配## Tools標題條目葉子保持 slug 形式即使源文件用下劃線send_email變成send-email。JSONC// config.jsonc { plugins: { github: {enabled: true, role: vcs}, slack: {enabled: false, role: chat} } }$ openclaw path resolve oc://config.jsonc/plugins/github/enabled --file config.jsonc --human leaf L4: true (boolean) $ openclaw path set oc://config.jsonc/plugins/slack/enabled true --file config.jsonc --dry-run --dry-run: would write 142 bytes to /…/config.jsonc { plugins: { github: {enabled: true, role: vcs}, slack: {enabled: true, role: chat} } }JSONC 編輯走jsonc-parser注釋與空白在set后存活。.json文件使用與.jsonc相同的適配器與編輯路徑。JSONL{event:start,userId:u1,ts:1} {event:action,userId:u1,ts:2} {event:end,userId:u1,ts:3}$ openclaw path find oc://session.jsonl/[eventaction]/userId --file session.jsonl --human 1 match for oc://session.jsonl/[eventaction]/userId: oc://session.jsonl/L2/userId → leaf L2: u1 (string) $ openclaw path resolve oc://session.jsonl/L2/ts --file session.jsonl --human leaf L2: 2 (number)每行是一條記錄。不知道行號時用謂詞[eventaction]尋址知道行號時用規范化的LN段。.ndjson文件與.jsonl使用同一適配器。YAML# workflow.yaml name: inbox-triage steps: - id: fetch command: gmail.search - id: classify command: openclaw.invoke$ openclaw path resolve oc://workflow.yaml/steps/0/id --file workflow.yaml --human leaf L3: fetch (string) $ openclaw path set oc://workflow.yaml/steps/$last/id classify-renamed --file workflow.yaml --dry-run --dry-run: would write 99 bytes to /…/workflow.yaml name: inbox-triage steps: - id: fetch command: gmail.search - id: classify-renamed command: openclaw.invokeYAML 用yaml包的DocumentAPI 而非手寫解析器普通 parse/emit 往返保留注釋與編寫形狀而解析出的路徑與 JSONC 使用同一套 map-key / sequence-index 模型。同一適配器處理.yaml、.yml與.lobster。子命令參考resolve oc-path讀取單個葉子或節點。通配符被拒絕——這類查詢用find。匹配時退出0干凈未命中退出1解析錯誤或模式被拒退出2。openclaw path resolve oc://AGENTS.md/tools/gh/risk --human openclaw path resolve oc://gateway.jsonc/server/port --jsonfind pattern枚舉通配符 / 謂詞 / 聯合模式的每一個匹配。至少一個匹配時退出0零匹配退出1。文件槽的通配符以OC_PATH_FILE_WILDCARD_UNSUPPORTED拒絕——必須傳具體文件多文件 glob 屬于后續功能。openclaw path find oc://AGENTS.md/tools/**/risk openclaw path find oc://session.jsonl/[eventaction]/userId openclaw path find oc://config.jsonc/plugins/{github,slack}/enabledset oc-path value寫入一個葉子。配合--dry-run預覽將要寫入的字節而不碰文件加--diff得到統一 diff 預覽。寫入成功退出0substrate 拒絕如哨兵守衛命中退出1解析錯誤退出2。openclaw path set oc://gateway.jsonc/version 2.0 --dry-run openclaw path set oc://gateway.jsonc/version 2.0 --dry-run --diff openclaw path set oc://gateway.jsonc/version 2.0 openclaw path set oc://AGENTS.md/Tools/gh/risk lowkey插入標記會在命名子節點不存在時創建它nnn與裸分別用于索引插入與追加插入。validate oc-path純解析檢查不做文件系統訪問。適合在替換變量前確認模板路徑格式正確或調試時查看結構拆解$ openclaw path validate oc://AGENTS.md/tools/gh --human valid: oc://AGENTS.md/tools/gh file: AGENTS.md section: tools item: gh合法退出0非法退出1帶結構化code與message參數錯誤退出2。emit file把文件完整走一遍對應類型的解析器與發射器。對健全文件輸出應與輸入逐字節一致出現差異說明解析器 bug 或哨兵命中。適合在真實輸入上調試 substrate 行為。openclaw path emit ./AGENTS.md openclaw path emit ./gateway.jsonc --json安全紅action 哨兵守衛set通過 substrate 的 emit 路徑寫原始字節emit 路徑自動應用紅action 哨兵守衛extensions/oc-path/src/oc-path/sentinel.ts。攜帶__OPENCLAW_REDACTED__逐字或作為子串出現的葉子在寫入時以OC_EMIT_SENTINEL拒絕——注意是子串匹配而非相等匹配prefix__OPENCLAW_REDACTED__suffix仍然泄漏標記所以同樣攔截。哨兵檢測對所有字符串值生效包括 markdown frontmatter、條目與標題的插入值既有的無關標記文本在普通編輯中原樣保留。守衛采用**失敗關閉fail-closed**策略與其靜默剝離標記那會悄然損壞文件不如拒絕寫入。guardSentinel在 emit 邊界拋出OcEmitSentinelError讓每一條寫入路徑都被覆蓋而不只是被審計的消費者。CLI 側cli.ts的emit/emitError/scrubSentinel還會在打印任何人類可讀或 JSON 輸出前把哨兵字面量替換成[REDACTED]終端捕獲與管道永遠不會泄漏該標記。與其他插件的關系memory-*內存寫入走 memory 插件不經過oc-path。oc-path是通用文件 substratememory 插件在其上疊加自己的語義。LKGpath不感知 last-known-good 配置恢復。如果你通過path編輯的文件同時被 LKG 跟蹤下一次配置 observe 周期會決定提升還是恢復它——把path編輯視同對該文件的任何其他直接寫入。實用速查組合語法示例# 校驗一個路徑不做文件系統訪問 openclaw path validate oc://AGENTS.md/Tools/$last/risk # 讀取一個葉子 openclaw path resolve oc://gateway.jsonc/version # 通配符搜索 openclaw path find oc://session.jsonl/*/event --file ./logs/session.jsonl # 干跑一次寫入 openclaw path set oc://gateway.jsonc/version 2.0 --dry-run # 干跑并以統一 diff 預覽 openclaw path set oc://gateway.jsonc/version 2.0 --dry-run --diff # 應用寫入 openclaw path set oc://gateway.jsonc/version 2.0 # 字節保真往返診斷 openclaw path emit ./AGENTS.md更完整的語法示例# 引號鍵容納包含 / 或 . 的鍵 openclaw path resolve oc://config.jsonc/agents.defaults.models/anthropic/claude-opus-4-7/alias # 深層 JSON/JSONC 路徑可用斜杠分段它們歸一化為點分子段 openclaw path set oc://openclaw.json/agents/list/0/tools/exec/security allowlist --dry-run # 把 JSONC 葉子替換為解析后的對象 openclaw path set oc://openclaw.json/gateway/auth/token {source:file,provider:secrets,id:/test} --value-json --dry-run # 在 JSONC 子節點上做謂詞搜索 openclaw path find oc://config.jsonc/plugins/[enabledtrue]/id # 插入 JSONC 數組元素 openclaw path set oc://config.jsonc/items/1 {id:new,enabled:true} --dry-run # 插入 JSONC 對象鍵 openclaw path set oc://config.jsonc/plugins/github {enabled:true} --dry-run # 追加 JSONL 事件 openclaw path set oc://session.jsonl/ {event:checkpoint,ok:true} --file ./logs/session.jsonl # 解析最后一行 JSONL 值 openclaw path resolve oc://session.jsonl/$last/event --file ./logs/session.jsonl # 解析 YAML 工作流步驟 openclaw path resolve oc://workflow.yaml/steps/0/id # 更新 YAML 標量 openclaw path set oc://workflow.yaml/steps/$last/id classify-renamed --dry-run # 尋址 markdown frontmatter openclaw path resolve oc://AGENTS.md/[frontmatter]/name # 插入 markdown frontmatter openclaw path set oc://AGENTS.md/[frontmatter]/description Agent instructions --dry-run # 查找 markdown 條目字段 openclaw path find oc://SKILL.md/Tools/*/send_email # 校驗一個帶會話作用域的路徑 openclaw path validate oc://AGENTS.md/Tools/$last/risk?sessioncron-daily使用邊界與注意事項set在寫入或干跑預覽前拒絕包含__OPENCLAW_REDACTED__逐字或子串的字符串葉子值。JSONC 解析與葉子編輯使用插件局部的jsonc-parser依賴普通葉子寫入保留注釋與格式而不是走手寫解析/重渲染路徑。path不感知 LKG 配置跟蹤或恢復——該生命周期由其他模塊所有。通過path編輯的 LKG 跟蹤文件下一次配置讀取決定提升或恢復視同任何其他直接寫入。resolve/set只接受具體路徑通配符、聯合、謂詞等模式在寫入前被拒絕探索性匹配請用find。進一步閱讀openclaw pathCLI 參考完整語法、逐動詞標志清單與逐文件類型工作示例管理插件構建插件插件源碼與測試extensions/oc-path/其中src/oc-path/tests/scenarios/下的byte-fidelity、sentinel-guard、roundtrip-property等測試用例覆蓋了本文所述的關鍵契約【免費下載鏈接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 項目地址: https://gitcode.com/GitHub_Trending/cl/openclaw創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 OpenClaw `oc-path` 插件：用 `oc://` 統一尋址 markdown / JSONC / JSONL / YAML 工作區文件
OpenClawoc-path插件用oc://統一尋址 markdown / JSONC / JSONL / YAML 工作區文件【免費下載鏈接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 項目地址: https://gitcode.com/GitHub_Trending/cl/openclawoc-path是 OpenClaw 內置bundled但默認不激活opt-in的 CLI 插件它為oc://工作區文件尋址方案提供openclaw path命令讓你在終端里用一套穩定、與文件類型無關kind-agnostic的地址語法精確讀取或改寫 markdown、JSONC、JSONL、YAML/.lobster文件中的單個葉子節點。讀完本文你將掌握oc://地址的完整語法、五個子命令resolve/find/set/validate/emit的用法與退出碼約定、逐文件類型的尋址與改寫語義以及插件背后的源碼實現原理解析器、哨兵守衛、字節保真契約。插件定位窄尋址層不做高層語義oc-path插件的元數據聲明在extensions/oc-path/openclaw.plugin.json它只做一件事把openclaw pathCLI 接入 CLI 體系。{ id: oc-path, name: OC Path, description: Adds the openclaw path CLI for oc:// workspace file addressing., cliCommands: [ { name: path, description: Inspect and edit workspace files via oc:// paths, hasSubcommands: true } ], activation: { onStartup: false, onCommands: [path] }, commandAliases: [ { name: path, kind: cli } ], configSchema: { type: object, additionalProperties: false, properties: {} } }插件入口extensions/oc-path/index.ts通過definePluginEntry注冊register(api)中調用registerOcPathCli(api)完成 CLI 接線。registerOcPathCli位于extensions/oc-path/cli-registration.ts它做兩件關鍵事懶加載真正的子命令實現通過動態import(./src/cli.js)引入CLI 在首次執行openclaw path …時才加載插件代碼機器輸出判定isPathMachineOutput決定默認輸出模式——顯式傳--json時輸出 JSON否則當 stdout 不是 TTY被管道/重定向時也輸出 JSON只有交互式終端且未傳--json/--human時才默認人類可讀輸出。onStartup: false保證插件不進 Gateway 啟動路徑commandAliases與activation.onCommands配合讓 CLI 在第一次運行path動詞時按需加載——從未用過該動詞的安裝不付出任何加載成本。為什么啟用它腳本、hooks 或本地 Agent 工具需要指向工作區狀態的精確片段、又不愿為每種文件形狀維護一套專屬解析器時就該啟用oc-path。一個oc://地址可以命名 markdown frontmatter 鍵、章節條目、JSONC 配置葉子、JSONL 事件字段或 YAML 工作流步驟。常見動機本地自動化shell 腳本用openclaw path … --json解析或更新一個工作區值免去分別維護 markdown、JSONC、JSONL、YAML 解析代碼Agent 可見的編輯Agent 寫入前先對一個被尋址的葉子展示 dry-run diff比自由格式的文件重寫更容易審查編輯器集成編輯器把oc://AGENTS.md/tools/gh映射到精確的 markdown 節點和行號無需靠標題文本猜測診斷emit把文件完整走一遍解析器 發射器在依賴自動化編輯前先確認某類文件是否字節穩定byte-stable。# 該配置中 GitHub 插件是否啟用 openclaw path resolve oc://config.jsonc/plugins/github/enabled --json # 這段會話日志里出現了哪些工具調用名 openclaw path find oc://session.jsonl/[eventtool_call]/name --json # 這次微小的配置編輯會寫出什么字節 openclaw path set oc://config.jsonc/plugins/github/enabled true --dry-run邊界聲明oc-path有意不擁有更高層語義。內存寫入歸 memory 插件完整配置管理歸 config 命令last-known-goodLKG配置恢復歸其自身的恢復/提升流程。oc-path是那些高層工具可以構建其上的窄尋址 字節保真文件操作層。它運行在哪里插件在調用命令的宿主機上、openclawCLI 進程內運行。它不需要正在運行的 Gateway不打開任何網絡 socket——每個動詞都是對指向文件的純變換pure transform。啟用與停用openclaw plugins enable oc-path啟用后如果運行 Gateway重啟它以便 manifest 快照拾取新狀態。裸的openclaw path調用在同一宿主機上立即生效——CLI 按需加載插件。停用openclaw plugins disable oc-path啟用oc-path不會給核心運行時拉入新包所有解析依賴都是插件局部的見extensions/oc-path/package.json。依賴清單如下依賴用途commanderresolve、find、set、validate、emit的子命令接線。jsonc-parserJSONC 解析與葉子編輯保留注釋與尾逗號。markdown-itmarkdown 分詞支撐 section / item / field 模型。yamlYAMLDocument的 parse / emit / edit保留注釋與 flow 風格。diffset --dry-run --diff的統一 diff 輸出源碼cli.ts引用structuredPatch/formatPatch。JSONL 保持手寫實現面向行的解析比任何依賴都簡單且逐行解析本身已經過jsonc-parser。插件提供的能力清單表面提供方openclaw pathCLIextensions/oc-path/cli-registration.ts注冊、extensions/oc-path/src/cli.ts子命令實現oc://解析器 / 格式化器extensions/oc-path/src/oc-path/oc-path.ts逐類型 parse / emit / editextensions/oc-path/src/oc-path/{md,jsonc,jsonl,yaml}通用 resolve / find / setextensions/oc-path/src/oc-path/{resolve,find,edit,universal}.ts紅action 哨兵守衛extensions/oc-path/src/oc-path/sentinel.ts目前 CLI 是唯一公開表面。底層的 substrate 動詞parseOcPath、resolveOcPath、setOcPath、findOcPaths、各類emit*等對插件私有消費者通過 CLI 使用或基于 SDK 構建自己的插件。extensions/oc-path/src/oc-path/index.ts這個 barrel 文件明確注釋“Keep this barrel limited to CLI imports”印證了內部面僅為 CLI 服務的定位。oc://地址語法oc://FILE/SECTION/ITEM/FIELD?sessionSCOPE槽位規則field依賴itemitem依賴section。跨全部四個槽位的語法要素引號段Quoted segmentsa/b.c內的/和.作為字面內容保留。引號內按字節原樣解釋且不允許包含與\。文件槽也感知引號oc://skills/email-drafter/Tools/$last把skills/email-drafter當作單一文件路徑。謂詞Predicates[kv]、[k!v]、[kv]、[kv]、[kv]、[kv]。數值運算符要求兩側都能轉成有限數值。聯合Unions{a,b,c}匹配任意一個候選項。通配符Wildcards*匹配單個子段**匹配零個或多個遞歸。find接受它們resolve與set拒絕并把它們視為有歧義。位置Positional$first/$last解析為第一個 / 最后一個索引或聲明鍵。序數Ordinal#N按文檔順序取第 N 個匹配。插入標記Insertion markers、key、nnn分別用于鍵控 / 索引插入配合set使用。會話作用域Session scope?sessioncron-daily等與槽位嵌套正交。會話值按原始文本處理、不做百分號解碼且不得包含控制字符或保留查詢分隔符?、、%。保留字符?、、%在引號、謂詞或聯合段之外會被拒絕。控制字符U0000–U001F、U007F在任何位置都被拒絕包括session查詢值。規范化往返契約formatOcPath(parseOcPath(path)) path對規范化路徑成立。非規范的查詢參數會被忽略只取第一個非空session值。硬上限源碼oc-path.ts中的常量路徑上限 4096 字節最多 4 個槽位file/section/item/field每個槽位最多 64 個點分dotted子段深層 JSON 路徑最多 256 層嵌套遍歷。另外任何會加載文件的動詞超過 16 MiB 的輸入文件在解析前一律拒絕——JSONC/JSON 報OC_JSONC_INPUT_TOO_LARGE其他文件類型報OC_PATH_INPUT_TOO_LARGECLI 側cli.ts中MAX_OC_PATH_INPUT_BYTES MAX_JSONC_INPUT_BYTES即所有解析器共用同一輸入上限。源碼中的安全校驗parseOcPath在入口處層層設防validateFileSlot拒絕絕對路徑/、\開頭或盤符:前綴錯誤碼OC_PATH_ABSOLUTE_FILE——oc://路徑是工作區相對的拒絕..父目錄逃逸段錯誤碼OC_PATH_PARENT_TRAVERSAL拒絕控制字符錯誤碼OC_PATH_CONTROL_CHAR。路徑先做 NFC 規范化兼容 macOS HFS 的 NFD 與 Unix/Windows 的 NFC并容忍 BOM 前綴因為 NFC 可能使字符串變長規范化后會重新檢查 4096 字節上限。formatOcPath還會做防御性檢查格式化結果若包含紅action 哨兵則直接拋OcEmitSentinelError見下文安全節防止哨兵經遙測/審計/錯誤消息流出。子命令一覽子命令用途resolve oc-path打印路徑處的具體匹配或 “not found”。find pattern枚舉通配符 / 聯合 / 謂詞路徑的所有匹配。set oc-path value在具體路徑寫入一個葉子或插入目標支持--dry-run。validate oc-path僅解析打印結構拆解file / section / item / field。emit file把文件完整跑一遍 parse emit字節保真診斷。全局標志標志適用命令用途--cwd dirresolve、find、set、emit相對該目錄解析文件槽默認process.cwd()。--file pathresolve、find、set、emit覆蓋文件槽解析出的路徑絕對訪問。--json全部強制 JSON 輸出stdout 非 TTY 時默認。--human全部強制人類可讀輸出stdout 為 TTY 時默認。--value-jsonset對 JSON/JSONC/JSONL 葉子替換把value當作 JSON 解析。--dry-runset只打印將要寫入的字節不實際寫入。--diffset需配合--dry-run打印統一 diff 而非完整字節。validate只接受--json/--human它不做任何文件系統訪問因此--cwd與--file不適用。退出碼約定碼含義0成功resolve/find至少一個匹配set寫入成功。1無匹配或set被 substrate 拒絕如哨兵守衛命中非系統級錯誤。2參數或解析錯誤。輸出模式openclaw path是 TTY 感知的終端上輸出人類可讀文本stdout 被管道或重定向時輸出 JSON。--json與--human覆蓋自動檢測。此外 CLI 在輸出前會把哨兵字面量替換為[REDACTED]cli.ts的scrubSentinel保證終端捕獲與管道不會泄漏標記。逐文件類型的尋址模型類型文件擴展名尋址模型Markdown.md按 slug 定位 H2 章節按 slug 或#N定位條目通過[frontmatter]訪問 frontmatter。JSONC/JSON.jsonc、.json對象鍵與數組索引點號拆分嵌套子段引號內除外。JSONL.jsonl、.ndjson頂層行地址L1、L2、$first、$last行內再按 JSONC 風格向下走。YAML/.lobster.yaml、.yml、.lobster映射鍵與序列索引注釋與 flow 風格由 YAML document API 處理。resolve返回結構化匹配root、node、leaf或insertion-point附 1 起始行號。葉子值以文本 leafType形式呈現讓插件作者無需依賴各類型 AST 形狀即可渲染預覽。改寫契約Mutation contractset只寫一個具體目標Markdownfrontmatter 值與- key: value條目字段是字符串葉子。值按字面寫入包括$1、$、$$。Markdown 插入會追加章節、frontmatter 鍵或章節條目并為變更后的文件渲染規范的 Markdown 形狀。章節正文不能整體通過set寫入。JSONC葉子寫入把字符串值強制轉換為既有葉子類型string、有限number、true/false或null。當 JSONC/JSON/JSONL 葉子替換需要把value當 JSON 解析、可能改變形狀時例如把字符串密鑰引用簡寫替換為對象使用--value-json。JSONC 對象與數組插入把value當 JSON 解析普通葉子寫入走jsonc-parser編輯路徑保留注釋與周邊格式。JSONL行內葉子寫入的強制轉換規則與 JSONC 一致。整行替換與追加把value當 JSON 解析。渲染時保留文件的主導 LF/CRLF 換行約定對文件內換行做多數投票所以以 CRLF 為主的文件即便混有零星 LF 也保持 CRLF。YAML葉子寫入強制轉換到既有標量類型string、有限number、true/false或null。YAML 插入使用內置yaml包的 document API 做 map/sequence 更新。帶解析錯誤的畸形 YAML 文檔在變更前即以parse-error拒絕。在字節精確重要的場景先跑--dry-run。JSONC 與 YAML 編輯是修補既有文檔經jsonc-parser或 YAML document API未觸及的字節通常原樣存活markdown 則在任何編輯時都會按解析出的結構重建文件可能規范化變更葉子之外的偶然格式。想要聚焦的前后補丁而非完整渲染文件時加--diff——補丁會記錄換行變化與缺失的結尾換行應用它產生的字節與真實寫入完全一致。逐類型實戰示例Markdown--human輸出!-- frontmatter.md -- --- name: drafter description: email drafting agent tier: core --- ## Tools - gh: GitHub CLI - curl: HTTP client - send_email: enabled$ openclaw path resolve oc://x.md/[frontmatter]/tier --file frontmatter.md --human leaf L4: core (string) $ openclaw path resolve oc://x.md/tools/gh/gh --file frontmatter.md --human leaf L9: GitHub CLI (string) $ openclaw path find oc://x.md/tools/* --file frontmatter.md --human 3 matches for oc://x.md/tools/*: oc://x.md/tools/gh → node L9 [md-item] oc://x.md/tools/curl → node L10 [md-item] oc://x.md/tools/send-email → node L11 [md-item][frontmatter]謂詞尋址 YAML frontmatter 塊tools通過 slug 匹配## Tools標題條目葉子保持 slug 形式即使源文件用下劃線send_email變成send-email。JSONC// config.jsonc { plugins: { github: {enabled: true, role: vcs}, slack: {enabled: false, role: chat} } }$ openclaw path resolve oc://config.jsonc/plugins/github/enabled --file config.jsonc --human leaf L4: true (boolean) $ openclaw path set oc://config.jsonc/plugins/slack/enabled true --file config.jsonc --dry-run --dry-run: would write 142 bytes to /…/config.jsonc { plugins: { github: {enabled: true, role: vcs}, slack: {enabled: true, role: chat} } }JSONC 編輯走jsonc-parser注釋與空白在set后存活。.json文件使用與.jsonc相同的適配器與編輯路徑。JSONL{event:start,userId:u1,ts:1} {event:action,userId:u1,ts:2} {event:end,userId:u1,ts:3}$ openclaw path find oc://session.jsonl/[eventaction]/userId --file session.jsonl --human 1 match for oc://session.jsonl/[eventaction]/userId: oc://session.jsonl/L2/userId → leaf L2: u1 (string) $ openclaw path resolve oc://session.jsonl/L2/ts --file session.jsonl --human leaf L2: 2 (number)每行是一條記錄。不知道行號時用謂詞[eventaction]尋址知道行號時用規范化的LN段。.ndjson文件與.jsonl使用同一適配器。YAML# workflow.yaml name: inbox-triage steps: - id: fetch command: gmail.search - id: classify command: openclaw.invoke$ openclaw path resolve oc://workflow.yaml/steps/0/id --file workflow.yaml --human leaf L3: fetch (string) $ openclaw path set oc://workflow.yaml/steps/$last/id classify-renamed --file workflow.yaml --dry-run --dry-run: would write 99 bytes to /…/workflow.yaml name: inbox-triage steps: - id: fetch command: gmail.search - id: classify-renamed command: openclaw.invokeYAML 用yaml包的DocumentAPI 而非手寫解析器普通 parse/emit 往返保留注釋與編寫形狀而解析出的路徑與 JSONC 使用同一套 map-key / sequence-index 模型。同一適配器處理.yaml、.yml與.lobster。子命令參考resolve oc-path讀取單個葉子或節點。通配符被拒絕——這類查詢用find。匹配時退出0干凈未命中退出1解析錯誤或模式被拒退出2。openclaw path resolve oc://AGENTS.md/tools/gh/risk --human openclaw path resolve oc://gateway.jsonc/server/port --jsonfind pattern枚舉通配符 / 謂詞 / 聯合模式的每一個匹配。至少一個匹配時退出0零匹配退出1。文件槽的通配符以OC_PATH_FILE_WILDCARD_UNSUPPORTED拒絕——必須傳具體文件多文件 glob 屬于后續功能。openclaw path find oc://AGENTS.md/tools/**/risk openclaw path find oc://session.jsonl/[eventaction]/userId openclaw path find oc://config.jsonc/plugins/{github,slack}/enabledset oc-path value寫入一個葉子。配合--dry-run預覽將要寫入的字節而不碰文件加--diff得到統一 diff 預覽。寫入成功退出0substrate 拒絕如哨兵守衛命中退出1解析錯誤退出2。openclaw path set oc://gateway.jsonc/version 2.0 --dry-run openclaw path set oc://gateway.jsonc/version 2.0 --dry-run --diff openclaw path set oc://gateway.jsonc/version 2.0 openclaw path set oc://AGENTS.md/Tools/gh/risk lowkey插入標記會在命名子節點不存在時創建它nnn與裸分別用于索引插入與追加插入。validate oc-path純解析檢查不做文件系統訪問。適合在替換變量前確認模板路徑格式正確或調試時查看結構拆解$ openclaw path validate oc://AGENTS.md/tools/gh --human valid: oc://AGENTS.md/tools/gh file: AGENTS.md section: tools item: gh合法退出0非法退出1帶結構化code與message參數錯誤退出2。emit file把文件完整走一遍對應類型的解析器與發射器。對健全文件輸出應與輸入逐字節一致出現差異說明解析器 bug 或哨兵命中。適合在真實輸入上調試 substrate 行為。openclaw path emit ./AGENTS.md openclaw path emit ./gateway.jsonc --json安全紅action 哨兵守衛set通過 substrate 的 emit 路徑寫原始字節emit 路徑自動應用紅action 哨兵守衛extensions/oc-path/src/oc-path/sentinel.ts。攜帶__OPENCLAW_REDACTED__逐字或作為子串出現的葉子在寫入時以OC_EMIT_SENTINEL拒絕——注意是子串匹配而非相等匹配prefix__OPENCLAW_REDACTED__suffix仍然泄漏標記所以同樣攔截。哨兵檢測對所有字符串值生效包括 markdown frontmatter、條目與標題的插入值既有的無關標記文本在普通編輯中原樣保留。守衛采用**失敗關閉fail-closed**策略與其靜默剝離標記那會悄然損壞文件不如拒絕寫入。guardSentinel在 emit 邊界拋出OcEmitSentinelError讓每一條寫入路徑都被覆蓋而不只是被審計的消費者。CLI 側cli.ts的emit/emitError/scrubSentinel還會在打印任何人類可讀或 JSON 輸出前把哨兵字面量替換成[REDACTED]終端捕獲與管道永遠不會泄漏該標記。與其他插件的關系memory-*內存寫入走 memory 插件不經過oc-path。oc-path是通用文件 substratememory 插件在其上疊加自己的語義。LKGpath不感知 last-known-good 配置恢復。如果你通過path編輯的文件同時被 LKG 跟蹤下一次配置 observe 周期會決定提升還是恢復它——把path編輯視同對該文件的任何其他直接寫入。實用速查組合語法示例# 校驗一個路徑不做文件系統訪問 openclaw path validate oc://AGENTS.md/Tools/$last/risk # 讀取一個葉子 openclaw path resolve oc://gateway.jsonc/version # 通配符搜索 openclaw path find oc://session.jsonl/*/event --file ./logs/session.jsonl # 干跑一次寫入 openclaw path set oc://gateway.jsonc/version 2.0 --dry-run # 干跑并以統一 diff 預覽 openclaw path set oc://gateway.jsonc/version 2.0 --dry-run --diff # 應用寫入 openclaw path set oc://gateway.jsonc/version 2.0 # 字節保真往返診斷 openclaw path emit ./AGENTS.md更完整的語法示例# 引號鍵容納包含 / 或 . 的鍵 openclaw path resolve oc://config.jsonc/agents.defaults.models/anthropic/claude-opus-4-7/alias # 深層 JSON/JSONC 路徑可用斜杠分段它們歸一化為點分子段 openclaw path set oc://openclaw.json/agents/list/0/tools/exec/security allowlist --dry-run # 把 JSONC 葉子替換為解析后的對象 openclaw path set oc://openclaw.json/gateway/auth/token {source:file,provider:secrets,id:/test} --value-json --dry-run # 在 JSONC 子節點上做謂詞搜索 openclaw path find oc://config.jsonc/plugins/[enabledtrue]/id # 插入 JSONC 數組元素 openclaw path set oc://config.jsonc/items/1 {id:new,enabled:true} --dry-run # 插入 JSONC 對象鍵 openclaw path set oc://config.jsonc/plugins/github {enabled:true} --dry-run # 追加 JSONL 事件 openclaw path set oc://session.jsonl/ {event:checkpoint,ok:true} --file ./logs/session.jsonl # 解析最后一行 JSONL 值 openclaw path resolve oc://session.jsonl/$last/event --file ./logs/session.jsonl # 解析 YAML 工作流步驟 openclaw path resolve oc://workflow.yaml/steps/0/id # 更新 YAML 標量 openclaw path set oc://workflow.yaml/steps/$last/id classify-renamed --dry-run # 尋址 markdown frontmatter openclaw path resolve oc://AGENTS.md/[frontmatter]/name # 插入 markdown frontmatter openclaw path set oc://AGENTS.md/[frontmatter]/description Agent instructions --dry-run # 查找 markdown 條目字段 openclaw path find oc://SKILL.md/Tools/*/send_email # 校驗一個帶會話作用域的路徑 openclaw path validate oc://AGENTS.md/Tools/$last/risk?sessioncron-daily使用邊界與注意事項set在寫入或干跑預覽前拒絕包含__OPENCLAW_REDACTED__逐字或子串的字符串葉子值。JSONC 解析與葉子編輯使用插件局部的jsonc-parser依賴普通葉子寫入保留注釋與格式而不是走手寫解析/重渲染路徑。path不感知 LKG 配置跟蹤或恢復——該生命周期由其他模塊所有。通過path編輯的 LKG 跟蹤文件下一次配置讀取決定提升或恢復視同任何其他直接寫入。resolve/set只接受具體路徑通配符、聯合、謂詞等模式在寫入前被拒絕探索性匹配請用find。進一步閱讀openclaw pathCLI 參考完整語法、逐動詞標志清單與逐文件類型工作示例管理插件構建插件插件源碼與測試extensions/oc-path/其中src/oc-path/tests/scenarios/下的byte-fidelity、sentinel-guard、roundtrip-property等測試用例覆蓋了本文所述的關鍵契約【免費下載鏈接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 項目地址: https://gitcode.com/GitHub_Trending/cl/openclaw創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考