---
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/<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]: ...`.

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

- [Управление секретами](/ru/gateway/secrets)
- [Хранение данных аутентификации](/ru/concepts/oauth)
