​

الاختبار

• ما الذي تغطيه كل مجموعة (وما الذي لا تغطيه عمدًا)
• ما هو الأوامر لتشغيل سير العمل المشترك (محلي مسبق، تصحيح)
• كيف تكتشف اختبارات live بيانات الاعتماد وتختار النماذج/الموفّرين
• كيفية إضافة اختبارات انحدار لمشكلات حقيقية في النماذج/الموفّرين

​

البدء السريع

• البوابة الكاملة (متوقعة قبل الدفع): pnpm build && pnpm check && pnpm test

• بوابة التغطية: pnpm test:coverage
• مجموعة E2E: pnpm test:e2e

• مجموعة Live (النماذج + فحوص أدوات/صور Gateway): pnpm test:live

​

مجموعات الاختبار (ما الذي يعمل وأين)

​

Unit / integration (الافتراضي)

• الأمر: pnpm test
• الإعداد: scripts/test-parallel.mjs (يشغّل vitest.unit.config.ts، vitest.extensions.config.ts، vitest.gateway.config.ts)
• الملفات: src/**/*.test.ts
• النطاق:
  • اختبارات unit خالصة
  • اختبارات تكامل داخل العملية (مصادقة Gateway، التوجيه، الأدوات، التحليل، التهيئة)
  • الانحدارات الوزيرية للأخطاء المعروفة
• التوقعات:
  • تعمل في CI
  • لا تتطلب مفاتيح حقيقية
  • سريعة ومستقرة
• ملاحظة حول التجميع (Pool):
  • يستخدم OpenClaw ميزة Vitest vmForks على Node 22/23 للحصول على تقسيمات وحدات أسرع.
  • على Node 24+، يعود OpenClaw تلقائيًا إلى forks العادية لتجنب أخطاء ربط Node VM (ERR_VM_MODULE_LINK_FAILURE / module is already linked).
  • يمكنك التجاوز يدويًا باستخدام OPENCLAW_TEST_VM_FORKS=0 (لفرض forks) أو OPENCLAW_TEST_VM_FORKS=1 (لفرض vmForks).

​

E2E (فحص دخاني للـ gateway)

• الأمر: pnpm test:e2e
• التهيئة: vitest.e2e.config.ts
• الملفات: src/**/*.e2e.test.ts
• الإعدادات الافتراضية لوقت التشغيل:
  • يستخدم Vitest vmForks لتسريع بدء تشغيل الملفات.
  • يستخدم عمّالًا متكيّفين (CI: 2-4، محليًا: 4-8).
  • يعمل في الوضع الصامت افتراضيًا لتقليل حمل إدخال/إخراج وحدة التحكم.
• تجاوزات مفيدة:
  • OPENCLAW_E2E_WORKERS=<n> لفرض عدد العمّال (بحد أقصى 16).
  • OPENCLAW_E2E_VERBOSE=1 لإعادة تفعيل مخرجات وحدة التحكم التفصيلية.
• النطاق:
  • سلوك end-to-end لعدة مثيلات Gateway
  • واجهات WebSocket/HTTP، إقران العُقد، وشبكات أثقل
• التوقعات:
  • تعمل في CI (عند تمكينها في خط الأنابيب)
  • لا تتطلب مفاتيح حقيقية
  • أجزاء متحركة أكثر من اختبارات unit (قد تكون أبطأ)

​

Live (موفّرون حقيقيون + نماذج حقيقية)

• الأمر: pnpm test:live
• التهيئة: vitest.live.config.ts
• الملفات: src/**/*.live.test.ts
• الافتراضي: مُمكّن بواسطة pnpm test:live (يضبط OPENCLAW_LIVE_TEST=1)
• النطاق:
  • «هل يعمل هذا الموفّر/النموذج فعليًا اليوم مع بيانات اعتماد حقيقية؟»
  • التقاط تغييرات تنسيقات الموفّرين، غرائب استدعاء الأدوات، مشكلات المصادقة، وسلوك تحديد المعدّل
• التوقعات:
  • غير مستقر في CI بطبيعته (شبكات حقيقية، سياسات موفّرين حقيقية، حصص، انقطاعات)
  • يكلّف مالًا / يستهلك حدود المعدّل
  • يُفضّل تشغيل مجموعات مضيّقة بدل «كل شيء»
  • ستجلب تشغيلات live ~/.profile لالتقاط مفاتيح API المفقودة
  • تدوير مفاتيح Anthropic: اضبط OPENCLAW_LIVE_ANTHROPIC_KEYS="sk-...,sk-..." (أو OPENCLAW_LIVE_ANTHROPIC_KEY=sk-...) أو عدة متغيرات ANTHROPIC_API_KEY*؛ ستُعيد الاختبارات المحاولة عند حدود المعدّل

​

أي مجموعة يجب أن أركض ؟

• تعديل المنطق/الاختبارات: شغّل pnpm test (وpnpm test:coverage إذا غيّرت الكثير)
• لمس شبكات Gateway / بروتوكول WS / الإقران: أضف pnpm test:e2e
• تصحيح «البوت متوقف» / أعطال خاصة بموفّر / استدعاء الأدوات: شغّل pnpm test:live مضيّقًا

​

Live: فحص دخاني للنماذج (مفاتيح الملفات التعريفية)

• «النموذج المباشر» يخبرنا إن كان الموفّر/النموذج قادرًا على الإجابة أصلًا بالمفتاح المعطى.
• «فحص Gateway الدخاني» يخبرنا إن كان خط أنابيب Gateway+الوكيل كاملًا يعمل لهذا النموذج (الجلسات، السجل، الأدوات، سياسة sandbox، إلخ).

​

الطبقة 1: إكمال مباشر للنموذج (بدون Gateway)

• الاختبار: src/agents/models.profiles.live.test.ts
• الهدف:
  • تعداد النماذج المكتشفة
  • استخدام getApiKeyForModel لاختيار النماذج التي لديك لها بيانات اعتماد
  • تشغيل إكمال صغير لكل نموذج (واختبارات انحدار مستهدفة عند الحاجة)
• كيفية التمكين:
  • pnpm test:live (أو OPENCLAW_LIVE_TEST=1 عند استدعاء Vitest مباشرة)
• اضبط OPENCLAW_LIVE_MODELS=modern (أو all، اسم بديل حديث) لتشغيل هذه المجموعة فعليًا؛ وإلا فسيتم تخطيها للحفاظ على تركيز pnpm test:live على فحص Gateway الدخاني
• كيفية اختيار النماذج:
  • OPENCLAW_LIVE_MODELS=modern لتشغيل allowlist الحديثة (Opus/Sonnet/Haiku 4.5، GPT-5.x + Codex، Gemini 3، GLM 4.7، MiniMax M2.1، Grok 4)
  • OPENCLAW_LIVE_MODELS=all اسم بديل لـ allowlist الحديثة
  • أو OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,..." (allowlist مفصولة بفواصل)
• كيفية اختيار الموفّرين:
  • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (allowlist مفصولة بفواصل)
• من أين تأتي المفاتيح:
  • بشكل افتراضي: متجر الملفات الشخصية و ردود فعل env
  • اضبط OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 لفرض مخزن الملفات التعريفية فقط
• لماذا يوجد هذا:
  • يفصل «واجهة API الموفّر معطلة / المفتاح غير صالح» عن «خط أنابيب وكيل Gateway معطّل»
  • يحتوي اختبارات انحدار صغيرة ومعزولة (مثال: إعادة تشغيل الاستدلال في OpenAI Responses/Codex Responses + تدفقات استدعاء الأدوات)

​

الطبقة 2: Gateway + وكيل التطوير (ما الذي يفعله “@openclaw” فعليًا)

• الاختبار: src/gateway/gateway-models.profiles.live.test.ts
• الهدف:
  • تشغيل Gateway داخل العملية
  • إنشاء/تعديل جلسة agent:dev:* (تجاوز النموذج لكل تشغيل)
  • الدوران على النماذج ذات المفاتيح والتحقق من:
    • استجابة «ذات معنى» (بدون أدوات)
    • نجاح استدعاء أداة حقيقي (فحص القراءة)
    • فحوص أدوات إضافية اختيارية (تنفيذ+قراءة)
    • بقاء مسارات انحدار OpenAI (أداة فقط → متابعة) تعمل
• تفاصيل الفحوص (لتفسير الأعطال بسرعة):
  • فحص read: يكتب الاختبار ملف nonce في مساحة العمل ويطلب من الوكيل read قراءته وإرجاع nonce.
  • فحص exec+read: يطلب الاختبار من الوكيل exec-كتابة nonce في ملف مؤقت، ثم read قراءته.
  • فحص الصورة: يرفق الاختبار PNG مُولّدًا (قط + كود عشوائي) ويتوقع أن يُعيد النموذج cat <CODE>.
  • مرجع التنفيذ: src/gateway/gateway-models.profiles.live.test.ts وsrc/gateway/live-image-probe.ts.
• كيفية التمكين:
  • pnpm test:live (أو OPENCLAW_LIVE_TEST=1 عند استدعاء Vitest مباشرة)
• كيفية اختيار النماذج:
  • الافتراضي: allowlist الحديثة (Opus/Sonnet/Haiku 4.5، GPT-5.x + Codex، Gemini 3، GLM 4.7، MiniMax M2.1، Grok 4)
  • OPENCLAW_LIVE_GATEWAY_MODELS=all اسم بديل لـ allowlist الحديثة
  • أو اضبط OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (أو قائمة مفصولة بفواصل) للتضييق
• كيفية اختيار الموفّرين (تجنّب «OpenRouter كل شيء»):
  • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (allowlist مفصولة بفواصل)
• فحوص الأدوات + الصور مفعّلة دائمًا في هذا الاختبار الحي:
  • فحص read + فحص exec+read (إجهاد الأدوات)
  • فحص الصورة يعمل عندما يعلن النموذج دعم إدخال الصور
  • التدفق (عالي المستوى):
    • يولّد الاختبار PNG صغيرًا يحتوي «CAT» + كودًا عشوائيًا (src/gateway/live-image-probe.ts)
    • يرسله عبر agent attachments: [{ mimeType: "image/png", content: "<base64>" }]
    • يحلّل Gateway المرفقات إلى images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)
    • يمرّر الوكيل المضمّن رسالة مستخدم متعددة الوسائط إلى النموذج
    • التحقق: يحتوي الرد على cat + الكود (تحمّل OCR: أخطاء طفيفة مسموحة)

openclaw models list
openclaw models list --json

​

Live: فحص دخاني لرمز إعداد Anthropic

• الاختبار: src/agents/anthropic.setup-token.live.test.ts
• الهدف: التحقق من أن رمز إعداد Claude Code CLI (أو ملف تعريف رمز إعداد ملصق) يمكنه إكمال مطالبة Anthropic.
• التمكين:
  • pnpm test:live (أو OPENCLAW_LIVE_TEST=1 عند استدعاء Vitest مباشرة)
  • OPENCLAW_LIVE_SETUP_TOKEN=1
• مصادر الرمز (اختر واحدًا):
  • ملف تعريفي: OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test
  • رمز خام: OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...
• تجاوز النموذج (اختياري):
  • OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-6

openclaw models auth paste-token --provider anthropic --profile-id anthropic:setup-token-test
OPENCLAW_LIVE_SETUP_TOKEN=1 OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test pnpm test:live src/agents/anthropic.setup-token.live.test.ts

​

Live: فحص دخاني لواجهة CLI الخلفية (Claude Code CLI أو CLIs محلية أخرى)

• الاختبار: src/gateway/gateway-cli-backend.live.test.ts
• الهدف: التحقق من خط أنابيب Gateway + الوكيل باستخدام واجهة CLI محلية، دون لمس التهيئة الافتراضية.
• التمكين:
  • pnpm test:live (أو OPENCLAW_LIVE_TEST=1 عند استدعاء Vitest مباشرة)
  • OPENCLAW_LIVE_CLI_BACKEND=1
• الافتراضيات:
  • النموذج: claude-cli/claude-sonnet-4-5
  • الأمر: claude
  • الوسائط: ["-p","--output-format","json","--dangerously-skip-permissions"]
• التجاوزات (اختياري):
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-6"
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.3-codex"
  • OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"
  • OPENCLAW_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","json","--permission-mode","bypassPermissions"]'
  • OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1 لإرسال مرفق صورة حقيقي (تُحقن المسارات في المطالبة).
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" لتمرير مسارات ملفات الصور كوسائط CLI بدل حقن المطالبة.
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (أو "list") للتحكم في كيفية تمرير وسائط الصور عند ضبط IMAGE_ARG.
  • OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1 لإرسال دور ثانٍ والتحقق من تدفق الاستئناف.
• OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0 للإبقاء على تهيئة MCP لـ Claude Code CLI مفعّلة (الافتراضي يعطّل تهيئة MCP بملف فارغ مؤقت).

OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-sonnet-4-5" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

​

وصفات live الموصى بها

• نموذج واحد، مباشر (بدون Gateway):
  • OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts
• نموذج واحد، فحص Gateway دخاني:
  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
• استدعاء الأدوات عبر عدة موفّرين:
  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
• تركيز Google (مفتاح Gemini API + Antigravity):
  • Gemini (مفتاح API): OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
  • Antigravity (OAuth): OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

• google/... يستخدم Gemini API (مفتاح API).
• google-antigravity/... يستخدم جسر OAuth لـ Antigravity (نقطة نهاية وكيل بأسلوب Cloud Code Assist).
• google-gemini-cli/... يستخدم Gemini CLI المحلي على جهازك (مصادقة وأدوات منفصلة).
• Gemini API مقابل Gemini CLI:
  • API: يستدعي OpenClaw واجهة Gemini المستضافة من Google عبر HTTP (مفتاح API / مصادقة ملف تعريفي)؛ وهذا ما يقصده معظم المستخدمين بـ «Gemini».
  • CLI: يستدعي OpenClaw ثنائي gemini محليًا؛ له مصادقته الخاصة وقد يتصرف بشكل مختلف (بثّ/دعم أدوات/اختلافات إصدار).

​

Live: مصفوفة النماذج (ما الذي نغطيه)

​

مجموعة الفحص الحديثة (استدعاء الأدوات + الصور)

• OpenAI (غير Codex): openai/gpt-5.2 (اختياري: openai/gpt-5.1)
• OpenAI Codex: openai-codex/gpt-5.3-codex (اختياري: openai-codex/gpt-5.3-codex-codex)
• Anthropic: anthropic/claude-opus-4-6 (أو anthropic/claude-sonnet-4-5)
• Google (Gemini API): google/gemini-3-pro-preview وgoogle/gemini-3-flash-preview (تجنّب نماذج Gemini 2.x الأقدم)
• Google (Antigravity): google-antigravity/claude-opus-4-6-thinking وgoogle-antigravity/gemini-3-flash
• Z.AI (GLM): zai/glm-4.7
• MiniMax: minimax/minimax-m2.1

​

الأساس: استدعاء الأدوات (قراءة + تنفيذ اختياري)

• OpenAI: openai/gpt-5.2 (أو openai/gpt-5-mini)
• Anthropic: anthropic/claude-opus-4-6 (أو anthropic/claude-sonnet-4-5)
• Google: google/gemini-3-flash-preview (أو google/gemini-3-pro-preview)
• Z.AI (GLM): zai/glm-4.7
• MiniMax: minimax/minimax-m2.1

• xAI: xai/grok-4 (أو الأحدث المتاح)
• Mistral: mistral/… (اختر نموذجًا واحدًا يدعم «tools» ومُفعّلًا لديك)
• Cerebras: cerebras/… (إن كان لديك وصول)
• LM Studio: lmstudio/… (محلي؛ يعتمد استدعاء الأدوات على وضع API)

​

الرؤية: إرسال صورة (مرفق → رسالة متعددة الوسائط)

​

المجمّعات / البوابات البديلة

• OpenRouter: openrouter/... (مئات النماذج؛ استخدم openclaw models scan للعثور على مرشحين يدعمون الأدوات+الصور)
• OpenCode Zen: opencode/... (مصادقة عبر OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)

• مدمجة: openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, xai, groq, cerebras, mistral, github-copilot
• عبر models.providers (نقاط نهاية مخصّصة): minimax (سحابة/API)، إضافةً إلى أي وكيل متوافق مع OpenAI/Anthropic (LM Studio، vLLM، LiteLLM، إلخ)

​

بيانات الاعتماد (لا تلتزم بها أبدًا)

• إذا كان CLI يعمل، ينبغي أن تعثر اختبارات live على المفاتيح نفسها.
• إذا قال اختبار live «لا توجد بيانات اعتماد»، فصَحّح بالطريقة نفسها التي تُصحّح بها openclaw models list / اختيار النموذج.
• مخزن الملفات التعريفية: ~/.openclaw/credentials/ (مفضّل؛ وهو ما تعنيه «مفاتيح الملف التعريفي» في الاختبارات)
• التهيئة: ~/.openclaw/openclaw.json (أو OPENCLAW_CONFIG_PATH)

​

Deepgram live (نسخ الصوت)

• الاختبار: src/media-understanding/providers/deepgram/audio.live.test.ts
• التمكين: DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts

​

مشغّلات Docker (اختبارات «تعمل على Linux» اختيارية)

• النماذج المباشرة: pnpm test:docker:live-models (السكريبت: scripts/test-live-models-docker.sh)
• Gateway + وكيل التطوير: pnpm test:docker:live-gateway (السكريبت: scripts/test-live-gateway-models-docker.sh)
• معالج التهيئة الأولية (TTY، توليد كامل): pnpm test:docker:onboard (السكريبت: scripts/e2e/onboard-docker.sh)
• شبكات Gateway (حاويتان، مصادقة WS + الصحة): pnpm test:docker:gateway-network (السكريبت: scripts/e2e/gateway-network-docker.sh)
• الإضافات (تحميل امتداد مخصّص + فحص السجل): pnpm test:docker:plugins (السكريبت: scripts/e2e/plugins-docker.sh)

• OPENCLAW_CONFIG_DIR=... (الافتراضي: ~/.openclaw) مُحمّل إلى /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (الافتراضي: ~/.openclaw/workspace) مُحمّل إلى /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... (الافتراضي: ~/.profile) مُحمّل إلى /home/node/.profile ومستورَد قبل تشغيل الاختبارات
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... لتضييق التشغيل
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 لضمان أن تأتي بيانات الاعتماد من مخزن الملفات التعريفية (وليس من البيئة)

​

صحة المستندات

​

انحدارات دون اتصال (آمنة لـ CI)

• استدعاء أدوات Gateway (OpenAI مُحاكَى، حلقة Gateway + وكيل حقيقية): src/gateway/gateway.tool-calling.mock-openai.test.ts
• معالج Gateway (WS wizard.start/wizard.next، يكتب التهيئة ويفرض المصادقة): src/gateway/gateway.wizard.e2e.test.ts

​

تقييمات موثوقية الوكيل (skills)

• استدعاء أدوات مُحاكَى عبر حلقة Gateway + وكيل حقيقية (src/gateway/gateway.tool-calling.mock-openai.test.ts).
• تدفقات معالج end-to-end تتحقق من توصيل الجلسة وتأثيرات التهيئة (src/gateway/gateway.wizard.e2e.test.ts).

• اتخاذ القرار: عند سرد skills في المطالبة، هل يختار الوكيل skill الصحيحة (أو يتجنب غير ذات الصلة)؟
• الامتثال: هل يقرأ الوكيل SKILL.md قبل الاستخدام ويتبع الخطوات/الوسائط المطلوبة؟
• عقود سير العمل: سيناريوهات متعددة الأدوار تتحقق من ترتيب الأدوات، وترحيل سجل الجلسة، وحدود sandbox.

• مشغّل سيناريوهات يستخدم موفّرين مُحاكَين للتحقق من استدعاءات الأدوات + ترتيبها، وقراءات ملفات skill، وتوصيل الجلسة.
• مجموعة صغيرة من السيناريوهات المركّزة على skills (استخدم مقابل تجنّب، البوابات، حقن المطالبات).
• تقييمات live اختيارية (مفعّلة بالبيئة) فقط بعد توفر المجموعة الآمنة لـ CI.

​

إضافة اختبارات انحدار (إرشادات)

• أضف اختبار انحدار آمنًا لـ CI إن أمكن (محاكاة/تجريد الموفّر، أو التقاط تحويل شكل الطلب بدقة)
• إذا كانت بطبيعتها live فقط (حدود المعدّل، سياسات المصادقة)، فأبقِ اختبار live ضيقًا ومفعّلًا اختياريًا عبر متغيرات البيئة
• فضّل استهداف أصغر طبقة تلتقط الخطأ:
  • خطأ تحويل/إعادة تشغيل طلب الموفّر → اختبار النماذج المباشرة
  • خطأ خط أنابيب جلسة/سجل/أدوات Gateway → فحص Gateway الحي أو اختبار Gateway مُحاكَى وآمن لـ CI