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

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

• 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 типово не портативні, оскільки refresh-токени можуть бути одноразовими або чутливими до ротації.
• OAuth-потоки, якими володіє провайдер, можуть увімкнути це через copyToAgents: true лише тоді, коли відомо, що копіювання refresh-матеріалу між агентами безпечне.

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

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

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

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

# Пов’язане

• Керування секретами
• Зберігання автентифікації