OC Path 插件

The bundled oc-path plugin adds the openclaw path CLI for the oc:// workspace-file addressing scheme. It ships in the OpenClaw repo under extensions/oc-path/ but is opt-in: install/build leaves it dormant until you enable it.

oc:// addresses point at a single leaf (or a wildcard set of leaves) inside a workspace file. The plugin understands four file kinds:

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`	保留注释和流样式的 YAML `Document` 解析 / 输出 / 编辑。

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