---
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-04-28T11:07:40Z"
    model: gpt-5.5
    provider: openai
    source_hash: d66ec20b81ab3894c7202ee1c1c6666bd9cdeffc8d48a280b1f298bb358887ef
    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.

<Steps>
  <Step title="Клієнт запускає міст">
    MCP-клієнт запускає `openclaw mcp serve`.
  </Step>
  <Step title="Міст підключається до Gateway">
    Міст підключається до OpenClaw Gateway через WebSocket.
  </Step>
  <Step title="Сеанси стають MCP-розмовами">
    Маршрутизовані сеанси стають MCP-розмовами та інструментами стенограми/історії.
  </Step>
  <Step title="Живі події стають у чергу">
    Живі події ставляться в чергу в пам’яті, поки міст підключений.
  </Step>
  <Step title="Необов’язкова push-доставка Claude">
    Якщо режим каналу Claude увімкнено, той самий сеанс також може отримувати push-сповіщення, специфічні для Claude.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Важлива поведінка">
    - стан живої черги починається, коли міст підключається
    - старіша історія стенограми читається за допомогою `messages_read`
    - push-сповіщення Claude існують лише поки MCP-сеанс активний
    - коли клієнт відключається, міст завершує роботу, а жива черга зникає
    - одноразові точки входу агента, як-от `openclaw agent` і `openclaw infer model run`, завершують усі комплектні MCP-середовища виконання, які вони відкривають, коли відповідь завершується, тому повторні скриптові запуски не накопичують дочірні stdio MCP-процеси
    - stdio MCP-сервери, запущені OpenClaw (комплектні або налаштовані користувачем), завершуються як дерево процесів під час вимкнення, тому дочірні підпроцеси, запущені сервером, не залишаються після виходу батьківського stdio-клієнта
    - видалення або скидання сеансу утилізує MCP-клієнти цього сеансу через спільний шлях очищення середовища виконання, тому не залишається завислих stdio-з’єднань, прив’язаних до видаленого сеансу

  </Accordion>
</AccordionGroup>

### Виберіть режим клієнта

Використовуйте той самий міст двома різними способами:

<Tabs>
  <Tab title="Загальні MCP-клієнти">
    Лише стандартні MCP-інструменти. Використовуйте `conversations_list`, `messages_read`, `events_poll`, `events_wait`, `messages_send` та інструменти схвалення.
  </Tab>
  <Tab title="Claude Code">
    Стандартні MCP-інструменти плюс адаптер каналу, специфічний для Claude. Увімкніть `--claude-channel-mode on` або залиште типове значення `auto`.
  </Tab>
</Tabs>

<Note>
Сьогодні `auto` поводиться так само, як `on`. Виявлення можливостей клієнта поки немає.
</Note>

### Що надає `serve`

Міст використовує наявні метадані маршруту сеансу Gateway, щоб надавати розмови, підтримані каналами. Розмова з’являється, коли OpenClaw уже має стан сеансу з відомим маршрутом, наприклад:

- `channel`
- метадані отримувача або призначення
- необов’язковий `accountId`
- необов’язковий `threadId`

Це дає MCP-клієнтам одне місце, щоб:

- перелічувати нещодавні маршрутизовані розмови
- читати нещодавню історію стенограми
- чекати на нові вхідні події
- надсилати відповідь назад через той самий маршрут
- бачити запити на схвалення, що надходять, поки міст підключений

### Використання

<Tabs>
  <Tab title="Локальний Gateway">
    ```bash
    openclaw mcp serve
    ```
  </Tab>
  <Tab title="Віддалений Gateway (токен)">
    ```bash
    openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
    ```
  </Tab>
  <Tab title="Віддалений Gateway (пароль)">
    ```bash
    openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password
    ```
  </Tab>
  <Tab title="Докладно / Claude вимкнено">
    ```bash
    openclaw mcp serve --verbose
    openclaw mcp serve --claude-channel-mode off
    ```
  </Tab>
</Tabs>

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

Поточний міст надає ці MCP-інструменти:

<AccordionGroup>
  <Accordion title="conversations_list">
    Перелічує нещодавні розмови, підтримані сеансами, які вже мають метадані маршруту в стані сеансу Gateway.

    Корисні фільтри:

    - `limit`
    - `search`
    - `channel`
    - `includeDerivedTitles`
    - `includeLastMessage`

  </Accordion>
  <Accordion title="conversation_get">
    Повертає одну розмову за `session_key`.
  </Accordion>
  <Accordion title="messages_read">
    Читає нещодавні повідомлення стенограми для однієї розмови, підтриманої сеансом.
  </Accordion>
  <Accordion title="attachments_fetch">
    Витягує нетекстові блоки вмісту повідомлення з одного повідомлення стенограми. Це подання метаданих поверх вмісту стенограми, а не окреме довговічне сховище blob-вкладень.
  </Accordion>
  <Accordion title="events_poll">
    Читає поставлені в чергу живі події після числового курсора.
  </Accordion>
  <Accordion title="events_wait">
    Виконує довге опитування, доки не надійде наступна відповідна подія в черзі або не мине час очікування.

    Використовуйте це, коли загальному MCP-клієнту потрібна доставка майже в реальному часі без push-протоколу, специфічного для Claude.

  </Accordion>
  <Accordion title="messages_send">
    Надсилає текст назад через той самий маршрут, уже записаний у сеансі.

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

    - вимагає наявного маршруту розмови
    - використовує канал сеансу, отримувача, ідентифікатор облікового запису та ідентифікатор гілки
    - надсилає лише текст

  </Accordion>
  <Accordion title="permissions_list_open">
    Перелічує очікувані запити на схвалення exec/plugin, які міст спостерігав від моменту підключення до Gateway.
  </Accordion>
  <Accordion title="permissions_respond">
    Розв’язує один очікуваний запит на схвалення exec/plugin за допомогою:

    - `allow-once`
    - `allow-always`
    - `deny`

  </Accordion>
</AccordionGroup>

### Модель подій

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

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

- `message`
- `exec_approval_requested`
- `exec_approval_resolved`
- `plugin_approval_requested`
- `plugin_approval_resolved`
- `claude_permission_request`

<Warning>
- черга призначена лише для живих подій; вона починається, коли MCP-міст запускається
- `events_poll` і `events_wait` самі не відтворюють старішу історію Gateway
- довговічний backlog слід читати за допомогою `messages_read`

</Warning>

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

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

<Tabs>
  <Tab title="off">
    `--claude-channel-mode off`: лише стандартні MCP-інструменти.
  </Tab>
  <Tab title="on">
    `--claude-channel-mode on`: увімкнути сповіщення каналу Claude.
  </Tab>
  <Tab title="auto (типово)">
    `--claude-channel-mode auto`: поточне типове значення; така сама поведінка мосту, як `on`.
  </Tab>
</Tabs>

Коли режим каналу 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` підтримує:

<ParamField path="--url" type="string">
  URL WebSocket для Gateway.
</ParamField>
<ParamField path="--token" type="string">
  Токен Gateway.
</ParamField>
<ParamField path="--token-file" type="string">
  Читати токен із файлу.
</ParamField>
<ParamField path="--password" type="string">
  Пароль Gateway.
</ParamField>
<ParamField path="--password-file" type="string">
  Читати пароль із файлу.
</ParamField>
<ParamField path="--claude-channel-mode" type='"auto" | "on" | "off"'>
  Режим сповіщень Claude.
</ParamField>
<ParamField path="-v, --verbose" type="boolean">
  Докладні журнали в stderr.
</ParamField>

<Tip>
Коли можливо, надавайте перевагу `--token-file` або `--password-file` замість inline-секретів.
</Tip>

### Безпека та межа довіри

Міст не вигадує маршрутизацію. Він лише надає розмови, які Gateway уже вміє маршрутизувати.

Це означає:

- списки дозволених відправників, pairing і довіра на рівні каналу досі належать до базової конфігурації каналу OpenClaw
- `messages_send` може відповідати лише через наявний збережений маршрут
- стан схвалення є живим/у пам’яті лише для поточного сеансу мосту
- автентифікація мосту має використовувати ті самі засоби керування токеном або паролем Gateway, яким ви довіряли б для будь-якого іншого віддаленого клієнта Gateway

Якщо розмови немає в `conversations_list`, звичайна причина не в конфігурації MCP. Це відсутні або неповні метадані маршруту в базовому сеансі Gateway.

### Тестування

OpenClaw постачає детермінований Docker smoke для цього мосту:

```bash
pnpm test:docker:mcp-channels
```

Цей smoke:

- запускає seeded Gateway-контейнер
- запускає другий контейнер, який породжує `openclaw mcp serve`
- перевіряє виявлення розмов, читання стенограм, читання метаданих вкладень, поведінку живої черги подій і маршрутизацію вихідного надсилання
- перевіряє сповіщення каналу та дозволів у стилі Claude через реальний stdio MCP-міст

Це найшвидший спосіб довести, що міст працює, без підключення реального облікового запису Telegram, Discord або iMessage до тестового запуску.

Для ширшого контексту тестування див. [Тестування](/uk/help/testing).

### Усунення несправностей

<AccordionGroup>
  <Accordion title="Розмови не повертаються">
    Зазвичай означає, що сеанс Gateway ще не придатний до маршрутизації. Підтвердьте, що базовий сеанс має збережені метадані маршруту каналу/провайдера, отримувача та необов’язкового облікового запису/гілки.
  </Accordion>
  <Accordion title="events_poll або events_wait пропускає старіші повідомлення">
    Очікувано. Жива черга починається, коли міст підключається. Читайте старішу історію стенограми за допомогою `messages_read`.
  </Accordion>
  <Accordion title="Сповіщення Claude не з’являються">
    Перевірте все це:

    - клієнт тримав stdio MCP-сеанс відкритим
    - `--claude-channel-mode` має значення `on` або `auto`
    - клієнт справді розуміє методи сповіщень, специфічні для Claude
    - вхідне повідомлення надійшло після підключення мосту

  </Accordion>
  <Accordion title="Схвалення відсутні">
    `permissions_list_open` показує лише запити на схвалення, спостережені, поки міст був підключений. Це не API довговічної історії схвалень.
  </Accordion>
</AccordionGroup>

## OpenClaw як реєстр MCP-клієнта

Це шлях `openclaw mcp list`, `show`, `set` і `unset`.

Ці команди не надають доступ до OpenClaw через MCP. Вони керують визначеннями MCP-серверів, що належать OpenClaw, у `mcp.servers` у конфігурації OpenClaw.

Ці збережені визначення призначені для середовищ виконання, які OpenClaw запускає або налаштовує пізніше, як-от вбудований Pi та інші адаптери середовища виконання. OpenClaw зберігає визначення централізовано, щоб цим середовищам виконання не доводилося підтримувати власні дублікати списків MCP-серверів.

<AccordionGroup>
  <Accordion title="Важлива поведінка">
    - ці команди лише читають або записують конфігурацію OpenClaw
    - вони не підключаються до цільового MCP-сервера
    - вони не перевіряють, чи команда, URL або віддалений транспорт доступні просто зараз
    - адаптери середовища виконання вирішують, які форми транспорту вони фактично підтримують під час виконання
    - вбудований Pi надає налаштовані MCP-інструменти у звичайних профілях інструментів `coding` і `messaging`; `minimal` усе ще приховує їх, а `tools.deny: ["bundle-mcp"]` вимикає їх явно
    - сеансові вбудовані MCP-середовища виконання прибираються після `mcp.sessionIdleTtlMs` мілісекунд простою (стандартно 10 хвилин; установіть `0`, щоб вимкнути), а одноразові вбудовані запуски очищають їх наприкінці виконання

  </Accordion>
</AccordionGroup>

Адаптери середовища виконання можуть нормалізувати цей спільний реєстр у форму, яку очікує їхній нижчий клієнт. Наприклад, вбудований 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 <name> <json>`
- `openclaw mcp unset <name>`

Примітки:

- `list` сортує імена серверів.
- `show` без імені виводить повний налаштований об’єкт MCP-сервера.
- `set` очікує одне значення JSON-об’єкта в командному рядку.
- Використовуйте `transport: "streamable-http"` для Streamable HTTP MCP-серверів. `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` | Робочий каталог для процесу               |

<Warning>
**Фільтр безпеки stdio env**

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.
</Warning>

### Транспорт 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 <token>"
        }
      }
    }
  }
}
```

Чутливі значення в `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 <token>"
        }
      }
    }
  }
}
```

<Note>
Ці команди керують лише збереженою конфігурацією. Вони не запускають міст каналу, не відкривають живий сеанс MCP-клієнта й не доводять, що цільовий сервер доступний.
</Note>

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

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

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

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

## Пов’язане

- [Довідник CLI](/uk/cli)
- [Plugins](/uk/cli/plugins)
