Ошибка OpenClaw 401 обычно означает не один «плохой токен», а одну из трех разных веток: invalid bearer token, missing authentication header или отсутствие учетных данных у конкретного агента. Пока вы не сопоставили точный текст ошибки с правильной веткой, любое вращение ключей, токенов и переменных окружения остается почти случайным действием.
Эта развилка полезна не только для текущего ремонта. Она сразу подсказывает, стоит ли после восстановления оставлять на этом хосте тот же способ аутентификации. Для long-lived gateway host стандартом по умолчанию обычно становится не самый удобный, а самый предсказуемый способ.
Маршрут за 30 секунд
Сначала разнесите 401 по правильной ветке, и только потом трогайте учетные данные:
| Если в логе написано | Что, скорее всего, сломалось | Самый безопасный первый шаг | Что нужно проверить на том же пути | Когда пора расширять расследование |
|---|---|---|---|---|
invalid bearer token | Токен-зависимый способ аутентификации устарел, отозван, перекрыт другой настройкой или плохо держится на текущем билде | Переаутентифицировать именно этот путь | Повторно запустить тот же агент на том же хосте и убедиться, что эта ветка больше не падает | После чистой re-auth ошибка остается той же |
missing authentication header | Request routing, provider config или слой, который вообще не отправляет usable auth | Сначала выяснить, какой слой собирает исходящий запрос | Проверить, что повторный запрос теперь действительно несет auth | Даже с заведомо рабочими credentials ошибка остается missing-header |
Один агент работает, а другой отдает 401 или no credentials | Сам падающий агент | Добавить или обновить credentials именно у него | Перепроверить только этот агент, а не тот, что уже работал | У агента по-прежнему пустой или непригодный auth profile |
Эта схема нужна не для красоты. Текущая документация OpenClaw по-прежнему описывает несколько способов аутентификации Anthropic, включая API key, Claude CLI reuse и setup-token reuse. Одновременно текущие provider docs и CLI-структура показывают, что auth state привязан к агенту. Публичные runtime-свидетельства тоже расходятся по разным веткам: issue #23538 фиксирует invalid bearer token на OpenClaw 2026.2.21-2, а issue #34830 документирует отдельную регрессию с 401 missing authentication header на более позднем билде.
Поэтому первый вопрос должен звучать не «какой key мне заменить?», а «в какой ветке я сейчас нахожусь?». Если пропустить этот шаг, проще всего испортить рабочий способ входа, пытаясь чинить совсем другую проблему.
Если ошибка содержит invalid bearer token
Эта ветка обычно означает, что credential действительно ушел в запросе, но upstream не смог его принять. Для текущих маршрутов OpenClaw это чаще связано не с прямым Anthropic API key, а с теми вариантами, где участвуют Claude login reuse, Claude CLI reuse или setup-token reuse.
Поэтому здесь первым действием должна быть re-authentication, а не большая переделка конфигурации. Текущие Anthropic provider docs OpenClaw все еще рассматривают 401 errors / token suddenly invalid как реальную отдельную ветку. Claude Help добавляет важную деталь: ANTHROPIC_API_KEY в Claude Code может перекрыть подписочную auth-схему. На практике это означает неприятную вещь: машина выглядит так, будто уже «залогинена», но реальные запросы идут по другой auth-линии, чем вы думаете.
Сохраненный token не является доказательством здоровой runtime-auth. Именно это показывает issue #23538: setup-token был принят и записан, но Anthropic-запросы все равно падали с HTTP 401 authentication_error: Invalid bearer token. Это не доказывает, что setup-token сломан всегда. Это доказывает, что успешный onboarding сам по себе еще не делает такой маршрут надежным на долгоживущем хосте.
Безопасный порядок действий здесь такой:
- Повторно пройти тот же token/setup-token flow, который этот хост должен использовать сейчас.
- Удалить stale Claude sessions или revoked tokens, если они все еще могут оказываться выше по приоритету. Claude объясняет, где отзываются активные сессии.
- Проверить, не перекрывает ли
ANTHROPIC_API_KEYту route, которую вы считали активной. - После re-auth перепроверить тот же агент и тот же host path, а не другую машину, где все случайно работает.
Если та же ветка продолжает падать после чистой re-auth, перестаньте трактовать это как обычную ротацию credentials. На этом этапе вопрос уже звучит иначе: подходит ли этой среде такой способ аутентификации вообще. Для long-lived gateway host практичнее смотреть в сторону самого предсказуемого маршрута. В реальной эксплуатации это часто означает переход к прямому API key. Если видно, что проблема действительно сидит в Anthropic token route, пригодится отдельный материал по ошибкам Anthropic API key в OpenClaw.
Если ошибка содержит missing authentication header
Missing authentication header выглядит как та же 401, но смысл у нее другой. Здесь речь чаще о том, что запрос вообще не донес usable auth до нужной точки. Это уже не история про «токен был отправлен и отклонен», а история про «нужный auth header не появился в запросе».
Здесь особенно важен issue #34830. Он показывает, что 401 missing authentication header может появляться как отдельная регрессионная ветка, даже когда пользователь уверен, что сам key корректен. Если текст ошибки уже говорит про отсутствующий header, первым действием должно стать выяснение того, какой слой собирает исходящий запрос и должен ли он вообще был иметь credentials для отправки.
Минимально безопасная последовательность короткая:
- Выяснить, какой provider path или какой агент породил конкретный failing request.
- Проверить активный config, env и auth profile именно для этого пути.
- Повторить запрос с заведомо рабочими credentials и посмотреть, появился ли auth header.
Если даже с рабочим key запрос продолжает уходить без auth header, не относитесь к этому как к обычному «дрейфу секретов». Дальше вы уже на территории request routing, config wiring или build-specific behavior. Продолжать крутить secrets в таком состоянии почти бесполезно.
Если основной агент работает, а другой не имеет credentials
Это третья ветка, и она тоже независима от двух предыдущих. Текущие OpenClaw docs и CLI-пути хранят auth profiles на уровне агента, в структурах вроде ~/.openclaw/agents/<agentId>/agent/auth-profiles.json. В переводе на обычный язык: каждому агенту нужны свои credentials. Здоровый основной агент не доказывает, что новый агент автоматически унаследовал что-то полезное.
Поэтому правильный ремонт здесь делается на падающем агенте, а не на всем хосте. Сравните auth state упавшего агента с рабочим, добавьте или обновите credentials именно там и затем перепроверьте только его. Когда вместо этого запускают повторный onboarding всего окружения, они часто меняют как раз ту часть, которая не была сломана.
Эта ветка еще и хорошо показывает цену избыточно сложной схемы. Смешение локального sign-in reuse, per-agent profiles и environment overrides может работать, но разбирать такие сбои заметно сложнее. Если gateway должен жить долго и предсказуемо, более простая auth-маршрутизация почти всегда выигрывает.
Какой способ аутентификации оставить на этом хосте
После того как сервис снова поднялся, полезный вопрос уже не «какой способ только что сработал один раз?», а «какой способ с меньшей вероятностью снова упадет на этом хосте?».
Текущая guidance OpenClaw здесь довольно ясна. Gateway authentication docs тяготеют к API key как к самому предсказуемому варианту для always-on gateway host. Anthropic provider docs по-прежнему сохраняют Claude CLI reuse и setup-token reuse, но FAQ OpenClaw точнее очерчивает границы среды: локальный Claude login reuse поддерживается, однако не рекомендуется как production default. Там же зафиксировано уведомление Anthropic от 4 апреля 2026 года: путь с Claude login в OpenClaw требует отдельного Extra Usage billing, а не просто обычной подписки.
Практическое правило выглядит так:
| Среда | Что разумнее оставить как default | Почему |
|---|---|---|
| Always-on server или shared gateway host | Прямой API key | Меньше скрытого состояния, меньше зависимости от локальных сессий и проще долгосрочная отладка |
| Личная машина под вашим прямым контролем | Claude CLI или auth, связанная с подпиской, могут быть приемлемы | Удобство здесь может перевесить, потому что и машина, и user session локальны |
| Setup-token reuse | Поддерживается, но остается version-sensitive | Документация его сохраняет, но публичная issue-история не позволяет подавать его как самый безопасный универсальный default |
Смысл не в том, чтобы навсегда объявить победителем один auth-способ. Смысл в том, чтобы выбрать маршрут под реальную среду. Если хост должен переживать перезапуски и обслуживать стабильный gateway-путь, предсказуемость важнее удобства. Если это личная локальная машина, удобная локальная auth-схема тоже может быть нормальной.
Короткая проверка после фикса
Большая часть повторных 401 появляется не потому, что первая диагностика была совсем неправильной, а потому что после ремонта никто не проверил тот же путь еще раз. Короткая post-fix routine обычно снимает эту проблему:
- Перепроверьте именно того агента, который падал. Другой рабочий profile не является доказательством успеха.
- Убедитесь, что активен именно тот auth route, который вы хотели оставить.
- Уберите stale token paths и старые сессии, которые больше не должны получать приоритет.
- Если вы сменили auth method, зафиксируйте новый default для этого host, чтобы старая схема тихо не вернулась позже.
Здесь важно не путать cooldown branch с реальной credential failure. Текущие Anthropic provider docs отдельно говорят, что No available auth profile (all in cooldown/unavailable) нужно смотреть через openclaw models status --json. Это не то же самое, что invalid bearer token, и не то же самое, что missing authentication header. Если смешать эти три случая, вы будете чинить secrets там, где на самом деле нужно смотреть доступность профиля.
Порог эскалации можно держать очень простым:
- Если
invalid bearer tokenуходит после re-auth, закройте именно эту ветку и отдельно решите, стоит ли оставлять тот же маршрут на хосте. - Если
missing authentication headerостается даже с рабочими credentials, продолжайте расследовать routing и config, а не ротацию токенов. - Если один агент работает, а другой падает, сначала восстановите именно падающий агент.
- Если проблема уже шире, чем эта узкая 401-развилка, переходите к более общему гайду по ошибкам OpenClaw или к руководству по установке и развертыванию.
FAQ
Значит ли любой OpenClaw 401, что у меня неверный API key?
Нет. Текущие публичные данные позволяют уверенно различать как минимум три класса: invalid bearer token, missing authentication header и отсутствие usable credentials у одного агента.
Setup-token по-прежнему поддерживается?
Да. Текущие документы OpenClaw продолжают описывать setup-token как поддерживаемый путь для Anthropic. Но по состоянию на 7 апреля 2026 года issue #23538 все еще показывает version-specific runtime-регрессию с invalid bearer token на OpenClaw 2026.2.21-2, поэтому точнее называть этот путь поддерживаемым, но чувствительным к версии.
Почему основной агент работает, а новый агент нет?
Потому что текущие provider docs делают хранение auth state агент-специфичным. Рабочий основной агент не означает автоматического наследования тех же credentials другим агентом.
Что безопаснее для сервера в долгую?
Для long-lived gateway host текущая guidance OpenClaw направляет к самому предсказуемому маршруту. На практике это чаще всего означает прямой API key, если для вас важнее стабильность, чем локальное удобство.
Рабочее правило
Исправлять OpenClaw 401 проще, когда вы перестаете спрашивать «какую credential мне заменить?» и начинаете спрашивать «какая именно ветка сломалась?». Сначала сопоставьте точный текст ошибки с правильной веткой, примените минимальное исправление только к ней, перепроверьте тот же путь и лишь потом решайте, какой способ аутентификации должен остаться на этом хосте.