openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh ar translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-08 02:26:47 +00:00
parent 2995056c0b
commit 7abbb6caf6
33 changed files with 7640 additions and 6530 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

702
docs/ar/channels/matrix.md
View File

File diff suppressed because it is too large Load Diff

149
docs/ar/concepts/compaction.md
View File

@ -1,23 +1,23 @@
---
read_when:
- تريد فهم الضغط التلقائي والأمر /compact
- أنت تصحح جلسات طويلة تصطدم بحدود السياق
summary: كيف يلخّص OpenClaw المحادثات الطويلة للبقاء ضمن حدود النموذج
- أنت تصحح أخطاء الجلسات الطويلة التي تصطدم بحدود السياق
summary: كيف يلخص OpenClaw المحادثات الطويلة للبقاء ضمن حدود النموذج
title: الضغط
x-i18n:
generated_at: "2026-04-05T12:39:54Z"
generated_at: "2026-04-08T02:14:14Z"
model: gpt-5.4
provider: openai
source_hash: 4c6dbd6ebdcd5f918805aafdc153925efef3e130faa3fab3c630832e938219fc
source_hash: e6590b82a8c3a9c310998d653459ca4d8612495703ca0a8d8d306d7643142fd1
source_path: concepts/compaction.md
workflow: 15
---
# الضغط
لكل نموذج نافذة سياق — وهي الحد الأقصى لعدد الرموز التي يمكنه معالجتها.
لكل نموذج نافذة سياق -- وهي الحد الأقصى لعدد الرموز التي يمكنه معالجتها.
عندما تقترب المحادثة من هذا الحد، يقوم OpenClaw **بضغط** الرسائل الأقدم
إلى ملخص حتى يمكن أن تستمر الدردشة.
في ملخص حتى تتمكن الدردشة من الاستمرار.
## كيف يعمل
@ -25,42 +25,107 @@ x-i18n:
2. يُحفَظ الملخص في نص الجلسة.
3. تُحفَظ الرسائل الحديثة كما هي.
عندما يقسم OpenClaw السجل إلى مقاطع ضغط، فإنه يُبقي استدعاءات أدوات المساعد
مقترنة بإدخالات `toolResult` المطابقة لها. وإذا وقعت نقطة التقسيم
داخل كتلة أداة، ينقل OpenClaw الحد بحيث يبقى الزوج معًا
ويُحفَظ الذيل الحالي غير الملخّص.
عندما يقسم OpenClaw السجل إلى مقاطع ضغط، فإنه يبقي استدعاءات أدوات المساعد
مقترنة بإدخالات `toolResult` المطابقة لها. إذا وقعت نقطة التقسيم
داخل كتلة أداة، ينقل OpenClaw الحد الفاصل بحيث يبقى الزوج معًا
ويُحفَظ الذيل الحالي غير المُلخَّص.
يبقى السجل الكامل للمحادثة محفوظًا على القرص. ولا يغيّر الضغط إلا ما
يبقى سجل المحادثة الكامل محفوظًا على القرص. يغيّر الضغط فقط ما
يراه النموذج في الدورة التالية.
## الضغط التلقائي
يكون الضغط التلقائي مفعّلًا افتراضيًا. ويعمل عندما تقترب الجلسة من حد
الضغط التلقائي مفعّل افتراضيًا. يعمل عندما تقترب الجلسة من حد
السياق، أو عندما يعيد النموذج خطأ تجاوز السياق (وفي هذه الحالة
يضغط OpenClaw ثم يعيد المحاولة). وتتضمن تواقيع التجاوز الشائعة
يقوم OpenClaw بالضغط ثم يعيد المحاولة). تتضمن تواقيع التجاوز الشائعة
`request_too_large` و`context length exceeded` و`input exceeds the maximum
number of tokens` و`input token count exceeds the maximum number of input
tokens` و`input is too long for the model` و`ollama error: context length
exceeded`.
<Info>
قبل الضغط، يذكّر OpenClaw الوكيل تلقائيًا بحفظ الملاحظات المهمة في ملفات
[memory](/concepts/memory). وهذا يمنع فقدان السياق.
قبل الضغط، يذكّر OpenClaw الوكيل تلقائيًا بحفظ الملاحظات المهمة
في ملفات [memory](/ar/concepts/memory). هذا يمنع فقدان السياق.
</Info>
استخدم الإعداد `agents.defaults.compaction` في ملف `openclaw.json` لتكوين سلوك الضغط (الوضع، والرموز المستهدفة، وغير ذلك).
يحافظ تلخيص الضغط افتراضيًا على المعرّفات المعتمة (`identifierPolicy: "strict"`). يمكنك تجاوز ذلك باستخدام `identifierPolicy: "off"` أو توفير نص مخصص باستخدام `identifierPolicy: "custom"` و`identifierInstructions`.
يمكنك اختياريًا تحديد نموذج مختلف لتلخيص الضغط عبر `agents.defaults.compaction.model`. يكون هذا مفيدًا عندما يكون نموذجك الأساسي نموذجًا محليًا أو صغيرًا وتريد أن تُنتَج ملخصات الضغط بواسطة نموذج أكثر قدرة. يقبل هذا التجاوز أي سلسلة `provider/model-id`:
```json
{
"agents": {
"defaults": {
"compaction": {
"model": "openrouter/anthropic/claude-sonnet-4-6"
}
}
}
}
```
يعمل هذا أيضًا مع النماذج المحلية، على سبيل المثال نموذج Ollama ثانٍ مخصص للتلخيص أو نموذج متخصص مضبوط بدقة للضغط:
```json
{
"agents": {
"defaults": {
"compaction": {
"model": "ollama/llama3.1:8b"
}
}
}
}
```
عند عدم ضبطه، يستخدم الضغط النموذج الأساسي للوكيل.
## موفرو الضغط القابلون للتوصيل
يمكن للمكونات الإضافية تسجيل موفر ضغط مخصص عبر `registerCompactionProvider()` على واجهة API الخاصة بالمكون الإضافي. عند تسجيل موفر وتكوينه، يفوض OpenClaw التلخيص إليه بدلًا من مسار LLM المدمج.
لاستخدام موفر مسجل، عيّن معرّف الموفر في إعداداتك:
```json
{
"agents": {
"defaults": {
"compaction": {
"provider": "my-provider"
}
}
}
}
```
يؤدي تعيين `provider` تلقائيًا إلى فرض `mode: "safeguard"`. تتلقى الموفرات تعليمات الضغط نفسها وسياسة الحفاظ على المعرّفات نفسها المستخدمة في المسار المدمج، ويستمر OpenClaw أيضًا في الحفاظ على سياق لاحقة الأدوار الحديثة والأدوار المقسومة بعد مخرجات الموفر. إذا فشل الموفر أو أعاد نتيجة فارغة، يعود OpenClaw إلى تلخيص LLM المدمج.
## الضغط التلقائي (مفعّل افتراضيًا)
عندما تقترب الجلسة من نافذة سياق النموذج أو تتجاوزها، يشغّل OpenClaw الضغط التلقائي وقد يعيد محاولة الطلب الأصلي باستخدام السياق المضغوط.
سترى:
- `🧹 Auto-compaction complete` في الوضع المفصل
- يعرض `/status` القيمة `🧹 Compactions: <count>`
قبل الضغط، يمكن لـ OpenClaw تشغيل دورة **تفريغ ذاكرة صامتة** لتخزين
الملاحظات الدائمة على القرص. راجع [Memory](/ar/concepts/memory) للحصول على التفاصيل والإعدادات.
## الضغط اليدوي
اكتب `/compact` في أي دردشة لفرض عملية ضغط. وأضف تعليمات لتوجيه
اكتب `/compact` في أي دردشة لفرض الضغط. أضف تعليمات لتوجيه
الملخص:
```
/compact ركّز على قرارات تصميم API
/compact Focus on the API design decisions
```
## استخدام نموذج مختلف
افتراضيًا، يستخدم الضغط النموذج الأساسي لوكيلك. ويمكنك استخدام نموذج أكثر
قدرة للحصول على ملخصات أفضل:
افتراضيًا، يستخدم الضغط النموذج الأساسي لوكيلك. يمكنك استخدام نموذج
أكثر قدرة للحصول على ملخصات أفضل:
```json5
{
@ -76,8 +141,8 @@ exceeded`.
## إشعار بدء الضغط
افتراضيًا، يعمل الضغط بصمت. ولعرض إشعار موجز عند بدء
الضغط، فعّل `notifyUser`:
افتراضيًا، يعمل الضغط بصمت. لإظهار إشعار موجز عند بدء الضغط،
فعّل `notifyUser`:
```json5
{
@ -91,39 +156,39 @@ exceeded`.
}
```
عند التمكين، يرى المستخدم رسالة قصيرة (على سبيل المثال، "جارٍ ضغط
السياق...") في بداية كل تشغيل لعملية الضغط.
عند تفعيله، يرى المستخدم رسالة قصيرة (على سبيل المثال، "جاري ضغط
السياق...") عند بداية كل عملية ضغط.
## الضغط مقابل التقليم
## الضغط مقابل التقليص
| | الضغط | التقليم |
| | الضغط | التقليص |
| ---------------- | ----------------------------- | -------------------------------- |
| **ما الذي يفعله** | يلخّص المحادثة الأقدم | يقتطع نتائج الأدوات القديمة |
| **هل يُحفَظ؟** | نعم (في نص الجلسة) | لا (في الذاكرة فقط، لكل طلب) |
| **النطاق** | المحادثة بأكملها | نتائج الأدوات فقط |
| **ما الذي يفعله** | يلخص المحادثة الأقدم | يقتطع نتائج الأدوات القديمة |
| **هل يُحفَظ؟** | نعم (في نص الجلسة) | لا (في الذاكرة فقط، لكل طلب) |
| **النطاق** | المحادثة بالكامل | نتائج الأدوات فقط |
يُعد [Session pruning](/concepts/session-pruning) مكمّلًا أخف وزنًا
يقوم بتقليم مخرجات الأدوات من دون تلخيص.
يُعد [تقليص الجلسة](/ar/concepts/session-pruning) مكمّلًا أخف وزنًا
يقتطع مخرجات الأدوات دون تلخيصها.
## استكشاف الأخطاء وإصلاحها
**هل يحدث الضغط كثيرًا جدًا؟** قد تكون نافذة سياق النموذج صغيرة، أو قد تكون
مخرجات الأدوات كبيرة. جرّب تمكين
[Session pruning](/concepts/session-pruning).
مخرجات الأدوات كبيرة. جرّب تفعيل
[تقليص الجلسة](/ar/concepts/session-pruning).
**هل يبدو السياق قديمًا بعد الضغط؟** استخدم `/compact ركّز على <topic>` لتوجيه
الملخص، أو فعّل [memory flush](/concepts/memory) حتى تبقى الملاحظات
محفوظة.
**هل يبدو السياق قديمًا بعد الضغط؟** استخدم `/compact Focus on <topic>` من أجل
توجيه الملخص، أو فعّل [تفريغ الذاكرة](/ar/concepts/memory) حتى تبقى
الملاحظات محفوظة.
**هل تحتاج إلى بداية نظيفة؟** يبدأ `/new` جلسة جديدة من دون ضغط.
**هل تحتاج إلى بداية نظيفة؟** يبدأ `/new` جلسة جديدة دون ضغط.
للحصول على تهيئة متقدمة (الرموز المحجوزة، والحفاظ على المعرّفات، ومحركات
للحصول على إعدادات متقدمة (الرموز المحجوزة، والحفاظ على المعرّفات، ومحركات
السياق المخصصة، والضغط من جهة الخادم في OpenAI)، راجع
[التعمق في إدارة الجلسات](/reference/session-management-compaction).
[التعمق في إدارة الجلسات](/ar/reference/session-management-compaction).
## ذو صلة
- [Session](/concepts/session) — إدارة الجلسات ودورة حياتها
- [Session Pruning](/concepts/session-pruning) — تقليم نتائج الأدوات
- [Context](/concepts/context) — كيف يُبنى السياق لأدوار الوكيل
- [Hooks](/automation/hooks) — hooks دورة حياة الضغط (`before_compaction` و`after_compaction`)
- [الجلسة](/ar/concepts/session) — إدارة الجلسات ودورة حياتها
- [تقليص الجلسة](/ar/concepts/session-pruning) — اقتطاع نتائج الأدوات
- [السياق](/ar/concepts/context) — كيفية بناء السياق لأدوار الوكيل
- [Hooks](/ar/automation/hooks) — خطافات دورة حياة الضغط (`before_compaction`, `after_compaction`)

216
docs/ar/concepts/context-engine.md
View File

@ -3,71 +3,71 @@ read_when:
- تريد فهم كيفية قيام OpenClaw بتجميع سياق النموذج
- أنت تنتقل بين المحرك القديم ومحرك plugin
- أنت تبني plugin لمحرك سياق
summary: 'محرك السياق: تجميع سياق قابل للتوصيل، والضغط، ودورة حياة الوكلاء الفرعيين'
title: Context Engine
summary: 'محرك السياق: تجميع سياق قابل للتوصيل، والضغط، ودورة حياة الوكيل الفرعي'
title: محرك السياق
x-i18n:
generated_at: "2026-04-05T12:40:19Z"
generated_at: "2026-04-08T02:14:24Z"
model: gpt-5.4
provider: openai
source_hash: 19fd8cbb0e953f58fd84637fc4ceefc65984312cf2896d338318bc8cf860e6d9
source_hash: e8290ac73272eee275bce8e481ac7959b65386752caa68044d0c6f3e450acfb1
source_path: concepts/context-engine.md
workflow: 15
---
# Context Engine
# محرك السياق
يتحكم **محرك السياق** في كيفية بناء OpenClaw لسياق النموذج لكل تشغيل.
فهو يحدد الرسائل التي يجب تضمينها، وكيفية تلخيص السجل الأقدم، وكيفية
ويقرر الرسائل التي يجب تضمينها، وكيفية تلخيص السجل الأقدم، وكيفية
إدارة السياق عبر حدود الوكلاء الفرعيين.
يوفر OpenClaw محركًا مدمجًا باسم `legacy`. ويمكن لـ Plugins تسجيل
محركات بديلة تستبدل دورة حياة محرك السياق النشط.
يأتي OpenClaw مزودًا بمحرك `legacy` مدمج. ويمكن لـ plugins تسجيل
محركات بديلة تحل محل دورة حياة محرك السياق النشطة.
## البدء السريع
تحقق من المحرك النشط:
تحقق من المحرك النشط حاليًا:
```bash
openclaw doctor
# أو افحص التكوين مباشرة:
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'
```
### تثبيت plugin لمحرك سياق
يتم تثبيت Plugins الخاصة بمحرك السياق مثل أي plugin آخر في OpenClaw. قم بالتثبيت
أولًا، ثم حدد المحرك في الـ slot:
يتم تثبيت plugins الخاصة بمحرك السياق مثل أي plugin أخرى في OpenClaw. ثبّت
plugin أولًا، ثم حدّد المحرك في slot:
```bash
# التثبيت من npm
# Install from npm
openclaw plugins install @martian-engineering/lossless-claw
# أو التثبيت من مسار محلي (للتطوير)
# Or install from a local path (for development)
openclaw plugins install -l ./my-context-engine
```
ثم قم بتمكين plugin وحدده كمحرك نشط في التكوين:
بعد ذلك، فعّل plugin وحددها كمحرك نشط في الإعدادات:
```json5
// openclaw.json
{
plugins: {
slots: {
contextEngine: "lossless-claw", // يجب أن يطابق معرّف المحرك المسجل في plugin
contextEngine: "lossless-claw", // must match the plugin's registered engine id
},
entries: {
"lossless-claw": {
enabled: true,
// يذهب هنا التكوين الخاص بـ plugin (راجع وثائق plugin)
// Plugin-specific config goes here (see the plugin's docs)
},
},
},
}
```
أعد تشغيل gateway بعد التثبيت والتكوين.
أعد تشغيل البوابة بعد التثبيت والإعداد.
للعودة إلى المحرك المدمج، اضبط `contextEngine` على `"legacy"` (أو
للرجوع إلى المحرك المدمج، اضبط `contextEngine` على `"legacy"` (أو
احذف المفتاح بالكامل — إذ إن `"legacy"` هو الافتراضي).
## كيف يعمل
@ -75,53 +75,55 @@ openclaw plugins install -l ./my-context-engine
في كل مرة يشغّل فيها OpenClaw مطالبة نموذج، يشارك محرك السياق في
أربع نقاط في دورة الحياة:
1. **Ingest** — يُستدعى عند إضافة رسالة جديدة إلى الجلسة. يمكن للمحرك
1. **الاستيعاب** — يُستدعى عند إضافة رسالة جديدة إلى الجلسة. ويمكن للمحرك
تخزين الرسالة أو فهرستها في مخزن البيانات الخاص به.
2. **Assemble** — يُستدعى قبل كل تشغيل للنموذج. يعيد المحرك مجموعة
مرتبة من الرسائل (و`systemPromptAddition` اختياريًا) تتلاءم مع
2. **التجميع** — يُستدعى قبل كل تشغيل للنموذج. ويعيد المحرك مجموعة
مرتبة من الرسائل (و`systemPromptAddition` اختياري) تتناسب مع
ميزانية الرموز.
3. **Compact** — يُستدعى عندما تمتلئ نافذة السياق، أو عندما يشغّل المستخدم
`/compact`. يقوم المحرك بتلخيص السجل الأقدم لتحرير مساحة.
4. **After turn** — يُستدعى بعد اكتمال التشغيل. يمكن للمحرك حفظ الحالة،
3. **الضغط** — يُستدعى عندما تمتلئ نافذة السياق، أو عندما يشغّل المستخدم
`/compact`. ويلخّص المحرك السجل الأقدم لتحرير مساحة.
4. **بعد الدور** — يُستدعى بعد اكتمال التشغيل. ويمكن للمحرك حفظ الحالة،
أو تشغيل ضغط في الخلفية، أو تحديث الفهارس.
### دورة حياة الوكيل الفرعي (اختياري)
يستدعي OpenClaw حاليًا hook واحدة فقط لدورة حياة الوكيل الفرعي:
يستدعي OpenClaw حاليًا خطافًا واحدًا لدورة حياة الوكيل الفرعي:
- **onSubagentEnded** — تنظيف عند اكتمال جلسة وكيل فرعي أو عند إزالتها.
- **onSubagentEnded** — للتنظيف عند اكتمال جلسة وكيل فرعي أو اكتساحها.
تُعد hook ‏`prepareSubagentSpawn` جزءًا من الواجهة لاستخدام مستقبلي، لكن
وقت التشغيل لا يستدعيها بعد.
خطاف `prepareSubagentSpawn` جزء من الواجهة لاستخدام مستقبلي، لكن
بيئة التشغيل لا تستدعيه بعد.
### إضافة مطالبة النظام
يمكن لطريقة `assemble` أن تعيد سلسلة `systemPromptAddition`. يقوم OpenClaw
بإضافتها في مقدمة مطالبة النظام لذلك التشغيل. يتيح ذلك للمحركات حقن
إرشادات استرجاع ديناميكية، أو تعليمات استدعاء، أو تلميحات
مدركة للسياق من دون الحاجة إلى ملفات مساحة عمل ثابتة.
يمكن للطريقة `assemble` أن تعيد سلسلة `systemPromptAddition`. ويقوم OpenClaw
بإضافتها في بداية مطالبة النظام الخاصة بالتشغيل. ويتيح هذا للمحركات حقن
إرشادات استدعاء ديناميكية، أو تعليمات استرجاع، أو تلميحات
مدركة للسياق دون الحاجة إلى ملفات مساحة عمل ثابتة.
## المحرك القديم
يحافظ المحرك المدمج `legacy` على السلوك الأصلي لـ OpenClaw:
يحافظ المحرك `legacy` المدمج على السلوك الأصلي لـ OpenClaw:
- **Ingest**: لا عملية (إذ يتولى مدير الجلسة حفظ الرسائل مباشرة).
- **Assemble**: تمرير مباشر (يتولى المسار الحالي sanitize → validate → limit
في وقت التشغيل تجميع السياق).
- **Compact**: يفوض إلى ضغط التلخيص المدمج، والذي ينشئ
ملخصًا واحدًا للرسائل الأقدم ويُبقي الرسائل الحديثة كما هي.
- **After turn**: لا عملية.
- **الاستيعاب**: لا إجراء (يتولى مدير الجلسة حفظ الرسائل مباشرة).
- **التجميع**: تمرير مباشر (يتولى خط الأنابيب الحالي sanitize → validate → limit
في بيئة التشغيل تجميع السياق).
- **الضغط**: يفوّض إلى ضغط التلخيص المدمج، الذي ينشئ
ملخصًا واحدًا للرسائل الأقدم ويحافظ على الرسائل الحديثة كما هي.
- **بعد الدور**: لا إجراء.
لا يسجل المحرك القديم أدوات ولا يوفّر `systemPromptAddition`.
عندما لا تكون `plugins.slots.contextEngine` مضبوطة (أو تكون مضبوطة على `"legacy"`)،
عندما لا يكون `plugins.slots.contextEngine` مضبوطًا (أو يكون مضبوطًا على `"legacy"`)،
يُستخدم هذا المحرك تلقائيًا.
## محركات plugin
يمكن لأي plugin تسجيل محرك سياق باستخدام API الخاصة بـ plugin:
يمكن لـ plugin تسجيل محرك سياق باستخدام plugin API:
```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
export default function register(api) {
api.registerContextEngine("my-engine", () => ({
info: {
@ -135,12 +137,15 @@ export default function register(api) {
return { ingested: true };
},
async assemble({ sessionId, messages, tokenBudget }) {
async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {
// Return messages that fit the budget
return {
messages: buildContext(messages, tokenBudget),
estimatedTokens: countTokens(messages),
systemPromptAddition: "Use lcm_grep to search history...",
systemPromptAddition: buildMemorySystemPromptAddition({
availableTools: availableTools ?? new Set(),
citationsMode,
}),
};
},
@ -152,7 +157,7 @@ export default function register(api) {
}
```
ثم قم بتمكينه في التكوين:
ثم فعّله في الإعدادات:
```json5
{
@ -173,49 +178,49 @@ export default function register(api) {
الأعضاء المطلوبة:
| العضو | النوع | الغرض |
| ------------------ | -------- | ------------------------------------------------------ |
| `info` | خاصية | معرّف المحرك واسمه وإصداره وما إذا كان يملك الضغط |
| `ingest(params)` | طريقة | تخزين رسالة واحدة |
| `assemble(params)` | طريقة | بناء سياق لتشغيل نموذج (تعيد `AssembleResult`) |
| `compact(params)` | طريقة | تلخيص/تقليل السياق |
| العضو | النوع | الغرض |
| ------------------ | -------- | -------------------------------------------------------- |
| `info` | خاصية | معرّف المحرك واسمه وإصداره وما إذا كان يملك الضغط |
| `ingest(params)` | طريقة | تخزين رسالة واحدة |
| `assemble(params)` | طريقة | بناء السياق لتشغيل نموذج (يعيد `AssembleResult`) |
| `compact(params)` | طريقة | تلخيص/تقليل السياق |
تعيد `assemble` قيمة `AssembleResult` تحتوي على:
- `messages` — الرسائل المرتبة التي سيتم إرسالها إلى النموذج.
- `estimatedTokens` ‏(مطلوب، `number`) — تقدير المحرك لإجمالي
الرموز في السياق المجمع. يستخدم OpenClaw هذا لاتخاذ قرارات حدود الضغط
ولإعداد تقارير التشخيص.
- `systemPromptAddition` ‏(اختياري، `string`) — يُضاف في مقدمة مطالبة النظام.
- `messages` — الرسائل المرتبة التي ستُرسل إلى النموذج.
- `estimatedTokens` (مطلوب، `number`) — تقدير المحرك لإجمالي
الرموز في السياق المجمّع. ويستخدم OpenClaw هذا لاتخاذ قرارات
حدّ الضغط وللتقارير التشخيصية.
- `systemPromptAddition` (اختياري، `string`) — تُضاف في بداية مطالبة النظام.
الأعضاء الاختيارية:
| العضو | النوع | الغرض |
| ----------------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `bootstrap(params)` | طريقة | تهيئة حالة المحرك لجلسة. تُستدعى مرة واحدة عندما يرى المحرك جلسة لأول مرة (مثل استيراد السجل). |
| `ingestBatch(params)` | طريقة | استيعاب دور مكتمل على شكل دفعة. تُستدعى بعد اكتمال تشغيل، مع جميع رسائل ذلك الدور دفعة واحدة. |
| `afterTurn(params)` | طريقة | أعمال ما بعد التشغيل في دورة الحياة (حفظ الحالة، تشغيل ضغط في الخلفية). |
| `prepareSubagentSpawn(params)`| طريقة | إعداد الحالة المشتركة لجلسة فرعية. |
| `onSubagentEnded(params)` | طريقة | التنظيف بعد انتهاء وكيل فرعي. |
| `dispose()` | طريقة | تحرير الموارد. تُستدعى أثناء إيقاف gateway أو إعادة تحميل plugin — وليس لكل جلسة. |
| العضو | النوع | الغرض |
| ------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------- |
| `bootstrap(params)` | طريقة | تهيئة حالة المحرك لجلسة. تُستدعى مرة واحدة عندما يرى المحرك جلسة لأول مرة (مثل استيراد السجل). |
| `ingestBatch(params)` | طريقة | استيعاب دور مكتمل كدفعة. تُستدعى بعد اكتمال التشغيل، مع جميع رسائل ذلك الدور دفعة واحدة. |
| `afterTurn(params)` | طريقة | أعمال دورة الحياة بعد التشغيل (حفظ الحالة، تشغيل ضغط في الخلفية). |
| `prepareSubagentSpawn(params)` | طريقة | إعداد حالة مشتركة لجلسة فرعية. |
| `onSubagentEnded(params)` | طريقة | التنظيف بعد انتهاء وكيل فرعي. |
| `dispose()` | طريقة | تحرير الموارد. تُستدعى أثناء إيقاف تشغيل البوابة أو إعادة تحميل plugin — وليس لكل جلسة. |
### ownsCompaction
يتحكم `ownsCompaction` فيما إذا كان الضغط التلقائي المدمج داخل المحاولة في Pi
يتحكم `ownsCompaction` فيما إذا كان الضغط التلقائي المدمج أثناء المحاولة في Pi
يبقى مفعّلًا أثناء التشغيل:
- `true` — يمتلك المحرك سلوك الضغط. يعطّل OpenClaw الضغط التلقائي المدمج في Pi
- `true` — يملك المحرك سلوك الضغط. يعطّل OpenClaw الضغط التلقائي المدمج في Pi
لذلك التشغيل، ويصبح تنفيذ `compact()` الخاص بالمحرك مسؤولًا عن `/compact`،
وضغط استعادة تجاوز السعة، وأي ضغط استباقي
وضغط الاسترداد من تجاوز السعة، وأي ضغط استباقي
يريد تنفيذه في `afterTurn()`.
- `false` أو غير معيّن — قد يستمر الضغط التلقائي المدمج في Pi أثناء
تنفيذ المطالبة، لكن تظل طريقة `compact()` الخاصة بالمحرك النشط تُستدعى
من أجل `/compact` واستعادة تجاوز السعة.
- `false` أو غير مضبوط — قد يستمر تشغيل الضغط التلقائي المدمج في Pi أثناء
تنفيذ المطالبة، لكن تظل طريقة `compact()` الخاصة بالمحرك النشط
مستدعاة من أجل `/compact` والاسترداد من تجاوز السعة.
لا تعني `ownsCompaction: false` أن OpenClaw يعود تلقائيًا
إلى مسار الضغط الخاص بالمحرك القديم.
لا يعني `ownsCompaction: false` أن OpenClaw يعود تلقائيًا إلى
مسار الضغط الخاص بالمحرك القديم.
وهذا يعني وجود نمطين صالحين لـ plugin:
وهذا يعني أن هناك نمطين صالحين لـ plugin:
- **وضع التملك** — نفّذ خوارزمية الضغط الخاصة بك واضبط
`ownsCompaction: true`.
@ -223,58 +228,65 @@ export default function register(api) {
`delegateCompactionToRuntime(...)` من `openclaw/plugin-sdk/core` لاستخدام
سلوك الضغط المدمج في OpenClaw.
إن `compact()` التي لا تقوم بأي شيء غير آمنة لمحرك نشط غير مالك لأنها
تعطّل المسار العادي لـ `/compact` وضغط استعادة تجاوز السعة لذلك الـ engine slot.
إن `compact()` التي لا تنفّذ أي شيء غير آمنة لمحرك نشط غير مالك لأن ذلك
يعطّل مسار `/compact` العادي ومسار ضغط الاسترداد من تجاوز السعة
لـ slot ذلك المحرك.
## مرجع التكوين
## مرجع الإعدادات
```json5
{
plugins: {
slots: {
// حدد محرك السياق النشط. الافتراضي: "legacy".
// اضبطه على معرّف plugin لاستخدام محرك plugin.
// Select the active context engine. Default: "legacy".
// Set to a plugin id to use a plugin engine.
contextEngine: "legacy",
},
},
}
```
يكون الـ slot حصريًا في وقت التشغيل — لا يتم
حل سوى محرك سياق مسجل واحد لتشغيل معيّن أو عملية ضغط. أما بقية
Plugins من النوع `kind: "context-engine"` والمفعلة فيمكنها أن تُحمّل وتنفّذ
شفرة التسجيل الخاصة بها؛ إذ يحدد `plugins.slots.contextEngine` فقط أي معرّف محرك مسجل
يحلّه OpenClaw عندما يحتاج إلى محرك سياق.
يكون الـ slot حصريًا في وقت التشغيل — إذ لا يُحل سوى محرك سياق مسجل واحد
لتشغيل أو عملية ضغط معينة. ويمكن لبقية plugins المفعّلة
من النوع `kind: "context-engine"` أن تُحمّل وتنفّذ
شيفرة التسجيل الخاصة بها؛ إذ يحدد `plugins.slots.contextEngine` فقط
معرّف المحرك المسجل الذي يحله OpenClaw عندما يحتاج إلى محرك سياق.
## العلاقة مع الضغط والذاكرة
- **الضغط** هو إحدى مسؤوليات محرك السياق. يفوض المحرك القديم
- **الضغط** هو إحدى مسؤوليات محرك السياق. يفوّض المحرك القديم
إلى التلخيص المدمج في OpenClaw. ويمكن لمحركات plugin تنفيذ
أي استراتيجية ضغط (ملخصات DAG، أو استدعاء vector، وما إلى ذلك).
- **Plugins الذاكرة** (`plugins.slots.memory`) منفصلة عن محركات السياق.
توفر Plugins الذاكرة البحث/الاستدعاء؛ بينما تتحكم محركات السياق فيما
يراه النموذج. ويمكنهما العمل معًا — فقد يستخدم محرك السياق بيانات
plugin الذاكرة أثناء التجميع.
- يظل **تشذيب الجلسة** (قص نتائج الأدوات القديمة في الذاكرة)
يعمل بغض النظر عن محرك السياق النشط.
أي استراتيجية ضغط (ملخصات DAG، أو استرجاع متجهي، وما إلى ذلك).
- **plugins الذاكرة** (`plugins.slots.memory`) منفصلة عن محركات السياق.
توفّر plugins الذاكرة البحث/الاسترجاع؛ بينما تتحكم محركات السياق فيما
يراه النموذج. ويمكنهما العمل معًا — فقد يستخدم محرك سياق
بيانات plugin الذاكرة أثناء التجميع. ويُفضّل أن تستخدم محركات plugin التي تريد
مسار مطالبة الذاكرة النشط `buildMemorySystemPromptAddition(...)` من
`openclaw/plugin-sdk/core`، إذ يحوّل مقاطع مطالبة الذاكرة النشطة
إلى `systemPromptAddition` جاهزة للإضافة في البداية. وإذا احتاج المحرك إلى
تحكم على مستوى أدنى، فلا يزال بإمكانه سحب الأسطر الخام من
`openclaw/plugin-sdk/memory-host-core` عبر
`buildActiveMemoryPromptSection(...)`.
- **تهذيب الجلسة** (قص نتائج الأدوات القديمة داخل الذاكرة) يظل يعمل
بغض النظر عن محرك السياق النشط.
## نصائح
- استخدم `openclaw doctor` للتحقق من أن محركك يتم تحميله بشكل صحيح.
- إذا قمت بالتبديل بين المحركات، فستستمر الجلسات الحالية بسجلها الحالي.
- استخدم `openclaw doctor` للتحقق من أن محركك يُحمَّل بشكل صحيح.
- إذا كنت تبدّل بين المحركات، فستستمر الجلسات الحالية بسجلها الحالي.
وسيتولى المحرك الجديد التشغيلات المستقبلية.
- يتم تسجيل أخطاء المحرك وعرضها في التشخيصات. إذا فشل محرك plugin
في التسجيل أو تعذر حل معرّف المحرك المحدد، فلن يعود OpenClaw تلقائيًا؛
بل ستفشل التشغيلات حتى تصلح plugin أو
- تُسجّل أخطاء المحرك وتظهر في التشخيصات. وإذا فشل محرك plugin
في التسجيل أو تعذر حل معرّف المحرك المحدد، فلن يعود OpenClaw
تلقائيًا؛ بل ستفشل التشغيلات حتى تصلح plugin أو
تعيد `plugins.slots.contextEngine` إلى `"legacy"`.
- لأغراض التطوير، استخدم `openclaw plugins install -l ./my-engine` لربط
دليل plugin محلي من دون نسخه.
دليل plugin محليًا من دون نسخه.
راجع أيضًا: [الضغط](/concepts/compaction)، [السياق](/concepts/context)،
[Plugins](/tools/plugin)، [بيان plugin](/plugins/manifest).
راجع أيضًا: [الضغط](/ar/concepts/compaction)، [السياق](/ar/concepts/context),
[Plugins](/ar/tools/plugin)، [بيان plugin](/ar/plugins/manifest).
## ذو صلة
- [السياق](/concepts/context) — كيفية بناء السياق لأدوار الوكيل
- [بنية plugin](/plugins/architecture) — تسجيل Plugins لمحركات السياق
- [الضغط](/concepts/compaction) — تلخيص المحادثات الطويلة
- [السياق](/ar/concepts/context) — كيف يُبنى السياق لأدوار الوكيل
- [معمارية Plugin](/ar/plugins/architecture) — تسجيل plugins لمحرك السياق
- [الضغط](/ar/concepts/compaction) — تلخيص المحادثات الطويلة

797
docs/ar/concepts/model-providers.md
View File

File diff suppressed because it is too large Load Diff

81
docs/ar/concepts/qa-e2e-automation.md
View File

@ -1,37 +1,37 @@
---
read_when:
- تقوم بتوسيع qa-lab أو qa-channel
- تضيف سيناريوهات QA مدعومة من المستودع
- تبني أتمتة QA أكثر واقعية حول لوحة Gateway
summary: بنية أتمتة QA الخاصة لـ qa-lab وqa-channel والسيناريوهات المزروعة وتقارير البروتوكول
title: أتمتة QA الشاملة من الطرف إلى الطرف
- عند توسيع qa-lab أو qa-channel
- عند إضافة سيناريوهات QA مدعومة بالمستودع
- عند بناء أتمتة QA أكثر واقعية حول لوحة تحكم Gateway
summary: شكل أتمتة QA الخاص لـ qa-lab وqa-channel والسيناريوهات المُهيأة مسبقًا وتقارير البروتوكول
title: أتمتة QA من طرف إلى طرف
x-i18n:
generated_at: "2026-04-07T07:16:41Z"
generated_at: "2026-04-08T02:14:02Z"
model: gpt-5.4
provider: openai
source_hash: 113e89d8d3ee8ef3058d95b9aea9a1c2335b07794446be2d231c0faeb044b23b
source_hash: 3b4aa5acc8e77303f4045d4f04372494cae21b89d2fdaba856dbb4855ced9d27
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
# أتمتة QA الشاملة من الطرف إلى الطرف
# أتمتة QA من طرف إلى طرف
تهدف حزمة QA الخاصة إلى اختبار OpenClaw بطريقة أكثر واقعية،
وأقرب إلى شكل القنوات، مما يمكن أن يحققه اختبار وحدة واحد.
تهدف حزمة QA الخاصة إلى اختبار OpenClaw بطريقة أكثر واقعية
ومشابهة للقنوات مما يمكن أن يقدمه اختبار وحدة واحد.
المكونات الحالية:
- `extensions/qa-channel`: قناة رسائل اصطناعية بواجهات للرسائل الخاصة، والقنوات، وسلاسل المحادثة،
والتفاعلات، والتعديل، والحذف.
- `extensions/qa-lab`: واجهة تصحيح وحافلة QA لمراقبة النص،
وحقن الرسائل الواردة، وتصدير تقرير Markdown.
- `qa/`: أصول زرع مدعومة من المستودع لمهمة الانطلاق وسيناريوهات QA
- `extensions/qa-channel`: قناة رسائل اصطناعية مع أسطح DM والقناة والخيط
والتفاعل والتعديل والحذف.
- `extensions/qa-lab`: واجهة مستخدم للتصحيح وناقل QA لمراقبة السجل،
وإدخال الرسائل الواردة، وتصدير تقرير Markdown.
- `qa/`: أصول تهيئة مدعومة بالمستودع لمهمة البداية وسيناريوهات QA
الأساسية.
التدفق الحالي لمشغل QA هو موقع QA ذو لوحتين:
مسار عمل مشغل QA الحالي هو موقع QA بلوحتين:
- اليسار: لوحة Gateway (واجهة التحكم) مع العامل.
- اليمين: QA Lab، وتعرض النص الشبيه بـ Slack وخطة السيناريو.
- اليسار: لوحة تحكم Gateway (Control UI) مع الوكيل.
- اليمين: QA Lab، يعرض السجل الشبيه بـ Slack وخطة السيناريو.
شغّله باستخدام:
@ -39,44 +39,57 @@ x-i18n:
pnpm qa:lab:up
```
يقوم ذلك ببناء موقع QA، وبدء مسار Gateway المدعوم بـ Docker، وإتاحة
صفحة QA Lab حيث يمكن لمشغل أو لحلقة أتمتة إعطاء العامل
يقوم ذلك ببناء موقع QA، وبدء مسار Gateway المعتمد على Docker، وإتاحة
صفحة QA Lab حيث يمكن لمشغل أو حلقة أتمتة إعطاء الوكيل
مهمة QA، ومراقبة سلوك القناة الفعلي، وتسجيل ما نجح، وما فشل، وما
ظل معطّلًا.
بقي معطّلًا.
## البذور المدعومة من المستودع
لتحسين سرعة التكرار على واجهة QA Lab دون إعادة بناء صورة Docker في كل مرة،
ابدأ الحزمة باستخدام حزمة QA Lab مركّبة عبر bind mount:
توجد أصول البذور في `qa/`:
```bash
pnpm openclaw qa docker-build-image
pnpm qa:lab:build
pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
- `qa/QA_KICKOFF_TASK.md`
- `qa/seed-scenarios.json`
يبقي `qa:lab:up:fast` خدمات Docker على صورة مبنية مسبقًا ويستخدم bind mount
للدليل `extensions/qa-lab/web/dist` داخل حاوية `qa-lab`. ويقوم `qa:lab:watch`
بإعادة بناء تلك الحزمة عند التغيير، ويُعاد تحميل المتصفح تلقائيًا عندما تتغير
بصمة أصول QA Lab.
## التهيئات المدعومة بالمستودع
توجد أصول التهيئة في `qa/`:
- `qa/scenarios.md`
هذه الملفات موجودة عمدًا في git بحيث تكون خطة QA مرئية لكل من البشر
والعامل. يجب أن تبقى القائمة الأساسية واسعة بما يكفي لتغطية:
والوكيل. يجب أن تظل القائمة الأساسية واسعة بما يكفي لتغطية:
- المحادثات الخاصة ومحادثات القنوات
- سلوك سلاسل المحادثة
- محادثات DM والقنوات
- سلوك الخيوط
- دورة حياة إجراءات الرسائل
- استدعاءات cron
- استرجاع الذاكرة
- تبديل النماذج
- تسليم المهام إلى عامل فرعي
- تمرير العمل إلى وكيل فرعي
- قراءة المستودع وقراءة الوثائق
- مهمة بناء صغيرة مثل Lobster Invaders
## إعداد التقارير
يصدر `qa-lab` تقرير بروتوكول بصيغة Markdown من الخط الزمني
للحافلة التي تمت ملاحظتها.
يصدر `qa-lab` تقرير بروتوكول Markdown من المخطط الزمني للناقل المرصود.
يجب أن يجيب التقرير عن:
- ما الذي نجح
- ما الذي فشل
- ما الذي ظل معطّلًا
- ما الذي بقي معطّلًا
- ما سيناريوهات المتابعة التي تستحق الإضافة
## وثائق ذات صلة
## الوثائق ذات الصلة
- [الاختبار](/ar/help/testing)
- [QA Channel](/ar/channels/qa-channel)
- [قناة QA](/ar/channels/qa-channel)
- [لوحة التحكم](/web/dashboard)

192
docs/ar/concepts/system-prompt.md
View File

@ -1,104 +1,104 @@
---
read_when:
- تحرير نص system prompt، أو قائمة الأدوات، أو أقسام الوقت/Heartbeat
- تغيير سلوك تهيئة مساحة العمل أو حقن Skills
summary: ما الذي يحتويه system prompt في OpenClaw وكيفية تجميعه
title: System Prompt
- عند تحرير نص موجّه النظام أو قائمة الأدوات أو أقسام الوقت/النبضات
- عند تغيير سلوك تهيئة مساحة العمل أو حقن Skills
summary: ما الذي يتضمنه موجّه نظام OpenClaw وكيفية تجميعه
title: موجّه النظام
x-i18n:
generated_at: "2026-04-06T03:07:26Z"
generated_at: "2026-04-08T02:14:45Z"
model: gpt-5.4
provider: openai
source_hash: f14ba7f16dda81ac973d72be05931fa246bdfa0e1068df1a84d040ebd551c236
source_hash: e55fc886bc8ec47584d07c9e60dfacd964dc69c7db976ea373877dc4fe09a79a
source_path: concepts/system-prompt.md
workflow: 15
---
# System Prompt
# موجّه النظام
يبني OpenClaw system prompt مخصصًا لكل تشغيل وكيل. ويكون prompt **مملوكًا لـ OpenClaw** ولا يستخدم prompt الافتراضي الخاص بـ pi-coding-agent.
يبني OpenClaw موجّه نظام مخصصًا لكل تشغيل وكيل. هذا الموجّه **مملوك لـ OpenClaw** ولا يستخدم الموجّه الافتراضي لـ pi-coding-agent.
يُجمَّع prompt بواسطة OpenClaw ويُحقن في كل تشغيل وكيل.
يتم تجميع الموجّه بواسطة OpenClaw وحقنه في كل تشغيل وكيل.
يمكن لإضافات المزوّدين المساهمة بإرشادات prompt واعية بالتخزين المؤقت من دون استبدال
prompt الكامل المملوك لـ OpenClaw. ويمكن لوقت تشغيل المزوّد:
يمكن لإضافات المزوّدين المساهمة بإرشادات موجّه تراعي الذاكرة المؤقتة دون استبدال
موجّه OpenClaw الكامل المملوك له. ويمكن لوقت تشغيل المزوّد أن يقوم بما يلي:
- استبدال مجموعة صغيرة من الأقسام الأساسية المسمّاة (`interaction_style`,
- استبدال مجموعة صغيرة من الأقسام الأساسية المسماة (`interaction_style`,
`tool_call_style`, `execution_bias`)
- حقن **بادئة مستقرة** فوق حد التخزين المؤقت للـ prompt
- حقن **لاحقة ديناميكية** تحت حد التخزين المؤقت للـ prompt
- حقن **بادئة ثابتة** فوق حد الذاكرة المؤقتة للموجّه
- حقن **لاحقة ديناميكية** أسفل حد الذاكرة المؤقتة للموجّه
استخدم المساهمات المملوكة للمزوّد من أجل الضبط الخاص بعائلات النماذج. وأبقِ
تعديل prompt القديم `before_prompt_build` للتوافق أو لتغييرات prompt
العالمية فعلًا، لا لسلوك المزوّد المعتاد.
استخدم المساهمات المملوكة للمزوّد لضبط السلوك الخاص بعائلة النموذج. واحتفِظ
بتعديل الموجّه القديم `before_prompt_build` من أجل التوافق أو التغييرات العامة
الحقيقية على الموجّه، وليس لسلوك المزوّد العادي.
## البنية
يُبنى prompt ليكون مضغوطًا عمدًا ويستخدم أقسامًا ثابتة:
الموجّه مضغوط عمدًا ويستخدم أقسامًا ثابتة:
- **الأدوات**: تذكير بالمصدر المرجعي للحقيقة للأدوات المهيكلة، بالإضافة إلى إرشادات وقت التشغيل لاستخدام الأدوات.
- **السلامة**: تذكير قصير بالضوابط لتجنب سلوك السعي إلى السلطة أو تجاوز الإشراف.
- **Skills** (عند توفرها): يوضح للنموذج كيفية تحميل تعليمات Skill عند الطلب.
- **التحديث الذاتي لـ OpenClaw**: كيفية فحص config بأمان باستخدام
`config.schema.lookup`، وتصحيح config باستخدام `config.patch`، واستبدال
config كاملًا باستخدام `config.apply`، وتشغيل `update.run` فقط عند طلب
صريح من المستخدم. كما أن أداة `gateway` الخاصة بالمالك فقط ترفض أيضًا
- **الأدوات**: تذكير منظّم بمصدر الحقيقة للأدوات المنظمة بالإضافة إلى إرشادات وقت التشغيل لاستخدام الأدوات.
- **السلامة**: تذكير قصير بالضوابط لتجنب السلوك الساعي إلى القوة أو تجاوز الإشراف.
- **Skills**: (عند توفرها): يوضح للنموذج كيفية تحميل تعليمات المهارة عند الطلب.
- **التحديث الذاتي لـ OpenClaw**: كيفية فحص الإعدادات بأمان باستخدام
`config.schema.lookup`، وتصحيح الإعدادات باستخدام `config.patch`، واستبدال
الإعدادات كاملة باستخدام `config.apply`، وتشغيل `update.run` فقط عند طلب
المستخدم بشكل صريح. كما أن أداة `gateway` المخصّصة للمالك فقط ترفض أيضًا
إعادة كتابة `tools.exec.ask` / `tools.exec.security`، بما في ذلك الأسماء
البديلة القديمة `tools.bash.*` التي تُطبَّع إلى مسارات exec المحمية تلك.
المستعارة القديمة `tools.bash.*` التي تُطبّع إلى مسارات exec المحمية تلك.
- **مساحة العمل**: دليل العمل (`agents.defaults.workspace`).
- **التوثيق**: المسار المحلي إلى مستندات OpenClaw (في المستودع أو حزمة npm) ومتى يجب قراءتها.
- **الوثائق**: المسار المحلي إلى وثائق OpenClaw (المستودع أو حزمة npm) ومتى يجب قراءتها.
- **ملفات مساحة العمل (محقونة)**: تشير إلى أن ملفات التهيئة الأولية مضمنة أدناه.
- **Sandbox** (عند التمكين): يشير إلى وقت تشغيل معزول، ومسارات sandbox، وما إذا كان exec المرتفع الصلاحيات متاحًا.
- **Sandbox**: (عند التمكين): تشير إلى بيئة تشغيل معزولة، ومسارات sandbox، وما إذا كان exec المرتفع الصلاحيات متاحًا.
- **التاريخ والوقت الحاليان**: الوقت المحلي للمستخدم، والمنطقة الزمنية، وتنسيق الوقت.
- **وسوم الرد**: صياغة وسوم الرد الاختيارية للمزوّدين المدعومين.
- **Heartbeats**: prompt الخاص بـ heartbeat وسلوك الإقرار.
- **وسوم الرد**: صيغة وسوم الرد الاختيارية للمزوّدين المدعومين.
- **النبضات**: موجّه النبضات وسلوك الإقرار، عند تمكين النبضات للوكيل الافتراضي.
- **وقت التشغيل**: المضيف، ونظام التشغيل، وnode، والنموذج، وجذر المستودع (عند اكتشافه)، ومستوى التفكير (سطر واحد).
- **الاستدلال**: مستوى الظهور الحالي + تلميح تبديل `/reasoning`.
- **الاستدلال**: مستوى الرؤية الحالي + تلميح تبديل `/reasoning`.
يتضمن قسم الأدوات أيضًا إرشادات وقت التشغيل للأعمال طويلة التنفيذ:
يتضمن قسم الأدوات أيضًا إرشادات وقت التشغيل للأعمال طويلة التشغيل:
- استخدم cron للمتابعة المستقبلية (`check back later`، والتذكيرات، والعمل المتكرر)
بدلًا من حلقات النوم عبر `exec`، أو حيل التأخير `yieldMs`، أو الاستطلاع المتكرر
لـ `process`
بدلًا من حلقات السكون عبر `exec`، أو حيل التأخير `yieldMs`، أو الاستطلاع
المتكرر لـ `process`
- استخدم `exec` / `process` فقط للأوامر التي تبدأ الآن وتستمر في العمل
في الخلفية
- عندما يكون إيقاظ الإكمال التلقائي ممكّنًا، ابدأ الأمر مرة واحدة واعتمد على
مسار الإيقاظ القائم على الدفع عندما يُخرج مخرجات أو يفشل
- عند تمكين تنبيه الإكمال التلقائي، ابدأ الأمر مرة واحدة واعتمد على
مسار التنبيه المعتمد على الدفع عندما يصدر مخرجات أو يفشل
- استخدم `process` للسجلات، أو الحالة، أو الإدخال، أو التدخل عندما تحتاج إلى
فحص أمر قيد التشغيل
- إذا كانت المهمة أكبر، ففضّل `sessions_spawn`; إذ إن إكمال الوكيل الفرعي
قائم على الدفع ويُعلَن تلقائيًا إلى الطالب
- لا تستطلع `subagents list` / `sessions_list` في حلقة لمجرد انتظار
الإكمال
- إذا كانت المهمة أكبر، ففضّل `sessions_spawn`؛ إذ إن إكمال الوكيل الفرعي
يعتمد على الدفع ويُعلن تلقائيًا إلى الجهة الطالبة
- لا تستطلع `subagents list` / `sessions_list` ضمن حلقة لمجرد انتظار
الاكتمال
عند تمكين أداة `update_plan` التجريبية، يخبر قسم الأدوات أيضًا
النموذج باستخدامها فقط للأعمال متعددة الخطوات غير التافهة، مع الإبقاء على
خطوة واحدة `in_progress` بالضبط، وتجنب تكرار الخطة كاملة بعد كل تحديث.
عند تمكين الأداة التجريبية `update_plan`، يوضح قسم الأدوات أيضًا
للنموذج أن يستخدمها فقط للأعمال متعددة الخطوات غير البسيطة، وأن يُبقي
خطوة واحدة فقط بحالة `in_progress`، وأن يتجنب تكرار الخطة كاملة بعد كل تحديث.
إن ضوابط السلامة في system prompt إرشادية. فهي توجه سلوك النموذج لكنها لا تفرض سياسة. استخدم سياسة الأدوات، وموافقات exec، وsandboxing، وقوائم السماح الخاصة بالقنوات لفرض القيود الصارمة؛ ويمكن للمشغّلين تعطيل هذه الأمور عمدًا.
ضوابط السلامة في موجّه النظام إرشادية. فهي توجه سلوك النموذج لكنها لا تفرض سياسة. استخدم سياسة الأدوات، وموافقات exec، وsandboxing، وقوائم السماح للقنوات من أجل فرض صارم؛ ويمكن للمشغلين تعطيل هذه الأشياء عمدًا.
في القنوات التي تحتوي على بطاقات/أزرار موافقة أصلية، يوجّه prompt وقت التشغيل الآن
الوكيل إلى الاعتماد أولًا على واجهة الموافقة الأصلية تلك. ولا ينبغي له تضمين
أمر `/approve` يدوي إلا عندما تشير نتيجة الأداة إلى أن موافقات الدردشة غير متاحة أو
في القنوات التي تحتوي على بطاقات/أزرار موافقة أصلية، يخبر موجّه وقت التشغيل الآن
الوكيل بالاعتماد أولًا على واجهة الموافقة الأصلية تلك. ويجب عليه تضمين
أمر `/approve` يدوي فقط عندما تشير نتيجة الأداة إلى أن موافقات الدردشة غير متاحة أو
أن الموافقة اليدوية هي المسار الوحيد.
## أوضاع prompt
## أوضاع الموجّه
يمكن لـ OpenClaw توليد system prompt أصغر للوكلاء الفرعيين. ويضبط وقت التشغيل
`promptMode` لكل تشغيل (وليس إعدادًا ظاهرًا للمستخدم):
يمكن لـ OpenClaw عرض موجّهات نظام أصغر للوكلاء الفرعيين. ويضبط وقت التشغيل
`promptMode` لكل تشغيل (وليس إعدادًا موجّهًا للمستخدم):
- `full` (الافتراضي): يتضمن جميع الأقسام أعلاه.
- `minimal`: يُستخدم للوكلاء الفرعيين؛ ويُسقط **Skills**، و**استدعاء الذاكرة**، و**التحديث الذاتي لـ OpenClaw**، و**أسماء النماذج البديلة**، و**هوية المستخدم**، و**وسوم الرد**،
و**المراسلة**، و**الردود الصامتة**، و**Heartbeats**. وتبقى الأدوات، و**السلامة**،
ومساحة العمل، وSandbox، و**التاريخ والوقت الحاليان** (عند المعرفة)، ووقت التشغيل، والسياق
- `minimal`: يُستخدم للوكلاء الفرعيين؛ ويحذف **Skills**، و**استدعاء الذاكرة**، و**التحديث الذاتي لـ OpenClaw**، و**الأسماء المستعارة للنماذج**، و**هوية المستخدم**، و**وسوم الرد**،
و**المراسلة**، و**الردود الصامتة**، و**النبضات**. وتبقى الأدوات، و**السلامة**،
ومساحة العمل، وSandbox، والتاريخ والوقت الحاليان (عند معرفتهما)، ووقت التشغيل، والسياق
المحقون متاحة.
- `none`: يعيد فقط سطر الهوية الأساسي.
عندما يكون `promptMode=minimal`، تُسمّى الـ prompts المحقونة الإضافية **سياق الوكيل الفرعي**
عندما يكون `promptMode=minimal`، تُوسم الموجّهات الإضافية المحقونة باسم **سياق الوكيل الفرعي**
بدلًا من **سياق الدردشة الجماعية**.
## حقن تهيئة مساحة العمل
## حقن تهيئة مساحة العمل الأولية
تُقص ملفات التهيئة الأولية وتُلحَق تحت **سياق المشروع** حتى يرى النموذج سياق الهوية والملف الشخصي من دون الحاجة إلى قراءات صريحة:
تُقص ملفات التهيئة الأولية وتُلحق ضمن **سياق المشروع** حتى يرى النموذج سياق الهوية والملف الشخصي من دون الحاجة إلى قراءات صريحة:
- `AGENTS.md`
- `SOUL.md`
@ -106,63 +106,67 @@ prompt الكامل المملوك لـ OpenClaw. ويمكن لوقت تشغيل
- `IDENTITY.md`
- `USER.md`
- `HEARTBEAT.md`
- `BOOTSTRAP.md` (في مساحات العمل الجديدة تمامًا فقط)
- `BOOTSTRAP.md` (فقط في مساحات العمل الجديدة تمامًا)
- `MEMORY.md` عند وجوده، وإلا `memory.md` كبديل بأحرف صغيرة
تُحقن كل هذه الملفات **في نافذة السياق** في كل دورة، ما
يعني أنها تستهلك tokens. أبقِها موجزة — خصوصًا `MEMORY.md`، الذي يمكن أن
يكبر مع الوقت ويؤدي إلى استخدام سياق أعلى من المتوقع وإلى ضغط أكثر تكرارًا.
تُحقن جميع هذه الملفات **في نافذة السياق** في كل دور ما لم
ينطبق قيد خاص بملف معين. ويتم حذف `HEARTBEAT.md` في التشغيلات العادية عندما
تكون النبضات معطلة للوكيل الافتراضي أو عندما يكون
`agents.defaults.heartbeat.includeSystemPromptSection` مضبوطًا على false. احرص على أن تبقى الملفات
المحقونة موجزة — وخاصة `MEMORY.md`، الذي يمكن أن ينمو بمرور الوقت ويؤدي إلى
استخدام مرتفع للسياق بشكل غير متوقع وتكثيف أكثر تكرارًا.
> **ملاحظة:** لا تُحقن ملفات `memory/*.md` اليومية **تلقائيًا**. بل
> يُوصَل إليها عند الطلب عبر الأداتين `memory_search` و`memory_get`، لذلك فهي
> لا تُحتسب ضمن نافذة السياق ما لم يقرأها النموذج صراحةً.
> **ملاحظة:** لا تُحقن الملفات اليومية `memory/*.md` **تلقائيًا**. بل
> يتم الوصول إليها عند الطلب عبر الأداتين `memory_search` و `memory_get`، لذلك فهي
> لا تُحتسب ضمن نافذة السياق ما لم يقم النموذج بقراءتها صراحة.
تُقتطع الملفات الكبيرة مع واسم. ويُتحكَّم في الحد الأقصى لحجم كل ملف عبر
`agents.defaults.bootstrapMaxChars` (الافتراضي: 20000). كما أن إجمالي محتوى التهيئة الأولية
المحقون عبر الملفات مقيّد بواسطة `agents.defaults.bootstrapTotalMaxChars`
(الافتراضي: 150000). وتحقن الملفات المفقودة واسمًا قصيرًا يدل على غياب الملف. وعند حدوث الاقتطاع،
يمكن لـ OpenClaw حقن كتلة تحذير في سياق المشروع؛ تحكم في ذلك باستخدام
`agents.defaults.bootstrapPromptTruncationWarning` ‏(`off` أو `once` أو `always`؛
تُقتطع الملفات الكبيرة مع علامة. ويتم التحكم في الحد الأقصى لحجم كل ملف عبر
`agents.defaults.bootstrapMaxChars` (الافتراضي: 20000). كما يُحدَّد إجمالي
محتوى التهيئة الأولية المحقون عبر الملفات بواسطة `agents.defaults.bootstrapTotalMaxChars`
(الافتراضي: 150000). وتحقن الملفات المفقودة علامة قصيرة تدل على غياب الملف. وعند حدوث الاقتطاع،
يمكن لـ OpenClaw حقن كتلة تحذير ضمن سياق المشروع؛ ويمكن التحكم في ذلك عبر
`agents.defaults.bootstrapPromptTruncationWarning` (`off`، `once`، `always`؛
الافتراضي: `once`).
لا تحقن جلسات الوكلاء الفرعيين إلا `AGENTS.md` و`TOOLS.md` (أما بقية ملفات التهيئة الأولية
فتُستبعد للحفاظ على صغر سياق الوكيل الفرعي).
تقوم جلسات الوكيل الفرعي بحقن `AGENTS.md` و`TOOLS.md` فقط (وتتم
تصفية ملفات التهيئة الأولية الأخرى للحفاظ على صغر سياق الوكيل الفرعي).
يمكن للـ hooks الداخلية اعتراض هذه الخطوة عبر `agent:bootstrap` لتعديل أو استبدال
يمكن للخطافات الداخلية اعتراض هذه الخطوة عبر `agent:bootstrap` لتعديل أو استبدال
ملفات التهيئة الأولية المحقونة (على سبيل المثال استبدال `SOUL.md` بشخصية بديلة).
إذا كنت تريد أن تجعل الوكيل يبدو أقل عمومية، فابدأ من
إذا كنت تريد أن تجعل الوكيل يبدو أقل عمومية، فابدأ بـ
[دليل شخصية SOUL.md](/ar/concepts/soul).
لفحص مقدار مساهمة كل ملف محقون (الخام مقابل المحقون، والاقتطاع، بالإضافة إلى الحمل الزائد لمخطط الأداة)، استخدم `/context list` أو `/context detail`. راجع [السياق](/ar/concepts/context).
## التعامل مع الوقت
يتضمن system prompt قسم **التاريخ والوقت الحاليان** مخصصًا عندما تكون
المنطقة الزمنية للمستخدم معروفة. وللحفاظ على استقرار التخزين المؤقت للـ prompt، فهو الآن يتضمن
**المنطقة الزمنية** فقط (من دون ساعة ديناميكية أو تنسيق وقت).
يتضمن موجّه النظام قسم **التاريخ والوقت الحاليان** مخصصًا عندما تكون
المنطقة الزمنية للمستخدم معروفة. وللحفاظ على ثبات الذاكرة المؤقتة للموجّه، فإنه الآن يتضمن فقط
**المنطقة الزمنية** (من دون ساعة ديناميكية أو تنسيق وقت).
استخدم `session_status` عندما يحتاج الوكيل إلى الوقت الحالي؛ إذ تتضمن بطاقة الحالة سطر طابع زمني. ويمكن للأداة نفسها أيضًا تعيين تجاوز نموذج لكل جلسة
(`model=default` يمسحه).
استخدم `session_status` عندما يحتاج الوكيل إلى الوقت الحالي؛ إذ تتضمن
بطاقة الحالة سطرًا زمنيًا. ويمكن للأداة نفسها اختياريًا تعيين تجاوز نموذج
لكل جلسة (`model=default` يمسحه).
اضبط ذلك باستخدام:
- `agents.defaults.userTimezone`
- `agents.defaults.timeFormat` ‏(`auto` | `12` | `24`)
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
راجع [التاريخ والوقت](/ar/date-time) للحصول على التفاصيل الكاملة للسلوك.
راجع [التاريخ والوقت](/ar/date-time) للحصول على تفاصيل السلوك الكاملة.
## Skills
عندما توجد Skills مؤهلة، يحقن OpenClaw **قائمة Skills متاحة مضغوطة**
عند وجود Skills مؤهلة، يحقن OpenClaw **قائمة Skills متاحة** مضغوطة
(`formatSkillsForPrompt`) تتضمن **مسار الملف** لكل Skill. ويوجه
prompt النموذج إلى استخدام `read` لتحميل ملف SKILL.md من الموقع المدرج
(مساحة العمل، أو المُدارة، أو المجمّعة). وإذا لم تكن هناك Skills مؤهلة، فسيُحذف
الموجّه النموذج إلى استخدام `read` لتحميل ملف SKILL.md في الموقع المدرج
(مساحة العمل، أو المُدار، أو المضمَّن). وإذا لم توجد Skills مؤهلة، فسيتم حذف
قسم Skills.
تشمل الأهلية بوابات بيانات Skill الوصفية، وفحوصات بيئة/إعداد وقت التشغيل،
وقائمة السماح الفعلية لـ Skills الخاصة بالوكيل عندما يكون `agents.defaults.skills` أو
`agents.list[].skills` مُكوَّنًا.
تتضمن الأهلية بوابات بيانات تعريف المهارة، وفحوصات بيئة/إعدادات وقت التشغيل،
وقائمة السماح الفعالة لـ Skills الخاصة بالوكيل عندما يكون `agents.defaults.skills` أو
`agents.list[].skills` مضبوطًا.
```
<available_skills>
@ -174,13 +178,13 @@ prompt النموذج إلى استخدام `read` لتحميل ملف SKILL.md
</available_skills>
```
يُبقي هذا prompt الأساسي صغيرًا مع الاستمرار في تمكين استخدام Skill المستهدف.
يحافظ هذا على صغر الموجّه الأساسي مع الاستمرار في تمكين استخدام مستهدف للمهارات.
## التوثيق
## الوثائق
عند توفره، يتضمن system prompt قسم **التوثيق** الذي يشير إلى
دليل مستندات OpenClaw المحلي (إما `docs/` في مساحة عمل المستودع أو مستندات حزمة npm
المجمّعة) ويذكر أيضًا النسخة العامة المطابقة، ومستودع المصدر، وDiscord الخاص بالمجتمع،
وClawHub ([https://clawhub.ai](https://clawhub.ai)) لاكتشاف Skills. ويوجه prompt النموذج إلى الرجوع إلى المستندات المحلية أولًا
لفهم سلوك OpenClaw، أو الأوامر، أو الإعدادات، أو البنية، وإلى تشغيل
`openclaw status` بنفسه عند الإمكان (وسؤال المستخدم فقط عندما لا يملك الوصول).
عند توفرها، يتضمن موجّه النظام قسم **الوثائق** الذي يشير إلى
دليل وثائق OpenClaw المحلي (إما `docs/` في مساحة عمل المستودع أو وثائق حزمة npm
المضمَّنة) ويشير أيضًا إلى النسخة العامة، ومستودع المصدر، وDiscord الخاص بالمجتمع، و
ClawHub ([https://clawhub.ai](https://clawhub.ai)) لاكتشاف Skills. ويوجه الموجّه النموذج إلى الرجوع إلى الوثائق المحلية أولًا
لسلوك OpenClaw، أو الأوامر، أو الإعدادات، أو البنية، وأن يشغّل
`openclaw status` بنفسه عندما يكون ذلك ممكنًا (وألا يسأل المستخدم إلا عندما يفتقر إلى الوصول).

195
docs/ar/gateway/cli-backends.md
View File

@ -2,46 +2,46 @@
read_when:
- تريد بديلًا موثوقًا عندما يفشل موفرو API
- أنت تشغّل Codex CLI أو غيره من واجهات AI CLI المحلية وتريد إعادة استخدامها
- تريد فهم جسر local loopback MCP لوصول أدوات الواجهة الخلفية CLI
summary: 'واجهات CLI الخلفية: بديل محلي لـ AI CLI مع جسر أدوات MCP اختياري'
- تريد فهم جسر MCP المحلي loopback للوصول إلى أدوات الواجهة الخلفية لـ CLI
summary: 'واجهات CLI الخلفية: بديل محلي لـ AI CLI مع جسر أداة MCP اختياري'
title: واجهات CLI الخلفية
x-i18n:
generated_at: "2026-04-07T07:17:29Z"
generated_at: "2026-04-08T02:14:26Z"
model: gpt-5.4
provider: openai
source_hash: f061357f420455ad6ffaabe7fe28f1fb1b1769d73a4eb2e6f45c6eb3c2e36667
source_hash: b0e8c41f5f5a8e34466f6b765e5c08585ef1788fa9e9d953257324bcc6cbc414
source_path: gateway/cli-backends.md
workflow: 15
---
# واجهات CLI الخلفية (بيئة تشغيل احتياطية)
# واجهات CLI الخلفية (بيئة تشغيل بديلة)
يمكن لـ OpenClaw تشغيل **واجهات AI CLI محلية** كـ **بديل نصي فقط** عندما تتعطل موفرو API،
أو تُقيَّد بالمعدل، أو تسيء التصرف مؤقتًا. هذا النهج متحفظ عمدًا:
يمكن لـ OpenClaw تشغيل **واجهات AI CLI المحلية** كـ **بديل نصي فقط** عندما تتعطل موفرو API،
أو تُفرض عليها حدود معدلات، أو تتصرف بشكل غير سليم مؤقتًا. هذا النهج محافظ عن قصد:
- **لا يتم حقن أدوات OpenClaw مباشرة**، لكن الواجهات الخلفية التي تحتوي على `bundleMcp: true`
يمكنها تلقي أدوات gateway عبر جسر MCP من نوع local loopback.
- **لا يتم حقن أدوات OpenClaw مباشرةً**، لكن يمكن للواجهات الخلفية التي تستخدم `bundleMcp: true`
أن تتلقى أدوات البوابة عبر جسر MCP محلي loopback.
- **بث JSONL** لواجهات CLI التي تدعمه.
- **الجلسات مدعومة** (بحيث تبقى المنعطفات اللاحقة متماسكة).
- **يمكن تمرير الصور** إذا كانت واجهة CLI تقبل مسارات الصور.
- **الجلسات مدعومة** (حتى تظل المنعطفات اللاحقة مترابطة).
- **يمكن تمرير الصور** إذا كانت CLI تقبل مسارات الصور.
تم تصميم ذلك ليكون **شبكة أمان** بدلًا من كونه مسارًا أساسيًا. استخدمه عندما
تريد ردودًا نصية "تعمل دائمًا" من دون الاعتماد على API خارجية.
هذا مصمم ليكون **شبكة أمان** بدلًا من أن يكون مسارًا أساسيًا. استخدمه عندما
تريد ردودًا نصية "تعمل دائمًا" من دون الاعتماد على واجهات API خارجية.
إذا كنت تريد بيئة تشغيل كاملة مع عناصر تحكم جلسات ACP، والمهام الخلفية،
وربط الخيوط/المحادثات، وجلسات ترميز خارجية دائمة، فاستخدم
[ACP Agents](/ar/tools/acp-agents) بدلًا من ذلك. واجهات CLI الخلفية ليست ACP.
إذا كنت تريد بيئة تشغيل كاملة مع عناصر تحكم جلسات ACP، والمهام في الخلفية،
وربط السلاسل/المحادثات، وجلسات برمجة خارجية دائمة، فاستخدم
[وكلاء ACP](/ar/tools/acp-agents) بدلًا من ذلك. واجهات CLI الخلفية ليست ACP.
## بداية سريعة مناسبة للمبتدئين
يمكنك استخدام Codex CLI **من دون أي إعدادات** (يسجل plugin OpenAI
المضمن واجهة خلفية افتراضية):
يمكنك استخدام Codex CLI **من دون أي إعداد** (إذ إن إضافة OpenAI المضمّنة
تسجّل واجهة خلفية افتراضية):
```bash
openclaw agent --message "hi" --model codex-cli/gpt-5.4
```
إذا كانت gateway تعمل تحت launchd/systemd وكان PATH محدودًا، فأضف فقط
إذا كانت بوابتك تعمل تحت launchd/systemd وكان PATH محدودًا، فأضف فقط
مسار الأمر:
```json5
@ -58,16 +58,16 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
}
```
هذا كل شيء. لا مفاتيح، ولا حاجة إلى إعدادات مصادقة إضافية تتجاوز ما تتطلبه CLI نفسها.
هذا كل شيء. لا حاجة إلى مفاتيح أو إعدادات مصادقة إضافية خارج ما تتطلبه CLI نفسها.
إذا كنت تستخدم واجهة CLI خلفية مضمنة باعتبارها **موفر الرسائل الأساسي** على
مضيف gateway، فإن OpenClaw يحمّل الآن تلقائيًا plugin المضمن المالك عندما
تشير إعداداتك صراحةً إلى تلك الواجهة الخلفية في مرجع نموذج أو تحت
إذا كنت تستخدم واجهة CLI خلفية مضمّنة باعتبارها **موفر الرسائل الأساسي** على
مضيف بوابة، فإن OpenClaw يحمّل الآن الإضافة المضمّنة المالكة تلقائيًا عندما يشير إعدادك
صراحةً إلى تلك الواجهة الخلفية في مرجع نموذج أو تحت
`agents.defaults.cliBackends`.
## استخدامه كبديل احتياطي
أضف واجهة CLI خلفية إلى قائمة البدائل الاحتياطية لديك بحيث تعمل فقط عند فشل النماذج الأساسية:
أضف واجهة CLI خلفية إلى قائمة البدائل لديك بحيث لا تعمل إلا عندما تفشل النماذج الأساسية:
```json5
{
@ -88,11 +88,11 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
ملاحظات:
- إذا كنت تستخدم `agents.defaults.models` (قائمة السماح)، فيجب أن تتضمن نماذج واجهات CLI الخلفية هناك أيضًا.
- إذا فشل الموفر الأساسي (المصادقة، أو حدود المعدل، أو انتهاء المهلة)، فسيحاول OpenClaw
استخدام واجهة CLI الخلفية بعد ذلك.
- إذا كنت تستخدم `agents.defaults.models` (قائمة سماح)، فيجب تضمين نماذج واجهة CLI الخلفية هناك أيضًا.
- إذا فشل الموفر الأساسي (المصادقة أو حدود المعدلات أو المهلات)، فسيحاول OpenClaw
استخدام واجهة CLI الخلفية بعده.
## نظرة عامة على الإعدادات
## نظرة عامة على الإعداد
توجد جميع واجهات CLI الخلفية تحت:
@ -100,14 +100,14 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
agents.defaults.cliBackends
```
يُفهرس كل إدخال بواسطة **معرّف موفر** (مثل `codex-cli` أو `my-cli`).
ويصبح معرّف الموفر هو الجزء الأيسر من مرجع النموذج:
كل إدخال يُعرَّف بواسطة **معرّف موفر** (مثل `codex-cli` أو `my-cli`).
ويصبح معرّف الموفر هو الطرف الأيسر من مرجع النموذج لديك:
```
<provider>/<model>
```
### مثال على الإعدادات
### مثال على الإعداد
```json5
{
@ -144,50 +144,50 @@ agents.defaults.cliBackends
## كيف يعمل
1. **يختار واجهة خلفية** بناءً على بادئة الموفر (`codex-cli/...`).
2. **يبني توجيه نظام** باستخدام توجيه OpenClaw نفسه + سياق مساحة العمل.
3. **ينفذ CLI** باستخدام معرّف جلسة (إذا كان مدعومًا) حتى يبقى السجل متسقًا.
4. **يحلل المخرجات** (JSON أو نص عادي) ويعيد النص النهائي.
5. **يحفظ معرّفات الجلسات** لكل واجهة خلفية، بحيث تعيد المتابعات استخدام جلسة CLI نفسها.
1. **يختار واجهة خلفية** استنادًا إلى بادئة الموفر (`codex-cli/...`).
2. **يبني موجّه نظام** باستخدام موجّه OpenClaw نفسه + سياق مساحة العمل.
3. **ينفّذ CLI** باستخدام معرّف جلسة (إذا كان مدعومًا) حتى يظل السجل متسقًا.
4. **يحلّل المخرجات** (`JSON` أو نص عادي) ويعيد النص النهائي.
5. **يحفظ معرّفات الجلسات** لكل واجهة خلفية، بحيث تعيد المنعطفات اللاحقة استخدام جلسة CLI نفسها.
<Note>
واجهة `claude-cli` الخلفية المضمنة الخاصة بـ Anthropic مدعومة مرة أخرى. أخبرنا
موظفو Anthropic أن استخدام Claude CLI بأسلوب OpenClaw مسموح به مجددًا، لذا
يتعامل OpenClaw مع استخدام `claude -p` على أنه معتمد لهذا التكامل ما لم تنشر
Anthropic سياسة جديدة.
أصبحت الواجهة الخلفية المضمّنة `claude-cli` الخاصة بـ Anthropic مدعومة مجددًا. وقد أخبرنا
موظفو Anthropic أن استخدام Claude CLI بأسلوب OpenClaw مسموح مجددًا، لذلك يتعامل OpenClaw مع
استخدام `claude -p` على أنه معتمد لهذا التكامل ما لم تنشر Anthropic
سياسة جديدة.
</Note>
## الجلسات
- إذا كانت CLI تدعم الجلسات، فاضبط `sessionArg` (مثل `--session-id`) أو
`sessionArgs` (العنصر النائب `{sessionId}`) عندما يلزم إدراج
المعرّف في عدة علامات.
- إذا كانت CLI تستخدم **أمرًا فرعيًا للاستئناف** بعلامات مختلفة، فاضبط
`resumeArgs` (يستبدل `args` عند الاستئناف) ويمكنك اختياريًا ضبط `resumeOutput`
(للاستئنافات غير المعتمدة على JSON).
`sessionArgs` (العنصر النائب `{sessionId}`) عندما يلزم إدراج المعرّف
في عدة أعلام.
- إذا كانت CLI تستخدم **أمرًا فرعيًا للاستئناف** مع أعلام مختلفة، فاضبط
`resumeArgs` (يستبدل `args` عند الاستئناف) و`resumeOutput` اختياريًا
(لحالات الاستئناف غير المعتمدة على JSON).
- `sessionMode`:
- `always`: أرسل دائمًا معرّف جلسة (UUID جديد إذا لم يكن هناك معرّف مخزن).
- `existing`: أرسل معرّف جلسة فقط إذا كان قد تم تخزينه مسبقًا.
- `none`: لا ترسل أبدًا معرّف جلسة.
- `always`: أرسل معرّف جلسة دائمًا (UUID جديد إذا لم يكن هناك معرّف مخزّن).
- `existing`: أرسل معرّف جلسة فقط إذا كان قد تم تخزينه من قبل.
- `none`: لا ترسل معرّف جلسة أبدًا.
ملاحظات حول التسلسل:
- `serialize: true` يُبقي عمليات التشغيل في المسار نفسه مرتبة.
- تسلسل معظم واجهات CLI يتم على مسار موفر واحد.
- يسقط OpenClaw إعادة استخدام جلسة CLI المخزنة عندما تتغير حالة مصادقة الواجهة الخلفية، بما في ذلك إعادة تسجيل الدخول، أو تدوير الرموز، أو تغيير بيانات اعتماد ملف تعريف المصادقة.
- `serialize: true` يحافظ على ترتيب التشغيلات ضمن المسار نفسه.
- معظم واجهات CLI تُسلسل على مسار موفر واحد.
- يسقط OpenClaw إعادة استخدام جلسة CLI المخزّنة عندما تتغير حالة مصادقة الواجهة الخلفية، بما في ذلك إعادة تسجيل الدخول، أو تدوير الرموز، أو تغيير بيانات اعتماد ملف تعريف المصادقة.
## الصور (تمرير مباشر)
إذا كانت CLI تقبل مسارات الصور، فاضبط `imageArg`:
إذا كانت CLI لديك تقبل مسارات الصور، فاضبط `imageArg`:
```json5
imageArg: "--image",
imageMode: "repeat"
```
سيكتب OpenClaw الصور المشفرة بصيغة base64 إلى ملفات مؤقتة. إذا تم ضبط `imageArg`،
فسيتم تمرير تلك المسارات كوسائط CLI. وإذا لم يكن `imageArg` موجودًا، فسيُلحق OpenClaw
مسارات الملفات بالتوجيه (حقن المسار)، وهذا يكفي لواجهات CLI التي تحمّل
سيكتب OpenClaw الصور المرمّزة base64 إلى ملفات مؤقتة. إذا تم ضبط `imageArg`، فسيتم
تمرير تلك المسارات كوسائط CLI. وإذا لم يكن `imageArg` موجودًا، فسيضيف OpenClaw
مسارات الملفات إلى الموجّه (حقن المسار)، وهذا يكفي لواجهات CLI التي تقوم بتحميل
الملفات المحلية تلقائيًا من المسارات النصية العادية.
## المدخلات / المخرجات
@ -195,19 +195,19 @@ imageMode: "repeat"
- `output: "json"` (الافتراضي) يحاول تحليل JSON واستخراج النص + معرّف الجلسة.
- بالنسبة إلى مخرجات JSON الخاصة بـ Gemini CLI، يقرأ OpenClaw نص الرد من `response` و
الاستخدام من `stats` عندما يكون `usage` مفقودًا أو فارغًا.
- `output: "jsonl"` يحلل تدفقات JSONL (مثل Codex CLI `--json`) ويستخرج رسالة العامل النهائية بالإضافة إلى
- `output: "jsonl"` يحلل تدفقات JSONL (على سبيل المثال Codex CLI `--json`) ويستخرج رسالة الوكيل النهائية بالإضافة إلى
معرّفات الجلسة عند وجودها.
- `output: "text"` يتعامل مع stdout باعتباره الاستجابة النهائية.
- `output: "text"` يتعامل مع stdout على أنه الاستجابة النهائية.
أنماط الإدخال:
أوضاع الإدخال:
- `input: "arg"` (الافتراضي) يمرر التوجيه باعتباره آخر وسيط CLI.
- `input: "stdin"` يرسل التوجيه عبر stdin.
- إذا كان التوجيه طويلًا جدًا وكان `maxPromptArgChars` مضبوطًا، فسيتم استخدام stdin.
- `input: "arg"` (الافتراضي) يمرر الموجّه باعتباره الوسيط الأخير لـ CLI.
- `input: "stdin"` يرسل الموجّه عبر stdin.
- إذا كان الموجّه طويلًا جدًا وتم ضبط `maxPromptArgChars`، فسيتم استخدام stdin.
## القيم الافتراضية (مملوكة لـ plugin)
## القيم الافتراضية (مملوكة للإضافة)
يسجل plugin OpenAI المضمن أيضًا قيمة افتراضية لـ `codex-cli`:
تسجّل إضافة OpenAI المضمّنة أيضًا قيمة افتراضية لـ `codex-cli`:
- `command: "codex"`
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
@ -218,77 +218,80 @@ imageMode: "repeat"
- `imageArg: "--image"`
- `sessionMode: "existing"`
يسجل plugin Google المضمن أيضًا قيمة افتراضية لـ `google-gemini-cli`:
وتسجّل إضافة Google المضمّنة أيضًا قيمة افتراضية لـ `google-gemini-cli`:
- `command: "gemini"`
- `args: ["--prompt", "--output-format", "json"]`
- `resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]`
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
- `resumeArgs: ["--resume", "{sessionId}", "--output-format", "json", "--prompt", "{prompt}"]`
- `imageArg: "@"`
- `imagePathScope: "workspace"`
- `modelArg: "--model"`
- `sessionMode: "existing"`
- `sessionIdFields: ["session_id", "sessionId"]`
المتطلب المسبق: يجب أن تكون Gemini CLI المحلية مثبتة ومتاحة باسم
المتطلب المسبق: يجب أن تكون Gemini CLI المحلية مثبّتة ومتاحة باسم
`gemini` على `PATH` (`brew install gemini-cli` أو
`npm install -g @google/gemini-cli`).
ملاحظات JSON الخاصة بـ Gemini CLI:
- يُقرأ نص الرد من حقل JSON `response`.
- يُقرأ نص الرد من الحقل `response` في JSON.
- يعود الاستخدام إلى `stats` عندما يكون `usage` غائبًا أو فارغًا.
- تتم تسوية `stats.cached` إلى OpenClaw `cacheRead`.
- إذا كان `stats.input` مفقودًا، يشتق OpenClaw رموز الإدخال من
- إذا كان `stats.input` مفقودًا، يستنتج OpenClaw رموز الإدخال من
`stats.input_tokens - stats.cached`.
لا تُجرِ تجاوزًا إلا عند الحاجة (الأكثر شيوعًا: مسار `command` المطلق).
قم بالتجاوز فقط عند الحاجة (والأكثر شيوعًا: مسار `command` مطلق).
## القيم الافتراضية المملوكة لـ plugin
## القيم الافتراضية المملوكة للإضافة
أصبحت القيم الافتراضية لواجهات CLI الخلفية الآن جزءًا من سطح plugin:
أصبحت القيم الافتراضية لواجهات CLI الخلفية الآن جزءًا من سطح الإضافة:
- تسجلها Plugins باستخدام `api.registerCliBackend(...)`.
- يصبح `id` الخاص بالواجهة الخلفية هو بادئة الموفر في مراجع النماذج.
- تظل إعدادات المستخدم في `agents.defaults.cliBackends.<id>` تتجاوز القيمة الافتراضية الخاصة بـ plugin.
- تبقى تنقية الإعدادات الخاصة بالواجهة الخلفية مملوكة لـ plugin من خلال الخطاف الاختياري
`normalizeConfig`.
- تسجّلها الإضافات باستخدام `api.registerCliBackend(...)`.
- يصبح `id` الخاص بالواجهة الخلفية بادئة الموفر في مراجع النماذج.
- يظل إعداد المستخدم في `agents.defaults.cliBackends.<id>` يتجاوز القيمة الافتراضية للإضافة.
- تظل عملية تنظيف الإعداد الخاصة بالواجهة الخلفية مملوكة للإضافة من خلال
الخطاف الاختياري `normalizeConfig`.
## تراكبات bundle MCP
## تراكبات Bundle MCP
لا تتلقى واجهات CLI الخلفية **استدعاءات أدوات OpenClaw مباشرة**، لكن يمكن لواجهة خلفية
أن تشترك في تراكب إعداد MCP مُولَّد عبر `bundleMcp: true`.
الاشتراك في تراكب إعداد MCP مُولَّد باستخدام `bundleMcp: true`.
السلوك المضمن الحالي:
السلوك المضمّن الحالي:
- `codex-cli`: لا يوجد تراكب bundle MCP
- `google-gemini-cli`: لا يوجد تراكب bundle MCP
- `claude-cli`: ملف إعداد MCP صارم مُولَّد
- `codex-cli`: تجاوزات إعدادات مضمنة لـ `mcp_servers`
- `google-gemini-cli`: ملف إعدادات نظام Gemini مُولَّد
عند تمكين bundle MCP، يقوم OpenClaw بما يلي:
- يشغّل خادم HTTP MCP من نوع loopback يعرّض أدوات gateway لعملية CLI
- يشغّل خادم HTTP MCP محلي loopback يعرّض أدوات البوابة لعملية CLI
- يصادق الجسر باستخدام رمز مميز لكل جلسة (`OPENCLAW_MCP_TOKEN`)
- يقيّد وصول الأدوات بسياق الجلسة والحساب والقناة الحالية
- يقيّد الوصول إلى الأدوات ضمن نطاق الجلسة الحالية والحساب وسياق القناة
- يحمّل خوادم bundle-MCP الممكّنة لمساحة العمل الحالية
- يدمجها مع أي `--mcp-config` موجود للواجهة الخلفية
- يعيد كتابة وسائط CLI لتمرير `--strict-mcp-config --mcp-config <generated-file>`
- يدمجها مع أي شكل إعداد/إعدادات MCP موجود للواجهة الخلفية
- يعيد كتابة إعدادات التشغيل باستخدام وضع التكامل المملوك للواجهة الخلفية من الامتداد المالك
إذا لم تكن أي خوادم MCP مفعّلة، فسيظل OpenClaw يحقن إعدادًا صارمًا عندما
تشترك واجهة خلفية في bundle MCP حتى تظل عمليات التشغيل الخلفية معزولة.
إذا لم تكن أي خوادم MCP ممكّنة، فسيظل OpenClaw يحقن إعدادًا صارمًا عندما
تشترك واجهة خلفية في bundle MCP حتى تظل عمليات الخلفية معزولة.
## القيود
- **لا توجد استدعاءات مباشرة لأدوات OpenClaw.** لا يحقن OpenClaw استدعاءات الأدوات ضمن
بروتوكول واجهة CLI الخلفية. لا ترى الواجهات الخلفية أدوات gateway إلا عندما تشترك في
- **لا توجد استدعاءات مباشرة لأدوات OpenClaw.** لا يحقن OpenClaw استدعاءات أدوات في
بروتوكول واجهة CLI الخلفية. لا ترى الواجهات الخلفية أدوات البوابة إلا عندما تشترك في
`bundleMcp: true`.
- **البث خاص بالواجهة الخلفية.** بعض الواجهات الخلفية تبث JSONL؛ بينما تخزن أخرى
كل شيء مؤقتًا حتى الخروج.
- **المخرجات المنظمة** تعتمد على تنسيق JSON الخاص بـ CLI.
- **جلسات Codex CLI** تُستأنف عبر مخرجات نصية (وليس JSONL)، وهو ما يجعلها أقل
- **البث خاص بكل واجهة خلفية.** بعض الواجهات الخلفية تبث JSONL؛ بينما يقوم بعضها الآخر
بالتجميع حتى الخروج.
- **المخرجات المنظَّمة** تعتمد على تنسيق JSON الخاص بـ CLI.
- **جلسات Codex CLI** تُستأنف عبر مخرجات نصية (من دون JSONL)، وهذا أقل
تنظيمًا من تشغيل `--json` الأولي. ومع ذلك، تظل جلسات OpenClaw تعمل
بشكل طبيعي.
## استكشاف الأخطاء وإصلاحها
- **لم يتم العثور على CLI**: اضبط `command` على مسار كامل.
- **اسم نموذج غير صحيح**: استخدم `modelAliases` لربط `provider/model` → نموذج CLI.
- **اسم النموذج غير صحيح**: استخدم `modelAliases` لربط `provider/model` → نموذج CLI.
- **لا يوجد استمرارية للجلسة**: تأكد من ضبط `sessionArg` وأن `sessionMode` ليس
`none` (لا يمكن لـ Codex CLI حاليًا الاستئناف بمخرجات JSON).
- **تم تجاهل الصور**: اضبط `imageArg` (وتأكد من أن CLI تدعم مسارات الملفات).
- **يتم تجاهل الصور**: اضبط `imageArg` (وتحقق من أن CLI تدعم مسارات الملفات).

1221
docs/ar/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

482
docs/ar/gateway/doctor.md
View File

@ -1,22 +1,22 @@
---
read_when:
- عند إضافة ترحيلات doctor أو تعديلها
- عند تقديم تغييرات كاسرة في الإعدادات
- عند إضافة أو تعديل ترحيلات doctor
- عند إدخال تغييرات جذرية على الإعدادات
summary: 'أمر Doctor: فحوصات السلامة، وترحيلات الإعدادات، وخطوات الإصلاح'
title: Doctor
x-i18n:
generated_at: "2026-04-07T07:18:29Z"
generated_at: "2026-04-08T02:15:41Z"
model: gpt-5.4
provider: openai
source_hash: a834dc7aec79c20d17bc23d37fb5f5e99e628d964d55bd8cf24525a7ee57130c
source_hash: 3761a222d9db7088f78215575fa84e5896794ad701aa716e8bf9039a4424dca6
source_path: gateway/doctor.md
workflow: 15
---
# Doctor
يُعد `openclaw doctor` أداة الإصلاح + الترحيل في OpenClaw. فهو يصلح
الإعدادات/الحالة القديمة، ويفحص السلامة، ويوفر خطوات إصلاح عملية.
إن `openclaw doctor` هو أداة الإصلاح + الترحيل في OpenClaw. فهو يصلح
الإعدادات/الحالة القديمة، ويتحقق من السلامة، ويوفر خطوات إصلاح قابلة للتنفيذ.
## البدء السريع
@ -30,32 +30,32 @@ openclaw doctor
openclaw doctor --yes
```
اقبل القيم الافتراضية من دون طلب تأكيد (بما في ذلك خطوات إصلاح إعادة التشغيل/الخدمة/sandbox عند الاقتضاء).
اقبل القيم الافتراضية من دون مطالبة (بما في ذلك خطوات إصلاح إعادة التشغيل/الخدمة/العزل عند الاقتضاء).
```bash
openclaw doctor --repair
```
طبّق الإصلاحات الموصى بها من دون طلب تأكيد (الإصلاحات + إعادة التشغيل حيثما كان ذلك آمنًا).
طبّق الإصلاحات الموصى بها من دون مطالبة (الإصلاحات + إعادة التشغيل عندما يكون ذلك آمنًا).
```bash
openclaw doctor --repair --force
```
طبّق أيضًا الإصلاحات المتقدمة (يكتب فوق إعدادات المشرف المخصصة).
طبّق الإصلاحات العدوانية أيضًا (يستبدل إعدادات supervisor المخصصة).
```bash
openclaw doctor --non-interactive
```
شغّل بدون مطالبات وطبّق فقط الترحيلات الآمنة (تطبيع الإعدادات + نقل الحالة على القرص). ويتخطى إجراءات إعادة التشغيل/الخدمة/sandbox التي تتطلب تأكيدًا بشريًا.
شغّل من دون مطالبات وطبّق فقط الترحيلات الآمنة (تطبيع الإعدادات + نقل الحالة على القرص). يتخطى إجراءات إعادة التشغيل/الخدمة/العزل التي تتطلب تأكيدًا بشريًا.
تعمل ترحيلات الحالة القديمة تلقائيًا عند اكتشافها.
```bash
openclaw doctor --deep
```
افحص خدمات النظام بحثًا عن تثبيتات Gateway إضافية (launchd/systemd/schtasks).
افحص خدمات النظام لاكتشاف عمليات تثبيت إضافية لـ gateway ‏(launchd/systemd/schtasks).
إذا كنت تريد مراجعة التغييرات قبل الكتابة، فافتح ملف الإعدادات أولًا:
@ -65,71 +65,71 @@ cat ~/.openclaw/openclaw.json
## ما الذي يفعله (ملخص)
- تحديث اختياري قبل التشغيل لتثبيتات git (في الوضع التفاعلي فقط).
- فحص حداثة بروتوكول واجهة المستخدم (ويعيد بناء Control UI عندما يكون مخطط البروتوكول أحدث).
- تحديث اختياري قبل التنفيذ لتثبيتات git ‏(تفاعلي فقط).
- فحص حداثة بروتوكول واجهة المستخدم (يعيد بناء Control UI عندما يكون مخطط البروتوكول أحدث).
- فحص السلامة + مطالبة بإعادة التشغيل.
- ملخص حالة Skills ‏(المؤهلة/المفقودة/المحجوبة) وحالة plugin.
- تطبيع الإعدادات للقيم القديمة.
- ترحيل إعدادات Talk من حقول `talk.*` القديمة المسطحة إلى `talk.provider` + `talk.providers.<provider>`.
- فحوصات ترحيل المتصفح لإعدادات إضافات Chrome القديمة وجاهزية Chrome MCP.
- تحذيرات تجاوز مزود OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- فحص متطلبات OAuth TLS الأساسية لملفات تعريف OpenAI Codex OAuth.
- فحوصات ترحيل المتصفح لإعدادات Chrome extension القديمة وجهوزية Chrome MCP.
- تحذيرات تجاوزات موفّر OpenCode ‏(`models.providers.opencode` / `models.providers.opencode-go`).
- تحذيرات حجب Codex OAuth ‏(`models.providers.openai-codex`).
- فحص متطلبات OAuth TLS لملفات OpenAI Codex OAuth الشخصية.
- ترحيل الحالة القديمة على القرص (الجلسات/دليل الوكيل/مصادقة WhatsApp).
- ترحيل مفتاح عقد manifest القديم لـ plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- ترحيل مخزن cron القديم (`jobId`, `schedule.cron`, حقول delivery/payload ذات المستوى الأعلى، و`provider` في payload، ووظائف webhook الاحتياطية البسيطة `notify: true`).
- فحص ملفات قفل الجلسة وتنظيف الأقفال القديمة.
- فحوصات سلامة الحالة والأذونات (الجلسات، transcripts، دليل الحالة).
- فحوصات أذونات ملف الإعدادات (chmod 600) عند التشغيل محليًا.
- سلامة مصادقة النماذج: يفحص انتهاء صلاحية OAuth، ويمكنه تحديث الرموز التي توشك على الانتهاء، ويعرض حالات التهدئة/التعطيل لملفات تعريف المصادقة.
- اكتشاف دليل workspace إضافي (`~/openclaw`).
- إصلاح صورة sandbox عند تفعيل sandboxing.
- ترحيل الخدمة القديمة واكتشاف Gateway إضافي.
- ترحيل الحالة القديمة لقناة Matrix (في وضع `--fix` / `--repair`).
- فحوصات وقت تشغيل Gateway (الخدمة مثبتة ولكنها لا تعمل؛ ووسم launchd مخزن مؤقتًا).
- تحذيرات حالة القنوات (يتم فحصها من Gateway العامل).
- تدقيق إعدادات المشرف (launchd/systemd/schtasks) مع إصلاح اختياري.
- ترحيل مفتاح عقد plugin manifest القديم (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` ← `contracts`).
- ترحيل مخزن cron القديم (`jobId`, ‏`schedule.cron`, وحقول delivery/payload ذات المستوى الأعلى، و`provider` في payload، ووظائف fallback القديمة البسيطة من نوع `notify: true` webhook).
- فحص ملف قفل الجلسة وتنظيف الأقفال القديمة.
- فحوصات تكامل الحالة والأذونات (الجلسات، والنصوص، ودليل الحالة).
- فحوصات أذونات ملف الإعدادات (`chmod 600`) عند التشغيل محليًا.
- سلامة مصادقة النموذج: يتحقق من انتهاء OAuth، ويمكنه تحديث الرموز الموشكة على الانتهاء، ويبلغ عن حالات auth-profile المهدأة/المعطلة.
- اكتشاف أدلة workspace الإضافية (`~/openclaw`).
- إصلاح صورة sandbox عند تفعيل العزل.
- ترحيل الخدمة القديمة واكتشاف gateway الإضافية.
- ترحيل الحالة القديمة لقناة Matrix ‏(في وضع `--fix` / `--repair`).
- فحوصات وقت تشغيل Gateway ‏(الخدمة مثبتة ولكنها لا تعمل؛ ووسم launchd المخزن مؤقتًا).
- تحذيرات حالة القناة (يتم فحصها من gateway الجاري تشغيله).
- تدقيق إعدادات supervisor ‏(launchd/systemd/schtasks) مع إصلاح اختياري.
- فحوصات أفضل الممارسات لوقت تشغيل Gateway ‏(Node مقابل Bun، ومسارات مديري الإصدارات).
- تشخيص تعارض منفذ Gateway ‏(الافتراضي `18789`).
- تحذيرات أمنية لسياسات DM المفتوحة.
- فحوصات مصادقة Gateway لوضع الرمز المحلي (يوفر إنشاء رمز عند عدم وجود مصدر رمز؛ ولا يكتب فوق إعدادات token SecretRef).
- فحوصات مصادقة Gateway لوضع الرمز المحلي (يعرض توليد رمز عند عدم وجود مصدر للرمز؛ ولا يستبدل إعدادات token SecretRef).
- فحص systemd linger على Linux.
- فحص حجم ملف bootstrap في workspace (تحذيرات الاقتطاع/الاقتراب من الحد لملفات السياق).
- فحص حجم ملف bootstrap في workspace ‏(تحذيرات الاقتطاع/الاقتراب من الحد لملفات السياق).
- فحص حالة shell completion والتثبيت/الترقية التلقائيين.
- فحص جاهزية مزود embedding الخاص ببحث الذاكرة (نموذج محلي، أو مفتاح API بعيد، أو ملف QMD تنفيذي).
- فحص جهوزية موفّر embedding لبحث الذاكرة (نموذج محلي، أو مفتاح API بعيد، أو ملف QMD تنفيذي).
- فحوصات تثبيت المصدر (عدم تطابق pnpm workspace، وغياب أصول UI، وغياب ملف tsx التنفيذي).
- يكتب الإعدادات المحدَّثة + بيانات wizard الوصفية.
- يكتب الإعدادات المحدّثة + بيانات wizard الوصفية.
## السلوك المفصل والمبررات
## السلوك التفصيلي والمبررات
### 0) تحديث اختياري (تثبيتات git)
إذا كان هذا مستودع git checkout وكان doctor يعمل في الوضع التفاعلي، فسيعرض
إذا كان هذا مستخرج git وكان doctor يعمل في وضع تفاعلي، فإنه يعرض
التحديث (fetch/rebase/build) قبل تشغيل doctor.
### 1) تطبيع الإعدادات
إذا احتوت الإعدادات على أشكال قيم قديمة (على سبيل المثال `messages.ackReaction`
من دون تجاوز خاص بالقناة)، يقوم doctor بتطبيعها إلى
المخطط الحالي.
إذا كانت الإعدادات تحتوي على أشكال قيم قديمة (مثل `messages.ackReaction`
من دون تجاوز خاص بالقناة)، فإن doctor يطبعها إلى المخطط الحالي.
ويشمل ذلك حقول Talk القديمة المسطحة. إعدادات Talk العامة الحالية هي
ويتضمن ذلك حقول Talk القديمة المسطحة. إعداد Talk العام الحالي هو
`talk.provider` + `talk.providers.<provider>`. ويعيد doctor كتابة
أشكال `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
`talk.apiKey` القديمة إلى خريطة المزود.
الأشكال القديمة `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
`talk.apiKey` إلى خريطة الموفّر.
### 2) ترحيلات مفاتيح الإعدادات القديمة
عندما تحتوي الإعدادات على مفاتيح مهجورة، ترفض الأوامر الأخرى التشغيل وتطلب
عندما تحتوي الإعدادات على مفاتيح متقادمة، ترفض الأوامر الأخرى التشغيل وتطلب
منك تشغيل `openclaw doctor`.
سيقوم Doctor بما يلي:
- شرح مفاتيح الإعدادات القديمة التي تم العثور عليها.
- عرض الترحيل الذي طبقه.
- إعادة كتابة `~/.openclaw/openclaw.json` بالمخطط المحدّث.
- يشرح أي مفاتيح قديمة تم العثور عليها.
- يعرض الترحيل الذي طبقه.
- يعيد كتابة `~/.openclaw/openclaw.json` بالمخطط المحدّث.
كما يشغّل Gateway ترحيلات doctor تلقائيًا عند بدء التشغيل عندما يكتشف
تنسيق إعدادات قديمًا، بحيث يتم إصلاح الإعدادات القديمة بدون تدخل يدوي.
كما أن Gateway يشغّل ترحيلات doctor تلقائيًا عند بدء التشغيل عندما يكتشف
تنسيق إعدادات قديمًا، بحيث تُصلح الإعدادات القديمة من دون تدخل يدوي.
تتم معالجة ترحيلات مخزن وظائف Cron بواسطة `openclaw doctor --fix`.
الترحيلات الحالية:
@ -141,7 +141,7 @@ cat ~/.openclaw/openclaw.json
- `routing.queue` → `messages.queue`
- `routing.bindings` → `bindings` في المستوى الأعلى
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
- `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` القديمة → `talk.provider` + `talk.providers.<provider>`
- القديم `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
@ -154,348 +154,356 @@ cat ~/.openclaw/openclaw.json
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold`
→ `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- بالنسبة إلى القنوات التي تحتوي على `accounts` مسماة مع بقاء قيم قناة ذات مستوى أعلى مخصصة لحساب واحد، انقل تلك القيم ذات النطاق الخاص بالحساب إلى الحساب المُرقّى المختار لتلك القناة (`accounts.default` لمعظم القنوات؛ ويمكن لـ Matrix الحفاظ على هدف مسمى/افتراضي موجود ومطابق)
- بالنسبة للقنوات التي تحتوي على `accounts` مسماة ولكن لا تزال فيها قيم قنوات ذات حساب واحد على المستوى الأعلى، انقل تلك القيم ذات النطاق الخاص بالحساب إلى الحساب المُرقّى المختار لتلك القناة (`accounts.default` لمعظم القنوات؛ ويمكن لـ Matrix الاحتفاظ بهدف مسمى/افتراضي مطابق موجود)
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` ‏(tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
→ `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- إزالة `browser.relayBindHost` (إعداد relay قديم للإضافة)
- إزالة `browser.relayBindHost` ‏(إعداد relay قديم للامتداد)
تتضمن تحذيرات Doctor أيضًا إرشادات حول الحساب الافتراضي للقنوات متعددة الحسابات:
- إذا تم ضبط إدخالين أو أكثر ضمن `channels.<channel>.accounts` بدون `channels.<channel>.defaultAccount` أو `accounts.default`، فسيحذر doctor من أن توجيه fallback قد يختار حسابًا غير متوقع.
- إذا تم ضبط `channels.<channel>.defaultAccount` على معرّف حساب غير معروف، فسيحذر doctor ويعرض معرّفات الحسابات المضبوطة.
- إذا تم إعداد إدخالين أو أكثر في `channels.<channel>.accounts` من دون `channels.<channel>.defaultAccount` أو `accounts.default`، فإن doctor يحذر من أن التوجيه الاحتياطي قد يختار حسابًا غير متوقع.
- إذا تم تعيين `channels.<channel>.defaultAccount` إلى معرّف حساب غير معروف، فإن doctor يحذر ويسرد معرّفات الحسابات المهيأة.
### 2b) تجاوزات مزود OpenCode
### 2b) تجاوزات موفّر OpenCode
إذا كنت قد أضفت `models.providers.opencode` أو `opencode-zen` أو `opencode-go`
يدويًا، فإنه يتجاوز كتالوج OpenCode المضمّن من `@mariozechner/pi-ai`.
وقد يؤدي ذلك إلى فرض النماذج على API غير صحيح أو تصفير التكاليف. يحذّر doctor حتى
تتمكن من إزالة التجاوز واستعادة توجيه API والتكاليف لكل نموذج.
يدويًا، فإنه يتجاوز كتالوج OpenCode المدمج القادم من `@mariozechner/pi-ai`.
وقد يفرض ذلك النماذج على API خاطئ أو يصفر التكاليف. ويحذر doctor لكي
تزيل التجاوز وتستعيد توجيه API + التكاليف لكل نموذج.
### 2c) ترحيل المتصفح وجاهزية Chrome MCP
### 2c) ترحيل المتصفح وجهوزية Chrome MCP
إذا كانت إعدادات متصفحك لا تزال تشير إلى مسار إضافة Chrome الذي تمت إزالته، فإن doctor
يقوم بتطبيعها إلى نموذج الإرفاق الحالي لـ Chrome MCP المحلي على المضيف:
إذا كانت إعدادات متصفحك لا تزال تشير إلى مسار Chrome extension الذي تمت إزالته، فإن doctor
يطبعها إلى نموذج الإرفاق الحالي المحلي للمضيف Chrome MCP:
- `browser.profiles.*.driver: "extension"` تصبح `"existing-session"`
- تتم إزالة `browser.relayBindHost`
كما يدقّق doctor في مسار Chrome MCP المحلي على المضيف عندما تستخدم `defaultProfile:
"user"` أو ملف تعريف `existing-session` مضبوط:
كما يقوم doctor بتدقيق المسار المحلي للمضيف Chrome MCP عندما تستخدم `defaultProfile:
"user"` أو ملف `existing-session` شخصي مهيأ:
- يفحص ما إذا كان Google Chrome مثبتًا على نفس المضيف لملفات التعريف
ذات الاتصال التلقائي الافتراضي
- يفحص إصدار Chrome المكتشف ويحذر إذا كان أقل من Chrome 144
- يذكّرك بتمكين remote debugging في صفحة inspect الخاصة بالمتصفح (على
سبيل المثال `chrome://inspect/#remote-debugging` أو `brave://inspect/#remote-debugging`
- يتحقق مما إذا كان Google Chrome مثبتًا على المضيف نفسه لملفات
الاتصال التلقائي الافتراضية
- يتحقق من إصدار Chrome المكتشف ويحذر عندما يكون أقل من Chrome 144
- يذكّرك بتمكين التصحيح عن بُعد في صفحة فحص المتصفح (مثل
`chrome://inspect/#remote-debugging` أو `brave://inspect/#remote-debugging`
أو `edge://inspect/#remote-debugging`)
لا يستطيع doctor تمكين الإعداد في Chrome نيابةً عنك. لا يزال Chrome MCP المحلي على المضيف
لا يمكن لـ Doctor تمكين الإعداد من جهة Chrome نيابةً عنك. ولا يزال Chrome MCP المحلي للمضيف
يتطلب:
- متصفحًا قائمًا على Chromium بإصدار 144+ على مضيف gateway/node
- تشغيل المتصفح محليًا
- تمكين remote debugging في ذلك المتصفح
- الموافقة على مطالبة الإذن الأولى بالإرفاق في المتصفح
- أن يكون المتصفح قيد التشغيل محليًا
- تمكين التصحيح عن بُعد في ذلك المتصفح
- الموافقة على أول مطالبة موافقة على الإرفاق في المتصفح
الجاهزية هنا تتعلق فقط بمتطلبات الإرفاق المحلي. يحتفظ existing-session
بقيود مسار Chrome MCP الحالية؛ أما المسارات المتقدمة مثل `responsebody` وتصدير PDF
واعتراض التنزيلات والإجراءات المجمعة فما تزال تتطلب
متصفحًا مُدارًا أو ملف تعريف CDP خام.
الجهوزية هنا تتعلق فقط بمتطلبات الإرفاق المحلي. ولا يزال existing-session
يحتفظ بحدود مسارات Chrome MCP الحالية؛ أما المسارات المتقدمة مثل `responsebody` وتصدير PDF
واعتراض التنزيلات وإجراءات الدُفعات فلا تزال تتطلب
متصفحًا مُدارًا أو ملف CDP شخصيًا خامًا.
لا ينطبق هذا الفحص على تدفقات Docker أو sandbox أو remote-browser أو غيرها من
التدفقات بدون واجهة. إذ تواصل تلك استخدام CDP الخام.
لا ينطبق هذا الفحص **على** تدفقات Docker أو sandbox أو remote-browser أو التدفقات
الأخرى عديمة الواجهة. فهي تواصل استخدام CDP الخام.
### 2d) متطلبات OAuth TLS الأساسية
### 2d) متطلبات OAuth TLS المسبقة
عندما يتم ضبط ملف تعريف OpenAI Codex OAuth، يقوم doctor بفحص نقطة
تفويض OpenAI للتحقق من أن مكدس TLS المحلي في Node/OpenSSL يمكنه
التحقق من سلسلة الشهادات. إذا فشل الفحص بخطأ في الشهادة (على
سبيل المثال `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` أو شهادة منتهية أو شهادة موقعة ذاتيًا)،
فسيعرض doctor إرشادات إصلاح خاصة بالمنصة. على macOS مع Node من Homebrew،
يكون الإصلاح عادةً `brew postinstall ca-certificates`. ومع `--deep`، يُشغَّل الفحص
حتى لو كانت حالة Gateway سليمة.
عندما يتم إعداد ملف OpenAI Codex OAuth شخصي، يقوم doctor بفحص نقطة نهاية
التفويض الخاصة بـ OpenAI للتحقق من أن مكدس TLS المحلي في Node/OpenSSL يمكنه
التحقق من سلسلة الشهادات. إذا فشل الفحص بسبب خطأ في الشهادة (مثل
`UNABLE_TO_GET_ISSUER_CERT_LOCALLY` أو شهادة منتهية أو شهادة موقعة ذاتيًا)،
فإن doctor يطبع إرشادات إصلاح خاصة بالنظام. على macOS مع Node من Homebrew،
يكون الإصلاح عادةً `brew postinstall ca-certificates`. ومع `--deep`، يعمل
الفحص حتى لو كانت gateway سليمة.
### 3) ترحيلات الحالة القديمة (تخطيط القرص)
### 2c) تجاوزات موفّر Codex OAuth
يمكن لـ Doctor ترحيل تخطيطات القرص القديمة إلى البنية الحالية:
إذا كنت قد أضفت سابقًا إعدادات نقل OpenAI القديمة ضمن
`models.providers.openai-codex`، فقد تحجب مسار
موفّر Codex OAuth المدمج الذي تستخدمه الإصدارات الأحدث تلقائيًا. ويحذر doctor عند رؤيته
هذه الإعدادات القديمة للنقل إلى جانب Codex OAuth لكي تتمكن من إزالة أو إعادة كتابة
تجاوز النقل القديم واستعادة سلوك التوجيه/الاحتياط المدمج.
لا تزال البروكسيات المخصصة وتجاوزات الترويسات فقط مدعومة ولا تؤدي إلى هذا التحذير.
- مخزن الجلسات + transcripts:
### 3) ترحيلات الحالة القديمة (بنية القرص)
يمكن لـ Doctor ترحيل البُنى القديمة على القرص إلى البنية الحالية:
- مخزن الجلسات + النصوص:
- من `~/.openclaw/sessions/` إلى `~/.openclaw/agents/<agentId>/sessions/`
- دليل الوكيل:
- من `~/.openclaw/agent/` إلى `~/.openclaw/agents/<agentId>/agent/`
- حالة مصادقة WhatsApp ‏(Baileys):
- من `~/.openclaw/credentials/*.json` القديمة (باستثناء `oauth.json`)
- إلى `~/.openclaw/credentials/whatsapp/<accountId>/...` (معرّف الحساب الافتراضي: `default`)
- إلى `~/.openclaw/credentials/whatsapp/<accountId>/...` ‏(معرّف الحساب الافتراضي: `default`)
هذه الترحيلات تُنفَّذ بأفضل جهد وهي idempotent؛ وسيصدر doctor تحذيرات عندما
يترك أي مجلدات قديمة كنسخ احتياطية. كما يقوم Gateway/CLI بترحيل
الجلسات القديمة + دليل الوكيل تلقائيًا عند بدء التشغيل لكي تنتقل
السجلات/المصادقة/النماذج إلى مسار كل وكيل من دون تشغيل doctor يدويًا. أما مصادقة WhatsApp
فيتم ترحيلها عمدًا فقط عبر `openclaw doctor`. كما أن تطبيع provider/provider-map لـ Talk
يقارن الآن بالمساواة البنيوية، لذلك لم تعد الفروقات الناتجة فقط عن ترتيب المفاتيح
تسبب تغييرات `doctor --fix` متكررة عديمة الأثر.
هذه الترحيلات تبذل أفضل جهد وهي قابلة للتكرار بأمان؛ وسيُصدر doctor تحذيرات عندما
يترك أي مجلدات قديمة خلفه كنسخ احتياطية. كما أن Gateway/CLI يرحّلان تلقائيًا
الجلسات القديمة + دليل الوكيل عند بدء التشغيل بحيث تهبط السجلات/المصادقة/النماذج في
المسار الخاص بكل وكيل من دون تشغيل doctor يدويًا. أما مصادقة WhatsApp فمقصود
أن تُرحّل فقط عبر `openclaw doctor`. كما أن تطبيع موفّر Talk/خريطة الموفّرين
يقارن الآن بالمساواة البنيوية، لذلك لم تعد الفروق في ترتيب المفاتيح فقط
تؤدي إلى تغييرات متكررة عديمة الأثر في `doctor --fix`.
### 3a) ترحيلات manifest القديمة لـ plugin
### 3a) ترحيلات plugin manifest القديمة
يفحص Doctor جميع manifest الخاصة بالـ plugin المثبتة بحثًا عن مفاتيح
الإمكانات القديمة ذات المستوى الأعلى (`speechProviders`, `realtimeTranscriptionProviders`,
يفحص Doctor جميع plugin manifests المثبتة بحثًا عن مفاتيح
القدرات العلوية المتقادمة (`speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`,
`webSearchProviders`). وعند العثور عليها، يعرض نقلها إلى الكائن `contracts`
وإعادة كتابة ملف manifest في مكانه. هذا الترحيل idempotent؛
وإذا كان المفتاح `contracts` يحتوي بالفعل على القيم نفسها، تتم إزالة
المفتاح القديم من دون تكرار البيانات.
`webSearchProviders`). وعند العثور عليها، يعرض نقلها إلى كائن `contracts`
وإعادة كتابة ملف manifest في مكانه. هذا الترحيل قابل للتكرار بأمان؛
إذا كان مفتاح `contracts` يحتوي بالفعل على القيم نفسها، فإن المفتاح القديم يُزال
من دون تكرار البيانات.
### 3b) ترحيلات مخزن cron القديمة
يفحص Doctor أيضًا مخزن وظائف cron ‏(`~/.openclaw/cron/jobs.json` افتراضيًا،
أو `cron.store` عند التجاوز) بحثًا عن أشكال وظائف قديمة ما يزال المجدول
يتحقق Doctor أيضًا من مخزن وظائف cron ‏(`~/.openclaw/cron/jobs.json` افتراضيًا،
أو `cron.store` عند تجاوزه) بحثًا عن أشكال وظائف قديمة لا يزال المجدول
يقبلها للتوافق.
تتضمن عمليات تنظيف cron الحالية:
تنظيفات cron الحالية تشمل:
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- حقول payload ذات المستوى الأعلى (`message`, `model`, `thinking`, ...) → `payload`
- حقول delivery ذات المستوى الأعلى (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- الأسماء البديلة للتسليم `provider` في payload → `delivery.channel` صريح
- وظائف webhook الاحتياطية القديمة البسيطة `notify: true` → `delivery.mode="webhook"` صريح مع `delivery.to=cron.webhook`
- أسماء delivery البديلة في `provider` داخل payload → `delivery.channel` صريح
- وظائف fallback القديمة البسيطة من نوع `notify: true` webhook → `delivery.mode="webhook"` صريح مع `delivery.to=cron.webhook`
لا يرحّل Doctor تلقائيًا وظائف `notify: true` إلا عندما يتمكن من ذلك
من دون تغيير السلوك. وإذا جمعت وظيفة ما بين fallback notify قديم ووضع
delivery موجود ليس webhook، فسيحذر doctor ويترك تلك الوظيفة للمراجعة اليدوية.
لا يرحّل Doctor وظائف `notify: true` تلقائيًا إلا عندما يستطيع فعل ذلك من دون
تغيير السلوك. وإذا كانت الوظيفة تجمع بين fallback الإشعار القديم ووضع
delivery موجود غير webhook، فإن doctor يحذر ويترك تلك الوظيفة للمراجعة اليدوية.
### 3c) تنظيف قفل الجلسة
يفحص Doctor كل دليل جلسات وكلاء بحثًا عن ملفات write-lock قديمة — وهي ملفات
تُترك خلفها عندما تنتهي الجلسة بشكل غير طبيعي. ولكل ملف قفل يعثر عليه، يعرض:
المسار وPID وما إذا كان PID ما يزال حيًا وعمر القفل وما إذا كان
يُعتبر قديمًا (PID ميت أو أقدم من 30 دقيقة). في وضع `--fix` / `--repair`
يقوم بإزالة ملفات القفل القديمة تلقائيًا؛ وإلا فإنه يطبع ملاحظة
يفحص Doctor كل دليل جلسات وكلاء بحثًا عن ملفات write-lock قديمة —
أي الملفات التي تُترك خلفها عندما تخرج الجلسة بشكل غير طبيعي. ولكل ملف قفل يعثر عليه يبلغ عن:
المسار، وPID، وما إذا كان PID ما يزال حيًا، وعمر القفل، وما إذا كان
يُعد قديمًا (PID ميت أو أقدم من 30 دقيقة). وفي وضع `--fix` / `--repair`
فإنه يزيل ملفات القفل القديمة تلقائيًا؛ وإلا فإنه يطبع ملاحظة
ويطلب منك إعادة التشغيل باستخدام `--fix`.
### 4) فحوصات سلامة الحالة (استمرارية الجلسة، والتوجيه، والسلامة)
### 4) فحوصات تكامل الحالة (استمرارية الجلسة، والتوجيه، والسلامة)
يُعد دليل الحالة بمثابة جذع الدماغ التشغيلي. فإذا اختفى، ستفقد
الجلسات وبيانات الاعتماد والسجلات والإعدادات (ما لم تكن لديك نسخ احتياطية في مكان آخر).
دليل الحالة هو الجذع التشغيلي الأساسي. وإذا اختفى، فستفقد
الجلسات، وبيانات الاعتماد، والسجلات، والإعدادات (ما لم تكن لديك نسخ احتياطية في مكان آخر).
يفحص Doctor ما يلي:
يتحقق Doctor من:
- **دليل الحالة مفقود**: يحذر من فقدان الحالة الكارثي، ويطلب إعادة إنشاء
الدليل، ويذكّرك بأنه لا يستطيع استعادة البيانات المفقودة.
- **أذونات دليل الحالة**: يتحقق من قابلية الكتابة؛ ويعرض إصلاح الأذونات
- **غياب دليل الحالة**: يحذر من فقدان كارثي للحالة، ويطلب إعادة إنشاء
الدليل، ويذكرك بأنه لا يستطيع استعادة البيانات المفقودة.
- **أذونات دليل الحالة**: يتحقق من إمكانية الكتابة؛ ويعرض إصلاح الأذونات
(ويصدر تلميح `chown` عند اكتشاف عدم تطابق المالك/المجموعة).
- **دليل حالة macOS المتزامن سحابيًا**: يحذر عندما تُحل الحالة تحت iCloud Drive
- **دليل حالة متزامن عبر السحابة على macOS**: يحذر عندما تُحل الحالة تحت iCloud Drive
(`~/Library/Mobile Documents/com~apple~CloudDocs/...`) أو
`~/Library/CloudStorage/...` لأن المسارات المدعومة بالمزامنة قد تسبب إدخال/إخراج أبطأ
وسباقات قفل/مزامنة.
- **دليل حالة Linux على SD أو eMMC**: يحذر عندما تُحل الحالة إلى
مصدر تركيب `mmcblk*`، لأن الإدخال/الإخراج العشوائي المدعوم بـ SD أو eMMC قد يكون أبطأ
ويتسبب في اهتراء أسرع مع كتابات الجلسات وبيانات الاعتماد.
- **أدلة الجلسات مفقودة**: مطلوب وجود `sessions/` ودليل مخزن الجلسة من
أجل حفظ السجل وتجنب أعطال `ENOENT`.
- **عدم تطابق transcript**: يحذر عندما تحتوي إدخالات الجلسات الحديثة على
ملفات transcript مفقودة.
- **main session “1-line JSONL”**: يضع علامة عند احتواء transcript الرئيسي على سطر واحد فقط
`~/Library/CloudStorage/...` لأن المسارات المدعومة بالمزامنة قد تسبب بطء I/O
وسباقات في القفل/المزامنة.
- **دليل حالة على SD أو eMMC في Linux**: يحذر عندما تُحل الحالة إلى مصدر ربط `mmcblk*`،
لأن I/O العشوائي المدعوم ببطاقات SD أو eMMC قد يكون أبطأ ويتعرض للتآكل
بشكل أسرع تحت عمليات كتابة الجلسات وبيانات الاعتماد.
- **غياب أدلة الجلسات**: إن `sessions/` ودليل مخزن الجلسات
مطلوبان لحفظ السجل وتجنب أعطال `ENOENT`.
- **عدم تطابق النصوص**: يحذر عندما تكون إدخالات الجلسات الحديثة تفتقد
إلى ملفات النصوص.
- **الجلسة الرئيسية "JSONL من سطر واحد"**: يعلّم عندما يحتوي النص الرئيسي على سطر واحد فقط
(السجل لا يتراكم).
- **أدلة حالة متعددة**: يحذر عند وجود عدة مجلدات `~/.openclaw` عبر
أدلة home أو عندما يشير `OPENCLAW_STATE_DIR` إلى مكان آخر (قد ينقسم السجل بين التثبيتات).
- **تذكير الوضع البعيد**: إذا كان `gateway.mode=remote`، يذكّرك doctor بتشغيله
على المضيف البعيد (فالحالة موجودة هناك).
الأدلة المنزلية أو عندما يشير `OPENCLAW_STATE_DIR` إلى مكان آخر (قد ينقسم السجل
بين التثبيتات).
- **تذكير الوضع البعيد**: إذا كان `gateway.mode=remote`، يذكرك doctor بتشغيله
على المضيف البعيد (الحالة موجودة هناك).
- **أذونات ملف الإعدادات**: يحذر إذا كان `~/.openclaw/openclaw.json`
قابلاً للقراءة من قبل المجموعة/العالم ويعرض تشديده إلى `600`.
قابلاً للقراءة من المجموعة/العالم ويعرض تشديده إلى `600`.
### 5) سلامة مصادقة النماذج (انتهاء OAuth)
### 5) سلامة مصادقة النموذج (انتهاء OAuth)
يفحص Doctor ملفات تعريف OAuth في مخزن المصادقة، ويحذر عندما تكون
الرموز على وشك الانتهاء/منتهية، ويمكنه تحديثها عندما يكون ذلك آمنًا. وإذا كان ملف
تعريف Anthropic OAuth/token قديمًا، فإنه يقترح مفتاح Anthropic API أو
مسار setup-token الخاص بـ Anthropic.
يفحص Doctor ملفات OAuth الشخصية في مخزن المصادقة، ويحذر عندما تكون الرموز
على وشك الانتهاء/منتهية، ويمكنه تحديثها عندما يكون ذلك آمنًا. وإذا كان ملف
Anthropic OAuth/token الشخصي قديمًا، فإنه يقترح مفتاح Anthropic API أو
مسار إعداد رمز Anthropic.
لا تظهر مطالبات التحديث إلا عند التشغيل تفاعليًا (TTY)؛ أما `--non-interactive`
فيتخطى محاولات التحديث.
كما يعرض Doctor أيضًا ملفات تعريف المصادقة غير القابلة للاستخدام مؤقتًا بسبب:
كما يبلغ Doctor عن ملفات المصادقة الشخصية التي تكون غير قابلة للاستخدام مؤقتًا بسبب:
- فترات تهدئة قصيرة (حدود المعدل/انقضاء المهلة/فشل المصادقة)
- فترات تهدئة قصيرة (حدود المعدل/انتهاء المهلة/فشل المصادقة)
- تعطيلات أطول (فشل الفوترة/الرصيد)
### 6) التحقق من نموذج Hooks
إذا كان `hooks.gmail.model` مضبوطًا، فإن doctor يتحقق من مرجع النموذج مقابل
الكتالوج وقائمة السماح ويحذر عندما يتعذر حله أو لا يُسمح به.
الكتالوج وقائمة السماح ويحذر عندما لا يمكن حله أو يكون غير مسموح به.
### 7) إصلاح صورة sandbox
عند تفعيل sandboxing، يفحص doctor صور Docker ويعرض بناءها أو
عند تفعيل العزل، يتحقق doctor من صور Docker ويعرض إنشاءها أو
التبديل إلى الأسماء القديمة إذا كانت الصورة الحالية مفقودة.
### 7b) تبعيات وقت التشغيل للـ plugin المضمّنة
### 7b) تبعيات وقت تشغيل plugin المضمنة
يتحقق Doctor من وجود تبعيات وقت التشغيل للـ plugin المضمّنة (على سبيل المثال
حزم وقت تشغيل plugin الخاصة بـ Discord) في جذر تثبيت OpenClaw.
إذا كان أي منها مفقودًا، فسيبلغ doctor عن الحزم ويثبتها في
وضع `openclaw doctor --fix` / `openclaw doctor --repair`.
يتحقق Doctor من وجود تبعيات وقت تشغيل plugin المضمنة (مثل
حزم وقت تشغيل Discord plugin) في جذر تثبيت OpenClaw.
إذا كان أي منها مفقودًا، فإن doctor يبلغ عن الحزم ويثبتها في وضع
`openclaw doctor --fix` / `openclaw doctor --repair`.
### 8) ترحيلات خدمة Gateway وتلميحات التنظيف
يكتشف Doctor خدمات Gateway القديمة (launchd/systemd/schtasks) و
يكتشف Doctor خدمات gateway القديمة (launchd/systemd/schtasks) و
يعرض إزالتها وتثبيت خدمة OpenClaw باستخدام منفذ gateway الحالي.
كما يمكنه أيضًا فحص الخدمات الإضافية الشبيهة بـ gateway وطباعة تلميحات للتنظيف.
تُعد خدمات OpenClaw gateway المسماة باسم ملف التعريف خدمات من الدرجة الأولى ولا
يتم وضع علامة "إضافية" عليها.
كما يمكنه فحص الخدمات الإضافية الشبيهة بـ gateway وطباعة تلميحات تنظيف.
تُعد خدمات OpenClaw gateway المسماة بحسب الملف الشخصي خدمات من الدرجة الأولى ولا
تُعلَّم على أنها "إضافية".
### 8b) ترحيل Matrix عند بدء التشغيل
عندما يكون لدى حساب قناة Matrix ترحيل حالة قديم معلّق أو قابل للتنفيذ،
عندما يكون لدى حساب قناة Matrix ترحيل حالة قديم معلق أو قابل للتنفيذ،
فإن doctor (في وضع `--fix` / `--repair`) ينشئ لقطة قبل الترحيل ثم
يشغّل خطوات الترحيل بأفضل جهد: ترحيل حالة Matrix القديمة وإعداد
الحالة المشفرة القديمة. كلتا الخطوتين غير قاتلتين؛ يتم تسجيل الأخطاء
ويستمر بدء التشغيل. أما في وضع القراءة فقط (`openclaw doctor` بدون `--fix`) فسيتم
يشغّل خطوات الترحيل بأفضل جهد: ترحيل حالة Matrix القديمة وإعداد الحالة المشفرة القديمة.
كلتا الخطوتين غير قاتلتين؛ يتم تسجيل الأخطاء ويستمر بدء التشغيل. أما في وضع القراءة فقط (`openclaw doctor` من دون `--fix`) فيتم
تخطي هذا الفحص بالكامل.
### 9) التحذيرات الأمنية
يصدر Doctor تحذيرات عندما يكون أحد الموفرين مفتوحًا على الرسائل الخاصة DM بدون قائمة سماح، أو
عندما تكون إحدى السياسات مضبوطة بطريقة خطرة.
يصدر Doctor تحذيرات عندما يكون موفّر ما مفتوحًا لرسائل DM من دون allowlist، أو
عندما تكون سياسة ما مهيأة بطريقة خطرة.
### 10) systemd linger ‏(Linux)
إذا كان يعمل كخدمة مستخدم systemd، يتأكد doctor من تفعيل lingering حتى
يبقى gateway يعمل بعد تسجيل الخروج.
إذا كان التشغيل يتم كخدمة مستخدم systemd، فإن doctor يضمن تمكين lingering بحيث
تبقى gateway حية بعد تسجيل الخروج.
### 11) حالة workspace ‏(Skills وplugins والأدلة القديمة)
يطبع Doctor ملخصًا لحالة workspace للوكيل الافتراضي:
يطبع Doctor ملخصًا عن حالة workspace للوكيل الافتراضي:
- **حالة Skills**: عدد Skills المؤهلة، وذات المتطلبات المفقودة، والمحجوبة بقائمة السماح.
- **حالة Skills**: يحسب Skills المؤهلة وتلك التي تفتقد المتطلبات وتلك المحجوبة بقائمة السماح.
- **أدلة workspace القديمة**: يحذر عند وجود `~/openclaw` أو أدلة workspace قديمة أخرى
إلى جانب workspace الحالية.
- **حالة plugin**: عدد plugins المحملة/المعطلة/التي بها أخطاء؛ ويسرد معرّفات plugin لأي
أخطاء؛ ويعرض إمكانات bundle plugin.
- **تحذيرات توافق plugin**: يضع علامة على plugins التي لديها مشكلات توافق مع
إلى جانب workspace الحالي.
- **حالة plugin**: يحسب plugins المحملة/المعطلة/ذات الأخطاء؛ ويسرد معرفات plugin لأي
أخطاء؛ ويبلغ عن قدرات bundle plugin.
- **تحذيرات توافق plugin**: يعلّم plugins التي لديها مشكلات توافق مع
وقت التشغيل الحالي.
- **تشخيصات plugin**: يعرض أي تحذيرات أو أخطاء وقت التحميل صادرة عن
plugin registry.
- **تشخيصات plugin**: يعرض أي تحذيرات أو أخطاء وقت التحميل صادرة من
سجل plugin.
### 11b) حجم ملف Bootstrap
يفحص Doctor ما إذا كانت ملفات bootstrap الخاصة بـ workspace (على سبيل المثال `AGENTS.md`،
أو `CLAUDE.md`، أو ملفات سياق أخرى يتم حقنها) قريبة من
الميزانية المكوّنة للأحرف أو تتجاوزها. ويعرض لكل ملف عدد الأحرف الخام مقابل المحقونة، ونسبة
الاقتطاع، وسبب الاقتطاع (`max/file` أو `max/total`)، وإجمالي الأحرف
المحقونة كنسبة من إجمالي الميزانية. وعندما يتم اقتطاع الملفات أو تكون قريبة من
يتحقق Doctor مما إذا كانت ملفات bootstrap في workspace ‏(مثل `AGENTS.md`,
و`CLAUDE.md`، أو ملفات السياق الأخرى المحقونة) قريبة من حد ميزانية الأحرف
أو متجاوزه. ويبلغ لكل ملف عن عدد الأحرف الخام مقابل المحقون، ونسبة الاقتطاع،
وسبب الاقتطاع (`max/file` أو `max/total`)، وإجمالي الأحرف المحقونة
بوصفها جزءًا من الميزانية الكلية. وعندما تكون الملفات مقتطعة أو قريبة من
الحد، يطبع doctor نصائح لضبط `agents.defaults.bootstrapMaxChars`
و`agents.defaults.bootstrapTotalMaxChars`.
### 11c) Shell completion
يفحص Doctor ما إذا كان tab completion مثبتًا للـ shell الحالي
يتحقق Doctor مما إذا كان إكمال التبويب مثبتًا للصدفة الحالية
(zsh أو bash أو fish أو PowerShell):
- إذا كان ملف تعريف shell يستخدم نمط completion ديناميكيًا بطيئًا
(`source <(openclaw completion ...)`)، فإن doctor يرقّيه إلى
متغير الملف المخزن مؤقتًا والأسرع.
- إذا كان completion مضبوطًا في ملف التعريف لكن ملف cache مفقودًا،
فإن doctor يعيد إنشاء cache تلقائيًا.
- إذا لم يكن completion مضبوطًا على الإطلاق، فسيعرض doctor تثبيته
(في الوضع التفاعلي فقط؛ ويتم التخطي مع `--non-interactive`).
- إذا كان ملف shell الشخصي يستخدم نمط إكمال ديناميكي بطيء
(`source <(openclaw completion ...)`)، فإن doctor يرقّيه إلى الصيغة
الأسرع المعتمدة على الملف المخزن مؤقتًا.
- إذا كان الإكمال مهيأ في الملف الشخصي ولكن ملف التخزين المؤقت مفقودًا،
فإن doctor يعيد توليد التخزين المؤقت تلقائيًا.
- إذا لم يكن هناك أي إكمال مهيأ أصلًا، فإن doctor يطلب تثبيته
(في الوضع التفاعلي فقط؛ ويتم تخطيه مع `--non-interactive`).
شغّل `openclaw completion --write-state` لإعادة إنشاء cache يدويًا.
شغّل `openclaw completion --write-state` لإعادة توليد التخزين المؤقت يدويًا.
### 12) فحوصات مصادقة Gateway ‏(الرمز المحلي)
يفحص Doctor جاهزية مصادقة رمز gateway المحلي.
يتحقق Doctor من جهوزية مصادقة رمز gateway المحلي.
- إذا كان وضع الرمز يحتاج إلى رمز ولا يوجد مصدر له، فسيعرض doctor إنشاء واحد.
- إذا كان `gateway.auth.token` مُدارًا بواسطة SecretRef ولكنه غير متاح، فسيحذر doctor ولن يكتب فوقه بنص صريح.
- يفرض `openclaw doctor --generate-gateway-token` الإنشاء فقط عند عدم ضبط أي token SecretRef.
- إذا كان وضع الرمز يحتاج إلى رمز ولا يوجد مصدر له، فإن doctor يعرض توليد واحد.
- إذا كان `gateway.auth.token` مدارًا بواسطة SecretRef ولكنه غير متاح، فإن doctor يحذر ولا يستبدله بنص صريح.
- يفرض `openclaw doctor --generate-gateway-token` التوليد فقط عندما لا يكون هناك token SecretRef مهيأ.
### 12b) إصلاحات واعية بـ SecretRef للقراءة فقط
تحتاج بعض تدفقات الإصلاح إلى فحص بيانات الاعتماد المضبوطة دون إضعاف
سلوك الفشل السريع في وقت التشغيل.
تحتاج بعض تدفقات الإصلاح إلى فحص بيانات الاعتماد المهيأة دون إضعاف سلوك الفشل السريع في وقت التشغيل.
- يستخدم `openclaw doctor --fix` الآن نموذج ملخص SecretRef نفسه للقراءة فقط كما في أوامر عائلة الحالة لإصلاحات الإعدادات المستهدفة.
- مثال: يحاول إصلاح `allowFrom` / `groupAllowFrom` `@username` في Telegram استخدام بيانات اعتماد البوت المضبوطة عندما تكون متاحة.
- إذا كان رمز Telegram bot مضبوطًا عبر SecretRef لكنه غير متاح في مسار الأمر الحالي، فإن doctor يبلغ أن بيانات الاعتماد مضبوطة لكنها غير متاحة، ويتخطى الحل التلقائي بدلًا من التعطل أو الإبلاغ خطأً عن أن الرمز مفقود.
- يستخدم `openclaw doctor --fix` الآن نموذج الملخص نفسه المعتمد على SecretRef للقراءة فقط كما في أوامر عائلة الحالة، وذلك لإصلاحات إعدادات مستهدفة.
- مثال: يحاول إصلاح Telegram `allowFrom` / `groupAllowFrom` لأسماء `@username` استخدام بيانات اعتماد البوت المهيأة عندما تكون متاحة.
- إذا كان رمز Telegram bot مهيأ عبر SecretRef ولكنه غير متاح في مسار الأمر الحالي، فإن doctor يبلغ أن بيانات الاعتماد مهيأة-لكن-غير-متاحة ويتخطى الحل التلقائي بدلًا من التعطل أو الإبلاغ خطأً عن أن الرمز مفقود.
### 13) فحص سلامة Gateway + إعادة التشغيل
يشغّل Doctor فحص سلامة ويعرض إعادة تشغيل gateway عندما يبدو
غير سليم.
يشغّل Doctor فحص سلامة ويعرض إعادة تشغيل gateway عندما تبدو
غير سليمة.
### 13b) جاهزية بحث الذاكرة
### 13b) جهوزية بحث الذاكرة
يفحص Doctor ما إذا كان مزود embedding المضبوط لبحث الذاكرة جاهزًا
للوكيل الافتراضي. ويعتمد السلوك على backend والمزود المضبوطين:
يتحقق Doctor مما إذا كان موفّر embedding المهيأ لبحث الذاكرة جاهزًا
للوكيل الافتراضي. ويعتمد السلوك على الواجهة الخلفية والموفّر المهيأين:
- **QMD backend**: يفحص ما إذا كان الملف التنفيذي `qmd` متاحًا وقابلًا للتشغيل.
وإذا لم يكن كذلك، يطبع إرشادات الإصلاح بما في ذلك حزمة npm وخيار مسار binary يدوي.
- **مزود محلي صريح**: يفحص وجود ملف نموذج محلي أو عنوان URL
معرَّف لنموذج بعيد/قابل للتنزيل. وإذا كان مفقودًا، يقترح التحويل إلى مزود بعيد.
- **مزود بعيد صريح** (`openai`, `voyage`، إلخ): يتحقق من وجود مفتاح API
في البيئة أو في مخزن المصادقة. ويطبع تلميحات إصلاح عملية إذا كان مفقودًا.
- **مزود تلقائي**: يفحص توفر النموذج المحلي أولًا، ثم يجرب كل مزود بعيد
بترتيب الاختيار التلقائي.
- **واجهة QMD الخلفية**: يفحص ما إذا كان الملف التنفيذي `qmd` متاحًا وقابلًا للتشغيل.
وإذا لم يكن كذلك، يطبع إرشادات إصلاح تتضمن حزمة npm وخيار مسار يدوي للملف التنفيذي.
- **موفّر محلي صريح**: يتحقق من وجود ملف نموذج محلي أو عنوان URL معروف
لنموذج بعيد/قابل للتنزيل. وإذا كان مفقودًا، يقترح التبديل إلى موفّر بعيد.
- **موفّر بعيد صريح** (`openai` أو `voyage` وغيرهما): يتحقق من وجود مفتاح API
في البيئة أو مخزن المصادقة. ويطبع تلميحات إصلاح قابلة للتنفيذ إذا كان مفقودًا.
- **موفّر تلقائي**: يتحقق أولًا من توفر النموذج المحلي، ثم يجرب كل موفّر بعيد
وفق ترتيب الاختيار التلقائي.
عندما تكون نتيجة فحص gateway متاحة (كانت حالة gateway سليمة وقت
الفحص)، فإن doctor يربط نتيجتها مع الإعدادات المرئية من CLI ويشير
عندما تكون نتيجة فحص gateway متاحة (كانت gateway سليمة وقت
الفحص)، فإن doctor يطابق نتيجتها مع الإعدادات المرئية في CLI ويشير
إلى أي اختلاف.
استخدم `openclaw memory status --deep` للتحقق من جاهزية embedding في وقت التشغيل.
استخدم `openclaw memory status --deep` للتحقق من جهوزية embedding في وقت التشغيل.
### 14) تحذيرات حالة القنوات
### 14) تحذيرات حالة القناة
إذا كانت حالة gateway سليمة، فسيجري doctor فحصًا لحالة القنوات ويعرض
تحذيرات مع إصلاحات مقترحة.
إذا كانت gateway سليمة، فإن doctor يشغّل فحص حالة القناة ويبلغ
عن التحذيرات مع الإصلاحات المقترحة.
### 15) تدقيق إعدادات المشرف + الإصلاح
### 15) تدقيق إعدادات Supervisor + الإصلاح
يفحص Doctor إعدادات المشرف المثبتة (launchd/systemd/schtasks) بحثًا عن
القيم الافتراضية المفقودة أو القديمة (مثل تبعيات systemd network-online و
يتحقق Doctor من إعدادات supervisor المثبتة (launchd/systemd/schtasks) بحثًا عن
الافتراضيات المفقودة أو القديمة (مثل تبعيات network-online في systemd و
تأخير إعادة التشغيل). وعندما يجد عدم تطابق، فإنه يوصي بالتحديث ويمكنه
إعادة كتابة ملف الخدمة/المهمة إلى القيم الافتراضية الحالية.
إعادة كتابة ملف الخدمة/المهمة إلى الافتراضيات الحالية.
ملاحظات:
- يطلب `openclaw doctor` التأكيد قبل إعادة كتابة إعدادات المشرف.
- يطلب `openclaw doctor` تأكيدًا قبل إعادة كتابة إعدادات supervisor.
- يقبل `openclaw doctor --yes` مطالبات الإصلاح الافتراضية.
- يطبّق `openclaw doctor --repair` الإصلاحات الموصى بها من دون مطالبات.
- يكتب `openclaw doctor --repair --force` فوق إعدادات المشرف المخصصة.
- إذا كانت مصادقة الرمز تتطلب رمزًا وكان `gateway.auth.token` مُدارًا بواسطة SecretRef، فإن تثبيت/إصلاح خدمة doctor يتحقق من SecretRef لكنه لا يحفظ قيم الرمز النصية الصريحة التي تم حلها في بيانات بيئة خدمة المشرف الوصفية.
- إذا كانت مصادقة الرمز تتطلب رمزًا وكان token SecretRef المضبوط غير محلول، فإن doctor يمنع مسار التثبيت/الإصلاح مع إرشادات عملية.
- إذا تم ضبط كل من `gateway.auth.token` و`gateway.auth.password` وكان `gateway.auth.mode` غير مضبوط، فإن doctor يمنع التثبيت/الإصلاح حتى يتم ضبط الوضع صراحةً.
- بالنسبة إلى وحدات Linux user-systemd، تتضمن فحوصات انجراف الرمز في doctor الآن كلاً من مصدري `Environment=` و`EnvironmentFile=` عند مقارنة بيانات مصادقة الخدمة الوصفية.
- يطبق `openclaw doctor --repair` الإصلاحات الموصى بها من دون مطالبات.
- يستبدل `openclaw doctor --repair --force` إعدادات supervisor المخصصة.
- إذا كانت مصادقة الرمز تتطلب رمزًا وكان `gateway.auth.token` مدارًا بواسطة SecretRef، فإن doctor عند تثبيت/إصلاح الخدمة يتحقق من SecretRef لكنه لا يحفظ قيم الرموز الصريحة المحلولة في بيانات البيئة الوصفية لخدمة supervisor.
- إذا كانت مصادقة الرمز تتطلب رمزًا وكان token SecretRef المهيأ غير محلول، فإن doctor يمنع مسار التثبيت/الإصلاح مع إرشادات قابلة للتنفيذ.
- إذا كان كل من `gateway.auth.token` و`gateway.auth.password` مهيأين وكان `gateway.auth.mode` غير مضبوط، فإن doctor يمنع التثبيت/الإصلاح حتى يُضبط الوضع صراحة.
- بالنسبة لوحدات Linux user-systemd، فإن فحوصات انجراف الرمز في doctor تشمل الآن كلا مصدري `Environment=` و`EnvironmentFile=` عند مقارنة بيانات المصادقة الوصفية للخدمة.
- يمكنك دائمًا فرض إعادة كتابة كاملة عبر `openclaw gateway install --force`.
### 16) تشخيصات وقت تشغيل Gateway + المنفذ
يفحص Doctor وقت تشغيل الخدمة (PID، وآخر حالة خروج) ويحذر عندما تكون
الخدمة مثبتة لكنها لا تعمل فعليًا. كما يفحص تعارضات المنافذ
على منفذ gateway ‏(الافتراضي `18789`) ويعرض الأسباب المحتملة (gateway يعمل بالفعل،
الخدمة مثبتة ولكنها لا تعمل فعليًا. كما يتحقق من تعارضات المنفذ
على منفذ gateway ‏(الافتراضي `18789`) ويبلغ عن الأسباب المحتملة (gateway تعمل بالفعل،
أو نفق SSH).
### 17) أفضل ممارسات وقت تشغيل Gateway
يحذر Doctor عندما تعمل خدمة gateway على Bun أو على مسار Node مُدار بإدارة الإصدارات
(`nvm`, `fnm`, `volta`, `asdf`، إلخ). تتطلب قنوات WhatsApp + Telegram وجود Node،
كما يمكن أن تتعطل مسارات مديري الإصدارات بعد الترقيات لأن الخدمة لا
تحمّل تهيئة shell الخاصة بك. يعرض doctor الترحيل إلى تثبيت Node على مستوى النظام عندما
يكون متاحًا (Homebrew/apt/choco).
يحذر Doctor عندما تعمل خدمة gateway على Bun أو على مسار Node مُدار بمدير إصدارات
(`nvm` أو `fnm` أو `volta` أو `asdf` وغيرها). تتطلب قنوات WhatsApp + Telegram استخدام Node،
وقد تتعطل مسارات مديري الإصدارات بعد الترقية لأن الخدمة لا تحمّل
تهيئة الصدفة الخاصة بك. ويعرض doctor الترحيل إلى تثبيت Node على مستوى النظام عند
توفره (Homebrew/apt/choco).
### 18) كتابة الإعدادات + بيانات wizard الوصفية
يحفظ Doctor أي تغييرات في الإعدادات ويضع ختمًا على بيانات wizard الوصفية لتسجيل
يحفظ Doctor أي تغييرات في الإعدادات ويضع بيانات وصفية لـ wizard لتسجيل
تشغيل doctor.
### 19) نصائح workspace ‏(النسخ الاحتياطي + نظام الذاكرة)
### 19) تلميحات workspace ‏(النسخ الاحتياطي + نظام الذاكرة)
يقترح Doctor نظام ذاكرة للـ workspace عند غيابه ويطبع تلميحًا للنسخ الاحتياطي
إذا لم تكن workspace تحت git بالفعل.
يقترح Doctor نظام ذاكرة لـ workspace عند غيابه ويطبع تلميح نسخ احتياطي
إذا لم يكن workspace موجودًا أصلًا تحت git.
راجع [/concepts/agent-workspace](/ar/concepts/agent-workspace) للحصول على دليل كامل
لبنية workspace والنسخ الاحتياطي باستخدام git (يُوصى باستخدام GitHub أو GitLab خاص).
راجع [/concepts/agent-workspace](/ar/concepts/agent-workspace) للحصول على دليل كامل حول
بنية workspace والنسخ الاحتياطي عبر git ‏(يوصى باستخدام GitHub أو GitLab خاص).

346
docs/ar/gateway/heartbeat.md
View File

@ -1,41 +1,41 @@
---
read_when:
- ضبط وتيرة heartbeat أو الرسائل
- اتخاذ قرار بين heartbeat وcron للمهام المجدولة
- تعديل وتيرة Heartbeat أو رسائله
- اتخاذ قرار بين Heartbeat وcron للمهام المجدولة
summary: رسائل استطلاع Heartbeat وقواعد الإشعارات
title: Heartbeat
x-i18n:
generated_at: "2026-04-05T12:43:47Z"
generated_at: "2026-04-08T02:15:34Z"
model: gpt-5.4
provider: openai
source_hash: f417b0d4453bed9022144d364521a59dec919d44cca8f00f0def005cd38b146f
source_hash: a8021d747637060eacb91ec5f75904368a08790c19f4fca32acda8c8c0a25e41
source_path: gateway/heartbeat.md
workflow: 15
---
# Heartbeat ‏(Gateway)
# Heartbeat (البوابة)
> **Heartbeat أم Cron؟** راجع [Automation & Tasks](/automation) للحصول على إرشادات حول وقت استخدام كل منهما.
> **Heartbeat أم Cron؟** راجع [الأتمتة والمهام](/ar/automation) للحصول على إرشادات حول وقت استخدام كل منهما.
يشغّل Heartbeat **أدوار وكيل دورية** في الجلسة الرئيسية حتى يتمكن النموذج من
إظهار أي شيء يحتاج إلى انتباه من دون إزعاجك برسائل متكررة.
إبراز أي شيء يحتاج إلى انتباه دون إغراقك بالرسائل.
يُعد Heartbeat دورًا مجدولًا في الجلسة الرئيسية — وهو **لا** ينشئ سجلات [background task](/automation/tasks).
فسجلات المهام مخصصة للعمل المنفصل (تشغيلات ACP، والوكلاء الفرعيون، ومهام cron المعزولة).
Heartbeat هو دور مجدول في الجلسة الرئيسية — وهو **لا** ينشئ سجلات [المهام الخلفية](/ar/automation/tasks).
سجلات المهام مخصصة للعمل المنفصل (تشغيلات ACP، والوكلاء الفرعيون، ووظائف cron المعزولة).
استكشاف الأخطاء وإصلاحها: [Scheduled Tasks](/automation/cron-jobs#troubleshooting)
استكشاف الأخطاء وإصلاحها: [المهام المجدولة](/ar/automation/cron-jobs#troubleshooting)
## البدء السريع (للمبتدئين)
## بداية سريعة (للمبتدئين)
1. اترك heartbeats مفعلة (الافتراضي هو `30m`، أو `1h` لمصادقة Anthropic OAuth/token، بما في ذلك إعادة استخدام Claude CLI) أو عيّن وتيرتك الخاصة.
2. أنشئ قائمة تحقق صغيرة في `HEARTBEAT.md` أو كتلة `tasks:` في مساحة عمل الوكيل (اختياري لكنه موصى به).
3. قرر أين يجب أن تذهب رسائل heartbeat ‏(`target: "none"` هو الافتراضي؛ اضبط `target: "last"` للتوجيه إلى آخر جهة اتصال).
4. اختياري: فعّل تسليم reasoning الخاص بـ heartbeat من أجل الشفافية.
5. اختياري: استخدم سياق bootstrap خفيفًا إذا كانت تشغيلات heartbeat تحتاج فقط إلى `HEARTBEAT.md`.
6. اختياري: فعّل الجلسات المعزولة لتجنب إرسال السجل الكامل للمحادثة في كل heartbeat.
7. اختياري: قيد heartbeats بالساعات النشطة (التوقيت المحلي).
1. اترك Heartbeat مفعّلًا (القيمة الافتراضية هي `30m`، أو `1h` لمصادقة Anthropic OAuth/الرمز، بما في ذلك إعادة استخدام Claude CLI) أو اضبط وتيرتك الخاصة.
2. أنشئ قائمة تحقق صغيرة في `HEARTBEAT.md` أو كتلة `tasks:` في مساحة عمل الوكيل (اختياري لكنه مستحسن).
3. قرر إلى أين يجب أن تذهب رسائل Heartbeat (القيمة الافتراضية هي `target: "none"`؛ اضبط `target: "last"` للتوجيه إلى آخر جهة اتصال).
4. اختياري: فعّل تسليم الاستدلال الخاص بـ Heartbeat لمزيد من الشفافية.
5. اختياري: استخدم سياق تمهيد خفيفًا إذا كانت تشغيلات Heartbeat تحتاج فقط إلى `HEARTBEAT.md`.
6. اختياري: فعّل الجلسات المعزولة لتجنب إرسال سجل المحادثة الكامل في كل Heartbeat.
7. اختياري: قيّد Heartbeats بساعات النشاط (بالتوقيت المحلي).
مثال على التكوين:
مثال على الإعدادات:
```json5
{
@ -43,10 +43,10 @@ x-i18n:
defaults: {
heartbeat: {
every: "30m",
target: "last", // تسليم صريح إلى آخر جهة اتصال (الافتراضي هو "none")
directPolicy: "allow", // الافتراضي: السماح بأهداف direct/DM؛ اضبط "block" لمنعها
lightContext: true, // اختياري: حقن HEARTBEAT.md فقط من ملفات bootstrap
isolatedSession: true, // اختياري: جلسة جديدة لكل تشغيل (من دون سجل المحادثة)
target: "last", // توصيل صريح إلى آخر جهة اتصال (الافتراضي هو "none")
directPolicy: "allow", // الافتراضي: السماح بالجهات المباشرة/الرسائل الخاصة؛ اضبط "block" لمنعها
lightContext: true, // اختياري: حقن `HEARTBEAT.md` فقط من ملفات التمهيد
isolatedSession: true, // اختياري: جلسة جديدة في كل تشغيل (من دون سجل محادثة)
// activeHours: { start: "08:00", end: "24:00" },
// includeReasoning: true, // اختياري: إرسال رسالة `Reasoning:` منفصلة أيضًا
},
@ -57,55 +57,58 @@ x-i18n:
## القيم الافتراضية
- الفاصل الزمني: `30m` ‏(أو `1h` عندما يكون وضع مصادقة Anthropic OAuth/token هو وضع المصادقة المكتشف، بما في ذلك إعادة استخدام Claude CLI). اضبط `agents.defaults.heartbeat.every` أو `agents.list[].heartbeat.every` لكل وكيل؛ واستخدم `0m` للتعطيل.
- نص المطالبة (قابل للتكوين عبر `agents.defaults.heartbeat.prompt`):
- الفاصل الزمني: `30m` (أو `1h` عندما تكون مصادقة Anthropic OAuth/الرمز هي وضع المصادقة المكتشف، بما في ذلك إعادة استخدام Claude CLI). اضبط `agents.defaults.heartbeat.every` أو `agents.list[].heartbeat.every` لكل وكيل؛ استخدم `0m` للتعطيل.
- نص الموجّه (قابل للتهيئة عبر `agents.defaults.heartbeat.prompt`):
`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
- تُرسل مطالبة heartbeat **حرفيًا** كرسالة مستخدم. وتتضمن مطالبة
النظام قسم “Heartbeat” ويتم تعليم التشغيل داخليًا.
- يتم التحقق من الساعات النشطة (`heartbeat.activeHours`) في المنطقة الزمنية المكوّنة.
وخارج هذه النافذة، يتم تخطي heartbeats حتى التوقيت التالي داخل النافذة.
- يُرسَل موجّه Heartbeat **حرفيًا** كرسالة مستخدم. يتضمن
موجّه النظام قسم “Heartbeat” فقط عندما تكون Heartbeats مفعّلة للوكيل
الافتراضي، ويكون التشغيل معلّمًا داخليًا.
- عندما يتم تعطيل Heartbeats باستخدام `0m`، تحذف التشغيلات العادية أيضًا `HEARTBEAT.md`
من سياق التمهيد حتى لا يرى النموذج تعليمات Heartbeat فقط.
- يتم التحقق من ساعات النشاط (`heartbeat.activeHours`) في المنطقة الزمنية المهيأة.
خارج النافذة، يتم تخطي Heartbeats حتى النبضة التالية داخل النافذة.
## الغرض من مطالبة heartbeat
## ما الغرض من موجّه Heartbeat
المطالبة الافتراضية واسعة عمدًا:
الموجّه الافتراضي عام عمدًا:
- **المهام الخلفية**: عبارة “Consider outstanding tasks” تدفع الوكيل إلى مراجعة
المتابعات (البريد الوارد، والتقويم، والتذكيرات، والعمل في قائمة الانتظار) وإظهار أي شيء عاجل.
- **الاطمئنان على الإنسان**: عبارة “Checkup sometimes on your human during day time” تدفع إلى
رسالة خفيفة أحيانًا مثل “هل تحتاج شيئًا؟”، لكنها تتجنب الإزعاج الليلي
باستخدام منطقتك الزمنية المحلية المكوّنة (راجع [/concepts/timezone](/concepts/timezone)).
- **المهام الخلفية**: عبارة “ضع في الاعتبار المهام المعلّقة” تدفع الوكيل إلى مراجعة
المتابعات (البريد الوارد، والتقويم، والتذكيرات، والعمل المصطف في الطابور) وإبراز أي شيء عاجل.
- **التحقق من المستخدم**: عبارة “تحقق من إنسانك أحيانًا أثناء النهار” تدفع إلى
رسالة خفيفة من حين لآخر مثل “هل تحتاج إلى شيء؟”، لكنها تتجنب الإزعاج الليلي
باستخدام منطقتك الزمنية المحلية المهيأة (راجع [/concepts/timezone](/ar/concepts/timezone)).
يمكن لـ Heartbeat التفاعل مع [background tasks](/automation/tasks) المكتملة، لكن تشغيل heartbeat نفسه لا ينشئ سجل مهمة.
يمكن لـ Heartbeat التفاعل مع [المهام الخلفية](/ar/automation/tasks) المكتملة، لكن تشغيل Heartbeat نفسه لا ينشئ سجل مهمة.
إذا كنت تريد من heartbeat أن يقوم بشيء محدد جدًا (مثل “check Gmail PubSub
stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbeat.prompt` (أو
`agents.list[].heartbeat.prompt`) على نص مخصص (يُرسل حرفيًا).
إذا كنت تريد من Heartbeat أن يفعل شيئًا محددًا جدًا (مثل “تحقق من إحصاءات Gmail PubSub”
أو “تحقق من صحة البوابة”)، فاضبط `agents.defaults.heartbeat.prompt` (أو
`agents.list[].heartbeat.prompt`) على نص مخصص (يُرسَل حرفيًا).
## عقد الاستجابة
- إذا لم يكن هناك ما يحتاج إلى انتباه، فردّ بـ **`HEARTBEAT_OK`**.
- أثناء تشغيلات heartbeat، يعامل OpenClaw الرمز `HEARTBEAT_OK` كإقرار عندما يظهر
في **بداية أو نهاية** الرد. تتم إزالة الرمز ويتم إسقاط الرد إذا كان
المحتوى المتبقي **≤ `ackMaxChars`** ‏(الافتراضي: 300).
- إذا ظهر `HEARTBEAT_OK` في **وسط** الرد، فلا تتم معاملته
بشكل خاص.
- بالنسبة إلى التنبيهات، **لا** تضمن `HEARTBEAT_OK`؛ وأعد نص التنبيه فقط.
- أثناء تشغيلات Heartbeat، يتعامل OpenClaw مع `HEARTBEAT_OK` كإقرار عندما يظهر
في **بداية أو نهاية** الرد. تتم إزالة الرمز ويُسقَط الرد
إذا كان المحتوى المتبقي **≤ `ackMaxChars`** (الافتراضي: 300).
- إذا ظهر `HEARTBEAT_OK` في **منتصف** الرد، فلا تتم معاملته
معاملة خاصة.
- للتنبيهات، **لا** تُضمّن `HEARTBEAT_OK`؛ أعد نص التنبيه فقط.
خارج heartbeats، تتم إزالة أي `HEARTBEAT_OK` عارض في بداية/نهاية الرسالة
ويتم تسجيله؛ وتُسقط الرسالة إذا كانت تحتوي فقط على `HEARTBEAT_OK`.
خارج Heartbeats، تتم إزالة أي `HEARTBEAT_OK` عارض في بداية/نهاية الرسالة
ويُسجَّل؛ وتُسقَط الرسالة إذا كانت فقط `HEARTBEAT_OK`.
## التكوين
## الإعدادات
```json5
{
agents: {
defaults: {
heartbeat: {
every: "30m", // الافتراضي: 30m (0m يعطّل)
every: "30m", // الافتراضي: 30m (يعطَّل عند 0m)
model: "anthropic/claude-opus-4-6",
includeReasoning: false, // الافتراضي: false (تسليم رسالة Reasoning: منفصلة عندما تكون متاحة)
lightContext: false, // الافتراضي: false؛ قيمة true تُبقي HEARTBEAT.md فقط من ملفات bootstrap لمساحة العمل
isolatedSession: false, // الافتراضي: false؛ قيمة true تشغّل كل heartbeat في جلسة جديدة (من دون سجل محادثة)
includeReasoning: false, // الافتراضي: false (تسليم رسالة Reasoning: منفصلة عند توفرها)
lightContext: false, // الافتراضي: false؛ true يبقي فقط `HEARTBEAT.md` من ملفات تمهيد مساحة العمل
isolatedSession: false, // الافتراضي: false؛ true يشغّل كل Heartbeat في جلسة جديدة (من دون سجل المحادثة)
target: "last", // الافتراضي: none | الخيارات: last | none | <channel id> (أساسي أو plugin، مثل "bluebubbles")
to: "+15551234567", // تجاوز اختياري خاص بالقناة
accountId: "ops-bot", // معرّف قناة متعدد الحسابات اختياري
@ -117,21 +120,21 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
}
```
### النطاق والأولوية
### النطاق والأسبقية
- يعيّن `agents.defaults.heartbeat` سلوك heartbeat العام.
- يتم دمج `agents.list[].heartbeat` فوقه؛ وإذا كان لأي وكيل كتلة `heartbeat`، فإن **هؤلاء الوكلاء فقط** هم الذين يشغّلون heartbeats.
- يضبط `channels.defaults.heartbeat` القيم الافتراضية للظهور لكل القنوات.
- يضبط `agents.defaults.heartbeat` سلوك Heartbeat العام.
- يُدمَج `agents.list[].heartbeat` فوقه؛ إذا كان لدى أي وكيل كتلة `heartbeat`، فإن **هؤلاء الوكلاء فقط** هم من يشغّلون Heartbeats.
- يضبط `channels.defaults.heartbeat` القيم الافتراضية للظهور لجميع القنوات.
- يتجاوز `channels.<channel>.heartbeat` القيم الافتراضية للقناة.
- يتجاوز `channels.<channel>.accounts.<id>.heartbeat` ‏(للقنوات متعددة الحسابات) الإعدادات لكل قناة.
- يتجاوز `channels.<channel>.accounts.<id>.heartbeat` (القنوات متعددة الحسابات) إعدادات كل قناة.
### Heartbeats لكل وكيل
إذا تضمّن أي إدخال `agents.list[]` كتلة `heartbeat`، فإن **هؤلاء الوكلاء فقط**
هم من يشغّلون heartbeats. ويتم دمج الكتلة لكل وكيل فوق `agents.defaults.heartbeat`
(بحيث يمكنك تعيين القيم المشتركة مرة واحدة ثم تجاوزها لكل وكيل).
إذا تضمّن أي إدخال في `agents.list[]` كتلة `heartbeat`، فإن **هؤلاء الوكلاء فقط**
هم من يشغّلون Heartbeats. وتُدمَج الكتلة الخاصة بكل وكيل فوق `agents.defaults.heartbeat`
(حتى تتمكن من ضبط القيم المشتركة مرة واحدة ثم تجاوزها لكل وكيل).
مثال: وكيلان، والوكيل الثاني فقط هو الذي يشغّل heartbeats.
مثال: وكيلان، والوكيل الثاني فقط هو من يشغّل Heartbeats.
```json5
{
@ -139,7 +142,7 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
defaults: {
heartbeat: {
every: "30m",
target: "last", // تسليم صريح إلى آخر جهة اتصال (الافتراضي هو "none")
target: "last", // توصيل صريح إلى آخر جهة اتصال (الافتراضي هو "none")
},
},
list: [
@ -158,9 +161,9 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
}
```
### مثال على الساعات النشطة
### مثال على ساعات النشاط
قيد heartbeats بساعات العمل في منطقة زمنية محددة:
قيّد Heartbeats بساعات العمل في منطقة زمنية محددة:
```json5
{
@ -168,11 +171,11 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
defaults: {
heartbeat: {
every: "30m",
target: "last", // تسليم صريح إلى آخر جهة اتصال (الافتراضي هو "none")
target: "last", // توصيل صريح إلى آخر جهة اتصال (الافتراضي هو "none")
activeHours: {
start: "09:00",
end: "22:00",
timezone: "America/New_York", // اختياري؛ يستخدم userTimezone إن كانت معيّنة، وإلا المنطقة الزمنية للمضيف
timezone: "America/New_York", // اختياري؛ يستخدم `userTimezone` إذا كان مضبوطًا، وإلا يستخدم المنطقة الزمنية للمضيف
},
},
},
@ -180,21 +183,21 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
}
```
خارج هذه النافذة (قبل 9 صباحًا أو بعد 10 مساءً بتوقيت الشرق)، يتم تخطي heartbeats. وسيعمل التوقيت المجدول التالي داخل النافذة بشكل طبيعي.
خارج هذه النافذة (قبل التاسعة صباحًا أو بعد العاشرة مساءً بالتوقيت الشرقي)، يتم تخطي Heartbeats. وستعمل النبضة المجدولة التالية داخل النافذة بشكل طبيعي.
### إعداد 24/7
إذا كنت تريد تشغيل heartbeats طوال اليوم، فاستخدم أحد هذين النمطين:
إذا كنت تريد تشغيل Heartbeats طوال اليوم، فاستخدم أحد هذين النمطين:
- احذف `activeHours` بالكامل (من دون تقييد بنافذة زمنية؛ وهذا هو السلوك الافتراضي).
- عيّن نافذة يوم كامل: `activeHours: { start: "00:00", end: "24:00" }`.
- اضبط نافذة يوم كامل: `activeHours: { start: "00:00", end: "24:00" }`.
لا تعيّن الوقت نفسه لكل من `start` و`end` (مثلًا `08:00` إلى `08:00`).
تُعامل هذه الحالة على أنها نافذة بعرض صفري، لذلك يتم دائمًا تخطي heartbeats.
لا تضبط القيمتين `start` و`end` على الوقت نفسه (مثل `08:00` إلى `08:00`).
تُعامَل هذه الحالة على أنها نافذة بعرض صفري، لذلك يتم دائمًا تخطي Heartbeats.
### مثال متعدد الحسابات
### مثال على الحسابات المتعددة
استخدم `accountId` لاستهداف حساب محدد على القنوات متعددة الحسابات مثل Telegram:
استخدم `accountId` لاستهداف حساب محدد في القنوات متعددة الحسابات مثل Telegram:
```json5
{
@ -223,56 +226,56 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
### ملاحظات الحقول
- `every`: الفاصل الزمني لـ heartbeat ‏(سلسلة مدة؛ وحدة القياس الافتراضية = دقائق).
- `model`: تجاوز اختياري للنموذج في تشغيلات heartbeat ‏(`provider/model`).
- `includeReasoning`: عند التمكين، يسلّم أيضًا رسالة `Reasoning:` منفصلة عندما تكون متاحة (بنفس شكل `/reasoning on`).
- `lightContext`: عندما تكون القيمة true، تستخدم تشغيلات heartbeat سياق bootstrap خفيفًا وتحتفظ فقط بـ `HEARTBEAT.md` من ملفات bootstrap الخاصة بمساحة العمل.
- `isolatedSession`: عندما تكون القيمة true، تعمل كل heartbeat في جلسة جديدة من دون سجل محادثة سابق. وتستخدم نفس نمط العزل الذي يستخدمه cron مع `sessionTarget: "isolated"`. وهذا يقلل بشكل كبير تكلفة الرموز لكل heartbeat. اجمعها مع `lightContext: true` لتحقيق أقصى توفير. ويظل توجيه التسليم يستخدم سياق الجلسة الرئيسية.
- `session`: مفتاح جلسة اختياري لتشغيلات heartbeat.
- `main` ‏(الافتراضي): الجلسة الرئيسية للوكيل.
- مفتاح جلسة صريح (انسخه من `openclaw sessions --json` أو من [sessions CLI](/cli/sessions)).
- تنسيقات مفاتيح الجلسات: راجع [Sessions](/concepts/session) و[Groups](/channels/groups).
- `every`: الفاصل الزمني لـ Heartbeat (سلسلة مدة؛ وحدة القياس الافتراضية = دقائق).
- `model`: تجاوز اختياري للنموذج في تشغيلات Heartbeat (`provider/model`).
- `includeReasoning`: عند تفعيله، يسلّم أيضًا رسالة `Reasoning:` المنفصلة عند توفرها (بالصيغة نفسها مثل `/reasoning on`).
- `lightContext`: عندما تكون قيمته true، تستخدم تشغيلات Heartbeat سياق تمهيد خفيفًا وتُبقي فقط `HEARTBEAT.md` من ملفات تمهيد مساحة العمل.
- `isolatedSession`: عندما تكون قيمته true، يعمل كل Heartbeat في جلسة جديدة من دون أي سجل محادثة سابق. ويستخدم نمط العزل نفسه مثل cron `sessionTarget: "isolated"`. ويقلل بدرجة كبيرة تكلفة الرموز لكل Heartbeat. اجمعه مع `lightContext: true` لتحقيق أكبر قدر من التوفير. يظل توجيه التسليم يستخدم سياق الجلسة الرئيسية.
- `session`: مفتاح جلسة اختياري لتشغيلات Heartbeat.
- `main` (الافتراضي): الجلسة الرئيسية للوكيل.
- مفتاح جلسة صريح (انسخه من `openclaw sessions --json` أو من [CLI الجلسات](/cli/sessions)).
- صيغ مفاتيح الجلسة: راجع [الجلسات](/ar/concepts/session) و[المجموعات](/ar/channels/groups).
- `target`:
- `last`: التسليم إلى آخر قناة خارجية مستخدمة.
- قناة صريحة: أي قناة مكوّنة أو معرّف plugin، مثل `discord` أو `matrix` أو `telegram` أو `whatsapp`.
- `none` ‏(الافتراضي): تشغيل heartbeat لكن **من دون تسليم** خارجي.
- `directPolicy`: يتحكم في سلوك التسليم المباشر/DM:
- `allow` ‏(الافتراضي): السماح بتسليم heartbeat إلى direct/DM.
- `block`: منع التسليم إلى direct/DM ‏(`reason=dm-blocked`).
- `to`: تجاوز اختياري للمستلم (معرّف خاص بالقناة، مثل E.164 لـ WhatsApp أو معرّف دردشة Telegram). وبالنسبة إلى Telegram topics/threads، استخدم `<chatId>:topic:<messageThreadId>`.
- `accountId`: معرّف حساب اختياري للقنوات متعددة الحسابات. وعندما تكون `target: "last"`، ينطبق معرّف الحساب على آخر قناة محلولة إذا كانت تدعم الحسابات؛ وإلا فيتم تجاهله. وإذا لم يطابق معرّف الحساب حسابًا مكوّنًا للقناة المحلولة، يتم تخطي التسليم.
- `prompt`: يتجاوز نص المطالبة الافتراضي (ولا يتم دمجه).
- قناة صريحة: أي قناة أو معرّف plugin مهيأ، مثل `discord` أو `matrix` أو `telegram` أو `whatsapp`.
- `none` (الافتراضي): شغّل Heartbeat لكن **لا تُسلِّمه** خارجيًا.
- `directPolicy`: يتحكم في سلوك التسليم المباشر/الرسائل الخاصة:
- `allow` (الافتراضي): السماح بتسليم Heartbeat إلى الأهداف المباشرة/الرسائل الخاصة.
- `block`: منع التسليم المباشر/الرسائل الخاصة (`reason=dm-blocked`).
- `to`: تجاوز اختياري للمستلم (معرّف خاص بالقناة، مثل E.164 لـ WhatsApp أو معرّف دردشة Telegram). بالنسبة إلى topics/threads في Telegram، استخدم `<chatId>:topic:<messageThreadId>`.
- `accountId`: معرّف حساب اختياري للقنوات متعددة الحسابات. عندما تكون `target: "last"`، يُطبَّق معرّف الحساب على آخر قناة محلولة إذا كانت تدعم الحسابات؛ وإلا يتم تجاهله. وإذا لم يطابق معرّف الحساب حسابًا مهيأً للقناة المحلولة، يتم تخطي التسليم.
- `prompt`: يتجاوز نص الموجّه الافتراضي (من دون دمج).
- `ackMaxChars`: الحد الأقصى للأحرف المسموح بها بعد `HEARTBEAT_OK` قبل التسليم.
- `suppressToolErrorWarnings`: عندما تكون القيمة true، يتم إخفاء حمولات تحذير أخطاء الأدوات أثناء تشغيلات heartbeat.
- `activeHours`: تقييد تشغيلات heartbeat بنافذة زمنية. كائن يحتوي على `start` ‏(HH:MM، شامل؛ استخدم `00:00` لبداية اليوم)، و`end` ‏(HH:MM غير شامل؛ ويُسمح بـ `24:00` لنهاية اليوم)، و`timezone` اختيارية.
- إذا حُذفت أو كانت `"user"`: تستخدم `agents.defaults.userTimezone` إن كانت معيّنة، وإلا تعود إلى المنطقة الزمنية لنظام المضيف.
- `"local"`: تستخدم دائمًا المنطقة الزمنية لنظام المضيف.
- أي معرّف IANA ‏(مثل `America/New_York`): يُستخدم مباشرة؛ وإذا كان غير صالح، يعود إلى سلوك `"user"` أعلاه.
- يجب ألا يكون `start` و`end` متساويين لنافذة نشطة؛ فالقيم المتساوية تُعامل على أنها عرض صفري (دائمًا خارج النافذة).
- خارج النافذة النشطة، يتم تخطي heartbeats حتى التوقيت التالي داخل النافذة.
- `suppressToolErrorWarnings`: عندما تكون قيمته true، يمنع حمولات تحذير أخطاء الأدوات أثناء تشغيلات Heartbeat.
- `activeHours`: يقيّد تشغيلات Heartbeat بنافذة زمنية. وهو كائن يحتوي على `start` (HH:MM، شامل؛ استخدم `00:00` لبداية اليوم) و`end` (HH:MM غير شامل؛ ويسمح بـ `24:00` لنهاية اليوم) و`timezone` اختياري.
- إذا حُذف أو كانت قيمته `"user"`: يستخدم `agents.defaults.userTimezone` إذا كان مضبوطًا، وإلا يعود إلى المنطقة الزمنية لنظام المضيف.
- `"local"`: يستخدم دائمًا المنطقة الزمنية لنظام المضيف.
- أي معرّف IANA (مثل `America/New_York`): يُستخدم مباشرة؛ وإذا كان غير صالح، يعود إلى سلوك `"user"` أعلاه.
- يجب ألا تكون `start` و`end` متساويتين في النافذة النشطة؛ إذ تُعامَل القيم المتساوية على أنها عرض صفري (أي دائمًا خارج النافذة).
- خارج النافذة النشطة، يتم تخطي Heartbeats حتى النبضة التالية داخل النافذة.
## سلوك التسليم
- تعمل Heartbeats في الجلسة الرئيسية للوكيل افتراضيًا (`agent:<id>:<mainKey>`)،
- تعمل Heartbeats افتراضيًا في الجلسة الرئيسية للوكيل (`agent:<id>:<mainKey>`)،
أو `global` عندما تكون `session.scope = "global"`. اضبط `session` للتجاوز إلى
جلسة قناة محددة (Discord/WhatsApp/إلخ).
- يؤثر `session` في سياق التشغيل فقط؛ أما التسليم فيتحكم فيه `target` و`to`.
- للتسليم إلى قناة/مستلم محدد، اضبط `target` + `to`. ومع
- يؤثر `session` فقط في سياق التشغيل؛ ويتحكم `target` و`to` في التسليم.
- للتسليم إلى قناة/مستلم محدد، اضبط `target` + `to`. مع
`target: "last"`، يستخدم التسليم آخر قناة خارجية لتلك الجلسة.
- تسمح عمليات تسليم Heartbeat بأهداف direct/DM افتراضيًا. اضبط `directPolicy: "block"` لمنع الإرسال إلى الأهداف المباشرة مع الاستمرار في تشغيل دور heartbeat.
- إذا كانت الطوابير الرئيسية مشغولة، يتم تخطي heartbeat وإعادة المحاولة لاحقًا.
- إذا جرى حل `target` إلى عدم وجود وجهة خارجية، يظل التشغيل يحدث ولكن لا
يتم إرسال أي رسالة صادرة.
- إذا كانت `showOk` و`showAlerts` و`useIndicator` كلها معطلة، فيتم تخطي التشغيل مسبقًا على أنه `reason=alerts-disabled`.
- إذا كان تسليم التنبيهات فقط معطلًا، فلا يزال بإمكان OpenClaw تشغيل heartbeat، وتحديث الطوابع الزمنية للمهام المستحقة، واستعادة الطابع الزمني للخمول للجلسة، ومنع حمولة التنبيه الخارجية.
- الردود الخاصة بـ heartbeat فقط لا **تبقي الجلسة نشطة**؛ إذ تتم استعادة قيمة `updatedAt`
الأخيرة بحيث يعمل انتهاء الصلاحية عند الخمول بشكل طبيعي.
- يمكن أن تقوم [background tasks](/automation/tasks) المنفصلة بصف نظام حدث وتوقظ heartbeat عندما ينبغي أن تلاحظ الجلسة الرئيسية شيئًا بسرعة. ولا يجعل هذا الإيقاظ تشغيل heartbeat مهمة خلفية.
- تسمح تسليمات Heartbeat بالأهداف المباشرة/الرسائل الخاصة افتراضيًا. اضبط `directPolicy: "block"` لمنع الإرسال إلى الأهداف المباشرة مع الاستمرار في تشغيل دور Heartbeat.
- إذا كان الطابور الرئيسي مشغولًا، يتم تخطي Heartbeat وإعادة المحاولة لاحقًا.
- إذا لم يُحلّ `target` إلى أي وجهة خارجية، فسيحدث التشغيل لكن لن
تُرسَل أي رسالة صادرة.
- إذا كانت `showOk` و`showAlerts` و`useIndicator` كلها معطلة، فيتم تخطي التشغيل مسبقًا بسبب `reason=alerts-disabled`.
- إذا كان تسليم التنبيهات فقط معطلًا، فلا يزال بإمكان OpenClaw تشغيل Heartbeat، وتحديث الطوابع الزمنية للمهام المستحقة، واستعادة الطابع الزمني لخمول الجلسة، ومنع حمولة التنبيه الخارجية.
- الردود الخاصة بـ Heartbeat فقط **لا** تُبقي الجلسة نشطة؛ بل تتم استعادة `updatedAt`
الأخيرة حتى يعمل انتهاء صلاحية الخمول بشكل طبيعي.
- يمكن لـ [المهام الخلفية](/ar/automation/tasks) المنفصلة إدراج حدث نظام وإيقاظ Heartbeat عندما ينبغي أن تلاحظ الجلسة الرئيسية شيئًا بسرعة. وهذا الإيقاظ لا يجعل تشغيل Heartbeat مهمة خلفية.
## عناصر التحكم في الظهور
افتراضيًا، يتم إخفاء إشعارات `HEARTBEAT_OK` بينما يتم
تسليم محتوى التنبيه. يمكنك ضبط ذلك لكل قناة أو لكل حساب:
افتراضيًا، يتم منع إقرارات `HEARTBEAT_OK` بينما يتم
تسليم محتوى التنبيهات. يمكنك ضبط هذا لكل قناة أو لكل حساب:
```yaml
channels:
@ -283,7 +286,7 @@ channels:
useIndicator: true # إصدار أحداث المؤشر (الافتراضي)
telegram:
heartbeat:
showOk: true # إظهار إشعارات OK على Telegram
showOk: true # إظهار إقرارات OK على Telegram
whatsapp:
accounts:
work:
@ -291,15 +294,15 @@ channels:
showAlerts: false # منع تسليم التنبيهات لهذا الحساب
```
الأولوية: لكل حساب ← لكل قناة ← القيم الافتراضية للقنوات ← القيم المدمجة الافتراضية.
الأسبقية: لكل حساب ← لكل قناة ← القيم الافتراضية للقناة ← القيم الافتراضية المدمجة.
### ما الذي يفعله كل علم
### ماذا يفعل كل علم
- `showOk`: يرسل إشعار `HEARTBEAT_OK` عندما يعيد النموذج ردًا يتضمن OK فقط.
- `showOk`: يرسل إقرار `HEARTBEAT_OK` عندما يعيد النموذج ردًا يحتوي فقط على OK.
- `showAlerts`: يرسل محتوى التنبيه عندما يعيد النموذج ردًا غير OK.
- `useIndicator`: يصدر أحداث مؤشرات لأسطح حالة واجهة المستخدم.
- `useIndicator`: يصدر أحداث مؤشر لواجهات حالة UI.
إذا كانت **الثلاثة كلها** false، فإن OpenClaw يتخطى تشغيل heartbeat بالكامل (من دون استدعاء للنموذج).
إذا كانت **الثلاثة جميعًا** false، يتخطى OpenClaw تشغيل Heartbeat بالكامل (من دون استدعاء للنموذج).
### أمثلة لكل قناة مقابل لكل حساب
@ -312,7 +315,7 @@ channels:
useIndicator: true
slack:
heartbeat:
showOk: true # كل حسابات Slack
showOk: true # جميع حسابات Slack
accounts:
ops:
heartbeat:
@ -324,25 +327,30 @@ channels:
### الأنماط الشائعة
| الهدف | التكوين |
| ---------------------------------------- | ----------------------------------------------------------------------------------------- |
| السلوك الافتراضي (OK صامت، والتنبيهات مفعلة) | _(لا حاجة إلى تكوين)_ |
| صامت بالكامل (لا رسائل، ولا مؤشر) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
| مؤشر فقط (من دون رسائل) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` |
| رسائل OK في قناة واحدة فقط | `channels.telegram.heartbeat: { showOk: true }` |
| الهدف | الإعدادات |
| ----------------------------------------- | ----------------------------------------------------------------------------------------- |
| السلوك الافتراضي (إشعارات OK صامتة، والتنبيهات مفعّلة) | _(لا حاجة إلى إعدادات)_ |
| صامت بالكامل (من دون رسائل، ومن دون مؤشر) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
| المؤشر فقط (من دون رسائل) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` |
| إظهار OK في قناة واحدة فقط | `channels.telegram.heartbeat: { showOk: true }` |
## `HEARTBEAT.md` ‏(اختياري)
## `HEARTBEAT.md` (اختياري)
إذا كان ملف `HEARTBEAT.md` موجودًا في مساحة العمل، فإن المطالبة الافتراضية تطلب من
الوكيل قراءته. فكّر فيه باعتباره “قائمة التحقق الخاصة بـ heartbeat”: صغيرة، وثابتة،
إذا كان ملف `HEARTBEAT.md` موجودًا في مساحة العمل، فإن الموجّه الافتراضي يطلب من
الوكيل قراءته. فكّر فيه باعتباره “قائمة تحقق Heartbeat” الخاصة بك: صغيرة، وثابتة،
وآمنة للإدراج كل 30 دقيقة.
إذا كان `HEARTBEAT.md` موجودًا لكنه فارغ فعليًا (أسطر فارغة فقط وعناوين markdown
مثل `# Heading`)، فإن OpenClaw يتخطى تشغيل heartbeat لتوفير استدعاءات API.
ويتم الإبلاغ عن هذا التجاوز على أنه `reason=empty-heartbeat-file`.
أما إذا كان الملف مفقودًا، فسيظل heartbeat يعمل ويقرر النموذج ما يجب فعله.
في التشغيلات العادية، لا يتم حقن `HEARTBEAT.md` إلا عندما تكون إرشادات Heartbeat
مفعّلة للوكيل الافتراضي. ويؤدي تعطيل وتيرة Heartbeat باستخدام `0m` أو
ضبط `includeSystemPromptSection: false` إلى حذفه من سياق التمهيد
العادي.
أبقِه صغيرًا (قائمة تحقق قصيرة أو تذكيرات) لتجنب تضخم المطالبة.
إذا كان `HEARTBEAT.md` موجودًا لكنه فارغ فعليًا (يحتوي فقط على أسطر فارغة وعناوين markdown
مثل `# Heading`)، فإن OpenClaw يتخطى تشغيل Heartbeat لتوفير استدعاءات API.
ويتم الإبلاغ عن هذا التخطي باعتباره `reason=empty-heartbeat-file`.
أما إذا كان الملف مفقودًا، فلا يزال Heartbeat يعمل ويقرر النموذج ما الذي ينبغي فعله.
اجعله صغيرًا جدًا (قائمة تحقق قصيرة أو تذكيرات) لتجنب تضخم الموجّه.
مثال على `HEARTBEAT.md`:
@ -356,8 +364,8 @@ channels:
### كتل `tasks:`
يدعم `HEARTBEAT.md` أيضًا كتلة `tasks:` مهيكلة صغيرة للفحوصات
المعتمدة على الفواصل داخل heartbeat نفسه.
يدعم `HEARTBEAT.md` أيضًا كتلة `tasks:` منظَّمة صغيرة لإجراء
فحوصات قائمة على الفواصل الزمنية داخل Heartbeat نفسه.
مثال:
@ -379,72 +387,72 @@ tasks:
السلوك:
- يقوم OpenClaw بتحليل كتلة `tasks:` والتحقق من كل مهمة مقابل `interval` الخاص بها.
- يتم تضمين المهام **المستحقة** فقط في مطالبة heartbeat لذلك التوقيت.
- إذا لم تكن هناك مهام مستحقة، يتم تخطي heartbeat بالكامل (`reason=no-tasks-due`) لتجنب استدعاء نموذج بلا فائدة.
- يحلل OpenClaw كتلة `tasks:` ويفحص كل مهمة وفق `interval` الخاص بها.
- لا يتم تضمين سوى المهام **المستحقة** في موجّه Heartbeat لتلك النبضة.
- إذا لم تكن هناك مهام مستحقة، يتم تخطي Heartbeat بالكامل (`reason=no-tasks-due`) لتجنب استدعاء نموذج غير ضروري.
- يتم الاحتفاظ بالمحتوى غير المتعلق بالمهام في `HEARTBEAT.md` وإلحاقه كسياق إضافي بعد قائمة المهام المستحقة.
- تُخزَّن الطوابع الزمنية لآخر تشغيل للمهام في حالة الجلسة (`heartbeatTaskState`)، لذا تبقى الفواصل الزمنية محفوظة عبر عمليات إعادة التشغيل العادية.
- لا يتم تقديم الطوابع الزمنية للمهام إلا بعد أن يكمل تشغيل heartbeat مسار الرد الطبيعي. ولا تضع التشغيلات المتخطاة بسبب `empty-heartbeat-file` / `no-tasks-due` علامة على المهام على أنها مكتملة.
- تُخزَّن الطوابع الزمنية لآخر تشغيل للمهمة في حالة الجلسة (`heartbeatTaskState`)، لذلك تظل الفواصل الزمنية محفوظة عبر عمليات إعادة التشغيل العادية.
- لا تُقدَّم الطوابع الزمنية للمهام إلا بعد أن يكمل Heartbeat مسار رده العادي. أما تشغيلات `empty-heartbeat-file` / `no-tasks-due` المتخطاة فلا تضع علامة على المهام باعتبارها مكتملة.
يفيد وضع المهام عندما تريد أن يحتوي ملف heartbeat واحد على عدة فحوصات دورية من دون أن تدفع تكلفة جميعها في كل توقيت.
يفيد وضع المهام عندما تريد أن يحتوي ملف Heartbeat واحد على عدة فحوصات دورية من دون أن تدفع تكلفة جميعها في كل نبضة.
### هل يمكن للوكيل تحديث `HEARTBEAT.md`؟
نعم — إذا طلبت منه ذلك.
إن `HEARTBEAT.md` مجرد ملف عادي في مساحة عمل الوكيل، لذلك يمكنك أن تطلب من
إن `HEARTBEAT.md` مجرد ملف عادي في مساحة عمل الوكيل، لذا يمكنك أن تطلب من
الوكيل (في دردشة عادية) شيئًا مثل:
- “حدّث `HEARTBEAT.md` لإضافة فحص يومي للتقويم.”
- “أعد كتابة `HEARTBEAT.md` ليكون أقصر وأكثر تركيزًا على متابعات البريد الوارد.”
- “أعد كتابة `HEARTBEAT.md` ليصبح أقصر ويركز على متابعات البريد الوارد.”
إذا كنت تريد أن يحدث ذلك بشكل استباقي، فيمكنك أيضًا تضمين سطر صريح في
مطالبة heartbeat مثل: “If the checklist becomes stale, update HEARTBEAT.md
with a better one.”
إذا كنت تريد أن يحدث هذا بشكل استباقي، فيمكنك أيضًا تضمين سطر صريح في
موجّه Heartbeat مثل: “إذا أصبحت قائمة التحقق قديمة، فحدّث HEARTBEAT.md
بنسخة أفضل.”
ملاحظة أمان: لا تضع أسرارًا (مفاتيح API، أو أرقام هواتف، أو رموزًا خاصة) في
`HEARTBEAT.md` — لأنه يصبح جزءًا من سياق المطالبة.
ملاحظة أمان: لا تضع أسرارًا (مفاتيح API أو أرقام الهواتف أو الرموز الخاصة) داخل
`HEARTBEAT.md` — لأنه يصبح جزءًا من سياق الموجّه.
## إيقاظ يدوي (عند الطلب)
يمكنك صف نظام حدث وتشغيل heartbeat فوري باستخدام:
يمكنك إدراج حدث نظام وتشغيل Heartbeat فوري باستخدام:
```bash
openclaw system event --text "Check for urgent follow-ups" --mode now
```
إذا كان عدة وكلاء لديهم `heartbeat` مكوّنًا، فإن الإيقاظ اليدوي يشغّل heartbeats
الخاصة بكل واحد من هؤلاء الوكلاء فورًا.
إذا كان لدى عدة وكلاء إعداد `heartbeat`، فإن الإيقاظ اليدوي يشغّل Heartbeats الخاصة بكل واحد منهم
فورًا.
استخدم `--mode next-heartbeat` للانتظار حتى التوقيت المجدول التالي.
استخدم `--mode next-heartbeat` للانتظار حتى النبضة المجدولة التالية.
## تسليم Reasoning ‏(اختياري)
## تسليم الاستدلال (اختياري)
افتراضيًا، تسلّم heartbeats حمولة “الإجابة” النهائية فقط.
افتراضيًا، تسلّم Heartbeats حمولة “الإجابة” النهائية فقط.
إذا كنت تريد الشفافية، ففعّل:
إذا كنت تريد مزيدًا من الشفافية، ففعّل:
- `agents.defaults.heartbeat.includeReasoning: true`
عند التمكين، ستسلّم heartbeats أيضًا رسالة منفصلة مسبوقة بـ
`Reasoning:` ‏(بنفس شكل `/reasoning on`). وقد يكون هذا مفيدًا عندما يكون الوكيل
يدير جلسات/codexes متعددة وتريد معرفة سبب قراره بتنبيهك —
لكنه قد يكشف أيضًا تفاصيل داخلية أكثر مما تريد. ويفضل إبقاؤه
معطّلًا في الدردشات الجماعية.
عند التفعيل، ستسلّم Heartbeats أيضًا رسالة منفصلة مسبوقة بـ
`Reasoning:` (بالصيغة نفسها مثل `/reasoning on`). وقد يكون هذا مفيدًا عندما يكون الوكيل
يدير عدة جلسات/نسخ Codex وتريد أن ترى لماذا قرر أن ينبهك —
لكنه قد يكشف أيضًا تفاصيل داخلية أكثر مما تريد. لذا يُفضَّل إبقاؤه
معطلًا في الدردشات الجماعية.
## الوعي بالتكلفة
تشغّل Heartbeats أدوار وكيل كاملة. وكلما كانت الفواصل أقصر زادت تكلفة الرموز. لتقليل التكلفة:
تشغّل Heartbeats أدوار وكيل كاملة. الفواصل الأقصر تستهلك رموزًا أكثر. لتقليل التكلفة:
- استخدم `isolatedSession: true` لتجنب إرسال السجل الكامل للمحادثة (تقريبًا من ~100K رمز إلى ~2-5K لكل تشغيل).
- استخدم `lightContext: true` لحصر ملفات bootstrap في `HEARTBEAT.md` فقط.
- عيّن `model` أرخص (مثل `ollama/llama3.2:1b`).
- أبقِ `HEARTBEAT.md` صغيرًا.
- استخدم `isolatedSession: true` لتجنب إرسال سجل المحادثة الكامل (من ~100 ألف رمز إلى ~2-5 آلاف لكل تشغيل).
- استخدم `lightContext: true` لقصر ملفات التمهيد على `HEARTBEAT.md` فقط.
- اضبط `model` أرخص (مثل `ollama/llama3.2:1b`).
- اجعل `HEARTBEAT.md` صغيرًا.
- استخدم `target: "none"` إذا كنت تريد فقط تحديثات الحالة الداخلية.
## ذو صلة
- [Automation & Tasks](/automation) — جميع آليات الأتمتة في لمحة
- [Background Tasks](/automation/tasks) — كيفية تتبع العمل المنفصل
- [Timezone](/concepts/timezone) — كيف تؤثر المنطقة الزمنية في جدولة heartbeat
- [Troubleshooting](/automation/cron-jobs#troubleshooting) — تصحيح مشكلات الأتمتة
- [الأتمتة والمهام](/ar/automation) — نظرة عامة على جميع آليات الأتمتة
- [المهام الخلفية](/ar/automation/tasks) — كيفية تتبع العمل المنفصل
- [المنطقة الزمنية](/ar/concepts/timezone) — كيف تؤثر المنطقة الزمنية في جدولة Heartbeat
- [استكشاف الأخطاء وإصلاحها](/ar/automation/cron-jobs#troubleshooting) — تصحيح أخطاء مشكلات الأتمتة

85
docs/ar/gateway/local-models.md
View File

@ -1,28 +1,28 @@
---
read_when:
- تريد تقديم النماذج من جهاز GPU الخاص بك
- أنت توصل LM Studio أو proxy متوافقًا مع OpenAI
- تحتاج إلى أفضل إرشادات أمان للنماذج المحلية
summary: تشغيل OpenClaw على نماذج LLM محلية (LM Studio وvLLM وLiteLLM ونقاط نهاية OpenAI مخصصة)
- أنت تقوم بربط LM Studio أو وكيل متوافق مع OpenAI
- تحتاج إلى أكثر إرشادات النماذج المحلية أمانًا
summary: شغّل OpenClaw على نماذج LLM محلية (LM Studio وvLLM وLiteLLM ونقاط نهاية OpenAI مخصصة)
title: النماذج المحلية
x-i18n:
generated_at: "2026-04-05T12:43:06Z"
generated_at: "2026-04-08T02:14:58Z"
model: gpt-5.4
provider: openai
source_hash: 3b99c8fb57f65c0b765fc75bd36933221b5aeb94c4a3f3428f92640ae064f8b6
source_hash: d619d72b0e06914ebacb7e9f38b746caf1b9ce8908c9c6638c3acdddbaa025e8
source_path: gateway/local-models.md
workflow: 15
---
# النماذج المحلية
النماذج المحلية ممكنة، لكن OpenClaw يتوقع سياقًا كبيرًا + دفاعات قوية ضد حقن المطالبات. البطاقات الصغيرة تقطع السياق وتضعف الأمان. استهدف مستوى عالٍ: **≥2 من أجهزة Mac Studio بمواصفات قصوى أو جهاز GPU مكافئ (~30 ألف دولار فأكثر)**. تعمل وحدة **24 GB** GPU واحدة فقط مع المطالبات الأخف وبزمن استجابة أعلى. استخدم **أكبر / النسخة الكاملة من النموذج التي يمكنك تشغيلها**؛ إذ إن نقاط الفحص المكممة بشدة أو “الصغيرة” ترفع خطر حقن المطالبات (راجع [Security](/gateway/security)).
التشغيل المحلي ممكن، لكن OpenClaw يتوقع سياقًا كبيرًا + وسائل دفاع قوية ضد حقن المطالبات. البطاقات الصغيرة تقتطع السياق وتسرّب الأمان. استهدف مستوى مرتفعًا: **استوديوهين Mac Studio ممتلئين بالمواصفات على الأقل أو جهاز GPU مكافئ (~$30k+)**. تعمل وحدة **24 GB** GPU واحدة فقط مع المطالبات الأخف وزمن استجابة أعلى. استخدم **أكبر / النسخة الكاملة من النموذج التي يمكنك تشغيلها**؛ إذ إن نقاط التحقق المكمّمة بشدة أو “الصغيرة” تزيد من خطر حقن المطالبات (راجع [الأمان](/ar/gateway/security)).
إذا كنت تريد أقل إعداد محلي احتكاكًا، فابدأ بـ [Ollama](/providers/ollama) و`openclaw onboard`. هذه الصفحة هي الدليل العملي الموجّه للحِزم المحلية الأعلى مستوى وخوادم OpenAI-compatible المحلية المخصصة.
إذا كنت تريد أقل إعداد محلي احتكاكًا، فابدأ بـ [Ollama](/ar/providers/ollama) و`openclaw onboard`. هذه الصفحة هي الدليل العملي الموجّه للإعدادات المحلية الأعلى مستوى وخوادم OpenAI المحلية المخصصة المتوافقة.
## الموصى به: LM Studio + نموذج محلي كبير (Responses API)
أفضل حزمة محلية حاليًا. حمّل نموذجًا كبيرًا في LM Studio (مثل إصدار كامل من Qwen أو DeepSeek أو Llama)، وفعّل الخادم المحلي (الافتراضي `http://127.0.0.1:1234`)، واستخدم Responses API لإبقاء الاستدلال منفصلًا عن النص النهائي.
أفضل بنية محلية حالية. حمّل نموذجًا كبيرًا في LM Studio (على سبيل المثال، إصدارًا كامل الحجم من Qwen أو DeepSeek أو Llama)، ثم فعّل الخادم المحلي (الافتراضي `http://127.0.0.1:1234`)، واستخدم Responses API لإبقاء الاستدلال منفصلًا عن النص النهائي.
```json5
{
@ -59,18 +59,18 @@ x-i18n:
}
```
**قائمة التحقق للإعداد**
**قائمة الإعداد**
- ثبّت LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
- في LM Studio، نزّل **أكبر إصدار نموذج متاح** (تجنب الإصدارات “الصغيرة”/المكممة بشدة)، وابدأ الخادم، وتأكد من أن `http://127.0.0.1:1234/v1/models` يسرده.
- في LM Studio، نزّل **أكبر إصدار نموذج متاح** (تجنب المتغيرات “الصغيرة”/المكمّمة بشدة)، ثم شغّل الخادم، وتأكد من أن `http://127.0.0.1:1234/v1/models` يعرضه.
- استبدل `my-local-model` بمعرّف النموذج الفعلي الظاهر في LM Studio.
- أبقِ النموذج محمّلًا؛ إذ تضيف البداية الباردة زمن تأخير عند بدء التشغيل.
- اضبط `contextWindow`/`maxTokens` إذا كان إصدار LM Studio لديك يختلف.
- بالنسبة إلى WhatsApp، التزم بـ Responses API بحيث يُرسل النص النهائي فقط.
- أبقِ النموذج محمّلًا؛ فالتحميل البارد يضيف زمن تأخير عند البدء.
- عدّل `contextWindow`/`maxTokens` إذا كان إصدار LM Studio لديك مختلفًا.
- بالنسبة إلى WhatsApp، التزم بـ Responses API حتى يُرسَل النص النهائي فقط.
أبقِ النماذج المستضافة مكوّنة حتى عند التشغيل محليًا؛ استخدم `models.mode: "merge"` حتى تظل fallbacks متاحة.
أبقِ النماذج المستضافة مضبوطة حتى عند التشغيل المحلي؛ استخدم `models.mode: "merge"` حتى تبقى خيارات الرجوع الاحتياطي متاحة.
### تكوين هجين: مستضاف كأساسي، ومحلي كرجوع احتياطي
### إعداد هجين: أساسي مستضاف، واحتياطي محلي
```json5
{
@ -113,16 +113,16 @@ x-i18n:
### محلي أولًا مع شبكة أمان مستضافة
بدّل ترتيب الأساسي والرجوع الاحتياطي؛ وأبقِ كتلة providers نفسها و`models.mode: "merge"` حتى تتمكن من الرجوع إلى Sonnet أو Opus عندما يتوقف الجهاز المحلي.
بدّل ترتيب الأساسي والاحتياطي؛ وأبقِ كتلة providers نفسها و`models.mode: "merge"` حتى تتمكن من الرجوع إلى Sonnet أو Opus عندما يتعطل الجهاز المحلي.
### الاستضافة الإقليمية / توجيه البيانات
- توجد أيضًا إصدارات MiniMax/Kimi/GLM المستضافة على OpenRouter مع نقاط نهاية مثبتة على مناطق محددة (مثل الاستضافة في الولايات المتحدة). اختر الإصدار الإقليمي هناك للحفاظ على حركة البيانات ضمن النطاق القضائي الذي تختاره مع الاستمرار في استخدام `models.mode: "merge"` لعمليات الرجوع الاحتياطي إلى Anthropic/OpenAI.
- يظل التشغيل المحلي فقط هو أقوى مسار للخصوصية؛ أما التوجيه الإقليمي المستضاف فهو حل وسط عندما تحتاج إلى ميزات المزوّد ولكنك تريد التحكم في تدفق البيانات.
- تتوفر أيضًا متغيرات MiniMax/Kimi/GLM المستضافة على OpenRouter مع نقاط نهاية مثبّتة على مناطق محددة (مثل الاستضافة داخل الولايات المتحدة). اختر المتغير الإقليمي هناك للحفاظ على حركة المرور ضمن الولاية القضائية التي تختارها مع الاستمرار في استخدام `models.mode: "merge"` لخيارات الرجوع الاحتياطي من Anthropic/OpenAI.
- يظل التشغيل المحلي فقط هو المسار الأقوى للخصوصية؛ أما التوجيه الإقليمي المستضاف فهو الحل الوسط عندما تحتاج إلى ميزات المزوّد لكنك تريد التحكم في تدفق البيانات.
## Proxies محلية أخرى متوافقة مع OpenAI
## وكلاء محليون آخرون متوافقون مع OpenAI
تعمل vLLM وLiteLLM وOAI-proxy أو gateways المخصصة إذا كانت تعرض نقطة نهاية `/v1` بأسلوب OpenAI. استبدل كتلة provider أعلاه بنقطة النهاية ومعرّف النموذج لديك:
تعمل vLLM وLiteLLM وOAI-proxy أو البوابات المخصصة إذا كانت تعرض نقطة نهاية `/v1` بأسلوب OpenAI. استبدل كتلة provider أعلاه بنقطة النهاية ومعرّف النموذج الخاصين بك:
```json5
{
@ -150,21 +150,42 @@ x-i18n:
}
```
أبقِ `models.mode: "merge"` حتى تظل النماذج المستضافة متاحة كخيارات fallback.
أبقِ `models.mode: "merge"` حتى تظل النماذج المستضافة متاحة كخيارات رجوع احتياطي.
ملاحظة سلوكية لخلفيات `/v1` المحلية/الممررة عبر proxy:
ملاحظة سلوكية لواجهات `/v1` المحلية/الوسيطة:
- يتعامل OpenClaw مع هذه المسارات باعتبارها مسارات OpenAI-compatible بنمط proxy، وليس
كنقاط نهاية OpenAI أصلية
- يتعامل OpenClaw مع هذه الواجهات على أنها مسارات وكيل متوافقة مع OpenAI، وليست
نقاط نهاية OpenAI أصلية
- لا ينطبق هنا تشكيل الطلبات الخاص بـ OpenAI الأصلية فقط: لا
`service_tier`، ولا `store` الخاصة بـ Responses، ولا تشكيل حمولة
التوافق مع reasoning في OpenAI، ولا تلميحات prompt-cache
- لا يتم حقن رؤوس الإسناد المخفية الخاصة بـ OpenClaw (`originator`, `version`, `User-Agent`)
في عناوين proxy المخصصة هذه
يوجد `service_tier`، ولا `store` الخاص بـ Responses، ولا تشكيل حمولة
التوافق مع الاستدلال الخاص بـ OpenAI، ولا تلميحات لذاكرة التخزين المؤقت للمطالبات
- لا يتم حقن ترويسات الإسناد المخفية الخاصة بـ OpenClaw (`originator` و`version` و`User-Agent`)
على عناوين URL الخاصة بهذه الوكلاء المخصصة
ملاحظات التوافق لواجهات OpenAI المتوافقة الأكثر صرامة:
- تقبل بعض الخوادم فقط `messages[].content` كسلسلة نصية في Chat Completions، وليس
مصفوفات أجزاء المحتوى المهيكلة. اضبط
`models.providers.<provider>.models[].compat.requiresStringContent: true` لهذه
النقاط.
- بعض الواجهات المحلية الأصغر أو الأكثر صرامة تكون غير مستقرة مع الشكل الكامل
لمطالبة بيئة تشغيل الوكيل في OpenClaw، خاصة عند تضمين مخططات الأدوات. إذا كانت
الواجهة تعمل مع استدعاءات `/v1/chat/completions` المباشرة الصغيرة ولكنها تفشل في
الأدوار العادية لوكيل OpenClaw، فجرّب
`models.providers.<provider>.models[].compat.supportsTools: false` أولًا.
- إذا كانت الواجهة لا تزال تفشل فقط في تشغيلات OpenClaw الأكبر، فعادةً ما تكون
المشكلة المتبقية في سعة النموذج/الخادم upstream أو في خطأ في الواجهة الخلفية،
وليس في طبقة النقل الخاصة بـ OpenClaw.
## استكشاف الأخطاء وإصلاحها
- هل يستطيع gateway الوصول إلى proxy؟ ‏`curl http://127.0.0.1:1234/v1/models`.
- هل تم إلغاء تحميل نموذج LM Studio؟ أعد تحميله؛ فالبداية الباردة سبب شائع لحالة “التعليق”.
- أخطاء السياق؟ خفّض `contextWindow` أو ارفع حد الخادم لديك.
- الأمان: تتجاوز النماذج المحلية عوامل التصفية من جهة المزوّد؛ لذا أبقِ الوكلاء محدودين وشغّل الضغط للحد من نطاق تأثير حقن المطالبات.
- هل تستطيع البوابة الوصول إلى الوكيل؟ `curl http://127.0.0.1:1234/v1/models`.
- هل تم إلغاء تحميل نموذج LM Studio؟ أعد تحميله؛ فالبدء البارد سبب شائع لـ “التعليق”.
- أخطاء في السياق؟ خفّض `contextWindow` أو ارفع حد الخادم.
- هل يعيد الخادم المتوافق مع OpenAI الخطأ `messages[].content ... expected a string`؟
أضف `compat.requiresStringContent: true` إلى إدخال ذلك النموذج.
- تعمل استدعاءات `/v1/chat/completions` المباشرة الصغيرة، لكن `openclaw infer model run`
يفشل على Gemma أو نموذج محلي آخر؟ عطّل مخططات الأدوات أولًا عبر
`compat.supportsTools: false`، ثم أعد الاختبار. إذا استمر الخادم في التعطل فقط
مع مطالبات OpenClaw الأكبر، فاعتبر ذلك قيدًا في الخادم/النموذج upstream.
- الأمان: تتجاوز النماذج المحلية عوامل التصفية الموجودة لدى المزوّد؛ أبقِ الوكلاء محدودي النطاق وفعّل الضغط لتقليل نطاق تأثير حقن المطالبات.

622
docs/ar/gateway/protocol.md
View File

@ -1,32 +1,32 @@
---
read_when:
- تنفيذ أو تحديث عملاء gateway عبر WS
- تصحيح أخطاء عدم تطابق البروتوكول أو فشل الاتصال
- إعادة توليد schema/models الخاصة بالبروتوكول
- تنفيذ عملاء WS للبوابة أو تحديثهم
- تصحيح حالات عدم تطابق البروتوكول أو فشل الاتصال
- إعادة توليد مخطط/نماذج البروتوكول
summary: 'بروتوكول Gateway عبر WebSocket: المصافحة، والإطارات، والإصدارات'
title: بروتوكول Gateway
x-i18n:
generated_at: "2026-04-05T12:44:58Z"
generated_at: "2026-04-08T02:16:02Z"
model: gpt-5.4
provider: openai
source_hash: c37f5b686562dda3ba3516ac6982ad87b2f01d8148233284e9917099c6e96d87
source_hash: 8635e3ac1dd311dbd3a770b088868aa1495a8d53b3ebc1eae0dfda3b2bf4694a
source_path: gateway/protocol.md
workflow: 15
---
# بروتوكول Gateway ‏(WebSocket)
# بروتوكول Gateway (WebSocket)
بروتوكول Gateway WS هو **سطح التحكم الوحيد + نقل العقد** لـ
OpenClaw. فجميع العملاء (CLI وواجهة الويب وتطبيق macOS وعقد iOS/Android والعقد
عديمة الرأس) يتصلون عبر WebSocket ويعلنون **الدور** + **النطاق** الخاصين بهم وقت
المصافحة.
يُعد بروتوكول Gateway عبر WS **مستوى التحكم الوحيد + ناقل العقد** في
OpenClaw. جميع العملاء (CLI، وواجهة الويب، وتطبيق macOS، وعقد iOS/Android، والعقد
عديمة الواجهة) يتصلون عبر WebSocket ويعلنون **الدور** + **النطاق**
في وقت المصافحة.
## النقل
- WebSocket، وإطارات نصية بحمولات JSON.
- **يجب** أن يكون الإطار الأول طلب `connect`.
## المصافحة (`connect`)
## المصافحة (connect)
Gateway → العميل (تحدي ما قبل الاتصال):
@ -84,7 +84,7 @@ Gateway → العميل:
}
```
عند إصدار device token، تتضمن `hello-ok` أيضًا:
عند إصدار رمز جهاز، يتضمن `hello-ok` أيضًا:
```json
{
@ -96,8 +96,8 @@ Gateway → العميل:
}
```
أثناء تسليم bootstrap الموثوق، قد تتضمن `hello-ok.auth` أيضًا إدخالات
أدوار إضافية محدودة ضمن `deviceTokens`:
أثناء تسليم bootstrap الموثوق، قد يتضمن `hello-ok.auth` أيضًا
إدخالات أدوار إضافية مقيّدة في `deviceTokens`:
```json
{
@ -116,14 +116,14 @@ Gateway → العميل:
}
```
في تدفق bootstrap المضمّن للعقدة/المشغّل، يبقى token الأساسي للعقدة
`scopes: []` وتبقى أي token للمشغّل مسلّمة ضمن الحدود
المقيدة بقائمة سماح bootstrap للمشغّل (`operator.approvals`, `operator.read`,
`operator.talk.secrets`, `operator.write`). وتظل فحوصات نطاق bootstrap
مرتبطة ببادئة الدور: إذ لا تلبّي إدخالات المشغّل إلا طلبات المشغّل، وما تزال
الأدوار غير المشغّلة تحتاج إلى نطاقات تحت بادئة دورها الخاصة.
في تدفق bootstrap المضمّن للعقدة/المشغّل، يظل رمز العقدة الأساسي
`scopes: []` وأي رمز مشغّل تم تسليمه يظل مقيّدًا بقائمة السماح الخاصة بمشغّل bootstrap
(`operator.approvals`، و`operator.read`،
و`operator.talk.secrets`، و`operator.write`). تظل فحوصات نطاق bootstrap
مسبوقة بالدور: إدخالات المشغّل لا تلبّي إلا طلبات المشغّل، وما زالت الأدوار
غير المشغّلة تحتاج إلى نطاقات ضمن بادئة دورها الخاصة.
### مثال عقدة
### مثال على عقدة
```json
{
@ -164,16 +164,16 @@ Gateway → العميل:
- **استجابة**: `{type:"res", id, ok, payload|error}`
- **حدث**: `{type:"event", event, payload, seq?, stateVersion?}`
تتطلب الطرق ذات الآثار الجانبية **مفاتيح idempotency** ‏(راجع schema).
تتطلب الأساليب ذات الآثار الجانبية **مفاتيح idempotency** (راجع المخطط).
## الأدوار + النطاقات
### الأدوار
- `operator` = عميل سطح التحكم (CLI/UI/الأتمتة).
- `node` = مضيف الإمكانات (`camera/screen/canvas/system.run`).
- `operator` = عميل مستوى التحكم (CLI/واجهة المستخدم/الأتمتة).
- `node` = مضيف الإمكانات (camera/screen/canvas/system.run).
### النطاقات (`operator`)
### النطاقات (operator)
النطاقات الشائعة:
@ -187,407 +187,417 @@ Gateway → العميل:
يتطلب `talk.config` مع `includeSecrets: true` النطاق `operator.talk.secrets`
(أو `operator.admin`).
قد تطلب طرق Gateway RPC المسجلة من المكونات الإضافية نطاق operator خاصًا بها، لكن
بادئات الإدارة الأساسية المحجوزة (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) تُحل دائمًا إلى `operator.admin`.
يمكن لأساليب RPC الخاصة بالبوابة والمسجَّلة من الإضافات أن تطلب نطاق operator خاصًا بها، لكن
بادئات الإدارة الأساسية المحجوزة (`config.*`، و`exec.approvals.*`، و`wizard.*`،
و`update.*`) تُحل دائمًا إلى `operator.admin`.
يمثل نطاق الطريقة البوابة الأولى فقط. إذ تطبق بعض الأوامر المائلة التي تصل عبر
`chat.send` فحوصات أشد على مستوى الأمر فوق ذلك. فعلى سبيل المثال، تتطلب
عمليات الكتابة الدائمة عبر `/config set` و`/config unset` النطاق `operator.admin`.
نطاق الأسلوب ليس سوى البوابة الأولى. بعض أوامر الشرطة المائلة التي يتم الوصول إليها
عبر `chat.send` تطبق فحوصات على مستوى الأمر أكثر صرامة فوق ذلك. على سبيل المثال،
تتطلب عمليات الكتابة الدائمة في `/config set` و`/config unset` النطاق `operator.admin`.
كما يملك `node.pair.approve` فحص نطاق إضافيًا وقت الموافقة فوق
نطاق الطريقة الأساسي:
يحتوي `node.pair.approve` أيضًا على فحص نطاق إضافي في وقت الموافقة فوق نطاق
الأسلوب الأساسي:
- الطلبات من دون أوامر: `operator.pairing`
- الطلبات التي تحتوي على أوامر عقدة غير `exec`: ‏`operator.pairing` + `operator.write`
- الطلبات التي تتضمن `system.run`, `system.run.prepare`, أو `system.which`:
‏`operator.pairing` + `operator.admin`
- الطلبات بلا أوامر: `operator.pairing`
- الطلبات التي تتضمن أوامر عقدة غير تنفيذية: `operator.pairing` + `operator.write`
- الطلبات التي تتضمن `system.run` أو `system.run.prepare` أو `system.which`:
`operator.pairing` + `operator.admin`
### `caps`/`commands`/`permissions` ‏(`node`)
### caps/commands/permissions (node)
تعلن العقد مطالبات الإمكانات وقت الاتصال:
تعلن العقد مطالبات الإمكانات في وقت الاتصال:
- `caps`: فئات إمكانات عالية المستوى.
- `caps`: فئات الإمكانات عالية المستوى.
- `commands`: قائمة سماح الأوامر للاستدعاء.
- `permissions`: مفاتيح تبديل دقيقة (مثل `screen.record`, `camera.capture`).
- `permissions`: مفاتيح تبديل دقيقة (مثل `screen.record` و`camera.capture`).
يتعامل Gateway مع هذه القيم على أنها **مطالبات** ويفرض قوائم سماح من جانب الخادم.
يتعامل Gateway مع هذه القيم على أنها **مطالبات** ويفرض قوائم سماح من جهة الخادم.
## الحضور
- تعيد `system-presence` إدخالات مفاتيحها حسب هوية الجهاز.
- تتضمن إدخالات الحضور `deviceId`, `roles`, و`scopes` لكي تتمكن واجهات المستخدم من عرض صف واحد لكل جهاز
حتى عندما يتصل بصفته **operator** و**node** معًا.
- يعيد `system-presence` إدخالات مفهرسة بحسب هوية الجهاز.
- تتضمن إدخالات الحضور `deviceId`، و`roles`، و`scopes` حتى تتمكن واجهات المستخدم من عرض صف واحد لكل جهاز
حتى عندما يتصل بوصفه **operator** و**node** معًا.
## عائلات طرق RPC الشائعة
## عائلات أساليب RPC الشائعة
ليست هذه الصفحة تفريغًا مولّدًا كاملًا، لكن السطح العام لـ WS أوسع
من أمثلة المصافحة/المصادقة أعلاه. وهذه هي عائلات الطرق الرئيسية التي يعرضها
Gateway اليوم.
هذه الصفحة ليست تفريغًا كاملاً مولدًا، لكن سطح WS العام أوسع
من أمثلة المصافحة/المصادقة أعلاه. هذه هي عائلات الأساليب الرئيسية التي
يكشفها Gateway اليوم.
`hello-ok.features.methods` هي قائمة اكتشاف متحفظة مبنية من
`src/gateway/server-methods-list.ts` بالإضافة إلى الطرق المصدّرة من المكونات الإضافية/القنوات المحمّلة.
تعامل معها على أنها اكتشاف للميزات، لا على أنها تفريغ مولّد لكل المساعدات القابلة للاستدعاء
المطبقة في `src/gateway/server-methods/*.ts`.
تمثل `hello-ok.features.methods` قائمة اكتشاف متحفظة مبنية من
`src/gateway/server-methods-list.ts` بالإضافة إلى صادرات أساليب الإضافات/القنوات المحمَّلة.
تعامل معها بوصفها لاكتشاف الميزات، لا بوصفها تفريغًا مولدًا لكل دالة قابلة للاستدعاء
تم تنفيذها في `src/gateway/server-methods/*.ts`.
### النظام والهوية
- تعيد `health` لقطة السلامة المخزنة مؤقتًا أو المفحوصة حديثًا للـ gateway.
- تعيد `status` ملخص gateway بنمط `/status`؛ وتُضمّن الحقول الحساسة
فقط لعملاء operator ذوي النطاق الإداري.
- تعيد `gateway.identity.get` هوية جهاز gateway المستخدمة في relay
وتدفقات الاقتران.
- تعيد `system-presence` لقطة الحضور الحالية للأجهزة المتصلة
operator/node.
- يعيد `health` لقطة صحة البوابة المخزنة مؤقتًا أو التي تم فحصها حديثًا.
- يعيد `status` ملخص البوابة على نمط `/status`؛ ويتم
تضمين الحقول الحساسة فقط لعملاء operator ذوي نطاق الإدارة.
- يعيد `gateway.identity.get` هوية جهاز البوابة المستخدمة في
تدفقات relay والاقتران.
- يعيد `system-presence` لقطة الحضور الحالية للأجهزة المتصلة
بوصفها operator/node.
- يضيف `system-event` حدث نظام ويمكنه تحديث/بث
سياق الحضور.
- تعيد `last-heartbeat` أحدث حدث heartbeat محفوظ.
- يبدّل `set-heartbeats` معالجة heartbeat على الـ gateway.
- يعيد `last-heartbeat` أحدث حدث heartbeat محفوظ.
- يقوم `set-heartbeats` بتبديل معالجة heartbeat على البوابة.
### النماذج والاستخدام
- تعيد `models.list` فهرس النماذج المسموح بها وقت التشغيل.
- تعيد `usage.status` ملخصات نوافذ استخدام المزوّد/الحصة المتبقية.
- تعيد `usage.cost` ملخصات مجمعة لاستخدام التكلفة لنطاق زمني.
- تعيد `doctor.memory.status` جاهزية الذاكرة المتجهية / embedding لمساحة عمل
الوكيل الافتراضي النشطة.
- تعيد `sessions.usage` ملخصات استخدام لكل جلسة.
- تعيد `sessions.usage.timeseries` سلسلة زمنية للاستخدام لجلسة واحدة.
- تعيد `sessions.usage.logs` إدخالات سجل الاستخدام لجلسة واحدة.
- يعيد `models.list` فهرس النماذج المسموح بها في بيئة التشغيل.
- يعيد `usage.status` ملخصات نوافذ استخدام الموفر/الحصة المتبقية.
- يعيد `usage.cost` ملخصات استخدام التكلفة المجمعة لنطاق تاريخ.
- يعيد `doctor.memory.status` جاهزية الذاكرة المتجهية / التضمين
لمساحة عمل الوكيل الافتراضي النشط.
- يعيد `sessions.usage` ملخصات الاستخدام لكل جلسة.
- يعيد `sessions.usage.timeseries` سلسلة زمنية للاستخدام لجلسة واحدة.
- يعيد `sessions.usage.logs` إدخالات سجل الاستخدام لجلسة واحدة.
### القنوات ومساعدات تسجيل الدخول
- تعيد `channels.status` ملخصات حالة القنوات/المكونات الإضافية
المضمّنة والمجمّعة.
- تسجّل `channels.logout` الخروج من قناة/حساب محدد حيث تدعم القناة
تسجيل الخروج.
- تبدأ `web.login.start` تدفق تسجيل دخول QR/ويب للقناة الحالية
القابلة لتسجيل دخول QR على الويب.
- تنتظر `web.login.wait` اكتمال تدفق تسجيل دخول QR/الويب ذاك وتبدأ
- يعيد `channels.status` ملخصات حالة القنوات/الإضافات المضمّنة والمجمعة.
- يقوم `channels.logout` بتسجيل الخروج من قناة/حساب محدد حيث
تدعم القناة تسجيل الخروج.
- يبدأ `web.login.start` تدفق تسجيل دخول QR/ويب للموفر
الحالي لقناة الويب القادرة على QR.
- ينتظر `web.login.wait` اكتمال تدفق تسجيل دخول QR/ويب ويبدأ
القناة عند النجاح.
- ترسل `push.test` دفعة APNs اختبارية إلى عقدة iOS مسجّلة.
- تعيد `voicewake.get` محفزات كلمة التنبيه المخزنة.
- تحدّث `voicewake.set` محفزات كلمة التنبيه وتبث التغيير.
- يرسل `push.test` إشعار APNs تجريبيًا إلى عقدة iOS مسجّلة.
- يعيد `voicewake.get` محفزات كلمة التنبيه المخزنة.
- يحدّث `voicewake.set` محفزات كلمة التنبيه ويبث التغيير.
### المراسلة والسجلات
- `send` هو RPC التسليم الصادر المباشر للإرسال الموجّه إلى قناة/حساب/سلسلة
خارج مشغّل الدردشة.
- تعيد `logs.tail` ذيل سجل ملف gateway المكوَّن مع أدوات
المؤشر/الحدود والتحكم في أقصى عدد من البايتات.
- `send` هو RPC التسليم الصادر المباشر للرسائل
الموجهة إلى قناة/حساب/سلسلة خارج مشغّل الدردشة.
- يعيد `logs.tail` ذيل سجل ملفات البوابة المضبوط مع المؤشر/الحد
وعناصر التحكم في الحد الأقصى للبايتات.
### Talk وTTS
- تعيد `talk.config` حمولة إعداد Talk الفعالة؛ ويتطلب `includeSecrets`
النطاق `operator.talk.secrets` ‏(أو `operator.admin`).
- تضبط `talk.mode`/تبث حالة وضع Talk الحالية لعملاء WebChat/Control UI.
- تولد `talk.speak` كلامًا من خلال مزود الكلام النشط في Talk.
- تعيد `tts.status` حالة تفعيل TTS، والمزوّد النشط، ومزوّدي fallback،
وحالة إعداد المزوّد.
- تعيد `tts.providers` جرد مزوّدي TTS المرئيين.
- تبدّل `tts.enable` و`tts.disable` حالة تفضيلات TTS.
- تحدّث `tts.setProvider` المزوّد المفضّل لـ TTS.
- تشغّل `tts.convert` تحويل text-to-speech لمرة واحدة.
- يعيد `talk.config` حمولة إعداد Talk الفعالة؛ ويتطلب `includeSecrets`
النطاق `operator.talk.secrets` (أو `operator.admin`).
- يضبط `talk.mode` حالة وضع Talk الحالية ويبثها لعملاء
WebChat/Control UI.
- يقوم `talk.speak` بتوليف الكلام عبر موفر كلام Talk النشط.
- يعيد `tts.status` حالة تمكين TTS، والموفر النشط، وموفري البدائل،
وحالة إعداد الموفر.
- يعيد `tts.providers` قائمة موفري TTS المرئية.
- يقوم `tts.enable` و`tts.disable` بتبديل حالة تفضيلات TTS.
- يحدّث `tts.setProvider` موفر TTS المفضل.
- يشغّل `tts.convert` تحويل نص إلى كلام لمرة واحدة.
### الأسرار، والإعداد، والتحديث، والمعالج
- تعيد `secrets.reload` حل SecretRefs النشطة وتبدّل حالة الأسرار وقت التشغيل
- يعيد `secrets.reload` حل SecretRefs النشطة ويبدّل حالة الأسرار في وقت التشغيل
فقط عند النجاح الكامل.
- تحل `secrets.resolve` إسنادات الأسرار المستهدفة بالأوامر لمجموعة
أوامر/أهداف محددة.
- تعيد `config.get` لقطة الإعداد الحالية وhash الخاص بها.
- تكتب `config.set` حمولة إعداد مُتحققًا من صحتها.
- تدمج `config.patch` تحديثًا جزئيًا للإعداد.
- تتحقق `config.apply` + تستبدل حمولة الإعداد الكاملة.
- تعيد `config.schema` حمولة schema الحية للإعداد المستخدمة بواسطة Control UI و
أدوات CLI: ‏schema، و`uiHints`، والإصدار، وبيانات التوليد الوصفية، بما في ذلك
بيانات schema الوصفية للمكونات الإضافية + القنوات عندما يستطيع وقت التشغيل تحميلها. وتتضمن schema
بيانات `title` / `description` الوصفية للحقول المشتقة من التسميات نفسها
ونصوص المساعدة المستخدمة في UI، بما في ذلك فروع
التركيب الخاصة بالكائنات المتداخلة، والرمز الشامل، وعناصر المصفوفات،
و`anyOf` / `oneOf` / `allOf` عندما توجد وثائق حقول مطابقة.
- تعيد `config.schema.lookup` حمولة lookup محددة بالمسار لمسار إعداد
واحد: المسار المطبع، وعقدة schema سطحية، وhint مطابق + `hintPath`، و
ملخصات الأبناء المباشرين للتعمق في UI/CLI.
- تحتفظ عقد schema الخاصة بالlookup بالوثائق الموجهة للمستخدم
وحقول التحقق الشائعة:
`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`,
وحدود الأعداد/السلاسل/المصفوفات/الكائنات، والأعلام المنطقية مثل
`additionalProperties`, `deprecated`, `readOnly`, `writeOnly`.
- تعرض ملخصات الأبناء `key`, و`path` المطبع، و`type`, و`required`,
- يقوم `secrets.resolve` بحل تعيينات الأسرار المستهدفة للأوامر لمجموعة
أمر/هدف محددة.
- يعيد `config.get` لقطة الإعداد الحالية وتجزئتها.
- يكتب `config.set` حمولة إعداد تم التحقق من صحتها.
- يدمج `config.patch` تحديث إعداد جزئيًا.
- يتحقق `config.apply` من حمولة الإعداد الكاملة ويستبدلها.
- يعيد `config.schema` حمولة مخطط الإعداد المباشر المستخدمة بواسطة Control UI و
أدوات CLI: المخطط، و`uiHints`، والإصدار، وبيانات التوليد الوصفية، بما في ذلك
بيانات مخطط الإضافات + القنوات الوصفية عندما تستطيع بيئة التشغيل تحميلها. يتضمن
المخطط بيانات الحقل `title` / `description`
المشتقة من التسميات نفسها ونصوص المساعدة التي تستخدمها واجهة المستخدم، بما في ذلك
الكائنات المتداخلة، والبدائل العامة، وعناصر المصفوفات،
وفروع التركيب `anyOf` / `oneOf` / `allOf` عندما توجد
وثائق حقل مطابقة.
- يعيد `config.schema.lookup` حمولة بحث محصورة بمسار لإعداد واحد
لمسار إعداد واحد: مسار مُطبَّع، وعقدة مخطط سطحية، وتلميح مطابق + `hintPath`،
وملخصات الأبناء المباشرين للتعمق عبر واجهة المستخدم/CLI.
- تحتفظ عقد مخطط البحث بوثائق المستخدم والحقول الشائعة للتحقق:
`title`، و`description`، و`type`، و`enum`، و`const`، و`format`، و`pattern`،
وحدود الأرقام/السلاسل/المصفوفات/الكائنات، والأعلام المنطقية مثل
`additionalProperties`، و`deprecated`، و`readOnly`، و`writeOnly`.
- تكشف ملخصات الأبناء `key`، و`path` المُطبَّع، و`type`، و`required`،
و`hasChildren`، بالإضافة إلى `hint` / `hintPath` المطابقين.
- تشغّل `update.run` تدفق تحديث gateway وتجدول إعادة التشغيل فقط عندما
- يشغّل `update.run` تدفق تحديث البوابة ويجدول إعادة تشغيل فقط عندما
ينجح التحديث نفسه.
- تعرض `wizard.start`, `wizard.next`, `wizard.status`, و`wizard.cancel`
- تكشف `wizard.start`، و`wizard.next`، و`wizard.status`، و`wizard.cancel`
معالج الإعداد الأولي عبر WS RPC.
### العائلات الرئيسية الموجودة
#### مساعدات الوكيل ومساحة العمل
- تعيد `agents.list` إدخالات الوكلاء المكوّنة.
- تدير `agents.create`, `agents.update`, و`agents.delete` سجلات الوكلاء
وربط مساحة العمل.
- تدير `agents.files.list`, `agents.files.get`, و`agents.files.set` ملفات
bootstrap الخاصة بمساحة العمل المعروضة لوكيل ما.
- تعيد `agent.identity.get` هوية المساعد الفعالة لوكيل أو
- يعيد `agents.list` إدخالات الوكلاء المضبوطة.
- تدير `agents.create`، و`agents.update`، و`agents.delete` سجلات الوكلاء و
ربط مساحة العمل.
- تدير `agents.files.list`، و`agents.files.get`، و`agents.files.set`
ملفات مساحة عمل bootstrap المعروضة لوكيل.
- يعيد `agent.identity.get` هوية المساعد الفعالة لوكيل أو
جلسة.
- تنتظر `agent.wait` انتهاء تشغيل ما وتعيد اللقطة النهائية عند
- ينتظر `agent.wait` انتهاء التشغيل ويعيد اللقطة النهائية عند
توفرها.
#### التحكم في الجلسة
#### التحكم في الجلسات
- تعيد `sessions.list` فهرس الجلسات الحالي.
- تبدّل `sessions.subscribe` و`sessions.unsubscribe` اشتراكات
تغييرات الجلسات لعميل WS الحالي.
- تبدّل `sessions.messages.subscribe` و`sessions.messages.unsubscribe`
اشتراكات أحداث النصوص/الرسائل لجلسة واحدة.
- تعيد `sessions.preview` معاينات نصوص محدودة لمفاتيح جلسات محددة.
- تحل `sessions.resolve` أو تحول إلى الصيغة القانونية هدف جلسة.
- يعيد `sessions.list` فهرس الجلسات الحالي.
- تقوم `sessions.subscribe` و`sessions.unsubscribe` بتبديل اشتراكات
أحداث تغيّر الجلسات لعميل WS الحالي.
- تقوم `sessions.messages.subscribe` و`sessions.messages.unsubscribe` بتبديل
اشتراكات أحداث السجل/الرسائل لجلسة واحدة.
- يعيد `sessions.preview` معاينات سجلات محصورة لمفاتيح جلسات
محددة.
- يقوم `sessions.resolve` بحل هدف جلسة أو جعله قياسيًا.
- تنشئ `sessions.create` إدخال جلسة جديدًا.
- ترسل `sessions.send` رسالة إلى جلسة موجودة.
- `sessions.steer` هو متغير المقاطعة والتوجيه لجلسة نشطة.
- توقف `sessions.abort` العمل النشط لجلسة.
- تحدّث `sessions.patch` بيانات الجلسة الوصفية/التجاوزات.
- تنفذ `sessions.reset`, `sessions.delete`, و`sessions.compact` صيانة
الجلسات.
- تعيد `sessions.get` صف الجلسة المخزن كاملًا.
- ما يزال تنفيذ الدردشة يستخدم `chat.history`, `chat.send`, `chat.abort`, و
- تمثل `sessions.steer` نسخة المقاطعة والتوجيه لجلسة نشطة.
- تقوم `sessions.abort` بإلغاء العمل النشط لجلسة.
- تحدّث `sessions.patch` البيانات الوصفية/التجاوزات الخاصة بالجلسة.
- تنفّذ `sessions.reset`، و`sessions.delete`، و`sessions.compact`
صيانة الجلسة.
- يعيد `sessions.get` صف الجلسة المخزَّن بالكامل.
- ما زال تنفيذ الدردشة يستخدم `chat.history`، و`chat.send`، و`chat.abort`، و
`chat.inject`.
- يتم تطبيع `chat.history` للعرض لعملاء UI: حيث تُزال وسوم التعليمات المضمنة من النص المرئي،
وتُزال حمولات XML النصية العادية لاستدعاءات الأدوات (بما في ذلك
`<tool_call>...</tool_call>`, `<function_call>...</function_call>`,
`<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, و
كتل استدعاءات الأدوات المقتطعة)، كما تُزال رموز التحكم بالنموذج المسرّبة بصيغة ASCII/العرض الكامل،
وتُحذف صفوف المساعد الصامتة البحتة مثل `NO_REPLY` /
`no_reply` المطابقة تمامًا، ويمكن استبدال الصفوف كبيرة الحجم بعناصر نائبة.
- تمت تهيئة `chat.history` للعرض لعملاء UI: تتم
إزالة وسوم التوجيه المضمنة من النص المرئي، كما تُزال حمولات XML النصية العادية
لاستدعاءات الأدوات (بما في ذلك
`<tool_call>...</tool_call>`، و`<function_call>...</function_call>`،
و`<tool_calls>...</tool_calls>`، و`<function_calls>...</function_calls>`،
وكتل استدعاءات الأدوات المقتطعة) ورموز التحكم بالنموذج المسرّبة بصيغة ASCII/العرض الكامل،
كما تُحذف صفوف المساعد المؤلفة فقط من رموز صامتة مثل `NO_REPLY` /
`no_reply`، ويمكن استبدال الصفوف كبيرة الحجم بعناصر نائبة.
#### اقتران الأجهزة وdevice tokens
#### اقتران الأجهزة ورموز الأجهزة
- تعيد `device.pair.list` الأجهزة المقترنة المعلقة والموافق عليها.
- تدير `device.pair.approve`, `device.pair.reject`, و`device.pair.remove`
- يعيد `device.pair.list` الأجهزة المقترنة المعلقة والمعتمدة.
- تدير `device.pair.approve`، و`device.pair.reject`، و`device.pair.remove`
سجلات اقتران الأجهزة.
- تدير `device.token.rotate` تدوير token جهاز مقترن ضمن حدود دوره
ونطاقاته المعتمدة.
- تلغي `device.token.revoke` device token.
- يقوم `device.token.rotate` بتدوير رمز جهاز مقترن ضمن حدود الدور
والنطاق المعتمدة له.
- يقوم `device.token.revoke` بإبطال رمز جهاز مقترن.
#### اقتران العقد، والاستدعاء، والعمل المعلّق
- تغطي `node.pair.request`, `node.pair.list`, `node.pair.approve`,
`node.pair.reject`, و`node.pair.verify` اقتران العقد والتحقق من
- تغطي `node.pair.request`، و`node.pair.list`، و`node.pair.approve`،
و`node.pair.reject`، و`node.pair.verify` اقتران العقد والتحقق من
bootstrap.
- تعيد `node.list` و`node.describe` حالة العقد المعروفة/المتصلة.
- تحدّث `node.rename` تسمية عقدة مقترنة.
- تمرر `node.invoke` أمرًا إلى عقدة متصلة.
- تعيد `node.invoke.result` النتيجة لطلب invoke.
- تحمل `node.event` الأحداث الصادرة من العقدة عودةً إلى الـ gateway.
- تحدّث `node.canvas.capability.refresh` رموز canvas-capability المحددة النطاق.
- تمثل `node.pending.pull` و`node.pending.ack` واجهات queue الخاصة بالعقد المتصلة.
- تدير `node.pending.enqueue` و`node.pending.drain` العمل المعلّق المتين
- يحدّث `node.rename` تسمية عقدة مقترنة.
- يمرّر `node.invoke` أمرًا إلى عقدة متصلة.
- يعيد `node.invoke.result` النتيجة لطلب استدعاء.
- يحمل `node.event` الأحداث الصادرة من العقدة عائدًا إلى البوابة.
- يقوم `node.canvas.capability.refresh` بتحديث رموز إمكانات canvas
المحصورة بالنطاق.
- تمثل `node.pending.pull` و`node.pending.ack` واجهات API الخاصة بطابور
العقد المتصلة.
- تدير `node.pending.enqueue` و`node.pending.drain` العمل المعلّق الدائم
للعقد غير المتصلة/المنفصلة.
#### عائلات الموافقات
- تغطي `exec.approval.request` و`exec.approval.resolve` طلبات
موافقة exec لمرة واحدة.
- تنتظر `exec.approval.waitDecision` قرار exec pending واحدًا وتعيد
- تغطي `exec.approval.request`، و`exec.approval.get`، و`exec.approval.list`، و
`exec.approval.resolve` طلبات موافقة exec لمرة واحدة بالإضافة إلى
البحث/إعادة التشغيل للموافقات المعلقة.
- ينتظر `exec.approval.waitDecision` قرار موافقة exec واحدًا معلقًا ويعيد
القرار النهائي (أو `null` عند انتهاء المهلة).
- تدير `exec.approvals.get` و`exec.approvals.set` لقطات سياسة موافقات exec الخاصة بالـ gateway.
- تدير `exec.approvals.node.get` و`exec.approvals.node.set` سياسة موافقات exec المحلية للعقدة
عبر أوامر relay الخاصة بالعقدة.
- تغطي `plugin.approval.request`, `plugin.approval.waitDecision`, و
`plugin.approval.resolve` تدفقات الموافقات المعرّفة من المكونات الإضافية.
- تدير `exec.approvals.get` و`exec.approvals.set` لقطات سياسة موافقة
exec على البوابة.
- تدير `exec.approvals.node.get` و`exec.approvals.node.set` سياسة موافقة exec
المحلية للعقدة عبر أوامر relay للعقدة.
- تغطي `plugin.approval.request`، و`plugin.approval.list`،
و`plugin.approval.waitDecision`، و`plugin.approval.resolve`
تدفقات الموافقة المعرفة من الإضافات.
#### عائلات رئيسية أخرى
- الأتمتة:
- تجدول `wake` حقن نص تنبيه فوري أو في heartbeat التالية
- `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`,
`cron.run`, `cron.runs`
- المهارات/الأدوات: `skills.*`, `tools.catalog`, `tools.effective`
- يقوم `wake` بجدولة حقن نص تنبيه فوري أو عند heartbeat التالي
- `cron.list`، و`cron.status`، و`cron.add`، و`cron.update`، و`cron.remove`،
و`cron.run`، و`cron.runs`
- Skills/tools: `skills.*`، و`tools.catalog`، و`tools.effective`
### عائلات الأحداث الشائعة
- `chat`: تحديثات دردشة UI مثل `chat.inject` وغيرها من
أحداث الدردشة الخاصة بالنصوص فقط.
- `session.message` و`session.tool`: تحديثات النصوص/تدفق الأحداث
لجلسة مشتركة.
- `chat`: تحديثات دردشة واجهة المستخدم مثل `chat.inject` وغيرها من
أحداث الدردشة الخاصة بالسجل فقط.
- `session.message` و`session.tool`: تحديثات السجل/تيار الأحداث لجلسة
مشترَك بها.
- `sessions.changed`: تغيّر فهرس الجلسات أو بياناتها الوصفية.
- `presence`: تحديثات لقطة حضور النظام.
- `tick`: حدث keepalive / liveness دوري.
- `health`: تحديث لقطة سلامة gateway.
- `heartbeat`: تحديث تدفق أحداث heartbeat.
- `cron`: حدث تغيّر تشغيل/وظيفة cron.
- `shutdown`: إشعار إيقاف gateway.
- `node.pair.requested` / `node.pair.resolved`: دورة حياة اقتران العقد.
- `node.invoke.request`: بث طلب استدعاء عقدة.
- `device.pair.requested` / `device.pair.resolved`: دورة حياة الأجهزة المقترنة.
- `voicewake.changed`: تغيّر إعداد محفزات كلمة التنبيه.
- `tick`: حدث دوري للإبقاء على الحياة / الحيوية.
- `health`: تحديث لقطة صحة البوابة.
- `heartbeat`: تحديث تيار أحداث heartbeat.
- `cron`: حدث تغير تشغيل/مهمة cron.
- `shutdown`: إشعار إيقاف تشغيل البوابة.
- `node.pair.requested` / `node.pair.resolved`: دورة حياة اقتران العقدة.
- `node.invoke.request`: بث طلب استدعاء العقدة.
- `device.pair.requested` / `device.pair.resolved`: دورة حياة الجهاز المقترن.
- `voicewake.changed`: تغيّر إعداد محفز كلمة التنبيه.
- `exec.approval.requested` / `exec.approval.resolved`: دورة حياة
موافقة exec.
- `plugin.approval.requested` / `plugin.approval.resolved`: دورة حياة موافقة
المكون الإضافي.
الإضافة.
### طرق مساعدة العقد
### أساليب مساعدة العقدة
- يمكن للعقد استدعاء `skills.bins` لجلب القائمة الحالية للملفات التنفيذية
الخاصة بالمهارات لفحوصات allow التلقائية.
- يمكن للعقد استدعاء `skills.bins` لجلب القائمة الحالية لملفات Skills التنفيذية
لفحوصات السماح التلقائي.
### طرق مساعدة المشغّل
### أساليب مساعدة operator
- يمكن للمشغّلين استدعاء `tools.catalog` ‏(`operator.read`) لجلب فهرس الأدوات وقت التشغيل لوكيل
ما. وتتضمن الاستجابة أدوات مجمّعة وبيانات وصفية للمصدر:
- `source`: ‏`core` أو `plugin`
- `pluginId`: مالك المكون الإضافي عندما يكون `source="plugin"`
- `optional`: ما إذا كانت أداة المكون الإضافي اختيارية
- يمكن للمشغّلين استدعاء `tools.effective` ‏(`operator.read`) لجلب جرد الأدوات
الفعّال وقت التشغيل لجلسة ما.
- يمكن للمشغّلين استدعاء `tools.catalog` (`operator.read`) لجلب فهرس الأدوات في وقت التشغيل
لوكيل. تتضمن الاستجابة أدوات مجمعة وبيانات وصفية للمصدر:
- `source`: `core` أو `plugin`
- `pluginId`: مالك الإضافة عندما يكون `source="plugin"`
- `optional`: ما إذا كانت أداة الإضافة اختيارية
- يمكن للمشغّلين استدعاء `tools.effective` (`operator.read`) لجلب جرد الأدوات الفعّال في وقت التشغيل
لجلسة.
- `sessionKey` مطلوب.
- يستمد gateway سياق وقت التشغيل الموثوق من الجلسة على جانب الخادم بدل قبول
سياق مصادقة أو تسليم يقدمه المستدعي.
- تكون الاستجابة محددة بالجسلة وتعكس ما الذي تستطيع المحادثة النشطة استخدامه الآن،
بما في ذلك الأدوات الأساسية وأدوات المكونات الإضافية وأدوات القنوات.
- يمكن للمشغّلين استدعاء `skills.status` ‏(`operator.read`) لجلب جرد
المهارات المرئي لوكيل ما.
- `agentId` اختياري؛ اتركه فارغًا لقراءة مساحة عمل الوكيل الافتراضي.
- تستخلص البوابة سياق وقت التشغيل الموثوق من الجلسة من جهة الخادم بدلًا من قبول
سياق المصادقة أو التسليم المورَّد من المستدعي.
- تكون الاستجابة محصورة بالجلسة وتعكس ما يمكن للمحادثة النشطة استخدامه الآن،
بما في ذلك أدوات core، وplugin، والقنوات.
- يمكن للمشغّلين استدعاء `skills.status` (`operator.read`) لجلب
جرد Skills المرئي لوكيل.
- `agentId` اختياري؛ احذفه لقراءة مساحة عمل الوكيل الافتراضية.
- تتضمن الاستجابة الأهلية، والمتطلبات المفقودة، وفحوصات الإعداد، و
خيارات التثبيت المنقحة من دون كشف القيم السرية الخام.
- يمكن للمشغّلين استدعاء `skills.search` و`skills.detail` ‏(`operator.read`) للحصول على
خيارات التثبيت المنقّحة من دون كشف قيم الأسرار الخام.
- يمكن للمشغّلين استدعاء `skills.search` و`skills.detail` (`operator.read`) للحصول على
بيانات اكتشاف ClawHub الوصفية.
- يمكن للمشغّلين استدعاء `skills.install` ‏(`operator.admin`) في وضعين:
- وضع ClawHub: ‏`{ source: "clawhub", slug, version?, force? }` يثبّت
مجلد مهارة داخل دليل `skills/` في مساحة عمل الوكيل الافتراضي.
- وضع مثبّت Gateway: ‏`{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
يشغّل إجراء `metadata.openclaw.install` مصرّحًا به على مضيف gateway.
- يمكن للمشغّلين استدعاء `skills.update` ‏(`operator.admin`) في وضعين:
- يحدّث وضع ClawHub slug متتبعًا واحدًا أو جميع عمليات تثبيت ClawHub المتتبعة في
مساحة عمل الوكيل الافتراضي.
- يقوم وضع config بترقيع قيم `skills.entries.<skillKey>` مثل `enabled`,
`apiKey`, و`env`.
- يمكن للمشغّلين استدعاء `skills.install` (`operator.admin`) في وضعين:
- وضع ClawHub: `{ source: "clawhub", slug, version?, force? }` يثبت
مجلد Skill داخل الدليل `skills/` لمساحة عمل الوكيل الافتراضية.
- وضع مُثبّت البوابة: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
يشغّل إجراء `metadata.openclaw.install` معلنًا على مضيف البوابة.
- يمكن للمشغّلين استدعاء `skills.update` (`operator.admin`) في وضعين:
- يقوم وضع ClawHub بتحديث slug متعقّب واحد أو جميع تثبيتات ClawHub المتعقبة في
مساحة عمل الوكيل الافتراضية.
- يقوم وضع الإعداد بترقيع قيم `skills.entries.<skillKey>` مثل `enabled`،
و`apiKey`، و`env`.
## موافقات exec
- عندما يحتاج طلب exec إلى موافقة، يبث gateway الحدث `exec.approval.requested`.
- يحل عملاء operator ذلك عبر استدعاء `exec.approval.resolve` ‏(يتطلب النطاق `operator.approvals`).
- بالنسبة إلى `host=node`، يجب أن يتضمن `exec.approval.request` القيمة `systemRunPlan` ‏(`argv`/`cwd`/`rawCommand`/بيانات الجلسة الوصفية القانونية). وتُرفض الطلبات التي تفتقد `systemRunPlan`.
- بعد الموافقة، تعيد استدعاءات `node.invoke system.run` المُمررة استخدام
`systemRunPlan` القانوني ذاك بوصفه السياق الموثوق للأمر/cwd/الجلسة.
- إذا عدّل مستدعٍ القيم `command`, `rawCommand`, `cwd`, `agentId`, أو
`sessionKey` بين التحضير والتمرير النهائي الموافق عليه لـ `system.run`، فإن
gateway يرفض التشغيل بدل الوثوق بالحمولة المعدلة.
- عندما يحتاج طلب exec إلى موافقة، تبث البوابة `exec.approval.requested`.
- يحسم عملاء operator ذلك عبر استدعاء `exec.approval.resolve` (يتطلب النطاق `operator.approvals`).
- بالنسبة إلى `host=node`، يجب أن يتضمن `exec.approval.request` القيمة `systemRunPlan` (الحقول القياسية `argv`/`cwd`/`rawCommand`/بيانات تعريف الجلسة). تُرفض الطلبات التي تفتقد `systemRunPlan`.
- بعد الموافقة، تعيد استدعاءات `node.invoke system.run` المُمرَّرة استخدام
`systemRunPlan` القياسي هذا بوصفه سياق الأمر/`cwd`/الجلسة المعتمد.
- إذا قام مستدعٍ بتعديل `command` أو`rawCommand` أو`cwd` أو`agentId` أو
`sessionKey` بين التحضير وتمرير `system.run` الموافق عليه النهائي، فإن
البوابة ترفض التشغيل بدلًا من الوثوق بالحمولة المعدلة.
## fallback تسليم الوكيل
## بديل تسليم الوكيل
- يمكن لطلبات `agent` أن تتضمن `deliver=true` لطلب تسليم صادر.
- يبقي `bestEffortDeliver=false` السلوك صارمًا: إذ تعيد أهداف التسليم غير المحلولة أو الداخلية فقط الخطأ `INVALID_REQUEST`.
- يسمح `bestEffortDeliver=true` بالرجوع الاحتياطي إلى التنفيذ داخل الجلسة فقط عندما لا يمكن حل أي مسار خارجي قابل للتسليم (مثل جلسات internal/webchat أو إعدادات متعددة القنوات ملتبسة).
- يمكن أن تتضمن طلبات `agent` القيمة `deliver=true` لطلب تسليم صادر.
- يحافظ `bestEffortDeliver=false` على السلوك الصارم: أهداف التسليم غير المحلولة أو الداخلية فقط تعيد `INVALID_REQUEST`.
- يسمح `bestEffortDeliver=true` بالرجوع إلى تنفيذ على مستوى الجلسة فقط عندما لا يمكن حل مسار خارجي قابل للتسليم (على سبيل المثال جلسات داخلية/WebChat أو إعدادات متعددة القنوات ملتبسة).
## الإصدارات
- يعيش `PROTOCOL_VERSION` في `src/gateway/protocol/schema.ts`.
- يرسل العملاء `minProtocol` + `maxProtocol`؛ ويرفض الخادم عدم التطابق.
- تُولَّد schemas + models من تعريفات TypeBox:
- توجد `PROTOCOL_VERSION` في `src/gateway/protocol/schema.ts`.
- يرسل العملاء `minProtocol` + `maxProtocol`؛ ويرفض الخادم حالات عدم التطابق.
- يتم توليد المخططات + النماذج من تعريفات TypeBox:
- `pnpm protocol:gen`
- `pnpm protocol:gen:swift`
- `pnpm protocol:check`
## المصادقة
- تستخدم مصادقة gateway بالسر المشترك إما `connect.params.auth.token` أو
`connect.params.auth.password`، بحسب وضع المصادقة المكوَّن.
- تلبّي الأوضاع الحاملة للهوية مثل Tailscale Serve
(`gateway.auth.allowTailscale: true`) أو `gateway.auth.mode: "trusted-proxy"`
غير المعتمد على loopback فحص مصادقة الاتصال من
ترويسات الطلب بدل `connect.params.auth.*`.
- يتجاوز `gateway.auth.mode: "none"` الخاص بالدخول الخاص فحص المصادقة بالسر المشترك
بالكامل؛ ولا تعرض هذا الوضع على دخول عام/غير موثوق.
- بعد الاقتران، يصدر Gateway **device token** محددة بالدور + النطاقات الخاصة بالاتصال.
وتُعاد في `hello-ok.auth.deviceToken` ويجب أن يحتفظ بها العميل
- تستخدم مصادقة البوابة بالسر المشترك `connect.params.auth.token` أو
`connect.params.auth.password`، حسب وضع المصادقة المضبوط.
- أوضاع حمل الهوية مثل Tailscale Serve
(`gateway.auth.allowTailscale: true`) أو
`gateway.auth.mode: "trusted-proxy"` غير loopback
تحقق فحص مصادقة الاتصال من ترويسات الطلب بدلًا من `connect.params.auth.*`.
- يتجاوز الوضع `gateway.auth.mode: "none"` للولوج الخاص مصادقة الاتصال بالسر المشترك
بالكامل؛ لا تعرّض هذا الوضع على منافذ عامة/غير موثوقة.
- بعد الاقتران، تصدر البوابة **رمز جهاز** محصورًا بدور الاتصال +
النطاقات. ويُعاد في `hello-ok.auth.deviceToken` ويجب أن يحفظه العميل
للاتصالات المستقبلية.
- يجب على العملاء الاحتفاظ بالـ `hello-ok.auth.deviceToken` الأساسية بعد أي
- يجب على العملاء حفظ `hello-ok.auth.deviceToken` الأساسي بعد أي
اتصال ناجح.
- كما يجب عند إعادة الاتصال باستخدام **device token** هذه المخزنة
إعادة استخدام مجموعة النطاقات المعتمدة المخزنة الخاصة بتلك الـ token. وهذا يحافظ على
وصول read/probe/status الذي مُنح بالفعل ويتجنب انهيار إعادة الاتصال بصمت إلى
نطاق ضمني أضيق خاص بالإدارة فقط.
- تكون أسبقية مصادقة الاتصال العادية: token/password المشتركة الصريحة أولًا، ثم
`deviceToken` الصريحة، ثم token المخزنة لكل جهاز، ثم bootstrap token.
- إن إدخالات `hello-ok.auth.deviceTokens` الإضافية هي tokens مسلّمة ضمن bootstrap.
ولا تحتفظ بها إلا عندما يستخدم الاتصال مصادقة bootstrap عبر نقل موثوق
مثل `wss://` أو loopback/local pairing.
- إذا قدّم عميل **`deviceToken` صريحة** أو `scopes` صريحة، فإن
مجموعة النطاقات المطلوبة من المستدعي تبقى هي المرجع؛ ولا يُعاد استخدام النطاقات المخبأة إلا
عندما يعيد العميل استخدام token المخزنة لكل جهاز.
- يمكن تدوير/إلغاء device tokens عبر `device.token.rotate` و
`device.token.revoke` ‏(يتطلب `operator.pairing`).
- يبقى إصدار/تدوير token مقيدًا بمجموعة الأدوار المعتمدة المسجلة في
إدخال اقتران ذلك الجهاز؛ ولا يمكن لتدوير token توسيع الجهاز إلى
- يجب أن تؤدي إعادة الاتصال باستخدام رمز الجهاز **المخزَّن** هذا أيضًا إلى إعادة استخدام
مجموعة النطاقات المعتمدة والمخزنة لذلك الرمز. وهذا يحافظ على وصول
القراءة/الفحص/الحالة الذي مُنح سابقًا ويمنع تقليص الاتصالات المعاد إنشاؤها
بصمت إلى نطاق إدارة ضمني أضيق.
- تكون أولوية مصادقة الاتصال العادية: الرمز/كلمة المرور المشتركة الصريحة أولًا، ثم
`deviceToken` الصريح، ثم الرمز المخزَّن لكل جهاز، ثم رمز bootstrap.
- تمثل إدخالات `hello-ok.auth.deviceTokens` الإضافية رموز تسليم bootstrap.
احفظها فقط عندما يستخدم الاتصال مصادقة bootstrap على ناقل موثوق
مثل `wss://` أو الاقتران المحلي/loopback.
- إذا قدّم عميل `deviceToken` **صريحًا** أو نطاقات `scopes` صريحة، فإن
مجموعة النطاقات المطلوبة من المستدعي تظل هي المعتمدة؛ ولا يعاد استخدام النطاقات المخزنة
إلا عندما يعيد العميل استخدام الرمز المخزَّن لكل جهاز.
- يمكن تدوير/إبطال رموز الأجهزة عبر `device.token.rotate` و
`device.token.revoke` (يتطلب النطاق `operator.pairing`).
- يظل إصدار/تدوير الرموز محصورًا ضمن مجموعة الأدوار المعتمدة والمسجلة في
إدخال اقتران ذلك الجهاز؛ ولا يمكن لتدوير رمز أن يوسّع الجهاز إلى
دور لم تمنحه موافقة الاقتران أصلًا.
- بالنسبة إلى جلسات token الخاصة بالأجهزة المقترنة، تكون إدارة الأجهزة محددة بالذات ما لم يكن
للمستدعي أيضًا `operator.admin`: إذ لا يستطيع غير المسؤولين إزالة/إلغاء/تدوير
إلا إدخال الجهاز **الخاص بهم**.
- كما يتحقق `device.token.rotate` من مجموعة نطاقات operator المطلوبة مقابل
نطاقات جلسة المستدعي الحالية. ولا يستطيع غير المسؤولين تدوير token إلى
مجموعة نطاقات operator أوسع مما يملكونه بالفعل.
- تتضمن إخفاقات المصادقة `error.details.code` بالإضافة إلى تلميحات الاستعادة:
- `error.details.canRetryWithDeviceToken` ‏(قيمة منطقية)
- `error.details.recommendedNextStep` ‏(`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
- بالنسبة إلى جلسات رموز الأجهزة المقترنة، تكون إدارة الجهاز محصورة ذاتيًا ما لم
يكن لدى المستدعي أيضًا `operator.admin`: لا يمكن للمستدعين غير الإداريين إزالة/إبطال/تدوير
إلا إدخال جهازهم **الخاص**.
- يتحقق `device.token.rotate` أيضًا من مجموعة نطاقات operator المطلوبة في مقابل
نطاقات جلسة المستدعي الحالية. لا يمكن للمستدعين غير الإداريين تدوير رمز
إلى مجموعة نطاقات operator أوسع مما يملكونه بالفعل.
- تتضمن حالات فشل المصادقة `error.details.code` بالإضافة إلى تلميحات الاسترداد:
- `error.details.canRetryWithDeviceToken` (منطقي)
- `error.details.recommendedNextStep` (`retry_with_device_token`، `update_auth_configuration`، `update_auth_credentials`، `wait_then_retry`، `review_auth_configuration`)
- سلوك العميل مع `AUTH_TOKEN_MISMATCH`:
- يمكن للعملاء الموثوقين محاولة إعادة محاولة واحدة محدودة باستخدام token مخزنة لكل جهاز.
- إذا فشلت إعادة المحاولة تلك، فيجب على العملاء إيقاف حلقات إعادة الاتصال التلقائية وإظهار إرشادات لاتخاذ إجراء من المشغّل.
- يمكن للعملاء الموثوقين محاولة إعادة واحدة محدودة باستخدام رمز
مخزَّن لكل جهاز.
- إذا فشلت إعادة المحاولة تلك، يجب على العملاء إيقاف حلقات إعادة الاتصال التلقائية
وإظهار إرشادات لإجراء من المشغّل.
## هوية الجهاز + الاقتران
- يجب على العقد تضمين هوية جهاز ثابتة (`device.id`) مشتقة من
- يجب أن تتضمن العقد هوية جهاز مستقرة (`device.id`) مشتقة من
بصمة زوج مفاتيح.
- تصدر Gateways tokens لكل جهاز + دور.
- موافقات الاقتران مطلوبة لمعرّفات الأجهزة الجديدة ما لم يكن تفعيل الموافقة التلقائية
المحلية مفعّلًا.
- تتمحور الموافقة التلقائية للاقتران حول اتصالات loopback المحلية المباشرة.
- يملك OpenClaw أيضًا مسار self-connect ضيقًا محليًا على مستوى backend/container
لتدفقات المساعدات الموثوقة ذات الأسرار المشتركة.
- ما تزال اتصالات tailnet أو LAN على المضيف نفسه تُعامل على أنها بعيدة لأغراض الاقتران وتتطلب موافقة.
- يجب أن تتضمن جميع عملاء WS هوية `device` أثناء `connect` ‏(operator + node).
ويمكن لـ Control UI حذفها فقط في هذه الأوضاع:
- `gateway.controlUi.allowInsecureAuth=true` لتوافق HTTP غير الآمن على localhost فقط.
- نجاح مصادقة operator في Control UI ضمن `gateway.auth.mode: "trusted-proxy"`.
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` ‏(وضع طوارئ، خفض أمني شديد).
- يجب أن توقّع جميع الاتصالات `connect.challenge` nonce التي يوفرها الخادم.
- تصدر البوابات رموزًا لكل جهاز + دور.
- تتطلب معتمَدات الاقتران لمعرّفات الأجهزة الجديدة موافقات اقتران ما لم يكن
التلقائي المحلي مفعّلًا.
- يتمحور الاعتماد التلقائي للاقتران حول اتصالات loopback المحلية المباشرة.
- لدى OpenClaw أيضًا مسار اتصال ذاتي ضيق على مستوى الواجهة الخلفية/الحاوية من أجل
تدفقات المساعد الموثوقة ذات السر المشترك.
- ما تزال اتصالات tailnet أو LAN على المضيف نفسه تُعامل باعتبارها بعيدة من أجل الاقتران
وتتطلب موافقة.
- يجب أن تتضمن جميع عملاء WS هوية `device` أثناء `connect` (operator + node).
يمكن لـ Control UI حذفها فقط في هذه الأوضاع:
- `gateway.controlUi.allowInsecureAuth=true` من أجل توافق HTTP غير الآمن على localhost فقط.
- نجاح مصادقة Control UI الخاصة بـ operator مع `gateway.auth.mode: "trusted-proxy"`.
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (وضع طوارئ، خفض أمني شديد).
- يجب على جميع الاتصالات توقيع nonce المقدَّم من الخادم في `connect.challenge`.
### تشخيصات ترحيل مصادقة الجهاز
بالنسبة إلى العملاء القدامى الذين ما زالوا يستخدمون سلوك التوقيع السابق للتحدي، يعيد `connect` الآن
رموز تفاصيل `DEVICE_AUTH_*` ضمن `error.details.code` مع قيمة ثابتة `error.details.reason`.
أكواد تفاصيل `DEVICE_AUTH_*` ضمن `error.details.code` مع `error.details.reason` ثابت.
إخفاقات الترحيل الشائعة:
| الرسالة | details.code | details.reason | المعنى |
| -------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | حذف العميل `device.nonce` (أو أرسل قيمة فارغة). |
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | وقّع العميل باستخدام nonce قديمة/خاطئة. |
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | لا تطابق حمولة التوقيع حمولة v2. |
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | يقع الطابع الزمني الموقَّع خارج الانحراف المسموح. |
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | لا يطابق `device.id` بصمة المفتاح العام. |
| `device public key invalid`| `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | فشل تنسيق/تحويل المفتاح العام إلى الصيغة القانونية. |
| الرسالة | details.code | details.reason | المعنى |
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | حذف العميل `device.nonce` (أو أرسله فارغًا). |
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | وقّع العميل باستخدام nonce قديم/خاطئ. |
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | حمولة التوقيع لا تطابق حمولة v2. |
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | الطابع الزمني الموقَّع خارج الانحراف المسموح به. |
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | لا يطابق `device.id` بصمة المفتاح العام. |
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | فشل تنسيق/توحيد المفتاح العام. |
هدف الترحيل:
- انتظر دائمًا `connect.challenge`.
- وقّع حمولة v2 التي تتضمن server nonce.
- أرسل nonce نفسها ضمن `connect.params.device.nonce`.
- وقّع حمولة v2 التي تتضمن nonce الخاص بالخادم.
- أرسل nonce نفسه في `connect.params.device.nonce`.
- حمولة التوقيع المفضلة هي `v3`، التي تربط `platform` و`deviceFamily`
بالإضافة إلى حقول الجهاز/العميل/الدور/النطاقات/token/nonce.
- ما تزال توقيعات `v2` القديمة مقبولة للتوافق، لكن
تثبيت البيانات الوصفية للأجهزة المقترنة ما يزال يتحكم في سياسة الأوامر عند إعادة الاتصال.
بالإضافة إلى حقول الجهاز/العميل/الدور/النطاقات/الرمز/nonce.
- ما تزال توقيعات `v2` القديمة مقبولة من أجل التوافق، لكن تثبيت بيانات
الجهاز المقترن الوصفية ما يزال يتحكم بسياسة الأوامر عند إعادة الاتصال.
## TLS + التثبيت
- TLS مدعوم لاتصالات WS.
- يمكن للعملاء اختياريًا تثبيت بصمة شهادة gateway (راجع إعداد `gateway.tls`
بالإضافة إلى `gateway.remote.tlsFingerprint` أو CLI `--tls-fingerprint`).
- دعم TLS متاح لاتصالات WS.
- يمكن للعملاء تثبيت بصمة شهادة البوابة اختياريًا (راجع إعداد `gateway.tls`
بالإضافة إلى `gateway.remote.tlsFingerprint` أو علم CLI `--tls-fingerprint`).
## النطاق
يعرض هذا البروتوكول **واجهة gateway API الكاملة** (الحالة، والقنوات، والنماذج، والدردشة،
والوكيل، والجلسات، والعقد، والموافقات، وغير ذلك). ويُعرَّف السطح الدقيق بواسطة
TypeBox schemas في `src/gateway/protocol/schema.ts`.
يكشف هذا البروتوكول **واجهة API الكاملة للبوابة** (الحالة، والقنوات، والنماذج، والدردشة،
والوكيل، والجلسات، والعقد، والموافقات، وغير ذلك). ويتم تعريف السطح الدقيق بواسطة
مخططات TypeBox في `src/gateway/protocol/schema.ts`.

350
docs/ar/gateway/troubleshooting.md
View File

@ -1,22 +1,22 @@
---
read_when:
- أحالَك مركز استكشاف الأخطاء وإصلاحها إلى هنا للحصول على تشخيص أعمق
- أحالَك مركز استكشاف الأخطاء وإصلاحها إلى هنا للتشخيص الأعمق
- تحتاج إلى أقسام دليل تشغيل مستقرة قائمة على الأعراض مع أوامر دقيقة
summary: دليل متعمق لاستكشاف الأخطاء وإصلاحها للـ gateway، والقنوات، والأتمتة، والعُقد، والمتصفح
summary: دليل متعمق لاستكشاف الأخطاء وإصلاحها للبوابة والقنوات والأتمتة والعُقد والمتصفح
title: استكشاف الأخطاء وإصلاحها
x-i18n:
generated_at: "2026-04-07T07:18:21Z"
generated_at: "2026-04-08T02:16:18Z"
model: gpt-5.4
provider: openai
source_hash: e0202e8858310a0bfc1c994cd37b01c3b2d6c73c8a74740094e92dc3c4c36729
source_hash: 02c9537845248db0c9d315bf581338a93215fe6fe3688ed96c7105cbb19fe6ba
source_path: gateway/troubleshooting.md
workflow: 15
---
# استكشاف أخطاء Gateway وإصلاحها
# استكشاف أخطاء البوابة وإصلاحها
هذه الصفحة هي دليل التشغيل المتعمق.
ابدأ من [/help/troubleshooting](/ar/help/troubleshooting) إذا كنت تريد أولًا مسار الفرز السريع.
ابدأ من [/help/troubleshooting](/ar/help/troubleshooting) إذا كنت تريد تدفق الفرز السريع أولًا.
## تسلسل الأوامر
@ -30,16 +30,16 @@ openclaw doctor
openclaw channels status --probe
```
الإشارات المتوقعة للحالة السليمة:
الإشارات السليمة المتوقعة:
- يعرض `openclaw gateway status` القيمتين `Runtime: running` و`RPC probe: ok`.
- يُبلغ `openclaw doctor` بعدم وجود مشكلات حظر في الإعداد/الخدمة.
- يعرض `openclaw channels status --probe` حالة النقل المباشر لكل حساب، ونتائج
الفحص/التدقيق عند الدعم، مثل `works` أو `audit ok`.
- يعرض `openclaw gateway status` القيمة `Runtime: running` و `RPC probe: ok`.
- يُبلغ `openclaw doctor` عن عدم وجود مشكلات حظر في الإعدادات/الخدمة.
- يعرض `openclaw channels status --probe` حالة النقل المباشرة لكل حساب،
وحيثما كان ذلك مدعومًا، نتائج الفحص/التدقيق مثل `works` أو `audit ok`.
## يتطلب Anthropic 429 استخدامًا إضافيًا للسياق الطويل
## خطأ Anthropic 429: استخدام إضافي مطلوب للسياق الطويل
استخدم هذا القسم عندما تتضمن السجلات/الأخطاء:
استخدم هذا عندما تتضمن السجلات/الأخطاء:
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
```bash
@ -56,9 +56,9 @@ openclaw config get agents.defaults.models
خيارات الإصلاح:
1. عطّل `context1m` لهذا النموذج للعودة إلى نافذة السياق العادية.
2. استخدم بيانات اعتماد Anthropic مؤهلة لطلبات السياق الطويل، أو بدّل إلى Anthropic API key.
3. اضبط نماذج احتياطية حتى تستمر التشغيلات عند رفض طلبات Anthropic للسياق الطويل.
1. عطّل `context1m` لذلك النموذج للرجوع إلى نافذة السياق العادية.
2. استخدم بيانات اعتماد Anthropic مؤهلة لطلبات السياق الطويل، أو انتقل إلى مفتاح Anthropic API.
3. اضبط نماذج بديلة حتى تستمر التشغيلات عندما تُرفض طلبات Anthropic ذات السياق الطويل.
ذو صلة:
@ -66,6 +66,60 @@ openclaw config get agents.defaults.models
- [/reference/token-use](/ar/reference/token-use)
- [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/ar/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
## الواجهة الخلفية المحلية المتوافقة مع OpenAI تجتاز الفحوصات المباشرة لكن تشغيلات الوكيل تفشل
استخدم هذا عندما:
- ينجح `curl ... /v1/models`
- تنجح استدعاءات `/v1/chat/completions` المباشرة الصغيرة
- تفشل تشغيلات نماذج OpenClaw فقط في أدوار الوكيل العادية
```bash
curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
-H 'content-type: application/json' \
-d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow
```
ابحث عن:
- أن الاستدعاءات الصغيرة المباشرة تنجح، لكن تشغيلات OpenClaw تفشل فقط مع الموجّهات الأكبر
- أخطاء في الواجهة الخلفية تشير إلى أن `messages[].content` يتوقع سلسلة نصية
- أعطال الواجهة الخلفية التي تظهر فقط مع أعداد أكبر من رموز الموجّه أو موجّهات
وقت تشغيل الوكيل الكاملة
الأنماط الشائعة:
- `messages[...].content: invalid type: sequence, expected a string` ← الواجهة الخلفية
ترفض أجزاء محتوى Chat Completions المهيكلة. الإصلاح: اضبط
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
- تنجح الطلبات المباشرة الصغيرة، لكن تشغيلات وكيل OpenClaw تفشل مع أعطال
الواجهة الخلفية/النموذج (مثلًا Gemma على بعض إصدارات `inferrs`) ← من
المرجح أن نقل OpenClaw صحيح بالفعل؛ الواجهة الخلفية هي التي تفشل مع شكل
موجّه وقت تشغيل الوكيل الأكبر.
- تتراجع حالات الفشل بعد تعطيل الأدوات لكنها لا تختفي ← كانت مخططات الأدوات
جزءًا من الضغط، لكن المشكلة المتبقية لا تزال في سعة النموذج/الخادم upstream
أو في خطأ بالواجهة الخلفية.
خيارات الإصلاح:
1. اضبط `compat.requiresStringContent: true` لواجهات Chat Completions الخلفية التي تقبل السلاسل النصية فقط.
2. اضبط `compat.supportsTools: false` للنماذج/الواجهات الخلفية التي لا تستطيع التعامل
مع سطح مخطط أدوات OpenClaw بشكل موثوق.
3. خفّض ضغط الموجّه حيثما أمكن: تهيئة أولية أصغر لمساحة العمل، وسجل جلسة أقصر،
أو نموذج محلي أخف، أو واجهة خلفية ذات دعم أقوى للسياق الطويل.
4. إذا استمرت الطلبات المباشرة الصغيرة بالنجاح بينما ما زالت أدوار وكيل OpenClaw تتعطل
داخل الواجهة الخلفية، فاعتبر ذلك قيدًا في الخادم/النموذج upstream وقدّم
بلاغ إعادة إنتاج هناك مع شكل الحمولة المقبول.
ذو صلة:
- [/gateway/local-models](/ar/gateway/local-models)
- [/gateway/configuration#models](/ar/gateway/configuration#models)
- [/gateway/configuration-reference#openai-compatible-endpoints](/ar/gateway/configuration-reference#openai-compatible-endpoints)
## لا توجد ردود
إذا كانت القنوات تعمل لكن لا يوجد أي رد، فتحقق من التوجيه والسياسة قبل إعادة توصيل أي شيء.
@ -84,11 +138,11 @@ openclaw logs --follow
- تقييد الإشارة في المجموعات (`requireMention`، `mentionPatterns`).
- عدم تطابق قائمة السماح للقناة/المجموعة.
العلامات الشائعة:
الأنماط الشائعة:
- `drop guild message (mention required` → تم تجاهل رسالة المجموعة حتى حدوث إشارة.
- `pairing request` → يحتاج المرسل إلى موافقة.
- `blocked` / `allowlist` → تمّت تصفية المرسل/القناة بواسطة السياسة.
- `drop guild message (mention required` ← تم تجاهل رسالة المجموعة حتى حدوث إشارة.
- `pairing request` ← يحتاج المرسل إلى موافقة.
- `blocked` / `allowlist` ← تمت تصفية المرسل/القناة بواسطة السياسة.
ذو صلة:
@ -96,9 +150,9 @@ openclaw logs --follow
- [/channels/pairing](/ar/channels/pairing)
- [/channels/groups](/ar/channels/groups)
## اتصال dashboard/control UI
## اتصال واجهة dashboard/control UI
عندما يتعذر على dashboard/control UI الاتصال، تحقّق من عنوان URL، ووضع المصادقة، وافتراضات السياق الآمن.
عندما لا يتصل dashboard/control UI، تحقّق من عنوان URL ووضع المصادقة وافتراضات السياق الآمن.
```bash
openclaw gateway status
@ -110,47 +164,49 @@ openclaw gateway status --json
ابحث عن:
- عنوان URL الصحيح للفحص وdashboard.
- عدم تطابق وضع المصادقة/الرمز المميز بين العميل وgateway.
- استخدام HTTP في مواضع تتطلب هوية الجهاز.
- عنوان URL الصحيح للفحص ولوحة التحكم.
- عدم تطابق وضع/رمز المصادقة بين العميل والبوابة.
- استخدام HTTP حيث تكون هوية الجهاز مطلوبة.
العلامات الشائعة:
الأنماط الشائعة:
- `device identity required` → سياق غير آمن أو مصادقة جهاز مفقودة.
- `origin not allowed` → `Origin` الخاص بالمتصفح ليس ضمن `gateway.controlUi.allowedOrigins`
(أو أنك تتصل من origin متصفح غير loopback بدون
- `device identity required` ← سياق غير آمن أو مصادقة جهاز مفقودة.
- `origin not allowed` ← قيمة `Origin` في المتصفح غير موجودة في `gateway.controlUi.allowedOrigins`
(أو أنك تتصل من مصدر متصفح غير loopback من دون
قائمة سماح صريحة).
- `device nonce required` / `device nonce mismatch` → العميل لا يكمل
تدفق مصادقة الجهاز القائم على التحدي (`connect.challenge` + `device.nonce`).
- `device signature invalid` / `device signature expired` → العميل وقّع الحمولة الخطأ
(أو استخدم طابعًا زمنيًا قديمًا) للمصافحة الحالية.
- `AUTH_TOKEN_MISMATCH` مع `canRetryWithDeviceToken=true` → يمكن للعميل تنفيذ إعادة محاولة موثوقة واحدة باستخدام رمز الجهاز المميز المخزّن مؤقتًا.
- تعيد محاولة الرمز المخزّن مؤقتًا هذه استخدام مجموعة النطاقات المخزّنة مع
رمز الجهاز المميز المقترن. أما المستدعون الذين يستخدمون `deviceToken` صريحًا / `scopes` صريحة فيحتفظون
بمجموعة النطاقات المطلوبة الخاصة بهم.
- خارج مسار إعادة المحاولة هذا، تكون أولوية مصادقة الاتصال هي
الرمز/كلمة المرور المشتركة الصريحة أولًا، ثم `deviceToken` الصريح، ثم رمز الجهاز المخزّن، ثم رمز bootstrap.
- في مسار Control UI غير المتزامن عبر Tailscale Serve، يتم تسلسل المحاولات الفاشلة لنفس
`{scope, ip}` قبل أن يسجل المحدِّد الفشل. لذلك قد تُظهر محاولتان سيئتان
متزامنتان من العميل نفسه الرسالة `retry later`
في المحاولة الثانية بدلًا من عدم تطابقين عاديين.
- `device nonce required` / `device nonce mismatch` ← العميل لا يُكمل
تدفق مصادقة الجهاز المعتمد على التحدي (`connect.challenge` + `device.nonce`).
- `device signature invalid` / `device signature expired` ← وقّع العميل الحمولة الخطأ
(أو بطابع زمني قديم) للمصافحة الحالية.
- `AUTH_TOKEN_MISMATCH` مع `canRetryWithDeviceToken=true` ← يمكن للعميل تنفيذ
إعادة محاولة موثوقة واحدة باستخدام رمز الجهاز المخزن مؤقتًا.
- تعيد إعادة المحاولة باستخدام الرمز المخزن مؤقتًا استخدام مجموعة النطاقات المخزنة مع
رمز الجهاز الموافق عليه. أما مستدعيات `deviceToken` / `scopes` الصريحة فتحافظ على
مجموعة النطاقات المطلوبة بدلًا من ذلك.
- خارج مسار إعادة المحاولة هذا، تكون أولوية مصادقة الاتصال: الرمز
أو كلمة المرور المشتركة الصريحة أولًا، ثم `deviceToken` الصريح، ثم رمز الجهاز المخزن،
ثم رمز التهيئة الأولية.
- في مسار Control UI غير المتزامن عبر Tailscale Serve، تتم
سلسلة المحاولات الفاشلة لنفس `{scope, ip}` قبل أن يسجل المحدِّد الفشل.
لذا قد تظهر في المحاولة الثانية من محاولتين خاطئتين متزامنتين من العميل نفسه رسالة `retry later`
بدلًا من حالتي عدم تطابق عاديتين.
- `too many failed authentication attempts (retry later)` من عميل loopback ذي أصل متصفح
→ يتم حظر الإخفاقات المتكررة من `Origin` المطبّع نفسه مؤقتًا؛ بينما يستخدم أصل localhost آخر حاوية منفصلة.
- تكرار `unauthorized` بعد إعادة المحاولة تلك → انجراف في الرمز المشترك/رمز الجهاز؛ حدّث إعداد الرمز وأعد الموافقة/تدوير رمز الجهاز عند الحاجة.
- `gateway connect failed:` → هدف host/port/url غير صحيح.
← تُحظر الإخفاقات المتكررة من `Origin` المُطبَّع نفسه مؤقتًا؛ بينما يستخدم أصل localhost آخر حاوية منفصلة.
- تكرار `unauthorized` بعد إعادة المحاولة تلك ← يوجد انجراف في الرمز المشترك/رمز الجهاز؛ حدّث إعدادات الرمز وأعِد الموافقة/دوّر رمز الجهاز عند الحاجة.
- `gateway connect failed:` ← المضيف/المنفذ/هدف عنوان URL غير صحيح.
### خريطة سريعة لرموز تفاصيل المصادقة
استخدم `error.details.code` من استجابة `connect` الفاشلة لاختيار الإجراء التالي:
| رمز التفاصيل | المعنى | الإجراء الموصى به |
| --------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | لم يرسل العميل الرمز المشترك المطلوب. | الصق/اضبط الرمز في العميل ثم أعد المحاولة. لمسارات dashboard: استخدم `openclaw config get gateway.auth.token` ثم الصقه في إعدادات Control UI. |
| `AUTH_TOKEN_MISMATCH` | الرمز المشترك لا يطابق رمز مصادقة gateway. | إذا كانت `canRetryWithDeviceToken=true`، فاسمح بإعادة محاولة موثوقة واحدة. تعيد محاولات الرمز المخزّن مؤقتًا استخدام النطاقات المعتمدة المخزنة؛ أما المستدعون الذين يستخدمون `deviceToken` / `scopes` صريحة فيحتفظون بالنطاقات المطلوبة. إذا استمر الفشل، فشغّل [قائمة التحقق من استعادة انجراف الرمز](/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | رمز كل جهاز المخزّن مؤقتًا قديم أو ملغى. | دوّر/أعد الموافقة على رمز الجهاز باستخدام [devices CLI](/cli/devices)، ثم أعد الاتصال. |
| `PAIRING_REQUIRED` | هوية الجهاز معروفة لكنها غير معتمدة لهذا الدور. | وافق على الطلب المعلق: `openclaw devices list` ثم `openclaw devices approve <requestId>`. |
| رمز التفاصيل | المعنى | الإجراء الموصى به |
| ---------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | لم يرسل العميل رمزًا مشتركًا مطلوبًا. | الصق/اضبط الرمز في العميل وأعد المحاولة. لمسارات dashboard: `openclaw config get gateway.auth.token` ثم الصقه في إعدادات Control UI. |
| `AUTH_TOKEN_MISMATCH` | لم يطابق الرمز المشترك رمز مصادقة البوابة. | إذا كانت `canRetryWithDeviceToken=true`، اسمح بإعادة محاولة موثوقة واحدة. تعيد محاولات الرمز المخزن مؤقتًا استخدام النطاقات الموافق عليها والمخزنة؛ أما مستدعيات `deviceToken` / `scopes` الصريحة فتحافظ على النطاقات المطلوبة. وإذا استمر الفشل، شغّل [قائمة التحقق من استرداد انجراف الرمز](/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | رمز كل جهاز المخزن مؤقتًا قديم أو أُلغي. | دوّر/أعِد الموافقة على رمز الجهاز باستخدام [CLI الأجهزة](/cli/devices)، ثم أعد الاتصال. |
| `PAIRING_REQUIRED` | هوية الجهاز معروفة لكنها غير معتمدة لهذا الدور. | وافق على الطلب المعلّق: `openclaw devices list` ثم `openclaw devices approve <requestId>`. |
فحص ترحيل device auth v2:
فحص ترحيل مصادقة الجهاز v2:
```bash
openclaw --version
@ -162,26 +218,26 @@ openclaw gateway status
1. ينتظر `connect.challenge`
2. يوقّع الحمولة المرتبطة بالتحدي
3. يرسل `connect.params.device.nonce` مع nonce التحدي نفسه
3. يرسل `connect.params.device.nonce` باستخدام nonce التحدي نفسه
إذا تم رفض `openclaw devices rotate` / `revoke` / `remove` بشكل غير متوقع:
إذا رُفض `openclaw devices rotate` / `revoke` / `remove` بشكل غير متوقع:
- يمكن لجلسات رموز الأجهزة المقترنة إدارة **أجهزتها الخاصة فقط** إلا إذا
كان لدى المستدعي أيضًا `operator.admin`
- لا يمكن لـ `openclaw devices rotate --scope ...` طلب نطاقات operator
إلا إذا كانت جلسة المستدعي تملكها بالفعل
- يمكن لجلسات رموز الأجهزة المقترنة إدارة **أجهزتها الخاصة فقط** ما لم يكن لدى
الجهة المستدعية أيضًا `operator.admin`
- يمكن للأمر `openclaw devices rotate --scope ...` طلب نطاقات مشغّل فقط
التي تمتلكها جلسة الجهة المستدعية بالفعل
ذو صلة:
- [/web/control-ui](/web/control-ui)
- [/gateway/configuration](/ar/gateway/configuration) (أوضاع مصادقة gateway)
- [/gateway/configuration](/ar/gateway/configuration) (أوضاع مصادقة البوابة)
- [/gateway/trusted-proxy-auth](/ar/gateway/trusted-proxy-auth)
- [/gateway/remote](/ar/gateway/remote)
- [/cli/devices](/cli/devices)
## خدمة Gateway لا تعمل
## خدمة البوابة لا تعمل
استخدم هذا القسم عندما تكون الخدمة مثبتة لكن العملية لا تظل قيد التشغيل.
استخدم هذا عندما تكون الخدمة مثبتة لكن العملية لا تبقى قيد التشغيل.
```bash
openclaw gateway status
@ -193,18 +249,18 @@ openclaw gateway status --deep # يفحص أيضًا الخدمات على م
ابحث عن:
- `Runtime: stopped` مع تلميحات الخروج.
- عدم تطابق إعداد الخدمة (`Config (cli)` مقابل `Config (service)`).
- `Runtime: stopped` مع تلميحات عن الخروج.
- عدم تطابق إعدادات الخدمة (`Config (cli)` مقابل `Config (service)`).
- تعارضات المنفذ/المستمع.
- عمليات تثبيت launchd/systemd/schtasks إضافية عند استخدام `--deep`.
- تلميحات التنظيف في `Other gateway-like services detected (best effort)`.
- تثبيتات launchd/systemd/schtasks إضافية عند استخدام `--deep`.
- تلميحات تنظيف `Other gateway-like services detected (best effort)`.
العلامات الشائعة:
الأنماط الشائعة:
- `Gateway start blocked: set gateway.mode=local` أو `existing config is missing gateway.mode` → وضع gateway المحلي غير مفعّل، أو تم إفساد ملف الإعداد وفقد `gateway.mode`. الإصلاح: اضبط `gateway.mode="local"` في إعدادك، أو أعد تشغيل `openclaw onboard --mode local` / `openclaw setup` لإعادة ختم إعداد الوضع المحلي المتوقع. إذا كنت تشغّل OpenClaw عبر Podman، فمسار الإعداد الافتراضي هو `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` → ربط non-loopback بدون مسار مصادقة صالح للـ gateway (رمز/كلمة مرور، أو trusted-proxy عند ضبطه).
- `another gateway instance is already listening` / `EADDRINUSE` → تعارض منفذ.
- `Other gateway-like services detected (best effort)` → توجد وحدات launchd/systemd/schtasks قديمة أو متوازية. يجب أن تحتفظ معظم الإعدادات بـ gateway واحد لكل جهاز؛ وإذا كنت تحتاج بالفعل إلى أكثر من واحد، فاعزل المنافذ + الإعداد + الحالة + مساحة العمل. راجع [/gateway#multiple-gateways-same-host](/ar/gateway#multiple-gateways-same-host).
- `Gateway start blocked: set gateway.mode=local` أو `existing config is missing gateway.mode` ← لم يتم تمكين وضع البوابة المحلية، أو تم العبث بملف الإعدادات وفقد `gateway.mode`. الإصلاح: اضبط `gateway.mode="local"` في إعداداتك، أو أعد تشغيل `openclaw onboard --mode local` / `openclaw setup` لإعادة ختم إعدادات الوضع المحلي المتوقعة. إذا كنت تشغّل OpenClaw عبر Podman، فمسار الإعدادات الافتراضي هو `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` ← ربط غير loopback من دون مسار مصادقة صالح للبوابة (رمز/كلمة مرور، أو trusted-proxy حيث يكون مضبوطًا).
- `another gateway instance is already listening` / `EADDRINUSE` ← تعارض منفذ.
- `Other gateway-like services detected (best effort)` ← توجد وحدات launchd/systemd/schtasks قديمة أو متوازية. معظم الإعدادات يجب أن تحتفظ ببوابة واحدة لكل جهاز؛ وإذا كنت تحتاج فعلًا إلى أكثر من واحدة، فاعزل المنافذ + الإعدادات/الحالة/مساحة العمل. راجع [/gateway#multiple-gateways-same-host](/ar/gateway#multiple-gateways-same-host).
ذو صلة:
@ -212,9 +268,9 @@ openclaw gateway status --deep # يفحص أيضًا الخدمات على م
- [/gateway/configuration](/ar/gateway/configuration)
- [/gateway/doctor](/ar/gateway/doctor)
## تحذيرات فحص Gateway
## تحذيرات فحص البوابة
استخدم هذا القسم عندما يتمكن `openclaw gateway probe` من الوصول إلى شيء ما، لكنه لا يزال يطبع كتلة تحذير.
استخدم هذا عندما يصل `openclaw gateway probe` إلى شيء ما، لكنه لا يزال يطبع كتلة تحذير.
```bash
openclaw gateway probe
@ -224,15 +280,15 @@ openclaw gateway probe --ssh user@gateway-host
ابحث عن:
- `warnings[].code` و`primaryTargetId` في خرج JSON.
- ما إذا كان التحذير يتعلق ببديل SSH، أو تعدد الـ gateways، أو النطاقات المفقودة، أو مراجع المصادقة غير المحلولة.
- `warnings[].code` و `primaryTargetId` في مخرجات JSON.
- ما إذا كان التحذير متعلقًا بالرجوع إلى SSH، أو بوجود عدة بوابات، أو بنطاقات مفقودة، أو بمراجع مصادقة غير محلولة.
العلامات الشائعة:
الأنماط الشائعة:
- `SSH tunnel failed to start; falling back to direct probes.` → فشل إعداد SSH، لكن الأمر ما زال يجرّب الأهداف المباشرة المضبوطة/loopback.
- `multiple reachable gateways detected` → استجاب أكثر من هدف واحد. عادةً ما يعني هذا إعدادًا مقصودًا متعدد الـ gateways أو مستمعين قديمين/مكررَين.
- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → نجح الاتصال، لكن RPC التفصيلي محدود بالنطاقات؛ قم بإقران هوية الجهاز أو استخدم بيانات اعتماد تحتوي على `operator.read`.
- نص تحذير SecretRef غير المحلول لـ `gateway.auth.*` / `gateway.remote.*` → كانت مواد المصادقة غير متاحة في مسار هذا الأمر للهدف الفاشل.
- `SSH tunnel failed to start; falling back to direct probes.` ← فشل إعداد SSH، لكن الأمر ما زال يحاول الأهداف المباشرة المضبوطة/loopback.
- `multiple reachable gateways detected` ← استجابت أكثر من جهة هدف. عادة يعني ذلك إعدادًا مقصودًا لعدة بوابات أو مستمعين قدامى/مكررين.
- `Probe diagnostics are limited by gateway scopes (missing operator.read)` ← نجح الاتصال، لكن تفاصيل RPC محدودة بالنطاقات؛ قم بإقران هوية الجهاز أو استخدم بيانات اعتماد تحتوي على `operator.read`.
- نص تحذير SecretRef غير المحلول لـ `gateway.auth.*` / `gateway.remote.*` ← لم تكن مواد المصادقة متاحة في مسار هذا الأمر للهدف الفاشل.
ذو صلة:
@ -242,7 +298,7 @@ openclaw gateway probe --ssh user@gateway-host
## القناة متصلة لكن الرسائل لا تتدفق
إذا كانت حالة القناة متصلة لكن تدفق الرسائل متوقف، فركّز على السياسة، والأذونات، وقواعد التسليم الخاصة بالقناة.
إذا كانت حالة القناة متصلة لكن تدفق الرسائل متوقف، فركّز على السياسة والأذونات وقواعد التسليم الخاصة بالقناة.
```bash
openclaw channels status --probe
@ -256,13 +312,13 @@ openclaw config get channels
- سياسة الرسائل المباشرة (`pairing`، `allowlist`، `open`، `disabled`).
- قائمة السماح للمجموعة ومتطلبات الإشارة.
- أذونات/نطاقات API الخاصة بالقناة المفقودة.
- أذونات/نطاقات API المفقودة الخاصة بالقناة.
العلامات الشائعة:
الأنماط الشائعة:
- `mention required` → تم تجاهل الرسالة بسبب سياسة الإشارة في المجموعة.
- آثار `pairing` / الموافقة المعلّقة → المرسل غير معتمد.
- `missing_scope`، `not_in_channel`، `Forbidden`، `401/403` → مشكلة في مصادقة/أذونات القناة.
- `mention required` ← تم تجاهل الرسالة بسبب سياسة الإشارة في المجموعة.
- `pairing` / آثار موافقة معلقة ← المرسل غير معتمد.
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` ← مشكلة في مصادقة/أذونات القناة.
ذو صلة:
@ -271,9 +327,9 @@ openclaw config get channels
- [/channels/telegram](/ar/channels/telegram)
- [/channels/discord](/ar/channels/discord)
## تسليم cron وheartbeat
## تسليم cron والنبضات
إذا لم يتم تشغيل cron أو heartbeat أو لم يتم التسليم، فتحقق أولًا من حالة المجدول، ثم من هدف التسليم.
إذا لم يتم تشغيل cron أو النبضات أو لم يتم تسليمهما، فتحقق أولًا من حالة المجدول، ثم من جهة التسليم المستهدفة.
```bash
openclaw cron status
@ -285,19 +341,19 @@ openclaw logs --follow
ابحث عن:
- أن cron مفعّل ووقت الاستيقاظ التالي موجود.
- أن cron مفعّل وأن وقت التنبيه التالي موجود.
- حالة سجل تشغيل المهمة (`ok`، `skipped`، `error`).
- أسباب تخطي heartbeat (`quiet-hours`، `requests-in-flight`، `alerts-disabled`، `empty-heartbeat-file`، `no-tasks-due`).
- أسباب تخطي النبضات (`quiet-hours`، `requests-in-flight`، `alerts-disabled`، `empty-heartbeat-file`، `no-tasks-due`).
العلامات الشائعة:
الأنماط الشائعة:
- `cron: scheduler disabled; jobs will not run automatically` → تم تعطيل cron.
- `cron: timer tick failed` → فشل نبض المجدول؛ تحقق من أخطاء الملف/السجل/وقت التشغيل.
- `heartbeat skipped` مع `reason=quiet-hours` → خارج نافذة الساعات النشطة.
- `heartbeat skipped` مع `reason=empty-heartbeat-file` → الملف `HEARTBEAT.md` موجود لكنه يحتوي فقط على أسطر فارغة / عناوين markdown، لذلك يتخطى OpenClaw استدعاء النموذج.
- `heartbeat skipped` مع `reason=no-tasks-due` → يحتوي `HEARTBEAT.md` على كتلة `tasks:`، لكن لا توجد مهام مستحقة في هذه النبضة.
- `heartbeat: unknown accountId` → معرّف حساب غير صالح لهدف تسليم heartbeat.
- `heartbeat skipped` مع `reason=dm-blocked` → تم حل هدف heartbeat إلى وجهة على نمط الرسائل المباشرة بينما `agents.defaults.heartbeat.directPolicy` (أو التجاوز لكل وكيل) مضبوط على `block`.
- `cron: scheduler disabled; jobs will not run automatically` ← تم تعطيل cron.
- `cron: timer tick failed` ← فشلت نبضة المؤقت للمجدول؛ تحقق من أخطاء الملفات/السجلات/وقت التشغيل.
- `heartbeat skipped` مع `reason=quiet-hours` ← خارج نافذة الساعات النشطة.
- `heartbeat skipped` مع `reason=empty-heartbeat-file` ← يوجد `HEARTBEAT.md` لكنه يحتوي فقط على أسطر فارغة / عناوين markdown، لذلك يتجاوز OpenClaw استدعاء النموذج.
- `heartbeat skipped` مع `reason=no-tasks-due` ← يحتوي `HEARTBEAT.md` على كتلة `tasks:`، لكن لا توجد مهام مستحقة في هذه النبضة.
- `heartbeat: unknown accountId` ← معرّف حساب غير صالح لجهة تسليم النبضات المستهدفة.
- `heartbeat skipped` مع `reason=dm-blocked` ← تم حل هدف النبضات إلى وجهة بأسلوب الرسائل المباشرة بينما `agents.defaults.heartbeat.directPolicy` (أو تجاوز كل وكيل) مضبوط على `block`.
ذو صلة:
@ -307,7 +363,7 @@ openclaw logs --follow
## فشل أداة العقدة المقترنة
إذا كانت العقدة مقترنة لكن الأدوات تفشل، فاعزل حالة الواجهة الأمامية، والأذونات، والموافقة.
إذا كانت العقدة مقترنة لكن الأدوات تفشل، فاعزل حالة المقدمة والأذونات والموافقات.
```bash
openclaw nodes status
@ -319,16 +375,16 @@ openclaw status
ابحث عن:
- أن العقدة متصلة وبها الإمكانات المتوقعة.
- منح أذونات نظام التشغيل للكاميرا/الميكروفون/الموقع/الشاشة.
- الموافقات التنفيذية وحالة قائمة السماح.
- أن العقدة متصلة بالإنترنت وبالقدرات المتوقعة.
- منح أذونات نظام التشغيل للكاميرا/المايكروفون/الموقع/الشاشة.
- حالة موافقات exec وقائمة السماح.
العلامات الشائعة:
الأنماط الشائعة:
- `NODE_BACKGROUND_UNAVAILABLE` → يجب أن يكون تطبيق العقدة في الواجهة الأمامية.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → أذونات نظام التشغيل مفقودة.
- `SYSTEM_RUN_DENIED: approval required` → موافقة التنفيذ معلّقة.
- `SYSTEM_RUN_DENIED: allowlist miss` → تم حظر الأمر بواسطة قائمة السماح.
- `NODE_BACKGROUND_UNAVAILABLE` ← يجب أن يكون تطبيق العقدة في المقدمة.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` ← إذن نظام تشغيل مفقود.
- `SYSTEM_RUN_DENIED: approval required` ← موافقة exec معلقة.
- `SYSTEM_RUN_DENIED: allowlist miss` ← تم حظر الأمر بواسطة قائمة السماح.
ذو صلة:
@ -338,7 +394,7 @@ openclaw status
## فشل أداة المتصفح
استخدم هذا القسم عندما تفشل إجراءات أداة المتصفح رغم أن gateway نفسه بحالة سليمة.
استخدم هذا عندما تفشل إجراءات أداة المتصفح رغم أن البوابة نفسها سليمة.
```bash
openclaw browser status
@ -351,38 +407,38 @@ openclaw doctor
ابحث عن:
- ما إذا كان `plugins.allow` مضبوطًا ويتضمن `browser`.
- صحة مسار الملف التنفيذي للمتصفح.
- مسار صالح لملف المتصفح التنفيذي.
- إمكانية الوصول إلى ملف تعريف CDP.
- توفر Chrome المحلي لملفات التعريف `existing-session` / `user`.
- توفر Chrome محليًا لملفات تعريف `existing-session` / `user`.
العلامات الشائعة:
الأنماط الشائعة:
- `unknown command "browser"` أو `unknown command 'browser'` → تم استبعاد browser plugin المضمّن بواسطة `plugins.allow`.
- غياب أداة المتصفح / عدم توفرها بينما `browser.enabled=true` → يستبعد `plugins.allow` قيمة `browser`، لذلك لم يتم تحميل الـ plugin.
- `Failed to start Chrome CDP on port` → فشلت عملية المتصفح في الإطلاق.
- `browser.executablePath not found` → المسار المضبوط غير صالح.
- `browser.cdpUrl must be http(s) or ws(s)` → يستخدم عنوان CDP المضبوط مخططًا غير مدعوم مثل `file:` أو `ftp:`.
- `browser.cdpUrl has invalid port` → يحتوي عنوان CDP المضبوط على منفذ سيئ أو خارج النطاق.
- `No Chrome tabs found for profile="user"` → لا توجد علامات تبويب Chrome محلية مفتوحة لملف تعريف الإرفاق Chrome MCP.
- `Remote CDP for profile "<name>" is not reachable` → تعذّر الوصول إلى نقطة نهاية CDP البعيدة المضبوطة من مضيف gateway.
- `Browser attachOnly is enabled ... not reachable` أو `Browser attachOnly is enabled and CDP websocket ... is not reachable` → لا يوجد هدف قابل للوصول لملف تعريف attach-only، أو أن نقطة نهاية HTTP استجابت لكن تعذّر مع ذلك فتح CDP WebSocket.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → لا يحتوي تثبيت gateway الحالي على حزمة Playwright الكاملة؛ لا تزال لقطات ARIA ولقطات الشاشة الأساسية للصفحات تعمل، لكن التنقل ولقطات AI ولقطات العناصر باستخدام محددات CSS وتصدير PDF تظل غير متاحة.
- `fullPage is not supported for element screenshots` → خلط طلب لقطة الشاشة `--full-page` مع `--ref` أو `--element`.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → يجب أن تستخدم استدعاءات لقطات الشاشة الخاصة بـ Chrome MCP / `existing-session` التقاط الصفحة أو `--ref` من اللقطة، وليس CSS `--element`.
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → تحتاج خطافات رفع الملفات في Chrome MCP إلى مراجع لقطات، لا إلى محددات CSS.
- `existing-session file uploads currently support one file at a time.` → أرسل عملية رفع واحدة لكل استدعاء في ملفات تعريف Chrome MCP.
- `existing-session dialog handling does not support timeoutMs.` → لا تدعم خطافات الحوار في ملفات تعريف Chrome MCP تجاوزات timeout.
- `response body is not supported for existing-session profiles yet.` → لا يزال `responsebody` يتطلب متصفحًا مُدارًا أو ملف تعريف CDP خامًا.
- تجاوزات viewport / dark-mode / locale / offline القديمة في ملفات تعريف attach-only أو CDP البعيدة → شغّل `openclaw browser stop --browser-profile <name>` لإغلاق جلسة التحكم النشطة وتحرير حالة المحاكاة Playwright/CDP بدون إعادة تشغيل gateway بالكامل.
- `unknown command "browser"` أو `unknown command 'browser'` ← تم استبعاد إضافة المتصفح المضمّنة بواسطة `plugins.allow`.
- أداة المتصفح مفقودة / غير متاحة بينما `browser.enabled=true` ← يستبعد `plugins.allow` المكوّن `browser`، لذا لم تُحمّل الإضافة أصلًا.
- `Failed to start Chrome CDP on port` ← فشلت عملية المتصفح في التشغيل.
- `browser.executablePath not found` ← المسار المضبوط غير صالح.
- `browser.cdpUrl must be http(s) or ws(s)` ← يستخدم عنوان CDP URL المضبوط مخططًا غير مدعوم مثل `file:` أو `ftp:`.
- `browser.cdpUrl has invalid port` ← يحتوي CDP URL المضبوط على منفذ سيئ أو خارج النطاق.
- `No Chrome tabs found for profile="user"` ← لا توجد علامات تبويب Chrome محلية مفتوحة لملف تعريف إرفاق Chrome MCP.
- `Remote CDP for profile "<name>" is not reachable` ← نقطة نهاية CDP البعيدة المضبوطة غير قابلة للوصول من مضيف البوابة.
- `Browser attachOnly is enabled ... not reachable` أو `Browser attachOnly is enabled and CDP websocket ... is not reachable` ← لا يوجد هدف يمكن الوصول إليه لملف التعريف attach-only، أو أن نقطة نهاية HTTP استجابت لكن لم يمكن بعد ذلك فتح CDP WebSocket.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` ← يفتقر تثبيت البوابة الحالي إلى حزمة Playwright الكاملة؛ ولا تزال لقطات ARIA ولقطات الشاشة الأساسية للصفحات تعمل، لكن يظل التنقل ولقطات AI ولقطات عناصر محددات CSS وتصدير PDF غير متاحة.
- `fullPage is not supported for element screenshots` ← طلب لقطة الشاشة خلط `--full-page` مع `--ref` أو `--element`.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` ← يجب أن تستخدم استدعاءات لقطة الشاشة لـ Chrome MCP / `existing-session` التقاط الصفحة أو `--ref` من اللقطة، وليس CSS `--element`.
- `existing-session file uploads do not support element selectors; use ref/inputRef.` ← تحتاج خطافات رفع الملفات في Chrome MCP إلى مراجع لقطات، وليس محددات CSS.
- `existing-session file uploads currently support one file at a time.` ← أرسل ملف رفع واحدًا لكل استدعاء في ملفات تعريف Chrome MCP.
- `existing-session dialog handling does not support timeoutMs.` ← لا تدعم خطافات مربعات الحوار في ملفات تعريف Chrome MCP تجاوزات المهلة.
- `response body is not supported for existing-session profiles yet.` ← ما يزال `responsebody` يتطلب متصفحًا مُدارًا أو ملف تعريف CDP خامًا.
- تجاوزات قديمة لمنفذ العرض / الوضع الداكن / اللغة المحلية / عدم الاتصال في ملفات تعريف attach-only أو CDP البعيدة ← شغّل `openclaw browser stop --browser-profile <name>` لإغلاق جلسة التحكم النشطة وتحرير حالة محاكاة Playwright/CDP من دون إعادة تشغيل البوابة كاملة.
ذو صلة:
- [/tools/browser-linux-troubleshooting](/ar/tools/browser-linux-troubleshooting)
- [/tools/browser](/ar/tools/browser)
## إذا قمت بالترقية وتوقف شيء ما فجأة
## إذا قمت بالترقية وتعطل شيء فجأة
معظم الأعطال بعد الترقية تكون بسبب انجراف في الإعداد أو فرض إعدادات افتراضية أكثر صرامة.
معظم الأعطال بعد الترقية تكون بسبب انجراف الإعدادات أو فرض إعدادات افتراضية أكثر صرامة الآن.
### 1) تغيّر سلوك المصادقة وتجاوز عنوان URL
@ -395,15 +451,15 @@ openclaw config get gateway.auth.mode
ما الذي يجب التحقق منه:
- إذا كانت `gateway.mode=remote`، فقد تكون استدعاءات CLI تستهدف جهة بعيدة بينما خدمتك المحلية سليمة.
- لا تعود الاستدعاءات الصريحة `--url` إلى بيانات الاعتماد المخزنة.
- إذا كان `gateway.mode=remote`، فقد تستهدف استدعاءات CLI البيئة البعيدة بينما تكون خدمتك المحلية سليمة.
- الاستدعاءات الصريحة `--url` لا تعود إلى بيانات الاعتماد المخزنة.
العلامات الشائعة:
الأنماط الشائعة:
- `gateway connect failed:` → هدف URL غير صحيح.
- `unauthorized` → يمكن الوصول إلى نقطة النهاية لكن المصادقة غير صحيحة.
- `gateway connect failed:` ← هدف URL غير صحيح.
- `unauthorized` ← يمكن الوصول إلى نقطة النهاية لكن المصادقة خاطئة.
### 2) أصبحت قيود الربط والمصادقة أكثر صرامة
### 2) أصبحت ضوابط الربط والمصادقة أكثر صرامة
```bash
openclaw config get gateway.bind
@ -415,13 +471,13 @@ openclaw logs --follow
ما الذي يجب التحقق منه:
- تحتاج عمليات الربط non-loopback (`lan`، `tailnet`، `custom`) إلى مسار مصادقة صالح للـ gateway: مصادقة برمز/كلمة مرور مشتركة، أو نشر `trusted-proxy` مضبوط بشكل صحيح على non-loopback.
- لا تستبدل المفاتيح القديمة مثل `gateway.token` القيمة `gateway.auth.token`.
- تحتاج عمليات الربط غير loopback (`lan`، `tailnet`، `custom`) إلى مسار مصادقة صالح للبوابة: مصادقة برمز/كلمة مرور مشتركة، أو نشر `trusted-proxy` غير loopback مضبوط بشكل صحيح.
- المفاتيح القديمة مثل `gateway.token` لا تحل محل `gateway.auth.token`.
العلامات الشائعة:
الأنماط الشائعة:
- `refusing to bind gateway ... without auth` → ربط non-loopback بدون مسار مصادقة صالح للـ gateway.
- `RPC probe: failed` بينما وقت التشغيل يعمل → الـ gateway حي لكن يتعذر الوصول إليه باستخدام المصادقة/عنوان URL الحاليين.
- `refusing to bind gateway ... without auth` ← ربط غير loopback من دون مسار مصادقة صالح للبوابة.
- `RPC probe: failed` بينما وقت التشغيل يعمل ← البوابة حيّة لكن يتعذر الوصول إليها باستخدام إعدادات المصادقة/URL الحالية.
### 3) تغيّرت حالة الاقتران وهوية الجهاز
@ -434,15 +490,15 @@ openclaw doctor
ما الذي يجب التحقق منه:
- طلبات الموافقة المعلقة للأجهزة الخاصة بـ dashboard/nodes.
- طلبات موافقة اقتران الرسائل المباشرة المعلقة بعد تغييرات السياسة أو الهوية.
- موافقات الأجهزة المعلقة لـ dashboard/nodes.
- موافقات اقتران الرسائل المباشرة المعلقة بعد تغييرات السياسة أو الهوية.
العلامات الشائعة:
الأنماط الشائعة:
- `device identity required` → لم يتم استيفاء مصادقة الجهاز.
- `pairing required` → يجب الموافقة على المرسل/الجهاز.
- `device identity required` ← لم تُستوفَ مصادقة الجهاز.
- `pairing required` ← يجب الموافقة على المرسل/الجهاز.
إذا ظل إعداد الخدمة ووقت التشغيل غير متطابقين بعد الفحوصات، فأعد تثبيت بيانات تعريف الخدمة من ملف التعريف/دليل الحالة نفسه:
إذا استمر عدم اتفاق إعدادات الخدمة ووقت التشغيل بعد عمليات التحقق، فأعد تثبيت بيانات تعريف الخدمة من الدليل نفسه للملف الشخصي/الحالة:
```bash
openclaw gateway install --force

1645
docs/ar/help/faq.md
View File

File diff suppressed because it is too large Load Diff

58
docs/ar/help/scripts.md
View File

@ -1,34 +1,60 @@
---
read_when:
- تشغيل البرامج النصية من المستودع
- إضافة أو تغيير البرامج النصية ضمن ‎./scripts
summary: 'برامج المستودع النصية: الغرض، والنطاق، وملاحظات السلامة'
title: البرامج النصية
- تشغيل السكريبتات من المستودع
- إضافة أو تغيير السكريبتات ضمن ./scripts
summary: 'سكريبتات المستودع: الغرض والنطاق وملاحظات السلامة'
title: السكريبتات
x-i18n:
generated_at: "2026-04-05T12:45:19Z"
generated_at: "2026-04-08T02:15:44Z"
model: gpt-5.4
provider: openai
source_hash: de53d64d91c564931bdd4e8b9f4a8e88646332a07cc2a6bf1d517b89debb29cd
source_hash: 3ecf1e9327929948fb75f80e306963af49b353c0aa8d3b6fa532ca964ff8b975
source_path: help/scripts.md
workflow: 15
---
# البرامج النصية
# السكريبتات
يحتوي الدليل `scripts/` على برامج نصية مساعدة لسير العمل المحلي ومهام التشغيل.
استخدمها عندما تكون المهمة مرتبطة بوضوح ببرنامج نصي؛ وخلاف ذلك، فضّل CLI.
يحتوي الدليل `scripts/` على سكريبتات مساعدة لسير العمل المحلي ومهام التشغيل.
استخدمها عندما تكون المهمة مرتبطة بوضوح بسكريبت؛ وإلا ففضّل استخدام CLI.
## الاصطلاحات
- تكون البرامج النصية **اختيارية** ما لم يُشر إليها في الوثائق أو قوائم التحقق الخاصة بالإصدار.
- السكريبتات **اختيارية** ما لم تتم الإشارة إليها في الوثائق أو قوائم التحقق الخاصة بالإصدار.
- فضّل واجهات CLI عندما تكون موجودة (مثال: تستخدم مراقبة المصادقة `openclaw models status --check`).
- افترض أن البرامج النصية خاصة بالمضيف؛ واقرأها قبل تشغيلها على جهاز جديد.
- افترض أن السكريبتات خاصة بالمضيف؛ واقرأها قبل تشغيلها على جهاز جديد.
## البرامج النصية لمراقبة المصادقة
## سكريبتات مراقبة المصادقة
تتم تغطية مراقبة المصادقة في [المصادقة](/gateway/authentication). أما البرامج النصية ضمن `scripts/` فهي إضافات اختيارية لسير عمل الهاتف باستخدام systemd/Termux.
تتم تغطية مراقبة المصادقة في [المصادقة](/ar/gateway/authentication). أما السكريبتات الموجودة ضمن `scripts/` فهي إضافات اختيارية لسير عمل systemd/Termux على الهاتف.
## عند إضافة برامج نصية
## مساعد قراءة GitHub
- أبقِ البرامج النصية مركزة وموثقة.
- أضف إدخالًا قصيرًا في الوثيقة ذات الصلة (أو أنشئ وثيقة إذا كانت مفقودة).
استخدم `scripts/gh-read` عندما تريد أن يستخدم `gh` رمز تثبيت GitHub App المميز لاستدعاءات القراءة ذات النطاق الخاص بالمستودع، مع إبقاء `gh` العادي على تسجيلك الشخصي لعمليات الكتابة.
متغيرات البيئة المطلوبة:
- `OPENCLAW_GH_READ_APP_ID`
- `OPENCLAW_GH_READ_PRIVATE_KEY_FILE`
متغيرات البيئة الاختيارية:
- `OPENCLAW_GH_READ_INSTALLATION_ID` عندما تريد تخطي البحث عن التثبيت المعتمد على المستودع
- `OPENCLAW_GH_READ_PERMISSIONS` كتجاوز مفصول بفواصل لمجموعة أذونات القراءة الفرعية المطلوب طلبها
ترتيب حل المستودع:
- `gh ... -R owner/repo`
- `GH_REPO`
- `git remote origin`
أمثلة:
- `scripts/gh-read pr view 123`
- `scripts/gh-read run list -R openclaw/openclaw`
- `scripts/gh-read api repos/openclaw/openclaw/pulls/123`
## عند إضافة سكريبتات
- حافظ على تركيز السكريبتات وتوثيقها.
- أضف إدخالًا قصيرًا في الوثيقة ذات الصلة (أو أنشئ واحدة إذا كانت مفقودة).

748
docs/ar/help/testing.md
View File

File diff suppressed because it is too large Load Diff

319
docs/ar/help/troubleshooting.md
View File

@ -1,25 +1,25 @@
---
read_when:
- OpenClaw لا يعمل وأنت تحتاج إلى أسرع مسار للإصلاح
- أنت تريد تدفق فرز أولي قبل الغوص في أدلة التشغيل التفصيلية
summary: مركز استكشاف الأخطاء وإصلاحها وفق الأعراض أولًا لـ OpenClaw
- لا يعمل OpenClaw وتحتاج إلى أسرع طريق إلى حل
- تريد مسار فرز أولي قبل التعمق في أدلة التشغيل التفصيلية
summary: مركز استكشاف الأخطاء وإصلاحها في OpenClaw وفقًا للأعراض أولًا
title: استكشاف الأخطاء وإصلاحها العام
x-i18n:
generated_at: "2026-04-05T12:46:17Z"
generated_at: "2026-04-08T02:16:50Z"
model: gpt-5.4
provider: openai
source_hash: 23ae9638af5edf5a5e0584ccb15ba404223ac3b16c2d62eb93b2c9dac171c252
source_hash: 8abda90ef80234c2f91a51c5e1f2c004d4a4da12a5d5631b5927762550c6d5e3
source_path: help/troubleshooting.md
workflow: 15
---
# استكشاف الأخطاء وإصلاحها
إذا لم يكن لديك سوى دقيقتين، فاستخدم هذه الصفحة كبوابة فرز أولية.
إذا كان لديك دقيقتان فقط، فاستخدم هذه الصفحة كنقطة دخول سريعة للفرز الأولي.
## أول 60 ثانية
شغّل هذا التسلسل بالترتيب نفسه:
شغّل هذا التسلسل بالترتيب تمامًا:
```bash
openclaw status
@ -33,25 +33,41 @@ openclaw logs --follow
المخرجات الجيدة في سطر واحد:
- `openclaw status` ← يعرض القنوات المهيأة ولا توجد أخطاء auth واضحة.
- `openclaw status --all` ← التقرير الكامل موجود وقابل للمشاركة.
- `openclaw gateway probe` ← الهدف المتوقع للبوابة قابل للوصول (`Reachable: yes`). إن `RPC: limited - missing scope: operator.read` يعني تشخيصات متدهورة، وليس فشل اتصال.
- `openclaw gateway status` ← `Runtime: running` و`RPC probe: ok`.
- `openclaw doctor` ← لا توجد أخطاء إعداد/خدمة مانعة.
- `openclaw channels status --probe` ← عندما تكون البوابة قابلة للوصول، يعرض حالة النقل الحية لكل حساب بالإضافة إلى نتائج الفحص/التدقيق مثل `works` أو `audit ok`؛ وإذا كانت
البوابة غير قابلة للوصول، يرجع الأمر إلى ملخصات تعتمد على الإعدادات فقط.
- `openclaw logs --follow` ← نشاط مستقر، ولا توجد أخطاء قاتلة متكررة.
- `openclaw status` → يعرض القنوات المهيأة ولا توجد أخطاء مصادقة واضحة.
- `openclaw status --all` → التقرير الكامل موجود وقابل للمشاركة.
- `openclaw gateway probe` → هدف البوابة المتوقع يمكن الوصول إليه (`Reachable: yes`). يشير `RPC: limited - missing scope: operator.read` إلى تشخيصات متدهورة، وليس إلى فشل في الاتصال.
- `openclaw gateway status` → `Runtime: running` و`RPC probe: ok`.
- `openclaw doctor` → لا توجد أخطاء حاجبة في الإعدادات/الخدمة.
- `openclaw channels status --probe` → إذا كانت البوابة قابلة للوصول، فسيُرجع حالة النقل الحية لكل حساب
بالإضافة إلى نتائج الفحص/التدقيق مثل `works` أو `audit ok`؛ وإذا كانت
البوابة غير قابلة للوصول، يعود الأمر إلى ملخصات تعتمد على الإعدادات فقط.
- `openclaw logs --follow` → نشاط مستقر، ولا توجد أخطاء قاتلة متكررة.
## ‏429 من Anthropic للسياق الطويل
## Anthropic long context 429
إذا رأيت:
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`,
فانتقل إلى [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`
فانتقل إلى [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/ar/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
## فشل تثبيت plugin بسبب غياب openclaw extensions
## تعمل واجهة OpenAI-compatible الخلفية المحلية مباشرة لكنها تفشل في OpenClaw
إذا كانت واجهة `/v1` الخلفية المحلية أو المستضافة ذاتيًا تستجيب مباشرةً
لاختبارات `/v1/chat/completions` الصغيرة لكنها تفشل مع `openclaw infer model run` أو في
أدوار الوكيل العادية:
1. إذا كان الخطأ يذكر أن `messages[].content` يتوقع سلسلة نصية، فاضبط
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
2. إذا استمرت الواجهة الخلفية في الفشل فقط في أدوار وكيل OpenClaw، فاضبط
`models.providers.<provider>.models[].compat.supportsTools: false` ثم أعد المحاولة.
3. إذا ظلت الاستدعاءات المباشرة الصغيرة تعمل لكن موجّهات OpenClaw الأكبر تتسبب في تعطل
الواجهة الخلفية، فاعتبر المشكلة المتبقية قيدًا من النموذج/الخادم upstream
وتابع في الدليل التفصيلي:
[/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/ar/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
## فشل تثبيت plugin مع openclaw extensions مفقودة
إذا فشل التثبيت مع `package.json missing openclaw.extensions`، فإن حزمة plugin
تستخدم شكلًا قديمًا لم يعد OpenClaw يقبله.
تستخدم بنية قديمة لم يعد OpenClaw يقبلها.
الحل في حزمة plugin:
@ -71,28 +87,28 @@ openclaw logs --follow
}
```
المرجع: [بنية Plugins](/plugins/architecture)
مرجع: [معمارية plugin](/ar/plugins/architecture)
## شجرة القرار
```mermaid
flowchart TD
A[OpenClaw is not working] --> B{What breaks first}
B --> C[No replies]
B --> D[Dashboard or Control UI will not connect]
B --> E[Gateway will not start or service not running]
B --> F[Channel connects but messages do not flow]
B --> G[Cron or heartbeat did not fire or did not deliver]
B --> H[Node is paired but camera canvas screen exec fails]
B --> I[Browser tool fails]
A[OpenClaw لا يعمل] --> B{ما أول شيء يتعطل}
B --> C[لا توجد ردود]
B --> D[لوحة المعلومات أو Control UI لا تتصل]
B --> E[البوابة لا تبدأ أو الخدمة لا تعمل]
B --> F[القناة تتصل لكن الرسائل لا تتدفق]
B --> G[Cron أو Heartbeat لم يعمل أو لم يسلّم]
B --> H[تم اقتران العقدة لكن أداة camera canvas screen exec تفشل]
B --> I[أداة Browser تفشل]
C --> C1[/No replies section/]
D --> D1[/Control UI section/]
E --> E1[/Gateway section/]
F --> F1[/Channel flow section/]
G --> G1[/Automation section/]
H --> H1[/Node tools section/]
I --> I1[/Browser section/]
C --> C1[/قسم لا توجد ردود/]
D --> D1[/قسم Control UI/]
E --> E1[/قسم البوابة/]
F --> F1[/قسم تدفق القناة/]
G --> G1[/قسم الأتمتة/]
H --> H1[/قسم أدوات العقدة/]
I --> I1[/قسم Browser/]
```
<AccordionGroup>
@ -105,28 +121,28 @@ flowchart TD
openclaw logs --follow
```
تبدو المخرجات الجيدة كالتالي:
تبدو المخرجات الجيدة كما يلي:
- `Runtime: running`
- `RPC probe: ok`
- تعرض قناتك اتصال النقل، وحيثما كان ذلك مدعومًا، `works` أو `audit ok` في `channels status --probe`
- يظهر المرسل على أنه معتمد (أو أن سياسة الرسائل الخاصة open/allowlist)
- يظهر المرسِل على أنه معتمد (أو أن سياسة الرسائل المباشرة مفتوحة/قائمة السماح)
التواقيع الشائعة في السجلات:
توقيعات السجلات الشائعة:
- `drop guild message (mention required` ← تقييد الإشارة منع الرسالة في Discord.
- `pairing request` ← المرسل غير معتمد وينتظر الموافقة على الاقتران عبر الرسائل الخاصة.
- `blocked` / `allowlist` في سجلات القناة ← تتم تصفية المرسل أو الغرفة أو المجموعة.
- `drop guild message (mention required` → منعت بوابة الإشارة معالجة الرسالة في Discord.
- `pairing request` → المرسل غير معتمد وينتظر الموافقة على الاقتران عبر الرسائل المباشرة.
- `blocked` / `allowlist` في سجلات القناة → تمت تصفية المرسل أو الغرفة أو المجموعة.
الصفحات التفصيلية:
- [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies)
- [/channels/troubleshooting](/channels/troubleshooting)
- [/channels/pairing](/channels/pairing)
- [/gateway/troubleshooting#no-replies](/ar/gateway/troubleshooting#no-replies)
- [/channels/troubleshooting](/ar/channels/troubleshooting)
- [/channels/pairing](/ar/channels/pairing)
</Accordion>
<Accordion title="‏Dashboard أو Control UI لا يتصلان">
<Accordion title="لوحة المعلومات أو Control UI لا تتصل">
```bash
openclaw status
openclaw gateway status
@ -135,38 +151,37 @@ flowchart TD
openclaw channels status --probe
```
تبدو المخرجات الجيدة كالتالي:
تبدو المخرجات الجيدة كما يلي:
- يظهر `Dashboard: http://...` في `openclaw gateway status`
- `RPC probe: ok`
- لا توجد حلقة auth في السجلات
- لا توجد حلقة مصادقة في السجلات
التواقيع الشائعة في السجلات:
توقيعات السجلات الشائعة:
- `device identity required` ← لا يمكن لسياق HTTP/غير الآمن إكمال مصادقة الجهاز.
- `origin not allowed` ← قيمة `Origin` في المتصفح غير مسموح بها لهدف
البوابة الخاص بـ Control UI.
- `AUTH_TOKEN_MISMATCH` مع تلميحات إعادة المحاولة (`canRetryWithDeviceToken=true`) ← قد تحدث إعادة محاولة واحدة تلقائيًا باستخدام device-token موثوق.
- تعيد تلك المحاولة باستخدام الرمز المخزن مؤقتًا استخدام مجموعة النطاقات المخزنة مع
رمز الجهاز المقترن. بينما تحتفظ الاستدعاءات الصريحة باستخدام `deviceToken` / `scopes` الصريحة
بمجموعة النطاقات المطلوبة الخاصة بها.
- في مسار Control UI غير المتزامن عبر Tailscale Serve، يتم تسلسل المحاولات الفاشلة لنفس
`{scope, ip}` قبل أن يسجل المحدِّد الفشل، لذلك قد تُظهر محاولة سيئة ثانية متزامنة بالفعل
`retry later`.
- `device identity required` → لا يمكن لسياق HTTP/غير الآمن إكمال مصادقة الجهاز.
- `origin not allowed` → لا يُسمح بـ `Origin` الخاص بالمتصفح لهدف بوابة Control UI.
- `AUTH_TOKEN_MISMATCH` مع تلميحات إعادة المحاولة (`canRetryWithDeviceToken=true`) → قد تحدث إعادة محاولة واحدة موثوقة باستخدام رمز الجهاز تلقائيًا.
- تعيد إعادة المحاولة باستخدام الرمز المؤقت استخدام مجموعة النطاقات المخزنة مؤقتًا مع
رمز الجهاز المقترن. أما المستدعون الذين يستخدمون `deviceToken` صريحًا / `scopes` صريحة
فيحتفظون بمجموعة النطاقات المطلوبة الخاصة بهم.
- في مسار Control UI غير المتزامن عبر Tailscale Serve، تتم
موازاة المحاولات الفاشلة لنفس `{scope, ip}` قبل أن يسجّل المحدِّد الفشل، لذلك
قد تُظهر إعادة محاولة سيئة ثانية متزامنة بالفعل `retry later`.
- `too many failed authentication attempts (retry later)` من
أصل متصفح localhost ← يتم قفل حالات الفشل المتكررة من `Origin` نفسه مؤقتًا؛ بينما يستخدم أصل localhost آخر مجموعة مستقلة.
- `unauthorized` المتكرر بعد تلك المحاولة ← token/password خاطئ، أو عدم تطابق وضع auth، أو رمز جهاز مقترن قديم.
- `gateway connect failed:` ← واجهة المستخدم تستهدف URL/منفذًا خاطئًا أو بوابة غير قابلة للوصول.
مصدر متصفح localhost → يتم قفل الإخفاقات المتكررة من `Origin` نفسه مؤقتًا؛ بينما يستخدم أصل localhost آخر سلة منفصلة.
- `unauthorized` متكرر بعد إعادة المحاولة تلك → رمز/كلمة مرور خاطئة، أو عدم تطابق وضع المصادقة، أو رمز جهاز مقترن قديم.
- `gateway connect failed:` → تستهدف UI عنوان URL/منفذًا خاطئًا أو بوابة يتعذر الوصول إليها.
الصفحات التفصيلية:
- [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity)
- [/gateway/troubleshooting#dashboard-control-ui-connectivity](/ar/gateway/troubleshooting#dashboard-control-ui-connectivity)
- [/web/control-ui](/web/control-ui)
- [/gateway/authentication](/gateway/authentication)
- [/gateway/authentication](/ar/gateway/authentication)
</Accordion>
<Accordion title="‏Gateway لا تبدأ أو أن الخدمة مثبتة لكنها لا تعمل">
<Accordion title="البوابة لا تبدأ أو الخدمة مثبتة لكنها لا تعمل">
```bash
openclaw status
openclaw gateway status
@ -175,27 +190,27 @@ flowchart TD
openclaw channels status --probe
```
تبدو المخرجات الجيدة كالتالي:
تبدو المخرجات الجيدة كما يلي:
- `Service: ... (loaded)`
- `Runtime: running`
- `RPC probe: ok`
التواقيع الشائعة في السجلات:
توقيعات السجلات الشائعة:
- `Gateway start blocked: set gateway.mode=local` أو `existing config is missing gateway.mode` ← وضع البوابة هو remote، أو أن ملف الإعدادات يفتقد علامة الوضع المحلي ويجب إصلاحه.
- `refusing to bind gateway ... without auth` ← ربط غير loopback من دون مسار auth صالح للبوابة (token/password، أو trusted-proxy حيثما يكون مهيأً).
- `another gateway instance is already listening` أو `EADDRINUSE` ← المنفذ مستخدم بالفعل.
- `Gateway start blocked: set gateway.mode=local` أو `existing config is missing gateway.mode` → وضع البوابة هو remote، أو أن ملف الإعدادات يفتقد علامة الوضع المحلي ويجب إصلاحه.
- `refusing to bind gateway ... without auth` → ربط غير loopback بدون مسار مصادقة صالح للبوابة (رمز/كلمة مرور، أو trusted-proxy حيثما كان مهيأً).
- `another gateway instance is already listening` أو `EADDRINUSE` → المنفذ مستخدم بالفعل.
الصفحات التفصيلية:
- [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running)
- [/gateway/background-process](/gateway/background-process)
- [/gateway/configuration](/gateway/configuration)
- [/gateway/troubleshooting#gateway-service-not-running](/ar/gateway/troubleshooting#gateway-service-not-running)
- [/gateway/background-process](/ar/gateway/background-process)
- [/gateway/configuration](/ar/gateway/configuration)
</Accordion>
<Accordion title="القناة متصلة لكن الرسائل لا تتدفق">
<Accordion title="القناة تتصل لكن الرسائل لا تتدفق">
```bash
openclaw status
openclaw gateway status
@ -204,26 +219,26 @@ flowchart TD
openclaw channels status --probe
```
تبدو المخرجات الجيدة كالتالي:
تبدو المخرجات الجيدة كما يلي:
- نقل القناة متصل.
- اجتياز فحوصات الاقتران/قائمة السماح.
- يتم اكتشاف الإشارات عند الحاجة.
- تمر فحوصات الاقتران/قائمة السماح.
- يتم اكتشاف الإشارات حيثما تكون مطلوبة.
التواقيع الشائعة في السجلات:
توقيعات السجلات الشائعة:
- `mention required` ← تقييد الإشارة في المجموعات منع المعالجة.
- `pairing` / `pending` ← مرسل الرسائل الخاصة لم تتم الموافقة عليه بعد.
- `not_in_channel` أو `missing_scope` أو `Forbidden` أو `401/403` ← مشكلة في أذونات القناة أو الرمز المميز.
- `mention required` → منعت بوابة الإشارة في المجموعة المعالجة.
- `pairing` / `pending` → مرسل الرسالة المباشرة غير معتمد بعد.
- `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → مشكلة في رمز أذونات القناة.
الصفحات التفصيلية:
- [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing)
- [/channels/troubleshooting](/channels/troubleshooting)
- [/gateway/troubleshooting#channel-connected-messages-not-flowing](/ar/gateway/troubleshooting#channel-connected-messages-not-flowing)
- [/channels/troubleshooting](/ar/channels/troubleshooting)
</Accordion>
<Accordion title="لم يعمل Cron أو heartbeat أو لم يتم التسليم">
<Accordion title="لم يعمل Cron أو Heartbeat أو لم يسلّم">
```bash
openclaw status
openclaw gateway status
@ -233,30 +248,30 @@ flowchart TD
openclaw logs --follow
```
تبدو المخرجات الجيدة كالتالي:
تبدو المخرجات الجيدة كما يلي:
- تعرض `cron.status` أنها مفعلة مع موعد الاستيقاظ التالي.
- تعرض `cron runs` إدخالات `ok` حديثة.
- Heartbeat مفعّل وليس خارج الساعات النشطة.
- يعرض `cron.status` أنه مفعّل مع وقت الاستيقاظ التالي.
- يعرض `cron runs` إدخالات `ok` حديثة.
- يكون Heartbeat مفعّلًا وليس خارج ساعات النشاط.
التواقيع الشائعة في السجلات:
توقيعات السجلات الشائعة:
- `cron: scheduler disabled; jobs will not run automatically` ← cron معطل.
- `heartbeat skipped` مع `reason=quiet-hours` ← خارج الساعات النشطة المهيأة.
- `heartbeat skipped` مع `reason=empty-heartbeat-file` ← الملف `HEARTBEAT.md` موجود لكنه يحتوي فقط على هيكل فارغ/عناوين فقط.
- `heartbeat skipped` مع `reason=no-tasks-due` ← وضع مهام `HEARTBEAT.md` نشط، لكن لم يحن موعد أي من فواصل المهام بعد.
- `heartbeat skipped` مع `reason=alerts-disabled` ← كل مظاهر عرض heartbeat معطلة (`showOk` و`showAlerts` و`useIndicator` كلها متوقفة).
- `requests-in-flight` ← المسار الرئيسي مشغول؛ وتم تأجيل استيقاظ heartbeat. - `unknown accountId` ← حساب هدف تسليم heartbeat غير موجود.
- `cron: scheduler disabled; jobs will not run automatically` → تم تعطيل cron.
- `heartbeat skipped` مع `reason=quiet-hours` → خارج ساعات النشاط المهيأة.
- `heartbeat skipped` مع `reason=empty-heartbeat-file` → الملف `HEARTBEAT.md` موجود لكنه يحتوي فقط على هيكل فارغ/عناوين فقط.
- `heartbeat skipped` مع `reason=no-tasks-due` → وضع المهام في `HEARTBEAT.md` نشط ولكن لم يحن موعد أي من فواصل المهام بعد.
- `heartbeat skipped` مع `reason=alerts-disabled` → تم تعطيل كل ظهور Heartbeat (`showOk` و`showAlerts` و`useIndicator` كلها معطلة).
- `requests-in-flight` → المسار الرئيسي مشغول؛ تم تأجيل تنبيه Heartbeat. - `unknown accountId` → حساب هدف تسليم Heartbeat غير موجود.
الصفحات التفصيلية:
- [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery)
- [/automation/cron-jobs#troubleshooting](/automation/cron-jobs#troubleshooting)
- [/gateway/heartbeat](/gateway/heartbeat)
- [/gateway/troubleshooting#cron-and-heartbeat-delivery](/ar/gateway/troubleshooting#cron-and-heartbeat-delivery)
- [/automation/cron-jobs#troubleshooting](/ar/automation/cron-jobs#troubleshooting)
- [/gateway/heartbeat](/ar/gateway/heartbeat)
</Accordion>
<Accordion title="العقدة مقترنة لكن الأداة تفشل في camera أو canvas أو screen أو exec">
<Accordion title="تم اقتران العقدة لكن الأداة تفشل في camera canvas screen exec">
```bash
openclaw status
openclaw gateway status
@ -265,28 +280,28 @@ flowchart TD
openclaw logs --follow
```
تبدو المخرجات الجيدة كالتالي:
تبدو المخرجات الجيدة كما يلي:
- العقدة مدرجة على أنها متصلة ومقترنة للدور `node`.
- الإمكانية موجودة للأمر الذي تستدعيه.
- حالة الأذونات ممنوحة لتلك الأداة.
- تظهر العقدة على أنها متصلة ومقترنة للدور `node`.
- توجد capability للأمر الذي تستدعيه.
- حالة الإذن ممنوحة للأداة.
التواقيع الشائعة في السجلات:
توقيعات السجلات الشائعة:
- `NODE_BACKGROUND_UNAVAILABLE` ← اجعل تطبيق العقدة في الواجهة الأمامية.
- `*_PERMISSION_REQUIRED` ← تم رفض إذن نظام التشغيل أو كان مفقودًا.
- `SYSTEM_RUN_DENIED: approval required` ← موافقة exec معلقة.
- `SYSTEM_RUN_DENIED: allowlist miss` ← الأمر غير موجود في قائمة سماح exec.
- `NODE_BACKGROUND_UNAVAILABLE` → اجلب تطبيق العقدة إلى الواجهة الأمامية.
- `*_PERMISSION_REQUIRED` → تم رفض/فقدان إذن نظام التشغيل.
- `SYSTEM_RUN_DENIED: approval required` → موافقة exec معلّقة.
- `SYSTEM_RUN_DENIED: allowlist miss` → الأمر غير موجود في قائمة السماح الخاصة بـ exec.
الصفحات التفصيلية:
- [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails)
- [/nodes/troubleshooting](/nodes/troubleshooting)
- [/tools/exec-approvals](/tools/exec-approvals)
- [/gateway/troubleshooting#node-paired-tool-fails](/ar/gateway/troubleshooting#node-paired-tool-fails)
- [/nodes/troubleshooting](/ar/nodes/troubleshooting)
- [/tools/exec-approvals](/ar/tools/exec-approvals)
</Accordion>
<Accordion title="أصبح Exec يطلب موافقة فجأة">
<Accordion title="أصبح Exec يطلب الموافقة فجأة">
```bash
openclaw config get tools.exec.host
openclaw config get tools.exec.security
@ -296,14 +311,14 @@ flowchart TD
ما الذي تغيّر:
- إذا لم يتم تعيين `tools.exec.host`، فالقيمة الافتراضية هي `auto`.
- تُحل `host=auto` إلى `sandbox` عندما يكون runtime المعزول نشطًا، وإلى `gateway` خلاف ذلك.
- `host=auto` خاصة بالتوجيه فقط؛ بينما يأتي سلوك "YOLO" من دون مطالبة من `security=full` مع `ask=off` على gateway/node.
- على `gateway` و`node`، تكون القيمة الافتراضية لـ `tools.exec.security` عند عدم التعيين هي `full`.
- تكون القيمة الافتراضية لـ `tools.exec.ask` عند عدم التعيين هي `off`.
- النتيجة: إذا كنت ترى موافقات، فقد تم تشديد بعض السياسات المحلية للمضيف أو الخاصة بكل جلسة على exec بعيدًا عن القيم الافتراضية الحالية.
- إذا لم يتم ضبط `tools.exec.host`، فالقيمة الافتراضية هي `auto`.
- يحل `host=auto` إلى `sandbox` عندما يكون runtime الخاص بـ sandbox نشطًا، وإلى `gateway` خلاف ذلك.
- `host=auto` خاص بالتوجيه فقط؛ أما سلوك "YOLO" بدون مطالبة فيأتي من `security=full` مع `ask=off` على gateway/node.
- في `gateway` و`node`، تكون القيمة الافتراضية لـ `tools.exec.security` عند عدم ضبطها هي `full`.
- تكون القيمة الافتراضية لـ `tools.exec.ask` عند عدم ضبطها هي `off`.
- النتيجة: إذا كنت ترى موافقات، فهذا يعني أن سياسة محلية على المضيف أو خاصة بالجلسة قد شددت exec بعيدًا عن القيم الافتراضية الحالية.
استعد سلوك عدم طلب الموافقة الافتراضي الحالي:
استعد سلوك الوضع الحالي الافتراضي بدون موافقة:
```bash
openclaw config set tools.exec.host gateway
@ -314,25 +329,25 @@ flowchart TD
بدائل أكثر أمانًا:
- اضبط فقط `tools.exec.host=gateway` إذا كنت تريد فقط توجيهًا مستقرًا للمضيف.
- استخدم `security=allowlist` مع `ask=on-miss` إذا كنت تريد exec على المضيف مع الإبقاء على المراجعة عند عدم التطابق مع قائمة السماح.
- فعّل وضع sandbox إذا كنت تريد أن تُحل `host=auto` مرة أخرى إلى `sandbox`.
- اضبط فقط `tools.exec.host=gateway` إذا كنت تريد مجرد توجيه مستقر على المضيف.
- استخدم `security=allowlist` مع `ask=on-miss` إذا كنت تريد exec على المضيف لكنك ما زلت تريد مراجعة عند الإخفاق في قائمة السماح.
- فعّل وضع sandbox إذا كنت تريد أن يعود `host=auto` إلى `sandbox`.
التواقيع الشائعة في السجلات:
توقيعات السجلات الشائعة:
- `Approval required.` ← الأمر ينتظر `/approve ...`.
- `SYSTEM_RUN_DENIED: approval required` ← موافقة exec على مضيف العقدة معلقة.
- `exec host=sandbox requires a sandbox runtime for this session` ← اختيار sandbox ضمني/صريح لكن وضع sandbox متوقف.
- `Approval required.` → ينتظر الأمر `/approve ...`.
- `SYSTEM_RUN_DENIED: approval required` → موافقة exec على مضيف العقدة معلّقة.
- `exec host=sandbox requires a sandbox runtime for this session` → تم اختيار sandbox ضمنيًا/صراحة لكن وضع sandbox معطل.
الصفحات التفصيلية:
- [/tools/exec](/tools/exec)
- [/tools/exec-approvals](/tools/exec-approvals)
- [/gateway/security#runtime-expectation-drift](/gateway/security#runtime-expectation-drift)
- [/tools/exec](/ar/tools/exec)
- [/tools/exec-approvals](/ar/tools/exec-approvals)
- [/gateway/security#runtime-expectation-drift](/ar/gateway/security#runtime-expectation-drift)
</Accordion>
<Accordion title="فشل أداة Browser">
<Accordion title="أداة Browser تفشل">
```bash
openclaw status
openclaw gateway status
@ -341,37 +356,37 @@ flowchart TD
openclaw doctor
```
تبدو المخرجات الجيدة كالتالي:
تبدو المخرجات الجيدة كما يلي:
- تعرض حالة Browser القيمة `running: true` ومتصفحًا/ملف تعريف مختارًا.
- يبدأ `openclaw`، أو يمكن للمستخدم رؤية علامات تبويب Chrome المحلية.
- تعرض حالة Browser `running: true` ومتصفحًا/ملف تعريف محددًا.
- يبدأ `openclaw`، أو يمكن لـ `user` رؤية علامات تبويب Chrome المحلية.
التواقيع الشائعة في السجلات:
توقيعات السجلات الشائعة:
- `unknown command "browser"` أو `unknown command 'browser'` ← تم تعيين `plugins.allow` ولا يتضمن `browser`.
- `Failed to start Chrome CDP on port` ← فشل تشغيل المتصفح المحلي.
- `browser.executablePath not found` ← مسار الثنائي المهيأ غير صحيح.
- `browser.cdpUrl must be http(s) or ws(s)` ← يستخدم عنوان CDP URL المهيأ مخططًا غير مدعوم.
- `browser.cdpUrl has invalid port` ← يحتوي CDP URL المهيأ على منفذ غير صالح أو خارج النطاق.
- `No Chrome tabs found for profile="user"` ← لا توجد علامات تبويب Chrome محلية مفتوحة لملف تعريف الإرفاق Chrome MCP.
- `Remote CDP for profile "<name>" is not reachable` ← نقطة نهاية CDP البعيدة المهيأة غير قابلة للوصول من هذا المضيف.
- `Browser attachOnly is enabled ... not reachable` أو `Browser attachOnly is enabled and CDP websocket ... is not reachable` ← لا يملك ملف تعريف attach-only هدف CDP حيًا.
- تجاوزات viewport / dark-mode / locale / offline القديمة في ملفات تعريف attach-only أو CDP البعيدة ← شغّل `openclaw browser stop --browser-profile <name>` لإغلاق جلسة التحكم النشطة وتحرير حالة المحاكاة من دون إعادة تشغيل البوابة.
- `unknown command "browser"` أو `unknown command 'browser'` → تم ضبط `plugins.allow` ولا يتضمن `browser`.
- `Failed to start Chrome CDP on port` → فشل تشغيل المتصفح المحلي.
- `browser.executablePath not found` → مسار الملف التنفيذي المهيأ غير صحيح.
- `browser.cdpUrl must be http(s) or ws(s)` → يستخدم عنوان CDP المهيأ مخططًا غير مدعوم.
- `browser.cdpUrl has invalid port` → يحتوي عنوان CDP المهيأ على منفذ سيئ أو خارج النطاق.
- `No Chrome tabs found for profile="user"` → لا يحتوي ملف تعريف إرفاق Chrome MCP على علامات تبويب Chrome محلية مفتوحة.
- `Remote CDP for profile "<name>" is not reachable` → يتعذر الوصول إلى نقطة نهاية CDP البعيدة المهيأة من هذا المضيف.
- `Browser attachOnly is enabled ... not reachable` أو `Browser attachOnly is enabled and CDP websocket ... is not reachable` → لا يحتوي ملف تعريف attach-only على هدف CDP حي.
- تجاوزات viewport / dark-mode / locale / offline القديمة على ملفات تعريف attach-only أو CDP البعيدة → شغّل `openclaw browser stop --browser-profile <name>` لإغلاق جلسة التحكم النشطة وتحرير حالة المحاكاة دون إعادة تشغيل البوابة.
الصفحات التفصيلية:
- [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails)
- [/tools/browser#missing-browser-command-or-tool](/tools/browser#missing-browser-command-or-tool)
- [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
- [/gateway/troubleshooting#browser-tool-fails](/ar/gateway/troubleshooting#browser-tool-fails)
- [/tools/browser#missing-browser-command-or-tool](/ar/tools/browser#missing-browser-command-or-tool)
- [/tools/browser-linux-troubleshooting](/ar/tools/browser-linux-troubleshooting)
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/ar/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
</Accordion>
</AccordionGroup>
## ذو صلة
- [الأسئلة الشائعة](/help/faq) — الأسئلة المتكررة
- [استكشاف أخطاء Gateway وإصلاحها](/gateway/troubleshooting) — المشكلات الخاصة بالبوابة
- [Doctor](/gateway/doctor) — فحوصات الصحة والإصلاحات الآلية
- [استكشاف أخطاء القنوات وإصلاحها](/channels/troubleshooting) — مشكلات اتصال القنوات
- [استكشاف أخطاء الأتمتة وإصلاحها](/automation/cron-jobs#troubleshooting) — مشكلات cron وheartbeat
- [الأسئلة الشائعة](/ar/help/faq) — الأسئلة المتداولة
- [استكشاف أخطاء البوابة وإصلاحها](/ar/gateway/troubleshooting) — المشكلات الخاصة بالبوابة
- [Doctor](/ar/gateway/doctor) — فحوصات الصحة والإصلاحات الآلية
- [استكشاف أخطاء القنوات وإصلاحها](/ar/channels/troubleshooting) — مشكلات اتصال القنوات
- [استكشاف أخطاء الأتمتة وإصلاحها](/ar/automation/cron-jobs#troubleshooting) — مشكلات cron وHeartbeat

1742
docs/ar/plugins/architecture.md
View File

File diff suppressed because it is too large Load Diff

366
docs/ar/plugins/sdk-channel-plugins.md
View File

@ -1,98 +1,114 @@
---
read_when:
- أنت تبني plugin قناة مراسلة جديدة
- أنت تبني إضافة قناة مراسلة جديدة
- تريد ربط OpenClaw بمنصة مراسلة
- تحتاج إلى فهم سطح محول ChannelPlugin
- تحتاج إلى فهم سطح محوّل ChannelPlugin
sidebarTitle: Channel Plugins
summary: دليل خطوة بخطوة لبناء plugin قناة مراسلة لـ OpenClaw
title: بناء plugins القنوات
summary: دليل خطوة بخطوة لبناء إضافة قناة مراسلة لـ OpenClaw
title: بناء إضافات القنوات
x-i18n:
generated_at: "2026-04-07T07:20:16Z"
generated_at: "2026-04-08T02:18:48Z"
model: gpt-5.4
provider: openai
source_hash: 0aab6cc835b292c62e33c52ad0c35f989fb1a5b225511e8bdc2972feb3c64f09
source_hash: d23365b6d92006b30e671f9f0afdba40a2b88c845c5d2299d71c52a52985672f
source_path: plugins/sdk-channel-plugins.md
workflow: 15
---
# بناء plugins القنوات
# بناء إضافات القنوات
يرشدك هذا الدليل خلال بناء plugin قناة يربط OpenClaw بمنصة
مراسلة. وبنهاية الدليل سيكون لديك قناة عاملة مع أمان الرسائل الخاصة،
وpairing، وربط الردود في سلاسل، والمراسلة الصادرة.
يرشدك هذا الدليل خلال بناء إضافة قناة تربط OpenClaw بمنصة
مراسلة. وبنهاية هذا الدليل سيكون لديك قناة عاملة تتضمن أمان الرسائل المباشرة،
والاقتران، وتسلسل الردود، والمراسلة الصادرة.
<Info>
إذا لم تكن قد بنيت أي plugin لـ OpenClaw من قبل، فاقرأ
[البدء](/ar/plugins/building-plugins) أولًا لمعرفة بنية الحزمة الأساسية
وإعداد manifest.
إذا لم تكن قد بنيت أي إضافة OpenClaw من قبل، فاقرأ
[البدء](/ar/plugins/building-plugins) أولًا للاطلاع على البنية الأساسية
للحزمة وإعداد manifest.
</Info>
## كيف تعمل plugins القنوات
## كيف تعمل إضافات القنوات
لا تحتاج plugins القنوات إلى أدوات send/edit/react خاصة بها. يحتفظ OpenClaw
بأداة `message` واحدة مشتركة في النواة. وتمتلك plugin الخاصة بك ما يلي:
لا تحتاج إضافات القنوات إلى أدوات send/edit/react خاصة بها. يحتفظ OpenClaw
بأداة `message` مشتركة واحدة في النواة. وتملك إضافتك ما يلي:
- **التهيئة** — تحليل الحسابات ومعالج الإعداد
- **الأمان** — سياسة الرسائل الخاصة وallowlists
- **Pairing** — تدفق اعتماد الرسائل الخاصة
- **صياغة الجلسة** — كيفية تعيين معرّفات المحادثة الخاصة بالموفر إلى الدردشات الأساسية ومعرّفات سلاسل الرسائل وبدائل الأصل
- **الصادر** — إرسال النصوص والوسائط واستطلاعات الرأي إلى المنصة
- **الترابط في السلاسل** — كيفية ربط الردود في سلاسل
- **الإعدادات** — حلّ الحسابات ومعالج الإعداد
- **الأمان** — سياسة الرسائل المباشرة وقوائم السماح
- **الاقتران** — تدفق الموافقة على الرسائل المباشرة
- **بنية الجلسة** — كيفية ربط معرّفات المحادثات الخاصة بالمزوّد بالدردشات الأساسية ومعرّفات السلاسل والبدائل الأصلية
- **الصادر** — إرسال النصوص والوسائط والاستطلاعات إلى المنصة
- **التسلسل** — كيفية ربط الردود ضمن السلاسل
تمتلك النواة أداة الرسائل المشتركة، وربط prompt، وشكل مفتاح الجلسة الخارجي،
والتتبّع العام `:thread:`، والإرسال.
تملك النواة أداة الرسائل المشتركة، وربط الموجّهات، وشكل مفتاح الجلسة الخارجي،
وإدارة `:thread:` العامة، والتوزيع.
إذا كانت منصتك تخزّن نطاقًا إضافيًا داخل معرّفات المحادثات، فاحتفظ بهذا التحليل
داخل plugin باستخدام `messaging.resolveSessionConversation(...)`. هذا هو
المدخل القياسي لتعيين `rawId` إلى معرّف المحادثة الأساسي، ومعرّف سلسلة
اختياري، و`baseConversationId` صريح، وأي `parentConversationCandidates`.
عندما تعيد `parentConversationCandidates`، فاحرص على ترتيبها من
الأصل الأضيق إلى المحادثة الأساسية/الأوسع.
إذا كانت منصتك تخزن نطاقًا إضافيًا داخل معرّفات المحادثات، فاحتفظ بهذا التحليل
داخل الإضافة باستخدام `messaging.resolveSessionConversation(...)`. هذا هو
الخطاف القياسي لتحويل `rawId` إلى معرّف المحادثة الأساسي، ومعرّف السلسلة الاختياري،
و`baseConversationId` الصريح، وأي `parentConversationCandidates`.
عندما تُرجع `parentConversationCandidates`، احرص على ترتيبها من
الأصل الأضيق إلى المحادثة الأوسع/الأساسية.
يمكن أيضًا لـ plugins المضمّنة التي تحتاج إلى التحليل نفسه قبل إقلاع سجل القنوات
أن تعرض ملف `session-key-api.ts` أعلى المستوى مع
تصدير `resolveSessionConversation(...)` مطابق. تستخدم النواة هذا السطح الآمن
للتمهيد فقط عندما لا يكون سجل plugin وقت التشغيل متاحًا بعد.
يمكن أيضًا للإضافات المضمّنة التي تحتاج إلى التحليل نفسه قبل إقلاع
سجل القنوات أن تعرض ملف `session-key-api.ts` على المستوى الأعلى مع
تصدير مطابق `resolveSessionConversation(...)`. تستخدم النواة هذا السطح
الآمن للإقلاع فقط عندما لا يكون سجل الإضافات وقت التشغيل متاحًا بعد.
يبقى `messaging.resolveParentConversationCandidates(...)` متاحًا كبديل
توافقي قديم عندما تحتاج plugin فقط إلى بدائل الأصل فوق
المعرّف العام/الخام. وإذا وُجد كلا المدخلين، تستخدم النواة
يبقى `messaging.resolveParentConversationCandidates(...)` متاحًا
كبديل توافق قديم عندما تحتاج الإضافة فقط إلى بدائل أصلية فوق
المعرّف العام/الخام. إذا وُجد الخطافان معًا، تستخدم النواة
`resolveSessionConversation(...).parentConversationCandidates` أولًا ولا
تعود إلى `resolveParentConversationCandidates(...)` إلا عندما يحذفها
المدخل القياسي.
تعود إلى `resolveParentConversationCandidates(...)` إلا عندما يتجاهلها
الخطاف القياسي.
## الموافقات وإمكانات القناة
## الموافقات وقدرات القناة
معظم plugins القنوات لا تحتاج إلى شيفرة خاصة بالموافقات.
لا تحتاج معظم إضافات القنوات إلى تعليمات برمجية خاصة بالموافقات.
- تمتلك النواة `/approve` في الدردشة نفسها، وحمولات أزرار الموافقة المشتركة، والتسليم الاحتياطي العام.
- فضّل كائن `approvalCapability` واحدًا على plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقات.
- يمثّل `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` مدخل التفويض القياسي للموافقات.
- إذا كانت قناتك تعرض موافقات exec أصلية، فنفّذ `approvalCapability.getActionAvailabilityState` حتى عندما تعيش وسيلة النقل الأصلية بالكامل تحت `approvalCapability.native`. تستخدم النواة هذا المدخل الخاص بالتوافر للتمييز بين `enabled` و`disabled`، وتقرير ما إذا كانت القناة البادئة تدعم الموافقات الأصلية، وتضمين القناة في إرشادات fallback الخاصة بالعميل الأصلي.
- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولات الخاص بالقناة مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم.
- استخدم `approvalCapability.delivery` فقط للتوجيه الأصلي للموافقات أو كبت fallback.
- استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من المصيّر المشترك.
- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد المسار المعطّل مفاتيح التهيئة الدقيقة المطلوبة لتمكين موافقات exec الأصلية. يتلقى المدخل `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسماة عرض مسارات بنطاق الحساب مثل `channels.<channel>.accounts.<id>.execApprovals.*` بدلًا من القيم الافتراضية على المستوى الأعلى.
- إذا كانت القناة تستطيع استنتاج هويات رسائل خاصة ثابتة شبيهة بالمالك من التهيئة الحالية، فاستخدم `createResolvedApproverActionAuthAdapter` من `openclaw/plugin-sdk/approval-runtime` لتقييد `/approve` في الدردشة نفسها دون إضافة منطق خاص بالموافقات إلى النواة.
- إذا كانت القناة تحتاج إلى تسليم موافقات أصلية، فأبقِ شيفرة القناة مركزة على تطبيع الهدف ومدخلات وسيلة النقل. استخدم `createChannelExecApprovalProfile` و`createChannelNativeOriginTargetResolver` و`createChannelApproverDmTargetResolver` و`createApproverRestrictedNativeApprovalCapability` و`createChannelNativeApprovalRuntime` من `openclaw/plugin-sdk/approval-runtime` حتى تمتلك النواة تصفية الطلبات والتوجيه وإزالة التكرار والانتهاء والاشتراك في البوابة.
- يجب على قنوات الموافقات الأصلية تمرير كل من `accountId` و`approvalKind` عبر هذه المساعدات. يحافظ `accountId` على تقييد سياسة الموافقات متعددة الحسابات بنطاق حساب الروبوت الصحيح، ويحافظ `approvalKind` على إتاحة سلوك exec مقابل plugin للقناة دون فروع ثابتة في النواة.
- حافظ على نوع معرّف الموافقة المُسلَّم من البداية إلى النهاية. يجب على العملاء الأصليين ألا
يخمّنوا أو يعيدوا كتابة توجيه موافقات exec مقابل plugin اعتمادًا على حالة محلية في القناة.
- يمكن لأنواع الموافقات المختلفة أن تعرض عمدًا أسطحًا أصلية مختلفة.
أمثلة مضمّنة حالية:
- يحتفظ Slack بإتاحة توجيه الموافقات الأصلية لكل من معرّفات exec وplugin.
- يحتفظ Matrix بتوجيه الرسائل الخاصة/القنوات الأصلي لموافقات exec فقط ويترك
موافقات plugin على مسار `/approve` المشترك داخل الدردشة نفسها.
- ما يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافق، لكن الشيفرة الجديدة يجب أن تفضّل باني الإمكانات وتعرض `approvalCapability` على plugin.
- تملك النواة الأمر `/approve` داخل الدردشة نفسها، وحمولات أزرار الموافقة المشتركة، وآلية التسليم العامة البديلة.
- فضّل استخدام كائن `approvalCapability` واحد في إضافة القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة.
- تمت إزالة `ChannelPlugin.approvals`. ضع حقائق تسليم/أصلية/عرض/مصادقة الموافقة في `approvalCapability`.
- يقتصر `plugin.auth` على login/logout فقط؛ ولم تعد النواة تقرأ خطافات مصادقة الموافقة من ذلك الكائن.
- يشكّل كل من `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` سطح مصادقة الموافقة القياسي.
- استخدم `approvalCapability.getActionAvailabilityState` لتوافر مصادقة الموافقة داخل الدردشة نفسها.
- إذا كانت قناتك تعرض موافقات exec أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة السطح المُطلِق/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل الدردشة نفسها. تستخدم النواة هذا الخطاف الخاص بـ exec للتمييز بين `enabled` و`disabled`، ولتحديد ما إذا كانت القناة المُطلِقة تدعم موافقات exec الأصلية، ولتضمين القناة في إرشادات بدائل العميل الأصلي. يملأ `createApproverRestrictedNativeApprovalCapability(...)` هذا للحالة الشائعة.
- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولة الخاص بالقناة مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم.
- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقة الأصلية أو منع التسليم البديل.
- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية للموافقة المملوكة للقناة. احرص على إبقائه كسولًا في نقاط دخول القناة الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، الذي يمكنه استيراد وحدة وقت التشغيل عند الطلب مع استمرار قدرة النواة على تجميع دورة حياة الموافقة.
- استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من العارض المشترك.
- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد مسار التعطيل مفاتيح الإعداد الدقيقة اللازمة لتمكين موافقات exec الأصلية. يتلقى الخطاف `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسمّاة عرض مسارات على مستوى الحساب مثل `channels.<channel>.accounts.<id>.execApprovals.*` بدلًا من الإعدادات الافتراضية العليا.
- إذا كانت القناة تستطيع استنتاج هويات DM مستقرة شبيهة بالمالك من الإعدادات الحالية، فاستخدم `createResolvedApproverActionAuthAdapter` من `openclaw/plugin-sdk/approval-runtime` لتقييد `/approve` داخل الدردشة نفسها دون إضافة منطق أساسي خاص بالموافقة.
- إذا احتاجت القناة إلى تسليم موافقة أصلية، فأبقِ تعليمات القناة البرمجية مركّزة على تطبيع الهدف وحقائق النقل/العرض. استخدم `createChannelExecApprovalProfile` و`createChannelNativeOriginTargetResolver` و`createChannelApproverDmTargetResolver` و`createApproverRestrictedNativeApprovalCapability` من `openclaw/plugin-sdk/approval-runtime`. ضع الحقائق الخاصة بالقناة خلف `approvalCapability.nativeRuntime`، ويفضل عبر `createChannelApprovalNativeRuntimeAdapter(...)` أو `createLazyChannelApprovalNativeRuntimeAdapter(...)`، حتى تتمكن النواة من تجميع المعالج وامتلاك تصفية الطلبات والتوجيه وإزالة التكرار والانتهاء والاشتراك في البوابة وإشعارات التوجيه إلى مكان آخر. ينقسم `nativeRuntime` إلى عدة أسطح أصغر:
- `availability` — ما إذا كان الحساب مضبوطًا وما إذا كان ينبغي التعامل مع الطلب
- `presentation` — تحويل نموذج عرض الموافقة المشترك إلى حمولات أصلية معلقة/محسومة/منتهية أو إجراءات نهائية
- `transport` — تجهيز الأهداف وإرسال/تحديث/حذف رسائل الموافقة الأصلية
- `interactions` — خطافات bind/unbind/clear-action اختيارية للأزرار أو التفاعلات الأصلية
- `observe` — خطافات اختيارية لتشخيصات التسليم
- إذا احتاجت القناة إلى كائنات مملوكة لوقت التشغيل مثل عميل أو رمز أو تطبيق Bolt أو مستقبل webhook، فسجّلها عبر `openclaw/plugin-sdk/channel-runtime-context`. يتيح سجل runtime-context العام للنواة تهيئة معالجات مدفوعة بالقدرات من حالة بدء تشغيل القناة دون إضافة غراء تغليف خاص بالموافقة.
- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` ذوي المستوى الأدنى إلا عندما لا يكون السطح المدفوع بالقدرات معبّرًا بما يكفي بعد.
- يجب على قنوات الموافقة الأصلية تمرير كل من `accountId` و`approvalKind` عبر هذه المساعدات. يحافظ `accountId` على حصر سياسة الموافقة متعددة الحسابات ضمن حساب البوت الصحيح، ويحافظ `approvalKind` على إتاحة سلوك موافقات exec مقابل الإضافة للقناة دون فروع مضمنة صراحة في النواة.
- أصبحت النواة الآن تملك إشعارات إعادة توجيه الموافقات أيضًا. يجب ألا ترسل إضافات القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل المباشرة / إلى قناة أخرى" من `createChannelNativeApprovalRuntime`؛ بل اعرض بدلًا من ذلك توجيه الأصل + الرسائل المباشرة للموافق عبر مساعدات قدرة الموافقة المشتركة واترك للنواة تجميع عمليات التسليم الفعلية قبل نشر أي إشعار إلى الدردشة المُطلِقة.
- حافظ على نوع معرّف الموافقة المسلَّم من البداية إلى النهاية. يجب ألا
يخمّن العملاء الأصليون أو يعيدوا كتابة توجيه موافقة exec مقابل الإضافة من حالة محلية بالقناة.
- يمكن لأنواع الموافقة المختلفة أن تعرض عمدًا أسطحًا أصلية مختلفة.
الأمثلة المضمّنة الحالية:
- يحتفظ Slack بإتاحة توجيه الموافقة الأصلية لكل من معرّفات exec والإضافة.
- يحتفظ Matrix بالتوجيه نفسه داخل الرسائل المباشرة/القناة وواجهة تفاعل reactions لموافقات exec
والإضافة، مع الاستمرار في السماح لاختلاف المصادقة حسب نوع الموافقة.
- ما يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافق، لكن التعليمات البرمجية الجديدة يجب أن تفضّل مُنشئ القدرات وأن تعرض `approvalCapability` على الإضافة.
بالنسبة إلى نقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق وقت التشغيل عندما تحتاج
إلى جزء واحد فقط من هذه المجموعة:
لنقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق لوقت التشغيل عندما
تحتاج جزءًا واحدًا فقط من هذه العائلة:
- `openclaw/plugin-sdk/approval-auth-runtime`
- `openclaw/plugin-sdk/approval-client-runtime`
- `openclaw/plugin-sdk/approval-delivery-runtime`
- `openclaw/plugin-sdk/approval-gateway-runtime`
- `openclaw/plugin-sdk/approval-handler-adapter-runtime`
- `openclaw/plugin-sdk/approval-handler-runtime`
- `openclaw/plugin-sdk/approval-native-runtime`
- `openclaw/plugin-sdk/approval-reply-runtime`
- `openclaw/plugin-sdk/channel-runtime-context`
وبالمثل، فضّل `openclaw/plugin-sdk/setup-runtime`،
و`openclaw/plugin-sdk/setup-adapter-runtime`،
@ -105,88 +121,88 @@ x-i18n:
وبالنسبة إلى الإعداد تحديدًا:
- يغطي `openclaw/plugin-sdk/setup-runtime` مساعدات الإعداد الآمنة لوقت التشغيل:
محولات رقع الإعداد الآمنة للاستيراد (`createPatchedAccountSetupAdapter`,
محوّلات تصحيح الإعداد الآمنة للاستيراد (`createPatchedAccountSetupAdapter`,
`createEnvPatchedAccountSetupAdapter`,
`createSetupInputPresenceValidator`)، ومخرجات ملاحظات البحث،
و`promptResolvedAllowFrom`، و`splitSetupEntries`، وبناة
proxy الإعداد المفوّض
- يمثّل `openclaw/plugin-sdk/setup-adapter-runtime`
مدخل المحول الضيق الواعي بمتغيرات البيئة لـ `createEnvPatchedAccountSetupAdapter`
- يغطي `openclaw/plugin-sdk/channel-setup` بناة الإعداد ذي التثبيت الاختياري
بالإضافة إلى بعض الأوليات الآمنة للإعداد:
`createOptionalChannelSetupSurface`، و`createOptionalChannelSetupAdapter`،
`createSetupInputPresenceValidator`)، ومخرجات ملاحظات lookup،
و`promptResolvedAllowFrom`، و`splitSetupEntries`، ومنشئات
setup-proxy المفوّضة
- يمثّل `openclaw/plugin-sdk/setup-adapter-runtime` سطح المحوّل
الضيق الواعي بالبيئة لـ `createEnvPatchedAccountSetupAdapter`
- يغطي `openclaw/plugin-sdk/channel-setup` منشئات الإعداد ذات التثبيت الاختياري
بالإضافة إلى بعض العناصر الأولية الآمنة للإعداد:
`createOptionalChannelSetupSurface` و`createOptionalChannelSetupAdapter`،
إذا كانت قناتك تدعم إعدادًا أو مصادقة مدفوعين بمتغيرات البيئة ويجب أن تعرف
تدفقات بدء التشغيل/التهيئة العامة أسماء متغيرات البيئة تلك قبل تحميل وقت التشغيل،
فصرّح بها في manifest الخاص بـ plugin باستخدام `channelEnvVars`. واحتفظ
بـ `envVars` وقت تشغيل القناة أو الثوابت المحلية لنسخة المشغّل فقط.
`createOptionalChannelSetupWizard`، و`DEFAULT_ACCOUNT_ID`،
و`createTopLevelChannelDmPolicy`، و`setSetupChannelEnabled`، و
إذا كانت قناتك تدعم الإعداد أو المصادقة المعتمدين على env وكان ينبغي لتدفقات
البدء/الإعدادات العامة معرفة أسماء env هذه قبل تحميل وقت التشغيل، فصرّح بها في
manifest الإضافة باستخدام `channelEnvVars`. واحتفظ بـ `envVars` الخاصة بوقت تشغيل القناة
أو الثوابت المحلية للنصوص الموجهة للمشغّل فقط.
`createOptionalChannelSetupWizard` و`DEFAULT_ACCOUNT_ID`،
و`createTopLevelChannelDmPolicy` و`setSetupChannelEnabled` و
`splitSetupEntries`
- استخدم المدخل الأوسع `openclaw/plugin-sdk/setup` فقط عندما تحتاج أيضًا إلى
مساعدات الإعداد/التهيئة المشتركة الأثقل مثل
- استخدم السطح الأوسع `openclaw/plugin-sdk/setup` فقط عندما تحتاج أيضًا إلى
مساعدات الإعداد/الضبط المشتركة الأثقل مثل
`moveSingleAccountChannelSectionToDefaultAccount(...)`
إذا كانت قناتك تريد فقط الإعلان عن "ثبّت هذه plugin أولًا" في أسطح الإعداد،
إذا كانت قناتك تريد فقط الإعلان "ثبّت هذه الإضافة أولًا" في أسطح الإعداد،
ففضّل `createOptionalChannelSetupSurface(...)`. يفشل
المحول/المعالج المولدان إغلاقًا على كتابات التهيئة والإنهاء، ويعيدان استخدام
رسالة "التثبيت مطلوب" نفسها عبر التحقق والإنهاء ونسخة روابط المستندات.
المحوّل/المعالج المولّد بطريقة مغلقة عند كتابة الإعدادات والإنهاء، ويعيدان استخدام
رسالة "التثبيت مطلوب" نفسها عبر التحقق والإنهاء ونصوص روابط الوثائق.
وبالنسبة إلى المسارات الساخنة الأخرى للقناة، فضّل المساعدات الضيقة على الأسطح القديمة الأوسع:
لمسارات القنوات الساخنة الأخرى، فضّل المساعدات الضيقة على الأسطح
القديمة الأوسع:
- `openclaw/plugin-sdk/account-core`،
و`openclaw/plugin-sdk/account-id`،
و`openclaw/plugin-sdk/account-resolution`، و
`openclaw/plugin-sdk/account-helpers` للتهيئة متعددة الحسابات
`openclaw/plugin-sdk/account-helpers` من أجل إعدادات الحسابات المتعددة
والرجوع إلى الحساب الافتراضي
- `openclaw/plugin-sdk/inbound-envelope` و
`openclaw/plugin-sdk/inbound-reply-dispatch` لربط
المسار/الظرف الوارد والتسجيل ثم الإرسال
`openclaw/plugin-sdk/inbound-reply-dispatch` لتوجيه/غلاف الوارد
وربط التسجيل والتوزيع
- `openclaw/plugin-sdk/messaging-targets` لتحليل/مطابقة الأهداف
- `openclaw/plugin-sdk/outbound-media` و
`openclaw/plugin-sdk/outbound-runtime` لتحميل الوسائط مع
مفوّضي الهوية/الإرسال الصادر
- `openclaw/plugin-sdk/thread-bindings-runtime` لدورة حياة
روابط سلاسل الرسائل وتسجيل المحول
- `openclaw/plugin-sdk/agent-media-payload` فقط عندما يكون
تخطيط حقول حمولة الوكيل/الوسائط القديم لا يزال مطلوبًا
- `openclaw/plugin-sdk/telegram-command-config` لتطبيع
الأوامر المخصصة في Telegram والتحقق من التكرار/التعارض وعقد
تهيئة الأوامر المستقر في fallback
`openclaw/plugin-sdk/outbound-runtime` لتحميل الوسائط بالإضافة إلى
مفوّضات الهوية/الإرسال الصادرة
- `openclaw/plugin-sdk/thread-bindings-runtime` لدورة حياة ربط السلاسل
وتسجيل المحوّلات
- `openclaw/plugin-sdk/agent-media-payload` فقط عندما يكون تخطيط حقل
agent/media القديم ما يزال مطلوبًا
- `openclaw/plugin-sdk/telegram-command-config` من أجل التطبيع والتحقق من التكرارات/التعارضات
الخاصة بأوامر Telegram المخصصة، وعقد إعداد الأوامر المستقر كبديل
يمكن للقنوات التي تعتمد على المصادقة فقط أن تتوقف غالبًا عند المسار الافتراضي: تتعامل النواة مع الموافقات وتعرض plugin فقط إمكانات الصادر/المصادقة. ويجب على قنوات الموافقات الأصلية مثل Matrix وSlack وTelegram ووسائط الدردشة المخصصة استخدام المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقات الخاصة بها.
يمكن للقنوات الخاصة بالمصادقة فقط عادةً أن تكتفي بالمسار الافتراضي: تتولى النواة الموافقات وتعرض الإضافة فقط قدرات الصادر/المصادقة. أما قنوات الموافقة الأصلية مثل Matrix وSlack وTelegram ووسائط الدردشة المخصصة فينبغي أن تستخدم المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة بنفسها.
## سياسة الذكر في الوارد
## سياسة الإشارة الواردة
أبقِ التعامل مع الذكر في الرسائل الواردة مقسّمًا إلى طبقتين:
احرص على فصل التعامل مع الإشارات الواردة إلى طبقتين:
- جمع الأدلة المملوك لـ plugin
- جمع الأدلة المملوك للإضافة
- تقييم السياسة المشتركة
استخدم `openclaw/plugin-sdk/channel-inbound` للطبقة المشتركة.
ملائم للمنطق المحلي في plugin:
ملائم للمنطق المحلي في الإضافة:
- اكتشاف الرد على الروبوت
- اكتشاف الاقتباس من الروبوت
- فحوصات المشاركة في سلسلة الرسائل
- اكتشاف الرد على البوت
- اكتشاف الاقتباس من البوت
- فحوص مشاركة السلسلة
- استبعاد رسائل الخدمة/النظام
- الذاكرات المخبئية الأصلية للمنصة اللازمة لإثبات مشاركة الروبوت
- الذاكرات المؤقتة الأصلية للمنصة اللازمة لإثبات مشاركة البوت
ملائم للمساعد المشترك:
- `requireMention`
- نتيجة الذكر الصريح
- allowlist الذكر الضمني
- نتيجة الإشارة الصريحة
- قائمة السماح الخاصة بالإشارة الضمنية
- تجاوز الأوامر
- قرار التخطي النهائي
التدفق المفضل:
1. احسب حقائق الذكر المحلية.
2. مرر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`.
3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد.
1. احسب حقائق الإشارة المحلية.
2. مرّر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`.
3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد لديك.
```typescript
import {
@ -225,8 +241,8 @@ const decision = resolveInboundMentionDecision({
if (decision.shouldSkip) return;
```
يكشف `api.runtime.channel.mentions` عن مساعدات الذكر المشتركة نفسها من أجل
plugins القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل:
يكشف `api.runtime.channel.mentions` عن مساعدات الإشارة المشتركة نفسها
لإضافات القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل:
- `buildMentionRegexes`
- `matchesMentionPatterns`
@ -234,18 +250,18 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
- `implicitMentionKindWhen`
- `resolveInboundMentionDecision`
تبقى المساعدات الأقدم `resolveMentionGating*` على
`openclaw/plugin-sdk/channel-inbound` كتصديرات توافق فقط. ويجب أن تستخدم الشيفرة الجديدة
`resolveInboundMentionDecision({ facts, policy })`.
تبقى مساعدات `resolveMentionGating*` الأقدم على
`openclaw/plugin-sdk/channel-inbound` كتصديرات توافق فقط. ويجب على
التعليمات البرمجية الجديدة استخدام `resolveInboundMentionDecision({ facts, policy })`.
## الشرح العملي
## شرح عملي
<Steps>
<a id="step-1-package-and-manifest"></a>
<Step title="الحزمة وmanifest">
أنشئ ملفات plugin القياسية. الحقل `channel` في `package.json` هو
ما يجعل هذه plugin قناة. وللاطلاع على سطح بيانات تعريف الحزمة الكامل،
راجع [إعداد plugin والتهيئة](/ar/plugins/sdk-setup#openclawchannel):
أنشئ ملفات الإضافة القياسية. إن حقل `channel` في `package.json` هو
ما يجعل هذه إضافة قناة. وللاطلاع على سطح بيانات تعريف الحزمة الكامل،
راجع [إعداد الإضافة والضبط](/ar/plugins/sdk-setup#openclawchannel):
<CodeGroup>
```json package.json
@ -294,9 +310,9 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
</Step>
<Step title="ابنِ كائن plugin القناة">
تحتوي الواجهة `ChannelPlugin` على العديد من أسطح المحولات الاختيارية. ابدأ
بالحد الأدنى — `id` و`setup` — ثم أضف المحولات عند الحاجة.
<Step title="ابنِ كائن إضافة القناة">
تحتوي الواجهة `ChannelPlugin` على العديد من أسطح المحوّلات الاختيارية. ابدأ
بالحد الأدنى — `id` و`setup` — وأضف المحوّلات حسب الحاجة.
أنشئ `src/channel.ts`:
@ -306,7 +322,7 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
createChannelPluginBase,
} from "openclaw/plugin-sdk/channel-core";
import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
import { acmeChatApi } from "./client.js"; // عميل API الخاص بمنصتك
import { acmeChatApi } from "./client.js"; // your platform API client
type ResolvedAccount = {
accountId: string | null;
@ -347,7 +363,7 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
},
}),
// أمان الرسائل الخاصة: من يمكنه مراسلة الروبوت
// DM security: who can message the bot
security: {
dm: {
channelKey: "acme-chat",
@ -357,7 +373,7 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
},
},
// Pairing: تدفق الاعتماد لجهات الاتصال الجديدة في الرسائل الخاصة
// Pairing: approval flow for new DM contacts
pairing: {
text: {
idLabel: "Acme Chat username",
@ -368,10 +384,10 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
},
},
// الترابط في السلاسل: كيفية تسليم الردود
// Threading: how replies are delivered
threading: { topLevelReplyToMode: "reply" },
// الصادر: إرسال الرسائل إلى المنصة
// Outbound: send messages to the platform
outbound: {
attachedResults: {
sendText: async (params) => {
@ -391,24 +407,24 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
});
```
<Accordion title="ما الذي ينجزه createChatChannelPlugin من أجلك">
بدلًا من تنفيذ واجهات المحولات منخفضة المستوى يدويًا، تمرر
خيارات تصريحية ويقوم الباني بتركيبها:
<Accordion title="ما الذي يفعله createChatChannelPlugin من أجلك">
بدلًا من تنفيذ واجهات المحوّلات منخفضة المستوى يدويًا، تمرّر
خيارات تصريحية ويقوم المنشئ بتركيبها:
| الخيار | ما الذي يربطه |
| --- | --- |
| `security.dm` | محلّل أمان الرسائل الخاصة ضمن النطاق من حقول التهيئة |
| `pairing.text` | تدفق pairing للرسائل الخاصة المعتمد على النص مع تبادل الرموز |
| `threading` | محلّل وضع الرد (ثابت، أو ضمن نطاق الحساب، أو مخصص) |
| `outbound.attachedResults` | دوال الإرسال التي تعيد بيانات تعريف النتيجة (معرّفات الرسائل) |
| `security.dm` | محلّل أمان DM مقيّد من حقول الإعداد |
| `pairing.text` | تدفق اقتران DM قائم على النص مع تبادل الرموز |
| `threading` | محلّل وضع reply-to (ثابت، أو مقيد بالحساب، أو مخصص) |
| `outbound.attachedResults` | دوال الإرسال التي ترجع بيانات تعريف النتيجة (معرّفات الرسائل) |
يمكنك أيضًا تمرير كائنات محولات خام بدلًا من الخيارات التصريحية
يمكنك أيضًا تمرير كائنات محوّلات خام بدلًا من الخيارات التصريحية
إذا كنت تحتاج إلى تحكم كامل.
</Accordion>
</Step>
<Step title="اربط نقطة الدخول">
<Step title="صِل نقطة الدخول">
أنشئ `index.ts`:
```typescript index.ts
@ -446,20 +462,20 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
ضع واصفات CLI المملوكة للقناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw
من عرضها في المساعدة الجذرية دون تفعيل وقت تشغيل القناة الكامل،
بينما تلتقط عمليات التحميل الكاملة العادية الواصفات نفسها لتسجيل الأوامر
الفعلي. واحتفظ بـ `registerFull(...)` للأعمال الخاصة بوقت التشغيل فقط.
إذا كان `registerFull(...)` يسجل أساليب RPC للبوابة، فاستخدم
بادئة خاصة بـ plugin. تبقى نطاقات الإدارة الأساسية (`config.*`،
و`exec.approvals.*`، و`wizard.*`، و`update.*`) محجوزة وتُحل دائمًا
إلى `operator.admin`.
يتعامل `defineChannelPluginEntry` مع تقسيم أوضاع التسجيل تلقائيًا. راجع
[نقاط الدخول](/ar/plugins/sdk-entrypoints#definechannelpluginentry) لكل
بينما تلتقط التحميلات الكاملة العادية الواصفات نفسها لتسجيل الأوامر الفعلي.
واحتفظ بـ `registerFull(...)` للعمل الخاص بوقت التشغيل فقط.
إذا كان `registerFull(...)` يسجّل طرائق Gateway RPC، فاستخدم
بادئة خاصة بالإضافة. تظل مساحات أسماء إدارة النواة (`config.*`،
و`exec.approvals.*`، و`wizard.*`، و`update.*`) محجوزة وتُحل دائمًا إلى
`operator.admin`.
يعالج `defineChannelPluginEntry` تقسيم وضع التسجيل تلقائيًا. راجع
[نقاط الدخول](/ar/plugins/sdk-entrypoints#definechannelpluginentry) للاطلاع على جميع
الخيارات.
</Step>
<Step title="أضف نقطة دخول للإعداد">
أنشئ `setup-entry.ts` للتحميل الخفيف أثناء onboarding:
أنشئ `setup-entry.ts` للتحميل الخفيف أثناء الإعداد الأولي:
```typescript setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
@ -469,27 +485,27 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
```
يحمّل OpenClaw هذا بدلًا من نقطة الدخول الكاملة عندما تكون القناة معطلة
أو غير مهيأة. وهو يتجنب سحب شيفرة وقت تشغيل ثقيلة أثناء تدفقات الإعداد.
راجع [الإعداد والتهيئة](/ar/plugins/sdk-setup#setup-entry) للتفاصيل.
أو غير مضبوطة. وهذا يتجنب سحب تعليمات وقت تشغيل ثقيلة أثناء تدفقات الإعداد.
راجع [الإعداد والضبط](/ar/plugins/sdk-setup#setup-entry) للتفاصيل.
</Step>
<Step title="تعامل مع الرسائل الواردة">
تحتاج plugin الخاصة بك إلى تلقي الرسائل من المنصة وإعادة توجيهها إلى
تحتاج إضافتك إلى استقبال الرسائل من المنصة وتمريرها إلى
OpenClaw. النمط المعتاد هو webhook يتحقق من الطلب
ويرسله عبر معالج الوارد الخاص بقناتك:
ويوزعه عبر معالج الوارد الخاص بقناتك:
```typescript
registerFull(api) {
api.registerHttpRoute({
path: "/acme-chat/webhook",
auth: "plugin", // مصادقة مُدارة بواسطة plugin (تحقق من التواقيع بنفسك)
auth: "plugin", // plugin-managed auth (verify signatures yourself)
handler: async (req, res) => {
const event = parseWebhookPayload(req);
// يقوم معالج الوارد لديك بإرسال الرسالة إلى OpenClaw.
// يعتمد الربط الدقيق على SDK الخاصة بمنصتك —
// راجع مثالًا حقيقيًا في حزمة plugin Microsoft Teams أو Google Chat المضمّنة.
// Your inbound handler dispatches the message to OpenClaw.
// The exact wiring depends on your platform SDK —
// see a real example in the bundled Microsoft Teams or Google Chat plugin package.
await handleAcmeChatInbound(api, event);
res.statusCode = 200;
@ -501,16 +517,16 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
```
<Note>
التعامل مع الرسائل الواردة خاص بالقناة. كل plugin قناة تمتلك
مسار الوارد الخاص بها. انظر إلى plugins القنوات المضمّنة
(مثل حزمة plugin Microsoft Teams أو Google Chat) للاطلاع على أنماط حقيقية.
التعامل مع الرسائل الواردة خاص بالقناة. كل إضافة قناة تملك
مسار الوارد الخاص بها. انظر إلى إضافات القنوات المضمّنة
(مثل حزمة إضافة Microsoft Teams أو Google Chat) للاطلاع على أنماط حقيقية.
</Note>
</Step>
<a id="step-6-test"></a>
<Step title="الاختبار">
اكتب اختبارات موضوعة بجانب الشيفرة في `src/channel.test.ts`:
اكتب اختبارات متجاورة في `src/channel.test.ts`:
```typescript src/channel.test.ts
import { describe, it, expect } from "vitest";
@ -548,7 +564,7 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
pnpm test -- <bundled-plugin-root>/acme-chat/
```
وبالنسبة إلى مساعدات الاختبار المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing).
للاطلاع على مساعدات الاختبار المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing).
</Step>
</Steps>
@ -557,46 +573,46 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على
```
<bundled-plugin-root>/acme-chat/
├── package.json # بيانات تعريف openclaw.channel
├── openclaw.plugin.json # Manifest مع مخطط التهيئة
├── package.json # openclaw.channel metadata
├── openclaw.plugin.json # Manifest with config schema
├── index.ts # defineChannelPluginEntry
├── setup-entry.ts # defineSetupPluginEntry
├── api.ts # التصديرات العامة (اختياري)
├── runtime-api.ts # تصديرات وقت التشغيل الداخلية (اختياري)
├── api.ts # Public exports (optional)
├── runtime-api.ts # Internal runtime exports (optional)
└── src/
├── channel.ts # ChannelPlugin عبر createChatChannelPlugin
├── channel.test.ts # الاختبارات
├── client.ts # عميل API الخاص بالمنصة
└── runtime.ts # مخزن وقت التشغيل (إذا لزم)
├── channel.ts # ChannelPlugin via createChatChannelPlugin
├── channel.test.ts # Tests
├── client.ts # Platform API client
└── runtime.ts # Runtime store (if needed)
```
## موضوعات متقدمة
<CardGroup cols={2}>
<Card title="خيارات الترابط في السلاسل" icon="git-branch" href="/ar/plugins/sdk-entrypoints#registration-mode">
أوضاع رد ثابتة، أو ضمن نطاق الحساب، أو مخصصة
<Card title="خيارات التسلسل" icon="git-branch" href="/ar/plugins/sdk-entrypoints#registration-mode">
أوضاع reply ثابتة أو مقيّدة بالحساب أو مخصصة
</Card>
<Card title="تكامل أداة الرسائل" icon="puzzle" href="/ar/plugins/architecture#channel-plugins-and-the-shared-message-tool">
describeMessageTool واكتشاف الإجراءات
</Card>
<Card title="تحليل الهدف" icon="crosshair" href="/ar/plugins/architecture#channel-target-resolution">
<Card title="حلّ الهدف" icon="crosshair" href="/ar/plugins/architecture#channel-target-resolution">
inferTargetChatType وlooksLikeId وresolveTarget
</Card>
<Card title="مساعدات وقت التشغيل" icon="settings" href="/ar/plugins/sdk-runtime">
TTS وSTT والوسائط وsubagent عبر api.runtime
TTS وSTT والوسائط والوكيل الفرعي عبر api.runtime
</Card>
</CardGroup>
<Note>
لا تزال بعض المداخل المساعدة المضمّنة موجودة لصيانة plugins المضمّنة
والتوافق. وهي ليست النمط الموصى به لـ plugins القنوات الجديدة؛
لا تزال بعض أسطح المساعدات المضمّنة موجودة لصيانة الإضافات المضمّنة
وللتوافق. وهي ليست النمط الموصى به لإضافات القنوات الجديدة؛
فضّل المسارات الفرعية العامة للقناة/الإعداد/الرد/وقت التشغيل من سطح SDK
المشترك ما لم تكن تصون عائلة plugin المضمّنة تلك مباشرة.
المشترك ما لم تكن تصون عائلة تلك الإضافات المضمّنة مباشرة.
</Note>
## الخطوات التالية
- [Provider Plugins](/ar/plugins/sdk-provider-plugins) — إذا كانت plugin الخاصة بك توفر النماذج أيضًا
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — المرجع الكامل لاستيرادات المسارات الفرعية
- [إضافات المزوّد](/ar/plugins/sdk-provider-plugins) — إذا كانت إضافتك توفّر أيضًا نماذج
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع كامل لواردات المسارات الفرعية
- [اختبار SDK](/ar/plugins/sdk-testing) — أدوات الاختبار واختبارات العقود
- [Manifest الخاص بـ plugin](/ar/plugins/manifest) — مخطط manifest الكامل
- [Manifest الإضافة](/ar/plugins/manifest) — مخطط manifest الكامل

514
docs/ar/plugins/sdk-migration.md
View File

@ -1,107 +1,130 @@
---
read_when:
- ترى التحذير OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED
- ترى التحذير OPENCLAW_EXTENSION_API_DEPRECATED
- أنت تحدّث إضافة إلى بنية الإضافات الحديثة
- أنت ترى التحذير OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED
- أنت ترى التحذير OPENCLAW_EXTENSION_API_DEPRECATED
- أنت تقوم بتحديث إضافة إلى معمارية الإضافات الحديثة
- أنت تصون إضافة OpenClaw خارجية
sidebarTitle: Migrate to SDK
summary: الانتقال من طبقة التوافق العكسي القديمة إلى plugin SDK الحديث
summary: الانتقال من طبقة التوافق العكسي القديمة إلى Plugin SDK الحديثة
title: ترحيل Plugin SDK
x-i18n:
generated_at: "2026-04-07T07:20:37Z"
generated_at: "2026-04-08T02:18:21Z"
model: gpt-5.4
provider: openai
source_hash: 3691060e9dc00ca8bee49240a047f0479398691bd14fb96e9204cc9243fdb32c
source_hash: 155a8b14bc345319c8516ebdb8a0ccdea2c5f7fa07dad343442996daee21ecad
source_path: plugins/sdk-migration.md
workflow: 15
---
# ترحيل Plugin SDK
انتقل OpenClaw من طبقة توافق عكسي واسعة إلى بنية إضافات حديثة ذات عمليات
استيراد مركزة وموثقة. إذا كانت إضافتك قد بُنيت قبل البنية الجديدة، فسيساعدك
هذا الدليل على ترحيلها.
انتقل OpenClaw من طبقة توافق عكسي واسعة إلى معمارية إضافات حديثة
ذات عمليات استيراد مركزة وموثقة. إذا كانت إضافتك قد بُنيت قبل
المعمارية الجديدة، فسيساعدك هذا الدليل على الترحيل.
## ما الذي يتغير
كان نظام الإضافات القديم يوفر سطحين مفتوحين على مصراعيهما يتيحان للإضافات
استيراد أي شيء تحتاجه من نقطة دخول واحدة:
كان نظام الإضافات القديم يوفر سطحين واسعين ومفتوحين يتيحان للإضافات استيراد
أي شيء تحتاج إليه من نقطة دخول واحدة:
- **`openclaw/plugin-sdk/compat`** — استيراد واحد يعيد تصدير عشرات من
المساعدات. وقد تم تقديمه لإبقاء الإضافات القديمة المعتمدة على hooks عاملة
أثناء بناء بنية الإضافات الجديدة.
- **`openclaw/extension-api`** — جسر منح الإضافات وصولًا مباشرًا إلى
المساعدات على جانب المضيف مثل مشغّل الوكيل المضمّن.
- **`openclaw/plugin-sdk/compat`** — استيراد واحد يعيد تصدير عشرات
الأدوات المساعدة. وقد تم تقديمه لإبقاء الإضافات الأقدم المعتمدة على الخطافات تعمل بينما
كانت معمارية الإضافات الجديدة قيد الإنشاء.
- **`openclaw/extension-api`** — جسر يمنح الإضافات وصولًا مباشرًا إلى
أدوات جانب المضيف مثل مشغّل الوكيل المضمن.
كلا السطحين الآن **مهملان**. لا يزالان يعملان في وقت التشغيل، لكن يجب ألا
تستخدمهما الإضافات الجديدة، ويجب أن ترحّل الإضافات الحالية قبل أن تزيلهما
النسخة الرئيسية التالية.
كلا السطحين أصبح الآن **مهملًا**. ما زالا يعملان في وقت التشغيل، لكن
يجب ألا تستخدمهما الإضافات الجديدة، وينبغي أن تهاجر الإضافات الحالية قبل أن تزيلهما
الإصدار الرئيسي التالي.
<Warning>
ستتم إزالة طبقة التوافق العكسي في إصدار رئيسي مستقبلي.
الإضافات التي لا تزال تستورد من هذه الأسطح ستتعطل عند حدوث ذلك.
ستُزال طبقة التوافق العكسي في إصدار رئيسي مستقبلي.
وستتعطل الإضافات التي ما تزال تستورد من هذه الأسطح عند حدوث ذلك.
</Warning>
## لماذا تغير هذا
## لماذا تغيّر هذا
تسبب النهج القديم في مشكلات:
- **بدء تشغيل بطيء** — كان استيراد مساعد واحد يحمّل عشرات الوحدات غير
المرتبطة
- **اعتماديات دائرية** — جعلت إعادة التصدير الواسعة من السهل إنشاء دورات
استيراد
- **سطح API غير واضح** — لم تكن هناك طريقة لمعرفة أي التصديرات مستقرة
وأيها داخلية
- **بدء تشغيل بطيء** — كان استيراد أداة مساعدة واحدة يحمّل عشرات الوحدات غير المرتبطة
- **تبعيات دائرية** — جعلت إعادة التصدير الواسعة من السهل إنشاء دورات استيراد
- **سطح API غير واضح** — لم تكن هناك طريقة لمعرفة أي التصديرات مستقرة وأيها داخلية
يصلح plugin SDK الحديث هذا: كل مسار استيراد (`openclaw/plugin-sdk/\<subpath\>`)
هو وحدة صغيرة مكتفية ذاتيًا ذات غرض واضح وعقد موثق.
تصلح Plugin SDK الحديثة هذا: كل مسار استيراد (`openclaw/plugin-sdk/\<subpath\>`)
هو وحدة صغيرة مستقلة بذاتها ذات غرض واضح وعقد موثق.
كما أزيلت أيضًا فواصل الراحة القديمة الخاصة بالمزوّدين للقنوات المضمّنة.
فالاستيرادات مثل `openclaw/plugin-sdk/slack` و`openclaw/plugin-sdk/discord` و
`openclaw/plugin-sdk/signal` و`openclaw/plugin-sdk/whatsapp`،
وفواصل المساعدات ذات العلامات الخاصة بالقنوات، و
`openclaw/plugin-sdk/telegram-core` كانت اختصارات خاصة بالمستودع الأحادي،
وليست عقود إضافات مستقرة. استخدم بدلًا من ذلك مسارات SDK عامة ضيقة. داخل
workspace الإضافات المضمّنة، أبقِ المساعدات المملوكة للمزوّد في `api.ts`
أو `runtime-api.ts` الخاصين بتلك الإضافة.
كما أُزيلت أيضًا طبقات الراحة القديمة لموفري القنوات المجمعة. فالاستيرادات
مثل `openclaw/plugin-sdk/slack` و`openclaw/plugin-sdk/discord`،
و`openclaw/plugin-sdk/signal` و`openclaw/plugin-sdk/whatsapp`،
وطبقات الأدوات المساعدة الموسومة بالقناة، و
`openclaw/plugin-sdk/telegram-core` كانت اختصارات داخلية خاصة بالمستودع الأحادي، وليست
عقود إضافات مستقرة. استخدم بدلًا منها المسارات الفرعية العامة الضيقة في SDK. وداخل
مساحة عمل الإضافات المجمعة، احتفظ بالأدوات المساعدة المملوكة للموفر في
`api.ts` أو `runtime-api.ts` الخاصين بتلك الإضافة.
أمثلة المزوّدات المضمّنة الحالية:
أمثلة موفّرين مجمّعين حالية:
- تحتفظ Anthropic بمساعدات البث الخاصة بـ Claude في الفاصل الخاص بها
`api.ts` / `contract-api.ts`
- تحتفظ OpenAI بمنشئات المزوّد، ومساعدات النموذج الافتراضي، ومنشئات المزوّد
الفوري في `api.ts` الخاص بها
- تحتفظ OpenRouter بمنشئ المزوّد ومساعدات onboarding/config في
`api.ts` الخاص بها
- يحتفظ Anthropic بأدوات مساعدة البث الخاصة بـ Claude في طبقة
`api.ts` / `contract-api.ts` الخاصة به
- يحتفظ OpenAI ببناة الموفر، وأدوات مساعدة النموذج الافتراضي، وبناة
الموفّر الآني في `api.ts` الخاص به
- يحتفظ OpenRouter بباني الموفر وأدوات مساعدة التهيئة/الإعداد في
`api.ts` الخاص به
## كيفية الترحيل
<Steps>
<Step title="راجع سلوك الرجوع الاحتياطي لغلاف Windows">
إذا كانت إضافتك تستخدم `openclaw/plugin-sdk/windows-spawn`، فإن أغلفة
Windows من نوع `.cmd`/`.bat` غير المحلولة تفشل الآن بشكل مغلق ما لم تمرّر
<Step title="ترحيل المعالجات الأصلية للموافقة إلى حقائق القدرات">
تعرض إضافات القنوات القادرة على الموافقة الآن سلوك الموافقة الأصلي من خلال
`approvalCapability.nativeRuntime` بالإضافة إلى سجل سياق وقت التشغيل المشترك.
التغييرات الأساسية:
- استبدل `approvalCapability.handler.loadRuntime(...)` بـ
`approvalCapability.nativeRuntime`
- انقل المصادقة/التسليم الخاصة بالموافقة من البنية القديمة `plugin.auth` /
`plugin.approvals` إلى `approvalCapability`
- تمت إزالة `ChannelPlugin.approvals` من عقد
الإضافات العامة للقنوات؛ انقل حقول التسليم/الأصلية/العرض إلى `approvalCapability`
- يظل `plugin.auth` مخصصًا فقط لتدفقات تسجيل الدخول/الخروج الخاصة بالقناة؛ أما خطافات
مصادقة الموافقة فيه فلم تعد تُقرأ من النواة
- سجّل كائنات وقت التشغيل المملوكة للقناة، مثل العملاء أو الرموز أو تطبيقات
Bolt، عبر `openclaw/plugin-sdk/channel-runtime-context`
- لا ترسل إشعارات إعادة توجيه مملوكة للإضافة من معالجات الموافقة الأصلية؛
فالنواة تمتلك الآن إشعارات "تم التوجيه إلى مكان آخر" المستندة إلى نتائج التسليم الفعلية
- عند تمرير `channelRuntime` إلى `createChannelManager(...)`، وفّر
سطح `createPluginRuntime().channel` حقيقيًا. يتم رفض القوالب الجزئية.
راجع `/plugins/sdk-channel-plugins` للاطلاع على التخطيط الحالي
لقدرة الموافقة.
</Step>
<Step title="مراجعة سلوك الرجوع الاحتياطي لملتفات Windows">
إذا كانت إضافتك تستخدم `openclaw/plugin-sdk/windows-spawn`،
فإن ملفات `.cmd`/`.bat` غير المحلولة في Windows تفشل الآن بشكل مغلق ما لم تمرر
صراحةً `allowShellFallback: true`.
```typescript
// Before
// قبل
const program = applyWindowsSpawnProgramPolicy({ candidate });
// After
// بعد
const program = applyWindowsSpawnProgramPolicy({
candidate,
// Only set this for trusted compatibility callers that intentionally
// accept shell-mediated fallback.
// اضبط هذا فقط للمتصلين المتوافقين الموثوقين الذين يقبلون عمدًا
// الرجوع الاحتياطي عبر الصدفة.
allowShellFallback: true,
});
```
إذا لم يكن المستدعي لديك يعتمد عمدًا على الرجوع الاحتياطي عبر shell، فلا
تضبط `allowShellFallback` وتعامل مع الخطأ المطروح بدلًا من ذلك.
إذا لم يكن المتصل لديك يعتمد عمدًا على الرجوع الاحتياطي عبر الصدفة، فلا تضبط
`allowShellFallback` وتعامل مع الخطأ المطروح بدلًا من ذلك.
</Step>
<Step title="ابحث عن عمليات الاستيراد المهملة">
ابحث في إضافتك عن عمليات استيراد من أي من السطحين المهملين:
<Step title="العثور على الاستيرادات المهملة">
ابحث في إضافتك عن الاستيرادات من أي من السطحين المهملين:
```bash
grep -r "plugin-sdk/compat" my-plugin/
@ -110,38 +133,38 @@ workspace الإضافات المضمّنة، أبقِ المساعدات الم
</Step>
<Step title="استبدلها بعمليات استيراد مركزة">
يطابق كل تصدير من السطح القديم مسار استيراد حديثًا محددًا:
<Step title="الاستبدال باستيرادات مركزة">
يرتبط كل تصدير من السطح القديم بمسار استيراد حديث محدد:
```typescript
// Before (deprecated backwards-compatibility layer)
// قبل (طبقة توافق عكسي مهملة)
import {
createChannelReplyPipeline,
createPluginRuntimeStore,
resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";
// After (modern focused imports)
// بعد (استيرادات حديثة ومركزة)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
```
بالنسبة إلى المساعدات على جانب المضيف، استخدم وقت تشغيل الإضافة المحقون
بدلًا من الاستيراد المباشر:
بالنسبة إلى أدوات جانب المضيف، استخدم وقت تشغيل الإضافة المحقون بدلًا من الاستيراد
المباشر:
```typescript
// Before (deprecated extension-api bridge)
// قبل (جسر extension-api مهمل)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });
// After (injected runtime)
// بعد (وقت تشغيل محقون)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```
ينطبق النمط نفسه على مساعدات الجسر القديمة الأخرى:
ينطبق النمط نفسه على أدوات الجسر القديمة الأخرى:
| الاستيراد القديم | المكافئ الحديث |
| الاستيراد القديم | البديل الحديث |
| --- | --- |
| `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` |
| `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` |
@ -149,11 +172,11 @@ workspace الإضافات المضمّنة، أبقِ المساعدات الم
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
| مساعدات مخزن الجلسات | `api.runtime.agent.session.*` |
| أدوات مساعدة مخزن الجلسات | `api.runtime.agent.session.*` |
</Step>
<Step title="ابنِ واختبر">
<Step title="البناء والاختبار">
```bash
pnpm build
pnpm test -- my-plugin/
@ -161,202 +184,207 @@ workspace الإضافات المضمّنة، أبقِ المساعدات الم
</Step>
</Steps>
## مرجع مسار الاستيراد
## مرجع مسارات الاستيراد
<Accordion title="جدول مسارات الاستيراد الشائعة">
| مسار الاستيراد | الغرض | التصديرات الأساسية |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | مساعد نقطة دخول الإضافة القانوني | `definePluginEntry` |
| `plugin-sdk/core` | إعادة تصدير قديمة جامعة لتعريفات/منشئات إدخال القنوات | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | تصدير مخطط الإعدادات الجذري | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | مساعد إدخال مزوّد واحد | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | تعريفات ومنشئات إدخال قنوات مركزة | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | مساعدات معالج الإعداد المشتركة | مطالبات قائمة السماح، ومنشئات حالة الإعداد |
| `plugin-sdk/setup-runtime` | مساعدات وقت تشغيل الإعداد | محولات تصحيح الإعداد الآمنة للاستيراد، ومساعدات ملاحظات البحث، و`promptResolvedAllowFrom`، و`splitSetupEntries`، ووكلاء الإعداد المفوضون |
| `plugin-sdk/setup-adapter-runtime` | مساعدات محول الإعداد | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | مساعدات أدوات الإعداد | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | مساعدات الحسابات المتعددة | مساعدات قائمة الحسابات/الإعدادات/بوابة الإجراءات |
| `plugin-sdk/account-id` | مساعدات معرّف الحساب | `DEFAULT_ACCOUNT_ID`، وتطبيع معرّف الحساب |
| `plugin-sdk/account-resolution` | مساعدات البحث عن الحساب | مساعدات البحث عن الحساب + الرجوع الاحتياطي الافتراضي |
| `plugin-sdk/account-helpers` | مساعدات حساب ضيقة | مساعدات قائمة الحسابات/إجراءات الحساب |
| `plugin-sdk/channel-setup` | محولات معالج الإعداد | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`، بالإضافة إلى `DEFAULT_ACCOUNT_ID` و`createTopLevelChannelDmPolicy` و`setSetupChannelEnabled` و`splitSetupEntries` |
| `plugin-sdk/channel-pairing` | أساسيات الاقتران عبر DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | توصيل بادئة الرد + الكتابة | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | مصانع محولات الإعدادات | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | منشئات مخطط الإعدادات | أنواع مخطط إعدادات القناة |
| `plugin-sdk/telegram-command-config` | مساعدات إعداد أوامر Telegram | تطبيع أسماء الأوامر، وتشذيب الوصف، والتحقق من التكرار/التعارض |
| `plugin-sdk/channel-policy` | حل سياسات المجموعات/DM | `resolveChannelGroupRequireMention` |
| `plugin-sdk/plugin-entry` | أداة مساعد إدخال الإضافة القياسية | `definePluginEntry` |
| `plugin-sdk/core` | إعادة تصدير جامعة قديمة لتعريفات/بناة إدخال القنوات | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | تصدير مخطط التكوين الجذري | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | أداة مساعد إدخال موفر واحد | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | تعريفات وبناة إدخال القنوات المركزة | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | أدوات مساعدة مشتركة لمعالج الإعداد | مطالبات قائمة السماح، وبناة حالة الإعداد |
| `plugin-sdk/setup-runtime` | أدوات مساعدة وقت تشغيل الإعداد | مهايئات تصحيح الإعداد الآمنة للاستيراد، وأدوات مساعدة ملاحظات البحث، و`promptResolvedAllowFrom` و`splitSetupEntries` ووكلاء الإعداد المفوضون |
| `plugin-sdk/setup-adapter-runtime` | أدوات مساعدة لمهايئات الإعداد | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | أدوات مساعدة لأدوات الإعداد | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | أدوات مساعدة متعددة الحسابات | أدوات مساعدة قائمة الحسابات/التكوين/بوابة الإجراءات |
| `plugin-sdk/account-id` | أدوات مساعدة لمعرّف الحساب | `DEFAULT_ACCOUNT_ID`، وتطبيع معرّف الحساب |
| `plugin-sdk/account-resolution` | أدوات مساعدة للبحث عن الحساب | أدوات مساعدة للبحث عن الحساب + الرجوع الافتراضي |
| `plugin-sdk/account-helpers` | أدوات مساعدة ضيقة للحساب | أدوات مساعدة قائمة الحسابات/إجراءات الحساب |
| `plugin-sdk/channel-setup` | مهايئات معالج الإعداد | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`، بالإضافة إلى `DEFAULT_ACCOUNT_ID` و`createTopLevelChannelDmPolicy` و`setSetupChannelEnabled` و`splitSetupEntries` |
| `plugin-sdk/channel-pairing` | بدائيات إقران الرسائل الخاصة | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | أسلاك بادئة الرد وحالة الكتابة | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | مصانع مهايئات التكوين | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | بناة مخطط التكوين | أنواع مخطط تكوين القناة |
| `plugin-sdk/telegram-command-config` | أدوات مساعدة لتكوين أوامر Telegram | تطبيع أسماء الأوامر، وتشذيب الوصف، والتحقق من التكرار/التعارض |
| `plugin-sdk/channel-policy` | حل سياسات المجموعات/الرسائل الخاصة | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | تتبع حالة الحساب | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | مساعدات الظرف الوارد | مساعدات المسار المشترك + منشئ الظرف |
| `plugin-sdk/inbound-reply-dispatch` | مساعدات الرد الوارد | مساعدات التسجيل والإرسال المشتركة |
| `plugin-sdk/messaging-targets` | تحليل أهداف المراسلة | مساعدات تحليل/مطابقة الأهداف |
| `plugin-sdk/outbound-media` | مساعدات الوسائط الصادرة | تحميل الوسائط الصادرة المشتركة |
| `plugin-sdk/outbound-runtime` | مساعدات وقت التشغيل الصادر | مساعدات الهوية الصادرة/التفويض بالإرسال |
| `plugin-sdk/thread-bindings-runtime` | مساعدات ربط السلاسل | دورة حياة ربط السلاسل ومساعدات المحول |
| `plugin-sdk/agent-media-payload` | مساعدات حمولة الوسائط القديمة | منشئ حمولة وسائط الوكيل لتخطيطات الحقول القديمة |
| `plugin-sdk/channel-runtime` | حشوة توافق مهملة | أدوات وقت تشغيل القنوات القديمة فقط |
| `plugin-sdk/inbound-envelope` | أدوات مساعدة لأغلفة الوارد | أدوات مساعدة مشتركة للمسارات وبناء الأظرف |
| `plugin-sdk/inbound-reply-dispatch` | أدوات مساعدة لردود الوارد | أدوات مساعدة مشتركة للتسجيل والإرسال |
| `plugin-sdk/messaging-targets` | تحليل أهداف المراسلة | أدوات مساعدة لتحليل/مطابقة الأهداف |
| `plugin-sdk/outbound-media` | أدوات مساعدة للوسائط الصادرة | تحميل الوسائط الصادرة المشتركة |
| `plugin-sdk/outbound-runtime` | أدوات مساعدة لوقت التشغيل الصادر | أدوات مساعدة لهوية الإرسال/وكيل الإرسال |
| `plugin-sdk/thread-bindings-runtime` | أدوات مساعدة لربط السلاسل | دورة حياة ربط السلاسل وأدوات المهايئات |
| `plugin-sdk/agent-media-payload` | أدوات مساعدة قديمة لحمولات الوسائط | باني حمولة وسائط الوكيل لتخطيطات الحقول القديمة |
| `plugin-sdk/channel-runtime` | طبقة توافق مهملة | أدوات وقت تشغيل القناة القديمة فقط |
| `plugin-sdk/channel-send-result` | أنواع نتائج الإرسال | أنواع نتائج الرد |
| `plugin-sdk/runtime-store` | تخزين الإضافات الدائم | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | مساعدات وقت تشغيل واسعة | مساعدات وقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت الإضافات |
| `plugin-sdk/runtime-env` | مساعدات بيئة وقت تشغيل ضيقة | مساعدات المسجل/بيئة وقت التشغيل، والمهلة، وإعادة المحاولة، والتراجع |
| `plugin-sdk/plugin-runtime` | مساعدات وقت تشغيل الإضافات المشتركة | مساعدات أوامر/‏hooks/‏http/‏التفاعل للإضافات |
| `plugin-sdk/hook-runtime` | مساعدات مسار hooks | مساعدات مسار webhook/internal hook المشتركة |
| `plugin-sdk/lazy-runtime` | مساعدات وقت التشغيل الكسول | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | مساعدات العمليات | مساعدات التنفيذ المشتركة |
| `plugin-sdk/cli-runtime` | مساعدات وقت تشغيل CLI | تنسيق الأوامر، والانتظار، ومساعدات الإصدار |
| `plugin-sdk/gateway-runtime` | مساعدات Gateway | عميل Gateway ومساعدات تصحيح حالة القناة |
| `plugin-sdk/config-runtime` | مساعدات الإعدادات | مساعدات تحميل/كتابة الإعدادات |
| `plugin-sdk/telegram-command-config` | مساعدات أوامر Telegram | مساعدات تحقق مستقرة للرجوع الاحتياطي لأوامر Telegram عندما يكون سطح عقد Telegram المضمّن غير متاح |
| `plugin-sdk/approval-runtime` | مساعدات مطالبة الموافقة | حمولة موافقة التنفيذ/الإضافة، ومساعدات قدرة/ملف تعريف الموافقة، ومساعدات التوجيه/وقت التشغيل الأصلي للموافقة |
| `plugin-sdk/approval-auth-runtime` | مساعدات مصادقة الموافقة | حلّ المُوافق، ومصادقة الإجراء داخل المحادثة نفسها |
| `plugin-sdk/approval-client-runtime` | مساعدات عميل الموافقة | مساعدات ملف تعريف/تصفية الموافقة الأصلية للتنفيذ |
| `plugin-sdk/approval-delivery-runtime` | مساعدات تسليم الموافقة | محولات قدرة/تسليم الموافقة الأصلية |
| `plugin-sdk/approval-native-runtime` | مساعدات هدف الموافقة | مساعدات ربط هدف/حساب الموافقة الأصلية |
| `plugin-sdk/approval-reply-runtime` | مساعدات رد الموافقة | مساعدات حمولة رد الموافقة للتنفيذ/الإضافة |
| `plugin-sdk/security-runtime` | مساعدات الأمان | مساعدات الثقة المشتركة، وبوابات DM، والمحتوى الخارجي، وجمع الأسرار |
| `plugin-sdk/ssrf-policy` | مساعدات سياسة SSRF | مساعدات قائمة سماح المضيف وسياسة الشبكة الخاصة |
| `plugin-sdk/ssrf-runtime` | مساعدات وقت تشغيل SSRF | مساعدات pinned-dispatcher وguarded fetch وسياسة SSRF |
| `plugin-sdk/collection-runtime` | مساعدات ذاكرة التخزين المؤقت المحدودة | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | مساعدات بوابات التشخيص | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | مساعدات تنسيق الأخطاء | `formatUncaughtError`, `isApprovalNotFoundError`، ومساعدات رسم الأخطاء |
| `plugin-sdk/fetch-runtime` | مساعدات fetch/proxy المغلفة | `resolveFetch`، ومساعدات الوكيل |
| `plugin-sdk/host-runtime` | مساعدات تطبيع المضيف | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | مساعدات إعادة المحاولة | `RetryConfig`, `retryAsync`، ومشغلات السياسات |
| `plugin-sdk/runtime-store` | تخزين دائم للإضافة | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | أدوات مساعدة واسعة لوقت التشغيل | أدوات وقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت الإضافات |
| `plugin-sdk/runtime-env` | أدوات ضيقة لبيئة وقت التشغيل | أدوات التسجيل/بيئة وقت التشغيل، والمهلة، وإعادة المحاولة، والتراجع التدريجي |
| `plugin-sdk/plugin-runtime` | أدوات مساعدة مشتركة لوقت تشغيل الإضافة | أدوات مساعدة لأوامر/خطافات/HTTP/تفاعل الإضافات |
| `plugin-sdk/hook-runtime` | أدوات مساعدة لمسار الخطافات | أدوات مساعدة مشتركة لمسار خطافات الويب/الداخلية |
| `plugin-sdk/lazy-runtime` | أدوات مساعدة لوقت التشغيل الكسول | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | أدوات مساعدة للعمليات | أدوات مساعدة مشتركة للتنفيذ |
| `plugin-sdk/cli-runtime` | أدوات مساعدة لوقت تشغيل CLI | تنسيق الأوامر، والانتظارات، وأدوات مساعدة الإصدارات |
| `plugin-sdk/gateway-runtime` | أدوات مساعدة للبوابة | عميل البوابة وأدوات مساعدة تصحيح حالة القنوات |
| `plugin-sdk/config-runtime` | أدوات مساعدة للتكوين | أدوات مساعدة لتحميل/كتابة التكوين |
| `plugin-sdk/telegram-command-config` | أدوات مساعدة لأوامر Telegram | أدوات مساعدة مستقرة احتياطيًا للتحقق من أوامر Telegram عندما لا يكون سطح عقد Telegram المجمّع متاحًا |
| `plugin-sdk/approval-runtime` | أدوات مساعدة لمطالبات الموافقة | حمولة موافقة التنفيذ/الإضافة، وأدوات مساعدة قدرة/ملف تعريف الموافقة، وأدوات مساعدة التوجيه/وقت التشغيل للموافقة الأصلية |
| `plugin-sdk/approval-auth-runtime` | أدوات مساعدة لمصادقة الموافقة | حل الموافق، ومصادقة الإجراء في الدردشة نفسها |
| `plugin-sdk/approval-client-runtime` | أدوات مساعدة لعميل الموافقة | أدوات مساعدة ملف التعريف/المرشحات لموافقة التنفيذ الأصلية |
| `plugin-sdk/approval-delivery-runtime` | أدوات مساعدة لتسليم الموافقة | مهايئات قدرة/تسليم الموافقة الأصلية |
| `plugin-sdk/approval-gateway-runtime` | أدوات مساعدة لبوابة الموافقة | أداة مساعدة مشتركة لحل بوابة الموافقة |
| `plugin-sdk/approval-handler-adapter-runtime` | أدوات مساعدة لمهايئات الموافقة | أدوات مساعدة خفيفة لتحميل مهايئات الموافقة الأصلية لنقاط إدخال القنوات الساخنة |
| `plugin-sdk/approval-handler-runtime` | أدوات مساعدة لمعالجات الموافقة | أدوات أوسع لوقت تشغيل معالجات الموافقة؛ فَضّل الطبقات الأضيق للمهايئات/البوابة عندما تكفي |
| `plugin-sdk/approval-native-runtime` | أدوات مساعدة لهدف الموافقة | أدوات مساعدة ربط الهدف/الحساب للموافقة الأصلية |
| `plugin-sdk/approval-reply-runtime` | أدوات مساعدة لردود الموافقة | أدوات مساعدة لحمولات رد الموافقة على التنفيذ/الإضافة |
| `plugin-sdk/channel-runtime-context` | أدوات مساعدة لسياق وقت تشغيل القناة | أدوات مساعدة عامة لتسجيل/جلب/مراقبة سياق وقت تشغيل القناة |
| `plugin-sdk/security-runtime` | أدوات مساعدة للأمان | أدوات مساعدة مشتركة للثقة، وبوابات الرسائل الخاصة، والمحتوى الخارجي، وتجميع الأسرار |
| `plugin-sdk/ssrf-policy` | أدوات مساعدة لسياسة SSRF | أدوات مساعدة لقائمة سماح المضيف وسياسة الشبكة الخاصة |
| `plugin-sdk/ssrf-runtime` | أدوات مساعدة لوقت تشغيل SSRF | أدوات مساعدة للمُرسِل المثبت، والجلب المحروس، وسياسات SSRF |
| `plugin-sdk/collection-runtime` | أدوات مساعدة لذاكرة التخزين المحدودة | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | أدوات مساعدة لبوابات التشخيص | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | أدوات مساعدة لتنسيق الأخطاء | `formatUncaughtError`, `isApprovalNotFoundError`، وأدوات رسم الأخطاء |
| `plugin-sdk/fetch-runtime` | أدوات مساعدة للجلب/الوكيل المغلف | `resolveFetch`، وأدوات مساعدة الوكيل |
| `plugin-sdk/host-runtime` | أدوات مساعدة لتطبيع المضيف | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | أدوات مساعدة لإعادة المحاولة | `RetryConfig`, `retryAsync`، ومشغلات السياسات |
| `plugin-sdk/allow-from` | تنسيق قائمة السماح | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | تعيين مدخلات قائمة السماح | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | بوابات الأوامر ومساعدات سطح الأوامر | `resolveControlCommandGate`، ومساعدات تفويض المرسل، ومساعدات سجل الأوامر |
| `plugin-sdk/secret-input` | تحليل مدخلات الأسرار | مساعدات مدخلات الأسرار |
| `plugin-sdk/webhook-ingress` | مساعدات طلبات webhook | أدوات هدف webhook |
| `plugin-sdk/webhook-request-guards` | مساعدات حراسة جسم webhook | مساعدات قراءة/تحديد جسم الطلب |
| `plugin-sdk/reply-runtime` | وقت تشغيل الرد المشترك | الإرسال الوارد، ونبضات القلب، ومخطط الرد، والتقطيع |
| `plugin-sdk/reply-dispatch-runtime` | مساعدات ضيقة لإرسال الرد | مساعدات الإنهاء + إرسال المزوّد |
| `plugin-sdk/reply-history` | مساعدات سجل الرد | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/allowlist-resolution` | ربط مدخلات قائمة السماح | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | بوابات الأوامر وأدوات سطح الأوامر | `resolveControlCommandGate`، وأدوات مساعدة تفويض المرسل، وأدوات سجل الأوامر |
| `plugin-sdk/secret-input` | تحليل المدخلات السرية | أدوات مساعدة للمدخلات السرية |
| `plugin-sdk/webhook-ingress` | أدوات مساعدة لطلبات Webhook | أدوات مساعدة لهدف Webhook |
| `plugin-sdk/webhook-request-guards` | أدوات مساعدة لحراسة طلبات Webhook | أدوات مساعدة لقراءة/تقييد جسم الطلب |
| `plugin-sdk/reply-runtime` | وقت تشغيل الرد المشترك | الإرسال الوارد، والنبض، ومخطط الرد، والتجزئة |
| `plugin-sdk/reply-dispatch-runtime` | أدوات ضيقة لإرسال الرد | الإنهاء + أدوات مساعدة إرسال الموفر |
| `plugin-sdk/reply-history` | أدوات مساعدة لسجل الرد | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | تخطيط مراجع الرد | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | مساعدات تقطيع الرد | مساعدات تقطيع النص/markdown |
| `plugin-sdk/session-store-runtime` | مساعدات مخزن الجلسات | مساعدات مسار المخزن + updated-at |
| `plugin-sdk/state-paths` | مساعدات مسارات الحالة | مساعدات الحالة ودليل OAuth |
| `plugin-sdk/routing` | مساعدات التوجيه/مفتاح الجلسة | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`، ومساعدات تطبيع مفتاح الجلسة |
| `plugin-sdk/status-helpers` | مساعدات حالة القناة | منشئات ملخص حالة القناة/الحساب، وافتراضيات حالة وقت التشغيل، ومساعدات بيانات تعريف المشكلات |
| `plugin-sdk/target-resolver-runtime` | مساعدات محلل الهدف | مساعدات محلل الهدف المشتركة |
| `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع السلاسل | مساعدات تطبيع slug/string |
| `plugin-sdk/request-url` | مساعدات URL الطلب | استخراج URLات نصية من مدخلات شبيهة بالطلبات |
| `plugin-sdk/run-command` | مساعدات الأوامر الموقّتة | مشغّل أوامر موقّت مع stdout/stderr مطبّعين |
| `plugin-sdk/param-readers` | قارئات المعاملات | قارئات معاملات الأدوات/CLI الشائعة |
| `plugin-sdk/tool-send` | استخراج إرسال الأداة | استخراج حقول هدف الإرسال القانونية من وسائط الأداة |
| `plugin-sdk/temp-path` | مساعدات المسارات المؤقتة | مساعدات مسارات التنزيل المؤقتة المشتركة |
| `plugin-sdk/logging-core` | مساعدات التسجيل | مسجل النظام الفرعي ومساعدات التنقيح |
| `plugin-sdk/markdown-table-runtime` | مساعدات جداول Markdown | مساعدات وضع جدول Markdown |
| `plugin-sdk/reply-payload` | أنواع رد الرسائل | أنواع حمولة الرد |
| `plugin-sdk/provider-setup` | مساعدات إعداد مزوّد محلي/مستضاف ذاتيًا منسّقة | مساعدات اكتشاف/إعداد المزوّد المستضاف ذاتيًا |
| `plugin-sdk/self-hosted-provider-setup` | مساعدات مركزة لإعداد مزوّدات مستضافة ذاتيًا متوافقة مع OpenAI | مساعدات اكتشاف/إعداد المزوّد المستضاف ذاتيًا نفسها |
| `plugin-sdk/provider-auth-runtime` | مساعدات المصادقة في وقت تشغيل المزوّد | مساعدات حل مفتاح API في وقت التشغيل |
| `plugin-sdk/provider-auth-api-key` | مساعدات إعداد مفتاح API للمزوّد | مساعدات onboarding/كتابة ملف التعريف لمفتاح API |
| `plugin-sdk/provider-auth-result` | مساعدات نتيجة مصادقة المزوّد | منشئ auth-result قياسي لـ OAuth |
| `plugin-sdk/provider-auth-login` | مساعدات تسجيل الدخول التفاعلي للمزوّد | مساعدات تسجيل الدخول التفاعلي المشتركة |
| `plugin-sdk/provider-env-vars` | مساعدات متغيرات البيئة للمزوّد | مساعدات البحث عن متغيرات بيئة مصادقة المزوّد |
| `plugin-sdk/provider-model-shared` | مساعدات مشتركة للنموذج/إعادة التشغيل للمزوّد | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، ومنشئات سياسة إعادة التشغيل المشتركة، ومساعدات نقاط نهاية المزوّد، ومساعدات تطبيع معرّف النموذج |
| `plugin-sdk/provider-catalog-shared` | مساعدات كتالوج المزوّد المشتركة | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | تصحيحات onboarding للمزوّد | مساعدات إعدادات onboarding |
| `plugin-sdk/provider-http` | مساعدات HTTP للمزوّد | مساعدات HTTP/قدرات نقاط النهاية العامة للمزوّد |
| `plugin-sdk/provider-web-fetch` | مساعدات web-fetch للمزوّد | مساعدات تسجيل/ذاكرة التخزين المؤقت لمزوّد web-fetch |
| `plugin-sdk/provider-web-search-contract` | مساعدات عقد web-search للمزوّد | مساعدات ضيقة لعقد إعدادات/بيانات اعتماد web-search مثل `enablePluginInConfig` و`resolveProviderWebSearchPluginConfig` وضبط/جلب بيانات الاعتماد المحدودة |
| `plugin-sdk/provider-web-search` | مساعدات web-search للمزوّد | مساعدات تسجيل/ذاكرة التخزين المؤقت/وقت التشغيل لمزوّد web-search |
| `plugin-sdk/provider-tools` | مساعدات توافق أدوات/مخططات المزوّد | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف مخطط Gemini + التشخيصات، ومساعدات توافق xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | مساعدات استخدام المزوّد | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`، ومساعدات استخدام مزوّد أخرى |
| `plugin-sdk/provider-stream` | مساعدات أغلفة تدفق المزوّد | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`، وأنواع أغلفة التدفق، ومساعدات الأغلفة المشتركة لـ Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/reply-chunking` | أدوات مساعدة لتجزئة الرد | أدوات مساعدة لتجزئة النص/Markdown |
| `plugin-sdk/session-store-runtime` | أدوات مساعدة لمخزن الجلسات | أدوات مساعدة لمسار المخزن ووقت آخر تحديث |
| `plugin-sdk/state-paths` | أدوات مساعدة لمسارات الحالة | أدوات مساعدة لأدلة الحالة وOAuth |
| `plugin-sdk/routing` | أدوات مساعدة للتوجيه/مفاتيح الجلسة | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`، وأدوات تطبيع مفاتيح الجلسة |
| `plugin-sdk/status-helpers` | أدوات مساعدة لحالة القناة | بناة ملخصات حالة القناة/الحساب، وافتراضات حالة وقت التشغيل، وأدوات بيانات تعريف المشكلات |
| `plugin-sdk/target-resolver-runtime` | أدوات مساعدة لحل الأهداف | أدوات مساعدة مشتركة لحل الأهداف |
| `plugin-sdk/string-normalization-runtime` | أدوات مساعدة لتطبيع السلاسل | أدوات مساعدة لتطبيع الـ slug/السلاسل |
| `plugin-sdk/request-url` | أدوات مساعدة لعناوين URL للطلبات | استخراج عناوين URL النصية من المدخلات الشبيهة بالطلبات |
| `plugin-sdk/run-command` | أدوات مساعدة للأوامر المؤقتة | مشغّل أوامر مؤقت مع stdout/stderr مطبعين |
| `plugin-sdk/param-readers` | قارئات المعاملات | قارئات شائعة لمعاملات الأدوات/CLI |
| `plugin-sdk/tool-send` | استخراج إرسال الأدوات | استخراج حقول هدف الإرسال القياسية من وسائط الأدوات |
| `plugin-sdk/temp-path` | أدوات مساعدة للمسارات المؤقتة | أدوات مساعدة مشتركة لمسارات تنزيل الملفات المؤقتة |
| `plugin-sdk/logging-core` | أدوات مساعدة للتسجيل | مسجل النظام الفرعي وأدوات الإخفاء |
| `plugin-sdk/markdown-table-runtime` | أدوات مساعدة لجداول Markdown | أدوات مساعدة لأنماط جداول Markdown |
| `plugin-sdk/reply-payload` | أنواع ردود الرسائل | أنواع حمولة الرد |
| `plugin-sdk/provider-setup` | أدوات مساعدة منسقة لإعداد الموفّرين المحليين/المستضافين ذاتيًا | أدوات مساعدة لاكتشاف/تكوين الموفّرين المستضافين ذاتيًا |
| `plugin-sdk/self-hosted-provider-setup` | أدوات مركزة لإعداد الموفّرين المستضافين ذاتيًا المتوافقين مع OpenAI | أدوات مساعدة الاكتشاف/التكوين نفسها للموفّرين المستضافين ذاتيًا |
| `plugin-sdk/provider-auth-runtime` | أدوات مساعدة لمصادقة موفر وقت التشغيل | أدوات مساعدة لحل مفاتيح API في وقت التشغيل |
| `plugin-sdk/provider-auth-api-key` | أدوات مساعدة لإعداد مفتاح API للموفر | أدوات مساعدة لتهيئة/كتابة ملفات تعريف مفتاح API |
| `plugin-sdk/provider-auth-result` | أدوات مساعدة لنتائج مصادقة الموفر | باني قياسي لنتائج مصادقة OAuth |
| `plugin-sdk/provider-auth-login` | أدوات مساعدة لتسجيل الدخول التفاعلي للموفر | أدوات مساعدة مشتركة لتسجيل الدخول التفاعلي |
| `plugin-sdk/provider-env-vars` | أدوات مساعدة لمتغيرات بيئة الموفر | أدوات مساعدة للبحث عن متغيرات بيئة مصادقة الموفر |
| `plugin-sdk/provider-model-shared` | أدوات مساعدة مشتركة لنماذج/إعادة تشغيل الموفّر | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، وبناة سياسات الإعادة المشتركة، وأدوات مساعدة لنقاط نهاية الموفّر، وأدوات تطبيع معرّفات النماذج |
| `plugin-sdk/provider-catalog-shared` | أدوات مساعدة مشتركة لفهرس الموفّر | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | تصحيحات تهيئة الموفّر | أدوات مساعدة لتكوين التهيئة |
| `plugin-sdk/provider-http` | أدوات مساعدة HTTP للموفّر | أدوات مساعدة عامة لقدرات HTTP/نقاط النهاية الخاصة بالموفّر |
| `plugin-sdk/provider-web-fetch` | أدوات مساعدة جلب الويب للموفّر | أدوات مساعدة لتسجيل/تخزين موفّر web-fetch |
| `plugin-sdk/provider-web-search-contract` | أدوات مساعدة لعقد بحث الويب للموفّر | أدوات ضيقة لعقد تكوين/اعتماد بحث الويب مثل `enablePluginInConfig` و`resolveProviderWebSearchPluginConfig` وأدوات ضبط/جلب بيانات الاعتماد المقيّدة |
| `plugin-sdk/provider-web-search` | أدوات مساعدة لبحث الويب للموفّر | أدوات مساعدة لتسجيل/تخزين/وقت تشغيل موفّر بحث الويب |
| `plugin-sdk/provider-tools` | أدوات مساعدة لتوافق الأدوات/المخططات للموفّر | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف مخططات Gemini + التشخيصات، وأدوات توافق xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | أدوات مساعدة لاستخدام الموفّر | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`، وأدوات مساعدة أخرى لاستخدام الموفّر |
| `plugin-sdk/provider-stream` | أدوات مساعدة لأغلفة بث الموفّر | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`، وأنواع أغلفة البث، وأدوات مساعدة مشتركة لأغلفة Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/keyed-async-queue` | طابور async مرتب | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | مساعدات الوسائط المشتركة | مساعدات جلب/تحويل/تخزين الوسائط بالإضافة إلى منشئات حمولة الوسائط |
| `plugin-sdk/media-generation-runtime` | مساعدات مشتركة لتوليد الوسائط | مساعدات الرجوع الاحتياطي المشتركة، واختيار المرشحين، ورسائل غياب النموذج لتوليد الصور/الفيديو/الموسيقى |
| `plugin-sdk/media-understanding` | مساعدات فهم الوسائط | أنواع مزوّدات فهم الوسائط بالإضافة إلى تصديرات مساعدات الصور/الصوت المواجهة للمزوّد |
| `plugin-sdk/text-runtime` | مساعدات النص المشتركة | إزالة النص المرئي للمساعد، ومساعدات عرض/تقطيع/جداول markdown، ومساعدات التنقيح، ومساعدات علامات التوجيه، وأدوات النص الآمن، ومساعدات النص/التسجيل ذات الصلة |
| `plugin-sdk/text-chunking` | مساعدات تقطيع النص | مساعد تقطيع النص الصادر |
| `plugin-sdk/speech` | مساعدات Speech | أنواع مزوّدات Speech بالإضافة إلى مساعدات التوجيه، والسجل، والتحقق المواجهة للمزوّد |
| `plugin-sdk/speech-core` | النواة المشتركة لـ Speech | أنواع مزوّدات Speech، والسجل، والتوجيهات، والتطبيع |
| `plugin-sdk/realtime-transcription` | مساعدات النسخ الفوري | أنواع المزوّدات ومساعدات السجل |
| `plugin-sdk/realtime-voice` | مساعدات الصوت الفوري | أنواع المزوّدات ومساعدات السجل |
| `plugin-sdk/image-generation-core` | النواة المشتركة لتوليد الصور | أنواع توليد الصور، والرجوع الاحتياطي، والمصادقة، ومساعدات السجل |
| `plugin-sdk/music-generation` | مساعدات توليد الموسيقى | أنواع المزوّد/الطلب/النتيجة لتوليد الموسيقى |
| `plugin-sdk/music-generation-core` | النواة المشتركة لتوليد الموسيقى | أنواع توليد الموسيقى، ومساعدات الرجوع الاحتياطي، والبحث عن المزوّد، وتحليل model-ref |
| `plugin-sdk/video-generation` | مساعدات توليد الفيديو | أنواع المزوّد/الطلب/النتيجة لتوليد الفيديو |
| `plugin-sdk/video-generation-core` | النواة المشتركة لتوليد الفيديو | أنواع توليد الفيديو، ومساعدات الرجوع الاحتياطي، والبحث عن المزوّد، وتحليل model-ref |
| `plugin-sdk/interactive-runtime` | مساعدات الرد التفاعلي | تطبيع/تقليل حمولة الرد التفاعلي |
| `plugin-sdk/channel-config-primitives` | أساسيات إعدادات القناة | أساسيات ضيقة لمخطط إعدادات القناة |
| `plugin-sdk/channel-config-writes` | مساعدات كتابة إعدادات القناة | مساعدات تفويض كتابة إعدادات القناة |
| `plugin-sdk/channel-plugin-common` | تمهيد القناة المشترك | تصديرات تمهيد الإضافة المشتركة للقنوات |
| `plugin-sdk/channel-status` | مساعدات حالة القناة | مساعدات اللقطة/الملخص المشتركة لحالة القناة |
| `plugin-sdk/allowlist-config-edit` | مساعدات إعدادات قائمة السماح | مساعدات تحرير/قراءة إعدادات قائمة السماح |
| `plugin-sdk/group-access` | مساعدات وصول المجموعات | مساعدات قرارات وصول المجموعات المشتركة |
| `plugin-sdk/direct-dm` | مساعدات Direct-DM | مساعدات المصادقة/الحراسة المشتركة لـ Direct-DM |
| `plugin-sdk/extension-shared` | مساعدات الإضافات المشتركة | أساسيات مساعدات القناة/الحالة السلبية والوكيل المحيطي |
| `plugin-sdk/webhook-targets` | مساعدات أهداف webhook | سجل أهداف webhook ومساعدات تثبيت المسارات |
| `plugin-sdk/webhook-path` | مساعدات مسار webhook | مساعدات تطبيع مسار webhook |
| `plugin-sdk/web-media` | مساعدات وسائط الويب المشتركة | مساعدات تحميل الوسائط البعيدة/المحلية |
| `plugin-sdk/zod` | إعادة تصدير Zod | إعادة تصدير `zod` لمستهلكي plugin SDK |
| `plugin-sdk/memory-core` | مساعدات memory-core المضمّنة | سطح مساعدات مدير الذاكرة/الإعداد/الملفات/CLI |
| `plugin-sdk/memory-core-engine-runtime` | واجهة وقت تشغيل محرك الذاكرة | واجهة وقت تشغيل فهرسة/بحث الذاكرة |
| `plugin-sdk/media-runtime` | أدوات مساعدة مشتركة للوسائط | أدوات مساعدة لجلب/تحويل/تخزين الوسائط بالإضافة إلى بناة حمولات الوسائط |
| `plugin-sdk/media-generation-runtime` | أدوات مساعدة مشتركة لتوليد الوسائط | أدوات مساعدة مشتركة للتحويل الاحتياطي، واختيار المرشحين، ورسائل النماذج المفقودة لتوليد الصور/الفيديو/الموسيقى |
| `plugin-sdk/media-understanding` | أدوات مساعدة لفهم الوسائط | أنواع موفري فهم الوسائط بالإضافة إلى تصديرات أدوات مساعدة الصور/الصوت المواجهة للموفّر |
| `plugin-sdk/text-runtime` | أدوات مساعدة مشتركة للنص | إزالة النص المرئي للمساعد، وأدوات عرض/تجزئة/جداول Markdown، وأدوات الإخفاء، وأدوات وسم التوجيهات، وأدوات النص الآمن، وأدوات ذات صلة بالنص/التسجيل |
| `plugin-sdk/text-chunking` | أدوات مساعدة لتجزئة النص | أداة مساعدة لتجزئة النص الصادر |
| `plugin-sdk/speech` | أدوات مساعدة للكلام | أنواع موفري الكلام بالإضافة إلى تصديرات أدوات مساعدة التوجيهات والسجل والتحقق المواجهة للموفّر |
| `plugin-sdk/speech-core` | نواة كلام مشتركة | أنواع موفري الكلام، والسجل، والتوجيهات، والتطبيع |
| `plugin-sdk/realtime-transcription` | أدوات مساعدة للنسخ الفوري | أنواع الموفّرين وأدوات السجل |
| `plugin-sdk/realtime-voice` | أدوات مساعدة للصوت الفوري | أنواع الموفّرين وأدوات السجل |
| `plugin-sdk/image-generation-core` | نواة مشتركة لتوليد الصور | أنواع توليد الصور، والتحويل الاحتياطي، والمصادقة، وأدوات السجل |
| `plugin-sdk/music-generation` | أدوات مساعدة لتوليد الموسيقى | أنواع موفّر/طلب/نتيجة توليد الموسيقى |
| `plugin-sdk/music-generation-core` | نواة مشتركة لتوليد الموسيقى | أنواع توليد الموسيقى، وأدوات التحويل الاحتياطي، والبحث عن الموفّر، وتحليل مراجع النماذج |
| `plugin-sdk/video-generation` | أدوات مساعدة لتوليد الفيديو | أنواع موفّر/طلب/نتيجة توليد الفيديو |
| `plugin-sdk/video-generation-core` | نواة مشتركة لتوليد الفيديو | أنواع توليد الفيديو، وأدوات التحويل الاحتياطي، والبحث عن الموفّر، وتحليل مراجع النماذج |
| `plugin-sdk/interactive-runtime` | أدوات مساعدة للردود التفاعلية | تطبيع/اختزال حمولات الردود التفاعلية |
| `plugin-sdk/channel-config-primitives` | بدائيات تكوين القنوات | بدائيات ضيقة لمخطط تكوين القناة |
| `plugin-sdk/channel-config-writes` | أدوات مساعدة لكتابة تكوين القنوات | أدوات مساعدة لتفويض كتابة تكوين القنوات |
| `plugin-sdk/channel-plugin-common` | تمهيد مشترك للقنوات | تصديرات تمهيد مشتركة لإضافات القنوات |
| `plugin-sdk/channel-status` | أدوات مساعدة لحالة القنوات | أدوات مساعدة مشتركة لالتقاط/تلخيص حالة القناة |
| `plugin-sdk/allowlist-config-edit` | أدوات مساعدة لتكوين قائمة السماح | أدوات مساعدة لتحرير/قراءة تكوين قائمة السماح |
| `plugin-sdk/group-access` | أدوات مساعدة للوصول إلى المجموعات | أدوات مساعدة مشتركة لاتخاذ قرارات وصول المجموعات |
| `plugin-sdk/direct-dm` | أدوات مساعدة للرسائل الخاصة المباشرة | أدوات مساعدة مشتركة لمصادقة/حراسة الرسائل الخاصة المباشرة |
| `plugin-sdk/extension-shared` | أدوات مساعدة مشتركة للإضافات | بدائيات القنوات/الحالة السلبية والمساعد الوكيل المحيط |
| `plugin-sdk/webhook-targets` | أدوات مساعدة لأهداف Webhook | سجل أهداف Webhook وأدوات تثبيت المسارات |
| `plugin-sdk/webhook-path` | أدوات مساعدة لمسارات Webhook | أدوات مساعدة لتطبيع مسارات Webhook |
| `plugin-sdk/web-media` | أدوات مساعدة مشتركة لوسائط الويب | أدوات مساعدة لتحميل الوسائط البعيدة/المحلية |
| `plugin-sdk/zod` | إعادة تصدير Zod | `zod` معاد تصديره لمستهلكي Plugin SDK |
| `plugin-sdk/memory-core` | أدوات memory-core المجمعة | سطح أدوات مساعدة مدير/تكوين/ملفات/CLI الخاصة بالذاكرة |
| `plugin-sdk/memory-core-engine-runtime` | واجهة وقت تشغيل لمحرك الذاكرة | واجهة وقت تشغيل فهرسة/بحث الذاكرة |
| `plugin-sdk/memory-core-host-engine-foundation` | محرك الأساس لمضيف الذاكرة | تصديرات محرك الأساس لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-engine-embeddings` | محرك embeddings لمضيف الذاكرة | تصديرات محرك embeddings لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-engine-embeddings` | محرك التضمين لمضيف الذاكرة | تصديرات محرك التضمين لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-engine-qmd` | محرك QMD لمضيف الذاكرة | تصديرات محرك QMD لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-engine-storage` | محرك التخزين لمضيف الذاكرة | تصديرات محرك التخزين لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-multimodal` | مساعدات متعددة الوسائط لمضيف الذاكرة | مساعدات متعددة الوسائط لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-query` | مساعدات استعلام مضيف الذاكرة | مساعدات استعلام مضيف الذاكرة |
| `plugin-sdk/memory-core-host-secret` | مساعدات أسرار مضيف الذاكرة | مساعدات أسرار مضيف الذاكرة |
| `plugin-sdk/memory-core-host-events` | مساعدات سجل أحداث مضيف الذاكرة | مساعدات سجل أحداث مضيف الذاكرة |
| `plugin-sdk/memory-core-host-status` | مساعدات حالة مضيف الذاكرة | مساعدات حالة مضيف الذاكرة |
| `plugin-sdk/memory-core-host-runtime-cli` | وقت تشغيل CLI لمضيف الذاكرة | مساعدات وقت تشغيل CLI لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-runtime-core` | وقت تشغيل النواة لمضيف الذاكرة | مساعدات وقت تشغيل النواة لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-runtime-files` | مساعدات ملفات/وقت تشغيل مضيف الذاكرة | مساعدات ملفات/وقت تشغيل مضيف الذاكرة |
| `plugin-sdk/memory-host-core` | اسم مستعار لوقت تشغيل نواة مضيف الذاكرة | اسم مستعار محايد للمورّد لمساعدات وقت تشغيل نواة مضيف الذاكرة |
| `plugin-sdk/memory-host-events` | اسم مستعار لسجل أحداث مضيف الذاكرة | اسم مستعار محايد للمورّد لمساعدات سجل أحداث مضيف الذاكرة |
| `plugin-sdk/memory-host-files` | اسم مستعار لملفات/وقت تشغيل مضيف الذاكرة | اسم مستعار محايد للمورّد لمساعدات ملفات/وقت تشغيل مضيف الذاكرة |
| `plugin-sdk/memory-host-markdown` | مساعدات markdown المُدارة | مساعدات managed-markdown المشتركة للإضافات المجاورة للذاكرة |
| `plugin-sdk/memory-core-host-multimodal` | أدوات مساعدة متعددة الوسائط لمضيف الذاكرة | أدوات مساعدة متعددة الوسائط لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-query` | أدوات مساعدة للاستعلام في مضيف الذاكرة | أدوات مساعدة للاستعلام في مضيف الذاكرة |
| `plugin-sdk/memory-core-host-secret` | أدوات مساعدة للأسرار في مضيف الذاكرة | أدوات مساعدة للأسرار في مضيف الذاكرة |
| `plugin-sdk/memory-core-host-events` | أدوات مساعدة لسجل أحداث مضيف الذاكرة | أدوات مساعدة لسجل أحداث مضيف الذاكرة |
| `plugin-sdk/memory-core-host-status` | أدوات مساعدة لحالة مضيف الذاكرة | أدوات مساعدة لحالة مضيف الذاكرة |
| `plugin-sdk/memory-core-host-runtime-cli` | وقت تشغيل CLI لمضيف الذاكرة | أدوات مساعدة وقت تشغيل CLI لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-runtime-core` | وقت تشغيل النواة لمضيف الذاكرة | أدوات مساعدة وقت تشغيل النواة لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-runtime-files` | أدوات مساعدة للملفات/وقت التشغيل لمضيف الذاكرة | أدوات مساعدة للملفات/وقت التشغيل لمضيف الذاكرة |
| `plugin-sdk/memory-host-core` | اسم مستعار لوقت تشغيل نواة مضيف الذاكرة | اسم مستعار محايد للمورّد لأدوات وقت تشغيل نواة مضيف الذاكرة |
| `plugin-sdk/memory-host-events` | اسم مستعار لسجل أحداث مضيف الذاكرة | اسم مستعار محايد للمورّد لأدوات سجل أحداث مضيف الذاكرة |
| `plugin-sdk/memory-host-files` | اسم مستعار لملفات/وقت تشغيل مضيف الذاكرة | اسم مستعار محايد للمورّد لأدوات ملفات/وقت تشغيل مضيف الذاكرة |
| `plugin-sdk/memory-host-markdown` | أدوات مساعدة لـ markdown المُدار | أدوات مساعدة مشتركة لـ markdown المُدار للإضافات المجاورة للذاكرة |
| `plugin-sdk/memory-host-search` | واجهة بحث الذاكرة النشطة | واجهة وقت تشغيل كسولة لمدير بحث الذاكرة النشطة |
| `plugin-sdk/memory-host-status` | اسم مستعار لحالة مضيف الذاكرة | اسم مستعار محايد للمورّد لمساعدات حالة مضيف الذاكرة |
| `plugin-sdk/memory-lancedb` | مساعدات memory-lancedb المضمّنة | سطح مساعدات memory-lancedb |
| `plugin-sdk/testing` | أدوات الاختبار | مساعدات ومحاكيات الاختبار |
| `plugin-sdk/memory-host-status` | اسم مستعار لحالة مضيف الذاكرة | اسم مستعار محايد للمورّد لأدوات حالة مضيف الذاكرة |
| `plugin-sdk/memory-lancedb` | أدوات memory-lancedb المجمعة | سطح أدوات مساعدة memory-lancedb |
| `plugin-sdk/testing` | أدوات الاختبار | أدوات الاختبار والمحاكاة |
</Accordion>
هذا الجدول هو عمدًا المجموعة الفرعية الشائعة للترحيل، وليس سطح SDK الكامل.
القائمة الكاملة التي تضم أكثر من 200 نقطة دخول موجودة في
هذا الجدول هو عمدًا مجموعة الترحيل الشائعة، وليس سطح SDK الكامل.
وتوجد القائمة الكاملة التي تضم أكثر من 200 نقطة إدخال في
`scripts/lib/plugin-sdk-entrypoints.json`.
ولا تزال تلك القائمة تتضمن بعض فواصل مساعدات الإضافات المضمّنة مثل
`plugin-sdk/feishu` و`plugin-sdk/feishu-setup` و`plugin-sdk/zalo` و
`plugin-sdk/zalo-setup` و`plugin-sdk/matrix*`. وتظل هذه مُصدّرة من أجل
صيانة الإضافات المضمّنة والتوافق، لكنها حُذفت عمدًا من جدول الترحيل الشائع
وليست الهدف الموصى به لشيفرة الإضافات الجديدة.
ما تزال تلك القائمة تتضمن بعض طبقات أدوات المساعدة الخاصة بالإضافات المجمعة مثل
`plugin-sdk/feishu` و`plugin-sdk/feishu-setup` و`plugin-sdk/zalo`،
و`plugin-sdk/zalo-setup` و`plugin-sdk/matrix*`. وما تزال هذه المداخل مُصدَّرة
لصيانة الإضافات المجمعة والتوافق، لكنها أُزيلت عمدًا من
جدول الترحيل الشائع وليست الهدف الموصى به
لكود الإضافات الجديد.
تنطبق القاعدة نفسها على عائلات المساعدات المضمّنة الأخرى مثل:
تنطبق القاعدة نفسها على عائلات الأدوات المجمعة الأخرى مثل:
- مساعدات دعم المتصفح: `plugin-sdk/browser-cdp` و`plugin-sdk/browser-config-runtime` و`plugin-sdk/browser-config-support` و`plugin-sdk/browser-control-auth` و`plugin-sdk/browser-node-runtime` و`plugin-sdk/browser-profiles` و`plugin-sdk/browser-security-runtime` و`plugin-sdk/browser-setup-tools` و`plugin-sdk/browser-support`
- Matrix: `plugin-sdk/matrix*`
- LINE: `plugin-sdk/line*`
- IRC: `plugin-sdk/irc*`
- أسطح المساعدات/الإضافات المضمّنة مثل `plugin-sdk/googlechat`،
و`plugin-sdk/zalouser`، و`plugin-sdk/bluebubbles*`،
و`plugin-sdk/mattermost*`، و`plugin-sdk/msteams`،
و`plugin-sdk/nextcloud-talk`، و`plugin-sdk/nostr`، و`plugin-sdk/tlon`،
و`plugin-sdk/twitch`،
و`plugin-sdk/github-copilot-login`، و`plugin-sdk/github-copilot-token`،
و`plugin-sdk/diagnostics-otel`، و`plugin-sdk/diffs`، و`plugin-sdk/llm-task`،
و`plugin-sdk/thread-ownership`، و`plugin-sdk/voice-call`
- أدوات دعم المتصفح: `plugin-sdk/browser-cdp` و`plugin-sdk/browser-config-runtime` و`plugin-sdk/browser-config-support` و`plugin-sdk/browser-control-auth` و`plugin-sdk/browser-node-runtime` و`plugin-sdk/browser-profiles` و`plugin-sdk/browser-security-runtime` و`plugin-sdk/browser-setup-tools` و`plugin-sdk/browser-support`
- Matrix: ‏`plugin-sdk/matrix*`
- LINE: ‏`plugin-sdk/line*`
- IRC: ‏`plugin-sdk/irc*`
- أسطح الأدوات/الإضافات المجمعة مثل `plugin-sdk/googlechat`،
و`plugin-sdk/zalouser` و`plugin-sdk/bluebubbles*`,
و`plugin-sdk/mattermost*` و`plugin-sdk/msteams`,
و`plugin-sdk/nextcloud-talk` و`plugin-sdk/nostr` و`plugin-sdk/tlon`,
و`plugin-sdk/twitch`,
و`plugin-sdk/github-copilot-login` و`plugin-sdk/github-copilot-token`,
و`plugin-sdk/diagnostics-otel` و`plugin-sdk/diffs` و`plugin-sdk/llm-task`,
و`plugin-sdk/thread-ownership` و`plugin-sdk/voice-call`
يكشف `plugin-sdk/github-copilot-token` حاليًا عن سطح مساعدات الرموز الضيق
`DEFAULT_COPILOT_API_BASE_URL`،
يكشف `plugin-sdk/github-copilot-token` حاليًا عن
سطح أدوات الرموز الضيق `DEFAULT_COPILOT_API_BASE_URL`،
و`deriveCopilotApiBaseUrlFromToken`، و`resolveCopilotApiToken`.
استخدم أضيق استيراد يطابق المهمة. إذا لم تتمكن من العثور على تصدير،
استخدم أضيق استيراد يطابق المهمة. وإذا لم تتمكن من العثور على تصدير،
فتحقق من المصدر في `src/plugin-sdk/` أو اسأل في Discord.
## الجدول الزمني للإزالة
| متى | ما الذي يحدث |
| ---------------------- | ----------------------------------------------------------------- |
| **الآن** | تصدر الأسطح المهملة تحذيرات في وقت التشغيل |
| **الإصدار الرئيسي التالي** | ستُزال الأسطح المهملة؛ وستفشل الإضافات التي لا تزال تستخدمها |
| متى | ما الذي يحدث |
| ---------------------- | ----------------------------------------------------------------------- |
| **الآن** | تُصدر الأسطح المهملة تحذيرات في وقت التشغيل |
| **الإصدار الرئيسي التالي** | ستُزال الأسطح المهملة؛ وستفشل الإضافات التي ما تزال تستخدمها |
تم ترحيل كل الإضافات الأساسية بالفعل. يجب أن ترحّل الإضافات الخارجية قبل
الإصدار الرئيسي التالي.
لقد تم بالفعل ترحيل جميع الإضافات الأساسية. ويجب أن تهاجر الإضافات الخارجية
قبل الإصدار الرئيسي التالي.
## كتم التحذيرات مؤقتًا
@ -371,9 +399,9 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
## ذو صلة
- [البدء](/ar/plugins/building-plugins) — أنشئ أول إضافة لك
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع كامل لعمليات الاستيراد عبر المسارات الفرعية
- [إضافات القنوات](/ar/plugins/sdk-channel-plugins) — بناء إضافات القنوات
- [إضافات المزوّدات](/ar/plugins/sdk-provider-plugins) — بناء إضافات المزوّدات
- [الآليات الداخلية للإضافات](/ar/plugins/architecture) — نظرة معمقة على البنية
- [بيان الإضافة](/ar/plugins/manifest) — مرجع مخطط البيان
- [Getting Started](/ar/plugins/building-plugins) — أنشئ إضافتك الأولى
- [SDK Overview](/ar/plugins/sdk-overview) — مرجع كامل لاستيراد المسارات الفرعية
- [Channel Plugins](/ar/plugins/sdk-channel-plugins) — بناء إضافات القنوات
- [Provider Plugins](/ar/plugins/sdk-provider-plugins) — بناء إضافات الموفّرين
- [Plugin Internals](/ar/plugins/architecture) — تعمق في المعمارية
- [Plugin Manifest](/ar/plugins/manifest) — مرجع مخطط البيان

603
docs/ar/plugins/sdk-overview.md
View File

@ -1,33 +1,33 @@
---
read_when:
- تحتاج إلى معرفة أي مسار فرعي من SDK يجب الاستيراد منه
- تحتاج إلى معرفة المسار الفرعي في SDK الذي يجب الاستيراد منه
- تريد مرجعًا لجميع أساليب التسجيل على OpenClawPluginApi
- تبحث عن export محدد في SDK
- تبحث عن تصدير محدد في SDK
sidebarTitle: SDK Overview
summary: خريطة الاستيراد، ومرجع API التسجيل، وبنية SDK
summary: خريطة الاستيراد، ومرجع API للتسجيل، وبنية SDK
title: نظرة عامة على Plugin SDK
x-i18n:
generated_at: "2026-04-07T07:21:02Z"
generated_at: "2026-04-08T02:18:17Z"
model: gpt-5.4
provider: openai
source_hash: 533bc3027ed8ad50b706518a4f58e75f6ef717fc8b36f242e928cae54d20985f
source_hash: c5a41bd82d165dfbb7fbd6e4528cf322e9133a51efe55fa8518a7a0a626d9d30
source_path: plugins/sdk-overview.md
workflow: 15
---
# نظرة عامة على Plugin SDK
يُعد plugin SDK العقد typed بين plugins وcore. هذه الصفحة هي
المرجع الخاص بـ **ما يجب استيراده** و**ما الذي يمكنك تسجيله**.
Plugin SDK هو العقد المطبّع بين الإضافات والنواة. هذه الصفحة هي
المرجع الخاص بـ **ما الذي يجب استيراده** و**ما الذي يمكنك تسجيله**.
<Tip>
**هل تبحث عن دليل عملي؟**
- أول plugin؟ ابدأ من [البدء](/ar/plugins/building-plugins)
- Channel plugin؟ راجع [Channel Plugins](/ar/plugins/sdk-channel-plugins)
- Provider plugin؟ راجع [Provider Plugins](/ar/plugins/sdk-provider-plugins)
- أول إضافة؟ ابدأ من [البدء](/ar/plugins/building-plugins)
- إضافة قناة؟ راجع [إضافات القنوات](/ar/plugins/sdk-channel-plugins)
- إضافة موفّر؟ راجع [إضافات الموفّرات](/ar/plugins/sdk-provider-plugins)
</Tip>
## اصطلاحات الاستيراد
## اصطلاح الاستيراد
استورد دائمًا من مسار فرعي محدد:
@ -36,39 +36,39 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
كل مسار فرعي عبارة عن وحدة صغيرة مستقلة بذاتها. وهذا يُبقي بدء التشغيل سريعًا
ويمنع مشكلات التبعيات الدائرية. بالنسبة إلى مساعدات الإدخال/البناء الخاصة بالقنوات،
فضّل `openclaw/plugin-sdk/channel-core`; وأبقِ `openclaw/plugin-sdk/core` للسطح
الأوسع الشامل والمساعدات المشتركة مثل
كل مسار فرعي هو وحدة صغيرة ومستقلة بذاتها. يحافظ هذا على سرعة بدء التشغيل
ويمنع مشكلات التبعيات الدائرية. بالنسبة إلى أدوات الإدخال/البناء الخاصة بالقنوات،
فضّل `openclaw/plugin-sdk/channel-core`؛ واحتفظ بـ `openclaw/plugin-sdk/core` من أجل
السطح الأشمل والمظلّي والمساعدات المشتركة مثل
`buildChannelConfigSchema`.
لا تضف ولا تعتمد على نقاط ربط تسهيلية مسماة باسم المزود مثل
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp` أو
نقاط ربط مساعدة تحمل العلامة الخاصة بالقناة. يجب أن تؤلف plugins المضمنة
المسارات الفرعية العامة من SDK داخل ملفات `api.ts` أو `runtime-api.ts` الخاصة بها، ويجب على core
إما استخدام هذه الملفات المحلية الخاصة بالـ plugin أو إضافة عقد SDK عام ضيق
عندما تكون الحاجة فعلًا عابرة للقنوات.
لا تضف ولا تعتمد على مسارات تسهيلية مسماة على اسم الموفّر مثل
`openclaw/plugin-sdk/slack` أو `openclaw/plugin-sdk/discord`،
أو `openclaw/plugin-sdk/signal` أو `openclaw/plugin-sdk/whatsapp`، أو
مسارات مساعدات تحمل علامة قناة محددة. يجب على الإضافات المضمّنة أن تركّب
مسارات SDK الفرعية العامة داخل ملفات `api.ts` أو `runtime-api.ts` الخاصة بها، ويجب على النواة
إما استخدام هذه الملفات المحلية للإضافة أو إضافة عقد SDK عام ضيّق
عندما تكون الحاجة عابرة للقنوات فعلًا.
لا تزال خريطة export المولدة تحتوي على مجموعة صغيرة من
نقاط الربط المساعدة للـ plugins المضمنة مثل `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, و`plugin-sdk/matrix*`. وهذه
المسارات الفرعية موجودة فقط لصيانة plugins المضمنة ولأغراض التوافق؛ وهي
مستبعدة عمدًا من الجدول الشائع أدناه وليست مسار الاستيراد الموصى به
للـ plugins الخارجية الجديدة.
لا تزال خريطة التصدير المولدة تحتوي على مجموعة صغيرة من
مسارات المساعدات الخاصة بالإضافات المضمّنة مثل `plugin-sdk/feishu` و`plugin-sdk/feishu-setup`،
و`plugin-sdk/zalo` و`plugin-sdk/zalo-setup` و`plugin-sdk/matrix*`. هذه
المسارات الفرعية موجودة فقط لصيانة الإضافات المضمّنة والتوافق؛ وهي
مستبعدة عمدًا من الجدول الشائع أدناه وليست مسار الاستيراد
الموصى به للإضافات الخارجية الجديدة.
## مرجع المسارات الفرعية
أكثر المسارات الفرعية استخدامًا، مجمعة حسب الغرض. والقائمة الكاملة المولدة التي تضم
أكثر المسارات الفرعية استخدامًا، مجمّعة حسب الغرض. القائمة الكاملة المولدة والتي تضم
أكثر من 200 مسار فرعي موجودة في `scripts/lib/plugin-sdk-entrypoints.json`.
لا تزال مسارات المساعدة المحجوزة الخاصة بالـ plugins المضمنة تظهر في تلك القائمة المولدة.
تعامل معها على أنها أسطح تنفيذية/توافقية ما لم تروّج صفحة توثيق
لأحدها صراحةً على أنه عام.
لا تزال المسارات الفرعية المحجوزة الخاصة بمساعدات الإضافات المضمّنة تظهر في تلك القائمة المولدة.
تعامل مع هذه المسارات على أنها تفاصيل تنفيذ/أسطح توافق إلا إذا
روّجت لها صفحة توثيق صراحة على أنها عامة.
### إدخال plugin
### إدخال الإضافة
| المسار الفرعي | أهم exports |
| المسار الفرعي | الصادرات الأساسية |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
@ -77,281 +77,286 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
<AccordionGroup>
<Accordion title="المسارات الفرعية للقنوات">
| المسار الفرعي | أهم exports |
| المسار الفرعي | الصادرات الأساسية |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | export مخطط Zod الجذر لـ `openclaw.json` ‏(`OpenClawSchema`) |
| `plugin-sdk/config-schema` | تصدير مخطط Zod الجذر لـ `openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`، بالإضافة إلى `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | مساعدات wizard المشتركة للإعداد، ومطالبات allowlist، وبناة حالة الإعداد |
| `plugin-sdk/setup` | مساعدات معالج الإعداد المشتركة، ومطالبات قائمة السماح، وبناة حالة الإعداد |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | مساعدات إعدادات/بوابة إجراءات متعددة الحسابات، ومساعدات fallback الخاصة بالحساب الافتراضي |
| `plugin-sdk/account-core` | مساعدات تكوين/بوابة إجراء الحسابات المتعددة ومساعدات الرجوع إلى الحساب الافتراضي |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`، ومساعدات تطبيع معرّف الحساب |
| `plugin-sdk/account-resolution` | مساعدات البحث عن الحساب + fallback الافتراضي |
| `plugin-sdk/account-helpers` | مساعدات ضيقة لقوائم الحسابات/إجراءات الحساب |
| `plugin-sdk/account-resolution` | مساعدات البحث عن الحساب + الرجوع إلى الافتراضي |
| `plugin-sdk/account-helpers` | مساعدات ضيقة لقائمة الحسابات/إجراءات الحساب |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | أنواع مخطط إعدادات القناة |
| `plugin-sdk/telegram-command-config` | مساعدات تطبيع/تحقق أوامر Telegram المخصصة مع fallback لعقد مجمّع |
| `plugin-sdk/channel-config-schema` | أنواع مخطط تكوين القناة |
| `plugin-sdk/telegram-command-config` | مساعدات تطبيع/تحقق للأوامر المخصصة في Telegram مع رجوع إلى العقدة المضمّنة |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | مساعدات مشتركة لبناء route + envelope للوارد |
| `plugin-sdk/inbound-reply-dispatch` | مساعدات مشتركة لتسجيل وإرسال الردود الواردة |
| `plugin-sdk/inbound-envelope` | مساعدات بناء المسار والمغلف المشترك للرسائل الواردة |
| `plugin-sdk/inbound-reply-dispatch` | مساعدات التسجيل والإرسال المشتركة للرسائل الواردة |
| `plugin-sdk/messaging-targets` | مساعدات تحليل/مطابقة الأهداف |
| `plugin-sdk/outbound-media` | مساعدات مشتركة لتحميل الوسائط الصادرة |
| `plugin-sdk/outbound-runtime` | مساعدات هوية الصادر/تفويض الإرسال |
| `plugin-sdk/thread-bindings-runtime` | مساعدات دورة حياة thread-binding وadapter |
| `plugin-sdk/agent-media-payload` | باني قديم لحمولة وسائط الوكيل |
| `plugin-sdk/conversation-runtime` | مساعدات الربط بالمحادثة/الخيط، والاقتران، والربط المُعد |
| `plugin-sdk/runtime-config-snapshot` | مساعد لقطة إعدادات وقت التشغيل |
| `plugin-sdk/runtime-group-policy` | مساعدات تحليل group-policy في وقت التشغيل |
| `plugin-sdk/channel-status` | مساعدات مشتركة للقطات/ملخصات حالة القناة |
| `plugin-sdk/channel-config-primitives` | بدائيات ضيقة لمخطط إعدادات القناة |
| `plugin-sdk/channel-config-writes` | مساعدات تفويض كتابة إعدادات القناة |
| `plugin-sdk/channel-plugin-common` | exports تمهيدية مشتركة لـ Channel plugin |
| `plugin-sdk/allowlist-config-edit` | مساعدات قراءة/تحرير إعدادات allowlist |
| `plugin-sdk/group-access` | مساعدات مشتركة لقرارات الوصول إلى المجموعات |
| `plugin-sdk/direct-dm` | مساعدات مشتركة لمصادقة/حراسة الرسائل الخاصة المباشرة |
| `plugin-sdk/interactive-runtime` | مساعدات تطبيع/تقليص حمولة الرد التفاعلي |
| `plugin-sdk/channel-inbound` | مساعدات إزالة ارتداد الوارد، ومطابقة الإشارات، وسياسة الإشارة، وenvelope |
| `plugin-sdk/channel-send-result` | أنواع نتائج الرد |
| `plugin-sdk/outbound-media` | مساعدات تحميل الوسائط الصادرة المشتركة |
| `plugin-sdk/outbound-runtime` | مساعدات هوية/تفويض الإرسال الصادر |
| `plugin-sdk/thread-bindings-runtime` | مساعدات دورة حياة وموائمات ربط الخيوط |
| `plugin-sdk/agent-media-payload` | باني حمولة وسائط الوكيل القديم |
| `plugin-sdk/conversation-runtime` | مساعدات المحادثة/ربط الخيوط/الإقران/الربط المهيأ |
| `plugin-sdk/runtime-config-snapshot` | مساعد أخذ لقطة من تكوين وقت التشغيل |
| `plugin-sdk/runtime-group-policy` | مساعدات حل سياسة المجموعة في وقت التشغيل |
| `plugin-sdk/channel-status` | مساعدات اللقطة/الملخص المشتركة لحالة القناة |
| `plugin-sdk/channel-config-primitives` | بدائيات ضيقة لمخطط تكوين القناة |
| `plugin-sdk/channel-config-writes` | مساعدات تفويض كتابة تكوين القناة |
| `plugin-sdk/channel-plugin-common` | صادرات تمهيدية مشتركة لإضافات القنوات |
| `plugin-sdk/allowlist-config-edit` | مساعدات قراءة/تحرير تكوين قائمة السماح |
| `plugin-sdk/group-access` | مساعدات مشتركة لاتخاذ قرار وصول المجموعة |
| `plugin-sdk/direct-dm` | مساعدات مشتركة لمصادقة/حماية الرسائل المباشرة المباشرة |
| `plugin-sdk/interactive-runtime` | مساعدات تطبيع/اختزال حمولة الرد التفاعلي |
| `plugin-sdk/channel-inbound` | مساعدات إزالة الارتداد، ومطابقة الذكر، وسياسة الذكر للرسائل الواردة، ومساعدات المغلف |
| `plugin-sdk/channel-send-result` | أنواع نتيجة الرد |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
| `plugin-sdk/channel-targets` | مساعدات تحليل/مطابقة الأهداف |
| `plugin-sdk/channel-contract` | أنواع عقد القناة |
| `plugin-sdk/channel-feedback` | توصيل feedback/reaction |
| `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لعقود الأسرار مثل `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` وأنواع أهداف الأسرار |
| `plugin-sdk/channel-feedback` | أسلاك التغذية الراجعة/التفاعلات |
| `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لعقد الأسرار مثل `collectSimpleChannelFieldAssignments` و`getChannelSurface` و`pushAssignment` وأنواع أهداف الأسرار |
</Accordion>
<Accordion title="المسارات الفرعية للمزودات">
| المسار الفرعي | أهم exports |
<Accordion title="المسارات الفرعية للموفّرات">
| المسار الفرعي | الصادرات الأساسية |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | مساعدات إعداد منتقاة للمزودات المحلية/المستضافة ذاتيًا |
| `plugin-sdk/self-hosted-provider-setup` | مساعدات إعداد مركزة لمزودات OpenAI-compatible المستضافة ذاتيًا |
| `plugin-sdk/cli-backend` | قيم افتراضية لـ CLI backend + ثوابت watchdog |
| `plugin-sdk/provider-auth-runtime` | مساعدات وقت التشغيل لتحليل API key الخاصة بـ Provider plugins |
| `plugin-sdk/provider-auth-api-key` | مساعدات onboarding/كتابة profile لمفتاح API مثل `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | باني auth-result قياسي لـ OAuth |
| `plugin-sdk/provider-auth-login` | مساعدات تسجيل دخول تفاعلية مشتركة لـ Provider plugins |
| `plugin-sdk/provider-env-vars` | مساعدات البحث عن متغيرات البيئة لمصادقة المزود |
| `plugin-sdk/provider-setup` | مساعدات منسقة لإعداد الموفّرات المحلية/المستضافة ذاتيًا |
| `plugin-sdk/self-hosted-provider-setup` | مساعدات إعداد مركزة لموفّرات مستضافة ذاتيًا متوافقة مع OpenAI |
| `plugin-sdk/cli-backend` | القيم الافتراضية للواجهة الخلفية لـ CLI + ثوابت المراقبة |
| `plugin-sdk/provider-auth-runtime` | مساعدات حل مفاتيح API وقت التشغيل لإضافات الموفّرات |
| `plugin-sdk/provider-auth-api-key` | مساعدات الإلحاق/الكتابة في الملف الشخصي لمفتاح API مثل `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | باني نتيجة مصادقة OAuth القياسي |
| `plugin-sdk/provider-auth-login` | مساعدات تسجيل الدخول التفاعلية المشتركة لإضافات الموفّرات |
| `plugin-sdk/provider-env-vars` | مساعدات البحث عن متغيرات بيئة مصادقة الموفّر |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، وبناة replay-policy المشتركون، ومساعدات endpoint للمزود، ومساعدات تطبيع model-id مثل `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، وبناة سياسة الإعادة المشتركة، ومساعدات نقطة نهاية الموفّر، ومساعدات تطبيع معرّف النموذج مثل `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | مساعدات عامة لقدرات HTTP/endpoint الخاصة بالمزود |
| `plugin-sdk/provider-web-fetch` | مساعدات التسجيل/cache لمزود web-fetch |
| `plugin-sdk/provider-web-search-contract` | مساعدات ضيقة لعقود إعدادات/بيانات اعتماد web-search مثل `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`، ومعينات set/get لبيانات اعتماد محددة النطاق |
| `plugin-sdk/provider-web-search` | مساعدات التسجيل/cache/وقت التشغيل لمزود web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف/تشخيص مخطط Gemini، ومساعدات توافق xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` وما شابه |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`، وأنواع stream wrapper، ومساعدات wrappers المشتركة لـ Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-onboard` | مساعدات تعديل إعدادات onboarding |
| `plugin-sdk/global-singleton` | مساعدات singleton/map/cache محلية للعملية |
| `plugin-sdk/provider-http` | مساعدات عامة لقدرات HTTP/نقطة النهاية الخاصة بالموفّر |
| `plugin-sdk/provider-web-fetch-contract` | مساعدات ضيقة لعقود تكوين/اختيار web-fetch مثل `enablePluginInConfig` و`WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | مساعدات تسجيل/ذاكرة التخزين المؤقت لموفّر web-fetch |
| `plugin-sdk/provider-web-search-contract` | مساعدات ضيقة لعقود تكوين/بيانات اعتماد web-search مثل `enablePluginInConfig` و`resolveProviderWebSearchPluginConfig` وضبط/جلب بيانات الاعتماد ذات النطاق |
| `plugin-sdk/provider-web-search` | مساعدات التسجيل/الذاكرة المؤقتة/وقت التشغيل لموفّر web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف مخطط Gemini + التشخيصات، ومساعدات التوافق مع xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` وما شابهها |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`، وأنواع مغطيات البث، ومساعدات المغطيات المشتركة لـ Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-onboard` | مساعدات ترقيع تكوين الإعداد الأولي |
| `plugin-sdk/global-singleton` | مساعدات القيم المفردة/الخرائط/الذاكرات المؤقتة المحلية للعملية |
</Accordion>
<Accordion title="المسارات الفرعية للمصادقة والأمان">
| المسار الفرعي | أهم exports |
| المسار الفرعي | الصادرات الأساسية |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`، ومساعدات سجل الأوامر، ومساعدات تفويض المرسل |
| `plugin-sdk/approval-auth-runtime` | مساعدات تحليل approver ومصادقة الإجراء في نفس الدردشة |
| `plugin-sdk/approval-client-runtime` | مساعدات ملفات التعريف/المرشحات الأصلية لـ exec approval |
| `plugin-sdk/approval-delivery-runtime` | محولات القدرات/التسليم الأصلية لـ approval |
| `plugin-sdk/approval-native-runtime` | مساعدات الهدف الأصلي لـ approval + ربط الحساب |
| `plugin-sdk/approval-reply-runtime` | مساعدات حمولة الرد لـ exec/plugin approval |
| `plugin-sdk/command-auth-native` | مصادقة الأوامر الأصلية + مساعدات الهدف الأصلي للجلسة |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`، ومساعدات سجل الأوامر، ومساعدات تفويض المرسِل |
| `plugin-sdk/approval-auth-runtime` | مساعدات حل الموافقين ومصادقة الإجراء في نفس الدردشة |
| `plugin-sdk/approval-client-runtime` | مساعدات الملف الشخصي/المرشح للموافقات الأصلية لـ exec |
| `plugin-sdk/approval-delivery-runtime` | موائمات قدرات/تسليم الموافقات الأصلية |
| `plugin-sdk/approval-gateway-runtime` | مساعد مشترك لحل بوابة الموافقات |
| `plugin-sdk/approval-handler-adapter-runtime` | مساعدات خفيفة لتحميل موائم الموافقات الأصلية لنقاط إدخال القنوات الساخنة |
| `plugin-sdk/approval-handler-runtime` | مساعدات أوسع لوقت تشغيل معالج الموافقات؛ فضّل المسارات الأضيق الخاصة بالموائم/البوابة عندما تكون كافية |
| `plugin-sdk/approval-native-runtime` | مساعدات الهدف الأصلي للموافقات + ربط الحساب |
| `plugin-sdk/approval-reply-runtime` | مساعدات حمولة رد موافقات exec/الإضافة |
| `plugin-sdk/command-auth-native` | مساعدات مصادقة الأوامر الأصلية + أهداف الجلسات الأصلية |
| `plugin-sdk/command-detection` | مساعدات مشتركة لاكتشاف الأوامر |
| `plugin-sdk/command-surface` | تطبيع نص الأمر ومساعدات سطح الأمر |
| `plugin-sdk/command-surface` | تطبيع جسم الأمر ومساعدات سطح الأوامر |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لتجميع عقود الأسرار لأسطح أسرار القناة/الـ plugin |
| `plugin-sdk/secret-ref-runtime` | مساعدات ضيقة لـ `coerceSecretRef` وأنواع SecretRef لتحليل عقود الأسرار/الإعدادات |
| `plugin-sdk/security-runtime` | مساعدات مشتركة للثقة، وتقييد DM، والمحتوى الخارجي، وتجميع الأسرار |
| `plugin-sdk/ssrf-policy` | مساعدات allowlist للمضيف وسياسة SSRF للشبكات الخاصة |
| `plugin-sdk/ssrf-runtime` | مساعدات pinned-dispatcher وfetch المحروس بـ SSRF وسياسة SSRF |
| `plugin-sdk/secret-input` | مساعدات تحليل مدخلات الأسرار |
| `plugin-sdk/webhook-ingress` | مساعدات طلب/هدف webhook |
| `plugin-sdk/webhook-request-guards` | مساعدات حجم جسم الطلب/المهلة |
| `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لتجميع عقود الأسرار لأسطح أسرار القناة/الإضافة |
| `plugin-sdk/secret-ref-runtime` | مساعدات ضيقة لـ `coerceSecretRef` وكتابة SecretRef لتحليل عقود الأسرار/التكوين |
| `plugin-sdk/security-runtime` | مساعدات مشتركة للثقة، وبوابات الرسائل المباشرة، والمحتوى الخارجي، وتجميع الأسرار |
| `plugin-sdk/ssrf-policy` | مساعدات قائمة السماح للمضيف وسياسة SSRF للشبكات الخاصة |
| `plugin-sdk/ssrf-runtime` | مساعدات المرسِل المثبّت، والجلب المحمي بـ SSRF، وسياسة SSRF |
| `plugin-sdk/secret-input` | مساعدات تحليل إدخال الأسرار |
| `plugin-sdk/webhook-ingress` | مساعدات طلب/هدف Webhook |
| `plugin-sdk/webhook-request-guards` | مساعدات حجم جسم الطلب/المهلة الزمنية |
</Accordion>
<Accordion title="المسارات الفرعية لوقت التشغيل والتخزين">
| المسار الفرعي | أهم exports |
| المسار الفرعي | الصادرات الأساسية |
| --- | --- |
| `plugin-sdk/runtime` | مساعدات واسعة لوقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت plugin |
| `plugin-sdk/runtime-env` | مساعدات ضيقة لبيئة وقت التشغيل، وlogger، والمهلة، وإعادة المحاولة، وbackoff |
| `plugin-sdk/runtime` | مساعدات عامة لوقت التشغيل/السجلات/النسخ الاحتياطي/تثبيت الإضافات |
| `plugin-sdk/runtime-env` | مساعدات ضيقة لبيئة وقت التشغيل، والمسجل، والمهلة، وإعادة المحاولة، وbackoff |
| `plugin-sdk/channel-runtime-context` | مساعدات عامة لتسجيل والبحث عن سياق وقت تشغيل القناة |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | مساعدات مشتركة لأوامر/خطافات/HTTP/التفاعلية الخاصة بالـ plugin |
| `plugin-sdk/hook-runtime` | مساعدات مشتركة لخطوط webhook/internal hook |
| `plugin-sdk/lazy-runtime` | مساعدات الاستيراد/الربط الكسول لوقت التشغيل مثل `createLazyRuntimeModule`, `createLazyRuntimeMethod`, و`createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | مساعدات تنفيذ العمليات |
| `plugin-sdk/cli-runtime` | مساعدات تنسيق CLI، والانتظار، والإصدار |
| `plugin-sdk/gateway-runtime` | مساعدات عميل Gateway وتعديل حالة القناة |
| `plugin-sdk/config-runtime` | مساعدات تحميل/كتابة الإعدادات |
| `plugin-sdk/telegram-command-config` | مساعدات تطبيع أسماء/أوصاف أوامر Telegram والتحقق من التكرار/التعارض، حتى عند عدم توفر سطح عقد Telegram المضمّن |
| `plugin-sdk/approval-runtime` | مساعدات exec/plugin approval، وبناة approval-capability، ومساعدات المصادقة/profile، ومساعدات التوجيه/وقت التشغيل الأصلية |
| `plugin-sdk/reply-runtime` | مساعدات مشتركة لوقت تشغيل الوارد/الرد، والتجزئة، والإرسال، وheartbeat، ومخطط الرد |
| `plugin-sdk/plugin-runtime` | مساعدات مشتركة لأوامر/خطافات/http/التفاعل الخاصة بالإضافةات |
| `plugin-sdk/hook-runtime` | مساعدات مشتركة لمسار Webhook/الخطافات الداخلية |
| `plugin-sdk/lazy-runtime` | مساعدات الاستيراد/الربط الكسول لوقت التشغيل مثل `createLazyRuntimeModule` و`createLazyRuntimeMethod` و`createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | مساعدات تنفيذ العملية |
| `plugin-sdk/cli-runtime` | مساعدات التنسيق والانتظار والإصدار لـ CLI |
| `plugin-sdk/gateway-runtime` | مساعدات عميل البوابة وترقيعات حالة القناة |
| `plugin-sdk/config-runtime` | مساعدات تحميل/كتابة التكوين |
| `plugin-sdk/telegram-command-config` | تطبيع اسم/وصف أمر Telegram وفحوصات التكرار/التعارض، حتى عند غياب سطح عقد Telegram المضمّن |
| `plugin-sdk/approval-runtime` | مساعدات موافقات exec/الإضافة، وبناة قدرات الموافقة، ومساعدات المصادقة/الملف الشخصي، ومساعدات التوجيه/وقت التشغيل الأصلية |
| `plugin-sdk/reply-runtime` | مساعدات مشتركة لوقت تشغيل الوارد/الرد، والتجزئة، والإرسال، والنبض، ومخطط الرد |
| `plugin-sdk/reply-dispatch-runtime` | مساعدات ضيقة لإرسال/إنهاء الرد |
| `plugin-sdk/reply-history` | مساعدات مشتركة لسجل الرد قصير النافذة مثل `buildHistoryContext`, `recordPendingHistoryEntry`, و`clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-history` | مساعدات مشتركة لسجل الردود ذي النافذة القصيرة مثل `buildHistoryContext` و`recordPendingHistoryEntry` و`clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | مساعدات ضيقة لتجزئة النص/Markdown |
| `plugin-sdk/session-store-runtime` | مساعدات مسار مخزن الجلسة + updated-at |
| `plugin-sdk/state-paths` | مساعدات مسارات الحالة/OAuth |
| `plugin-sdk/routing` | مساعدات route/session-key وربط الحساب مثل `resolveAgentRoute`, `buildAgentSessionKey`, و`resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | مساعدات مشتركة لملخصات حالة القناة/الحساب، والقيم الافتراضية لحالة وقت التشغيل، ومساعدات بيانات issue الوصفية |
| `plugin-sdk/target-resolver-runtime` | مساعدات مشتركة لتحليل الأهداف |
| `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع slug/string |
| `plugin-sdk/session-store-runtime` | مساعدات مسار مخزن الجلسة و`updated-at` |
| `plugin-sdk/state-paths` | مساعدات مسارات الحالة/دليل OAuth |
| `plugin-sdk/routing` | مساعدات المسار/مفتاح الجلسة/ربط الحساب مثل `resolveAgentRoute` و`buildAgentSessionKey` و`resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | مساعدات مشتركة لملخص حالة القناة/الحساب، والقيم الافتراضية لحالة وقت التشغيل، ومساعدات بيانات تعريف المشكلات |
| `plugin-sdk/target-resolver-runtime` | مساعدات مشتركة لحل الأهداف |
| `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع السلاسل/slug |
| `plugin-sdk/request-url` | استخراج عناوين URL النصية من مدخلات شبيهة بـ fetch/request |
| `plugin-sdk/run-command` | مُشغّل أوامر موقّت بنتائج stdout/stderr مطبّعة |
| `plugin-sdk/run-command` | مشغل أوامر مؤقت بنتائج stdout/stderr مطبعة |
| `plugin-sdk/param-readers` | قارئات معلمات شائعة للأدوات/CLI |
| `plugin-sdk/tool-send` | استخراج حقول هدف الإرسال القياسية من وسيطات الأداة |
| `plugin-sdk/temp-path` | مساعدات مشتركة لمسارات التنزيل المؤقت |
| `plugin-sdk/logging-core` | مساعدات logger الخاصة بالأنظمة الفرعية وإخفاء البيانات |
| `plugin-sdk/markdown-table-runtime` | مساعدات وضع جداول Markdown |
| `plugin-sdk/tool-send` | استخراج حقول هدف الإرسال القياسية من وسائط الأداة |
| `plugin-sdk/temp-path` | مساعدات مشتركة لمسار التنزيل المؤقت |
| `plugin-sdk/logging-core` | مساعدات المسجل الفرعي والتنقيح |
| `plugin-sdk/markdown-table-runtime` | مساعدات أوضاع جداول Markdown |
| `plugin-sdk/json-store` | مساعدات صغيرة لقراءة/كتابة حالة JSON |
| `plugin-sdk/file-lock` | مساعدات file-lock قابلة لإعادة الدخول |
| `plugin-sdk/persistent-dedupe` | مساعدات cache لإزالة التكرار مدعومة بالقرص |
| `plugin-sdk/acp-runtime` | مساعدات وقت تشغيل ACP/session وإرسال الرد |
| `plugin-sdk/agent-config-primitives` | بدائيات ضيقة لمخطط إعدادات وقت تشغيل الوكيل |
| `plugin-sdk/boolean-param` | قارئ مرن لمعامل boolean |
| `plugin-sdk/dangerous-name-runtime` | مساعدات تحليل مطابقة الأسماء الخطرة |
| `plugin-sdk/device-bootstrap` | مساعدات bootstrap للجهاز ورمز الاقتران |
| `plugin-sdk/extension-shared` | بدائيات مساعدة مشتركة للقنوات السلبية، والحالة، والـ ambient proxy |
| `plugin-sdk/models-provider-runtime` | مساعدات الرد لأمر `/models`/المزود |
| `plugin-sdk/file-lock` | مساعدات إعادة الدخول لقفل الملفات |
| `plugin-sdk/persistent-dedupe` | مساعدات ذاكرة التخزين المؤقت لإزالة التكرار المدعومة بالقرص |
| `plugin-sdk/acp-runtime` | مساعدات ACP وقت التشغيل/الجلسة وإرسال الرد |
| `plugin-sdk/agent-config-primitives` | بدائيات ضيقة لمخطط تكوين وقت تشغيل الوكيل |
| `plugin-sdk/boolean-param` | قارئ معلمات منطقي مرن |
| `plugin-sdk/dangerous-name-runtime` | مساعدات حل مطابقة الأسماء الخطرة |
| `plugin-sdk/device-bootstrap` | مساعدات bootstrap للجهاز ورمز الإقران |
| `plugin-sdk/extension-shared` | بدائيات مشتركة لمساعدات القنوات السلبية، والحالة، والوكيل المحيط |
| `plugin-sdk/models-provider-runtime` | مساعدات أوامر `/models` / ردود الموفّر |
| `plugin-sdk/skill-commands-runtime` | مساعدات سرد أوامر Skills |
| `plugin-sdk/native-command-registry` | مساعدات السجل الأصلي للأوامر/البناء/التسلسل |
| `plugin-sdk/provider-zai-endpoint` | مساعدات اكتشاف endpoint لـ Z.A.I |
| `plugin-sdk/infra-runtime` | مساعدات أحداث النظام/heartbeat |
| `plugin-sdk/collection-runtime` | مساعدات صغيرة لـ cache محدود |
| `plugin-sdk/diagnostic-runtime` | مساعدات الأعلام التشخيصية والأحداث |
| `plugin-sdk/error-runtime` | رسم الأخطاء، والتنسيق، ومساعدات تصنيف الأخطاء المشتركة، و`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | مساعدات fetch مغلف، وproxy، والبحث المثبت |
| `plugin-sdk/native-command-registry` | مساعدات سجل/بناء/تسلسل الأوامر الأصلية |
| `plugin-sdk/provider-zai-endpoint` | مساعدات اكتشاف نقطة نهاية Z.A.I |
| `plugin-sdk/infra-runtime` | مساعدات أحداث النظام/النبض |
| `plugin-sdk/collection-runtime` | مساعدات صغيرة لذاكرة تخزين مؤقتة محدودة |
| `plugin-sdk/diagnostic-runtime` | مساعدات أعلام التشخيص والأحداث |
| `plugin-sdk/error-runtime` | مساعدات رسم الأخطاء، والتنسيق، وتصنيف الأخطاء المشتركة، و`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | مساعدات fetch المغلّفة، والوكيل، والبحث المثبّت |
| `plugin-sdk/host-runtime` | مساعدات تطبيع اسم المضيف ومضيف SCP |
| `plugin-sdk/retry-runtime` | إعدادات إعادة المحاولة ومساعدات مشغّل الإعادة |
| `plugin-sdk/agent-runtime` | مساعدات دليل الوكيل/الهوية/workspace |
| `plugin-sdk/directory-runtime` | query/dedup للأدلة المدعومة بالإعدادات |
| `plugin-sdk/retry-runtime` | مساعدات تكوين إعادة المحاولة ومشغّل إعادة المحاولة |
| `plugin-sdk/agent-runtime` | مساعدات دليل/هوية/مساحة عمل الوكيل |
| `plugin-sdk/directory-runtime` | استعلام/إزالة تكرار الدليل المدعوم بالتكوين |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="المسارات الفرعية للقدرات والاختبار">
| المسار الفرعي | أهم exports |
| المسار الفرعي | الصادرات الأساسية |
| --- | --- |
| `plugin-sdk/media-runtime` | مساعدات مشتركة لجلب/تحويل/تخزين الوسائط بالإضافة إلى بناة حمولة الوسائط |
| `plugin-sdk/media-generation-runtime` | مساعدات مشتركة لفشل-over في توليد الوسائط، واختيار candidates، ورسائل النماذج المفقودة |
| `plugin-sdk/media-understanding` | أنواع مزود فهم الوسائط بالإضافة إلى exports مساعدة موجهة للمزود للصورة/الصوت |
| `plugin-sdk/text-runtime` | مساعدات مشتركة للنص/Markdown/التسجيل مثل إزالة النص المرئي للمساعد، ومساعدات render/chunking/table الخاصة بـ Markdown، ومساعدات إخفاء البيانات، وdirective-tag، وأدوات النص الآمن |
| `plugin-sdk/media-runtime` | مساعدات مشتركة لجلب/تحويل/تخزين الوسائط بالإضافة إلى بناة حمولات الوسائط |
| `plugin-sdk/media-generation-runtime` | مساعدات مشتركة للإخفاق المرحلي في توليد الوسائط، واختيار المرشحين، ورسائل النماذج المفقودة |
| `plugin-sdk/media-understanding` | أنواع موفّر فهم الوسائط بالإضافة إلى صادرات مساعدات الصور/الصوت المواجهة للموفّر |
| `plugin-sdk/text-runtime` | مساعدات مشتركة للنص/Markdown/السجلات مثل إزالة النص المرئي للمساعد، ومساعدات عرض/تجزئة/جداول Markdown، ومساعدات التنقيح، ووسوم التوجيه، وأدوات النص الآمن |
| `plugin-sdk/text-chunking` | مساعد تجزئة النص الصادر |
| `plugin-sdk/speech` | أنواع مزود الكلام بالإضافة إلى exports موجهة للمزود خاصة بالتوجيه، والسجل، والتحقق |
| `plugin-sdk/speech-core` | أنواع مشتركة لمزود الكلام، والسجل، والتوجيه، ومساعدات التطبيع |
| `plugin-sdk/realtime-transcription` | أنواع مزود النسخ الفوري ومساعدات السجل |
| `plugin-sdk/realtime-voice` | أنواع مزود الصوت الفوري ومساعدات السجل |
| `plugin-sdk/image-generation` | أنواع مزود توليد الصور |
| `plugin-sdk/image-generation-core` | أنواع مشتركة لتوليد الصور، والفشل-over، والمصادقة، ومساعدات السجل |
| `plugin-sdk/music-generation` | أنواع الطلب/النتيجة/المزود لتوليد الموسيقى |
| `plugin-sdk/music-generation-core` | أنواع مشتركة لتوليد الموسيقى، ومساعدات failover، والبحث عن المزود، وتحليل model-ref |
| `plugin-sdk/video-generation` | أنواع الطلب/النتيجة/المزود لتوليد الفيديو |
| `plugin-sdk/video-generation-core` | أنواع مشتركة لتوليد الفيديو، ومساعدات failover، والبحث عن المزود، وتحليل model-ref |
| `plugin-sdk/webhook-targets` | سجل أهداف webhook ومساعدات تثبيت المسارات |
| `plugin-sdk/webhook-path` | مساعدات تطبيع مسار webhook |
| `plugin-sdk/speech` | أنواع موفّر الكلام بالإضافة إلى مساعدات التوجيه، والسجل، والتحقق المواجهة للموفّر |
| `plugin-sdk/speech-core` | أنواع موفّر الكلام المشتركة، والسجل، والتوجيه، ومساعدات التطبيع |
| `plugin-sdk/realtime-transcription` | أنواع موفّر النسخ الفوري ومساعدات السجل |
| `plugin-sdk/realtime-voice` | أنواع موفّر الصوت الفوري ومساعدات السجل |
| `plugin-sdk/image-generation` | أنواع موفّر توليد الصور |
| `plugin-sdk/image-generation-core` | أنواع توليد الصور المشتركة، والإخفاق المرحلي، والمصادقة، ومساعدات السجل |
| `plugin-sdk/music-generation` | أنواع موفّر/طلب/نتيجة توليد الموسيقى |
| `plugin-sdk/music-generation-core` | أنواع توليد الموسيقى المشتركة، ومساعدات الإخفاق المرحلي، والبحث عن الموفّر، وتحليل مرجع النموذج |
| `plugin-sdk/video-generation` | أنواع موفّر/طلب/نتيجة توليد الفيديو |
| `plugin-sdk/video-generation-core` | أنواع توليد الفيديو المشتركة، ومساعدات الإخفاق المرحلي، والبحث عن الموفّر، وتحليل مرجع النموذج |
| `plugin-sdk/webhook-targets` | سجل أهداف Webhook ومساعدات تثبيت المسارات |
| `plugin-sdk/webhook-path` | مساعدات تطبيع مسار Webhook |
| `plugin-sdk/web-media` | مساعدات مشتركة لتحميل الوسائط البعيدة/المحلية |
| `plugin-sdk/zod` | إعادة export لـ `zod` لمستهلكي Plugin SDK |
| `plugin-sdk/zod` | إعادة تصدير `zod` لمستهلكي Plugin SDK |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="المسارات الفرعية للذاكرة">
| المسار الفرعي | أهم exports |
| المسار الفرعي | الصادرات الأساسية |
| --- | --- |
| `plugin-sdk/memory-core` | سطح مساعد memory-core المضمّن لمساعدات manager/config/file/CLI |
| `plugin-sdk/memory-core-engine-runtime` | واجهة وقت تشغيل لفهرسة/بحث الذاكرة |
| `plugin-sdk/memory-core-host-engine-foundation` | exports محرك الأساس لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-engine-embeddings` | exports محرك embeddings لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-engine-qmd` | exports محرك QMD لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-engine-storage` | exports محرك التخزين لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-multimodal` | مساعدات متعددة الوسائط لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-query` | مساعدات الاستعلام لمضيف الذاكرة |
| `plugin-sdk/memory-core` | سطح مساعد memory-core المضمّن لمساعدات المدير/التكوين/الملف/CLI |
| `plugin-sdk/memory-core-engine-runtime` | واجهة وقت التشغيل لفهرسة/بحث الذاكرة |
| `plugin-sdk/memory-core-host-engine-foundation` | صادرات محرك الأساس لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-engine-embeddings` | صادرات محرك embeddings لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-engine-qmd` | صادرات محرك QMD لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-engine-storage` | صادرات محرك التخزين لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-multimodal` | مساعدات الوسائط المتعددة لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-query` | مساعدات استعلام مضيف الذاكرة |
| `plugin-sdk/memory-core-host-secret` | مساعدات الأسرار لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-events` | مساعدات سجل أحداث مضيف الذاكرة |
| `plugin-sdk/memory-core-host-events` | مساعدات دفتر أحداث مضيف الذاكرة |
| `plugin-sdk/memory-core-host-status` | مساعدات حالة مضيف الذاكرة |
| `plugin-sdk/memory-core-host-runtime-cli` | مساعدات CLI الخاصة بوقت تشغيل مضيف الذاكرة |
| `plugin-sdk/memory-core-host-runtime-core` | مساعدات core لوقت تشغيل مضيف الذاكرة |
| `plugin-sdk/memory-core-host-runtime-cli` | مساعدات CLI وقت التشغيل لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-runtime-core` | مساعدات وقت التشغيل الأساسية لمضيف الذاكرة |
| `plugin-sdk/memory-core-host-runtime-files` | مساعدات الملفات/وقت التشغيل لمضيف الذاكرة |
| `plugin-sdk/memory-host-core` | اسم مستعار محايد للمورّد لمساعدات core لوقت تشغيل مضيف الذاكرة |
| `plugin-sdk/memory-host-events` | اسم مستعار محايد للمورّد لمساعدات سجل أحداث مضيف الذاكرة |
| `plugin-sdk/memory-host-core` | اسم مستعار محايد للمورّد لمساعدات وقت التشغيل الأساسية لمضيف الذاكرة |
| `plugin-sdk/memory-host-events` | اسم مستعار محايد للمورّد لمساعدات دفتر أحداث مضيف الذاكرة |
| `plugin-sdk/memory-host-files` | اسم مستعار محايد للمورّد لمساعدات الملفات/وقت التشغيل لمضيف الذاكرة |
| `plugin-sdk/memory-host-markdown` | مساعدات managed-Markdown مشتركة للـ plugins القريبة من الذاكرة |
| `plugin-sdk/memory-host-search` | واجهة وقت تشغيل الذاكرة النشطة للوصول إلى search-manager |
| `plugin-sdk/memory-host-markdown` | مساعدات Markdown المُدار المشتركة للإضافات المجاورة للذاكرة |
| `plugin-sdk/memory-host-search` | واجهة وقت تشغيل الذاكرة النشطة للوصول إلى مدير البحث |
| `plugin-sdk/memory-host-status` | اسم مستعار محايد للمورّد لمساعدات حالة مضيف الذاكرة |
| `plugin-sdk/memory-lancedb` | سطح مساعد memory-lancedb المضمّن |
</Accordion>
<Accordion title="المسارات الفرعية المساعدة المحجوزة للمضمن">
<Accordion title="المسارات الفرعية المحجوزة للمساعدات المضمّنة">
| العائلة | المسارات الفرعية الحالية | الاستخدام المقصود |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | مساعدات دعم Browser plugin المضمّن (`browser-support` يبقى barrel التوافقية) |
| المتصفح | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | مساعدات دعم إضافة المتصفح المضمّنة (`browser-support` يبقى الشريط المتوافق) |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | سطح مساعد/وقت تشغيل Matrix المضمّن |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | سطح مساعد/وقت تشغيل LINE المضمّن |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | سطح مساعد IRC المضمّن |
| مساعدات خاصة بالقنوات | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | نقاط ربط التوافق/المساعدة للقنوات المضمنة |
| مساعدات خاصة بالمصادقة/الـ plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | نقاط ربط مساعدة للميزات/الـ plugins المضمنة؛ ويقوم `plugin-sdk/github-copilot-token` حاليًا بتصدير `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, و`resolveCopilotApiToken` |
| مساعدات خاصة بالقنوات | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | مسارات توافق/مساعدات القنوات المضمّنة |
| مساعدات خاصة بالمصادقة/الإضافة | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | مسارات مساعدات الميزات/الإضافات المضمّنة؛ يصدّر `plugin-sdk/github-copilot-token` حاليًا `DEFAULT_COPILOT_API_BASE_URL` و`deriveCopilotApiBaseUrlFromToken` و`resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## API التسجيل
يتلقى callback الخاص بـ `register(api)` كائن `OpenClawPluginApi` يحوي
هذه الأساليب:
يتلقى استدعاء `register(api)` كائن `OpenClawPluginApi` بهذه
الأساليب:
### تسجيل القدرات
| الأسلوب | ما الذي يسجله |
| ------------------------------------------------ | -------------------------------- |
| `api.registerProvider(...)` | الاستدلال النصي (LLM) |
| `api.registerCliBackend(...)` | CLI inference backend محلي |
| `api.registerChannel(...)` | قناة مراسلة |
| `api.registerSpeechProvider(...)` | تحويل النص إلى كلام / توليف STT |
| `api.registerProvider(...)` | استدلال النص (LLM) |
| `api.registerCliBackend(...)` | واجهة خلفية محلية للاستدلال عبر CLI |
| `api.registerChannel(...)` | قناة مراسلة |
| `api.registerSpeechProvider(...)` | تحويل النص إلى كلام / توليف STT |
| `api.registerRealtimeTranscriptionProvider(...)` | نسخ فوري متدفق |
| `api.registerRealtimeVoiceProvider(...)` | جلسات صوت فوري ثنائية الاتجاه |
| `api.registerMediaUnderstandingProvider(...)` | تحليل الصور/الصوت/الفيديو |
| `api.registerImageGenerationProvider(...)` | توليد الصور |
| `api.registerMusicGenerationProvider(...)` | توليد الموسيقى |
| `api.registerVideoGenerationProvider(...)` | توليد الفيديو |
| `api.registerWebFetchProvider(...)` | مزود جلب / scrape للويب |
| `api.registerWebSearchProvider(...)` | البحث على الويب |
| `api.registerRealtimeVoiceProvider(...)` | جلسات صوت فورية ثنائية الاتجاه |
| `api.registerMediaUnderstandingProvider(...)` | تحليل الصور/الصوت/الفيديو |
| `api.registerImageGenerationProvider(...)` | توليد الصور |
| `api.registerMusicGenerationProvider(...)` | توليد الموسيقى |
| `api.registerVideoGenerationProvider(...)` | توليد الفيديو |
| `api.registerWebFetchProvider(...)` | موفّر Web fetch / scrape |
| `api.registerWebSearchProvider(...)` | البحث على الويب |
### الأدوات والأوامر
| الأسلوب | ما الذي يسجله |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | أداة وكيل (مطلوبة أو `{ optional: true }`) |
| `api.registerCommand(def)` | أمر مخصص (يتجاوز LLM) |
| `api.registerCommand(def)` | أمر مخصص (يتجاوز LLM) |
### البنية التحتية
| الأسلوب | ما الذي يسجله |
| ---------------------------------------------- | --------------------------------------- |
| `api.registerHook(events, handler, opts?)` | event hook |
| `api.registerHttpRoute(params)` | endpoint ‏HTTP في Gateway |
| `api.registerGatewayMethod(name, handler)` | أسلوب Gateway RPC |
| `api.registerCli(registrar, opts?)` | أمر CLI فرعي |
| `api.registerService(service)` | خدمة في الخلفية |
| `api.registerInteractiveHandler(registration)` | معالج تفاعلي |
| `api.registerMemoryPromptSupplement(builder)` | قسم إضافي من prompt مجاور للذاكرة |
| `api.registerMemoryCorpusSupplement(adapter)` | corpus إضافي لبحث/قراءة الذاكرة |
| `api.registerHook(events, handler, opts?)` | خطاف حدث |
| `api.registerHttpRoute(params)` | نقطة نهاية HTTP للبوابة |
| `api.registerGatewayMethod(name, handler)` | أسلوب RPC للبوابة |
| `api.registerCli(registrar, opts?)` | أمر فرعي في CLI |
| `api.registerService(service)` | خدمة خلفية |
| `api.registerInteractiveHandler(registration)` | معالج تفاعلي |
| `api.registerMemoryPromptSupplement(builder)` | قسم إضافي للمطالبات المجاورة للذاكرة |
| `api.registerMemoryCorpusSupplement(adapter)` | corpus إضافي لبحث/قراءة الذاكرة |
تظل مساحات أسماء الإدارة الأساسية المحجوزة (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) دائمًا عند `operator.admin`، حتى إذا حاول plugin تعيين
نطاق أضيق لأسلوب gateway. ويفضل استخدام بادئات خاصة بالـ plugin
للأساليب المملوكة له.
تظل مساحات أسماء الإدارة الأساسية المحجوزة (`config.*` و`exec.approvals.*` و`wizard.*`،
و`update.*`) دائمًا `operator.admin`، حتى إذا حاولت إضافة تعيين
نطاق أضيق لأسلوب البوابة. فضّل البادئات الخاصة بالإضافة
للأساليب التي تملكها الإضافة.
### بيانات تعريف تسجيل CLI
يقبل `api.registerCli(registrar, opts?)` نوعين من بيانات التعريف العليا:
يقبل `api.registerCli(registrar, opts?)` نوعين من بيانات التعريف في المستوى الأعلى:
- `commands`: جذور أوامر صريحة يملكها registrar
- `commands`: جذور أوامر صريحة يملكها المُسجِّل
- `descriptors`: واصفات أوامر وقت التحليل المستخدمة لمساعدة CLI الجذرية،
والتوجيه، والتسجيل الكسول لـ CLI الخاص بالـ plugin
والتوجيه، وتسجيل CLI الكسول للإضافة
إذا كنت تريد أن يبقى أمر plugin محمّلًا بكسل في مسار CLI الجذري العادي،
فقدّم `descriptors` تغطي كل جذر أمر من المستوى الأعلى يكشفه
ذلك registrar.
إذا كنت تريد أن يظل أمر الإضافة محمّلًا بكسل في المسار الجذري العادي لـ CLI،
فقدّم `descriptors` تغطي كل جذر أمر من المستوى الأعلى يكشفه ذلك
المُسجِّل.
```typescript
api.registerCli(
@ -363,7 +368,7 @@ api.registerCli(
descriptors: [
{
name: "matrix",
description: "Manage Matrix accounts, verification, devices, and profile state",
description: "إدارة حسابات Matrix، والتحقق، والأجهزة، وحالة الملف الشخصي",
hasSubcommands: true,
},
],
@ -371,128 +376,134 @@ api.registerCli(
);
```
استخدم `commands` وحدها فقط عندما لا تحتاج إلى تسجيل CLI جذري كسول.
يظل مسار التوافق eager هذا مدعومًا، لكنه لا يثبت
عناصر نائبة مدعومة بـ descriptor للتحميل الكسول وقت التحليل.
استخدم `commands` وحده فقط عندما لا تحتاج إلى تسجيل CLI جذري كسول.
لا يزال هذا المسار التوافقي المتعجل مدعومًا، لكنه لا يثبت
عناصر نائبة مدعومة بالواصفات من أجل التحميل الكسول وقت التحليل.
### تسجيل CLI backend
### تسجيل الواجهة الخلفية لـ CLI
يتيح `api.registerCliBackend(...)` للـ plugin امتلاك الإعداد الافتراضي لـ
AI CLI backend محلي مثل `codex-cli`.
يتيح `api.registerCliBackend(...)` لإضافة أن تملك التكوين الافتراضي لواجهة خلفية
محلية لـ CLI للذكاء الاصطناعي مثل `codex-cli`.
- يصبح `id` الخاص بالـ backend بادئة المزوّد في مراجع النماذج مثل `codex-cli/gpt-5`.
- تستخدم `config` الخاصة بالـ backend الشكل نفسه الموجود في `agents.defaults.cliBackends.<id>`.
- تظل إعدادات المستخدم هي الغالبة. يدمج OpenClaw ‏`agents.defaults.cliBackends.<id>` فوق
القيمة الافتراضية للـ plugin قبل تشغيل CLI.
- استخدم `normalizeConfig` عندما يحتاج backend إلى إعادة كتابة توافقية بعد الدمج
(مثل تطبيع أشكال flags القديمة).
- يصبح `id` الخاص بالواجهة الخلفية بادئة الموفّر في مراجع النماذج مثل `codex-cli/gpt-5`.
- يستخدم `config` الخاص بالواجهة الخلفية الشكل نفسه المستخدم في `agents.defaults.cliBackends.<id>`.
- يظل تكوين المستخدم هو الغالب. يدمج OpenClaw `agents.defaults.cliBackends.<id>` فوق
القيمة الافتراضية للإضافة قبل تشغيل CLI.
- استخدم `normalizeConfig` عندما تحتاج الواجهة الخلفية إلى إعادة كتابة توافقية بعد الدمج
(على سبيل المثال، تطبيع أشكال الأعلام القديمة).
### الخانات الحصرية
### الفتحات الحصرية
| الأسلوب | ما الذي يسجله |
| ------------------------------------------ | ------------------------------------- |
| `api.registerContextEngine(id, factory)` | محرك سياق (واحد فقط نشط في كل مرة) |
| `api.registerMemoryPromptSection(builder)` | باني قسم prompt للذاكرة |
| `api.registerMemoryFlushPlan(resolver)` | محلل خطة flush للذاكرة |
| `api.registerMemoryRuntime(runtime)` | محول وقت تشغيل الذاكرة |
| `api.registerContextEngine(id, factory)` | محرك السياق (واحد نشط في كل مرة) |
| `api.registerMemoryCapability(capability)` | قدرة الذاكرة الموحدة |
| `api.registerMemoryPromptSection(builder)` | باني قسم مطالبة الذاكرة |
| `api.registerMemoryFlushPlan(resolver)` | محلّل خطة تفريغ الذاكرة |
| `api.registerMemoryRuntime(runtime)` | موائم وقت تشغيل الذاكرة |
### محولات embedding الخاصة بالذاكرة
### موائمات تضمين الذاكرة
| الأسلوب | ما الذي يسجله |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | محول embedding للذاكرة للـ plugin النشط |
| `api.registerMemoryEmbeddingProvider(adapter)` | موائم تضمين ذاكرة للإضافة النشطة |
- `registerMemoryPromptSection`, `registerMemoryFlushPlan`, و
`registerMemoryRuntime` حصرية لـ Memory plugins.
- يتيح `registerMemoryEmbeddingProvider` للـ memory plugin النشط تسجيل
معرّف محول embedding واحد أو أكثر (مثل `openai`, `gemini`، أو معرّف
مخصص يعرّفه plugin).
- تُحل إعدادات المستخدم مثل `agents.defaults.memorySearch.provider` و
`agents.defaults.memorySearch.fallback` مقابل معرّفات المحولات المسجلة تلك.
- `registerMemoryCapability` هو API الإضافة الحصرية المفضلة الخاصة بذاكرة الذاكرة.
- قد يكشف `registerMemoryCapability` أيضًا `publicArtifacts.listArtifacts(...)`
بحيث تتمكن الإضافات المرافقة من استهلاك مصنوعات الذاكرة المصدّرة عبر
`openclaw/plugin-sdk/memory-host-core` بدلًا من الوصول إلى التخطيط الخاص
لإضافة ذاكرة محددة.
- `registerMemoryPromptSection` و`registerMemoryFlushPlan` و
`registerMemoryRuntime` هي APIs حصرية متوافقة مع الإصدارات القديمة لإضافات الذاكرة.
- يتيح `registerMemoryEmbeddingProvider` لإضافة الذاكرة النشطة تسجيل
معرّف واحد أو أكثر لموائمات التضمين (مثل `openai` أو `gemini` أو معرّف
مخصص تعرّفه الإضافة).
- يُحل تكوين المستخدم مثل `agents.defaults.memorySearch.provider` و
`agents.defaults.memorySearch.fallback` مقابل معرّفات الموائمات المسجلة هذه.
### الأحداث ودورة الحياة
| الأسلوب | ما الذي يفعله |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | hook دورة حياة typed |
| `api.onConversationBindingResolved(handler)` | callback عند تحليل ربط المحادثة |
| `api.on(hookName, handler, opts?)` | خطاف دورة حياة مطبّع |
| `api.onConversationBindingResolved(handler)` | استدعاء رد رابط المحادثة |
### دلالات قرارات الـ hook
### دلالات قرارات الخطافات
- `before_tool_call`: إرجاع `{ block: true }` نهائي. وبمجرد أن يضبطه أي معالج، يتم تخطي المعالجات الأقل أولوية.
- `before_tool_call`: إرجاع `{ block: false }` يُعامل على أنه بدون قرار (مثل حذف `block`) وليس كتجاوز.
- `before_install`: إرجاع `{ block: true }` نهائي. وبمجرد أن يضبطه أي معالج، يتم تخطي المعالجات الأقل أولوية.
- `before_install`: إرجاع `{ block: false }` يُعامل على أنه بدون قرار (مثل حذف `block`) وليس كتجاوز.
- `reply_dispatch`: إرجاع `{ handled: true, ... }` نهائي. وبمجرد أن يدّعي أي معالج الإرسال، يتم تخطي المعالجات الأقل أولوية ومسار إرسال النموذج الافتراضي.
- `message_sending`: إرجاع `{ cancel: true }` نهائي. وبمجرد أن يضبطه أي معالج، يتم تخطي المعالجات الأقل أولوية.
- `message_sending`: إرجاع `{ cancel: false }` يُعامل على أنه بدون قرار (مثل حذف `cancel`) وليس كتجاوز.
- `before_tool_call`: إرجاع `{ block: true }` نهائي. بمجرد أن يضبطه أي معالج، يتم تخطي المعالجات ذات الأولوية الأقل.
- `before_tool_call`: إرجاع `{ block: false }` يُعامل على أنه لا قرار (مثل حذف `block`)، وليس كتجاوز.
- `before_install`: إرجاع `{ block: true }` نهائي. بمجرد أن يضبطه أي معالج، يتم تخطي المعالجات ذات الأولوية الأقل.
- `before_install`: إرجاع `{ block: false }` يُعامل على أنه لا قرار (مثل حذف `block`)، وليس كتجاوز.
- `reply_dispatch`: إرجاع `{ handled: true, ... }` نهائي. بمجرد أن يطالب أي معالج بالإرسال، يتم تخطي المعالجات ذات الأولوية الأقل ومسار إرسال النموذج الافتراضي.
- `message_sending`: إرجاع `{ cancel: true }` نهائي. بمجرد أن يضبطه أي معالج، يتم تخطي المعالجات ذات الأولوية الأقل.
- `message_sending`: إرجاع `{ cancel: false }` يُعامل على أنه لا قرار (مثل حذف `cancel`)، وليس كتجاوز.
### حقول كائن API
| الحقل | النوع | الوصف |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | معرّف plugin |
| `api.name` | `string` | اسم العرض |
| `api.version` | `string?` | إصدار plugin ‏(اختياري) |
| `api.description` | `string?` | وصف plugin ‏(اختياري) |
| `api.source` | `string` | مسار مصدر plugin |
| `api.rootDir` | `string?` | الدليل الجذري لـ plugin ‏(اختياري) |
| `api.config` | `OpenClawConfig` | لقطة الإعدادات الحالية (لقطة وقت تشغيل داخل الذاكرة النشطة عندما تكون متاحة) |
| `api.pluginConfig` | `Record<string, unknown>` | إعدادات خاصة بالـ plugin من `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | logger محدود النطاق (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ و`"setup-runtime"` هي نافذة بدء التشغيل/الإعداد الخفيفة قبل الإدخال الكامل |
| `api.resolvePath(input)` | `(string) => string` | تحليل المسار نسبةً إلى جذر plugin |
| `api.id` | `string` | معرّف الإضافة |
| `api.name` | `string` | اسم العرض |
| `api.version` | `string?` | إصدار الإضافة (اختياري) |
| `api.description` | `string?` | وصف الإضافة (اختياري) |
| `api.source` | `string` | مسار مصدر الإضافة |
| `api.rootDir` | `string?` | الدليل الجذري للإضافة (اختياري) |
| `api.config` | `OpenClawConfig` | لقطة التكوين الحالية (لقطة وقت التشغيل النشطة داخل الذاكرة عند توفرها) |
| `api.pluginConfig` | `Record<string, unknown>` | تكوين خاص بالإضافة من `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | مسجّل ذو نطاق (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ `"setup-runtime"` هي نافذة بدء التشغيل/الإعداد الخفيفة قبل الإدخال الكامل |
| `api.resolvePath(input)` | `(string) => string` | حل المسار نسبةً إلى جذر الإضافة |
## اصطلاحات الوحدات الداخلية
## اصطلاح الوحدات الداخلية
داخل plugin الخاص بك، استخدم ملفات barrel محلية للاستيراد الداخلي:
داخل إضافتك، استخدم ملفات barrel محلية للاستيرادات الداخلية:
```
my-plugin/
api.ts # Exports عامة للمستهلكين الخارجيين
runtime-api.ts # Exports داخلية فقط لوقت التشغيل
index.ts # نقطة إدخال plugin
setup-entry.ts # إدخال خفيف خاص بالإعداد فقط (اختياري)
api.ts # الصادرات العامة للمستهلكين الخارجيين
runtime-api.ts # صادرات وقت تشغيل داخلية فقط
index.ts # نقطة إدخال الإضافة
setup-entry.ts # إدخال خفيف للإعداد فقط (اختياري)
```
<Warning>
لا تستورد plugin الخاص بك أبدًا عبر `openclaw/plugin-sdk/<your-plugin>`
من كود الإنتاج. وجّه عمليات الاستيراد الداخلية عبر `./api.ts` أو
لا تستورد إضافتك الخاصة أبدًا من خلال `openclaw/plugin-sdk/<your-plugin>`
من كود الإنتاج. وجّه الاستيرادات الداخلية عبر `./api.ts` أو
`./runtime-api.ts`. مسار SDK هو العقد الخارجي فقط.
</Warning>
تفضّل الآن الأسطح العامة للـ plugins المضمنة المحمّلة عبر facade (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts`، وملفات الإدخال العامة المشابهة) استخدام
لقطة إعدادات وقت التشغيل النشطة عندما يكون OpenClaw يعمل بالفعل. وإذا لم تكن
هناك لقطة وقت تشغيل متاحة بعد، فسترجع إلى ملف الإعدادات المحلول على القرص.
تفضّل الآن الأسطح العامة للإضافات المضمّنة المحمّلة عبر الواجهة (`api.ts` و`runtime-api.ts`،
و`index.ts` و`setup-entry.ts`، وملفات الإدخال العامة المشابهة)
لقطة تكوين وقت التشغيل النشطة عندما يكون OpenClaw قيد التشغيل بالفعل. وإذا لم تكن
لقطة وقت التشغيل موجودة بعد، فإنها ترجع إلى ملف التكوين المحلول على القرص.
يمكن لـ Provider plugins أيضًا كشف barrel عقد محلي ضيق خاص بالـ plugin عندما يكون
المساعد مقصودًا أن يكون خاصًا بالمزود ولا ينتمي بعد إلى مسار فرعي عام في SDK.
المثال المضمّن الحالي: يحتفظ مزود Anthropic بمساعدات تدفق Claude
داخل نقطة الربط العامة الخاصة به `api.ts` / `contract-api.ts` بدلًا من
ترقية منطق ترويسات Anthropic beta و`service_tier` إلى عقد عام
`plugin-sdk/*`.
يمكن لإضافات الموفّرات أيضًا كشف ملف barrel محلي ضيق خاص بالإضافة عندما يكون
المساعد خاصًا بالموفّر عمدًا ولا ينتمي بعد إلى مسار فرعي عام في SDK.
المثال المضمّن الحالي: يحتفظ موفّر Anthropic بمساعدات بث Claude
الخاصة به في سطحه العام `api.ts` / `contract-api.ts` بدلًا من
ترقية منطق رؤوس Anthropic التجريبية و`service_tier` إلى عقد
عام من `plugin-sdk/*`.
أمثلة مضمنة حالية أخرى:
أمثلة مضمّنة حالية أخرى:
- `@openclaw/openai-provider`: يصدّر `api.ts` بناة المزودات،
ومساعدات النماذج الافتراضية، وبناة مزودات الوقت الفعلي
- `@openclaw/openrouter-provider`: يصدّر `api.ts` باني المزود بالإضافة إلى
مساعدات onboarding/config
- `@openclaw/openai-provider`: يصدّر `api.ts` بُناة الموفّر،
ومساعدات النموذج الافتراضي، وبناة الموفّر الفوري
- `@openclaw/openrouter-provider`: يصدّر `api.ts` باني الموفّر بالإضافة إلى
مساعدات الإعداد الأولي/التكوين
<Warning>
يجب أيضًا على كود الإنتاج الخاص بالامتدادات تجنب استيرادات
`openclaw/plugin-sdk/<other-plugin>`. وإذا كان أحد المساعدات مشتركًا فعلًا، فقم بترقيته إلى مسار فرعي
محايد في SDK مثل `openclaw/plugin-sdk/speech`, `.../provider-model-shared` أو أي
سطح موجّه للقدرات بدلًا من ربط pluginين معًا.
يجب أيضًا على كود الإنتاج في الامتدادات تجنّب الاستيراد من `openclaw/plugin-sdk/<other-plugin>`.
إذا كان المساعد مشتركًا فعلًا، فقم بترقيته إلى مسار فرعي محايد في SDK
مثل `openclaw/plugin-sdk/speech` أو `.../provider-model-shared` أو سطح آخر
موجّه للقدرات بدلًا من ربط إضافتين معًا.
</Warning>
## ذو صلة
- [Entry Points](/ar/plugins/sdk-entrypoints) — خيارات `definePluginEntry` و`defineChannelPluginEntry`
- [Runtime Helpers](/ar/plugins/sdk-runtime) — المرجع الكامل لمساحة الأسماء `api.runtime`
- [Setup and Config](/ar/plugins/sdk-setup) — التغليف، وmanifest، ومخططات الإعدادات
- [Testing](/ar/plugins/sdk-testing) — أدوات الاختبار وقواعد lint
- [SDK Migration](/ar/plugins/sdk-migration) — الترحيل من الأسطح المهجورة
- [Plugin Internals](/ar/plugins/architecture) — البنية العميقة ونموذج القدرات
- [نقاط الإدخال](/ar/plugins/sdk-entrypoints) — خيارات `definePluginEntry` و`defineChannelPluginEntry`
- [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) — المرجع الكامل لمساحة الاسم `api.runtime`
- [الإعداد والتكوين](/ar/plugins/sdk-setup) — الحزم، وmanifestات، ومخططات التكوين
- [الاختبار](/ar/plugins/sdk-testing) — أدوات الاختبار وقواعد lint
- [ترحيل SDK](/ar/plugins/sdk-migration) — الترحيل من الأسطح القديمة المهملة
- [الداخلية الخاصة بالإضافات](/ar/plugins/architecture) — بنية عميقة ونموذج القدرات

142
docs/ar/providers/google.md
View File

@ -1,30 +1,30 @@
---
read_when:
- تريد استخدام نماذج Google Gemini مع OpenClaw
- تحتاج إلى تدفق المصادقة عبر مفتاح API أو OAuth
summary: إعداد Google Gemini ‏(مفتاح API + OAuth، وتوليد الصور، وفهم الوسائط، والبحث على الويب)
- تحتاج إلى تدفق المصادقة بمفتاح API أو OAuth
summary: إعداد Google Gemini ‏(مفتاح API وOAuth، وإنشاء الصور، وفهم الوسائط، والبحث على الويب)
title: Google (Gemini)
x-i18n:
generated_at: "2026-04-07T07:21:24Z"
generated_at: "2026-04-08T02:17:12Z"
model: gpt-5.4
provider: openai
source_hash: 36cc7c7d8d19f6d4a3fb223af36c8402364fc309d14ffe922bd004203ceb1754
source_hash: e9e558f5ce35c853e0240350be9a1890460c5f7f7fd30b05813a656497dee516
source_path: providers/google.md
workflow: 15
---
# Google (Gemini)
يوفر Google plugin الوصول إلى نماذج Gemini عبر Google AI Studio، بالإضافة إلى
توليد الصور، وفهم الوسائط (الصور/الصوت/الفيديو)، والبحث على الويب عبر
يوفر plugin Google إمكانية الوصول إلى نماذج Gemini عبر Google AI Studio، بالإضافة إلى
إنشاء الصور، وفهم الوسائط (الصور/الصوت/الفيديو)، والبحث على الويب عبر
Gemini Grounding.
- المزود: `google`
- الموفر: `google`
- المصادقة: `GEMINI_API_KEY` أو `GOOGLE_API_KEY`
- API: ‏Google Gemini API
- مزود بديل: `google-gemini-cli` ‏(OAuth)
- API: Google Gemini API
- موفر بديل: `google-gemini-cli` ‏(OAuth)
## البدء السريع
## بداية سريعة
1. اضبط مفتاح API:
@ -53,17 +53,17 @@ openclaw onboard --non-interactive \
--gemini-api-key "$GEMINI_API_KEY"
```
## OAuth ‏(Gemini CLI)
## OAuth (Gemini CLI)
يستخدم مزود بديل باسم `google-gemini-cli` مصادقة PKCE OAuth بدلًا من مفتاح
API. وهذا تكامل غير رسمي؛ وقد أفاد بعض المستخدمين بوجود قيود
على الحسابات. استخدمه على مسؤوليتك الخاصة.
يستخدم موفر بديل باسم `google-gemini-cli` مصادقة PKCE OAuth بدلًا من مفتاح API.
هذا تكامل غير رسمي؛ وقد أبلغ بعض المستخدمين عن
قيود على الحساب. استخدمه على مسؤوليتك الخاصة.
- النموذج الافتراضي: `google-gemini-cli/gemini-3.1-pro-preview`
- الاسم البديل: `gemini-cli`
- متطلب التثبيت: توفر Gemini CLI محليًا باسم `gemini`
- Homebrew: ‏`brew install gemini-cli`
- npm: ‏`npm install -g @google/gemini-cli`
- النموذج الافتراضي: `google-gemini-cli/gemini-3-flash-preview`
- الاسم المستعار: `gemini-cli`
- متطلب التثبيت المسبق: أن يكون Gemini CLI المحلي متاحًا باسم `gemini`
- Homebrew: `brew install gemini-cli`
- npm: `npm install -g @google/gemini-cli`
- تسجيل الدخول:
```bash
@ -75,48 +75,48 @@ openclaw models auth login --provider google-gemini-cli --set-default
- `OPENCLAW_GEMINI_OAUTH_CLIENT_ID`
- `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET`
(أو متغيرات `GEMINI_CLI_*` البديلة.)
(أو الصيغ `GEMINI_CLI_*`.)
إذا فشلت طلبات Gemini CLI OAuth بعد تسجيل الدخول، فاضبط
`GOOGLE_CLOUD_PROJECT` أو `GOOGLE_CLOUD_PROJECT_ID` على مضيف gateway ثم
`GOOGLE_CLOUD_PROJECT` أو `GOOGLE_CLOUD_PROJECT_ID` على مضيف البوابة ثم
أعد المحاولة.
إذا فشل تسجيل الدخول قبل بدء تدفق المتصفح، فتأكد من أن الأمر المحلي `gemini`
مثبّت وموجود على `PATH`. يدعم OpenClaw كلًا من تثبيتات Homebrew
وتثبيتات npm العامة، بما في ذلك تخطيطات Windows/npm الشائعة.
مثبّت وموجود على `PATH`. يدعم OpenClaw كلاً من عمليات التثبيت عبر Homebrew
وعمليات التثبيت العامة عبر npm، بما في ذلك تخطيطات Windows/npm الشائعة.
ملاحظات استخدام JSON في Gemini CLI:
ملاحظات استخدام Gemini CLI JSON:
- يأتي نص الرد من الحقل `response` في JSON الخاص بـ CLI.
- تعود معلومات الاستخدام إلى `stats` عندما يترك CLI الحقل `usage` فارغًا.
- يتم تطبيع `stats.cached` إلى `cacheRead` في OpenClaw.
- إذا كان `stats.input` مفقودًا، فإن OpenClaw يستنتج رموز الإدخال من
- يعود الاستخدام إلى `stats` عندما يترك CLI الحقل `usage` فارغًا.
- تتم تسوية `stats.cached` إلى OpenClaw `cacheRead`.
- إذا كان `stats.input` مفقودًا، فإن OpenClaw يشتق رموز الإدخال من
`stats.input_tokens - stats.cached`.
## القدرات
## الإمكانات
| القدرة | مدعومة |
| ---------------------- | ----------------- |
| إكمالات الدردشة | نعم |
| توليد الصور | نعم |
| توليد الموسيقى | نعم |
| فهم الصور | نعم |
| نسخ الصوت | نعم |
| فهم الفيديو | نعم |
| البحث على الويب (Grounding) | نعم |
| التفكير/الاستدلال | نعم (Gemini 3.1+) |
| الإمكانية | مدعومة |
| --------------------- | ---------------- |
| إكمالات الدردشة | نعم |
| إنشاء الصور | نعم |
| إنشاء الموسيقى | نعم |
| فهم الصور | نعم |
| نسخ الصوت | نعم |
| فهم الفيديو | نعم |
| البحث على الويب (Grounding) | نعم |
| التفكير/الاستدلال | نعم (Gemini 3.1+) |
## إعادة استخدام ذاكرة Gemini المؤقتة مباشرة
## إعادة استخدام ذاكرة Gemini المؤقتة المباشرة
بالنسبة إلى تشغيلات Gemini API المباشرة (`api: "google-generative-ai"`)، يقوم OpenClaw الآن
بتمرير معرّف `cachedContent` المضبوط إلى طلبات Gemini.
بالنسبة إلى التشغيلات المباشرة لـ Gemini API ‏(`api: "google-generative-ai"`)، يقوم OpenClaw الآن
بتمرير معرّف `cachedContent` المهيأ إلى طلبات Gemini.
- اضبط المعلمات لكل نموذج أو بشكل عام باستخدام
- اضبط معلمات لكل نموذج أو معلمات عامة باستخدام
`cachedContent` أو `cached_content` القديم
- إذا وُجد الاثنان، تكون الأولوية لـ `cachedContent`
- مثال على القيمة: `cachedContents/prebuilt-context`
- يتم تطبيع استخدام إصابة ذاكرة Gemini المؤقتة إلى `cacheRead` في OpenClaw من
`cachedContentTokenCount` الصادر من المصدر
- تتم تسوية استخدام إصابة الذاكرة المؤقتة في Gemini إلى OpenClaw `cacheRead` من
`cachedContentTokenCount` الصادر من الخدمة upstream
مثال:
@ -136,21 +136,21 @@ openclaw models auth login --provider google-gemini-cli --set-default
}
```
## توليد الصور
## إنشاء الصور
يضبط مزود توليد الصور المضمّن `google` افتراضيًا على
يفترض موفر إنشاء الصور `google` المضمن افتراضيًا استخدام
`google/gemini-3.1-flash-image-preview`.
- يدعم أيضًا `google/gemini-3-pro-image-preview`
- التوليد: حتى 4 صور لكل طلب
- وضع التحرير: مفعّل، حتى 5 صور إدخال
- عناصر التحكم بالهندسة: `size` و`aspectRatio` و`resolution`
- الإنشاء: حتى 4 صور لكل طلب
- وضع التحرير: مفعّل، وحتى 5 صور إدخال
- عناصر التحكم الهندسية: `size` و`aspectRatio` و`resolution`
المزود `google-gemini-cli` المعتمد على OAuth فقط هو سطح منفصل
للاستدلال النصي. أما توليد الصور، وفهم الوسائط، وGemini Grounding فتبقى على
معرّف المزود `google`.
يُعد الموفر `google-gemini-cli` المعتمد على OAuth فقط واجهة منفصلة
للاستدلال النصي. أما إنشاء الصور، وفهم الوسائط، وGemini Grounding فتبقى على
معرّف الموفر `google`.
لاستخدام Google بوصفه مزود الصور الافتراضي:
لاستخدام Google كموفر الصور الافتراضي:
```json5
{
@ -164,20 +164,20 @@ openclaw models auth login --provider google-gemini-cli --set-default
}
```
راجع [توليد الصور](/ar/tools/image-generation) لمعلمات
الأداة المشتركة، واختيار المزود، وسلوك failover.
راجع [إنشاء الصور](/ar/tools/image-generation) للتعرّف على
معلمات الأداة المشتركة، واختيار الموفر، وسلوك التبديل الاحتياطي.
## توليد الفيديو
## إنشاء الفيديو
يسجل Google plugin المضمّن أيضًا توليد الفيديو عبر الأداة المشتركة
يسجل plugin `google` المضمن أيضًا إنشاء الفيديو عبر الأداة المشتركة
`video_generate`.
- نموذج الفيديو الافتراضي: `google/veo-3.1-fast-generate-preview`
- الأوضاع: من نص إلى فيديو، ومن صورة إلى فيديو، وتدفقات مرجعية لفيديو واحد
- الأوضاع: نص إلى فيديو، وصورة إلى فيديو، وتدفقات مرجعية لفيديو واحد
- يدعم `aspectRatio` و`resolution` و`audio`
- حد المدة الحالي: **من 4 إلى 8 ثوانٍ**
- القيد الحالي للمدة: **من 4 إلى 8 ثوانٍ**
لاستخدام Google بوصفه مزود الفيديو الافتراضي:
لاستخدام Google كموفر الفيديو الافتراضي:
```json5
{
@ -191,22 +191,22 @@ openclaw models auth login --provider google-gemini-cli --set-default
}
```
راجع [توليد الفيديو](/ar/tools/video-generation) لمعلمات
الأداة المشتركة، واختيار المزود، وسلوك failover.
راجع [إنشاء الفيديو](/ar/tools/video-generation) للتعرّف على
معلمات الأداة المشتركة، واختيار الموفر، وسلوك التبديل الاحتياطي.
## توليد الموسيقى
## إنشاء الموسيقى
يسجل Google plugin المضمّن أيضًا توليد الموسيقى عبر الأداة المشتركة
يسجل plugin `google` المضمن أيضًا إنشاء الموسيقى عبر الأداة المشتركة
`music_generate`.
- نموذج الموسيقى الافتراضي: `google/lyria-3-clip-preview`
- يدعم أيضًا `google/lyria-3-pro-preview`
- عناصر التحكم في prompt: ‏`lyrics` و`instrumental`
- عناصر التحكم في الموجّه: `lyrics` و`instrumental`
- تنسيق الإخراج: `mp3` افتراضيًا، بالإضافة إلى `wav` على `google/lyria-3-pro-preview`
- مدخلات مرجعية: حتى 10 صور
- المدخلات المرجعية: حتى 10 صور
- يتم فصل التشغيلات المدعومة بالجلسات عبر تدفق المهمة/الحالة المشترك، بما في ذلك `action: "status"`
لاستخدام Google بوصفه مزود الموسيقى الافتراضي:
لاستخدام Google كموفر الموسيقى الافتراضي:
```json5
{
@ -220,11 +220,11 @@ openclaw models auth login --provider google-gemini-cli --set-default
}
```
راجع [توليد الموسيقى](/ar/tools/music-generation) لمعلمات
الأداة المشتركة، واختيار المزود، وسلوك failover.
راجع [إنشاء الموسيقى](/ar/tools/music-generation) للتعرّف على
معلمات الأداة المشتركة، واختيار الموفر، وسلوك التبديل الاحتياطي.
## ملاحظة حول البيئة
## ملاحظة البيئة
إذا كان Gateway يعمل كخدمة daemon ‏(launchd/systemd)، فتأكد من أن `GEMINI_API_KEY`
إذا كانت البوابة تعمل كخدمة خلفية (launchd/systemd)، فتأكد من أن `GEMINI_API_KEY`
متاح لتلك العملية (على سبيل المثال، في `~/.openclaw/.env` أو عبر
`env.shellEnv`).

45
docs/ar/providers/index.md
View File

@ -1,28 +1,28 @@
---
read_when:
- تريد اختيار مزوّد نموذج
- تحتاج إلى نظرة عامة سريعة على واجهات LLM الخلفية المدعومة
summary: مزوّدو النماذج (LLMs) الذين يدعمهم OpenClaw
title: دليل المزوّدين
- تريد اختيار موفر نموذج
- تحتاج إلى نظرة عامة سريعة على الواجهات الخلفية المدعومة لـ LLM
summary: موفرو النماذج (LLMs) الذين يدعمهم OpenClaw
title: دليل الموفرين
x-i18n:
generated_at: "2026-04-07T07:21:18Z"
generated_at: "2026-04-08T02:17:25Z"
model: gpt-5.4
provider: openai
source_hash: 39d9ace35fd9452a4fb510fd980d251b6e51480e4647f051020bee2f1f2222e1
source_hash: e7bee5528b7fc9a982b3d0eaa4930cb77f7bded19a47aec00572b6fcbd823a70
source_path: providers/index.md
workflow: 15
---
# مزودو النماذج
# موفرو النماذج
يمكن لـ OpenClaw استخدام العديد من مزوّدي LLM. اختر مزوّدًا، ثم صادق، ثم اضبط
يمكن لـ OpenClaw استخدام العديد من موفري LLM. اختر موفرًا، ثم أكمل المصادقة، ثم اضبط
النموذج الافتراضي بصيغة `provider/model`.
هل تبحث عن وثائق قنوات الدردشة (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/إلخ)؟ راجع [القنوات](/ar/channels).
## البدء السريع
## بداية سريعة
1. صادق مع المزوّد (عادةً عبر `openclaw onboard`).
1. أكمل المصادقة مع الموفر (عادةً عبر `openclaw onboard`).
2. اضبط النموذج الافتراضي:
```json5
@ -31,13 +31,13 @@ x-i18n:
}
```
## وثائق المزوّدين
## وثائق الموفرين
- [Alibaba Model Studio](/ar/providers/alibaba)
- [Amazon Bedrock](/ar/providers/bedrock)
- [Anthropic (API + Claude CLI)](/ar/providers/anthropic)
- [Arcee AI (نماذج Trinity)](/ar/providers/arcee)
- [BytePlus (دولي)](/ar/concepts/model-providers#byteplus-international)
- [BytePlus (الدولي)](/ar/concepts/model-providers#byteplus-international)
- [Chutes](/ar/providers/chutes)
- [ComfyUI](/ar/providers/comfy)
- [Cloudflare AI Gateway](/ar/providers/cloudflare-ai-gateway)
@ -49,6 +49,7 @@ x-i18n:
- [Google (Gemini)](/ar/providers/google)
- [Groq (استدلال LPU)](/ar/providers/groq)
- [Hugging Face (Inference)](/ar/providers/huggingface)
- [inferrs (نماذج محلية)](/ar/providers/inferrs)
- [Kilocode](/ar/providers/kilocode)
- [LiteLLM (بوابة موحدة)](/ar/providers/litellm)
- [MiniMax](/ar/providers/minimax)
@ -68,7 +69,7 @@ x-i18n:
- [StepFun](/ar/providers/stepfun)
- [Synthetic](/ar/providers/synthetic)
- [Together AI](/ar/providers/together)
- [Venice (Venice AI، يركّز على الخصوصية)](/ar/providers/venice)
- [Venice (Venice AI، مع التركيز على الخصوصية)](/ar/providers/venice)
- [Vercel AI Gateway](/ar/providers/vercel-ai-gateway)
- [Vydra](/ar/providers/vydra)
- [vLLM (نماذج محلية)](/ar/providers/vllm)
@ -79,18 +80,18 @@ x-i18n:
## صفحات النظرة العامة المشتركة
- [متغيرات مضمّنة إضافية](/ar/providers/models#additional-bundled-provider-variants) - Anthropic Vertex وCopilot Proxy وGemini CLI OAuth
- [توليد الصور](/ar/tools/image-generation) - أداة `image_generate` المشتركة، واختيار المزوّد، والرجوع الاحتياطي
- [توليد الموسيقى](/ar/tools/music-generation) - أداة `music_generate` المشتركة، واختيار المزوّد، والرجوع الاحتياطي
- [توليد الفيديو](/ar/tools/video-generation) - أداة `video_generate` المشتركة، واختيار المزوّد، والرجوع الاحتياطي
- [المتغيرات المضمنة الإضافية](/ar/providers/models#additional-bundled-provider-variants) - Anthropic Vertex وCopilot Proxy وGemini CLI OAuth
- [إنشاء الصور](/ar/tools/image-generation) - الأداة المشتركة `image_generate`، واختيار الموفر، وسلوك التبديل الاحتياطي
- [إنشاء الموسيقى](/ar/tools/music-generation) - الأداة المشتركة `music_generate`، واختيار الموفر، وسلوك التبديل الاحتياطي
- [إنشاء الفيديو](/ar/tools/video-generation) - الأداة المشتركة `video_generate`، واختيار الموفر، وسلوك التبديل الاحتياطي
## مزودو النسخ
## موفرو النسخ الصوتي
- [Deepgram (نسخ صوتي)](/ar/providers/deepgram)
- [Deepgram (نسخ الصوت)](/ar/providers/deepgram)
## أدوات المجتمع
- [Claude Max API Proxy](/ar/providers/claude-max-api-proxy) - وكيل مجتمع لبيانات اعتماد اشتراك Claude (تحقق من سياسة/شروط Anthropic قبل الاستخدام)
- [Claude Max API Proxy](/ar/providers/claude-max-api-proxy) - وكيل مجتمعي لبيانات اعتماد اشتراك Claude (تحقق من سياسة Anthropic/الشروط قبل الاستخدام)
للاطلاع على كتالوج المزوّدين الكامل (xAI وGroq وMistral وما إلى ذلك) والإعدادات المتقدمة،
راجع [مزوّدو النماذج](/ar/concepts/model-providers).
للاطلاع على فهرس الموفرين الكامل (xAI وGroq وMistral وما إلى ذلك) والإعدادات المتقدمة،
راجع [موفرو النماذج](/ar/concepts/model-providers).

180
docs/ar/providers/inferrs.md Normal file
View File

@ -0,0 +1,180 @@
---
read_when:
- تريد تشغيل OpenClaw مقابل خادم inferrs محلي
- أنت تقدّم Gemma أو نموذجًا آخر عبر inferrs
- تحتاج إلى علامات التوافق الدقيقة في OpenClaw لـ inferrs
summary: تشغيل OpenClaw عبر inferrs ‏(خادم محلي متوافق مع OpenAI)
title: inferrs
x-i18n:
generated_at: "2026-04-08T02:18:16Z"
model: gpt-5.4
provider: openai
source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6
source_path: providers/inferrs.md
workflow: 15
---
# inferrs
يمكن لـ [inferrs](https://github.com/ericcurtin/inferrs) تقديم نماذج محلية خلف
واجهة `/v1` API متوافقة مع OpenAI. يعمل OpenClaw مع `inferrs` عبر
مسار `openai-completions` العام.
من الأفضل حاليًا التعامل مع `inferrs` على أنه واجهة خلفية مخصصة
ذاتية الاستضافة متوافقة مع OpenAI، وليس plugin موفر مخصصًا في OpenClaw.
## بداية سريعة
1. ابدأ `inferrs` مع نموذج.
مثال:
```bash
inferrs serve gg-hf-gg/gemma-4-E2B-it \
--host 127.0.0.1 \
--port 8080 \
--device metal
```
2. تحقّق من أن الخادم قابل للوصول.
```bash
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/models
```
3. أضف إدخال موفر صريحًا في OpenClaw ووجّه النموذج الافتراضي إليه.
## مثال إعداد كامل
يستخدم هذا المثال Gemma 4 على خادم `inferrs` محلي.
```json5
{
agents: {
defaults: {
model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" },
models: {
"inferrs/gg-hf-gg/gemma-4-E2B-it": {
alias: "Gemma 4 (inferrs)",
},
},
},
},
models: {
mode: "merge",
providers: {
inferrs: {
baseUrl: "http://127.0.0.1:8080/v1",
apiKey: "inferrs-local",
api: "openai-completions",
models: [
{
id: "gg-hf-gg/gemma-4-E2B-it",
name: "Gemma 4 E2B (inferrs)",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 131072,
maxTokens: 4096,
compat: {
requiresStringContent: true,
},
},
],
},
},
},
}
```
## لماذا يهم `requiresStringContent`
تقبل بعض مسارات Chat Completions في `inferrs` فقط
`messages[].content` كسلسلة نصية، وليس كمصفوفات منظَّمة لأجزاء المحتوى.
إذا فشلت تشغيلات OpenClaw مع خطأ مثل:
```text
messages[1].content: invalid type: sequence, expected a string
```
فضبط:
```json5
compat: {
requiresStringContent: true
}
```
سيقوم OpenClaw بتسطيح أجزاء المحتوى النصية الخالصة إلى سلاسل نصية عادية قبل إرسال
الطلب.
## ملاحظة Gemma ومخطط الأدوات
تقبل بعض التركيبات الحالية من `inferrs` + Gemma طلبات
`/v1/chat/completions` المباشرة الصغيرة، لكنها لا تزال تفشل في أدوار
runtime الكاملة للوكيل في OpenClaw.
إذا حدث ذلك، فجرّب هذا أولًا:
```json5
compat: {
requiresStringContent: true,
supportsTools: false
}
```
يعطّل هذا سطح مخطط الأدوات في OpenClaw لهذا النموذج ويمكن أن يقلل ضغط
الموجّه على الواجهات الخلفية المحلية الأكثر صرامة.
إذا ظلت الطلبات المباشرة الصغيرة تعمل لكن أدوار الوكيل العادية في OpenClaw لا تزال
تتعطل داخل `inferrs`، فعادةً ما تكون المشكلة المتبقية
سلوكًا من النموذج/الخادم upstream وليس من طبقة النقل في OpenClaw.
## اختبار smoke يدوي
بعد الإعداد، اختبر الطبقتين كلتيهما:
```bash
curl http://127.0.0.1:8080/v1/chat/completions \
-H 'content-type: application/json' \
-d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}'
openclaw infer model run \
--model inferrs/gg-hf-gg/gemma-4-E2B-it \
--prompt "What is 2 + 2? Reply with one short sentence." \
--json
```
إذا نجح الأمر الأول لكن فشل الثاني، فاستخدم ملاحظات استكشاف الأخطاء وإصلاحها
أدناه.
## استكشاف الأخطاء وإصلاحها
- فشل `curl /v1/models`: `inferrs` لا يعمل، أو يتعذر الوصول إليه، أو أنه
غير مربوط بالمضيف/المنفذ المتوقع.
- `messages[].content ... expected a string`: اضبط
`compat.requiresStringContent: true`.
- تنجح استدعاءات `/v1/chat/completions` المباشرة الصغيرة، لكن يفشل `openclaw infer model run`:
جرّب `compat.supportsTools: false`.
- لم يعد OpenClaw يتلقى أخطاء مخطط، لكن `inferrs` لا يزال يتعطل في أدوار
الوكيل الأكبر: تعامل مع ذلك على أنه قيد في `inferrs` أو في النموذج من upstream وخفف
ضغط الموجّه أو بدّل الواجهة الخلفية/النموذج المحلي.
## سلوك على نمط الوكيل
يُعامَل `inferrs` على أنه واجهة خلفية `/v1` متوافقة مع OpenAI على نمط الوكيل، وليس
كنقطة نهاية OpenAI أصلية.
- لا ينطبق هنا تشكيل الطلبات الخاص بـ OpenAI الأصلي فقط
- لا يوجد `service_tier`، ولا Responses `store`، ولا تلميحات ذاكرة التخزين المؤقت للموجّه، ولا
تشكيل حمولة توافق الاستدلال الخاصة بـ OpenAI
- لا يتم حقن ترويسات الإسناد المخفية في OpenClaw (`originator` و`version` و`User-Agent`)
على عناوين `inferrs` الأساسية المخصصة
## راجع أيضًا
- [النماذج المحلية](/ar/gateway/local-models)
- [استكشاف أخطاء البوابة وإصلاحها](/ar/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
- [موفرو النماذج](/ar/concepts/model-providers)

61
docs/ar/providers/mistral.md
View File

@ -1,23 +1,23 @@
---
read_when:
- تريد استخدام نماذج Mistral في OpenClaw
- تحتاج إلى onboarding لمفتاح Mistral API وmodel refs
summary: استخدم نماذج Mistral ونسخ Voxtral مع OpenClaw
- تحتاج إلى إعداد Mistral بمفتاح API ومراجع النماذج
summary: استخدم نماذج Mistral ونسخ Voxtral الصوتي مع OpenClaw
title: Mistral
x-i18n:
generated_at: "2026-04-05T12:53:24Z"
generated_at: "2026-04-08T02:18:30Z"
model: gpt-5.4
provider: openai
source_hash: 8f61b9e0656dd7e0243861ddf14b1b41a07c38bff27cef9ad0815d14c8e34408
source_hash: 4e32a0eb2a37dba6383ba338b06a8d0be600e7443aa916225794ccb0fdf46aee
source_path: providers/mistral.md
workflow: 15
---
# Mistral
يدعم OpenClaw مزود Mistral لكل من توجيه النماذج النصية/الصور (`mistral/...`) ونسخ
الصوت عبر Voxtral في فهم الوسائط.
كما يمكن استخدام Mistral في embeddings الخاصة بالذاكرة (`memorySearch.provider = "mistral"`).
يدعم OpenClaw موفر Mistral لكلٍّ من توجيه النماذج النصية/المرئية (`mistral/...`) ونسخ
الصوت عبر Voxtral ضمن فهم الوسائط.
كما يمكن استخدام Mistral لتضمينات الذاكرة (`memorySearch.provider = "mistral"`).
## إعداد CLI
@ -27,7 +27,7 @@ openclaw onboard --auth-choice mistral-api-key
openclaw onboard --mistral-api-key "$MISTRAL_API_KEY"
```
## مقتطف تكوين (مزوّد LLM)
## مقتطف إعدادات (موفر LLM)
```json5
{
@ -36,21 +36,21 @@ openclaw onboard --mistral-api-key "$MISTRAL_API_KEY"
}
```
## كتالوج LLM المضمّن
## فهرس LLM المضمن
يشحن OpenClaw حاليًا كتالوج Mistral المضمّن التالي:
يشحن OpenClaw حاليًا فهرس Mistral المضمن التالي:
| مرجع النموذج | الإدخال | السياق | الحد الأقصى للخرج | ملاحظات |
| ---------------------------------- | ------------ | ------- | ----------------- | ------------------------- |
| `mistral/mistral-large-latest` | نص، صورة | 262,144 | 16,384 | النموذج الافتراضي |
| `mistral/mistral-medium-2508` | نص، صورة | 262,144 | 8,192 | Mistral Medium 3.1 |
| `mistral/mistral-small-latest` | نص، صورة | 128,000 | 16,384 | نموذج أصغر متعدد الوسائط |
| `mistral/pixtral-large-latest` | نص، صورة | 128,000 | 32,768 | Pixtral |
| `mistral/codestral-latest` | نص | 256,000 | 4,096 | للبرمجة |
| `mistral/devstral-medium-latest` | نص | 262,144 | 32,768 | Devstral 2 |
| `mistral/magistral-small` | نص | 128,000 | 40,000 | يدعم الاستدلال |
| مرجع النموذج | الإدخال | السياق | الحد الأقصى للإخراج | ملاحظات |
| -------------------------------- | ------------ | ------- | ------------------- | ----------------------------------------------------------------- |
| `mistral/mistral-large-latest` | نص، صورة | 262,144 | 16,384 | النموذج الافتراضي |
| `mistral/mistral-medium-2508` | نص، صورة | 262,144 | 8,192 | Mistral Medium 3.1 |
| `mistral/mistral-small-latest` | نص، صورة | 128,000 | 16,384 | Mistral Small 4؛ استدلال قابل للضبط عبر `reasoning_effort` في API |
| `mistral/pixtral-large-latest` | نص، صورة | 128,000 | 32,768 | Pixtral |
| `mistral/codestral-latest` | نص | 256,000 | 4,096 | للبرمجة |
| `mistral/devstral-medium-latest` | نص | 262,144 | 32,768 | Devstral 2 |
| `mistral/magistral-small` | نص | 128,000 | 40,000 | مع تمكين الاستدلال |
## مقتطف تكوين (نسخ الصوت باستخدام Voxtral)
## مقتطف إعدادات (نسخ الصوت باستخدام Voxtral)
```json5
{
@ -65,11 +65,22 @@ openclaw onboard --mistral-api-key "$MISTRAL_API_KEY"
}
```
## الاستدلال القابل للضبط (`mistral-small-latest`)
يشير `mistral/mistral-small-latest` إلى Mistral Small 4 ويدعم [الاستدلال القابل للضبط](https://docs.mistral.ai/capabilities/reasoning/adjustable) على Chat Completions API عبر `reasoning_effort` (تقلل `none` التفكير الإضافي في المخرجات إلى الحد الأدنى؛ بينما يعرض `high` آثار التفكير الكاملة قبل الإجابة النهائية).
يربط OpenClaw مستوى **thinking** في الجلسة بـ API الخاص بـ Mistral:
- **off** / **minimal** → `none`
- **low** / **medium** / **high** / **xhigh** / **adaptive** → `high`
لا تستخدم النماذج الأخرى في فهرس Mistral المضمن هذا المعامل؛ واصل استخدام نماذج `magistral-*` عندما تريد سلوك Mistral الأصلي المعتمد على الاستدلال أولًا.
## ملاحظات
- تستخدم مصادقة Mistral القيمة `MISTRAL_API_KEY`.
- تكون القيمة الافتراضية لعنوان URL الأساسي للمزوّد هي `https://api.mistral.ai/v1`.
- النموذج الافتراضي في onboarding هو `mistral/mistral-large-latest`.
- تستخدم مصادقة Mistral المتغير `MISTRAL_API_KEY`.
- يكون عنوان URL الأساسي للموفر افتراضيًا `https://api.mistral.ai/v1`.
- النموذج الافتراضي في الإعداد الأولي هو `mistral/mistral-large-latest`.
- نموذج الصوت الافتراضي لفهم الوسائط في Mistral هو `voxtral-mini-latest`.
- يستخدم مسار نسخ الوسائط المسار `/v1/audio/transcriptions`.
- يستخدم مسار embeddings الخاصة بالذاكرة المسار `/v1/embeddings` ‏(النموذج الافتراضي: `mistral-embed`).
- يستخدم مسار نسخ الوسائط `/v1/audio/transcriptions`.
- يستخدم مسار تضمينات الذاكرة `/v1/embeddings` (النموذج الافتراضي: `mistral-embed`).

34
docs/ar/providers/models.md
View File

@ -1,27 +1,27 @@
---
read_when:
- تريد اختيار مزوّد نموذج
- تريد اختيار موفّر نموذج
- تريد أمثلة إعداد سريعة لمصادقة LLM + اختيار النموذج
summary: مزوّدو النماذج (LLMs) الذين يدعمهم OpenClaw
title: البدء السريع لمزوّد النماذج
summary: موفّرات النماذج (LLMs) التي يدعمها OpenClaw
title: البدء السريع لموفّر النموذج
x-i18n:
generated_at: "2026-04-07T07:21:28Z"
generated_at: "2026-04-08T02:18:28Z"
model: gpt-5.4
provider: openai
source_hash: 500191bfe853241096f97928ced2327a13b6f7f62003cb7452b24886c272e6ba
source_hash: 59ee4c2f993fe0ae05fe34f52bc6f3e0fc9a76b10760f56b20ad251e25ee9f20
source_path: providers/models.md
workflow: 15
---
# مزودو النماذج
# موفّرات النماذج
يمكن لـ OpenClaw استخدام العديد من مزوّدي LLM. اختر واحدًا، ثم صادق، ثم اضبط
يمكن لـ OpenClaw استخدام العديد من موفّرات LLM. اختر واحدًا، وقم بالمصادقة، ثم عيّن
النموذج الافتراضي بصيغة `provider/model`.
## البدء السريع (خطوتان)
1. صادق مع المزوّد (عادةً عبر `openclaw onboard`).
2. اضبط النموذج الافتراضي:
1. قم بالمصادقة مع الموفّر (عادةً عبر `openclaw onboard`).
2. عيّن النموذج الافتراضي:
```json5
{
@ -29,18 +29,18 @@ x-i18n:
}
```
## المزوّدون المدعومون (المجموعة الابتدائية)
## الموفّرون المدعومون (مجموعة البداية)
- [Alibaba Model Studio](/ar/providers/alibaba)
- [Anthropic (API + Claude CLI)](/ar/providers/anthropic)
- [Amazon Bedrock](/ar/providers/bedrock)
- [BytePlus (دولي)](/ar/concepts/model-providers#byteplus-international)
- [BytePlus (International)](/ar/concepts/model-providers#byteplus-international)
- [Chutes](/ar/providers/chutes)
- [ComfyUI](/ar/providers/comfy)
- [Cloudflare AI Gateway](/ar/providers/cloudflare-ai-gateway)
- [fal](/ar/providers/fal)
- [Fireworks](/ar/providers/fireworks)
- [نماذج GLM](/ar/providers/glm)
- [GLM models](/ar/providers/glm)
- [MiniMax](/ar/providers/minimax)
- [Mistral](/ar/providers/mistral)
- [Moonshot AI (Kimi + Kimi Coding)](/ar/providers/moonshot)
@ -57,11 +57,11 @@ x-i18n:
- [xAI](/ar/providers/xai)
- [Z.AI](/ar/providers/zai)
## متغيرات المزوّدات المضمّنة الإضافية
## متغيرات موفّرات إضافية مضمّنة
- `anthropic-vertex` - دعم Anthropic ضمن Google Vertex بشكل ضمني عندما تكون بيانات اعتماد Vertex متاحة؛ لا يوجد خيار مصادقة onboarding منفصل
- `anthropic-vertex` - دعم Anthropic ضمني على Google Vertex عند توفر بيانات اعتماد Vertex؛ لا يوجد خيار مصادقة منفصل أثناء الإعداد الأولي
- `copilot-proxy` - جسر Copilot Proxy محلي لـ VS Code؛ استخدم `openclaw onboard --auth-choice copilot-proxy`
- `google-gemini-cli` - تدفق OAuth غير رسمي لـ Gemini CLI؛ يتطلب تثبيت `gemini` محليًا (`brew install gemini-cli` أو `npm install -g @google/gemini-cli`)؛ النموذج الافتراضي هو `google-gemini-cli/gemini-3.1-pro-preview`؛ استخدم `openclaw onboard --auth-choice google-gemini-cli` أو `openclaw models auth login --provider google-gemini-cli --set-default`
- `google-gemini-cli` - تدفق OAuth غير رسمي لـ Gemini CLI؛ يتطلب تثبيت `gemini` محليًا (`brew install gemini-cli` أو `npm install -g @google/gemini-cli`)؛ النموذج الافتراضي هو `google-gemini-cli/gemini-3-flash-preview`؛ استخدم `openclaw onboard --auth-choice google-gemini-cli` أو `openclaw models auth login --provider google-gemini-cli --set-default`
للاطلاع على كتالوج المزوّدين الكامل (xAI وGroq وMistral وما إلى ذلك) والإعدادات المتقدمة،
راجع [مزوّدو النماذج](/ar/concepts/model-providers).
للاطلاع على كتالوج الموفّرات الكامل (xAI وGroq وMistral وغيرها) والتكوين المتقدم،
راجع [موفّرات النماذج](/ar/concepts/model-providers).

39
docs/ar/providers/nvidia.md
View File

@ -1,35 +1,35 @@
---
read_when:
- أنت تريد استخدام نماذج NVIDIA في OpenClaw
- أنت تحتاج إلى إعداد NVIDIA_API_KEY
summary: استخدم API المتوافقة مع OpenAI من NVIDIA في OpenClaw
- أنت تريد استخدام النماذج المفتوحة في OpenClaw مجانًا
- تحتاج إلى إعداد NVIDIA_API_KEY
summary: استخدم API المتوافق مع OpenAI من NVIDIA في OpenClaw
title: NVIDIA
x-i18n:
generated_at: "2026-04-05T12:53:27Z"
generated_at: "2026-04-08T02:18:31Z"
model: gpt-5.4
provider: openai
source_hash: a24c5e46c0cf0fbc63bf09c772b486dd7f8f4b52e687d3b835bb54a1176b28da
source_hash: b00f8cedaf223a33ba9f6a6dd8cf066d88cebeea52d391b871e435026182228a
source_path: providers/nvidia.md
workflow: 15
---
# NVIDIA
توفر NVIDIA واجهة API متوافقة مع OpenAI عند `https://integrate.api.nvidia.com/v1` لنماذج Nemotron وNeMo. قم بالمصادقة باستخدام مفتاح API من [NVIDIA NGC](https://catalog.ngc.nvidia.com/).
توفر NVIDIA واجهة API متوافقة مع OpenAI على `https://integrate.api.nvidia.com/v1` للنماذج المفتوحة مجانًا. قم بالمصادقة باستخدام مفتاح API من [build.nvidia.com](https://build.nvidia.com/settings/api-keys).
## إعداد CLI
قم بتصدير المفتاح مرة واحدة، ثم شغّل onboarding واضبط نموذج NVIDIA:
صدّر المفتاح مرة واحدة، ثم شغّل التهيئة واضبط نموذج NVIDIA:
```bash
export NVIDIA_API_KEY="nvapi-..."
openclaw onboard --auth-choice skip
openclaw models set nvidia/nvidia/llama-3.1-nemotron-70b-instruct
openclaw models set nvidia/nvidia/nemotron-3-super-120b-a12b
```
إذا كنت لا تزال تمرر `--token`، فتذكر أنه سيظهر في سجل shell ومخرجات `ps`؛ لذا فضّل متغير البيئة عندما يكون ذلك ممكنًا.
إذا كنت ما تزال تمرر `--token`، فتذكر أنه يُحفَظ في سجل الصدفة ومخرجات `ps`؛ ويفضل استخدام متغير البيئة عند الإمكان.
## مقتطف إعدادات
## مقتطف التكوين
```json5
{
@ -44,7 +44,7 @@ openclaw models set nvidia/nvidia/llama-3.1-nemotron-70b-instruct
},
agents: {
defaults: {
model: { primary: "nvidia/nvidia/llama-3.1-nemotron-70b-instruct" },
model: { primary: "nvidia/nvidia/nemotron-3-super-120b-a12b" },
},
},
}
@ -52,14 +52,15 @@ openclaw models set nvidia/nvidia/llama-3.1-nemotron-70b-instruct
## معرّفات النماذج
| مرجع النموذج | الاسم | السياق | الحد الأقصى للخرج |
| ---------------------------------------------------- | ----------------------------------------- | ------- | ----------------- |
| `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | NVIDIA Llama 3.1 Nemotron 70B Instruct | 131,072 | 4,096 |
| `nvidia/meta/llama-3.3-70b-instruct` | Meta Llama 3.3 70B Instruct | 131,072 | 4,096 |
| `nvidia/nvidia/mistral-nemo-minitron-8b-8k-instruct` | NVIDIA Mistral NeMo Minitron 8B Instruct | 8,192 | 2,048 |
| مرجع النموذج | الاسم | السياق | الحد الأقصى للإخراج |
| ------------------------------------------ | ---------------------------- | ------- | ---------- |
| `nvidia/nvidia/nemotron-3-super-120b-a12b` | NVIDIA Nemotron 3 Super 120B | 262,144 | 8,192 |
| `nvidia/moonshotai/kimi-k2.5` | Kimi K2.5 | 262,144 | 8,192 |
| `nvidia/minimaxai/minimax-m2.5` | Minimax M2.5 | 196,608 | 8,192 |
| `nvidia/z-ai/glm5` | GLM 5 | 202,752 | 8,192 |
## ملاحظات
- نقطة نهاية `/v1` متوافقة مع OpenAI؛ استخدم مفتاح API من NVIDIA NGC.
- يتم تمكين المزوّد تلقائيًا عند ضبط `NVIDIA_API_KEY`.
- يكون الفهرس المضمّن ثابتًا؛ وتكون التكاليف الافتراضية في المصدر هي `0`.
- نقطة نهاية `/v1` متوافقة مع OpenAI؛ استخدم مفتاح API من [build.nvidia.com](https://build.nvidia.com/).
- يتم تمكين الموفّر تلقائيًا عند تعيين `NVIDIA_API_KEY`.
- الفهرس المجمّع ثابت؛ وتكون التكاليف مضبوطة افتراضيًا على `0` في المصدر.

162
docs/ar/providers/ollama.md
View File

@ -1,45 +1,45 @@
---
read_when:
- تريد تشغيل OpenClaw مع نماذج سحابية أو محلية عبر Ollama
- تحتاج إلى إرشادات إعداد وتهيئة Ollama
summary: تشغيل OpenClaw مع Ollama ‏(النماذج السحابية والمحلية)
- تحتاج إلى إرشادات إعداد وتكوين Ollama
summary: تشغيل OpenClaw مع Ollama (النماذج السحابية والمحلية)
title: Ollama
x-i18n:
generated_at: "2026-04-05T12:54:06Z"
generated_at: "2026-04-08T02:19:04Z"
model: gpt-5.4
provider: openai
source_hash: 337b8ec3a7756e591e6d6f82e8ad13417f0f20c394ec540e8fc5756e0fc13c29
source_hash: 222ec68f7d4bb29cc7796559ddef1d5059f5159e7a51e2baa3a271ddb3abb716
source_path: providers/ollama.md
workflow: 15
---
# Ollama
Ollama هي بيئة تشغيل LLM محلية تجعل من السهل تشغيل النماذج مفتوحة المصدر على جهازك. يتكامل OpenClaw مع API الأصلية لـ Ollama ‏(`/api/chat`)، ويدعم البث واستدعاء الأدوات، ويمكنه الاكتشاف التلقائي لنماذج Ollama المحلية عندما تفعّل ذلك باستخدام `OLLAMA_API_KEY` ‏(أو ملف تعريف مصادقة) ولا تعرّف إدخالًا صريحًا لـ `models.providers.ollama`.
Ollama هو بيئة تشغيل محلية لـ LLM تجعل من السهل تشغيل النماذج مفتوحة المصدر على جهازك. يتكامل OpenClaw مع API الأصلي لـ Ollama (`/api/chat`)، ويدعم البث واستدعاء الأدوات، ويمكنه اكتشاف نماذج Ollama المحلية تلقائيًا عندما تختار ذلك عبر `OLLAMA_API_KEY` (أو ملف تعريف مصادقة) ولا تعرّف إدخال `models.providers.ollama` صريحًا.
<Warning>
**مستخدمو Ollama البعيدة**: لا تستخدم عنوان URL المتوافق مع OpenAI لمسار `/v1` ‏(`http://host:11434/v1`) مع OpenClaw. فهذا يكسر استدعاء الأدوات، وقد تخرج النماذج JSON الأدوات الخام كنص عادي. استخدم بدلًا من ذلك عنوان API الأصلي لـ Ollama: ‏`baseUrl: "http://host:11434"` ‏(من دون `/v1`).
**مستخدمو Ollama البعيد**: لا تستخدم عنوان URL المتوافق مع OpenAI الخاص بـ `/v1` (`http://host:11434/v1`) مع OpenClaw. فهذا يعطّل استدعاء الأدوات وقد تُخرج النماذج JSON الأدوات الخام كنص عادي. استخدم بدلًا من ذلك عنوان URL الخاص بـ API الأصلي لـ Ollama: ‏`baseUrl: "http://host:11434"` (من دون `/v1`).
</Warning>
## بدء سريع
## البدء السريع
### Onboarding ‏(موصى به)
### الإعداد الأولي (مستحسن)
أسرع طريقة لإعداد Ollama هي عبر onboarding:
أسرع طريقة لإعداد Ollama هي عبر الإعداد الأولي:
```bash
openclaw onboard
```
اختر **Ollama** من قائمة الموفّرين. ستقوم onboarding بما يلي:
اختر **Ollama** من قائمة الموفّرين. سيقوم الإعداد الأولي بما يلي:
1. ستسأل عن base URL الخاص بـ Ollama الذي يمكن الوصول إلى مثيلك من خلاله (الافتراضي `http://127.0.0.1:11434`).
2. ستتيح لك الاختيار بين **Cloud + Local** ‏(النماذج السحابية والنماذج المحلية) أو **Local** ‏(النماذج المحلية فقط).
3. ستفتح تدفق تسجيل دخول في المتصفح إذا اخترت **Cloud + Local** ولم تكن قد سجلت الدخول إلى ollama.com.
4. ستكتشف النماذج المتاحة وتقترح القيم الافتراضية.
5. ستنفذ `pull` للنموذج المحدد تلقائيًا إذا لم يكن متاحًا محليًا.
1. سيسألك عن عنوان URL الأساسي لـ Ollama الذي يمكن الوصول إلى المثيل من خلاله (الافتراضي `http://127.0.0.1:11434`).
2. يتيح لك اختيار **Cloud + Local** (نماذج سحابية ونماذج محلية) أو **Local** (نماذج محلية فقط).
3. يفتح تدفق تسجيل دخول عبر المتصفح إذا اخترت **Cloud + Local** ولم تكن قد سجلت الدخول إلى ollama.com.
4. يكتشف النماذج المتاحة ويقترح الإعدادات الافتراضية.
5. يسحب النموذج المحدد تلقائيًا إذا لم يكن متاحًا محليًا.
كما يُدعم الوضع غير التفاعلي:
الوضع غير التفاعلي مدعوم أيضًا:
```bash
openclaw onboard --non-interactive \
@ -47,7 +47,7 @@ openclaw onboard --non-interactive \
--accept-risk
```
يمكنك اختياريًا تحديد base URL أو نموذج مخصص:
يمكنك اختياريًا تحديد عنوان URL أساسي مخصص أو نموذج مخصص:
```bash
openclaw onboard --non-interactive \
@ -59,12 +59,12 @@ openclaw onboard --non-interactive \
### الإعداد اليدوي
1. ثبّت Ollama: ‏[https://ollama.com/download](https://ollama.com/download)
1. ثبّت Ollama: [https://ollama.com/download](https://ollama.com/download)
2. نفّذ `pull` لنموذج محلي إذا كنت تريد استدلالًا محليًا:
2. اسحب نموذجًا محليًا إذا كنت تريد استدلالًا محليًا:
```bash
ollama pull glm-4.7-flash
ollama pull gemma4
# أو
ollama pull gpt-oss:20b
# أو
@ -77,28 +77,28 @@ ollama pull llama3.3
ollama signin
```
4. شغّل onboarding واختر `Ollama`:
4. شغّل الإعداد الأولي واختر `Ollama`:
```bash
openclaw onboard
```
- `Local`: النماذج المحلية فقط
- `Cloud + Local`: النماذج المحلية بالإضافة إلى النماذج السحابية
- النماذج السحابية مثل `kimi-k2.5:cloud` و`minimax-m2.5:cloud` و`glm-5:cloud` **لا** تتطلب تنفيذ `ollama pull` محليًا
- `Local`: نماذج محلية فقط
- `Cloud + Local`: نماذج محلية بالإضافة إلى نماذج سحابية
- النماذج السحابية مثل `kimi-k2.5:cloud` و`minimax-m2.7:cloud` و`glm-5.1:cloud` لا **تتطلب** `ollama pull` محليًا
يقترح OpenClaw حاليًا:
- الافتراضي المحلي: `glm-4.7-flash`
- القيم الافتراضية السحابية: `kimi-k2.5:cloud` و`minimax-m2.5:cloud` و`glm-5:cloud`
- الافتراضي المحلي: `gemma4`
- الإعدادات الافتراضية السحابية: `kimi-k2.5:cloud` و`minimax-m2.7:cloud` و`glm-5.1:cloud`
5. إذا كنت تفضل الإعداد اليدوي، ففعّل Ollama لـ OpenClaw مباشرة (أي قيمة تعمل؛ لا تتطلب Ollama مفتاحًا حقيقيًا):
5. إذا كنت تفضّل الإعداد اليدوي، فقم بتمكين Ollama مباشرة لـ OpenClaw (أي قيمة تعمل؛ لا يتطلب Ollama مفتاحًا حقيقيًا):
```bash
# تعيين متغير البيئة
export OLLAMA_API_KEY="ollama-local"
# أو التهيئة في ملف الإعداد
# أو التكوين في ملف التكوين
openclaw config set models.providers.ollama.apiKey "ollama-local"
```
@ -106,41 +106,41 @@ openclaw config set models.providers.ollama.apiKey "ollama-local"
```bash
openclaw models list
openclaw models set ollama/glm-4.7-flash
openclaw models set ollama/gemma4
```
7. أو اضبط القيمة الافتراضية في الإعداد:
7. أو عيّن الإعداد الافتراضي في التكوين:
```json5
{
agents: {
defaults: {
model: { primary: "ollama/glm-4.7-flash" },
model: { primary: "ollama/gemma4" },
},
},
}
```
## اكتشاف النماذج (موفّر ضمني)
## اكتشاف النماذج (الموفّر الضمني)
عندما تضبط `OLLAMA_API_KEY` ‏(أو ملف تعريف مصادقة) و**لا** تعرّف `models.providers.ollama`، يكتشف OpenClaw النماذج من مثيل Ollama المحلي على `http://127.0.0.1:11434`:
عندما تعيّن `OLLAMA_API_KEY` (أو ملف تعريف مصادقة) و**لا** تعرّف `models.providers.ollama`، يكتشف OpenClaw النماذج من مثيل Ollama المحلي على `http://127.0.0.1:11434`:
- يستعلم `/api/tags`
- يستخدم عمليات lookup من نوع `/api/show` بأفضل جهد لقراءة `contextWindow` عند التوفر
- يوسم `reasoning` باستخدام heuristics لأسماء النماذج (`r1` أو `reasoning` أو `think`)
- يضبط `maxTokens` على الحد الأقصى الافتراضي للرموز في Ollama الذي يستخدمه OpenClaw
- يستعلم عن `/api/tags`
- يستخدم عمليات بحث `/api/show` بأفضل جهد لقراءة `contextWindow` عند توفره
- يضع علامة `reasoning` باستخدام استدلال يعتمد على اسم النموذج (`r1` أو `reasoning` أو `think`)
- يضبط `maxTokens` على الحد الأقصى الافتراضي للرموز في Ollama المستخدم من قبل OpenClaw
- يضبط جميع التكاليف على `0`
وهذا يتجنب إدخالات النماذج اليدوية مع إبقاء الفهرس متوافقًا مع مثيل Ollama المحلي.
يؤدي ذلك إلى تجنب إدخالات النماذج اليدوية مع إبقاء الكتالوج متوافقًا مع مثيل Ollama المحلي.
لرؤية النماذج المتاحة:
لمعرفة النماذج المتاحة:
```bash
ollama list
openclaw models list
```
لإضافة نموذج جديد، ما عليك سوى تنفيذ `pull` له باستخدام Ollama:
لإضافة نموذج جديد، ما عليك سوى سحبه عبر Ollama:
```bash
ollama pull mistral
@ -148,9 +148,9 @@ ollama pull mistral
سيتم اكتشاف النموذج الجديد تلقائيًا وسيصبح متاحًا للاستخدام.
إذا ضبطت `models.providers.ollama` صراحة، فسيتم تخطي الاكتشاف التلقائي وسيتعين عليك تعريف النماذج يدويًا (راجع أدناه).
إذا عيّنت `models.providers.ollama` صراحة، فسيتم تخطي الاكتشاف التلقائي، ويجب عليك تعريف النماذج يدويًا (انظر أدناه).
## الإعداد
## التكوين
### إعداد أساسي (اكتشاف ضمني)
@ -162,9 +162,9 @@ export OLLAMA_API_KEY="ollama-local"
### إعداد صريح (نماذج يدوية)
استخدم الإعداد الصريح عندما:
استخدم التكوين الصريح عندما:
- تعمل Ollama على مضيف/منفذ آخر.
- يعمل Ollama على مضيف/منفذ آخر.
- تريد فرض نوافذ سياق أو قوائم نماذج محددة.
- تريد تعريفات نماذج يدوية بالكامل.
@ -193,11 +193,11 @@ export OLLAMA_API_KEY="ollama-local"
}
```
إذا كان `OLLAMA_API_KEY` مضبوطًا، يمكنك حذف `apiKey` من إدخال الموفّر وسيملؤه OpenClaw من أجل فحوصات التوافر.
إذا كان `OLLAMA_API_KEY` معيّنًا، فيمكنك حذف `apiKey` من إدخال الموفّر وسيقوم OpenClaw بملئه من أجل فحوصات التوفر.
### Base URL مخصص (إعداد صريح)
### عنوان URL أساسي مخصص (تكوين صريح)
إذا كانت Ollama تعمل على مضيف أو منفذ مختلفين (يؤدي الإعداد الصريح إلى تعطيل الاكتشاف التلقائي، لذا عرّف النماذج يدويًا):
إذا كان Ollama يعمل على مضيف أو منفذ مختلفين (يعطّل التكوين الصريح الاكتشاف التلقائي، لذا عرّف النماذج يدويًا):
```json5
{
@ -205,8 +205,8 @@ export OLLAMA_API_KEY="ollama-local"
providers: {
ollama: {
apiKey: "ollama-local",
baseUrl: "http://ollama-host:11434", // بدون /v1 - استخدم عنوان API الأصلي لـ Ollama
api: "ollama", // اضبطه صراحة لضمان سلوك استدعاء الأدوات الأصلي
baseUrl: "http://ollama-host:11434", // بدون /v1 - استخدم عنوان URL الخاص بـ API الأصلي لـ Ollama
api: "ollama", // عيّنه صراحة لضمان سلوك استدعاء الأدوات الأصلي
},
},
},
@ -214,12 +214,12 @@ export OLLAMA_API_KEY="ollama-local"
```
<Warning>
لا تضف `/v1` إلى عنوان URL. فالمسار `/v1` يستخدم الوضع المتوافق مع OpenAI، حيث لا يكون استدعاء الأدوات موثوقًا. استخدم عنوان Ollama الأساسي من دون لاحقة مسار.
لا تضف `/v1` إلى عنوان URL. يستخدم المسار `/v1` الوضع المتوافق مع OpenAI، حيث لا يكون استدعاء الأدوات موثوقًا. استخدم عنوان URL الأساسي لـ Ollama من دون لاحقة مسار.
</Warning>
### اختيار النموذج
بمجرد التهيئة، تصبح كل نماذج Ollama لديك متاحة:
بمجرد التكوين، ستكون جميع نماذج Ollama الخاصة بك متاحة:
```json5
{
@ -236,24 +236,24 @@ export OLLAMA_API_KEY="ollama-local"
## النماذج السحابية
تتيح لك النماذج السحابية تشغيل نماذج مستضافة سحابيًا (مثل `kimi-k2.5:cloud` و`minimax-m2.5:cloud` و`glm-5:cloud`) إلى جانب نماذجك المحلية.
تتيح لك النماذج السحابية تشغيل نماذج مستضافة سحابيًا (على سبيل المثال `kimi-k2.5:cloud` و`minimax-m2.7:cloud` و`glm-5.1:cloud`) إلى جانب نماذجك المحلية.
لاستخدام النماذج السحابية، اختر وضع **Cloud + Local** أثناء الإعداد. ويتحقق المعالج مما إذا كنت مسجل الدخول ويفتح تدفق تسجيل دخول في المتصفح عند الحاجة. وإذا تعذّر التحقق من المصادقة، يعود المعالج إلى القيم الافتراضية للنماذج المحلية.
لاستخدام النماذج السحابية، اختر وضع **Cloud + Local** أثناء الإعداد. يتحقق المعالج مما إذا كنت قد سجلت الدخول ويفتح تدفق تسجيل دخول عبر المتصفح عند الحاجة. إذا تعذر التحقق من المصادقة، فسيعود المعالج إلى الإعدادات الافتراضية للنماذج المحلية.
يمكنك أيضًا تسجيل الدخول مباشرة على [ollama.com/signin](https://ollama.com/signin).
## Ollama Web Search
يدعم OpenClaw أيضًا **Ollama Web Search** بوصفه موفّر `web_search`
مدمجًا.
يدعم OpenClaw أيضًا **Ollama Web Search** كموفّر
`web_search` مضمّن.
- يستخدم مضيف Ollama المهيأ لديك (`models.providers.ollama.baseUrl` عندما
يكون مضبوطًا، وإلا `http://127.0.0.1:11434`).
- يستخدم مضيف Ollama المهيأ لديك (`models.providers.ollama.baseUrl` عند
تعيينه، وإلا `http://127.0.0.1:11434`).
- لا يحتاج إلى مفتاح.
- يتطلب أن تكون Ollama قيد التشغيل وأن تكون قد سجلت الدخول عبر `ollama signin`.
- يتطلب أن يكون Ollama قيد التشغيل وأن تكون قد سجلت الدخول عبر `ollama signin`.
اختر **Ollama Web Search** أثناء `openclaw onboard` أو
`openclaw configure --section web`، أو اضبط:
`openclaw configure --section web`، أو عيّن:
```json5
{
@ -267,13 +267,13 @@ export OLLAMA_API_KEY="ollama-local"
}
```
للحصول على التفاصيل الكاملة الخاصة بالإعداد والسلوك، راجع [Ollama Web Search](/tools/ollama-search).
للحصول على تفاصيل الإعداد والسلوك الكاملة، راجع [Ollama Web Search](/ar/tools/ollama-search).
## متقدم
### نماذج الاستدلال
يتعامل OpenClaw افتراضيًا مع النماذج التي تحمل أسماء مثل `deepseek-r1` أو `reasoning` أو `think` على أنها قادرة على الاستدلال:
يعامل OpenClaw النماذج ذات الأسماء مثل `deepseek-r1` أو `reasoning` أو `think` على أنها قادرة على الاستدلال افتراضيًا:
```bash
ollama pull deepseek-r1:32b
@ -281,19 +281,19 @@ ollama pull deepseek-r1:32b
### تكاليف النماذج
Ollama مجانية وتعمل محليًا، لذلك تُضبط جميع تكاليف النماذج على $0.
Ollama مجاني ويعمل محليًا، لذا يتم تعيين جميع تكاليف النماذج إلى $0.
### تهيئة البث
### تكوين البث
يستخدم تكامل OpenClaw مع Ollama **API الأصلية لـ Ollama** ‏(`/api/chat`) افتراضيًا، والتي تدعم بالكامل البث واستدعاء الأدوات في الوقت نفسه. ولا حاجة إلى أي إعداد خاص.
يستخدم تكامل OpenClaw مع Ollama **API الأصلي لـ Ollama** (`/api/chat`) افتراضيًا، وهو يدعم بالكامل البث واستدعاء الأدوات في الوقت نفسه. لا يلزم أي تكوين خاص.
#### الوضع القديم المتوافق مع OpenAI
<Warning>
**استدعاء الأدوات ليس موثوقًا في الوضع المتوافق مع OpenAI.** استخدم هذا الوضع فقط إذا كنت تحتاج إلى تنسيق OpenAI من أجل proxy ولا تعتمد على سلوك استدعاء الأدوات الأصلي.
**استدعاء الأدوات ليس موثوقًا في الوضع المتوافق مع OpenAI.** استخدم هذا الوضع فقط إذا كنت بحاجة إلى تنسيق OpenAI من أجل وكيل ولا تعتمد على سلوك استدعاء الأدوات الأصلي.
</Warning>
إذا كنت تحتاج إلى استخدام نقطة النهاية المتوافقة مع OpenAI بدلًا من ذلك (مثلًا خلف proxy لا يدعم إلا تنسيق OpenAI)، فاضبط `api: "openai-completions"` صراحة:
إذا كنت بحاجة إلى استخدام نقطة النهاية المتوافقة مع OpenAI بدلًا من ذلك (مثلًا خلف وكيل لا يدعم إلا تنسيق OpenAI)، فعيّن `api: "openai-completions"` صراحة:
```json5
{
@ -311,9 +311,9 @@ Ollama مجانية وتعمل محليًا، لذلك تُضبط جميع تك
}
```
قد لا يدعم هذا الوضع البث + استدعاء الأدوات في وقت واحد. وقد تحتاج إلى تعطيل البث باستخدام `params: { streaming: false }` في إعداد النموذج.
قد لا يدعم هذا الوضع البث + استدعاء الأدوات في الوقت نفسه. قد تحتاج إلى تعطيل البث باستخدام `params: { streaming: false }` في تكوين النموذج.
عندما يُستخدم `api: "openai-completions"` مع Ollama، يحقن OpenClaw القيمة `options.num_ctx` افتراضيًا حتى لا تعود Ollama بصمت إلى نافذة سياق مقدارها 4096. وإذا كان proxy/upstream لديك يرفض حقول `options` غير المعروفة، فقم بتعطيل هذا السلوك:
عند استخدام `api: "openai-completions"` مع Ollama، يحقن OpenClaw القيمة `options.num_ctx` افتراضيًا حتى لا يعود Ollama بصمت إلى نافذة سياق قدرها 4096. إذا كان وكيلك/خادمك الصاعد يرفض حقول `options` غير المعروفة، فعطّل هذا السلوك:
```json5
{
@ -333,19 +333,19 @@ Ollama مجانية وتعمل محليًا، لذلك تُضبط جميع تك
### نوافذ السياق
بالنسبة إلى النماذج المكتشفة تلقائيًا، يستخدم OpenClaw نافذة السياق التي يبلّغ عنها Ollama عندما تكون متاحة، وإلا فإنه يعود إلى نافذة سياق Ollama الافتراضية التي يستخدمها OpenClaw. ويمكنك تجاوز `contextWindow` و`maxTokens` في إعداد الموفّر الصريح.
بالنسبة إلى النماذج المكتشفة تلقائيًا، يستخدم OpenClaw نافذة السياق التي يبلغ عنها Ollama عند توفرها، وإلا فإنه يعود إلى نافذة سياق Ollama الافتراضية المستخدمة من قبل OpenClaw. يمكنك تجاوز `contextWindow` و`maxTokens` في تكوين الموفّر الصريح.
## استكشاف الأخطاء وإصلاحها
### لم يتم اكتشاف Ollama
تأكد من أن Ollama قيد التشغيل وأنك قد ضبطت `OLLAMA_API_KEY` ‏(أو ملف تعريف مصادقة)، وأنك **لم** تعرّف إدخالًا صريحًا لـ `models.providers.ollama`:
تأكد من أن Ollama قيد التشغيل وأنك عيّنت `OLLAMA_API_KEY` (أو ملف تعريف مصادقة)، وأنك **لم** تعرّف إدخال `models.providers.ollama` صريحًا:
```bash
ollama serve
```
وتأكد من أن API قابلة للوصول:
وتأكد من أن API يمكن الوصول إليه:
```bash
curl http://localhost:11434/api/tags
@ -353,26 +353,26 @@ curl http://localhost:11434/api/tags
### لا توجد نماذج متاحة
إذا لم يكن نموذجك مدرجًا، فإما:
إذا لم يكن نموذجك مدرجًا، فإما أن:
- أن تنفّذ `pull` للنموذج محليًا، أو
- أن تعرّف النموذج صراحة في `models.providers.ollama`.
- تسحب النموذج محليًا، أو
- تعرّف النموذج صراحة في `models.providers.ollama`.
لإضافة نماذج:
```bash
ollama list # عرض ما هو مثبت
ollama pull glm-4.7-flash
ollama list # اعرض ما هو مثبّت
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3 # أو نموذج آخر
```
### تم رفض الاتصال
تحقق من أن Ollama تعمل على المنفذ الصحيح:
تحقق من أن Ollama يعمل على المنفذ الصحيح:
```bash
# تحقق مما إذا كانت Ollama تعمل
# تحقق مما إذا كان Ollama قيد التشغيل
ps aux | grep ollama
# أو أعد تشغيل Ollama
@ -381,6 +381,6 @@ ollama serve
## راجع أيضًا
- [موفرو النماذج](/concepts/model-providers) - نظرة عامة على جميع الموفّرين
- [اختيار النموذج](/concepts/models) - كيفية اختيار النماذج
- [التهيئة](/gateway/configuration) - المرجع الكامل للإعداد
- [موفّرات النماذج](/ar/concepts/model-providers) - نظرة عامة على جميع الموفّرين
- [اختيار النموذج](/ar/concepts/models) - كيفية اختيار النماذج
- [التكوين](/ar/gateway/configuration) - المرجع الكامل للتكوين

534
docs/ar/refactor/qa.md Normal file
View File

@ -0,0 +1,534 @@
---
x-i18n:
generated_at: "2026-04-08T02:19:16Z"
model: gpt-5.4
provider: openai
source_hash: 0e156cc8e2fe946a0423862f937754a7caa1fe7e6863b50a80bff49a1c86e1e8
source_path: refactor/qa.md
workflow: 15
---
# إعادة هيكلة QA
الحالة: تم إنجاز الترحيل التأسيسي.
## الهدف
نقل QA في OpenClaw من نموذج تعريف منقسم إلى مصدر حقيقة واحد:
- بيانات السيناريو الوصفية
- الموجّهات المرسلة إلى النموذج
- الإعداد والتنظيف
- منطق أداة التشغيل
- التأكيدات ومعايير النجاح
- العناصر الناتجة وتلميحات التقرير
الحالة النهائية المطلوبة هي أداة QA عامة تقوم بتحميل ملفات تعريف سيناريو قوية بدلًا من ترميز معظم السلوك بشكل ثابت في TypeScript.
## الحالة الحالية
المصدر الأساسي للحقيقة موجود الآن في `qa/scenarios.md`.
تم تنفيذ ما يلي:
- `qa/scenarios.md`
- حزمة QA القياسية
- هوية المشغّل
- مهمة الانطلاق
- بيانات السيناريو الوصفية
- روابط المعالِجات
- `extensions/qa-lab/src/scenario-catalog.ts`
- محلّل حزمة markdown + تحقق zod
- `extensions/qa-lab/src/qa-agent-bootstrap.ts`
- عرض الخطة من حزمة markdown
- `extensions/qa-lab/src/qa-agent-workspace.ts`
- يزرع ملفات توافق مولّدة بالإضافة إلى `QA_SCENARIOS.md`
- `extensions/qa-lab/src/suite.ts`
- يختار السيناريوهات القابلة للتنفيذ عبر روابط المعالِجات المعرّفة في markdown
- بروتوكول ناقل QA + UI
- مرفقات مضمنة عامة لعرض الصور/الفيديو/الصوت/الملفات
الأسطح المنقسمة المتبقية:
- `extensions/qa-lab/src/suite.ts`
- لا يزال يملك معظم منطق المعالِجات المخصصة القابلة للتنفيذ
- `extensions/qa-lab/src/report.ts`
- لا يزال يشتق بنية التقرير من مخرجات runtime
لذا تم إصلاح انقسام مصدر الحقيقة، لكن التنفيذ لا يزال يعتمد في الغالب على المعالِجات بدلًا من أن يكون تصريحيًا بالكامل.
## كيف يبدو سطح السيناريو الحقيقي
تُظهر قراءة الحزمة الحالية بضع فئات مميزة من السيناريوهات.
### تفاعل بسيط
- خط أساس القناة
- خط أساس الرسائل المباشرة
- متابعة مترابطة
- تبديل النموذج
- استكمال الموافقة
- التفاعل/التحرير/الحذف
### تعديل الإعدادات وruntime
- تصحيح config لتعطيل skill
- إيقاظ إعادة تشغيل تطبيق config
- قلب قدرة إعادة تشغيل config
- فحص انجراف مخزون runtime
### تأكيدات نظام الملفات والمستودع
- تقرير اكتشاف المصدر/الوثائق
- بناء Lobster Invaders
- البحث عن عنصر ناتج صورة مولّدة
### تنظيم الذاكرة
- استدعاء الذاكرة
- أدوات الذاكرة في سياق القناة
- احتياط فشل الذاكرة
- ترتيب ذاكرة الجلسة
- عزل ذاكرة السلسلة
- اكتساح أحلام الذاكرة
### تكامل الأدوات وplugin
- استدعاء أدوات plugin الخاصة بـ MCP
- ظهور skill
- تثبيت skill ساخن
- إنشاء صور أصلي
- دورة كاملة للصورة
- فهم الصورة من المرفق
### متعدد الأدوار ومتعدد الأطراف
- تسليم إلى وكيل فرعي
- تجميع توليف الوكيل الفرعي
- تدفقات بأسلوب الاسترداد بعد إعادة التشغيل
هذه الفئات مهمة لأنها تحدد متطلبات DSL. لا تكفي قائمة مسطحة من موجّه + نص متوقع.
## الاتجاه
### مصدر حقيقة واحد
استخدم `qa/scenarios.md` بوصفه مصدر الحقيقة المؤلف.
يجب أن تظل الحزمة:
- قابلة للقراءة البشرية أثناء المراجعة
- قابلة للتحليل آليًا
- غنية بما يكفي لقيادة:
- تنفيذ الحزمة
- تمهيد مساحة عمل QA
- بيانات تعريف QA Lab في UI
- موجّهات الوثائق/الاكتشاف
- توليد التقارير
### تنسيق التأليف المفضّل
استخدم markdown باعتباره التنسيق الأعلى، مع YAML منظّم بداخله.
البنية الموصى بها:
- YAML frontmatter
- id
- title
- surface
- tags
- مراجع الوثائق
- مراجع الشيفرة
- تجاوزات النموذج/الموفر
- المتطلبات المسبقة
- أقسام نثرية
- الهدف
- الملاحظات
- تلميحات التصحيح
- كتل YAML مسوّرة
- setup
- steps
- assertions
- cleanup
وهذا يوفّر:
- قابلية قراءة أفضل في PR من JSON ضخم
- سياقًا أغنى من YAML صرف
- تحليلًا صارمًا وتحقق zod
يكون JSON الخام مقبولًا فقط بوصفه صيغة وسيطة مولّدة.
## البنية المقترحة لملف السيناريو
مثال:
````md
---
id: image-generation-roundtrip
title: Image generation roundtrip
surface: image
tags: [media, image, roundtrip]
models:
primary: openai/gpt-5.4
requires:
tools: [image_generate]
plugins: [openai, qa-channel]
docsRefs:
- docs/help/testing.md
- docs/concepts/model-providers.md
codeRefs:
- extensions/qa-lab/src/suite.ts
- src/gateway/chat-attachments.ts
---
# Objective
Verify generated media is reattached on the follow-up turn.
# Setup
```yaml scenario.setup
- action: config.patch
patch:
agents:
defaults:
imageGenerationModel:
primary: openai/gpt-image-1
- action: session.create
key: agent:qa:image-roundtrip
```
# Steps
```yaml scenario.steps
- action: agent.send
session: agent:qa:image-roundtrip
message: |
Image generation check: generate a QA lighthouse image and summarize it in one short sentence.
- action: artifact.capture
kind: generated-image
promptSnippet: Image generation check
saveAs: lighthouseImage
- action: agent.send
session: agent:qa:image-roundtrip
message: |
Roundtrip image inspection check: describe the generated lighthouse attachment in one short sentence.
attachments:
- fromArtifact: lighthouseImage
```
# Expect
```yaml scenario.expect
- assert: outbound.textIncludes
value: lighthouse
- assert: requestLog.matches
where:
promptIncludes: Roundtrip image inspection check
imageInputCountGte: 1
- assert: artifact.exists
ref: lighthouseImage
```
````
## قدرات أداة التشغيل التي يجب أن يغطيها DSL
استنادًا إلى الحزمة الحالية، تحتاج أداة التشغيل العامة إلى أكثر من مجرد تنفيذ الموجّهات.
### إجراءات البيئة والإعداد
- `bus.reset`
- `gateway.waitHealthy`
- `channel.waitReady`
- `session.create`
- `thread.create`
- `workspace.writeSkill`
### إجراءات دور الوكيل
- `agent.send`
- `agent.wait`
- `bus.injectInbound`
- `bus.injectOutbound`
### إجراءات الإعدادات وruntime
- `config.get`
- `config.patch`
- `config.apply`
- `gateway.restart`
- `tools.effective`
- `skills.status`
### إجراءات الملفات والعناصر الناتجة
- `file.write`
- `file.read`
- `file.delete`
- `file.touchTime`
- `artifact.captureGeneratedImage`
- `artifact.capturePath`
### إجراءات الذاكرة وcron
- `memory.indexForce`
- `memory.searchCli`
- `doctor.memory.status`
- `cron.list`
- `cron.run`
- `cron.waitCompletion`
- `sessionTranscript.write`
### إجراءات MCP
- `mcp.callTool`
### التأكيدات
- `outbound.textIncludes`
- `outbound.inThread`
- `outbound.notInRoot`
- `tool.called`
- `tool.notPresent`
- `skill.visible`
- `skill.disabled`
- `file.contains`
- `memory.contains`
- `requestLog.matches`
- `sessionStore.matches`
- `cron.managedPresent`
- `artifact.exists`
## المتغيرات ومراجع العناصر الناتجة
يجب أن يدعم DSL المخرجات المحفوظة والمراجع اللاحقة.
أمثلة من الحزمة الحالية:
- إنشاء سلسلة، ثم إعادة استخدام `threadId`
- إنشاء جلسة، ثم إعادة استخدام `sessionKey`
- إنشاء صورة، ثم إرفاق الملف في الدور التالي
- إنشاء سلسلة علامة إيقاظ، ثم التأكيد على ظهورها لاحقًا
القدرات المطلوبة:
- `saveAs`
- `${vars.name}`
- `${artifacts.name}`
- مراجع مكتوبة النوع للمسارات، ومفاتيح الجلسة، ومعرّفات السلاسل، والعلامات، ومخرجات الأدوات
من دون دعم المتغيرات، ستظل أداة التشغيل تسرّب منطق السيناريو إلى TypeScript.
## ما الذي يجب أن يبقى كمنافذ هروب
ليست أداة تشغيل تصريحية نقية بالكامل واقعية في المرحلة 1.
بعض السيناريوهات بطبيعتها كثيفة التنسيق:
- اكتساح أحلام الذاكرة
- إيقاظ إعادة تشغيل تطبيق config
- قلب قدرة إعادة تشغيل config
- حل عنصر الصورة المولّد حسب الطابع الزمني/المسار
- تقييم تقرير الاكتشاف
يجب أن تستخدم هذه السيناريوهات معالِجات مخصصة صريحة في الوقت الحالي.
القاعدة الموصى بها:
- 85-90% تصريحي
- خطوات `customHandler` صريحة للباقي الصعب
- معالِجات مخصصة مسماة وموثقة فقط
- لا شيفرة مضمنة مجهولة داخل ملف السيناريو
يبقي ذلك المحرك العام نظيفًا مع السماح بالتقدم.
## التغيير المعماري
### الحالي
يعد markdown الخاص بالسيناريو بالفعل مصدر الحقيقة لـ:
- تنفيذ الحزمة
- ملفات تمهيد مساحة العمل
- فهرس سيناريو QA Lab في UI
- بيانات التقرير الوصفية
- موجّهات الاكتشاف
التوافق المولّد:
- لا تزال مساحة العمل المزروعة تتضمن `QA_KICKOFF_TASK.md`
- لا تزال مساحة العمل المزروعة تتضمن `QA_SCENARIO_PLAN.md`
- تتضمن مساحة العمل المزروعة الآن أيضًا `QA_SCENARIOS.md`
## خطة إعادة الهيكلة
### المرحلة 1: أداة التحميل والمخطط
تمت.
- تمت إضافة `qa/scenarios.md`
- تمت إضافة محلّل لمحتوى حزمة markdown YAML المسماة
- تم التحقق باستخدام zod
- تم تحويل المستهلكين إلى الحزمة المحللة
- تمت إزالة `qa/seed-scenarios.json` و`qa/QA_KICKOFF_TASK.md` على مستوى المستودع
### المرحلة 2: المحرك العام
- تقسيم `extensions/qa-lab/src/suite.ts` إلى:
- أداة تحميل
- محرك
- سجل إجراءات
- سجل تأكيدات
- معالِجات مخصصة
- الإبقاء على الدوال المساعدة الحالية كعمليات للمحرك
المُنجَز:
- ينفذ المحرك السيناريوهات التصريحية البسيطة
ابدأ بالسيناريوهات التي تتكون غالبًا من موجّه + انتظار + تأكيد:
- متابعة مترابطة
- فهم الصورة من المرفق
- ظهور skill واستدعاؤها
- خط أساس القناة
المُنجَز:
- أول سيناريوهات حقيقية معرّفة في markdown تُشحن عبر المحرك العام
### المرحلة 4: ترحيل السيناريوهات المتوسطة
- دورة كاملة لإنشاء الصور
- أدوات الذاكرة في سياق القناة
- ترتيب ذاكرة الجلسة
- تسليم إلى وكيل فرعي
- تجميع توليف الوكيل الفرعي
المُنجَز:
- إثبات المتغيرات والعناصر الناتجة وتأكيدات الأدوات وتأكيدات سجل الطلبات
### المرحلة 5: إبقاء السيناريوهات الصعبة على المعالِجات المخصصة
- اكتساح أحلام الذاكرة
- إيقاظ إعادة تشغيل تطبيق config
- قلب قدرة إعادة تشغيل config
- انجراف مخزون runtime
المُنجَز:
- تنسيق التأليف نفسه، لكن مع كتل خطوات مخصصة صريحة عند الحاجة
### المرحلة 6: حذف خريطة السيناريوهات المرمّزة ثابتًا
بمجرد أن تصبح تغطية الحزمة جيدة بما يكفي:
- إزالة معظم التفرعات الخاصة بالسيناريوهات في TypeScript من `extensions/qa-lab/src/suite.ts`
## دعم Fake Slack / الوسائط الغنية
ناقل QA الحالي يركز على النص أولًا.
الملفات ذات الصلة:
- `extensions/qa-channel/src/protocol.ts`
- `extensions/qa-lab/src/bus-state.ts`
- `extensions/qa-lab/src/bus-queries.ts`
- `extensions/qa-lab/src/bus-server.ts`
- `extensions/qa-lab/web/src/ui-render.ts`
اليوم يدعم ناقل QA:
- النص
- التفاعلات
- السلاسل
ولا يقوم بعد بنمذجة مرفقات الوسائط المضمنة.
### عقد النقل المطلوب
أضف نموذج مرفقات ناقل QA عامًا:
```ts
type QaBusAttachment = {
id: string;
kind: "image" | "video" | "audio" | "file";
mimeType: string;
fileName?: string;
inline?: boolean;
url?: string;
contentBase64?: string;
width?: number;
height?: number;
durationMs?: number;
altText?: string;
transcript?: string;
};
```
ثم أضف `attachments?: QaBusAttachment[]` إلى:
- `QaBusMessage`
- `QaBusInboundMessageInput`
- `QaBusOutboundMessageInput`
### لماذا العام أولًا
لا تبنِ نموذج وسائط خاصًا بـ Slack فقط.
بدلًا من ذلك:
- نموذج نقل QA عام واحد
- عدة عارِضات فوقه
- دردشة QA Lab الحالية
- ويب Fake Slack مستقبلي
- أي عروض نقل وهمية أخرى
يمنع هذا ازدواجية المنطق ويسمح لسيناريوهات الوسائط بأن تظل غير مرتبطة بوسيلة نقل معينة.
### أعمال UI المطلوبة
حدّث UI الخاص بـ QA لعرض:
- معاينة صورة مضمنة
- مشغل صوت مضمن
- مشغل فيديو مضمن
- شريحة مرفق ملف
يمكن لـ UI الحالي بالفعل عرض السلاسل والتفاعلات، لذا يجب أن يضاف عرض المرفقات فوق نموذج بطاقة الرسالة نفسه.
### أعمال السيناريو التي يتيحها نقل الوسائط
بمجرد تدفق المرفقات عبر ناقل QA، يمكننا إضافة سيناريوهات دردشة وهمية أغنى:
- رد بصورة مضمنة في Fake Slack
- فهم مرفق صوتي
- فهم مرفق فيديو
- ترتيب مختلط للمرفقات
- رد في سلسلة مع الاحتفاظ بالوسائط
## التوصية
يجب أن تكون كتلة التنفيذ التالية:
1. إضافة أداة تحميل سيناريو markdown + مخطط zod
2. توليد الفهرس الحالي من markdown
3. ترحيل بعض السيناريوهات البسيطة أولًا
4. إضافة دعم مرفقات ناقل QA عام
5. عرض صورة مضمنة في UI الخاص بـ QA
6. ثم التوسع إلى الصوت والفيديو
هذا هو أصغر مسار يثبت الهدفين معًا:
- QA عام معرّف في markdown
- أسطح مراسلة وهمية أغنى
## أسئلة مفتوحة
- ما إذا كان يجب أن تسمح ملفات السيناريو بقوالب موجّهات markdown مضمنة مع استبدال المتغيرات
- ما إذا كان يجب أن يكون setup/cleanup أقسامًا مسماة أو مجرد قوائم إجراءات مرتبة
- ما إذا كان يجب أن تكون مراجع العناصر الناتجة مكتوبة النوع بقوة في المخطط أو معتمدة على السلاسل
- ما إذا كان يجب أن تعيش المعالِجات المخصصة في سجل واحد أو في سجلات بحسب السطح
- ما إذا كان يجب أن يظل ملف التوافق JSON المولّد محفوظًا في المستودع أثناء الترحيل

293
docs/ar/reference/session-management-compaction.md
View File

@ -1,32 +1,32 @@
---
read_when:
- تحتاج إلى تصحيح معرّفات الجلسات أو JSONL الخاص بالنص التفريغي أو حقول sessions.json
- تحتاج إلى تصحيح أخطاء معرّفات الجلسات أو JSONL الخاص بالنصوص أو حقول sessions.json
- أنت تغيّر سلوك الضغط التلقائي أو تضيف أعمال ترتيب "ما قبل الضغط"
- تريد تنفيذ عمليات تفريغ الذاكرة أو الأدوار النظامية الصامتة
summary: 'شرح متعمق: مخزن الجلسات + النصوص التفريغية، ودورة الحياة، والضغط (التلقائي) داخليًا'
title: شرح متعمق لإدارة الجلسات
- تريد تنفيذ عمليات تفريغ الذاكرة أو الدورات النظامية الصامتة
summary: 'شرح تفصيلي: مخزن الجلسات + النصوص، ودورة الحياة، وبواطن الضغط (التلقائي) الداخلي'
title: شرح تفصيلي لإدارة الجلسات
x-i18n:
generated_at: "2026-04-07T07:22:22Z"
generated_at: "2026-04-08T02:19:36Z"
model: gpt-5.4
provider: openai
source_hash: e379d624dd7808d3af25ed011079268ce6a9da64bb3f301598884ad4c46ab091
source_hash: cb1a4048646486693db8943a9e9c6c5bcb205f0ed532b34842de3d0346077454
source_path: reference/session-management-compaction.md
workflow: 15
---
# إدارة الجلسات والضغط (شرح متعمق)
# إدارة الجلسات والضغط (شرح تفصيلي)
تشرح هذه الوثيقة كيف يدير OpenClaw الجلسات من البداية إلى النهاية:
يوضح هذا المستند كيف يدير OpenClaw الجلسات من البداية إلى النهاية:
- **توجيه الجلسات** (كيف تُربط الرسائل الواردة بـ `sessionKey`)
- **مخزن الجلسات** (`sessions.json`) وما الذي يتتبعه
- **الاحتفاظ بالنص التفريغي** (`*.jsonl`) وبنيته
- **نظافة النص التفريغي** (إصلاحات خاصة بالمزوّد قبل التشغيل)
- **استمرارية النص** (`*.jsonl`) وبنيته
- **نظافة النص** (إصلاحات خاصة بالموفر قبل التشغيل)
- **حدود السياق** (نافذة السياق مقابل الرموز المتتبعة)
- **الضغط** (الضغط اليدوي + الضغط التلقائي) وأين يمكن ربط أعمال ما قبل الضغط
- **الترتيب الصامت** (مثلًا، عمليات كتابة الذاكرة التي يجب ألا تنتج مخرجات مرئية للمستخدم)
- **الترتيب الصامت** (مثل عمليات كتابة الذاكرة التي لا ينبغي أن تنتج مخرجات مرئية للمستخدم)
إذا كنت تريد أولًا نظرة عامة على مستوى أعلى، فابدأ من:
إذا كنت تريد أولًا نظرة عامة أعلى مستوى، فابدأ من:
- [/concepts/session](/ar/concepts/session)
- [/concepts/compaction](/ar/concepts/compaction)
@ -37,38 +37,38 @@ x-i18n:
---
## مصدر الحقيقة: Gateway
## مصدر الحقيقة: البوابة
صُمم OpenClaw حول **عملية Gateway واحدة** تملك حالة الجلسة.
تم تصميم OpenClaw حول **عملية Gateway واحدة** تمتلك حالة الجلسة.
- يجب على واجهات المستخدم (تطبيق macOS وControl UI على الويب وTUI) الاستعلام من Gateway عن قوائم الجلسات وأعداد الرموز.
- في الوضع البعيد، تكون ملفات الجلسات على المضيف البعيد؛ لذا فإن "فحص ملفات Mac المحلية لديك" لن يعكس ما يستخدمه Gateway.
- يجب على واجهات المستخدم (تطبيق macOS، وواجهة الويب Control UI، وTUI) الاستعلام من البوابة عن قوائم الجلسات وعدد الرموز.
- في الوضع البعيد، تكون ملفات الجلسة على المضيف البعيد؛ لذا فإن "فحص ملفات Mac المحلية" لن يعكس ما تستخدمه البوابة.
---
## طبقتا الاحتفاظ
## طبقتا الاستمرارية
يحتفظ OpenClaw بالجلسات على طبقتين:
يحفظ OpenClaw الجلسات في طبقتين:
1. **مخزن الجلسات (`sessions.json`)**
- خريطة مفتاح/قيمة: `sessionKey -> SessionEntry`
- صغيرة، قابلة للتغيير، وآمنة للتحرير (أو حذف الإدخالات)
- تتتبع بيانات الجلسة الوصفية (معرّف الجلسة الحالي، وآخر نشاط، والمبدلات، وعدادات الرموز، وما إلى ذلك)
- تتتبع بيانات تعريف الجلسة (معرّف الجلسة الحالي، وآخر نشاط، والمفاتيح البديلة، وعدادات الرموز، وما إلى ذلك)
2. **النص التفريغي (`<sessionId>.jsonl`)**
- نص تفريغي بإلحاق فقط مع بنية شجرية (للإدخالات `id` و`parentId`)
- يخزّن المحادثة الفعلية + استدعاءات الأدوات + ملخصات الضغط
- يُستخدم لإعادة بناء سياق النموذج للأدوار المستقبلية
2. **النص (`<sessionId>.jsonl`)**
- نص إضافي فقط ببنية شجرية (تحتوي الإدخالات على `id` + `parentId`)
- يخزن المحادثة الفعلية + استدعاءات الأدوات + ملخصات الضغط
- يُستخدم لإعادة بناء سياق النموذج للدورات المستقبلية
---
## المواقع على القرص
لكل وكيل، على مضيف Gateway:
لكل وكيل، على مضيف البوابة:
- المخزن: `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- النصوص التفريغية: `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
- جلسات مواضيع Telegram: `.../<sessionId>-topic-<threadId>.jsonl`
- النصوص: `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
- جلسات موضوعات Telegram: ‏`.../<sessionId>-topic-<threadId>.jsonl`
يحل OpenClaw هذه المسارات عبر `src/config/sessions.ts`.
@ -76,23 +76,23 @@ x-i18n:
## صيانة المخزن وعناصر التحكم في القرص
يحتوي الاحتفاظ بالجلسات على عناصر تحكم صيانة تلقائية (`session.maintenance`) لـ `sessions.json` وعناصر النص التفريغي:
تحتوي استمرارية الجلسة على عناصر تحكم صيانة تلقائية (`session.maintenance`) لـ `sessions.json` وعناصر النص:
- `mode`: `warn` (الافتراضي) أو `enforce`
- `mode`: ‏`warn` (افتراضي) أو `enforce`
- `pruneAfter`: حد عمر الإدخالات القديمة (الافتراضي `30d`)
- `maxEntries`: حد أقصى للإدخالات في `sessions.json` (الافتراضي `500`)
- `rotateBytes`: تدوير `sessions.json` عندما يصبح كبيرًا جدًا (الافتراضي `10mb`)
- `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات النص التفريغي `*.reset.<timestamp>` (الافتراضي: نفس `pruneAfter`؛ و`false` يعطّل التنظيف)
- `maxEntries`: الحد الأقصى للإدخالات في `sessions.json` (الافتراضي `500`)
- `rotateBytes`: تدوير `sessions.json` عند زيادة حجمه (الافتراضي `10mb`)
- `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات النص `*.reset.<timestamp>` (الافتراضي: نفس `pruneAfter`؛ وتعطّل `false` التنظيف)
- `maxDiskBytes`: ميزانية اختيارية لدليل الجلسات
- `highWaterBytes`: الهدف الاختياري بعد التنظيف (الافتراضي `80%` من `maxDiskBytes`)
- `highWaterBytes`: هدف اختياري بعد التنظيف (الافتراضي `80%` من `maxDiskBytes`)
ترتيب الفرض لتنظيف ميزانية القرص (`mode: "enforce"`):
ترتيب التنفيذ لتنظيف ميزانية القرص (`mode: "enforce"`):
1. إزالة أقدم عناصر النص التفريغي المؤرشفة أو اليتيمة أولًا.
2. إذا بقي الاستخدام أعلى من الهدف، تُزال أقدم إدخالات الجلسة وملفات نصوصها التفريغية.
1. إزالة أقدم عناصر النص المؤرشفة أو اليتيمة أولًا.
2. إذا ظل الاستخدام فوق الهدف، يتم إخراج أقدم إدخالات الجلسات وملفات النص الخاصة بها.
3. الاستمرار حتى يصبح الاستخدام عند `highWaterBytes` أو أقل.
في `mode: "warn"`، يبلّغ OpenClaw عن عمليات الإزالة المحتملة لكنه لا يغيّر المخزن/الملفات.
في `mode: "warn"`، يبلغ OpenClaw عن عمليات الإخراج المحتملة لكنه لا يغير المخزن/الملفات.
شغّل الصيانة عند الطلب:
@ -103,43 +103,43 @@ openclaw sessions cleanup --enforce
---
## جلسات Cron وسجلات التشغيل
## جلسات cron وسجلات التشغيل
تنشئ تشغيلات cron المعزولة أيضًا إدخالات جلسات/نصوصًا تفريغية، ولها عناصر تحكم احتفاظ مخصصة:
تنشئ عمليات cron المعزولة أيضًا إدخالات/نصوص جلسات، ولها عناصر تحكم احتفاظ مخصصة:
- `cron.sessionRetention` (الافتراضي `24h`) يزيل جلسات تشغيل cron المعزولة القديمة من مخزن الجلسات (`false` يعطّل ذلك).
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` يقلّمان ملفات `~/.openclaw/cron/runs/<jobId>.jsonl` (الافتراضيات: `2_000_000` بايت و`2000` سطر).
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` يقتطعان ملفات `~/.openclaw/cron/runs/<jobId>.jsonl` (الافتراضيان: `2_000_000` بايت و`2000` سطر).
---
## مفاتيح الجلسات (`sessionKey`)
## مفاتيح الجلسة (`sessionKey`)
يحدد `sessionKey` _أي حاوية محادثة_ أنت فيها (التوجيه + العزل).
أنماط شائعة:
الأنماط الشائعة:
- الدردشة الرئيسية/المباشرة (لكل وكيل): `agent:<agentId>:<mainKey>` (الافتراضي `main`)
- مجموعة: `agent:<agentId>:<channel>:group:<id>`
- غرفة/قناة (Discord/Slack): `agent:<agentId>:<channel>:channel:<id>` أو `...:room:<id>`
- Cron: `cron:<job.id>`
- Webhook: `hook:<uuid>` (إلا إذا تم تجاوزه)
- المجموعة: `agent:<agentId>:<channel>:group:<id>`
- الغرفة/القناة (Discord/Slack): ‏`agent:<agentId>:<channel>:channel:<id>` أو `...:room:<id>`
- Cron: ‏`cron:<job.id>`
- Webhook: ‏`hook:<uuid>` (ما لم يتم تجاوزه)
القواعد القانونية موثقة في [/concepts/session](/ar/concepts/session).
القواعد القياسية موثقة في [/concepts/session](/ar/concepts/session).
---
## معرّفات الجلسات (`sessionId`)
## معرّفات الجلسة (`sessionId`)
يشير كل `sessionKey` إلى `sessionId` حالي (ملف النص التفريغي الذي تتابع فيه المحادثة).
يشير كل `sessionKey` إلى `sessionId` حالي (ملف النص الذي يواصل المحادثة).
قواعد عملية:
قواعد عامة:
- **إعادة التعيين** (`/new` و`/reset`) تنشئ `sessionId` جديدًا لذلك `sessionKey`.
- **إعادة التعيين اليومية** (افتراضيًا الساعة 4:00 صباحًا بالتوقيت المحلي على مضيف gateway) تنشئ `sessionId` جديدًا عند الرسالة التالية بعد حد إعادة التعيين.
- **انتهاء الخمول** (`session.reset.idleMinutes` أو القديم `session.idleMinutes`) ينشئ `sessionId` جديدًا عندما تصل رسالة بعد نافذة الخمول. عند ضبط اليومي + الخمول معًا، يفوز أول ما ينتهي.
- **حارس تشعب الأصل للخيط** (`session.parentForkMaxTokens`، والافتراضي `100000`) يتخطى تشعيب النص التفريغي للأصل عندما تكون جلسة الأصل كبيرة جدًا بالفعل؛ ويبدأ الخيط الجديد من الصفر. اضبطه على `0` للتعطيل.
- **إعادة الضبط** (`/new`، ‏`/reset`) تنشئ `sessionId` جديدًا لذلك `sessionKey`.
- **إعادة الضبط اليومية** (الافتراضي 4:00 صباحًا بالتوقيت المحلي على مضيف البوابة) تنشئ `sessionId` جديدًا عند الرسالة التالية بعد حد إعادة الضبط.
- **انتهاء المهلة بسبب الخمول** (`session.reset.idleMinutes` أو القديم `session.idleMinutes`) ينشئ `sessionId` جديدًا عندما تصل رسالة بعد نافذة الخمول. وعند ضبط اليومي + الخمول معًا، يفوز الذي ينتهي أولًا.
- **حارس تشعب الأصل في السلسلة** (`session.parentForkMaxTokens`، الافتراضي `100000`) يتجاوز تشعيب نص الأصل عندما تكون الجلسة الأصلية كبيرة جدًا بالفعل؛ فتبدأ السلسلة الجديدة من الصفر. اضبط `0` للتعطيل.
تفصيل تنفيذي: يحدث القرار في `initSessionState()` في `src/auto-reply/reply/session.ts`.
تفصيل تنفيذي: يتم اتخاذ القرار في `initSessionState()` في `src/auto-reply/reply/session.ts`.
---
@ -147,46 +147,46 @@ openclaw sessions cleanup --enforce
نوع قيمة المخزن هو `SessionEntry` في `src/config/sessions.ts`.
حقول أساسية (ليست شاملة):
الحقول الأساسية (غير شاملة):
- `sessionId`: معرّف النص التفريغي الحالي (يُشتق اسم الملف منه ما لم يُضبط `sessionFile`)
- `sessionId`: معرّف النص الحالي (يُشتق اسم الملف من هذا ما لم يتم تعيين `sessionFile`)
- `updatedAt`: طابع زمني لآخر نشاط
- `sessionFile`: تجاوز اختياري صريح لمسار النص التفريغي
- `chatType`: `direct | group | room` (يساعد واجهات المستخدم وسياسة الإرسال)
- `provider` و`subject` و`room` و`space` و`displayName`: بيانات وصفية لتسمية المجموعة/القناة
- المبدلات:
- `sessionFile`: تجاوز مسار نص صريح اختياري
- `chatType`: ‏`direct | group | room` (يساعد واجهات المستخدم وسياسة الإرسال)
- `provider` و`subject` و`room` و`space` و`displayName`: بيانات تعريف لتسمية المجموعات/القنوات
- المفاتيح البديلة:
- `thinkingLevel` و`verboseLevel` و`reasoningLevel` و`elevatedLevel`
- `sendPolicy` (تجاوز لكل جلسة)
- اختيار النموذج:
- `providerOverride` و`modelOverride` و`authProfileOverride`
- عدادات الرموز (أفضل جهد / تعتمد على المزوّد):
- عدادات الرموز (أفضل جهد / حسب الموفّر):
- `inputTokens` و`outputTokens` و`totalTokens` و`contextTokens`
- `compactionCount`: عدد مرات اكتمال الضغط التلقائي لهذا `sessionKey`
- `memoryFlushAt`: طابع زمني لآخر تفريغ ذاكرة قبل الضغط
- `memoryFlushAt`: الطابع الزمني لآخر تفريغ ذاكرة قبل الضغط
- `memoryFlushCompactionCount`: عدد مرات الضغط عند آخر تشغيل للتفريغ
المخزن آمن للتحرير، لكن Gateway هو المرجع: فقد يعيد كتابة الإدخالات أو إعادة ترطيبها أثناء تشغيل الجلسات.
المخزن آمن للتحرير، لكن البوابة هي الجهة المخولة: قد تعيد كتابة الإدخالات أو إعادة ترطيبها أثناء تشغيل الجلسات.
---
## بنية النص التفريغي (`*.jsonl`)
## بنية النص (`*.jsonl`)
تُدار النصوص التفريغية بواسطة `SessionManager` من `@mariozechner/pi-coding-agent`.
تُدار النصوص بواسطة `SessionManager` الخاص بـ `@mariozechner/pi-coding-agent`.
الملف بصيغة JSONL:
- السطر الأول: ترويسة الجلسة (`type: "session"`، وتتضمن `id` و`cwd` و`timestamp` و`parentSession` الاختياري)
- السطر الأول: ترويسة الجلسة (`type: "session"`، وتتضمن `id` و`cwd` و`timestamp` و`parentSession` اختياريًا)
- ثم: إدخالات الجلسة مع `id` + `parentId` (شجرة)
أنواع إدخالات بارزة:
- `message`: رسائل المستخدم/المساعد/`toolResult`
- `custom_message`: رسائل محقونة من الإضافة _تدخل_ إلى سياق النموذج (ويمكن إخفاؤها من واجهة المستخدم)
- `custom`: حالة إضافة لا تدخل إلى سياق النموذج
- `custom_message`: رسائل محقونة من الإضافات _تدخل_ في سياق النموذج (ويمكن إخفاؤها من واجهة المستخدم)
- `custom`: حالة إضافة _لا تدخل_ في سياق النموذج
- `compaction`: ملخص ضغط محفوظ مع `firstKeptEntryId` و`tokensBefore`
- `branch_summary`: ملخص محفوظ عند التنقل داخل فرع شجري
- `branch_summary`: ملخص محفوظ عند التنقل في فرع شجري
يتعمد OpenClaw **عدم** "إصلاح" النصوص التفريغية؛ إذ يستخدم Gateway `SessionManager` لقراءتها وكتابتها.
يتعمد OpenClaw **عدم** "إصلاح" النصوص؛ إذ تستخدم البوابة `SessionManager` لقراءتها/كتابتها.
---
@ -194,13 +194,13 @@ openclaw sessions cleanup --enforce
هناك مفهومان مختلفان مهمان:
1. **نافذة سياق النموذج**: الحد الصارم لكل نموذج (الرموز المرئية للنموذج)
2. **عدادات مخزن الجلسات**: إحصاءات متدحرجة مكتوبة في `sessions.json` (تُستخدم في `/status` ولوحات المعلومات)
1. **نافذة سياق النموذج**: حد صارم لكل نموذج (الرموز المرئية للنموذج)
2. **عدادات مخزن الجلسات**: إحصاءات متدحرجة تُكتب في `sessions.json` (تُستخدم في `/status` ولوحات المعلومات)
إذا كنت تضبط الحدود:
- تأتي نافذة السياق من كتالوج النموذج (ويمكن تجاوزها عبر الإعدادات).
- إن `contextTokens` في المخزن قيمة تقديرية/إبلاغية في وقت التشغيل؛ فلا تعاملها كضمان صارم.
- تأتي نافذة السياق من فهرس النماذج (ويمكن تجاوزها عبر التكوين).
- إن `contextTokens` في المخزن هو قيمة تقديرية/تقارير وقت تشغيل؛ فلا تتعامل معه كضمان صارم.
للمزيد، راجع [/token-use](/ar/reference/token-use).
@ -208,54 +208,55 @@ openclaw sessions cleanup --enforce
## الضغط: ما هو
يلخص الضغط المحادثة الأقدم في إدخال `compaction` محفوظ داخل النص التفريغي، مع إبقاء الرسائل الحديثة سليمة.
يلخّص الضغط المحادثة الأقدم في إدخال `compaction` محفوظ في النص ويحافظ على الرسائل الحديثة كما هي.
بعد الضغط، ترى الأدوار المستقبلية:
بعد الضغط، ترى الدورات المستقبلية:
- ملخص الضغط
- الرسائل بعد `firstKeptEntryId`
الضغط **دائم** (على عكس تقليم الجلسة). راجع [/concepts/session-pruning](/ar/concepts/session-pruning).
الضغط **دائم** (على عكس تقليم الجلسات). راجع [/concepts/session-pruning](/ar/concepts/session-pruning).
## حدود كتل الضغط واقتران الأدوات
## حدود أجزاء الضغط وإقران الأدوات
عندما يقسّم OpenClaw نصًا تفريغيًا طويلًا إلى كتل ضغط، فإنه يُبقي
استدعاءات أدوات المساعد مقترنةً بإدخالات `toolResult` المطابقة لها.
عندما يقسم OpenClaw نصًا طويلًا إلى أجزاء ضغط، فإنه يحافظ
على اقتران استدعاءات أدوات المساعد مع إدخالات `toolResult` المطابقة لها.
- إذا وقع تقسيم حصة الرموز بين استدعاء أداة ونتيجته، يحرّك OpenClaw
الحد إلى رسالة استدعاء أداة المساعد بدلًا من فصل الزوج.
- إذا كانت كتلة `toolResult` لاحقة ستدفع الكتلة فوق الهدف لولا ذلك،
فإن OpenClaw يحتفظ بتلك الكتلة المعلقة للأداة ويُبقي الذيل غير الملخّص
سليمًا.
- لا تُبقي كتل استدعاء الأدوات المجهضة/الخاطئة انقسامًا معلقًا مفتوحًا.
- إذا وقع تقسيم حصة الرموز بين استدعاء أداة ونتيجتها، فإن OpenClaw
يزيح الحد إلى رسالة استدعاء أداة المساعد بدلًا من فصل
الزوج.
- إذا كانت كتلة `toolResult` اللاحقة ستدفع الجزء فوق الهدف،
فإن OpenClaw يحافظ على كتلة الأداة المعلقة هذه ويبقي الذيل غير الملخَّص
كما هو.
- لا تُبقي كتل استدعاء الأدوات الملغاة/الخاطئة انقسامًا معلقًا مفتوحًا.
---
## متى يحدث الضغط التلقائي (وقت تشغيل Pi)
في وكيل Pi المضمّن، يُفعّل الضغط التلقائي في حالتين:
في وكيل Pi المضمن، يتم تشغيل الضغط التلقائي في حالتين:
1. **استرداد الفيض**: يعيد النموذج خطأ فيض سياق
(`request_too_large` و`context length exceeded` و`input exceeds the maximum
number of tokens` و`input token count exceeds the maximum number of input
tokens` و`input is too long for the model` و`ollama error: context length
exceeded` وأشكالًا مشابهة خاصة بالمزوّد) ← ضغط ← إعادة محاولة.
2. **صيانة العتبة**: بعد دور ناجح، عندما:
1. **استرداد تجاوز الحد**: يعيد النموذج خطأ تجاوز سياق
(`request_too_large` أو `context length exceeded` أو `input exceeds the maximum
number of tokens` أو `input token count exceeds the maximum number of input
tokens` أو `input is too long for the model` أو `ollama error: context length
exceeded`، وأشكالًا مشابهة بصياغة الموفّر) ← ضغط ← إعادة محاولة.
2. **صيانة الحد**: بعد دورة ناجحة، عندما:
`contextTokens > contextWindow - reserveTokens`
حيث:
- `contextWindow` هي نافذة سياق النموذج
- `reserveTokens` هي مساحة احتياطية مخصصة للمطالبات + مخرج النموذج التالي
- `reserveTokens` هي مساحة احتياطية محفوظة للمطالبات + خرج النموذج التالي
هذه دلالات وقت تشغيل Pi (يستهلك OpenClaw الأحداث، لكن Pi هو من يقرر متى يضغط).
---
## إعدادات الضغط (`reserveTokens` و`keepRecentTokens`)
## إعدادات الضغط (`reserveTokens`، ‏`keepRecentTokens`)
توجد إعدادات ضغط Pi في إعدادات Pi:
تعيش إعدادات الضغط في Pi ضمن إعدادات Pi:
```json5
{
@ -267,92 +268,106 @@ exceeded` وأشكالًا مشابهة خاصة بالمزوّد) ← ضغط
}
```
يفرض OpenClaw أيضًا حدًا أدنى آمنًا للتشغيلات المضمّنة:
يفرض OpenClaw أيضًا حدًا أدنى آمنًا للتشغيلات المضمنة:
- إذا كان `compaction.reserveTokens < reserveTokensFloor`، يرفع OpenClaw القيمة.
- الحد الأدنى الافتراضي هو `20000` رمز.
- اضبط `agents.defaults.compaction.reserveTokensFloor: 0` لتعطيل الحد الأدنى.
- إذا كانت أعلى أصلًا، يتركها OpenClaw كما هي.
- اضبط `agents.defaults.compaction.reserveTokensFloor: 0` لتعطيل هذا الحد.
- إذا كانت القيمة أعلى بالفعل، فإن OpenClaw يتركها كما هي.
السبب: ترك مساحة كافية لأعمال "ترتيب" متعددة الأدوار (مثل كتابات الذاكرة) قبل أن يصبح الضغط أمرًا لا مفر منه.
السبب: ترك مساحة كافية لـ "أعمال الترتيب" متعددة الدورات (مثل كتابات الذاكرة) قبل أن يصبح الضغط حتميًا.
التنفيذ: `ensurePiCompactionReserveTokens()` في `src/agents/pi-settings.ts`
(ويُستدعى من `src/agents/pi-embedded-runner.ts`).
التنفيذ: ‏`ensurePiCompactionReserveTokens()` في `src/agents/pi-settings.ts`
(يُستدعى من `src/agents/pi-embedded-runner.ts`).
---
## الواجهات الظاهرة للمستخدم
## موفّرو ضغط قابلون للتوصيل
يمكن للإضافات تسجيل موفر ضغط عبر `registerCompactionProvider()` في API الخاص بالإضافة. عندما يتم تعيين `agents.defaults.compaction.provider` إلى معرّف موفر مسجل، يقوم امتداد الحماية بتفويض التلخيص إلى ذلك الموفر بدلًا من خط أنابيب `summarizeInStages` المضمن.
- `provider`: معرّف إضافة موفر ضغط مسجلة. اتركه غير معيّن لاستخدام تلخيص LLM الافتراضي.
- يؤدي تعيين `provider` إلى فرض `mode: "safeguard"`.
- تتلقى الموفّرات تعليمات الضغط نفسها وسياسة الحفاظ على المعرّفات نفسها كما في المسار المضمن.
- ما تزال الحماية تحافظ على سياق لاحقة الدورات الحديثة والدورات المنقسمة بعد خرج الموفّر.
- إذا فشل الموفّر أو أعاد نتيجة فارغة، يعود OpenClaw تلقائيًا إلى التلخيص المضمن باستخدام LLM.
- تُعاد إشارات الإيقاف/انتهاء المهلة كما هي (ولا تُبتلع) احترامًا لإلغاء المستدعي.
المصدر: `src/plugins/compaction-provider.ts`، ‏`src/agents/pi-hooks/compaction-safeguard.ts`.
---
## الأسطح المرئية للمستخدم
يمكنك ملاحظة الضغط وحالة الجلسة عبر:
- `/status` (في أي جلسة دردشة)
- `openclaw status` (CLI)
- `openclaw status` ‏(CLI)
- `openclaw sessions` / `sessions --json`
- الوضع المفصل: `🧹 Auto-compaction complete` + عدد مرات الضغط
- الوضع المطول: ‏`🧹 Auto-compaction complete` + عدد مرات الضغط
---
## الترتيب الصامت (`NO_REPLY`)
يدعم OpenClaw الأدوار "الصامتة" للمهام الخلفية التي يجب ألا يرى فيها المستخدم مخرجات وسيطة.
يدعم OpenClaw الدورات "الصامتة" للمهام الخلفية حيث يجب ألا يرى المستخدم خرجًا وسيطًا.
الاتفاقية:
الاصطلاح:
- يبدأ المساعد مخرجاته بالرمز الصامت الدقيق `NO_REPLY` /
`no_reply` للدلالة على "لا تُرسل ردًا إلى المستخدم".
- يقوم OpenClaw بإزالة/كبت هذا في طبقة التسليم.
- يكون كبت الرمز الصامت الدقيق غير حساس لحالة الأحرف، لذا يُحتسب كل من `NO_REPLY` و
`no_reply` عندما تكون الحمولة كاملةً مجرد الرمز الصامت.
- هذا مخصص فقط للأدوار الخلفية الحقيقية/من دون تسليم؛ وليس اختصارًا
- يبدأ المساعد خرجه بالرمز الصامت الدقيق `NO_REPLY` /
`no_reply` للإشارة إلى "لا تسلّم ردًا إلى المستخدم".
- يقوم OpenClaw بإزالة/كتم ذلك في طبقة التسليم.
- يكون كتم الرمز الصامت الدقيق غير حساس لحالة الأحرف، لذلك يُحتسب كل من `NO_REPLY` و
`no_reply` عندما تكون الحمولة بأكملها مجرد الرمز الصامت.
- هذا مخصص فقط للدورات الخلفية الحقيقية/التي لا يتم فيها التسليم؛ وليس اختصارًا
لطلبات المستخدم العادية القابلة للتنفيذ.
اعتبارًا من `2026.1.10`، يكبت OpenClaw أيضًا **البث المسودّي/الكتابة**
عندما تبدأ كتلة جزئية بـ `NO_REPLY`، حتى لا تُسرّب العمليات الصامتة
مخرجات جزئية في منتصف الدور.
اعتبارًا من `2026.1.10`، يقوم OpenClaw أيضًا بكتم **البث المرحلي/مؤشر الكتابة** عندما يبدأ
جزء جزئي بـ `NO_REPLY`، حتى لا تتسرب العمليات الصامتة إلى خرج جزئي في منتصف الدورة.
---
## "تفريغ الذاكرة" قبل الضغط (منفّذ)
## "تفريغ الذاكرة" قبل الضغط (منفذ)
الهدف: قبل حدوث الضغط التلقائي، شغّل دورًا وكيليًا صامتًا يكتب حالة دائمة
إلى القرص (مثل `memory/YYYY-MM-DD.md` في مساحة عمل الوكيل) حتى لا يتمكن الضغط من
الهدف: قبل حدوث الضغط التلقائي، يتم تشغيل دورة وكيلية صامتة تكتب حالة
دائمة إلى القرص (مثل `memory/YYYY-MM-DD.md` في مساحة عمل الوكيل) بحيث لا يستطيع الضغط
محو السياق الحرج.
يستخدم OpenClaw نهج **التفريغ قبل العتبة**:
يستخدم OpenClaw نهج **التفريغ قبل الحد**:
1. راقب استخدام سياق الجلسة.
2. عندما يتجاوز "عتبة ناعمة" (أقل من عتبة ضغط Pi)، شغّل توجيهًا صامتًا
من نوع "اكتب الذاكرة الآن" إلى الوكيل.
2. عندما يتجاوز "حدًا مرنًا" (أقل من حد ضغط Pi)، شغّل توجيهًا صامتًا
"اكتب الذاكرة الآن" إلى الوكيل.
3. استخدم الرمز الصامت الدقيق `NO_REPLY` / `no_reply` حتى لا يرى المستخدم
شيئًا.
أي شيء.
الإعداد (`agents.defaults.compaction.memoryFlush`):
التكوين (`agents.defaults.compaction.memoryFlush`):
- `enabled` (الافتراضي: `true`)
- `softThresholdTokens` (الافتراضي: `4000`)
- `prompt` (رسالة المستخدم لدور التفريغ)
- `systemPrompt` (مطالبة نظام إضافية تُلحق بدور التفريغ)
- `prompt` (رسالة المستخدم لدورة التفريغ)
- `systemPrompt` (مطالبة نظام إضافية تُلحق بدورة التفريغ)
ملاحظات:
- تتضمن المطالبة/مطالبة النظام الافتراضيتان تلميح `NO_REPLY` لكبت
- تتضمن المطالبة الافتراضية/مطالبة النظام الافتراضية تلميح `NO_REPLY` لكتم
التسليم.
- يعمل التفريغ مرة واحدة لكل دورة ضغط (ويُتتبّع في `sessions.json`).
- يعمل التفريغ فقط لجلسات Pi المضمّنة (تتخطاه واجهات CLI الخلفية).
- يُتخطى التفريغ عندما تكون مساحة عمل الجلسة للقراءة فقط (`workspaceAccess: "ro"` أو `"none"`).
- راجع [الذاكرة](/ar/concepts/memory) لمعرفة تخطيط ملفات مساحة العمل وأنماط الكتابة.
- يعمل التفريغ مرة واحدة لكل دورة ضغط (ويتم تتبعه في `sessions.json`).
- يعمل التفريغ فقط لجلسات Pi المضمنة (تتجاوزها الواجهات الخلفية لـ CLI).
- يتم تجاوز التفريغ عندما تكون مساحة عمل الجلسة للقراءة فقط (`workspaceAccess: "ro"` أو `"none"`).
- راجع [Memory](/ar/concepts/memory) لتخطيط ملفات مساحة العمل وأنماط الكتابة.
يكشف Pi أيضًا hook باسم `session_before_compact` في API الإضافات، لكن منطق
التفريغ في OpenClaw يعيش اليوم على جانب Gateway.
يكشف Pi أيضًا عن خطاف `session_before_compact` في API الامتداد، لكن منطق
التفريغ في OpenClaw يعيش حاليًا على جانب البوابة.
---
## قائمة التحقق لاستكشاف الأخطاء وإصلاحها
- مفتاح الجلسة خاطئ؟ ابدأ من [/concepts/session](/ar/concepts/session) وأكّد `sessionKey` في `/status`.
- عدم تطابق بين المخزن والنص التفريغي؟ أكّد مضيف Gateway ومسار المخزن من `openclaw status`.
- ضغط متكرر مزعج؟ تحقّق من:
- هل مفتاح الجلسة خاطئ؟ ابدأ من [/concepts/session](/ar/concepts/session) وأكد قيمة `sessionKey` في `/status`.
- هل يوجد عدم تطابق بين المخزن والنص؟ أكد مضيف البوابة ومسار المخزن من `openclaw status`.
- هل هناك تكرار مفرط للضغط؟ تحقق من:
- نافذة سياق النموذج (صغيرة جدًا)
- إعدادات الضغط (قد يسبب `reserveTokens` المرتفع جدًا بالنسبة إلى نافذة النموذج ضغطًا أبكر)
- تضخم `toolResult`: فعّل/اضبط تقليم الجلسة
- تسرّب الأدوار الصامتة؟ أكّد أن الرد يبدأ بـ `NO_REPLY` (رمز دقيق غير حساس لحالة الأحرف) وأنك تستخدم إصدارًا يتضمن إصلاح كبت البث.
- إعدادات الضغط (`reserveTokens` المرتفعة جدًا بالنسبة لنافذة النموذج قد تسبب ضغطًا أبكر)
- تضخم نتائج الأدوات: فعّل/اضبط تقليم الجلسة
- هل تتسرب الدورات الصامتة؟ تأكد من أن الرد يبدأ بـ `NO_REPLY` (رمز دقيق غير حساس لحالة الأحرف) وأنك تستخدم إصدارًا يتضمن إصلاح كتم البث.

108
docs/ar/reference/test.md
View File

@ -1,77 +1,77 @@
---
read_when:
- تشغيل الاختبارات أو إصلاحها
summary: كيفية تشغيل الاختبارات محليًا (vitest) ومتى تستخدم وضعي force/coverage
- عند تشغيل الاختبارات أو إصلاحها
summary: كيفية تشغيل الاختبارات محليًا (vitest) ومتى تستخدم أوضاع force/coverage
title: الاختبارات
x-i18n:
generated_at: "2026-04-07T07:22:04Z"
generated_at: "2026-04-08T02:19:21Z"
model: gpt-5.4
provider: openai
source_hash: a25236a707860307cc324f32752ad13a53e448bee9341d8df2e11655561e841c
source_hash: f7c19390f7577b3a29796c67514c96fe4c86c9fa0c7686cd4e377c6e31dcd085
source_path: reference/test.md
workflow: 15
---
# الاختبارات
- عدة الاختبار الكاملة (المجموعات، المباشر، Docker): [الاختبار](/ar/help/testing)
- عدة الاختبار الكاملة (الأجنحة، وlive، وDocker): [الاختبار](/ar/help/testing)
- `pnpm test:force`: يقتل أي عملية بوابة متبقية تحتفظ بمنفذ التحكم الافتراضي، ثم يشغّل مجموعة Vitest الكاملة بمنفذ بوابة معزول حتى لا تتصادم اختبارات الخادم مع نسخة قيد التشغيل. استخدم هذا عندما يترك تشغيل سابق للبوابة المنفذ 18789 مشغولًا.
- `pnpm test:coverage`: يشغّل مجموعة اختبارات الوحدات مع تغطية V8 ‏(عبر `vitest.unit.config.ts`). الحدود العامة هي 70% للأسطر/الفروع/الدوال/العبارات. تستبعد التغطية نقاط الدخول الثقيلة تكامليًا (ربط CLI، وجسور gateway/telegram، وخادم webchat الثابت) للحفاظ على تركيز الهدف على المنطق القابل لاختبار الوحدات.
- `pnpm test:coverage:changed`: يشغّل تغطية اختبارات الوحدات فقط للملفات التي تغيّرت منذ `origin/main`.
- `pnpm test:changed`: يوسّع مسارات git المتغيرة إلى مسارات Vitest محددة النطاق عندما يلمس الفرق فقط ملفات المصدر/الاختبار القابلة للتوجيه. أما تغييرات الإعداد/التهيئة فتعود إلى تشغيل مشاريع الجذر الأصلية بحيث تعيد تعديلات التوصيل التشغيل على نطاق واسع عند الحاجة.
- `pnpm test`: يوجّه أهداف الملفات/الأدلة الصريحة عبر مسارات Vitest محددة النطاق. أمّا التشغيلات غير المستهدفة فتنفّذ الآن عشرة إعدادات شظايا متسلسلة (`vitest.full-core-unit-src.config.ts`, `vitest.full-core-unit-security.config.ts`, `vitest.full-core-unit-ui.config.ts`, `vitest.full-core-unit-support.config.ts`, `vitest.full-core-contracts.config.ts`, `vitest.full-core-bundled.config.ts`, `vitest.full-core-runtime.config.ts`, `vitest.full-agentic.config.ts`, `vitest.full-auto-reply.config.ts`, `vitest.full-extensions.config.ts`) بدلًا من عملية مشروع جذر عملاقة واحدة.
- توجَّه الآن ملفات اختبار `plugin-sdk` و `commands` المحددة عبر مسارات خفيفة مخصصة تُبقي فقط `test/setup.ts`، وتترك الحالات الثقيلة من جهة وقت التشغيل على مساراتها الحالية.
- كما تقوم ملفات المصدر المساعدة المحددة في `plugin-sdk` و `commands` أيضًا بربط `pnpm test:changed` باختبارات شقيقة صريحة في تلك المسارات الخفيفة، بحيث تتجنب التعديلات الصغيرة على المساعدات إعادة تشغيل المجموعات الثقيلة المدعومة بوقت التشغيل.
- تنقسم `auto-reply` الآن أيضًا إلى ثلاثة إعدادات مخصصة (`core`, `top-level`, `reply`) حتى لا تهيمن عدة الردود على اختبارات الحالة/الرمز/المساعد الأخف على المستوى الأعلى.
- يستخدم إعداد Vitest الأساسي الآن افتراضيًا `pool: "threads"` و `isolate: false`، مع تمكين المشغّل المشترك غير المعزول عبر إعدادات المستودع.
- `pnpm test:force`: يقتل أي عملية gateway متبقية تحتجز منفذ التحكم الافتراضي، ثم يشغّل جناح Vitest الكامل بمنفذ gateway معزول حتى لا تتعارض اختبارات الخادم مع مثيل قيد التشغيل. استخدم هذا عندما يترك تشغيل gateway سابق المنفذ 18789 مشغولًا.
- `pnpm test:coverage`: يشغّل جناح unit مع تغطية V8 ‏(عبر `vitest.unit.config.ts`). الحدود العامة هي 70% للأسطر/الفروع/الدوال/التعليمات. تستثني التغطية نقاط الدخول الثقيلة على مستوى integration ‏(توصيلات CLI، وجسور gateway/telegram، وخادم webchat الثابت) للإبقاء على الهدف مركزًا على المنطق القابل للاختبار بوحدة.
- `pnpm test:coverage:changed`: يشغّل تغطية unit فقط للملفات المتغيرة منذ `origin/main`.
- `pnpm test:changed`: يوسّع مسارات git المتغيرة إلى مسارات Vitest محددة عندما يمس الفرق فقط ملفات المصدر/الاختبار القابلة للتوجيه. أما تغييرات config/setup فتعود إلى تشغيل root projects الأصلي بحيث تعيد تعديلات التوصيل التشغيل على نطاق واسع عند الحاجة.
- `pnpm test`: يوجّه أهداف الملفات/الأدلة الصريحة عبر مسارات Vitest محددة. أما التشغيلات غير المستهدفة فتنفذ الآن إحدى عشرة إعدادات shard متتابعة (`vitest.full-core-unit-src.config.ts` و`vitest.full-core-unit-security.config.ts` و`vitest.full-core-unit-ui.config.ts` و`vitest.full-core-unit-support.config.ts` و`vitest.full-core-support-boundary.config.ts` و`vitest.full-core-contracts.config.ts` و`vitest.full-core-bundled.config.ts` و`vitest.full-core-runtime.config.ts` و`vitest.full-agentic.config.ts` و`vitest.full-auto-reply.config.ts` و`vitest.full-extensions.config.ts`) بدلًا من عملية root-project ضخمة واحدة.
- تُوجَّه الآن ملفات الاختبار المحددة في `plugin-sdk` و`commands` عبر مسارات خفيفة مخصصة تُبقي فقط `test/setup.ts`، بينما تبقى الحالات الثقيلة على مستوى runtime في مساراتها الحالية.
- كما تربط ملفات المصدر المساعدة المحددة في `plugin-sdk` و`commands` بين `pnpm test:changed` واختبارات شقيقة صريحة في تلك المسارات الخفيفة، بحيث تتجنب تعديلات المساعدات الصغيرة إعادة تشغيل الأجنحة الثقيلة المدعومة بـ runtime.
- ينقسم `auto-reply` الآن أيضًا إلى ثلاثة إعدادات مخصصة (`core` و`top-level` و`reply`) حتى لا تهيمن حاضنة reply على اختبارات الحالة/الرمز/المساعدات الأخف في المستوى الأعلى.
- أصبح إعداد Vitest الأساسي يستخدم افتراضيًا `pool: "threads"` و`isolate: false`، مع تفعيل المشغّل المشترك غير المعزول عبر إعدادات المستودع.
- `pnpm test:channels` يشغّل `vitest.channels.config.ts`.
- `pnpm test:extensions` يشغّل `vitest.extensions.config.ts`.
- `pnpm test:extensions`: يشغّل مجموعات الإضافات/Plugins.
- `pnpm test:perf:imports`: يفعّل تقارير مدة الاستيراد + تفصيلات الاستيراد في Vitest، مع الاستمرار في استخدام توجيه المسارات المحددة النطاق لأهداف الملفات/الأدلة الصريحة.
- `pnpm test:perf:imports:changed`: يطبّق profiling الاستيراد نفسه، ولكن فقط للملفات التي تغيّرت منذ `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` يقيس أداء مسار الوضع المتغير الموجّه مقابل تشغيل مشروع الجذر الأصلي لنفس فرق git الملتزم.
- `pnpm test:perf:changed:bench -- --worktree` يقيس مجموعة تغييرات worktree الحالية من دون عمل commit أولًا.
- `pnpm test:perf:profile:main`: يكتب ملف تعريف CPU للخيط الرئيسي في Vitest ‏(`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: يكتب ملفات تعريف CPU + heap لمشغّل الوحدات (`.artifacts/vitest-runner-profile`).
- تكامل Gateway: الاشتراك اختياري عبر `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` أو `pnpm test:gateway`.
- `pnpm test:e2e`: يشغّل اختبارات smoke الشاملة للبوابة (إقران WS/HTTP/node متعدد النسخ). يستخدم افتراضيًا `threads` + `isolate: false` مع عمّال متكيّفين في `vitest.e2e.config.ts`; اضبطه عبر `OPENCLAW_E2E_WORKERS=<n>` وعيّن `OPENCLAW_E2E_VERBOSE=1` للحصول على سجلات مطوّلة.
- `pnpm test:live`: يشغّل الاختبارات المباشرة للمزوّدين (minimax/zai). يتطلب مفاتيح API و `LIVE=1` (أو `*_LIVE_TEST=1` الخاص بالمزوّد) لإزالة التخطي.
- `pnpm test:docker:openwebui`: يبدأ OpenClaw + Open WebUI داخل Docker، ويسجّل الدخول عبر Open WebUI، ويفحص `/api/models`، ثم يشغّل دردشة حقيقية عبر الوكيل من خلال `/api/chat/completions`. يتطلب مفتاح نموذج مباشر قابلًا للاستخدام (مثل OpenAI في `~/.profile`)، ويسحب صورة Open WebUI خارجية، ولا يُتوقع أن يكون مستقرًا في CI مثل مجموعات الوحدات/e2e العادية.
- `pnpm test:docker:mcp-channels`: يبدأ حاوية Gateway مهيأة مسبقًا وحاوية عميل ثانية تشغّل `openclaw mcp serve`، ثم يتحقق من اكتشاف المحادثات الموجّهة، وقراءات النصوص، وبيانات تعريف المرفقات، وسلوك قائمة انتظار الأحداث المباشرة، وتوجيه الإرسال الصادر، وإشعارات القناة + الأذونات على نمط Claude عبر جسر stdio الحقيقي. يقرأ تأكيد إشعارات Claude إطارات MCP الخام لـ stdio مباشرةً بحيث يعكس اختبار smoke ما يصدره الجسر فعلًا.
- `pnpm test:extensions`: يشغّل أجنحة extension/plugin.
- `pnpm test:perf:imports`: يفعّل تقارير مدة الاستيراد + تفصيل الاستيراد في Vitest، مع الاستمرار في استخدام توجيه المسارات المحددة لأهداف الملفات/الأدلة الصريحة.
- `pnpm test:perf:imports:changed`: profiling الاستيراد نفسه، ولكن فقط للملفات المتغيرة منذ `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` يقيس مسار الوضع المتغير الموجّه مقابل تشغيل root-project الأصلي للفرق نفسه في git بعد الالتزام.
- `pnpm test:perf:changed:bench -- --worktree` يقيس مجموعة تغييرات worktree الحالية من دون الالتزام أولًا.
- `pnpm test:perf:profile:main`: يكتب ملف CPU profile لخيط Vitest الرئيسي (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: يكتب ملفات CPU + heap profiles لمشغّل unit ‏(`.artifacts/vitest-runner-profile`).
- Gateway integration: تفعيل اختياري عبر `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` أو `pnpm test:gateway`.
- `pnpm test:e2e`: يشغّل اختبارات الفحص الأساسية end-to-end لـ gateway ‏(تعدد المثيلات، وWS/HTTP، واقتران العقد). يستخدم افتراضيًا `threads` + `isolate: false` مع عمال تكيفيين في `vitest.e2e.config.ts`؛ اضبطه عبر `OPENCLAW_E2E_WORKERS=<n>` واضبط `OPENCLAW_E2E_VERBOSE=1` للحصول على سجلات تفصيلية.
- `pnpm test:live`: يشغّل اختبارات الموفّرين الحية (`minimax`/`zai`). يتطلب مفاتيح API و`LIVE=1` ‏(أو `*_LIVE_TEST=1` الخاص بكل موفّر) لإلغاء التخطي.
- `pnpm test:docker:openwebui`: يبدأ OpenClaw + Open WebUI داخل Docker، ويسجل الدخول عبر Open WebUI، ويفحص `/api/models`، ثم يشغّل دردشة حقيقية عبر proxy من خلال `/api/chat/completions`. ويتطلب مفتاح نموذج حي صالحًا (مثل OpenAI في `~/.profile`)، ويجلب صورة Open WebUI خارجية، ولا يُتوقع أن يكون مستقرًا في CI مثل أجنحة unit/e2e العادية.
- `pnpm test:docker:mcp-channels`: يبدأ حاوية Gateway مهيأة مسبقًا وحاوية عميل ثانية تشغّل `openclaw mcp serve`، ثم يتحقق من اكتشاف المحادثات الموجّهة، وقراءة transcript، وmetadata الخاصة بالمرفقات، وسلوك قائمة الأحداث الحية، وتوجيه الإرسال الصادر، وإشعارات القنوات + الأذونات بأسلوب Claude عبر جسر stdio الحقيقي. ويقرأ تحقق إشعارات Claude إطارات stdio MCP الخام مباشرة بحيث يعكس الفحص ما يصدره الجسر فعليًا.
## بوابة PR المحلية
لفحوصات الهبوط/البوابة المحلية لـ PR، شغّل:
لإجراء فحوصات بوابة/الهبوط الخاصة بـ PR محليًا، شغّل:
- `pnpm check`
- `pnpm build`
- `pnpm test`
- `pnpm check:docs`
إذا كان `pnpm test` غير مستقر على مضيف محمّل، فأعد تشغيله مرة واحدة قبل اعتباره تراجعًا، ثم اعزله باستخدام `pnpm test <path/to/test>`. وبالنسبة إلى المضيفين المقيّدين بالذاكرة، استخدم:
إذا تعطل `pnpm test` بشكل متقطع على مضيف محمّل، فأعد تشغيله مرة واحدة قبل اعتباره تراجعًا، ثم اعزله باستخدام `pnpm test <path/to/test>`. وبالنسبة للمضيفين ذوي الذاكرة المحدودة، استخدم:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## معيار زمن استجابة النموذج (مفاتيح محلية)
## قياس زمن استجابة النموذج (مفاتيح محلية)
البرنامج النصي: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
السكربت: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
الاستخدام:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- متغيرات البيئة الاختيارية: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- متغيرات بيئة اختيارية: `MINIMAX_API_KEY` و`MINIMAX_BASE_URL` و`MINIMAX_MODEL` و`ANTHROPIC_API_KEY`
- المطالبة الافتراضية: “Reply with a single word: ok. No punctuation or extra text.”
آخر تشغيل (2025-12-31، ‏20 تشغيلًا):
آخر تشغيل (2025-12-31، 20 تشغيلًا):
- median لـ minimax: ‏1279ms ‏(الحد الأدنى 1114، الحد الأقصى 2431)
- median لـ opus: ‏2454ms ‏(الحد الأدنى 1224، الحد الأقصى 3170)
- median لـ minimax هو 1279ms ‏(الحد الأدنى 1114، والحد الأقصى 2431)
- median لـ opus هو 2454ms ‏(الحد الأدنى 1224، والحد الأقصى 3170)
## معيار بدء تشغيل CLI
## قياس بدء تشغيل CLI
البرنامج النصي: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
السكربت: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
الاستخدام:
@ -90,41 +90,41 @@ x-i18n:
- `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu`
- `pnpm tsx scripts/bench-cli-startup.ts --json`
الإعدادات المسبقة:
المجموعات المسبقة:
- `startup`: ‏`--version`، ‏`--help`، ‏`health`، ‏`health --json`، ‏`status --json`، ‏`status`
- `real`: ‏`health`، ‏`status`، ‏`status --json`، ‏`sessions`، ‏`sessions --json`، ‏`agents list --json`، ‏`gateway status`، ‏`gateway status --json`، ‏`gateway health --json`، ‏`config get gateway.port`
- `all`: كلا الإعدادين المسبقين
- `startup`: ‏`--version` و`--help` و`health` و`health --json` و`status --json` و`status`
- `real`: ‏`health` و`status` و`status --json` و`sessions` و`sessions --json` و`agents list --json` و`gateway status` و`gateway status --json` و`gateway health --json` و`config get gateway.port`
- `all`: كلتا المجموعتين المسبقتين
يتضمن الخرج `sampleCount`، وavg، وp50، وp95، والحدين الأدنى/الأقصى، وتوزيع exit-code/signal، وملخصات أعلى RSS لكل أمر. ويكتب `--cpu-prof-dir` / `--heap-prof-dir` الاختياري ملفات تعريف V8 لكل تشغيل بحيث يستخدم القياس الزمني والتقاط ملفات التعريف المشغّل نفسه.
يتضمن الإخراج `sampleCount`، وavg، وp50، وp95، وmin/max، وتوزيع exit-code/signal، وملخصات max RSS لكل أمر. وتكتب الخيارات `--cpu-prof-dir` / `--heap-prof-dir` ملفات V8 profile لكل تشغيل بحيث يستخدم الالتقاط الزمني وprofile الحاضنة نفسها.
اتفاقيات الخرج المحفوظ:
اصطلاحات الإخراج المحفوظ:
- يكتب `pnpm test:startup:bench:smoke` العنصر المستهدف لاختبار smoke في `.artifacts/cli-startup-bench-smoke.json`
- يكتب `pnpm test:startup:bench:save` عنصر المجموعة الكاملة في `.artifacts/cli-startup-bench-all.json` باستخدام `runs=5` و `warmup=1`
- يحدّث `pnpm test:startup:bench:update` ملف baseline المثبّت في `test/fixtures/cli-startup-bench.json` باستخدام `runs=5` و `warmup=1`
- يكتب `pnpm test:startup:bench:smoke` ملف smoke المستهدف في `.artifacts/cli-startup-bench-smoke.json`
- يكتب `pnpm test:startup:bench:save` ملف الجناح الكامل في `.artifacts/cli-startup-bench-all.json` باستخدام `runs=5` و`warmup=1`
- يحدّث `pnpm test:startup:bench:update` baseline fixture الملتزم في `test/fixtures/cli-startup-bench.json` باستخدام `runs=5` و`warmup=1`
الملف المثبّت:
الـ fixture الملتزم:
- `test/fixtures/cli-startup-bench.json`
- حدّثه باستخدام `pnpm test:startup:bench:update`
- قارن النتائج الحالية بالملف باستخدام `pnpm test:startup:bench:check`
- حدّثه عبر `pnpm test:startup:bench:update`
- قارن النتائج الحالية مع الـ fixture عبر `pnpm test:startup:bench:check`
## E2E للتهيئة (Docker)
## Onboarding E2E ‏(Docker)
Docker اختياري؛ وهذا مطلوب فقط لاختبارات smoke الخاصة بالتهيئة داخل الحاويات.
Docker اختياري؛ وهذا مطلوب فقط لاختبارات onboarding الأساسية المعتمدة على الحاويات.
تدفق بدء تشغيل كامل من الصفر داخل حاوية Linux نظيفة:
تدفق البدء البارد الكامل داخل حاوية Linux نظيفة:
```bash
scripts/e2e/onboard-docker.sh
```
يقود هذا البرنامج النصي المعالج التفاعلي عبر pseudo-tty، ويتحقق من ملفات الإعداد/مساحة العمل/الجلسة، ثم يبدأ البوابة ويشغّل `openclaw health`.
يقود هذا السكربت المعالج التفاعلي عبر pseudo-tty، ويتحقق من ملفات config/workspace/session، ثم يبدأ gateway ويشغّل `openclaw health`.
## اختبار smoke لاستيراد QR ‏(Docker)
## فحص QR import الأساسي (Docker)
يضمن أن `qrcode-terminal` يُحمّل ضمن بيئات Node المدعومة في Docker ‏(Node 24 افتراضيًا، وNode 22 متوافق):
يضمن تحميل `qrcode-terminal` تحت بيئات Node المدعومة في Docker ‏(Node 24 افتراضي، وNode 22 متوافق):
```bash
pnpm test:docker:qr

594
docs/ar/tools/acp-agents.md
View File

@ -1,161 +1,161 @@
---
read_when:
- تشغيل coding harnesses عبر ACP
- تشغيل حاضنات البرمجة عبر ACP
- إعداد جلسات ACP مرتبطة بالمحادثة على قنوات المراسلة
- ربط محادثة قناة رسائل بجلسة ACP مستمرة
- استكشاف أخطاء الواجهة الخلفية لـ ACP وتوصيل الإضافة وإصلاحها
- استكشاف مشكلات الواجهة الخلفية لـ ACP وتوصيلات plugin وإصلاحها
- تشغيل أوامر `/acp` من الدردشة
summary: استخدم جلسات وقت تشغيل ACP لـ Codex وClaude Code وCursor وGemini CLI وOpenClaw ACP ووكلاء harness آخرين
summary: استخدم جلسات تشغيل ACP لـ Codex وClaude Code وCursor وGemini CLI وOpenClaw ACP ووكلاء الحاضنة الآخرين
title: وكلاء ACP
x-i18n:
generated_at: "2026-04-07T07:24:22Z"
generated_at: "2026-04-08T02:22:49Z"
model: gpt-5.4
provider: openai
source_hash: fb651ab39b05e537398623ee06cb952a5a07730fc75d3f7e0de20dd3128e72c6
source_hash: 71c7c0cdae5247aefef17a0029360950a1c2987ddcee21a1bb7d78c67da52950
source_path: tools/acp-agents.md
workflow: 15
---
# وكلاء ACP
تتيح جلسات [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) لـ OpenClaw تشغيل coding harnesses خارجية (مثل Pi، وClaude Code، وCodex، وCursor، وCopilot، وOpenClaw ACP، وOpenCode، وGemini CLI، وغيرها من harnesses المدعومة عبر ACPX) من خلال إضافة واجهة خلفية لـ ACP.
تتيح جلسات [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) لـ OpenClaw تشغيل حاضنات برمجة خارجية (مثل Pi وClaude Code وCodex وCursor وCopilot وOpenClaw ACP وOpenCode وGemini CLI وغيرها من حاضنات ACPX المدعومة) عبر plugin واجهة خلفية لـ ACP.
إذا طلبت من OpenClaw بلغة طبيعية "شغّل هذا في Codex" أو "ابدأ Claude Code في سلسلة محادثة"، فيجب على OpenClaw توجيه هذا الطلب إلى وقت تشغيل ACP (وليس وقت تشغيل الوكيل الفرعي الأصلي). يتم تتبع كل عملية spawn لجلسة ACP باعتبارها [مهمة في الخلفية](/ar/automation/tasks).
إذا طلبت من OpenClaw بلغة عادية "شغّل هذا في Codex" أو "ابدأ Claude Code في سلسلة محادثة"، فيفترض أن يوجّه OpenClaw هذا الطلب إلى وقت تشغيل ACP (وليس إلى وقت تشغيل الوكيل الفرعي الأصلي). يتم تتبع كل عملية إنشاء جلسة ACP باعتبارها [مهمة في الخلفية](/ar/automation/tasks).
إذا كنت تريد أن يتصل Codex أو Claude Code كعميل MCP خارجي مباشرةً
إذا كنت تريد أن يتصل Codex أو Claude Code مباشرةً كعميل MCP خارجي
بمحادثات قنوات OpenClaw الموجودة، فاستخدم [`openclaw mcp serve`](/cli/mcp)
بدلًا من ACP.
## أي صفحة أريد؟
## ما الصفحة التي أريدها؟
هناك ثلاث واجهات متقاربة يسهل الخلط بينها:
هناك ثلاثة أسطح متقاربة يسهل الخلط بينها:
| أنت تريد أن... | استخدم هذا | ملاحظات |
| ---------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| تشغيل Codex أو Claude Code أو Gemini CLI أو harness خارجي آخر _عبر_ OpenClaw | هذه الصفحة: وكلاء ACP | جلسات مرتبطة بالدردشة، و`/acp spawn`، و`sessions_spawn({ runtime: "acp" })`، والمهام الخلفية، وعناصر تحكم وقت التشغيل |
| عرض جلسة OpenClaw Gateway _كخادم_ ACP لمحرر أو عميل | [`openclaw acp`](/cli/acp) | وضع الجسر. يتحدث IDE/العميل عبر ACP إلى OpenClaw عبر stdio/WebSocket |
| إعادة استخدام AI CLI محلي كنموذج احتياطي نصي فقط | [CLI Backends](/ar/gateway/cli-backends) | ليس ACP. لا أدوات OpenClaw، ولا عناصر تحكم ACP، ولا وقت تشغيل harness |
| تشغيل Codex أو Claude Code أو Gemini CLI أو حاضنة خارجية أخرى _عبر_ OpenClaw | هذه الصفحة: وكلاء ACP | جلسات مرتبطة بالدردشة، و`/acp spawn`، و`sessions_spawn({ runtime: "acp" })`، والمهام في الخلفية، وعناصر تحكم وقت التشغيل |
| عرض جلسة OpenClaw Gateway _باعتبارها_ خادم ACP لمحرر أو عميل | [`openclaw acp`](/cli/acp) | وضع الجسر. يتحدث IDE/العميل مع OpenClaw عبر ACP باستخدام stdio/WebSocket |
| إعادة استخدام AI CLI محلي كنموذج احتياطي نصي فقط | [الواجهات الخلفية لـ CLI](/ar/gateway/cli-backends) | ليس ACP. لا توجد أدوات OpenClaw ولا عناصر تحكم ACP ولا وقت تشغيل للحاضنة |
## هل يعمل هذا مباشرة؟
## هل يعمل هذا مباشرةً دون إعداد إضافي؟
عادةً نعم.
عادةً، نعم.
- تأتي التثبيتات الجديدة الآن مع تفعيل إضافة وقت التشغيل المضمّنة `acpx` افتراضيًا.
- تفضّل الإضافة المضمّنة `acpx` الثنائية المثبتة والمثبت إصدارها محليًا ضمن الإضافة.
- عند بدء التشغيل، يفحص OpenClaw هذه الثنائية ويصلحها ذاتيًا عند الحاجة.
- ابدأ بـ `/acp doctor` إذا كنت تريد فحص جاهزية سريعًا.
- تأتي التثبيتات الجديدة الآن مع plugin وقت التشغيل المضمّن `acpx` مفعّلًا افتراضيًا.
- يفضّل plugin `acpx` المضمّن ثنائي `acpx` المثبّت محليًا داخل plugin.
- عند بدء التشغيل، يفحص OpenClaw هذا الثنائي ويصلحه ذاتيًا إذا لزم الأمر.
- ابدأ بـ `/acp doctor` إذا كنت تريد فحصًا سريعًا للجاهزية.
ما الذي قد يحدث مع أول استخدام:
ما الذي قد يحدث مع أول استخدام رغم ذلك:
- قد يتم جلب مهايئ harness الهدف عند الطلب عبر `npx` في أول مرة تستخدم فيها ذلك الـ harness.
- يجب أن تكون مصادقة المورّد موجودة أيضًا على المضيف لذلك الـ harness.
- إذا لم يكن لدى المضيف وصول إلى npm/الشبكة، فقد تفشل عمليات الجلب الأولى للمهايئات إلى أن يتم تسخين الذاكرات المؤقتة مسبقًا أو تثبيت المهايئ بطريقة أخرى.
- قد يتم جلب مهيئ الحاضنة المستهدفة عند الطلب باستخدام `npx` في أول مرة تستخدم فيها تلك الحاضنة.
- يجب أن يكون توثيق المورّد موجودًا على المضيف لتلك الحاضنة.
- إذا لم يكن لدى المضيف وصول إلى npm/الشبكة، فقد يفشل جلب المهيئات عند أول تشغيل إلى أن تُسخّن الذاكرات المؤقتة مسبقًا أو يُثبَّت المهيئ بطريقة أخرى.
أمثلة:
- `/acp spawn codex`: يجب أن يكون OpenClaw جاهزًا لتمهيد `acpx`، لكن قد يظل مهايئ Codex ACP بحاجة إلى جلب أولي.
- `/acp spawn claude`: الأمر نفسه بالنسبة إلى مهايئ Claude ACP، بالإضافة إلى مصادقة Claude على ذلك المضيف.
- `/acp spawn codex`: ينبغي أن يكون OpenClaw جاهزًا لتهيئة `acpx`، لكن قد يظل مهيئ Codex ACP بحاجة إلى جلب أولي.
- `/acp spawn claude`: نفس الفكرة بالنسبة إلى مهيئ Claude ACP، إضافةً إلى توثيق Claude على ذلك المضيف.
## تدفق تشغيل سريع للمشغّل
## تدفق التشغيل السريع
استخدم هذا عندما تريد دليلًا عمليًا لأوامر `/acp`:
استخدم هذا عندما تريد دليلاً عمليًا لتشغيل `/acp`:
1. أنشئ جلسة:
- `/acp spawn codex --bind here`
- `/acp spawn codex --mode persistent --thread auto`
2. اعمل في المحادثة أو السلسلة المرتبطة (أو استهدف مفتاح تلك الجلسة صراحةً).
3. افحص حالة وقت التشغيل:
3. تحقّق من حالة وقت التشغيل:
- `/acp status`
4. اضبط خيارات وقت التشغيل حسب الحاجة:
- `/acp model <provider/model>`
- `/acp permissions <profile>`
- `/acp timeout <seconds>`
5. وجّه جلسة نشطة من دون استبدال السياق:
5. وجّه جلسة نشطة دون استبدال السياق:
- `/acp steer tighten logging and continue`
6. أوقف العمل:
- `/acp cancel` (إيقاف الدور الحالي)، أو
- `/acp close` (إغلاق الجلسة + إزالة الروابط)
- `/acp close` (إغلاق الجلسة + إزالة الارتباطات)
## بدء سريع للبشر
## البدء السريع للبشر
أمثلة على طلبات طبيعية:
أمثلة على الطلبات الطبيعية:
- "اربط قناة Discord هذه بـ Codex."
- "ابدأ جلسة Codex مستمرة في سلسلة هنا وأبقها مركزة."
- "ابدأ جلسة Codex مستمرة في سلسلة محادثة هنا وأبقها مركّزة."
- "شغّل هذا كجلسة Claude Code ACP لمرة واحدة ولخّص النتيجة."
- "اربط دردشة iMessage هذه بـ Codex واحتفظ بالمتابعات في مساحة العمل نفسها."
- "استخدم Gemini CLI لهذه المهمة في سلسلة، ثم احتفظ بالمتابعات في السلسلة نفسها."
- "اربط دردشة iMessage هذه بـ Codex وأبقِ المتابعات في مساحة العمل نفسها."
- "استخدم Gemini CLI لهذه المهمة في سلسلة محادثة، ثم أبقِ المتابعات في السلسلة نفسها."
ما الذي يجب أن يفعله OpenClaw:
ما الذي ينبغي أن يفعله OpenClaw:
1. اختيار `runtime: "acp"`.
2. حل هدف harness المطلوب (`agentId`، مثل `codex`).
3. إذا طُلب الربط بالمحادثة الحالية وكانت القناة النشطة تدعم ذلك، فاربط جلسة ACP بهذه المحادثة.
4. وإلا، إذا طُلب ربط سلسلة محادثة وكانت القناة الحالية تدعم ذلك، فاربط جلسة ACP بالسلسلة.
5. وجّه رسائل المتابعة المرتبطة إلى جلسة ACP نفسها حتى يتم إلغاء التركيز/الإغلاق/الانتهاء.
1. يختار `runtime: "acp"`.
2. يحلّ هدف الحاضنة المطلوب (`agentId`، مثل `codex`).
3. إذا طُلِب الربط بالمحادثة الحالية وكانت القناة النشطة تدعمه، يربط جلسة ACP بهذه المحادثة.
4. بخلاف ذلك، إذا طُلِب الربط بسلسلة محادثة وكانت القناة الحالية تدعمه، يربط جلسة ACP بهذه السلسلة.
5. يوجّه رسائل المتابعة المرتبطة إلى جلسة ACP نفسها إلى أن يتم إلغاء التركيز عنها أو إغلاقها أو انتهاء صلاحيتها.
## ACP مقابل الوكلاء الفرعيين
استخدم ACP عندما تريد وقت تشغيل harness خارجيًا. واستخدم الوكلاء الفرعيين عندما تريد تشغيلات مفوّضة أصلية لـ OpenClaw.
استخدم ACP عندما تريد وقت تشغيل لحاضنة خارجية. واستخدم الوكلاء الفرعيين عندما تريد تشغيلات مفوّضة أصلية في OpenClaw.
| المجال | جلسة ACP | تشغيل وكيل فرعي |
| -------------- | --------------------------------------- | --------------------------------- |
| وقت التشغيل | إضافة واجهة خلفية لـ ACP (مثل acpx) | وقت تشغيل الوكيل الفرعي الأصلي في OpenClaw |
| مفتاح الجلسة | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| الأوامر الرئيسية | `/acp ...` | `/subagents ...` |
| أداة spawn | `sessions_spawn` مع `runtime:"acp"` | `sessions_spawn` (وقت التشغيل الافتراضي) |
| المجال | جلسة ACP | تشغيل وكيل فرعي |
| --------------- | ---------------------------------- | ------------------------------------ |
| وقت التشغيل | plugin واجهة خلفية لـ ACP (مثل acpx) | وقت تشغيل الوكيل الفرعي الأصلي في OpenClaw |
| مفتاح الجلسة | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| الأوامر الرئيسية | `/acp ...` | `/subagents ...` |
| أداة الإنشاء | `sessions_spawn` مع `runtime:"acp"` | `sessions_spawn` (وقت التشغيل الافتراضي) |
راجع أيضًا [الوكلاء الفرعيون](/ar/tools/subagents).
## كيف يشغّل ACP ‏Claude Code
بالنسبة إلى Claude Code عبر ACP، تكون الطبقات كالتالي:
عند تشغيل Claude Code عبر ACP، تكون البنية كالتالي:
1. مستوى التحكم في جلسة OpenClaw ACP
2. إضافة وقت التشغيل المضمّنة `acpx`
3. مهايئ Claude ACP
4. آلية وقت التشغيل/الجلسة على جهة Claude
1. مستوى التحكم في جلسات OpenClaw ACP
2. plugin وقت التشغيل المضمّن `acpx`
3. مهيئ Claude ACP
4. آليات وقت التشغيل/الجلسة الخاصة بـ Claude
تمييز مهم:
- ACP Claude عبارة عن جلسة harness مع عناصر تحكم ACP، واستئناف الجلسة، وتتبع المهام في الخلفية، وإمكانية اختيارية للربط بالمحادثة/السلسلة.
- الواجهات الخلفية لـ CLI هي بيئات تشغيل احتياطية نصية فقط محلية ومنفصلة. راجع [CLI Backends](/ar/gateway/cli-backends).
- Claude عبر ACP هو جلسة حاضنة مع عناصر تحكم ACP، واستئناف الجلسة، وتتبع المهام في الخلفية، وإمكانية ربط المحادثة/سلسلة المحادثة اختياريًا.
- الواجهات الخلفية لـ CLI هي أوقات تشغيل احتياطية محلية منفصلة تعمل بالنص فقط. راجع [الواجهات الخلفية لـ CLI](/ar/gateway/cli-backends).
بالنسبة إلى المشغّلين، القاعدة العملية هي:
- إذا كنت تريد `/acp spawn`، أو جلسات قابلة للربط، أو عناصر تحكم وقت التشغيل، أو عمل harness مستمرًا: استخدم ACP
- إذا كنت تريد `/acp spawn` أو جلسات قابلة للربط أو عناصر تحكم لوقت التشغيل أو عمل حاضنة مستمر: استخدم ACP
- إذا كنت تريد احتياطيًا نصيًا محليًا بسيطًا عبر CLI الخام: استخدم الواجهات الخلفية لـ CLI
## الجلسات المرتبطة
### الربط بالمحادثة الحالية
### الارتباطات بالمحادثة الحالية
استخدم `/acp spawn <harness> --bind here` عندما تريد أن تصبح المحادثة الحالية مساحة عمل ACP دائمة من دون إنشاء سلسلة فرعية.
استخدم `/acp spawn <harness> --bind here` عندما تريد أن تصبح المحادثة الحالية مساحة عمل ACP دائمة دون إنشاء سلسلة محادثة فرعية.
السلوك:
- يواصل OpenClaw امتلاك نقل القناة، والمصادقة، والأمان، والتسليم.
- تُثبَّت المحادثة الحالية على مفتاح جلسة ACP الذي تم إنشاؤه.
- يظل OpenClaw مسؤولًا عن نقل القناة، والتوثيق، والسلامة، والتسليم.
- تُثبَّت المحادثة الحالية على مفتاح جلسة ACP المنشأة.
- تُوجَّه رسائل المتابعة في تلك المحادثة إلى جلسة ACP نفسها.
- يعيد `/new` و`/reset` تعيين جلسة ACP المرتبطة نفسها في مكانها.
- يغلق `/acp close` الجلسة ويزيل ربط المحادثة الحالية.
- يغلق `/acp close` الجلسة ويزيل ارتباط المحادثة الحالية.
ماذا يعني هذا عمليًا:
ما الذي يعنيه هذا عمليًا:
- يحافظ `--bind here` على سطح الدردشة نفسه. في Discord، تبقى القناة الحالية هي القناة الحالية.
- يمكن أن ينشئ `--bind here` مع ذلك جلسة ACP جديدة إذا كنت تبدأ عملًا جديدًا. يقوم الربط بإلحاق تلك الجلسة بالمحادثة الحالية.
- لا ينشئ `--bind here` سلسلة Discord فرعية أو موضوع Telegram بحد ذاته.
- يمكن لوقت تشغيل ACP مع ذلك أن يملك دليل عمل خاصًا به (`cwd`) أو مساحة عمل على القرص يديرها backend. تكون مساحة عمل وقت التشغيل هذه منفصلة عن سطح الدردشة ولا تعني وجود سلسلة رسائل جديدة.
- إذا أجريت spawn إلى وكيل ACP مختلف ولم تمرر `--cwd`، فسيرث OpenClaw مساحة عمل **الوكيل الهدف** افتراضيًا، وليس مساحة عمل طالب الطلب.
- `--bind here` يبقي نفس سطح الدردشة. على Discord، تظل القناة الحالية هي القناة الحالية.
- يمكن أن ينشئ `--bind here` جلسة ACP جديدة إذا كنت تنشئ عملًا جديدًا. يربط هذا الخيار تلك الجلسة بالمحادثة الحالية.
- لا ينشئ `--bind here` سلسلة Discord فرعية أو موضوع Telegram من تلقاء نفسه.
- يمكن لوقت تشغيل ACP أن يملك مع ذلك دليل عمل (`cwd`) خاصًا به أو مساحة عمل يديرها في الواجهة الخلفية على القرص. مساحة عمل وقت التشغيل هذه منفصلة عن سطح الدردشة ولا تعني وجود سلسلة رسائل جديدة.
- إذا أنشأت جلسة لوكيل ACP مختلف ولم تمرر `--cwd`، فسيرث OpenClaw مساحة عمل **الوكيل المستهدف** افتراضيًا، وليس مساحة عمل الطالب.
- إذا كان مسار مساحة العمل الموروثة هذا مفقودًا (`ENOENT`/`ENOTDIR`)، فسيعود OpenClaw إلى `cwd` الافتراضي للواجهة الخلفية بدلًا من إعادة استخدام الشجرة الخاطئة بصمت.
- إذا كانت مساحة العمل الموروثة موجودة لكن لا يمكن الوصول إليها (مثل `EACCES`)، فستُرجع عملية spawn خطأ الوصول الحقيقي بدلًا من إسقاط `cwd`.
- إذا كانت مساحة العمل الموروثة موجودة لكن تعذر الوصول إليها (مثل `EACCES`)، فستعيد عملية الإنشاء خطأ الوصول الحقيقي بدلًا من إسقاط `cwd`.
النموذج الذهني:
- سطح الدردشة: المكان الذي يواصل فيه الأشخاص الحديث (`Discord channel`، `Telegram topic`، `iMessage chat`)
- سطح الدردشة: المكان الذي يواصل فيه الناس الحديث (`Discord channel`، `Telegram topic`، `iMessage chat`)
- جلسة ACP: حالة وقت تشغيل Codex/Claude/Gemini الدائمة التي يوجّه إليها OpenClaw
- سلسلة/موضوع فرعي: سطح رسائل إضافي اختياري لا يُنشأ إلا بواسطة `--thread ...`
- مساحة عمل وقت التشغيل: موقع نظام الملفات الذي يعمل فيه الـ harness (`cwd`، نسخة المستودع المحلية، مساحة العمل التي تديرها الواجهة الخلفية)
- سلسلة/موضوع فرعي: سطح مراسلة إضافي اختياري يُنشأ فقط بواسطة `--thread ...`
- مساحة عمل وقت التشغيل: موقع نظام الملفات الذي تعمل فيه الحاضنة (`cwd`، أو مستودع تم سحبه، أو مساحة عمل للواجهة الخلفية)
أمثلة:
@ -165,81 +165,81 @@ x-i18n:
دعم الربط بالمحادثة الحالية:
- يمكن لقنوات الدردشة/الرسائل التي تعلن دعم الربط بالمحادثة الحالية استخدام `--bind here` عبر مسار الربط المشترك للمحادثات.
- يمكن للقنوات ذات دلالات السلاسل/الموضوعات المخصصة مع ذلك توفير جعل معياري خاص بالقناة خلف الواجهة المشتركة نفسها.
- يمكن لقنوات الدردشة/الرسائل التي تعلن دعم ربط المحادثة الحالية استخدام `--bind here` عبر مسار ربط المحادثة المشترك.
- يمكن للقنوات ذات دلالات السلاسل/الموضوعات المخصصة أن توفّر مع ذلك تسوية خاصة بالقناة خلف الواجهة المشتركة نفسها.
- يعني `--bind here` دائمًا "اربط المحادثة الحالية في مكانها".
- تستخدم عمليات الربط العامة بالمحادثة الحالية مخزن الربط المشترك في OpenClaw وتبقى بعد عمليات إعادة تشغيل البوابة العادية.
- تستخدم الارتباطات العامة للمحادثة الحالية مخزن الربط المشترك في OpenClaw وتستمر عبر عمليات إعادة تشغيل البوابة العادية.
ملاحظات:
- إن `--bind here` و `--thread ...` متنافيان في `/acp spawn`.
- في Discord، يربط `--bind here` القناة أو السلسلة الحالية في مكانها. لا تكون `spawnAcpSessions` مطلوبة إلا عندما يحتاج OpenClaw إلى إنشاء سلسلة فرعية من أجل `--thread auto|here`.
- إذا لم تكشف القناة النشطة روابط ACP للمحادثة الحالية، فسيُرجع OpenClaw رسالة واضحة بعدم الدعم.
- أسئلة `resume` و"جلسة جديدة" هي أسئلة خاصة بجلسة ACP، وليست أسئلة خاصة بالقناة. يمكنك إعادة استخدام حالة وقت التشغيل أو استبدالها من دون تغيير سطح الدردشة الحالي.
- `--bind here` و`--thread ...` متنافيان في `/acp spawn`.
- على Discord، يربط `--bind here` القناة الحالية أو السلسلة الحالية في مكانها. لا تكون `spawnAcpSessions` مطلوبة إلا عندما يحتاج OpenClaw إلى إنشاء سلسلة فرعية لـ `--thread auto|here`.
- إذا كانت القناة النشطة لا تعرض ارتباطات ACP للمحادثة الحالية، فسيعيد OpenClaw رسالة واضحة بعدم الدعم.
- أسئلة `resume` و"الجلسة الجديدة" هي أسئلة تخص جلسات ACP، وليست أسئلة تخص القنوات. يمكنك إعادة استخدام حالة وقت التشغيل أو استبدالها دون تغيير سطح الدردشة الحالي.
### الجلسات المرتبطة بالسلسلة
### الجلسات المرتبطة بسلسلة محادثة
عندما تكون روابط السلاسل مفعّلة لمهايئ قناة، يمكن ربط جلسات ACP بالسلاسل:
عندما تكون ارتباطات السلاسل مفعّلة لمهايئ القناة، يمكن ربط جلسات ACP بسلاسل المحادثة:
- يربط OpenClaw سلسلةً بجلسة ACP مستهدفة.
- يربط OpenClaw سلسلة محادثة بجلسة ACP مستهدفة.
- تُوجَّه رسائل المتابعة في تلك السلسلة إلى جلسة ACP المرتبطة.
- يُسلَّم خرج ACP إلى السلسلة نفسها.
- تؤدي عملية unfocus/close/archive/انتهاء المهلة عند الخمول أو انتهاء max-age إلى إزالة الربط.
- يتم تسليم مخرجات ACP إلى سلسلة المحادثة نفسها.
- تؤدي إزالة التركيز أو الإغلاق أو الأرشفة أو انتهاء مهلة الخمول أو انتهاء الحد الأقصى للعمر إلى إزالة الارتباط.
يعتمد دعم ربط السلاسل على المهايئ. وإذا لم يكن مهايئ القناة النشطة يدعم روابط السلاسل، فسيُرجع OpenClaw رسالة واضحة بعدم الدعم/عدم التوفر.
يعتمد دعم ربط السلاسل على المهايئ. إذا لم يكن مهايئ القناة النشطة يدعم ارتباطات السلاسل، فسيعيد OpenClaw رسالة واضحة تفيد بعدم الدعم/التوفر.
أعلام الميزات المطلوبة لـ ACP المرتبط بالسلسلة:
علامات الميزات المطلوبة لـ ACP المرتبط بالسلسلة:
- `acp.enabled=true`
- `acp.dispatch.enabled` مفعّل افتراضيًا (عيّنه إلى `false` لإيقاف توجيه ACP مؤقتًا)
- تمكين علم spawn الخاص بجلسات ACP في مهايئ القناة (بحسب المهايئ)
- يكون `acp.dispatch.enabled` مفعّلًا افتراضيًا (اضبطه على `false` لإيقاف توجيه ACP مؤقتًا)
- تفعيل علامة إنشاء سلاسل ACP في مهايئ القناة (خاصة بالمهايئ)
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
### القنوات التي تدعم السلاسل
- أي مهايئ قناة يكشف قدرة ربط الجلسات/السلاسل.
- أي مهايئ قناة يكشف قدرة ربط الجلسة/السلسلة.
- الدعم المضمّن الحالي:
- سلاسل/قنوات Discord
- موضوعات Telegram (موضوعات المنتدى في المجموعات/المجموعات الفائقة وموضوعات الرسائل المباشرة)
- يمكن لقنوات الإضافات إضافة الدعم عبر واجهة الربط نفسها.
- مواضيع Telegram (مواضيع المنتدى في المجموعات/المجموعات الفائقة ومواضيع الرسائل الخاصة)
- يمكن لقنوات plugin إضافة الدعم عبر واجهة الربط نفسها.
## إعدادات خاصة بالقناة
## الإعدادات الخاصة بالقنوات
بالنسبة إلى مسارات العمل غير المؤقتة، قم بتهيئة روابط ACP المستمرة في إدخالات `bindings[]` ذات المستوى الأعلى.
للتدفقات غير المؤقتة، اضبط ارتباطات ACP المستمرة في إدخالات `bindings[]` ذات المستوى الأعلى.
### نموذج الربط
- يحدد `bindings[].type="acp"` ربط محادثة ACP مستمر.
- يحدد `bindings[].match` المحادثة المستهدفة:
- قناة أو سلسلة Discord: ‏`match.channel="discord"` + ‏`match.peer.id="<channelOrThreadId>"`
- موضوع منتدى Telegram: ‏`match.channel="telegram"` + ‏`match.peer.id="<chatId>:topic:<topicId>"`
- دردشة مباشرة/مجموعة BlueBubbles: ‏`match.channel="bluebubbles"` + ‏`match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
فضّل `chat_id:*` أو `chat_identifier:*` للروابط الجماعية المستقرة.
- دردشة مباشرة/مجموعة iMessage: ‏`match.channel="imessage"` + ‏`match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
فضّل `chat_id:*` للروابط الجماعية المستقرة.
- تشير `bindings[].type="acp"` إلى ربط محادثة ACP مستمر.
- تحدد `bindings[].match` المحادثة المستهدفة:
- قناة أو سلسلة Discord: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- موضوع منتدى Telegram: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- دردشة BlueBubbles فردية/جماعية: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
فضّل `chat_id:*` أو `chat_identifier:*` لارتباطات المجموعات المستقرة.
- دردشة iMessage فردية/جماعية: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
فضّل `chat_id:*` لارتباطات المجموعات المستقرة.
- `bindings[].agentId` هو معرّف وكيل OpenClaw المالك.
- توجد تجاوزات ACP الاختيارية تحت `bindings[].acp`:
- `mode` ‏(`persistent` أو `oneshot`)
- `mode` (`persistent` أو `oneshot`)
- `label`
- `cwd`
- `backend`
### القيم الافتراضية لوقت التشغيل لكل وكيل
استخدم `agents.list[].runtime` لتعريف القيم الافتراضية لـ ACP مرة واحدة لكل وكيل:
استخدم `agents.list[].runtime` لتعريف قيم ACP الافتراضية مرة واحدة لكل وكيل:
- `agents.list[].runtime.type="acp"`
- `agents.list[].runtime.acp.agent` ‏(معرّف harness، مثل `codex` أو `claude`)
- `agents.list[].runtime.acp.agent` (معرّف الحاضنة، مثل `codex` أو `claude`)
- `agents.list[].runtime.acp.backend`
- `agents.list[].runtime.acp.mode`
- `agents.list[].runtime.acp.cwd`
ترتيب أسبقية التجاوز للجلسات المرتبطة بـ ACP:
ترتيب أولوية التجاوز لجلسات ACP المرتبطة:
1. ‏`bindings[].acp.*`
2. ‏`agents.list[].runtime.acp.*`
3. القيم الافتراضية العامة لـ ACP ‏(مثل `acp.backend`)
1. `bindings[].acp.*`
2. `agents.list[].runtime.acp.*`
3. القيم الافتراضية العامة لـ ACP (مثل `acp.backend`)
مثال:
@ -323,14 +323,14 @@ x-i18n:
السلوك:
- يضمن OpenClaw وجود جلسة ACP المهيأة قبل الاستخدام.
- تُوجَّه الرسائل في تلك القناة أو الموضوع إلى جلسة ACP المهيأة.
- يضمن OpenClaw وجود جلسة ACP المضبوطة قبل استخدامها.
- تُوجَّه الرسائل في تلك القناة أو الموضوع إلى جلسة ACP المضبوطة.
- في المحادثات المرتبطة، يعيد `/new` و`/reset` تعيين مفتاح جلسة ACP نفسه في مكانه.
- تظل روابط وقت التشغيل المؤقتة (مثل تلك التي تنشئها تدفقات التركيز على السلسلة) مطبّقة حيثما كانت موجودة.
- بالنسبة إلى عمليات spawn عبر وكلاء ACP من دون `cwd` صريح، يرث OpenClaw مساحة عمل الوكيل الهدف من إعدادات الوكيل.
- تعود مسارات مساحات العمل الموروثة المفقودة إلى `cwd` الافتراضي للواجهة الخلفية؛ أما إخفاقات الوصول إلى المسارات الموجودة فتظهر كأخطاء spawn.
- تستمر ارتباطات وقت التشغيل المؤقتة (مثل تلك التي تنشئها تدفقات التركيز على السلسلة) في التطبيق عند وجودها.
- في عمليات إنشاء ACP بين وكلاء مختلفين من دون `cwd` صريح، يرث OpenClaw مساحة عمل الوكيل المستهدف من إعدادات الوكيل.
- تعود مسارات مساحة العمل الموروثة المفقودة إلى `cwd` الافتراضي للواجهة الخلفية؛ أما حالات فشل الوصول غير المفقودة فتظهر كأخطاء إنشاء.
## بدء جلسات ACP ‏(الواجهات)
## بدء جلسات ACP (الواجهات)
### من `sessions_spawn`
@ -348,29 +348,29 @@ x-i18n:
ملاحظات:
- تكون القيمة الافتراضية لـ `runtime` هي `subagent`، لذا عيّن `runtime: "acp"` صراحةً لجلسات ACP.
- إذا حُذف `agentId`، يستخدم OpenClaw القيمة `acp.defaultAgent` إذا كانت مهيأة.
- يتطلب `mode: "session"` وجود `thread: true` للاحتفاظ بمحادثة مرتبطة مستمرة.
- القيمة الافتراضية لـ `runtime` هي `subagent`، لذا اضبط `runtime: "acp"` صراحةً لجلسات ACP.
- إذا تم حذف `agentId`، يستخدم OpenClaw القيمة `acp.defaultAgent` عند ضبطها.
- يتطلب `mode: "session"` وجود `thread: true` للإبقاء على محادثة مرتبطة مستمرة.
تفاصيل الواجهة:
- `task` ‏(مطلوب): المطالبة الأولية المرسلة إلى جلسة ACP.
- `runtime` ‏(مطلوب لـ ACP): يجب أن يكون `"acp"`.
- `agentId` ‏(اختياري): معرّف harness الهدف لـ ACP. يعود إلى `acp.defaultAgent` إذا كان مضبوطًا.
- `thread` ‏(اختياري، الافتراضي `false`): طلب تدفق ربط السلسلة عند الدعم.
- `mode` ‏(اختياري): ‏`run` ‏(مرة واحدة) أو `session` ‏(مستمر).
- `task` (مطلوب): الموجّه الأولي المرسل إلى جلسة ACP.
- `runtime` (مطلوب لـ ACP): يجب أن يكون `"acp"`.
- `agentId` (اختياري): معرّف حاضنة ACP المستهدفة. يعود إلى `acp.defaultAgent` إذا تم ضبطه.
- `thread` (اختياري، الافتراضي `false`): طلب تدفق ربط السلسلة عند دعمه.
- `mode` (اختياري): `run` (مرة واحدة) أو `session` (مستمر).
- القيمة الافتراضية هي `run`
- إذا كانت `thread: true` وحُذف `mode`، فقد يستخدم OpenClaw سلوكًا مستمرًا افتراضيًا بحسب مسار وقت التشغيل
- إذا كانت `thread: true` وتم حذف الوضع، فقد يستخدم OpenClaw سلوكًا مستمرًا افتراضيًا بحسب مسار وقت التشغيل
- يتطلب `mode: "session"` وجود `thread: true`
- `cwd` ‏(اختياري): دليل العمل المطلوب لوقت التشغيل (ويتحقق منه backend/سياسة وقت التشغيل). إذا حُذف، ترث عملية spawn لـ ACP مساحة عمل الوكيل الهدف عند تهيئتها؛ وتعود المسارات الموروثة المفقودة إلى القيم الافتراضية للواجهة الخلفية، بينما تُرجع أخطاء الوصول الحقيقية.
- `label` ‏(اختياري): تسمية موجهة للمشغّل تُستخدم في نص الجلسة/اللافتة.
- `resumeSessionId` ‏(اختياري): استئناف جلسة ACP موجودة بدلًا من إنشاء أخرى جديدة. يعيد الوكيل تشغيل سجل محادثاته عبر `session/load`. يتطلب `runtime: "acp"`.
- `streamTo` ‏(اختياري): تقوم القيمة `"parent"` ببث ملخصات تقدّم التشغيل الأولي لـ ACP إلى جلسة الطالب كأحداث نظام.
- عند التوفر، قد تتضمن الاستجابات المقبولة `streamLogPath` الذي يشير إلى سجل JSONL ضمن نطاق الجلسة (`<sessionId>.acp-stream.jsonl`) يمكنك تتبعه لمعرفة سجل الترحيل الكامل.
- `cwd` (اختياري): دليل عمل وقت التشغيل المطلوب (ويتم التحقق منه وفق سياسة الواجهة الخلفية/وقت التشغيل). إذا تم حذفه، يرث إنشاء ACP مساحة عمل الوكيل المستهدف عند ضبطها؛ وتعود المسارات الموروثة المفقودة إلى القيم الافتراضية للواجهة الخلفية، بينما تُعاد أخطاء الوصول الحقيقية.
- `label` (اختياري): تسمية موجّهة للمشغّل تُستخدم في نص الجلسة/الشعار.
- `resumeSessionId` (اختياري): استئناف جلسة ACP موجودة بدلًا من إنشاء جلسة جديدة. يعيد الوكيل تشغيل سجل محادثته عبر `session/load`. يتطلب `runtime: "acp"`.
- `streamTo` (اختياري): تؤدي القيمة `"parent"` إلى بث ملخصات تقدم تشغيل ACP الأولي إلى جلسة الطالب كأحداث نظام.
- عند التوفر، تتضمن الاستجابات المقبولة `streamLogPath` الذي يشير إلى سجل JSONL خاص بالجسلة (`<sessionId>.acp-stream.jsonl`) يمكنك مراقبته للاطلاع على سجل الترحيل الكامل.
### استئناف جلسة موجودة
استخدم `resumeSessionId` لمتابعة جلسة ACP سابقة بدلًا من البدء من جديد. يعيد الوكيل تشغيل سجل محادثته عبر `session/load`، لذلك يلتقط العمل مع السياق الكامل لما سبق.
استخدم `resumeSessionId` لمتابعة جلسة ACP سابقة بدلًا من البدء من جديد. يعيد الوكيل تشغيل سجل محادثته عبر `session/load`، بحيث يواصل العمل مع كامل السياق السابق.
```json
{
@ -383,41 +383,41 @@ x-i18n:
حالات الاستخدام الشائعة:
- تسليم جلسة Codex من الكمبيوتر المحمول إلى الهاتف — اطلب من وكيلك متابعة العمل من حيث توقفت
- متابعة جلسة برمجة بدأتَها تفاعليًا في CLI، ولكن الآن بصورة غير تفاعلية عبر وكيلك
- متابعة عمل انقطع بسبب إعادة تشغيل البوابة أو انتهاء مهلة الخمول
- تسليم جلسة Codex من حاسوبك المحمول إلى هاتفك — اطلب من وكيلك متابعة العمل من حيث توقفت
- متابعة جلسة برمجة بدأت بها بشكل تفاعلي في CLI، ولكن الآن بدون واجهة مباشرة عبر وكيلك
- استكمال العمل الذي انقطع بسبب إعادة تشغيل البوابة أو انتهاء مهلة الخمول
ملاحظات:
- يتطلب `resumeSessionId` وجود `runtime: "acp"` — ويعيد خطأ إذا استُخدم مع وقت تشغيل الوكيل الفرعي.
- يستعيد `resumeSessionId` سجل المحادثة الأعلى مستوى لـ ACP؛ وما تزال `thread` و`mode` تطبقان بشكل طبيعي على جلسة OpenClaw الجديدة التي تنشئها، لذلك ما يزال `mode: "session"` يتطلب `thread: true`.
- يجب أن يدعم الوكيل الهدف `session/load` ‏(كل من Codex وClaude Code يدعمان ذلك).
- إذا لم يُعثر على معرّف الجلسة، تفشل عملية spawn برسالة خطأ واضحة — ولا يوجد تراجع صامت إلى جلسة جديدة.
- يعيد `resumeSessionId` سجل محادثة ACP الصاعد؛ ولا يزال `thread` و`mode` يُطبّقان بشكل طبيعي على جلسة OpenClaw الجديدة التي تنشئها، لذا يظل `mode: "session"` يتطلب `thread: true`.
- يجب أن يدعم الوكيل المستهدف `session/load` (ويدعمه كل من Codex وClaude Code).
- إذا لم يتم العثور على معرّف الجلسة، تفشل عملية الإنشاء مع خطأ واضح — دون عودة صامتة إلى جلسة جديدة.
### اختبار smoke للمشغّل
### اختبار دخاني للمشغّل
استخدم هذا بعد نشر البوابة عندما تريد فحصًا مباشرًا سريعًا يثبت أن spawn لـ ACP
يعمل فعليًا من طرف إلى طرف، وليس مجرد اجتياز اختبارات الوحدات.
استخدم هذا بعد نشر البوابة عندما تريد فحصًا حيًا سريعًا يثبت أن إنشاء ACP
يعمل فعلًا من طرف إلى طرف، وليس فقط أنه ينجح في اختبارات الوحدة.
البوابة الموصى بها:
1. تحقّق من إصدار/commit البوابة المنشورة على المضيف الهدف.
2. أكّد أن المصدر المنشور يتضمن قبول نسب ACP في
`src/gateway/sessions-patch.ts` ‏(`subagent:* or acp:* sessions`).
3. افتح جلسة جسر ACPX مؤقتة إلى وكيل مباشر (مثل
1. تحقّق من إصدار/التزام البوابة المنشورة على المضيف المستهدف.
2. أكّد أن المصدر المنشور يتضمن قبول سلالة ACP في
`src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`).
3. افتح جلسة جسر ACPX مؤقتة إلى وكيل حي (مثل
`razor(main)` على `jpclawhq`).
4. اطلب من ذلك الوكيل استدعاء `sessions_spawn` بالقيم التالية:
4. اطلب من ذلك الوكيل استدعاء `sessions_spawn` باستخدام:
- `runtime: "acp"`
- `agentId: "codex"`
- `mode: "run"`
- المهمة: `Reply with exactly LIVE-ACP-SPAWN-OK`
5. تحقّق من أن الوكيل يبلّغ بما يلي:
5. تحقّق من أن الوكيل يبلغ عن:
- `accepted=yes`
- `childSessionKey` حقيقي
- لا يوجد خطأ تحقق
- عدم وجود خطأ تحقق
6. نظّف جلسة جسر ACPX المؤقتة.
مثال على مطالبة إلى الوكيل المباشر:
مثال على موجّه إلى الوكيل الحي:
```text
Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
@ -427,29 +427,29 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
ملاحظات:
- أبقِ اختبار smoke هذا على `mode: "run"` ما لم تكن تختبر عمدًا
- أبقِ هذا الاختبار الدخاني على `mode: "run"` ما لم تكن تختبر عمدًا
جلسات ACP المستمرة المرتبطة بالسلسلة.
- لا تجعل `streamTo: "parent"` شرطًا لهذه البوابة الأساسية. فهذا المسار يعتمد على
قدرات الجلسة/الطالب وهو فحص تكامل منفصل.
- تعامل مع اختبار `mode: "session"` المرتبط بالسلسلة باعتباره تمرير تكامل
ثانيًا وأكثر غنى من سلسلة Discord حقيقية أو موضوع Telegram.
- لا تشترط `streamTo: "parent"` للبوابة الأساسية. يعتمد هذا المسار على
قدرات الطالب/الجلسة ويُعد فحص تكامل منفصل.
- تعامل مع اختبار `mode: "session"` المرتبط بالسلسلة باعتباره تمريرة تكامل
ثانية وأكثر ثراءً من سلسلة Discord حقيقية أو موضوع Telegram حقيقي.
## توافق sandbox
## توافق Sandbox
تعمل جلسات ACP حاليًا على وقت تشغيل المضيف، وليس داخل sandbox في OpenClaw.
تعمل جلسات ACP حاليًا على وقت تشغيل المضيف، وليس داخل Sandbox الخاص بـ OpenClaw.
القيود الحالية:
- إذا كانت جلسة الطالب تعمل داخل sandbox، فسيتم حظر عمليات spawn الخاصة بـ ACP لكل من `sessions_spawn({ runtime: "acp" })` و`/acp spawn`.
- إذا كانت جلسة الطالب داخل sandbox، فسيتم حظر عمليات إنشاء ACP لكل من `sessions_spawn({ runtime: "acp" })` و`/acp spawn`.
- الخطأ: `Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.`
- لا يدعم `sessions_spawn` مع `runtime: "acp"` القيمة `sandbox: "require"`.
- الخطأ: `sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`
استخدم `runtime: "subagent"` عندما تحتاج إلى تنفيذ مفروض عبر sandbox.
استخدم `runtime: "subagent"` عندما تحتاج إلى تنفيذ مفروض بواسطة sandbox.
### من أمر `/acp`
استخدم `/acp spawn` للتحكم الصريح من المشغّل من داخل الدردشة عند الحاجة.
استخدم `/acp spawn` للتحكم التشغيلي الصريح من الدردشة عند الحاجة.
```text
/acp spawn codex --mode persistent --thread auto
@ -458,7 +458,7 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
/acp spawn codex --thread here
```
الأعلام الرئيسية:
العلامات الرئيسية:
- `--mode persistent|oneshot`
- `--bind here|off`
@ -476,48 +476,48 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
1. وسيطة الهدف الصريحة (أو `--session` في `/acp steer`)
- يحاول أولًا المفتاح
- ثم معرّف جلسة على شكل UUID
- ثم معرّف الجلسة على هيئة UUID
- ثم التسمية
2. ربط السلسلة الحالية (إذا كانت هذه المحادثة/السلسلة مرتبطة بجلسة ACP)
2. ارتباط السلسلة الحالية (إذا كانت هذه المحادثة/السلسلة مرتبطة بجلسة ACP)
3. الرجوع إلى جلسة الطالب الحالية
تشارك روابط المحادثة الحالية وروابط السلاسل في الخطوة 2.
تشارك ارتباطات المحادثة الحالية وارتباطات السلاسل في كلتيهما في الخطوة 2.
إذا تعذر حل أي هدف، فسيُرجع OpenClaw خطأ واضحًا (`Unable to resolve session target: ...`).
إذا لم يتم حل أي هدف، يعيد OpenClaw خطأ واضحًا (`Unable to resolve session target: ...`).
## أوضاع الربط عند spawn
## أوضاع ربط الإنشاء
يدعم `/acp spawn` ‏`--bind here|off`.
يدعم `/acp spawn` الخيار `--bind here|off`.
| الوضع | السلوك |
| ------ | --------------------------------------------------------------------- |
| الوضع | السلوك |
| ------ | -------------------------------------------------------------------- |
| `here` | اربط المحادثة النشطة الحالية في مكانها؛ وافشل إذا لم تكن هناك محادثة نشطة. |
| `off` | لا تنشئ ربطًا بالمحادثة الحالية. |
| `off` | لا تنشئ ارتباطًا للمحادثة الحالية. |
ملاحظات:
- يُعد `--bind here` أبسط مسار للمشغّل لتحقيق "اجعل هذه القناة أو الدردشة مدعومة بـ Codex."
- `--bind here` هو أبسط مسار تشغيلي لعبارة "اجعل هذه القناة أو الدردشة مدعومة بواسطة Codex."
- لا ينشئ `--bind here` سلسلة فرعية.
- لا يتوفر `--bind here` إلا على القنوات التي تكشف دعم الربط بالمحادثة الحالية.
- لا يمكن الجمع بين `--bind` و`--thread` في الاستدعاء نفسه لـ `/acp spawn`.
- يتوفر `--bind here` فقط على القنوات التي تكشف دعم ربط المحادثة الحالية.
- لا يمكن الجمع بين `--bind` و`--thread` في استدعاء `/acp spawn` نفسه.
## أوضاع السلسلة عند spawn
## أوضاع سلسلة الإنشاء
يدعم `/acp spawn` ‏`--thread auto|here|off`.
يدعم `/acp spawn` الخيار `--thread auto|here|off`.
| الوضع | السلوك |
| ------ | --------------------------------------------------------------------------------------------------- |
| `auto` | داخل سلسلة نشطة: اربط هذه السلسلة. خارج سلسلة: أنشئ/اربط سلسلة فرعية عند الدعم. |
| `here` | يتطلب سلسلة نشطة حالية؛ ويفشل إذا لم تكن داخل سلسلة. |
| `off` | لا يوجد ربط. تبدأ الجلسة من دون ربط. |
| الوضع | السلوك |
| ------ | ------------------------------------------------------------------------------------------------- |
| `auto` | في سلسلة نشطة: اربط تلك السلسلة. خارج سلسلة: أنشئ/اربط سلسلة فرعية عند الدعم. |
| `here` | اشترط وجود سلسلة نشطة حالية؛ وافشل إذا لم تكن داخل واحدة. |
| `off` | بلا ربط. تبدأ الجلسة غير مرتبطة. |
ملاحظات:
- على الأسطح التي لا تدعم ربط السلاسل، يكون السلوك الافتراضي فعليًا هو `off`.
- يتطلب spawn المرتبط بالسلسلة دعم سياسة القناة:
- يتطلب إنشاء جلسة مرتبطة بسلسلة دعم سياسة القناة:
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
- استخدم `--bind here` عندما تريد تثبيت المحادثة الحالية من دون إنشاء سلسلة فرعية.
- استخدم `--bind here` عندما تريد تثبيت المحادثة الحالية دون إنشاء سلسلة فرعية.
## عناصر تحكم ACP
@ -539,54 +539,54 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
- `/acp doctor`
- `/acp install`
يعرض `/acp status` خيارات وقت التشغيل الفعلية، وعند التوفر، يوضح كلًا من معرّفات الجلسات على مستوى وقت التشغيل وعلى مستوى الواجهة الخلفية.
يعرض `/acp status` خيارات وقت التشغيل الفعالة، وعند التوفر، كلًا من معرّفات الجلسة على مستوى وقت التشغيل ومستوى الواجهة الخلفية.
تعتمد بعض عناصر التحكم على قدرات الواجهة الخلفية. وإذا لم تكن واجهة خلفية ما تدعم عنصر تحكم معينًا، فسيُرجع OpenClaw خطأً واضحًا يفيد بعدم دعم ذلك العنصر.
تعتمد بعض عناصر التحكم على قدرات الواجهة الخلفية. إذا كانت الواجهة الخلفية لا تدعم عنصر تحكم ما، فسيعيد OpenClaw خطأ واضحًا يفيد بعدم دعم عنصر التحكم.
## كتاب وصفات أوامر ACP
| الأمر | ما الذي يفعله | مثال |
| -------------------- | ----------------------------------------------------------- | ------------------------------------------------------------ |
| `/acp spawn` | إنشاء جلسة ACP؛ مع ربط اختياري بالحالية أو بالسلسلة. | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | إلغاء الدور الجاري للجلسة الهدف. | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | إرسال توجيه إلى جلسة قيد التشغيل. | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close` | إغلاق الجلسة وفك ربط أهداف السلسلة. | `/acp close` |
| `/acp status` | عرض الواجهة الخلفية، والوضع، والحالة، وخيارات وقت التشغيل، والقدرات. | `/acp status` |
| `/acp set-mode` | تعيين وضع وقت التشغيل للجلسة الهدف. | `/acp set-mode plan` |
| `/acp set` | كتابة عامة لخيار من خيارات إعداد وقت التشغيل. | `/acp set model openai/gpt-5.4` |
| `/acp cwd` | تعيين تجاوز دليل العمل لوقت التشغيل. | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | تعيين ملف سياسة الموافقات. | `/acp permissions strict` |
| `/acp timeout` | تعيين مهلة وقت التشغيل (بالثواني). | `/acp timeout 120` |
| `/acp model` | تعيين تجاوز نموذج وقت التشغيل. | `/acp model anthropic/claude-opus-4-6` |
| `/acp reset-options` | إزالة تجاوزات خيارات وقت التشغيل للجلسة. | `/acp reset-options` |
| `/acp sessions` | سرد جلسات ACP الحديثة من المخزن. | `/acp sessions` |
| `/acp doctor` | صحة الواجهة الخلفية، والقدرات، والإصلاحات القابلة للتنفيذ. | `/acp doctor` |
| `/acp install` | طباعة خطوات تثبيت وتمكين حتمية. | `/acp install` |
| الأمر | ما الذي يفعله | مثال |
| ------------------ | ---------------------------------------------------------- | ----------------------------------------------------------- |
| `/acp spawn` | إنشاء جلسة ACP؛ مع ربط اختياري للمحادثة الحالية أو ربط بسلسلة. | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | إلغاء الدور الجاري للجلسة المستهدفة. | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | إرسال توجيه إلى جلسة قيد التشغيل. | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close` | إغلاق الجلسة وفك ربط أهداف السلاسل. | `/acp close` |
| `/acp status` | عرض الواجهة الخلفية والوضع والحالة وخيارات وقت التشغيل والقدرات. | `/acp status` |
| `/acp set-mode` | تعيين وضع وقت التشغيل للجلسة المستهدفة. | `/acp set-mode plan` |
| `/acp set` | كتابة خيار إعداد عام لوقت التشغيل. | `/acp set model openai/gpt-5.4` |
| `/acp cwd` | تعيين تجاوز دليل عمل وقت التشغيل. | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | تعيين ملف سياسة الموافقة. | `/acp permissions strict` |
| `/acp timeout` | تعيين مهلة وقت التشغيل (بالثواني). | `/acp timeout 120` |
| `/acp model` | تعيين تجاوز نموذج وقت التشغيل. | `/acp model anthropic/claude-opus-4-6` |
| `/acp reset-options` | إزالة تجاوزات خيارات وقت التشغيل للجلسة. | `/acp reset-options` |
| `/acp sessions` | سرد جلسات ACP الحديثة من المخزن. | `/acp sessions` |
| `/acp doctor` | سلامة الواجهة الخلفية، والقدرات، والإصلاحات القابلة للتنفيذ. | `/acp doctor` |
| `/acp install` | طباعة خطوات تثبيت وتمكين حتمية. | `/acp install` |
يقرأ `/acp sessions` المخزن للجلسة الحالية المرتبطة أو جلسة الطالب الحالية. وتحل الأوامر التي تقبل رموز `session-key` أو `session-id` أو `session-label` الأهداف عبر اكتشاف جلسات البوابة، بما في ذلك جذور `session.store` المخصصة لكل وكيل.
يقرأ `/acp sessions` المخزن للجلسة المرتبطة الحالية أو جلسة الطالب الحالية. تحل الأوامر التي تقبل رموز `session-key` أو `session-id` أو `session-label` الأهداف عبر اكتشاف جلسات البوابة، بما في ذلك الجذور المخصصة لـ `session.store` لكل وكيل.
## ربط خيارات وقت التشغيل
يحتوي `/acp` على أوامر تسهيلية ومُعيّن عام.
تحتوي `/acp` على أوامر مريحة وأداة تعيين عامة.
العمليات المكافئة:
- يربط `/acp model <id>` بمفتاح إعداد وقت التشغيل `model`.
- يربط `/acp permissions <profile>` بمفتاح إعداد وقت التشغيل `approval_policy`.
- يربط `/acp timeout <seconds>` بمفتاح إعداد وقت التشغيل `timeout`.
- يحدّث `/acp cwd <path>` تجاوز `cwd` لوقت التشغيل مباشرة.
- يمثّل `/acp set <key> <value>` المسار العام.
- حالة خاصة: إذا كان `key=cwd` فإنه يستخدم مسار تجاوز `cwd`.
- يمسح `/acp reset-options` كل تجاوزات وقت التشغيل للجلسة الهدف.
- يطابق `/acp model <id>` مفتاح إعداد وقت التشغيل `model`.
- يطابق `/acp permissions <profile>` مفتاح إعداد وقت التشغيل `approval_policy`.
- يطابق `/acp timeout <seconds>` مفتاح إعداد وقت التشغيل `timeout`.
- يحدّث `/acp cwd <path>` تجاوز `cwd` لوقت التشغيل مباشرةً.
- يشكّل `/acp set <key> <value>` المسار العام.
- حالة خاصة: يستخدم `key=cwd` مسار تجاوز cwd.
- يزيل `/acp reset-options` جميع تجاوزات وقت التشغيل للجلسة المستهدفة.
## دعم harness في acpx ‏(الحالي)
## دعم حاضنات acpx (الحالي)
الأسماء المستعارة المضمّنة الحالية لـ harness في acpx:
الأسماء المستعارة المضمّنة الحالية للحاضنات في acpx:
- `claude`
- `codex`
- `copilot`
- `cursor` ‏(Cursor CLI: ‏`cursor-agent acp`)
- `cursor` (Cursor CLI: `cursor-agent acp`)
- `droid`
- `gemini`
- `iflow`
@ -598,10 +598,10 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
- `pi`
- `qwen`
عندما يستخدم OpenClaw الواجهة الخلفية acpx، ففضّل هذه القيم لـ `agentId` ما لم يحدد إعداد acpx لديك أسماء مستعارة مخصصة للوكلاء.
إذا كان تثبيت Cursor المحلي لديك ما يزال يعرض ACP على شكل `agent acp`، فقم بتجاوز أمر الوكيل `cursor` في إعداد acpx بدلًا من تغيير القيمة الافتراضية المضمّنة.
عندما يستخدم OpenClaw الواجهة الخلفية acpx، ففضّل هذه القيم لـ `agentId` ما لم يعرّف إعداد acpx لديك أسماء مستعارة مخصصة للوكلاء.
إذا كان تثبيت Cursor المحلي لديك لا يزال يعرض ACP باعتباره `agent acp`، فتجاوز أمر الوكيل `cursor` في إعداد acpx بدلًا من تغيير القيمة الافتراضية المضمّنة.
يمكن أيضًا لاستخدام acpx CLI المباشر استهداف مهايئات عشوائية عبر `--agent <command>`، لكن منفذ الهروب الخام هذا هو ميزة في acpx CLI (وليس المسار المعتاد لـ `agentId` في OpenClaw).
يمكن لاستخدام CLI المباشر لـ acpx أيضًا استهداف مهيئات اعتباطية عبر `--agent <command>`، لكن منفذ الهروب الخام هذا هو ميزة في CLI الخاص بـ acpx (وليس مسار `agentId` المعتاد في OpenClaw).
## الإعداد المطلوب
@ -611,7 +611,7 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
{
acp: {
enabled: true,
// اختياري. القيمة الافتراضية هي true؛ عيّن false لإيقاف توجيه ACP مؤقتًا مع الإبقاء على عناصر التحكم /acp.
// اختياري. القيمة الافتراضية true؛ اضبطها على false لإيقاف توجيه ACP مؤقتًا مع الإبقاء على عناصر تحكم /acp.
dispatch: { enabled: true },
backend: "acpx",
defaultAgent: "codex",
@ -643,7 +643,7 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
}
```
يكون إعداد ربط السلاسل خاصًا بمهايئ القناة. مثال لـ Discord:
إعداد ربط السلاسل خاص بمهايئ القناة. مثال على Discord:
```json5
{
@ -665,18 +665,18 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
}
```
إذا لم يعمل spawn لـ ACP المرتبط بالسلسلة، فتحقق أولًا من علم الميزة في المهايئ:
إذا لم يعمل إنشاء ACP المرتبط بالسلسلة، فتحقق أولًا من علامة ميزة المهايئ:
- Discord: ‏`channels.discord.threadBindings.spawnAcpSessions=true`
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
لا تتطلب روابط المحادثة الحالية إنشاء سلسلة فرعية. لكنها تتطلب سياق محادثة نشطًا ومهايئ قناة يكشف روابط محادثات ACP.
لا تتطلب ارتباطات المحادثة الحالية إنشاء سلسلة فرعية. وهي تتطلب سياق محادثة نشطًا ومهايئ قناة يكشف ارتباطات محادثة ACP.
راجع [مرجع الإعدادات](/ar/gateway/configuration-reference).
راجع [مرجع الإعداد](/ar/gateway/configuration-reference).
## إعداد الإضافة للواجهة الخلفية acpx
## إعداد plugin للواجهة الخلفية acpx
تأتي التثبيتات الجديدة مع تفعيل إضافة وقت التشغيل المضمّنة `acpx` افتراضيًا، لذا يعمل ACP
عادةً من دون خطوة تثبيت إضافة يدوية.
تأتي التثبيتات الجديدة مع plugin وقت التشغيل المضمّن `acpx` مفعّلًا افتراضيًا، لذا فإن ACP
يعمل عادةً بدون خطوة تثبيت plugin يدوية.
ابدأ بـ:
@ -684,38 +684,38 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
/acp doctor
```
إذا كنت قد عطّلت `acpx`، أو رفضته عبر `plugins.allow` / `plugins.deny`، أو أردت
التحول إلى نسخة تطوير محلية، فاستخدم مسار الإضافة الصريح:
إذا كنت قد عطلت `acpx` أو منعتَه عبر `plugins.allow` / `plugins.deny` أو كنت
تريد التبديل إلى نسخة تطوير محلية، فاستخدم مسار plugin الصريح:
```bash
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true
```
تثبيت مساحة عمل محلية أثناء التطوير:
التثبيت المحلي في مساحة العمل أثناء التطوير:
```bash
openclaw plugins install ./path/to/local/acpx-plugin
```
ثم تحقق من صحة الواجهة الخلفية:
ثم تحقّق من سلامة الواجهة الخلفية:
```text
/acp doctor
```
### إعداد أمر acpx والإصدار
### إعدادات الأمر والإصدار لـ acpx
افتراضيًا، تستخدم إضافة الواجهة الخلفية المضمّنة acpx ‏(`acpx`) الثنائية المثبتة إصدارًا محليًا ضمن الإضافة:
افتراضيًا، يستخدم plugin الواجهة الخلفية المضمّن acpx (`acpx`) الثنائي المثبّت محليًا داخل plugin:
1. تكون القيمة الافتراضية للأمر هي `node_modules/.bin/acpx` المحلي ضمن حزمة إضافة ACPX.
2. تكون القيمة الافتراضية للإصدار المتوقع هي الإصدار المثبّت في الإضافة.
3. يسجل بدء التشغيل الواجهة الخلفية لـ ACP فورًا على أنها غير جاهزة.
4. تتحقق مهمة ensure في الخلفية من `acpx --version`.
5. إذا كانت الثنائية المحلية ضمن الإضافة مفقودة أو لا تطابق الإصدار، فيُشغِّل:
1. تكون القيمة الافتراضية للأمر هي `node_modules/.bin/acpx` المحلي داخل حزمة plugin ACPX.
2. تكون القيمة الافتراضية للإصدار المتوقع هي الإصدار المثبّت في extension.
3. يسجّل بدء التشغيل الواجهة الخلفية لـ ACP فورًا على أنها غير جاهزة.
4. تتحقق مهمة ضمان في الخلفية من `acpx --version`.
5. إذا كان الثنائي المحلي داخل plugin مفقودًا أو غير مطابق، يشغّل:
`npm install --omit=dev --no-save acpx@<pinned>` ثم يعيد التحقق.
يمكنك تجاوز الأمر/الإصدار في إعداد الإضافة:
يمكنك تجاوز الأمر/الإصدار في إعداد plugin:
```json
{
@ -735,28 +735,28 @@ openclaw plugins install ./path/to/local/acpx-plugin
ملاحظات:
- يقبل `command` مسارًا مطلقًا أو نسبيًا أو اسم أمر (`acpx`).
- يقبل `command` مسارًا مطلقًا أو مسارًا نسبيًا أو اسم أمر (`acpx`).
- تُحل المسارات النسبية انطلاقًا من دليل مساحة عمل OpenClaw.
- يؤدي `expectedVersion: "any"` إلى تعطيل المطابقة الصارمة للإصدار.
- عندما يشير `command` إلى ثنائية/مسار مخصص، يتم تعطيل التثبيت التلقائي المحلي ضمن الإضافة.
- يظل بدء تشغيل OpenClaw غير حاجز أثناء تنفيذ فحص صحة الواجهة الخلفية.
- عندما يشير `command` إلى ثنائي/مسار مخصص، يتم تعطيل التثبيت التلقائي المحلي داخل plugin.
- يظل بدء تشغيل OpenClaw غير معيق أثناء تنفيذ فحص سلامة الواجهة الخلفية.
راجع [الإضافات](/ar/tools/plugin).
راجع [Plugins](/ar/tools/plugin).
### التثبيت التلقائي للتبعيات
عند تثبيت OpenClaw عالميًا عبر `npm install -g openclaw`، تُثبَّت تبعيات وقت تشغيل acpx
(الثنائيات الخاصة بالمنصة) تلقائيًا
عبر خطاف postinstall. وإذا فشل التثبيت التلقائي، فستبدأ البوابة بشكل طبيعي
وتبلّغ عن التبعية المفقودة عبر `openclaw acp doctor`.
عند تثبيت OpenClaw عالميًا باستخدام `npm install -g openclaw`، يتم تثبيت
تبعيات وقت التشغيل الخاصة بـ acpx (الثنائيات الخاصة بالنظام الأساسي) تلقائيًا
عبر خطاف postinstall. إذا فشل التثبيت التلقائي، فستبدأ البوابة بشكل طبيعي
وستبلّغ عن التبعية المفقودة عبر `openclaw acp doctor`.
### جسر MCP لأدوات الإضافات
### جسر MCP لأدوات plugin
افتراضيًا، لا تعرض جلسات ACPX **أدوات** الإضافات المسجلة في OpenClaw إلى
ACP harness.
افتراضيًا، لا تكشف جلسات ACPX **عن** أدوات OpenClaw المسجلة بواسطة plugin
إلى حاضنة ACP.
إذا كنت تريد أن تستدعي وكلاء ACP مثل Codex أو Claude Code أدوات
إضافات OpenClaw المثبتة مثل استدعاء/تخزين الذاكرة، ففعّل الجسر المخصص:
إذا كنت تريد أن تتمكن وكلاء ACP مثل Codex أو Claude Code من استدعاء
أدوات OpenClaw المثبّتة بواسطة plugin مثل memory recall/store، فعِّل الجسر المخصص:
```bash
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
@ -764,51 +764,61 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
ما الذي يفعله هذا:
- يحقن خادم MCP مضمّنًا باسم `openclaw-plugin-tools` ضمن
تمهيد جلسة ACPX.
- يكشف أدوات الإضافات المسجلة أصلًا بواسطة إضافات OpenClaw
المثبتة والمفعّلة.
- يُبقي هذه الميزة صريحة ومعطّلة افتراضيًا.
- يحقن خادم MCP مضمّنًا باسم `openclaw-plugin-tools` في تهيئة جلسة ACPX.
- يكشف أدوات plugin المسجلة بالفعل بواسطة plugins OpenClaw المثبّتة والمفعّلة.
- يبقي الميزة صريحة ومُعطّلة افتراضيًا.
ملاحظات الأمان والثقة:
- يوسّع هذا سطح أدوات ACP harness.
- لا يحصل وكلاء ACP إلا على أدوات الإضافات النشطة أصلًا في البوابة.
- تعامل مع هذا على أنه نفس حد الثقة الذي ينطبق على السماح لتلك الإضافات بالتنفيذ داخل
OpenClaw نفسه.
- راجع الإضافات المثبتة قبل تفعيله.
- يؤدي هذا إلى توسيع سطح الأدوات في حاضنة ACP.
- لا يحصل وكلاء ACP إلا على الوصول إلى أدوات plugin النشطة بالفعل في البوابة.
- تعامل مع هذا باعتباره الحد نفسه من الثقة الذي ينطبق على السماح لتلك plugins بالتنفيذ داخل OpenClaw نفسه.
- راجع plugins المثبّتة قبل تفعيله.
تظل `mcpServers` المخصصة تعمل كما كانت من قبل. إن جسر أدوات الإضافات المضمّن هو
ميزة راحة إضافية اختيارية، وليس بديلًا عن إعداد خادم MCP العام.
تظل `mcpServers` المخصصة تعمل كما كانت من قبل. جسر أدوات plugin المضمّن هو
وسيلة راحة إضافية اختيارية، وليس بديلًا عن إعداد خادم MCP العام.
## إعداد الأذونات
### إعداد مهلة وقت التشغيل
تعمل جلسات ACP بصورة غير تفاعلية — لا يوجد TTY للموافقة أو الرفض على مطالبات أذونات كتابة الملفات وتنفيذ shell. توفّر إضافة acpx مفتاحي إعداد يتحكمان في كيفية التعامل مع الأذونات:
يضبط plugin `acpx` المضمّن مهلة أدوار وقت التشغيل المضمّن افتراضيًا على 120
ثانية. يمنح هذا الحاضنات الأبطأ مثل Gemini CLI وقتًا كافيًا لإكمال
بدء تشغيل ACP والتهيئة. تجاوز هذا إذا كان مضيفك يحتاج إلى حد مختلف
لوقت التشغيل:
هذه الأذونات الخاصة بـ ACPX harness منفصلة عن موافقات التنفيذ في OpenClaw ومنفصلة عن أعلام تجاوز المورّد في CLI-backend مثل Claude CLI ‏`--permission-mode bypassPermissions`. تمثل ACPX ‏`approve-all` مفتاح كسر الزجاج على مستوى harness لجلسات ACP.
```bash
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
```
أعد تشغيل البوابة بعد تغيير هذه القيمة.
## إعدادات الأذونات
تعمل جلسات ACP بشكل غير تفاعلي — لا توجد TTY للموافقة على مطالبات أذونات كتابة الملفات وتنفيذ shell أو رفضها. يوفّر plugin ‏acpx مفتاحَي إعداد يتحكمان في كيفية التعامل مع الأذونات:
هذه الأذونات الخاصة بحاضنات ACPX منفصلة عن موافقات تنفيذ OpenClaw ومنفصلة عن علامات تجاوز المورّد في الواجهات الخلفية لـ CLI مثل Claude CLI `--permission-mode bypassPermissions`. وتمثل ACPX ‏`approve-all` مفتاح الكسر الطارئ على مستوى الحاضنة لجلسات ACP.
### `permissionMode`
يتحكم في العمليات التي يمكن لوكيل harness تنفيذها من دون مطالبة.
يتحكم في العمليات التي يمكن لوكيل الحاضنة تنفيذها دون مطالبة.
| القيمة | السلوك |
| --------------- | -------------------------------------------------------- |
| `approve-all` | الموافقة التلقائية على جميع عمليات كتابة الملفات وأوامر shell. |
| `approve-reads` | الموافقة التلقائية على عمليات القراءة فقط؛ أما الكتابة والتنفيذ فتتطلبان مطالبات. |
| `deny-all` | رفض جميع مطالبات الأذونات. |
| القيمة | السلوك |
| ---------------- | ------------------------------------------------------- |
| `approve-all` | الموافقة التلقائية على جميع عمليات كتابة الملفات وأوامر shell. |
| `approve-reads` | الموافقة التلقائية على القراءات فقط؛ تتطلب الكتابة والتنفيذ مطالبات. |
| `deny-all` | رفض جميع مطالبات الأذونات. |
### `nonInteractivePermissions`
يتحكم فيما يحدث عندما يفترض أن تظهر مطالبة أذونات ولكن لا يوجد TTY تفاعلي متاح (وهو الحال دائمًا بالنسبة إلى جلسات ACP).
يتحكم في ما يحدث عندما كان من المفترض عرض مطالبة إذن ولكن لا توجد TTY تفاعلية متاحة (وهو الحال دائمًا في جلسات ACP).
| القيمة | السلوك |
| ------ | ------------------------------------------------------------------ |
| `fail` | إجهاض الجلسة مع `AcpRuntimeError`. **(الافتراضي)** |
| `deny` | رفض الإذن بصمت والمتابعة (تراجع سلس). |
| القيمة | السلوك |
| ------ | ---------------------------------------------------------------- |
| `fail` | إيقاف الجلسة مع `AcpRuntimeError`. **(الافتراضي)** |
| `deny` | رفض الإذن بصمت والمتابعة (تدهور سلس). |
### الإعداد
قم بالتعيين عبر إعداد الإضافة:
اضبطه عبر إعداد plugin:
```bash
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
@ -817,27 +827,27 @@ openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
أعد تشغيل البوابة بعد تغيير هذه القيم.
> **مهم:** يستخدم OpenClaw حاليًا القيم الافتراضية `permissionMode=approve-reads` و`nonInteractivePermissions=fail`. وفي جلسات ACP غير التفاعلية، يمكن أن تفشل أي عملية كتابة أو تنفيذ تؤدي إلى مطالبة إذن بالخطأ `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
> **مهم:** يستخدم OpenClaw حاليًا افتراضيًا `permissionMode=approve-reads` و`nonInteractivePermissions=fail`. في جلسات ACP غير التفاعلية، قد تفشل أي عملية كتابة أو تنفيذ تؤدي إلى مطالبة إذن مع `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
>
> إذا كنت بحاجة إلى تقييد الأذونات، فعيّن `nonInteractivePermissions` إلى `deny` حتى تتراجع الجلسات بسلاسة بدلًا من أن تتعطل.
> إذا كنت بحاجة إلى تقييد الأذونات، فاضبط `nonInteractivePermissions` على `deny` حتى تتدهور الجلسات بسلاسة بدلًا من أن تتعطل.
## استكشاف الأخطاء وإصلاحها
| العرض | السبب المحتمل | الإصلاح |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACP runtime backend is not configured` | إضافة الواجهة الخلفية مفقودة أو معطّلة. | ثبّت إضافة الواجهة الخلفية وفعّلها، ثم شغّل `/acp doctor`. |
| `ACP is disabled by policy (acp.enabled=false)` | تم تعطيل ACP عالميًا. | عيّن `acp.enabled=true`. |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | تم تعطيل التوجيه من رسائل السلاسل العادية. | عيّن `acp.dispatch.enabled=true`. |
| `ACP agent "<id>" is not allowed by policy` | الوكيل غير موجود في قائمة السماح. | استخدم `agentId` مسموحًا به أو حدّث `acp.allowedAgents`. |
| `Unable to resolve session target: ...` | رمز مفتاح/معرّف/تسمية غير صحيح. | شغّل `/acp sessions`، وانسخ المفتاح/التسمية بدقة، ثم أعد المحاولة. |
| `--bind here requires running /acp spawn inside an active ... conversation` | استُخدم `--bind here` من دون محادثة نشطة قابلة للربط. | انتقل إلى الدردشة/القناة المستهدفة وأعد المحاولة، أو استخدم spawn غير مرتبط. |
| `Conversation bindings are unavailable for <channel>.` | لا يملك المهايئ قدرة ربط ACP بالمحادثة الحالية. | استخدم `/acp spawn ... --thread ...` عند الدعم، أو هيئ `bindings[]` على المستوى الأعلى، أو انتقل إلى قناة مدعومة. |
| `--thread here requires running /acp spawn inside an active ... thread` | استُخدم `--thread here` خارج سياق سلسلة. | انتقل إلى السلسلة المستهدفة أو استخدم `--thread auto`/`off`. |
| `Only <user-id> can rebind this channel/conversation/thread.` | يمتلك مستخدم آخر هدف الربط النشط. | أعد الربط بصفتك المالك أو استخدم محادثة أو سلسلة مختلفة. |
| `Thread bindings are unavailable for <channel>.` | لا يملك المهايئ قدرة ربط السلاسل. | استخدم `--thread off` أو انتقل إلى مهايئ/قناة مدعومة. |
| `Sandboxed sessions cannot spawn ACP sessions ...` | وقت تشغيل ACP يعمل على جهة المضيف؛ جلسة الطالب تعمل داخل sandbox. | استخدم `runtime="subagent"` من جلسات sandboxed، أو شغّل ACP spawn من جلسة غير sandboxed. |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | تم طلب `sandbox="require"` لوقت تشغيل ACP. | استخدم `runtime="subagent"` عندما يكون sandbox مطلوبًا، أو استخدم ACP مع `sandbox="inherit"` من جلسة غير sandboxed. |
| Missing ACP metadata for bound session | بيانات تعريف ACP قديمة/محذوفة للجلسة المرتبطة. | أعد الإنشاء باستخدام `/acp spawn`، ثم أعد الربط/تركيز السلسلة. |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | تمنع `permissionMode` عمليات الكتابة/التنفيذ في جلسة ACP غير تفاعلية. | عيّن `plugins.entries.acpx.config.permissionMode` إلى `approve-all` ثم أعد تشغيل البوابة. راجع [إعداد الأذونات](#permission-configuration). |
| تفشل جلسة ACP مبكرًا مع خرج قليل | تُحظر مطالبات الأذونات بواسطة `permissionMode`/`nonInteractivePermissions`. | تحقق من سجلات البوابة للعثور على `AcpRuntimeError`. للحصول على أذونات كاملة، عيّن `permissionMode=approve-all`؛ وللتراجع السلس، عيّن `nonInteractivePermissions=deny`. |
| تتوقف جلسة ACP إلى أجل غير مسمى بعد إكمال العمل | انتهت عملية harness لكن جلسة ACP لم تبلغ عن الاكتمال. | راقب عبر `ps aux \| grep acpx`; واقتل العمليات القديمة يدويًا. |
| العَرَض | السبب المرجّح | الإصلاح |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACP runtime backend is not configured` | plugin الواجهة الخلفية مفقود أو معطّل. | ثبّت plugin الواجهة الخلفية وفعّله، ثم شغّل `/acp doctor`. |
| `ACP is disabled by policy (acp.enabled=false)` | تم تعطيل ACP عالميًا. | اضبط `acp.enabled=true`. |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | تم تعطيل التوجيه من رسائل السلاسل العادية. | اضبط `acp.dispatch.enabled=true`. |
| `ACP agent "<id>" is not allowed by policy` | الوكيل ليس ضمن قائمة السماح. | استخدم `agentId` مسموحًا به أو حدّث `acp.allowedAgents`. |
| `Unable to resolve session target: ...` | رمز مفتاح/معرّف/تسمية غير صحيح. | شغّل `/acp sessions`، وانسخ المفتاح/التسمية بدقة، ثم أعد المحاولة. |
| `--bind here requires running /acp spawn inside an active ... conversation` | استُخدم `--bind here` بدون وجود محادثة نشطة قابلة للربط. | انتقل إلى الدردشة/القناة المستهدفة وأعد المحاولة، أو استخدم إنشاءً غير مرتبط. |
| `Conversation bindings are unavailable for <channel>.` | يفتقر المهايئ إلى قدرة ربط ACP بالمحادثة الحالية. | استخدم `/acp spawn ... --thread ...` عند الدعم، أو اضبط `bindings[]` ذات المستوى الأعلى، أو انتقل إلى قناة مدعومة. |
| `--thread here requires running /acp spawn inside an active ... thread` | استُخدم `--thread here` خارج سياق سلسلة. | انتقل إلى السلسلة المستهدفة أو استخدم `--thread auto`/`off`. |
| `Only <user-id> can rebind this channel/conversation/thread.` | يملك مستخدم آخر هدف الربط النشط. | أعد الربط بصفتك المالك أو استخدم محادثة أو سلسلة أخرى. |
| `Thread bindings are unavailable for <channel>.` | يفتقر المهايئ إلى قدرة ربط السلاسل. | استخدم `--thread off` أو انتقل إلى مهايئ/قناة مدعومين. |
| `Sandboxed sessions cannot spawn ACP sessions ...` | وقت تشغيل ACP يعمل على المضيف؛ وجلسة الطالب داخل sandbox. | استخدم `runtime="subagent"` من الجلسات داخل sandbox، أو شغّل إنشاء ACP من جلسة خارج sandbox. |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | طُلِب `sandbox="require"` لوقت تشغيل ACP. | استخدم `runtime="subagent"` إذا كان العزل الإلزامي مطلوبًا، أو استخدم ACP مع `sandbox="inherit"` من جلسة خارج sandbox. |
| Missing ACP metadata for bound session | بيانات تعريف ACP قديمة/محذوفة للجلسة المرتبطة. | أعد الإنشاء باستخدام `/acp spawn`، ثم أعد الربط/التركيز على السلسلة. |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | يمنع `permissionMode` عمليات الكتابة/التنفيذ في جلسة ACP غير تفاعلية. | اضبط `plugins.entries.acpx.config.permissionMode` على `approve-all` وأعد تشغيل البوابة. راجع [إعدادات الأذونات](#permission-configuration). |
| ACP session fails early with little output | يتم حظر مطالبات الأذونات بواسطة `permissionMode`/`nonInteractivePermissions`. | تحقّق من سجلات البوابة بحثًا عن `AcpRuntimeError`. للحصول على أذونات كاملة، اضبط `permissionMode=approve-all`؛ وللتدهور السلس، اضبط `nonInteractivePermissions=deny`. |
| ACP session stalls indefinitely after completing work | انتهت عملية الحاضنة لكن جلسة ACP لم تُبلغ عن الاكتمال. | راقب باستخدام `ps aux \| grep acpx`; واقتل العمليات العالقة يدويًا. |

545
docs/ar/tools/exec-approvals.md
View File

@ -1,70 +1,70 @@
---
read_when:
- ضبط موافقات exec أو قوائم السماح
- تنفيذ تجربة مستخدم موافقات exec في تطبيق macOS
- مراجعة مطالبات الخروج من sandbox وآثارها
summary: موافقات exec وقوائم السماح ومطالبات الخروج من sandbox
- عند تكوين موافقات exec أو قوائم السماح
- عند تنفيذ واجهة مستخدم موافقة exec في تطبيق macOS
- عند مراجعة مطالبات الخروج من العزل وتبعاتها
summary: موافقات exec، قوائم السماح، ومطالبات الخروج من العزل
title: موافقات Exec
x-i18n:
generated_at: "2026-04-06T03:14:23Z"
generated_at: "2026-04-08T02:22:46Z"
model: gpt-5.4
provider: openai
source_hash: 39e91cd5c7615bdb9a6b201a85bde7514327910f6f12da5a4b0532bceb229c22
source_hash: 6041929185bab051ad873cc4822288cb7d6f0470e19e7ae7a16b70f76dfc2cd9
source_path: tools/exec-approvals.md
workflow: 15
---
# موافقات Exec
تمثل موافقات exec **حاجز الحماية للتطبيق المرافق / مستضيف العقدة** للسماح لوكيل داخل sandbox بتشغيل
أوامر على مستضيف حقيقي (`gateway` أو `node`). فكّر فيها على أنها قفل أمان:
لا يُسمح بالأوامر إلا عندما تتفق السياسة + قائمة السماح + (اختياريًا) موافقة المستخدم كلها.
تأتي موافقات exec **بالإضافة** إلى سياسة الأدوات وتقييد elevated (إلا إذا كانت elevated مضبوطة على `full`، إذ يتم تجاوز الموافقات).
السياسة الفعلية هي **الأكثر تقييدًا** بين `tools.exec.*` والقيم الافتراضية للموافقات؛ وإذا تم حذف أحد حقول الموافقات، تُستخدم قيمة `tools.exec`.
يستخدم exec على المستضيف أيضًا حالة الموافقات المحلية على ذلك الجهاز. إن كانت قيمة
`ask: "always"` المحلية على المستضيف في `~/.openclaw/exec-approvals.json` مضبوطة، فسيستمر
إظهار المطالبة حتى لو طلبت الجلسة أو الإعدادات الافتراضية `ask: "on-miss"`.
استخدم `openclaw approvals get`، أو `openclaw approvals get --gateway`، أو
تُعد موافقات exec **وسيلة الحماية في التطبيق المرافق / مضيف العقدة** للسماح لوكيل معزول بتشغيل
الأوامر على مضيف فعلي (`gateway` أو `node`). فكّر فيها كأنها قفل أمان:
لا يُسمح بالأوامر إلا عندما تتفق السياسة + قائمة السماح + (اختياريًا) موافقة المستخدم جميعًا.
تُستخدم موافقات exec **بالإضافة** إلى سياسة الأدوات وبوابة elevated (إلا إذا كانت قيمة elevated هي `full`، إذ يتم عندها تجاوز الموافقات).
السياسة الفعلية هي **الأكثر تقييدًا** بين `tools.exec.*` والإعدادات الافتراضية للموافقات؛ إذا تم حذف حقل من حقول الموافقات، تُستخدم قيمة `tools.exec`.
يستخدم exec على المضيف أيضًا حالة الموافقات المحلية على تلك الآلة. تؤدي قيمة
`ask: "always"` المحلية للمضيف في `~/.openclaw/exec-approvals.json` إلى استمرار ظهور المطالبات حتى إذا
كانت إعدادات الجلسة أو التكوين الافتراضية تطلب `ask: "on-miss"`.
استخدم `openclaw approvals get` أو `openclaw approvals get --gateway` أو
`openclaw approvals get --node <id|name|ip>` لفحص السياسة المطلوبة،
ومصادر سياسة المستضيف، والنتيجة الفعلية.
ومصادر سياسة المضيف، والنتيجة الفعلية.
إذا كانت واجهة التطبيق المرافق **غير متاحة**، فإن أي طلب يتطلب مطالبة
يُحسم بواسطة **البديل ask** (والافتراضي هو deny).
يُحسم بواسطة **الرجوع الاحتياطي للسؤال** (الافتراضي: الرفض).
يمكن لعملاء الموافقة الأصليين في الدردشة أيضًا عرض وسائل خاصة بكل قناة على
رسالة الموافقة المعلقة. على سبيل المثال، يمكن لـ Matrix إنشاء اختصارات تفاعلات على
مطالبة الموافقة (`✅` للسماح مرة واحدة، و`❌` للرفض، و`♾️` للسماح دائمًا عند التوفر)
مع الإبقاء على أوامر `/approve ...` في الرسالة كبديل.
يمكن لعملاء الموافقة الأصليين في الدردشة أيضًا عرض عناصر تفاعل خاصة بالقناة على
رسالة الموافقة المعلقة. على سبيل المثال، يمكن لـ Matrix تهيئة اختصارات التفاعل على
مطالبة الموافقة (`✅` للسماح مرة واحدة، و`❌` للرفض، و`♾️` للسماح دائمًا عند توفره)
مع الإبقاء على أوامر `/approve ...` في الرسالة كخيار احتياطي.
## أين ينطبق ذلك
تُفرض موافقات exec محليًا على مستضيف التنفيذ:
تُفرض موافقات exec محليًا على مضيف التنفيذ:
- **مستضيف gateway** → عملية `openclaw` على جهاز البوابة
- **مستضيف node** → مشغل العقدة (تطبيق macOS المرافق أو مستضيف عقدة بدون واجهة)
- **مضيف gateway** ← عملية `openclaw` على جهاز gateway
- **مضيف node** ← مشغّل العقدة (تطبيق macOS المرافق أو مضيف عقدة بدون واجهة)
ملاحظة حول نموذج الثقة:
- يُعد المستدعون المصادق عليهم عبر البوابة مشغلين موثوقين لتلك البوابة.
- توسّع العقد المقترنة هذه القدرة الخاصة بالمشغّل الموثوق إلى مستضيف العقدة.
- تقلل موافقات exec من مخاطر التنفيذ العرضي، لكنها ليست حدًا للمصادقة لكل مستخدم.
- تربط التشغيلات الموافق عليها على مستضيف العقدة سياق تنفيذ قياسيًا: `cwd` القياسي، و`argv` الدقيق، وربط `env`
عند وجوده، ومسار الملف التنفيذي المثبّت عند الاقتضاء.
- بالنسبة إلى shell scripts واستدعاءات الملفات المباشرة للمفسر/وقت التشغيل، يحاول OpenClaw أيضًا ربط
معامل ملف محلي ملموس واحد. إذا تغيّر هذا الملف المرتبط بعد الموافقة ولكن قبل التنفيذ،
- يُعد المستدعون المصادق عليهم من قبل Gateway مشغّلين موثوقين لذلك الـ Gateway.
- توسّع العقد المقترنة هذه القدرة التشغيلية الموثوقة إلى مضيف العقدة.
- تقلل موافقات exec من خطر التنفيذ العرضي، لكنها ليست حدًا للمصادقة لكل مستخدم.
- ترتبط عمليات التشغيل المعتمدة على مضيف العقدة بسياق تنفيذ أساسي: cwd أساسي، وargv مطابق، وربط env
عند وجوده، ومسار ملف تنفيذي مثبت عند الاقتضاء.
- بالنسبة إلى نصوص shell البرمجية والاستدعاءات المباشرة لملفات المفسر/بيئة التشغيل، يحاول OpenClaw أيضًا ربط
مُعامل ملف محلي ملموس واحد. إذا تغيّر هذا الملف المرتبط بعد الموافقة ولكن قبل التنفيذ،
يُرفض التشغيل بدلًا من تنفيذ محتوى منجرف.
- هذا الربط للملفات هو عمدًا بأفضل جهد ممكن، وليس نموذجًا دلاليًا كاملًا لكل
مسارات تحميل المفسرات/أوقات التشغيل. إذا تعذر على وضع الموافقة تحديد ملف محلي ملموس واحد بالضبط
- يظل ربط الملفات هذا عمدًا على أساس أفضل جهد، وليس نموذجًا دلاليًا كاملًا لكل
مسار تحميل خاص بالمفسر/بيئة التشغيل. إذا تعذر على وضع الموافقة تحديد ملف محلي ملموس واحد بالضبط
لربطه، فإنه يرفض إنشاء تشغيل مدعوم بالموافقة بدلًا من الادعاء بتغطية كاملة.
الانقسام في macOS:
تقسيم macOS:
- **خدمة مستضيف node** تمرر `system.run` إلى **تطبيق macOS** عبر IPC محلي.
- **تطبيق macOS** يفرض الموافقات + ينفذ الأمر في سياق واجهة المستخدم.
- تقوم **خدمة مضيف node** بتمرير `system.run` إلى **تطبيق macOS** عبر IPC محلي.
- يقوم **تطبيق macOS** بفرض الموافقات + تنفيذ الأمر ضمن سياق واجهة المستخدم.
## الإعدادات والتخزين
توجد الموافقات في ملف JSON محلي على مستضيف التنفيذ:
تعيش الموافقات في ملف JSON محلي على مضيف التنفيذ:
`~/.openclaw/exec-approvals.json`
@ -103,30 +103,30 @@ x-i18n:
}
```
## وضع "YOLO" من دون موافقة
## وضع "YOLO" بدون موافقة
إذا كنت تريد أن يعمل exec على المستضيف من دون مطالبات موافقة، فيجب فتح **طبقتَي** السياسة كلتيهما:
إذا كنت تريد تشغيل exec على المضيف دون مطالبات موافقة، فيجب عليك فتح **طبقتي** السياسة كلتيهما:
- سياسة exec المطلوبة في إعدادات OpenClaw (`tools.exec.*`)
- سياسة الموافقات المحلية على المستضيف في `~/.openclaw/exec-approvals.json`
- سياسة الموافقات المحلية على المضيف في `~/.openclaw/exec-approvals.json`
هذا هو الآن سلوك المستضيف الافتراضي ما لم تُحكم تقييده صراحة:
هذا هو الآن سلوك المضيف الافتراضي ما لم تشدده صراحةً:
- `tools.exec.security`: ‏`full` على `gateway`/`node`
- `tools.exec.ask`: ‏`off`
- قيمة `askFallback` على المستضيف: ‏`full`
- `tools.exec.security`: `full` على `gateway`/`node`
- `tools.exec.ask`: `off`
- `askFallback` على المضيف: `full`
تمييز مهم:
- يختار `tools.exec.host=auto` مكان تشغيل exec: داخل sandbox عند توفره، وإلا على gateway.
- ويختار وضع YOLO كيفية الموافقة على exec على المستضيف: `security=full` بالإضافة إلى `ask=off`.
- في وضع YOLO، لا يضيف OpenClaw بوابة موافقة منفصلة قائمة على الكشف الإرشادي عن تمويه الأوامر فوق سياسة exec على المستضيف المضبوطة.
- لا يجعل `auto` توجيه gateway تجاوزًا مجانيًا من جلسة داخل sandbox. يُسمح بطلب `host=node` لكل استدعاء من `auto`، ولا يُسمح بـ `host=gateway` من `auto` إلا عندما لا يكون هناك runtime نشط لـ sandbox. إذا كنت تريد قيمة افتراضية ثابتة غير auto، فاضبط `tools.exec.host` أو استخدم `/exec host=...` صراحة.
- يحدد `tools.exec.host=auto` مكان تشغيل exec: داخل العزل عند توفره، وإلا على gateway.
- يحدد YOLO كيفية اعتماد exec على المضيف: `security=full` مع `ask=off`.
- في وضع YOLO، لا يضيف OpenClaw بوابة موافقة استدلالية منفصلة لإخفاء الأوامر فوق سياسة exec على المضيف المكوّنة.
- لا يجعل `auto` توجيه gateway تجاوزًا مجانيًا من جلسة معزولة. يُسمح بطلب `host=node` لكل استدعاء من `auto`، ويُسمح بـ `host=gateway` من `auto` فقط عندما لا تكون هناك بيئة تشغيل عزل نشطة. إذا كنت تريد إعدادًا افتراضيًا ثابتًا غير auto، فاضبط `tools.exec.host` أو استخدم `/exec host=...` صراحةً.
إذا كنت تريد إعدادًا أكثر تحفظًا، فأعد تشديد أي من الطبقتين إلى `allowlist` / `on-miss`
أو `deny`.
إعداد دائم على مستضيف gateway لتعطيل كل المطالبات:
إعداد دائم لـ gateway-host مع "عدم المطالبة مطلقًا":
```bash
openclaw config set tools.exec.host gateway
@ -135,7 +135,7 @@ openclaw config set tools.exec.ask off
openclaw gateway restart
```
ثم اضبط ملف الموافقات على المستضيف ليتطابق:
ثم اضبط ملف موافقات المضيف ليتطابق:
```bash
openclaw approvals set --stdin <<'EOF'
@ -150,7 +150,7 @@ openclaw approvals set --stdin <<'EOF'
EOF
```
وبالنسبة إلى مستضيف node، طبّق ملف الموافقات نفسه على تلك العقدة بدلًا من ذلك:
بالنسبة إلى مضيف node، طبّق ملف الموافقات نفسه على تلك العقدة بدلًا من ذلك:
```bash
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
@ -165,39 +165,39 @@ openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
EOF
```
اختصار خاص بالجلسة فقط:
اختصار على مستوى الجلسة فقط:
- يغيّر `/exec security=full ask=off` الجلسة الحالية فقط.
- يُعد `/elevated full` اختصارًا للطوارئ يتجاوز أيضًا موافقات exec لتلك الجلسة.
- يعد `/elevated full` اختصارًا للطوارئ يتجاوز أيضًا موافقات exec لتلك الجلسة.
إذا ظل ملف الموافقات على المستضيف أكثر تقييدًا من الإعدادات، فستظل سياسة المستضيف الأكثر تشددًا هي السارية.
إذا ظل ملف موافقات المضيف أكثر تقييدًا من الإعدادات، فستظل سياسة المضيف الأكثر تقييدًا هي السارية.
## عناصر التحكم في السياسة
## مفاتيح السياسة
### الأمان (`exec.security`)
- **deny**: حظر كل طلبات exec على المستضيف.
- **allowlist**: السماح فقط بالأوامر الموجودة في قائمة السماح.
- **deny**: حظر جميع طلبات exec على المضيف.
- **allowlist**: السماح فقط للأوامر الموجودة في قائمة السماح.
- **full**: السماح بكل شيء (مكافئ لـ elevated).
### Ask (`exec.ask`)
### السؤال (`exec.ask`)
- **off**: عدم إظهار مطالبة مطلقًا.
- **on-miss**: إظهار مطالبة فقط عندما لا تطابق قائمة السماح.
- **always**: إظهار مطالبة لكل أمر.
- لا يؤدي trust الدائم `allow-always` إلى إخفاء المطالبات عندما يكون وضع ask الفعلي هو `always`
- **off**: عدم عرض أي مطالبة مطلقًا.
- **on-miss**: عرض مطالبة فقط عندما لا تتطابق قائمة السماح.
- **always**: عرض مطالبة لكل أمر.
- الثقة الدائمة `allow-always` لا تمنع ظهور المطالبات عندما يكون وضع السؤال الفعلي هو `always`
### Ask fallback (`askFallback`)
### الرجوع الاحتياطي للسؤال (`askFallback`)
إذا كانت المطالبة مطلوبة ولكن لا توجد واجهة مستخدم قابلة للوصول، فإن البديل يقرر:
إذا كانت المطالبة مطلوبة ولكن لا يمكن الوصول إلى واجهة مستخدم، فإن آلية الرجوع الاحتياطي تقرر:
- **deny**: حظر.
- **allowlist**: السماح فقط إذا طابقت قائمة السماح.
- **allowlist**: السماح فقط إذا تطابقت قائمة السماح.
- **full**: السماح.
### تقوية eval المضمنة للمفسر (`tools.exec.strictInlineEval`)
### تقوية eval المضمن للمفسر (`tools.exec.strictInlineEval`)
عندما تكون `tools.exec.strictInlineEval=true`، يعامل OpenClaw صيغ eval المضمنة على أنها تتطلب موافقة فقط حتى لو كان ملف المفسر التنفيذي نفسه موجودًا في قائمة السماح.
عندما تكون القيمة `tools.exec.strictInlineEval=true`، يتعامل OpenClaw مع صيغ eval البرمجية المضمنة على أنها تتطلب الموافقة فقط حتى لو كان ملف المفسر نفسه ضمن قائمة السماح.
أمثلة:
@ -209,19 +209,18 @@ EOF
- `lua -e`
- `osascript -e`
هذا دفاع إضافي لطبقة التفسير بالنسبة إلى محمّلات المفسرات التي لا ترتبط بوضوح
بمعامل ملف واحد ثابت. في الوضع الصارم:
هذا دفاع إضافي للمحمّلات الخاصة بالمفسرات التي لا ترتبط بوضوح بملف ثابت واحد. في الوضع الصارم:
- لا تزال هذه الأوامر تحتاج إلى موافقة صريحة؛
- ولا يؤدي `allow-always` إلى حفظ إدخالات جديدة في قائمة السماح لها تلقائيًا.
- لا يؤدي `allow-always` إلى حفظ إدخالات جديدة في قائمة السماح لها تلقائيًا.
## قائمة السماح (لكل وكيل)
تكون قوائم السماح **لكل وكيل**. إذا كان هناك عدة وكلاء، فبدّل الوكيل الذي تقوم
بتحريره في تطبيق macOS. الأنماط هي **مطابقات glob غير حساسة لحالة الأحرف**.
ويجب أن تُحل الأنماط إلى **مسارات ملفات تنفيذية** (ويتم تجاهل الإدخالات التي تحتوي على الاسم الأساسي فقط).
تُرحّل إدخالات `agents.default` القديمة إلى `agents.main` عند التحميل.
ولا تزال سلاسل shell مثل `echo ok && pwd` تتطلب أن يحقق كل مقطع من المستوى الأعلى قواعد قائمة السماح.
تكون قوائم السماح **لكل وكيل**. إذا كان هناك عدة وكلاء، فبدّل الوكيل الذي
تقوم بتحريره في تطبيق macOS. تكون الأنماط **مطابقات glob غير حساسة لحالة الأحرف**.
يجب أن تُحل الأنماط إلى **مسارات ملفات تنفيذية** (تُتجاهل الإدخالات التي تحتوي على الاسم الأساسي فقط).
تُنقل إدخالات `agents.default` القديمة إلى `agents.main` عند التحميل.
لا تزال سلاسل shell مثل `echo ok && pwd` تتطلب أن يستوفي كل جزء علوي قواعد قائمة السماح.
أمثلة:
@ -231,43 +230,43 @@ EOF
يتتبع كل إدخال في قائمة السماح:
- **id** UUID ثابت يُستخدم لهوية واجهة المستخدم (اختياري)
- **id** معرّف UUID ثابت يُستخدم لهوية واجهة المستخدم (اختياري)
- **آخر استخدام** طابع زمني
- **آخر أمر مستخدم**
- **آخر مسار محلول**
- **آخر مسار تم حله**
## Auto-allow لـ CLIs الخاصة بـ Skills
## السماح التلقائي لـ CLI الخاصة بـ Skills
عند تفعيل **Auto-allow skill CLIs**، تُعامل الملفات التنفيذية المشار إليها من Skills معروفة
على أنها موجودة في قائمة السماح على العقد (عقدة macOS أو مستضيف عقدة بدون واجهة). يستخدم هذا
`skills.bins` عبر Gateway RPC لجلب قائمة ملفات skill bin. عطّل هذا إذا كنت تريد قوائم سماح يدوية صارمة.
عند تمكين **السماح التلقائي لـ CLI الخاصة بـ Skills**، تُعامل الملفات التنفيذية المشار إليها بواسطة Skills المعروفة
على أنها مدرجة في قائمة السماح على العقد (عقدة macOS أو مضيف عقدة بدون واجهة). يستخدم هذا
`skills.bins` عبر Gateway RPC لجلب قائمة ملفات bin الخاصة بالمهارات. عطّل هذا إذا كنت تريد قوائم سماح يدوية صارمة.
ملاحظات ثقة مهمة:
- هذه **قائمة سماح ضمنية للتيسير**، منفصلة عن إدخالات قائمة السماح اليدوية للمسارات.
- وهي مخصّصة لبيئات المشغّلين الموثوقين حيث تقع البوابة والعقدة ضمن حدود الثقة نفسها.
- إذا كنت تحتاج إلى ثقة صريحة صارمة، فأبقِ `autoAllowSkills: false` واستخدم إدخالات قائمة السماح اليدوية للمسارات فقط.
- هذه **قائمة سماح ضمنية للتسهيل**، منفصلة عن إدخالات قائمة سماح المسارات اليدوية.
- وهي مخصصة لبيئات المشغّلين الموثوقين حيث يكون Gateway والعقدة ضمن حدود الثقة نفسها.
- إذا كنت تحتاج إلى ثقة صريحة صارمة، فأبقِ `autoAllowSkills: false` واستخدم إدخالات قائمة سماح المسارات اليدوية فقط.
## Safe bins (stdin-only)
يعرّف `tools.exec.safeBins` قائمة صغيرة من الملفات التنفيذية **المقتصرة على stdin** (مثل `cut`)
والتي يمكن تشغيلها في وضع allowlist **من دون** إدخالات صريحة في قائمة السماح. ترفض safe bins
وسائط الملفات الموضعية والرموز الشبيهة بالمسارات، لذا يمكنها العمل فقط على الدفق الوارد.
تعامل مع هذا على أنه مسار سريع ضيق لفلاتر الدفق، وليس قائمة ثقة عامة.
**لا** تضف ملفات المفسرات أو أوقات التشغيل التنفيذية (مثل `python3` أو `node` أو `ruby` أو `bash` أو `sh` أو `zsh`) إلى `safeBins`.
إذا كان بإمكان أمر ما تقييم الشيفرة أو تنفيذ أوامر فرعية أو قراءة ملفات بطبيعته، ففضّل إدخالات قائمة سماح صريحة مع إبقاء مطالبات الموافقة مفعلة.
يجب أن تعرّف safe bins المخصصة ملف تعريف صريحًا في `tools.exec.safeBinProfiles.<bin>`.
ويكون التحقق حتميًا من شكل argv فقط (من دون فحوصات لوجود الملفات في نظام ملفات المستضيف)،
مما يمنع سلوك oracle لوجود الملفات الناتج عن فروق السماح/المنع.
تُرفض الخيارات الموجهة للملفات بالنسبة إلى safe bins الافتراضية (مثل `sort -o` و`sort --output`,
و`sort --files0-from` و`sort --compress-program` و`sort --random-source`,
و`sort --temporary-directory`/`-T`، و`wc --files0-from`، و`jq -f/--from-file`,
يحدد `tools.exec.safeBins` قائمة صغيرة من الملفات الثنائية **الخاصة بـ stdin فقط** (مثل `cut`)
التي يمكنها التشغيل في وضع allowlist **من دون** إدخالات صريحة في قائمة السماح. ترفض Safe bins
وسائط الملفات الموضعية والرموز الشبيهة بالمسارات، لذلك لا يمكنها العمل إلا على الدفق الوارد.
تعامل مع ذلك كمسار سريع ضيق لمرشحات الدفق، وليس كقائمة ثقة عامة.
**لا** تضف ملفات مفسرات أو بيئات تشغيل ثنائية (مثل `python3` و`node` و`ruby` و`bash` و`sh` و`zsh`) إلى `safeBins`.
إذا كان بإمكان الأمر تقييم تعليمات برمجية، أو تنفيذ أوامر فرعية، أو قراءة ملفات بطبيعته، ففضّل إدخالات قائمة السماح الصريحة وأبقِ مطالبات الموافقة مفعّلة.
يجب أن تحدد Safe bins المخصصة ملف تعريف صريحًا في `tools.exec.safeBinProfiles.<bin>`.
يكون التحقق حتميًا استنادًا إلى شكل argv فقط (من دون فحوصات لوجود الملفات على نظام المضيف)، مما
يمنع سلوك تسريب معلومات وجود الملفات من خلال اختلافات السماح/الرفض.
تُرفض الخيارات الموجهة للملفات بالنسبة إلى Safe bins الافتراضية (مثل `sort -o` و`sort --output`،
و`sort --files0-from` و`sort --compress-program` و`sort --random-source`،
و`sort --temporary-directory`/`-T`، و`wc --files0-from`، و`jq -f/--from-file`،
و`grep -f/--file`).
وتفرض safe bins أيضًا سياسة صريحة لكل ملف تنفيذي على مستوى الأعلام بالنسبة إلى الخيارات التي تكسر
سلوك stdin-only (مثل `sort -o/--output/--compress-program` وأعلام grep التكرارية).
ويتم التحقق من الخيارات الطويلة بأسلوب fail-closed في وضع safe-bin: تُرفض الأعلام غير المعروفة
والاختصارات الغامضة.
الأعلام الممنوعة بحسب ملف تعريف safe-bin:
تفرض Safe bins أيضًا سياسة صريحة لكل ملف ثنائي على مستوى العلامات للخيارات التي تكسر سلوك
stdin-only (مثل `sort -o/--output/--compress-program` وعلامات grep التكرارية).
تُتحقق الخيارات الطويلة وفق مبدأ الفشل المغلق في وضع safe-bin: تُرفض العلامات غير المعروفة
والاختصارات الملتبسة.
العلامات المرفوضة حسب ملف تعريف safe-bin:
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
@ -278,33 +277,34 @@ EOF
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
وتفرض safe bins أيضًا معاملة رموز argv على أنها **نص حرفي** وقت التنفيذ (من دون globbing
ولا توسيع `$VARS`) لمقاطع stdin-only، بحيث لا يمكن استخدام أنماط مثل `*` أو `$HOME/...`
تُجبر Safe bins أيضًا رموز argv على أن تُعامل كـ **نص حرفي** في وقت التنفيذ (من دون globbing
ومن دون توسيع `$VARS`) بالنسبة إلى المقاطع الخاصة بـ stdin فقط، بحيث لا يمكن استخدام أنماط مثل `*` أو `$HOME/...`
لتهريب قراءات الملفات.
كما يجب أن تُحل safe bins من أدلة ملفات تنفيذية موثوق بها (القيم الافتراضية للنظام بالإضافة إلى
`tools.exec.safeBinTrustedDirs` الاختيارية). ولا تُعامل إدخالات `PATH` على أنها موثوقة تلقائيًا.
إن أدلة safe-bin الافتراضية الموثوقة محدودة عمدًا: `/bin`، `/usr/bin`.
إذا كان الملف التنفيذي الخاص بـ safe-bin لديك موجودًا في مسارات مدير الحزم/المستخدم (مثل
`/opt/homebrew/bin` أو `/usr/local/bin` أو `/opt/local/bin` أو `/snap/bin`)، فأضفها صراحة
يجب أيضًا أن تُحل Safe bins من أدلة ملفات ثنائية موثوقة (الإعدادات الافتراضية للنظام بالإضافة إلى
`tools.exec.safeBinTrustedDirs` الاختيارية). لا تُعد إدخالات `PATH` موثوقة تلقائيًا أبدًا.
أدلة Safe-bin الموثوقة الافتراضية محدودة عمدًا: `/bin`، `/usr/bin`.
إذا كان الملف التنفيذي لـ safe-bin موجودًا في مسارات مدير الحزم/المستخدم (مثل
`/opt/homebrew/bin` أو `/usr/local/bin` أو `/opt/local/bin` أو `/snap/bin`)، فأضفها صراحةً
إلى `tools.exec.safeBinTrustedDirs`.
لا يُسمح تلقائيًا بسلاسل shell وعمليات إعادة التوجيه في وضع allowlist.
لا يُسمح تلقائيًا بتسلسل shell وإعادات التوجيه في وضع allowlist.
يُسمح بسلاسل shell (`&&` و`||` و`;`) عندما يحقق كل مقطع من المستوى الأعلى متطلبات قائمة السماح
(بما في ذلك safe bins أو auto-allow الخاصة بـ skill). ولا تزال عمليات إعادة التوجيه غير مدعومة في وضع allowlist.
ويُرفض command substitution (`$()` / backticks) أثناء تحليل allowlist، بما في ذلك داخل
يُسمح بتسلسل shell (`&&` و`||` و`;`) عندما يستوفي كل جزء علوي متطلبات قائمة السماح
(بما في ذلك safe bins أو السماح التلقائي للمهارات). تظل إعادات التوجيه غير مدعومة في وضع allowlist.
يُرفض استبدال الأوامر (`$()` / backticks) أثناء تحليل allowlist، بما في ذلك داخل
علامات الاقتباس المزدوجة؛ استخدم علامات اقتباس مفردة إذا كنت تحتاج إلى نص `$()` حرفي.
في موافقات تطبيق macOS المرافق، يُعامل نص shell الخام الذي يحتوي على صياغات تحكم shell أو التوسيع
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) على أنه عدم تطابق مع allowlist ما لم
يكن ملف shell التنفيذي نفسه موجودًا في قائمة السماح.
بالنسبة إلى مغلفات shell (`bash|sh|zsh ... -c/-lc`)، تُختزل تجاوزات env ضمن نطاق الطلب إلى
قائمة سماح صغيرة وصريحة (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
وبالنسبة إلى قرارات allow-always في وضع allowlist، فإن مغلفات الإرسال المعروفة
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) تحفظ مسارات الملفات التنفيذية الداخلية بدلًا
من مسارات المغلفات. كما يتم أيضًا فك multiplexers الخاصة بالـ shell (`busybox`, `toybox`) في حالة applets الخاصة بالـ shell (`sh`, `ash`، إلخ) بحيث تُحفَظ الملفات التنفيذية الداخلية بدلًا من ملفات multiplexer التنفيذية. وإذا تعذر
فك غلاف أو multiplexer بأمان، فلا يتم حفظ أي إدخال في قائمة السماح تلقائيًا.
إذا وضعت مفسرات مثل `python3` أو `node` في قائمة السماح، ففضّل `tools.exec.strictInlineEval=true` بحيث يظل inline eval يتطلب موافقة صريحة. في الوضع الصارم، لا يزال `allow-always` قادرًا على حفظ استدعاءات مفسر/سكريبت غير ضارة، لكن الوسائط الحاملة لـ inline-eval لا تُحفَظ تلقائيًا.
في موافقات تطبيق macOS المرافق، يُعامل نص shell الخام الذي يحتوي على بنية تحكم أو توسيع shell
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) على أنه عدم تطابق مع allowlist إلا إذا
كان الملف الثنائي لـ shell نفسه موجودًا في allowlist.
بالنسبة إلى أغلفة shell (`bash|sh|zsh ... -c/-lc`)، تُخفض تجاوزات env على مستوى الطلب إلى
قائمة سماح صريحة صغيرة (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
بالنسبة إلى قرارات allow-always في وضع allowlist، تحفظ أغلفة الإرسال المعروفة
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) مسارات الملفات التنفيذية الداخلية بدلًا من مسارات
الأغلفة. كما تُفك أيضًا أغلفة تعدد shell (`busybox`, `toybox`) بالنسبة إلى تطبيقات shell الصغيرة (`sh`, `ash`,
وغيرها) بحيث تُحفظ الملفات التنفيذية الداخلية بدلًا من الملفات الثنائية الخاصة بالمضاعِف. إذا تعذر فك غلاف أو
مضاعِف بأمان، فلا يُحفَظ أي إدخال في allowlist تلقائيًا.
إذا أضفت مفسرات مثل `python3` أو `node` إلى allowlist، ففضّل `tools.exec.strictInlineEval=true` حتى يظل eval المضمن يتطلب موافقة صريحة. في الوضع الصارم، لا يزال بإمكان `allow-always` حفظ استدعاءات مفسر/نص برمجي غير ضارة، لكن حوامل inline-eval لا تُحفَظ تلقائيًا.
القيم الافتراضية لـ safe bins:
Safe bins الافتراضية:
[//]: # "SAFE_BIN_DEFAULTS:START"
@ -312,214 +312,213 @@ EOF
[//]: # "SAFE_BIN_DEFAULTS:END"
لا يشمل ذلك `grep` و`sort` في القائمة الافتراضية. إذا فعّلتهما صراحة، فأبقِ إدخالات قائمة سماح صريحة
لسير العمل غير المعتمد على stdin الخاص بهما.
بالنسبة إلى `grep` في وضع safe-bin، قدّم النمط باستخدام `-e`/`--regexp`؛
ويُرفض الشكل الموضعي للنمط حتى لا يمكن تهريب معاملات الملفات بوصفها معاملات موضعية غامضة.
لا يوجد `grep` و`sort` في القائمة الافتراضية. إذا قمت بتمكينهما صراحةً، فأبقِ إدخالات allowlist صريحة من أجل
سير العمل غير المعتمد على stdin.
بالنسبة إلى `grep` في وضع safe-bin، وفّر النمط باستخدام `-e`/`--regexp`؛
يُرفض شكل النمط الموضعي حتى لا يمكن تهريب معاملات الملفات كمعاملات موضعية ملتبسة.
### Safe bins مقابل allowlist
| الموضوع | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| الهدف | السماح التلقائي لفلاتر stdin الضيقة | الوثوق الصريح بملفات تنفيذية محددة |
| نوع المطابقة | اسم الملف التنفيذي + سياسة argv الخاصة بـ safe-bin | نمط glob لمسار الملف التنفيذي المحلول |
| نطاق الوسائط | مقيّد بملف تعريف safe-bin وقواعد الرموز الحرفية | المطابقة على المسار فقط؛ أما الوسائط فهي ضمن مسؤوليتك |
| أمثلة شائعة | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, CLIs مخصصة |
| أفضل استخدام | تحويلات نصية منخفضة المخاطر في خطوط الأنابيب | أي أداة ذات سلوك أوسع أو آثار جانبية |
| الموضوع | `tools.exec.safeBins` | allowlist (`exec-approvals.json`) |
| ---------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
| الهدف | السماح التلقائي لمرشحات stdin الضيقة | الثقة الصريحة في ملفات تنفيذية محددة |
| نوع المطابقة | اسم الملف التنفيذي + سياسة argv الخاصة بـ safe-bin | نمط glob لمسار الملف التنفيذي الذي تم حله |
| نطاق الوسائط | مقيّد بملف تعريف safe-bin وقواعد الرموز الحرفية | مطابقة المسار فقط؛ أما الوسائط فهي مسؤوليتك |
| أمثلة نموذجية | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, CLI مخصصة |
| أفضل استخدام | تحويلات نصية منخفضة المخاطر داخل خطوط الأنابيب | أي أداة ذات سلوك أوسع أو آثار جانبية |
موقع الإعدادات:
موقع التكوين:
- تأتي `safeBins` من الإعدادات (`tools.exec.safeBins` أو لكل وكيل `agents.list[].tools.exec.safeBins`).
- تأتي `safeBinTrustedDirs` من الإعدادات (`tools.exec.safeBinTrustedDirs` أو لكل وكيل `agents.list[].tools.exec.safeBinTrustedDirs`).
- تأتي `safeBinProfiles` من الإعدادات (`tools.exec.safeBinProfiles` أو لكل وكيل `agents.list[].tools.exec.safeBinProfiles`). وتتجاوز مفاتيح ملفات التعريف لكل وكيل المفاتيح العامة.
- تعيش إدخالات allowlist في `~/.openclaw/exec-approvals.json` المحلي على المستضيف تحت `agents.<id>.allowlist` (أو عبر Control UI / `openclaw approvals allowlist ...`).
- يحذر `openclaw security audit` باستخدام `tools.exec.safe_bins_interpreter_unprofiled` عندما تظهر ملفات المفسر/وقت التشغيل التنفيذية في `safeBins` من دون ملفات تعريف صريحة.
- يمكن لـ `openclaw doctor --fix` إنشاء إدخالات `safeBinProfiles.<bin>` المخصصة المفقودة تلقائيًا على شكل `{}` (راجعها وشدّدها بعد ذلك). ولا يتم إنشاء ملفات تعريف ملفات المفسرات/أوقات التشغيل التنفيذية تلقائيًا.
- تأتي `safeBinProfiles` من الإعدادات (`tools.exec.safeBinProfiles` أو لكل وكيل `agents.list[].tools.exec.safeBinProfiles`). تتجاوز مفاتيح ملفات التعريف لكل وكيل المفاتيح العامة.
- تعيش إدخالات allowlist في `~/.openclaw/exec-approvals.json` المحلي على المضيف تحت `agents.<id>.allowlist` (أو عبر Control UI / `openclaw approvals allowlist ...`).
- يحذر `openclaw security audit` بواسطة `tools.exec.safe_bins_interpreter_unprofiled` عندما تظهر ملفات مفسرات/بيئات تشغيل ثنائية في `safeBins` من دون ملفات تعريف صريحة.
- يمكن لـ `openclaw doctor --fix` إنشاء إدخالات `safeBinProfiles.<bin>` المخصصة المفقودة على شكل `{}` (راجعها وشددها بعد ذلك). لا تُنشأ ملفات مفسرات/بيئات التشغيل الثنائية تلقائيًا.
مثال على ملف تعريف مخصص:
__OC_I18N_900004__
إذا فعّلت `jq` صراحة ضمن `safeBins`، فإن OpenClaw لا يزال يرفض builtin المسمى `env` في وضع safe-bin
بحيث لا يستطيع `jq -n env` تفريغ بيئة عملية المستضيف من دون مسار allowlist صريح
إذا قمت صراحةً بإضافة `jq` إلى `safeBins`، فسيظل OpenClaw يرفض builtin المسمى `env` في وضع safe-bin
حتى لا يتمكن `jq -n env` من تفريغ بيئة عملية المضيف من دون مسار allowlist صريح
أو مطالبة موافقة.
## التحرير عبر Control UI
## التحرير في Control UI
استخدم بطاقة **Control UI → Nodes → Exec approvals** لتحرير الإعدادات الافتراضية،
والتجاوزات لكل وكيل، وقوائم السماح. اختر نطاقًا (Defaults أو وكيلًا)، وعدّل السياسة،
وأضف/أزل أنماط allowlist، ثم **احفظ**. تعرض واجهة المستخدم بيانات **آخر استخدام**
لكل نمط حتى تتمكن من الحفاظ على القائمة مرتبة.
استخدم بطاقة **Control UI → Nodes → Exec approvals** لتحرير الإعدادات الافتراضية، وتجاوزات
كل وكيل، وقوائم السماح. اختر نطاقًا (الإعدادات الافتراضية أو وكيلًا)، وعدّل السياسة،
وأضف/أزل أنماط allowlist، ثم انقر **حفظ**. تعرض الواجهة بيانات **آخر استخدام**
لكل نمط حتى تتمكن من إبقاء القائمة مرتبة.
يختار محدد الهدف **Gateway** (الموافقات المحلية) أو **Node**.
ويجب أن تعلن العقد عن `system.execApprovals.get/set` (تطبيق macOS أو مستضيف عقدة بدون واجهة).
إذا كانت العقدة لا تعلن عن موافقات exec بعد، فحرّر ملفها المحلي
`~/.openclaw/exec-approvals.json` مباشرة.
يختار محدد الهدف **Gateway** (الموافقات المحلية) أو **Node**. يجب على العقد
الإعلان عن `system.execApprovals.get/set` (تطبيق macOS أو مضيف عقدة بدون واجهة).
إذا لم تعلن العقدة عن موافقات exec بعد، فحرر ملفها المحلي
`~/.openclaw/exec-approvals.json` مباشرةً.
CLI: يدعم `openclaw approvals` التحرير للبوابة أو للعقدة (راجع [CLI الخاص بالموافقات](/cli/approvals)).
CLI: يدعم `openclaw approvals` التحرير على gateway أو node (راجع [CLI للموافقات](/cli/approvals)).
## تدفق الموافقة
عندما تكون المطالبة مطلوبة، تبث البوابة `exec.approval.requested` إلى عملاء المشغل.
وتقوم Control UI وتطبيق macOS بحسمها عبر `exec.approval.resolve`، ثم تمرر البوابة
الطلب الموافق عليه إلى مستضيف العقدة.
عندما تكون المطالبة مطلوبة، يبث gateway الحدث `exec.approval.requested` إلى عملاء المشغّلين.
يقوم Control UI وتطبيق macOS بحلها عبر `exec.approval.resolve`، ثم يمرر gateway
الطلب المعتمد إلى مضيف node.
بالنسبة إلى `host=node`، تتضمن طلبات الموافقة حمولة `systemRunPlan` قياسية. وتستخدم البوابة
هذه الخطة باعتبارها سياق الأمر/‏cwd/الجلسة الموثوق عند تمرير طلبات `system.run`
الموافق عليها.
بالنسبة إلى `host=node`، تتضمن طلبات الموافقة حمولة `systemRunPlan` أساسية. يستخدم gateway
هذه الخطة كسياق موثوق للأمر/cwd/الجلسة عند تمرير طلبات `system.run`
المعتمدة.
وهذا مهم لتأخر الموافقة غير المتزامنة:
وهذا مهم بالنسبة إلى زمن انتظار الموافقة غير المتزامنة:
- يقوم مسار exec الخاص بالعقدة بإعداد خطة قياسية واحدة مسبقًا
- ويخزن سجل الموافقة تلك الخطة وبيانات الربط الخاصة بها
- وبعد الموافقة، يعيد الاستدعاء النهائي الممرر لـ `system.run` استخدام الخطة المخزنة
بدلًا من الوثوق بتعديلات لاحقة من المستدعي
- وإذا غيّر المستدعي `command` أو `rawCommand` أو `cwd` أو `agentId` أو
`sessionKey` بعد إنشاء طلب الموافقة، ترفض البوابة
التشغيل الممرر بسبب عدم تطابق الموافقة
- يقوم مسار exec الخاص بالعقدة بإعداد خطة أساسية واحدة مسبقًا
- يخزّن سجل الموافقة هذه الخطة وبيانات الربط الخاصة بها
- بمجرد الموافقة، تعيد مكالمة `system.run` النهائية الممرّرة استخدام الخطة المخزنة
بدلًا من الثقة في تعديلات المستدعي اللاحقة
- إذا غيّر المستدعي `command` أو `rawCommand` أو `cwd` أو `agentId` أو
`sessionKey` بعد إنشاء طلب الموافقة، يرفض gateway
التشغيل الممرّر باعتباره عدم تطابق في الموافقة
## أوامر المفسرات/أوقات التشغيل
## أوامر المفسر/بيئة التشغيل
تكون تشغيلات المفسرات/أوقات التشغيل المدعومة بالموافقة محافظة عمدًا:
تكون عمليات تشغيل المفسر/بيئة التشغيل المدعومة بالموافقة محافظة عمدًا:
- يتم دائمًا ربط سياق `argv/cwd/env` الدقيق.
- يتم ربط shell script المباشر وأشكال ملفات وقت التشغيل المباشرة بأفضل جهد ممكن إلى لقطة
ملف محلي ملموس واحد.
- يتم فك صيغ مغلفات مدير الحزم الشائعة التي ما زالت تُحل إلى ملف محلي مباشر واحد (مثل
- يُربط دائمًا سياق argv/cwd/env المطابق.
- تُربط صيغ نصوص shell البرمجية المباشرة وصيغ ملفات بيئة التشغيل المباشرة، بأفضل جهد، بلقطة ملف محلي ملموس واحد.
- تُفك صيغ أغلفة مديري الحزم الشائعة التي ما تزال تُحل إلى ملف محلي مباشر واحد (مثل
`pnpm exec` و`pnpm node` و`npm exec` و`npx`) قبل الربط.
- إذا تعذر على OpenClaw تحديد ملف محلي ملموس واحد بالضبط لأمر مفسر/وقت تشغيل
(مثل package scripts، أو صيغ eval، أو سلاسل التحميل الخاصة بوقت تشغيل معيّن، أو الصيغ
متعددة الملفات الغامضة)، فيُرفض التنفيذ المدعوم بالموافقة بدلًا من الادعاء بتغطية دلالية
لا يملكها.
- بالنسبة إلى مثل هذه التدفقات، ففضّل sandboxing، أو حدًا منفصلًا للمستضيف، أو سير عمل
موثوقًا وصريحًا باستخدام allowlist/full حيث يقبل المشغّل الدلالات الأوسع لوقت التشغيل.
- إذا تعذر على OpenClaw تحديد ملف محلي ملموس واحد بالضبط لأمر مفسر/بيئة تشغيل
(مثل نصوص الحزم البرمجية، وصيغ eval، وسلاسل التحميل الخاصة ببيئات التشغيل، أو الصيغ متعددة الملفات الملتبسة)،
فيُرفض التنفيذ المدعوم بالموافقة بدلًا من الادعاء بتغطية دلالية لا يمتلكها.
- بالنسبة إلى سير العمل هذا، ففضّل العزل، أو حدًا منفصلًا للمضيف، أو سير عمل صريحًا موثوقًا
يعتمد على allowlist/full حيث يقبل المشغّل الدلالات الأوسع لبيئة التشغيل.
عندما تكون الموافقات مطلوبة، تعيد أداة exec فورًا معرّف موافقة. استخدم هذا المعرّف
لربط أحداث النظام اللاحقة (`Exec finished` / `Exec denied`). وإذا لم يصل أي قرار قبل انتهاء المهلة،
يُعامل الطلب على أنه انتهاء مهلة للموافقة ويُعرض بوصفه سبب رفض.
عندما تكون الموافقات مطلوبة، تعيد أداة exec فورًا معرّف موافقة. استخدم هذا المعرف
لربط أحداث النظام اللاحقة (`Exec finished` / `Exec denied`). إذا لم يصل أي قرار قبل
انتهاء المهلة، يُعامل الطلب على أنه انتهاء مهلة الموافقة ويُعرض كسبب للرفض.
### سلوك تسليم المتابعة
بعد انتهاء exec غير متزامن تمت الموافقة عليه، يرسل OpenClaw دور `agent` متابعًا إلى الجلسة نفسها.
بعد انتهاء exec غير المتزامن المعتمد، يرسل OpenClaw متابعة من نوع `agent` إلى الجلسة نفسها.
- إذا كان هناك هدف تسليم خارجي صالح (قناة قابلة للتسليم بالإضافة إلى الهدف `to`)، فإن تسليم المتابعة يستخدم تلك القناة.
- في تدفقات webchat فقط أو تدفقات الجلسات الداخلية من دون هدف خارجي، يبقى تسليم المتابعة داخل الجلسة فقط (`deliver: false`).
- إذا طلب مستدعٍ صراحة تسليمًا خارجيًا صارمًا من دون قناة خارجية قابلة للحل، يفشل الطلب بالخطأ `INVALID_REQUEST`.
- إذا كانت `bestEffortDeliver` مفعلة ولم يمكن حل قناة خارجية، يُخفَّض التسليم إلى داخل الجلسة فقط بدلًا من الفشل.
- إذا كان هناك هدف تسليم خارجي صالح (قناة قابلة للتسليم مع الهدف `to`)، يستخدم تسليم المتابعة تلك القناة.
- في تدفقات webchat فقط أو الجلسات الداخلية التي لا تحتوي على هدف خارجي، يبقى تسليم المتابعة على مستوى الجلسة فقط (`deliver: false`).
- إذا طلب مستدعٍ صراحةً تسليمًا خارجيًا صارمًا من دون قناة خارجية قابلة للحل، يفشل الطلب بالرمز `INVALID_REQUEST`.
- إذا كان `bestEffortDeliver` مفعّلًا ولم يمكن حل أي قناة خارجية، فيُخفض التسليم إلى مستوى الجلسة فقط بدلًا من الفشل.
يتضمن مربع حوار التأكيد:
يتضمن مربع حوار التأكيد ما يلي:
- الأمر + الوسائط
- `cwd`
- cwd
- معرّف الوكيل
- مسار الملف التنفيذي المحلول
- بيانات المستضيف + السياسة
- مسار الملف التنفيذي الذي تم حله
- بيانات المضيف + السياسة
الإجراءات:
- **Allow once** → التشغيل الآن
- **Always allow** → الإضافة إلى allowlist + التشغيل
- **Deny** → الحظر
- **السماح مرة واحدة** ← تشغيل الآن
- **السماح دائمًا** ← الإضافة إلى allowlist + التشغيل
- **رفض** ← حظر
## تمرير الموافقة إلى قنوات الدردشة
يمكنك تمرير مطالبات موافقة exec إلى أي قناة دردشة (بما في ذلك قنوات الإضافات) والموافقة
عليها باستخدام `/approve`. ويستخدم ذلك مسار التسليم الصادر العادي.
يمكنك تمرير مطالبات موافقة exec إلى أي قناة دردشة (بما في ذلك قنوات plugin) واعتمادها
باستخدام `/approve`. يستخدم هذا مسار التسليم الصادر المعتاد.
الإعدادات:
التكوين:
__OC_I18N_900005__
الرد في الدردشة:
__OC_I18N_900006__
يتعامل الأمر `/approve` مع كل من موافقات exec وموافقات الإضافات. وإذا لم يطابق المعرّف أي موافقة exec معلقة، فإنه يتحقق تلقائيًا من موافقات الإضافات بدلًا من ذلك.
يتعامل الأمر `/approve` مع كلٍّ من موافقات exec وموافقات plugin. إذا لم يطابق المعرّف أي موافقة exec معلّقة، فإنه يتحقق تلقائيًا من موافقات plugin بدلًا من ذلك.
### تمرير موافقات الإضافات
### تمرير موافقة plugin
يستخدم تمرير موافقات الإضافات مسار التسليم نفسه الذي تستخدمه موافقات exec لكنه يملك
إعداداته المستقلة الخاصة تحت `approvals.plugin`. ولا يؤثر تفعيل أحدهما أو تعطيله في الآخر.
يستخدم تمرير موافقة plugin مسار التسليم نفسه الذي تستخدمه موافقات exec، لكن لديه
تكوين مستقل خاص به تحت `approvals.plugin`. لا يؤثر تمكين أحدهما أو تعطيله في الآخر.
__OC_I18N_900007__
يكون شكل الإعداد مطابقًا لـ `approvals.exec`: تعمل `enabled` و`mode` و`agentFilter`,
و`sessionFilter`، و`targets` بالطريقة نفسها.
شكل التكوين مطابق لـ `approvals.exec`: تعمل `enabled` و`mode` و`agentFilter`،
و`sessionFilter` و`targets` بالطريقة نفسها.
تعرض القنوات التي تدعم الردود التفاعلية المشتركة أزرار الموافقة نفسها لكل من exec
وموافقات الإضافات. أما القنوات التي لا تملك واجهة تفاعلية مشتركة فتعود إلى النص العادي مع
تعليمات `/approve`.
تعرض القنوات التي تدعم الردود التفاعلية المشتركة أزرار الموافقة نفسها لكل من موافقات exec و
plugin. أما القنوات التي لا تدعم واجهة تفاعلية مشتركة فترجع إلى النص العادي مع
إرشادات `/approve`.
### الموافقات داخل الدردشة نفسها على أي قناة
### الموافقات من الدردشة نفسها على أي قناة
عندما ينشأ طلب موافقة exec أو موافقة إضافة من سطح دردشة قابل للتسليم، يمكن الآن للدردشة نفسها
الموافقة عليه باستخدام `/approve` افتراضيًا. وينطبق هذا على قنوات مثل Slack وMatrix و
Microsoft Teams بالإضافة إلى تدفقات Web UI وواجهة الطرفية الموجودة مسبقًا.
عندما ينشأ طلب موافقة exec أو plugin من سطح دردشة قابل للتسليم، يمكن للدردشة نفسها
الآن اعتماده باستخدام `/approve` افتراضيًا. ينطبق هذا على قنوات مثل Slack وMatrix و
Microsoft Teams بالإضافة إلى تدفقات Web UI وواجهة الطرفية الحالية.
يستخدم مسار الأوامر النصية المشتركة هذا نموذج مصادقة القناة العادي لتلك المحادثة. فإذا كانت
الدردشة الأصلية تستطيع بالفعل إرسال الأوامر واستقبال الردود، فلن تعود طلبات الموافقة بحاجة إلى
محوّل تسليم أصلي منفصل لكي تظل معلقة.
يستخدم مسار الأوامر النصية المشتركة هذا نموذج المصادقة المعتاد للقناة ضمن تلك المحادثة. إذا كان
بإمكان الدردشة الأصلية إرسال الأوامر واستقبال الردود بالفعل، فلن تعود طلبات الموافقة بحاجة إلى
مهايئ تسليم أصلي منفصل لمجرد البقاء معلقة.
يدعم Discord وTelegram أيضًا `/approve` داخل الدردشة نفسها، لكن هاتين القناتين لا تزالان
تستخدمان قائمة الموافقين المحلولة الخاصة بهما من أجل التفويض حتى عندما يكون تسليم الموافقة الأصلي معطلًا.
يدعم Discord وTelegram أيضًا `/approve` داخل الدردشة نفسها، لكن هاتين القناتين تواصلان استخدام
قائمة الموافقين التي تم حلها للتخويل حتى عندما يكون تسليم الموافقات الأصلي معطلًا.
وبالنسبة إلى Telegram وعملاء الموافقة الأصليين الآخرين الذين يستدعون Gateway مباشرة،
فإن هذا البديل مقيد عمدًا بإخفاقات "لم يتم العثور على الموافقة". ولا تؤدي
حالة رفض/خطأ حقيقية في موافقة exec إلى إعادة المحاولة بصمت بوصفها موافقة إضافة.
بالنسبة إلى Telegram وغيره من عملاء الموافقة الأصليين الذين يستدعون Gateway مباشرةً،
فإن هذا الرجوع الاحتياطي يظل مقيدًا عمدًا بحالات فشل "الموافقة غير موجودة". أما
أي رفض/خطأ حقيقي لموافقة exec فلا يُعاد توجيهه بصمت كموافقة plugin.
### تسليم الموافقة الأصلي
### التسليم الأصلي للموافقات
يمكن لبعض القنوات أيضًا أن تعمل كعملاء موافقة أصليين. ويضيف العملاء الأصليون رسائل خاصة للموافقين، وتوزيعًا إلى الدردشة الأصلية،
وتجربة مستخدم تفاعلية خاصة بالقناة للموافقة فوق مسار `/approve` المشترك داخل الدردشة نفسها.
يمكن لبعض القنوات أيضًا أن تعمل كعملاء موافقة أصليين. يضيف العملاء الأصليون رسائل الموافقين الخاصة،
والتوزيع على الدردشة الأصلية، وواجهة مستخدم تفاعلية خاصة بالقناة للموافقة فوق
تدفق `/approve` المشترك داخل الدردشة نفسها.
عندما تكون بطاقات/أزرار الموافقة الأصلية متاحة، تكون هذه الواجهة الأصلية هي
المسار الأساسي الموجّه إلى الوكيل. ويجب ألا يعرض الوكيل أيضًا أمر
`/approve` عاديًا مكررًا في الدردشة إلا إذا كانت نتيجة الأداة تشير إلى أن
الموافقات عبر الدردشة غير متاحة أو أن الموافقة اليدوية هي المسار المتبقي الوحيد.
عندما تكون بطاقات/أزرار الموافقة الأصلية متاحة، تكون واجهة المستخدم الأصلية تلك هي المسار الأساسي
المواجه للوكيل. لا ينبغي للوكيل أيضًا أن يكرر أمر دردشة
عاديًا من نوع `/approve` إلا إذا كانت نتيجة الأداة تشير إلى أن موافقات الدردشة غير متاحة أو
أن الموافقة اليدوية هي المسار الوحيد المتبقي.
النموذج العام:
- لا تزال سياسة exec على المستضيف هي التي تقرر ما إذا كانت موافقة exec مطلوبة
- ما تزال سياسة exec على المضيف هي التي تقرر ما إذا كانت موافقة exec مطلوبة
- يتحكم `approvals.exec` في تمرير مطالبات الموافقة إلى وجهات دردشة أخرى
- يتحكم `channels.<channel>.execApprovals` في ما إذا كانت تلك القناة تعمل كعميل موافقة أصلي
يقوم عملاء الموافقة الأصليون تلقائيًا بتفعيل التسليم الخاص بالرسائل الخاصة أولًا عندما تكون جميع الشروط التالية صحيحة:
يقوم عملاء الموافقة الأصليون بتمكين التسليم أولًا إلى الرسائل الخاصة تلقائيًا عندما تكون كل الشروط التالية صحيحة:
- تدعم القناة تسليم الموافقة الأصلي
- يمكن حل الموافقين من `execApprovals.approvers` الصريح أو من مصادر الاحتياط الموثقة
- تدعم القناة تسليم الموافقات الأصلي
- يمكن حل الموافقين من `execApprovals.approvers` الصريح أو من مصادر الرجوع الاحتياطي الموثقة
لتلك القناة
- تكون `channels.<channel>.execApprovals.enabled` غير مضبوطة أو `"auto"`
- تكون قيمة `channels.<channel>.execApprovals.enabled` غير معيّنة أو `"auto"`
اضبط `enabled: false` لتعطيل عميل موافقة أصلي صراحة. واضبط `enabled: true` لفرض
تفعيله عندما يتم حل الموافقين. ويظل التسليم العام إلى الدردشة الأصلية صريحًا عبر
اضبط `enabled: false` لتعطيل عميل موافقة أصلي صراحةً. واضبط `enabled: true` لفرض
تمكينه عندما يمكن حل الموافقين. يظل التسليم العام إلى الدردشة الأصلية صريحًا عبر
`channels.<channel>.execApprovals.target`.
الأسئلة الشائعة: [لماذا توجد إعداداتان لموافقة exec فيما يتعلق بموافقات الدردشة؟](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
الأسئلة الشائعة: [لماذا توجد إعداداتان لموافقة exec لموافقات الدردشة؟](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
- Discord: ‏`channels.discord.execApprovals.*`
- Slack: ‏`channels.slack.execApprovals.*`
- Telegram: ‏`channels.telegram.execApprovals.*`
- Discord: `channels.discord.execApprovals.*`
- Slack: `channels.slack.execApprovals.*`
- Telegram: `channels.telegram.execApprovals.*`
تضيف عملاء الموافقة الأصليون هؤلاء التوجيه إلى الرسائل الخاصة والخيار الاختياري لإرسال الرسائل إلى القناة فوق
مسار `/approve` المشترك داخل الدردشة نفسها وأزرار الموافقة المشتركة.
تضيف عملاء الموافقة الأصليون هؤلاء توجيه الرسائل الخاصة والتوزيع الاختياري على القنوات فوق
تدفق `/approve` المشترك داخل الدردشة نفسها وأزرار الموافقة المشتركة.
السلوك المشترك:
- تستخدم الدردشات القابلة للتسليم مثل Slack وMatrix وMicrosoft Teams نموذج مصادقة القناة العادي
بالنسبة إلى `/approve` داخل الدردشة نفسها
- عندما يتم التفعيل التلقائي لعميل موافقة أصلي، يكون هدف التسليم الأصلي الافتراضي هو الرسائل الخاصة للموافقين
- بالنسبة إلى Discord وTelegram، لا يمكن إلا للموافقين المحلولين الموافقة أو الرفض
- تستخدم Slack وMatrix وMicrosoft Teams وغيرها من الدردشات القابلة للتسليم نموذج مصادقة القناة المعتاد
من أجل `/approve` داخل الدردشة نفسها
- عندما يتم تمكين عميل موافقة أصلي تلقائيًا، يكون هدف التسليم الأصلي الافتراضي هو الرسائل الخاصة للموافقين
- بالنسبة إلى Discord وTelegram، لا يمكن الموافقة أو الرفض إلا من قبل الموافقين الذين تم حلهم
- يمكن أن يكون الموافقون في Discord صريحين (`execApprovals.approvers`) أو مستنتجين من `commands.ownerAllowFrom`
- يمكن أن يكون الموافقون في Telegram صريحين (`execApprovals.approvers`) أو مستنتجين من إعدادات المالك الموجودة (`allowFrom`، بالإضافة إلى `defaultTo` للرسائل المباشرة حيثما كان مدعومًا)
- يمكن أن يكون الموافقون في Telegram صريحين (`execApprovals.approvers`) أو مستنتجين من إعدادات المالك الحالية (`allowFrom`، بالإضافة إلى `defaultTo` للرسائل المباشرة حيثما كان ذلك مدعومًا)
- يمكن أن يكون الموافقون في Slack صريحين (`execApprovals.approvers`) أو مستنتجين من `commands.ownerAllowFrom`
- تحافظ أزرار Slack الأصلية على نوع معرّف الموافقة، بحيث يمكن لمعرّفات `plugin:` حل موافقات الإضافات
من دون طبقة بديلة ثانية محلية في Slack
- يكون التوجيه الأصلي للرسائل الخاصة/القنوات في Matrix خاصًا بـ exec فقط؛ وتبقى موافقات الإضافات في Matrix على
مسار `/approve` المشترك داخل الدردشة نفسها ومسارات التمرير الاختيارية `approvals.plugin`
- لا يحتاج الطالب إلى أن يكون موافقًا
- يمكن للدردشة الأصلية الموافقة مباشرة باستخدام `/approve` عندما كانت تلك الدردشة تدعم الأوامر والردود بالفعل
- تقوم أزرار الموافقة الأصلية في Discord بالتوجيه بحسب نوع معرّف الموافقة: تذهب معرّفات `plugin:` مباشرة
إلى موافقات الإضافات، ويذهب كل شيء آخر إلى موافقات exec
- تتبع أزرار الموافقة الأصلية في Telegram مسار الاحتياط المحدود نفسه من exec إلى plugin كما في `/approve`
- تحافظ الأزرار الأصلية في Slack على نوع معرّف الموافقة، بحيث يمكن لمعرّفات `plugin:` حل موافقات plugin
من دون طبقة رجوع احتياطي ثانية محلية خاصة بـ Slack
- يتعامل توجيه الرسائل الخاصة/القنوات الأصلي في Matrix واختصارات التفاعل مع كلٍّ من موافقات exec وplugin؛
بينما يظل تخويل plugin صادرًا من `channels.matrix.dm.allowFrom`
- لا يحتاج مقدّم الطلب إلى أن يكون من الموافقين
- يمكن للدردشة الأصلية الموافقة مباشرةً باستخدام `/approve` عندما تكون تلك الدردشة تدعم بالفعل الأوامر والردود
- تقوم أزرار الموافقة الأصلية في Discord بالتوجيه حسب نوع معرّف الموافقة: تنتقل معرّفات `plugin:` مباشرةً
إلى موافقات plugin، وكل ما عدا ذلك ينتقل إلى موافقات exec
- تتبع أزرار الموافقة الأصلية في Telegram نفس الرجوع الاحتياطي المحدود من exec إلى plugin كما في `/approve`
- عندما يفعّل `target` الأصلي التسليم إلى الدردشة الأصلية، تتضمن مطالبات الموافقة نص الأمر
- تنتهي صلاحية موافقات exec المعلقة بعد 30 دقيقة افتراضيًا
- إذا لم يتمكن أي مشغّل UI أو عميل موافقة مضبوط من قبول الطلب، تعود المطالبة إلى `askFallback`
- إذا لم تتمكن أي واجهة مستخدم للمشغّل أو عميل موافقة مكوّن من قبول الطلب، تعود المطالبة إلى `askFallback`
يستخدم Telegram افتراضيًا الرسائل الخاصة للموافقين (`target: "dm"`). ويمكنك التبديل إلى `channel` أو `both` عندما
تريد أن تظهر مطالبات الموافقة أيضًا في دردشة/موضوع Telegram الأصلية. وبالنسبة إلى موضوعات منتديات Telegram،
يحافظ OpenClaw على الموضوع من أجل مطالبة الموافقة والمتابعة التي تلي الموافقة.
يفترض Telegram استخدام الرسائل الخاصة للموافقين (`target: "dm"`). يمكنك التبديل إلى `channel` أو `both` عندما
تريد أن تظهر مطالبات الموافقة في دردشة/موضوع Telegram الأصلي أيضًا. بالنسبة إلى مواضيع منتديات Telegram،
يحافظ OpenClaw على الموضوع لمطالبة الموافقة ولمتابعة ما بعد الموافقة.
راجع:
@ -530,38 +529,38 @@ Microsoft Teams بالإضافة إلى تدفقات Web UI وواجهة الط
__OC_I18N_900008__
ملاحظات أمنية:
- وضع Unix socket هو `0600`، ويتم تخزين الرمز المميز في `exec-approvals.json`.
- فحص النظير بنفس UID.
- challenge/response ‏(nonce + HMAC token + request hash) + TTL قصير.
- وضع Unix socket هو `0600`، ويُخزّن الرمز المميز في `exec-approvals.json`.
- فحص النظير ذي المعرّف UID نفسه.
- تحدٍّ/استجابة (nonce + HMAC token + request hash) + TTL قصير.
## أحداث النظام
يتم عرض دورة حياة Exec على شكل رسائل نظام:
تظهر دورة حياة Exec كرسائل نظام:
- `Exec running` (فقط إذا تجاوز الأمر عتبة إشعار التشغيل)
- `Exec finished`
- `Exec denied`
تُنشر هذه الرسائل إلى جلسة الوكيل بعد أن تبلغ العقدة بالحدث.
وتصدر موافقات exec على مستضيف gateway أحداث دورة الحياة نفسها عندما ينتهي الأمر (واختياريًا عندما يستغرق مدة أطول من العتبة).
وتعيد عمليات exec المقيدة بالموافقة استخدام معرّف الموافقة باعتباره `runId` في هذه الرسائل لتسهيل الربط.
تُنشر هذه الرسائل إلى جلسة الوكيل بعد أن تُبلغ العقدة عن الحدث.
تصدر موافقات exec على gateway-host أحداث دورة الحياة نفسها عندما ينتهي الأمر (واختياريًا عندما يستمر التشغيل مدة أطول من العتبة).
تعيد عمليات exec المقيدة بالموافقة استخدام معرّف الموافقة باعتباره `runId` في هذه الرسائل لسهولة الربط.
## سلوك الموافقة المرفوضة
عند رفض موافقة exec غير متزامنة، يمنع OpenClaw الوكيل من إعادة استخدام
المخرجات الناتجة عن أي تشغيل سابق للأمر نفسه في الجلسة. ويتم تمرير سبب الرفض
مع إرشادات صريحة تفيد بعدم وجود مخرجات للأمر، مما يمنع
الوكيل من الادعاء بوجود مخرجات جديدة أو إعادة تكرار الأمر المرفوض مع
نتائج قديمة من تشغيل ناجح سابق.
المخرجات من أي تشغيل سابق للأمر نفسه في الجلسة. يُمرَّر سبب الرفض
مع إرشادات صريحة تفيد بعدم وجود أي مخرجات للأمر، مما يمنع
الوكيل من الادعاء بوجود مخرجات جديدة أو تكرار الأمر المرفوض مع
نتائج قديمة من تشغيل سابق ناجح.
## الآثار
## التبعات
- إن **full** قوي جدًا؛ ويفضل استخدام قوائم السماح عندما يكون ذلك ممكنًا.
- إن **full** قوي جدًا؛ ففضّل allowlists متى أمكن.
- يبقيك **ask** ضمن الحلقة مع السماح بموافقات سريعة.
- تمنع قوائم السماح لكل وكيل انتقال موافقات وكيل ما إلى الآخرين.
- لا تنطبق الموافقات إلا على طلبات exec على المستضيف من **مرسلين مخولين**. ولا يستطيع المرسلون غير المخولين إصدار `/exec`.
- يُعد `/exec security=full` وسيلة راحة على مستوى الجلسة للمشغلين المخولين، ويتجاوز الموافقات عمدًا.
ولحظر exec على المستضيف بشكل صارم، اضبط أمان الموافقات على `deny` أو امنع أداة `exec` عبر سياسة الأدوات.
- تمنع allowlists لكل وكيل تسرب موافقات وكيل إلى وكلاء آخرين.
- لا تنطبق الموافقات إلا على طلبات exec على المضيف من **مرسلين مخولين**. لا يمكن للمرسلين غير المخولين إصدار `/exec`.
- يعد `/exec security=full` وسيلة مريحة على مستوى الجلسة للمشغّلين المخولين ويتجاوز الموافقات بحكم التصميم.
ولحظر exec على المضيف حظرًا صارمًا، اضبط أمان الموافقات على `deny` أو ارفض أداة `exec` عبر سياسة الأدوات.
ذو صلة:
@ -572,6 +571,6 @@ __OC_I18N_900008__
## ذو صلة
- [Exec](/ar/tools/exec) — أداة تنفيذ أوامر shell
- [Sandboxing](/ar/gateway/sandboxing) — أوضاع sandbox والوصول إلى مساحة العمل
- [العزل](/ar/gateway/sandboxing) — أوضاع العزل والوصول إلى مساحة العمل
- [الأمان](/ar/gateway/security) — نموذج الأمان والتقوية
- [Sandbox مقابل Tool Policy مقابل Elevated](/ar/gateway/sandbox-vs-tool-policy-vs-elevated) — متى تستخدم كل واحد منها
- [العزل مقابل سياسة الأدوات مقابل Elevated](/ar/gateway/sandbox-vs-tool-policy-vs-elevated) — متى تستخدم كل واحد منها