MCP

openclaw mcp memiliki dua tugas:

• menjalankan OpenClaw sebagai server MCP dengan openclaw mcp serve
• mengelola definisi server MCP keluar yang dikelola OpenClaw dengan list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload, dan unset

Dengan kata lain:

• serve adalah OpenClaw yang bertindak sebagai server MCP
• subperintah lainnya adalah OpenClaw yang bertindak sebagai registri sisi klien MCP untuk server MCP yang mungkin dikonsumsi runtime-nya nanti

Gunakan openclaw acp saat OpenClaw harus menghosting sendiri sesi harness coding dan merutekan runtime tersebut melalui ACP.

Pilih jalur MCP yang tepat

OpenClaw memiliki beberapa permukaan MCP. Pilih yang sesuai dengan siapa pemilik runtime agen dan siapa pemilik alat.

OpenClaw sebagai server MCP

Ini adalah jalur openclaw mcp serve.

Kapan menggunakan serve

Gunakan openclaw mcp serve saat:

• Codex, Claude Code, atau klien MCP lain harus berbicara langsung dengan percakapan kanal yang didukung OpenClaw
• Anda sudah memiliki Gateway OpenClaw lokal atau jarak jauh dengan sesi yang dirutekan
• Anda menginginkan satu server MCP yang bekerja di seluruh backend kanal OpenClaw alih-alih menjalankan bridge terpisah per kanal

Gunakan openclaw acp sebagai gantinya saat OpenClaw harus menghosting sendiri runtime coding dan menjaga sesi agen tetap di dalam OpenClaw.

Cara kerjanya

openclaw mcp serve memulai server MCP stdio. Klien MCP memiliki proses tersebut. Selama klien menjaga sesi stdio tetap terbuka, bridge terhubung ke Gateway OpenClaw lokal atau jarak jauh melalui WebSocket dan mengekspos percakapan kanal yang dirutekan melalui MCP.

Pilih mode klien

Gunakan bridge yang sama dengan dua cara berbeda:

Apa yang diekspos serve

Bridge menggunakan metadata rute sesi Gateway yang ada untuk mengekspos percakapan berbasis kanal. Percakapan muncul saat OpenClaw sudah memiliki status sesi dengan rute yang diketahui seperti:

• channel
• metadata penerima atau tujuan
• accountId opsional
• threadId opsional

Ini memberi klien MCP satu tempat untuk:

• mencantumkan percakapan terbaru yang dirutekan
• membaca riwayat transkrip terbaru
• menunggu peristiwa masuk baru
• mengirim balasan kembali melalui rute yang sama
• melihat permintaan persetujuan yang tiba saat bridge terhubung

Penggunaan

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

Alat bridge

Bridge saat ini mengekspos alat MCP berikut:

Model peristiwa

Bridge mempertahankan antrean peristiwa dalam memori selama terhubung.

Jenis peristiwa saat ini:

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

Notifikasi kanal Claude

Bridge juga dapat mengekspos notifikasi kanal khusus Claude. Ini adalah padanan OpenClaw dari adaptor kanal Claude Code: alat MCP standar tetap tersedia, tetapi pesan masuk langsung juga dapat tiba sebagai notifikasi MCP khusus Claude.

Saat mode kanal Claude diaktifkan, server mengiklankan kapabilitas eksperimental Claude dan dapat mengeluarkan:

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

Perilaku bridge saat ini:

• pesan transkrip user masuk diteruskan sebagai notifications/claude/channel
• permintaan izin Claude yang diterima melalui MCP dilacak dalam memori
• jika pemilik perintah dalam percakapan tertaut kemudian mengirim yes abcde atau no abcde, bridge mengonversinya menjadi notifications/claude/channel/permission
• notifikasi ini hanya untuk sesi langsung; jika klien MCP terputus, tidak ada target push

Ini sengaja khusus klien. Klien MCP generik harus mengandalkan alat polling standar.

Konfigurasi klien MCP

Contoh konfigurasi klien stdio:

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

Untuk sebagian besar klien MCP generik, mulai dengan permukaan alat standar dan abaikan mode Claude. Aktifkan mode Claude hanya untuk klien yang benar-benar memahami metode notifikasi khusus Claude.

Opsi

openclaw mcp serve mendukung:

Keamanan dan batas kepercayaan

Bridge tidak menciptakan perutean. Ia hanya mengekspos percakapan yang sudah diketahui cara peruteannya oleh Gateway.

Artinya:

• allowlist pengirim, pairing, dan kepercayaan tingkat channel tetap menjadi bagian dari konfigurasi channel OpenClaw yang mendasarinya
• messages_send hanya dapat membalas melalui route tersimpan yang sudah ada
• status persetujuan hanya live/di memori untuk sesi bridge saat ini
• auth bridge harus menggunakan kontrol token atau kata sandi Gateway yang sama dengan yang Anda percayai untuk klien Gateway jarak jauh lainnya

Jika percakapan tidak ada di conversations_list, penyebab biasanya bukan konfigurasi MCP. Penyebabnya adalah metadata route yang hilang atau tidak lengkap dalam sesi Gateway yang mendasarinya.

Pengujian

OpenClaw menyertakan smoke Docker deterministik untuk bridge ini:

pnpm test:docker:mcp-channels

Smoke tersebut:

• memulai kontainer Gateway dengan seed
• memulai kontainer kedua yang menjalankan openclaw mcp serve
• memverifikasi penemuan percakapan, pembacaan transkrip, pembacaan metadata lampiran, perilaku antrean event live, dan perutean pengiriman keluar
• memvalidasi notifikasi channel dan izin bergaya Claude melalui bridge MCP stdio nyata

Ini adalah cara tercepat untuk membuktikan bridge berfungsi tanpa menghubungkan akun Telegram, Discord, atau iMessage nyata ke dalam proses uji.

Untuk konteks pengujian yang lebih luas, lihat Pengujian.

Pemecahan masalah

OpenClaw sebagai registri klien MCP

Ini adalah jalur openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload, dan unset.

Perintah-perintah ini tidak mengekspos OpenClaw melalui MCP. Perintah ini mengelola definisi server MCP yang dikelola OpenClaw di bawah mcp.servers dalam konfigurasi OpenClaw. Perintah ini tidak membaca server mcporter dari config/mcporter.json.

Definisi yang disimpan tersebut ditujukan untuk runtime yang diluncurkan atau dikonfigurasi OpenClaw nanti, seperti OpenClaw tertanam dan adaptor runtime lainnya. OpenClaw menyimpan definisi secara terpusat sehingga runtime tersebut tidak perlu menyimpan daftar server MCP duplikat miliknya sendiri.

Adaptor runtime dapat menormalisasi registri bersama ini ke bentuk yang diharapkan klien downstream mereka. Misalnya, OpenClaw tertanam mengonsumsi nilai transport OpenClaw secara langsung, sedangkan Claude Code dan Gemini menerima nilai type native CLI seperti http, sse, atau stdio.

Codex app-server juga menghormati blok codex opsional pada setiap server. Ini adalah metadata proyeksi OpenClaw khusus untuk thread Codex app-server; ini tidak mengubah sesi ACP, konfigurasi harness Codex generik, atau adaptor runtime lain. Gunakan codex.agents yang tidak kosong untuk memproyeksikan server hanya ke id agen OpenClaw tertentu. Daftar agen yang kosong, blank, atau tidak valid ditolak oleh validasi konfigurasi dan dihilangkan oleh jalur proyeksi runtime alih-alih menjadi global. Gunakan codex.defaultToolsApprovalMode (auto, prompt, atau approve) untuk memancarkan default_tools_approval_mode native Codex bagi server tepercaya. OpenClaw menghapus metadata codex sebelum menyerahkan konfigurasi mcp_servers native ke Codex.

Definisi server MCP tersimpan

OpenClaw juga menyimpan registri server MCP ringan dalam konfigurasi untuk surface yang menginginkan definisi MCP yang dikelola OpenClaw.

Perintah:

• 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>

Catatan:

• list mengurutkan nama server.
• show tanpa nama mencetak objek server MCP lengkap yang dikonfigurasi.
• status mengklasifikasikan transport yang dikonfigurasi tanpa terhubung. --verbose menyertakan detail launch, timeout, OAuth, filter, dan panggilan paralel yang telah di-resolve.
• doctor melakukan pemeriksaan statis tanpa terhubung. Tambahkan --probe ketika perintah juga harus memverifikasi bahwa server yang diaktifkan dapat terhubung.
• probe terhubung dan melaporkan jumlah tool, dukungan resource/prompt, dukungan perubahan daftar, dan diagnostik.
• add menerima flag stdio seperti --command, --arg, --env, dan --cwd, atau flag HTTP seperti --url, --transport, --header, --auth oauth, TLS, timeout, dan flag pemilihan tool.
• set mengharapkan satu nilai objek JSON pada baris perintah.
• configure memperbarui pengaktifan, filter tool, timeout, OAuth, TLS, dan petunjuk panggilan tool paralel tanpa mengganti seluruh definisi server.
• tools memperbarui filter tool per server. Entri include/exclude adalah nama tool MCP dan glob * sederhana.
• login menjalankan alur OAuth untuk server HTTP yang dikonfigurasi dengan auth: "oauth". Run pertama mencetak URL otorisasi; jalankan ulang dengan --code setelah persetujuan.
• logout menghapus kredensial OAuth tersimpan untuk server bernama tanpa menghapus definisi server yang tersimpan.
• reload membuang runtime MCP dalam proses yang di-cache. Proses Gateway atau agen di proses lain tetap memerlukan jalur reload atau restart mereka sendiri.
• Gunakan transport: "streamable-http" untuk server MCP Streamable HTTP. openclaw mcp set juga menormalkan type: "http" native CLI ke bentuk konfigurasi kanonis yang sama untuk kompatibilitas.
• unset gagal jika server bernama tidak ada.

Contoh:

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

Resep server umum

Contoh-contoh ini hanya menyimpan definisi server. Jalankan openclaw mcp doctor --probe setelahnya untuk membuktikan bahwa server mulai dan mengekspos tool.

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

Bentuk keluaran JSON

Gunakan --json untuk skrip dan dasbor. Kumpulan bidang dapat bertambah seiring waktu, jadi konsumen harus mengabaikan kunci yang tidak dikenal.

{  "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": []}

Contoh bentuk konfigurasi:

{  "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_*"]        }      }    }  }}

Transport Stdio

Meluncurkan proses anak lokal dan berkomunikasi melalui stdin/stdout.

Transport SSE / HTTP

Terhubung ke server MCP jarak jauh melalui HTTP Server-Sent Events.

Contoh:

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

Nilai sensitif dalam url (userinfo) dan headers disunting dalam log dan keluaran status. openclaw mcp doctor memperingatkan saat entri headers atau env yang tampak sensitif berisi nilai literal, sehingga operator dapat memindahkan nilai tersebut keluar dari konfigurasi yang dikomit.

Alur kerja OAuth

OAuth ditujukan untuk server MCP HTTP yang mengiklankan alur OAuth MCP. Header Authorization statis diabaikan untuk server saat auth: "oauth" diaktifkan.

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

Jika penyedia merotasi token atau status otorisasi macet, jalankan openclaw mcp logout <name>, lalu ulangi login. logout dapat menghapus kredensial untuk server HTTP yang disimpan bahkan setelah auth: "oauth" dihapus dari konfigurasi, selama nama server dan URL masih mengidentifikasi entri penyimpanan kredensial.

Transport HTTP streamable

streamable-http adalah opsi transport tambahan di samping sse dan stdio. Opsi ini menggunakan streaming HTTP untuk komunikasi dua arah dengan server MCP jarak jauh.

Konfigurasi OpenClaw menggunakan transport: "streamable-http" sebagai ejaan kanonis. Nilai MCP native CLI type: "http" diterima saat disimpan melalui openclaw mcp set dan diperbaiki oleh openclaw doctor --fix dalam konfigurasi yang ada, tetapi transport adalah yang dikonsumsi langsung oleh OpenClaw tertanam.

Contoh:

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

UI Kontrol

UI Kontrol browser menyertakan halaman pengaturan MCP khusus di /mcp. Halaman ini menampilkan jumlah server yang dikonfigurasi, ringkasan aktif/OAuth/filter, baris transport per server, kontrol aktif/nonaktif, perintah CLI umum, dan editor terbatas untuk bagian konfigurasi mcp.

Gunakan halaman ini untuk edit operator dan inventaris cepat. Gunakan openclaw mcp doctor --probe atau openclaw mcp probe saat Anda memerlukan bukti server langsung.

Alur kerja operator:

1. Buka UI Kontrol dan pilih MCP.
2. Tinjau kartu ringkasan untuk total server, server yang diaktifkan, OAuth, dan server yang difilter.
3. Gunakan setiap baris server untuk petunjuk transport, autentikasi, filter, timeout, dan perintah.
4. Alihkan pengaktifan saat Anda ingin mempertahankan definisi tetapi mengecualikannya dari penemuan runtime.
5. Edit bagian konfigurasi mcp tercakup untuk perubahan struktural seperti server baru, header, TLS, metadata OAuth, atau filter alat.
6. Pilih Simpan untuk hanya menyimpan konfigurasi, atau Simpan & Publikasikan untuk menerapkannya melalui jalur konfigurasi Gateway.
7. Jalankan openclaw mcp doctor --probe saat Anda memerlukan bukti langsung bahwa server yang diedit mulai berjalan dan mencantumkan alat.

Catatan:

• cuplikan perintah mengapit nama server dengan tanda kutip agar nama yang tidak biasa tetap dapat disalin ke shell
• nilai mirip URL yang ditampilkan disunting sebelum dirender saat berisi kredensial tertanam
• halaman ini tidak memulai transport MCP dengan sendirinya
• runtime aktif mungkin memerlukan openclaw mcp reload, publikasi konfigurasi Gateway, atau mulai ulang proses, bergantung pada proses mana yang memiliki klien MCP

Batas saat ini

Halaman ini mendokumentasikan bridge sebagaimana dikirimkan saat ini.

Batas saat ini:

• penemuan percakapan bergantung pada metadata rute sesi Gateway yang sudah ada
• belum ada protokol push generik selain adapter khusus Claude
• belum ada alat edit pesan atau reaksi
• transport HTTP/SSE/streamable-http terhubung ke satu server jarak jauh; belum ada upstream multipleks
• permissions_list_open hanya mencakup persetujuan yang diamati saat bridge terhubung

Terkait

• Referensi CLI
• Plugin