---
read_when:
    - Робота з визначенням профілю автентифікації або маршрутизацією облікових даних
    - Діагностика помилок автентифікації моделі або порядку профілів
summary: Канонічна семантика придатності та розв’язання облікових даних для профілів автентифікації
title: Семантика облікових даних автентифікації
x-i18n:
    generated_at: "2026-04-30T20:36:55Z"
    model: gpt-5.5
    provider: openai
    source_hash: 39b9f96159d5a7b793983d07c37a73139a0904abbbc8831267807d6acf5c0037
    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` за замовчуванням не портативні, оскільки токени оновлення можуть бути одноразовими або чутливими до ротації.
- OAuth-потоки, що належать провайдеру, можуть увімкнути це через `copyToAgents: true` лише коли відомо, що копіювання матеріалу оновлення між агентами є безпечним.

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

## Фільтрування явного порядку автентифікації

- Коли для провайдера задано `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.`

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

## Пов’язане

- [Керування секретами](/uk/gateway/secrets)
- [Сховище автентифікації](/uk/concepts/oauth)
