Аудитория: Gateway работает, но инструменты MCP не появляются, вызовы истекают по таймауту или Skills пропадают после перезапуска. Результат: bootstrap оставьте в гайде по установке и runbook Docker в проде; персистентность — в статье про тома и права Skills. Этот runbook покрывает объявить → видимость процесса → регистрация в Gateway → триаж модели, инструмента и канала. Структура: шесть ловушек, две таблицы, набросок конфигурации, предупреждение, шесть шагов, три KPI, заключение.
MCP — это сессия JSON-RPC между Gateway и дочерним процессом или удалённой конечной точкой. Записи в конфиге есть ≠ процесс стартует; процесс стартует ≠ схемы возвращаются. Ниже шесть частых ошибок прочтения ситуации.
PATH и ключи API из ~/.zshrc.AGENTS.md и bootstrap: дубли между MCP и Skills раздувают контекст; границы разделяйте по чеклисту настройки Skills.Запускайте openclaw doctor в порядке из гайда doctor после установки; эта статья добавляет цепочку доказательств регистрации инструментов, а не ещё один установочный туториал.
На каждый MCP-сервер — карточка «минимального воспроизведения»: один читающий запрос, один негативный тест, который должен быть отклонён, три ожидаемых токена в логах — дежурный сравнивает карточки без перечитывания гигантских промптов. Укажите на карточке разрешённый исходящий трафик и классификацию данных, чтобы инциденты не расширяли область токенов без записи.
Имена полей зависят от версии OpenClaw; таблица фиксирует порядок работ.
| Симптом | Собрать сначала | Вероятная причина | Действие с аудитом |
|---|---|---|---|
| Пустой или частичный список инструментов | Логи Gateway, коды выхода дочернего процесса | Нет бинарника, cwd, permission denied | Абсолютные command/args/cwd; запускать дочерний процесс от того же пользователя, что и Gateway |
| Первый вызов медленный, дальше норма | Время cold-start, логи загрузки пакетов | npx -y или JIT рантайма | Прогрев; закрепить версии в образах; ослабить таймаут первого вызова |
| Постоянные таймауты | Жив ли процесс, CPU, использование FD | Взаимная блокировка, блокирующий IO | Выборка/трассировка где разрешено; A/B с инструментом только чтения |
| «Инструмент не зарегистрирован» | Логи схем, версия протокола | Несовпадение реализаций | Согласовать версии MCP; закрепить минорные; читать changelog upstream |
Опубликуйте матрицу возможностей, чтобы один сценарий не описывали тремя способами.
| Источник | Лучше всего для | Версионирование | Риск |
|---|---|---|---|
| ClawHub / маркетплейс | Быстрые эксперименты | Закрепить коммит или диапазон semver; еженедельный diff | Дрейф upstream — нужны регрессионные тесты |
SKILL.md в репо / приватные паки | Потоки с жёстким compliance | Поставлять с основной веткой через PR | Нагрузка на сопровождение; согласовать с областью MCP |
| MCP (источник истины) | БД, тикеты, внутренние HTTP API | Независимый ритм релизов | Слишком широкие токены — ведите allowlist |
# Только структурный набросок — реальные ключи, вложенность и hot reload по текущей доке OpenClaw.
# Цель: Gateway запускает MCP-сервер по stdio от фиксированного пользователя.
#
# mcpServers:
# internal-readonly-lookup:
# command: /usr/local/bin/node
# args: ["/opt/mcp-servers/lookup/dist/index.js"]
# env:
# LOOKUP_API_TOKEN: "${LOOKUP_TOKEN_READONLY}"
#
# Skill ClawHub: распаковать/клонировать в каталог skills команды, затем обновить
# индекс skills или выполнить документированную команду reload для вашей версии.
Предупреждение: MCP подключает ассистентов к продуктивным данным. Минимальные привилегии и аудиторские следы важнее «лишь бы заработало». Разделяйте серверы чтения и записи, разделяйте токены, прикладывайте фрагменты allowlist к тикету изменения.
PATH, cwd и bind-монты.memory_search или инструменты документации, чтобы сдерживать рост контекста.AGENTS.md — всё >1 требует подписанного исключения.На удалённых Mac или облачных хостах диск и ротация логов влияют на дочерние процессы MCP, которые пишут временные файлы на маленькие системные тома — таймауты могут казаться случайными при неизменной конфигурации модели. Смотрите эксплуатацию хоста вместе с настройкой инструментов.
Для HTTP/SSE-фронтов MCP учитывайте idle-таймауты reverse proxy, обработку Upgrade и завершение TLS: Gateway может залогировать успешное рукопожатие, пока edge отдаёт 499/504. Перед тем как только поднимать таймауты OpenClaw, сверьтесь с гайдом по reverse proxy Nginx/Caddy.
Ориентир сообщества (не бенчмарк): три тяжёлых MCP-сервера плюс широкая выборка часто дают джиттер очереди порядка минут — для SLA матрицы возможностей и allowlist лучше бесконечного числа плагинов.
Сон, пропадание VPN и дрейф путей делают дочерние процессы и индексы skills непредсказуемыми. Подключение реальных бизнес-данных требует аптайма 24/7, постоянных путей и прав, пригодных для аудита.
Самоуправляемые машины без выбора региона и гибких условий подталкивают к общим хостам, где cold start и IO логов конкурируют. Размещение Gateway на выделенном Apple Silicon с предсказуемыми дисками и исходящим трафиком — типичный выбор профессионального Mac-cloud. MACCOME сдаёт в аренду Mac mini M4 / M4 Pro в нескольких регионах на гибких условиях как стабильную базу для Gateway и сборочных ферм; перед заказом проверьте публичные цены и SLA центра помощи.
Прогоните три проверки из этого runbook на удалённом Mac до раската образа на всю флотилю — избегайте циклов «локально ок, в проде таймаут». Если Gateway смотрит в интернет, доставьте TLS, лимиты скорости и IP-allowlist в том же изменении, а не отдельным патчем позже.
FAQ
Как это сочетается с подключением каналов?
Гайды по каналам покрывают OAuth Slack/Discord/Telegram; эта статья — обнаружение инструментов. Если сообщения доходят до Gateway, а инструменты падают, сначала соберите доказательства из таблицы 1, прежде чем снова открывать кейсы «подключено, но тишина».
Что должно войти в откат?
Удалить записи MCP, задокументировать порядок перезапуска, выполнить проверочный запрос только чтения и убедиться по дашбордам, что счётчики инструментов вернулись к базовой линии. Сверьте биллинг с ценами аренды.
Пути в контейнере и на bare metal различаются — что делать?
Поддерживайте матрицу абсолютных путей на каждый runtime; не позволяйте модели угадывать пути в чате. Сопоставьте центр помощи со статьёй про Docker-тома.