Gateway

Семантика облікових даних автентифікації

Цей документ визначає канонічну придатність облікових даних і семантику розв’язання, що використовуються в:

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.

Правила придатності

Профіль токена непридатний, якщо відсутні і token, і tokenRef.
expires є необов’язковим.
Якщо expires наявний, він має бути скінченним числом, більшим за 0.
Якщо expires недійсний (NaN, 0, від’ємне значення, нескінченне значення або неправильний тип), профіль непридатний із invalid_expires.
Якщо expires у минулому, профіль непридатний із expired.
tokenRef не обходить перевірку expires.

Правила розв’язання

Семантика розв’язувача відповідає семантиці придатності для expires.
Для придатних профілів матеріал токена може бути розв’язаний із вбудованого значення або tokenRef.
Нерозв’язувані посилання створюють 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.

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

Пов’язане

Was this useful?