openspec-lab/openspec/changes/archive/2026-09-06-tavily-proxy-setup/design.md

Design: tavily-proxy-setup

Approach

Tavily API блокирует РФ-адреса (403 на уровне AWS ELB). Решение — не менять глобально прокси Hermes (сломало бы прямой доступ к deepseek/polza), а завернуть только Tavily в локальный форвардер:

• tavily_proxy.py — http.server на 127.0.0.1:8971, принимает POST на /extract и /search, проксирует через httpx-клиент с SOCKS5-транспортом (socks5://127.0.0.1:1080, туннель до VPS01).
• Hermes настраивается на TAVILY_BASE_URL=http://127.0.0.1:8971 — официальный способ подменить endpoint, httpx-провайдер Tavily шлёт запросы туда.
• Зависимость от туннеля: After=telegram-tunnel.service + Restart=always.

Files

• /opt/hermes/.hermes/scripts/tavily_proxy.py — форвардер (Python, venv Hermes)
• /opt/hermes/.hermes/scripts/tavily_extract_proxy.py — форвардер + локальный экстрактор (trafilatura), юнит указывает на него: --socks 127.0.0.1:1080 --upstream https://api.tavily.com
• /etc/systemd/system/tavily-proxy.service — юнит (enabled)
• /opt/hermes/.hermes/.env — TAVILY_API_KEY, TAVILY_BASE_URL=http://127.0.0.1:8971
• /opt/hermes/.hermes/config.yaml — web.extract_backend: tavily

Commands

# Применение
sudo systemctl daemon-reload
sudo systemctl enable --now tavily-proxy.service

# Проверка
systemctl is-active tavily-proxy.service
curl -s -o /dev/null -w "%{http_code}" -X POST http://127.0.0.1:8971/extract \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com"],"api_key":"'"$TAVILY_API_KEY"'"}'
# → 200, web_extract отдаёт контент

Rollback

sudo systemctl disable --now tavily-proxy.service
# удалить TAVILY_BASE_URL из .env; extract_backend вернуть на searxng (extract не работал — деградация к прежнему состоянию)

Risks

• Туннель VPS01 недоступен → Tavily тоже недоступен (extract лежит) — приемлемо: без туннеля Tavily блокирован в любом случае.
• httpx-SOCKS требует пакет socksio в venv — проверено, есть.
• Форвардер — однопоточный http.server (ThreadingHTTPServer), достаточно для одного агента.