跳转至

OC Path 插件

捆绑的 oc-path 插件为 oc:// 工作区文件寻址方案添加了 openclaw path CLI。它随 OpenClaw 仓库一起位于 extensions/oc-path/ 下,但属于可选启用:安装/构建后它保持休眠,直到你启用它。

oc:// 地址指向工作区文件中的单个叶子(或一组通配叶子)。该插件理解四种文件类型:

  • markdown (.md):frontmatter、章节、条目、字段
  • jsonc (.jsonc, .json):保留注释和格式
  • jsonl (.jsonl, .ndjson):面向行的记录
  • yaml (.yaml, .yml, .lobster):通过 yaml 包的 Document API 处理映射/序列/标量节点

自托管者和编辑器扩展使用该 CLI 读取或写入单个叶子,而无需直接针对 SDK 编写脚本;代理和钩子将其视为确定性底层,因此字节保真往返和脱敏哨兵保护可统一适用于各种类型。完整语法、逐动词标志列表以及每种文件类型的示例,请参阅 CLI 参考;本页介绍为何以及如何启用该插件。

为何启用它

当脚本、钩子或本地代理工具需要指向工作区状态中的精确部分,而无需为每种文件形状定制解析器时,请启用 oc-path。单个 oc:// 地址可以命名 markdown frontmatter 键、章节条目、JSONC 配置叶子、JSONL 事件字段或 YAML 工作流步骤。

对于维护者工作流,这一点很重要,因为变更应保持小型、可审计且可重复:检查一个值,查找匹配的记录,试运行写入,然后仅应用该叶子,同时保持注释、换行符和附近格式不变。

常见启用原因:

  • 本地自动化:shell 脚本使用 openclaw path … --json 解析或更新一个工作区值,而不是携带单独的 markdown、JSONC、JSONL 和 YAML 解析代码。
  • 代理可见的编辑:代理在写入前显示针对某个已寻址叶子的试运行差异,这比自由格式的文件重写更容易审查。
  • 编辑器集成:编辑器将 oc://AGENTS.md/tools/gh 映射到确切的 markdown 节点和行号,而无需根据标题文本猜测。
  • 诊断:emit 通过解析器和输出器往返处理文件,因此你可以在依赖自动编辑之前检查某种文件类型是否字节稳定。
# 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

oc-path 有意不作为更高层语义的所有者。内存插件仍负责内存写入,配置命令仍负责完整配置管理,最后已知良好(LKG)配置恢复仍负责恢复/提升。oc-path 是这些更高层工具可围绕构建的窄范围寻址和字节保留文件操作层。

它在哪里运行

该插件在你调用命令的主机上,在 openclaw CLI 进程内运行。它不需要运行中的 Gateway,也不会打开任何网络套接字;每个动词都是对你指定文件的纯转换。

插件元数据位于 extensions/oc-path/openclaw.plugin.json:

{
  "id": "oc-path",
  "name": "OC Path",
  "activation": {
    "onStartup": false,
    "onCommands": ["path"]
  },
  "commandAliases": [{ "name": "path", "kind": "cli" }]
}

onStartup: false 使插件不进入 Gateway 启动路径。commandAliases 和 activation.onCommands 告诉 CLI 在你第一次运行 openclaw path … 时懒加载插件,因此从不使用该动词的安装不会付出任何成本。

启用

openclaw plugins enable oc-path

在同一主机上,裸 openclaw path 调用可立即工作;CLI 会按需加载插件。运行中的 Gateway 会自动应用启用;请参阅 应用更改并检查。

使用以下命令禁用:

openclaw plugins disable oc-path

依赖

所有解析器依赖都是插件本地的;启用 oc-path 不会将新包拉入核心运行时:

依赖 用途
commander 为 resolve、find、set、validate、emit 提供子命令接线。
jsonc-parser 解析 JSONC 并进行叶子编辑,保留注释和尾随逗号。
markdown-it 为章节 / 条目 / 字段模型提供 Markdown 分词。
yaml 使用 Document 解析、输出和编辑 YAML,保留注释和流式样式。

JSONL 保持手工实现:面向行的解析比任何依赖都简单,并且逐行解析已经通过 jsonc-parser。

它提供什么

接口面 由...提供
openclaw path CLI extensions/oc-path/cli-registration.ts
oc:// 解析器 / 格式化器 extensions/oc-path/src/oc-path/oc-path.ts
按类型解析 / 输出 / 编辑 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-*:内存写入通过内存插件进行,而不是 oc-path。oc-path 是通用文件底层;内存插件在其上层叠加自己的语义。
  • LKG:path 不了解最后已知良好配置恢复。如果你通过 path 编辑的文件也受 LKG 跟踪,则下一个配置观察周期会决定是否提升或恢复它;将 path 编辑视为对该文件的任何其他直接写入。

安全

set 通过基底的 emit 路径写入原始字节,该路径会自动应用 脱敏哨兵保护。任何携带 __OPENCLAW_REDACTED__(逐字匹配或作为子串)的叶子节点都会在写入时 以 OC_EMIT_SENTINEL 被拒绝。CLI 还会从它打印的任何人类可读或 JSON 输出中清除字面哨兵值, 并将其替换为 [REDACTED],因此终端 捕获和管道永远不会泄露该标记。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw