> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

* `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`.

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

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

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

1. Семантика резолвера для `expires` соответствует семантике допустимости.
2. Для допустимых профилей материал токена может быть разрешен из встроенного значения или `tokenRef`.
3. Неразрешимые ссылки дают `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.`

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

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

* [Управление секретами](/ru/gateway/secrets)
* [Хранилище аутентификации](/ru/concepts/oauth)