---
read_when:
    - Робота з визначенням профілю автентифікації або маршрутизацією облікових даних
    - Налагодження збоїв автентифікації моделі або порядку профілів
summary: Канонічні правила придатності та визначення облікових даних для профілів автентифікації
title: Семантика облікових даних автентифікації
x-i18n:
    generated_at: "2026-07-12T12:57:26Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 6b0516b1bb23f400d5ac5fd39a628736034440216ac22823eef061b38564dff0
    source_path: auth-credential-semantics.md
    workflow: 16
---

Ця семантика узгоджує поведінку автентифікації під час вибору та виконання. Її спільно використовують:

- `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, яким керує Plugin. Ідентифікатори цих профілів можуть бути в `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` і подробицю `Виключено через auth.order для цього провайдера.`

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

- Цілі перевірки можуть походити з профілів автентифікації, облікових даних середовища або `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` — лише для збереженої автентифікації або автентифікації Plugin, `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]: ...`.

## Пов’язані матеріали

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