結論：互換性エラーと機能低下を分けて判断する
Claude Code 2.1.288では、MantleやGatewayなど構造化出力を拒否する経路で、session title・memory recall・prompt hooksが失敗する問題への対処としてCLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTSが追加されました。ただし、これはエラーを回避する互換性設定であり、モデル性能や安全性を高める設定ではありません。原因の経路を特定し、必要なscopeだけで有効化します。
Anthropic公式のClaude Code changelogは2.1.288で、structured outputsを拒否するGatewayなどでの不具合修正と環境変数を案内しています。settings公式リファレンスはmanaged settings、command line、project local、shared project、userの優先順位を説明しています。Gatewayを組織経路として使う場合はClaude Apps Gateway公式資料も対象のserver・provider・versionと一緒にreadbackしてください。
structured outputsが問題になる境界
structured outputsは、自由文ではなく定義された構造に沿って返すための経路です。Claude Code内部では、session titleやprompt hookなど複数の補助機能が利用する可能性があります。Gatewayがリクエストをそのまま中継せず、特定のresponse formatを拒否・変換すると、メインの会話は動いても補助機能だけが失敗することがあります。
| 症状 | 先に分ける原因 | 判断 |
|---|---|---|
| titleが作れない | structured output拒否、provider応答、保存 | debug logとGateway応答を比較 |
| memory recallだけ失敗 | sessionの補助リクエスト | 本文の生成失敗と混同しない |
| prompt hookが止まる | hook実行、schema、権限 | hook単体の再現を取る |
| 全機能が遅い | Gateway、認証、providerの経路 | compatibility設定の前に疎通を測る |
この切り分けは、Claude Codeがエラーを出したから直ちに環境変数を全員へ配る、という判断を避けるためです。既存のGateway認証エラーの記事では認証・API経路を、組織ポリシーの記事ではmanaged settingsの適用を扱っています。本稿はstructured outputsの互換性に限定します。
8手順で設定の必要性を確認する
claude --version、provider、Gateway server version、sessionの実行面を記録します。- 失敗する機能をtitle、memory、prompt hook、structured responseのどれかに分けます。
- Claude Codeのdebug logとGatewayのrequest・response・HTTP statusを同じ時刻で保存します。
- 直接providerへ送る検証環境とGateway経由の環境で、同じprompt・model・設定を比較します。
- Gatewayがstructured outputまたはresponse schemaを拒否している事実を確認します。
- 影響範囲を限定したsessionまたは端末で
CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTSを設定します。 - title、memory、hook、再開、通常会話を一つずつ再試行し、直った機能と失われた機能を記録します。
- 原因が修正されたら環境変数を外し、同じ回帰テストを実行して通常経路へ戻します。
設定値の配置は、shell、user settings、project settings、managed settingsのどこへ置くかを分けます。秘密情報を含むGatewayのheadersをprojectへ置かないのと同じように、互換性フラグをrepositoryへ無条件にcommitしない選択もあります。設定を追加する場合は、対象、owner、期限、rollbackを一緒に記録します。
設定scopeと運用の比較
| 配置 | 向いている状態 | リスク |
|---|---|---|
| 一時shell | 再現確認、個別の障害調査 | 別sessionへ引き継がれない |
| user | 同じ端末の限定provider | 別projectへ影響する |
| project | 全員が同じGatewayを使う検証 | 意図せず本番へ配布する |
| managed | 組織で経路を統一する | 範囲が広くrollbackに時間がかかる |
公式の優先順位ではmanaged settingsが最も高く、command line、project local、shared project、userの順です。ただし、同じ変数名を複数箇所に置くと原因が見えにくくなります。最初は一時設定で再現し、検証が終わるまでmanagedへ昇格させないことを勧めます。Gatewayの仕様、契約、利用できるモデル、データ保持は公開直前にも公式画面でreadbackします。
公開前チェックリスト
- エラーがGateway・providerのstructured output拒否である
- Claude Code versionとGateway server versionを記録した
- 直接経路とGateway経路で同じ条件を比較した
- 環境変数を対象session・端末・providerへ限定した
- title、memory、hook、通常会話の回帰を確認した
- 設定のowner、期限、rollback、社内告知を決めた
- 機能低下や別の失敗を「修正済み」と誤認していない
企業利用では、互換性フラグを標準設定にする前に、Gatewayが何を変換しているかを説明できる状態にします。structured outputを無効化した後に、hookやmemoryのエラーが表面化しなくなるだけなら、監査の観測点が減っている可能性があります。失敗件数、再試行、手動作業、データ送信先を比較して判断します。
FAQ
- 設定すると全ての構造化出力が無効になりますか？
- 環境変数の具体的な適用範囲はversion・provider・実行面に依存します。対象sessionでtitle、memory、hook、通常会話を実測し、公式changelogと実ログを照合してください。
- Gatewayのエラーなら必ずこの設定を使いますか？
- いいえ。認証、model、schema変換、provider制限の可能性を先に分けます。structured outputs拒否と確認できた場合に限り、限定scopeで検証します。
- 互換性診断を無料で相談できますか？
- できます。version、provider、Gateway経路、ログのマスキング済み抜粋、設定scopeを無料診断（60秒）へまとめてください。
復旧後に残す証跡は、成功したことだけでは不十分です。どの経路で、どの機能が、どの設定の有無で変わったかを表にします。エラーメッセージやGatewayログにはprompt、token、個人情報が含まれる場合があるため、共有前にマスキングします。providerのサポートへ問い合わせる場合も、最小限の再現条件を作ります。
更新を継続する場合は、Claude Codeのchangelogを見て、structured outputsに関する修正が入った時にフラグを外すテストを自動化します。互換性のための暫定設定を永続化すると、別providerへの移行や新しい機能追加の障害になります。期限を過ぎた設定は、責任者が再承認しない限り削除するルールにします。