Аутентификация

OpenClaw поддерживает OAuth и API-ключи для провайдеров моделей. Для постоянно работающего хоста Gateway наиболее предсказуемым вариантом является API-ключ; потоки подписки/OAuth также работают, если соответствуют модели учётной записи у вашего провайдера.

• Полное описание потока OAuth и структуры хранилища: /concepts/oauth
• Аутентификация на основе SecretRef (провайдеры env/file/exec): Управление секретами
• Коды допустимости и причин для учётных данных, используемые models status --probe: Семантика учётных данных аутентификации

Рекомендуемая настройка: API-ключ (любой провайдер)

1. Создайте API-ключ в консоли вашего провайдера.
2. Разместите его на хосте Gateway (компьютере, на котором работает openclaw gateway):

export <PROVIDER>_API_KEY="..."openclaw models status

3. Если Gateway работает под управлением systemd/launchd, поместите ключ в ~/.openclaw/.env, чтобы демон мог его прочитать:

cat >> ~/.openclaw/.env <<'EOF'&lt;PROVIDER&gt;_API_KEY=...EOF

4. Перезапустите процесс Gateway (или демон), затем выполните повторную проверку:

openclaw models statusopenclaw doctor

openclaw onboard также может хранить API-ключи для использования демоном, если вы не хотите самостоятельно управлять переменными окружения. Полный порядок загрузки переменных окружения (env.shellEnv, ~/.openclaw/.env, systemd/launchd) см. в разделе Переменные окружения.

Anthropic: повторное использование Claude CLI

Аутентификация с помощью токена настройки Anthropic остаётся поддерживаемым вариантом. Повторное использование Claude CLI (в стиле claude -p) также официально поддерживается для этой интеграции; если на хосте доступен вход через Claude CLI, этот вариант предпочтителен для локального использования и настольных систем. Для долговременно работающих хостов Gateway наиболее предсказуемым вариантом по-прежнему является API-ключ Anthropic, обеспечивающий явное управление оплатой на стороне сервера.

Настройка повторного использования Claude CLI на хосте:

# Выполните на хосте Gatewayclaude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

Процесс состоит из двух шагов: сначала выполните вход Claude Code в Anthropic на хосте, а затем укажите OpenClaw направлять выбор моделей Anthropic через локальный бэкенд claude-cli и сохранить соответствующий профиль аутентификации OpenClaw.

Если claude отсутствует в PATH, установите Claude Code или укажите путь к исполняемому файлу в agents.defaults.cliBackends.claude-cli.command.

Ввод токена вручную

Работает с любым провайдером; записывает данные в хранилище аутентификации SQLite соответствующего агента и обновляет конфигурацию:

openclaw models auth paste-token --provider openrouter

OpenClaw считывает профили аутентификации из openclaw-agent.sqlite каждого агента. Параметры конечной точки (baseUrl, api, идентификаторы моделей, заголовки, тайм-ауты) должны находиться в models.providers.<id> файла openclaw.json или models.json, а не в профилях аутентификации.

Если в старой установке всё ещё присутствует auth-profiles.json, auth-state.json или плоская структура наподобие { "openrouter": { "apiKey": "..." } }, выполните openclaw doctor --fix, чтобы импортировать её в SQLite; doctor сохраняет резервные копии с временными метками рядом с исходными файлами JSON.

Внешние маршруты аутентификации, такие как Bedrock auth: "aws-sdk", не являются учётными данными. Для именованного маршрута Bedrock задайте auth.profiles.<id>.mode: "aws-sdk" в openclaw.json — не записывайте type: "aws-sdk" в хранилище профилей аутентификации. openclaw doctor --fix переносит устаревшие маркеры AWS SDK из хранилища учётных данных в метаданные конфигурации.

Учётные данные на основе SecretRef

• Учётные данные api_key могут использовать keyRef: { source, provider, id }
• Учётные данные token могут использовать tokenRef: { source, provider, id }
• Профили в режиме OAuth отклоняют учётные данные SecretRef: если auth.profiles.<id>.mode имеет значение "oauth", то keyRef/tokenRef на основе SecretRef для этого профиля отклоняется.

Проверка состояния аутентификации моделей

openclaw models statusopenclaw doctor

Проверка, подходящая для автоматизации: код выхода 1 при истёкших или отсутствующих данных и 2 при приближении срока истечения:

openclaw models status --check

Проверки аутентификации в реальном времени (для сужения области добавьте --probe-provider, --probe-profile, --probe-timeout, --probe-concurrency или --probe-max-tokens):

openclaw models status --probe

Примечания:

• Строки результатов проверки могут формироваться из профилей аутентификации, учётных данных из переменных окружения или models.json.
• Если auth.order.<provider> не включает сохранённый профиль, проверка сообщает для него excluded_by_auth_order, не пытаясь его использовать.
• Если данные аутентификации существуют, но OpenClaw не может определить для этого провайдера модель, доступную для проверки, выводится status: no_model.
• Периоды ожидания после ограничения частоты запросов могут относиться к отдельным моделям: профиль, временно недоступный для одной модели, всё ещё может обслуживать другую модель того же провайдера.

Дополнительные эксплуатационные скрипты (systemd/Termux): Скрипты мониторинга аутентификации.

Ротация API-ключей (Gateway)

Некоторые провайдеры повторяют запрос с другим настроенным ключом, если вызов сталкивается с ограничением частоты запросов провайдера.

Порядок приоритета ключей для каждого провайдера:

1. OPENCLAW_LIVE_<PROVIDER>_KEY (одиночное переопределение, фиксирует один ключ)
2. <PROVIDER>_API_KEYS (список с разделителями-запятыми, пробелами или точками с запятой)
3. <PROVIDER>_API_KEY
4. <PROVIDER>_API_KEY_* (любая переменная окружения с этим префиксом)

Провайдеры Google (google, google-vertex) дополнительно используют GOOGLE_API_KEY в качестве резервного варианта. Перед использованием из объединённого списка удаляются дубликаты.

OpenClaw переходит к следующему ключу, только если сообщение об ошибке соответствует одному из следующих значений: rate_limit, rate limit, 429, quota exceeded/quota_exceeded, resource exhausted/resource_exhausted или too many requests. При других ошибках повторная попытка с альтернативными ключами не выполняется. Если не сработал ни один ключ, возвращается итоговая ошибка последней попытки.

Удаление сохранённых данных аутентификации не отзывает ключ у провайдера — если требуется аннулировать его на стороне провайдера, выполните ротацию или отзыв ключа на панели управления провайдера.

Удаление аутентификации провайдера во время работы Gateway

При удалении аутентификации провайдера через плоскость управления Gateway OpenClaw удаляет сохранённые профили аутентификации этого провайдера и прерывает активные чаты или запуски агентов, для которых выбранная модель относится к удалённому провайдеру. Прерванные запуски создают обычные события отмены и жизненного цикла с stopReason: "auth-revoked", поэтому подключённые клиенты могут показать, что запуск остановлен из-за удаления учётных данных.

Управление выбором учётных данных

OpenAI и устаревшие идентификаторы openai-codex

Профили API-ключей OpenAI и профили OAuth ChatGPT/Codex используют канонический идентификатор провайдера openai. Для новой конфигурации используйте идентификаторы профилей openai:* и auth.order.openai.

Если в старой конфигурации, идентификаторах профилей аутентификации или auth.order.openai-codex встречается openai-codex, считайте его устаревшими входными данными для миграции — не создавайте новые профили openai-codex. Выполните:

openclaw doctor --fixopenclaw models auth list --provider openai

Doctor преобразует устаревшие идентификаторы профилей openai-codex:* и записи auth.order.openai-codex в канонический маршрут openai. Подробнее о маршрутизации моделей и среды выполнения OpenAI см. в разделе OpenAI.

Во время входа (CLI)

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

--profile-id позволяет раздельно хранить несколько входов OAuth для одного провайдера в рамках одного агента.

--force удаляет сохранённые профили аутентификации этого провайдера из каталога выбранного агента, а затем повторно запускает тот же поток аутентификации. Используйте этот вариант, если сохранённый профиль завис, истёк или связан не с той учётной записью. Учётные данные у провайдера при этом не отзываются.

openclaw models auth login --provider anthropic --force

Для отдельного сеанса (команда чата)

• /model <alias-or-id>@<profileId> фиксирует определённые учётные данные провайдера для текущего сеанса (примеры идентификаторов профилей: anthropic:default, anthropic:work).
• /model (или /model list) показывает компактное средство выбора; /model status показывает полное представление (кандидаты и следующий профиль аутентификации, а также параметры конечной точки провайдера, если они настроены).

Если вы изменили порядок аутентификации или закрепление профиля для уже работающего чата, отправьте /new или /reset, чтобы начать новый сеанс — существующие сеансы сохраняют текущий выбор модели и профиля до сброса.

Для отдельного агента (переопределение через CLI)

Переопределения порядка аутентификации хранятся в состоянии аутентификации SQLite этого агента:

openclaw models auth order get --provider anthropicopenclaw models auth order set --provider anthropic anthropic:defaultopenclaw models auth order clear --provider anthropic

Используйте --agent <id>, чтобы указать определённого агента; если параметр не задан, используется настроенный агент по умолчанию. openclaw models status --probe отображает отсутствующие сохранённые профили как excluded_by_auth_order, а не молча пропускает их.

Устранение неполадок

«Учётные данные не найдены»

Настройте API-ключ Anthropic на хосте Gateway или настройте вариант с токеном настройки Anthropic, затем выполните повторную проверку:

openclaw models status

Срок действия токена истекает или уже истёк

Выполните openclaw models status, чтобы узнать, срок действия какого профиля истекает. Если профиль токена Anthropic отсутствует или срок его действия истёк, обновите его с помощью токена настройки либо перейдите на API-ключ Anthropic.

Связанные разделы

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