openclaw path
Shell access to the oc:// addressing scheme: one kind-dispatched path syntax
for inspecting and editing addressable workspace files (markdown, jsonc,
jsonl, yaml/yml/lobster). Self-hosters, plugin authors, and editor extensions
use it to read, find, or update a narrow location without hand-rolling a
per-file parser.
path is provided by the bundled optional oc-path plugin. Enable it before
first use:
resolveis concrete and single-match.findis the multi-match verb for wildcards, unions, predicates, and positional expansion.setonly accepts concrete paths or insertion markers; wildcard patterns are rejected before writing.validateparses a path with no filesystem access.emitround-trips a file through parse + emit (byte-fidelity diagnostic).
Why use it
OpenClaw state is spread across human-edited markdown, commented JSONC config, append-only JSONL logs, and YAML workflow/spec files. Scripts, hooks, and agents often need one small value from those files: a frontmatter key, a plugin setting, a log record field, a YAML step, or a bullet item under a named section.openclaw path gives those callers a stable address instead of a one-off
grep, regex, or parser per file kind. The same oc:// path can be validated,
resolved, searched, dry-run, and written from the terminal, which keeps narrow
automation reviewable and replayable. It preserves the rest of the file, so
writing one leaf does not disturb its comments, line endings, or nearby
formatting.
Use it when the thing you want has a logical address, but the file shape
varies:
- A hook reads one setting from commented JSONC without losing comments when it writes the value back.
- A maintenance script finds every matching event field in a JSONL log without loading the whole log into a custom parser.
- An editor jumps to a markdown section or bullet item by slug, then renders the exact line it resolved to.
- An agent dry-runs a small workspace edit before applying it, with the changed bytes visible in review.
openclaw path for ordinary whole-file edits, rich config migrations, or
memory-specific writes; those should use the owner command or plugin. path
is for small, addressable file operations where a repeatable terminal command
beats another bespoke parser.
How it is used
Read one value from a human-edited config file:--json when
a caller needs structured output and --human when a person is inspecting
the result.
How it works
- Parses the
oc://address into slots: file, section, item, field, and an optional session query. - Chooses the file-kind adapter from the target extension (
.md,.jsonc,.json,.jsonl,.ndjson,.yaml,.yml,.lobster). - Resolves the slots against that file kind’s structure: markdown headings/items, JSONC object keys/array indexes, JSONL line records, or YAML map/sequence nodes.
- For
set, emits edited bytes through the same adapter so untouched parts of the file keep their comments, line endings, and nearby formatting where the kind supports it.
resolve and set require one concrete target. find is the exploratory
verb: it expands wildcards, unions, predicates, and ordinals into the concrete
matches you can inspect before choosing one to write.
Subcommands
| Subcommand | Purpose |
|---|---|
resolve <oc-path> | Print the concrete match at the path (or “not found”). |
find <pattern> | Enumerate matches for a wildcard / union / predicate path. |
set <oc-path> <value> | Write a leaf or insertion target at a concrete path. Supports --dry-run. |
validate <oc-path> | Parse-only; print the structural breakdown (file / section / item / field). |
emit <file> | Round-trip a file through parse + emit (byte-fidelity diagnostic). |
Global flags
| Flag | Applies to | Purpose |
|---|---|---|
--cwd <dir> | resolve, find, set, emit | Resolve the file slot against this directory (default: process.cwd()). |
--file <path> | resolve, find, set, emit | Override the file slot’s resolved path (absolute access). |
--json | all | Force JSON output (default when stdout is not a TTY). |
--human | all | Force human output (default when stdout is a TTY). |
--value-json | set | Parse <value> as JSON for JSON/JSONC/JSONL leaf replacement. |
--dry-run | set | Print the bytes that would be written without writing. |
--diff | set (requires --dry-run) | Print a unified diff instead of the full bytes. |
validate takes only --json / --human; it does no filesystem access, so
--cwd and --file do not apply.
oc:// syntax
field requires item, and item requires section. Across
all four slots:
- Quoted segments —
"a/b.c"survives/and.separators. Content is byte-literal;"and\are not allowed inside quotes. The file slot is also quote-aware:oc://"skills/email-drafter"/Tools/$lasttreatsskills/email-drafteras a single file path. - Predicates —
[k=v],[k!=v],[k<v],[k<=v],[k>v],[k>=v]. Numeric operators require both sides to coerce to finite numbers. - Unions —
{a,b,c}matches any of the alternatives. - Wildcards —
*(single sub-segment) and**(zero-or-more, recursive).findaccepts these;resolveandsetreject them as ambiguous. - Positional —
$first/$lastresolve to the first / last index or declared key. - Ordinal —
#Nfor the Nth match by document order. - Insertion markers —
+,+key,+nnnfor keyed / indexed insertion (use withset). - Session scope —
?session=cron-dailyetc. Orthogonal to slot nesting. Session values are raw, not percent-decoded; they may not contain control characters or reserved query delimiters (?,&,%).
?, &, %) outside quoted, predicate, or union
segments are rejected. Control characters (U+0000-U+001F, U+007F) are
rejected anywhere, including the session query value.
formatOcPath(parseOcPath(path)) === path is guaranteed for canonical paths.
Non-canonical query parameters are ignored except for the first non-empty
session= value.
Hard limits: a path caps at 4096 bytes, at most 4 slots (file/section/item/
field), at most 64 dotted sub-segments per slot, and at most 256 nested
traversal levels for deep JSON paths. Separately, any JSONC/JSON file input
over 16 MiB is refused with a parse diagnostic instead of being parsed, for
any verb that loads that file.
Addressing by file kind
| Kind | File extensions | Addressing model |
|---|---|---|
| Markdown | .md | H2 sections by slug, bullet items by slug or #N, frontmatter via [frontmatter]. |
| JSONC/JSON | .jsonc, .json | Object keys and array indexes; dots split nested sub-segments unless quoted. |
| JSONL | .jsonl, .ndjson | Top-level line addresses (L1, L2, $first, $last), then JSONC-style descent inside the line. |
| YAML/.lobster | .yaml, .yml, .lobster | Map keys and sequence indexes; comments and flow style are handled by the YAML document API. |
resolve returns a structured match: root, node, leaf, or
insertion-point, with a 1-based line number. Leaf values are surfaced as
text plus a leafType so plugin authors can render previews without
depending on the per-kind AST shape.
Mutation contract
set writes one concrete target:
- Markdown frontmatter values and
- key: valueitem fields are string leaves. Markdown insertions append sections, frontmatter keys, or section items and render a canonical markdown shape for the changed file. Section bodies are not writable as a whole throughset. - JSONC leaf writes coerce the string value to the existing leaf type
(
string, finitenumber,true/false, ornull). Use--value-jsonwhen a JSONC/JSON/JSONL leaf replacement should parse<value>as JSON and may change shape, such as replacing a string secret-ref shorthand with an object. JSONC object and array insertions parse<value>as JSON and use thejsonc-parseredit path for ordinary leaf writes, preserving comments and nearby formatting. - JSONL leaf writes coerce like JSONC inside a line. Whole-line replacement
and append parse
<value>as JSON. Rendered JSONL preserves the file’s dominant LF/CRLF line-ending convention (majority vote across the file’s newlines, so a mostly-CRLF file stays CRLF even with a few stray LFs). - YAML leaf writes coerce to the existing scalar type (
string, finitenumber,true/false, ornull). YAML insertions use the bundledyamlpackage’s document API for map/sequence updates. Malformed YAML documents with parser errors are refused before mutation withparse-error.
--dry-run before user-visible writes when the exact bytes matter. JSONC
and YAML edits patch the existing document (via jsonc-parser or the yaml
document API), so untouched bytes usually survive; markdown rebuilds the file
from its parsed structure on any edit, which can normalize incidental
formatting outside the changed leaf. Add --diff when you want the preview
as a focused before/after patch instead of the full rendered file.
Examples
Recipes by file kind
The same five verbs work across kinds; the addressing scheme dispatches on the file extension.Markdown
[frontmatter] predicate addresses the YAML frontmatter block; tools
matches the ## Tools heading via slug, and item leaves keep their slug form
even when the source uses underscores (send_email becomes send-email).
JSONC
jsonc-parser, so comments and whitespace survive a
set. Run with --dry-run first to inspect the bytes before committing.
.json files use the same adapter and edit path as .jsonc.
JSONL
[event=action]) when you do
not know the line number, or by the canonical LN segment when you do.
.ndjson files use the same adapter as .jsonl.
YAML
yaml package’s Document API rather than a hand-rolled
parser, so ordinary parse/emit round-trips preserve comments and authoring
shape while resolved paths use the same map-key / sequence-index model as
JSONC. The same adapter handles .yaml, .yml, and .lobster files.
Subcommand reference
resolve <oc-path>
Read a single leaf or node. Wildcards are rejected — use find for those.
Exits 0 on a match, 1 on a clean miss, 2 on a parse error or refused
pattern.
find <pattern>
Enumerate every match for a wildcard / predicate / union pattern. Exits 0
on at least one match, 1 on zero. File-slot wildcards are rejected with
OC_PATH_FILE_WILDCARD_UNSUPPORTED — pass a concrete file (multi-file
globbing is a follow-up feature).
set <oc-path> <value>
Write a leaf. Pair with --dry-run to preview the bytes that would be
written without touching the file. Add --diff for a unified diff preview.
Exits 0 on a successful write, 1 if the substrate refuses (for example, a
sentinel guard hit), 2 on parse errors.
+key insertion marker creates the named child if it does not already
exist; +nnn and bare + work for indexed and append insertion
respectively.
validate <oc-path>
Parse-only check. No filesystem access. Useful when you want to confirm a
template path is well-formed before substituting variables, or when you want
the structural breakdown for debugging:
0 when valid, 1 when invalid (with a structured code and
message), 2 on argument errors.
emit <file>
Round-trip a file through the per-kind parser and emitter. The output should
be byte-identical to the input on a sound file; divergence indicates a
parser bug or a sentinel hit. Useful for debugging substrate behavior on
real-world inputs.
Exit codes
| Code | Meaning |
|---|---|
0 | Success. (resolve / find: at least one match. set: write succeeded.) |
1 | No match, or set rejected by the substrate (no system-level error). |
2 | Argument or parse error. |
Output mode
openclaw path is TTY-aware: human-readable output on a terminal, JSON when
stdout is piped or redirected. --json and --human override the
auto-detection.
Notes
setwrites 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.- JSONC parsing and leaf edits use the plugin-local
jsonc-parserdependency, so comments and formatting are preserved on ordinary leaf writes instead of going through a hand-rolled parser/re-render path. pathis not aware of last-known-good (LKG) config tracking or recovery; that lifecycle is owned elsewhere. If a file you edit throughpathis also LKG-tracked, the next config read decides whether to promote or recover it; treat apathedit the same as any other direct write to that file.