openclaw path 提供终端内对 oc:// 地址的查询与编辑能力，适合从脚本或编辑扩展中精确读取或修改工作区文件中的某个值，而不破坏文件注释和格式。支持子命令 resolve（单次匹配）、find（通配符/谓词枚举）、set（写入）、validate（仅解析）和 emit（往返诊断）。写入前可用 --dry-run 预览变更，变更时自动应用 redaction-sentinel 保护。预装 oc-path 插件后启用：openclaw plugins enable oc-path。

OpenClaw path 命令：oc://路径查询与编辑指南

openclaw path 是插件提供的 shell 访问 oc:// 寻址基座的接口：一种按文件类型（kind）分发路径的方案，用于检查和编辑可寻址的工作区文件（markdown、jsonc、jsonl、yaml/yml/lobster）。自托管用户、插件作者和编辑器扩展用它读取、查找或更新一个狭窄位置，而无需为每种文件类型手写解析器。

CLI 镜像了基座的公共动词：

resolve 是具体的、单次匹配。
find 是多匹配动词，支持通配符、联合、谓词和位置展开。
set 只接受具体路径或插入标记；通配符模式在写入前被拒绝。

path 由捆绑的可选插件 oc-path 提供。首次使用前请启用：

bash

openclaw plugins enable oc-path

为什么使用它

OpenClaw 的状态分布在人工编辑的 markdown、带注释的 JSONC 配置、追加写入的 JSONL 日志和 YAML 工作流/规约文件中。Shell 脚本、钩子和智能体经常需要从这些文件中获取一个小的值：frontmatter 键、插件设置、日志记录字段、YAML 步骤或命名小节下的列表项。

openclaw path 为这些调用方提供了一个稳定的地址，而不是为每种文件类型编写一次性的 grep、正则或解析器。同一个 oc:// 路径可以从终端验证、解析、搜索、dry-run 和写入，这使得狭窄的自动化更容易审查和更安全地重放。当你希望更新一个叶子节点同时保留文件其余部分的注释、换行和周围格式时，它尤其有用。

当你需要的对象有逻辑地址，但物理文件形状变化时使用它：

钩子想从带注释的 JSONC 中读取一个设置，并在写回时保留注释。
维护脚本想找到 JSONL 日志中所有匹配的事件字段，而不将整个日志加载到自定义解析器中。
编辑器扩展想通过 slug 跳转到 markdown 章节或列表项，然后渲染它解析到的具体行。
智能体想在应用之前 dry-run 一个微小的工作区编辑，并在审查中看到变更后的字节。

你通常不需要 openclaw path 来做普通的全文件编辑、复杂的配置迁移或内存特定的写入。这些应该使用对应的命令或插件。path 适用于小的、可寻址的文件操作，在这种情况下，一个可重复的终端命令比另一个定制的解析器更清晰。

如何使用

从人工编辑的配置文件中读取一个值：

bash

openclaw path resolve 'oc://config.jsonc/plugins/github/enabled'

在不接触磁盘的情况下预览写入：

bash

openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

在追加写入的 JSONL 日志中查找匹配的记录：

bash

openclaw path find 'oc://session.jsonl/[event=tool_call]/name'

按章节和项目而不是行号来寻址 markdown 中的指令：

bash

openclaw path resolve 'oc://AGENTS.md/runtime-safety/openclaw-gateway'

在 CI 或预检脚本中验证路径，然后再读取或写入：

bash

openclaw path validate 'oc://AGENTS.md/tools/$last/risk'

这些命令设计为可复制到 shell 脚本中。当调用方需要结构化输出时使用 --json，当人检查结果时使用 --human。

工作原理

openclaw path 做四件事：

将 oc:// 地址解析为多个槽位：file、section、item、field 和可选的 session。
根据目标扩展名（.md、.jsonc、.jsonl、.yaml、.yml、.lobster 及相关别名）选择文件类型适配器。
将该文件类型的 AST 中的槽位解析出来：markdown 标题/列表项、JSONC 对象键/数组索引、JSONL 行记录或 YAML 映射/序列节点。
对于 set，通过同一个适配器发出编辑后的字节，使得文件中未修改的部分保留其注释、换行和附近格式（如果该文件类型支持）。

resolve 和 set 需要一个具体的目标。find 是探索性动词：它将通配符、联合、谓词和序数展开为具体的匹配，你可以在选择写入之前检查这些匹配。

子命令

子命令	用途
`resolve <oc-path>`	打印路径的具体匹配（或 "not found"）。
`find <pattern>`	枚举通配符/联合/谓词路径的匹配。
`set <oc-path> <value>`	在具体路径写入叶子节点或插入目标。支持 `--dry-run`。
`validate <oc-path>`	仅解析；打印结构分解（file / section / item / field）。
`emit <file>`	通过 `parseXxx` + `emitXxx` 往返处理文件（字节保真度诊断）。

全局标志

标志	用途
`--cwd <dir>`	相对此目录解析文件槽位（默认：`process.cwd()`）。
`--file <path>`	覆盖文件槽位的解析路径（绝对访问）。
`--json`	强制 JSON 输出（当 stdout 不是 TTY 时默认）。
`--human`	强制人类可读输出（当 stdout 是 TTY 时默认）。
`--dry-run`	（仅用于 `set`）打印将要写入的字节，但不写入。
`--diff`	（与 `set --dry-run` 一起使用）打印统一 diff 而不是完整字节。

`oc://` 语法

oc://FILE/SECTION/ITEM/FIELD?session=SCOPE

槽位规则：field 需要 item，item 需要 section。在所有四个槽位中：

引号段 — "a/b.c" 可避开 / 和 . 分隔符。内容是字节字面量；引号内不允许有 " 和 \。文件槽位也支持引号：oc://"skills/email-drafter"/Tools/$last 将 skills/email-drafter 视为单个文件路径。
谓词 — [k=v]、[k!=v]、[k<v]、[k<=v]、[k>v]、[k>=v]。数值操作要求两边都能转为有限数字。
联合 — {a,b,c} 匹配任何一个选项。
通配符 — *（单个子段）和 **（零个或多个，递归）。find 接受它们；resolve 和 set 因歧义拒绝它们。
位置 — $first / $last 解析为第一个/最后一个索引或声明的键。
序数 — #N 表示文档顺序中的第 N 个匹配。
插入标记 — +、+key、+nnn 用于键控/索引插入（与 set 一起使用）。
会话范围 — ?session=cron-daily 等。与槽位嵌套正交。会话值是原始文本，不进行百分比解码；它们不能包含控制字符或保留的查询分隔符（?、&、%）。

在引号段、谓词段或联合段之外的保留字符（?、&、%）会被拒绝。任何地方的控制字符（U+0000-U+001F、U+007F）都会被拒绝，包括 session 查询值。

formatOcPath(parseOcPath(path)) === path 对规范路径保证成立。非规范的查询参数会被忽略，除了第一个非空的 session= 值。

按文件类型寻址

类型	寻址模型
Markdown	通过 slug 的 H2 章节、通过 slug 或 `#N` 的列表项、通过 `[frontmatter]` 的 frontmatter。
JSONC/JSON	对象键和数组索引；点分隔嵌套的子段，除非用引号包裹。
JSONL	顶层的行地址（`L1`、`L2`、`$first`、`$last`），然后行内按 JSONC 风格下降。
YAML/YML/.lobster	映射键和序列索引；注释和流风格由 YAML 文档 API 处理。

resolve 返回结构化匹配：root、node、leaf 或 insertion-point，并带有基于 1 的行号。叶子值以文本和 leafType 形式呈现，以便插件作者无需依赖每种文件类型的 AST 形状即可渲染预览。

突变契约

set 写入一个具体目标：

Markdown frontmatter 值和 - key: value 列表项字段是字符串叶子。Markdown 插入会附加章节、frontmatter 键或章节列表项，并为更改后的文件渲染规范的 markdown 形状。
JSONC 叶子写入会强制将字符串值转换为现有叶子类型（string、有限 number、true/false 或 null）。JSONC 对象和数组插入将 <value> 解析为 JSON，并使用 jsonc-parser 编辑路径进行普通叶子写入，保留注释和附近格式。
JSONL 叶子写入在行内强制转换（类似 JSONC）。整行替换和追加将 <value> 解析为 JSON。渲染后的 JSONL 保留文件主导的 LF/CRLF 换行约定。
YAML 叶子写入会强制转换为现有标量类型（string、有限 number、true/false 或 null）。YAML 插入使用捆绑的 yaml 包的文档 API 进行映射/序列更新。格式错误的 YAML 文档在变异前会被拒绝，并返回 parse-error。

在对字节有严格要求时，在用户可见的写入之前使用 --dry-run。基座为解析/发出往返保证字节相同的输出，但一次突变可能会规范化编辑区域或文件（取决于类型）。当你想要预览为集中的前后对比补丁而非完整渲染文件时，添加 --diff。

示例

bash

# 验证路径（不访问文件系统）
openclaw path validate 'oc://AGENTS.md/Tools/$last/risk'

# 读取叶子节点
openclaw path resolve 'oc://gateway.jsonc/version'

# 通配符搜索
openclaw path find 'oc://session.jsonl/*/event' --file ./logs/session.jsonl

# Dry-run 写入
openclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run

# Dry-run 写入为 unified diff
openclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run --diff

# 应用写入
openclaw path set 'oc://gateway.jsonc/version' '2.0'

# 字节保真往返（诊断）
openclaw path emit ./AGENTS.md

更多语法示例：

bash

# 引号键包含 / 或 .
openclaw path resolve 'oc://config.jsonc/agents.defaults.models/"anthropic/claude-opus-4-7"/alias'

# 对 JSONC 子元素进行谓词搜索
openclaw path find 'oc://config.jsonc/plugins/[enabled=true]/id'

# 插入到 JSONC 数组
openclaw path set 'oc://config.jsonc/items/+1' '{"id":"new","enabled":true}' --dry-run

# 插入 JSONC 对象键
openclaw path set 'oc://config.jsonc/plugins/+github' '{"enabled":true}' --dry-run

# 追加 JSONL 事件
openclaw path set 'oc://session.jsonl/+' '{"event":"checkpoint","ok":true}' --file ./logs/session.jsonl

# 解析最后一条 JSONL 值的行
openclaw path resolve 'oc://session.jsonl/$last/event' --file ./logs/session.jsonl

# 解析 YAML 工作流步骤
openclaw path resolve 'oc://workflow.yaml/steps/0/id' --file workflow.yaml

# 更新 YAML 标量
openclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --dry-run

# 寻址 markdown frontmatter
openclaw path resolve 'oc://AGENTS.md/[frontmatter]/name'

# 插入 markdown frontmatter
openclaw path set 'oc://AGENTS.md/[frontmatter]/+description' 'Agent instructions' --dry-run

# 查找 markdown 列表项字段
openclaw path find 'oc://SKILL.md/Tools/*/send_email'

# 验证会话范围的路径
openclaw path validate 'oc://AGENTS.md/Tools/$last/risk?session=cron-daily'

按文件类型的配方

同样的五个动词适用于所有类型；寻址方案根据文件扩展名分发。以下示例使用文档描述中的测试文件。

Markdown

text

<!-- frontmatter.md -->
---
name: drafter
description: email drafting agent
tier: core
---
## Tools
- gh: GitHub CLI
- curl: HTTP client
- send_email: enabled

bash

$ openclaw path resolve 'oc://x.md/[frontmatter]/tier' --file frontmatter.md --human
leaf @ L4: "core" (string)

$ openclaw path resolve 'oc://x.md/tools/gh/gh' --file frontmatter.md --human
leaf @ L9: "GitHub CLI" (string)

$ openclaw path find 'oc://x.md/tools/*' --file frontmatter.md --human
3 matches for oc://x.md/tools/*:
  oc://x.md/tools/gh           →  node @ L9 [md-item]
  oc://x.md/tools/curl         →  node @ L10 [md-item]
  oc://x.md/tools/send-email   →  node @ L11 [md-item]

[frontmatter] 谓词寻址 YAML frontmatter 块；tools 通过 slug 匹配 ## Tools 标题，并且列表项叶子即使源文件使用下划线（send_email → send-email）也会保留其 slug 形式。

JSONC

text

// config.jsonc
{
  "plugins": {
    "github": {"enabled": true, "role": "vcs"},
    "slack":  {"enabled": false, "role": "chat"}
  }
}

bash

$ openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --file config.jsonc --human
leaf @ L4: "true" (boolean)

$ openclaw path set 'oc://config.jsonc/plugins/slack/enabled' 'true' --file config.jsonc --dry-run
--dry-run: would write 142 bytes to /…/config.jsonc
{
  "plugins": {
    "github": {"enabled": true, "role": "vcs"},
    "slack":  {"enabled": true, "role": "chat"}
  }
}

JSONC 编辑通过 jsonc-parser 进行，因此注释和空白在 set 后保留。先使用 --dry-run 在提交之前检查字节。

JSONL

text

{"event":"start","userId":"u1","ts":1}
{"event":"action","userId":"u1","ts":2}
{"event":"end","userId":"u1","ts":3}

bash

$ openclaw path find 'oc://session.jsonl/[event=action]/userId' --file session.jsonl --human
1 match for oc://session.jsonl/[event=action]/userId:
  oc://session.jsonl/L2/userId  →  leaf @ L2: "u1" (string)

$ openclaw path resolve 'oc://session.jsonl/L2/ts' --file session.jsonl --human
leaf @ L2: "2" (number)

每行是一条记录。当你不知道行号时通过谓词（[event=action]）寻址，当你知道规范行段 LN 时直接寻址。

YAML

text

# workflow.yaml
name: inbox-triage
steps:
  - id: fetch
    command: gmail.search
  - id: classify
    command: openclaw.invoke

bash

$ openclaw path resolve 'oc://workflow.yaml/steps/0/id' --file workflow.yaml --human
leaf @ L3: "fetch" (string)

$ openclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --file workflow.yaml --dry-run
--dry-run: would write 99 bytes to /…/workflow.yaml
name: inbox-triage
steps:
  - id: fetch
    command: gmail.search
  - id: classify-renamed
    command: openclaw.invoke

YAML 使用 yaml 包的 Document API 而不是自制解析器，因此普通的解析/发出往返保留注释和创作形状，而解析后的路径使用与 JSONC 相同的映射键/序列索引模型。同一个适配器处理 .yaml、.yml 和 .lobster 文件。

子命令参考

`resolve <oc-path>`

读取单个叶子或节点。通配符被拒绝——请使用 find。匹配时退出 0，干净未命中时退出 1，解析错误或模式被拒绝时退出 2。

bash

openclaw path resolve 'oc://AGENTS.md/tools/gh/risk' --human
openclaw path resolve 'oc://gateway.jsonc/server/port' --json

`find <pattern>`

枚举通配符/谓词/联合模式的每个匹配。至少一个匹配时退出 0，零匹配时退出 1。文件槽位的通配符被拒绝，返回 OC_PATH_FILE_WILDCARD_UNSUPPORTED（多文件 glob 是一个后续功能）。

bash

openclaw path find 'oc://AGENTS.md/tools/**/risk'
openclaw path find 'oc://session.jsonl/[event=action]/userId'
openclaw path find 'oc://config.jsonc/plugins/{github,slack}/enabled'

`set <oc-path> <value>`

写入一个叶子。配合 --dry-run 预览将要写入的字节而不修改文件。添加 --diff 以获取统一 diff 预览。成功写入时退出 0，基座拒绝时退出 1（例如命中 sentinel 守卫），解析错误时退出 2。

bash

openclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run
openclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run --diff
openclaw path set 'oc://gateway.jsonc/version' '2.0'
openclaw path set 'oc://AGENTS.md/Tools/+gh/risk' 'low'

+key 插入标记创建命名子元素（如果尚不存在）；+nnn 和单独 + 分别用于索引插入和追加插入。

`validate <oc-path>`

仅解析检查。不访问文件系统。当你想确认模板路径格式是否正确（以便在替换变量之前），或想要结构分解以供调试时使用：

bash

$ openclaw path validate 'oc://AGENTS.md/tools/gh' --human
valid: oc://AGENTS.md/tools/gh
  file:    AGENTS.md
  section: tools
  item:    gh

有效时退出 0，无效时退出 1（附带结构化的 code 和 message），参数错误时退出 2。

`emit <file>`

通过每种文件类型的解析器和发射器往返处理文件。对于正常的文件，输出应与输入字节相同——差异表明解析器错误或 sentinel 命中。用于调试基座对真实世界输入的行为。

bash

openclaw path emit ./AGENTS.md
openclaw path emit ./gateway.jsonc --json

退出码

代码	含义
`0`	成功。（`resolve`/`find`：至少一个匹配。`set`：写入成功。）
`1`	无匹配，或 `set` 被基座拒绝（非系统级错误）。
`2`	参数或解析错误。

输出模式

openclaw path 是 TTY 感知的：在终端上输出人类可读格式，stdout 被管道或重定向时输出 JSON。--json 和 --human 覆盖自动检测。

注意事项

set 通过基座的发射路径写入字节，这会自动应用 redaction-sentinel 守卫。包含 __OPENCLAW_REDACTED__（原样或作为子字符串）的叶子会在写入时被拒绝。
JSONC 解析和叶子编辑使用插件本地的 jsonc-parser 依赖，因此普通叶子写入时注释和格式会被保留，而不是通过自制的解析器/重新渲染路径。
path 不了解 LKG。如果文件受 LKG 跟踪，下一次 observe 调用决定是提升还是恢复。通过 LKG 提升/恢复生命周期实现原子多写的 set --batch 计划与 LKG 恢复基座一起提供。

参考

CLI 参考

常见问题

openclaw path set 写入失败怎么办？

检查写入值是否包含 __OPENCLAW_REDACTED__（redaction-sentinel 拒绝写入）。也检查路径是否包含通配符（通配符只能用于 find）。使用 --dry-run 预览写入的字节，确认路径解析正确。退出码 1 表示基座拒绝，2 表示参数或解析错误。

oc:// 路径格式错误怎么验证？

使用 openclaw path validate <oc-path> 命令，它仅解析路径语法，不访问文件系统。如果路径无效，会输出结构化的错误代码和消息。例如 oc://AGENTS.md/tools/gh 有效，而包含保留字符的路径会被拒绝。

openclaw path 支持哪些文件类型？

支持 .md（Markdown）、.jsonc/.json（JSONC）、.jsonl（JSONL）、.yaml/.yml/.lobster（YAML）。每个文件类型有不同的寻址模型：Markdown 按 slug 和 frontmatter，JSONC 按键和索引，JSONL 按行号和键，YAML 按映射键和序列索引。

OpenClaw path 命令：oc://路径查询与编辑指南 ​

为什么使用它 ​

如何使用 ​

工作原理 ​

子命令 ​

全局标志 ​

oc:// 语法 ​

按文件类型寻址 ​

突变契约 ​

示例 ​

按文件类型的配方 ​

Markdown ​

JSONC ​

JSONL ​

YAML ​

子命令参考 ​

resolve &lt;oc-path&gt; ​

find &lt;pattern&gt; ​

set &lt;oc-path&gt; &lt;value&gt; ​

validate &lt;oc-path&gt; ​

emit &lt;file&gt; ​

退出码 ​

输出模式 ​

注意事项 ​

参考 ​

常见问题 ​

openclaw path set 写入失败怎么办？ ​

oc:// 路径格式错误怎么验证？ ​

openclaw path 支持哪些文件类型？ ​

OpenClaw path 命令：oc://路径查询与编辑指南

为什么使用它

如何使用

工作原理

子命令

全局标志

`oc://` 语法

按文件类型寻址

突变契约

示例

按文件类型的配方

Markdown

JSONC

JSONL

YAML

子命令参考

`resolve <oc-path>`

`find <pattern>`

`set <oc-path> <value>`

`validate <oc-path>`

`emit <file>`

退出码

输出模式

注意事项

参考

常见问题

openclaw path set 写入失败怎么办？

oc:// 路径格式错误怎么验证？

openclaw path 支持哪些文件类型？