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

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

• resolveAuthProfileOrder (упорядкування профілів)
• resolveApiKeyForProfile (визначення облікових даних під час виконання)
• openclaw models status --probe
• перевірки автентифікації openclaw doctor (doctor-auth)

Стабільні коди причин перевірки

Результати перевірки містять категорію status (ok, auth, rate_limit, billing, timeout, format, unknown, no_model), а також стабільний reasonCode, якщо перевірка так і не дійшла до виклику моделі:

Перевірки придатності повертають код причини 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]: ....

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

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