Skip to main content
内置的 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 通过解析器和发射器对文件进行往返处理， 以便你在依赖自动编辑之前检查某种文件类型是否具备字节稳定性。
oc-path 有意不负责更高层级的语义。记忆插件仍负责记忆写入，配置命令仍负责完整的配置管理，最后已知良好状态（LKG）配置恢复仍负责还原/提升。oc-path 是一个范围有限的寻址和字节保真文件操作层，更高层级的工具可以围绕它进行构建。

​
运行位置

该插件在你调用命令的主机上，于 openclaw CLI 进程内运行。它不需要正在运行的 Gateway 网关，也不会打开任何网络套接字；每个动词都只是对你所指定文件执行的纯转换。 插件元数据位于 extensions/oc-path/openclaw.plugin.json：
onStartup: false 使该插件不进入 Gateway 网关启动路径。 commandAliases 和 activation.onCommands 指示 CLI 在你首次运行 openclaw path … 时延迟加载该插件，因此从不使用该动词的安装不会产生任何开销。

​
启用

重启 Gateway 网关（如果你运行了一个），以便清单快照获取新状态。同一主机上的裸 openclaw path 调用会立即生效；CLI 会按需加载该插件。 禁用命令：

​
依赖项

所有解析器依赖项均为插件本地依赖；启用 oc-path 不会向核心运行时引入新软件包： JSONL 仍采用手写实现：面向行的解析比任何依赖项都更简单，而且每行解析已经通过 jsonc-parser 进行。

​
提供的功能

目前 CLI 是唯一的公开表面。底层基础动词是插件私有的；使用方通过 CLI 使用它们（或基于 SDK 构建自己的插件）。

​
与其他插件的关系

  • memory-*：记忆写入通过记忆插件完成，而不是通过 oc-path。oc-path 是通用文件底层基础；记忆插件在其上叠加自己的语义。
  • LKG：path 不处理最后已知良好状态的配置恢复。如果你通过 path 编辑的文件也由 LKG 跟踪，则下一个配置观察周期将决定是提升还是恢复该文件；应将 path 编辑视为对该文件的任何其他直接写入。

​
安全性

set 通过底层基础的发射路径写入原始字节，该路径会自动应用脱敏哨兵保护机制。携带 __OPENCLAW_REDACTED__（原样或作为子字符串）的叶节点在写入时会被拒绝，并返回 OC_EMIT_SENTINEL。CLI 还会从其打印的所有人类可读或 JSON 输出中清除字面哨兵，将其替换为 [REDACTED]，确保终端捕获和管道永远不会泄露该标记。

​
相关内容