Skip to content

توصيل MCP: علبة أدوات إضافية لـ Claw ​

منح متصفح الدرس السابق Claw يدًا للتصفح؛ وفي هذا الدرس سنزوده بـعلبة أدوات إضافية. تشرح الوثائق الرسمية لـ MCP (Model Context Protocol، بروتوكول سياق النموذج) جوهره في جملة واحدة: «an agent borrows tools from another program»——الـ agent يستعير الأدوات من برنامج آخر. يكشف خادم MCP الأدوات والموارد والرسائل التوجيهية للخارج، وOpenClaw بمجرد الاتصال به تظهر هذه الأدوات في دليل أدوات الـ agent لديك، جاهزة للاستخدام متى شئت.

OpenClaw لتوصيل MCP ثلاثة أوجه: النقر في Control UI، و**openclaw mcp سطر الأوامر**، و**mcp.servers ملف التهيئة**——كلها تؤدي إلى النتيجة نفسها، فكلها تكتب التهيئة ذاتها. وهناك اتجاه معاكس أيضًا: openclaw mcp serve يكشف OpenClaw محادثات القنوات عكسيًا لعملاء MCP مثل Claude Code / Codex. جميع الأمثلة مبنية على OpenClaw v2026.10.9.

ماذا ستستطيع أن تفعل بعد إتمام الدرس ​

  • توصيل خوادم MCP إلى OpenClaw بثلاث طرق (Control UI / openclaw mcp CLI / mcp.servers ملف التهيئة)
  • التحقق باستخدام openclaw mcp doctor <name> --probe من أن الخادم متصل فعلًا وأنه يكشف عن أدوات فعلًا
  • استخدام --include / toolFilter / openclaw mcp tools للكشف فقط عن الأدوات اللازمة للـ agent
  • إتمام تسجيل الدخول لخوادم HTTP البعيدة التي تتطلب OAuth
  • استخدام openclaw mcp serve للكشف العكسي عن محادثات قنوات OpenClaw لصالح Claude Code / Codex

مأزقك الحالي ​

  • يستطيع Claw الدردشة وتشغيل الأوامر والتصفح، لكنه يعجز عند التعامل مع الأنظمة الداخلية أو مصادر بيانات محددة——ليست لديه الأدوات المقابلة
  • وجدت خادم MCP جاهزًا، لكنك لا تعرف كيف توصله بـ OpenClaw: أين تُكتب التهيئة، وكيف يبدو تنسيقها، وكيف تتحقق بعد التوصيل——كل شيء بالتخمين
  • تخشى أن تخرج الأدوات الإضافية عن السيطرة: بعد توصيل خادم طرف ثالث، هل ستتجاوز أدواته الأذونات التي وضعتها

متى تستخدم هذه الحيلة ​

عندما تحتاج إلى:

  • إضافة قدرات إلى Claw لا تملكها الأدوات المدمجة: قراءة وكتابة أدلة محددة، وقواعد ذاكرة خارجية، وواجهات API داخلية، والتحكم بسطح المكتب……
  • إعادة استخدام الخوادم الجاهزة في منظومة MCP——npx أمر واحد للتوصيل، دون الحاجة لكتابة إضافات بنفسك
  • مشاركة عدة agents / عدة بيئات تشغيل التعريف ذاته للأدوات——OpenClaw يخزنها مركزيًا في mcp.servers، فلا تحتاج كل بيئة تشغيل إلى صيانة نسختها الخاصة

ولا تريد:

  • تعديل جوهر OpenClaw أو كتابة إضافات من أجل كل قدرة جديدة
  • حشر طرق استخدام الأدوات قسرًا في الرسائل التوجيهية——أدوات MCP تحمل schema مدمجًا، والـ agent يكتشفها تلقائيًا

🎒 الاستعدادات قبل البدء ​

الفكرة الجوهرية ​

ابنِ أولًا إحساسًا بالاتجاه. لـ MCP اتجاهان، لا تخلط بينهما:

الاتجاهمن هو خادم MCPماذا يفعلنقطة الدخول
التوصيل (محور هذا الدرس)برنامج طرف ثالثOpenClaw يتصل به ويستعير أدواته لـ agent الخاص بهSettings → MCP / openclaw mcp add / mcp.servers
الكشف العكسي (متقدم)OpenClaw هو نفسهيأتي عملاء MCP آخرون لقراءة / إرسال محادثات قنوات OpenClawopenclaw mcp serve

ثلاثة خطوط حمراء ينص عليها المسؤول صراحةً:

  1. تُخزن تعريفات الخوادم موحدةً تحت mcp.servers في التهيئة، وأوجه التوصيل الثلاثة تكتب الشيء نفسه؛
  2. أدوات MCP** تخضع لنفس منظومة إدارة tool-profile / tool-policy** — «connecting a server does not bypass your policy»، أي أن الاتصال لا يعني السماح؛
  3. لا تكتب بيانات الاعتماد كقيم حرفية في الإعدادات — خزّن الترويسات الحساسة ومتغيرات البيئة عبر آلية الأسرار المدعومة.

ثلاثة أنواع من النقل، اختر حسب مكان الخادم:

النقلمناسب لـما يجب ملؤه
Stdioخوادم تُطلق بأمر محليcommand + args (اختياري cwd / env)
Streamable HTTPخوادم بعيدةhttp(s):// URL
SSEخوادم بعيدة قديمةhttp(s):// URL

القاعدة في سطر واحد: اختر بين command (stdio) و URL (عائلة HTTP)، وكتابة الاثنين معًا يرفضها التحقق من الإعدادات؛ enabled: false يبقي التعريف دون اتصال؛ واسم الخادم __proto__ كلمة محجوزة، فاختر اسمًا آخر.

ثلاث واجهات للاتصال، اختر حسب تفضيلك:

واجهة الاتصاللمن تناسبالخصائص
Control UI (Settings → MCP)لمن لا يريد لمس الطرفيةيمكن التعديل أثناء تشغيل Gateway، و OAuth بنقرة في المتصفح
CLI (openclaw mcp)لمن يريد النسخ واللصق والأتمتة بالسكربتاتأوامر الكتابة تتطلب حالة حصرية، أوقف Gateway أولًا (انظر المصيدة 1)
ملف الإعدادات (mcp.servers)لمن يريد إدارة الإصدارات والتهيئة الجماعيةالحقول الأكمل، تحرير مباشر

نفّذ معي ​

الخطوة 1: اعرف وضع OpenClaw MCP الحالي (openclaw mcp status --verbose) ​

لماذا: قبل العمل اطّلع على ما لديك. status يقرأ الإعدادات فقط، دون الاتصال بأي خادم، ويمكن تشغيله أثناء عمل Gateway.

bash
openclaw mcp status --verbose

ينبغي أن ترى: قائمة بتعريفات الخوادم المحفوظة — نوع النقل ومعاملات التشغيل والمهلة وحالة OAuth ومرشّحات الأدوات لكل خادم. في التثبيت الجديد تكون القائمة فارغة، وهو بداية مثالية من الصفر.

💡 إن لم تكن متأكدًا فشغّله أولًا

نصيحة الجهة الرسمية هي نفسها: إن لم تدرِ أي مسار تسلك، فشغّل openclaw mcp status --verbose أولًا — يخبرك بما هو محفوظ في OpenClaw دون تشغيل أي خادم MCP.

الخطوة 2: إضافة أول خادم MCP (اختر إحدى الطرق الثلاث) ​

لماذا: خذ خادم memory من الوصفات الرسمية كأول خادم — npx أمر واحد يشغّله دون أي إعداد. الطرق الثلاث تكتب في نفس mcp.servers، فاختر الأنسب لك.

الطريقة A (موصى بها): CLI في نافذة توقف واحدة ​

لماذا نلفها بـ stop / restart: أوامر الكتابة مثل add تتطلب حصرية دليل الحالة، وإذا كان Gateway يعمل ويحتفظ به فسيرفض الكتابة ويطلب الإيقاف أولًا — هذا تصميم لا عطل.

bash
openclaw gateway stop
openclaw mcp add memory \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-memory
openclaw gateway restart

ينبغي أن ترى: add يجري الفحص أولًا ثم يحفظ التعريف (الفحص مضمّن افتراضيًا إلا مع --no-probe أو إذا تطلب الأمر المرور بـ OAuth أولًا)، وبعد الحفظ restart يجعل Gateway يعمل بالتعريف الجديد.

  • تحقق سريع: openclaw mcp list يظهر memory

الطريقة B: الإضافة مباشرة عبر Control UI أثناء التشغيل ​

  1. افتح Control UI وادخل إلى Settings → MCP (أدخل /settings/mcp مباشرة في شريط عنوان المتصفح أو استخدم الاختصار /mcp).
  2. تحت Configured servers اختر Add server.
  3. اختر اسمًا فريدًا وحدد النقل: Streamable HTTP / SSE / Stdio.
  4. لنقل عائلة HTTP املأ http:// أو https:// URL الخاص بالخادم؛ ولـ stdio املأ أمر التشغيل ومعاملاته.
  5. اختر Add server — يُكتب التعريف عبر Gateway في mcp.servers.

ينبغي أن ترى: الخادم يظهر في القائمة، ويمكن تمكين كل صف أو تعطيله أو حذفه؛ أما العناصر المتقدمة مثل headers ومتغيرات البيئة و OAuth و TLS والمهلة فتوجد في محرر الإعدادات المُقسَّم أسفل الصفحة.

يمكن الإضافة من نافذة المحادثة أيضًا: + → Plugins → Add MCP server… (يتطلب صلاحيات مسؤول)، واختر النطاق This session (هذه الجلسة فقط) أو Everywhere (عام).

الطريقة C: كتابة ملف الإعدادات مباشرة ​

نفس خادم memory، عند كتابته في mcp.servers يبدو هكذا (JSON5):

json5
{
  mcp: {
    servers: {
      memory: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-memory"],
        enabled: true,
      },
    },
  },
}

ينبغي أن ترى: بعد الحفظ، في التثبيتات التي فعّلت إعادة التحميل الساخن لـ Gateway تسري التغييرات فورًا — الخوادم المعدّلة أو المحذوفة تُسحب من الخدمة مباشرة، ويستخدم اكتشاف الأدوات في الدور التالي التعريفات الجديدة؛ الخوادم التي لم تُمَسّ تحافظ على اتصالها وذاكرتها المؤقتة.

الخطوة 3: الفحص الطبي — doctor --probe لإثبات أن الخادم متصل فعلًا ​

لماذا: النص الرسمي يقول «Saving a definition proves nothing about reachability» — حفظ التعريف لا يثبت شيئًا، والاتصال الناجح هو ما يُحتسب. سلّم استكشاف الأخطاء من الأخف إلى الأثقل:

bash
openclaw mcp status --verbose      # 只读配置,随时能跑
openclaw mcp doctor memory         # 静态检查,随时能跑
openclaw mcp doctor memory --probe # 真实连接,要独占状态(Gateway 在跑会拒绝)
openclaw mcp probe memory          # 只做真实连接、列工具(同样要独占状态)

ينبغي أن ترى: doctor يفحص أولًا مشكلات الإعدادات المحلية — أمر stdio مفقود، cwd غير موجود، ملفات TLS مفقودة، خادم معطّل، قيم حساسة بنص صريح، تفويض OAuth غير مكتمل؛ --probe ثم يفتح اتصالًا حقيقيًا ويعرض الأدوات والقدرات الأخرى التي يوفرها الخادم.

إذا تعذّر الاتصال بالخادم مؤقتًا فلا تستعجل استكشاف الأخطاء: OpenClaw العميل المدمج يعيد الاتصال بـ تراجع أسّي — يبدأ من 30 ثانية ويتضاعف في كل مرة وبحد أقصى 10 دقائق؛ يجري الاسترداد في الخلفية وتصبح الأدوات متاحة عند حدّ الدور التالي دون حجب المحادثة الحالية.

  • تحقق سريع: قائمة الأدوات تظهر في مخرجات doctor --probe

الخطوة 4: ترشيح الأدوات وكشف ما يلزم فقط ​

لماذا: قد يجلب الخادم الواحد كومة من الأدوات، وكشفها جميعًا مزعج وغير آمن. خادم نظام الملفات هو المثال النموذجي الرسمي — أبقِ القراءة والبحث فقط، ولا تسمح بالكتابة:

bash
openclaw gateway stop
openclaw mcp add files \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-filesystem \
  --arg "$HOME/Documents" \
  --include 'read_file,list_directory,search_files'
openclaw mcp doctor files --probe
openclaw gateway restart

ينبغي أن ترى: doctor files --probe يتصل بالخادم ويبلّغ عن الأدوات؛ --include تتم التصفية قبل دخول الأدوات إلى دليل الوكيل****، فلا تظهر أدوات الكتابة. توصي الجهة الرسمية بحصر خادم نظام الملفات في أصغر شجرة أدلة يحتاجها الوكيل.

أما تعديل الخوادم المحفوظة لاحقًا فيتم عبر tools (مع ضرورة نافذة توقف أيضًا):

bash
openclaw mcp tools files --include 'read_file,list_directory,search_files'
openclaw mcp tools files --clear   # 清除过滤

في ملف التهيئة يقابل ذلك toolFilter.include / toolFilter.exclude، مع دعم * كمحرف بدل. ويمكن أيضًا الضبط الدقيق داخل الجلسة: نافذة الدردشة + ← Plugins ← Tool access، حيث يمكنك فحص أدوات تلك الجلسة أو تعطيلها واحدة واحدة.

الخطوة 5: ربط خادم بعيد يتطلب تسجيل دخول OAuth ​

لماذا: تستخدم خوادم HTTP البعيدة عادةً مصادقة OAuth. خذ وصفة خادم docs الرسمية كمثال، عند add نصرّح مباشرةً:

bash
openclaw gateway stop
openclaw mcp add docs \
  --url https://mcp.example.com/mcp \
  --transport streamable-http \
  --auth oauth \
  --oauth-scope docs.read \
  --timeout 20 \
  --connect-timeout 5 \
  --include 'search,read_*'
openclaw mcp login docs
openclaw gateway restart

لماذا يلزم التوقف: openclaw mcp login يعمل في وضع عدم الاتصال فقط (لأنه يحتاج إلى حصريّة دليل الحالة لإكمال استدعاء OAuth الرجعي).

يجب أن ترى: الطرفية تطبع رابط التفويض؛ بعد إكمال التفويض في المتصفح، عادةً ما يلتقط OpenClaw إعادة التوجيه الحلقية تلقائيًا ويحفظ بيانات الاعتماد. عندما لا يستطيع المتصفح الوصول إلى مستمع الاستدعاء (بيئة بعيدة أو بلا واجهة)، استخدم أمر --code المطبوع كحل احتياطي.

أسهل في واجهة التحكم: في Settings → MCP يمكن للمسؤول اختيار Sign in مباشرةً لخوادم OAuth المفعّلة، وبعد الموافقة على الوصول في المتصفح يكفي العودة إلى Settings.

نقطة تحقق ✅ ​

  • openclaw mcp status --verbose يستطيع سرد الخوادم المحفوظة لديك وأنواع النقل
  • openclaw mcp doctor <name> --probe يتصل بالخادم ويسرد أدواته
  • في محادثة، اطلب من Claw استخدام أداة جديدة مرة واحدة، فينجح في استدعائها
  • استخدمت openclaw mcp tools <name> --include … لتضييق نطاق الأدوات المكشوفة
  • تستطيع تفسير سبب وجوب إيقاف Gateway أولًا قبل أوامر CLI الكتابية (أو استخدام واجهة التحكم بدلًا منها)

تنبيهات للمزالق ​

❌ أثناء تشغيل Gateway، تُرفض أوامر الكتابة في CLI ​

add / set / configure / tools / unset / login / logout / probe / doctor --probe جميعها تتطلبحصريّة دليل الحالة. عندما يكون Gateway قيد التشغيل ويحتفظ به، ترفض الأوامر الكتابة وتعطي تلميحًا «أوقف أولًا ثم أعد المحاولة».

الطريقة الصحيحة: إما openclaw gateway stop ← العملية ← openclaw gateway restart، أو استخدام واجهة التحكم مباشرةً (Settings → MCP تدعم التعديل وتسجيل الدخول أثناء التشغيل). أما list / show / status / doctor (بدون --probe) فلا تتأثر، ويمكن تشغيلها في أي وقت أثناء عمل Gateway.

❌ الخادم موجود في القائمة لكن لا توجد أدوات في المحادثة ​

الحفظ ≠ قابلية الوصول. ترتيب استكشاف الخلل:

bash
openclaw mcp doctor <name> --probe
  • اتصل لكن الأدوات أقل من المتوقع ← تحقق مما إذا كانت toolFilter.include / toolFilter.exclude تصفّي بشدة
  • الخوادم ذات enabled: false تحتفظ بالتعريف لكنها لا تتصل، ولا تدخل اكتشاف الأدوات
  • إذا كان كل شيء سليمًا وما زال لا يعمل ← فقد لا تصل التغييرات إلى الوكيل قيد التشغيل: openclaw mcp reload يحدّث بيئة التشغيل لعملية CLI الحالية فقط، بينما يحتاج Gateway أو الوكلاء في أماكن أخرى إلى reload / نشر تهيئة / إعادة تشغيل خاصة بكل منهم

❌ خادم stdio لا يعمل ​

هناك ثلاثة أسباب شائعة، وdoctor يكشفها جميعًا:

  • command لا يمكن تحليله في بيئة عملية Gateway—كونك تستطيع تشغيله في الصدفة الخاصة بك لا يعني أنه يعمل في بيئة Gateway
  • دليل cwd غير موجود
  • المعاملات في المكان الخطأ: المعاملات تتبع args، فلا تدمجها في command؛ وtransport: "stdio" الصريح يتطلب command غير فارغ

❌ خادم HTTP يرجّع 401 (authentication refused) ​

سجلّات التشغيل وتشخيص الدليل ستبلّغ عن authentication refused (401). هذا يعني أن الخادم يطلب المصادقة، وليس أن OpenClaw معطّل:

  • خوادم OAuth: تأكد من تهيئة auth: "oauth" وبيانات oauth الوصفية المطلوبة، ثم اتبع عملية تسجيل الدخول في الخطوة 5
  • بيانات اعتماد ثابتة: تحقق من تهيئة header / بيانات الاعتماد لهذا الخادم في mcp.servers—وفي الوقت نفسهلا تكتب token نصًا صريحًا في التهيئة، بل خزّنه عبر آلية secret

تقنيات متقدمة (اختياري) ​

**الاتجاه المعاكس: كشف محادثات القنوات إلى Claude Code / Codex. ** يجعل openclaw mcp serve OpenClaw نفسه يعمل كخادم MCP (stdio): يبدأ عميل MCP العملية ويحتفظ بها، ويتصل الجسر عبر WebSocket بـ Gateway محلي أو بعيد، فيحوّل جلسات القنوات المُوجَّهة إلى جلسات MCP.

bash
openclaw mcp serve                                                 # 本地 Gateway
openclaw mcp serve --url wss://gateway-host:18789 \
  --token-file ~/.openclaw/gateway.token                          # 远程 Gateway(token)

الأدوات التي يكشفها الجسر: conversations_list، conversation_get، messages_read، attachments_fetch، events_poll، events_wait، messages_send، بالإضافة إلى permissions_list_open / permissions_respond لمعالجة موافقات exec والإضافات. لاحظ أن قائمة الانتظار للأحداث في الوقت الفعلي—تضيع فور انقطاع الجسر، وتُقرأ الرسائل التاريخية عبر messages_read.

**ضبط وضع الموافقة للخوادم الموثوقة. ** موافقة أدوات MCP في Codex تتبع افتراضيًا موقف أذونات الجلسة؛ ويمكن تخفيف ذلك صراحةً للخوادم الموثوقة:

bash
openclaw mcp add memory \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-memory \
  --approval approve

ثلاث درجات: approve (تخطي الموافقة لكل استدعاء، للخوادم الموثوقة فقط) / prompt (السؤال في كل مرة) / auto (حسب تعليقات أمان الأداة). الخوادم المحفوظة تُعدَّل فرديًا عبر openclaw mcp configure <name> --approval ….

**مهلة وتزامن لكل خادم. ** تضبط connectionTimeoutMs / requestTimeoutMs مهلات الاتصال والطلبات (بالميلي ثانية)؛ وsupportsParallelToolCalls: true يعلّم الخوادم التي يمكن للمحوّل استدعاؤها بشكل متزامن.

خلاصة هذا الدرس ​

✅ MCP = بروتوكولاستعارة الأدوات من برامج أخرى. OpenClaw بعد الاتصال بخادم MCP، تدخل الأدوات تلقائيًا إلى دليل أدوات الوكيل، بل وتخضع لنفس منظومة tool-profile / tool-policy للإدارة—الربط لا يتجاوز سياساتك.

✅ ربط MCP في OpenClaw ثلاثة وجوه لكيان واحد: واجهة التحكم (Settings → MCP)، وCLI (openclaw mcp)، وملف التهيئة (mcp.servers)، وجميعها تكتب في نفس التهيئة.

✅ سلسلة التحقق: status --verbose (تهيئة للقراءة فقط) ← doctor (فحص ثابت) ← doctor --probe / probe (اتصال حقيقي يسرد الأدوات). حفظ التعريف لا يثبت شيئًا.

✅ تضييق سطح التعرض: --include / toolFilter / openclaw mcp tools؛ حصر خادم نظام الملفات في أصغر شجرة أدلة ممكنة؛ داخل الجلسة استخدم + ← Plugins ← Tool access للتعطيل واحدًا تلو الآخر.

✅ أوامر CLI الكتابية (add / set / configure / tools / unset / login / logout / probe / doctor --probe) تتطلب حالة حصرية — إذا كان Gateway يعمل فأوقفه أولًا ثم أعد المحاولة، أو استخدم Control UI بدلًا من ذلك.

✅ الاتجاه المعاكس openclaw mcp serve: تشغيل OpenClaw كخادم MCP، لإتاحة محادثات القنوات لـ Claude Code / Codex.

حقول التكوين الرئيسيةالقيمة الموصى بهاالشرح
mcp.servers.<name>.transportstreamable-http / sse / stdioالخوادم البعيدة تستخدم عائلة HTTP، والأوامر المحلية تستخدم stdio
command + args مقابل urlاختر واحدًا فقطلـ stdio املأ الأمر والوسائط، ولـ HTTP املأ URL؛ كتابة الاثنين معًا سيُرفضها التحقق
toolFilter.include / excludeاحتفظ فقط بالأدوات المطلوبة (يدعم * كمحرف بدل)يحدث التصفية قبل دخول الأدوات إلى الكتالوج
enabledtrue / falsefalse يُبقي التعريف دون اتصال
connectionTimeoutMs / requestTimeoutMs5000 / 20000مهلة الاتصال / الطلب لكل خادم (بالمللي ثانية)
auth"oauth"OAuth لخوادم HTTP، يُستخدم مع openclaw mcp login
codex.defaultToolsApprovalModeapprove / prompt / autoCodex وضع اعتماد الأدوات، للكتابة استخدم --approval

مرجع سريع لـ CLI: openclaw mcp list / show / status / doctor / probe / add / set / configure / tools / login / logout / reload / unset. لجدول الأوامر الكامل انظر مرجع سريع لأوامر وإعدادات CLI.

استعراض الدرس التالي ​

اكتملت ثلاثية سير العمل: المهام المجدولة تدير متى يتم العمل، والمتصفح يدير جلب المعلومات من الإنترنت، وMCP يدير القدرات الإضافية. في الدرس التالي تطبيقات عملية: اختر مسارك، اختر مسارًا حسب هويتك واجمع الثلاثية في عمل حقيقي.

ستتعلم:

دروس ذات صلة ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.