MCP

openclaw mcp لديه مهمتان:

• تشغيل OpenClaw كخادم MCP باستخدام openclaw mcp serve
• إدارة تعريفات خوادم MCP الصادرة المُدارة من OpenClaw باستخدام list وshow وstatus وdoctor وprobe وadd وset وconfigure وtools وlogin وlogout وreload وunset

بعبارة أخرى:

• serve يعني أن OpenClaw يعمل كخادم MCP
• الأوامر الفرعية الأخرى تعني أن OpenClaw يعمل كسجل من جهة عميل MCP لخوادم MCP التي قد تستهلكها بيئات تشغيله لاحقًا

استخدم openclaw acp عندما ينبغي أن يستضيف OpenClaw جلسة حاضنة برمجة بنفسه ويوجه بيئة التشغيل تلك عبر ACP.

اختر مسار MCP المناسب

لدى OpenClaw عدة أسطح MCP. اختر السطح الذي يطابق من يملك بيئة تشغيل الوكيل ومن يملك الأدوات.

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.

اختر وضع عميل

استخدم الجسر نفسه بطريقتين مختلفتين:

ما الذي يعرضه serve

يستخدم الجسر بيانات تعريف مسار جلسة Gateway الحالية لعرض المحادثات المدعومة بالقنوات. تظهر المحادثة عندما تكون لدى OpenClaw بالفعل حالة جلسة ذات مسار معروف مثل:

• channel
• بيانات تعريف المستلم أو الوجهة
• accountId اختياري
• threadId اختياري

يمنح هذا عملاء MCP مكانًا واحدًا من أجل:

• سرد المحادثات الموجهة الأخيرة
• قراءة سجل النصوص الأخير
• انتظار أحداث واردة جديدة
• إرسال رد عبر المسار نفسه
• رؤية طلبات الموافقة التي تصل أثناء اتصال الجسر

الاستخدام

openclaw mcp serve

openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verboseopenclaw mcp serve --claude-channel-mode off

أدوات الجسر

يعرض الجسر الحالي أدوات MCP التالية:

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

يحتفظ الجسر بطابور أحداث في الذاكرة أثناء اتصاله.

أنواع الأحداث الحالية:

• message
• exec_approval_requested
• exec_approval_resolved
• plugin_approval_requested
• plugin_approval_resolved
• claude_permission_request

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

يمكن للجسر أيضًا عرض إشعارات قناة خاصة بـ Claude. هذا هو مكافئ OpenClaw لمحول قناة Claude Code: تبقى أدوات MCP القياسية متاحة، لكن الرسائل الواردة الحية يمكن أن تصل أيضًا كإشعارات MCP خاصة بـ Claude.

عند تفعيل وضع قناة 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:

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

لا يخترع الجسر التوجيه. إنه لا يكشف إلا المحادثات التي يعرف Gateway بالفعل كيفية توجيهها.

وهذا يعني:

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

إذا كانت محادثة مفقودة من conversations_list، فالسبب المعتاد ليس إعداد MCP. بل تكون بيانات تعريف المسار مفقودة أو غير مكتملة في جلسة Gateway الأساسية.

الاختبار

يوفّر OpenClaw اختبار Docker smoke حتميًا لهذا الجسر:

pnpm test:docker:mcp-channels

يتولى هذا الاختبار:

• تشغيل حاوية Gateway مهيأة ببيانات أولية
• تشغيل حاوية ثانية تستدعي openclaw mcp serve
• التحقق من اكتشاف المحادثات، وقراءة النصوص، وقراءة بيانات تعريف المرفقات، وسلوك طابور الأحداث المباشر، وتوجيه الإرسال الصادر
• التحقق من إشعارات القنوات والأذونات بأسلوب Claude عبر جسر stdio MCP الحقيقي

هذه أسرع طريقة لإثبات أن الجسر يعمل دون ربط حساب Telegram أو Discord أو iMessage حقيقي بتشغيل الاختبار.

للمزيد من سياق الاختبار، راجع الاختبار.

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

OpenClaw كسجل عملاء MCP

هذا هو مسار openclaw mcp list وshow وstatus وdoctor وprobe وadd وset وconfigure وtools وlogin وlogout وreload وunset.

لا تكشف هذه الأوامر OpenClaw عبر MCP. إنها تدير تعريفات خوادم MCP المُدارة بواسطة OpenClaw ضمن mcp.servers في إعدادات OpenClaw. ولا تقرأ خوادم mcporter من config/mcporter.json.

هذه التعريفات المحفوظة مخصصة لبيئات التشغيل التي يشغّلها OpenClaw أو يهيئها لاحقًا، مثل OpenClaw المضمّن ومحوّلات بيئات التشغيل الأخرى. يخزّن OpenClaw التعريفات مركزيًا حتى لا تضطر تلك البيئات إلى الاحتفاظ بقوائم خوادم MCP مكررة خاصة بها.

قد تطبّع محوّلات بيئة التشغيل هذا السجل المشترك إلى الشكل الذي يتوقعه عميلها اللاحق. على سبيل المثال، يستهلك OpenClaw المضمّن قيم transport الخاصة بـ OpenClaw مباشرةً، بينما يتلقى Claude Code وGemini قيم type أصلية للـ CLI مثل http أو sse أو stdio.

يحترم Codex app-server أيضًا كتلة codex اختيارية على كل خادم. هذه بيانات تعريف إسقاط OpenClaw لسلاسل Codex app-server فقط؛ ولا تغيّر جلسات ACP أو إعدادات حزمة Codex العامة أو محوّلات بيئات التشغيل الأخرى. استخدم codex.agents غير الفارغة لإسقاط خادم إلى معرّفات وكلاء OpenClaw محددة فقط. تُرفض قوائم الوكلاء الفارغة أو البيضاء أو غير الصالحة بواسطة تحقق الإعدادات وتُحذف بواسطة مسار إسقاط بيئة التشغيل بدلًا من أن تصبح عامة. استخدم codex.defaultToolsApprovalMode (auto أو prompt أو approve) لإصدار default_tools_approval_mode الأصلي لـ Codex لخادم موثوق. يزيل OpenClaw بيانات تعريف codex قبل تسليم إعدادات mcp_servers الأصلية إلى Codex.

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

يخزّن OpenClaw أيضًا سجل خوادم MCP خفيفًا في الإعدادات للأسطح التي تريد تعريفات MCP مُدارة بواسطة OpenClaw.

الأوامر:

• openclaw mcp list
• openclaw mcp show [name]
• openclaw mcp status [--verbose]
• openclaw mcp doctor [name] [--probe]
• openclaw mcp probe [name]
• openclaw mcp add <name> [flags]
• openclaw mcp set <name> <json>
• openclaw mcp configure <name> [flags]
• openclaw mcp tools <name> [--include csv] [--exclude csv] [--clear]
• openclaw mcp login <name> [--code code]
• openclaw mcp logout <name>
• openclaw mcp reload
• openclaw mcp unset <name>

ملاحظات:

• يرتّب list أسماء الخوادم.
• يطبع show دون اسم كائن خادم MCP المهيأ بالكامل.
• يصنّف status وسائل النقل المهيأة دون الاتصال. يتضمن --verbose تفاصيل التشغيل والمهلة وOAuth والمرشح والاستدعاء المتوازي التي تم حلها.
• ينفّذ doctor فحوصات ثابتة دون الاتصال. أضف --probe عندما ينبغي للأمر أن يتحقق أيضًا من اتصال الخوادم المفعّلة.
• يتصل probe ويبلغ عن أعداد الأدوات، ودعم الموارد/المطالبات، ودعم تغيّر القوائم، والتشخيصات.
• يقبل add أعلام stdio مثل --command و--arg و--env و--cwd، أو أعلام HTTP مثل --url و--transport و--header و--auth oauth وTLS والمهلة وأعلام اختيار الأدوات.
• يتوقع set قيمة كائن JSON واحدة على سطر الأوامر.
• يحدّث configure التفعيل، ومرشحات الأدوات، والمهل، وOAuth، وTLS، وتلميحات استدعاء الأدوات المتوازي دون استبدال تعريف الخادم كله.
• يحدّث tools مرشحات الأدوات لكل خادم. إدخالات التضمين/الاستبعاد هي أسماء أدوات MCP وأنماط * بسيطة.
• يشغّل login تدفق OAuth لخوادم HTTP المهيأة بـ auth: "oauth". يطبع التشغيل الأول عنوان URL للتفويض؛ أعد التشغيل مع --code بعد الموافقة.
• يمحو logout بيانات اعتماد OAuth المخزنة للخادم المسمى دون إزالة تعريف الخادم المحفوظ.
• يتخلص reload من بيئات تشغيل MCP المخبأة داخل العملية. لا تزال عمليات Gateway أو الوكلاء في عملية أخرى تحتاج إلى مسار إعادة تحميل أو إعادة تشغيل خاص بها.
• استخدم transport: "streamable-http" لخوادم Streamable HTTP MCP. يطبّع openclaw mcp set أيضًا type: "http" الأصلي للـ CLI إلى شكل الإعدادات القانوني نفسه للتوافق.
• يفشل unset إذا لم يكن الخادم المسمى موجودًا.

أمثلة:

openclaw mcp listopenclaw mcp show context7 --jsonopenclaw mcp status --verboseopenclaw mcp doctor --probeopenclaw mcp probe context7 --jsonopenclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memoryopenclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'openclaw mcp tools context7 --include 'resolve-library-id,get-library-docs'openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'openclaw mcp configure docs --timeout 20 --connect-timeout 5 --include 'search,read_*'openclaw mcp configure docs --auth oauth --oauth-scope 'docs.read'openclaw mcp login docsopenclaw mcp logout docsopenclaw mcp unset context7

وصفات الخوادم الشائعة

تحفظ هذه الأمثلة تعريفات الخوادم فقط. شغّل openclaw mcp doctor --probe بعدها لإثبات أن الخادم يبدأ ويكشف الأدوات.

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 mcp add memory \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-memoryopenclaw mcp probe memory --json

openclaw mcp add local-tools \  --command node \  --arg ./dist/mcp-server.js \  --cwd /srv/openclaw-tools \  --env API_BASE=https://internal.exampleopenclaw mcp status --verbose

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 doctor docs --probe

openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'openclaw mcp tools cua-driver --include 'list_apps,observe,click,type'openclaw mcp doctor cua-driver --probe

أشكال إخراج JSON

استخدم --json للسكربتات ولوحات المعلومات. يمكن أن تنمو مجموعات الحقول بمرور الوقت، لذلك ينبغي للمستهلكين تجاهل المفاتيح غير المعروفة.

{  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "configured": true,      "enabled": true,      "ok": true,      "transport": "streamable-http",      "launch": "streamable-http https://mcp.example.com/mcp",      "auth": "oauth",      "authStatus": {        "hasTokens": true,        "hasClientInformation": true,        "hasCodeVerifier": false,        "hasDiscoveryState": true,        "hasLastAuthorizationUrl": false      },      "requestTimeoutMs": 20000,      "connectionTimeoutMs": 5000,      "toolFilter": {        "include": ["search", "read_*"],        "exclude": []      },      "supportsParallelToolCalls": true    }  ]}

{  "ok": false,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": false,      "issues": [        {          "level": "error",          "message": "OAuth credentials are not authorized; run openclaw mcp login docs"        }      ]    }  ]}

{  "path": "/home/user/.openclaw/openclaw.json",  "generatedAt": "2026-05-31T09:00:00.000Z",  "servers": {    "docs": {      "launch": "streamable-http https://mcp.example.com/mcp",      "tools": 2,      "resources": true,      "prompts": false,      "listChanged": {        "tools": true,        "resources": false,        "prompts": false      }    }  },  "tools": ["docs__read_page", "docs__search"],  "diagnostics": []}

مثال على شكل التكوين:

{  "mcp": {    "servers": {      "context7": {        "command": "uvx",        "args": ["context7-mcp"]      },      "docs": {        "url": "https://mcp.example.com",        "transport": "streamable-http",        "timeout": 20,        "connectTimeout": 5,        "supportsParallelToolCalls": true,        "auth": "oauth",        "oauth": {          "scope": "docs.read"        },        "sslVerify": true,        "clientCert": "/path/to/client.crt",        "clientKey": "/path/to/client.key",        "toolFilter": {          "include": ["search_*"],          "exclude": ["admin_*"]        }      }    }  }}

نقل Stdio

يطلق عملية فرعية محلية ويتواصل عبر stdin/stdout.

نقل SSE / HTTP

يتصل بخادم MCP بعيد عبر HTTP Server-Sent Events.

مثال:

{  "mcp": {    "servers": {      "remote-tools": {        "url": "https://mcp.example.com",        "auth": "oauth",        "timeout": 20,        "headers": {          "Authorization": "Bearer <token>"        }      }    }  }}

تُنقّح القيم الحساسة في url (userinfo) وheaders في السجلات وإخراج الحالة. يحذر openclaw mcp doctor عندما تحتوي إدخالات headers أو env التي تبدو حساسة على قيم نصية صريحة، حتى يتمكن المشغلون من نقل تلك القيم خارج التكوين المثبت.

سير عمل OAuth

OAuth مخصص لخوادم MCP عبر HTTP التي تعلن عن تدفق MCP OAuth. تُتجاهل ترويسات Authorization الثابتة لخادم ما أثناء تفعيل auth: "oauth".

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

openclaw mcp login docs

openclaw mcp login docs --code abc123

openclaw mcp status --verboseopenclaw mcp doctor docs --probe

openclaw mcp logout docs

إذا كان المزود يدوّر الرموز أو علقت حالة التفويض، فشغّل openclaw mcp logout <name>، ثم كرر login. يستطيع logout مسح بيانات الاعتماد لخادم HTTP محفوظ حتى بعد إزالة auth: "oauth" من التكوين، ما دام اسم الخادم وعنوان URL لا يزالان يحددان إدخال مخزن بيانات الاعتماد.

نقل Streamable HTTP

streamable-http خيار نقل إضافي إلى جانب sse وstdio. يستخدم بث HTTP للتواصل ثنائي الاتجاه مع خوادم MCP البعيدة.

يستخدم تكوين OpenClaw transport: "streamable-http" كتهجئة معيارية. تُقبل قيم MCP الأصلية في CLI من نوع type: "http" عند حفظها عبر openclaw mcp set ويصلحها openclaw doctor --fix في التكوين الموجود، لكن transport هو ما يستهلكه OpenClaw المضمّن مباشرة.

مثال:

{  "mcp": {    "servers": {      "streaming-tools": {        "url": "https://mcp.example.com/stream",        "transport": "streamable-http",        "connectTimeout": 10,        "timeout": 30,        "headers": {          "Authorization": "Bearer <token>"        }      }    }  }}

واجهة التحكم

تتضمن واجهة التحكم في المتصفح صفحة مخصصة لإعدادات MCP على /mcp. تعرض الصفحة أعداد الخوادم المكوّنة، وملخصات التفعيل/OAuth/المرشحات، وصفوف النقل لكل خادم، وعناصر تحكم التفعيل/التعطيل، وأوامر CLI الشائعة، ومحررا محدود النطاق لقسم تكوين mcp.

استخدم الصفحة لتعديلات المشغل والجرد السريع. استخدم openclaw mcp doctor --probe أو openclaw mcp probe عندما تحتاج إلى إثبات حي للخادم.

سير عمل المشغل:

1. افتح واجهة التحكم واختر MCP.
2. راجع بطاقات الملخص لإجمالي الخوادم والمفعّلة منها وخوادم OAuth والخوادم التي تمت تصفيتها.
3. استخدم كل صف خادم للاطلاع على تلميحات النقل والمصادقة والمرشح والمهلة والأوامر.
4. بدّل التفعيل عندما تريد الاحتفاظ بتعريف مع استبعاده من اكتشاف وقت التشغيل.
5. حرّر قسم تكوين mcp محدود النطاق لإجراء تغييرات بنيوية مثل إضافة خوادم أو ترويسات أو TLS أو بيانات OAuth الوصفية أو مرشحات الأدوات.
6. اختر حفظ للاحتفاظ بالتكوين فقط، أو حفظ ونشر للتطبيق عبر مسار تكوين Gateway.
7. شغّل openclaw mcp doctor --probe عندما تحتاج إلى إثبات مباشر بأن الخادم المحرر يبدأ العمل ويعرض الأدوات.

ملاحظات:

• تقتبس مقتطفات الأوامر أسماء الخوادم حتى تظل الأسماء غير المعتادة قابلة للنسخ في الصدفة
• تُحجب القيم التي تبدو كعناوين URL قبل العرض عندما تحتوي على بيانات اعتماد مضمّنة
• لا تبدأ الصفحة عمليات نقل MCP من تلقاء نفسها
• قد تحتاج أوقات التشغيل النشطة إلى openclaw mcp reload أو نشر تكوين Gateway أو إعادة تشغيل العملية، بحسب العملية التي تملك عملاء MCP

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

توثّق هذه الصفحة الجسر كما هو مشحون اليوم.

الحدود الحالية:

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

ذات صلة

• مرجع CLI
• Plugins