Skip to content

configuration reference

Jump to bottom
github-actions[bot] edited this page Nov 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 или none named — профиль не назван, и profile тогда null.

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

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

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

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

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

Файл

~/.config/max-cli/config.json на Linux; пути на других системах — в руководстве по настройкам. Первая команда, читающая настройки, — например config show, account list или chats list — создаёт его с limit, keep_runs_for_days, sends_per_hour, update_check и skill_hint в defaults. Файл создаётся и записывается max personal config set с правами 0600, каталог — 0700. max personal doctor называет файл или каталог, которые могут читать другие, в files.problems и печатает chmod, который это исправляет. max personal doctor файл только читает: если его нет, он отвечает config.found: false и не создаёт его.

Имена настроек пишутся в snake_case: sends_per_hour, keep_runs_for_days, models.<назначение>.base_url.

{
  "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 ….
Поле Что делает Что перекрывает на один запуск По умолчанию
limit сколько записей показывать, когда --limit не передан --limit 20
timeout_ms сколько ждать ответа на один запрос — (--timeout — другое, см. ниже) берётся из транспорта
color цвет в терминале; без поля решается по тому, терминал ли это —; без поля цвет выключает NO_COLOR по терминалу
sender_colors в max personal messages свой цвет у каждого автора; вы — всегда голубым. Без color не действует. Только для личного аккаунта — false
search_catch_up после messages sync или ремонта разрывов готовит граф и установленные локальные векторы этого чата в заданных пределах. Модели не скачиваются, удалённые провайдеры не вызываются. Только для личного аккаунта --catch-up, --no-catch-up false
history_dialog_days на сколько дней назад messages sync читает личный чат, от 1 до 1095 messages sync --full-history 1095
history_group_days на сколько дней назад messages sync читает группу, от 1 до 1095 messages sync --full-history 365
history_group_members_max историю группы, где людей больше, messages sync не читает; store status показывает, что пропущено. Новые сообщения от serve сохраняются всегда messages sync --full-history 50
history_muted читает ли messages sync --all и заглушённые чаты; без поля они пропускаются messages sync --all --with-muted false
picture_search искать картинки по тому, что на них, моделью на этом компьютере (max images embed, search); модель скачивается отдельно: max images models download clip-b32 — false
search_reranker какой моделью search messages --discover переставляет первые 50 результатов: mmarco, bge-reranker-v2-m3 или off. Действует, только когда модель скачана (max personal models download mmarco); сама она не скачивается — mmarco
record записывать ли удачные запуски; неудачные записываются и при false (диагностика) --record, --no-record true
record_input хранить ли в записи запуска командную строку так, как вы её набрали; false скрывает набранное, failed хранит его только у неудачных запусков, секреты скрыты всегда (диагностика) — true
keep_runs_for_days сколько дней хранятся записи неудачных запусков — 30
keep_successful_runs_for_days сколько дней хранятся записи удачных запусков — 7
keep_store_runs_for_days сколько дней хранятся записи удачных запусков, которые меняли хранилище, даже при record: false — 3
runs_size_limit_mb сколько мегабайт может занимать каталог запусков; сверх него сначала удаляются самые старые удачные — 200
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
embedding_provider локальная модель (local) или openai --provider local
embedding_model модель векторов --model по сервису
embedding_base_url адрес API векторов --base-url по сервису
embedding_dims размер вектора, целое 1–65 536 --dims по модели
models внешние модели по назначению (ниже) переменные MAX_MODELS_* нет
search_stemmers.cyrillic, search_stemmers.latin языки основ слов для поиска во всём общем архиве (ниже) — russian, english,spanish
task_first_pass_per_chat сколько задач правила могут открыть в каждом чате при первой синхронизации аккаунта, по истории; целое число от 0 до 1000. Позже читаются только новые сообщения, а tasks scan <чат> строит задачи по истории по вашей просьбе. Общая для всего архива — 0
task_agent_close, task_agent_close_min закрывает ли задачу агент, и с какой уверенностью из --certainty; ниже порога задача остаётся открытой с предложением закрыть (задачи). Общие для всего архива — on, 0.8

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

Записываются они по-разному нарочно, чтобы их нельзя было спутать: timeout_ms — число миллисекунд в файле, --timeout — длительность с единицей на командной строке (30s, 2m, 6h, 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, mentions, search, searches, tasks, replies, attachments, stats, store или metadata. У calls и stickers есть только чтение, и ключа права у них нет: config set отвечает кодом 2. У бота ключи начинаются с bot, например bot.messages.send. config set отклоняет неизвестный ключ команды, в том числе внутри целого объекта permissions, с кодом 2. Если такой ключ уже записан в файле, команды не запускаются: ошибка configuration_error называет ключ и команду config unset, которая его удаляет. config show, set и unset работают, чтобы файл можно было исправить.

Более точный ключ переопределяет ресурс. Пример выше разрешает чтение сообщений и удаление без подтверждения и запрещает остальные записи в сообщения. Контакты, чаты, реакции и другие ресурсы этим примером не ограничиваются. 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, и тогда удаление снова спрашивает, как по умолчанию.

По умолчанию разрешено всё, кроме нескольких изменений, которые трудно отменить. Спрашивают: 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.

mcp.authority ограничивает изменение настроек, правил, получателей и других условий будущих запусков; по умолчанию — deny. Команды остаются в каталоге; для их выполнения владелец задаёт allow или ask. Сырые операции бота отдельно требуют явного bot.api: allow или ask; общий bot: allow их не открывает. Агент не может менять эти ключи или заменять объект permissions целиком; отдельные остальные ключи можно менять при разрешённом mcp.authority.

Команды работы с хранилищем, управления сервером, скачивания моделей и создания отчётов имеют собственные ключи: например, store.backup, server.start, models.download, doctor.reports.create. Их уровень по умолчанию — ask.

Ответ «только чтение» при первом запуске ограничивает все профили всех инструментов WireCat, включая MCP. Более точный allow профиля это ограничение не снимает. Изменить ответ можно через max setup в терминале.

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

max personal config set limit 50        # профилю personal
max work config set record false        # профилю 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 personal config set limit 0 откажет, и файл останется прежним. serve, sender_colors и search_catch_up с --bot не принимаются: у бота нет ни сервера, ни цветов авторов, ни непрочитанного.

Языки поиска

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

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

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

{"error":{"code":"configuration_error","reason":"config.invalid","message":"/home/you/.config/max-cli/config.json: profiles.default.limitt is an unknown setting","retry":{"safe":false}}}

Значение не того вида называет поле, но не само значение — вдруг туда по ошибке вставлен токен: profiles.default.limit has the wrong type. Если ошибок несколько, названа первая, а остальные посчитаны: (and 2 more problems).

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

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

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

Переменная Что делает
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_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.<имя>, если строка не сужает её. Неизвестные ключи и значения неверного типа отклоняются. Значения по умолчанию приведены выше.

Ключ Допустимый тип или значение Область
limit, timeout_ms, keep_runs_for_days, keep_successful_runs_for_days, keep_store_runs_for_days, runs_size_limit_mb, sends_per_hour целое число ≥ 1 профиль
requests_per_minute целое число ≥ 0 профиль
history_dialog_days, history_group_days целое число от 1 до 1095 профиль
history_group_members_max целое число ≥ 1 профиль
color, record, history_muted, picture_search boolean профиль
record_input boolean или failed профиль
sender_colors, search_catch_up, serve boolean личный аккаунт
search_reranker mmarco, bge-reranker-v2-m3, off профиль
permissions объект путей команд и уровней deny, readonly, ask, allow профиль
read_other_bots boolean или массив имён профилей только bot
update_check, skill_hint boolean только defaults
transcribe_model строковый id из max personal models list kind:audio только defaults
embedding_provider local или openai профиль
embedding_model непустая строка, не более 200 символов профиль
embedding_base_url URL HTTP(S) без credentials, query и fragment профиль
embedding_dims целое 1–65 536 профиль
models объект назначений моделей; поля описаны ниже профиль
search_stemmers.cyrillic russian, none общий архив, через config set
search_stemmers.latin english, spanish, оба через запятую, none общий архив, через config set
task_agent_close on, off общий архив, через config set
task_agent_close_min число от 0 до 1 общий архив, через config set
task_first_pass_per_chat целое число от 0 до 1000 общий архив, через 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, затем ближайшая запись файла для назначения, затем переменные и записи models.default. Дефисы в имени назначения превращаются в _ для переменной окружения. Токены провайдера не входят в этот объект.

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

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

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

Дальше

Clone this wiki locally