Skip to content

configuration reference

github-actions[bot] edited this page Oct 14, 2026 · 1 revision

Справочник настроек

Эта страница нужна, когда требуется точное имя, тип, значение по умолчанию или область действия настройки либо имя переменной окружения. Здесь перечислены все настройки, которые читает max, все способы их переопределить и то, какое значение побеждает. Для обычных изменений и примера файла начните с руководства по настройкам. Как ведут себя команды, вывод и коды возврата, описано в контракте CLI.

Слова, которые встречаются на странице:

  • Раздел — часть файла настроек. defaults действует для всех профилей, profiles.<имя> — для одного профиля, personal.* — только для команд личного аккаунта, bot.* — только для команд бота.
  • Область действия — разделы, где настройка допустима. Настройка вне своей области — ошибка.
  • Источник — откуда взялось действующее значение: параметр, переменная окружения, раздел файла или встроенное значение.

Ни одна настройка не может хранить секрет: в файле нет поля для токена, номера телефона или идентификатора чата.

Короткий пример файла и полный, со всеми разделами и объяснением каждой части, — в руководстве по настройкам.

Какое значение побеждает

Параметр → переменная окружения → файл → встроенное значение. Один порядок на всю программу, в одном месте, чтобы никакая команда не могла решить иначе.

Внутри файла побеждает самая точная запись. Для команды личного аккаунта на профиле work: personal.profiles.work → profiles.work → personal.defaults → defaults. Для команды max work bot … — то же, но с bot вместо personal. Профиль старше раздела: запись про один аккаунт важнее записи про все.

max personal chats list --limit 5          # флаг: 5
MAX_PROFILE=personal max chats list   # переменная выбирает профиль
# "limit": 50 у профиля в файле — когда флага нет
# "limit": 30 в "defaults" — когда и у профиля нет
# 20 — когда нет ничего

Не у каждой настройки есть все способы. Таблица настроек говорит, какие есть.

Два исключения старше этого порядка:

  • MAX_TOKEN старше ключницы. Если переменная задана, берётся она — так это работает в CI.
  • MAX_CONFIG_DIR, MAX_STATE_DIR переносят настройки и вход max, включая то, какая запись в ключнице соответствует профилю.

Что действует сейчас

max config show            # профиль, какие профили есть, файл и каждая настройка
max work config show       # то же для профиля work
max shop config show --bot # то же для команд бота shop
max config show --json     # то же одним объектом

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

Против каждой настройки — откуда она: flag, default или config file: с ключом, из которого она прочитана, например config file: bot.profiles.test. Против профиля — first word, MAX_PROFILE, MAX_PROFILE_LOCK, config file: default_profile или none named — профиль не назван, и profile тогда null.

С --json в ответе есть и storeSettings — настройки общего архива (searchStemmers.*) и откуда они взяты: store или default.

--bot показывает настройки так, как их получит max <имя> bot …: у бота свой раздел и свой лимит отправок. Если файла нет, загрузка настроек сначала создаёт его с обычными значениями по умолчанию. Существующий файл не перезаписывается. Если задана одна из переменных MAX_*_DIR, команда скажет об этом в stderr: с ними у профиля другая запись в ключнице, и вход, сделанный без них, выглядит как «нет сессии».

⚠ В списке профилей — все, что есть на машине: названные в файле, со входом личным аккаунтом и с ботом, и у каждого — личный он, бот или оба.

⚠ Это не проверка здоровья. Команда читает файлы: не открывает кеш, не трогает ключницу и не связывается с MAX. Жива ли сессия, проверяет max personal doctor (первый шаг при проблемах).

Секретов в выводе нет: в файле настроек нет поля, куда их можно было бы положить.

Файл

~/.config/max-cli/config.json на Linux; пути на других системах — в руководстве по настройкам. Первая команда, читающая настройки, создаёт его с limit, keep_runs_for_days, sends_per_hour, update_check и skill_hint в defaults. Файл создаётся с правами 0600, а max personal config set записывает его с правами 0644: секретов в нём нет.

Имена настроек пишутся в snake_case: sends_per_hour, read_only, models.<назначение>.base_url. Файл со старыми именами (sendsPerHour, readOnly, baseUrl) первое же чтение переименовывает само, один раз и только если результат проходит проверку. Имена профилей, пути в permissions и назначения моделей не меняются. Одна настройка под обоими именами с разными значениями — ошибка.

{
  "default_profile": "personal",
  "defaults": { "keep_runs_for_days": 14 },
  "profiles": {
    "personal": { "limit": 50, "timeout_ms": 20000, "color": true },
    "work": { "limit": 10 }
  },
  "personal": {
    "defaults": { "sends_per_hour": 30 }
  },
  "bot": {
    "defaults": { "permissions": { "bot": "readonly", "bot.messages.send": "allow" } },
    "profiles": { "shop": { "sends_per_hour": 200 } }
  }
}
  • defaults — всем профилям, и личным аккаунтам, и ботам.
  • profiles.<имя> — одному профилю, в какой бы роли он ни работал.
  • personal.defaults, personal.profiles.<имя> — только командам личного аккаунта.
  • bot.defaults, bot.profiles.<имя> — только командам max <имя> bot ….
Поле Что делает Что перекрывает на один запуск По умолчанию
default_profile какой профиль, если первым словом ничего не названо и MAX_PROFILE не задан первое слово (max work …), MAX_PROFILE нет: без имени команда перечисляет профили
limit сколько записей показывать, когда --limit не передан --limit 20
timeout_ms сколько ждать ответа на один запрос — (--timeout — другое, см. ниже) берётся из транспорта
color цвет в терминале; без поля решается по тому, терминал ли это —; без поля цвет выключает NO_COLOR по терминалу
sender_colors в max personal messages свой цвет у каждого автора; вы — всегда голубым. Без color не действует. Только для личного аккаунта — false
catch_up_marks_read max personal inbox и max personal review отмечают прочитанным каждый показанный чат — до последнего показанного сообщения. Собеседник видит отметку. Только для личного аккаунта --mark-read, --no-mark-read false
search_catch_up после messages sync или ремонта разрывов готовит граф и установленные локальные векторы этого чата в заданных пределах. Модели не скачиваются, удалённые провайдеры не вызываются. Только для личного аккаунта --catch-up, --no-catch-up false
record записывать ли каждый запуск, как будто передан --record (диагностика) --record, --no-record false
keep_runs_for_days сколько дней хранятся записи запусков — 30
permissions уровни прав по ресурсам и командам: deny, readonly, ask, allow; более точный ключ имеет приоритет (ниже) —; --yes и --allow-dangerous только отвечают на ask, deny они не снимают всё allow, кроме: удаление, завершение других сессий и ещё несколько необратимых изменений — ask; автоответы replies.send — deny
sends_per_hour сколько сообщений профиль может отправить за час — вместе с пересылками, правками, закреплениями с уведомлением, удалёнными сообщениями, добавленными в группы людьми и принятыми заявками на вступление; сверх — отказ с кодом 8. Боту лимит задаётся только в разделе bot; без него бот не ограничен (защита от отправки) — 30, у бота — нет
requests_per_minute сколько запросов в минуту профиль делает к MAX — после первых 10 подряд, вместе во всех процессах этого профиля; 0 — без ограничения (ограничения и ожидания) MAX_REQUESTS_PER_MINUTE 20
serve запускать ли max personal serve в фоне, когда команде нужен MAX, а сервера нет. С MAX_TOKEN сервер не запускается. Только для личного аккаунта --serve, --no-serve true
transcribe_model какой моделью max personal messages transcribe распознаёт речь. Только в defaults --model у messages transcribe и рядом с --transcribe gigaam-v3
read_other_bots может ли бот читать копии других ботов, когда команда просит это --all-bots или --bots: false, true — всех, или список профилей ботов. Только в разделе bot (боты) —; --all-bots и --bots просят, поле разрешает false
update_check раз в сутки спрашивать npm, нет ли новой версии, и сказать об этом в терминале. Только в defaults: версия у программы одна на все профили —; выключают MAX_NO_UPDATE_CHECK, NO_UPDATE_NOTIFIER, CI true
skill_hint раз в сутки говорить агенту в stderr, что навыка max у него нет или он старше программы и что его ставит max skill install. Агента узнаём по переменной AI_AGENT или CLAUDECODE. Только в defaults — true
read_only, allow, mcp_tools старые настройки, читаются для совместимости; config migrate переводит их в permissions — после миграции изменять их нельзя
embedding_provider локальная модель (local) или openai --provider local
embedding_model модель векторов --model по сервису
embedding_base_url адрес API векторов --base-url по сервису
embedding_dims размер вектора, целое 1–65 536 --dims по модели
analysis_provider агент (agent), openai или anthropic build --provider agent
analysis_model модель анализа build --model нет; для --analyze задайте явно
analysis_base_url адрес API анализа build --base-url по сервису
models внешние модели по назначению (ниже) переменные MAX_MODELS_* нет
searchStemmers.cyrillic, searchStemmers.latin языки основ слов для поиска во всём общем архиве (ниже) — russian, english,spanish

⚠ timeout_ms и --timeout — разные вещи, и перепутать их дорого. timeout_ms — это сколько ждать один ответ от MAX. --timeout — сколько отведено команде целиком. Одно чтение — это подключение, INIT, LOGIN, разбор имени чата и сам запрос, поэтому время работы кратно timeout_ms и никогда ему не равно.

Записываются они по-разному нарочно, чтобы их нельзя было спутать: timeout_ms — число миллисекунд в файле, --timeout — длительность с единицей на командной строке (30s, 2m, 500ms). Единица обязательна: --timeout 30 отвергается, потому что рядом лежит поле в миллисекундах, а все остальные программы пишут так секунды — ошибиться можно в тридцать раз в любую сторону.

Поля для --timeout в файле нет: бюджет на команду — это про конкретный запуск, а не про привычку.

--page и --all поля не имеют, и это намеренно. Номер страницы, записанный в файл, нужен ровно один раз и потом мешает каждому следующему запуску. То же про --order у max personal contacts list: настройка contactOrder была бы вторым написанием того же самого. --limit поле имеет, потому что «сколько показывать» — это привычка, а не разовый выбор.

Права доступа

permissions — объект: каждый ключ — путь команды, каждое значение — уровень.

{ "profiles": { "work": { "permissions": { "messages": "readonly", "messages.delete": "allow" } } } }
Уровень Что происходит
deny ничего, даже чтение: отказ с кодом 5 до подключения
readonly чтение работает; изменение — отказ с кодом 5
ask вопрос в терминале, по умолчанию ответ «нет» (ниже)
allow действие выполняется без вопроса

Ключ — это путь команды: messages, messages.delete, messages.send, reactions, chats.members, contacts, account.sessions.end. Он начинается с ресурса — messages, reactions, polls, topics, chats, contacts, account, bot, conversations, tags, search, searches, tasks, replies, attachments, stats, store или metadata. У бота ключи начинаются с bot, например bot.messages.send. config set отклоняет неизвестный ключ команды, в том числе внутри целого объекта permissions, с кодом 2. config unset позволяет удалить старый неизвестный ключ. Чтение уже существующего файла с таким ключом предупреждает в stderr и продолжает работу.

Более точный ключ переопределяет ресурс. Пример выше разрешает чтение сообщений и удаление без подтверждения и запрещает остальные записи в сообщения. Контакты, чаты, реакции и другие ресурсы этим примером не ограничиваются. config show показывает действующие права и их источник.

Права из разных разделов файла складываются, но сначала решает ближайший раздел, потом длина ключа. Ключ, заданный у профиля, закрывает такой же ключ и все ключи под ним в personal.defaults, bot.defaults и defaults. Профиль agent здесь не удаляет сообщения: его messages закрывает messages.delete из defaults.

{
  "defaults": { "permissions": { "messages.delete": "allow" } },
  "profiles": { "agent": { "permissions": { "messages": "readonly" } } }
}

Это работает в обе стороны: messages: allow у профиля закрывает и messages.delete: deny из defaults, и тогда удаление снова спрашивает, как по умолчанию. Старые read_only и allow действуют в том разделе, где записаны.

По умолчанию разрешено всё, кроме нескольких изменений, которые трудно отменить. Спрашивают: messages.delete, bot.messages.delete, chats.delete, chats.clear, topics.enable, topics.delete и account.sessions.end. Автоответы не отправляют, пока вы не разрешите: replies.send — deny.

max personal config set permissions.messages.delete allow     # удалять без вопроса
max personal config set permissions.messages.send ask         # спрашивать перед каждой отправкой
max personal config unset permissions.messages.delete         # вернуть значение по умолчанию

Вопрос перед изменением

На уровне ask в терминале появляется вопрос с ответом по умолчанию «нет». Ответ за вас даёт флаг: --allow-dangerous — для необратимого удаления (сообщений, чата, его истории или темы), --yes — для любого другого изменения. В JSON-режиме вопроса нет: нужен один из этих флагов.

Через MCP

В MCP формы подтверждения отсутствуют: ask разрешает вызванную запись, deny и readonly по-прежнему запрещают её. --permission ключ=уровень временно переопределяет права процесса. Старые флаги подтверждения больше не определяют доступ; для CLI уровни ask по-прежнему требуют ответа или явного флага. Подключение описано в руководстве по MCP.

Старые настройки, которые ещё работают

read_only: true читается как readonly для каждого ресурса. Список в allow (send, forward, reaction, edit, pin, read, delete, groups, contacts, profile, folders, sessions) читается как allow для этих действий и readonly для остальных; удаление всё равно спрашивает. Ключ в permissions того же раздела важнее обоих. mcp_tools читается, но доступ больше не меняет.

Перевод старых настроек

Перед переводом старого файла можно посмотреть изменения:

max config migrate --dry-run
max config migrate

Миграция сохраняет действовавшие права, настройки MAX и отметки модерации; старые уровни правил forbid/flag/confirm становятся deny/ask/ask. --dry-run ничего не пишет. После появления permissions команды изменения read_only, allow и mcp_tools отказывают с указанием новой настройки. Под MAX_PROFILE_LOCK миграция всего файла запрещена; предпросмотр доступен.

Изменить, не открывая файл

max personal config set limit 50        # профилю personal
max work config set record true         # профилю work
max config set keep_runs_for_days 7 --defaults   # всем профилям сразу
max work config unset limit             # убрать; снова решает defaults или встроенное
max agent config set permissions.messages readonly  # чтение сообщений без записи
max shop config set --bot sends_per_hour 200    # только боту shop
max config set --personal --defaults limit 30 # всем личным аккаунтам
max config set default_profile work      # какой профиль без первого слова

Значение проверяется той же схемой, что и при чтении, до записи: max personal config set limit 0 откажет, и файл останется прежним. serve, sender_colors, catch_up_marks_read, search_catch_up и mcp_tools с --bot не принимаются: у бота нет ни сервера, ни цветов авторов, ни непрочитанного, а старое mcp_tools относится только к личному аккаунту.

Языки поиска

searchStemmers.cyrillic (russian или none) и searchStemmers.latin (english, spanish, оба через запятую — так по умолчанию — или none) хранятся не в файле настроек, а в общем архиве сообщений: они одни на все профили и на оба мессенджера. Поэтому --defaults, --personal и --bot с ними не принимаются, а под MAX_PROFILE_LOCK их менять нельзя. config unset возвращает встроенное значение. После смены выполните max personal store reindex — см. обслуживание архива.

Опечатка — это ошибка, а не умолчание

Неизвестное поле отвергается с именем поля и кодом configuration_error (возврат 3):

{"error":{"code":"configuration_error","reason":"config.invalid","message":"/home/you/.config/max-cli/config.json is not a valid config:\n  profiles.default.limitt: unknown setting — the known ones are limit, timeout_ms, color, record, keep_runs_for_days, read_only, allow, permissions, sends_per_hour, requests_per_minute, embedding_provider, embedding_model, embedding_base_url, embedding_dims, analysis_provider, analysis_model, analysis_base_url, models, sender_colors, catch_up_marks_read, search_catch_up, serve, mcp_tools"}}

Значение не того вида называет поле и то, что допустимо: profiles.default.limit: has to be a whole number, 1 or more, not "20".

Так сделано намеренно. Схема, которая молча выбрасывает непонятное поле, превращает опечатку в полдня недоумения: настройка «не работает», и никто не говорит почему.

Отсутствующий файл — не ошибка: это программа, которую не настраивали.

Переменные окружения

Переменная Что делает
MAX_PROFILE профиль на всю сессию оболочки; то же, что первое слово
MAX_PROFILE_LOCK запирает процесс на одном профиле: другой профиль — первым словом или через MAX_PROFILE — и config set --defaults получают отказ. Держит только там, где агент не может сам поменять окружение: в настройках MCP-клиента или в скрипте-обёртке. Агент с доступом к оболочке снимет переменную сам
MAX_TIMEOUT ограничение на команду целиком, на всю сессию оболочки; то же, что --timeout
MAX_REQUESTS_PER_MINUTE то же, что requests_per_minute, и сильнее файла
MAX_TOKEN токен напрямую, в обход ключницы — для CI и разовых запусков
MAX_BOT_TOKEN токен бота для max sales bot, в обход ключницы
MAX_CONFIG_DIR где лежат config.json и, при отсутствии ключницы, файл с токеном
MAX_STATE_DIR где лежат состояние профилей и каталог runs/
MAX_CACHE_DIR только прежний кэш: max personal doctor ищет там оставшийся файл. Для совместимости всё ещё меняет запись в ключнице; для общей копии используйте MESSAGING_STORE
MESSAGING_STORE файл общей локальной копии чатов, сообщений и расшифровок
WIRECAT_STATE_DIR папка WireCat, общая для всех CLI: локальная копия и модели речи
NO_COLOR выключает цвет, как и в любой другой программе
MAX_NO_UPDATE_CHECK, NO_UPDATE_NOTIFIER не спрашивать npm о новой версии; CI действует так же
MAX_EMBEDDING_*, MAX_ANALYSIS_*, MAX_MODELS_* настройки моделей (ниже)

Пустая строка — это не значение, а несуществующая переменная: MAX_PROFILE= то же самое, что MAX_PROFILE не задана.

Переменной для --json или для цвета нет, и это намеренно. Забытая в оболочке, она меняла бы вывод команды, которая об этом не просила, — а найти такое потом труднее, чем набрать флаг.

Отдельный набор настроек на время

Переменные каталогов дают отдельные настройки и состояние входа — это удобно для пробы, для второго аккаунта и для тестов. Общая локальная копия сообщений, та же, что у tg, от них не зависит: её отдельный файл задаёт MESSAGING_STORE. Модели речи остаются общими.

export MAX_CONFIG_DIR=/tmp/max-try/config
export MAX_STATE_DIR=/tmp/max-try/state
export MESSAGING_STORE=/tmp/max-try/wirecat.db

max personal setup            # этот токен не виден обычной установке
max personal chats list

⚠ И обратно тоже: обычная установка не видит эту сессию. Если переменные заданы в одном окне терминала и не заданы в другом, второе окно скажет «нет сессии» при живом токене.

Типы и области действия ключей

Область «профиль» включает defaults, profiles.<имя>, personal.defaults, personal.profiles.<имя>, bot.defaults и bot.profiles.<имя>, если строка не сужает её. Неизвестные ключи и значения неверного типа отклоняются. Значения по умолчанию приведены выше.

Ключ Допустимый тип или значение Область
default_profile строка с именем профиля корень файла
limit, timeout_ms, keep_runs_for_days, sends_per_hour целое число ≥ 1 профиль
requests_per_minute целое число ≥ 0 профиль
color, record, read_only boolean профиль
sender_colors, catch_up_marks_read, search_catch_up, serve boolean личный аккаунт
permissions объект путей команд и уровней deny, readonly, ask, allow профиль
allow массив разрешённых действий; старый формат профиль
mcp_tools массив contacts, polls, groups, profile; старый формат личный аккаунт
read_other_bots boolean или массив имён профилей только bot
update_check, skill_hint boolean только defaults
transcribe_model строковый id из max personal models audio list только defaults
embedding_provider local или openai профиль
embedding_model, analysis_model непустая строка, не более 200 символов профиль
embedding_base_url, analysis_base_url URL HTTP(S) без credentials, query и fragment профиль
embedding_dims целое 1–65 536 профиль
analysis_provider agent, openai, anthropic профиль
models объект назначений моделей; поля описаны ниже профиль
searchStemmers.cyrillic russian, none общий архив, через config set
searchStemmers.latin english, spanish, оба через запятую, none общий архив, через config set

Модели по назначению

models.<назначение> содержит только provider, model, base_url. Назначение — строчные латинские буквы, цифры и дефисы, с буквы в начале. default задаёт общие значения; analysis и replies переопределяют их по полям. Другие корректные имена можно сохранить заранее: это не включает отсутствующий use case. Без провайдера, либо с off, внешний вызов выключен.

Ключ Допустимое значение По умолчанию
models.<назначение>.provider off, openai, anthropic не задан; внешнего вызова нет
models.<назначение>.model непустая строка, не более 200 символов не задан; включённому провайдеру нужен явный id
models.<назначение>.base_url URL HTTP(S) без credentials, query и fragment адрес провайдера

В каждом поле сначала действует MAX_MODELS_<НАЗНАЧЕНИЕ>_PROVIDER, _MODEL или _BASE_URL, затем ближайшая запись файла для назначения, затем явные старые analysis* для analysis, затем переменные и записи models.default. Дефисы в имени назначения превращаются в _ для переменной окружения. Токены провайдера не входят в этот объект.

Настройки векторов и анализа независимы и могут различаться по профилям. Адрес — HTTP/S без встроенного пароля, query и fragment. Внешний сервис векторов получает и вопрос из MCP-поиска. Ключи задаются через models text key set openai|anthropic и не записываются в config.json. Обычный build внешнего анализа не запускает: нужен явный --analyze. Провайдеры и примеры — в руководстве по внешним моделям.

Переменные для настроек моделей

Семь старых полей поддерживают MAX_EMBEDDING_PROVIDER, MAX_EMBEDDING_MODEL, MAX_EMBEDDING_BASE_URL, MAX_EMBEDDING_DIMS, MAX_ANALYSIS_PROVIDER, MAX_ANALYSIS_MODEL, MAX_ANALYSIS_BASE_URL. Они действуют перед значениями файла; параметры команды сильнее них. MAX_MODELS_DEFAULT_PROVIDER, MAX_MODELS_DEFAULT_MODEL, MAX_MODELS_DEFAULT_BASE_URL задают общие поля нового формата; вместо DEFAULT можно указать назначение, например ANALYSIS. Пустая переменная не переопределяет настройку. Неверное значение возвращает configuration_error.

Дальше

Clone this wiki locally