SpyBara
Go Premium

claude-apps-gateway-deploy.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 49 additions and 42 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Sat 19 23:57 Fri 25 23:58

Claude apps gateway のデプロイと運用

IdP にゲートウェイを登録し、コンテナをビルドして Kubernetes または Cloud Run にデプロイし、ヘルスチェック、シークレットローテーション、アップグレード、セキュリティを運用します。

このページでは、Claude apps gateway の運用側について説明します。ID プロバイダー（IdP）で OAuth クライアントを登録し、ゲートウェイをコンテナとしてデプロイし、日々運用します。ゲートウェイが起動時に読み込む gateway.yaml ファイルのすべてのオプションについては、設定リファレンス を参照してください。

本番環境のデプロイメントは順序立てた 4 つのステップに従い、以下のセクションがそれに対応しています。最初の 2 つは選択を行う場所です。後の 2 つは、実行中に参照するリファレンス資料です。

  1. ID プロバイダーをセットアップする：OAuth クライアントを登録し、Okta、Entra、Google の IdP 固有の注記を確認します
  2. ゲートウェイをデプロイする：ピン留めされたコンテナイメージをビルドし、Kubernetes、Cloud Run、または独自のプラットフォームで実行します。このセクションではコスト、バイパス、複数ゲートウェイ、サーバーレスの決定についても説明します
  3. 運用をセットアップする：ログ、ヘルスプローブ、障害時の動作、シークレットローテーション、アップグレード。監視とランブックを配線するときに参照するリファレンス
  4. セキュリティ体制を確認する：データがどこを流れるか、脅威モデル、コンプライアンスの回答。セキュリティレビュー用のリファレンス

サインインまたはブート中に失敗が発生した場合は、トラブルシューティング に直接進んでください。これは表示されるエラーに基づいてキー付けされています。

ID プロバイダーのセットアップ

単一のリダイレクト URI https://<gateway>/oauth/callback を持つ機密 OAuth/OpenID Connect（OIDC）ウェブアプリケーションを ID プロバイダーに登録し、ゲートウェイアクセスを持つべきユーザーまたはグループに割り当てます。

任意の OIDC 準拠 IdP が機能します：Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、PingFederate など。IdP は 3 つの要件を満たす必要があります：

  • /.well-known/openid-configuration を提供します。本番環境では HTTPS 経由です。ゲートウェイは http:// issuer を受け入れ、ループバック issuer は追加で CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 が必要です
  • 認可コードフローをサポートします。PKCE（Proof Key for Code Exchange）はデフォルトで有効です。サポートしない IdP の場合は oidc.use_pkce: false で無効にします
  • id_token で email と必要に応じて groups を返すか、oidc.userinfo_fallback: true で userinfo エンドポイントから提供します

プライベート PKI の場合は、oidc.ca_cert_pem を設定します。

いくつかのプロバイダーはメールとグループクレームを異なる方法で処理します：

  • Okta：https://example.okta.com の org 認可サーバーは、email と groups を省略した薄い id_token を返すため、issuer として使用する場合は常に oidc.userinfo_fallback: true を設定します。https://example.okta.com/oauth2/default などのカスタム認可サーバーは、id_token に email と必要に応じて groups を含め、直接発行し、フォールバックは不要です。Okta は oidc.scopes で groups スコープがリクエストされ、アプリのグループクレームフィルターが許可する場合にのみ groups を発行します。userinfo_fallback は IdP がリクエストされなかったクレームを埋めることはできません。
  • Microsoft Entra ID：issuer = https://login.microsoftonline.com/<tenant-id>/v2.0。Entra はグループ名ではなくグループオブジェクト ID を発行するため、managed.policies.match.groups で GUID を使用するか、人間が読める名前のためにアプリロールを使用します。テナントが groups の代わりに roles の下でロールを発行する場合は、oidc.groups_claim: roles を設定します。
  • Google Workspace：issuer = https://accounts.google.com。Google の id_token はグループを含みません。Google を IdP として、グループベースの allowed_groups または managed.policies を使用するには、oidc.google_groups を設定します。これは、ドメイン全体の委任を持つサービスアカウントを使用して Admin SDK Directory API を通じて各ユーザーのグループを検索します。これなしで、メンバーシップゲーティングに oidc.allowed_email_domains を使用し、ポリシー割り当てに managed.policies.match.email_domain を使用します。Google は標準の offline_access スコープも無視します。リフレッシュトークンの場合は、oidc.scopes: [openid, profile, email] と oidc.extra_auth_params: { access_type: offline, prompt: consent } を設定します。

デプロイ

ゲートウェイは単一のステートレス Linux バイナリで、Postgres を通じて調整されるため、環境内でステートレスサービスをデプロイする方法でデプロイします。ネットワーク内に保持し、開発者と IdP が HTTPS 経由で到達でき、本番認証情報を保持する他のサービスと同様に扱います。

デプロイメントを実行する場所を超えて形作るいくつかの決定があります：

  • コスト：ゲートウェイの個別ライセンスまたはシートごとの料金はありません。ゲートウェイは claude バイナリの一部であるため、既存のコミットメントを通じて推論に対して支払い、実行するコンピュートに対して支払います。
  • バイパス：ゲートウェイは、モデルへの唯一のルートがそれを通過することを強制しません。独自の認証情報を持つ開発者は引き続きプロバイダーを直接呼び出すことができるため、そのパスを閉じることはネットワークポリシーの決定です。例えば、api.anthropic.com へのエグレスをゲートウェイ以外からブロックします。そのエグレスをブロックすると、各開発者のマシンから api.anthropic.com を呼び出す WebFetch ドメインセーフティチェック も破壊されます。管理ポリシーで skipWebFetchPreflight: true を設定して無効にします。
  • 複数ゲートウェイ：各ゲートウェイは独自の設定を持つ個別のデプロイメントで、CLI はゲートウェイホスト名ごとに信頼と認証情報を保存するため、チームは競合なしに異なるゲートウェイを使用できます。複数の OIDC issuer を提供するには、個別のインスタンスを実行します。
  • サーバーレス：Cloud Run は機能します。min-instances: 1 を設定して、コールド OIDC ディスカバリーを回避します。Lambda と Cloud Functions は機能しません。ゲートウェイは長時間実行 HTTP サーバーであるためです。

ここのすべての本番トポロジーは、L7 プロキシ（Ingress、Cloud Run のフロントエンド、ALB など）をプレーン HTTP レプリカの前に配置します。listen.trusted_proxies をプロキシのソース範囲に設定して、ゲートウェイが X-Forwarded-For からクライアント IP を読み込みます。ゲートウェイは TCP ピアが信頼されている場合にのみヘッダーを尊重します。Google Cloud と AWS の実装例には、トポロジーごとに具体的な値があります。信頼されたプロキシなしでは、すべてのリクエストはプロキシの IP から来ているように見え、IP ごとのレート制限を 1 つの共有バケットに折りたたみ、監査イベントにプロキシの IP を記録します。

ゲートウェイのデバイス認可とトークンエンドポイントへのリクエストをリダイレクトしないでください。Claude Code はこれらのリクエストでリダイレクトに従わないため、HTTP から HTTPS へのリダイレクトやホスト正規化の書き換えなどのリダイレクトルールは、サインインとトークン更新を破壊します。

プロキシに、ゲートウェイのキープアライブ間隔より長いアイドルタイムアウトを与えます。これは上流に依存します：

  • provider: anthropic 以外のすべての上流では、ゲートウェイはストリームが約 15 秒間サイレント状態になった後、SSE ping を 1 回書き込みます。
  • provider: anthropic では、ゲートウェイは Anthropic API 独自の ping を含む応答をそのまま渡します。

ALB の 60 秒などのデフォルトは、静かなストリームを開いたままにするのに十分です。AWS の実装例 はとにかくそれを 1 時間に引き上げ、トラブルシューティング行は v2.1.229 より古いゲートウェイをカバーしており、現在 ping を取得する上流でサイレント期間中に何も送信しませんでした。

コンテナイメージ

標準 Claude Code リリースのネイティブ claude バイナリの周りに独自のイメージをビルドします：

  1. ピン留めされたリリースからイメージアーキテクチャの Linux ビルドをダウンロードします。ダウンロード URL については、特定のバージョンをインストールする を参照してください。
  2. バイナリの整合性とコード署名 で説明されているように、リリースの GPG 署名付き manifest.json に対して検証します。
  3. ビルドコンテキストにコピーします。

ビルドがリリースホストに到達できない場合は、リリースを内部レジストリにミラーリングし、フロートが実行するバージョンをピン留めします。

バイナリを超えて、イメージは以下が必要です：

  • glibc ベースのイメージ：glibc ビルドの唯一の動的依存関係は glibc ライブラリです。Musl ベースのイメージは linux-x64-musl または linux-arm64-musl ビルドと追加パッケージが必要です。Alpine Linux セットアップ を参照してください。
  • 書き込み可能な状態ディレクトリ：ゲートウェイは任意のユーザーとして実行されますが、最小限のイメージには書き込み可能なホームがありません。CLAUDE_CONFIG_DIR を /tmp/.claude などの書き込み可能なパスに設定します。
  • コンテナコマンド：claude gateway --config /etc/claude/gateway.yaml。設定ファイルは読み取り専用でマウントされ、シークレットは環境変数として提供されます。ゲートウェイは listen.port でリッスンします。デフォルトは 8080 です。

Kubernetes

ゲートウェイをデプロイメントとして実行します。他のステートレスサービスと同様です：

  • ConfigMap から設定をマウントし、Secret からシークレットをマウントします。YAML で ${file:/path/to/secret} または環境変数を通じてシークレットを参照します
  • Ingress で TLS を終了し、listen.public_url を Ingress ホスト名に設定します
  • readiness プローブを GET /readyz に、liveness プローブを GET /healthz に指定します

AWS での完全な実装例（ECS Fargate または EKS、Amazon RDS、AWS Secrets Manager をカバー）については、AWS にデプロイする を参照してください。

静的キーよりもプラットフォームのワークロードアイデンティティを優先します。upstreams リファレンス にはプラットフォームごとのセットアップ詳細があります。クロスクラウドペアリング（例えば GKE 上の Amazon Bedrock 上流）の場合は、上流の auth ブロックで明示的な認証情報を設定します。

Cloud Run

サービスを以下のように設定します：

  • listen.port をデフォルトの 8080 のままにします。これは Cloud Run のデフォルト PORT と一致するか、port: ${PORT} を設定します
  • public_url を外部到達可能なオリジンに設定します。本番環境では、これは通常、内部ロードバランサーのホスト名です。/login は パブリックアドレスを拒否 し、*.run.app URL はそれに解決するため、Cloud Run URL だけは curl またはブラウザスモークテストにのみ機能します。例外は、*.run.app が Private Service Connect と Cloud DNS プライベートゾーンを通じてプライベートに解決するネットワークです。そのトポロジーでは、Cloud Run URL は有効な public_url です。Google Cloud の実装例 は両方をカバーしています。
  • シークレットボリュームとして設定をマウントします
  • min-instances: 1 を設定して、最初のリクエストでコールド OIDC ディスカバリーを回避します

Google Cloud での完全な実装例（Cloud Run または GKE、Cloud SQL、Secret Manager をカバー）については、Google Cloud にデプロイする を参照してください。

ゲートウェイ URL を開発者マシンにプッシュする

ゲートウェイがサービスを提供したら、MDM を通じて、または OS ごとの managed-settings.json を直接書き込むことで、管理設定を通じて各開発者のマシンに forceLoginMethod、forceLoginGatewayUrl、および parentSettingsBehavior: "merge" をプッシュします。これなしでは、/login はゲートウェイオプションなしで標準アカウントピッカーを表示します。ファイルパスと Claude Desktop bootstrapUrl 相当については、クライアント側の管理設定 を参照してください。

運用

ゲートウェイがトラフィックを提供したら、日々の運用はそのログを読み込み、その健全性をプローブし、スケジュールに従ってシークレットをローテーションすることです。サブセクションは各々をカバーし、Postgres が保持するもの、アップグレードとロールバックがどのように動作するかをカバーします。

ログ

ゲートウェイは stderr に 2 つのストリームを書き込みます。両方とも JSON フレンドリーです：

  • 監査イベント：セキュリティ関連イベントごとの単一行 JSON。stderr をログアグリゲーターにパイプします。発行されるイベントには config.load、session.mint、session.refresh、device.authorize、device.verify、device.callback、auth.denied、access.denied、inference、managed.serve、desktop_bootstrap.serve、desktop_bootstrap.denied、spend.blocked、admin.denied、admin.limit.upsert、admin.limit.delete が含まれます。フィールドはイベントによって異なります：
    • 成功した mint と refresh イベントは sub、email、client_ip、結果を含みます
    • auth.denied と access.denied は理由とクライアント IP を含み、auth.denied ではリクエストパスも含みます。拒否時にはユーザーアイデンティティが存在しないため
    • inference は、どの上流がリクエストを提供したか、応答ステータスを記録します
    • desktop_bootstrap.denied は、拒否された Claude Desktop ブートストラップフェッチを理由（not_configured、policy_not_opted_in、no_policy_matched）とユーザーのアイデンティティで記録します
    • admin.denied は、拒否された admin-API 認証試行をクライアント IP、メソッド、パス、理由で記録します。提示されたキーマテリアルなし：x-api-key が提示されたが設定されたキーと一致しなかった場合は invalid_key、Authorization ヘッダーのみが提示され、ゲートウェイセッションとして admin.admin_groups で検証されなかった場合は bearer_rejected、どちらのヘッダーも提示されなかった場合は no_credentials
  • 運用ログ：ブート、警告、上流エラーの人間が読める [gateway] プレフィックス付きの行。CLAUDE_GATEWAY_LOG_LEVEL 環境変数は詳細度を制御し、debug、info、warn、error を受け入れます。デフォルトは info です。debug では、各サインインと更新は id_token のクレーム名（値ではなく）もログに記録され、userinfo_fallback が提供した場合は userinfo クレーム名もログに記録されるため、PII をログに記録することなく email_claim と groups_claim 設定を診断できます。監査イベントには影響しません。常に発行されます。

ヘルス

ゲートウェイは GET /healthz を liveness プローブとして、GET /readyz を readiness プローブとして提供します。/readyz はストアが到達可能であることを検証します。両方とも access_control.allow_cidrs から除外されるため、プローブはロックダウンされたリスナーで機能し続けます。

/.well-known/oauth-authorization-server の OAuth ディスカバリードキュメントは、設定ロード、OIDC ディスカバリー、上流クライアント構築、Postgres マイグレーションがすべて成功した後にのみ 200 を返すため、エンドツーエンドのブートチェックとしても機能します。

障害時の動作

Postgres がダウンした場合、ゲートウェイ自体はサインイン済みの開発者にサービスを提供し続け、新しいサインインは失敗します。開発者が実際に機能し続けるかどうかは、オーケストレーターが readiness をどのように処理するかに依存します：

  • 既存セッション：ベアラートークンは JWT シークレットでローカルに検証され、セッション更新はストアに触れず、ゲートウェイプロセスは引き続き推論を提供できます
  • 新しいサインイン：Postgres が回復するまで失敗します。デバイスフローとそのレート制限カウンターは Postgres に存在するため
  • 支出制限の実装：デフォルトでは障害中に失敗してオープンになるため、推論は引き続き流れます。ブロックするのを好む場合は、失敗を閉じるようにフリップします
  • Readiness：/readyz は障害中に not-ready を報告するため、readiness でトラフィックをゲートするオーケストレーターはすべてのレプリカを一度にローテーションから削除します。そのトポロジーでは、ゲートウェイが引き続き提供できる推論を含むすべてのトラフィックは、Postgres が回復するまでロードバランサーで失敗します。/healthz の liveness プローブは引き続き合格するため、レプリカは再起動されません。ストア障害を通じてサインイン済みの開発者が機能し続けるようにしたい場合は、readiness プローブを /healthz に指定します。コストは新しいサインインが引き続き ready を報告するレプリカに対して失敗することです。

IdP がダウンした場合、既存セッションは ttl_hours まで機能し、新しいログインと更新は失敗します。IdP が頻繁なメンテナンスウィンドウを持つ場合は、より長い ttl_hours を設定します。

JWT シークレットローテーション

既存セッションが有効なままになるように、3 つのステップで署名シークレットをローテーションします：

  1. 新しいシークレットを生成します。session.jwt_secret 配列の前に付加します。
  2. デプロイメントをロールします。新しいトークンは新しいシークレットで署名します。古いトークンは引き続き検証されます。
  3. ttl_hours とマージンの後、古いシークレットを削除してもう一度ロールします。

ローテーションは、有効期限が切れる前にセッションを強制的に削除する唯一の方法でもあります。ベアラートークンは JWT シークレットに対してローカルに検証されるため、セッションごとの取り消しはありません。シークレットを完全に置き換え、配列に古いものを保持しないと、すべての未処理セッションが一度に無効になります。個別のオフボーディングの場合は、IdP でユーザーをプロビジョニング解除します。セッションは ttl_hours 内に終了します。

Postgres

ゲートウェイは 5 つのデータテーブルと _migrations テーブルを保持し、すべてはブート時マイグレーションで作成されます：

テーブル 内容 保持期間
kv デバイスグラント（10 分 TTL）とレート制限カウンター 行ごとの TTL
spend プリンシパルごとの期間から現在までの支出カウンター（セント単位） admin.spend_retention_months、デフォルト 13
spend_limits 設定された支出キャップ API 経由で削除されるまで
admin_audit Admin API ミューテーショントレイル admin.audit_retention_days、デフォルト 365
principal_emails 各プリンシパルの最後に見たメール、表示名、IdP グループ。PII を含みます。 admin.identity_retention_days 最後のアクティビティ以来、デフォルト 90

30 秒ループは TTL を超えた kv 行を期限切れにし、1 時間のスイープは支出テーブルの保持ウィンドウを実装するため、何も無制限に成長しません。支出制限 が設定されていない場合、kv のみが書き込まれます。ゲートウェイはブート時と各アップグレード時に独自のスキーママイグレーションを適用するため、そのデータベースロールはテーブルを作成および変更する権限が必要です。ゲートウェイ専用のデータベースまたはスキーマを指定して、その権限を狭く保ちます。

支出制限が使用されている場合、失われたデータベースは失われた支出追跡とキャップを意味し、開発者の再ログインだけではないため、定期的なバックアップを実行します。保持を待つのではなく、出発した開発者を直ちに削除するには、DELETE FROM principal_emails WHERE principal = '<sub>' を直接実行します。これはメール、名前、グループを保持する唯一のテーブルを削除します。spend と admin_audit 行は疑似匿名 OIDC sub のみを参照します。

アップグレード

レプリカはステートレスであるため、ローリング再起動はいつでも安全です。ゲートウェイはブート時にスキーママイグレーションを実行します。つまり、新しいバイナリをデプロイするとデータベースが自動的にマイグレーションされます。同時実行レプリカは Postgres アドバイザリロックでシリアライズされるため、各マイグレーションを適用するのは 1 つだけです。

マイグレーションは追加のみであるため、より少ないマイグレーションを知っている以前のバイナリにロールバックするのは安全です。余分な行を無視します。ロールバックは YAML を古いバイナリのスキーマに対して再検証するため、新しいリリースで導入されたキーを採用した設定は古いバイナリでのブートに失敗します。ロールバックする前に新しいキーを削除します。

独自のイメージでゲートウェイのバージョンをピン留めするため、新しい Claude Code リリースのセキュリティ修正を含む修正は、ピンを更新して再デプロイするときにのみデプロイメントに到達します。ゲートウェイを、本番認証情報を保持する他のサービスに使用するのと同じパッチングケーデンスに含めます。

セキュリティ

このセクションは、セキュリティレビューが尋ねる質問に答えます：ゲートウェイを通じてどのデータが流れ、どこに行くか、設計が防御する攻撃、コンプライアンスアンケートに属する回答。

データフロー

データ パス ゲートウェイによって Anthropic に送信
推論（プロンプト、完了） CLI → ゲートウェイ → 上流 Anthropic API が設定された上流の場合のみ
テレメトリ（OTLP メトリクス、プラス オプトイン ログとトレース） CLI → ゲートウェイ → コレクター なし
アイデンティティ（メール、グループ、sub） IdP → ゲートウェイ → JWT → CLI。CLI はそれを OTLP エクスポートにスタンプします。forward_user_identity をオンにすると、ゲートウェイは開発者のメールと IdP サブジェクトをヘッダーとしてプロキシに送信します なし
管理設定 ゲートウェイ YAML → CLI なし
監査ログ ゲートウェイ stderr → アグリゲーター なし

脅威モデルの概要

ゲートウェイはネットワーク境界内に位置しますが、個々の開発者ラップトップは信頼されていないと見なされます。設計はこれを 3 つの方法で説明します：

  • 開発者は生の上流キーの代わりに短命の JWT を保持します。CLI からゲートウェイへのレッグは RFC 8628 デバイスグラントを使用し、ゲートウェイの IdP との認可コード交換はデフォルト設定で PKCE を実行するため、インターセプトされた IdP 認可コードは無用です。
  • デバイス検証ページは同一オリジン POST と RFC 8628 §5.1 ごとの IP ごとのレート制限を実装します。ユーザーコードブルートフォース耐性 を参照してください。
  • アウトバウンドリクエストはサーバー側リクエストフォージェリ（SSRF）ガードを通じて行われます。DNS を解決し、リンクローカルとクラウドメタデータアドレスをブロックし、デフォルトではループバックをブロックし、接続を解決された IP にピン留めします。IdP と OTLP 宛先などのオペレーター影響 URL はクラウドメタデータエンドポイントにリダイレクトできません。RFC 1918 プライベート範囲は意図的に許可されます。IdP と OTLP コレクターは一般的にプライベート IP に存在するため。ゲートウェイが正当に到達する必要があるもの（ローカル開発 IdP やサイドカー OTLP コレクター（localhost など）など）がループバック上に存在する場合にのみ、ゲートウェイの環境で CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 を設定します。変数はすべてのオペレーター設定 URL のループバックブロックを緩和し、ポッドがクラウドメタデータエンドポイントに到達できるかどうかをチェックするブート時警告もスキップするため、コレクターに独自の内部アドレスを与えることをお勧めします。

独自のエグレス制御を追加する場合、ゲートウェイはワークロードアイデンティティなどのインスタンスメタデータ認証情報を使用するときはいつでもメタデータサーバーに到達する必要があります。

2 つの脅威は、インフラストラクチャを保護するためのものであるため、スコープ外です：

  • 侵害されたゲートウェイホスト：ホストは上流認証情報を保持し、管理設定 をすべての接続された開発者に配布するため、ゲートウェイの設定の制御は MDM の制御に匹敵します。CLI の 承認ダイアログ はシェル対応設定のサイレント変更を制限しますが、ホストセキュリティに置き換わりません。
  • 悪意のある OIDC プロバイダー：プロバイダーはゲートウェイが信頼する id_token に署名するため、任意のアイデンティティを主張できます。IdP の検証と保護はあなたの責任です。

ユーザーコードブルートフォース耐性

開発者が /device 検証ページに入力する user_code は、20 文字のアルファベットから引き出された 8 文字です。これは 20⁸ または約 2.56×10¹⁰ の組み合わせを生成し、10 分後に期限切れになります。

ゲートウェイは rate_limits を通じて設定可能なデバイスグラントエンドポイントに IP ごとのレート制限を適用します。多くの開発者が単一の共有企業 NAT アドレスからサインインする場合は、制限を上げます。制限はサインインフローにのみ適用され、推論には適用されません。

コンプライアンス体制

  • データレジデンシー：ゲートウェイ自体のデータプレーンは、Anthropic API が設定された上流の場合を除き、Anthropic に何も送信しません。その場合、既存のデータ処理契約が推論パスに適用されます。テレメトリ、監査、アイデンティティ、設定は設定した宛先にのみ行きます。
  • ホストプロセストラフィック：ホストプロセスは Claude Code CLI です。claude gateway は Amazon Bedrock および Google Cloud の Agent Platform デプロイメントと同じサードパーティルールの下で実行され、Anthropic に何も送信しません。v2.1.227 より前では、ホストプロセスは製品バージョンとプラットフォームなどのスタートアップテレメトリを送信していました。これはコンテナ環境で CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 を設定することでオフにできました。これらのリリースはまた、ボート時に本文または認証情報なしで 1 つの HEAD リクエストを https://api.anthropic.com の /api/hello に送信していました。または環境が ANTHROPIC_BASE_URL を設定した場合はそれに、環境が HTTPS_PROXY などのプロキシ変数または mTLS クライアント証明書も設定していない限り。彼らは応答を無視したため、エグレスファイアウォールでそのリクエストをブロックしてもゲートウェイに影響しませんでした。
  • クライアント分析：CLI はゲートウェイにサインインしている間、独自の使用分析とエラー報告を無効にします。最初のサインイン前に、CLI はまだ Anthropic にスタートアップイベントを送信します。これには、管理設定がゲートウェイサインインを強制するマシンも含まれます。これらもオフにするには、ゲートウェイサインインを強制する同じ クライアント側管理設定 で DISABLE_TELEMETRY を配信します。
  • エラー報告：CLI はモデルリクエストが Anthropic のファーストパーティ API 以外のエンドポイント（Amazon Bedrock やカスタム ANTHROPIC_BASE_URL など）に行くときはいつでもエラー報告をオフにします。
  • クライアントマシン：開発者の CLI は、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 と skipWebFetchPreflight: true が設定されていない限り、WebFetch ホスト名チェックとバージョンチェックを Anthropic に送信し続けます。データ使用 を参照してください。
  • サーベイ評価：ゲートウェイにサインインしている間、CLI は Anthropic バウンド評価アップロードを分析ストリームと一緒に無効にするため、評価を Anthropic に送信しません。
  • トランスクリプト共有：サーベイのトランスクリプト共有プロンプトで「はい」を選択すると、Anthropic にアップロードする代わりに ~/.claude/feedback-bundles/ の下にローカルファイルを書き込みます。
  • クライアント更新：更新チェックはゲートウェイトラフィックとは別です。独自の配布を通じてバージョンをピン留めし、ラップトップがリリースをフェッチしてはいけない場合は DISABLE_UPDATES を設定します。DISABLE_AUTOUPDATER はバックグラウンド更新のみを停止し、claude update は引き続き機能します。
  • TLS：本番環境で public_url を HTTPS 経由で提供します。ゲートウェイ自体のリスナー経由で listen.tls を使用するか、プレーン HTTP レプリカの前の TLS 終了 ingress から listen.public_url を設定します。どちらの場合でも。ゲートウェイはプレーン HTTP を拒否しません。IdP は本番環境で HTTPS を提供する必要があり、Postgres は ?sslmode=require をサポートします。ingress で Strict-Transport-Security を設定します。
  • 脆弱性開示：セキュリティ問題の報告 に従います

トラブルシューティング

質問とフィードバックについては、Claude Code サポート を使用するか、Claude Code GitHub リポジトリ で issue を開きます。問題を報告するときは、以下を含めます：

  • ゲートウェイの問題：関連するウィンドウのゲートウェイの stderr、シークレットが削除された gateway.yaml、ゲートウェイバージョン（/ のランディングページに表示、/managed/settings の x-cc-gateway-version レスポンスヘッダー）、最近変更されたもの
  • ログイン問題：開発者は claude --debug-file ./claude-debug.txt を実行し、再現し、そのファイルとゲートウェイの同じウィンドウの監査ログを送信します
  • 推論問題：リクエストされたモデル、設定された上流、リクエストのゲートウェイ監査ログ。どの上流がそれを提供したか、応答ステータスを記録します

ゲートウェイの stderr には監査イベントストリームが含まれ、監査ログには開発者の ID が記録され、デバッグファイルには開発者のマシンからの hook と MCP サーバーの出力が記録されます。公開 issue に投稿する前に、これらを確認して秘密情報を削除してください。

症状 原因 修正
開発者の /login は標準アカウントピッカーを表示し、Cloud gateway 画面ではなく 管理設定で forceLoginMethod または forceLoginGatewayUrl が設定されていない 管理設定ファイル をデバイスにデプロイします。/login はそこからゲートウェイ URL を読み込みます
Claude Desktop はブートストラップ設定を取得できなかったと報告 /user/bootstrap は 404 を返しました：ユーザーと一致するポリシーが desktop キーを持たないか、ポリシーが一致しません。ゲートウェイの監査ログは各拒否を desktop_bootstrap.denied として理由とともに記録します。 ユーザーと一致するポリシーに desktop ブロックを追加するか、match: {} ベースレイヤーに追加します。空の desktop: {} で十分です。Claude Desktop オーバーレイ を参照してください。
スタートアップは Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support. を表示 インストールされた Claude Code ビルドはゲートウェイサポートより前 開発者に Claude Code を Cloud gateway サポートを含むリリースに更新させます
CLI /login：Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip> ゲートウェイホスト名は少なくとも 1 つのパブリック IP アドレスに解決されます。Claude Code は各解決されたアドレスをチェックし、すべてがプライベートであることを要求します。一般的な原因は、1 つのファミリーがパブリックアドレスに解決するデュアルスタック名です。AWS 内部デュアルスタックロードバランサーを含み、パブリック範囲 AAAA アドレスを返します。 ゲートウェイ名が開発者マシンでプライベートアドレスのみに解決されるようにします。デュアルスタック名の場合は、パブリック範囲レコードをドロップするか、個別の内部専用 DNS 名を提供します。プライベートネットワーク前提条件 を参照してください。
CLI /login：Gateway login would go through proxy <proxy>, which is not on a private network HTTPS_PROXY または HTTP_PROXY がゲートウェイホストに適用され、プロキシのホスト名がパブリックアドレスに解決されます。ホスト名がプライベートアドレスのみに解決するプロキシは許可され、このエラーをトリガーしません ゲートウェイホストを開発者のマシンの NO_PROXY に追加して、接続が直接になるようにするか、ホスト名がプライベートアドレスに解決するプロキシを使用します。メッセージは追加する正確な NO_PROXY エントリを名前で指定します
CLI /login：Could not resolve the configured HTTP proxy HTTPS_PROXY または HTTP_PROXY のホスト名が開発者のマシンから解決されません。通常、企業ネットワークに接続していないため 開発者にネットワークまたは VPN に接続させて再試行するか、プロキシ URL を修正します
CLI /login：Could not resolve gateway host <host> マシンはゲートウェイの内部 DNS 名を解決できません。通常、企業ネットワークにないため 開発者にネットワークまたは VPN に接続させ、/login を再試行します
ブートは store.postgres_url という名前の設定検証エラーで終了 Postgres が設定されていません。ゲートウェイは Postgres が必要です store.postgres_url を設定します。ローカル開発の場合は、使い捨てコンテナを使用します：docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres。
ブートは終了：requires the native binary Node の代わりにネイティブバイナリの下で実行 スタンドアロンインストール方法 の 1 つで Claude Code をインストールします
ブートは config.load の後の OIDC ディスカバリーエラーで終了 oidc.issuer に到達不可、または TLS チェーンが信頼されていない issuer がポッドから到達可能で /.well-known/openid-configuration を提供することを確認します。プライベート PKI の場合は ca_cert_pem を設定します。 ポッドが forward proxy を通じてのみ IdP に到達する場合は、oidc.use_proxy: true を設定します。v2.1.227 より前のバージョンでは、代わりに IdP の各エンドポイントへの直接ルートをポッドに提供します。
ブートは Postgres パーミッションエラーで終了 データベースロールがそのスキーマに対して DDL 権限を持たない ロールにゲートウェイのスキーマに対する CREATE を付与して、ブート時にテーブルを作成および変更できるようにします
/oauth/callback は「Sign-in could not be completed」を表示 メールドメインが拒否されました。id_token 検証が失敗しました。または email_verified が明示的に false です。ゲートウェイは常にオーバーライドなしで拒否します allowed_email_domains を確認し、IdP が検証済み email クレームを返すことを確認します。email_verified: false の場合は、IdP 側の検証を修正します。IdP がメールを別のクレーム名の下で発行する場合は、oidc.email_claim を設定します。
ログ：token exchange failed request_id=<id>: id_token missing email claim IdP はデフォルトで id_token に email を含めていません。この拒否は allowed_email_domains が設定されている場合にのみ発火します。なしでは、欠落したメールはメールなしでセッションをミントします IdP を設定して id_token で email を発行します。Okta：カスタム認可サーバーの ID トークンクレームに email を追加します。Entra：アプリ登録でオプションクレームとして email を追加します。PingFederate：email を発行する OpenID Connect ポリシーを有効にします。IdP が userinfo エンドポイントから email を提供するが、id_token に含めない場合（Okta org 認可サーバーなど）、oidc.userinfo_fallback: true を設定します。
すべての Amazon Bedrock リクエストは 502 を返します。ログは Could not load credentials from any providers を表示 EC2 では、IMDSv2 のデフォルトホップリミット 1 がコンテナ内からのインスタンスメタデータリクエストをブロックします。ブートと /readyz はクライアント構築時ではなく最初のリクエストで AWS SDK がインスタンス認証情報を解決するため、とにかく合格します aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2 でホップリミットを上げるか、起動テンプレートで設定します。変更はインスタンス上のすべてのコンテナに適用されます。利用可能な場合は ECS タスクロールを優先します。ECS コンテナ認証情報エンドポイントから認証情報を読み込み、変更を完全に回避するか、専用ゲートウェイインスタンスで変更を適用して露出を制限します。
IdP エラー：unknown or unsupported scope IdP は認識しないスコープを拒否します oidc.scopes を IdP が受け入れる正確なリストに設定します。openid を含める必要があります。デフォルトは openid profile email offline_access です。
oidc.scopes を設定した後、セッションはサイレントに更新されません offline_access がオーバーライドからドロップされました IdP がサポートしている場合は offline_access を戻します。リフレッシュトークンなしでは、開発者は session.ttl_hours ごとにブラウザログインを再実行します。
ブラウザは「This request came from another site and was blocked」を表示 クロスサイトフォーム POST。CSRF 保護としてブロックされました。埋め込みまたはプロキシされたページの場合は予想されます 検証リンクを直接開きます
Chrome は「Refused to send form data … violates … Content Security Policy directive: form-action」で Approve ボタンをブロックしますが、同じページは Safari または Firefox で機能します Chrome はリダイレクトチェーン全体に対して form-action を実装します。IdP はさらに、許可リストに登録されていない 2 番目のホストにリダイレクトします。 リダイレクトチェーン内の各追加オリジンを oidc.form_action_origins に追加します。Approve ページで Chrome DevTools → Console を開いて、どのオリジンがブロックされたかを確認します。
サインインは IdP で完了しますが、コールバックは失敗します。Chrome で CSP エラーまたは Safari で「this sign-in link has expired」 IdP は response_mode=form_post を通じてコードを返しました。これは /oauth/callback にクロスオリジン POST を通じて自動送信します。Chrome はそれを厳密な CSP の下でブロックします。Safari は送信を許可しますが、コールバックはクエリ文字列のみを読み込みます。 IdP が response_mode=query を尊重することを確認します。ゲートウェイは明示的にリクエストするため、コールバックはプレーンリダイレクトです
ログインはローカルで機能しますが、ALB の背後で失敗します public_url が設定されていないため、IdP は内部 http:// オリジンを redirect_uri として取得します listen.public_url を外部 https:// オリジンに設定し、<public_url>/oauth/callback を IdP に登録します
開発者は信頼プロンプトを繰り返し見ます TLS 証明書はレプリカごと、またはリクエストごとにローテーションしています ingress で安定した証明書を使用するか、TLS を 1 回終了し、レプリカをプレーン HTTP で内部で実行します
CLI /login：「Could not verify the gateway's TLS certificate」または SELF_SIGNED_CERT_IN_CHAIN ゲートウェイの TLS チェーンは、CLI ホストの信頼ストアにないプライベート CA によって署名されています Claude Code はデフォルトでネイティブバイナリで OS 信頼ストアを読み込み、Node 22.15 以降で読み込みます。CLAUDE_CODE_CERT_STORE はこの動作を制御します。CA が OS 信頼ストアにインストールされている場合は、開発者が現在のランタイムにいることを確認します。そうでない場合は、起動する前に NODE_EXTRA_CA_CERTS を CA 証明書 PEM に設定します。最初の接続フィンガープリントプロンプトは引き続き適用されます。
CLI /login はブラウザサインインを完了し、セッションは Cloud gateway sign-in was not completed で終了し、TLS 証明書の不一致 サインイン後の最初のリクエストで、ゲートウェイは Claude Code がピンした フィンガープリントと一致しない証明書を提示したため、Claude Code はゲートウェイ認証情報を保持しませんでした。通常の原因は、1 つのアドレスの背後にあるレプリカが異なる証明書を提供するか、ネットワークパス上の何かが TLS をインターセプトしています。 ホスト名に対して 1 つの証明書を提供します。例えば、ingress で TLS を 1 回終了し、開発者に /login を再度実行させます。その証明書がピンされたものと異なる場合、Claude Code は 信頼プロンプト を警告とともに表示し、証明書が変更されたことを示します。
CLI /login は The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted で停止 サインインリクエストは、開発者が /login を開始したときに受け入れた証明書と一致しない証明書を提供するサーバーに到達しました：1 つのアドレスの背後にあるレプリカが異なる証明書を提供、パス上の TLS インターセプション、またはサインイン中の証明書ローテーション。 ホスト名に対して 1 つの証明書を提供し、開発者にサインインを再度開始させ、信頼プロンプト で新しい証明書を確認させます。

Cloud gateway sign-in was not completed メッセージはゲートウェイホスト名を名前で指定し、Claude Code が両方のフィンガープリントを持つ場合、ピンされたものと提示されたものの最初の 16 文字を指定します。

Claude Code がゲートウェイサインイン後に couldn't load your organization's managed settings を報告する場合、Claude Code は理由を名前で指定し、その場で再起動し、会話を再開します。Claude Code が再起動できない場合（例えば、バックグラウンドセッション）、Claude Code はセッションを終了し、サインインを保持します。