docs/docs/uk/auth-credential-semantics.md

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

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

Пов’язане

• Керування секретами
• Сховище автентифікації