OC Path Plugin: CLI for oc:// Workspace File Addressing

The oc-path plugin, which ships with OpenClaw, provides the openclaw path command line tool for the oc:// workspace file addressing scheme. You can find it in the repository under extensions/oc-path/, but it is not activated by default. Installation and builds leave it inactive unless you specifically turn it on.

An oc:// address targets a single leaf, or a wildcard set of leaves, within a workspace file. The plugin supports four file types:

markdown (.md): frontmatter, sections, items, fields
jsonc (.jsonc, .json): preserves comments and formatting
jsonl (.jsonl, .ndjson): records organized by line
yaml (.yaml, .yml, .lobster): map, sequence, and scalar nodes accessed through the yaml package's Document API

Self hosted deployments and editor extensions rely on the CLI to read or write individual leaves without needing to script against the SDK. Agents and hooks use it as a deterministic foundation, so byte fidelity round trips and the redaction sentinel guard work consistently across all file types. For the complete grammar, a verb by verb flag list, and worked examples per file type, see the CLI reference. This page explains why you would enable the plugin and how to do it.

Why enable it

Turn on oc-path when scripts, hooks, or local agent tooling need to reference a specific piece of workspace state without a custom parser for each file format. A single oc:// address can point to a markdown frontmatter key, a section item, a JSONC config leaf, a JSONL event field, or a YAML workflow step.

This matters for maintainer workflows where changes should stay small, auditable, and repeatable. You can inspect one value, find matching records, dry run a write, and then apply only that leaf while leaving comments, line endings, and nearby formatting untouched.

Common reasons to enable it:

Local automation: Shell scripts resolve or update a single workspace value using openclaw path … --json instead of carrying separate parsing code for markdown, JSONC, JSONL, and YAML.
Agent visible edits: An agent shows a dry run diff for one addressed leaf before writing, which is easier to review than a full 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 passes a file through the parser and emitter, so you can verify whether a file type 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 deliberately not responsible for 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 and promotion. oc-path serves as the narrow addressing and byte preserving file operation layer that those higher level tools can build on.

Where it runs

The plugin runs in process inside the openclaw CLI on the host where you issue the command. It does not require a running Gateway and does not open any network sockets. Every verb is a pure transformation on a file you point it at.

Plugin metadata is stored 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 instruct the CLI to load the plugin lazily the first time you run openclaw path …, so installations that never use the verb incur 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.

To disable it:

openclaw plugins disable oc-path

Dependencies

All parser dependencies are local to the plugin. Enabling oc-path does not introduce new packages into the core runtime:

Dependency	Purpose
`commander`	Subcommand wiring for `resolve`, `find`, `set`, `validate`, `emit`.
`jsonc-parser`	JSONC parsing and leaf edits that preserve comments and trailing commas.
`markdown-it`	Markdown tokenization for the section, item, and field model.
`yaml`	YAML `Document` parsing, emitting, and editing while keeping comments and flow style.

JSONL is handled with custom code. 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 and formatter	`extensions/oc-path/src/oc-path/oc-path.ts`
Per type parse, emit, and edit	`extensions/oc-path/src/oc-path/{md,jsonc,jsonl,yaml}`
Universal resolve, find, and 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 available 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 are routed through the memory plugins rather than oc-path. The generic file layer oc-path serves as a base; memory plugins impose their own logic on top of it.
LKG: Last-known-good config restoration is unknown to path. When you modify a file through path and that file is also tracked by LKG, the subsequent config observation cycle determines whether to promote or recover it. Treat a path edit the same as any direct write to that file.

Safety

Through the substrate's emit path, set writes raw bytes, and the redaction-sentinel guard is applied automatically. A leaf containing __OPENCLAW_REDACTED__ (either exactly or as a substring) is rejected at write time, returning OC_EMIT_SENTINEL. Additionally, the CLI strips the literal sentinel from any printed human or JSON output, substituting it with [REDACTED] so terminal captures and pipelines never expose the marker.