beaver-agent/MODELS.md

Модели: как вводить новую (чеклист)

Единственное место с процедурой. Проверено 2026-09-01 боевым тестом на dell.

Главный инвариант

API отбрасывает новые модели по версии клиента. claude CLI 2.1.248 с --model claude-fable-5-1 получает от API 400: version 2.1.251 or newer is required — id проходит насквозь, но сервер режет по минимальной версии Claude Code для этой модели. Поэтому порядок строго такой: сначала CLI, потом id в конфигах.

CLI живёт в двух местах:

• гейтвей (контейнер на dell) — забандлен в питоновский пакет claude-agent-sdk (_bundled/claude), замораживается при сборке образа. Версия CLI = версия пакета, соответствие в CHANGELOG SDK (например 0.2.146 → CLI 2.1.248, 0.2.150 → 2.1.257).
• t3code на машинах (mac, dell-хост) — обычный claude пользователя (~/.local/share/claude/versions/…, /usr/local/bin/claude), сам автообновляется; вручную — claude update.

Чеклист «вышла новая модель X»

1. beaver-gateway: поднять SDK до версии с достаточно новым CLI: pyproject.toml (claude-agent-sdk>=…) + uv lock -P claude-agent-sdk, закоммитить, запушить main.
2. beaver-agent/config.py (строки ~383–399, список агентов): поменять id моделей у deep/dispatcher/… Effort там же.
3. beaver-agent/t3code.toml (дефолты t3code-mcp per-machine, model = "claudeAgent/…"): поменять id. Внимание: t3code для незнакомого ему слага теряет опции effort/contextWindow (см. ниже) — id должен быть в каталоге t3code, т.е. t3code-приложение должно быть обновлено.
4. Деплой: make deploy (push main:stable; образ гейтвея собирается из beaver-gateway#main при деплое, поэтому шаг 1 — раньше).
5. t3code на машинах: claude --version ≥ минимума модели (обычно уже сам обновился); само приложение t3code (alpha) обновляется nightly и привозит новую модель в каталог.

Проверить, какие id вообще существуют:

TOK=$(security find-generic-password -s "Claude Code-credentials" -w | jq -r .claudeAiOauth.accessToken)
curl -s https://api.anthropic.com/v1/models -H "Authorization: Bearer $TOK" \
  -H "anthropic-version: 2023-06-01" -H "anthropic-beta: oauth-2025-04-20" | jq -r '.data[].id'

Алиасы fable / opus / sonnet

CLI принимает голые алиасы и резолвит их в новейшую модель, которую знает установленный CLI (проверено: CLI 2.1.248 резолвит fable → claude-fable-5, не 5.1). Свойства:

• никогда не дают 400 «слишком старый клиент» — деградируют до старой модели;
• «всегда новейшая» они дают только при свежем CLI, так что шаг 1 чеклиста они не отменяют, но убирают шаги 2–3 (id в конфигах менять не надо);
• в t3code кастомный слаг (fable, opus, как и любой id вне каталога) имеет пустые capabilities → t3 не передаёт --effort и суффикс [1m] (ClaudeAdapter.ts: resolveClaudeEffort(caps,…) → undefined). Модель работает, но на дефолтном effort и дефолтном окне CLI.

Рекомендация: в config.py и t3code.toml можно перейти на алиасы, если устраивает «новейшее из того, что знает CLI»; explicit id — когда нужен точный контроль (и тогда обязательно проверять минимум версии CLI).