--- read_when: - Работа с разрешением профилей аутентификации или маршрутизацией учётных данных - Отладка ошибок аутентификации модели или порядка профилей summary: Канонические правила допустимости и разрешения учётных данных для профилей аутентификации title: Семантика учётных данных аутентификации x-i18n: generated_at: "2026-07-13T17:51:24Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 6b0516b1bb23f400d5ac5fd39a628736034440216ac22823eef061b38564dff0 source_path: auth-credential-semantics.md workflow: 16 --- Эта семантика обеспечивает согласованность поведения аутентификации при выборе и во время выполнения. Она используется совместно в: - `resolveAuthProfileOrder` (порядок профилей) - `resolveApiKeyForProfile` (разрешение учётных данных во время выполнения) - `openclaw models status --probe` - проверках аутентификации `openclaw doctor` (`doctor-auth`) ## Стабильные коды причин проверки Результаты проверки содержат категорию `status` (`ok`, `auth`, `rate_limit`, `billing`, `timeout`, `format`, `unknown`, `no_model`), а также стабильный код `reasonCode`, если проверка не дошла до вызова модели: | `reasonCode` | Значение | | ------------------------ | ---------------------------------------------------------------------------- | | `excluded_by_auth_order` | Профиль исключён из явно заданного порядка аутентификации для своего провайдера. | | `missing_credential` | Встроенные учётные данные или SecretRef не настроены. | | `expired` | Значение `expires` токена находится в прошлом. | | `invalid_expires` | `expires` не является допустимой положительной меткой времени Unix в мс. | | `unresolved_ref` | Не удалось разрешить настроенный SecretRef. | | `ineligible_profile` | Профиль несовместим с конфигурацией провайдера (включая некорректный ключ). | | `no_model` | Учётные данные существуют, но не удалось определить модель-кандидат для проверки. | Проверки допустимости сообщают `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//agent/openclaw-agent.sqlite`). Явные операции копирования, такие как `openclaw agents add`, используют следующую политику переносимости: - Профили `api_key` и `token` переносимы, если только `copyToAgents: false`. - Профили `oauth` по умолчанию непереносимы, поскольку токены обновления могут быть одноразовыми или зависеть от ротации. - OAuth-потоки, принадлежащие провайдеру, могут явно включить переносимость с помощью `copyToAgents: true`, только если известно, что копирование данных обновления между агентами безопасно; это разрешение применяется только тогда, когда профиль содержит встроенные данные токена доступа/обновления. Непереносимые профили остаются доступными через наследование со сквозным чтением, если целевой агент не выполнит отдельный вход и не создаст собственный локальный профиль. ## Маршруты аутентификации только из конфигурации Записи `auth.profiles` с `mode: "aws-sdk"` являются метаданными маршрутизации, а не сохранёнными учётными данными. Они допустимы, когда целевой провайдер использует `models.providers..auth: "aws-sdk"` — маршрут, записываемый настройкой Amazon Bedrock, принадлежащей плагину. Идентификаторы этих профилей могут встречаться в `auth.order` и переопределениях сеанса, даже если в хранилище учётных данных нет соответствующей записи. Не записывайте `type: "aws-sdk"` в хранилище учётных данных; сохранёнными учётными данными могут быть только `api_key`, `token` или `oauth`. Если устаревший `auth-profiles.json` содержит такой маркер, `openclaw doctor --fix` перемещает его в `auth.profiles` и удаляет маркер из хранилища. ## Фильтрация по явно заданному порядку аутентификации - Если для провайдера задано `auth.order.` или переопределение порядка в хранилище аутентификации, `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..mode` имеет значение `"oauth"`, ввод `keyRef`/`tokenRef` на основе SecretRef для этого профиля отклоняется. - Нарушения приводят к жёстким сбоям (выбрасываемым ошибкам) в путях подготовки секретов при запуске/перезагрузке и разрешения профилей. ## Сообщения с поддержкой устаревших сценариев Для совместимости со сценариями первая строка ошибок проверки остаётся неизменной: `Auth profile credentials are missing or expired.` Понятные человеку подробности и стабильный код причины следуют в последующих строках в формате `↳ Auth reason [code]: ...`. ## Связанные материалы - [Управление секретами](/ru/gateway/secrets) - [Хранение данных аутентификации](/ru/concepts/oauth)