06. Модели и провайдеры

AstraCode работает с разными большими языковыми моделями (LLM) через провайдеров — это endpoint'ы (URL), куда AstraCode шлёт запросы. Один провайдер обычно даёт несколько моделей. Этот документ — как выбрать, добавить, переключиться.

Что такое модель и провайдер

• Модель — конкретный «мозг», например gpt-5 или claude-sonnet-4-6 или llama-3.3-70b. Каждая модель имеет свои сильные стороны (быстрее / умнее / дешевле / большой контекст).
• Провайдер — кто хостит модель и предоставляет API: OpenAI, Anthropic, локальный server, on-prem gateway.

Один провайдер = один API endpoint = свой API-ключ.

Команда /model

В TUI:

/model

Откроется трёхколонный picker:

┌─ Provider ────────┬─ Status ─────┬─ Models ──────────────┐
│ OpenAI            │ Online       │ gpt-5                 │
│                   │              │ gpt-5-mini            │
│                   │              │ gpt-4o                │
│                   │              │ o3-mini               │
│ Company GPT       │ Online       │ claude-sonnet-4-6     │
│                   │              │ claude-opus-4-8       │
│ Local AstraCode   │ Needs key    │ —                     │
│                   │              │                       │
│ + Add provider                                            │
└────────────────────────────────────────────────────────────┘
↑↓ navigate · Enter activate · r refresh · d delete · Esc cancel

• Стрелки — навигация.
• Enter — активировать выделенную модель.
• r — обновить каталог моделей у провайдера.
• d — удалить провайдера (и его API-ключ).
• Esc — отмена.

В picker попадают провайдеры, которые вы сами добавили (через UI или config.toml). Зарезервированные/встроенные идентификаторы — только openai и amazon-bedrock; прочие провайдеры (Anthropic, Together, локальные и т.п.) добавляете вы сами.

Добавить нового провайдера

В picker'е стрелкой вниз доходите до + Add provider и Enter. Откроется одна форма с тремя полями на одном экране: Display name, Base URL, API key.

Display name

Любое человекочитаемое имя — My Local LLM, Company GPT, Personal OpenAI. Только для UI, не должно быть уникальным.

Base URL

Корневой URL API. Обязательно /v1-совместимый с OpenAI (Chat Completions). Примеры:

URL валидируется при сохранении.

API key

Bearer-токен. Шифруется и хранится в ~/.astracode/secrets/local.age. Видим только вам.

Поле опционально — если провайдеру не нужен ключ (например, локальный llama.cpp), можно оставить его пустым.

После добавления

Провайдер появится в picker'е. Выберите модель, Enter — активирована для последующих turn'ов.

Сменить модель / провайдера на лету

Просто /model → выбрать другую → Enter. Текущая сессия продолжится с новой модели; что было до — остаётся в истории.

Выбор сохраняется автоматически в [ui_state] файла ~/.astracode/config.toml. При следующем запуске AstraCode возьмёт ту же модель.

Удалить провайдера

В picker'е выделите провайдера, d. Удалится из конфига и сотрётся его API-ключ из secrets.

⚠️ Безвозвратно. Для провайдеров нет режима временного отключения: при необходимости изменить настройки удалите провайдера и добавьте его заново.

Редактирование провайдера

Редактирования провайдера на месте в 0.5.1 нет. Чтобы изменить display name, Base URL или API key, удалите провайдера клавишей d и добавьте заново через + Add provider.

После удаления AstraCode также очищает сохранённый ключ и состояние выбора этого провайдера. Роли сабагентов, которые ссылались на него, возвращаются к наследованию основной модели.

Модели для сабагентов

Команда /submodel открывает read-only вариант model picker'а с колонкой ролей:

• w назначает выделенную модель роли worker;
• e — роли explorer;
• c — пользовательской роли custom;
• роль без явного назначения наследует модель, выбранную в /model.

Назначения сохраняются в [ui_state.role_models] файла config.toml. Добавление, удаление и обновление провайдеров выполняется только через /model.

Команда /subagent управляет пользовательскими ролями сабагентов: через форму можно добавить, изменить или удалить имя и описание роли. Эти роли сохраняются в конфигурации и становятся доступны при запуске сабагентов.

Какую модель выбрать

Никакого «лучшего» ответа — зависит от задач, бюджета, доступности. Ориентиры:

Цена и скорость варьируются: смотрите на сайтах провайдеров.

Конфигурация в config.toml

Когда хотите менять много или скриптом — редактируйте ~/.astracode/config.toml напрямую:

default_provider = "openai"
model = "gpt-5"
model_context_window = 200000
model_auto_compact_token_limit = 180000
model_reasoning_effort = "medium"   # none | minimal | low | medium | high | xhigh

# Провайдер для /review (отдельно от основной модели)
review_model = "claude-sonnet-4-6"

[[providers]]
id = "openai"
display_name = "OpenAI"
base_url = "https://api.openai.com/v1"

[[providers]]
id = "anthropic"
display_name = "Anthropic"
base_url = "https://api.anthropic.com/v1"

[[providers]]
id = "company-llm"
display_name = "Company LLM Gateway"
base_url = "https://llm.company.internal/v1"

default_provider — top-level поле ConfigToml, оно пишется в корне конфига, а не внутри секции [[providers]].

Изменения применяются при следующем запуске. Чтобы перезагрузить «на горячую» — /new.

Параметры модели

model_context_window

Размер контекста модели в токенах (например, 200000 для GPT-5, 200000 для Claude 4). AstraCode использует это, чтобы предупреждать о приближении к лимиту.

model_auto_compact_token_limit

Когда токены превысят этот порог, AstraCode сам предложит /compact. По умолчанию — 70% от model_context_window, но не более 120 000 токенов.

model_reasoning_effort

Для моделей с extended thinking (o1, o3, GPT-5 reasoning, Claude extended thinking): - none — без размышлений. - minimal — минимальные. - low — короткие. - medium — стандарт (по умолчанию). - high — длинные (дольше, дороже, но точнее). - xhigh — максимальные.

review_model

Отдельная модель для команды /review. Хорошая практика — взять более дешёвую/быструю чем основная.

personality

Выбор фиксированного стиля ответов модели: none, friendly, pragmatic. Переключается командой /personality (popup) — это меняет стиль на текущую сессию и намеренно не пишет в config.toml. Чтобы задать постоянное значение, впишите personality = "friendly" в config.toml вручную (поле существует). Директории ~/.astracode/personalities/ нет — стили захардкожены.

On-prem / self-hosted

Подробно — 02-installation.md. Кратко:

default_provider = "company-llm"

[[providers]]
id = "company-llm"
display_name = "Company LLM"
base_url = "https://llm.company.internal/v1"

default_provider указывает, какой из [[providers]] активировать по умолчанию; это top-level поле, оно стоит в корне конфига, отдельно от секций провайдеров.

Если у gateway self-signed CA:

export ASTRACODE_CA_CERTIFICATE=/etc/ssl/certs/company-ca.pem
astracode

API-ключи: где живут и безопасны ли

• Все ключи зашифровываются библиотекой age: содержимое защищено ChaCha20-Poly1305, а ключ шифрования выводится из passphrase через scrypt.
• Сам файл секретов — ~/.astracode/secrets/local.age.
• Passphrase (от которой scrypt-деривация даёт ключ) хранится в одном из двух мест:
• режим keyring — в OS keyring;
• режим file — в файле ~/.astracode/secrets/local.key (защищён правами доступа).
• Режим задаётся переменной окружения ASTRACODE_PROVIDER_SECRETS_KEY_STORAGE (keyring / file / auto). Значение auto означает «keyring, если доступен, иначе файл». По умолчанию на macOS — file (релизы ad-hoc подписаны, Keychain не даёт стабильного доступа), на остальных платформах — auto.
• В config.toml ключи никогда не пишутся — только идентификаторы провайдеров.

Подробнее — 13-safety.md.

Сколько денег я трачу

/status показывает текущий расход токенов в сессии. По провайдерам: - OpenAI — https://platform.openai.com/usage. - Anthropic — https://console.anthropic.com/dashboard.

Стоимость за 1k токенов меняется — смотрите в дашбордах. Грубо: - Haiku / mini-модели: $0.0001-0.001 за 1k токенов. - Sonnet / 4o: $0.003-0.015 за 1k токенов. - Opus / GPT-5: $0.015-0.075 за 1k токенов.

Длинная сессия с большим контекстом и многими tool-вызовами легко съест $1-5. Для тех, кто работает много — стоит выбирать дешёвые модели на рутину и дорогие на сложное.

Несколько профилей с разными провайдерами

Если хотите разные конфиги для рабочих и личных задач:

# Рабочие — корпоративный gateway
ASTRACODE_HOME=~/.astracode-work astracode

# Личные — OpenAI
ASTRACODE_HOME=~/.astracode-personal astracode

Каждая директория — полностью изолирована: свои секреты, свои сессии, свой конфиг.

Прокси

Если выход в интернет через прокси, настройте секцию [network] в ~/.astracode/config.toml:

# ~/.astracode/config.toml
[network]
enabled = true
proxy_url = "http://proxy.company.com:3128"
socks_url = "socks5://proxy.company.com:1080"
mode = "full"
domains = ["*.internal", "localhost"]

Поля секции [network]: proxy_url, socks_url, enabled, mode, domains. mode — limited (только чтение: GET/HEAD/OPTIONS, SOCKS5 заблокирован) или full (по умолчанию — полный доступ, HTTPS-CONNECT туннелируется).

Или через env: HTTP_PROXY, HTTPS_PROXY, NO_PROXY.

Если что-то не работает

См. 15-troubleshooting.md. Типовые:

• Could not find suitable model provider — провайдер не настроен. /model → добавить.
• 401 Unauthorized — API-ключ протух или неверный. /model → отредактировать ключ (или удалить и добавить заново).
• Rate limit exceeded — провайдер ограничивает запросы. Подождать или сменить тариф.
• Failed to decrypt secrets file — passphrase/keyring разъехался с файлом. rm ~/.astracode/secrets/local.age (потеряете ключи) и заново.