# Агент ответов на отзывы: установка для нового магазина Инструкция для человека, который ни разу не настраивал сервер. Идите по шагам сверху вниз. На всё уходит 1–2 часа, большая часть времени — получение ключей в кабинетах площадок. **Что делает агент.** Каждые 15 минут забирает новые отзывы и вопросы с Wildberries, Ozon и Яндекс Маркета, ищет ответ в вашей базе знаний и пишет ответ через нейросеть Claude. Хорошие отзывы (4–5★) и вопросы, ответ на которые есть в базе, он публикует сам. Негатив и всё сомнительное присылает вам в чат (Битрикс24, Telegram или MAX) с кнопками «Опубликовать», «Свой текст», «Переписать», «Пропустить». --- ## Шаг 0. Что понадобится | Что | Зачем | Стоимость | |---|---|---| | Сервер VPS с Ubuntu | агент работает на нём круглосуточно | 300–700 ₽ в месяц | | Ключ Claude API (Anthropic) | пишет ответы | оплата по факту, см. ниже | | Ключ хотя бы одной площадки: WB, Ozon или Яндекс Маркет | читать отзывы и публиковать ответы | бесплатно (Ozon — только с подпиской Premium Plus) | | Чат для модерации: Битрикс24, Telegram или MAX | вам приходят отзывы на проверку | бесплатно | | Компьютер или телефон с SSH | подключаться к серверу | бесплатно | **Сколько стоит Claude.** Один ответ — один запрос к модели. Ориентир: около 1–2 центов за ответ на модели Sonnet и в несколько раз дешевле на Haiku. Точные цены: anthropic.com/pricing. Для 1000 отзывов в месяц это порядка 10–20 $ на Sonnet или 3–5 $ на Haiku. --- ## Шаг 1. Арендовать сервер **Важно: сервер должен быть НЕ в России.** Claude API не отвечает на запросы с российских IP-адресов. Подойдёт сервер в Казахстане, Армении, Финляндии, Нидерландах, Германии и т.п. API Wildberries, Ozon и Яндекс Маркета работают из-за рубежа нормально. Характеристики (минимум, этого хватает с запасом): - 1 ядро процессора (vCPU); - 1 ГБ оперативной памяти (лучше 2 ГБ); - 10–20 ГБ диска (SSD/NVMe); - операционная система **Ubuntu 24.04** (или 22.04); - публичный IPv4-адрес. Где взять: любой хостинг с VPS, например Timeweb Cloud, Beget, Aeza, PS.kz, Hetzner. При заказе выберите регион за пределами России, Ubuntu 24.04 и минимальный тариф. После оплаты хостинг пришлёт (на почту или в панели управления): - **IP-адрес** сервера, например `203.0.113.10`; - логин — обычно `root`; - **пароль** root. Запишите их. Дальше в инструкции вместо `IP_СЕРВЕРА` подставляйте свой адрес. --- ## Шаг 2. Подключиться к серверу Подключение идёт по SSH: вы вводите команды, а выполняет их сервер. **С компьютера (Windows 10/11, macOS, Linux).** Откройте «Терминал» (в Windows — PowerShell) и введите: ``` ssh root@IP_СЕРВЕРА ``` На вопрос `Are you sure you want to continue connecting` напишите `yes` и нажмите Enter. Затем введите пароль. Символы при вводе пароля не отображаются, это нормально. **С телефона на Android.** Установите **Termux** (из F-Droid) и в нём выполните: ``` pkg install openssh ``` ``` ssh root@IP_СЕРВЕРА ``` На iPhone подойдёт приложение **Termius**: «New Host», адрес = IP сервера, пользователь `root`, пароль. Вы на сервере, если строка ввода выглядит примерно так: `root@имя-сервера:~#`. Полезно знать: - вставить текст в терминал: правая кнопка мыши (Windows) или долгое нажатие (телефон); - отменить зависшую команду: `Ctrl + C`; - отключиться от сервера: `exit`. **Проверьте, что сервер видит Claude** (если ответ `403` или ошибка соединения, сервер в неподходящей стране): ``` curl -s -o /dev/null -w "%{http_code}\n" https://api.anthropic.com/v1/messages ``` Нормальный ответ: `405` или `401`. Это значит, что Claude доступен. --- ## Шаг 3. Загрузить файлы агента на сервер У вас есть архив `reviews-agent.zip`. **С компьютера.** Откройте ВТОРОЕ окно терминала (не на сервере, а на своём компьютере), перейдите в папку, где лежит архив (например, «Загрузки»), и отправьте архив на сервер: ``` cd Downloads ``` ``` scp reviews-agent.zip root@IP_СЕРВЕРА:/root/ ``` **С телефона (Termux).** Один раз дайте Termux доступ к файлам телефона: ``` termux-setup-storage ``` Затем отправьте архив из «Загрузок» на сервер: ``` scp ~/storage/downloads/reviews-agent.zip root@IP_СЕРВЕРА:/root/ ``` Вернитесь в окно, где вы подключены к серверу, и распакуйте архив: ``` apt-get update && apt-get install -y unzip ``` ``` cd /root && unzip -o reviews-agent.zip ``` --- ## Шаг 4. Установить агента Одна команда всё установит: Python, библиотеки, отдельного системного пользователя `reviews`, папку `/opt/reviews-agent` и службу автозапуска. ``` bash /root/reviews-agent/deploy/install.sh ``` В конце появится надпись «Готово». Агент пока не запущен: сначала нужны ключи. Дальше все настройки лежат в двух файлах: - `/opt/reviews-agent/.env` — ключи и токены (секреты); - `/opt/reviews-agent/config.yaml` — настройки: какие площадки включены, название бренда, тон ответов. **Как редактировать файлы.** Откройте файл в редакторе nano: ``` nano /opt/reviews-agent/.env ``` Стрелками дойдите до нужной строки и впишите значение сразу после `=` без пробелов и кавычек, например `WB_API_TOKEN=eyJhbGciOi...`. Сохранить: `Ctrl + O`, затем Enter. Выйти: `Ctrl + X`. **Безопасность.** Ключи вписывайте только в файл `.env` на сервере. Не отправляйте их в мессенджеры, почту и чаты: любой, у кого есть ключ, может отвечать от имени вашего магазина. --- ## Шаг 5. Получить ключ Claude (обязательно) 1. Зайдите на **console.anthropic.com** и зарегистрируйтесь. 2. **Billing** → пополните баланс (нужна карта, которая работает с зарубежными сервисами), например на 10 $. 3. **API Keys** → **Create Key** → скопируйте ключ. Он начинается с `sk-ant-` и показывается один раз. 4. Впишите в `/opt/reviews-agent/.env`: ``` ANTHROPIC_API_KEY=sk-ant-... ``` --- ## Шаг 6. Получить ключи площадок Подключите хотя бы одну площадку. Ключ каждой площадки вписывается в `.env`, а сама площадка включается в `config.yaml` (шаг 7). ### Wildberries 1. Личный кабинет продавца → **Профиль** (справа вверху) → **Настройки** → **Доступ к API**. 2. **Создать новый токен**. Отметьте категорию **«Вопросы и отзывы»**. Галочку **«Только на чтение» НЕ ставьте**, иначе агент не сможет отвечать. 3. Скопируйте токен (длинная строка, начинается с `eyJ`) и впишите в `.env`: ``` WB_API_TOKEN=eyJ... WB_NAME=Мой магазин ``` `WB_NAME` — просто подпись кабинета в карточках модерации, можно оставить пустым. Учтите: токен WB действует 180 дней, потом его нужно выпустить заново и заменить в `.env`. WB разрешает кабинету примерно один запрос к отзывам в 10–12 минут, поэтому отзывы и вопросы агент забирает по очереди. Первые карточки могут прийти через 15–30 минут после запуска, это нормально. ### Ozon Отзывы через API доступны **только с подпиской Premium Plus**. Без неё Ozon подключить нельзя. 1. Личный кабинет продавца → **Настройки** → **Seller API**. 2. **Сгенерировать ключ**, роль — **Admin** (или роль с доступом к отзывам и вопросам). 3. На той же странице указан **Client ID**. Впишите оба значения в `.env`: ``` OZON_CLIENT_ID=123456 OZON_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ``` ### Яндекс Маркет 1. Кабинет продавца на partner.market.yandex.ru → **Настройки** → **API и модули** → **Авторизационные токены** → **Создать токен**. 2. Дайте токену доступ **«Общение с покупателями»** (отзывы и вопросы). Скопируйте токен. 3. **ID бизнеса** виден в адресной строке кабинета: `partner.market.yandex.ru/business/12345678/...`, здесь `12345678` — нужное число. 4. Впишите в `.env`: ``` YANDEX_API_KEY=ACMA:... YANDEX_BUSINESS_ID=12345678 YANDEX_NAME=Мой магазин ``` ### Несколько кабинетов на одной площадке Второй кабинет добавляется теми же строками с окончанием `_2`, третий — с `_3`: `WB_API_TOKEN_2`, `WB_NAME_2`, `OZON_CLIENT_ID_2` и `OZON_API_KEY_2`, `YANDEX_API_KEY_2` и `YANDEX_BUSINESS_ID_2`. Ответ всегда уходит в тот кабинет, откуда пришёл отзыв. --- ## Шаг 7. Настроить config.yaml ``` nano /opt/reviews-agent/config.yaml ``` Что поменять: 1. **Бренд и тон** (блок `brand`): ```yaml brand: name: "Название вашего магазина" tone: "дружелюбно и по делу, на «вы», без канцелярита и штампов" signature: "" # подпись в конце ответа, например "Команда Название" rules: # свои правила, по одному в строке - "Не предлагай скидки и промокоды." ``` 2. **Площадки** (блок `platforms`): у тех, ключи которых вы вписали, поставьте `enabled: true`, у остальных — `enabled: false`. По умолчанию включён только WB. 3. **Возвраты** (блок `policy`): если ваш товар невозвратный, поставьте `no_returns: true`. Тогда агент не будет предлагать возврат и обмен, а приглашать покупателя в чат с продавцом. 4. **Модель**: `llm: model: claude-sonnet-5`. Дешевле — `claude-haiku-4-5-20251001`. 5. **Тестовый режим** `dry_run: true` пока не трогайте (шаг 11). Отступы в этом файле важны: используйте пробелы, не Tab, и сохраняйте отступы как в примере. --- ## Шаг 8. Чат для модерации Выберите один вариант. Проще всего Telegram; если команда работает в Битрикс24, выбирайте его. ### Вариант А. Битрикс24 (отдельный чат на каждую площадку) 1. Битрикс24 → **Разработчикам** (в левом меню, иногда в «Ещё») → **Другое** → **Входящий вебхук**. 2. Права доступа: отметьте **imbot** (Чат-боты) и **im** (Чат и уведомления). Сохраните. 3. Скопируйте ссылку вида `https://ваш-портал.bitrix24.ru/rest/1/abcdef123456/` и впишите в `.env`: ``` BITRIX_WEBHOOK_URL=https://ваш-портал.bitrix24.ru/rest/1/abcdef123456/ BITRIX_ENABLED=1 ``` (уберите `#` перед строкой `BITRIX_ENABLED`, если он есть). 4. Запустите агента (шаг 10). При первом запуске он сам создаст в Битрикс24 бота **«Отзывы магазина»** и допишет `BITRIX_BOT_ID` и `BITRIX_BOT_TOKEN` в `.env`. Эти строки не трогайте. 5. В Битрикс24 создайте групповые чаты, например «Отзывы WB», «Отзывы Ozon», «Отзывы Яндекс». 6. **Добавьте бота «Отзывы магазина» в каждый чат участником.** Без этого бот не видит чат и не может туда писать. 7. В каждом чате напишите команду площадки: `/connect wb`, `/connect ozon` или `/connect yandex`. Бот ответит, что чат подключён. 8. Проверка: `reviews bitrix-test` — в чаты придёт тестовое сообщение. Если площадку нужно перенести в другой чат, напишите там `/connect wb перенести`. ### Вариант Б. Telegram 1. В Telegram откройте **@BotFather** → `/newbot` → придумайте имя и логин бота → скопируйте токен вида `123456789:AA...`. 2. Узнайте свой ID: напишите **@userinfobot**, он ответит числом. Если хотите получать карточки в группу: создайте группу, добавьте туда бота, напишите в группе любое сообщение и откройте в браузере `https://api.telegram.org/botТОКЕН/getUpdates`. Найдите `"chat":{"id":-100...`. Число с минусом и есть ID группы. 3. Впишите в `.env`: ``` TELEGRAM_BOT_TOKEN=123456789:AA... TELEGRAM_CHAT_IDS=ваш_ID_или_ID_группы ``` Несколько получателей — через запятую. Отдельная группа на площадку: `TELEGRAM_CHAT_WB=`, `TELEGRAM_CHAT_OZON=`, `TELEGRAM_CHAT_YANDEX=`. 4. Напишите своему боту `/start`, иначе Telegram не даст ему писать вам первым. 5. В `config.yaml` должно стоять `telegram: enabled: true` (стоит по умолчанию). ### Вариант В. MAX 1. business.max.ru → **Чат-боты** → создайте бота, скопируйте токен в `.env`: `MAX_BOT_TOKEN=...` 2. Создайте группу в MAX (например «Отзывы Яндекс»), добавьте бота и сделайте его администратором. 3. Выполните `reviews max-connect yandex` (или `wb`, `ozon`) и в течение 3 минут напишите в группе `/start`. ID группы запишется в `.env` сам. 4. Если Telegram не используется, поставьте в `config.yaml` `telegram: enabled: false`. Площадка, для которой подключена группа MAX, уходит из Telegram в MAX; остальные остаются в Telegram. --- ## Шаг 9. База знаний Из базы знаний агент берёт факты для ответов: характеристики, размеры, гарантию, условия доставки и возврата, решения частых проблем. **Чего нет в базе, агент не выдумывает**: такие ответы он отправит вам на проверку. Чем полнее база, тем больше ответов публикуется без вас. Два способа (можно оба сразу): В комплекте **нет ничьей готовой базы**: папка `knowledge_base/` пустая, а в `examples/knowledge_base/` лежат два выдуманных примера (куртка, чехол), чтобы было видно формат. Их не нужно подключать. **Что положить в базу:** ответы на частые вопросы по каждому товару, характеристики и размеры, комплектацию, инструкции (как собрать, настроить, ухаживать), условия гарантии, доставки и возврата, решения типичных проблем («не включается — сделайте так»). Источники: вопросы покупателей в кабинетах площадок, ваши прошлые ответы на отзывы, описания карточек. **Google Таблица.** Удобно, если базу ведут несколько человек. 1. Откройте sheets.google.com → **Пустая таблица**. 2. В первой строке напишите заголовки: **Артикул**, **Вопрос**, **Ответ**. Каждая следующая строка — одна пара «вопрос → ответ». В «Артикул» пишите артикул продавца или модель, к которой относится строка; для общих вопросов (доставка, гарантия) оставьте пустым. Вместо «Вопрос»/«Ответ» можно назвать колонки «Проблема»/«Решение». Строка, где заполнена одна ячейка, считается названием раздела. Пример формата: `examples/knowledge_base/02_частые_вопросы_ПРИМЕР.csv`. 3. Кнопка **Настройки доступа** (справа вверху) → «Все, у кого есть ссылка» → роль **Читатель** → **Готово**. Скопируйте ссылку из адресной строки. 3. В `config.yaml` замените строку `google_sheets: []` на: ```yaml google_sheets: - https://docs.google.com/spreadsheets/d/ВАШ_ID/edit#gid=0 ``` Таблица перечитывается раз в час; сразу подхватить правки — команда `/reload` в чате модерации. **Файлы.** Положите файлы `.md`, `.txt`, `.docx`, `.csv` или `.xlsx` в папку `/opt/reviews-agent/knowledge_base/` (например, загрузите через `scp` как в шаге 3). Лучше всего работают короткие разделы с заголовками, один раздел на одну тему. Пример: `examples/knowledge_base/01_общее_ПРИМЕР.md`. После добавления файлов выполните `chown -R reviews:reviews /opt/reviews-agent/knowledge_base`. **Без базы знаний** агент тоже работает, но публиковать сам будет почти только благодарности за 4–5★, а вопросы и негатив будут приходить вам на проверку. Проверить, что найдёт база (после изменений в таблице — `/reload` в чате или `systemctl restart reviews-agent`): ``` reviews kb "какой наполнитель у куртки" --product "Куртка зимняя KURT-01" ``` --- ## Шаг 10. Проверка и первый запуск 1. **Ключи площадок** (сами ключи не показываются; проверяются WB и Яндекс Маркет): ``` reviews check ``` Для WB должно быть «Вопросы и отзывы: есть» и без надписи «ТОЛЬКО ЧТЕНИЕ». 2. **Пробный ответ без площадок** (проверяет ключ Claude и тон бренда): ``` reviews draft "Пришла с браком, молния заедает" --rating 2 --product "Куртка зимняя" ``` ``` reviews draft "Подойдёт ли на рост 180?" --question --product "Куртка зимняя" ``` Если тон не нравится, поправьте `brand` в `config.yaml` и повторите. 3. **Запуск службы**: агент будет работать постоянно и сам перезапускаться после перезагрузки сервера. ``` systemctl enable --now reviews-agent ``` 4. **Журнал** (выход: `Ctrl + C`): ``` journalctl -u reviews-agent -f ``` Должна появиться строка «Старт. Площадки: ...», а в чат модерации придёт «Агент отзывов запущен». --- ## Шаг 11. Тестовый режим, потом боевой Сначала агент работает в **тестовом режиме** (`dry_run: true`): он всё делает, но ничего не публикует на площадках. Карточки в чат приходят, ответы видны в отчёте. Подержите так 1–3 дня и посмотрите отчёт: ``` reviews report --days 3 ``` Когда ответы устраивают: 1. В `config.yaml` поставьте `dry_run: false`. 2. Первое время лучше `auto_publish_questions: false`, чтобы все вопросы шли через вас. 3. Перезапустите: `systemctl restart reviews-agent`. Ответы из тестового режима агент после переключения опубликует заново сам. Учтите: на WB ответ на отзыв можно изменить только один раз и только в течение 60 дней. --- ## Работа с карточками в чате Карточка содержит отзыв, оценку, товар, черновик ответа и причину, почему агент не опубликовал сам. - **Опубликовать** — отправить черновик как есть. - **Свой текст** — опубликовать ваш вариант (в Битрикс24 в поле ввода появится `/edit 12 `, допишите текст). - **Переписать** — попросить агента переписать с вашим комментарием («короче», «без извинений»). - **Пропустить** — не отвечать. Команды в чате: `/pending` — всё, что ждёт решения; `/report` — сводка за неделю; `/reload` — перечитать базу знаний; `/help` — подсказка. **Что публикуется само**, если выполнено всё сразу: отзыв на 4–5★ или вопрос с ответом из базы; модель уверена в ответе; в тексте покупателя нет стоп-слов (брак, возврат, суд, аллергия и т.п.); в ответе нет ссылок, телефонов и мессенджеров. Пороги настраиваются в `config.yaml → policy`. --- ## Полезные команды | Команда | Что делает | |---|---| | `systemctl status reviews-agent` | работает ли агент | | `systemctl restart reviews-agent` | перезапустить (после правки `.env` или `config.yaml`) | | `systemctl stop reviews-agent` | остановить | | `journalctl -u reviews-agent -n 100` | последние 100 строк журнала | | `reviews check` | проверить ключи WB и Яндекс Маркета | | `reviews report --days 7` | сводка за неделю: жалобы по товарам, частые вопросы, чего нет в базе | | `reviews report --csv /tmp/otchet.csv` | выгрузка всех ответов для Excel | | `reviews kb "текст"` | что найдёт база знаний | --- ## Если что-то не работает | Что видно | Что делать | |---|---| | `ANTHROPIC_API_KEY не задан` | ключ не вписан в `/opt/reviews-agent/.env` или опечатка в названии строки | | Ошибка 403 от Claude, `connection` к api.anthropic.com | сервер в России; нужен сервер в другой стране (шаг 1) | | Ошибка 401 от Claude | неверный ключ или на балансе Anthropic 0 $ | | WB: 401 | токен истёк, неверный или выпущен без категории «Вопросы и отзывы» | | WB: «лимит запросов, площадка просит подождать» | нормально: агент сам подождёт и продолжит | | Ozon: 403 | нет подписки Premium Plus или у ключа не та роль | | Яндекс: 401/403 | у токена нет доступа «Общение с покупателями» или неверный ID бизнеса | | Битрикс24: `ACCESS_DENIED` | бот «Отзывы магазина» не добавлен в чат участником | | Битрикс24: карточки не приходят | в чате не написан `/connect wb` (или `yandex`, `ozon`); проверьте `reviews bitrix-test` | | Telegram: `chat not found` | неверный `TELEGRAM_CHAT_IDS` или вы не написали боту `/start` | | `Ни одна площадка не включена` | в `config.yaml` у площадок `enabled: false` | | Агент не запускается после правки `config.yaml` | сломаны отступы: сравните с `config.example.yaml` | --- ## Что в комплекте ``` reviews-agent/ ИНСТРУКЦИЯ.md — эта инструкция README.md — техническое описание .env.example — шаблон ключей (копируется в /opt/reviews-agent/.env) config.example.yaml — шаблон настроек (копируется в /opt/reviews-agent/config.yaml) deploy/install.sh — установка на сервер одной командой deploy/reviews-agent.service — служба автозапуска agent/ — код агента examples/knowledge_base/ — примеры базы знаний knowledge_base/ — сюда ваши файлы базы знаний Dockerfile, docker-compose.yml — запуск в Docker (по желанию, вместо install.sh) ``` **Обновление агента.** Загрузите новый архив, распакуйте и снова выполните `bash /root/reviews-agent/deploy/install.sh`. Ваши `.env`, `config.yaml`, база знаний и данные (`data/agent.db`) сохранятся. Затем `systemctl restart reviews-agent`.