Семантика учётных данных аутентификации

Эта семантика обеспечивает согласованность поведения аутентификации при выборе и во время выполнения. Она используется совместно в:

• 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, принадлежащей плагину. Идентификаторы этих профилей могут встречаться в 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 и подробность Excluded by auth.order for this provider.

Разрешение цели проверки

• Цели проверки могут поступать из профилей аутентификации, учётных данных окружения или 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 только для сохранённой аутентификации/аутентификации плагина, 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]: ....

Связанные материалы

• Управление секретами
• Хранение данных аутентификации