mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-11 14:10:49 +00:00
118 lines
4.9 KiB
Markdown
118 lines
4.9 KiB
Markdown
---
|
|
summary: "Bundled `oc-path` plugin: ships the `openclaw path` CLI for the `oc://` workspace-file addressing scheme"
|
|
read_when:
|
|
- 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
|
|
title: "OC Path plugin"
|
|
---
|
|
|
|
The bundled `oc-path` plugin adds the [`openclaw path`](/cli/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 three kinds of files today:
|
|
|
|
- **markdown** (`.md`, `.mdx`): frontmatter, sections, items, fields
|
|
- **jsonc** (`.jsonc`, `.json5`, `.json`): comments and formatting preserved
|
|
- **jsonl** (`.jsonl`, `.ndjson`): line-oriented records
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
The plugin metadata lives in `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` keeps the plugin out of the Gateway hot path. `onCommands:
|
|
["path"]` tells 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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 + leaf edits with comments and trailing commas kept. |
|
|
| `markdown-it` | Markdown tokenization for the section / item / field model. |
|
|
|
|
JSONL stays hand-rolled — line-oriented parsing is simpler than any
|
|
dependency, and the per-line JSONC 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}` |
|
|
| 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 is LKG-tracked, the next `observe` call decides whether to promote or
|
|
recover; `set --batch` for atomic multi-set through the LKG promote/recover
|
|
lifecycle is planned alongside the LKG-recovery substrate.
|
|
|
|
## 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](/cli/path)
|
|
- [Manage plugins](/plugins/manage-plugins)
|
|
- [Building plugins](/plugins/building-plugins)
|