Настройки

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

Порядок, в котором решается настройкаCopy Anchor Link

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

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

max 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_CACHE_DIR переносят всю установку, включая то, какая запись в ключнице соответствует профилю.

Что действует сейчасCopy Anchor Link

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

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

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

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

ФайлCopy Anchor Link

~/.config/max-cli/config.json, режим 0644. Его пишет max config set (ниже) или вы сами.

{
  "defaultProfile": "personal",
  "defaults": { "keepRunsForDays": 14 },
  "profiles": {
    "personal": { "limit": 50, "timeoutMs": 20000, "color": true },
    "work": { "limit": 10 }
  },
  "personal": {
    "defaults": { "sendsPerHour": 30 }
  },
  "bot": {
    "defaults": { "allow": ["send", "reaction"] },
    "profiles": { "shop": { "sendsPerHour": 200 } }
  }
}

• defaults — всем профилям, и личным аккаунтам, и ботам.
• profiles.<имя> — одному профилю, в какой бы роли он ни работал.
• personal.defaults, personal.profiles.<имя> — только командам личного аккаунта.
• bot.defaults, bot.profiles.<имя> — только командам max <имя> bot ….

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

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

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

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

Секрет в этот файл положить некуда. В схеме нет ни поля для токена, ни для телефона, ни для идентификатора чата: схема, в которой нет места секрету, надёжнее правила «не кладите сюда секрет».

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

max config set limit 50                 # профилю по умолчанию
max work config set record true         # профилю work
max config set keepRunsForDays 7 --defaults   # всем профилям сразу
max work config unset limit             # убрать; снова решает defaults или встроенное
max agent config set readOnly true      # профиль agent ничего не отправит
max shop config set --bot sendsPerHour 200    # только боту shop
max config set --personal --defaults limit 30 # всем личным аккаунтам
max config set defaultProfile work      # какой профиль без первого слова

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

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

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

{"error":{"code":"configuration_error","message":"/home/you/.config/max-cli/config.json is not a valid config:\n  profiles.default.limitt: unknown setting — the known ones are limit, timeoutMs, color, record, keepRunsForDays, readOnly, allow, sendsPerHour, senderColors, serve, mcpTools"}}

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

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

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

Посмотреть, что получилосьCopy Anchor Link

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

max config show
max config show --json

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

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

⚠ Это не проверка здоровья. Она читает файлы: не открывает кеш, не трогает ключницу и не связывается с MAX. Вопрос «жива ли сессия» стоит одного входа и относится к другой команде.

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

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

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

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

Три переменные каталогов дают полностью изолированную установку — это удобно для пробы, для второго аккаунта и для тестов:

export MAX_CONFIG_DIR=/tmp/max-try/config
export MAX_STATE_DIR=/tmp/max-try/state
export MAX_CACHE_DIR=/tmp/max-try/cache

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

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

ДальшеCopy Anchor Link

• commands.md — каждая команда и опция, и полная таблица кодов возврата
• sessions.md — как устроены профили и где лежит токен
• troubleshooting.md — что делать, когда не работает