Сессии и профили

Сессия — сохранённое подключение к вашему аккаунту MAX. Токен — секретный ключ авторизации: с ним CLI получает доступ к аккаунту без нового кода входа при каждой команде. CLI сохраняет токен в защищённом хранилище ключей операционной системы (keyring), а отдельный файл запоминает устройство, чтобы команды использовали одно подключение.

Перед первым входом откройте MAX на телефоне и войдите в нужный аккаунт. Для первого подключения используйте QR по инструкции ниже; ручной импорт токена — вариант для тех, у кого уже есть этот ключ.

Первый запускCopy Anchor Link

max setup --agent codex проверяет локальные каталоги, проводит через QR-вход, проверяет аккаунт и до пяти чатов и устанавливает навык агента. Варианты агента: codex, cursor, claude, gemini, all, none. Без параметра в терминале задаётся вопрос; машинный режим пропускает установку навыка. Инструкция max skill show доступна до входа.

Выделите около пяти минут. История скачивается отдельно после выбора чата и объёма; setup не запускает фоновый сервис. Повторный запуск проверяет существующую сессию. --method token|qr|qr-chrome|sms выбирает способ свежего входа; default setup — qr. QR и браузер требуют человека у локального терминала. Не передавайте токен аргументом. Если настройка прервана, повторите setup. При истёкшем токене явно выполните max session start qr; при недоступной ключнице сначала исправьте окружение по подсказке.

Откуда берётся токенCopy Anchor Link

max session start <способ> — четыре способа войти. Каким бы способом ни был получен токен, в ключницу он попадает только после того, как MAX его принял.

max session start qr

1. Оставьте QR-код видимым на компьютере — в терминале или в окне браузера, которое открыла команда.
2. На телефоне откройте MAX и выберите аккаунт, который хотите подключить.
3. Перейдите в Настройки → Устройства и откройте сканер для входа по QR. Названия пунктов могут отличаться в вашей версии приложения.
4. Отсканируйте QR на компьютере сканером внутри MAX и подтвердите подключение, если появится запрос.
5. Если MAX запрашивает дополнительный пароль аккаунта, введите его по запросу терминала; символы не отображаются.
6. Дождитесь успешного завершения команды. Проверьте аккаунт через max account show, затем прочитайте несколько чатов через max chats list --limit 5.

Официальная инструкция входа MAX.

qr-chrome и sms — самые осторожные. Вход делает сам web.max.ru в настоящем браузере, и MAX видит свой собственный веб-клиент. Браузер запускается с отдельным временным профилем, а не с вашим; как только web.max.ru вошёл, окно закрывается, а профиль удаляется — и при Ctrl-C тоже. Закрытие окна не завершает сессию: это как закрыть вкладку. Браузер ищется сам; другой можно указать в MAX_BROWSER. Браузеры из snap не подходят — у них своя папка /tmp.

qr просит код у MAX нашим собственным соединением, изображая веб-клиент. Он работает без браузера, но это уже не настоящий веб-клиент.

Вход по SMS — только через браузер. Когда SMS просит наше соединение, MAX требует капчу, а её можно пройти только на странице.

После любого из трёх входов в списке сессий приложения MAX появится новое устройство. Если у аккаунта есть облачный пароль, qr спросит его без эха, до трёх раз; потом код придётся сканировать заново.

Все три требуют человека у терминала: без него команда откажет с кодом 2. Для скриптов и агентов остаётся token. Пока задана MAX_TOKEN, они тоже откажут: она старше ключницы и перекрыла бы новую сессию.

Токен вручнуюCopy Anchor Link

max session start без способа импортирует токен, который уже выдан официальным клиентом — веб-версией web.max.ru или другим клиентом, — и кладёт его в ключницу. Он работает и тогда, когда вход упирается в капчу или в необычный второй фактор.

max session start
MAX token: ▏          # ввод не отображается

Токен не передаётся аргументом. Аргумент команды виден в ps любому процессу на машине и остаётся в истории оболочки. Поэтому он спрашивается у терминала без эха — или читается из трубы, если терминала нет:

pass show max/token | max session start

Для CI и разовых запусков есть переменная. Она старше ключницы: если MAX_TOKEN задана, берётся она, и в ключницу ничего не пишется. Фоновый сервер max serve с ней не запускается: команда подключается к MAX сама.

MAX_TOKEN="$(cat /path/to/token)" max chats list --json

Проверить и забытьCopy Anchor Link

max account show      # кто вы: id, имя, телефон
max session end       # забыть токен на этой машине

session end стирает токен локально и ничего не сообщает серверу. Сессия, открытая в браузере, продолжает работать — это видно и в ответе:

{ "profile": "default", "forgotten": true, "revokedOnServer": false }

Разница не косметическая: забытый токен, который всё ещё живёт на сервере, — это не то же самое, что отозванный.

ПрофилиCopy Anchor Link

Профиль хранит свой токен и своё состояние; локальная копия сообщений общая, с данными по аккаунтам. Называется первым словом, а не флагом:

max chats list              # профиль default
max personal chats list     # профиль personal
export MAX_PROFILE=personal # или на всю сессию оболочки

Правило: первое слово — это профиль, если оно не совпадает с именем команды. Поэтому профиль нельзя назвать chats, runs или session — такое имя отвергается при создании, пока это ещё можно объяснить. Потом max chats молча значило бы «профиль chats без команды».

Если первое слово не команда и команды за ним нет, программа не показывает справку молча, а говорит, что произошло:

"nonsense" is not a command, so it was read as a profile name — and no command followed it.
Run `max --help` for the commands, or `max nonsense account show` if "nonsense" is your profile.

Где что лежитCopy Anchor Link

Личность устройства записывается при первом же чтении, до того как будет использована. Клиент, который представляется MAX новым устройством на каждую команду, — это не подражание настоящему клиенту, и сессии на стороне сервера привязаны именно к нему.

⚠ MAX_CONFIG_DIR, MAX_STATE_DIR и MAX_CACHE_DIR переносят и запись в ключнице: под капотом меняется имя службы. Сессия, сохранённая с этими переменными, не видна команде, запущенной без них, и наоборот. Либо ставьте их всегда, либо никогда.

Если ключницы нетCopy Anchor Link

На машине без ключницы (типичный контейнер) запись не удаётся — тогда токен ложится в файл credentials.json рядом с настройками, с правами 0600, и команда говорит об этом одной строкой на stderr.

В CI правильнее не полагаться ни на то, ни на другое и передавать MAX_TOKEN.

Сколько живёт токенCopy Anchor Link

MAX не сообщает фиксированный срок истечения токена, поэтому CLI не может обещать конкретное число дней. Закрытие вкладки web.max.ru не завершает авторизацию. Если MAX перестал принимать сохранённый токен, подключитесь заново по QR:

max session start qr

Для рабочего профиля используйте max work session start qr. Затем проверьте аккаунт командой max account show или max work account show. Команда max session start без способа импортирует существующий токен, а не показывает QR-код. Число входов для профиля показывает max doctor.

ДальшеCopy Anchor Link

• usage.md — первые команды
• configuration.md — настройки и порядок их разрешения
• security.md — что попадает на диск, а что не попадает никогда