openclaw path

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

يوفّر Plugin الاختياري المضمّن oc-path الأمر path. فعّله قبل الاستخدام الأول:

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 لعمليات الملفات الصغيرة القابلة للعنونة، حيث يتفوق أمر طرفية قابل للتكرار على إنشاء محلل مخصص آخر.

كيفية استخدامه

اقرأ قيمة واحدة من ملف إعدادات يحرره البشر:

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 هدفًا محددًا واحدًا. أما find فهو الفعل الاستكشافي: يوسّع أحرف البدل والاتحادات والمسندات والترتيبيات إلى المطابقات المحددة التي يمكنك فحصها قبل اختيار واحدة للكتابة.

الأوامر الفرعية

العلامات العامة

لا يقبل validate سوى --json / --human؛ فهو لا يصل إلى نظام الملفات، لذلك لا ينطبق عليه --cwd و--file.

صيغة oc://

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 مع تشخيص تحليل بدلًا من تحليله، وذلك لأي فعل يحمّل ذلك الملف.

العنونة حسب نوع الملف

يعيد 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 عندما تريد المعاينة في شكل رقعة مركزة قبل/بعد بدلًا من الملف المعروض كاملًا.

أمثلة

# التحقق من مسار (دون الوصول إلى نظام الملفات)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

مزيد من أمثلة القواعد النحوية:

# ضع علامات اقتباس حول المفاتيح التي تحتوي على / أو .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 # بحث بالمسند ضمن أبناء JSONCopenclaw path find 'oc://config.jsonc/plugins/[enabled=true]/id' # أدرج عنصرًا في مصفوفة JSONCopenclaw path set 'oc://config.jsonc/items/+1' '{"id":"new","enabled":true}' --dry-run # أدرج مفتاح كائن JSONCopenclaw path set 'oc://config.jsonc/plugins/+github' '{"enabled":true}' --dry-run # ألحق حدث JSONLopenclaw path set 'oc://session.jsonl/+' '{"event":"checkpoint","ok":true}' --file ./logs/session.jsonl # اعثر على آخر سطر قيمة في JSONLopenclaw path resolve 'oc://session.jsonl/$last/event' --file ./logs/session.jsonl # اعثر على خطوة في سير عمل YAMLopenclaw path resolve 'oc://workflow.yaml/steps/0/id' # حدّث قيمة YAML عدديةopenclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --dry-run # عنون البيانات الوصفية الأمامية في Markdownopenclaw path resolve 'oc://AGENTS.md/[frontmatter]/name' # أدرج بيانات وصفية أمامية في Markdownopenclaw path set 'oc://AGENTS.md/[frontmatter]/+description' 'Agent instructions' --dry-run # ابحث عن حقول عناصر Markdownopenclaw path find 'oc://SKILL.md/Tools/*/send_email' # تحقّق من مسار ضمن نطاق الجلسةopenclaw path validate 'oc://AGENTS.md/Tools/$last/risk?session=cron-daily'

وصفات حسب نوع الملف

تعمل الأفعال الخمسة نفسها عبر الأنواع المختلفة؛ ويُوجّه نظام العنونة العملية بناءً على امتداد الملف.

Markdown

<!-- frontmatter.md -->---name: drafterdescription: email drafting agenttier: core---## Tools- gh: GitHub CLI- curl: HTTP client- send_email: enabled

$ 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 --human3 تطابقات مع 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

// 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ورقة عند السطر 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

{"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 --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

# 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ورقة عند السطر 3: "fetch" (سلسلة نصية) $ openclaw path set 'oc://workflow.yaml/steps/$last/id' 'classify-renamed' --file workflow.yaml --dry-run--dry-run: ستُكتب 99 بايت إلى /…/workflow.yamlname: inbox-triagesteps:  - 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 عند حدوث خطأ تحليل أو رفض النمط.

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

find <pattern>

اسرد كل تطابق لنمط يحتوي على حرف بدل / مسند / اتحاد. ينتهي برمز 0 عند وجود تطابق واحد على الأقل، و1 عند عدم وجود أي تطابق. تُرفض أحرف البدل في خانة الملف بالرمز OC_PATH_FILE_WILDCARD_UNSUPPORTED — مرّر ملفًا محددًا (مطابقة الأنماط عبر ملفات متعددة ميزة لاحقة).

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 عند حدوث أخطاء تحليل.

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 عندما يُمرر stdout عبر أنبوب أو يُعاد توجيهه. يتجاوز --json و--human الاكتشاف التلقائي.

ملاحظات

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

ذو صلة

• مرجع CLI