Автентифікація

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

Див. /concepts/oauth, щоб переглянути повний потік OAuth і схему зберігання. Для автентифікації на основі SecretRef (постачальники env/file/exec) див. Керування секретами. Правила придатності облікових даних/кодів причин, які використовує models status --probe, див. у Семантика облікових даних автентифікації.

Рекомендоване налаштування (API-ключ, будь-який постачальник)

Якщо ви запускаєте довгоживучий Gateway, почніть з API-ключа для вибраного постачальника. Зокрема для Anthropic автентифікація за API-ключем усе ще є найпередбачуванішим серверним налаштуванням, але OpenClaw також підтримує повторне використання локального входу Claude CLI.

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

Потім перезапустіть демон (або перезапустіть процес Gateway) і перевірте знову:

openclaw models statusopenclaw doctor

Якщо ви не хочете самостійно керувати змінними середовища, onboarding може зберігати API-ключі для використання демоном: openclaw onboard.

Докладніше про успадкування середовища (env.shellEnv, ~/.openclaw/.env, systemd/launchd) див. у Довідці.

Anthropic: сумісність Claude CLI і токенів

Автентифікація Anthropic setup-token усе ще доступна в OpenClaw як підтримуваний шлях токена. Співробітники Anthropic відтоді повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і використання claude -p санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. Коли повторне використання Claude CLI доступне на хості, це тепер бажаний шлях.

Для довгоживучих хостів Gateway API-ключ Anthropic усе ще є найпередбачуванішим налаштуванням. Якщо ви хочете повторно використати наявний вхід Claude на тому самому хості, скористайтеся шляхом Anthropic Claude CLI в onboarding/configure.

Рекомендоване налаштування хоста для повторного використання Claude CLI:

# Run on the gateway hostclaude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

Це двоетапне налаштування:

1. Увійдіть у сам Claude Code в Anthropic на хості Gateway.
2. Повідомте OpenClaw, щоб він перемкнув вибір моделей Anthropic на локальний бекенд claude-cli і зберіг відповідний профіль автентифікації OpenClaw.

Якщо claude немає в PATH, спершу встановіть Claude Code або задайте agents.defaults.cliBackends.claude-cli.command як реальний шлях до бінарного файла.

Ручне введення токена (будь-який постачальник; записує сховище автентифікації SQLite для агента + оновлює конфігурацію):

openclaw models auth paste-token --provider openrouter

Сховище профілів автентифікації зберігає лише облікові дані. Застарілі файли auth-profiles.json використовували цю канонічну форму:

{  "version": 1,  "profiles": {    "openrouter:default": {      "type": "api_key",      "provider": "openrouter",      "key": "OPENROUTER_API_KEY"    }  }}

Тепер OpenClaw читає профілі автентифікації з openclaw-agent.sqlite кожного агента. Якщо старіше встановлення все ще має auth-profiles.json, auth-state.json або плаский файл профілю автентифікації, як-от { "openrouter": { "apiKey": "..." } }, запустіть openclaw doctor --fix, щоб імпортувати його в SQLite; doctor зберігає резервні копії з мітками часу поруч з оригінальними JSON-файлами. Деталі endpoint, як-от baseUrl, api, ідентифікатори моделей, заголовки й таймаути, мають бути в models.providers.<id> у openclaw.json або models.json, а не в профілях автентифікації.

Зовнішні маршрути автентифікації, як-от Bedrock auth: "aws-sdk", також не є обліковими даними. Якщо вам потрібен іменований маршрут Bedrock, помістіть auth.profiles.<id>.mode: "aws-sdk" у openclaw.json; не записуйте type: "aws-sdk" у сховище профілів автентифікації. openclaw doctor --fix переносить застарілі маркери AWS SDK зі сховища облікових даних у метадані конфігурації.

Посилання на профілі автентифікації також підтримуються для статичних облікових даних:

• Облікові дані api_key можуть використовувати keyRef: { source, provider, id }
• Облікові дані token можуть використовувати tokenRef: { source, provider, id }
• Профілі в режимі OAuth не підтримують облікові дані SecretRef; якщо auth.profiles.<id>.mode задано як "oauth", введення keyRef/tokenRef на основі SecretRef для цього профілю відхиляється.

Перевірка, зручна для автоматизації (вихід 1, коли термін дії минув/відсутній, 2, коли термін дії скоро мине):

openclaw models status --check

Активні перевірки автентифікації:

openclaw models status --probe

Примітки:

• Рядки probe можуть надходити з профілів автентифікації, облікових даних середовища або models.json.
• Якщо явний auth.order.<provider> пропускає збережений профіль, probe повідомляє excluded_by_auth_order для цього профілю замість того, щоб пробувати його.
• Якщо автентифікація існує, але OpenClaw не може визначити придатного для probe кандидата моделі для цього постачальника, probe повідомляє status: no_model.
• Періоди cooldown через rate-limit можуть бути прив’язані до моделі. Профіль, що перебуває в cooldown для однієї моделі, усе ще може бути придатним для спорідненої моделі того самого постачальника.

Необов’язкові операційні скрипти (systemd/Termux) задокументовані тут: Скрипти моніторингу автентифікації

Примітка щодо Anthropic

Бекенд Anthropic claude-cli знову підтримується.

• Співробітники Anthropic повідомили нам, що цей шлях інтеграції OpenClaw знову дозволений.
• Тому OpenClaw вважає повторне використання Claude CLI і використання claude -p санкціонованими для запусків на базі Anthropic, якщо Anthropic не опублікує нову політику.
• API-ключі Anthropic залишаються найпередбачуванішим вибором для довгоживучих хостів Gateway і явного контролю серверного білінгу.

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

openclaw models statusopenclaw doctor

Поведінка ротації API-ключів (Gateway)

Деякі постачальники підтримують повторну спробу запиту з альтернативними ключами, коли API-виклик натрапляє на provider rate limit.

• Порядок пріоритету:
  • OPENCLAW_LIVE_<PROVIDER>_KEY (одиночне перевизначення)
  • <PROVIDER>_API_KEYS
  • <PROVIDER>_API_KEY
  • <PROVIDER>_API_KEY_*
• Постачальники Google також включають GOOGLE_API_KEY як додатковий fallback.
• Той самий список ключів дедуплікується перед використанням.
• OpenClaw повторює спробу з наступним ключем лише для помилок rate-limit (наприклад 429, rate_limit, quota, resource exhausted, Too many concurrent requests, ThrottlingException, concurrency limit reached або workers_ai ... quota limit exceeded).
• Помилки, не пов’язані з rate-limit, не повторюються з альтернативними ключами.
• Якщо всі ключі не спрацьовують, повертається фінальна помилка з останньої спроби.

Видалення автентифікації постачальника під час роботи Gateway

Коли автентифікацію постачальника видаляють через control plane Gateway, OpenClaw видаляє збережені профілі автентифікації для цього постачальника й перериває активні запуски чату або агента, у яких вибраний постачальник моделей відповідає видаленому постачальнику. Перервані запуски випускають звичайні події скасування чату й життєвого циклу з stopReason: "auth-revoked", щоб підключені клієнти могли показати, що запуск було зупинено через видалення облікових даних.

Видалення збереженої автентифікації не відкликає ключі в постачальника. Обертайте або відкликайте ключ у dashboard постачальника, коли потрібна інвалідація на боці постачальника.

Керування тим, які облікові дані використовуються

OpenAI і застарілі ідентифікатори openai-codex

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

Якщо ви бачите openai-codex у старішій конфігурації, ідентифікаторах профілів автентифікації або auth.order.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 <id> --profile-id <profileId> для постачальників, які підтримують іменовані профілі автентифікації під час входу.

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

Це найпростіший спосіб зберігати кілька OAuth-входів для одного постачальника окремо в межах одного агента.

Використовуйте --force, коли збережений профіль постачальника застряг, прострочений або прив’язаний до неправильного облікового запису, а звичайна команда входу продовжує повторно його використовувати. --force видаляє збережені профілі автентифікації для цього постачальника в каталозі вибраного агента, а потім знову запускає той самий потік автентифікації постачальника. Це не відкликає облікові дані в постачальника; обертайте або відкликайте їх у dashboard постачальника, коли потрібна інвалідація на боці постачальника.

openclaw models auth login --provider anthropic --force

Для сесії (команда чату)

Використовуйте /model <alias-or-id>@<profileId>, щоб закріпити конкретні облікові дані постачальника для поточної сесії (приклади ідентифікаторів профілів: anthropic:default, anthropic:work).

Використовуйте /model (або /model list) для компактного вибору; використовуйте /model status для повного перегляду (кандидати + наступний профіль автентифікації, а також деталі endpoint постачальника, якщо налаштовано).

Для агента (перевизначення 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 замість мовчазного пропуску. Коли ви налагоджуєте проблеми cooldown, пам’ятайте, що cooldown через rate-limit може бути прив’язаний до одного ідентифікатора моделі, а не до всього профілю постачальника.

Якщо ви змінюєте порядок автентифікації або закріплення профілю для чату, який уже запущено, надішліть /new або /reset у цьому чаті, щоб почати свіжу сесію. Наявні сесії можуть зберігати свій поточний вибір моделі/профілю до reset.

Усунення несправностей

"Облікові дані не знайдено"

Якщо профіль Anthropic відсутній, налаштуйте API-ключ Anthropic на хості Gateway або налаштуйте шлях Anthropic setup-token, а потім перевірте знову:

openclaw models status

Термін дії токена скоро минає/минув

Запустіть openclaw models status, щоб підтвердити, термін дії якого профілю минає. Якщо профіль токена Anthropic відсутній або прострочений, оновіть це налаштування через setup-token або перейдіть на API-ключ Anthropic.

Пов’язане

• Керування секретами
• Віддалений доступ
• Сховище автентифікації