Home Assistant: голосовой ассистент на Claude через API

Разговорный движок Home Assistant умеет подключаться к внешнему OpenAI-совместимому API — это ровно тот протокол, который отдаёт шлюз на https://api.zukko.pro/v1. Дальше голосовой помощник работает как обычно: Assist слушает команду, переводит её в текст, текст уходит в модель, ответ озвучивается — разница только в том, чей ключ и чей счёт стоят за ответом.

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

Для интеграции с произвольным OpenAI-совместимым провайдером (например, широко используемая в сообществе Extended OpenAI Conversation) настройка через UI или YAML сводится к трём полям:

base_url: "https://api.zukko.pro/v1"
api_key: "fetch_ваш_ключ"
model: "gpt-5.6-sol"

Заголовок авторизации интеграция формирует сама — Authorization: Bearer fetch_... — вручную ничего добавлять не нужно. Модель можно указать любую из каталога (актуальный список — GET https://api.zukko.pro/v1/models): например, claude-sonnet-5 или лёгкую glm-5.3-flash, если хочется минимизировать задержку между командой и озвучкой, — какая звучит лучше для ваших команд, проверьте на практике.

Проверка ключа до того, как чинить YAML

Перед тем как разбираться, почему Home Assistant отвечает ошибкой, стоит убедиться, что ключ рабочий сам по себе:

curl https://api.zukko.pro/v1/chat/completions \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"включи свет на кухне"}]}'

Если curl отвечает нормально, а интеграция в HA — нет, дело в конфигурации, а не в доступе. Частая ошибка здесь та же, что и везде: адрес указан с лишним или недостающим /v1 — OpenAI-совместимые интеграции ждут суффикс /v1 в базовом адресе, без него любой запрос вернёт 404.

Лимит на ключ, потому что это семейное устройство

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

Мониторинг баланса прямо из Home Assistant

Раз HA умеет ходить в произвольный REST API, несложно завести сенсор, который сам следит за балансом:

sensor:
  - platform: rest
    name: zukko_balance
    resource: https://api.zukko.pro/v1/balance
    headers:
      Authorization: !secret zukko_api_key
    value_template: "{{ value_json.balance_cents / 100 }}"
    unit_of_measurement: "$"
    scan_interval: 3600

На основе этого сенсора можно повесить автоматизацию — уведомление в телефон, если баланс упал ниже условного порога, до того как голосовой ассистент внезапно замолчит с ошибкой 402.

Что произойдёт при ошибке

Если баланс закончился, ответ будет {"error":{"message":"Недостаточно средств на балансе","code":"insufficient_balance"}}, и Home Assistant озвучит либо системную фразу об ошибке, либо ничего — зависит от того, как настроена интеграция. Полезно помнить, что баланс проверяется до обращения к модели, так что сама эта неудачная попытка ничего не стоит, и повторный вызов сразу после пополнения отработает штатно, без перезапуска HA.

Если модель, которую вы указали в конфиге, выключили, ответ придёт с кодом 503 и model_disabled; актуальный список моделей — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете. Это стоит проверять в логах HA — если голосовой ассистент вдруг перестал отвечать без видимых изменений в конфиге, вероятная причина именно тут.

Одновременные запросы от нескольких членов семьи

Сами по себе одновременные запросы шлюз не ограничивает — своего rate limit у него нет. Но если вся семья активно пользуется ассистентом, а на ключе стоит жёсткий дневной или месячный лимит расхода в долларах, возможна ошибка 429 с кодом key_daily_limit_reached (сброс в 00:00 UTC) или key_monthly_limit_reached — в зависимости от того, какой лимит исчерпан. Отличить это от перегруза у провайдера модели (429 без этих кодов приходит именно от провайдера) можно по телу ответа: если код указывает конкретно на ключ, дело в настройках лимита.

Идемпотентность при нестабильном Wi-Fi

Голосовые колонки нередко сидят на слабом Wi-Fi-сигнале, и запрос иногда обрывается на середине без ответа. Если интеграция поддерживает пользовательские заголовки, стоит генерировать Idempotency-Key на каждый голосовой запрос и использовать его при автоматическом повторе: если исходный запрос на самом деле прошёл на сервере, повторная отправка с тем же ключом идемпотентности за 24 часа вернёт тот же ответ без повторного списания.

Если модель временно недоступна

Ответ 503 с кодом provider_unavailable или model_disabled означает, что конкретная модель на время выключена в каталоге — это не авария на стороне Home Assistant и не проблема с ключом. Если в конфиге интеграции указана только одна модель, разумно держать про запас второй профиль подключения с другой моделью (например, glm-5.3 вместо gpt-5.6-sol) и переключаться на него автоматизацией, если основной несколько раз подряд вернул 503. Для голосового ассистента в доме это особенно чувствительно: в отличие от чат-интерфейса, где можно просто повторить вопрос глазами прочитав ошибку, колонка в такой ситуации либо повторяет системную фразу об ошибке, либо просто молчит, и понять причину без взгляда в логи HA не получится.

Что писать в логах для будущего разбора

Если Assist в доме используют несколько человек, полезно логировать хотя бы код ошибки и время каждого неудачного запроса — через logger в конфиге компонента разговорного движка. Тогда при разборе вопроса «почему ассистент вчера вечером не отвечал» не приходится гадать между четырьмя разными причинами: пустой баланс, лимит ключа, отключённая модель или обычный сетевой сбой роутера. Каждая из них требует разного действия, а не одного и того же «перезагрузите Home Assistant», которое чаще всего проблему не решает.