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 має самостійно розміщувати сеанс кодового harness і маршрутизувати це середовище виконання через 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-сеанс відкритим, міст підключається до локального або віддаленого OpenClaw Gateway через 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 сповіщення каналу. Це еквівалент адаптера каналу Claude Code в OpenClaw: стандартні MCP-інструменти залишаються доступними, але живі вхідні повідомлення також можуть надходити як специфічні для Claude MCP-сповіщення.

Коли режим каналу Claude увімкнено, сервер оголошує експериментальні можливості Claude і може надсилати:

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

Поточна поведінка моста:

• вхідні повідомлення стенограми user пересилаються як notifications/claude/channel
• запити дозволів Claude, отримані через MCP, відстежуються в пам'яті
• якщо власник команди у пов'язаній розмові пізніше надсилає yes abcde або no abcde, міст перетворює це на notifications/claude/channel/permission
• ці сповіщення доступні лише для живого сеансу; якщо MCP-клієнт відключається, push-цілі немає

Це навмисно специфічно для клієнта. Загальні 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

Цей smoke:

• запускає контейнер Gateway із початковими даними
• запускає другий контейнер, який створює openclaw mcp serve
• перевіряє виявлення розмов, читання транскриптів, читання метаданих вкладень, поведінку черги live-подій і маршрутизацію вихідного надсилання
• перевіряє сповіщення каналів і дозволів у стилі 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 споживає значення OpenClaw transport напряму, тоді як Claude Code і Gemini отримують CLI-native значення type, як-от http, sse або stdio.

Codex app-server також враховує необов’язковий блок codex на кожному сервері. Це проєкційні метадані OpenClaw лише для потоків Codex app-server; вони не змінюють ACP-сеанси, загальну конфігурацію Codex harness або інші адаптери середовища виконання. Використовуйте непорожній codex.agents, щоб проєктувати сервер лише в конкретні ідентифікатори агентів OpenClaw. Порожні, blank або недійсні списки агентів відхиляються валідацією конфігурації та пропускаються шляхом проєкції середовища виконання замість того, щоб ставати глобальними. Використовуйте codex.defaultToolsApprovalMode (auto, prompt або approve), щоб видавати нативний для Codex default_tools_approval_mode для довіреного сервера. 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 підключається та звітує про кількість інструментів, підтримку ресурсів/prompts, підтримку змін списку та діагностику.
• add приймає stdio-прапорці, як-от --command, --arg, --env і --cwd, або HTTP-прапорці, як-от --url, --transport, --header, --auth oauth, TLS, час очікування та прапорці вибору інструментів.
• set очікує одне значення JSON-об’єкта в командному рядку.
• configure оновлює ввімкнення, фільтри інструментів, часи очікування, OAuth, TLS і підказки паралельних викликів інструментів без заміни всього визначення сервера.
• tools оновлює фільтри інструментів для кожного сервера. Записи включення/виключення — це назви MCP-інструментів і прості * globs.
• login запускає потік OAuth для HTTP-серверів, налаштованих із auth: "oauth". Перший запуск друкує URL авторизації; повторно запустіть із --code після затвердження.
• logout очищає збережені облікові дані OAuth для названого сервера, не видаляючи збережене визначення сервера.
• reload утилізує кешовані MCP-середовища виконання в поточному процесі. Gateway або агентські процеси в іншому процесі все ще потребують власного шляху перезавантаження або перезапуску.
• Використовуйте transport: "streamable-http" для Streamable HTTP MCP-серверів. openclaw mcp set також нормалізує CLI-native type: "http" до тієї самої канонічної форми конфігурації для сумісності.
• 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 призначений для HTTP MCP-серверів, які оголошують потік 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" як канонічне написання. CLI-нативні значення MCP 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>"        }      }    }  }}

Control UI

Браузерний Control UI містить окрему сторінку налаштувань MCP за адресою /mcp. Вона показує кількість налаштованих серверів, зведення про ввімкнення/OAuth/фільтри, рядки транспорту для кожного сервера, елементи керування ввімкненням/вимкненням, поширені CLI-команди та редактор з областю дії для розділу конфігурації mcp.

Використовуйте сторінку для операторських редагувань і швидкої інвентаризації. Використовуйте openclaw mcp doctor --probe або openclaw mcp probe, коли потрібне живе підтвердження сервера.

Робочий процес оператора:

1. Відкрийте Control UI і виберіть MCP.
2. Перегляньте підсумкові картки для загальної кількості, увімкнених, OAuth і відфільтрованих серверів.
3. Використовуйте кожен рядок сервера для підказок щодо транспорту, автентифікації, фільтра, часу очікування та команди.
4. Перемикайте ввімкнення, коли потрібно зберегти визначення, але виключити його з виявлення під час виконання.
5. Редагуйте секцію конфігурації mcp у межах області для структурних змін, як-от нові сервери, заголовки, TLS, метадані OAuth або фільтри інструментів.
6. Виберіть Зберегти, щоб лише зберегти конфігурацію, або Зберегти й опублікувати, щоб застосувати її через шлях конфігурації Gateway.
7. Запустіть openclaw mcp doctor --probe, коли потрібен живий доказ, що відредагований сервер запускається та перелічує інструменти.

Примітки:

• фрагменти команд беруть назви серверів у лапки, щоб незвичні назви залишалися придатними для копіювання в shell
• відображені URL-подібні значення редагуються перед рендерингом, якщо містять вбудовані облікові дані
• сторінка сама не запускає транспорти MCP
• активним середовищам виконання може знадобитися openclaw mcp reload, публікація конфігурації Gateway або перезапуск процесу залежно від того, який процес володіє клієнтами MCP

Поточні обмеження

Ця сторінка документує міст у тому вигляді, у якому він постачається сьогодні.

Поточні обмеження:

• виявлення розмов залежить від наявних метаданих маршруту сеансу Gateway
• немає універсального push-протоколу поза адаптером, специфічним для Claude
• інструментів для редагування повідомлень або реакцій поки немає
• транспорт HTTP/SSE/streamable-http підключається до одного віддаленого сервера; мультиплексованого upstream поки немає
• permissions_list_open містить лише схвалення, зафіксовані, поки міст підключений

Пов’язане

• Довідка CLI
• Plugins