Claude apps gatewayをCIやリモート開発機から使うには

CIパイプラインはClaude apps gatewayに直接サインインできない

Claude apps gatewayにサービストークンの仕組みはありません。サインインは常にブラウザのデバイスフローで、承認する開発者がいないCIジョブはこの経路で認証できません。無人のパイプラインにはプロバイダー直結の構成が必要です。

一方でリモート開発機は事情が違います。開発者が一度サインインしてしまえば、そのマシン上のどのClaude Codeセッションもゲートウェイセッションを使い回せます。ディスプレイのないリモートボックスでも、SSH越しに/loginを実行し、確認リンクだけ手元のブラウザで開けば認証が完結します。「CIパイプライン」と「リモートマシン」はどちらもディスプレイを持たない実行環境という点で似ていますが、承認者の有無という一点で扱いが分かれます。

リモート開発機でサインインする手順

デバイスフローは、ポーリングするCLIと承認するブラウザを分離した設計です。この分離のおかげで、リモートボックス自体にブラウザが無くても成立します。

ssh dev-box.internal
claude

/login

/loginは確認用URLとuser_codeを表示します。これをリモートボックスではなく、手元のノートPCのブラウザで開いて承認します。承認が完了すると、リモートボックス側のCLIがサインインを検知してセッションを開始します。

初回サインイン時には、CLIがゲートウェイのTLS証明書の指紋(SHA-256の先頭16文字)を表示し、そのホスト名に対して指紋をピン留めします。管理者が事前に正しい指紋を共有していれば、リモートボックス上で表示された値と見比べるだけで、中間者攻撃による偽ゲートウェイへの接続を検知できます。証明書がローテートされると、この確認プロンプトは全開発者に対して再表示されます。

MDM管理下のリモート開発機ならURLを自動入力できる

社給のリモート開発機がMDMで管理されているなら、OS別のmanaged settingsファイルにforceLoginMethodとforceLoginGatewayUrlを配布しておけます。

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
}

この設定があると、/loginはゲートウェイのURLが入力済みの状態で直接開き、開発者はEnterを押すだけでサインインに進めます。逆に、この設定を配布していない自己管理のリモートボックスでは、開発者はゲートウェイのURLを自分で把握していないと/loginを先に進められません。

一度サインインすれば、そのマシンの全セッションが対象になる

/loginでサインインした後は、同じマシン上で動く非対話のclaude -p実行も、Agent SDKが起動するセッションも、すべて同じゲートウェイセッションを使います。ゲートウェイのポリシーは、対話セッションと同じ強さでそれぞれに適用されます。

つまり、リモート開発機を「常時サインイン済みの実行環境」として扱えば、そこで動く自動化スクリプトは追加設定なしでゲートウェイ経由になります。使い捨てのCIジョブランナーではなく、開発者本人が管理する常駐マシンでの自動化に向いた構成です。

開発者に強制される制約は自動化にもそのまま及ぶ

/loginでサインインしたセッションには、次の制約が例外なくかかります。自動化スクリプトから呼び出す場合も同じです。

最後の起動時到達性の挙動は、CIやスケジュールジョブで動かす場合に見落としやすい点です。ゲートウェイが一時的に不通になっただけで、ジョブがフォールバックせずに失敗します。リトライだけでなく、ゲートウェイの可用性そのものを監視対象に含める必要があります。

モデルアクセスの制約も、人間が対話的に使うときと自動化スクリプトとで扱いは変わりません。たとえばgateway.yamlのポリシーでeng-contractorsグループにpermissions.deny: [WebFetch, WebSearch]を設定している場合、そのグループの開発者が起動したリモートボックスでの自動化も同じく2つのツールを使えません。ポリシーはIdPグループかメールドメイン単位で決まるため、自動化用に緩いポリシーを別途用意することはできず、実行アカウントに紐づくグループそのものを見直す必要があります。

デプロビジョニングの挙動も長時間動くジョブでは効いてきます。開発者がIdP側で無効化されると、その瞬間はまだセッションが生きていても、次のサイレント更新に失敗した時点でttl_hours以内に失効します。数時間かかるバッチジョブをリモートボックスで走らせている最中に担当者がオフボーディングされると、ジョブは終了を待たずに認証エラーで止まります。

Agent SDKはゲートウェイ専用のオプションを持たない

Agent SDKには、ゲートウェイに固有の設定項目がありません。SDKは環境変数をそのままClaude Codeプロセスへ渡すだけで、TypeScriptとPythonでは引き継ぎ方が違います。

• TypeScript: options.envを設定すると環境が丸ごと置き換わる。ゲートウェイ変数を維持するにはprocess.envを展開してから上書きする
• Python: ClaudeAgentOptions(env=...)は継承した環境にマージされるため、親プロセスで設定済みのゲートウェイ変数はそのまま自動的に引き継がれる

Agent SDKからリモート開発機のゲートウェイセッションを使う場合、この違いを意識していないと、TypeScript側だけ環境変数が丸ごと消えて原因不明の認証エラーになります。

自動化が当てにできない最適化がある

長時間の自動化タスクをリモートボックスで回す場合、ゲートウェイ経由だと使えない最適化がいくつかあります。コストやレイテンシーを見積もる前に押さえておきたい点です。

繰り返し同じ長いシステムプロンプトを送るタイプの自動化では、5分TTLの前提でキャッシュヒット率を設計し直す必要があります。1時間TTLを前提にコストを見積もっていると、ゲートウェイ経由に切り替えた途端に想定より高くつきます。

リモートボックスでの自動化は組織からどう見えるか

リモート開発機で自動化スクリプトを回す前に、組織側から何が見えているかを知っておく価値があります。使用状況のテレメトリには、開発者の身元・トークン数・モデル・レイテンシーが乗り、ゲートウェイ自体はプロンプトや応答の内容をログにも保存しません。ログやトレースのような、実行したコマンドやファイルパスまで含みうるリッチなテレメトリを集めるかどうかは、転送先ごとの組織の選択です。

つまり、自動化スクリプトが何を実行したかという粗い実績は組織の可観測性スタックに残りますが、既定の設定ではコマンドの中身までは残りません。ログ・トレースを有効にした転送先を運用している組織では、その前提が変わる点に注意しておく必要があります。

本当に無人のCIを回したいなら、別のゲートウェイ経路を使う

デバイスフローが要求する「承認する人間」をその場に用意できない、GitHub Actionsのような完全無人のCIでは、Claude apps gatewayの/login経路はそもそも選択肢になりません。この場合の現実的な対応は次の2つです。

1. プロバイダーに対して直接認証する: Amazon BedrockやAnthropic APIのクレデンシャルをCIのシークレットストアに登録し、ゲートウェイを経由せずに直接呼び出す
2. 自社運用の別のLLMゲートウェイを使う: サービストークンやAPIキーでの認証をサポートするゲートウェイ製品であれば、GitHub ActionsやAgent SDKからの接続手順がそのまま使える

どちらもClaude apps gateway自体の制約を回避する構成であって、Claude apps gatewayをCIから使う方法ではありません。この違いを混同すると、「ゲートウェイ経由の一元管理」というメリットがCIのぶんだけ抜け落ちていることに気づかず、監査の抜け穴になります。CIの資格情報とリモート開発機のゲートウェイセッションは、管理対象としては別物だと最初から割り切って設計しておくのが実務上は簡単です。

まとめ

Claude apps gatewayが対応するのは、人が承認できる場所での認証だけです。リモート開発機はSSH越しの/loginで対応でき、一度サインインすればAgent SDKやclaude -pもそのセッションに乗ります。無人のCIパイプラインだけは対象外で、プロバイダー直結か、サービストークンに対応した別のゲートウェイに切り替える必要があります。

判断に迷ったら、「その実行を承認できる人間がそばに存在するか」で切り分けるのが早道です。存在するならリモート開発機としてデバイスフローに乗せ、存在しないなら最初から別経路を選びます。導入の全体像はClaude apps gatewayの使い方、開発者ごとの支出上限はSpend limitsの設定で確認できます。