---
read_when:
    - Работа с разрешением профиля аутентификации или маршрутизацией учетных данных
    - Отладка сбоев аутентификации модели или порядка профилей
summary: Каноническая семантика допустимости и разрешения учетных данных для профилей аутентификации
title: Семантика учетных данных аутентификации
x-i18n:
    generated_at: "2026-06-28T22:32:03Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 591c0384e1d43512252aaa7b362141b6bc93183b30b5847168758f86127f0663
    source_path: auth-credential-semantics.md
    workflow: 16
---

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

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