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

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:

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

Процес складається з двох кроків: увійдіть у Anthropic через Claude Code на хості, а потім укажіть 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.

Пов’язані матеріали

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