MCP

openclaw mcp دو وظیفه دارد:

• اجرای OpenClaw به‌عنوان سرور MCP با openclaw mcp serve
• مدیریت تعریف‌های سرورهای MCP خروجیِ متعلق به OpenClaw با list، show، set و unset

به بیان دیگر:

• serve یعنی OpenClaw به‌عنوان سرور MCP عمل می‌کند
• list / show / set / unset یعنی OpenClaw به‌عنوان رجیستری سمت کلاینت MCP برای سرورهای MCP دیگری عمل می‌کند که runtimeهای آن ممکن است بعدا مصرف کنند

از openclaw acp زمانی استفاده کنید که OpenClaw باید خودش یک نشست harness کدنویسی را میزبانی کند و آن runtime را از طریق ACP مسیریابی کند.

# OpenClaw به‌عنوان سرور MCP

این مسیر openclaw mcp serve است.

# چه زمانی از serve استفاده کنید

از openclaw mcp serve زمانی استفاده کنید که:

• Codex، Claude Code، یا کلاینت MCP دیگری باید مستقیما با گفت‌وگوهای کانالیِ پشتیبانی‌شده توسط OpenClaw صحبت کند
• از قبل یک OpenClaw Gateway محلی یا راه‌دور با نشست‌های مسیریابی‌شده دارید
• یک سرور MCP می‌خواهید که به‌جای اجرای bridgeهای جداگانه برای هر کانال، روی backendهای کانالی OpenClaw کار کند

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

# نحوه کار

openclaw mcp serve یک سرور MCP مبتنی بر stdio را شروع می‌کند. کلاینت MCP مالک آن فرایند است. تا زمانی که کلاینت نشست stdio را باز نگه می‌دارد، bridge از طریق WebSocket به یک OpenClaw Gateway محلی یا راه‌دور وصل می‌شود و گفت‌وگوهای کانالی مسیریابی‌شده را از طریق MCP ارائه می‌کند.

# انتخاب حالت کلاینت

از همان bridge به دو روش متفاوت استفاده کنید:

# آنچه serve ارائه می‌کند

bridge از metadata مسیر نشست موجود در Gateway استفاده می‌کند تا گفت‌وگوهای پشتیبانی‌شده توسط کانال را ارائه کند. یک گفت‌وگو زمانی ظاهر می‌شود که OpenClaw از قبل وضعیت نشستی با مسیر شناخته‌شده داشته باشد، مانند:

• channel
• metadata گیرنده یا مقصد
• accountId اختیاری
• threadId اختیاری

این به کلاینت‌های MCP یک محل واحد می‌دهد تا:

• گفت‌وگوهای مسیریابی‌شده اخیر را فهرست کنند
• تاریخچه transcript اخیر را بخوانند
• منتظر رویدادهای ورودی جدید بمانند
• از طریق همان مسیر پاسخ بفرستند
• درخواست‌های approval را که هنگام اتصال bridge می‌رسند ببینند

# استفاده

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 --verbose
openclaw mcp serve --claude-channel-mode off

# ابزارهای bridge

bridge فعلی این ابزارهای MCP را ارائه می‌کند:

# مدل رویداد

bridge تا زمانی که وصل است یک صف رویداد درون‌حافظه‌ای نگه می‌دارد.

انواع رویداد فعلی:

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

# اعلان‌های کانال Claude

bridge همچنین می‌تواند اعلان‌های کانال ویژه Claude را ارائه کند. این معادل OpenClaw برای adapter کانال Claude Code است: ابزارهای استاندارد MCP همچنان در دسترس می‌مانند، اما پیام‌های ورودی زنده همچنین می‌توانند به‌صورت اعلان‌های MCP ویژه Claude برسند.

وقتی حالت کانال Claude فعال باشد، سرور قابلیت‌های آزمایشی Claude را advertise می‌کند و می‌تواند این موارد را emit کند:

• notifications/claude/channel
• notifications/claude/channel/permission

رفتار فعلی bridge:

• پیام‌های transcript ورودی user به‌صورت notifications/claude/channel forward می‌شوند
• درخواست‌های permission مربوط به Claude که از طریق MCP دریافت می‌شوند، در حافظه track می‌شوند
• اگر گفت‌وگوی لینک‌شده بعدا yes abcde یا no abcde بفرستد، bridge آن را به notifications/claude/channel/permission تبدیل می‌کند
• این اعلان‌ها فقط برای نشست زنده هستند؛ اگر کلاینت MCP قطع شود، هدف push وجود ندارد

این رفتار عمدا ویژه کلاینت است. کلاینت‌های MCP عمومی باید به ابزارهای polling استاندارد تکیه کنند.

# پیکربندی کلاینت MCP

نمونه پیکربندی کلاینت stdio:

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url",
        "wss://gateway-host:18789",
        "--token-file",
        "/path/to/gateway.token"
      ]
    }
  }
}

برای بیشتر کلاینت‌های MCP عمومی، با سطح ابزار استاندارد شروع کنید و حالت Claude را نادیده بگیرید. حالت Claude را فقط برای کلاینت‌هایی روشن کنید که واقعا methodهای اعلان ویژه Claude را می‌فهمند.

# گزینه‌ها

openclaw mcp serve این موارد را پشتیبانی می‌کند:

# امنیت و مرز اعتماد

bridge مسیریابی اختراع نمی‌کند. فقط گفت‌وگوهایی را ارائه می‌کند که Gateway از قبل می‌داند چگونه مسیریابی کند.

یعنی:

• allowlistهای فرستنده، pairing و اعتماد در سطح کانال همچنان متعلق به پیکربندی کانال OpenClaw زیرین هستند
• messages_send فقط می‌تواند از طریق یک مسیر ذخیره‌شده موجود پاسخ دهد
• وضعیت approval فقط برای نشست فعلی bridge، زنده/درون‌حافظه‌ای است
• احراز هویت bridge باید از همان کنترل‌های token یا password مربوط به Gateway استفاده کند که برای هر کلاینت راه‌دور دیگر Gateway به آن اعتماد می‌کنید

اگر گفت‌وگویی در conversations_list نیست، علت معمول پیکربندی MCP نیست. علت، metadata مسیر ناقص یا موجود نبودن آن در نشست Gateway زیرین است.

# آزمون

OpenClaw برای این bridge یک smoke قطعی Docker ارائه می‌کند:

pnpm test:docker:mcp-channels

آن smoke:

• یک container seeded Gateway را شروع می‌کند
• container دومی را شروع می‌کند که openclaw mcp serve را spawn می‌کند
• کشف گفت‌وگو، خواندن transcript، خواندن metadata پیوست، رفتار صف رویداد زنده و مسیریابی ارسال خروجی را verify می‌کند
• اعلان‌های کانال و permission به سبک Claude را روی bridge واقعی stdio MCP اعتبارسنجی می‌کند

این سریع‌ترین راه برای اثبات کارکرد bridge بدون اتصال یک حساب واقعی Telegram، Discord یا iMessage به اجرای آزمون است.

برای زمینه گسترده‌تر آزمون، Testing را ببینید.

# عیب‌یابی

# OpenClaw به‌عنوان رجیستری کلاینت MCP

این مسیر openclaw mcp list، show، set و unset است.

این فرمان‌ها OpenClaw را از طریق MCP در معرض دسترسی قرار نمی‌دهند. آن‌ها تعاریف سرور MCP متعلق به OpenClaw را زیر mcp.servers در پیکربندی OpenClaw مدیریت می‌کنند.

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

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

# تعاریف ذخیره‌شده سرور MCP

OpenClaw همچنین یک registry سبک‌وزن سرور MCP را در پیکربندی برای سطح‌هایی ذخیره می‌کند که تعاریف MCP مدیریت‌شده توسط OpenClaw را می‌خواهند.

فرمان‌ها:

• openclaw mcp list
• openclaw mcp show [name]
• openclaw mcp set <name> <json>
• openclaw mcp unset <name>

نکته‌ها:

• list نام سرورها را مرتب می‌کند.
• show بدون نام، کل شیء پیکربندی‌شده سرور MCP را چاپ می‌کند.
• set یک مقدار شیء JSON را در خط فرمان انتظار دارد.
• برای سرورهای Streamable HTTP MCP از transport: "streamable-http" استفاده کنید. openclaw mcp set همچنین برای سازگاری، type: "http" بومی CLI را به همان شکل پیکربندی canonical عادی‌سازی می‌کند.
• 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 ارتباط برقرار می‌کند.

# انتقال SSE / HTTP

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

نمونه:

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

مقادیر حساس در url (userinfo) و headers در logها و خروجی وضعیت redacted می‌شوند.

# انتقال Streamable HTTP

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

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

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

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

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

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

# مرتبط

• مرجع CLI
• Pluginها