Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

サーバーがトークン有効期限切れを報告したが、ローカルの有効期限チェックと不一致の場合にOAuthトークンリフレッシュがトリガーされない問題を修正しました

原文（英語） ​

Fixed OAuth token refresh not triggering when server reports token expired but local expiration check disagrees

概要 ​

Claude Code v2.1.0で修正された、OAuth認証の重大なバグです。以前のバージョンでは、Claude APIサーバーがトークンの有効期限切れを報告した際、ローカル側のトークン有効期限チェック（クライアント時刻ベース）が「まだ有効」と判断すると、トークンリフレッシュが実行されずに認証エラーが発生していました。この修正により、サーバーの判断が優先され、時刻のずれによる認証失敗が解消されます。

修正前の問題 ​

症状 ​

bash
claude

> ファイルを読んで

# エラー: 401 Unauthorized
# Error: Token expired

# 再試行しても同じエラー
> もう一度試して

# エラー: 401 Unauthorized
# Claude Codeを再起動するまで使用不可

根本原因 ​

ローカル時刻: 2026-01-31 10:00:00
トークン有効期限: 2026-01-31 11:00:00

サーバー時刻: 2026-01-31 10:05:00（5分進んでいる）
サーバー判断: "トークンは9:05に期限切れ" → 401エラー

ローカル判断: "まだ11:00まで有効" → リフレッシュ不要

結果: トークンリフレッシュが実行されず、認証エラーが続く

修正後の動作 ​

自動リフレッシュ ​

bash
claude

> ファイルを読んで

# サーバーが 401 Unauthorized を返す
# ローカルチェック: "有効期限まで1時間ある"
# サーバー応答: "Token expired"

# 修正後: サーバーの判断を優先
# → 自動的にトークンリフレッシュを実行
# → 新しいトークンで再試行
# → 成功

# ユーザーには透過的に処理される

実践例 ​

長時間セッションでの自動回復 ​

時刻のずれがあっても、セッションが継続します。

bash
# 朝から Claude Code を使用
claude

# 数時間後（トークン有効期限切れ）
> このファイルを編集して

# 修正前: 401エラーで停止
# 修正後: 自動リフレッシュで継続
# ✓ 編集が正常に実行される

クラウド環境での安定動作 ​

時刻同期が不完全なクラウド環境でも安定します。

bash
# EC2インスタンス（時刻が数分ずれている）
ssh ec2-instance
claude

> コードレビューを実施

# サーバー時刻とローカル時刻にずれがあっても
# サーバーの判断に従ってリフレッシュ
# ✓ 正常に動作

タイムゾーンをまたぐ作業 ​

異なるタイムゾーンでも問題なく動作します。

bash
# 日本時間で作業開始
claude
> ファイルを作成

# 数時間後、米国サーバーにデプロイ
# サーバー時刻（PST）とローカル時刻（JST）が異なる

# 修正前: 時差による認証エラー
# 修正後: 自動リフレッシュで正常動作

注意点 ​

  • この修正は Claude Code v2.1.0（2026年1月7日リリース）で実装されました
  • 影響を受けるシナリオ:
    • ローカルマシンの時刻がサーバーとずれている場合
    • タイムゾーンが異なる環境での使用
    • NTPサーバーと同期していない仮想マシン
    • クラウド環境（時刻同期が不完全な場合）
  • 修正の詳細:
    • サーバーが 401 Unauthorized と Token expired を返した場合、常にトークンリフレッシュを試行
    • ローカルの有効期限チェックはヒントとして使用（決定要因ではない）
    • リフレッシュ成功後、元のリクエストを自動的に再試行
  • トークンリフレッシュの動作:
    • リフレッシュトークンを使用して新しいアクセストークンを取得
    • ユーザーには透過的（再ログイン不要）
    • リフレッシュに失敗した場合のみ、再ログインを要求
  • 時刻同期の推奨:
    • この修正により時刻ずれの影響は軽減されるが、正確な時刻同期を推奨
    • NTPサーバーとの同期を有効化:
      bash
      # macOS
sudo sntp -sS time.apple.com

# Linux
sudo ntpdate pool.ntp.org
  • デバッグ:
    • --debug フラグでトークンリフレッシュのログを確認
    • リフレッシュ失敗時のエラーメッセージに詳細が表示される
  • リフレッシュトークンの有効期限:
    • リフレッシュトークン自体も有効期限がある（通常30日）
    • リフレッシュトークンが期限切れの場合、再ログインが必要:
      bash
      claude auth --login
  • エラー処理:
    • 修正前: 401エラーでセッションが停止
    • 修正後: 自動リフレッシュ → 再試行 → 成功（透過的）
    • リフレッシュ失敗時のみユーザーに通知

関連情報 ​