---
read_when:
    - Робота над визначенням профілю автентифікації або маршрутизацією облікових даних
    - Налагодження збоїв автентифікації моделі або порядку профілів
summary: Канонічна відповідність облікових даних вимогам і семантика визначення для профілів автентифікації
title: Семантика облікових даних автентифікації
x-i18n:
    generated_at: "2026-04-23T20:43:02Z"
    model: gpt-5.4
    provider: openai
    source_hash: 94661670e510f4571f0e54488bd39772b76a6368448920a7b9362da00e8afc34
    source_path: auth-credential-semantics.md
    workflow: 15
---

Цей документ визначає канонічну відповідність облікових даних вимогам і семантику визначення, що використовуються в таких місцях:

- `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.order.<provider>` або перевизначення порядку сховища автентифікації, `models status --probe` перевіряє лише ті id профілів, які залишаються в визначеному порядку автентифікації для цього провайдера.
- Збережений профіль для цього провайдера, який пропущено в явному порядку, пізніше не перевіряється неявно. У виводі перевірки для нього буде вказано
  `reasonCode: excluded_by_auth_order` і деталь
  `Excluded by auth.order for this provider.`

## Визначення цілі перевірки

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

## Захисне правило політики OAuth SecretRef

- Вхід SecretRef призначений лише для статичних облікових даних.
- Якщо облікові дані профілю мають `type: "oauth"`, об’єкти SecretRef не підтримуються для матеріалу облікових даних цього профілю.
- Якщо `auth.profiles.<id>.mode` має значення `"oauth"`, вхід `keyRef`/`tokenRef` на основі SecretRef для цього профілю відхиляється.
- Такі порушення є жорсткими збоями в шляхах визначення автентифікації під час запуску/перезавантаження.

## Повідомлення зі збереженням сумісності зі старими версіями

Для сумісності зі скриптами помилки перевірки зберігають цей перший рядок без змін:

`Auth profile credentials are missing or expired.`

Зрозумілі для людини деталі та стабільні коди причин можуть бути додані в наступних рядках.
