---
read_when:
    - می‌خواهید از ترمینال یک برگ را درون فایلی در فضای کاری بخوانید یا بنویسید
    - در حال اسکریپت‌نویسی بر اساس وضعیت فضای کاری هستید و یک طرح آدرس‌دهی پایدار و مستقل از نوع می‌خواهید
    - در حال اشکال‌زدایی یک مسیر `oc://` هستید (درستی نحو را بررسی کنید و ببینید به چه چیزی resolve می‌شود)
summary: مرجع CLI برای `openclaw path` (بررسی و ویرایش فایل‌های فضای کاری از طریق طرح آدرس‌دهی `oc://`)
title: مسیر
x-i18n:
    generated_at: "2026-07-27T16:20:36Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 7afe5bd1c3a5fca8dd22c7d807e390e751ae7e895c54bf0e10e2734f3889436c
    source_path: cli/path.md
    workflow: 16
---

# `openclaw path`

دسترسی پوسته به طرح آدرس‌دهی `oc://`: نحو مسیر واحدی که بر اساس نوع توزیع می‌شود
برای بازرسی و ویرایش فایل‌های قابل‌آدرس‌دهی فضای کاری (markdown، jsonc،
jsonl، yaml/yml/lobster). میزبان‌های شخصی، نویسندگان Plugin و افزونه‌های ویرایشگر
از آن برای خواندن، یافتن یا به‌روزرسانی مکانی محدود، بدون نوشتن دستی
تجزیه‌گر جداگانه برای هر فایل، استفاده می‌کنند.

`path` توسط Plugin اختیاری همراهِ `oc-path` ارائه می‌شود. پیش از
نخستین استفاده آن را فعال کنید:

```bash
openclaw plugins enable oc-path
```

افعال CLI از مدل آدرس‌دهی پیروی می‌کنند:

- `resolve` مشخص است و تنها یک تطابق دارد.
- `find` فعل چندتطابقی برای نویسه‌های عام، اجتماع‌ها، گزاره‌ها و
  بسط موقعیتی است.
- `set` فقط مسیرهای مشخص یا نشانگرهای درج را می‌پذیرد؛ الگوهای دارای نویسه عام
  پیش از نوشتن رد می‌شوند.
- `validate` مسیر را بدون دسترسی به سیستم فایل تجزیه می‌کند.
- `emit` فایل را از چرخه تجزیه + تولید عبور می‌دهد (عیب‌یابی وفاداری بایتی).

## چرا از آن استفاده کنیم

وضعیت OpenClaw میان markdown ویرایش‌شده توسط انسان، پیکربندی JSONC
دارای توضیحات، گزارش‌های JSONL فقط‌افزودنی و فایل‌های گردش‌کار/مشخصات YAML پراکنده است. اسکریپت‌ها، هوک‌ها
و عامل‌ها اغلب به یک مقدار کوچک از این فایل‌ها نیاز دارند: کلید frontmatter، یک
تنظیم Plugin، فیلد رکورد گزارش، گام YAML یا مورد گلوله‌ای زیر یک
بخش نام‌گذاری‌شده.

`openclaw path` به‌جای grep، عبارت منظم یا تجزیه‌گر موردی برای هر نوع فایل،
آدرسی پایدار در اختیار این فراخواننده‌ها می‌گذارد. همان مسیر `oc://` را می‌توان از ترمینال
اعتبارسنجی، تفکیک، جست‌وجو، اجرای آزمایشی و ثبت کرد؛ در نتیجه خودکارسازی محدود،
قابل‌بازبینی و قابل‌بازتکرار می‌ماند. بقیه فایل حفظ می‌شود، بنابراین
نوشتن یک برگ، توضیحات، پایان خط‌ها یا قالب‌بندی مجاور آن را
برهم نمی‌زند.

وقتی چیزی که می‌خواهید آدرس منطقی دارد اما شکل فایل
متفاوت است، از آن استفاده کنید:

- یک هوک، تنظیمی را از JSONC دارای توضیحات می‌خواند، بدون اینکه هنگام
  بازنویسی مقدار، توضیحات از بین بروند.
- یک اسکریپت نگه‌داری، همه فیلدهای رویداد منطبق را در گزارش JSONL
  بدون بارگذاری کل گزارش در یک تجزیه‌گر سفارشی پیدا می‌کند.
- یک ویرایشگر با استفاده از slug به بخش یا مورد گلوله‌ای markdown می‌رود، سپس
  دقیقاً خطی را که تفکیک کرده است نمایش می‌دهد.
- یک عامل، ویرایش کوچک فضای کاری را پیش از اعمال به‌صورت آزمایشی اجرا می‌کند و
  بایت‌های تغییریافته در بازبینی قابل‌مشاهده‌اند.

برای ویرایش‌های عادی کل فایل، مهاجرت‌های پیکربندی غنی یا
نوشتن‌های مختص حافظه از `openclaw path` صرف‌نظر کنید؛ این موارد باید از فرمان یا Plugin مالک استفاده کنند. `path`
برای عملیات کوچک و قابل‌آدرس‌دهی فایل است که در آن یک فرمان تکرارپذیر ترمینال
از تجزیه‌گر سفارشی دیگری بهتر است.

## نحوه استفاده

خواندن یک مقدار از فایل پیکربندی ویرایش‌شده توسط انسان:

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

پیش‌نمایش نوشتن بدون دست‌زدن به دیسک:

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

یافتن رکوردهای منطبق در گزارش JSONL فقط‌افزودنی:

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

آدرس‌دهی یک دستورالعمل در markdown بر اساس بخش و مورد، به‌جای شماره
خط:

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

اعتبارسنجی مسیر در CI یا اسکریپت پیش‌بررسی، پیش از اینکه اسکریپت بخواند یا
بنویسد:

```bash
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` به یک هدف مشخص نیاز دارند. `find` فعل اکتشافی
است: نویسه‌های عام، اجتماع‌ها، گزاره‌ها و ترتیب‌ها را به تطابق‌های مشخص
گسترش می‌دهد تا پیش از انتخاب یکی برای نوشتن، آن‌ها را بررسی کنید.

## زیرفرمان‌ها

| زیرفرمان              | هدف                                                                     |
| ----------------------- | --------------------------------------------------------------------------- |
| `resolve <oc-path>`     | تطابق مشخص در مسیر را چاپ می‌کند (یا «یافت نشد»).                      |
| `find <pattern>`        | تطابق‌های مسیر دارای نویسه عام / اجتماع / گزاره را فهرست می‌کند.                  |
| `set <oc-path> <value>` | یک برگ یا هدف درج را در مسیری مشخص می‌نویسد. از `--dry-run` پشتیبانی می‌کند.  |
| `validate <oc-path>`    | فقط تجزیه؛ تفکیک ساختاری را چاپ می‌کند (فایل / بخش / مورد / فیلد). |
| `emit <file>`           | فایل را از چرخه تجزیه + تولید عبور می‌دهد (عیب‌یابی وفاداری بایتی).          |

## پرچم‌های سراسری

| پرچم            | کاربرد برای                       | هدف                                                                  |
| --------------- | -------------------------------- | ------------------------------------------------------------------------ |
| `--cwd <dir>`   | `resolve`، `find`، `set`، `emit` | جایگاه فایل را نسبت به این پوشه تفکیک می‌کند (پیش‌فرض: `process.cwd()`). |
| `--file <path>` | `resolve`، `find`، `set`، `emit` | مسیر تفکیک‌شده جایگاه فایل را بازنویسی می‌کند (دسترسی مطلق).                |
| `--json`        | همه                              | خروجی JSON را اجباری می‌کند (وقتی stdout یک TTY نیست، پیش‌فرض است).                    |
| `--human`       | همه                              | خروجی خوانا برای انسان را اجباری می‌کند (وقتی stdout یک TTY است، پیش‌فرض است).                       |
| `--value-json`  | `set`                            | برای جایگزینی برگ JSON/JSONC/JSONL، `<value>` را به‌عنوان JSON تجزیه می‌کند.           |
| `--dry-run`     | `set`                            | بایت‌هایی را که قرار بود نوشته شوند، بدون نوشتن چاپ می‌کند.                   |
| `--diff`        | `set` (نیازمند `--dry-run`)     | به‌جای تمام بایت‌ها، diff یکپارچه را چاپ می‌کند.                          |

`validate` فقط `--json` / `--human` را می‌پذیرد؛ هیچ دسترسی به سیستم فایل ندارد، بنابراین
`--cwd` و `--file` کاربرد ندارند.

## نحو `oc://`

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

قواعد جایگاه‌ها: `field` به `item` نیاز دارد و `item` به `section`. در هر
چهار جایگاه:

- **قطعه‌های نقل‌قول‌شده** — `"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}` با هر یک از گزینه‌ها تطابق دارد.
- **نویسه‌های عام** — `*` (یک زیرقطعه) و `**` (صفر یا بیشتر،
  بازگشتی). `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 زیرقطعه نقطه‌ای در هر جایگاه و حداکثر 256
سطح پیمایش تودرتو برای مسیرهای عمیق JSON دارد. جدا از این موارد، هر ورودی فایل JSONC/JSON
بزرگ‌تر از 16 MiB، برای هر فعلی که آن فایل را بارگذاری می‌کند، به‌جای تجزیه‌شدن
با یک پیام عیب‌یابی تجزیه رد می‌شود.

## آدرس‌دهی بر اساس نوع فایل

| نوع          | پسوندهای فایل             | مدل آدرس‌دهی                                                                                    |
| ------------- | --------------------------- | --------------------------------------------------------------------------------------------------- |
| Markdown      | `.md`                       | بخش‌های H2 بر اساس slug، موارد گلوله‌ای بر اساس slug یا `#N`، و frontmatter از طریق `[frontmatter]`.                 |
| JSONC/JSON    | `.jsonc`، `.json`           | کلیدهای شیء و نمایه‌های آرایه؛ نقطه‌ها زیرقطعه‌های تودرتو را جدا می‌کنند، مگر اینکه نقل‌قول شده باشند.                        |
| JSONL         | `.jsonl`، `.ndjson`         | آدرس‌های خط سطح‌بالا (`L1`، `L2`، `$first`، `$last`)، سپس پیمایش به سبک JSONC درون خط. |
| YAML/.lobster | `.yaml`، `.yml`، `.lobster` | کلیدهای نگاشت و نمایه‌های دنباله؛ توضیحات و سبک جریان توسط API سند YAML مدیریت می‌شوند.        |

`resolve` یک تطابق ساخت‌یافته برمی‌گرداند: `root`، `node`، `leaf` یا
`insertion-point`، همراه با شماره خط مبتنی بر 1. مقادیر برگ به‌صورت
متن به‌همراه یک `leafType` ارائه می‌شوند تا نویسندگان Plugin بتوانند بدون
وابستگی به شکل AST مخصوص هر نوع، پیش‌نمایش‌ها را نمایش دهند.

## قرارداد تغییر

`set` یک هدف مشخص را می‌نویسد:

- مقادیر frontmatter در Markdown و فیلدهای آیتم `- key: value` برگ‌های رشته‌ای
  هستند. درج‌های Markdown بخش‌ها، کلیدهای frontmatter یا آیتم‌های بخش را اضافه
  می‌کنند و برای فایل تغییریافته، ساختار استاندارد Markdown را رندر می‌کنند. بدنه‌های
  بخش را نمی‌توان به‌طور کامل از طریق `set` نوشت.
- نوشتن برگ در JSONC، مقدار رشته‌ای را به نوع برگ موجود تبدیل می‌کند
  (`string`، `number` متناهی، `true`/`false` یا `null`). زمانی از `--value-json`
  استفاده کنید که جایگزینی یک برگ JSONC/JSON/JSONL باید `<value>` را به‌عنوان JSON تجزیه کند و
  ممکن است ساختار را تغییر دهد؛ مانند جایگزینی شکل کوتاه رشته‌ای ارجاع به secret با یک
  شیء. درج‌های شیء و آرایه در JSONC، `<value>` را به‌عنوان JSON تجزیه می‌کنند و برای
  نوشتن برگ‌های معمولی از مسیر ویرایش `jsonc-parser` استفاده می‌کنند و توضیحات
  و قالب‌بندی مجاور را حفظ می‌کنند.
- نوشتن برگ در JSONL، درون هر خط مانند JSONC تبدیل نوع انجام می‌دهد. جایگزینی
  کل خط و افزودن، `<value>` را به‌عنوان JSON تجزیه می‌کنند. JSONL رندرشده، قرارداد غالب
  پایان خط LF/CRLF فایل را حفظ می‌کند (با رأی اکثریت میان نویسه‌های
  خط جدید فایل؛ بنابراین فایلی که عمدتاً CRLF است، حتی با چند LF پراکنده CRLF باقی می‌ماند).
- نوشتن برگ در YAML، مقدار را به نوع اسکالر موجود تبدیل می‌کند (`string`،
  `number` متناهی، `true`/`false` یا `null`). درج‌های YAML برای به‌روزرسانی نگاشت/دنباله از API سند
  بسته همراه `yaml` استفاده می‌کنند. سندهای YAML معیوب دارای خطای تجزیه،
  پیش از تغییر با `parse-error` رد می‌شوند.

هنگامی که بایت‌های دقیق اهمیت دارند، پیش از نوشتن‌های قابل‌مشاهده برای کاربر از `--dry-run` استفاده کنید. ویرایش‌های JSONC
و YAML سند موجود را وصله می‌کنند (از طریق `jsonc-parser` یا API سند `yaml`)؛
بنابراین بایت‌های دست‌نخورده معمولاً باقی می‌مانند؛ Markdown در هر ویرایش، فایل را
از ساختار تجزیه‌شده آن بازسازی می‌کند که ممکن است قالب‌بندی فرعی خارج از برگ
تغییریافته را استاندارد کند. اگر می‌خواهید پیش‌نمایش به‌جای کل فایل رندرشده،
وصله‌ای متمرکز از قبل/بعد باشد، `--diff` را اضافه کنید.

## مثال‌ها

```bash
# اعتبارسنجی یک مسیر (بدون دسترسی به سیستم فایل)
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

# اجرای آزمایشی یک نوشتن به‌شکل 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
```

مثال‌های بیشتر از دستور زبان:

```bash
# کلیدهای حاوی / یا . را داخل نقل‌قول قرار دهید
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

# آدرس‌دهی frontmatter در Markdown
openclaw path resolve 'oc://AGENTS.md/[frontmatter]/name'

# درج frontmatter در Markdown
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'
```

## دستورالعمل‌ها بر اساس نوع فایل

همان پنج فعل در همه نوع‌ها کار می‌کنند؛ طرح آدرس‌دهی بر اساس
پسوند فایل مسیردهی می‌کند.

### Markdown

```text
<!-- frontmatter.md -->
---
name: drafter
description: عامل پیش‌نویس ایمیل
tier: core
---
## ابزارها
- gh: GitHub CLI
- curl: کلاینت HTTP
- send_email: فعال
```

```bash
$ 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 --human
3 تطابق برای oc://x.md/tools/*:
  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]` بلوک frontmatter در YAML را آدرس‌دهی می‌کند؛ `tools`
از طریق slug با عنوان `## Tools` تطابق می‌یابد و برگ‌های آیتم حتی زمانی که
منبع از زیرخط استفاده می‌کند، شکل slug خود را حفظ می‌کنند (`send_email` به `send-email` تبدیل می‌شود).

### JSONC

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

```bash
$ 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: مقدار 142 بایت در /…/config.jsonc نوشته می‌شد
{
  "plugins": {
    "github": {"enabled": true, "role": "vcs"},
    "slack":  {"enabled": true, "role": "chat"}
  }
}
```

ویرایش‌های JSONC از `jsonc-parser` عبور می‌کنند؛ بنابراین توضیحات و فاصله‌های سفید در یک
`set` حفظ می‌شوند. ابتدا با `--dry-run` اجرا کنید تا بایت‌ها را پیش از ثبت بررسی کنید.
فایل‌های `.json` از همان آداپتور و مسیر ویرایش `.jsonc` استفاده می‌کنند.

### JSONL

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

```bash
$ openclaw path find 'oc://session.jsonl/[event=action]/userId' --file session.jsonl --human
1 تطابق برای oc://session.jsonl/[event=action]/userId:
  oc://session.jsonl/L2/userId  →  برگ @ L2: "u1" (رشته)

$ openclaw path resolve 'oc://session.jsonl/L2/ts' --file session.jsonl --human
برگ @ L2: "2" (عدد)
```

هر خط یک رکورد است. زمانی که شماره خط را نمی‌دانید، با محمول (`[event=action]`)
آدرس‌دهی کنید؛ در غیر این صورت از قطعه استاندارد `LN` استفاده کنید.
فایل‌های `.ndjson` از همان آداپتور `.jsonl` استفاده می‌کنند.

### YAML

```text
# workflow.yaml
name: inbox-triage
steps:
  - id: fetch
    command: gmail.search
  - id: classify
    command: openclaw.invoke
```

```bash
$ 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: مقدار 99 بایت در /…/workflow.yaml نوشته می‌شد
name: inbox-triage
steps:
  - id: fetch
    command: gmail.search
  - id: classify-renamed
    command: openclaw.invoke
```

YAML به‌جای تجزیه‌گر دست‌ساز، از API `Document` بسته `yaml` استفاده می‌کند؛
بنابراین رفت‌وبرگشت‌های معمول تجزیه/تولید، توضیحات و ساختار تألیف را حفظ می‌کنند،
درحالی‌که مسیرهای واکشی‌شده از همان مدل کلید نگاشت / نمایه دنباله JSONC استفاده می‌کنند.
همان آداپتور فایل‌های `.yaml`، `.yml` و `.lobster` را مدیریت می‌کند.

## مرجع زیرفرمان‌ها

### `resolve <oc-path>`

خواندن یک برگ یا گره منفرد. نویسه‌های عام رد می‌شوند — برای آن‌ها از `find` استفاده کنید.
در صورت تطابق با `0`، در صورت عدم تطابق بدون خطا با `1` و در صورت خطای تجزیه یا الگوی
ردشده با `2` خارج می‌شود.

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

### `find <pattern>`

تمام تطابق‌ها را برای یک الگوی نویسه عام / محمول / اجتماع فهرست می‌کند. در صورت وجود
حداقل یک تطابق با `0` و در صورت نبود تطابق با `1` خارج می‌شود. نویسه‌های عام جایگاه فایل با
`OC_PATH_FILE_WILDCARD_UNSUPPORTED` رد می‌شوند — یک فایل مشخص ارائه کنید (glob چندفایلی
قابلیتی برای آینده است).

```bash
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` همراه کنید تا بدون تغییر فایل، بایت‌هایی را
که نوشته می‌شدند پیش‌نمایش کنید. برای پیش‌نمایش diff یکپارچه، `--diff` را اضافه کنید.
در صورت نوشتن موفق با `0`، اگر زیرلایه آن را رد کند (برای مثال،
فعال‌شدن محافظ sentinel) با `1` و در صورت خطای تجزیه با `2` خارج می‌شود.

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

نشانگر درج `+key`، اگر فرزند نام‌گذاری‌شده از قبل وجود نداشته باشد آن را ایجاد می‌کند؛
`+nnn` و `+` بدون پیرایه، به‌ترتیب برای درج نمایه‌دار و افزودن کار می‌کنند.

### `validate <oc-path>`

بررسی فقط برای تجزیه. بدون دسترسی به سیستم فایل. زمانی مفید است که بخواهید پیش از
جایگزینی متغیرها، خوش‌ساخت‌بودن یک مسیر الگو را تأیید کنید یا برای اشکال‌زدایی
تفکیک ساختاری را ببینید:

```bash
$ 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>`

یک فایل را از تجزیه‌گر و تولیدکننده مخصوص نوع آن به‌صورت رفت‌وبرگشتی عبور می‌دهد. در یک
فایل سالم، خروجی باید از نظر بایتی با ورودی یکسان باشد؛ تفاوت نشان‌دهنده
اشکال تجزیه‌گر یا فعال‌شدن sentinel است. برای اشکال‌زدایی رفتار زیرلایه روی
ورودی‌های واقعی مفید است.

```bash
openclaw path emit ./AGENTS.md
openclaw path emit ./gateway.jsonc --json
```

## کدهای خروج

| کد | معنا                                                                    |
| ---- | -------------------------------------------------------------------------- |
| `0`  | موفقیت. (`resolve` / `find`: حداقل یک تطابق. `set`: نوشتن موفق بود.) |
| `1`  | بدون تطابق، یا `set` توسط زیرلایه رد شد (بدون خطای سطح سیستم).      |
| `2`  | خطای آرگومان یا تجزیه.                                                   |

## حالت خروجی

`openclaw path` از TTY آگاه است: خروجی خوانا برای انسان در ترمینال و JSON زمانی که
stdout به پایپ یا تغییرمسیر فرستاده شده باشد. `--json` و `--human`
تشخیص خودکار را لغو می‌کنند.

## یادداشت‌ها

- `set` بایت‌ها را از طریق مسیر emit زیرلایه می‌نویسد که محافظ redaction-sentinel را به‌طور خودکار اعمال می‌کند. یک برگ حاوی
  `__OPENCLAW_REDACTED__` (به‌صورت عین‌به‌عین یا به‌عنوان زیررشته) هنگام نوشتن
  رد می‌شود.
- تجزیهٔ JSONC و ویرایش برگ‌ها از وابستگی محلی Plugin یعنی `jsonc-parser`
  استفاده می‌کنند؛ بنابراین در نوشتن‌های معمولی برگ، توضیحات و قالب‌بندی
  حفظ می‌شوند و عملیات از مسیر تجزیه‌گر/بازرندر دست‌ساز عبور نمی‌کند.
- `path` از ردیابی یا بازیابی پیکربندی آخرین وضعیت سالم (LKG) آگاه نیست؛
  مالکیت این چرخهٔ حیات در جای دیگری است. اگر فایلی که از طریق `path` ویرایش می‌کنید
  نیز تحت ردیابی LKG باشد، خواندن بعدی پیکربندی تعیین می‌کند که آن را ارتقا دهد یا
  بازیابی کند؛ با ویرایش `path` همانند هر نوشتن مستقیم دیگری در
  آن فایل رفتار کنید.

## مرتبط

- [مرجع CLI](/fa/cli)
