Установка Vrio

Vrio — ИИ-агент для 1С:Предприятия. Эта инструкция проводит через установку от начала до работающего чата.

Знать 1С-разработку не требуется. Все шаги делаются в Конфигураторе, в терминале сервера и в веб-консоли.

Годятся и Linux, и Windows. Команды в основном одинаковы; там, где они различаются, приведены оба варианта — выбирайте свой. Действия внутри 1С от операционной системы не зависят вообще.

Ориентировочное время выполнения — один час.

Прежде чем начинать, прочитайте раздел Веб-консоль в документации. Установка почти целиком сводится к работе в ней: там регистрируются базы, скачивается расширение, допускаются сотрудники, заводятся языковые модели. Полчаса на чтение избавят от возврата к каждому шагу с вопросом «а зачем я это сейчас нажал».

Из чего состоит Vrio

Четыре части. Три вы разворачиваете, четвёртая внешняя.

   1С:Предприятие                    Ваш сервер                    Языковая модель
   ┌────────────────┐            ┌──────────────────┐         ┌──────────────┐
   │  Расширение    │  WebSocket │     Служба       │  HTTPS  │              │
   │    Vrio.cfe    │◄──────────►│   (контейнер)    │◄───────►│  ваш провайдер
   │                │  порт 8765 │                  │         │  или ваш сервер
   │  чат, роли,    │            │  ┌────────────┐  │         │              │
   │  выполнение    │            │  │  Консоль   │  │         └──────────────┘
   │  команд        │            │  │ /console   │  │
   └────────────────┘            │  └────────────┘  │
                                 └──────────────────┘

Часть	Что делает	Где живёт
Служба	Мозг агента. Держит связь с языковой моделью, ведёт диалог, решает, что делать, и превращает решение в команду для 1С. Хранит переписку, настройки и журнал действий	Контейнер Docker на вашем сервере
Расширение 1С	Руки агента внутри базы. Чат, роли доступа, исполнение команд, чтение данных, построение форм. Ставится в каждую базу отдельно	Файл `Vrio.cfe`, скачивается из консоли и загружается в информационную базу
Веб-консоль	Рабочее место администратора. Регистрация баз, допуск людей, модели, журнал действий, лицензия	Внутри службы, адрес `/console`
Языковая модель	Собственно интеллект. Служба обращается к ней по сети. В комплект поставки не входит	Ваш провайдер или ваш собственный сервер

Две вещи, которые стоит понять сразу. Изменяющие операции выполняются только после подтверждения человеком, и каждое действие пишется в журнал — без записи в журнал команда не выполняется вообще. За периметр уходит только то, что отправляется в языковую модель; если модель развёрнута у вас в сети, наружу не уходит ничего.

Что нужно в 1С

1С:Предприятие 8.3.27 или новее, режим совместимости конфигурации — не ниже 8.3.27. На более ранних расширение не загрузится, и настройками это не обходится.

Что нужно на сервере

Доступ к Docker Hub. Служба опубликована там как itworksgroup/vrio, и вместе с ней приходит комплект для установки: файлы настроек и скрипты обновления (шаг 1). Со страницы сайта ничего скачивать не нужно.

Комплект один для обеих редакций: без лицензионного ключа служба работает как свободная редакция, ключ Pro (пробный или купленный) вводится потом в консоли.
Docker версии 20 и новее с плагином compose. Проверить: docker --version и docker compose version. В Windows это Docker Desktop (потребуется WSL2) либо Docker Engine на Windows Server. Если не установлен — поставьте по инструкции производителя.
Права на работу с Docker. Администратор системы не нужен, но пользователь должен состоять в группе docker (Linux) или docker-users (Windows). После добавления в группу перезайдите в систему, иначе команды docker будут отвечать отказом в доступе.

Свободный порт 8765. Вывод должен быть пустым:

ss -lntp | grep :8765          # Linux
netstat -ano | findstr :8765   # Windows

Сетевой доступ с сервера до языковой модели. Адрес прописывается в .env на шаге 2. Если модель облачная — нужен интернет; если развёрнута у вас в локальной сети или на этом же сервере — интернет не нужен, достаточно доступа до неё по сети.
Около 2 ГБ свободного места.
Отдельная пустая папка для файлов службы — например /opt/vrio в Linux или C:\vrio в Windows. На шаге 1 в неё лягут docker-compose.yml, .env и скрипты обновления. Все команды инструкции выполняются из этой папки, создайте её и перейдите в неё до начала работы:
```
sudo mkdir -p /opt/vrio && sudo chown "$USER": /opt/vrio && cd /opt/vrio   # Linux
```
```
mkdir C:\vrio; cd C:\vrio                                                  # Windows
```

Шаг 1. Получить комплект

В папке службы выполните одну команду:

docker run --rm --pull always itworksgroup/vrio:latest kit | tar -xk  # Linux

docker run --rm --pull always -v "${PWD}:/kit" itworksgroup/vrio:latest kit   # Windows

Команда скачивает образ службы с Docker Hub — около 180 МБ, входить в Docker Hub не нужно, образ открыт для скачивания — и кладёт в папку четыре файла:

docker-compose.yml — как Docker запускает службу. В строке image: записана точная версия образа, например itworksgroup/vrio:0.2.0-2026-10-14: служба не сменит версию сама, пока вы её не обновите;
.env — настройки, их вы заполните на шаге 2;
update.sh и update.ps1 — скрипты обновления для Linux и Windows.

Файлы, которые уже есть в папке, команда не перезаписывает.

Проверка. ls -la в Linux или dir в Windows показывает эти четыре файла. В Linux .env сразу закрыт от посторонних: читать и менять его может только тот, кто выполнил команду.

Шаг 2. Заполнить настройки

Откройте .env любым текстовым редактором. Заполнить нужно шесть строк, все про доступ к моделям. Значения берутся у того, кто модели вам предоставляет: облачного провайдера или вашего собственного сервера. В комплект поставки модели не входят, и ключ остаётся вашим.

Vrio работает с любым провайдером, совместимым с интерфейсом OpenAI, с моделью, развёрнутой в вашей сети, и с Claude по ключу Anthropic.

Строка	Что вписать
`VRIO_LLM_BASE_URL`	Адрес языковой модели
`VRIO_LLM_MODEL`	Название модели
`VRIO_LLM_API_KEY`	Ключ доступа
`VRIO_CONTEXT_WINDOW_TOKENS`	Число — зависит от модели
`VRIO_MEMORY_EMBEDDING_BASE_URL`	Адрес модели для памяти агента. Обычно тот же, что `VRIO_LLM_BASE_URL`
`VRIO_MEMORY_EMBEDDING_API_KEY`	Ключ для памяти агента. Обычно тот же, что `VRIO_LLM_API_KEY`

Выглядеть должно примерно так:

VRIO_LLM_BASE_URL=https://api.example.com/v1
VRIO_LLM_MODEL=some-model-name
VRIO_LLM_API_KEY=sk-abc123...
VRIO_CONTEXT_WINDOW_TOKENS=131072
VRIO_MEMORY_EMBEDDING_BASE_URL=https://api.example.com/v1
VRIO_MEMORY_EMBEDDING_API_KEY=sk-abc123...

Строки памяти заполняйте всегда, даже когда они повторяют адрес и ключ выше. Пустые служба заменяет адресом и ключом модели, и память молча ломается, как только модель сменят: на Claude или на поставщика без такой модели эмбеддингов. Агент при этом отвечает как обычно, просто ничего не запоминает.

Остальные строки в файле не трогайте — они уже настроены правильно.

Claude по ключу самой Anthropic. Три строки VRIO_LLM_… оставьте пустыми. Ниже них в файле есть три строки со знаком # в начале: VRIO_LLM_PROVIDER=anthropic, VRIO_CLAUDE_MODEL и VRIO_ANTHROPIC_API_KEY. Уберите # и впишите ключ в последнюю. Адрес и ключ для памяти агента в этом случае нужны от другого поставщика: у Anthropic нет моделей для памяти. Подойдёт любой поставщик, совместимый с интерфейсом OpenAI; название модели и её размерность задаются строками ниже в файле.

Не стирайте значение у числовой строки. Пустой VRIO_CONTEXT_WINDOW_TOKENS роняет службу при запуске с сообщением unable to parse string as an integer. Не знаете числа — поставьте 32768.

Windows, Блокнот: следите за кодировкой. В строке сохранения внизу есть выпадающий список; там должно быть UTF-8, а не ANSI. Иначе русские комментарии в файле превратятся в мусор.

Строку VRIO_MODEL_SECRET_KEY заполнять не нужно — оставьте пустой. Этим ключом служба шифрует чужие секреты в своей базе: API-ключи моделей и токены ботов. Если строка пуста, служба выпускает ключ сама при первом запуске и кладёт его в папку secrets рядом с docker-compose.yml.

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

Linux: создайте папку заранее и отдайте её службе. Иначе Docker создаст её от имени root, служба писать не сможет и положит ключ вместе с данными — работать будет, но разделения не получится.
mkdir -p secrets && sudo chown 1000:1000 secrets && chmod 700 secrets
Windows ничего делать не нужно — папка создастся сама и будет доступна на запись.

Закройте доступ к файлу посторонним — в нём ключи:

chmod 600 .env                                                # Linux

icacls .env /inheritance:r /grant:r "$env:USERNAME:(R,W)"     # Windows

Если команда icacls не отработала, те же права назначаются через интерфейс: правой кнопкой по файлу → Свойства → вкладка Безопасность → Дополнительно → отключить наследование и оставить в списке только текущего пользователя.

Если поставщик прислал .env уже заполненным — заполнение пропустите, но доступ к файлу закройте всё равно.

Шаг 3. Запустить службу

docker compose up -d

Подождите секунд двадцать и проверьте:

curl http://127.0.0.1:8765/health          # Linux
curl.exe http://127.0.0.1:8765/health      # Windows

В Windows указывайте именно curl.exe. Команда curl в PowerShell — это псевдоним другой команды, её вывод выглядит иначе и к проверке отношения не имеет.

Должно вернуться: {"status":"ok","version":"0.2.0"}

Если вернулось — служба работает. Если нет, посмотрите docker compose logs agent и загляните в раздел «Если что-то не работает» в конце.

Вторая проверка — что настройки из шага 2 дошли до службы:

docker compose exec agent printenv VRIO_LLM_BASE_URL VRIO_LLM_MODEL VRIO_LLM_API_KEY VRIO_MEMORY_EMBEDDING_BASE_URL VRIO_MEMORY_EMBEDDING_API_KEY

Должны напечататься пять непустых строк: адрес, название модели и ключ, затем адрес и ключ для памяти. С Claude первые три строки пустые, это нормально. Тогда проверьте ещё строки Claude, здесь тоже должны быть три непустые:

docker compose exec agent printenv VRIO_LLM_PROVIDER VRIO_CLAUDE_MODEL VRIO_ANTHROPIC_API_KEY

Пустой вывод означает, что .env не заполнен — вернитесь к шагу 2. Служба при этом запускается и выглядит исправной: /health отвечает штатно. Ошибка проявится только на шаге 10, когда чат сообщит о внутренней ошибке. Выполните проверку здесь, чтобы не искать причину позже. После правки .env выполните docker compose up -d — именно её, см. врезку в разделе «Обслуживание».

Проверьте, что ключ шифрования лёг в свою папку. Рядом с docker-compose.yml должен появиться файл secrets/master.key:

ls secrets

Пусто — значит служба не смогла туда писать и положила ключ вместе с данными. Ничего не сломано, работать будет, но разделения не получится; как это исправить, написано на шаге 2.

Служба запускается автоматически при перезагрузке сервера — это уже настроено.

Консоль администратора

Часть настройки делается в веб-консоли: в ней видны подключённые базы и список пользователей 1С. В .env она уже включена — остаётся завести учётную запись для входа.

docker compose exec agent python -m vrio_agent.admin.user_admin create-admin --username admin

Команда спросит пароль — при вводе он не отображается, это нормально. Должно ответить created admin 'admin' (…).

Запишите пароль. Прочитать его обратно нельзя, можно только задать новый:

docker compose exec agent python -m vrio_agent.admin.user_admin set-password --user admin

Предупреждение Password input may be echoed перед запросом пароля означает, что вводимые символы будут отображаться на экране. Команда при этом работает штатно; убедитесь в отсутствии посторонних либо повторите её из терминала на сервере.

Консоль открывается по адресу http://127.0.0.1:8765/console — с самого сервера. Если сервер Windows или Linux с графической оболочкой, просто откройте этот адрес в браузере на нём.

Если графической оболочки нет (обычный случай для Linux), пробросьте порт на свой компьютер:

ssh -L 8765:127.0.0.1:8765 <пользователь>@<адрес сервера>

Не закрывая это подключение, откройте в своём браузере http://localhost:8765/console и войдите под только что созданной учётной записью.

Проверка. После входа слева появится меню из девяти разделов: Пользователи, Группы, Модели, MCP-серверы, Форматы файлов, Информационные базы, Мессенджеры, Аудит, Лицензия. Разделы отображаются независимо от редакции; те из них, которые не входят в вашу лицензию, при открытии сообщают об ошибке. Далее консоль понадобится на шагах 4, 5, 7 и 9.

Консоль — рабочее место администратора, обычным пользователям она не нужна и не должна быть доступна. Учётная запись в ней одна на всё: кто вошёл, тот может и базы регистрировать, и людей допускать, и читать журнал всех действий агента. Заводите её только тем, кому положено всё перечисленное.

Консоль намеренно доступна только с самого сервера. Не выставляйте её в сеть без шифрования канала.

Шаг 4. Ввести лицензионный ключ

Пропустите шаг, если ключа у вас нет: без него служба работает в свободной редакции — одна информационная база, без разделов «Группы» и «Мессенджеры».

В консоли откройте раздел Лицензия, вставьте выданную вам строку и нажмите Активировать.

Затем перезапустите службу:

docker compose restart agent

Перезапуск обязателен. Возможности включаются в момент старта службы, поэтому до перезапуска консоль покажет новую лицензию, а работать служба будет по старой.

Проверка. После перезапуска в разделе Лицензия видны название организации, которой выдан ключ, и дата окончания. Раздел показывает то, на чём служба работает сейчас, а не то, что даст установленный, но не применённый ключ.

Ключ можно ввести и позже, в любой момент. Порядок шагов от этого не меняется.

Шаг 5. Загрузить расширение в 1С

Скачайте расширение в консоли: раздел Информационные базы, карточка «Расширение для 1С» внизу страницы. Кнопка отдаёт файл Vrio.cfe.

Скачивайте на той машине, где вы запускаете Конфигуратор 1С — это может быть и сам сервер, и ваш рабочий компьютер.

Расширение берётся отсюда, а не из письма: в консоли лежит копия, собранная вместе с вашей службой, поэтому загрузить в базу расширение, не совпадающее с версией службы, невозможно.

Дальше всё — в Конфигураторе нужной информационной базы:

Меню Конфигурация → Расширения конфигурации. Откроется окно со списком, скорее всего пустым.
Нажмите Добавить — появится строка с полями «Имя», «Синоним», «Префикс». Заполнять их не нужно, любые значения перезапишутся при загрузке. Нажмите ОК.
Выделите созданную строку и, не снимая выделения, идите в меню Конфигурация → Загрузить конфигурацию из файла…. Выберите Vrio.cfe.

Выделение обязательно: пункт применяется к тому расширению, которое выделено в списке. Если выделения нет, вы перезапишете основную конфигурацию.
Имя расширения станет Vrio, префикс Vrio_ — подставятся сами.
Снимите галку в колонке «Безопасный режим» у строки расширения.

Это обязательно. С включённым безопасным режимом расширение установится и будет видно в интерфейсе, но работать не будет, а сообщение об ошибке не укажет на причину. Это самая частая причина неудачной установки.
Нажмите F7 (меню Конфигурация → Обновить конфигурацию базы данных) и согласитесь с изменениями.

Проверка. Запустите 1С:Предприятие. В панели разделов должен появиться раздел «Vrio agent» — латиницей, именно так. Если разделов много и он не помещается, ищите его в меню «Все функции» или в настройке панели разделов. Если раздела нет совсем — переходите к шагу 6, скорее всего дело в правах.

Шаг 6. Выдать права пользователю

Начало шага — справка: какие роли есть и как они подписаны в 1С. Делать по ней ничего не надо, действия начинаются ниже, в одном из двух подразделов.

Ролей в расширении семь. В Конфигураторе и в профилях они показываются синонимами, а не именами:

Имя роли	Подпись в интерфейсе	Требуется
`Vrio_User`	Пользователь агента / Agent user	обязательно
`Vrio_ExecuteArbitraryOperations`	Выполнение произвольных операций	обязательно
`Vrio_Administrator`	Администратор агента	хотя бы одному сотруднику
`Vrio_CodeAnalysis`	Анализ кода	по усмотрению
`Vrio_AutonomousMode`	Автономный режим агента	по усмотрению
`Vrio_IssueExternalTokens`	Vrio: выпуск внешних токенов	нет
`Vrio_MessengerAccess`	Vrio: выпуск токенов привязки мессенджера	нет

У роли Vrio_User заданы две подписи — русская «Пользователь агента» и английская «Agent user». Какая из них попадёт в список, зависит от языка интерфейса базы. Если одной в списке нет, ищите вторую; при английской подписи роль окажется среди латинских названий, отдельно от остальных.

Назначение ролей. Без Пользователь агента чат сообщает о недостатке прав. Без Выполнение произвольных операций агент отвечает на вопросы, но не выполняет действий. Администратор агента требуется тому, кто выполняет шаги 7 и 9; хотя бы у одного сотрудника эта роль должна быть, иначе указанные шаги выполнить невозможно. Анализ кода нужен разработчикам: в окне подтверждения он показывает не только описание операции, но и текст обработки, которую агент собирается выполнить. Автономный режим агента даёт право отключать подтверждения, выбрав в чате автономный режим: агент будет выполнять действия в 1С, не спрашивая разрешения. Назначайте её только тем, кто понимает, что делает агент, — обычно разработчикам.

Дальше — два разных пути. Выберите тот, что подходит вашей конфигурации.

Если конфигурация типовая — БГУ, ЗКГУ, ERP, УТ, Бухгалтерия

Роли выдаются дважды: сначала профилем в режиме 1С:Предприятие, потом в Конфигураторе. Порядок обязателен и в обратную сторону не работает: библиотека стандартных подсистем перезаписывает роли пользователя из своих профилей, поэтому всё, что отмечено в Конфигураторе раньше, будет затёрто. Внешне это выглядит как самопроизвольная потеря прав.

Сначала создать профиль:

Запустите 1С:Предприятие под пользователем с полными правами.
Раздел Администрирование → Настройки пользователей и прав.
В открывшемся окне — ссылка Профили групп доступа.
Кнопка Создать. Откроется карточка нового профиля.
В поле Наименование впишите что-то узнаваемое, например Пользователи Vrio.
Перейдите на закладку Разрешенные действия (роли) — появится список всех ролей конфигурации с флажками.
Найдите и отметьте:
- Пользователь агента (либо Agent user — см. примечание выше);
- Выполнение произвольных операций;
- Анализ кода — если сотрудникам, обычно разработчикам, нужно видеть текст обработки перед выполнением.
- Автономный режим агента — если сотрудникам можно разрешить работу без подтверждений. Роль, выданная только в Конфигураторе, пропадает при каждом обновлении расширения.
Тому, кто будет администрировать агента, отметьте дополнительно Администратор агента. Если таких сотрудников один-два, для них удобнее завести отдельный профиль, например Администраторы Vrio.

Список ролей длинный, поэтому пользуйтесь строкой поиска. Искать следует по подписи роли: агент находит «Пользователь агента» и «Администратор агента», остальные две — по их собственным подписям. Поиск по строке Vrio для этих ролей не работает: в их подписях этого слова нет.
Нажмите Записать и закрыть.

Затем включить людей в группу доступа:

Там же: Администрирование → Настройки пользователей и прав → Группы доступа.
Кнопка Создать.
В поле Наименование — например Пользователи Vrio.
В поле Профиль выберите созданный профиль.
В таблице Участники кнопкой Подобрать добавьте нужных пользователей.
Записать и закрыть.

И только теперь — Конфигуратор:

Откройте Конфигуратор этой базы.
Меню Администрирование → Пользователи.
Двойной клик по тому же пользователю, закладка Прочие.
Отметьте флажками Agent user, Выполнение произвольных операций и, если давали профилем, Анализ кода, Администратор агента и Автономный режим агента. Часть флажков может уже стоять — их проставила библиотека стандартных подсистем по профилю, так и должно быть.
ОК.

Этот шаг обязателен: без него агент может отвечать «недостаточно прав» при полностью настроенном профиле.

После загрузки нового .cfe перезапускайте 1С дважды, прежде чем делать выводы о правах. В первом сеансе после обновления библиотека перестраивает роли заново, и агент в нём отвечает «недостаточно прав», даже когда всё настроено верно. Второй запуск показывает настоящее положение дел.

Если конфигурация самописная, без библиотеки стандартных подсистем

Здесь всё делается в Конфигураторе и в один приём:

Меню Администрирование → Пользователи.
Двойной клик по нужному пользователю.
Закладка Прочие.
Отметьте Agent user, Выполнение произвольных операций и, по желанию, Анализ кода и Администратор агента.
ОК.

Если список пользователей пуст, сначала создайте пользователя кнопкой Добавить. Пустой список не означает, что доступ разрешён всем: агенту требуется явно выданная роль.

Шаг 7. Зарегистрировать базу в службе

База и служба должны узнать друг друга. Делается один раз, в двух местах: код выдаёт консоль, вводится он в 1С.

В консоли (раздел Информационные базы) нажмите Зарегистрировать базу и заполните:

Поле	Что вписать
префикс	короткое имя базы латиницей: строчные буквы, цифры и `_`, до 16 символов. Например `buh`. Изменить его потом нельзя
название	понятная подпись для списка, например «Бухгалтерия». Её менять можно

Нажмите Создать — на экране появится код вида 1134-0DBA-B618-6638.

Код отображается один раз и действует один час. Повторно посмотреть его нельзя, поэтому не закрывайте страницу, пока не введёте код в 1С. Если код утрачен, нажмите Новый код в строке базы и введите новый.

В 1С:Предприятии, под пользователем с ролью Администратор агента:

Откройте раздел «Vrio agent» в панели разделов.
В панели действий раздела найдите группу «Vrio agent». Внутри четыре команды.
Нажмите «Зарегистрировать базу». Откроется форма с одним полем.
Вставьте код и нажмите «Зарегистрировать».

Форма регистрации базы в 1С

В поле «Состояние» появится «База зарегистрирована» и присвоенный базе идентификатор. Код при этом гасится: он одноразовый, повторно ввести его нельзя.

То же самое командой, без консоли:
docker compose exec agent python -m vrio_agent.admin.ib_admin register --prefix buh --title "Бухгалтерия"
Команда напечатает такой же код. Остальные действия администратора тоже продублированы командами — они приведены рядом с описанием в разделе Веб-консоль.

Проверка. Вернитесь в консоль, нажмите Обновить. Ваша база должна быть в списке со статусом active. Статус pending означает, что код ещё не введён или не прошёл.

Затем полностью перезапустите 1С — само приложение, а не форму. Это обязательно. При регистрации база получает собственный секрет и с этого момента подписывает им подключение к службе; сеанс, открытый до регистрации, продолжает работать по прежней схеме и получает отказ. После первого отказа 1С прекращает попытки переподключения до конца сеанса. Внешне это выглядит так: база зарегистрирована, а чат не отвечает.

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

Шаг 8. Указать адрес службы

Если Docker и сервер 1С на одной машине — пропустите этот шаг. Адрес по умолчанию ws://localhost:8765/ws уже верный.

Если служба на другой машине, задайте константу Vrio_ServiceEndpoint:

ws://<адрес сервера>:8765/ws

И на сервере со службой откройте порт 8765 наружу: в docker-compose.yml замените строку - "127.0.0.1:8765:8765" на - "8765:8765", затем docker compose up -d.

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

Учтите: на этом же порту работает консоль администратора. Открыв порт, вы открываете и её — по незашифрованному http. Ограничьте доступ к порту 8765 межсетевым экраном (в Windows — брандмауэром), разрешив его только адресу сервера 1С.

Шаг 9. Разрешить пользователей

Регистрация базы из шага 7 допустила базу. Каждого человека нужно допустить отдельно.

Порядок такой: 1С сама присылает свой список пользователей, вы находите нужного человека в консоли по имени и нажимаете «Разрешить». Никаких идентификаторов вводить не нужно.

9.1. Отправить список пользователей из 1С

В 1С:Предприятии, под пользователем с ролью Администратор агента: раздел «Vrio agent» → панель действий → группа «Vrio agent» → «Отправить реестр пользователей».

Появится сообщение вида «Реестр отправлен. Пользователей: 3; принято сервисом: 3». Оба числа должны совпадать.

В список попадают только те, у кого есть роль Пользователь агента (шаг 6). Если кого-то в списке нет, роль ему не выдана: вернитесь к шагу 6 и отправьте реестр заново.

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

9.2. Разрешить нужных людей в консоли

Откройте консоль (шаг 3) → раздел Информационные базы → таблица Ростер. Если она пуста, нажмите Загрузить.

В таблице по строке на человека:

Столбец	Что в нём
иб	база, из которой пришла строка
логин	логин пользователя в 1С
имя	ФИО из карточки пользователя
доступ	«разрешён» или «не разрешён»
principal	внутренний идентификатор, набирать его не нужно

Найдите человека по имени и нажмите Разрешить в его строке. Столбец «доступ» сразу переключится на «разрешён».

Не нажимайте «Разрешить» дважды. Повторное нажатие ответит ошибкой и заведёт лишнюю учётную запись. Если не помните, нажимали ли, — смотрите столбец «доступ», а лишнюю запись потом удалите в разделе «Пользователи».

Если доступ выдан ошибочно, нажмите Отозвать: доступ сотрудника к агенту прекратится, сам пользователь 1С при этом не затрагивается.

Разрешить можно только того, кого 1С действительно прислала в реестре. Произвольного человека добавить нельзя — в этом смысл шага 9.1.

То же самое командами:
docker compose exec agent python -m vrio_agent.admin.ib_admin roster
docker compose exec agent python -m vrio_agent.admin.ib_admin map --ib <ib_id> --principal <uuid> --from-roster
Идентификаторы берутся из вывода первой команды.

9.3. Пользователь перезапускает 1С

Разрешённый пользователь должен полностью закрыть и заново открыть 1С:Предприятие — именно приложение, а не форму. До перезапуска чат у него работать не начнёт.

Добавить нового сотрудника позже: выдайте ему роли (шаг 6), повторите 9.1, затем нажмите Разрешить в его строке. Заново проходить весь шаг не нужно.

Шаг 10. Проверить

Откройте раздел «Vrio agent» → «Vrio: чат агента» и отправьте два сообщения — именно в таком порядке.

Первое: «привет». Агент должен ответить. Это значит, что связь и языковая модель работают.

Второе: вопрос по данным базы. Например «сколько документов поступления за этот год». Агент должен вернуть настоящую цифру.

Второй вопрос важнее первого: он проверяет другой канал связи, который может не установиться незаметно. Если агент отвечает на приветствие, но на любой вопрос по данным возвращает ошибку, обратитесь к таблице ниже.

Первый вопрос по данным после запуска службы может не уложиться в 30 секунд и завершиться ошибкой. Это прогрев, а не неисправность: повторите вопрос, второй ответ придёт за доли секунды.

Если оба ответа получены — установка закончена.

Если что-то не работает

Что видите	Что делать
`docker` отвечает отказом в доступе	Пользователь не в группе `docker` (Linux) или `docker-users` (Windows). Добавьте и перезайдите в систему.
`curl` выводит что-то странное	В PowerShell пишите `curl.exe`, а не `curl`.
`curl` на `/health` не отвечает	`docker compose logs agent` покажет причину. Чаще всего порт 8765 уже занят другой программой.
Контейнер сразу останавливается	Смотрите последние строки `docker compose logs agent`. Если там упоминается `auth_mode=static` — прислан неверный `.env`, свяжитесь с поставщиком.
В логе `unable to parse string as an integer`	Из `.env` стёрли значение у числовой строки. Верните, например `VRIO_CONTEXT_WINDOW_TOKENS=32768`.
Русские комментарии в `.env` стали мусором	Блокнот сохранил в ANSI. Пересохраните в UTF-8.
Расширение не загружается в Конфигураторе	Версия платформы или режим совместимости ниже 8.3.27. Шаг «Что нужно в 1С».
В 1С нет раздела «Vrio agent»	Расширение не загрузилось, не обновлена конфигурация базы (F7) либо у пользователя нет роли Пользователь агента. Шаги 5 и 6.
Чат пишет «недостаточно прав»	Нет роли Пользователь агента. На типовых конфигурациях её нужно выдать дважды — профилем и в Конфигураторе, шаг 6.
Роли выдали, а они «слетели»	Их отметили в Конфигураторе раньше, чем создали профиль, и библиотека их перезаписала. Порядок обратный, шаг 6.
Обновили расширение — и «недостаточно прав»	Перезапустите 1С ещё раз: библиотека перестраивает роли в первом сеансе после обновления. Не помогло — роли слетели, верните их в Конфигураторе вручную: «Обслуживание» → обновление расширения.
Базу зарегистрировали, а чат молчит	Не перезапущена 1С после регистрации. Полностью закройте и откройте приложение, шаг 7.
Чат открылся, но не отвечает	Пользователь ещё не разрешён — шаг 9. В таблице «Ростер» его строка должна быть помечена «разрешён». Если помечена — полностью перезапустите 1С.
Агент отвечает на «привет», но не отвечает на вопросы по данным	Второй канал связи ещё не поднялся. Подождите две минуты и спросите снова. Если не помогло — перезапустите 1С полностью.
В логе `not mapped to a Vrio user`	Ожидаемо до шага 9: пользователь подключился, но ещё не разрешён. Нажмите «Разрешить» в его строке ростера.
Кнопка «Разрешить» отвечает ошибкой	Строка устарела: 1С прислала новый реестр, а страница показывает старый. Нажмите Загрузить и повторите.
Таблица «Ростер» в консоли пуста	Реестр из 1С ещё не приходил. Выполните 9.1, затем в консоли нажмите Загрузить.
«Реестр отправлен. Пользователей: 0»	Ни у кого нет роли Пользователь агента. Шаг 6, затем отправьте реестр заново.
«Отправка реестра доступна только роли Vrio: администратор»	У текущего пользователя 1С нет роли Администратор агента. Шаг 6.
«Сервис отклонил реестр: база не зарегистрирована…»	Не пройден или не завершён шаг 7. Проверьте, что база в списке со статусом `active`.
Лицензию ввели, а разделы всё равно недоступны	Не перезапущена служба: `docker compose restart agent`, шаг 4.
Консоль не открывается	Она доступна только с самого сервера. Пробросьте порт по ssh — шаг 3.
В консоль не пускает по правильному паролю	После пяти неверных попыток вход блокируется на пять минут. Подождите и повторите.
В логе службы вообще пусто	1С не достучалась до службы. Проверьте порт и константу `Vrio_ServiceEndpoint` (шаг 8).
Чат пишет «внутренняя ошибка»	Сервер не достучался до языковой модели. Проверьте, что адрес из `.env` доступен с сервера: для облачной модели — интернет, для локальной — сеть до неё. Затем обратитесь к поставщику.
Чат пишет «Модель не отвечает уже 10 минут, запрос остановлен»	Поставщик модели перестал отвечать посреди ответа. Проверьте, работает ли он; если пользователю в консоли назначена своя модель — проверьте её карточку или назначьте другую. Предел ожидания в секундах задаёт строка `VRIO_LLM_SILENCE_LIMIT` в `.env`, по умолчанию 600 (10 минут).
Агент или консоль пишет, что расширение старше службы	Службу обновили, а расширение в базе осталось прежним. Обновите его через Конфигуратор — «Обновление расширения 1С».
Агент долго молчит после перезапуска службы	Нормально. 1С восстанавливает связь до двух с половиной минут.

Если ничего не помогло — соберите диагностику и отправьте поставщику:

docker compose logs --tail 200 agent > vrio-logs.txt
docker compose exec agent python -m vrio_agent.admin.ib_admin list >> vrio-logs.txt
docker compose exec agent python -m vrio_agent.admin.ib_admin roster >> vrio-logs.txt

В логе может встретиться строка с token= — это учётные данные. Перед отправкой уберите её или предупредите получателя, что файл содержит секрет.

Обслуживание

Посмотреть, что происходит

docker compose logs -f agent      # выход — Ctrl+C
docker compose ps                 # состояние, должно быть healthy

Перезапустить

docker compose restart agent

После перезапуска 1С восстанавливает связь сама, до двух с половиной минут. Делать на её стороне ничего не нужно.

После правки .env эта команда не поможет. Настройки попадают внутрь контейнера один раз — когда он создаётся. restart запускает тот же самый контейнер с тем же окружением, поэтому правка файла до службы не доходит; то же делает и кнопка перезапуска в Docker Desktop. Чтобы новые значения применились, контейнер нужно пересоздать:
docker compose up -d
Данные при этом сохраняются — они в томе, а не в контейнере. Проверить, что служба видит новое значение, можно так (на месте ИМЯ — нужная переменная):
docker compose exec agent printenv ИМЯ

Остановить и запустить

docker compose stop agent
docker compose start agent

Резервное копирование. Все данные агента — переписка, настройки, журнал действий — лежат в хранилище Docker. Копию снимайте с остановленной службой:

docker compose stop agent
docker run --rm -v vrio_vrio-data:/data -v "${PWD}:/backup" alpine \
  tar czf /backup/vrio-backup.tar.gz -C /data .
docker compose start agent

В PowerShell ${PWD} тоже работает — это переменная самой оболочки, не Docker.

Копия ляжет в текущую папку под именем vrio-backup.tar.gz — переименуйте её с датой, иначе следующая копия затрёт предыдущую.

Точное имя хранилища покажет docker volume ls — оно оканчивается на vrio-data.

Копируйте и папку secrets. В ней лежит ключ шифрования; без него API-ключи моделей и токены ботов из резервной копии не восстановить — их придётся вводить заново. Это обычная папка рядом с docker-compose.yml, копируется как есть.

Файл .env храните вместе с копией и отдельно от неё. Без него часть данных из резервной копии восстановить невозможно.

Обновление

Новая версия приходит так же, как при установке: комплект с файлами настроек и скриптом обновления выдаёт образ новой версии с Docker Hub. Обновление идёт в два этапа, и порядок важен:

Служба — один раз, на сервере. Проще всего скриптом; если его запустить нельзя — вручную.
Расширение 1С — после службы, через Конфигуратор, в каждой базе, где оно установлено: порядок ниже.

Данные при обновлении не трогаются: переписка, пользователи, модели, зарегистрированные базы и настройки консоли остаются как были.

Обновить службу скриптом

В папке службы запустите скрипт обновления:

cd /opt/vrio && ./update.sh                                            # Linux

cd C:\vrio; powershell -ExecutionPolicy Bypass -File .\update.ps1     # Windows

Скрипт сам проверяет, есть ли на Docker Hub версия новее установленной. Если нет, он пишет «Установлена последняя версия» и ничего не меняет. Если есть, он берёт с Docker Hub комплект новой версии и обновляет службу скриптом из этого комплекта, так что обновление всегда идёт свежим скриптом.

Скрипт сверяет образ с Docker Hub, пока прежняя версия ещё работает, так что без связи он остановится, ничего не изменив. В Linux запускайте скрипт от пользователя, которому доступен Docker (состоит в группе docker), или через sudo.

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

mkdir ~/vrio-update && cd ~/vrio-update                               # Linux
docker run --rm --pull always itworksgroup/vrio:latest kit | tar -xk
./update.sh /opt/vrio

mkdir C:\vrio-update; cd C:\vrio-update                              # Windows
docker run --rm --pull always -v "${PWD}:/kit" itworksgroup/vrio:latest kit
powershell -ExecutionPolicy Bypass -File .\update.ps1 C:\vrio

--pull always обязателен: без него Docker возьмёт образ latest, оставшийся от прошлой установки, и комплект окажется прежней версии. Если папка осталась от прошлого обновления, удалите её и создайте заново: в непустую папку комплект не ляжет.

Скрипт делает по порядку то же, что описано вручную, и останавливается на первой ошибке:

проверяет Docker, папку службы и файлы комплекта и скачивает новый образ с Docker Hub;
останавливает службу и снимает резервную копию — данные, .env, docker-compose.yml и папку secrets — в папку backups/<дата-время> рядом со службой;
ставит новые скрипты обновления и новый docker-compose.yml, перенося из прежнего строку порта (если вы меняли её на шаге 8). Порт переносится, только если строка записана как в комплекте, например - "8765:8765" или - "0.0.0.0:8765:8765", без комментария в конце; иначе останется 127.0.0.1:8765, и скрипт не напишет «строка порта перенесена». Другие ваши правки docker-compose.yml — тома, сеть, ограничения памяти — не переносятся: прежний файл лежит в резервной копии, перенесите их оттуда и выполните docker compose up -d;
оставляет ваш .env как есть и перечисляет настройки, которые появились в новой версии;
запускает службу и ждёт, пока она ответит с номером новой версии;
в конце напоминает обновить расширение 1С и печатает команду для возврата.

Служба на это время остановлена — обычно пару минут; 1С восстановит связь сама. Если резервную копию снять не удалось, скрипт запускает прежнюю службу и ничего не меняет.

Копии из backups скрипт не удаляет — старые удаляйте сами, когда новая версия проработает достаточно долго. Комплект, взятый с Docker Hub, скрипт удаляет сам. Папку комплекта, полученного вручную, после обновления можно удалить: образ уже загружен в Docker, а скрипт кладёт свою копию в папку резервной копии, чтобы вернуть прежнюю версию можно было и без комплекта.

Дальше — обновите расширение 1С.

Вернуть прежнюю версию

Если новая версия не ответит за три минуты, скрипт сам вернёт прежнюю: образ, docker-compose.yml и данные из только что снятой копии. Журнал неудачного запуска остаётся в папке копии, файл new-version.log — пришлите его поставщику.

Если проблема обнаружилась позже, перейдите в папку нужной копии и запустите скрипт с ключом --rollback — скрипт печатает эту команду в конце обновления. Копии лежат в папке службы, в backups, и называются датой и временем обновления; нужна та, что снята перед обновлением, после которого начались проблемы — обычно последняя.

cd /opt/vrio/backups/20260925-123411
./update.sh --rollback

cd C:\vrio\backups\20260925-123411
powershell -ExecutionPolicy Bypass -File .\update.ps1 -Rollback

Указывать пути не нужно: скрипт восстанавливает ту копию, в папке которой лежит, а папку службы берёт из записи, сделанной при обновлении.

Возврат — крайняя мера. Он возвращает данные службы на момент копии, то есть на момент обновления: всё, что появилось после него, пропадёт — переписка, изменения в консоли (пользователи, модели, базы, боты), записи журнала действий. Изменения, которые агент за это время внёс в базы 1С, останутся — в самих базах возврат ничего не меняет. Файл .env возврат тоже не трогает; если вы правили его после обновления, прежний лежит в папке копии.

Если обновляли вручную, возврат тоже ручной — он описан в конце следующего раздела.

Обновить службу вручную

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

Снимите резервную копию — данные, папку secrets и .env, как описано в разделе «Обслуживание». В установках старше 9 сентября 2026 года папки secrets нет — это нормально, копируйте данные и .env.
Получите новый комплект в отдельную пустую папку той же командой, что при обновлении скриптом. Она заодно скачает новый образ с Docker Hub.
Замените docker-compose.yml файлом из нового комплекта. В нём записан тег нового образа — версия и дата сборки. Со старым файлом служба и после скачивания нового образа продолжит запускать прежнюю версию, а docker compose up -d ответит, что всё и так в порядке. Если вы меняли в старом файле строку порта на "8765:8765" (шаг 8) или вносили другие правки, повторите их в новом.
.env оставьте свой, шаблон из нового комплекта им не заменяйте. Главное — строка VRIO_MODEL_SECRET_KEY: если в ней стоит значение, не стирайте его. Без него служба выпустит новый ключ и не сможет прочитать сохранённые API-ключи моделей и токены ботов — их придётся вводить заново. Строка VRIO_SHARED_TOKEN, если осталась от прежней версии, больше не используется; её можно не трогать.
Linux: если рядом с docker-compose.yml нет папки secrets, создайте её так же, как на шаге 2:
```
mkdir -p secrets && sudo chown 1000:1000 secrets && chmod 700 secrets
```
Если строка VRIO_MODEL_SECRET_KEY в .env заполнена, папка так и останется пустой — ключ берётся из .env, это нормально. То же самое, если ключ прежняя версия хранила в томе данных: служба сначала ищет существующий ключ и в .env, и в папке secrets, и в томе данных, и только если не нашла нигде — выпускает новый. В Windows папку создавать не нужно: Docker создаст её сам.
Запустите службу с новым образом:
```
docker compose up -d
```
Проверьте, что работает новая версия: curl http://127.0.0.1:8765/health (в Windows — curl.exe) должен вернуть номер из нового комплекта, например {"status":"ok","version":"0.2.0"}. Если там прежний номер — служба запустила старый образ: вернитесь к пункту 3.
Обновите расширение 1С через Конфигуратор — порядок ниже. Свежая копия лежит в консоли: раздел Информационные базы, карточка «Расширение для 1С». Там всегда копия, отвечающая работающей у вас службе, — искать письмо не нужно.

Настройки, переписка, регистрация баз и разрешённые пользователи обновление переживают.

Вернуть прежнюю версию вручную

Старый образ остаётся загруженным. Остановите службу, верните прежний docker-compose.yml и восстановите данные из копии, снятой в пункте 1: новая версия могла успеть изменить их под себя.

docker compose stop agent
docker run --rm -v vrio_vrio-data:/data -v "${PWD}:/backup" alpine \
  sh -c "rm -rf /data/* && tar xzf /backup/vrio-backup.tar.gz -C /data"
docker compose up -d

Имя хранилища и файла копии — те же, что при резервном копировании.

Обновление расширения 1С

Расширение обновляется только через Конфигуратор: после обновления службы, отдельно в каждой базе, где оно установлено.

Попросите пользователей выйти из базы.
Конфигуратор → Конфигурация → Расширения конфигурации. Выделите строку Vrio — без выделения следующий пункт перезапишет основную конфигурацию.
Конфигурация → Загрузить конфигурацию из файла… → новый Vrio.cfe. Скачайте его в консоли (Информационные базы → «Расширение для 1С») после обновления службы: там лежит копия, которая соответствует новой версии.
Убедитесь, что галка в колонке «Безопасный режим» у строки расширения по-прежнему снята.
F7 — обновить конфигурацию базы данных.
Пользователи полностью закрывают и открывают 1С.

Проверьте права

Загрузка нового .cfe может снять с пользователей роли расширения. На типовых конфигурациях библиотека стандартных подсистем восстанавливает их из профиля сама — в первом сеансе после обновления, поэтому 1С и перезапускают дважды.

Если же чат и после второго перезапуска отвечает «недостаточно прав» или «Ассистент недоступен», профиль роли не вернул и их нужно проставить руками:

Конфигуратор → Администрирование → Пользователи → нужный пользователь → вкладка «Прочие» → отметить роли Vrio → ОК.

Роли расширения стоят в конце алфавитного списка, после всех ролей самой конфигурации. Это самое частое место, где их не находят и делают вывод, что расширение установилось неправильно.

Регистрация базы, адрес и ключ службы, переписка и настройки обновление переживают. Регистрировать базу заново и отправлять реестр пользователей не нужно.

Из чего состоит Vrio​

Что нужно в 1С​

Что нужно на сервере​

Шаг 1. Получить комплект​

Шаг 2. Заполнить настройки​

Шаг 3. Запустить службу​

Консоль администратора​

Шаг 4. Ввести лицензионный ключ​

Шаг 5. Загрузить расширение в 1С​

Шаг 6. Выдать права пользователю​

Если конфигурация типовая — БГУ, ЗКГУ, ERP, УТ, Бухгалтерия​

Если конфигурация самописная, без библиотеки стандартных подсистем​

Шаг 7. Зарегистрировать базу в службе​

Шаг 8. Указать адрес службы​

Шаг 9. Разрешить пользователей​

9.1. Отправить список пользователей из 1С​

9.2. Разрешить нужных людей в консоли​

9.3. Пользователь перезапускает 1С​

Шаг 10. Проверить​

Если что-то не работает​

Обслуживание​

Обновление​

Обновить службу скриптом​

Вернуть прежнюю версию​

Обновить службу вручную​

Вернуть прежнюю версию вручную​

Обновление расширения 1С​

Проверьте права​