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

Когда режим канала 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-клиенты должны полагаться на стандартные инструменты polling.

Конфигурация 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
• проверяет обнаружение бесед, чтение транскриптов, чтение метаданных вложений, поведение очереди живых событий и маршрутизацию исходящей отправки
• проверяет уведомления каналов и разрешений в стиле 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 использует значения transport OpenClaw напрямую, а Claude Code и Gemini получают нативные для CLI значения 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 обновляет фильтры инструментов для каждого сервера. Записи include/exclude — это имена MCP-инструментов и простые glob-шаблоны *.
• login запускает поток OAuth для HTTP-серверов, настроенных с auth: "oauth". Первый запуск выводит URL авторизации; повторно запустите с --code после подтверждения.
• logout очищает сохраненные учетные данные OAuth для указанного сервера, не удаляя сохраненное определение сервера.
• reload удаляет кэшированные внутрипроцессные MCP-среды выполнения. Процессам Gateway или агентов в другом процессе по-прежнему нужен собственный путь перезагрузки или рестарта.
• Используйте transport: "streamable-http" для Streamable HTTP MCP-серверов. 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": 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-серверов, которые объявляют поддержку потока OAuth MCP. Статические заголовки 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-native 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. Отредактируйте scoped-раздел конфигурации mcp для структурных изменений, таких как новые серверы, заголовки, TLS, метаданные OAuth или фильтры инструментов.
6. Выберите Сохранить, чтобы только сохранить конфигурацию, или Сохранить и опубликовать, чтобы применить ее через путь конфигурации Gateway.
7. Запустите openclaw mcp doctor --probe, когда нужно live-подтверждение, что отредактированный сервер запускается и выводит список инструментов.

Примечания:

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

Текущие ограничения

На этой странице документируется мост в том виде, в котором он поставляется сегодня.

Текущие ограничения:

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

Связанные материалы

• Справочник CLI
• Plugins