Claude Code 2.1.310：ゲートウェイエラーとWindowsフックの修正
実際に起動するClaude Codeを更新し、effort betaと会話途中のsystemメッセージが拒否されるケースを切り分けます。Windowsではフックのインタープリターが起動できないときにツール呼び出しが止まることを確認します。極端に大きいcleanupPeriodDaysを目的に合った保持期間へ変更し、残っている添付画像の退避、再試行の限界、削除済みファイルの復元条件まで説明します。
目次
Claude Codeをゲートウェイ経由で使い、effort-2025-11-24に言及するUnexpected value(s)や、Unexpected role "system"で失敗する場合は、2.1.310以降へ更新し、問題が起きた会話で再試行してください。Windowsを使うチームは、フックのインタープリターが起動に失敗したとき、ツール呼び出しが実際に止まるかも確認する必要があります。極端に大きいcleanupPeriodDaysを設定していて貼り付け画像が見つからない場合は、保持期間を変更する前に、残っているデータを退避してください。
2026-10-25時点の2.1.310公式リリースノートでは、これらのゲートウェイ、Windowsフック、クリーンアップの問題に対する修正が確認できます。以下では、症状ごとに確認する対象と対処手順を分けて説明します。
起動している実行ファイルが2.1.310以降か確認する
まずターミナルが実際に起動する実行ファイルを確認し、現在のインストール方法に合った手順で更新します。Bashで次を実行してください。Windows PowerShellでも同じコマンドを使えます。
claude --version
claude doctorclaude doctorは、インストール状態と設定を変更せずに診断する読み取り専用のコマンドです。更新後に比較できるよう、表示されたバージョンを控えておきます。
Anthropicのインストールと更新の手順から、現在のインストール方法に対応するコマンドを選んでください。
| 現在のインストール方法 | シェル | 更新コマンド |
|---|---|---|
| ネイティブインストーラー | BashまたはPowerShell | claude update |
| Homebrewのstable cask | Bash | brew upgrade claude-code |
| Homebrewのlatest cask | Bash | brew upgrade claude-code@latest |
| WinGet | PowerShell | winget upgrade Anthropic.ClaudeCode |
| npm | BashまたはPowerShell | npm install -g @anthropic-ai/claude-code@latest |
ネイティブ版の更新は、設定済みのリリースチャネルに従います。Homebrewのclaude-code caskはstable、claude-code@latestはlatestを追うため、更新コマンドが成功しても、必要なバージョンに達していない場合があります。
既存のネイティブ版では、claude install 2.1.310で特定のバージョンをインストールすることもできます。パッケージ管理下の環境では、その環境で定められた通常の手順に従い、必要なバージョンを提供するパッケージまたはチャネルを選んでください。
更新後にclaude --versionをもう一度実行し、Claude Codeの新しいセッションを開始します。古いバージョンのままなら、Bashではwhich -a claude、PowerShellではwhere.exe claudeを使い、複数のインストールが競合していないか確認してください。エディター内のターミナルを使っている場合、変更したPATHを反映するためにエディター自体の再起動が必要になることもあります。
ゲートウェイのエラーから対応する再試行を見分ける
返されたエラー本文を見て対処を選びます。単に400と表示されただけでは、ゲートウェイがどの機能を拒否したのかは特定できません。
Anthropicのゲートウェイ互換性ガイドでは、次のフォールバック、つまり互換性を保つためにリクエストを変更して再試行する動作が説明されています。
| 応答の特徴 | 自動フォールバック | 確認すること |
|---|---|---|
Unexpected value(s)で始まり、anthropic-betaについてeffort-2025-11-24に言及する400 | Claude Codeを終了するまで、そのモデルに対するeffortフィールドとbetaを省きます。 | この値をANTHROPIC_BETASへ手動で追加していた場合は削除します。 |
output_config.effortについてExtra inputs are not permittedと示す、またはeffortが未対応だと示す400 | effortを省くフォールバックを使います。 | 拒否されたフィールドがeffortであることを確認します。 |
Unexpected role "system"などの400 | 会話途中のsystemテキストをuserメッセージへ移します。/clearまたはコンテキストの圧縮まで、その形式を維持します。 | 問題が起きた会話で再試行します。 |
フォールバックでは、送信するリクエスト自体が変わります。effortパラメーターはモデルのトークンの使い方を制御するため、省略後の再試行が成功しても、指定したeffort設定が適用された証拠にはなりません。同様に、systemテキストをuserメッセージへ移す処理では、テキストは維持されますが、その表現形式は変わります。
問題が起きた会話で再現する
更新の効果を確認するときは、ゲートウェイ、認証情報の取得元、選択したモデルを変えないでください。プロバイダーとバージョンを同時に変えると、どちらが結果に影響したのか判断できなくなるためです。
最初にClaude Codeを起動し、/statusを実行します。ゲートウェイへの接続手順には、そこで有効なベースURLと認証情報の取得元を確認する方法が記載されています。意図したゲートウェイが表示されなければ、betaへの対応を調べる前に接続設定を直してください。
次にいったん終了し、ローカルに診断ログを記録しながら問題の会話を開き直します。Bashでは次を実行します。
claude --resume --debug-file ./claude-gateway-debug.log選択画面で失敗したセッションを選び、問題を再現できる最小限のリクエストを繰り返してください。これらのフラグはCLIリファレンスに記載されています。
まず確認する成功条件は、以前失敗したリクエストに対して、利用できるアシスタントの応答が返ることです。互換性フォールバックによって復旧したと判断するには、利用可能なクライアントの診断情報と、参照できる場合はゲートウェイ側のリクエスト診断を調べ、拒否の後に調整済みの再試行が行われたことを確認します。新しい会話の最初のプロンプトが成功しただけでは、その後に現れるすべてのメッセージ構造を検証したことにはなりません。
BetterTokenのClaude Code設定手順では、/v1を付けないANTHROPIC_BASE_URL=https://bettertoken.aiが指定されています。クライアント更新の確認中も、この文書で示された接続先を維持してください。
更新後も失敗する場合
上流サービスのエラーレスポンス本文を保持してください。認識可能な拒否をゲートウェイ独自の不明瞭なエラーへ置き換えると、クライアントがフォールバックの条件を検出できない場合があります。また、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1でもeffortと会話途中のsystemエントリーは残るため、これらの問題を一律に解消するスイッチとしては使えません。
残っているエラーの内容に合わせて、次の確認先を選びます。
- 同じ、認識対象の拒否が繰り返される： 実際に起動している実行ファイル、手動指定のbeta値、ゲートウェイによる上流エラーの書き換えを確認します。
- 認証に失敗する： ゲートウェイの認証情報に関する手順に従います。接続ガイドでは、Bearer認証用の
ANTHROPIC_AUTH_TOKENと、x-api-key用のANTHROPIC_API_KEYが区別されています。プロバイダーが指定する方式を使ってください。 - エラーが別のフィールドを指している： そのフィールドの互換性要件を調べます。スキーマの拒否をすべてeffortの問題と判断しないでください。
- APIレスポンスが返る前に接続に失敗する： エンドポイント、プロキシ、DNS、TLSの接続経路を調べます。
問い合わせ時には、クライアントのバージョン、OS、選択したモデルID、リクエスト時刻またはリクエストID、HTTPステータス、正確なエラー文を揃えます。認証情報や会話ログ全体ではなく、機密情報を除いた診断ログの抜粋を共有してください。
Windowsフックが実際に呼び出しを止めることを確かめる
少なくとも2.1.310まで更新し、ポリシー適用に利用しているフックについて、失敗時の動作を確認してください。連続する2つのリリースで修正されたのは、それぞれ異なるケースです。
- 2.1.309は、PowerShellフックの終了コード処理と、フックがPowerShellを明示的に選んだ場合のGit不在時の問題を修正しています。
- 2.1.310は、Git Bashが存在せず、フックのコマンドが引用符で囲まれた文字列だけの場合に起きる、追加の問題を修正しています。
フックでエラーが起きても、それだけで操作が拒否されるとは限りません。フックリファレンスには、失敗時にトリガー元の操作を止める必要があるcommandフックとHTTPフック向けに、onFailure: "block"が用意されています。
引用符付き文字列だけのコマンドで起きる不具合を確認する
Git Bashのない、使い捨てのネイティブWindowsテスト環境を使ってください。Claude Codeの接続は正常に動作し、無関係なフックやプラグインが結果へ影響しない環境にします。これにより、作業用マシンからGitを削除せずに、Git Bashがない場合の動作を確認できます。
PowerShellで、新しいテスト用ディレクトリと無害なファイルを作成します。
$hookProbe = Join-Path $env:TEMP ("claude-hook-probe-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path (Join-Path $hookProbe '.claude') -Force | Out-Null
Set-Location $hookProbe
Set-Content -LiteralPath .\probe.txt -Value ([guid]::NewGuid().ToString())
Test-Path 'C:\__claude_hook_probe_missing__\python.exe'
claude --versionTest-Pathの結果がFalseであり、バージョンが2.1.310以降であることを確認してください。
このテスト用ディレクトリに.claude/settings.local.jsonを作成し、次を記述します。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Read",
"hooks": [
{
"type": "command",
"command": "\"C:\\__claude_hook_probe_missing__\\python.exe\""
}
]
}
]
}
}shell、args、onFailureを省いているのは意図的です。この段階では、引用符で囲まれたコマンドに対するフォールバックそのものを確認します。
PowerShellでセッションを開始します。
claude --tools Read --debug-file .\phase1.logこの使い捨てディレクトリについてワークスペースの信頼を承認し、/hooksを実行してPreToolUseフックがReadに一致することを確認してください。その後、次のように指示します。
Readツールをちょうど1回使ってprobe.txtを読んでください。呼び出しがブロックされた場合は、そのことを報告して停止してください。ほかの方法は使わないでください。
期待する結果： Readの呼び出しがブロックされ、エラーまたは診断情報にPowerShell started no programが表示されます。PowerShellは通常、引用符で囲まれたパスを文字列として評価します。PowerShell自体が起動しても、その文字列が指すプログラムを起動したことにはなりません。なぜそのパスを実行するには別の構文が必要なのかは、Microsoftの呼び出し演算子の説明で確認できます。
Readが実際に成功して結果を返した場合、この確認は不合格です。ClaudeがReadを呼び出そうとしなかった場合は、判定できません。モデルの説明だけを証拠にせず、ツールの実行結果とログを確認してください。
/hooksに設定が表示されない場合は、フック読み込みの確認手順に従います。設定は通常、自動で再読み込みされますが、ファイル監視が変更を見落とした場合は、再起動することで再読み込みさせられます。管理対象のフックだけを許可するポリシーがある場合も、このプロジェクト設定によるテストは実行されていないことになります。その場合、Readが動かなかっただけでは、設定したフックが機能したとは判定できません。
本当にインタープリターが存在しない場合を確認する
インタープリターを起動できない場合の挙動は、明示的な失敗時ポリシーを指定して確認します。テストセッションを終了し、内側のフックオブジェクトだけを次に置き換えてください。
{
"type": "command",
"command": "C:\\__claude_hook_probe_missing__\\python.exe",
"args": [],
"onFailure": "block"
}ここではargsによって、実行ファイルを直接起動する方式を選んでいます。引用符で囲まれた文字列を評価するのではなく、実在しない実行ファイルを起動しようとするため、実際の起動失敗が発生します。
PowerShellで起動し直し、先ほどと同じReadへの指示を繰り返します。
claude --tools Read --debug-file .\phase2.log期待する結果： インタープリターが起動できなかったため、Readがブロックされます。これはGit Bashの有無に依存せず、明示した失敗時処理を確認するテストです。引用符付き文字列だけのコマンドに関する不具合の確認とは、検証対象が異なります。
結果を確認したら、テスト用の設定を削除してください。実際にポリシーを適用するフックでは、動作するインタープリターへ戻します。チェックに失敗したら操作を止める必要がある箇所では、明示的にブロックする失敗時ポリシーを維持します。
これらのテストが確認するのはPreToolUseです。PermissionRequestフックは、権限確認の段階まで到達する操作を使って別途確認する必要があります。通常の拒否にはhookSpecificOutput.decision.behaviorを"deny"に設定します。終了コード2だけでは、このイベントは拒否されません。一方、onFailure: "block"を設定したフックで実際に失敗が起きれば、リクエストは拒否されます。
極端に長い保持期間を目的に合う値へ変更する
チームに特別な保持要件がなければ、文書に記載されたデフォルトの30日を使ってください。すでに長い期間を設定している場合は、短縮する前に、残したい履歴を別の場所へ保存します。
今回のクリーンアップ修正が対象とするのは、cleanupPeriodDaysが極端に大きい場合に最近のファイルが削除される問題です。この設定がアーカイブ機能になるわけではなく、すでに削除されたファイルが更新によって戻るわけでもありません。
保持期間を変える前に残っているデータを退避する
実行中のセッションを停止し、必要なデータをClaude Codeの管理ディレクトリ外へコピーしてください。~/.claude、Windowsでは%USERPROFILE%\.claudeにある必要なデータに加え、残っている添付画像も対象にします。
現在のアプリケーションデータの説明では、新しく貼り付けた画像は、Claude Codeの一時ルート配下にあるセッションごとのimages/ディレクトリへ保存されます。この一時ルートはCLAUDE_CODE_TMPDIRで制御されます。そのため、~/.claudeだけをバックアップしても、現在の画像コピーを保存できたことにはなりません。
データを退避した後、該当する設定ファイルに次の設定を追加・統合します。
{
"cleanupPeriodDays": 30
}個人のデフォルト値を設定するファイルは~/.claude/settings.json、Windowsでは%USERPROFILE%\.claude\settings.jsonです。既存のほかのキーは残してください。
2026-10-25時点の文書では最小値は1であり、0は検証エラーになります。期間を短くすると古いデータがクリーンアップ対象になるため、必要なデータの退避を先に行います。
claude doctorで設定が有効か確認してください。指定した値が適用されない場合は、設定の優先順位を調べます。管理設定や、より優先度の高いセッション・プロジェクト設定が個人用ファイルを上書きすることがあります。/statusで確認できるのは読み込まれた設定元であり、各キーについて最終的にどの値が採用されたかがすべて表示されるわけではありません。
消えた添付画像は別途復元する
見つからない画像は、元のファイルか既存のファイルシステムのバックアップから復元し、そのコピーを会話へ再添付してください。ローカルでファイルを開けることと、Claudeが添付画像を再び利用できることを確認します。
保持期間の変更では、削除済みのバイト列を再構成できません。/rewindで添付画像が復元できるとも考えないでください。チェックポイントのスナップショットにも有効期限があり、必要なスナップショットがなくなっていれば復元に失敗することがあります。
すでにテレメトリーをエクスポートしているチームは、完了済みのclaude_code.retention_sweepイベントを確認できます。モニタリングリファレンスには、result: "complete"と、文字列値のperiod_daysが記載されています。"30"であれば、そのクリーンアップ実行で30日の保持期間が使われたと確認できます。
再起動して短時間動かしただけでは、クリーンアップが実行された証拠にはなりません。処理はバックグラウンドでセッションごとに最大1回実行され、直前の24時間以内に実行されていれば、次のセッションでの実行は少なくとも10分遅れます。添付画像を開けることと、クリーンアップが完了した証拠は、別々の確認事項として扱ってください。
Monitorの対応拡大は別の変更として扱う
バージョン2.1.310では、MonitorツールとプラグインのモニターがBedrock、Vertex、Foundryでも利用可能になりました。テレメトリーや必須ではない通信を無効にした構成も含まれます。リリースノートには、これらの環境でもフォアグラウンドで長時間スリープする処理がブロックされると記載されています。
該当する環境でMonitorが使えなかった場合は、テレメトリーポリシーを変更する前に、起動中のバージョンを確認してください。この対応拡大と、個々のゲートウェイがeffort設定や会話途中のsystemエントリーを受け付けるかどうかは、別の問題です。
