# OC Path 插件

> 内置 oc-path 插件：提供用于 oc:// 工作区文件寻址方案的 openclaw path CLI

- 网址：https://funcoding.ai/agents/openclaw/plugins/oc-path/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/plugins/oc-path

---
内置的 `oc-path` 插件为 `oc://` 工作区文件寻址方案添加了 [`openclaw path`](https://funcoding.ai/agents/openclaw/cli/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 参考](https://funcoding.ai/agents/openclaw/cli/path/)；本页介绍启用该插件的原因和方法。

## 为什么启用它

当脚本、钩子或本地智能体工具需要精确指向工作区状态中的某个部分，而又不希望为每种文件结构编写专用解析器时，请启用 `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]`，确保终端捕获和管道永远不会泄露该标记。

## 相关内容

- [`openclaw path` CLI 参考](https://funcoding.ai/agents/openclaw/cli/path/)
- [管理插件](https://funcoding.ai/agents/openclaw/plugins/manage-plugins/)
- [Building Plugins](https://funcoding.ai/agents/openclaw/plugins/building-plugins/)