OpenClaw の 401 は、たいてい一つの bad token 問題ではなく、invalid bearer token、missing authentication header、または特定の agent に認証情報が無いという三つの別々の枝のどれかです。最初にやるべきことは、正確なエラー文字列を正しい枝へ戻すことです。
この切り分けができると、いま壊れている枝だけを最小修正できます。さらに復旧後に、この host にどの認証方式を残すべきかも判断しやすくなります。長時間動かす gateway host では、一度通った経路より、後から説明しやすい予測可能な経路のほうが安全です。
30 秒の切り分けボード
設定を触る前に、まずエラーを正しい枝へ分けてください。
| ログに出ている文言 | まず疑うべき箇所 | 最初に取る安全な一手 | 同じ経路で何を確認するか | どこで拡張調査に切り替えるか |
|---|---|---|---|---|
invalid bearer token | token ベースの認証経路が失効、上書き、または現在の build と相性が悪い | その経路を再認証する | 同じ agent・同じ host で同じ枝が消えたかを見る | clean な再認証後も同じ枝が続く |
missing authentication header | request routing、provider config、または auth が送られていない送信経路 | どの層が outbound request を作っているか確認する | リトライ時に auth header が実際に載っているかを見る | 正常な credential でも missing-header のまま |
一つの agent は動くのに別の agent が 401 や no credentials になる | 失敗しているその agent 自身 | 失敗した agent に credential を追加または更新する | その agent だけを再テストする | その agent に usable profile が残らない |
この分岐は理屈の話ではありません。現在の OpenClaw 文書は Anthropic に対して API key、Claude CLI reuse、setup-token reuse など複数の認証経路を案内しています。同時に現在の provider docs は auth state が agent ごとに管理されると示しています。公開 issue でも 401 が別々の枝に分かれていることが見えます。issue #23538 は OpenClaw 2026.2.21-2 での invalid bearer token を記録し、issue #34830 は別の 401 missing authentication header 回帰を示しています。
だから最初の問いは「どの key を入れ替えるか」ではなく「どの枝が壊れたか」です。ここを飛ばすと、元々動いていた認証経路まで一緒に壊しやすくなります。
invalid bearer token が出るとき
invalid bearer token は、request に credential 自体は載っていたが、upstream がそれを使えなかったと判断したときに出やすい枝です。現在の OpenClaw の公開ガイダンスでは、これは direct な Anthropic API key より、Claude login reuse、Claude CLI reuse、setup-token reuse のような token 駆動の経路で起きやすいと考えたほうが自然です。
この枝で最初にやることは、大きな設定変更ではなく再認証です。現在の OpenClaw Anthropic provider docs は 401 errors / token suddenly invalid を独立した運用上の枝として扱っています。さらに Claude Help は、ANTHROPIC_API_KEY が Claude Code の subscription-style auth を上書きし得ると説明しています。つまり見た目には「ログイン済み」でも、実際の request は別の認証経路で送られていることがあります。
保存済み token の存在は、runtime auth が健康だという証明にはなりません。issue #23538 では setup-token が受理され保存されたのに、Anthropic request は HTTP 401 authentication_error: Invalid bearer token で失敗しました。ここから読み取るべきなのは、setup-token が常に壊れているという話ではなく、「保存成功」だけでは長期運用の証拠にならないということです。
安全な復旧順序は次のとおりです。
- いま使う想定の token/setup-token flow を current docs に沿ってやり直す。
- 優先され続ける stale session や revoked token を整理する。Claude の session revoke 説明 が使えます。
ANTHROPIC_API_KEYが想定外の経路を有効化していないか確認する。- 再認証後は同じ agent、同じ host で再テストする。
それでも同じ枝が残るなら、これは単なる token の入れ直しではなく、その host に残す認証方式の選び直しです。長時間動かす host では、fragile な token reuse より direct API key のほうが扱いやすいことが多くなります。もし Anthropic token 側の深掘りが必要なら、関連する英語ガイドの OpenClaw Anthropic API key errors も参照できます。
missing authentication header が出るとき
missing authentication header は、見た目は同じ 401 でも意味が違います。こちらは request が usable auth を載せずに出ている可能性が高く、invalid bearer token のように「送った credential が拒否された」枝とは修理順序が変わります。
Issue #34830 が重要なのは、この枝を独立した回帰として見せてくれるからです。ログに header 欠落と出ているなら、最初の仕事はどの層が request を組み立てているか、その層が本当に auth を持っているかを確認することです。
最低限の順序は短くて十分です。
- どの provider path、またはどの agent が failing request を出したか確認する。
- その経路に対応する active config、env、profile を見る。
- known-good credential でリトライし、本当に auth header が付いたか確認する。
それでも missing-header のままなら、ここから先は token rotation より routing や build behavior の問題です。秘密情報を入れ替え続けても、この枝では解決しないことが多いです。
main agent は動くのに別の agent が落ちるとき
この枝も別物です。現在の OpenClaw docs と CLI では、auth profiles は ~/.openclaw/agents/<agentId>/agent/auth-profiles.json のような agent 単位の場所に置かれます。つまり、各 agent は自分の credential を必要とします。main agent が正常でも、新しい agent に同じ状態が自動で移るわけではありません。
だからここで修理すべき相手は host 全体ではなく、失敗した agent です。失敗した agent の auth state を正常な agent と比べ、必要な credential をその agent だけに追加または更新し、その agent を再テストしてください。host 全体の onboarding をやり直すと、壊れていない経路まで巻き込むことがあります。
この枝は、複雑な auth 構成が調査コストを増やすことも教えてくれます。local sign-in reuse、per-agent profiles、environment overrides を全部混ぜると動くことはありますが、どの枝が壊れたかを見抜きにくくなります。長く動かす gateway なら、単純な経路のほうが強いです。
この host に残す認証経路を選ぶ
復旧後に本当に決めるべきことは、「いま一度通った route は何か」ではなく、「この host でいちばん再発しにくい認証経路は何か」です。
現在の OpenClaw guidance はこの点でかなり明確です。Gateway authentication docs は always-on gateway host に API key を勧める方向です。Anthropic provider docs は Claude CLI reuse や setup-token reuse を残していますが、OpenClaw FAQ はローカル Claude login reuse を production default としては勧めていません。さらに FAQ には 2026 年 4 月 4 日付の Anthropic 通知が記録されており、OpenClaw の Claude login path では subscription とは別に Extra Usage billing が必要だとされています。
実務上の整理は次の表で十分です。
| 環境 | 残しやすい default | 理由 |
|---|---|---|
| 長時間動かす server / shared gateway host | direct API key | 隠れた状態が少なく、再起動後も説明しやすい |
| 自分で管理する個人マシン | Claude CLI や subscription-linked auth も許容できる | 利便性の価値が高く、machine と session がどちらもローカル |
| setup-token reuse | 公式にはサポートされるが version-sensitive | docs は残しているが、公開 issue は universal default としては強く推せないことを示す |
大事なのは host に合わせて選ぶことです。長時間動かす host なら predictability が優先で、ローカルの個人環境なら convenience が勝つ場合もあります。
修正後の短い確認
同じ 401 を繰り返さないためには、復旧後の短い確認が効きます。
- 実際に落ちた同じ agentを再テストする。
- 残したつもりの認証経路が本当に active か確認する。
- stale token paths や古い session を整理する。
- 認証方式を変えたなら、この host の default を記録する。
ここでは cooldown state と credential failure を混ぜないことも大切です。現在の Anthropic provider docs は No available auth profile (all in cooldown/unavailable) を openclaw models status --json で確認するよう案内しています。cooldown は invalid bearer token でも missing authentication header でもありません。
判断の線引きはこうです。
invalid bearer tokenが re-auth で消えるなら、その枝の修理は閉じて、同じ経路を残すかを別で決める。missing authentication headerが残るなら、routing と build behavior を追い続ける。- 一つの agent だけ失敗するなら、その agent を先に直す。
- 問題が 401 の範囲を超えて広がるなら、より広い OpenClaw troubleshooting guide や installation and deployment guide に移る。
FAQ
OpenClaw の 401 は全部 API key の間違いですか
いいえ。現在の公開情報だけでも、invalid bearer token、missing authentication header、agent ごとの credential gap という少なくとも三つの枝を分ける必要があります。
setup-token はまだサポートされていますか
はい。現在の OpenClaw docs は setup-token を引き続きサポート対象として扱っています。ただし 2026 年 4 月 7 日時点でも issue #23538 は OpenClaw 2026.2.21-2 上の invalid bearer token を示しているため、「サポートされるが version-sensitive」と表現するのが正確です。
なぜ main agent は動くのに新しい agent は失敗するのですか
現在の docs が auth state を agent ごとに分けているからです。main agent が健康でも、新しい agent が同じ credential を自動継承した証拠にはなりません。
長時間動かす server では何がいちばん安全ですか
long-lived host では current guidance がもっとも予測しやすい経路を勧めています。実務では direct API key が選ばれやすいです。
最後の運用ルール
OpenClaw 401 を早く直すコツは、「どの credential を変えるか」より「どの枝が壊れたか」を先に問うことです。正確なエラー文字列で枝を分け、その枝だけを最小修正し、同じ経路で確認し、最後にこの host に残す認証方式を決めてください。