Repository navigation
configuration reference
Эта страница нужна, когда требуется точное имя, тип, значение по умолчанию или область действия
настройки либо имя переменной окружения. Здесь перечислены все настройки, которые читает 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 формы подтверждения отсутствуют: 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.
-
Безопасность: что защищают
permissions, список получателей иsends_per_hour - Профили и вход: как устроены профили и где лежит токен
- Все команды: каждая команда и опция и полная таблица кодов возврата
- Решение проблем: что делать, когда не работает