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 для серверів, які згодом можуть використовувати його власні середовища виконання.

Використовуйте openclaw acp, коли OpenClaw має самостійно розміщувати сеанс середовища програмування та спрямовувати це середовище виконання через ACP.

Вибір правильного шляху 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 запускає сервер MCP через stdio. Цей процес належить клієнту 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

Інструменти мосту

Модель подій

Поки міст підключений, він зберігає чергу подій у пам’яті.

Поточні типи подій:

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

Сповіщення каналу Claude

Міст також може надавати сповіщення каналу, специфічні для Claude. Це еквівалент адаптера каналу Claude Code в OpenClaw: стандартні інструменти MCP залишаються доступними, але вхідні повідомлення наживо також можуть надходити як сповіщення MCP, специфічні для Claude.

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

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

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

• вхідні повідомлення стенограми user пересилаються як notifications/claude/channel
• запити Claude на дозвіл, отримані через MCP, відстежуються в пам’яті
• якщо власник команди в пов’язаній розмові згодом надсилає yes <id> або no <id> (<id> — це 5-літерний ідентифікатор запиту без l), міст перетворює це на 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-смоук-тестом для цього мосту:

pnpm test:docker:mcp-channels

Цей смоук-тест запускає один контейнер: він заповнює стан розмови, запускає Gateway, потім породжує openclaw mcp serve як дочірній процес stdio та керує ним як клієнтом MCP. Він перевіряє виявлення розмов, читання розшифровок, читання метаданих вкладень, поведінку черги подій наживо, а також сповіщення про канали й дозволи у стилі Claude через справжній міст MCP stdio. Маршрутизація вихідного надсилання (messages_send із повторним використанням збереженого маршруту розмови) окремо покривається модульними тестами в src/mcp/channel-server.test.ts.

Це найшвидший спосіб довести працездатність мосту без підключення справжнього облікового запису 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 значення type, як-от http, sse або stdio.

Codex app-server також враховує необов’язковий блок codex на кожному сервері. Це метадані проєкції OpenClaw лише для гілок Codex app-server; вони не змінюють сеанси ACP, конфігурацію універсального середовища Codex або інші адаптери середовищ виконання. Використовуйте непорожній codex.agents, щоб проєктувати сервер лише в певні ідентифікатори агентів OpenClaw. Порожні, незаповнені або недійсні списки агентів відхиляються під час перевірки конфігурації та пропускаються шляхом проєкції середовища виконання замість того, щоб ставати глобальними. Використовуйте codex.defaultToolsApprovalMode (auto, prompt або approve), щоб створити нативний default_tools_approval_mode Codex для довіреного сервера. OpenClaw вилучає метадані codex, перш ніж передати нативну конфігурацію mcp_servers до Codex.

Збережені визначення серверів MCP

Команди:

• 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 підключається та повідомляє кількість інструментів, підтримку ресурсів/запитів, підтримку зміни списку й діагностику.
• add приймає прапорці stdio, як-от --command, --arg, --env та --cwd, або прапорці HTTP, як-от --url, --transport, --header, --auth oauth, а також прапорці TLS, часу очікування й вибору інструментів.
• set очікує одне значення об’єкта JSON у командному рядку.
• configure оновлює стан увімкнення, фільтри інструментів, часи очікування, OAuth, TLS і підказки щодо паралельних викликів інструментів без заміни всього визначення сервера. Додайте --probe, щоб перевірити оновлений сервер перед збереженням.
• tools оновлює фільтри інструментів для кожного сервера. Записи включення/виключення — це назви інструментів MCP і прості шаблони *.
• login запускає потік OAuth для HTTP-серверів, налаштованих із auth: "oauth". Перший запуск виводить URL-адресу авторизації; після схвалення запустіть повторно з --code.
• logout очищає збережені облікові дані OAuth для вказаного сервера, не видаляючи збережене визначення сервера.
• reload звільняє кешовані внутрішньопроцесні середовища виконання MCP лише для поточного процесу CLI. Процеси Gateway або агента в іншому процесі все одно потребують власного способу перезавантаження чи перезапуску.
• Використовуйте transport: "streamable-http" для серверів MCP Streamable HTTP. openclaw mcp set також нормалізує нативний для CLI 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": true,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": true,      "issues": [        {          "level": "warning",          "message": "Облікові дані OAuth не авторизовано; запустіть openclaw mcp login docs"        }      ]    }  ]}

{  "generatedAt": "2026-05-31T09:00:00.000Z",  "servers": {    "docs": {      "launch": "streamable-http https://mcp.example.com/mcp",      "tools": 2,      "resources": true,      "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 (відомостях про користувача) і headers приховуються в журналах і виводі стану. openclaw mcp doctor попереджає, коли схожі на конфіденційні записи headers або env містять буквальні значення, щоб оператори могли винести їх із конфігурації, доданої до комітів.

Робочий процес OAuth

OAuth призначено для MCP-серверів HTTP, які оголошують підтримку потоку MCP OAuth. Статичні заголовки Authorization ігноруються для сервера, коли ввімкнено auth: "oauth". Облікові дані, збережені командою openclaw mcp login, працюють із вбудованим MCP, засобами запуску CLI та локальним сервером застосунку Codex.

Доки облікові дані недоступні, OpenClaw вилучає з середовища виконання агента лише цей MCP-сервер, а не завершує хід агента з помилкою. Після цього оператор або агент із доступом до оболонки може запустити openclaw mcp login <name> і скористатися сервером у наступному ході.

Якщо віддалена служба MCP уже використовує окремий профіль автентифікації OpenClaw із можливістю оновлення, можна додатково встановити oauth.authProfileId. OpenClaw оновлює будь-яке із джерел облікових даних перед проєкцією середовища виконання та передає нижчому клієнту MCP лише поточний токен доступу.

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}'

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-адреса сервера все ще дають змогу ідентифікувати запис у сховищі облікових даних.

Потоковий транспорт HTTP

streamable-http — це додатковий варіант транспорту поряд із sse та stdio. Він використовує потокове передавання HTTP для двостороннього обміну даними з віддаленими серверами MCP.

У конфігурації OpenClaw канонічним написанням є transport: "streamable-http". Значення type: "http", властиві MCP у CLI, приймаються під час збереження через openclaw mcp set і виправляються командою openclaw doctor --fix в наявній конфігурації, але вбудований OpenClaw безпосередньо використовує transport.

Приклад:

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

Інтерфейс керування

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

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

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

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

Примітки:

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

Застосунки MCP

OpenClaw може відтворювати інструменти, які реалізують стабільне розширення MCP Apps. Застосунки потрібно вмикати окремо, оскільки їхній HTML надходить із налаштованого сервера MCP і може запитувати видимі застосунку інструменти або ресурси з того самого сервера.

Увімкніть міст хоста:

openclaw config set mcp.apps.enabled true --strict-json

Перезапустіть Gateway після зміни цього параметра. Коли його ввімкнено, OpenClaw запускає призначений лише для пісочниці слухач HTTP(S) на порту Gateway плюс один (для типового Gateway — 18790). Інтерфейс керування завантажує застосунки з цього окремого джерела; слухач ніколи не обслуговує інтерфейс керування, автентифіковані маршрути Gateway або дані користувачів.

Для прямих підключень до Gateway потрібен доступ до обох портів. Якщо зворотний проксі-сервер або термінатор TLS відкриває доступ до інтерфейсу керування, надайте застосункам окреме загальнодоступне джерело та проксіюйте лише його до слухача пісочниці:

{  mcp: {    apps: {      enabled: true,      sandboxOrigin: "https://mcp-apps.example.com",      sandboxPort: 18790,    },  },}

Джерело пісочниці має відрізнятися від джерела інтерфейсу керування. Не розміщуйте в ньому інший автентифікований або конфіденційний вміст.

Наприклад, офіційну базову демонстрацію React можна налаштувати так:

{  mcp: {    apps: { enabled: true },    servers: {      "basic-react": {        command: "npx",        args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"],      },    },  },}

Поведінка та межі безпеки:

• OpenClaw оголошує розширення io.modelcontextprotocol/ui лише тоді, коли застосунки ввімкнено.
• Відтворюються лише ресурси ui:// із точним MIME-типом text/html;profile=mcp-app.
• Розмір ресурсів інтерфейсу обмежено 2 MiB; вони розміщуються за проксі-сервером із подвійним iframe у спеціальному зовнішньому джерелі, завантажуються в непрозоре внутрішнє джерело застосунку й обмежуються політикою CSP, сформованою з метаданих ресурсу.
• Інструменти лише для застосунків (_meta.ui.visibility: ["app"]) не потрапляють до списків інструментів моделі. Застосунки можуть викликати лише видимі застосунку інструменти на своєму сервері-власнику, які також відповідають чинній політиці інструментів OpenClaw для запуску, що створив подання.
• Прив’язані до джерела дозволи застосунку, як-от доступ до камери, мікрофона та геолокації, не надаються, поки внутрішні документи застосунку використовують непрозорі джерела для ізоляції між застосунками.
• HTML застосунку, повні аргументи інструментів і необроблені результати зберігаються в обмеженій десятхвилинній оренді подання в пам’яті та не записуються на диск і не копіюються до метаданих попереднього перегляду розшифрування. У розшифруванні зберігається лише обмежений дескриптор сервера, інструмента й ресурсу, пов’язаний з ідентифікатором початкового виклику інструмента. Після перезапуску Gateway інтерфейс керування може перевірити цей дескриптор за розшифруванням автентифікованого сеансу та повторно отримати ресурс ui://; відновлені подання доступні лише для читання, доки новий запуск не встановить поточні дозволи інструментів.
• openclaw security audit попереджає, поки міст увімкнено. Вимкніть його за допомогою openclaw config set mcp.apps.enabled false --strict-json, коли він не потрібен.

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

На цій сторінці описано міст у його поточному випущеному стані.

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

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

Пов’язані матеріали

• Довідник CLI
• Плагіни