OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

扩展

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 通过解析器和发射器对文件进行往返处理， 以便你在依赖自动编辑之前检查某种文件类型是否具备字节稳定性。
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

oc-path 有意不负责更高层级的语义。记忆插件仍负责记忆写入，配置命令仍负责完整的配置管理，最后已知良好状态（LKG）配置恢复仍负责还原/提升。oc-path 是一个范围有限的寻址和字节保真文件操作层，更高层级的工具可以围绕它进行构建。

运行位置

该插件在你调用命令的主机上，于 openclaw 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 网关启动路径。 commandAliases 和 activation.onCommands 指示 CLI 在你首次运行 openclaw path … 时延迟加载该插件，因此从不使用该动词的安装不会产生任何开销。

启用

bash
openclaw plugins enable oc-path

重启 Gateway 网关（如果你运行了一个），以便清单快照获取新状态。同一主机上的裸 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-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}
通用解析/查找/设置 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 通过底层基础的发射路径写入原始字节，该路径会自动应用脱敏哨兵保护机制。携带 __OPENCLAW_REDACTED__（原样或作为子字符串）的叶节点在写入时会被拒绝，并返回 OC_EMIT_SENTINEL。CLI 还会从其打印的所有人类可读或 JSON 输出中清除字面哨兵，将其替换为 [REDACTED]，确保终端捕获和管道永远不会泄露该标记。

相关内容

Was this useful?
On this page

On this page