--- 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-07-13T19:38:32Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: f62657954709e3f25eb7031dafca9c4050f2420443587f76ce2b2db23f187987 source_path: cli/mcp.md workflow: 16 --- `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 для серверов, которые позднее могут использовать его собственные среды выполнения. `list`, `show`, `set` и `unset` только читают и записывают управляемые OpenClaw записи `mcp.servers` в конфигурации OpenClaw. Они не включают серверы mcporter из `config/mcporter.json`; для этого реестра используйте `mcporter list`. Используйте [`openclaw acp`](/ru/cli/acp), когда OpenClaw должен самостоятельно размещать сеанс среды программирования и направлять эту среду выполнения через ACP. ## Выбор подходящего пути MCP | Цель | Используйте | Почему | | ------------------------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Разрешить внешнему клиенту MCP читать и отправлять сообщения в беседах каналов OpenClaw | `openclaw mcp serve` | OpenClaw выступает сервером MCP и предоставляет через stdio беседы на базе Gateway. | | Сохранить сторонние серверы MCP для управляемых OpenClaw запусков агентов | `openclaw mcp add`, `set`, `configure`, `tools`, `login` | OpenClaw выступает клиентским реестром MCP и позднее передаёт эти серверы в подходящие среды выполнения. | | Проверить сохранённый сервер без запуска хода агента | `openclaw mcp status`, `doctor`, `probe` | `status` и `doctor` проверяют конфигурацию; `probe` открывает действующее подключение MCP и выводит список возможностей. | | Изменить конфигурацию MCP в браузере | Control UI `/settings/mcp` (псевдоним `/mcp`) | На странице отображаются перечень, состояние включения, сводки OAuth и фильтров, подсказки команд и редактор `mcp` с ограниченной областью действия. | | Предоставить Codex app-server нативный сервер MCP с ограниченной областью действия | `mcp.servers..codex` | Блок `codex` влияет только на проекцию потоков Codex app-server и удаляется перед передачей нативной конфигурации. | | Запускать размещённые через ACP сеансы среды выполнения | [`openclaw acp`](/ru/cli/acp) и [агенты ACP](/ru/tools/acp-agents-setup) | Режим моста ACP не поддерживает внедрение серверов MCP для отдельных сеансов; вместо этого настройте мосты Gateway или плагинов. | Если вы не уверены, какой путь вам нужен, начните с `openclaw mcp status --verbose`. Эта команда показывает сохранённые OpenClaw данные, не запуская серверы MCP. ## OpenClaw как сервер MCP Это путь `openclaw mcp serve`. ### Когда использовать serve Используйте `openclaw mcp serve`, когда: - Codex, Claude Code или другой клиент MCP должен напрямую взаимодействовать с беседами каналов на базе OpenClaw - у вас уже есть локальный или удалённый OpenClaw Gateway с маршрутизируемыми сеансами - вам нужен один сервер MCP, работающий со всеми серверными реализациями каналов OpenClaw, вместо отдельных мостов для каждого канала Вместо этого используйте [`openclaw acp`](/ru/cli/acp), когда OpenClaw должен самостоятельно размещать среду программирования и хранить сеанс агента внутри OpenClaw. ### Принцип работы `openclaw mcp serve` запускает сервер MCP через stdio. Процессом владеет клиент MCP. Пока клиент держит сеанс stdio открытым, мост подключается по WebSocket к локальному или удалённому OpenClaw Gateway и предоставляет маршрутизируемые беседы каналов через MCP. Клиент MCP запускает `openclaw mcp serve`. Мост подключается по WebSocket к OpenClaw Gateway. Маршрутизируемые сеансы становятся беседами MCP и инструментами для работы с расшифровками и историей. Пока мост подключён, события в реальном времени помещаются в очередь в памяти. Если включён режим канала Claude, тот же сеанс также может получать push-уведомления, специфичные для Claude. - состояние очереди событий в реальном времени создаётся при подключении моста - предыдущая история расшифровки считывается с помощью `messages_read` - push-уведомления Claude существуют только во время работы сеанса MCP - при отключении клиента мост завершает работу, а очередь событий в реальном времени удаляется - одноразовые точки входа агента, такие как `openclaw agent` и `openclaw infer model run`, завершают работу всех открытых ими встроенных сред выполнения MCP после завершения ответа, поэтому повторные запуски из скриптов не накапливают дочерние процессы MCP через stdio - серверы MCP через stdio, запущенные 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 ``` ### Инструменты моста Выводит список недавних бесед на базе сеансов, для которых в состоянии сеансов Gateway уже имеются метаданные маршрутов. Фильтры: `limit` (не более 500), `search`, `channel`, `includeDerivedTitles`, `includeLastMessage`. Возвращает одну беседу по `session_key`, используя прямой поиск сеанса Gateway. Читает недавние сообщения расшифровки для одной беседы на базе сеанса. Значение `limit` по умолчанию — 20, максимальное — 200. Извлекает нетекстовые блоки содержимого сообщения из одного сообщения расшифровки. Это представление метаданных содержимого расшифровки, а не отдельное долговременное хранилище двоичных объектов вложений. Читает помещённые в очередь события после указанного числового курсора. Максимальное значение `limit` — 200. Использует длительный опрос до поступления следующего подходящего события в очереди или истечения времени ожидания (по умолчанию 30 с, максимум 300 с). Используйте этот инструмент, когда универсальному клиенту MCP требуется доставка практически в реальном времени без специфичного для Claude протокола push-уведомлений. Отправляет текст обратно по тому же маршруту, который уже записан для сеанса. Текущее поведение: - требуется существующий маршрут беседы - используются канал, получатель, идентификатор учётной записи и идентификатор потока сеанса - отправляется только текст Выводит список ожидающих запросов на подтверждение выполнения команд или действий плагинов, обнаруженных мостом после подключения к Gateway. Обрабатывает один ожидающий запрос на подтверждение выполнения команды или действия плагина с помощью: - `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 - долговременную историю следует читать с помощью `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 ` или `no ` (`` — это 5-буквенный идентификатор запроса без `l`), мост преобразует это в `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.remote.url`, если он настроен. Токен Gateway. Прочитать токен из файла. Пароль Gateway. Прочитать пароль из файла. Режим уведомлений Claude. По умолчанию — `auto`. Подробные журналы в stderr. По возможности используйте `--token-file` или `--password-file` вместо секретов, указанных непосредственно в команде. ### Безопасность и граница доверия Мост не создаёт маршрутизацию. Он предоставляет доступ только к тем разговорам, которые Gateway уже умеет маршрутизировать. Это означает следующее: - списки разрешённых отправителей, сопряжение и доверие на уровне канала по-прежнему определяются базовой конфигурацией канала OpenClaw - `messages_send` может отвечать только через существующий сохранённый маршрут - состояние подтверждений существует только в оперативной памяти и только в рамках текущего сеанса моста - для аутентификации моста следует использовать те же механизмы токена или пароля Gateway, которым вы доверили бы любой другой удалённый клиент Gateway Если разговор отсутствует в `conversations_list`, причина обычно не в конфигурации MCP. Как правило, в базовом сеансе Gateway отсутствуют или не полностью заданы метаданные маршрута. ### Тестирование OpenClaw поставляется с детерминированным дымовым Docker-тестом для этого моста: ```bash 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. Более подробный контекст тестирования см. в разделе [Тестирование](/ru/help/testing). ### Устранение неполадок Обычно это означает, что сеанс Gateway ещё не поддерживает маршрутизацию. Убедитесь, что в базовом сеансе сохранены метаданные канала или провайдера, получателя, а также необязательные метаданные маршрута учётной записи или ветки. Это ожидаемое поведение. Очередь событий в реальном времени начинает работать при подключении моста. Для чтения более ранней истории расшифровки используйте `messages_read`. Проверьте всё перечисленное ниже: - клиент сохранил сеанс MCP stdio открытым - `--claude-channel-mode` имеет значение `on` или `auto` - клиент действительно поддерживает специфичные для Claude методы уведомлений - входящее сообщение поступило после подключения моста `permissions_list_open` показывает только запросы подтверждения, полученные во время подключения моста. Это не API долговременной истории подтверждений. ## 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 - `status`, `list`, `show`, `doctor` без `--probe`, `set`, `configure`, `tools`, `logout`, `reload` и `unset` не подключаются к целевому серверу MCP - `login` выполняет сетевой процесс OAuth MCP для настроенного HTTP-сервера и сохраняет полученные локальные учётные данные - `status --verbose` выводит сведения о разрешённом транспорте, аутентификации, тайм-аутах, фильтрах и параллельных вызовах инструментов без подключения - `doctor` проверяет сохранённые определения на наличие локальных проблем настройки, таких как отсутствующие команды stdio, недопустимые рабочие каталоги, отсутствующие файлы TLS, отключённые серверы, явно указанные конфиденциальные значения заголовков или переменных среды и незавершённая авторизация OAuth - `doctor --probe` после успешного прохождения статических проверок добавляет такую же проверку подключения в реальном времени, как `probe` - `probe` подключается к выбранному серверу или ко всем настроенным серверам, перечисляет инструменты и сообщает о возможностях и диагностике - `add` создаёт определение из флагов и проверяет его перед сохранением, если не задан `--no-probe` или сначала не требуется авторизация OAuth - адаптеры сред выполнения во время исполнения определяют, какие формы транспорта они фактически поддерживают - `enabled: false` сохраняет сервер, но исключает его из обнаружения встроенной средой выполнения - `timeout` и `connectTimeout` задают тайм-ауты запросов и подключений для каждого сервера в секундах - `supportsParallelToolCalls: true` отмечает серверы, которые адаптеры могут вызывать параллельно - HTTP-серверы могут использовать статические заголовки, вход через OAuth, управление проверкой TLS и пути к сертификату и ключу mTLS - встроенный OpenClaw предоставляет настроенные инструменты MCP в обычных профилях инструментов `coding` и `messaging`; `minimal` по-прежнему скрывает их, а `tools.deny: ["bundle-mcp"]` явно отключает их - параметры `toolFilter.include` и `toolFilter.exclude` для каждого сервера фильтруют обнаруженные инструменты MCP до их преобразования в инструменты OpenClaw - серверы, объявляющие ресурсы или подсказки, также предоставляют служебные инструменты для перечисления и чтения ресурсов, а также перечисления и получения подсказок; к этим создаваемым служебным именам (`resources_list`, `resources_read`, `prompts_list`, `prompts_get`) применяется тот же фильтр включения и исключения - динамические изменения списка инструментов MCP делают кэшированный каталог этого сеанса недействительным; при следующем обнаружении или использовании данные обновляются с сервера - повторяющиеся сбои запросов к инструментам MCP или протокола временно приостанавливают работу этого сервера, чтобы один неисправный сервер не занял весь ход - встроенные среды выполнения MCP, связанные с сеансом, завершаются после `mcp.sessionIdleTtlMs` миллисекунд бездействия (по умолчанию 10 минут; задайте `0`, чтобы отключить), а одноразовые запуски встроенной среды очищают их по завершении запуска Адаптеры сред выполнения могут преобразовывать этот общий реестр в форму, ожидаемую их нижестоящим клиентом. Например, встроенный 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 [flags]` - `openclaw mcp set ` - `openclaw mcp configure [flags]` - `openclaw mcp tools [--include csv] [--exclude csv] [--clear]` - `openclaw mcp login [--code code]` - `openclaw mcp logout ` - `openclaw mcp reload` - `openclaw mcp unset ` Примечания: - `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` завершается с ошибкой, если указанный сервер не существует. Примеры: ```bash openclaw mcp list openclaw mcp show context7 --json openclaw mcp status --verbose openclaw mcp doctor --probe openclaw mcp probe context7 --json openclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memory openclaw 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 docs openclaw mcp logout docs openclaw mcp unset context7 ``` ### Распространённые конфигурации серверов Эти примеры только сохраняют определения серверов. После этого выполните `openclaw mcp doctor --probe`, чтобы убедиться, что сервер запускается и предоставляет инструменты. ```bash 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 ``` Ограничивайте область действия серверов файловой системы минимальным деревом каталогов, которое агенту необходимо читать или изменять. ```bash openclaw mcp add memory \ --command npx \ --arg -y \ --arg @modelcontextprotocol/server-memory openclaw mcp probe memory --json ``` Используйте фильтр инструментов, если сервер предоставляет инструменты записи, которые не должны быть доступны обычным агентам. ```bash openclaw mcp add local-tools \ --command node \ --arg ./dist/mcp-server.js \ --cwd /srv/openclaw-tools \ --env API_BASE=https://internal.example openclaw mcp status --verbose ``` `doctor` проверяет, что `cwd` существует и команда разрешается в настроенной среде. ```bash 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 ``` Используйте OAuth, если удалённый сервер его поддерживает. Если серверу требуются статические заголовки, не фиксируйте в репозитории токены доступа в явном виде. ```bash 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` для скриптов и панелей мониторинга. Наборы полей со временем могут расширяться, поэтому потребители должны игнорировать неизвестные ключи. ```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 } ] } ``` ```json { "ok": true, "path": "/home/user/.openclaw/openclaw.json", "servers": [ { "name": "docs", "ok": true, "issues": [ { "level": "warning", "message": "Учётные данные OAuth не авторизованы; выполните openclaw mcp login docs" } ] } ] } ``` `doctor --json` завершается с ненулевым кодом, если у любого проверенного включённого сервера есть проблема уровня `error`. Проблемы `warning` и `info` отображаются, но сами по себе не приводят к сбою команды. ```json { "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": [] } ``` `probe --json` открывает активный клиентский сеанс MCP и выводит его результат напрямую; в отличие от `status`/`doctor`, в выводе нет поля верхнего уровня `path`. Ключи `resources` и `prompts` присутствуют только тогда, когда сервер действительно объявляет соответствующую возможность (сервер без подсказок не включает ключ `prompts`, а не сообщает `false`). Используйте `probe` для проверки доступности и возможностей, а не для статического аудита конфигурации. Пример структуры конфигурации: ```json { "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. | Поле | Описание | | -------------------------- | --------------------------------- | | `command` | Запускаемый исполняемый файл (обязательно) | | `args` | Массив аргументов командной строки | | `env` | Дополнительные переменные среды | | `cwd` / `workingDirectory` | Рабочий каталог процесса | **Фильтр безопасности среды Stdio** Перед запуском stdio-сервера MCP OpenClaw отклоняет ключи среды, управляющие запуском интерпретатора, подменой загрузчика и инициализацией оболочки, даже если они указаны в блоке `env` сервера. Для этого применяется та же политика безопасности среды хоста, что и для других процессов, запускаемых OpenClaw: блокируются известные перехватчики запуска интерпретаторов (например, `NODE_OPTIONS`, `PYTHONSTARTUP`, `PERL5OPT`, `RUBYOPT`, `BASHOPTS`, `KSH_ENV`), префиксы внедрения общих библиотек и функций (`DYLD_*`, `LD_*`, `BASH_FUNC_*`), а также аналогичные переменные управления средой выполнения. При запуске эти переменные без уведомления удаляются, а в журнал записывается предупреждение, чтобы они не могли внедрить неявную преамбулу, заменить интерпретатор, включить отладчик или перехватить динамический компоновщик процесса stdio. Явный список разрешённых переменных сохраняет возможность использовать обычные переменные среды с учётными данными MCP (`GITHUB_TOKEN`, `GH_TOKEN`, `GITLAB_TOKEN`, `NPM_TOKEN`, `NODE_AUTH_TOKEN`, `DATABASE_URL`, `MONGODB_URI`, `REDIS_URL`, `AMQP_URL`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`), а также обычные переменные прокси и серверные переменные среды (`HTTP_PROXY`, пользовательские `*_API_KEY` и т. д.). Другие ключи `AWS_*`, такие как `AWS_CONFIG_FILE` и `AWS_SHARED_CREDENTIALS_FILE`, остаются заблокированными, поскольку указывают на файлы учётных данных, а не содержат непосредственно значение учётных данных. Если вашему серверу MCP действительно требуется одна из заблокированных переменных, задайте её для хост-процесса Gateway, а не в `env` stdio-сервера. ### Транспорт SSE / HTTP Подключается к удалённому серверу MCP по протоколу HTTP Server-Sent Events. | Поле | Описание | | ------------------------------ | ---------------------------------------------------------------- | | `url` | HTTP- или HTTPS-URL удалённого сервера (обязательно) | | `headers` | Необязательная карта HTTP-заголовков в формате «ключ — значение» (например, токены аутентификации) | | `connectionTimeoutMs` | Тайм-аут подключения для сервера в мс (необязательно) | | `connectTimeout` | Тайм-аут подключения для сервера в секундах (необязательно) | | `timeout` / `requestTimeoutMs` | Тайм-аут запроса MCP для сервера в секундах или мс | | `auth: "oauth"` | Использовать учётные данные MCP OAuth, сохранённые командой `openclaw mcp login` | | `sslVerify` | Устанавливайте значение false только для явно доверенных частных конечных точек HTTPS | | `clientCert` / `clientKey` | Пути к клиентскому сертификату и ключу mTLS | | `supportsParallelToolCalls` | Указание, что параллельные вызовы безопасны для этого сервера | Пример: ```json { "mcp": { "servers": { "remote-tools": { "url": "https://mcp.example.com", "auth": "oauth", "timeout": 20, "headers": { "Authorization": "Bearer " } } } } } ``` Конфиденциальные значения в `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 ` и использовать сервер на одном из последующих ходов. Если удалённая служба MCP уже использует отдельный профиль аутентификации OpenClaw с возможностью обновления, можно дополнительно задать `oauth.authProfileId`. Перед проецированием в среду выполнения OpenClaw обновляет учётные данные из любого из этих источников и передаёт нижестоящему клиенту MCP только текущий токен доступа. Добавьте или обновите сервер с помощью `auth: "oauth"` и при необходимости укажите метаданные OAuth. ```bash openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}' ``` Для токена доступа на основе профиля аутентификации сохраните привязку профиля: ```bash openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}' ``` Выполните команду входа, чтобы создать запрос авторизации. ```bash openclaw mcp login docs ``` OpenClaw выводит URL авторизации и сохраняет временное состояние верификатора OAuth в каталоге состояния OpenClaw. После подтверждения в браузере передайте полученный код обратно в OpenClaw. ```bash openclaw mcp login docs --code abc123 ``` Используйте status или doctor, чтобы убедиться в наличии токенов. ```bash openclaw mcp status --verbose openclaw mcp doctor docs --probe ``` Выход удаляет сохранённые учётные данные OAuth, но сохраняет определение сервера. ```bash openclaw mcp logout docs ``` Если провайдер обновляет токены или состояние авторизации зависает, выполните `openclaw mcp logout `, а затем повторите `login`. Команда `logout` может удалить учётные данные сохранённого HTTP-сервера даже после удаления `auth: "oauth"` из конфигурации, если имя и URL сервера по-прежнему позволяют определить запись в хранилище учётных данных. ### Потоковый транспорт HTTP `streamable-http` — дополнительный вариант транспорта наряду с `sse` и `stdio`. Он использует потоковую передачу HTTP для двунаправленного обмена данными с удалёнными серверами MCP. | Поле | Описание | | ------------------------------ | -------------------------------------------------------------------------------------- | | `url` | URL удалённого сервера по HTTP или HTTPS (обязательно) | | `transport` | Установите значение `"streamable-http"`, чтобы выбрать этот транспорт; если оно не указано, OpenClaw использует `sse` | | `headers` | Необязательное отображение HTTP-заголовков в виде пар «ключ — значение» (например, токенов авторизации) | | `connectionTimeoutMs` | Тайм-аут подключения к отдельному серверу в мс (необязательно) | | `connectTimeout` | Тайм-аут подключения к отдельному серверу в секундах (необязательно) | | `timeout` / `requestTimeoutMs` | Тайм-аут запроса MCP к отдельному серверу в секундах или мс | | `auth: "oauth"` | Использовать учётные данные MCP OAuth, сохранённые командой `openclaw mcp login` | | `sslVerify` | Устанавливайте false только для явно доверенных частных конечных точек HTTPS | | `clientCert` / `clientKey` | Пути к клиентскому сертификату и ключу mTLS | | `supportsParallelToolCalls` | Указание на то, что параллельные вызовы безопасны для этого сервера | В конфигурации OpenClaw каноническим написанием является `transport: "streamable-http"`. Значения MCP `type: "http"`, используемые непосредственно в CLI, принимаются при сохранении через `openclaw mcp set` и исправляются в существующей конфигурации командой `openclaw doctor --fix`, но встроенный OpenClaw напрямую использует `transport`. Пример: ```json { "mcp": { "servers": { "streaming-tools": { "url": "https://mcp.example.com/stream", "transport": "streamable-http", "connectTimeout": 10, "timeout": 30, "headers": { "Authorization": "Bearer " } } } } } ``` Команды реестра не запускают мост канала. Только `probe` и `doctor --probe` открывают активный клиентский сеанс MCP, чтобы подтвердить доступность целевого сервера. ## Интерфейс управления Браузерный интерфейс управления содержит отдельную страницу настроек 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](https://modelcontextprotocol.io/extensions/apps). Приложения необходимо включать явно, поскольку их HTML поступает с настроенного сервера MCP и может запрашивать доступные приложению инструменты или ресурсы с того же сервера. Включите мост хоста: ```bash openclaw config set mcp.apps.enabled true --strict-json ``` После изменения этого параметра перезапустите Gateway. Когда он включён, OpenClaw запускает HTTP(S)-слушатель только для песочницы на порту Gateway плюс один (для Gateway по умолчанию — `18790`). Интерфейс управления загружает приложения из этого отдельного источника; слушатель никогда не обслуживает интерфейс управления, аутентифицированные маршруты Gateway или пользовательские данные. Для прямых подключений к Gateway требуется доступ к обоим портам. Если обратный прокси-сервер или терминатор TLS предоставляет доступ к интерфейсу управления, выделите приложениям отдельный публичный источник и перенаправляйте только его на слушатель песочницы: ```json5 { mcp: { apps: { enabled: true, sandboxOrigin: "https://mcp-apps.example.com", sandboxPort: 18790, }, }, } ``` Источник песочницы должен отличаться от источника интерфейса управления. Не размещайте на нём другой аутентифицированный или конфиденциальный контент. Например, официальный базовый демонстрационный пример на React можно настроить следующим образом: ```json5 { 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](/ru/cli) - [Плагины](/ru/cli/plugins)