結論：egressの名前解決とheadersの用途を分けて管理する
Claude Code v2.1.277では、Claude apps gatewayの唯一のegressがforward proxyである場合にCLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1を使えるようになりました。これにより、outbound requestはhostnameをproxyへ渡し、Gatewayが宛先をローカル解決しない経路を設計できます。またupstreamへ送る任意のheaders: mapも追加されましたが、static headerへsecretを直書きしてよいという意味ではありません。
読者の課題は、proxyを置いた後もDNS、header、TLS、upstreamのどこで外部へ出るかを説明できないことです。まず送信経路を図にし、名前解決を誰が行うか、headersを誰が付与・閲覧するか、失敗時に止めるかを分けてください。
根拠はClaude Code v2.1.277公式リリースとClaude apps gateway configuration公式文書です。gatewayが通過させるrequest・responseの条件はgateway compatibility公式文書、Gateway導入の全体像はClaude apps gateway公式overviewを正本にします。既存のGatewayの公開範囲制限はCIDRとinternal network、OTLP転送はcollectorと保持が中心で、本稿はforward proxyのegress boundaryとupstream headersへ限定します。
直接接続・forward proxy・Gatewayを比較する
| 経路 | 名前解決 | 先に決める境界 |
|---|---|---|
| Gatewayが直接egress | Gatewayまたは基盤側 | 宛先allowlist、DNS、TLS、secret |
| forward proxyが唯一のegress | proxyへhostnameを渡す | proxyのallowlist、認証、log、停止条件 |
| upstream headersを付与 | 経路とは別のmetadata | 値、閲覧者、転送先、secret化 |
| proxy障害 | 解決できても送信不可 | fail-closed、通知、再試行上限 |
CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1は、forward proxyが本当に唯一の外向き経路であることを前提にします。別のDNS経路、debug用のcurl、health check、コンテナ内のdirect routeが残っていれば、環境変数だけで境界は閉じません。network policy、route table、security group、host firewallを別レイヤーで確認し、proxy logのhostnameとGateway logのrequest idを対応付けます。
安全に設計する8手順
- 外向き先を列挙する。Anthropic API、cloud provider、IdP、OTLP collector、health check、packageや更新経路を分けます。
- 唯一のegressを証明する。Gateway container、host、sidecar、管理用shellにdirect routeや別proxyがないか確認します。
- 名前解決者を固定する。Gatewayで解決するのか、forward proxyへhostnameを渡すのかをdiagramと設定台帳に記録します。
- 変数のscopeを限定する。
CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1を検証環境から適用し、起動時に期待した経路になったかreadbackします。 - headersを分類する。routing、tenant、trace、認証補助など目的ごとに分け、providerへ転送する値とproxyだけが使う値を区別します。
- secretを外出しする。gateway.yamlへtokenやclient secretを直書きせず、公式configが示す環境変数・file reference・secret managerの経路で注入します。
- 通過条件をテストする。request header、body field、response key、streaming event、tool-use IDがproxyで欠落・改変しないことを確認します。
- 停止と監査を試す。proxy拒否、DNS失敗、TLS失敗、header不備、upstream timeoutで、fail-openせず通知とrequest idを残せるか確認します。
static headersは便利ですが、すべてのupstreamへ無条件に同じ値を送るとtenant混同や意図しない情報共有につながります。header名、値のsource、対象upstream、ログでのマスキング、変更ownerを表にし、認証に使う値はsecretの有効期限とrotationを別台帳で管理します。proxyがheaderを追加する場合とGatewayが追加する場合を同時に採用すると、どちらが正本か分からなくなるため、まず一つの責任点へ寄せます。
Claude apps gatewayのconfigは起動時にschema検証され、unknown keyや必須sectionの欠落はboot errorになります。これは安全の証拠ではなく、入力ミスを早く見つける仕組みです。listen、oidc、session、store、upstreamsなどの正規設定と、proxy関連の環境変数・header mapを同じcommitでレビューし、credentialの値そのものはcommitへ入れないようにします。
企業導入でのfail-closed境界
proxyが停止した時、Gatewayを起動し続けるか、推論受付を止めるかは業務によって異なります。認証、監査、費用制御、外部送信をproxyへ依存しているなら、到達不能なのに処理を続けるfallbackは説明が難しくなります。read-onlyのhealth checkと本番inferenceを分け、proxyのallowlistにないhostnameは明示的に拒否し、拒否理由とrequest idだけを監査へ残します。
upstream headersの変更では、値の漏えいだけでなく、cache key、rate limit、tenant routing、support調査への影響を確認します。headerにcustomer nameや個人情報を入れず、必要ならopaqueな識別子へ変換します。proxy log、Gateway log、upstream logの三つで同じ値が見える範囲を確認し、保持期間と閲覧権限を揃えます。
gateway compatibility文書が示す通り、Claude Codeの新機能は未認識のfieldやstreaming eventを使うことがあります。proxyが「知らないfieldを削る」設計だと、Auto modeのserver checksや将来の機能が壊れます。許可するpass-throughをversion付きで管理し、更新時はrequest・responseのgolden testを行います。単に200を返すだけでなく、tool call、長いstream、エラー、再試行を含むreadbackを合格条件にしてください。
チェックリスト
- v2.1.277の正式な変数名を確認した
- forward proxyが唯一のegressか証明した
- Gatewayとproxyの名前解決責任を固定した
- headersの目的・対象upstream・ownerを記録した
- secretをconfig本文へ直書きしていない
- request・response・streamingのpass-throughを検証した
- proxy停止時のfail-open/closedを決めた
- logのmasking、保持、request id照合を確認した
よくある質問
環境変数を設定すればdirect egressは必ず消えますか？
いいえ。これはGatewayの解決経路を設計するための設定です。hostやcontainerのroute、sidecar、debug経路など別の外向き経路をnetwork側でも閉じます。
headers mapへAPI keyを書いてよいですか？
直書きを前提にしないでください。config公式文書のsecret expansionやsecret managerを使い、値の閲覧・rotation・log maskingを確認します。
proxyが200を返せば互換性は十分ですか？
不十分です。request field、response key、streaming、tool-use ID、Auto mode関連fieldが通過するか、代表ケースとエラーケースで検証します。
公式情報
次の一歩
proxy、Gateway、provider、監査の責任が分かれていて、外向き経路を一枚で説明できない場合は、設定追加より先に境界を棚卸しします。Miraigentの無料診断で、egress、headers、secret、停止責任を60秒から確認できます。