> 🇬🇧 [English version](../configuration.md) — каноническая версия, она может быть новее. # Конфигурация Iva настраивается одним файлом: `.env` в директории установки. Мастер установки заполняет его за вас — любой шаг можно переиграть командой `iva config` ([cli.md](../cli.md)). Шаблон — `.env.example` в корне репозитория. На этой странице описана каждая переменная. **Смена модели, ключа или провайдера требует только перезапуска.** Iva читает эти настройки `.env` при старте. После правки: ```bash 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](../menu.md). ## Провайдер модели Шесть провайдеров. Выберите один через `MODEL_PROVIDER` и заполните только его блок. `ollama`/`opencode`/`openrouter` — API-ключ (OpenAI-совместимы); `codex` — личная подписка OpenAI (ChatGPT) по OAuth, без ключа; `claude` — подписка Claude Pro/Max через CLI `claude`, залогиненный на том же сервере, тоже без ключа; `custom` — любой OpenAI-совместимый эндпоинт, адрес которого вы задаёте сами. Цены и полные списки моделей: [providers.md](../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](https://opencode.ai/docs/go/#endpoints). Один ключ и `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](https://openrouter.ai/keys) (начинается с `sk-or-`). | | `OPENROUTER_MODEL` | `openai/gpt-5.1` | **Слаг** модели с [openrouter.ai/models](https://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 выполняет все шаги одного диалога в одной приватной папке (`/iva-cwd-/<хэш сессии>`, права 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](../cli.md)), не руками. `codex` получает его нативно; `ollama`/`opencode` (chat-completions) шлют `low`/`medium`/`high` по OpenAI-совместимому протоколу, остальное игнорируют; при выборе `openrouter` или `custom` визард строку убирает вовсе, а вписанное руками значение там игнорируется. | `*_VISION_MODEL` — запасной путь, а не основной. На первой входящей картинке Ива одним маленьким запросом спрашивает саму модель чата, принимает ли она картинки. Принимает — картинка идёт прямо ей, пикселями, без пересказа, и vision-модель не зовётся вовсе. Отвечает отказом — картинка уходит в `*_VISION_MODEL`, и модель получает её описание, как раньше. Ответ помнится до перезапуска процесса: после рестарта и после смены модели вопрос задаётся заново. Следствие смены на модель без зрения: у картинок, присланных раньше, описания не сохранено — при нужде перешлите фото заново. Ровно эти шесть имён, буква в букву. Любое другое значение, включая опечатку и другой регистр, останавливает агента на старте и печатает список принятых имён, вместо того чтобы запустить Ollama под именем, которого никто не задавал. То же самое скажут `iva doctor` и экран «📊 Статус» в `/menu` ([troubleshooting.md](../troubleshooting.md)). Если строки `MODEL_PROVIDER` нет вовсе, это по-прежнему `ollama`. Для `custom` ничего не угадывается: `CUSTOM_BASE_URL` и `CUSTOM_MODEL` — две строки, без которых провайдер не работает, и пустая из них это отказ на старте с именем переменной, а не тихий дефолт. `THINKING_EFFORT` намеренно не действует на `custom`: OpenAI-совместимость ничего не обещает про `reasoning_effort`, и слать его вслепую чужому эндпоинту — риск HTTP 400 на каждом ходу. Полный сценарий: [providers.md](../providers.md#your-own-openai-compatible-endpoint-custom). Для `codex` ключа в `.env` нет: выполните `iva login` (по ссылке+коду, годится для headless-VPS) или `iva login --browser`. OAuth-токен лежит в `data/codex-auth.json` (chmod 600, в gitignore) и автоматически обновляется до истечения. Полный сценарий: [providers.md](../providers.md#openai-by-chatgpt-subscription-codex). **Не завышайте контекстное окно.** Ива сжимает разговор между ходами, когда вход хода доходит до 60% этого числа (или до 110 000 токенов, что меньше), а внутри хода страхуется порогом на четверть выше. Поставите больше реального окна модели — компактор включится слишком поздно: запрос переполнится раньше, чем история будет подрезана. Меняете модель — вписывайте её настоящее окно, а не круглое число побольше. Команда `/compact` сворачивает свободный разговор с измеренным входом от 30 000 токенов. Ива подтверждает завершение, затем со следующим ответом показывает размер до и после свёртки по первому измеренному входу модели. Во время ответа повторите команду после его завершения. После перезапуска один законченный ход даст новый замер. ## Telegram | Переменная | По умолчанию | Заметки | | ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TELEGRAM_BOT_TOKEN` | — | От [@BotFather](https://t.me/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-сообщением, когда в нём есть таблица, чек-лист, `
` или блочная формула; `never` оставляет такие ответы на обычном HTML/plain-пути. Любое другое значение останавливает старт. `iva post` не затронут. | Список разрешённых работает по принципу **fail-closed: пустой список — Iva не отвечает никому.** Мастер сам подхватывает ваш ID, как только вы напишете боту; или спросите у [@userinfobot](https://t.me/userinfobot). Почему fail-closed важен: [security.md](./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](../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](../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](./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/0022-insight-brings-one-capability-a-day.md). Алерты - о проблемах (память не бэкапится, ночной проход не прошёл) и о новых версиях - приходят всегда: их нельзя выключить, но каждый говорит, что делать, и повторяется не чаще раза в неделю на проблему - [ADR-0007](../adr/0007-notices-are-opt-in.md). ## Система | Переменная | По умолчанию | Заметки | | -------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AGENT_LANGUAGE` | `ru` | `en` или `ru`. Язык ответов Iva, локаль дат и какой сид CORE.md берёт `init-vault`. Кнопка **🌐 Язык** в `/menu` переопределяет его в рантайме через `data/settings.json` (перечитывается на каждом ходе) и дублирует выбор сюда, так что смена мгновенна — без перезапуска ([menu.md](../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](../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, модели, ключи и данные.