自己ホスト環境は Team および Enterprise プランでパブリックベータ版です。利用可能性と制限事項に有効化パスが記載されています。このページは CI テストレシピです。セットアップについてはクイックスタートを、フリートレシピについては本番環境へのデプロイをご覧ください。
テスト実行イメージにキャプチャフックをインストールする
読み取りは Claude Code のStop フックを通じて機能します。Claude がターンを完了すると、フックは最終アシスタントメッセージを stdin JSON のlast_assistant_message として受け取り、$E2E_REPLY_DIR/<session_id>.txt に追加します。commit-nudge Stop フックと同じ方法でインストールします。実行イメージホストの ~/.claude/ にインストールします。実行イメージはこれをすべてのセッションにシードします。
フックファイルを保存する
実行イメージホストに以下の 2 つのファイルを保存します。- 設定ブロック:実行イメージホストの
~/.claude/settings.jsonにマージします - スクリプト:実行イメージホストに
~/.claude/hooks/e2e-stop-hook-capture.shとして保存し、実行可能にします
実行イメージを開始する前に
フックが依存する 2 つのこと:- 実行イメージを開始する前にインストールします。実行イメージは起動時に
~/.claude/をスナップショットするため、実行中の実行イメージに追加されたフックは再起動後にのみ有効になります。 - 実行イメージプロセスに
E2E_REPLY_DIRをエクスポートします。フックは変数が未設定または ディレクトリが存在しない場合は no-op です。実行イメージを開始する場所(systemd ユニット、pod spec、CI ステップなど)で設定します。以下のテストスクリプトもこれが必要です。
E2E_REPLY_DIR が存在するたびにすべてのセッションの最終返信をディスクに書き込みます。これは使い捨ての CI 実行イメージでは無害ですが、変数が誤って設定される可能性がある本番環境実行イメージには含めるべきではありません。
テストループを実行する
--environment および --ref ディスパッチフラグには、スクリプトを実行するマシン上の Claude Code v2.1.224 以降が必要です。これは実行イメージ自体と同じ下限です。フックが配置され、このホストで実行イメージが開始されている場合、テストスクリプトは以下を実行します。
claude -p "<prompt>" --environment <environment-id> --output-format jsonでテスト環境にセッションを作成します。git チェックアウトから実行して、CLI がoriginリモートからリポジトリを自動検出できるようにします。オプションの--ref <branch>は、ローカル HEAD の代わりに名前付き ref に基づいてセッションのチェックアウトを行います。コマンドはセッションを作成し、session_idを含む 1 行の JSON を出力し、Claude の返信を待たずに終了します。- Stop フックが実行イメージ上でターンが完了したら
$E2E_REPLY_DIR/<session_id>.txtに返信が表示されるまで待機します。 claude -p "<message>" --cloud <session_id> --output-format jsonでフォローアップを送信します(実行中のセッションにフォローアップメッセージを送信するを参照)。これは既存のセッションにユーザーイベントをポストし、終了します。- ステップ 2 と同じ方法でフォローアップの返信を待機します。
--environment ディスパッチ動作
Claude Code はセッションを作成し、セッション ID とそのリンクを出力して終了します。
フラグは remote.defaultEnvironmentId 設定よりも優先されます。--output-format stream-json をサポートしておらず、--resume、--continue、--teleport、--session-id、--init-only など、セッションを再開、アタッチ、または事前設定するフラグと組み合わせることはできません。--cloud はセッション ID または URL で拒否され、非対話型実行では説明を含む場合に拒否されます。ベアの --cloud は存在しないものとして扱われます。ターミナルから、位置指定プロンプトの代わりに --cloud 説明としてタスクを渡すことができます。
スクリプト例
以下のスクリプトは$CLAUDE_TEST_ENVIRONMENT_ID(テスト環境の ccpool_... ID)に対して完全なループを実行します。これは管理ページの環境詳細ダイアログに表示されるか、環境作成呼び出しによって返されます。各返信のセンチネルフレーズをアサートします。キャプチャフックがインストールされ、E2E_REPLY_DIR がエクスポートされている実行イメージを使用して、このホストで実行イメージを開始した後、セッションを実行したいリポジトリの git チェックアウトから実行します。
TURN1/TURN2 プロンプトと EXPECT1/EXPECT2 センチネルを、カスタム MCP ツールの 1 つを実行するよう Claude に依頼し、その出力をアサートするなど、セットアップを実行するものに置き換えます。
リモートテスト実行イメージ
テスト実行イメージが別のインフラストラクチャ上にある場合(CI ジョブがファイルシステムを共有できない永続的な Kubernetes フリートなど)、Stop フックのファイル書き込みをドライバーがリッスンするエンドポイントへの POST に置き換えます。CI から認証する
claude -p ... --environment と claude -p ... --cloud の両方は claude.ai OAuth トークンで認証します。sk-ant-xxxxx などの API キーはどちらの呼び出しでも受け入れられません。2 つのアプローチにより、CI でトークンを利用できるようになります。
長期間存続する CI ホスト
スクリプトを実行するマシン上で、自動化用の専用ユーザーアカウントを使用して、claude auth login を 1 回対話的に実行します。Claude Code はトークンを macOS ではOS キーチェーンに、Linux と Windows では ~/.claude/.credentials.json に保存します。キーチェーンに書き込みできない macOS ホスト(SSH セッションでログインキーチェーンがロックされたままの場合など)では、Claude Code はトークンを ~/.claude/.credentials.json にも保存します。認証情報管理を参照してください。
CLI は各呼び出しで短期アクセストークンを自動的に更新しますが、基盤となるリフレッシュトークングラントは初期ログインから 30 日間に制限されているため、そのホストで 30 日ごとに claude auth login を対話的に再実行してください。
エフェメラル CI 実行イメージ
現在、これに対する長期間存続する CI トークンはありません。リモートセッション制御を付与するスコープuser:sessions:claude_code はサーバー側で 30 日間に制限されているため、1 年間の推論のみのトークンを発行する claude setup-token はこれをカバーしていません。環境シークレットも受け入れられません。これは実行イメージが環境に登録することのみを認可し、セッションを作成することは認可しないためです。
エフェメラル実行イメージに保存されたログインをプロビジョニングするには、CLAUDE_CODE_OAUTH_REFRESH_TOKEN と CLAUDE_CODE_OAUTH_SCOPES を設定して、claude auth login がブラウザなしでトークンを交換できるようにします。リフレッシュグラントに対して同じ 30 日間の上限が適用されます。人間のアカウントにバインドされていないマシンアイデンティティパスが必要な場合は、Anthropic アカウントチームにお問い合わせください。
専用テスト環境を作成する
CI の各実行ごとにクリーンな環境を取得するために、環境をプログラムで作成および削除します。CI ジョブが開始する runner がこのフレッシュな環境に登録されます。以下の作成および削除呼び出しは、claude.ai の Cloud environments 管理ページが使用するのと同じエンドポイントであり、anthropic-beta: ccr-byoc-2025-07-29 ヘッダーが必要です。
管理トークンを生成する
$ADMIN_TOKEN は、Owner ロールを保持するアカウントの claude.ai OAuth アクセストークンであり、CI から認証すると同じ方法で生成されます。
- 生成する: Owner ロールを保持するアカウントで
claude auth loginを実行してから、長期間実行される CI ホストが Claude Code がそれを保存した場所を示す場所から現在のアクセストークンを読み取ります。 - 各実行ごとにフレッシュに読み取る: CLI はアクセストークンをローテーションし、同じ 30 日間のリフレッシュ許可上限が適用されるため、コピーを保存しないでください。
- stdin 経由で渡す: 例が行うように、トークンが curl の引数リストまたはビルドログに記録されないようにします。
環境を作成する
レスポンスをキャプチャして出力しないようにします。pool_secret は、runner を環境に登録できる長期間有効な認証情報であるため、マスクされた CI シークレットとして保存し、環境 ID のみを出力します。トークンをプロセスリストから除外する -H @- 形式には curl 7.55 以降が必要です。古い curl は @- をリテラルヘッダーとして扱い、認可なしでリクエストを送信します。
403 permission_error で失敗し、self-hosted runners are disabled by your organization's policy と表示されます。
このホストで runner を開始します。SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET=$ENVIRONMENT_SECRET と、キャプチャフックをテスト runner にインストールするに従う capture hook および E2E_REPLY_DIR を使用してから、テストスクリプトを実行します。