Appearance
本页指导如何配置 OpenClaw OC Path 插件，使用 openclaw path CLI 命令对工作区文件（Markdown、JSONC、JSONL、YAML）进行精准寻址和字节级写入。插件默认休眠，需主动启用：openclaw plugins enable oc-path。支持 resolve、find、set、validate、emit 子命令，并自动保护 __OPENCLAW_REDACTED__ 哨兵。适用于本地自动化脚本、智能体编辑验证和编辑器集成场景。
OpenClaw OC Path 插件配置与 CLI 工具使用指南
oc-path 是 OpenClaw 项目自带的插件，为 openclaw path CLI 提供 oc:// 工作区文件寻址方案。插件源码位于 extensions/oc-path/ 目录，但默认不激活——安装或构建后需手动启用。
oc:// 地址指向工作区文件中的单个叶子节点（或通配符匹配的叶子集合）。目前支持四种文件类型：
- markdown（
.md,.mdx）：frontmatter、章节、条目、字段 - jsonc（
.jsonc,.json5,.json）：保留注释和格式 - jsonl（
.jsonl,.ndjson）：按行组织的记录 - yaml（
.yaml,.yml,.lobster）：通过 YAML 文档 API 访问映射/序列/标量节点
自托管用户和编辑器扩展可使用 CLI 读取或写入单个叶子，无需直接调用 SDK；智能体和钩子将其视为确定性底层组件，确保字节级往返和脱敏哨兵保护在各文件类型间一致生效。
为什么要启用该插件
当你需要脚本、钩子或本地智能体工具精准定位工作区状态的某一片段，而不想为每种文件格式单独编写解析器时，应启用 oc-path。一个 oc:// 地址可以指向 markdown frontmatter 键、JSONC 配置叶子、JSONL 事件字段或 YAML 工作流步骤。
这对于维护场景很重要：变更应小范围、可审计、可重复。你可以检查某个值、查找匹配记录、预演写入，然后只修改目标叶子，同时保留注释、换行和周围格式不变。将此插件设计为可选，让高级用户使用寻址底层，而无需为不需要它的安装引入解析器依赖或 CLI 表面。
常见启用原因：
- 本地自动化：shell 脚本可用
openclaw path … --json解析或更新单个工作区值，无需分别携带 markdown、JSONC、JSONL 和 YAML 解析代码。 - 智能体可见的编辑：智能体可以在写入前展示目标叶子的预演差异，比自由格式的文件重写更容易审查。
- 编辑器集成：编辑器可将
oc://AGENTS.md/tools/gh映射到精确的 markdown 节点和行号，无需通过标题文本猜测。 - 诊断：
emit子命令可将文件通过解析器和发射器往返处理，用于检查文件类型在自动编辑前是否字节稳定。
具体示例：
bash
# 检查此配置中 Github 插件是否启用
openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json
# 此会话日志中有哪些工具调用名称
openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json
# 这次小型配置编辑将写入哪些字节
openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run该插件有意不拥有更高层语义。内存插件仍控制内存写入，配置命令仍管理完整配置，LKG 逻辑仍负责恢复/晋升。oc-path 是狭窄的寻址和字节级文件操作层，供高层工具搭建。
它在哪里运行
插件在调用 openclaw path 命令的主机上，在 CLI 进程内运行。无需运行 Gateway，也不需打开任何网络套接字——每个动词都是对指定文件的纯变换。
插件元数据位于 extensions/oc-path/openclaw.plugin.json：
json
{
"id": "oc-path",
"name": "OC Path",
"activation": {
"onStartup": false,
"onCommands": ["path"]
},
"commandAliases": [{ "name": "path", "kind": "cli" }]
}onStartup: false 让插件远离 Gateway 热路径。onCommands: ["path"] 告诉 CLI 在首次运行 openclaw path 时懒加载该插件，因此从不使用该命令的安装无任何开销。
怎么启用
bash
openclaw plugins enable oc-path如果运行了 Gateway，重启以便 manifest 快照获取新状态。在同一主机上，直接执行 openclaw path 命令会立即工作——CLI 按需加载插件。
禁用：
bash
openclaw plugins disable oc-path依赖
所有解析器依赖都是插件本地的——启用 oc-path 不会为核心运行时引入新包：
| 依赖项 | 用途 |
|---|---|
commander | 子命令路由（resolve、find、set、validate、emit） |
jsonc-parser | JSONC 解析 + 保留注释和尾随逗号的叶子编辑 |
markdown-it | Markdown 分词（用于章节/条目/字段模型） |
yaml | YAML Document 解析/发射/编辑，保留注释和流样式 |
JSONL 保持手写——基于行的解析比任何依赖都简单，且每行的 JSONC 解析已通过 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不了解 Last-Known-Good 配置恢复。如果文件受 LKG 追踪，下一次observe调用决定是晋升还是恢复；set --batch通过 LKG 晋升/恢复生命周期实现原子多集写入的计划将与 LKG 恢复底层一同提供。
安全
set 通过底层发射路径写入原始字节，自动应用脱敏哨兵保护。携带 __OPENCLAW_REDACTED__（逐字或作为子字符串）的叶子在写入时会被拒绝并报错 OC_EMIT_SENTINEL。CLI 还会从其打印的任何人类或 JSON 输出中清除文字哨兵，替换为 [REDACTED]，以确保终端捕获和管道不会泄漏标记。
相关
常见问题
我可以使用 oc-path 编辑由内存插件管理的文件吗？
不可以。内存写入（如记忆管理）必须通过对应的 memory-* 插件进行。oc-path 只提供通用的文件寻址和编辑能力，不会处理内存插件的特定语义。
如何安全地进行批量写操作？
使用 set --batch 标志进行原子多集写入。该功能计划与 LKG 恢复底层一同提供，有助于确保批量变更的可审计性和回滚可能性。
为什么我的写入请求被拒绝了（OB_EMIT_SENTINEL 错误）？
当你要写入的叶子中包含 __OPENCLAW_REDACTED__ 哨兵字符串时，会触发此错误。这是为了保护敏感信息不被意外泄露。请检查输入数据，确保不包含该哨兵，然后重试。