MCP

openclaw mcp memiliki dua tugas:

• menjalankan OpenClaw sebagai server MCP dengan openclaw mcp serve
• mengelola definisi server MCP outbound milik OpenClaw dengan list, show, set, dan unset

Dengan kata lain:

• serve adalah OpenClaw yang bertindak sebagai server MCP
• list / show / set / unset adalah OpenClaw yang bertindak sebagai registri sisi klien MCP untuk server MCP lain yang mungkin digunakan runtime-nya nanti

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

# 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 ke percakapan channel yang didukung OpenClaw
• Anda sudah memiliki OpenClaw Gateway lokal atau remote dengan sesi yang dirutekan
• Anda menginginkan satu server MCP yang bekerja di seluruh backend channel OpenClaw, alih-alih menjalankan bridge terpisah per channel

Gunakan openclaw acp sebagai gantinya saat OpenClaw harus menghosting runtime pengodean itu sendiri 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 tersambung ke OpenClaw Gateway lokal atau remote melalui WebSocket dan mengekspos percakapan channel yang dirutekan melalui MCP.

# Pilih mode klien

Gunakan bridge yang sama dengan dua cara berbeda:

# Yang diekspos serve

Bridge menggunakan metadata rute sesi Gateway yang sudah ada untuk mengekspos percakapan yang didukung channel. 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 inbound baru
• mengirim balasan kembali melalui rute yang sama
• melihat permintaan persetujuan yang masuk saat bridge tersambung

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

# Alat bridge

Bridge saat ini mengekspos alat MCP berikut:

# Model peristiwa

Bridge menyimpan antrean peristiwa dalam memori selama tersambung.

Jenis peristiwa saat ini:

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

# Notifikasi channel Claude

Bridge juga dapat mengekspos notifikasi channel khusus Claude. Ini adalah padanan OpenClaw dari adapter channel Claude Code: alat MCP standar tetap tersedia, tetapi pesan inbound live juga dapat masuk sebagai notifikasi MCP khusus Claude.

Saat mode channel Claude diaktifkan, server mengiklankan kapabilitas eksperimental Claude dan dapat memancarkan:

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

Perilaku bridge saat ini:

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

Ini sengaja khusus klien. Klien MCP generik sebaiknya 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. Bridge hanya mengekspos percakapan yang sudah diketahui Gateway cara merutekannya.

Artinya:

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

Jika suatu percakapan hilang dari conversations_list, penyebab biasanya bukan konfigurasi MCP. Penyebabnya adalah metadata rute yang hilang atau tidak lengkap dalam sesi Gateway yang mendasarinya.

# Pengujian

OpenClaw menyediakan smoke Docker deterministik untuk bridge ini:

pnpm test:docker:mcp-channels

Smoke tersebut:

• memulai kontainer Gateway dengan seed
• memulai kontainer kedua yang memunculkan openclaw mcp serve
• memverifikasi penemuan percakapan, pembacaan transkrip, pembacaan metadata lampiran, perilaku antrean peristiwa live, dan perutean pengiriman outbound
• 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 run pengujian.

Untuk konteks pengujian yang lebih luas, lihat Pengujian.

# Pemecahan masalah

# OpenClaw sebagai registri klien MCP

Ini adalah path openclaw mcp list, show, set, dan unset.

Perintah-perintah ini tidak mengekspos OpenClaw melalui MCP. Perintah ini mengelola definisi server MCP milik OpenClaw di bawah mcp.servers dalam konfigurasi OpenClaw.

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

Adaptor runtime dapat menormalkan registri bersama ini ke bentuk yang diharapkan klien hilirnya. Misalnya, Pi tertanam menggunakan nilai transport OpenClaw secara langsung, sementara Claude Code dan Gemini menerima nilai type asli CLI seperti http, sse, atau stdio.

# Definisi server MCP tersimpan

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

Perintah:

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

Catatan:

• list mengurutkan nama server.
• show tanpa nama mencetak objek server MCP yang dikonfigurasi secara lengkap.
• set mengharapkan satu nilai objek JSON pada baris perintah.
• Gunakan transport: "streamable-http" untuk server MCP Streamable HTTP. openclaw mcp set juga menormalkan type: "http" asli CLI ke bentuk konfigurasi kanonis yang sama untuk kompatibilitas.
• unset gagal jika server bernama tersebut tidak ada.

Contoh:

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

Contoh bentuk konfigurasi:

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com",
        "transport": "streamable-http"
      }
    }
  }
}

# Transport stdio

Meluncurkan proses turunan 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",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

Nilai sensitif dalam url (userinfo) dan headers disunting dalam log dan output status.

# Transport Streamable HTTP

streamable-http adalah opsi transport tambahan bersama sse dan stdio. Ini menggunakan streaming HTTP untuk komunikasi dua arah dengan server MCP jarak jauh.

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

Contoh:

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

# Batasan saat ini

Halaman ini mendokumentasikan bridge sebagaimana dikirimkan saat ini.

Batasan saat ini:

• penemuan percakapan bergantung pada metadata rute sesi Gateway yang ada
• belum ada protokol push generik selain adaptor 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