本页内容
本页内容
插件指南
OC Path 插件
捆绑的 oc-path 插件为 oc:// 工作区文件寻址方案添加了 openclaw path CLI。它在 extensions/oc-path/ 下的 OpenClaw 存储库中提供,但可以选择加入:install/build 使其处于休眠状态,直到您启用它。
oc:// 地址指向工作区文件中的单个叶子节点(或一组通配符叶子节点)。该插件支持四种文件类型:
- markdown (
.md):frontmatter、部分、项目、字段 - jsonc (
.jsonc,.json): 注释和格式会被保留 - jsonl (
.jsonl,.ndjson): 按行组织的记录 - yaml (
.yaml,.yml,.lobster): 通过yaml包的DocumentAPI 处理 map/sequence/scalar 节点
自托管程序和编辑器扩展使用 CLI 来读取或写入单个叶子,而无需直接针对 SDK 编写脚本;代理和钩子将其视为可预测的基础,因此字节保真度往返和编辑哨兵防护在不同类型之间统一应用。请参阅 CLI 参考 了解完整的语法、逐个动词的标志列表以及每种文件类型的工作示例;本页介绍了启用该插件的原因和方法。
为什么启用它
当脚本、钩子或本地代理工具需要指向工作区状态中的某个精确位置,而不想为每种文件形态各写一套专用解析器时,就启用 oc-path。一个 oc:// 地址可以表示 markdown frontmatter 键、某个节项、JSONC 配置叶子节点、JSONL 事件字段,或者 YAML 工作流步骤。
这对于维护者工作流很重要,因为这类变更应该保持小、可审计、可重复:检查一个值,找到匹配记录,先 dry-run 一次写入,然后只应用那个叶子节点,同时保留注释、行尾和附近的格式不变。
启用它的常见原因:
- 本地自动化:shell 脚本使用
openclaw path … --json解析或更新一个工作区值,而不是分别编写 markdown、JSONC、JSONL 和 YAML 的解析代码。 - 代理可见的编辑:代理在写入前会为一个已定位的叶子节点展示 dry-run diff,这比自由形式的文件重写更容易审查。
- 编辑器集成:编辑器将
oc://AGENTS.md/tools/gh映射到确切的 markdown 节点和行号,而不是根据标题文本猜测。 - 诊断:
emit会让文件经过解析器和生成器再回到原样,因此你可以在依赖自动化编辑之前检查某种文件是否按字节稳定。
oc-path 故意不是高级语义的所有者。内存插件仍然拥有内存写入,配置命令仍然拥有完整的配置管理,最后已知的(LKG)配置恢复仍然拥有restore/promotion. oc-path是那些高级工具可以围绕它们构建的窄寻址和字节保留文件操作层。
运行位置
该插件以内嵌进程的方式运行在 openclaw CLI 内部,并在你执行命令的主机上运行。它不需要运行中的 Gateway,也不会打开任何网络套接字;每个动词都是对你指定文件的纯转换。
插件元数据位于 extensions/oc-path/openclaw.plugin.json:
onStartup: false 可将插件排除在 Gateway 的启动路径之外。 commandAliases 和 activation.onCommands 会告诉 CLI 在你第一次运行 openclaw path … 时按需加载该插件,因此从不使用该动词的安装不会承担任何成本。
启用
裸 openclaw path 调用立即在同一主机上运行; CLI 按需加载插件。正在运行的网关会自动应用启用;请参阅 应用更改并检查 。
禁用:
依赖
所有解析器依赖都仅限于插件本地;启用 oc-path 不会将新包引入核心运行时:
| 依赖项 | 用途 |
|---|---|
commander |
resolve、find、set、validate、emit 的子命令连接。 |
jsonc-parser |
带注释和保留尾随逗号的 JSONC 解析和叶子编辑。 |
markdown-it |
用于 section / item / field 模型的 Markdown 词法分析。 |
yaml |
带注释和保留 flow style 的 YAML Document 解析 / 生成 / 编辑。 |
JSONL 仍然采用手工实现:按行解析比任何依赖都更简单,而且逐行解析本身已经通过 jsonc-parser 进行。
它提供什么
| 表面 | 由以下内容提供 |
|---|---|
openclaw path CLI |
extensions/oc-path/cli-registration.ts |
oc:// 解析器 / 格式化器 |
extensions/oc-path/src/oc-path/oc-path.ts |
| 按类型的 parse / emit / edit | extensions/oc-path/src/oc-path/{md,jsonc,jsonl,yaml} |
| 通用 resolve / find / set | extensions/oc-path/src/oc-path/{resolve,find,edit}.ts |
| 重写哨兵保护 | extensions/oc-path/src/oc-path/sentinel.ts |
目前 CLI 是唯一公开的表面。底层动词对插件是私有的;使用者通过 CLI(或基于 SDK 自行构建插件)来使用。
与其他插件的关系
memory-*:内存写入通过 memory 插件进行,而不是通过oc-path。oc-path是一个通用的文件底层层;memory 插件在其之上叠加自己的语义。- LKG:
path不知道最后一次正确的配置恢复。如果您通过path编辑的文件也被 LKG- 跟踪,则下一个配置观察周期决定是提升还是恢复它;将path编辑视为对该文件的任何其他直接写入。
安全性
set 通过底层基础的 emit 路径写入原始字节,这会自动应用重写哨兵保护。包含 __OPENCLAW_REDACTED__(原样或作为子串)的叶子节点会在写入时被拒绝,并返回 OC_EMIT_SENTINEL。CLI 还会清理它输出的任何人类可读或 JSON 输出中的字面哨兵,将其替换为 [REDACTED],这样终端捕获和管道就不会泄露该标记。