openclaw-openclaw/docs/plugins/oc-path.md

summary, read_when, title

summary	read_when	title
Bundled `oc-path` plugin: ships the `openclaw path` CLI for the `oc://` workspace-file addressing scheme	You want to inspect or edit a single leaf inside a workspace file from the terminal You are scripting against workspace state and need a stable, kind-agnostic addressing scheme You are deciding whether to enable the optional `oc-path` plugin on a self-hosted Gateway	OC Path plugin

The bundled oc-path plugin adds the openclaw path CLI for the oc:// workspace-file addressing scheme. It ships in the OpenClaw repo under extensions/oc-path/ but is opt-in: install/build leaves it dormant until you enable it.

oc:// addresses point at a single leaf (or a wildcard set of leaves) inside a workspace file. The plugin understands four file kinds:

• markdown (.md): frontmatter, sections, items, fields
• jsonc (.jsonc, .json): comments and formatting preserved
• jsonl (.jsonl, .ndjson): line-oriented records
• yaml (.yaml, .yml, .lobster): map/sequence/scalar nodes through the yaml package's Document API

Self-hosters and editor extensions use the CLI to read or write a single leaf without scripting against the SDK directly; agents and hooks treat it as a deterministic substrate so byte-fidelity round-trips and the redaction sentinel guard apply uniformly across kinds. See the CLI reference for the full grammar, verb-by-verb flag list, and worked examples per file kind; this page covers why and how to enable the plugin.

Why enable it

Enable oc-path when scripts, hooks, or local agent tooling need to point at a precise piece of workspace state without a bespoke parser per file shape. A single oc:// address can name a markdown frontmatter key, a section item, a JSONC config leaf, a JSONL event field, or a YAML workflow step.

That matters for maintainer workflows where the change should stay small, auditable, and repeatable: inspect one value, find matching records, dry-run a write, then apply only that leaf while leaving comments, line endings, and nearby formatting alone.

Common reasons to enable it:

• Local automation: shell scripts resolve or update one workspace value with openclaw path … --json instead of carrying separate markdown, JSONC, JSONL, and YAML parsing code.
• Agent-visible edits: an agent shows a dry-run diff for one addressed leaf before writing, which is easier to review than a free-form file rewrite.
• Editor integrations: an editor maps oc://AGENTS.md/tools/gh to the exact markdown node and line number without guessing from heading text.
• Diagnostics: emit round-trips a file through the parser and emitter, so you can check whether a file kind is byte-stable before relying on automated edits.

# Is the GitHub plugin enabled in this config?
openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json

# Which tool-call names appear in this session log?
openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json

# What bytes would this tiny config edit write?
openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

oc-path is intentionally not the owner of higher-level semantics. Memory plugins still own memory writes, config commands still own full config management, and last-known-good (LKG) config recovery still owns restore/promotion. oc-path is the narrow addressing and byte-preserving file operation layer those higher-level tools can build around.

Where it runs

The plugin runs in-process inside the openclaw CLI on the host where you invoke the command. It does not need a running Gateway and does not open any network sockets; every verb is a pure transform over a file you point it at.

Plugin metadata lives in extensions/oc-path/openclaw.plugin.json:

{
  "id": "oc-path",
  "name": "OC Path",
  "activation": {
    "onStartup": false,
    "onCommands": ["path"]
  },
  "commandAliases": [{ "name": "path", "kind": "cli" }]
}

onStartup: false keeps the plugin out of the Gateway startup path. commandAliases and activation.onCommands tell the CLI to load the plugin lazily the first time you run openclaw path …, so installs that never use the verb pay no cost.

Enable

openclaw plugins enable oc-path

Restart the Gateway (if you run one) so the manifest snapshot picks up the new state. Bare openclaw path invocations work immediately on the same host; the CLI loads the plugin on demand.

Disable with:

openclaw plugins disable oc-path

Dependencies

All parser dependencies are plugin-local; enabling oc-path does not pull new packages into the core runtime:

Dependency	Purpose
commander	Subcommand wiring for resolve, find, set, validate, emit.
jsonc-parser	JSONC parse and leaf edits with comments and trailing commas kept.
markdown-it	Markdown tokenization for the section / item / field model.
yaml	YAML Document parse / emit / edit with comments and flow style kept.

JSONL stays hand-rolled: line-oriented parsing is simpler than any dependency, and the per-line parse already goes through jsonc-parser.

What it provides

Surface	Provided by
openclaw path CLI	extensions/oc-path/cli-registration.ts
oc:// parser / formatter	extensions/oc-path/src/oc-path/oc-path.ts
Per-kind parse / emit / edit	extensions/oc-path/src/oc-path/{md,jsonc,jsonl,yaml}
Universal resolve / find / set	extensions/oc-path/src/oc-path/{resolve,find,edit}.ts
Redaction-sentinel guard	extensions/oc-path/src/oc-path/sentinel.ts

The CLI is the only public surface today. The substrate verbs are private to the plugin; consumers use the CLI (or build their own plugin against the SDK).

Relationship to other plugins

• memory-*: memory writes go through the memory plugins, not oc-path. oc-path is a generic file substrate; memory plugins layer their own semantics on top.
• LKG: path does not know about last-known-good config restore. If a file you edit through path is also LKG-tracked, the next config observe cycle decides whether to promote or recover it; treat a path edit the same as any other direct write to that file.

Safety

set writes raw bytes through the substrate's emit path, which applies the redaction-sentinel guard automatically. A leaf carrying __OPENCLAW_REDACTED__ (verbatim or as a substring) is refused at write time with OC_EMIT_SENTINEL. The CLI also scrubs the literal sentinel from any human or JSON output it prints, replacing it with [REDACTED] so terminal captures and pipelines never leak the marker.

Related

• openclaw path CLI reference
• Manage plugins
• Building plugins