---
read_when:
    - می‌خواهید یک برگ منفرد را درون یک فایل فضای کاری از طریق ترمینال بررسی یا ویرایش کنید
    - شما در حال اسکریپت‌نویسی برای کار با وضعیت فضای کاری هستید و به یک طرح آدرس‌دهی پایدار و مستقل از نوع نیاز دارید
    - شما در حال تصمیم‌گیری هستید که آیا Plugin اختیاری `oc-path` را روی یک Gateway خودمیزبان فعال کنید یا خیر
summary: 'Plugin همراه `oc-path`: CLI ‏`openclaw path` را برای طرح آدرس‌دهی فایل‌های فضای کاری `oc://` ارائه می‌کند'
title: Plugin مسیر OC
x-i18n:
    generated_at: "2026-07-12T10:27:35Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: eb7bb1aacd37e5cc9c391372b871dc519f4048232d93a0016138ae00a6985a59
    source_path: plugins/oc-path.md
    workflow: 16
---

Plugin همراه `oc-path`، CLI مربوط به [`openclaw path`](/fa/cli/path) را برای
طرح آدرس‌دهی فایل‌های فضای کاری با `oc://` اضافه می‌کند. این Plugin در مخزن OpenClaw و در
`extensions/oc-path/` ارائه می‌شود، اما استفاده از آن اختیاری است: پس از نصب/ساخت، تا زمانی که
آن را فعال نکنید غیرفعال باقی می‌ماند.

آدرس‌های `oc://` به یک برگ منفرد (یا مجموعه‌ای از برگ‌ها با نویسهٔ عام) درون
یک فایل فضای کاری اشاره می‌کنند. این Plugin چهار نوع فایل را می‌شناسد:

- **مارک‌داون** (`.md`): فرادادهٔ ابتدایی، بخش‌ها، موارد، فیلدها
- **JSONC** (`.jsonc`، `.json`): با حفظ توضیحات و قالب‌بندی
- **JSONL** (`.jsonl`، `.ndjson`): رکوردهای خط‌محور
- **YAML** (`.yaml`، `.yml`، `.lobster`): گره‌های نگاشت/دنباله/مقدار اسکالر از طریق
  API مربوط به `Document` در بستهٔ `yaml`

میزبان‌های مستقل و افزونه‌های ویرایشگر از CLI استفاده می‌کنند تا یک برگ منفرد را
بدون اسکریپت‌نویسی مستقیم بر پایهٔ SDK بخوانند یا بنویسند؛ عامل‌ها و هوک‌ها نیز آن را
به‌عنوان بستری قطعی به کار می‌گیرند تا رفت‌وبرگشت‌های وفادار به بایت و محافظ
نشانگر سانسور، به‌طور یکنواخت برای همهٔ انواع اعمال شوند. برای دستور زبان کامل،
فهرست گزینه‌های هر فعل و مثال‌های عملی برای هر نوع فایل، به
[مرجع CLI](/fa/cli/path) مراجعه کنید؛ این صفحه چرایی و چگونگی فعال‌سازی این
Plugin را توضیح می‌دهد.

## چرا آن را فعال کنیم

زمانی `oc-path` را فعال کنید که اسکریپت‌ها، هوک‌ها یا ابزارهای محلی عامل باید بدون
یک تجزیه‌گر اختصاصی برای هر ساختار فایل، به بخش دقیقی از وضعیت فضای کاری اشاره کنند. یک
آدرس `oc://` می‌تواند کلید فرادادهٔ ابتدایی مارک‌داون، یک مورد از بخش، یک
برگ پیکربندی JSONC، فیلد رویداد JSONL یا گامی از گردش کار YAML را مشخص کند.

این قابلیت برای گردش‌کارهای نگه‌داری اهمیت دارد که در آن‌ها تغییر باید کوچک،
قابل ممیزی و تکرارپذیر باقی بماند: یک مقدار را بررسی کنید، رکوردهای منطبق را بیابید، اجرای آزمایشی
نوشتن را انجام دهید و سپس فقط همان برگ را اعمال کنید، بی‌آنکه توضیحات، پایان خطوط و
قالب‌بندی مجاور تغییر کنند.

دلایل رایج برای فعال‌سازی آن:

- **خودکارسازی محلی**: اسکریپت‌های پوسته با `openclaw path … --json` یک مقدار
  فضای کاری را واکشی یا به‌روزرسانی می‌کنند، به‌جای آنکه کدهای تجزیهٔ جداگانه‌ای برای مارک‌داون، JSONC،
  JSONL و YAML داشته باشند.
- **ویرایش‌های قابل مشاهده برای عامل**: عامل پیش از نوشتن، تفاوت اجرای آزمایشی یک
  برگ آدرس‌دهی‌شده را نمایش می‌دهد که بررسی آن از بازنویسی آزادانهٔ فایل
  آسان‌تر است.
- **یکپارچه‌سازی با ویرایشگر**: ویرایشگر `oc://AGENTS.md/tools/gh` را بدون
  حدس‌زدن بر اساس متن عنوان، به گره و شماره‌خط دقیق مارک‌داون نگاشت می‌کند.
- **عیب‌یابی**: `emit` فایل را از تجزیه‌گر و مولد خروجی رفت‌وبرگشت می‌دهد،
  بنابراین می‌توانید پیش از اتکا به ویرایش‌های خودکار بررسی کنید که آیا یک نوع فایل
  از نظر بایتی پایدار است یا نه.

```bash
# آیا Plugin مربوط به GitHub در این پیکربندی فعال است؟
openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json

# چه نام‌هایی از فراخوانی ابزار در این گزارش نشست ظاهر می‌شوند؟
openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json

# این ویرایش کوچک پیکربندی چه بایت‌هایی می‌نویسد؟
openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run
```

`oc-path` عمداً مالک معناشناسی سطح بالاتر نیست. Pluginهای حافظه همچنان مالک
نوشتن در حافظه هستند، فرمان‌های پیکربندی همچنان مدیریت کامل پیکربندی را بر عهده دارند
و بازیابی آخرین پیکربندی سالم (LKG) همچنان مالک بازیابی/ارتقا است.
`oc-path` لایهٔ محدود عملیات فایل با آدرس‌دهی دقیق و حفظ بایت است که ابزارهای
سطح بالاتر می‌توانند پیرامون آن ساخته شوند.

## محل اجرا

این Plugin به‌صورت **درون‌فرایندی داخل CLI مربوط به `openclaw`** و روی میزبانی اجرا می‌شود که
فرمان را در آن فراخوانی می‌کنید. به Gateway در حال اجرا نیاز ندارد و هیچ
سوکت شبکه‌ای باز نمی‌کند؛ هر فعل، تبدیلی خالص روی فایلی است که به آن اشاره می‌کنید.

فرادادهٔ Plugin در `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` این Plugin را خارج از مسیر راه‌اندازی Gateway نگه می‌دارد.
`commandAliases` و `activation.onCommands` به CLI می‌گویند که نخستین بار که
`openclaw path …` را اجرا می‌کنید، Plugin را به‌صورت تنبل بارگیری کند؛ بنابراین نصب‌هایی که هرگز از
این فعل استفاده نمی‌کنند، هزینه‌ای نمی‌پردازند.

## فعال‌سازی

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

Gateway را، اگر اجرا می‌کنید، راه‌اندازی مجدد کنید تا تصویر لحظه‌ای مانیفست وضعیت جدید را
دریافت کند. فراخوانی‌های مستقیم `openclaw path` روی همان میزبان بلافاصله کار می‌کنند؛
CLI این Plugin را هنگام نیاز بارگیری می‌کند.

برای غیرفعال‌سازی:

```bash
openclaw plugins disable oc-path
```

## وابستگی‌ها

همهٔ وابستگی‌های تجزیه‌گر مختص Plugin هستند؛ فعال‌سازی `oc-path` هیچ بستهٔ
جدیدی را وارد زمان اجرای هسته نمی‌کند:

| وابستگی       | کاربرد                                                                      |
| -------------- | -------------------------------------------------------------------------- |
| `commander`    | سیم‌کشی زیرفرمان‌ها برای `resolve`، `find`، `set`، `validate` و `emit`.     |
| `jsonc-parser` | تجزیهٔ JSONC و ویرایش برگ‌ها با حفظ توضیحات و ویرگول‌های پایانی.           |
| `markdown-it`  | توکن‌سازی مارک‌داون برای مدل بخش / مورد / فیلد.                            |
| `yaml`         | تجزیه / تولید / ویرایش `Document` در YAML با حفظ توضیحات و سبک جریانی.     |

JSONL همچنان به‌صورت دستی پیاده‌سازی شده است: تجزیهٔ خط‌محور از هر
وابستگی‌ای ساده‌تر است و تجزیهٔ هر خط نیز از `jsonc-parser` عبور می‌کند.

## قابلیت‌های ارائه‌شده

| سطح                           | ارائه‌شده توسط                                          |
| ----------------------------- | ------------------------------------------------------- |
| CLI مربوط به `openclaw path`  | `extensions/oc-path/cli-registration.ts`                |
| تجزیه‌گر / قالب‌بند `oc://`   | `extensions/oc-path/src/oc-path/oc-path.ts`             |
| تجزیه / تولید / ویرایش هر نوع | `extensions/oc-path/src/oc-path/{md,jsonc,jsonl,yaml}`  |
| واکشی / جست‌وجو / تنظیم عمومی | `extensions/oc-path/src/oc-path/{resolve,find,edit}.ts` |
| محافظ نشانگر سانسور           | `extensions/oc-path/src/oc-path/sentinel.ts`            |

در حال حاضر CLI تنها سطح عمومی است. فعل‌های بستر، خصوصیِ
Plugin هستند؛ مصرف‌کنندگان از CLI استفاده می‌کنند یا Plugin خود را بر پایهٔ
SDK می‌سازند.

## ارتباط با دیگر Pluginها

- **`memory-*`**: نوشتن در حافظه از طریق Pluginهای حافظه انجام می‌شود، نه
  `oc-path`. `oc-path` بستری عمومی برای فایل است؛ Pluginهای حافظه
  معناشناسی خود را روی آن لایه‌بندی می‌کنند.
- **LKG**: `path` از بازیابی آخرین پیکربندی سالم آگاهی ندارد. اگر
  فایلی که از طریق `path` ویرایش می‌کنید تحت ردیابی LKG نیز باشد، چرخهٔ بعدی مشاهدهٔ
  پیکربندی تصمیم می‌گیرد که آن را ارتقا دهد یا بازیابی کند؛ با ویرایش `path`
  همانند هر نوشتن مستقیم دیگری در آن فایل رفتار کنید.

## ایمنی

`set` بایت‌های خام را از طریق مسیر تولید خروجی بستر می‌نویسد که محافظ
نشانگر سانسور را به‌صورت خودکار اعمال می‌کند. نوشتن برگی که شامل
`__OPENCLAW_REDACTED__` باشد، چه عیناً و چه به‌صورت زیررشته، هنگام نوشتن
با `OC_EMIT_SENTINEL` رد می‌شود. CLI همچنین نشانگر لفظی را از هر
خروجی انسانی یا JSON که چاپ می‌کند پاک می‌کند و آن را با `[REDACTED]` جایگزین می‌کند تا
ضبط‌های ترمینال و خط‌های لوله هرگز این نشانگر را افشا نکنند.

## مرتبط

- [مرجع CLI مربوط به `openclaw path`](/fa/cli/path)
- [مدیریت Pluginها](/fa/plugins/manage-plugins)
- [ساخت Pluginها](/fa/plugins/building-plugins)