Пулы учётных данных
Пулы учётных данных позволяют зарегистрировать несколько API-ключей или OAuth-токенов для одного провайдера. Когда один ключ достигает лимита запросов или квоты биллинга, VibeOS автоматически переключается на следующий рабочий ключ — ваш сеанс остаётся активным без смены провайдера.
Это отличается от резервных провайдеров, которые переключаются на другого провайдера полностью. Пулы учётных данных — это ротация в рамках одного провайдера; резервные провайдеры — это аварийное переключение между провайдерами. Сначала используются пулы — если все ключи в пуле исчерпаны, тогда активируется резервный провайдер.
Пулы учётных данных в основном предназначены для провайдеров с API-ключами (OpenRouter, Anthropic). Единый OAuth-доступ через Nous Portal покрывает более 300 моделей, поэтому большинству пользователей пул не нужен при работе через Portal.
Как это работает
Ваш запрос
→ Выбор ключа из пула (round_robin / least_used / fill_first / random)
→ Отправка провайдеру
→ 429 — превышение лимита запросов?
→ Достигнут лимит плана/использования (например, «usage limit reached» от ChatGPT/Codex)?
→ Немедленная ротация на следующий ключ в пуле (без повторной попытки — лимит не снимется при повторе)
→ Общий / временный 429?
→ Одна повторная попытка с тем же ключом (временный сбой)
→ Второй 429 → ротация на следующий ключ в пуле
→ Все ключи исчерпаны → fallback_model (другой провайдер)
→ 402 — ошибка биллинга?
→ Немедленная ротация на следующий ключ в пуле (тайм-аут 24 часа)
→ 401 — срок действия токена истёк?
→ Попытка обновить токен (OAuth)
→ Обновление не удалось → ротация на следующий ключ в пуле
→ Успех → продолжение в обычном режиме
Быстрый старт
Если у вас уже есть API-ключ, заданный в .env, VibeOS автоматически обнаружит его как пул из одного ключа. Чтобы воспользоваться преимуществами пула, добавьте больше ключей:
# Добавление второго ключа OpenRouter
vibeos auth add openrouter --api-key sk-or-v1-your-second-key
# Добавление второго ключа Anthropic
vibeos auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key
# Добавление OAuth-учётных данных Anthropic (требуется план Claude Max + дополнительные кредиты на использование)
vibeos auth add anthropic --type oauth
# Откроется браузер для входа через OAuth
Проверьте свои пулы:
vibeos auth list
Вывод:
openrouter (2 учётных данных):
#1 OPENROUTER_API_KEY api_key env:OPENROUTER_API_KEY ←
#2 backup-key api_key manual
anthropic (3 учётных данных):
#1 vibeos_pkce oauth vibeos_pkce ←
#2 claude_code oauth claude_code
#3 ANTHROPIC_API_KEY api_key env:ANTHROPIC_API_KEY
Символ ← отмечает текущее выбранное учётное данное.
Интерактивное управление
Запустите vibeos auth без подкоманды для интерактивного мастера:
vibeos auth
Отобразится полный статус вашего пула и меню:
Что вы хотите сделать?
1. Добавить учётные данные
2. Удалить учётные данные
3. Сбросить тайм-ауты для провайдера
4. Установить стратегию ротации для провайдера
5. Выйти
Для провайдеров, поддерживающих как API-ключи, так и OAuth (Anthropic, Nous, Codex), мастер добавления запрашивает тип:
anthropic поддерживает как API-ключи, так и вход через OAuth.
1. API-ключ (вставьте ключ из панели управления провайдера)
2. Вход через OAuth (аутентификация через браузер)
Введите [1/2]:
Команды CLI
| Команда | Описание |
|---|---|
vibeos auth | Интерактивный мастер управления пулом |
vibeos auth list | Показать все пулы и учётные данные |
vibeos auth list <provider>` | Показать пул конкретного провайдера |
vibeos auth add <provider>` | Добавить учётные данные (запрашивает тип и ключ) |
vibeos auth add <provider> --type api-key --api-key <key>` | Добавить API-ключ в неинтерактивном режиме |
vibeos auth add <provider> --type oauth | Добавить OAuth-учётные данные через вход в браузере |
vibeos auth remove <provider> <index>` | Удалить учётные данные по индексу (начиная с 1) |
vibeos auth reset <provider>` | Очистить все тайм-ауты и статусы исчерпания |
Стратегии ротации
Настройка через vibeos auth → «Установить стратегию ротации» или в config.yaml:
credential_pool_strategies:
openrouter: round_robin
anthropic: least_used
| Стратегия | Поведение |
|---|---|
fill_first (по умолчанию) | Использовать первый рабочий ключ до его исчерпания, затем перейти к следующему |
round_robin | Циклически перебирать ключи равномерно, ротация после каждого выбора |
least_used | Всегда выбирать ключ с наименьшим количеством запросов |
random | Случайный выбор среди рабочих ключей |
Восстановление после ошибок
Пул обрабатывает разные ошибки по-разному:
| Ошибка | Поведение | Тайм-аут |
|---|---|---|
| 429 — превышение лимита запросов | Одна повторная попытка с тем же ключом (временный сбой). Второй последовательный 429 — ротация на следующий ключ | 1 час |
| 402 — ошибка биллинга/квоты | Немедленная ротация на следующий ключ | 24 часа |
| 401 — срок действия аутентификации истёк | Сначала попытка обновить OAuth-токен. Ротация только в случае неудачи обновления | — |
| Все ключи исчерпаны | Переход к fallback_model, если настроен | — |
Флаг has_retried_429 сбрасывается при каждом успешном вызове API, поэтому одиночный временный 429 не вызывает ротацию.
Пулы пользовательских конечных точек
Пользовательские конечные точки, совместимые с OpenAI (Together.ai, RunPod, локальные серверы), получают собственные пулы, ключом которых является имя конечной точки из custom_providers в config.yaml.
При настройке пользовательской конечной точки через vibeos model автоматически генерируется имя, например «Together.ai» или «Local (localhost:8080)». Это имя становится ключом пула.
# После настройки пользовательской конечной точки через vibeos model:
vibeos auth list
# Отображается:
# Together.ai (1 учётные данные):
# #1 config key api_key config:Together.ai ←
# Добавление второго ключа для той же конечной точки:
vibeos auth add Together.ai --api-key sk-together-second-key
Пулы пользовательских конечных точек хранятся в auth.json под ключом credential_pool с префиксом custom::
{
"credential_pool": {
"openrouter": [...],
"custom:together.ai": [...]
}
}
Автообнаружение
VibeOS автоматически обнаруживает учётные данные из нескольких источников и заполняет пул при запуске:
| Источник | Пример | Автозаполнение? |
|---|---|---|
| Переменные окружения | OPENROUTER_API_KEY, ANTHROPIC_API_KEY | Да |
| OAuth-токены (auth.json) | Код устройства Codex, код устройства Nous | Да |
| Учётные данные Claude Code | ~/.claude/.credentials.json | Да (Anthropic) |
| PKCE OAuth VibeOS | ~/.vibeos/auth.json | Да (Anthropic) |
| Конфигурация пользовательской конечной точки | model.api_key в config.yaml | Да (пользовательские конечные точки) |
| Ручные записи | Добавлены через vibeos auth add | Сохраняются в auth.json |
Автозаполненные записи обновляются при каждой загрузке пула — если вы удалите переменную окружения, соответствующая запись в пуле будет автоматически удалена. Ручные записи (добавленные через vibeos auth add) никогда не удаляются автоматически.
Заимствованные секреты времени выполнения (например, переменные окружения, ссылки на Bitwarden/Vault/keyring/systemd и значения пользовательской конфигурации) хранятся только как ссылки на границе auth.json. VibeOS может использовать разрешённое значение в памяти для текущего запуска, но сохраняет только метаданные, такие как ссылка на источник, метка, статус, счётчики запросов и необратимый отпечаток. Ручные записи и состояние OAuth/кода устройства, принадлежащее VibeOS, сохраняют необходимые долговременные токены для обновления.
Делегирование и совместное использование с подчинёнными агентами
Когда агент порождает подчинённых агентов через delegate_task, пул учётных данных родителя автоматически передаётся дочерним агентам:
- Тот же провайдер — дочерний агент получает полный пул родителя, что обеспечивает ротацию ключей при ограничениях скорости
- Другой провайдер — дочерний агент загружает собственный пул этого провайдера (если настроен)
- Пул не настроен — дочерний агент использует унаследованный одиночный API-ключ
Таким образом, подчинённые агенты получают такую же устойчивость к ограничениям скорости, как и родитель, без необходимости дополнительной настройки. Позадачная аренда учётных данных гарантирует, что дочерние агенты не конфликтуют друг с другом при одновременной ротации ключей.
Потокобезопасность
Пул учётных данных использует блокировку потоков для всех изменений состояния (select(), mark_exhausted_and_rotate(), try_refresh_current(), mark_used()). Это обеспечивает безопасный конкурентный доступ, когда шлюз обрабатывает несколько сеансов чата одновременно.
Архитектура
Полную диаграмму потока данных см. в docs/credential-pool-flow.excalidraw в репозитории.
Пул учётных данных интегрируется на уровне разрешения провайдера:
agent/credential_pool.py— Менеджер пула: хранение, выбор, ротация, тайм-аутыvibeos_cli/auth_commands.py— Команды CLI и интерактивный мастерvibeos_cli/runtime_provider.py— Разрешение учётных данных с учётом пулаrun_agent.py— Восстановление после ошибок: 429/402/401 → ротация пула → резервный провайдер
Хранение
Состояние пула хранится в ~/.vibeos/auth.json под ключом credential_pool:
{
"version": 1,
"credential_pool": {
"openrouter": [
{
"id": "abc123",
"label": "OPENROUTER_API_KEY",
"auth_type": "api_key",
"priority": 0,
"source": "env:OPENROUTER_API_KEY",
"secret_source": "bitwarden",
"secret_fingerprint": "sha256:12ab34cd56ef7890",
"last_status": "ok",
"request_count": 142
}
],
"anthropic": [
{
"id": "manual1",
"label": "personal-api-key",
"auth_type": "api_key",
"priority": 0,
"source": "manual",
"access_token": "sk-ant-api03-..."
}
]
}
}
Запись OpenRouter выше была заимствована из внешнего источника, поэтому исходный ключ не хранится в auth.json. Ручная запись Anthropic была намеренно добавлена в хранилище учётных данных VibeOS, поэтому её токен остаётся сохраняемым.
Стратегии хранятся в config.yaml (не в auth.json):
credential_pool_strategies:
openrouter: round_robin
anthropic: least_used