openclaw path
oc:// アドレス指定方式へのシェルアクセス：アドレス指定可能なワークスペースファイル（markdown、jsonc、jsonl、yaml/yml/lobster）を検査および編集するための、種類に応じてディスパッチされる単一のパス構文です。セルフホスト運用者、Plugin 作成者、エディター拡張機能は、ファイルごとのパーサーを独自実装することなく、限定された位置の読み取り、検索、更新にこれを使用できます。
path は、同梱のオプション oc-path Plugin によって提供されます。初めて使用する前に有効化してください：
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 つの値を読み取ります：--json を、人が結果を確認する場合は --human を使用します。
仕組み
oc://アドレスを、ファイル、セクション、項目、フィールド、オプションのセッションクエリというスロットに解析します。- 対象の拡張子（
.md、.jsonc、.json、.jsonl、.ndjson、.yaml、.yml、.lobster）からファイル種類のアダプターを選択します。 - そのファイル種類の構造（Markdown の見出し／項目、JSONC のオブジェクトキー／配列インデックス、JSONL の行レコード、YAML のマップ／シーケンスノード）に対してスロットを解決します。
setでは、同じアダプターを通じて編集後のバイトを出力するため、その種類が対応している場合、ファイル内の変更されていない部分のコメント、改行コード、周辺の書式が保持されます。
resolve と set には、具体的な対象が 1 つ必要です。find は探索用の動詞です。ワイルドカード、ユニオン、述語、序数を具体的な一致へ展開し、書き込む対象を 1 つ選ぶ前に確認できます。
サブコマンド
グローバルフラグ
validate は --json／--human のみを受け取ります。ファイルシステムへアクセスしないため、--cwd と --file は適用されません。
oc:// の構文
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 を追加します。
例
ファイル種別別のレシピ
同じ 5 つの動詞がすべての種別で機能し、アドレス指定方式は ファイル拡張子に応じて処理を振り分けます。Markdown
[frontmatter] 述語は YAML frontmatter ブロックを指定します。tools
はスラッグを介して ## Tools 見出しに一致し、ソースでアンダースコアが使われていても
項目のリーフはスラッグ形式を維持します（send_email は send-email になります）。
JSONC
jsonc-parser を経由するため、
set の実行後もコメントと空白が保持されます。確定する前にバイト列を確認するには、まず --dry-run を付けて実行します。
.json ファイルは、.jsonc と同じアダプターおよび編集パスを使用します。
JSONL
[event=action]）で、
判明している場合は正規の LN セグメントで指定します。
.ndjson ファイルは、.jsonl と同じアダプターを使用します。
YAML
yaml パッケージの Document API を使用します。
そのため、通常の解析／出力ラウンドトリップではコメントと記述形式が保持され、
解決済みパスでは JSONC と同じマップキー／シーケンスインデックスモデルが使用されます。
同じアダプターが .yaml、.yml、および .lobster ファイルを処理します。
サブコマンドリファレンス
resolve <oc-path>
単一のリーフまたはノードを読み取ります。ワイルドカードは拒否されます。その場合は find を使用してください。
一致した場合は 0、正常に一致しなかった場合は 1、解析エラーまたは拒否された
パターンの場合は 2 で終了します。
find <pattern>
ワイルドカード／述語／ユニオンパターンに一致するすべての項目を列挙します。1 件以上一致した場合は 0、
0 件の場合は 1 で終了します。ファイルスロットのワイルドカードは
OC_PATH_FILE_WILDCARD_UNSUPPORTED で拒否されます。具体的なファイルを渡してください（複数ファイルの
glob は今後追加予定の機能です）。
set <oc-path> <value>
リーフを書き込みます。ファイルに触れずに書き込まれるバイト列をプレビューするには、
--dry-run と組み合わせます。unified diff のプレビューには --diff を追加します。
書き込みに成功した場合は 0、基盤が拒否した場合（たとえば、
センチネルガードに該当した場合）は 1、解析エラーの場合は 2 で終了します。
+key 挿入マーカーは、指定された子がまだ存在しない場合に作成します。
+nnn と単独の + は、それぞれインデックス指定挿入と末尾への追加に使用できます。
validate <oc-path>
解析のみを行うチェックです。ファイルシステムにはアクセスしません。変数を置換する前に
テンプレートパスの形式が正しいことを確認したい場合や、デバッグ用に
構造の内訳を確認したい場合に便利です：
0、無効な場合は 1（構造化された code と
message を伴う）、引数エラーの場合は 2 で終了します。
emit <file>
ファイル種別ごとのパーサーとエミッターを通してファイルをラウンドトリップします。正常なファイルでは、
出力が入力とバイト単位で同一になる必要があります。差異がある場合は、
パーサーのバグまたはセンチネルへの該当を示します。実環境の入力に対する
基盤の動作をデバッグする際に便利です。
終了コード
出力モード
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による編集は、そのファイルへの他の直接書き込みと 同様に扱ってください。