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

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

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

一方でリモート開発機は事情が違います。開発者が一度サインインすれば、そのマシン上のどのClaude Codeセッションもゲートウェイセッションを使い回せます。ディスプレイのないリモートボックスでも、SSH越しに/loginを実行し、確認リンクだけ手元のブラウザで開けば認証は完結します。

分かれ目は承認者の有無だけです。画面があるかどうかは関係しません。

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

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

ssh dev-box.internal
claude

/login

承認が完了すると、リモートボックス側のCLIがサインインを検知してセッションを開始します。ゲートウェイが取り消し用のエンドポイントを公開していれば、/logoutはゲートウェイ側のセッションも終わらせにいきます。応答がなくても、手元のサインアウトは完了します。この取り消しはv2.1.275以降のClaude Codeが対象です。

TLS証明書の指紋ピン留めはリモートでも効く

ゲートウェイのホスト名やIPアドレスは、/loginの時点で私設アドレスにだけ解決される必要があります。パブリックなIPv4ブロックを社内網に使う組織は、managed settingsのgatewayInternalNetworksにそのブロックを列挙します。この場合、開発機は同じブロックの内側から接続します。このキーはv2.1.268以降が対象です。HTTPS_PROXYがゲートウェイのホストに効いていると/loginが拒否され、追加すべきNO_PROXYのエントリが表示されます。

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

ピンの照合はサインイン時だけではありません。サイレントなセッション更新と、managed settingsの取得でも走ります。推論リクエストは通常のTLS検証だけで、ピンは使いません。

リモートボックスがHTTPSプロキシ経由で外に出る構成では、プロキシ越しのリクエストはピンの照合を飛ばします。ゲートウェイのホストをNO_PROXYに入れて直接つなぐのが、ドキュメント上の対処です。証明書がローテートされると、確認プロンプトは全開発者に再表示されます。

ポリシーファイルが無い自己管理のボックスでは、サインインを始められない

リモート開発機でサインインできる条件は、forceLoginMethodとforceLoginGatewayUrlが、そのマシンのmanaged settingsに入っていることです。MDMで配るか、OS別のmanaged settingsファイルを直接置きます。

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

この設定があると、/loginはゲートウェイのURLが入力済みの状態で直接開きます。開発者はEnterを押すだけでサインインに進めます。

逆に、開発者が自分でURLを打ち込む経路はありません。ログインの選択画面にゲートウェイの項目は無く、開発者自身の設定ファイルに書いたforceLoginGatewayUrlは無視されます。URLなしでforceLoginMethodだけを置くと、「Contact your IT administrator」と表示されて止まります。

claude auth loginのサインイン方法のフラグは--claudeai・--console・--email・--ssoで、v2.1.289時点でゲートウェイ向けのものはありません。ゲートウェイへの入口はmanaged settingsだけです。

したがって、自己管理のリモートボックスを使う場合は、管理者に先にポリシーファイルを置いてもらうのが最初の仕事になります。

古いAPIキーが残っていると、起動時に止まる

ポリシーが届いたマシンに、Anthropic発行の資格情報が残っている場合も要注意です。ANTHROPIC_API_KEY・ANTHROPIC_AUTH_TOKEN、apiKeyHelperの設定、Claude Consoleの旧ログインで保存されたAPIキーが該当します。

managed settingsがforceLoginMethodかforceLoginOrgUUIDを設定している場合、Claude Codeは起動時に終了します。メッセージは、設定されている資格情報の出どころと外し方を名指しします。たとえばシェルにANTHROPIC_API_KEYがあると次のとおりです。

Administrator policy requires a Cloud gateway sign-in on this machine, but this session is configured with an API key from ANTHROPIC_API_KEY, which a gateway machine does not accept.
 
To continue: unset ANTHROPIC_API_KEY (or run in a shell without it), then run claude and sign in with /login.

v2.1.284より前のメッセージは、候補の資格情報を並べるだけで、どれを外すかを名指ししませんでした。同じ文言が出たら、v2.1.284以降へ更新すると原因が特定できます。

CLAUDE_CODE_USE_BEDROCKのように、クラウドプロバイダーを環境変数で選んだセッションは、ゲートウェイのサインインを要求されません。リモートボックスで既にBedrock直結の自動化を回しているなら、この経路が残ります。

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

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

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

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

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

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

モデルアクセスの扱いも、人間が対話的に使うときと変わりません。ポリシーでenforceAvailableModels: trueを設定すると、Defaultの選択肢がavailableModelsの中のモデルに解決されます。設定がなければ、Defaultは選べる状態のまま、許可されていないモデルだと実行時に拒否されます。夜間のバッチが、前日まで動いていたDefaultで急に400を返す場面は、この組み合わせで起こりえます。

ツール権限も同じです。gateway.yamlのポリシーでeng-contractorsグループにpermissions.deny: [WebFetch, WebSearch]を設定していれば、そのグループの開発者が起動したリモートボックスでの自動化も、この2つのツールを使えません。ポリシーはIdPグループかメールドメイン単位で選ばれるため、自動化用に別のポリシーを当てるには、実行アカウントを別のグループに入れる必要があります。

長時間のジョブではデプロビジョニングも効きます。開発者がIdP側で無効化されても、その瞬間はセッションが生きています。次の更新に失敗するとttl_hours以内にセッションが失効し、再ログインが求められます。数時間かかるバッチの最中に担当者がオフボーディングされると、ジョブはその時点で続行できなくなります。

ttl_hoursの既定値は1です。IdPがリフレッシュトークンを発行できない構成では、毎時間ブラウザのログインに戻らずに済むよう、8や12に上げる選択肢があります。

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

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

TypeScriptで環境変数を丸ごと消さないための書き方は次のとおりです。

const options = {
  env: {
    ...process.env,
    ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
  },
};

この違いを意識していないと、TypeScript側だけ環境変数が消えて原因不明の認証エラーになります。上のコードは、別のLLMゲートウェイへ認証情報を渡す場合の例です。

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

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

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

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

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

送り先にも注意点があります。/loginでサインインしたセッションでは、CLIはOTLP/HTTPの送信先を、ローカルに設定したOTEL_EXPORTER_OTLP_ENDPOINTではなくゲートウェイにします。ポリシーが自前のコレクターを送信先として名指ししている場合は例外です。自動化スクリプト側で独自のコレクターを設定していても、ポリシーがなければそちらには届きません。

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

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

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

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

2つ目の場合、GitHub ActionsやAgent SDKからの接続手順がそのまま使えます。x-api-keyで認証するゲートウェイなら、ワークフローは次のとおりです。

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
 
steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Bearerトークンのゲートウェイでは、同じシークレットをanthropic_api_keyの入力と、envのANTHROPIC_AUTH_TOKENの両方に渡します。アクションは起動前にanthropic_api_keyなどの存在を検査しますが、ANTHROPIC_AUTH_TOKENは読みません。Authorizationヘッダーに鍵を載せるのは、env側の変数です。

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

まとめ

承認できる人間がそばにいて、かつ管理者のポリシーファイルが届いているマシンなら、リモート開発機としてデバイスフローに乗せられます。どちらかが欠けるなら、プロバイダー直結か、サービストークンに対応した別のゲートウェイを最初から選びます。

導入の全体像はClaude apps gatewayの使い方、開発者ごとの支出上限はSpend limitsの設定で確認できます。