---
read_when:
    - تشغيل pnpm openclaw qa matrix محليًا
    - إضافة سيناريوهات ضمان الجودة في Matrix أو اختيارها
    - فرز حالات فشل ضمان الجودة في Matrix أو انتهاء المهلات أو تعثر التنظيف
summary: 'مرجع المشرفين لمسار ضمان الجودة المباشر لـ Matrix المدعوم بـ Docker: CLI والملفات التعريفية ومتغيرات البيئة والسيناريوهات ومخرجات التشغيل.'
title: ضمان جودة Matrix
x-i18n:
    generated_at: "2026-04-30T07:54:50Z"
    model: gpt-5.5
    provider: openai
    source_hash: 6ab862474e2abe45a1dcd66f025e3a3dd52a3417b0c1f42a26cd7944dd4053f5
    source_path: concepts/qa-matrix.md
    workflow: 16
---

يشغّل مسار ضمان الجودة Matrix Plugin المضمّن `@openclaw/matrix` مقابل خادم منازل Tuwunel مؤقت في Docker، مع حسابات مؤقتة للسائق، والنظام قيد الاختبار، والمراقب، إضافة إلى غرف مزروعة مسبقًا. وهذا هو الغطاء الحي الواقعي للنقل في Matrix.

هذه أدوات مخصّصة للمشرفين فقط. إصدارات OpenClaw المعبأة تحذف `qa-lab` عمدًا، لذلك لا يتوفر `openclaw qa` إلا من نسخة مصدرية. تحمّل النسخ المصدرية المشغّل المضمّن مباشرة — ولا حاجة إلى خطوة تثبيت Plugin.

للحصول على سياق أوسع حول إطار ضمان الجودة، راجع [نظرة عامة على ضمان الجودة](/ar/concepts/qa-e2e-automation).

## البدء السريع

```bash
pnpm openclaw qa matrix --profile fast --fail-fast
```

يشغّل `pnpm openclaw qa matrix` العادي `--profile all` ولا يتوقف عند أول فشل. استخدم `--profile fast --fail-fast` كبوابة إصدار؛ وقسّم الفهرس باستخدام `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli` عند تشغيل المخزون الكامل بالتوازي.

## ما يفعله المسار

1. يجهّز خادم منازل Tuwunel مؤقتًا في Docker (الصورة الافتراضية `ghcr.io/matrix-construct/tuwunel:v1.5.1`، واسم الخادم `matrix-qa.test`، والمنفذ `28008`).
2. يسجّل ثلاثة مستخدمين مؤقتين — `driver` (يرسل حركة المرور الواردة)، و`sut` (حساب OpenClaw Matrix قيد الاختبار)، و`observer` (التقاط حركة مرور طرف ثالث).
3. يزرع الغرف المطلوبة للسيناريوهات المحددة (الرئيسية، والترابط، والوسائط، وإعادة التشغيل، والثانوية، وقائمة السماح، وE2EE، ورسائل التحقق المباشرة، وما إلى ذلك).
4. يبدأ Gateway فرعيًا من OpenClaw باستخدام Plugin الحقيقي لـ Matrix والمقصور على حساب النظام قيد الاختبار؛ ولا يتم تحميل `qa-channel` في الفرع.
5. يشغّل السيناريوهات بالتسلسل، مع مراقبة الأحداث عبر عملاء Matrix للسائق/المراقب.
6. يهدم خادم المنازل، ويكتب عناصر التقرير والملخص، ثم يخرج.

## CLI

```text
pnpm openclaw qa matrix [options]
```

### الخيارات الشائعة

| الخيار                | الافتراضي                                    | الوصف                                                                                                                   |
| --------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--profile <profile>` | `all`                                         | ملف السيناريو. راجع [الملفات](#profiles).                                                                              |
| `--fail-fast`         | متوقف                                        | التوقف بعد أول فحص أو سيناريو فاشل.                                                                                    |
| `--scenario <id>`     | —                                             | تشغيل هذا السيناريو فقط. قابل للتكرار. راجع [السيناريوهات](#scenarios).                                                |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | مكان كتابة التقارير والملخص والأحداث المرصودة وسجل الإخراج. تُحل المسارات النسبية مقابل `--repo-root`.                 |
| `--repo-root <path>`  | `process.cwd()`                               | جذر المستودع عند الاستدعاء من دليل عمل محايد.                                                                          |
| `--sut-account <id>`  | `sut`                                         | معرّف حساب Matrix داخل إعدادات Gateway الخاصة بضمان الجودة.                                                            |

### خيارات المزوّد

يستخدم المسار نقل Matrix حقيقيًا، لكن مزوّد النموذج قابل للتهيئة:

| الخيار                   | الافتراضي       | الوصف                                                                                                                             |
| ------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--provider-mode <mode>` | `live-frontier`  | `mock-openai` للإرسال الوهمي الحتمي أو `live-frontier` لمزوّدي frontier الحيين. لا يزال الاسم البديل القديم `live-openai` يعمل. |
| `--model <ref>`          | افتراضي المزوّد | مرجع `provider/model` الأساسي.                                                                                                    |
| `--alt-model <ref>`      | افتراضي المزوّد | مرجع `provider/model` البديل عندما تبدّل السيناريوهات أثناء التشغيل.                                                              |
| `--fast`                 | متوقف           | تفعيل الوضع السريع للمزوّد حيثما يكون مدعومًا.                                                                                    |

لا يقبل ضمان جودة Matrix الخيارين `--credential-source` أو `--credential-role`. يجهّز المسار مستخدمين مؤقتين محليًا؛ ولا توجد مجموعة بيانات اعتماد مشتركة للاستئجار منها.

## الملفات

يحدد الملف المحدد السيناريوهات التي ستعمل.

| الملف           | استخدمه من أجل                                                                                                                                                                                                                                  |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `all` (افتراضي) | الفهرس الكامل. بطيء لكنه شامل.                                                                                                                                                                                                                  |
| `fast`          | مجموعة فرعية لبوابة الإصدار تختبر عقد النقل الحي: canary، وبوابة الإشارة، وحظر قائمة السماح، وشكل الرد، واستئناف إعادة التشغيل، ومتابعة الترابط، وعزل الترابط، ومراقبة التفاعلات، وتسليم بيانات موافقة التنفيذ الوصفية.                    |
| `transport`     | سيناريوهات الترابط على مستوى النقل، والرسائل المباشرة، والغرف، والانضمام التلقائي، والإشارة/قائمة السماح، والموافقة، والتفاعلات.                                                                                                               |
| `media`         | تغطية مرفقات الصور والصوت والفيديو وPDF وEPUB.                                                                                                                                                                                                 |
| `e2ee-smoke`    | الحد الأدنى لتغطية E2EE — رد مشفّر أساسي، ومتابعة ترابط، ونجاح التمهيد.                                                                                                                                                                        |
| `e2ee-deep`     | سيناريوهات شاملة لفقدان حالة E2EE والنسخ الاحتياطي والمفاتيح والاسترداد.                                                                                                                                                                      |
| `e2ee-cli`      | سيناريوهات CLI الخاصة بـ `openclaw matrix encryption setup` و`verify *` المدفوعة عبر حزمة ضمان الجودة.                                                                                                                                          |

يوجد التعيين الدقيق في `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts`.

## السيناريوهات

قائمة معرّفات السيناريوهات الكاملة هي اتحاد `MatrixQaScenarioId` في `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15`. تشمل الفئات:

- الترابط — `matrix-thread-*`، `matrix-subagent-thread-spawn`
- المستوى الأعلى / رسالة مباشرة / غرفة — `matrix-top-level-reply-shape`، `matrix-room-*`، `matrix-dm-*`
- البث وتقدم الأدوات — `matrix-room-partial-streaming-preview`، `matrix-room-quiet-streaming-preview`، `matrix-room-tool-progress-*`، `matrix-room-block-streaming`
- الوسائط — `matrix-media-type-coverage`، `matrix-room-image-understanding-attachment`، `matrix-attachment-only-ignored`، `matrix-unsupported-media-safe`
- التوجيه — `matrix-room-autojoin-invite`، `matrix-secondary-room-*`
- التفاعلات — `matrix-reaction-*`
- الموافقات — `matrix-approval-*` (بيانات exec/plugin الوصفية، والرجوع المجزأ، وتفاعلات الرفض، والترابطات، وتوجيه `target: "both"`)
- إعادة التشغيل وإعادة التشغيل المسجل — `matrix-restart-*`، `matrix-stale-sync-replay-dedupe`، `matrix-room-membership-loss`، `matrix-homeserver-restart-resume`، `matrix-initial-catchup-then-incremental`
- بوابة الإشارة، واتصال البوتات ببعضها، وقوائم السماح — `matrix-mention-*`، `matrix-allowbots-*`، `matrix-allowlist-*`، `matrix-multi-actor-ordering`، `matrix-inbound-edit-*`، `matrix-mxid-prefixed-command-block`، `matrix-observer-allowlist-override`
- E2EE — `matrix-e2ee-*` (رد أساسي، ومتابعة ترابط، وتمهيد، ودورة حياة مفتاح الاسترداد، ومتغيرات فقدان الحالة، وسلوك النسخ الاحتياطي للخادم، ونظافة الأجهزة، والتحقق عبر SAS / QR / الرسائل المباشرة، وإعادة التشغيل، وتنقيح العناصر)
- E2EE CLI — `matrix-e2ee-cli-*` (إعداد التشفير، والإعداد متكرر التشغيل بأمان، وفشل التمهيد، ودورة حياة مفتاح الاسترداد، وتعدد الحسابات، ورحلة ذهاب وإياب لرد Gateway، والتحقق الذاتي)

مرّر `--scenario <id>` (قابل للتكرار) لتشغيل مجموعة مختارة يدويًا؛ واجمعه مع `--profile all` لتجاهل بوابة الملف.

## متغيرات البيئة

| المتغير                                | الافتراضي                                   | التأثير                                                                                                                                                                                         |
| --------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_QA_MATRIX_TIMEOUT_MS`         | `1800000` (30 دقيقة)                        | حد أعلى صارم للتشغيل بأكمله.                                                                                                                                                            |
| `OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS`  | `45000`                                   | حد زمني للرد الأولي التجريبي. ترفع CI للإصدار هذه القيمة على المشغّلات المشتركة حتى لا يفشل أول دور بطيء من Gateway قبل بدء تغطية السيناريوهات.                                       |
| `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000`                                    | نافذة هادئة لتأكيدات عدم الرد السلبية. تُقيَّد بحيث تكون `≤` مهلة التشغيل.                                                                                                                 |
| `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000`                                   | حد زمني لتفكيك Docker. تتضمن أسطح الفشل أمر الاسترداد `docker compose ... down --remove-orphans`.                                                                           |
| `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`      | `ghcr.io/matrix-construct/tuwunel:v1.5.1` | تجاوز صورة خادم المنزل عند التحقق مقابل إصدار Tuwunel مختلف.                                                                                                             |
| `OPENCLAW_QA_MATRIX_PROGRESS`           | مفعّل                                        | تجعل `0` أسطر التقدم `[matrix-qa] ...` صامتة على stderr. وتفرض `1` إظهارها.                                                                                                                   |
| `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT`    | منقّح                                  | تحتفظ `1` بنص الرسالة و`formatted_body` في `matrix-qa-observed-events.json`. ينقّح الافتراضي ذلك للحفاظ على أمان عناصر CI الأثرية.                                                                    |
| `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT` | معطّل                                       | تتخطى `1` استدعاء `process.exit` الحتمي بعد كتابة العنصر الأثري. يفرض الافتراضي الخروج لأن مقابض التشفير الأصلية في matrix-js-sdk قد تُبقي حلقة الأحداث نشطة بعد اكتمال العنصر الأثري. |
| `OPENCLAW_RUN_NODE_OUTPUT_LOG`          | غير معيّن                                     | عند تعيينه بواسطة مشغّل خارجي (مثل `scripts/run-node.mjs`)، تعيد Matrix QA استخدام مسار السجل هذا بدلًا من بدء tee خاص بها.                                                                   |

## عناصر الإخراج الأثرية

تُكتب إلى `--output-dir`:

- `matrix-qa-report.md` — تقرير بروتوكول Markdown (ما نجح، وما فشل، وما تم تخطيه، ولماذا).
- `matrix-qa-summary.json` — ملخص منظم مناسب لتحليل CI ولوحات المعلومات.
- `matrix-qa-observed-events.json` — أحداث Matrix المرصودة من عملاء برنامج التشغيل والمراقب. تُنقّح النصوص ما لم تكن `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1`؛ وتُلخّص بيانات اعتماد الموافقة بميادين آمنة محددة ومعاينة أمر مقتطعة.
- `matrix-qa-output.log` — stdout/stderr المدمجان من التشغيل. إذا كان `OPENCLAW_RUN_NODE_OUTPUT_LOG` معيّنًا، يُعاد استخدام سجل المشغّل الخارجي بدلًا من ذلك.

دليل الإخراج الافتراضي هو `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` حتى لا تستبدل عمليات التشغيل المتعاقبة بعضها بعضًا.

## نصائح الفرز

- **يتعطل التشغيل قرب النهاية:** قد تعيش مقابض التشفير الأصلية في `matrix-js-sdk` بعد انتهاء الحزمة. يفرض الافتراضي استدعاء `process.exit` نظيفًا بعد كتابة العنصر الأثري؛ إذا ألغيت تعيين `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1`، فتوقع أن تبقى العملية عالقة.
- **خطأ التنظيف:** ابحث عن أمر الاسترداد المطبوع (استدعاء `docker compose ... down --remove-orphans`) وشغّله يدويًا لتحرير منفذ خادم المنزل.
- **نوافذ التأكيد السلبي المتقطعة في CI:** خفّض `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` (الافتراضي 8 ثوانٍ) عندما تكون CI سريعة؛ وارفعه على المشغّلات المشتركة البطيئة.
- **تحتاج إلى النصوص المنقّحة لتقرير خطأ:** أعد التشغيل باستخدام `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1` وأرفق `matrix-qa-observed-events.json`. تعامل مع العنصر الأثري الناتج باعتباره حساسًا.
- **إصدار Tuwunel مختلف:** وجّه `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` إلى الإصدار قيد الاختبار. يتحقق المسار من الصورة الافتراضية المثبتة فقط.

## عقد النقل الحي

Matrix هو أحد ثلاثة مسارات نقل حي (Matrix، Telegram، Discord) تشترك في قائمة تحقق واحدة للعقد محددة في [نظرة عامة على QA → تغطية النقل الحي](/ar/concepts/qa-e2e-automation#live-transport-coverage). يبقى `qa-channel` مجموعة اصطناعية واسعة وليس جزءًا من تلك المصفوفة عمدًا.

## ذو صلة

- [نظرة عامة على QA](/ar/concepts/qa-e2e-automation) — حزمة QA العامة وعقد النقل الحي
- [QA Channel](/ar/channels/qa-channel) — محوّل قناة اصطناعي للسيناريوهات المدعومة بالمستودع
- [الاختبار](/ar/help/testing) — تشغيل الاختبارات وإضافة تغطية QA
- [Matrix](/ar/channels/matrix) — Plugin القناة قيد الاختبار
