openclaw path

oc:// アドレス指定方式へのシェルアクセス：アドレス指定可能なワークスペースファイル（markdown、jsonc、jsonl、yaml/yml/lobster）を検査および編集するための、種類に応じてディスパッチされる単一のパス構文です。セルフホスト運用者、Plugin 作成者、エディター拡張機能は、ファイルごとのパーサーを独自実装することなく、限定された位置の読み取り、検索、更新にこれを使用できます。

path は、同梱のオプション oc-path Plugin によって提供されます。初めて使用する前に有効化してください：

openclaw plugins enable oc-path

CLI の動詞はアドレス指定モデルに対応しています：

• resolve は具体的で、単一一致です。
• find は、ワイルドカード、ユニオン、述語、位置展開に対応する複数一致用の動詞です。
• set は具体的なパスまたは挿入マーカーのみを受け付けます。ワイルドカードパターンは書き込み前に拒否されます。
• validate は、ファイルシステムにアクセスせずにパスを解析します。
• emit は、解析と出力を通じてファイルをラウンドトリップします（バイト忠実性の診断）。

使用する理由

OpenClaw の状態は、人が編集する Markdown、コメント付き JSONC 設定、追記専用 JSONL ログ、YAML ワークフロー／仕様ファイルに分散しています。スクリプト、フック、エージェントがこれらのファイルから必要とするのは、多くの場合、frontmatter のキー、Plugin 設定、ログレコードのフィールド、YAML のステップ、名前付きセクション下の箇条書き項目など、1 つの小さな値です。

openclaw path は、ファイル種類ごとに一度限りの grep、正規表現、パーサーを用意する代わりに、これらの呼び出し元へ安定したアドレスを提供します。同じ oc:// パスを端末から検証、解決、検索、ドライラン、書き込みできるため、限定的な自動化のレビューと再実行が容易になります。ファイルの残りの部分は保持されるため、1 つの末端を書き込んでも、コメント、改行コード、周辺の書式は乱れません。

必要な対象に論理的なアドレスがある一方で、ファイル形式が異なる場合に使用します：

• フックがコメント付き JSONC から 1 つの設定を読み取り、値を書き戻す際にもコメントを失いません。
• 保守スクリプトが、JSONL ログ全体を独自パーサーへ読み込むことなく、一致するすべてのイベントフィールドを検索します。
• エディターが、Markdown のセクションまたは箇条書き項目へスラッグで移動し、解決した正確な行を表示します。
• エージェントが小規模なワークスペース編集を適用前にドライランし、変更されるバイトをレビューで確認できるようにします。

通常のファイル全体の編集、高度な設定移行、メモリ固有の書き込みには openclaw path を使用しないでください。これらには所有者のコマンドまたは Plugin を使用する必要があります。path は、別の専用パーサーを作るよりも再実行可能な端末コマンドが適している、小規模でアドレス指定可能なファイル操作向けです。

使用方法

人が編集する設定ファイルから 1 つの値を読み取ります：

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

ディスクに触れずに書き込みをプレビューします：

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

追記専用 JSONL ログから一致するレコードを検索します：

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

Markdown 内の指示を、行番号ではなくセクションと項目で指定します：

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

スクリプトが読み取りまたは書き込みを行う前に、CI または事前確認スクリプトでパスを検証します：

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

これらのコマンドは、シェルスクリプトへコピーできるように設計されています。呼び出し元が構造化出力を必要とする場合は --json を、人が結果を確認する場合は --human を使用します。

仕組み

1. oc:// アドレスを、ファイル、セクション、項目、フィールド、オプションのセッションクエリというスロットに解析します。
2. 対象の拡張子（.md、.jsonc、.json、.jsonl、.ndjson、.yaml、.yml、.lobster）からファイル種類のアダプターを選択します。
3. そのファイル種類の構造（Markdown の見出し／項目、JSONC のオブジェクトキー／配列インデックス、JSONL の行レコード、YAML のマップ／シーケンスノード）に対してスロットを解決します。
4. set では、同じアダプターを通じて編集後のバイトを出力するため、その種類が対応している場合、ファイル内の変更されていない部分のコメント、改行コード、周辺の書式が保持されます。

resolve と set には、具体的な対象が 1 つ必要です。find は探索用の動詞です。ワイルドカード、ユニオン、述語、序数を具体的な一致へ展開し、書き込む対象を 1 つ選ぶ前に確認できます。

サブコマンド

グローバルフラグ

validate は --json／--human のみを受け取ります。ファイルシステムへアクセスしないため、--cwd と --file は適用されません。

oc:// の構文

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

スロットの規則：field には item が必要で、item には section が必要です。4 つのすべてのスロットに共通する規則：

• 引用符付きセグメント — "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} は、いずれかの選択肢に一致します。
• ワイルドカード — *（単一のサブセグメント）と **（0 個以上、再帰的）。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= 値を除いて無視されます。

ハードリミット：パスは最大 4096 バイト、最大 4 スロット（ファイル／セクション／項目／フィールド）、各スロットで最大 64 個のドット区切りサブセグメント、深い JSON パスでは最大 256 レベルの入れ子走査に制限されます。これとは別に、16 MiB を超える JSONC／JSON ファイル入力は、そのファイルを読み込むすべての動詞において、解析される代わりに解析診断とともに拒否されます。

ファイル種類別のアドレス指定

resolve は、1 始まりの行番号を含む構造化された一致（root、node、leaf、または insertion-point）を返します。Plugin 作成者が種類ごとの AST 形状に依存せずプレビューを表示できるよう、末端値はテキストと leafType として公開されます。

変更の契約

set は、具体的な対象を 1 つ書き込みます：

• Markdown の frontmatter 値と - key: value 項目フィールドは文字列の リーフです。Markdown の挿入では、セクション、frontmatter キー、またはセクション 項目を追加し、変更対象ファイルを正規化された Markdown 形式でレンダリングします。セクション 本文全体を set で書き込むことはできません。
• JSONC のリーフ書き込みでは、文字列値を既存のリーフ型 （string、有限の number、true/false、または null）に型変換します。JSONC/JSON/JSONL のリーフ置換で <value> を JSON として解析し、 文字列によるシークレット参照の省略形をオブジェクトに置き換える場合など、形状を変更できるようにするには --value-json を使用します。JSONC のオブジェクトおよび配列への挿入では、<value> を JSON として解析し、 通常のリーフ書き込みには jsonc-parser 編集パスを使用して、コメントと 周辺の書式を保持します。
• JSONL のリーフ書き込みでは、行内で JSONC と同様に型変換します。行全体の置換 および追加では、<value> を JSON として解析します。レンダリングされた JSONL は、ファイルで 優勢な LF/CRLF 改行規則を保持します（ファイル内の 改行の多数決により、ほとんどが CRLF のファイルは、少数の LF が混在していても CRLF のままです）。
• YAML のリーフ書き込みでは、既存のスカラー型（string、有限の number、true/false、または null）に型変換します。YAML の挿入では、バンドルされた yaml パッケージのドキュメント API を使用してマップ／シーケンスを更新します。パーサーエラーを含む不正な YAML ドキュメントは、変更前に parse-error で拒否されます。

正確なバイト列が重要な場合は、ユーザーに見える書き込みの前に --dry-run を使用します。JSONC と YAML の編集では、既存のドキュメントにパッチを適用するため（jsonc-parser または yaml ドキュメント API を使用）、通常、変更していないバイト列は保持されます。一方、Markdown はどの編集でも 解析済み構造からファイルを再構築するため、変更したリーフ以外の付随的な 書式が正規化されることがあります。レンダリングされたファイル全体ではなく、変更前後に絞ったパッチとして プレビューするには、--diff を追加します。

例

# パスを検証（ファイルシステムにはアクセスしない）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 # 書き込みをドライランopenclaw path set 'oc://gateway.jsonc/version' '2.0' --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

その他の文法例：

# / または . を含むキーを引用符で囲むopenclaw path resolve 'oc://config.jsonc/agents.defaults.models/"anthropic/claude-opus-4-7"/alias' # 深い JSON/JSONC パスではスラッシュ区切りを使用でき、ドット区切りのサブセグメントに正規化されるopenclaw path set 'oc://openclaw.json/agents/list/0/tools/exec/security' 'allowlist' --dry-run # JSONC のリーフを解析済みオブジェクトで置換openclaw path set 'oc://openclaw.json/gateway/auth/token' '{"source":"file","provider":"secrets","id":"/test"}' --value-json --dry-run # 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' # 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'

ファイル種別別のレシピ

同じ 5 つの動詞がすべての種別で機能し、アドレス指定方式は ファイル拡張子に応じて処理を振り分けます。

Markdown

<!-- frontmatter.md -->---name: drafterdescription: メール下書きエージェントtier: core---## ツール- gh: GitHub CLI- curl: HTTP クライアント- send_email: 有効

$ openclaw path resolve 'oc://x.md/[frontmatter]/tier' --file frontmatter.md --humanリーフ @ L4: "core"（文字列） $ openclaw path resolve 'oc://x.md/tools/gh/gh' --file frontmatter.md --humanリーフ @ L9: "GitHub CLI"（文字列） $ openclaw path find 'oc://x.md/tools/*' --file frontmatter.md --humanoc://x.md/tools/* に 3 件一致：  oc://x.md/tools/gh           →  ノード @ L9 [md-item]  oc://x.md/tools/curl         →  ノード @ L10 [md-item]  oc://x.md/tools/send-email   →  ノード @ L11 [md-item]

[frontmatter] 述語は YAML frontmatter ブロックを指定します。tools はスラッグを介して ## Tools 見出しに一致し、ソースでアンダースコアが使われていても 項目のリーフはスラッグ形式を維持します（send_email は send-email になります）。

JSONC

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

$ openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --file config.jsonc --humanリーフ @ L4: "true"（真偽値） $ openclaw path set 'oc://config.jsonc/plugins/slack/enabled' 'true' --file config.jsonc --dry-run--dry-run: /…/config.jsonc に 142 バイトを書き込む予定{  "plugins": {    "github": {"enabled": true, "role": "vcs"},    "slack":  {"enabled": true, "role": "chat"}  }}

JSONC の編集は jsonc-parser を経由するため、 set の実行後もコメントと空白が保持されます。確定する前にバイト列を確認するには、まず --dry-run を付けて実行します。 .json ファイルは、.jsonc と同じアダプターおよび編集パスを使用します。

JSONL

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

$ openclaw path find 'oc://session.jsonl/[event=action]/userId' --file session.jsonl --humanoc://session.jsonl/[event=action]/userId に 1 件一致：  oc://session.jsonl/L2/userId  →  リーフ @ L2: "u1"（文字列） $ openclaw path resolve 'oc://session.jsonl/L2/ts' --file session.jsonl --humanリーフ @ L2: "2"（数値）

各行が 1 つのレコードです。行番号が不明な場合は述語（[event=action]）で、 判明している場合は正規の LN セグメントで指定します。 .ndjson ファイルは、.jsonl と同じアダプターを使用します。

YAML

# workflow.yamlname: inbox-triagesteps:  - id: fetch    command: gmail.search  - id: classify    command: openclaw.invoke

$ openclaw path resolve 'oc://workflow.yaml/steps/0/id' --file workflow.yaml --humanリーフ @ L3: "fetch"（文字列） $ openclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --file workflow.yaml --dry-run--dry-run: /…/workflow.yaml に 99 バイトを書き込む予定name: inbox-triagesteps:  - 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 で終了します。

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

find <pattern>

ワイルドカード／述語／ユニオンパターンに一致するすべての項目を列挙します。1 件以上一致した場合は 0、 0 件の場合は 1 で終了します。ファイルスロットのワイルドカードは OC_PATH_FILE_WILDCARD_UNSUPPORTED で拒否されます。具体的なファイルを渡してください（複数ファイルの glob は今後追加予定の機能です）。

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 と組み合わせます。unified diff のプレビューには --diff を追加します。 書き込みに成功した場合は 0、基盤が拒否した場合（たとえば、 センチネルガードに該当した場合）は 1、解析エラーの場合は 2 で終了します。

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

+key 挿入マーカーは、指定された子がまだ存在しない場合に作成します。 +nnn と単独の + は、それぞれインデックス指定挿入と末尾への追加に使用できます。

validate <oc-path>

解析のみを行うチェックです。ファイルシステムにはアクセスしません。変数を置換する前に テンプレートパスの形式が正しいことを確認したい場合や、デバッグ用に 構造の内訳を確認したい場合に便利です：

$ openclaw path validate 'oc://AGENTS.md/tools/gh' --human有効: oc://AGENTS.md/tools/gh  ファイル:      AGENTS.md  セクション:    tools  項目:          gh

有効な場合は 0、無効な場合は 1（構造化された code と message を伴う）、引数エラーの場合は 2 で終了します。

emit <file>

ファイル種別ごとのパーサーとエミッターを通してファイルをラウンドトリップします。正常なファイルでは、 出力が入力とバイト単位で同一になる必要があります。差異がある場合は、 パーサーのバグまたはセンチネルへの該当を示します。実環境の入力に対する 基盤の動作をデバッグする際に便利です。

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

終了コード

出力モード

openclaw path は TTY を認識し、端末では人間が読みやすい出力を使用し、標準出力が パイプまたはリダイレクトされている場合は JSON を使用します。--json と --human は 自動検出を上書きします。

注記

• set は substrate の emit パスを通じてバイトを書き込み、このパスでは redaction-sentinel ガードが自動的に適用されます。 __OPENCLAW_REDACTED__ を含むリーフ（そのまま、または部分文字列として）は、書き込み 時に拒否されます。
• JSONC の解析とリーフの編集には Plugin ローカルの jsonc-parser 依存関係が使用されるため、通常のリーフ 書き込みでは、独自実装のパーサー／再レンダリングパスを経由せず、コメントと書式が保持されます。
• path は last-known-good（LKG）設定の追跡や復旧を認識しません。 そのライフサイクルは別の場所が所有します。path を通じて編集するファイルが LKG でも追跡されている場合、次回の設定読み取り時に、それを昇格するか 復旧するかが決定されます。path による編集は、そのファイルへの他の直接書き込みと 同様に扱ってください。

関連項目

• CLI リファレンス