[2026-06-15] balda-valera.md: add key gotchas — OPENAI_BASE_URL, DOCKER_OPTS, restart vs up -d

personal/projects/balda/balda-valera.md

@@ -45,6 +45,36 @@ docker-compose build && docker-compose up -d
 2. `extractOtherMention()` — проверяет текст на @**Name**, где Name не равен botName и не @**all**/@**everyone**. Если найден чужой @mention — сообщение игнорируется.
 3. Детальное логирование в `handleAutoClaimMention` — видны все шаги от входа до ошибки.
 
+## Ключевые грабли
+
+### 1. OPENAI_BASE_URL — обязательная env var
+Norma не читает `base_url` из config.yaml для `provider: deepseek`. Она читает env `OPENAI_BASE_URL`.
+Без неё запросы уходят на `api.openai.com` (401).
+
+**В `.env` обязательно:**
+```
+OPENAI_BASE_URL=https://api.deepseek.com/v1
+```
+
+**ВАЖНО:** `docker-compose restart` не перечитывает `.env`. Нужно `docker-compose up -d` (пересоздание контейнера).
+
+### 2. DOCKER_OPTS — пустая строка убивает старт
+Если `DOCKER_OPTS=""` (или пустая строка в `.env`), norma падает на парсинге float:
+```
+strconv.ParseFloat: parsing ""
+```
+
+**Должен быть валидный JSON:**
+```
+DOCKER_OPTS={"max_tokens": 2048, "temperature": 0.7}
+```
+
+### 3. composerestart vs compose up -d
+- `docker-compose restart` — не перечитывает `.env`, не пересоздаёт контейнер
+- `docker-compose up -d` — пересоздаёт контейнер с обновлённым `.env`
+
+При изменении `.env` всегда использовать `up -d`.
+
 ## Конфигурация провайдера
 В `config.yaml` обязательно:
 ```yaml