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 صحبت کند
• از قبل یک OpenClaw Gateway محلی یا راه‌دور با نشست‌های مسیریابی‌شده دارید
• یک سرور MCP می‌خواهید که روی بک‌اندهای کانالی OpenClaw کار کند، به‌جای اجرای پل‌های جداگانه برای هر کانال

زمانی به‌جای آن از openclaw acp استفاده کنید که OpenClaw باید خودش زمان اجرای کدنویسی را میزبانی کند و نشست عامل را داخل OpenClaw نگه دارد.

نحوه کار

openclaw mcp serve یک سرور stdio MCP راه‌اندازی می‌کند. کلاینت MCP مالک آن فرایند است. تا زمانی که کلاینت نشست stdio را باز نگه دارد، پل از طریق WebSocket به یک OpenClaw Gateway محلی یا راه‌دور متصل می‌شود و گفت‌وگوهای کانالی مسیریابی‌شده را از طریق 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 قطعی ارائه می‌کند:

pnpm test:docker:mcp-channels

این دودآزمایی:

• یک کانتینر Gateway با داده اولیه راه‌اندازی می‌کند
• کانتینر دومی را راه‌اندازی می‌کند که openclaw mcp serve را اجرا می‌کند
• کشف گفتگو، خواندن رونوشت، خواندن فراداده پیوست، رفتار صف رویداد زنده، و مسیریابی ارسال خروجی را راستی‌آزمایی می‌کند
• اعلان‌های کانال و مجوز به سبک Claude را روی پل MCP واقعی stdio اعتبارسنجی می‌کند

این سریع‌ترین راه برای اثبات کارکرد پل بدون اتصال یک حساب واقعی 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 نمی‌خوانند.

این تعریف‌های ذخیره‌شده برای runtimeهایی هستند که OpenClaw بعداً راه‌اندازی یا پیکربندی می‌کند، مانند OpenClaw توکار و adapterهای runtime دیگر. OpenClaw تعریف‌ها را به‌صورت مرکزی ذخیره می‌کند تا آن runtimeها نیاز نداشته باشند فهرست‌های تکراری سرور MCP خودشان را نگه دارند.

adapterهای runtime ممکن است این رجیستری مشترک را به شکلی normalize کنند که کلاینت پایین‌دستی آن‌ها انتظار دارد. برای مثال، OpenClaw توکار مقادیر transport ‏OpenClaw را مستقیماً مصرف می‌کند، در حالی که Claude Code و Gemini مقادیر type بومی CLI مانند http، sse، یا stdio را دریافت می‌کنند.

app-server ‏Codex همچنین یک بلوک اختیاری codex را روی هر سرور رعایت می‌کند. این فراداده projection ‏OpenClaw فقط برای رشته‌های app-server ‏Codex است؛ نشست‌های ACP، پیکربندی عمومی harness ‏Codex، یا adapterهای runtime دیگر را تغییر نمی‌دهد. از codex.agents غیرخالی استفاده کنید تا یک سرور را فقط به idهای عامل مشخص OpenClaw project کنید. فهرست‌های عامل خالی، blank، یا نامعتبر توسط اعتبارسنجی پیکربندی رد می‌شوند و به‌جای global شدن، توسط مسیر projection runtime حذف می‌شوند. از codex.defaultToolsApprovalMode (auto، prompt، یا approve) استفاده کنید تا default_tools_approval_mode بومی Codex را برای یک سرور مورد اعتماد صادر کنید. OpenClaw پیش از تحویل پیکربندی بومی mcp_servers به Codex، فراداده 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 ‏transportهای پیکربندی‌شده را بدون اتصال دسته‌بندی می‌کند. --verbose جزئیات راه‌اندازی، timeout، OAuth، filter، و فراخوانی موازی resolve‌شده را شامل می‌شود.
• doctor بررسی‌های ایستا را بدون اتصال انجام می‌دهد. وقتی فرمان باید وصل شدن سرورهای فعال را نیز راستی‌آزمایی کند، --probe را اضافه کنید.
• probe وصل می‌شود و تعداد ابزارها، پشتیبانی resources/prompts، پشتیبانی list-change، و عیب‌یابی‌ها را گزارش می‌دهد.
• add ‏flagهای stdio مانند --command، --arg، --env، و --cwd، یا flagهای HTTP مانند --url، --transport، --header، --auth oauth، TLS، timeout، و flagهای انتخاب ابزار را می‌پذیرد.
• set انتظار دارد یک مقدار شیء JSON روی خط فرمان دریافت کند.
• configure فعال‌سازی، filterهای ابزار، timeoutها، OAuth، TLS، و راهنمایی‌های فراخوانی موازی ابزار را بدون جایگزین کردن کل تعریف سرور به‌روزرسانی می‌کند.
• tools ‏filterهای ابزار هر سرور را به‌روزرسانی می‌کند. ورودی‌های include/exclude نام ابزارهای MCP و globهای ساده * هستند.
• login جریان OAuth را برای سرورهای HTTP پیکربندی‌شده با auth: "oauth" اجرا می‌کند. اجرای اول یک URL مجوز چاپ می‌کند؛ پس از تأیید، با --code دوباره اجرا کنید.
• logout اعتبارنامه‌های OAuth ذخیره‌شده را برای سرور نام‌گذاری‌شده پاک می‌کند، بدون اینکه تعریف ذخیره‌شده سرور را حذف کند.
• reload ‏runtimeهای MCP درون‌فرایندی کش‌شده را dispose می‌کند. فرایندهای Gateway یا عامل در فرایندی دیگر همچنان به مسیر reload یا restart خودشان نیاز دارند.
• برای سرورهای Streamable HTTP ‏MCP از transport: "streamable-http" استفاده کنید. openclaw mcp set همچنین برای سازگاری، type: "http" بومی CLI را به همان شکل پیکربندی canonical normalize می‌کند.
• اگر سرور نام‌گذاری‌شده وجود نداشته باشد، 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

از طریق HTTP Server-Sent Events به یک سرور MCP راه‌دور متصل می‌شود.

نمونه:

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

مقادیر حساس در url (userinfo) و headers در گزارش‌ها و خروجی وضعیت redact می‌شوند. openclaw mcp doctor وقتی ورودی‌های ظاهراً حساس در headers یا env شامل مقادیر لفظی باشند هشدار می‌دهد، تا اپراتورها بتوانند آن مقادیر را از پیکربندی commitشده بیرون ببرند.

گردش‌کار OAuth

OAuth برای سرورهای HTTP MCP است که جریان OAuth مربوط به MCP را اعلام می‌کنند. وقتی auth: "oauth" برای یک سرور فعال باشد، سرآیندهای ایستای Authorization برای آن سرور نادیده گرفته می‌شوند.

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

اگر ارائه‌دهنده توکن‌ها را rotate می‌کند یا وضعیت مجوز گیر می‌کند، openclaw mcp logout <name> را اجرا کنید و سپس login را تکرار کنید. logout می‌تواند اعتبارنامه‌های یک سرور HTTP ذخیره‌شده را حتی پس از حذف auth: "oauth" از پیکربندی پاک کند، تا وقتی که نام سرور و URL همچنان ورودی مخزن اعتبارنامه را شناسایی کنند.

انتقال HTTP قابل‌استریم

streamable-http یک گزینه انتقال اضافی در کنار sse و stdio است. از استریم HTTP برای ارتباط دوسویه با سرورهای MCP راه‌دور استفاده می‌کند.

پیکربندی OpenClaw از transport: "streamable-http" به‌عنوان املای canonical استفاده می‌کند. مقدارهای type: "http" مربوط به MCP بومی CLI وقتی از طریق 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 را نشان می‌دهد.

از این صفحه برای ویرایش‌های اپراتور و inventory سریع استفاده کنید. وقتی به اثبات زنده سرور نیاز دارید، از openclaw mcp doctor --probe یا openclaw mcp probe استفاده کنید.

گردش‌کار اپراتور:

1. رابط کاربری کنترل را باز کنید و MCP را انتخاب کنید.
2. کارت‌های خلاصه را برای سرورهای کل، فعال‌شده، OAuth، و پالایش‌شده بررسی کنید.
3. از ردیف هر سرور برای نکات انتقال، احراز هویت، پالایه، وقفه زمانی، و فرمان استفاده کنید.
4. وقتی می‌خواهید یک تعریف را نگه دارید اما آن را از کشف در زمان اجرا کنار بگذارید، فعال‌سازی را تغییر دهید.
5. بخش پیکربندی محدوده‌دار mcp را برای تغییرات ساختاری مانند سرورهای جدید، سرآیندها، TLS، فراداده OAuth، یا پالایه‌های ابزار ویرایش کنید.
6. ذخیره را برای ماندگار کردن فقط پیکربندی انتخاب کنید، یا ذخیره و انتشار را برای اعمال از مسیر پیکربندی Gateway انتخاب کنید.
7. وقتی به اثبات زنده نیاز دارید که سرور ویرایش‌شده شروع می‌شود و ابزارها را فهرست می‌کند، openclaw mcp doctor --probe را اجرا کنید.

یادداشت‌ها:

• قطعه‌های فرمان نام سرورها را داخل نقل‌قول می‌گذارند تا نام‌های غیرمعمول در shell همچنان قابل کپی باشند
• مقادیر شبیه URL نمایش‌داده‌شده، وقتی اعتبارنامه‌های جاسازی‌شده داشته باشند، پیش از رندر پنهان‌سازی می‌شوند
• این صفحه خودش انتقال‌های MCP را شروع نمی‌کند
• اجراهای فعال بسته به اینکه کدام فرایند مالک کلاینت‌های MCP است، ممکن است به openclaw mcp reload، انتشار پیکربندی Gateway، یا راه‌اندازی مجدد فرایند نیاز داشته باشند

محدودیت‌های فعلی

این صفحه پل را همان‌طور که امروز ارائه شده مستند می‌کند.

محدودیت‌های فعلی:

• کشف گفتگو به فراداده مسیر نشست موجود Gateway وابسته است
• هیچ پروتکل push عمومی فراتر از آداپتور اختصاصی Claude وجود ندارد
• هنوز ابزارهای ویرایش پیام یا واکنش وجود ندارند
• انتقال HTTP/SSE/streamable-http به یک سرور راه‌دور واحد وصل می‌شود؛ هنوز upstream چندگانه وجود ندارد
• permissions_list_open فقط تأییدهایی را شامل می‌شود که هنگام اتصال پل مشاهده شده‌اند

مرتبط

• مرجع CLI
• Pluginها