---
read_when:
    - Працюєте з розв’язанням профілю автентифікації або маршрутизацією облікових даних
    - Налагодження помилок автентифікації моделі або порядку профілів
summary: Канонічна придатність облікових даних і семантика визначення для профілів автентифікації
title: Семантика облікових даних автентифікації
x-i18n:
    generated_at: "2026-06-27T17:09:00Z"
    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` типово не портативні, оскільки токени оновлення можуть бути
  одноразовими або чутливими до ротації.
- OAuth-потоки, якими володіє провайдер, можуть увімкнути це через `copyToAgents: true` лише тоді, коли
  відомо, що копіювання матеріалу оновлення між агентами безпечне.

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

## Маршрути автентифікації лише з конфігурації

Записи `auth.profiles` з `mode: "aws-sdk"` є метаданими маршрутизації, а не збереженими
обліковими даними. Вони чинні, коли цільовий провайдер використовує
`models.providers.<id>.auth: "aws-sdk"` або AWS SDK-маршрут налаштування Amazon Bedrock,
яким володіє Plugin. Ці ідентифікатори профілів можуть з’являтися в `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.`

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

## Пов’язане

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