Решение проблем агента

Копировать страницу Markdown llms.txt

Эта страница помогает быстро понять, что сломалось: подключение к клиенту, ключ, сервер или синхронизация сессий. Каждый раздел — симптом, причина, решение.

Первый шаг почти всегда один и тот же: выполнить status в терминале с теми же переменными, что в конфигурации клиента.

MMW_API_KEY=mmw_ваш_ключ \
  uvx --from https://app.mmwhub.ru/downloads/mmw-agent/mmw_agent-0.1.4-py3-none-any.whl mmw-agent status

Инструменты MMW не появились в клиенте

Причина 1: нет uvx или подходящего Python. Агент требует Python 3.11 и новее и запускается через uv.

Решение: установите uv, проверьте uvx --version в том же окружении, откуда запускается клиент, и перезапустите клиента. Графические клиенты (Claude Desktop) иногда не видят PATH терминала — тогда укажите в command полный путь к uvx.

Причина 2: не задан ключ. Агент сразу завершается с сообщением «Не задан MMW_API_KEY. Скопируйте ключ из личного кабинета MMW и укажите его в настройках MCP». Клиент показывает, что сервер не запустился.

Решение: добавьте MMW_API_KEY в блок env конфигурации (не в профиль оболочки — клиент его может не читать).

Причина 3: клиент не перезапущен. Список инструментов клиент запрашивает при запуске агента.

Решение: полностью перезапустите клиента после правки конфигурации.

Виден только `mmw_sync_status`, а сервер называется «MMW (офлайн, локальный агент)»

Причина: при запуске клиента сервер MMW был недоступен (нет сети, прокси, сервер перезапускался). Агент ответил клиенту сам, чтобы тот не упал, и отдал только локальный инструмент.

Решение: проверьте сеть и status. Агент сам пробует подключиться при каждом следующем вызове, но многие клиенты запоминают список инструментов при старте — перезапустите клиента, когда сервер снова доступен.

Вызов инструмента возвращает «Сервер MMW недоступен: …»

Причина: агент не смог отправить запрос на сервер (сеть, DNS, таймаут).

Решение: повторите позже. Если в конфигурации задан MMW_ENDPOINT, проверьте адрес. Синхронизация сессий в это время не теряет данные — она догонит автоматически.

«MMW отклонил API-ключ (проверьте MMW_API_KEY в настройках MCP)»

Причина: сервер ответил 401 или 403 — ключа нет, он отозван, истёк или скопирован не полностью. В организации доступ мог закончиться (увольнение, истёк срок подрядчика).

Решение: скопируйте ключ заново или выпустите новый в кабинете — см. Ключи и OAuth. Ключ показывается один раз; если он потерян, его нельзя «посмотреть ещё раз», только выпустить новый.

Та же причина у ошибки ServerError: 401 …, которую печатает mmw-agent status или mmw-agent sync.

Инструменты работают, но сервер пишет о подписке

Сообщения вида [MMW Notice]: … приходят с сервера, а не от агента:

Сообщение	Что значит
…has no active subscription, so memory is unavailable	Нет активной подписки — память недоступна.
…subscription has expired. Memory is read-only during the grace period	Подписка истекла: льготный период, только чтение — `search` работает, `remember` нет.
…account is suspended	Аккаунт приостановлен из-за истёкшей подписки.

Решение: продлите тариф в кабинете — Тарифы и оплата. Остальные ошибки сервера — в справочнике ошибок.

`consent` пишет «Согласие даёт человек в интерактивном терминале»

Причина: команду запустили не из интерактивного терминала — из скрипта, CI, IDE-задачи или её попыталась выполнить модель. Так задумано: согласие не может выдать программа.

Решение: откройте обычный терминал и выполните mmw-agent consent сами.

`consent` пишет «На этом компьютере не найдено сессий Claude Code и Codex»

Причина: агент ищет файлы в ~/.claude/projects/*/*.jsonl и ~/.codex/sessions/**/*.jsonl. Сессий там нет, или клиенты хранят их в другом домашнем каталоге (например, под другим пользователем).

Решение: поработайте в Claude Code или Codex, чтобы появились сессии, либо укажите каталог через MMW_SESSIONS_HOME — и в терминале, и в конфигурации клиента.

Согласие дано, но `last_cycle.state` = `consent_required`

Причина: терминал и клиент смотрят в разные каталоги состояния. Например, в конфигурации клиента задан MMW_AGENT_HOME или MMW_SESSIONS_HOME, а в терминале — нет.

Решение: выполните consent с теми же переменными, что в конфигурации клиента. Квитанция хранится в agent.json внутри MMW_AGENT_HOME (по умолчанию ~/.mmw).

Сессии Codex (или Claude Code) не загружаются

Причина: в согласие записываются только клиенты, чьи сессии были на диске в момент consent. Если Codex появился позже, его сессии не входят в согласие.

Решение: выполните mmw-agent consent ещё раз — агент покажет обновлённый список клиентов.

Ничего не загружается, хотя согласие есть

Спросите ассистента о статусе синхронизации (инструмент mmw_sync_status) и посмотрите last_cycle:

`state`	Причина	Что делать
`idle`	Агент только что запущен, цикла ещё не было.	Подождите до минуты.
`offline`	Сервер недоступен; пауза между попытками растёт до 5 минут.	Ничего: агент догонит сам.
`server_busy`	На сервере временно мало места, данные не приняты.	Ничего: агент повторит через 5 минут, данные остаются на диске.
`quota_exceeded`	Объём истории по тарифу исчерпан (`used_bytes`, `max_bytes`).	Смените тариф или примите, что новые сессии не загружаются.
`unsupported`	На сервере нет синхронизации сессий.	Проверьте `MMW_ENDPOINT`.
`error`	Непредвиденная ошибка; текст в поле `error`.	Агент повторит; если не проходит — напишите в поддержку.
`ok`	Цикл прошёл.	Смотрите счётчики ниже.

Счётчики при ok:

skipped_by_plan_history — сессии старше глубины истории тарифа, они пропускаются намеренно;
conflicts — файлы, которые на сервере уже приняты в другом виде; агент их пропускает;
truncated — файлы, которые стали короче принятой части (их перезаписали или обрезали); агент их не трогает.

Помните, что синхронизация идёт только пока запущен агент, то есть пока открыт клиент. Разовый цикл: mmw-agent sync.

`revoke` пишет «Локальное согласие удалено; сервер не уведомлён»

Причина: сервер был недоступен в момент отзыва.

Решение: загрузка уже остановлена — локальной квитанции нет. Повторите mmw-agent revoke, когда сеть появится, чтобы сервер тоже снял регистрацию устройства.

Подсказки агента на другом языке

Причина: язык выбирается по адресу сервера: для mmwhub.ru — русский, для остальных — английский.

Решение: задайте MMW_LANG=ru или MMW_LANG=en.

Что дальше

Ошибки сервера Коды и тексты ошибок remember, search и других инструментов.

Настройка агента Все переменные окружения с примерами.

Поддержка Как написать нам и что приложить.