Configuración

Puedes usar max sin crear un archivo de configuración. Un indicador es una opción del comando, como --limit 5. El valor predeterminado se usa si no la indicas. Una variable de entorno es un ajuste con nombre que tu terminal o agente pasa al programa. Guarda ajustes en un archivo cuando quieras reutilizarlos entre comandos.

No necesitas configurar nada: sin archivo ni variables funcionan los valores iniciales. El archivo sirve para evitar repetir opciones.

Prioridad de los ajustesCopy Anchor Link

Opción → variable de entorno → archivo → valor inicial. Toda la aplicación utiliza el mismo orden.

Dentro del archivo prevalece la entrada más específica. Para una cuenta personal en work: personal.profiles.work → profiles.work → personal.defaults → defaults. Para max work bot …, se sustituye personal por bot. Un ajuste específico del perfil prevalece sobre uno para todas las cuentas.

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

Dos excepciones explícitas:

• MAX_TOKEN prevalece sobre el llavero, para CI.
• MAX_CONFIG_DIR y MAX_STATE_DIR cambian configuración y acceso de max, incluida la entrada del llavero correspondiente al perfil.

Ajustes efectivosCopy Anchor Link

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

Cada ajuste indica su origen: flag, default o config file: con la clave, como config file: bot.profiles.test. El perfil muestra first word, MAX_PROFILE, MAX_PROFILE_LOCK, config file: defaultProfile o default.

max test config show --bot muestra lo usado por max test bot …, con sección y límite propios. configFound: false indica que no hay archivo y se aplican valores iniciales. Si hay variables MAX_*_DIR, aparece un aviso en stderr: al cambiar la entrada del llavero, una sesión creada sin ellas puede parecer inexistente.

No aparecen secretos: el archivo no dispone de campos para guardarlos.

ArchivoCopy Anchor Link

~/.config/max-cli/config.json, permisos 0644. Lo escribe max config set o puedes editarlo.

{
  "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: todos los perfiles, personales y bots.
• profiles.<имя>: un perfil, cualquiera que sea su función.
• personal.defaults, personal.profiles.<имя>: cuentas personales.
• bot.defaults, bot.profiles.<имя>: comandos max <имя> bot ….

⚠ timeoutMs y --timeout son distintos. El primero limita una respuesta de MAX; el segundo toda la orden. Conexión, INIT, LOGIN, resolución del chat y solicitud requieren varias esperas, por lo que la duración total puede multiplicar timeoutMs.

Los formatos difieren deliberadamente: timeoutMs es un número de milisegundos en el archivo; --timeout exige una unidad (30s, 2m, 500ms). --timeout 30 se rechaza para evitar confundir segundos y milisegundos, con errores de hasta treinta veces.

No hay campo para --timeout: el presupuesto corresponde a una ejecución, no a una preferencia duradera.

--page y --all no tienen campos de configuración. Guardar una página sirve una vez y molesta después. Tampoco --order de max contacts list tiene un duplicado contactOrder. --limit sí, porque es una preferencia estable.

No hay dónde guardar un secreto. Sin campos de token, teléfono ni ID de chat, el esquema impide almacenarlos en lugar de depender de una advertencia.

Cambiar sin abrir el archivoCopy 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      # какой профиль без первого слова

Los valores se validan con el mismo esquema antes de escribir. max config set limit 0 rechaza y deja el archivo intacto. serve, senderColors, mcpTools no aceptan --bot: no tiene servidor ni colores y mcpTools corresponde a la cuenta personal.

Las erratas son erroresCopy Anchor Link

Un campo desconocido se rechaza con su nombre y configuration_error, código 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"}}

Un tipo incorrecto identifica el campo y lo admitido: profiles.default.limit: has to be a whole number, 1 or more, not "20".

Ignorar campos desconocidos ocultaría erratas y haría perder tiempo buscando por qué no funciona un ajuste.

Un archivo inexistente no es un error: simplemente no has configurado la aplicación.

Comprobar el resultadoCopy Anchor Link

Las capas pueden dificultar saber qué valor prevaleció. Esta orden lo explica:

max config show
max config show --json

Muestra perfil y origen, ruta y existencia del archivo, perfiles disponibles y valores efectivos con su fuente.

⚠ Incluye todos los perfiles locales: configurados, cuentas personales con sesión y bots; cada uno marcado como personal, bot o ambos.

⚠ No comprueba la conexión. Lee archivos sin abrir la caché, consultar el llavero ni contactar con MAX. Validar una sesión requiere acceso y pertenece a otra orden.

Variables de entornoCopy Anchor Link

Una cadena vacía equivale a no definida: MAX_PROFILE= es como no establecer MAX_PROFILE.

Solo perfil y tiempo límite tienen variables equivalentes. Son decisiones del proceso. No habrá variables para --json o color: olvidarlas en el terminal cambiaría salidas sin que el comando lo pidiera.

Configuración temporal separadaCopy Anchor Link

Las variables de directorios separan configuración y estado de acceso para pruebas u otra cuenta. No afectan al almacén compartido con tg: su archivo se elige mediante MESSAGING_STORE. Los modelos de voz siguen compartidos.

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

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

⚠ También a la inversa: la instalación habitual no ve esta sesión. Una hora se perdió buscando una sesión válida porque las variables estaban establecidas en una ventana y no en otra.

Siguiente pasoCopy Anchor Link

• Referencia: comandos, opciones y códigos.
• Sesiones y perfiles: acceso y llavero.
• Solución de problemas: qué hacer ante errores.

MAX_CACHE_DIR solo corresponde a la caché antigua: max doctor busca allí el archivo restante. Por compatibilidad, todavía cambia la entrada del llavero; para la copia compartida nueva, usa MESSAGING_STORE.