Конфигурация и окружение

Этот раздел объясняет, какие переменные окружения использует Telegram‑бот и как они связаны с кодом. Ниже приведены небольшие примеры из реальных модулей.

Базовая конфигурация бота

Конфигурация бота сосредоточена в файле telegram-bot/config/settings.py. Класс Config считывает из окружения токен бота (BOT_TOKEN), внешний базовый URL (WEBHOOK_BASE_URL), секретный путь webhook (WEBHOOK_SECRET_PATH), а также адрес и порт HTTP‑сервера (APP_HOST, APP_PORT). Если одно из обязательных значений не задано, при импорте модуля будет выброшено исключение ValueError, и приложение не запустится — это позволяет сразу заметить некорректную настройку.

Переменные окружения для базовой конфигурации

Name	Type	Description	Default
`BOT_TOKEN`	`str`	Токен Telegram‑бота. Обязателен; без него приложение не стартует.	—
`WEBHOOK_BASE_URL`	`str`	Базовый внешний URL, по которому Telegram будет вызывать webhook (например, `https://example.com`).	—
`WEBHOOK_SECRET_PATH`	`str`	Секретный путь вебхука (начинается с `/`), добавляется к `WEBHOOK_BASE_URL` для формирования `WEBHOOK_URL`.	—
`APP_HOST`	`str`	Адрес, на котором слушает HTTP‑сервер aiohttp.	`127.0.0.1`
`APP_PORT`	`int`	Порт HTTP‑сервера Telegram‑бота.	`8081`

Пример определения конфигурации повторяет реальный код: значения читаются через os.getenv, а при отсутствии обязательных переменных выбрасывается ValueError уже на этапе импорта.

import os
from dotenv import load_dotenv

load_dotenv()


class Config:
    BOT_TOKEN = os.getenv("BOT_TOKEN")
    if not BOT_TOKEN:
        raise ValueError("BOT_TOKEN не найден в переменных окружения")

    WEBHOOK_BASE_URL = os.getenv("WEBHOOK_BASE_URL")
    WEBHOOK_SECRET_PATH = os.getenv("WEBHOOK_SECRET_PATH")
    if not WEBHOOK_BASE_URL or not WEBHOOK_SECRET_PATH:
        raise ValueError("WEBHOOK_BASE_URL/WEBHOOK_SECRET_PATH не заданы")

    WEBHOOK_URL = f"{WEBHOOK_BASE_URL}{WEBHOOK_SECRET_PATH}"

    APP_HOST = os.getenv("APP_HOST", "127.0.0.1")
    APP_PORT = int(os.getenv("APP_PORT", "8081"))


config = Config()

Экземпляр config создаётся один раз и доступен через одноимённое имя. Его импортируют в main.py, services/webhook.py и других модулях, где нужны настройки бота или сервера:

from config.settings import config

bot = Bot(token=config.BOT_TOKEN, parse_mode="HTML")

Настройки базы данных

Помимо параметров, описанных в Config, сервис использует несколько групп переменных, связанных с базой данных и OpenAI. Файл telegram-bot/env.example содержит полный перечень с пустыми значениями, а здесь имеет смысл выделить только основные.

Подключение к базе данных описано в services/mysql_memory.py. Здесь используются MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD и MYSQL_DATABASE. Они задают подключение к общей базе MariaDB, где лежат таблицы users, dialogue_history, cargo_requests (и опционально user_state). Эти же параметры должны совпадать с настройками MCP‑сервера и SIP Hook, чтобы все сервисы работали с одной и той же базой:

Note

Таблица user_state нужна, чтобы бот «помнил» служебное состояние между перезапусками (последнюю роль, previous_response_id, контекст doc‑flow и историю вызовов MCP‑инструментов). Если таблицы нет — бот продолжит работать, но это состояние не будет сохраняться. DDL лежит в telegram-bot/scripts/20260113_user_state.sql.

Переменные окружения для базы данных

Name	Type	Description	Default
`MYSQL_HOST`	`str`	Хост MariaDB/MySQL, к которому подключается бот.	`127.0.0.1`
`MYSQL_PORT`	`int`	Порт MariaDB/MySQL.	`3306`
`MYSQL_USER`	`str`	Имя пользователя базы данных. Обязательно; при отсутствии будет выброшено `ValueError`.	—
`MYSQL_PASSWORD`	`str`	Пароль пользователя базы данных. Обязательно.	—
`MYSQL_DATABASE`	`str`	Имя базы данных (схемы), в которой находятся `users`, `dialogue_history`, `cargo_requests`.	—

engine = create_async_engine(
    build_mysql_url(),
    echo=False,
    pool_pre_ping=True,
)
SessionLocal = async_sessionmaker(engine, expire_on_commit=False)

Настройки OpenAI и MCP

Настройки OpenAI и MCP читаются в services/openai/config.py и services/identity.py. Основные переменные: OPENAI_API_KEY (ключ OpenAI), OPENAI_RESPONSES_MODEL (основная модель Responses API, по умолчанию gpt-4.1), OPENAI_FALLBACK_MODEL (резервная модель, используется при недоступности MCP), OPENAI_HISTORY_LIMIT (сколько сообщений истории передавать в модель, по умолчанию 20). MCP_SERVER_URL используется для MCP‑инструментов внутри Responses API. MCP_LOCAL_URL нужен MCPIdentityResolver для вызова verify_user через fastmcp. Если MCP_SERVER_URL не задан, OpenAIService работает в текстовом режиме без инструментов, но MCP_LOCAL_URL всё равно нужен для корректного сопоставления tg_id → user_id.

Переменные окружения для OpenAI и MCP

Name	Type	Description	Default
`OPENAI_API_KEY`	`str`	Ключ OpenAI. Обязателен; при отсутствии `OpenAIConfig.load()` выбрасывает `ValueError`.	—
`OPENAI_RESPONSES_MODEL`	`str`	Основная модель Responses API, используемая для текста+MCP‑инструментов.	`"gpt-4.1"`
`OPENAI_FALLBACK_MODEL`	`str`	Резервная модель Responses API, используется при недоступности MCP; по умолчанию совпадает с `OPENAI_RESPONSES_MODEL`.	`primary`
`OPENAI_HISTORY_LIMIT`	`int`	Максимальное количество сообщений истории, передаваемой в модель; некорректные или неположительные значения заменяются на `20`.	`20`
`MCP_SERVER_URL`	`str` \| `None`	HTTP‑URL MCP‑сервера для Responses API. Если не задан, `OpenAIService` работает в текстовом режиме без инструментов.	`None`
`MCP_LOCAL_URL`	`str`	URL MCP‑сервера для `fastmcp` в `MCPIdentityResolver` (вызов инструмента `verify_user`). Обязателен для обработки входящих сообщений.	—
`MCP_AUTH_TOKEN`	`str` \| `None`	JWT‑токен для MCP‑сервера (если включена авторизация). Используется и в `fastmcp` (`MCP_LOCAL_URL`), и в Responses API (`MCP_SERVER_URL`).	`None`
`SYSTEM_INSTRUCTIONS_PATH`	`str` \| `None`	Необязательный путь до файла с системными инструкциями; если не задан, используется `config/instructions/base.md`.	`None`

Пример инициализации клиента OpenAI Responses:

from openai import AsyncOpenAI

client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

Telegram Business: служебные параметры

Часть функциональности бота (принятие подписанных документов, отправка DOCX, уведомления о взятом грузе) требует дополнительных переменных окружения.

Переменные окружения бизнес‑канала и документов

Name	Type	Description	Default
`BUSINESS_CONNECTION_ID`	`str` \| `None`	Идентификатор Telegram Business connection для проактивных исходящих сообщений (используется эндпоинт `POST /cargo-assigned`).	`None`
`RESPONSIBLE_TG_ID`	`int` \| `None`	Telegram ID ответственного аккаунта, которому бот пересылает подписанные документы и копию DOCX, полученного через `POST /cargo-docx`.	`None`
`SIGNED_DOCS_DIR`	`str` \| `None`	Каталог для сохранения входящих подписанных документов (`.doc/.docx/.pdf`). Если не задан — используется `storage/signed_docs`.	`None`

Tip

Если у вас не работает POST /cargo-assigned и сервис отвечает business_connection_id not available yet (422), значит не задан BUSINESS_CONNECTION_ID.
Это значение приходит от Telegram Business во входящих сообщениях и лежит в поле business_connection_id. Обычно его берут из первого входящего update, прописывают в .env и перезапускают сервис.

Warning

BUSINESS_CONNECTION_ID может «протухнуть» (Telegram начнёт отвечать 403 на отправку). В этом случае POST /cargo-assigned вернёт 500 с текстом про устаревшее соединение.
Обычно помогает получить актуальный business_connection_id из нового входящего сообщения и обновить переменную окружения.

Note

services/signed_documents.py принимает только .doc/.docx/.pdf и режет файлы больше 20 МБ (по сигнатуре, а не по расширению).

Telethon (отправка файлов как пользователь)

Telegram‑бот использует Telethon для отправки DOCX‑документов пользователю и ответственному аккаунту. В текущей реализации Telethon инициализируется в on_startup() и при отсутствии настроек бот не стартует.

Name	Type	Description	Default
`TELETHON_API_ID`	`int`	`api_id` приложения Telegram для Telethon. Обязателен для запуска.	—
`TELETHON_API_HASH`	`str`	`api_hash` приложения Telegram для Telethon. Обязателен для запуска.	—
`TELETHON_SESSION`	`str`	Путь до файла сессии Telethon (должен быть авторизован). Обязателен.	—

Note

Если Telethon не видит получателя в своих диалогах, POST /cargo-docx может вернуть 422 recipient not found in telethon dialogs.
Это не «падение бота»: просто аккаунт Telethon не может отправить файл этому получателю, пока не появится диалог/контакт.

Интеграция с Lardi и практическая настройка

В проекте есть также интеграция с Lardi. Токен LARDI_API используется в MCP‑сервере при работе с Lardi API, а в Telegram‑боте этот параметр может понадобиться только при появлении прямых вызовов Lardi из Telegram‑слоя.

Переменные окружения для интеграции с Lardi

Name	Type	Description	Default
`LARDI_API`	`str`	Токен доступа к Lardi API. В текущей версии Telegram‑бот использует его опосредованно через MCP‑сервер, но переменная есть в `.env`.	—

На практике настройка выглядит так: вы копируете telegram-bot/env.example в .env, заполняете обязательные значения (бот, URL, OpenAI, параметры БД и MCP) и при необходимости добавляете дополнительные настройки — например, выбираете нестандартные модели Responses API или меняете лимит истории. Более подробный пример заполнения .env приведён в разделе «Быстрый старт».