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 остаются доступными, но входящие сообщения в реальном времени также могут поступать как специфичные для Claude уведомления MCP.

Когда режим канала 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 также учитывает необязательный блок codex на каждом сервере. Это метаданные проекции OpenClaw только для веток сервера приложений Codex; они не изменяют сеансы 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 предназначен для HTTP-серверов MCP, которые объявляют поддержку потока OAuth MCP. Статические заголовки 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". Значения MCP type: "http", используемые непосредственно в 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
• в зависимости от процесса, которому принадлежат клиенты MCP, активным средам выполнения может потребоваться openclaw mcp reload, публикация конфигурации Gateway или перезапуск процесса

Приложения 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
• Плагины