Ошибка API-ключа OpenClaw: No API Key, 401, 429 и сбои Gateway

При ошибке API-ключа OpenClaw сначала определите, кто отказал: поставщик модели, Gateway, устройство или канал. No API key found for provider означает, что для выбранного подключения не найден подходящий ключ. 401 требует чтения исходного сообщения об авторизации, а 429 — определения источника ограничения и срока ожидания. Новый ключ модели не исправит токен Gateway, ошибку сертификата или переполненный контекст.

Рабочий порядок: найти первую ошибку одного запуска, проверить его агента и фактическую модель, исправить подтверждённую причину, затем получить результат на том же подключении. Если предыдущая попытка могла выполнить внешнее действие, сначала выясните её результат — повтор всего задания способен создать дубликат.

Ниже приведены действия по документации, проверенной 7 октября 2026 года. Реальный отказ ключа и восстановление работающего бота здесь не воспроизводились; программный пример проверяет только решение о повторе на искусственных данных.

Найдите первую ошибку и проблемного агента

Начните на машине, где работает Gateway, с учётом пользователя службы и используемого профиля OpenClaw. <agentId> в примере замените идентификатором агента, у которого возник сбой:

openclaw status
openclaw gateway status
openclaw models status --agent <agentId> --json
openclaw logs --follow

В журнале сопоставьте время запуска, поставщика, модель, профиль авторизации, полный текст первой ошибки и доступный идентификатор запроса. Завершите просмотр сочетанием Ctrl+C. Не передавайте ключи, токены и личную переписку вместе с диагностикой.

В самом проблемном чате отдельно проверьте:

/model status
/status

CLI показывает настроенную модель и резервные варианты агента, но не переопределение модели в конкретном чате. /model status помогает увидеть выбор сессии, а /status — отличить выбранную модель от фактически использованной резервной. Внешняя среда запуска, например ACP, может иметь собственную авторизацию. Как читать состояние моделей.

Таблица направляет проверку, но один код не устанавливает причину. Последнее all in cooldown может подводить итог предыдущим отказам авторизации, лимитам или недоступности среды запуска.

No API key: восстановите нужный источник учётных данных

Если OpenClaw не находит ключ, выясните, откуда проблемный агент должен его получать. В текущей версии общий базовый набор хранится в ~/.openclaw/state/openclaw.sqlite, а локальные записи агента — в ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Агент без локального профиля может читать общий; запись с тем же идентификатором на уровне агента перекрывает общую. Отсутствие ключа у одного агента не означает, что всем нужно скопировать секрет вручную. Хранение авторизации.

Выбирайте исправление по результату проверки:

1. Профиль действительно отсутствует. На нужной машине и для нужного агента добавьте учётные данные через интерактивный помощник. Выберите фактического поставщика и поддерживаемый способ авторизации.
2. Профиль есть, но исключён из выбора. Проверьте локальный порядок авторизации, переопределение профиля и закреплённый выбор сессии. Исправляйте выбор, если он ошибочен, а не добавляйте одинаковый ключ ещё раз.
3. Явный SecretRef не разрешается. Восстановите его источник и предусмотренную загрузку секрета. Ошибка файла, внешнего хранилища или исполняемого помощника не доказывает, что поставщик отклонил ключ. Явно недоступный источник нельзя обходить случайным ключом из окружения.
4. Недоступен внешний способ запуска. Восстановите соответствующий вход или среду запуска на машине Gateway. Найденный API-ключ не восстановит отсутствующий исполняемый файл или авторизацию другого процесса.

Для первого случая используйте поддерживаемый интерактивный помощник. Эти команды — альтернативы: общий выбор способа входа либо ввод API-ключа. Замените оба идентификатора реальными значениями из своей настройки:

openclaw models auth add --agent <agentId>
openclaw models auth paste-api-key --provider <providerId> --agent <agentId>

paste-api-key обновляет настроенный активный профиль или создаёт ручной. Если нужно подготовить отдельный именованный профиль, задайте --profile-id <profileId> и отдельно проверьте его выбор: создание запасной записи ещё не означает смену действующего подключения. Не вставляйте ключ в командную строку вместо интерактивного ввода. paste-token предназначен для поддерживаемого токена, а не для API-ключа. Помощники авторизации.

У OpenAI вход ChatGPT/Codex и API-ключ используют поставщика openai, но это разные способы авторизации; старое имя openai-codex может встречаться при миграции. У Anthropic нативный Claude CLI, управляемый setup-token и API-ключ тоже нельзя подменять друг другом.

После исправления снова посмотрите статус того же агента. Если он сообщает indeterminate, уточните недоступный источник или среду запуска: это не успешная проверка ключа. Старые auth-profiles.json, auth-state.json и auth.json относятся к миграции, а не к текущему хранению секретов. Не редактируйте SQLite вручную и не удаляйте старые файлы «для сброса»: сначала сохраните данные и установите конкретную проблему миграции по диагностике.

401: проверьте поставщика, а не только вид ключа

Если отказ пришёл от API модели, сопоставьте поставщика, адрес API, модель и выбранный профиль. Параметры API, включая baseUrl и идентификаторы моделей, относятся к models.providers.<id> в конфигурации, а не к строке с секретом. Ключ, который принят на одном адресе, не обязательно подходит другому API или промежуточному шлюзу. Префикс sk- тоже не доказывает действительность ключа. Авторизация OpenClaw.

Дальнейшее действие зависит от текста отказа:

• При отсутствующем исходящем заголовке авторизации проверьте доступность источника учётных данных и формирование запроса для фактического API.
• При отклонённом, истёкшем или отозванном ключе обновите именно затронутый профиль через поддерживаемый помощник поставщика.
• При отказе в доступе к модели или ограничении аккаунта проверьте его права и состояние у поставщика. Один 401 или 403 не доказывает, что необходимо пополнить баланс.
• При нативном Claude CLI проверьте пользователя, машину, PATH и CLAUDE_CONFIG_DIR, под которыми он запускается. Наличие входа в вашем терминале не доказывает наличие входа у службы Gateway.

OpenClaw не извлекает и не пересылает нативные токены входа Claude CLI: сам вход и выбор CLI как способа запуска модели — отдельные действия. Название Claude в настройке не доказывает оплату по подписке или доступность конкретного тарифа. Различия способов авторизации.

Для подробной проверки отсутствующего заголовка, локального переопределения профиля и выбранной сессии используйте руководство по OpenClaw 401. Здесь важно сначала отделить этот отказ от сбоя входа в Gateway.

Gateway, устройство и канал: ключ модели здесь не поможет

У клиента Gateway собственная авторизация. В режиме общего токена или пароля HTTP-запрос использует Authorization: Bearer с учётными данными Gateway, а не с ключом Anthropic или OpenAI. Для режима доверенного прокси действуют другие правила определения пользователя. Сервис HTTP Responses по умолчанию отключён: его 404 не является доказательством плохого ключа модели. HTTP API Gateway.

При отказе подключения найдите error.details.code и выбирайте действие по нему:

Общий секрет не заменяет удостоверение устройства панели управления. WebSocket 1008 обозначает нарушение политики; причину уточняет ответ подключения. Не отключайте авторизацию и не расширяйте доступ к порту для устранения ошибки клиента. Коды подключения и действия.

Есть важный случай 429: местный HTTP-вход Gateway ограничивает неудачные попытки авторизации и возвращает Retry-After. Это не лимит токенов модели. Исправьте данные клиента и выдержите паузу; смена API-ключа модели или резервной модели не снимает ограничение. Ошибки HTTP API.

Если клиент подключился, но бот молчит только в одном канале, проверьте разрешения канала, правила допуска сообщений и состояние его плагина. Успешное соединение с Gateway ещё не доказывает право отправить сообщение в канал. Неподходящее правило обработки сообщения может объяснить отсутствие ответа без отказа API модели.

429 и cooldown: дождитесь нужного срока и сохраните работу

Когда 429 пришёл именно от поставщика модели, сначала остановите дополнительные запуски того же задания. Прочитайте тело ответа, доступные заголовки и состояние аккаунта: временный лимит запросов, токенов или расходов требует разных действий. Уменьшение параллелизма помогает при перегрузке частыми запросами; сокращение истории и вывода инструментов — при ограничении токенов. Исчерпанный периодический лимит не восстановится от короткого ожидания.

Retry-After задаёт минимальную паузу в целых секундах либо дату HTTP. Поддерживаемый OpenClaw retry-after-ms задаёт миллисекунды. Более длинный срок поставщика нельзя обрезать до привычных 30 секунд: если он не помещается в срок задачи, отложите работу или используйте допустимый заранее настроенный резерв. Семантика Retry-After, правила повторов OpenClaw.

Текущий механизм OpenClaw допускает до 10 попыток всего при модельном 429; для других временных ошибок действуют отдельные ограничения повторов и 90-секундное окно непрерывной недоступности. Полный ответ модели сбрасывает это окно, частичный ответ или активность инструмента — нет. Не добавляйте вокруг него цикл, который заново запускает весь диалог: так легко умножить попытки и повторить внешние действия. Действующая политика восстановления.

Сохранённый cooldown — отдельное состояние профиля. Его срок не равен универсальному сроку сброса лимита поставщика; недоступность из-за оплаты или постоянного отказа авторизации может затронуть профиль целиком. Перезапуск, пополнение или смена тарифа сами по себе не очищают это состояние. Найдите исходную причину и текущий срок, прежде чем повторять запрос. Переключение профилей и моделей.

Резервная модель пригодна только при действующих учётных данных, разрешённом выборе и поддержке нужных инструментов, вложений, контекста и условий обработки данных. Явно выбранная пользователем модель может быть строгим выбором; наличие другой модели в списке не означает разрешённое переключение. Успешный резерв действует для текущего хода, следующий снова может начинаться с выбранной основной модели. Подробнее — как восстановиться после OpenClaw 429.

Пример решения о повторе без нового вызова API

В рабочем приложении решение должно учитывать не только статус, но и источник ответа, известный результат действия и оставшийся срок. Ниже — самостоятельный офлайн-пример для своей обвязки, а не реализация внутренней политики OpenClaw. Он ничего не отправляет, не спит и не переключает аккаунты; принимает уже разобранный результат и возвращает следующее действие.

Поля issuer, kind, complete и replay_safe заполняет вызывающий код по документированному ответу и состоянию операции. Если причина неизвестна, нельзя просто поставить kind="transient". Без подтверждения безопасности повторной отправки пример останавливает автоматизацию. Число оставшихся попыток и пауза задаются вашим приложением; если повтором уже управляет OpenClaw, этот пример не нужно превращать в дополнительный цикл.

from datetime import datetime, timezone
from email.utils import parsedate_to_datetime


def retry_floor(headers, now):
    headers = {k.lower(): str(v).strip() for k, v in headers.items()}
    floors = [0.0]
    value = headers.get("retry-after")
    if value is not None:
        if value.isascii() and value.isdigit():
            floors.append(float(value))
        else:
            target = parsedate_to_datetime(value)
            if target.tzinfo is None:
                raise ValueError("Retry-After date needs a time zone")
            floors.append(max(0.0, (target - now).total_seconds()))
    value_ms = headers.get("retry-after-ms")
    if value_ms is not None:
        if not (value_ms.isascii() and value_ms.isdigit()):
            raise ValueError("Invalid retry-after-ms")
        floors.append(int(value_ms) / 1000)
    return max(floors)


def next_action(reply, *, now, seconds_left, attempts_left,
                backoff_seconds, replay_safe):
    if reply["kind"] == "success" and reply.get("complete"):
        return ("done", 0)
    if seconds_left <= 0 or attempts_left <= 0:
        return ("stop_budget", 0)
    if reply["issuer"] != "provider":
        return ("inspect_local_or_channel", 0)
    if reply["kind"] in {"auth", "billing", "request", "context", "refusal"}:
        return ("fix_cause", 0)
    if not replay_safe or reply["kind"] == "unknown_outcome":
        return ("reconcile_result", 0)
    if reply["kind"] not in {"rate_limit", "transient"}:
        return ("inspect_response", 0)
    if reply["status"] not in {429, 500, 502, 503, 504, 529}:
        return ("inspect_response", 0)
    try:
        floor = retry_floor(reply.get("headers", {}), now)
    except (TypeError, ValueError, OverflowError):
        return ("inspect_retry_header", 0)
    wait = max(0.0, backoff_seconds, floor)
    if wait >= seconds_left:
        return ("defer", wait)
    return ("retry_after", wait)


now = datetime(2026, 10, 7, 0, 0, tzinfo=timezone.utc)
reply = {
    "issuer": "provider", "status": 429, "kind": "rate_limit",
    "headers": {"Retry-After": "120"},
}
print(next_action(
    reply, now=now, seconds_left=45, attempts_left=2,
    backoff_seconds=2, replay_safe=True,
))

Ожидаемый вывод: ('defer', 120.0). У приложения осталось 45 секунд, а минимальная пауза — 120. Решение сохраняет полный срок, а не отправляет запрос через 45 секунд. При attempts_left=0 функция сразу возвращает stop_budget, без бессмысленного ожидания после последней попытки. При тайм-ауте с неизвестным результатом верните kind="unknown_outcome" и сначала сверяйте результат операции.

Управляющий код должен уменьшать бюджет после каждой попытки, учитывать время самого запроса, отмену и завершённые действия. Повтор POST не становится безопасным от того, что вы повторили текст задания или придумали одинаковый job ID: нужна документированная идемпотентность либо подтверждённая возможность повтора конкретной операции. Правила повторной отправки HTTP.

400 и context_length_exceeded: исправьте запрос

Invalid beta flag указывает на неподдерживаемый параметр фактического API. Проверьте настройки поставщика и уберите несовместимый флаг либо выберите разрешённое подключение, которое его поддерживает. Возможности прямого API нельзя автоматически переносить на Bedrock, Vertex или совместимый шлюз.

При context_length_exceeded сохраните выполненную работу и незавершённый запрос. Сопоставьте размер истории, инструкций, схем инструментов и новых вложений с контекстом фактически использованной модели. Если отказ появился после переключения, резервная модель могла иметь другое ограничение; сначала восстановите последовательность попыток.

Сжатие истории помогает, когда переполнение вызывает история, но не исправляет слишком большой новый ввод или неподдерживаемые параметры. Дальнейшие действия описаны в руководстве по context_length_exceeded. Не очищайте всю сессию до сохранения результата и сведений о выполненных действиях.

Docker и конфигурация: проверьте действующий процесс

Если в терминале всё работает, а у службы — нет, сравните машину, пользователя, корень состояния, активный файл конфигурации и источники нужных переменных. Проверяйте наличие и происхождение значения без печати самого секрета. Полный вывод env или конфигурации не нужен для публичного отчёта.

Для обычной загрузки OpenClaw уже существующие переменные процесса не перезаписываются. Файл .env рабочего каталога не служит произвольным источником ключей поставщиков; глобальный файл .env корня состояния имеет другую роль. Есть также специальные правила обновления переменных службы, управляемой OpenClaw. Утверждение «окружение всегда перекрывает всю конфигурацию» слишком широкое. Приоритеты окружения.

В Docker важны значения запущенного контейнера, а не только терминала хоста. Если причина найдена в изменённых переменных Compose, обычный restart не применяет новое окружение: требуется предусмотренное пересоздание службы через up -d, в согласованное окно и с сохранением постоянных данных. Не удаляйте тома для исправления ключа. Переменные Docker.

Для структурной ошибки используйте openclaw config file, чтобы найти активный файл, и openclaw config validate, чтобы проверить его. Успешный разбор JSON не проверяет всю действующую схему OpenClaw; config validate тоже не доказывает, что поставщик примет секрет или каждый параметр своего API. openclaw doctor полезен для конкретной найденной проблемы установки или миграции, а исправляющий режим требует сохранения данных и понимания изменения. Он не создаёт недостающий ключ и не повышает лимит. Диагностика конфигурации.

Если ошибка относится к загрузке плагина, навыку или локальной базе только для чтения, исправляйте этот компонент по его сообщению. Замена ключа модели не восстановит разрешение на запись или отсутствующую зависимость; массовый chmod и принудительная переустановка здесь не являются универсальным первым шагом.

502, тайм-аут и TLS: выясните участок и результат сбоя

502 может прийти от промежуточного сервиса или от самого Gateway. Например, локальный HTTP API способен завершить запрос ошибкой, если клиент не вернул требуемый результат инструмента. Сначала установите источник ответа и наличие завершённых действий, затем проверяйте адрес API, состояние поставщика и сообщение транспорта. Отсутствие ответа при тайм-ауте не доказывает отсутствие обработки или списания. Поведение HTTP API Gateway.

При ошибке сертификата проверьте имя узла, срок действия, цепочку и легитимный корпоративный центр сертификации. Сохраняйте проверку TLS. Если администратор установил доверенный дополнительный сертификат, Node может использовать NODE_EXTRA_CA_CERTS с PEM-файлом при запуске процесса; изменение переменной после запуска не подгрузит сертификат. Явная настройка ca у клиента меняет использование стандартных и дополнительных корней. Документация Node.

NODE_TLS_REJECT_UNAUTHORIZED=0 отключает проверку и не восстанавливает API-ключ. Не используйте его для сокрытия ошибки сертификата.

Чем подтвердить восстановление

Проверяйте результат по той же цепочке, где произошёл сбой: тот же Gateway, агент, сессия, поставщик и модель. Различайте три уровня:

1. Настройки читаются. config validate не показывает соответствующую структурную ошибку.
2. Подключение и авторизация готовы по диагностике. models status показывает нужный профиль, а клиент проходит требуемую авторизацию Gateway. Код 0 у models status --check означает отсутствие распознанной проблемы состояния, а не успешную генерацию.
3. Запрос реально принят. Один согласованный короткий запрос по проблемному подключению завершился ответом, и нет прежнего отказа. Проверка списка моделей или /healthz этого не доказывает.

models status --probe делает реальные запросы, может тратить токены и попадать под ограничения. Используйте его только с разрешённым доступом, ограниченным охватом и исключительным владением состоянием: документация требует остановить работающий Gateway в подходящее окно обслуживания и дождаться завершения работы и очистки перед возобновлением службы. Это отдельная проверка, а не обязательный безвредный шаг первой диагностики. Ограничения проверки моделей.

Если короткий запрос прошёл через резерв, зафиксируйте фактическую модель. Это подтверждает работоспособность резерва в проверенном случае, но ещё не исправление основного подключения.

Частые вопросы

Почему ключ есть, но OpenClaw пишет No API key?

Проблемный агент может использовать другое локальное переопределение, порядок профилей, корень состояния или внешний способ запуска. Начните с models status --agent <agentId> и выбора модели в самой сессии. Найденный, но недоступный SecretRef также отличается от отсутствующего ключа. Профили и состояние моделей.

Нужно ли менять токен Gateway при 401?

Только если отказ действительно относится к авторизации клиента Gateway. Если API модели отклонил исходящий запрос, проверяйте его учётные данные. При ошибке устройства или области разрешений действительный общий токен может быть недостаточен. Коды отказа подключения.

Поможет ли перезапуск при all in cooldown?

Перезапуск не устраняет первоначальный отказ и не гарантирует очистку сохранённого состояния. Найдите причину недоступности профиля и текущий срок восстановления; ограничения модели, оплаты и авторизации обрабатываются по-разному. Сохранённое состояние отказов.

Если models status успешен, ключ точно работает?

Нет. Статус и список моделей не равны успешному запросу генерации. Для подтверждения нужна разрешённая проверка того же агента, модели, профиля и подключения, где возникла ошибка. Что проверяет CLI моделей.