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

Единственное место с процедурой. Проверено 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](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md)
  (например 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 вообще существуют:

```bash
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).