--- read_when: - Підключення Codex, Claude Code або іншого MCP-клієнта до каналів на базі OpenClaw - Запуск `openclaw mcp serve` - Керування визначеннями серверів MCP, збереженими в OpenClaw sidebarTitle: MCP summary: Надавайте доступ до розмов у каналах OpenClaw через MCP і керуйте збереженими визначеннями серверів MCP title: MCP x-i18n: generated_at: "2026-05-02T13:34:06Z" model: gpt-5.5 provider: openai source_hash: d1d3b5d7c3a9075c020a35bc9617d6e6902c96b40cc03e76119d01d0d94fd014 source_path: cli/mcp.md workflow: 16 --- `openclaw mcp` має два завдання: - запускати OpenClaw як MCP-сервер за допомогою `openclaw mcp serve` - керувати вихідними визначеннями MCP-серверів, що належать OpenClaw, за допомогою `list`, `show`, `set` і `unset` Інакше кажучи: - `serve` — це OpenClaw, що діє як MCP-сервер - `list` / `show` / `set` / `unset` — це OpenClaw, що діє як клієнтський реєстр MCP для інших MCP-серверів, які його середовища виконання можуть споживати пізніше Використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має самостійно розмістити сеанс кодового середовища й маршрутизувати це середовище виконання через ACP. ## OpenClaw як MCP-сервер Це шлях `openclaw mcp serve`. ### Коли використовувати `serve` Використовуйте `openclaw mcp serve`, коли: - Codex, Claude Code або інший MCP-клієнт має напряму взаємодіяти з розмовами каналів, підтриманими OpenClaw - у вас уже є локальний або віддалений OpenClaw Gateway із маршрутизованими сеансами - вам потрібен один MCP-сервер, що працює з різними каналовими бекендами OpenClaw, замість запуску окремих мостів для кожного каналу Натомість використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам розмістити кодове середовище виконання й утримувати сеанс агента всередині OpenClaw. ### Як це працює `openclaw mcp serve` запускає stdio MCP-сервер. MCP-клієнт володіє цим процесом. Поки клієнт тримає stdio-сеанс відкритим, міст підключається до локального або віддаленого OpenClaw Gateway через WebSocket і надає маршрутизовані розмови каналів через MCP. MCP-клієнт породжує `openclaw mcp serve`. Міст підключається до OpenClaw Gateway через WebSocket. Маршрутизовані сеанси стають MCP-розмовами та інструментами стенограми/історії. Живі події ставляться в чергу в пам’яті, поки міст підключений. Якщо ввімкнено режим каналу Claude, той самий сеанс також може отримувати специфічні для Claude push-сповіщення. - стан живої черги починається, коли міст підключається - старіша історія стенограми читається через `messages_read` - push-сповіщення Claude існують лише поки MCP-сеанс активний - коли клієнт відключається, міст завершує роботу, а жива черга зникає - одноразові точки входу агента, як-от `openclaw agent` і `openclaw infer model run`, завершують будь-які вбудовані MCP-середовища виконання, які вони відкривають, після завершення відповіді, тому повторні скриптові запуски не накопичують дочірні stdio MCP-процеси - stdio MCP-сервери, запущені OpenClaw (вбудовані або налаштовані користувачем), під час завершення роботи зупиняються як дерево процесів, тому дочірні підпроцеси, запущені сервером, не залишаються після виходу батьківського stdio-клієнта - видалення або скидання сеансу прибирає MCP-клієнтів цього сеансу через спільний шлях очищення середовища виконання, тому не лишається завислих stdio-з’єднань, прив’язаних до видаленого сеансу ### Виберіть режим клієнта Використовуйте той самий міст двома різними способами: Лише стандартні MCP-інструменти. Використовуйте `conversations_list`, `messages_read`, `events_poll`, `events_wait`, `messages_send` та інструменти схвалення. Стандартні MCP-інструменти плюс специфічний для Claude адаптер каналу. Увімкніть `--claude-channel-mode on` або залиште типове значення `auto`. Сьогодні `auto` поводиться так само, як `on`. Виявлення можливостей клієнта ще немає. ### Що надає `serve` Міст використовує наявні метадані маршрутів сеансів Gateway, щоб надавати розмови, підтримані каналами. Розмова з’являється, коли OpenClaw уже має стан сеансу з відомим маршрутом, таким як: - `channel` - метадані одержувача або призначення - необов’язковий `accountId` - необов’язковий `threadId` Це дає MCP-клієнтам одне місце, щоб: - перелічувати нещодавні маршрутизовані розмови - читати нещодавню історію стенограми - чекати на нові вхідні події - надсилати відповідь назад через той самий маршрут - бачити запити на схвалення, що надходять, поки міст підключений ### Використання ```bash openclaw mcp serve ``` ```bash openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token ``` ```bash openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password ``` ```bash openclaw mcp serve --verbose openclaw mcp serve --claude-channel-mode off ``` ### Інструменти мосту Поточний міст надає такі MCP-інструменти: Перелічує нещодавні розмови, підтримані сеансами, які вже мають метадані маршрутів у стані сеансу Gateway. Корисні фільтри: - `limit` - `search` - `channel` - `includeDerivedTitles` - `includeLastMessage` Повертає одну розмову за `session_key` через прямий пошук сеансу Gateway. Читає нещодавні повідомлення стенограми для однієї розмови, підтриманої сеансом. Витягує нетекстові блоки вмісту повідомлення з одного повідомлення стенограми. Це подання метаданих поверх вмісту стенограми, а не окреме довговічне сховище blob-вкладень. Читає живі події в черзі від числового курсора. Виконує long-poll, доки не надійде наступна відповідна подія в черзі або не спливе час очікування. Використовуйте це, коли загальному MCP-клієнту потрібна майже реальна доставка без специфічного для Claude push-протоколу. Надсилає текст назад через той самий маршрут, уже записаний у сеансі. Поточна поведінка: - потребує наявного маршруту розмови - використовує канал, одержувача, ідентифікатор облікового запису та ідентифікатор потоку сеансу - надсилає лише текст Перелічує очікувані запити на схвалення exec/plugin, які міст спостерігав від моменту підключення до Gateway. Вирішує один очікуваний запит на схвалення exec/plugin за допомогою: - `allow-once` - `allow-always` - `deny` ### Модель подій Міст утримує чергу подій у пам’яті, поки він підключений. Поточні типи подій: - `message` - `exec_approval_requested` - `exec_approval_resolved` - `plugin_approval_requested` - `plugin_approval_resolved` - `claude_permission_request` - черга є лише живою; вона запускається, коли запускається MCP-міст - `events_poll` і `events_wait` самі не відтворюють старішу історію Gateway - довговічний backlog слід читати через `messages_read` ### Сповіщення каналу Claude Міст також може надавати специфічні для Claude сповіщення каналу. Це еквівалент адаптера каналу Claude Code в OpenClaw: стандартні MCP-інструменти залишаються доступними, але живі вхідні повідомлення також можуть надходити як специфічні для Claude MCP-сповіщення. `--claude-channel-mode off`: лише стандартні MCP-інструменти. `--claude-channel-mode on`: увімкнути сповіщення каналу Claude. `--claude-channel-mode auto`: поточне типове значення; така сама поведінка мосту, як `on`. Коли режим каналу 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-клієнта: ```json { "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` підтримує: URL WebSocket Gateway. Токен Gateway. Зчитати токен із файлу. Пароль Gateway. Зчитати пароль із файлу. Режим сповіщень Claude. Докладні журнали в stderr. Коли можливо, віддавайте перевагу `--token-file` або `--password-file` замість секретів у командному рядку. ### Безпека та межа довіри Міст не вигадує маршрутизацію. Він лише надає розмови, які Gateway уже вміє маршрутизувати. Це означає: - списки дозволених відправників, сполучення та довіра на рівні каналу все ще належать базовій конфігурації каналу OpenClaw - `messages_send` може відповідати лише через наявний збережений маршрут - стан схвалень є живим/у пам’яті лише для поточного сеансу мосту - автентифікація мосту має використовувати ті самі засоби керування токеном або паролем Gateway, яким ви довіряли б для будь-якого іншого віддаленого клієнта Gateway Якщо розмова відсутня в `conversations_list`, звичайна причина — не конфігурація MCP. Причина в тому, що в базовому сеансі Gateway відсутні або неповні метадані маршруту. ### Тестування OpenClaw постачає детермінований Docker smoke-тест для цього мосту: ```bash pnpm test:docker:mcp-channels ``` Цей smoke-тест: - запускає контейнер Gateway із початковими даними - запускає другий контейнер, який породжує `openclaw mcp serve` - перевіряє виявлення розмов, читання стенограми, читання метаданих вкладень, поведінку живої черги подій і маршрутизацію вихідних надсилань - перевіряє сповіщення каналу та дозволів у стилі Claude через справжній stdio MCP-міст Це найшвидший спосіб довести, що міст працює, без підключення справжнього облікового запису Telegram, Discord або iMessage до тестового запуску. Ширший контекст тестування див. у [Тестування](/uk/help/testing). ### Усунення несправностей Зазвичай це означає, що сеанс Gateway ще не маршрутизований. Переконайтеся, що базовий сеанс має збережені метадані маршруту каналу/провайдера, одержувача та необов’язкового облікового запису/потоку. Очікувано. Жива черга запускається, коли міст підключається. Читайте старішу історію стенограми через `messages_read`. Перевірте все наведене: - клієнт тримав stdio MCP-сеанс відкритим - `--claude-channel-mode` має значення `on` або `auto` - клієнт справді розуміє специфічні для Claude методи сповіщень - вхідне повідомлення сталося після підключення мосту `permissions_list_open` показує лише запити на схвалення, які спостерігалися, поки міст був підключений. Це не API довговічної історії схвалень. ## OpenClaw як реєстр MCP-клієнта Це шлях `openclaw mcp list`, `show`, `set` і `unset`. Ці команди не відкривають OpenClaw через MCP. Вони керують визначеннями MCP-серверів, що належать OpenClaw, у `mcp.servers` у конфігурації OpenClaw. Ці збережені визначення призначені для середовищ виконання, які OpenClaw запускає або налаштовує пізніше, як-от вбудований Pi та інші адаптери середовища виконання. OpenClaw зберігає визначення централізовано, щоб цим середовищам виконання не потрібно було підтримувати власні дублікати списків MCP-серверів. - ці команди лише читають або записують конфігурацію OpenClaw - вони не підключаються до цільового MCP-сервера - вони не перевіряють, чи команда, URL або віддалений транспорт доступні зараз - адаптери середовища виконання вирішують, які форми транспорту вони фактично підтримують під час виконання - вбудований Pi відкриває налаштовані MCP-інструменти у звичайних профілях інструментів `coding` і `messaging`; `minimal` все ще приховує їх, а `tools.deny: ["bundle-mcp"]` явно вимикає їх - обмежені сеансом вбудовані середовища виконання MCP прибираються після `mcp.sessionIdleTtlMs` мілісекунд простою (стандартно 10 хвилин; установіть `0`, щоб вимкнути), а одноразові вбудовані запуски очищають їх наприкінці виконання Адаптери середовища виконання можуть нормалізувати цей спільний реєстр до форми, якої очікує їхній нижчий клієнт. Наприклад, вбудований Pi напряму споживає значення OpenClaw `transport`, тоді як Claude Code і Gemini отримують нативні для CLI значення `type`, як-от `http`, `sse` або `stdio`. ### Збережені визначення MCP-серверів OpenClaw також зберігає полегшений реєстр MCP-серверів у конфігурації для поверхонь, яким потрібні MCP-визначення, керовані OpenClaw. Команди: - `openclaw mcp list` - `openclaw mcp show [name]` - `openclaw mcp set ` - `openclaw mcp unset ` Примітки: - `list` сортує імена серверів. - `show` без імені виводить повний налаштований об’єкт MCP-сервера. - `set` очікує одне значення JSON-об’єкта в командному рядку. - Використовуйте `transport: "streamable-http"` для MCP-серверів Streamable HTTP. `openclaw mcp set` також нормалізує нативне для CLI `type: "http"` до тієї самої канонічної форми конфігурації для сумісності. - `unset` завершується помилкою, якщо сервер із таким іменем не існує. Приклади: ```bash 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 ``` Приклад форми конфігурації: ```json { "mcp": { "servers": { "context7": { "command": "uvx", "args": ["context7-mcp"] }, "docs": { "url": "https://mcp.example.com", "transport": "streamable-http" } } } } ``` ### Транспорт stdio Запускає локальний дочірній процес і взаємодіє через stdin/stdout. | Поле | Опис | | -------------------------- | ----------------------------------------- | | `command` | Виконуваний файл для запуску (обов’язково) | | `args` | Масив аргументів командного рядка | | `env` | Додаткові змінні середовища | | `cwd` / `workingDirectory` | Робочий каталог для процесу | **Фільтр безпеки env для stdio** OpenClaw відхиляє ключі env запуску інтерпретатора, які можуть змінити те, як stdio MCP-сервер запускається до першого RPC, навіть якщо вони з’являються в блоці `env` сервера. Заблоковані ключі включають `NODE_OPTIONS`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4` і подібні змінні керування середовищем виконання. Запуск відхиляє їх із помилкою конфігурації, щоб вони не могли ін’єктувати неявну преамбулу, підмінити інтерпретатор або ввімкнути налагоджувач для процесу stdio. Звичайні облікові дані, проксі та специфічні для сервера змінні env (`GITHUB_TOKEN`, `HTTP_PROXY`, власні `*_API_KEY` тощо) не зачіпаються. Якщо вашому MCP-серверу справді потрібна одна із заблокованих змінних, установіть її в хост-процесі gateway замість `env` stdio-сервера. ### Транспорт SSE / HTTP Підключається до віддаленого MCP-сервера через HTTP Server-Sent Events. | Поле | Опис | | --------------------- | ----------------------------------------------------------------- | | `url` | HTTP- або HTTPS-URL віддаленого сервера (обов’язково) | | `headers` | Необов’язкова мапа ключ-значення HTTP-заголовків (наприклад, токени авторизації) | | `connectionTimeoutMs` | Тайм-аут підключення для кожного сервера в мс (необов’язково) | Приклад: ```json { "mcp": { "servers": { "remote-tools": { "url": "https://mcp.example.com", "headers": { "Authorization": "Bearer " } } } } } ``` Чутливі значення в `url` (userinfo) і `headers` редагуються в журналах і виводі стану. ### Транспорт Streamable HTTP `streamable-http` — це додатковий варіант транспорту поряд із `sse` і `stdio`. Він використовує потокове передавання HTTP для двонапрямної взаємодії з віддаленими MCP-серверами. | Поле | Опис | | --------------------- | ------------------------------------------------------------------------------------ | | `url` | HTTP- або HTTPS-URL віддаленого сервера (обов’язково) | | `transport` | Установіть `"streamable-http"`, щоб вибрати цей транспорт; якщо опущено, OpenClaw використовує `sse` | | `headers` | Необов’язкова мапа ключ-значення HTTP-заголовків (наприклад, токени авторизації) | | `connectionTimeoutMs` | Тайм-аут підключення для кожного сервера в мс (необов’язково) | Конфігурація OpenClaw використовує `transport: "streamable-http"` як канонічне написання. Нативні для CLI значення MCP `type: "http"` приймаються під час збереження через `openclaw mcp set` і виправляються `openclaw doctor --fix` в існуючій конфігурації, але саме `transport` напряму споживає вбудований Pi. Приклад: ```json { "mcp": { "servers": { "streaming-tools": { "url": "https://mcp.example.com/stream", "transport": "streamable-http", "connectionTimeoutMs": 10000, "headers": { "Authorization": "Bearer " } } } } } ``` Ці команди керують лише збереженою конфігурацією. Вони не запускають міст каналу, не відкривають живий клієнтський сеанс MCP і не доводять, що цільовий сервер доступний. ## Поточні обмеження Ця сторінка документує міст у тому вигляді, у якому він постачається сьогодні. Поточні обмеження: - виявлення розмов залежить від наявних метаданих маршруту сеансу Gateway - немає загального push-протоколу поза адаптером, специфічним для Claude - інструментів редагування повідомлень або реакцій поки немає - транспорт HTTP/SSE/streamable-http підключається до одного віддаленого сервера; мультиплексованого upstream поки немає - `permissions_list_open` включає лише схвалення, спостережені, поки міст підключений ## Пов’язане - [Довідник CLI](/uk/cli) - [Plugins](/uk/cli/plugins)