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

> Симптом, причина и решение для типичных проблем mmw-agent — по тому, как агент ведёт себя на самом деле.

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

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

```bash
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](https://docs.astral.sh/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](/account/api-keys-and-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 | Аккаунт приостановлен из-за истёкшей подписки. |

**Решение:** продлите тариф в кабинете — [Тарифы и оплата](/account/plans-and-billing/). Остальные ошибки сервера — в [справочнике ошибок](/reference/errors/).

## `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`. | Агент повторит; если не проходит — напишите в [поддержку](/account/support/). |
| `ok` | Цикл прошёл. | Смотрите счётчики ниже. |

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

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

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

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

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

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

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

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

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

Отправляя вопрос в поддержку, приложите вывод `mmw-agent status` и время ошибки. Ключ и содержимое памяти не присылайте: `status` их не печатает, но конфигурационные файлы — содержат ключ.

## Что дальше