---
read_when:
    - تريد قراءة قيمة طرفية أو كتابتها داخل ملف مساحة عمل من الطرفية
    - أنت تكتب برنامجًا نصيًا يتعامل مع حالة مساحة العمل وتريد مخطط عنونة مستقرًا لا يعتمد على النوع
    - أنت تصحّح أخطاء مسار `oc://` (تحقّق من صحة الصياغة، وانظر إلى المسار الذي يُحلّ إليه)
summary: مرجع CLI لـ `openclaw path` (فحص ملفات مساحة العمل وتحريرها عبر مخطط العنونة `oc://`)
title: المسار
x-i18n:
    generated_at: "2026-07-12T05:46:55Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 7afe5bd1c3a5fca8dd22c7d807e390e751ae7e895c54bf0e10e2734f3889436c
    source_path: cli/path.md
    workflow: 16
---

# `openclaw path`

وصول عبر الصدفة إلى مخطط العنونة `oc://`: صيغة مسار واحدة توجّه حسب النوع
لفحص ملفات مساحة العمل القابلة للعنونة وتحريرها (markdown وjsonc وjsonl
وyaml/yml/lobster). يستخدمها مستضيفو الأنظمة ذاتيًا ومؤلفو الإضافات وامتدادات
المحررات لقراءة موقع ضيق أو العثور عليه أو تحديثه دون إنشاء محلل مخصص
لكل نوع ملف يدويًا.

يوفّر Plugin الاختياري المضمّن `oc-path` الأمر `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
  دون تحميل السجل كاملًا في محلل مخصص.
- ينتقل محرر إلى قسم 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`                            | تحليل `<value>` بوصفه JSON لاستبدال ورقة طرفية في JSON/JSONC/JSONL.        |
| `--dry-run`     | `set`                            | طباعة البايتات التي ستُكتب دون كتابتها.                                    |
| `--diff`        | `set` (يتطلب `--dry-run`)        | طباعة فرق موحّد بدلًا من البايتات الكاملة.                                 |

لا يقبل `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 حسب المعرّف المختصر، وعناصر نقطية حسب المعرّف المختصر أو `#N`، وfrontmatter عبر `[frontmatter]`.   |
| JSONC/JSON    | `.jsonc`, `.json`           | مفاتيح الكائنات وفهارس المصفوفات؛ تفصل النقاط المقاطع الفرعية المتداخلة ما لم تكن مقتبسة.                  |
| JSONL         | `.jsonl`, `.ndjson`         | عناوين الأسطر العليا (`L1` و`L2` و`$first` و`$last`)، ثم نزول بأسلوب JSONC داخل السطر.                    |
| YAML/.lobster | `.yaml`, `.yml`, `.lobster` | مفاتيح الخرائط وفهارس التسلسلات؛ تتولى واجهة برمجة مستند 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 وقد يغيّر الشكل، مثل
  استبدال اختصار مرجع سر نصي بكائن. تحلل عمليات الإدراج في كائنات ومصفوفات
  JSONC القيمة `<value>` بوصفها JSON، وتستخدم مسار تحرير `jsonc-parser`
  لعمليات كتابة الأوراق الطرفية العادية، مع الحفاظ على التعليقات والتنسيق
  القريب.
- تحوّل عمليات كتابة أوراق JSONL الطرفية الأنواع كما يفعل JSONC داخل السطر.
  يحلل استبدال السطر كاملًا والإلحاق القيمة `<value>` بوصفها JSON. يحافظ
  JSONL المعروض على النمط الغالب لنهايات الأسطر LF/CRLF في الملف (بتصويت
  الأغلبية عبر أسطر الملف الجديدة، لذا يبقى الملف ذو أغلبية CRLF بصيغة CRLF
  حتى مع وجود بعض أسطر LF الشاذة).
- تحوّل عمليات كتابة أوراق YAML الطرفية القيمة إلى نوع العدد القياسي الحالي
  (`string` أو `number` منتهٍ أو `true`/`false` أو `null`). تستخدم عمليات
  إدراج YAML واجهة برمجة المستند في حزمة `yaml` المضمّنة لتحديث الخرائط/
  التسلسلات. تُرفض مستندات YAML المشوهة التي تحتوي على أخطاء محلل قبل
  التعديل مع `parse-error`.

استخدم `--dry-run` قبل عمليات الكتابة المرئية للمستخدم عندما تكون البايتات
الدقيقة مهمة. تُرقّع تعديلات JSONC وYAML المستند الحالي (عبر `jsonc-parser`
أو واجهة برمجة مستند `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

# تجربة كتابة دون تنفيذها في شكل فرق موحّد
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

# عنون البيانات الوصفية الأمامية في Markdown
openclaw path resolve 'oc://AGENTS.md/[frontmatter]/name'

# أدرج بيانات وصفية أمامية في 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: email drafting agent
tier: core
---
## Tools
- gh: GitHub CLI
- curl: HTTP client
- send_email: enabled
```

```bash
$ openclaw path resolve 'oc://x.md/[frontmatter]/tier' --file frontmatter.md --human
ورقة عند السطر 4: "core" (سلسلة نصية)

$ openclaw path resolve 'oc://x.md/tools/gh/gh' --file frontmatter.md --human
ورقة عند السطر 9: "GitHub CLI" (سلسلة نصية)

$ openclaw path find 'oc://x.md/tools/*' --file frontmatter.md --human
3 تطابقات مع oc://x.md/tools/*:
  oc://x.md/tools/gh           →  عقدة عند السطر 9 [عنصر Markdown]
  oc://x.md/tools/curl         →  عقدة عند السطر 10 [عنصر Markdown]
  oc://x.md/tools/send-email   →  عقدة عند السطر 11 [عنصر Markdown]
```

يُعنون المسند `[frontmatter]` كتلة البيانات الوصفية الأمامية في YAML؛ ويطابق `tools`
العنوان `## Tools` عبر الاسم اللطيف، وتحتفظ أوراق العناصر بصيغة الاسم اللطيف الخاصة بها
حتى عندما يستخدم المصدر الشرطات السفلية (تتحول `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
ورقة عند السطر 4: "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
تطابق واحد مع oc://session.jsonl/[event=action]/userId:
  oc://session.jsonl/L2/userId  →  ورقة عند السطر 2: "u1" (سلسلة نصية)

$ openclaw path resolve 'oc://session.jsonl/L2/ts' --file session.jsonl --human
ورقة عند السطر 2: "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
ورقة عند السطر 3: "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 واجهة `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` — مرّر ملفًا محددًا (مطابقة الأنماط عبر
ملفات متعددة ميزة لاحقة).

```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` لمعاينة فرق موحّد.
ينتهي برمز `0` عند نجاح الكتابة، و`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>`

مرّر ملفًا في دورة كاملة عبر المحلل والمُخرِج الخاصين بنوعه. يجب أن يكون الناتج
مطابقًا للمدخل على مستوى البايتات إذا كان الملف سليمًا؛ ويشير الاختلاف إلى
خلل في المحلل أو تفعيل علامة. يفيد لتصحيح سلوك الركيزة على
مدخلات واقعية.

```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` البايتات عبر مسار الإخراج الخاص بالركيزة، والذي يطبق
  حارس علامة التنقيح تلقائيًا. تُرفض أثناء الكتابة أي ورقة تحمل
  `__OPENCLAW_REDACTED__` (حرفيًا أو كسلسلة فرعية).
- يستخدم تحليل JSONC وتعديل الأوراق اعتمادية `jsonc-parser`
  المحلية للـ Plugin، لذا تُحفظ التعليقات والتنسيق في عمليات كتابة الأوراق
  العادية بدلًا من المرور عبر مسار محلل وإعادة تصيير مُنشأ يدويًا.
- لا يدرك `path` تتبع إعدادات آخر نسخة صالحة معروفة (LKG) أو الاسترداد؛
  فتلك دورة حياة مملوكة في موضع آخر. إذا كان ملف تعدله عبر `path`
  خاضعًا أيضًا لتتبع LKG، فإن قراءة الإعدادات التالية تقرر ما إذا كانت ستعتمده أو
  تسترده؛ تعامل مع تعديل `path` بالطريقة نفسها التي تعامل بها أي كتابة مباشرة أخرى إلى
  ذلك الملف.

## ذو صلة

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