🇬🇧 English version — каноническая версия, она может быть новее.
Конфигурация
Iva настраивается одним файлом: .env в директории установки. Мастер установки заполняет его за вас — любой шаг можно переиграть командой iva config (cli.md). Шаблон — .env.example в корне репозитория. На этой странице описана каждая переменная.
Смена модели, ключа или провайдера требует только перезапуска. Iva читает эти настройки .env при старте. После правки:
iva restartСменить модель, ключ или провайдера — это правка → перезапуск, без пересборки.
MEMORY_NIGHT_TIME=HH:mm задаёт местное время единственного Schedule memory-night в ASSISTANT_TIMEZONE (по умолчанию 04:00; строго 00:00..23:59). Это настройка сборки: после правки .env запустите iva update --force; в чекауте разработчика — npm run build и iva restart. Одна правка .env не меняет ни Schedule, ни догон. /menu → ⏰ показывает активное расписание и время, ожидающее пересборки. Schedule и догон читают один артефакт сборки; неудачная сборка или откат сохраняют прежнее время. Старые сборки без артефакта сохраняют 04:00.
Одно исключение — язык ответов. Кнопка 🌐 Язык в /menu пишет data/settings.json, который оба процесса перечитывают на лету — смена срабатывает сразу, без перезапуска. См. menu.md.
Провайдер модели
Шесть провайдеров. Выберите один через MODEL_PROVIDER и заполните только его блок. ollama/opencode/openrouter — API-ключ (OpenAI-совместимы); codex — личная подписка OpenAI (ChatGPT) по OAuth, без ключа; claude — подписка Claude Pro/Max через CLI claude, залогиненный на том же сервере, тоже без ключа; custom — любой OpenAI-совместимый эндпоинт, адрес которого вы задаёте сами. Цены и полные списки моделей: providers.md.
| Переменная | По умолчанию | Заметки |
|---|---|---|
MODEL_PROVIDER | ollama | ollama (Ollama Cloud), opencode (OpenCode Go), openrouter (OpenRouter), codex (подписка OpenAI ChatGPT), claude (подписка Claude Pro/Max через CLI claude) или custom (свой OpenAI-совместимый эндпоинт). |
OLLAMA_API_KEY | — | Ключ с ollama.com. |
OLLAMA_MODEL | deepseek-v4-pro | Любая модель вашего тарифа Ollama Cloud. |
OLLAMA_VISION_MODEL | gemma4:31b | Модель, которая описывает входящее фото. Текстовая модель обычно картинки не видит, поэтому зрение работает на своей модели и на том же ключе. Пусто = дефолт. |
OLLAMA_CONTEXT_WINDOW | 131072 | См. предупреждение ниже. |
OPENCODE_API_KEY | — | Ключ с opencode.ai/auth. |
OPENCODE_PROTOCOL | chat-completions | Протокол текстовой модели Go: chat-completions или responses, по таблице Go. Один ключ и OPENCODE_MODEL; iva config проверяет Responses выбранным протоколом. /model сохраняет выбор протокола. /messages не поддерживается. После ручной правки — iva restart. |
OPENCODE_VISION_PROTOCOL | chat-completions | Отдельный протокол запасной OPENCODE_VISION_MODEL: chat-completions или responses. Текстовая модель сначала проверяется на зрение своим протоколом. qwen3.7-plus теперь требует /messages: выберите совместимую vision-модель; отказ явно сообщает причину. |
OPENCODE_MODEL | deepseek-v4-pro | Любая модель Go, bare ID (напр. kimi-k3) — iva config показывает живой список. |
OPENCODE_VISION_MODEL | qwen3.7-plus | То же для OpenCode Go, bare ID. Берите из тех моделей, что реально читают картинки — многие модели Go отвечают на фото 400, а часть подмешивает в описание своё рассуждение. |
OPENCODE_CONTEXT_WINDOW | 131072 | То же предупреждение. |
OPENROUTER_API_KEY | — | Ключ с openrouter.ai/keys (начинается с sk-or-). |
OPENROUTER_MODEL | openai/gpt-5.1 | Слаг модели с openrouter.ai/models, вид vendor/model (напр. anthropic/claude-sonnet-5.5). iva config шлёт живой тест-запрос, чтобы кривой слаг не проскочил. |
OPENROUTER_VISION_MODEL | google/gemini-2.5-flash | То же для OpenRouter — любой слаг, принимающий картинки. iva config его живьём не проверяет. |
OPENROUTER_CONTEXT_WINDOW | 131072 | То же предупреждение — впишите реальное окно выбранной модели. |
CODEX_MODEL | gpt-5.5 | Модель вашего тарифа OpenAI. iva config покажет реальный список подписки. |
CODEX_CONTEXT_WINDOW | 272000 | То же предупреждение — впишите реальное окно выбранной модели. |
CLAUDE_MODEL | claude-fable-5-1 | Одна из четырёх: Fable 5.1 (claude-fable-5-1, по умолчанию), Opus 5.5 (claude-opus-5-5), Sonnet 5.5 (claude-sonnet-5-5) или Haiku 5.5 (claude-haiku-5-5). iva config показывает те, что пикер CLI реально отдал. |
CLAUDE_CONTEXT_WINDOW | 1000000 | То же предупреждение — 1000000 у Fable 5.1, Opus 5.5, Sonnet 5.5 и Haiku 5.5. |
CLAUDE_COMMAND | (пусто) | Путь к бинарю claude или команда с аргументами. Пусто — берётся claude из PATH сервиса. |
CLAUDE_SESSION_CWD | (включено) | Claude Code CLI выполняет все шаги одного диалога в одной приватной папке (<tmp>/iva-cwd-<uid>/<хэш сессии>, права 0700): CLI пишет рабочую папку в каждый запрос, и папка, новая на каждом шаге, заставляла кэш промпта записывать всю историю заново. 0, false, no или off выключает это, и каждый шаг снова идёт в своей временной папке. |
CUSTOM_BASE_URL | — | Обязательна для custom. OpenAI-совместимая база целиком, вместе с суффиксом вида /v1 — та же конвенция, что у https://ollama.com/v1 у Ollama. Пусто — агент останавливается на старте и называет эту переменную, дефолта не выдумывает. |
CUSTOM_API_KEY | — | Необязательна. Пусто = заголовок Authorization не отправляется вовсе, а это то, что обычно и нужно своему серверу. iva doctor её не требует. |
CUSTOM_MODEL | — | Обязательна для custom. Дефолта нет: что отдаёт этот эндпоинт, знаете только вы. Пусто — агент останавливается на старте, чужую модель не подставляет. |
CUSTOM_VISION_MODEL | (пусто) | Необязательна, дефолта нет: модель чата, которая видит картинки, спрашивается напрямую, и сюда вписывать нечего. Пусто оставляет запасной путь на самой модели чата — слепая просто не даст описания. Запасному вызову нужен CUSTOM_API_KEY; без ключа он пропускается. |
CUSTOM_CONTEXT_WINDOW | 131072 | То же предупреждение — впишите реальное окно выбранной модели. |
THINKING_EFFORT | (пусто) | Усилие размышлений: minimal, low, medium, high, xhigh, max. Пишется командами /model и /think в Telegram (cli.md), не руками. codex получает его нативно; ollama/opencode (chat-completions) шлют low/medium/high по OpenAI-совместимому протоколу, остальное игнорируют; при выборе openrouter или custom визард строку убирает вовсе, а вписанное руками значение там игнорируется. |
*_VISION_MODEL — запасной путь, а не основной. На первой входящей картинке Ива одним маленьким запросом спрашивает саму модель чата, принимает ли она картинки. Принимает — картинка идёт прямо ей, пикселями, без пересказа, и vision-модель не зовётся вовсе. Отвечает отказом — картинка уходит в *_VISION_MODEL, и модель получает её описание, как раньше. Ответ помнится до перезапуска процесса: после рестарта и после смены модели вопрос задаётся заново. Следствие смены на модель без зрения: у картинок, присланных раньше, описания не сохранено — при нужде перешлите фото заново.
Ровно эти шесть имён, буква в букву. Любое другое значение, включая опечатку и другой регистр, останавливает агента на старте и печатает список принятых имён, вместо того чтобы запустить Ollama под именем, которого никто не задавал. То же самое скажут iva doctor и экран «📊 Статус» в /menu (troubleshooting.md). Если строки MODEL_PROVIDER нет вовсе, это по-прежнему ollama.
Для custom ничего не угадывается: CUSTOM_BASE_URL и CUSTOM_MODEL — две строки, без которых провайдер не работает, и пустая из них это отказ на старте с именем переменной, а не тихий дефолт. THINKING_EFFORT намеренно не действует на custom: OpenAI-совместимость ничего не обещает про reasoning_effort, и слать его вслепую чужому эндпоинту — риск HTTP 400 на каждом ходу. Полный сценарий: providers.md.
Для codex ключа в .env нет: выполните iva login (по ссылке+коду, годится для headless-VPS) или iva login --browser. OAuth-токен лежит в data/codex-auth.json (chmod 600, в gitignore) и автоматически обновляется до истечения. Полный сценарий: providers.md.
Не завышайте контекстное окно. Ива сжимает разговор между ходами, когда вход хода доходит до 60% этого числа (или до 110 000 токенов, что меньше), а внутри хода страхуется порогом на четверть выше. Поставите больше реального окна модели — компактор включится слишком поздно: запрос переполнится раньше, чем история будет подрезана. Меняете модель — вписывайте её настоящее окно, а не круглое число побольше.
Команда /compact сворачивает свободный разговор с измеренным входом от 30 000 токенов. Ива подтверждает завершение, затем со следующим ответом показывает размер до и после свёртки по первому измеренному входу модели. Во время ответа повторите команду после его завершения. После перезапуска один законченный ход даст новый замер.
Telegram
| Переменная | По умолчанию | Заметки |
|---|---|---|
TELEGRAM_BOT_TOKEN | — | От @BotFather. |
TELEGRAM_BOT_USERNAME | — | Username вашего бота. Мастер проверяет токен через getMe и определяет его сам. |
TELEGRAM_WEBHOOK_SECRET_TOKEN | — | Общий секрет между long-poll-мостом и локальным вебхуком. Любая длинная случайная строка. |
TELEGRAM_ALLOWED_USER_IDS | (пусто) | Числовые ID пользователей через запятую — кому разрешено говорить с Iva. |
TELEGRAM_DIGEST_CHAT_ID | — | Чат для ночных отчётов памяти и разовых предложений стабильных обновлений. Обычно ваш собственный chat ID. Watch, Brief и провал задания с кнопкой «Починить» идут в личный чат (первый ID из TELEGRAM_ALLOWED_USER_IDS): в них почта и переписка, а кнопка принимается только там. |
SUPPORT_CHAT_URL | (пусто) | Ссылка-приглашение в чат поддержки, куда скилл report-problem предлагает прийти при сбое; пусто - Ива честно скажет, что адрес не настроен. |
TELEGRAM_RICH_REPLIES | auto | auto шлёт ответ в текущий чат rich-сообщением, когда в нём есть таблица, чек-лист, <details> или блочная формула; never оставляет такие ответы на обычном HTML/plain-пути. Любое другое значение останавливает старт. iva post не затронут. |
Список разрешённых работает по принципу fail-closed: пустой список — Iva не отвечает никому. Мастер сам подхватывает ваш ID, как только вы напишете боту; или спросите у @userinfobot. Почему fail-closed важен: security.md.
В 10:00 по ASSISTANT_TIMEZONE Iva без обращения к модели проверяет Git upstream. Пока новой стабильной версии MAJOR.MINOR.PATCH нет, сообщений не будет; каждую новую версию Iva предлагает только один раз. Если TELEGRAM_DIGEST_CHAT_ID пуст, используется первый доверенный ID.
Голос
| Переменная | По умолчанию | Заметки |
|---|---|---|
DEEPGRAM_API_KEY | — | Необязательный. С console.deepgram.com. Расшифровывает голосовые, видеокружки и аудиофайлы; без него записи сохраняются, но не расшифровываются. Мастер даёт пропустить (Enter); добавить потом в /menu → 🎤 Голос или iva config. Бесплатный тариф: providers.md. |
DEEPGRAM_LANGUAGE | multi | multi сам определяет язык каждого сообщения (ru/uz/en и другие). Фиксируйте один код вроде en, только если автоопределение спотыкается на вашей смеси языков. |
DEEPGRAM_KEYTERMS | — | Необязательный. Имена и термины, которые Deepgram должен писать как у вас, через запятую: OJ,Sonnet,Todoist. Каждое уходит в запрос как keyterm (Keyterm Prompting у nova-3); в запрос идут первые, пока их не больше 50 и вместе не больше 500 знаков: сверх лимита на keyterm Deepgram отказывает всему запросу. В .env помещается только латиница. Keyterm Prompting Deepgram берёт в счёт отдельной поминутной доплатой. Задаётся в /menu → 🎤 Голос. |
Поиск
| Переменная | По умолчанию | Заметки |
|---|---|---|
SEARCH_PROVIDER | tavily | tavily, exa, parallel или brave. |
TAVILY_API_KEY EXA_API_KEY PARALLEL_API_KEY BRAVE_API_KEY | — | Ключ соответствующего провайдера. Ключи могут лежать все сразу; смена провайдера — это только флаг. |
Нет ключа у активного провайдера — web_search вернёт понятную ошибку, ничего не упадёт. Бесплатные тарифы и сравнительная таблица: providers.md.
Память
| Переменная | По умолчанию | Заметки |
|---|---|---|
MEMORY_SEARCH_MODE | grep | grep = BM25 поверх встроенного в Node SQLite FTS5 плюс переранжировка по графу. Ноль внешних зависимостей, ноль ключей, работает на сервере за $4. hybrid добавляет векторные эмбеддинги — один внешний ключ. |
JINA_API_KEY | — | Для hybrid. Jina jina-embeddings-v3: политика no-train, хостинг в ЕС. |
DEEPINFRA_API_KEY | — | Для hybrid. Дешевле, отдаёт BAAI/bge-m3. Хватит одного из двух ключей. |
MEMORY_EMBED_PROVIDER | (авто) | Переопределить автовыбор: jina или deepinfra. |
MEMORY_EMBED_MODEL | jina-embeddings-v3 | Имя модели эмбеддингов. |
MEMORY_EMBED_URL | — | Любой OpenAI-совместимый endpoint эмбеддингов, например локальная Ollama на http://127.0.0.1:11434/v1/embeddings — тогда внешний ключ вообще не нужен. |
Гибридный индекс собирает ночной проход Brain; чтобы собрать его прямо сейчас, запустите node --env-file=.env scripts/memory/embed-index.ts. Как поиск устроен на самом деле: memory.md.
Уведомления
То, что Iva говорит сама, живёт в data/settings.json, а не в .env - эти ключи пишет экран 🔔 Уведомления в /menu, а тумблер отчётов читается в конце каждого ночного прогона, ключ proactive — на каждом получасовом тике Watch, Brief и Insight - поэтому тап срабатывает без перезапуска.
| Ключ | По умолчанию | Заметки |
|---|---|---|
memoryReports.enabled | false | Ночной отчёт памяти (daily 04:00 и weekly пн 04:15) в Telegram. Выключено - vault всё равно пишется. |
proactive.enabled | true | Watch, Brief и Insight (Сама пишет). Выключено - нет всех трёх, сбои приходят. Остальное - iva proactive. |
proactive.briefTimes | ["08:30", "14:00"] | Обзор дня, HH:00 или HH:30, не больше двух; пусто — обзора нет. Команда /digest даёт Brief руками в любое время. |
proactive.insightTimes | [] | Insight (инсайт): одно время HH:00 или HH:30, лучше HH:30; пусто — выключено. Окно 3 ч в тихих часах — хода нет; и тумблер Инсайт в /menu → Уведомления. |
proactive.ceilingTokensPerDay | 0 | Ceiling дня для Watch, Brief и Insight в токенах их ходов (iva usage by-source); достигнут — в этот день нет Insight и Brief, Watch сообщает только сбои. 0 — выключен. |
Insight (инсайт): раз в день Ива собирает и прогоняет один черновик плагина под то, что вы делаете руками, и спрашивает, ставить ли, - ADR-0022.
Алерты - о проблемах (память не бэкапится, ночной проход не прошёл) и о новых версиях - приходят всегда: их нельзя выключить, но каждый говорит, что делать, и повторяется не чаще раза в неделю на проблему - ADR-0007.
Система
| Переменная | По умолчанию | Заметки |
|---|---|---|
AGENT_LANGUAGE | ru | en или ru. Язык ответов Iva, локаль дат и какой сид CORE.md берёт init-vault. Кнопка 🌐 Язык в /menu переопределяет его в рантайме через data/settings.json (перечитывается на каждом ходе) и дублирует выбор сюда, так что смена мгновенна — без перезапуска (menu.md). |
ASSISTANT_TIMEZONE | Asia/Almaty | Имя из базы IANA. Задаёт даты дневных транскриптов, два systemd watchdog-таймера, семь внутрипроцессных eve schedules и дату/время, которые Iva видит на каждом ходе. Экспортируется как TZ. |
ASSISTANT_VAULT_DIR | vault | Живая память: отдельный приватный git-репозиторий, открывается в Obsidian. |
ASSISTANT_DATA_DIR | data | Данные рантайма: tasks.json, лог токенов usage.jsonl. |
IVA_PORT | 8723 | Порт локального eve-сервера. Немодный нарочно — 3000/8000/8080 на типовом VPS обычно уже заняты docker и компанией. Меняйте через iva config, не руками: systemd-юнит прописывает порт буквально, и они должны совпадать (deploy.md). |
ASSISTANT_HOST | http://127.0.0.1:${IVA_PORT} | Где poll-мост и скрипты памяти ищут сервер. Меняйте, только если агент живёт на другом хосте. |
ASSISTANT_BEARER | (генерируется) | Общий секрет для session-маршрутов Eve. Setup/upgrade создают его, локальные клиенты читают автоматически. Не публикуйте. |
AGENT_BROWSER_MAX_OUTPUT | 24000 | Лимит символов на вывод agent-browser, чтобы один дамп страницы не съел контекстное окно. |
OpenCode Responses не отправляет THINKING_EFFORT: контракт reasoning для произвольных моделей Go не доказан; /think не предлагает уровни в этом режиме. Старые установки без обеих переменных сохраняют chat/completions, модели, ключи и данные.