Gateway

Семантика учетных данных аутентификации

Этот документ определяет канонические семантики допустимости и разрешения учетных данных, используемые в:

resolveAuthProfileOrder
resolveApiKeyForProfile
models status --probe
doctor-auth

Цель — сохранить согласованность поведения во время выбора и во время выполнения.

Стабильные коды причин проверки

ok
excluded_by_auth_order
missing_credential
invalid_expires
expired
unresolved_ref
no_model

Учетные данные токенов

Учетные данные токенов (type: "token") поддерживают встроенный token и/или tokenRef.

Правила допустимости

Профиль токена недопустим, когда отсутствуют и token, и tokenRef.
expires необязателен.
Если expires присутствует, он должен быть конечным числом больше 0.
Если expires недействителен (NaN, 0, отрицательное значение, неконечное значение или неверный тип), профиль недопустим с invalid_expires.
Если expires находится в прошлом, профиль недопустим с expired.
tokenRef не обходит проверку expires.

Правила разрешения

Семантика резолвера для expires соответствует семантике допустимости.
Для допустимых профилей материал токена может быть разрешен из встроенного значения или tokenRef.
Неразрешимые ссылки дают unresolved_ref в выводе models status --probe.

Переносимость копии агента

Наследование аутентификации агента выполняется сквозным чтением. Когда у агента нет локального профиля, он может разрешать профили из хранилища агента по умолчанию/основного агента во время выполнения без копирования секретного материала в собственный auth-profiles.json.

Явные потоки копирования, такие как openclaw agents add, используют эту политику переносимости:

Профили api_key переносимы, если не указано copyToAgents: false.
Профили token переносимы, если не указано copyToAgents: false.
Профили oauth по умолчанию не переносимы, потому что refresh tokens могут быть одноразовыми или чувствительными к ротации.
Потоки OAuth, принадлежащие провайдеру, могут включать это с copyToAgents: true только когда известно, что копирование материала обновления между агентами безопасно.

Непереносимые профили остаются доступными через наследование со сквозным чтением, если только целевой агент не войдет отдельно и не создаст собственный локальный профиль.

Маршруты аутентификации только из конфигурации

Записи auth.profiles с mode: "aws-sdk" являются маршрутными метаданными, а не сохраненными учетными данными. Они допустимы, когда целевой провайдер использует models.providers.<id>.auth: "aws-sdk" или принадлежащий Plugin маршрут AWS SDK для настройки Amazon Bedrock. Эти идентификаторы профилей могут появляться в auth.order и переопределениях сессии, даже когда в auth-profiles.json нет соответствующей записи.

Не записывайте type: "aws-sdk" в auth-profiles.json. Если в устаревшей установке есть такой маркер, openclaw doctor --fix переносит его в auth.profiles и удаляет маркер из хранилища учетных данных.

Явная фильтрация порядка аутентификации

Когда для провайдера задан auth.order.<provider> или переопределение порядка в хранилище аутентификации, models status --probe проверяет только идентификаторы профилей, которые остаются в разрешенном порядке аутентификации для этого провайдера.
Сохраненный профиль для этого провайдера, отсутствующий в явном порядке, не пробуется позднее неявно. Вывод проверки сообщает о нем с reasonCode: excluded_by_auth_order и подробностью Excluded by auth.order for this provider.

Разрешение цели проверки

Цели проверки могут поступать из профилей аутентификации, учетных данных окружения или models.json.
Если у провайдера есть учетные данные, но OpenClaw не может разрешить проверяемую модель-кандидат для него, models status --probe сообщает status: no_model с reasonCode: no_model.

Обнаружение учетных данных внешнего CLI

Учетные данные только для времени выполнения, принадлежащие внешним CLI, обнаруживаются только когда провайдер, среда выполнения или профиль аутентификации находятся в области действия текущей операции, или когда сохраненный локальный профиль для этого внешнего источника уже существует.
Вызывающие стороны хранилища аутентификации должны выбирать явный режим обнаружения внешнего CLI: none для сохраненной/Plugin-аутентификации, existing для обновления уже сохраненных профилей внешнего CLI или scoped для конкретного набора провайдеров/профилей.
Пути только для чтения/статуса передают allowKeychainPrompt: false; они используют только файловые учетные данные внешнего CLI и не читают и не переиспользуют результаты macOS Keychain.

Ограничение политики OAuth SecretRef

Ввод SecretRef предназначен только для статических учетных данных.
Если учетные данные профиля имеют type: "oauth", объекты SecretRef не поддерживаются для материала учетных данных этого профиля.
Если auth.profiles.<id>.mode равно "oauth", ввод keyRef/tokenRef на базе SecretRef для этого профиля отклоняется.
Нарушения являются жесткими отказами в путях разрешения аутентификации при запуске/перезагрузке.

Сообщения, совместимые с устаревшими версиями

Для совместимости со скриптами ошибки проверки сохраняют эту первую строку без изменений:

Auth profile credentials are missing or expired.

Понятные человеку подробности и стабильные коды причин могут добавляться на последующих строках.

Связанные материалы

Was this useful?