> ## 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` (разрешение учётных данных во время выполнения)
* `openclaw models status --probe`
* проверках аутентификации `openclaw doctor` (`doctor-auth`)

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

Результаты проверки содержат категорию `status` (`ok`, `auth`, `rate_limit`, `billing`, `timeout`, `format`, `unknown`, `no_model`), а также стабильный код `reasonCode`, если проверка не дошла до вызова модели:

| `reasonCode` | Значение |
| - | - |
| `excluded_by_auth_order` | Профиль исключён из явно заданного порядка аутентификации для своего провайдера. |
| `missing_credential` | Встроенные учётные данные или SecretRef не настроены. |
| `expired` | Значение `expires` токена находится в прошлом. |
| `invalid_expires` | `expires` не является допустимой положительной меткой времени Unix в мс. |
| `unresolved_ref` | Не удалось разрешить настроенный SecretRef. |
| `ineligible_profile` | Профиль несовместим с конфигурацией провайдера (включая некорректный ключ). |
| `no_model` | Учётные данные существуют, но не удалось определить модель-кандидат для проверки. |

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

## Учётные данные токена

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

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

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

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

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

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

Наследование аутентификации агентом выполняется сквозным чтением. Если у агента нет локального профиля, во время выполнения он разрешает профили из хранилища агента по умолчанию/основного агента, не копируя секретные данные в собственное хранилище учётных данных (`agents/<agentId>/agent/openclaw-agent.sqlite`).

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

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

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

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

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

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

## Фильтрация по явно заданному порядку аутентификации

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

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

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

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

* Учётные данные только для времени выполнения, принадлежащие внешним CLI (Claude CLI для `claude-cli`, Codex CLI для `openai`, MiniMax CLI для `minimax-portal`), обнаруживаются только тогда, когда провайдер, среда выполнения или профиль аутентификации входит в область текущей операции либо уже существует сохранённый локальный профиль для этого внешнего источника.
* Вызывающий код хранилища аутентификации выбирает явный режим обнаружения внешних CLI: `none` только для сохранённой аутентификации/аутентификации плагина, `existing` для обновления уже сохранённых профилей внешних CLI или `scoped` для конкретного набора провайдеров/профилей.
* Пути только для чтения/получения состояния передают `allowKeychainPrompt: false`; они используют только файловые учётные данные внешних CLI и не считывают и не используют повторно результаты macOS Keychain.

## Защитная политика OAuth для SecretRef

Ввод SecretRef предназначен только для статических учётных данных. Учётные данные OAuth изменяются во время выполнения (потоки обновления сохраняют ротированные токены), поэтому OAuth-данные на основе SecretRef разделили бы изменяемое состояние между хранилищами.

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

## Сообщения с поддержкой устаревших сценариев

Для совместимости со сценариями первая строка ошибок проверки остаётся неизменной:

`Auth profile credentials are missing or expired.`

Понятные человеку подробности и стабильный код причины следуют в последующих строках в формате `↳ Auth reason [code]: ...`.

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

* [Управление секретами](https://docs2.openclaw.ai/ru/gateway/secrets.md)
* [Хранение данных аутентификации](https://docs2.openclaw.ai/ru/concepts/oauth.md)