---
read_when:
    - Під час роботи над розв’язанням профілів автентифікації або маршрутизацією облікових даних
    - Під час налагодження збоїв автентифікації моделі або порядку профілів
summary: Канонічні правила придатності облікових даних і семантика розв’язання для профілів автентифікації
title: Семантика облікових даних автентифікації
x-i18n:
    generated_at: "2026-04-05T17:56:45Z"
    model: gpt-5.4
    provider: openai
    source_hash: a4cd3e16cd25eb22c5e707311d06a19df1a59747ee3261c2d32c534a245fd7fb
    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.`

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