跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

內建的 oc-path Plugin 會為 oc:// 工作區檔案定址方案加入 openclaw path CLI。它隨 OpenClaw repo 一起提供，位於 extensions/oc-path/，但採選擇啟用；安裝/建置後會保持休眠，直到你啟用它。 oc:// 位址會指向工作區檔案中的單一葉節點（或一組萬用字元葉節點）。此 Plugin 目前理解三種檔案：
  • markdown（.md、.mdx）：frontmatter、區段、項目、欄位
  • jsonc（.jsonc、.json5、.json）：保留註解與格式
  • jsonl（.jsonl、.ndjson）：以行為導向的記錄
自架主機者與編輯器擴充功能會使用 CLI 讀寫單一葉節點，而不必直接針對 SDK 撰寫腳本；agents 與 hooks 會把它視為確定性的基底，讓位元組保真的來回轉換與遮罩哨兵防護能一致套用到各種類型。

​
為什麼要啟用它

當你希望腳本、hooks 或本機 agent 工具能指向工作區狀態中的精確片段，而不必為每種檔案形狀發明 parser 時，請啟用 oc-path。單一 oc:// 位址可以命名 markdown frontmatter key、區段項目、JSONC config 葉節點，或 JSONL event 欄位。 這對維護者工作流程很重要，因為變更應該小、可稽核且可重複：檢查一個值、尋找相符記錄、dry-run 一次寫入，然後只套用該葉節點，同時保留註解、換行符號與鄰近格式。把它維持為選擇啟用的 Plugin，能讓進階使用者取得定址基底，而不必把 parser 依賴或 CLI surface 放進不需要它的核心安裝。 常見的啟用理由：
  • 本機自動化：shell scripts 可以用 openclaw path … --json 解析或更新一個工作區值，而不用攜帶個別的 markdown、JSONC 與 JSONL parsing code。
  • agent 可見的編輯：agent 可以在寫入前顯示單一已定址葉節點的 dry-run diff，這比自由形式的檔案重寫更容易審查。
  • 編輯器整合：編輯器可以將 oc://AGENTS.md/tools/gh 對應到精確的 markdown node 與行號，而不必根據標題文字猜測。
  • 診斷：emit 會讓檔案通過 parser 與 emitter 來回轉換，因此你可以在依賴自動化編輯前，檢查某種檔案類型是否具備位元組穩定性。
具體範例： 
# Is the GitHub plugin enabled in this config?
openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json

# Which tool-call names appear in this session log?
openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json

# What bytes would this tiny config edit write?
openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run
此 Plugin 刻意不負責更高階的語意。memory Plugins 仍然負責 memory writes，config commands 仍然負責完整的 config 管理，LKG 邏輯也仍然負責 restore/promotion。oc-path 是狹義的定址與位元組保留檔案操作層，讓那些更高階工具可以圍繞它建構。

​
它在哪裡執行

此 Plugin 會在你呼叫命令的主機上，於 openclaw CLI 程序內執行。它不需要執行中的 Gateway，也不會開啟任何網路 sockets；每個 verb 都只是對你指定檔案的純轉換。 Plugin metadata 位於 extensions/oc-path/openclaw.plugin.json： 
{
  "id": "oc-path",
  "name": "OC Path",
  "activation": {
    "onStartup": false,
    "onCommands": ["path"]
  },
  "commandAliases": [{ "name": "path", "kind": "cli" }]
}
onStartup: false 會讓此 Plugin 離開 Gateway hot path。onCommands: ["path"] 會告訴 CLI 在你第一次執行 openclaw path … 時才延遲載入此 Plugin，因此從未使用該 verb 的安裝不會付出任何成本。

​
啟用

openclaw plugins enable oc-path
重新啟動 Gateway（如果你有執行），讓 manifest snapshot 取得新的狀態。裸 openclaw path 呼叫會立即在同一台主機上運作；CLI 會依需求載入此 Plugin。 停用方式： 
openclaw plugins disable oc-path

​
依賴

所有 parser 依賴都是 Plugin-local；啟用 oc-path 不會把新 packages 拉進核心 runtime：
依賴項用途
commanderresolve、find、set、validate、emit 的 subcommand wiring。
jsonc-parserJSONC parse + 葉節點編輯，保留註解與 trailing commas。
markdown-it用於區段/項目/欄位模型的 Markdown tokenization。
JSONL 維持手寫；以行為導向的 parsing 比任何依賴都簡單，而且每行 JSONC parse 已經會經過 jsonc-parser。

​
它提供什麼

Surface提供者
openclaw path CLIextensions/oc-path/cli-registration.ts
oc:// parser / formatterextensions/oc-path/src/oc-path/oc-path.ts
各類型 parse / emit / editextensions/oc-path/src/oc-path/{md,jsonc,jsonl}
通用 resolve / find / setextensions/oc-path/src/oc-path/{resolve,find,edit}.ts
遮罩哨兵防護extensions/oc-path/src/oc-path/sentinel.ts
CLI 是目前唯一的公開 surface。基底 verbs 對此 Plugin 是私有的；consumers 使用 CLI（或針對 SDK 建構自己的 Plugin）。

​
與其他 Plugins 的關係

  • memory-*：memory writes 會通過 memory Plugins，而不是 oc-path。oc-path 是通用檔案基底；memory Plugins 會在其上疊加自己的語意。
  • LKG：path 不知道 Last-Known-Good config restore。如果檔案由 LKG 追蹤，下一次 observe call 會決定是否 promote 或 recover；透過 LKG promote/recover 生命週期執行 atomic multi-set 的 set --batch，規劃會與 LKG-recovery 基底一起提供。

​
安全性

set 會透過基底的 emit path 寫入原始位元組，該路徑會自動套用遮罩哨兵防護。帶有 __OPENCLAW_REDACTED__（逐字或作為 substring）的葉節點會在寫入時被拒絕，錯誤為 OC_EMIT_SENTINEL。CLI 也會從它列印的任何 human 或 JSON output 中清除 literal sentinel，將其替換為 [REDACTED]，因此 terminal captures 與 pipelines 永遠不會洩漏該 marker。

​
相關