الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

openclaw mcp له مهمتان:
  • تشغيل OpenClaw كخادم MCP باستخدام openclaw mcp serve
  • إدارة تعريفات خوادم MCP الصادرة المملوكة لـ OpenClaw باستخدام list وshow وset وunset
بعبارة أخرى:
  • serve يعني أن OpenClaw يعمل كخادم MCP
  • list / show / set / unset تعني أن OpenClaw يعمل كسجل من جهة عميل MCP لخوادم MCP أخرى قد تستهلكها بيئات التشغيل الخاصة به لاحقًا
استخدم openclaw acp عندما ينبغي لـ OpenClaw استضافة جلسة حاضنة ترميز بنفسه وتوجيه بيئة التشغيل تلك عبر ACP.

​
OpenClaw كخادم MCP

هذا هو مسار openclaw mcp serve.

​
متى تستخدم serve

استخدم openclaw mcp serve عندما:
  • ينبغي لـ Codex أو Claude Code أو عميل MCP آخر التحدث مباشرة إلى محادثات القنوات المدعومة من OpenClaw
  • لديك بالفعل Gateway محلي أو بعيد لـ OpenClaw مع جلسات موجهة
  • تريد خادم MCP واحدًا يعمل عبر خلفيات قنوات OpenClaw بدلًا من تشغيل جسور منفصلة لكل قناة
استخدم openclaw acp بدلًا من ذلك عندما ينبغي لـ OpenClaw استضافة بيئة تشغيل الترميز بنفسه وإبقاء جلسة الوكيل داخل OpenClaw.

​
آلية العمل

يبدأ openclaw mcp serve خادم MCP عبر stdio. يملك عميل MCP تلك العملية. ما دام العميل يبقي جلسة stdio مفتوحة، يتصل الجسر بـ Gateway محلي أو بعيد لـ OpenClaw عبر WebSocket ويعرض محادثات القنوات الموجهة عبر MCP.
1

ينشئ العميل الجسر

ينشئ عميل MCP العملية openclaw mcp serve.
2

يتصل الجسر بـ Gateway

يتصل الجسر بـ OpenClaw Gateway عبر WebSocket.
3

تصبح الجلسات محادثات MCP

تصبح الجلسات الموجهة محادثات MCP وأدوات نصوص/سجل.
4

تصطف الأحداث الحية في طابور

تُضاف الأحداث الحية إلى طابور في الذاكرة أثناء اتصال الجسر.
5

دفع Claude اختياري

إذا كان وضع قناة Claude مفعّلًا، يمكن للجلسة نفسها أيضًا تلقي إشعارات دفع خاصة بـ Claude.
  • تبدأ حالة الطابور الحي عند اتصال الجسر
  • يُقرأ سجل النصوص الأقدم باستخدام messages_read
  • لا توجد إشعارات دفع Claude إلا أثناء بقاء جلسة MCP نشطة
  • عند قطع اتصال العميل، يخرج الجسر ويختفي الطابور الحي
  • نقاط دخول الوكيل أحادية التشغيل مثل openclaw agent وopenclaw infer model run تنهي أي بيئات تشغيل MCP مضمّنة تفتحها عند اكتمال الرد، لذلك لا تتراكم عمليات stdio MCP الفرعية عند التشغيل النصي المتكرر
  • تُفكك خوادم stdio MCP التي يشغلها OpenClaw (المضمّنة أو المكوّنة من المستخدم) كشجرة عمليات عند الإيقاف، لذلك لا تبقى العمليات الفرعية التي يبدأها الخادم بعد خروج عميل stdio الأب
  • حذف جلسة أو إعادة تعيينها يتخلص من عملاء MCP لتلك الجلسة عبر مسار التنظيف المشترك لبيئة التشغيل، لذلك لا تبقى اتصالات stdio عالقة مرتبطة بجلسة محذوفة

​
اختر وضع عميل

استخدم الجسر نفسه بطريقتين مختلفتين:
أدوات MCP القياسية فقط. استخدم conversations_list وmessages_read وevents_poll وevents_wait وmessages_send وأدوات الموافقة.
حاليًا، يتصرف auto مثل on. لا يوجد اكتشاف لقدرات العميل بعد.

​
ما يعرضه serve

يستخدم الجسر بيانات وصف مسارات جلسات Gateway الموجودة لعرض المحادثات المدعومة بالقنوات. تظهر محادثة عندما يكون لدى OpenClaw بالفعل حالة جلسة ذات مسار معروف مثل:
  • channel
  • بيانات وصف المستلم أو الوجهة
  • accountId اختياري
  • threadId اختياري
يوفر ذلك لعملاء MCP مكانًا واحدًا من أجل:
  • سرد المحادثات الموجهة الحديثة
  • قراءة سجل النصوص الحديث
  • انتظار أحداث واردة جديدة
  • إرسال رد عبر المسار نفسه
  • رؤية طلبات الموافقة التي تصل أثناء اتصال الجسر

​
الاستخدام

openclaw mcp serve

​
أدوات الجسر

يعرض الجسر الحالي أدوات MCP التالية:
يسرد المحادثات الحديثة المدعومة بجلسات والتي لديها بالفعل بيانات وصف للمسار في حالة جلسة Gateway.عوامل تصفية مفيدة:
  • limit
  • search
  • channel
  • includeDerivedTitles
  • includeLastMessage
يعيد محادثة واحدة حسب session_key باستخدام بحث مباشر عن جلسة Gateway.
يقرأ رسائل النصوص الحديثة لمحادثة واحدة مدعومة بجلسة.
يستخرج كتل محتوى الرسائل غير النصية من رسالة نصية واحدة. هذه طريقة عرض بيانات وصفية فوق محتوى النصوص، وليست مخزنًا مستقلًا ودائمًا لكائنات المرفقات.
يقرأ الأحداث الحية الموضوعة في الطابور منذ مؤشر رقمي.
يجري استقصاءً طويلًا حتى يصل الحدث التالي المطابق في الطابور أو تنتهي المهلة.استخدم هذا عندما يحتاج عميل MCP عام إلى تسليم قريب من الوقت الفعلي دون بروتوكول دفع خاص بـ Claude.
يرسل النص عبر المسار نفسه المسجل بالفعل في الجلسة.السلوك الحالي:
  • يتطلب مسار محادثة موجودًا
  • يستخدم قناة الجلسة والمستلم ومعرف الحساب ومعرف السلسلة
  • يرسل نصًا فقط
يسرد طلبات الموافقة المعلقة على exec/Plugin التي لاحظها الجسر منذ اتصاله بـ Gateway.
يحل طلب موافقة معلقًا واحدًا على exec/Plugin باستخدام:
  • allow-once
  • allow-always
  • deny

​
نموذج الأحداث

يحتفظ الجسر بطابور أحداث في الذاكرة أثناء اتصاله. أنواع الأحداث الحالية:
  • message
  • exec_approval_requested
  • exec_approval_resolved
  • plugin_approval_requested
  • plugin_approval_resolved
  • claude_permission_request
  • الطابور حي فقط؛ يبدأ عند بدء جسر MCP
  • لا يعيد events_poll وevents_wait تشغيل سجل Gateway الأقدم من تلقاء نفسيهما
  • ينبغي قراءة السجل الدائم باستخدام messages_read

​
إشعارات قناة Claude

يمكن للجسر أيضًا عرض إشعارات قناة خاصة بـ Claude. هذا هو مكافئ OpenClaw لمحول قناة Claude Code: تبقى أدوات MCP القياسية متاحة، لكن يمكن أن تصل الرسائل الواردة الحية أيضًا كإشعارات MCP خاصة بـ Claude.
--claude-channel-mode off: أدوات MCP القياسية فقط.
عند تفعيل وضع قناة Claude، يعلن الخادم عن قدرات Claude التجريبية ويمكنه إصدار:
  • notifications/claude/channel
  • notifications/claude/channel/permission
سلوك الجسر الحالي:
  • تُمرّر رسائل نصوص user الواردة كـ notifications/claude/channel
  • تُتبع طلبات إذن Claude المستلمة عبر MCP في الذاكرة
  • إذا أرسلت المحادثة المرتبطة لاحقًا yes abcde أو no abcde، يحول الجسر ذلك إلى notifications/claude/channel/permission
  • هذه الإشعارات خاصة بالجلسة الحية فقط؛ إذا قطع عميل MCP الاتصال، فلا يوجد هدف دفع
هذا مخصص للعميل عمدًا. ينبغي لعملاء MCP العامين الاعتماد على أدوات الاستقصاء القياسية.

​
تكوين عميل MCP

مثال على تكوين عميل stdio: 
{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url",
        "wss://gateway-host:18789",
        "--token-file",
        "/path/to/gateway.token"
      ]
    }
  }
}
بالنسبة إلى معظم عملاء MCP العامين، ابدأ بسطح الأدوات القياسي وتجاهل وضع Claude. شغّل وضع Claude فقط للعملاء الذين يفهمون فعليًا أساليب الإشعارات الخاصة بـ Claude.

​
الخيارات

يدعم openclaw mcp serve ما يلي:
​
--url
string
عنوان URL لـ Gateway WebSocket.
​
--token
string
رمز Gateway.
​
--token-file
string
قراءة الرمز من ملف.
​
--password
string
كلمة مرور Gateway.
​
--password-file
string
قراءة كلمة المرور من ملف.
​
--claude-channel-mode
"auto" | "on" | "off"
وضع إشعارات Claude.
​
-v, --verbose
boolean
سجلات تفصيلية على stderr.
فضّل --token-file أو --password-file بدلًا من الأسرار المضمنة مباشرة عند الإمكان.

​
الأمان وحدود الثقة

لا يخترع الجسر التوجيه. إنه يعرض فقط المحادثات التي يعرف Gateway بالفعل كيفية توجيهها. هذا يعني:
  • قوائم السماح للمرسلين والاقتران والثقة على مستوى القناة لا تزال تابعة لتكوين قناة OpenClaw الأساسية
  • لا يمكن لـ messages_send الرد إلا عبر مسار مخزن موجود
  • حالة الموافقة حية/في الذاكرة فقط لجلسة الجسر الحالية
  • ينبغي لمصادقة الجسر استخدام عناصر تحكم رمز Gateway أو كلمة المرور نفسها التي تثق بها لأي عميل Gateway بعيد آخر
إذا كانت محادثة مفقودة من conversations_list، فغالبًا ليس السبب تكوين MCP. السبب هو فقدان بيانات وصف المسار أو عدم اكتمالها في جلسة Gateway الأساسية.

​
الاختبار

يوفر OpenClaw اختبار دخان Docker حتميًا لهذا الجسر: 
pnpm test:docker:mcp-channels
اختبار الدخان هذا:
  • يبدأ حاوية Gateway مزروعة مسبقًا
  • يبدأ حاوية ثانية تنشئ openclaw mcp serve
  • يتحقق من اكتشاف المحادثات وقراءات النصوص وقراءات بيانات وصف المرفقات وسلوك طابور الأحداث الحية وتوجيه الإرسال الصادر
  • يتحقق من إشعارات القناة والأذونات بأسلوب Claude عبر جسر stdio MCP الحقيقي
هذه أسرع طريقة لإثبات أن الجسر يعمل دون توصيل حساب Telegram أو Discord أو iMessage حقيقي بتشغيل الاختبار. لسياق اختبار أوسع، راجع الاختبار.

​
استكشاف الأخطاء وإصلاحها

يعني ذلك عادةً أن جلسة Gateway ليست قابلة للتوجيه بالفعل. تأكد من أن الجلسة الأساسية لديها بيانات وصف لمسار القناة/الموفر والمستلم والحساب/السلسلة الاختياريين.
متوقع. يبدأ الطابور الحي عندما يتصل الجسر. اقرأ سجل النصوص الأقدم باستخدام messages_read.
تحقق من كل ما يلي:
  • أبقى العميل جلسة stdio MCP مفتوحة
  • --claude-channel-mode مضبوط على on أو auto
  • العميل يفهم فعليًا أساليب الإشعارات الخاصة بـ Claude
  • حدثت الرسالة الواردة بعد اتصال الجسر
يعرض permissions_list_open فقط طلبات الموافقة التي لوحظت أثناء اتصال الجسر. إنه ليس واجهة API دائمة لسجل الموافقات.

​
OpenClaw كسجل عميل MCP

هذا هو مسار openclaw mcp list وshow وset وunset. لا تعرض هذه الأوامر OpenClaw عبر MCP. إنها تدير تعريفات خادم MCP المملوكة لـ OpenClaw ضمن mcp.servers في إعدادات OpenClaw. هذه التعريفات المحفوظة مخصصة لبيئات التشغيل التي يشغلها OpenClaw أو يهيئها لاحقا، مثل Pi المضمن ومحولات التشغيل الأخرى. يخزن OpenClaw التعريفات مركزيا حتى لا تحتاج بيئات التشغيل هذه إلى الاحتفاظ بقوائم خوادم MCP مكررة خاصة بها.
  • هذه الأوامر تقرأ إعدادات OpenClaw أو تكتبها فقط
  • لا تتصل بخادم MCP الهدف
  • لا تتحقق مما إذا كان الأمر أو عنوان URL أو النقل البعيد قابلا للوصول الآن
  • تقرر محولات التشغيل أشكال النقل التي تدعمها فعليا وقت التنفيذ
  • يعرض Pi المضمن أدوات MCP المهيأة في ملفات تعريف الأدوات العادية coding وmessaging؛ لا يزال minimal يخفيها، ويعطلها tools.deny: ["bundle-mcp"] صراحة
  • تتم إزالة بيئات تشغيل MCP المضمنة محددة النطاق للجلسة بعد mcp.sessionIdleTtlMs مللي ثانية من وقت الخمول (الافتراضي 10 دقائق؛ اضبطها على 0 للتعطيل)، وتنظفها عمليات التشغيل المضمنة أحادية التنفيذ عند نهاية التشغيل
قد تطبع محولات التشغيل هذا السجل المشترك بالشكل الذي يتوقعه العميل اللاحق. على سبيل المثال، يستهلك Pi المضمن قيم transport في OpenClaw مباشرة، بينما يتلقى Claude Code وGemini قيم type الأصلية للـ CLI مثل http أوsse أوstdio.

​
تعريفات خادم MCP المحفوظة

يخزن OpenClaw أيضا سجل خادم MCP خفيفا في الإعدادات للواجهات التي تريد تعريفات MCP مدارة من OpenClaw. الأوامر:
  • openclaw mcp list
  • openclaw mcp show [name]
  • openclaw mcp set <name> <json>
  • openclaw mcp unset <name>
ملاحظات:
  • يرتب list أسماء الخوادم.
  • يطبع show، دون اسم، كائن خادم MCP المهيأ كاملا.
  • يتوقع set قيمة كائن JSON واحدة في سطر الأوامر.
  • استخدم transport: "streamable-http" لخوادم MCP عبر Streamable HTTP. يطبع openclaw mcp set أيضا type: "http" الأصلي للـ CLI إلى شكل الإعدادات القياسي نفسه للتوافق.
  • يفشل unset إذا لم يكن الخادم المسمى موجودا.
أمثلة: 
openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'
openclaw mcp unset context7
مثال على شكل الإعدادات: 
{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com",
        "transport": "streamable-http"
      }
    }
  }
}

​
نقل Stdio

يشغل عملية فرعية محلية ويتواصل عبر stdin/stdout.
الحقلالوصف
commandالملف التنفيذي المراد تشغيله (مطلوب)
argsمصفوفة من وسيطات سطر الأوامر
envمتغيرات بيئة إضافية
cwd / workingDirectoryدليل العمل للعملية
مرشح أمان بيئة Stdioيرفض OpenClaw مفاتيح بيئة بدء تشغيل المفسر التي يمكنها تغيير كيفية بدء خادم MCP عبر stdio قبل أول RPC، حتى إذا ظهرت في كتلة env الخاصة بالخادم. تشمل المفاتيح المحظورة NODE_OPTIONS وPYTHONSTARTUP وPYTHONPATH وPERL5OPT وRUBYOPT وSHELLOPTS وPS4 ومتغيرات التحكم في التشغيل المشابهة. يرفض بدء التشغيل هذه المفاتيح بخطأ في الإعدادات حتى لا تتمكن من حقن تمهيد ضمني، أو تبديل المفسر، أو تمكين مصحح أخطاء ضد عملية stdio. لا تتأثر متغيرات البيئة العادية الخاصة بالاعتماديات والوكيل والخادم (GITHUB_TOKEN وHTTP_PROXY و*_API_KEY المخصصة، وما إلى ذلك).إذا كان خادم MCP لديك يحتاج فعلا إلى أحد المتغيرات المحظورة، فاضبطه على عملية مضيف Gateway بدلا من وضعه ضمن env لخادم stdio.

​
نقل SSE / HTTP

يتصل بخادم MCP بعيد عبر HTTP Server-Sent Events.
الحقلالوصف
urlعنوان URL عبر HTTP أو HTTPS للخادم البعيد (مطلوب)
headersخريطة اختيارية من مفاتيح وقيم لترويسات HTTP (مثل رموز المصادقة)
connectionTimeoutMsمهلة اتصال لكل خادم بالمللي ثانية (اختياري)
مثال: 
{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}
تتم تنقيح القيم الحساسة في url (userinfo) وheaders في السجلات ومخرجات الحالة.

​
نقل Streamable HTTP

streamable-http هو خيار نقل إضافي إلى جانب sse وstdio. يستخدم بث HTTP للتواصل ثنائي الاتجاه مع خوادم MCP البعيدة.
الحقلالوصف
urlعنوان URL عبر HTTP أو HTTPS للخادم البعيد (مطلوب)
transportاضبطه على "streamable-http" لاختيار هذا النقل؛ عند حذفه، يستخدم OpenClaw sse
headersخريطة اختيارية من مفاتيح وقيم لترويسات HTTP (مثل رموز المصادقة)
connectionTimeoutMsمهلة اتصال لكل خادم بالمللي ثانية (اختياري)
تستخدم إعدادات OpenClaw transport: "streamable-http" كالتهجئة القياسية. يتم قبول قيم MCP الأصلية للـ CLI مثل type: "http" عند حفظها عبر openclaw mcp set وإصلاحها بواسطة openclaw doctor --fix في الإعدادات الحالية، لكن transport هو ما يستهلكه Pi المضمن مباشرة. مثال: 
{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}
تدير هذه الأوامر الإعدادات المحفوظة فقط. إنها لا تبدأ جسر القناة، ولا تفتح جلسة عميل MCP حية، ولا تثبت أن الخادم الهدف قابل للوصول.

​
الحدود الحالية

توثق هذه الصفحة الجسر كما هو مشحون اليوم. الحدود الحالية:
  • يعتمد اكتشاف المحادثات على بيانات تعريف مسار جلسة Gateway الحالية
  • لا يوجد بروتوكول دفع عام يتجاوز المحول الخاص بـ Claude
  • لا توجد أدوات تعديل الرسائل أو التفاعل معها بعد
  • يتصل نقل HTTP/SSE/streamable-http بخادم بعيد واحد؛ لا توجد واجهة صاعدة متعددة الإرسال بعد
  • لا يتضمن permissions_list_open إلا الموافقات المرصودة أثناء اتصال الجسر

​
ذو صلة