Claude Code クラウドセッションの環境設計 ― ネットワーク・秘密情報・セットアップの決め方

Claude Code のクラウドセッションを試してみて、「最初の数分がパッケージのインストールで消える」「外部 API に届かない」「テストが動かない」と感じた方は多いと思います。こうした問題の多くは、モデルではなく「環境」の設計で解決できます。この記事では、クラウドセッションの環境を自分のリポジトリに合わせて作る方法を、Laravel 案件を例に説明します。内容は 2026 年 11 月時点の公式ドキュメントと、実際のクラウドセッション上での確認にもとづいています。

クラウドセッションの仕組みそのものや、依頼する側から見た注意点は「Claude Code のクラウドセッションとは ― 制作会社に任せる前に確認したい 7 つのこと」にまとめています。

クラウド環境の 4 つの要素

クラウドセッションは、毎回新しい仮想マシン（Ubuntu 24.04、x86_64）で始まります。リポジトリは GitHub から新しく複製され、前回のセッションでインストールしたものは残っていません。そこで、「どんな仮想マシンで始めるか」を保存しておくのが「クラウド環境」です。claude.ai/code の環境の編集画面で、次の 4 つを決めます。

最初から入っている道具も把握しておきましょう。公式ドキュメントによれば、PHP 8.3 と Composer、Node.js 20〜22、Python、Ruby、Java、Go、Rust、Docker、PostgreSQL 16、Redis 7.0 などが入っています。仮想マシンの中で check-tools コマンドを実行すると一覧が出ます。筆者が確かめたところ、PHP は 8.3.6 で、pdo_sqlite・pdo_pgsql・intl・gd・mbstring・redis の拡張が有効でした。一方で bcmath は入っていませんでした。MySQL は一覧にありません。

つまり、Laravel 案件なら、多くの場合は少し足すだけで動きます。足りないものを見極めて、どの要素で補うかを決めるのが環境の設計です。

ネットワーク：どこまで届かせるか

ネットワークアクセスは 4 段階から選びます。

標準の「信頼済み」には、npm、Packagist、PyPI、Docker Hub、GitHub などが含まれます。Composer の composer install は、この段階でそのまま通ります。

案件で使う外部 API（決済、地図、メール配信など）を呼ぶテストがあるなら、「カスタム」にして必要なドメインだけを足します。「Allowed domains」の欄に 1 行 1 ドメインで書き、「Also include default list of common package managers」にチェックを入れると、標準の一覧も残せます。

api.stripe.com
api.sendgrid.com
*.example-cms.jp

先頭の *. は、すべてのサブドメインに一致します。広く許可したくなりますが、許可した先はプロンプトインジェクション（ページやファイルに仕込まれた指示で AI をだます攻撃）を受けたときのデータの出口にもなります。「すべて」を常用せず、案件ごとに必要な先だけを足すのが基本です。

秘密情報：環境変数とネットワークシークレット

外部 API のキーを渡したいとき、まず思いつくのは環境変数です。しかし、公式ドキュメントでは、環境変数の値はその環境を使える人なら誰でも読めるとされています。Claude もコマンドで読めるので、ログや会話に出てしまう可能性もあります。

キーには「ネットワークシークレット」を使います。環境の編集画面の「Network secrets」で「Add secret」を選び、許可するホスト（例：api.stripe.com）とヘッダーを入れます。標準では Authorization ヘッダーに Bearer を付けて送る形になっていて、X-Api-Key のようにキーだけを送る API なら、ヘッダー名を変えて Prefix を消します。

仕組みは、仮想マシンから出た通信にプロキシがキーを付け足すというものです。仮想マシンの中にキーの値は存在せず、保存したあとは人も値を見られません。変えたいときは削除して登録し直します。

使い分けは次のとおりです。

セットアップ：スクリプトとフックの使い分け

仮想マシンに道具や依存を入れる方法は 2 つあります。

おすすめは、OS に近いものはセットアップスクリプト、リポジトリの依存は SessionStart フックに分けることです。セットアップスクリプトはキャッシュされるので、重いインストールを毎回くり返さずに済みます。一方、composer.lock が変わるたびに追従すべき依存は、リポジトリと一緒にバージョン管理されるフックのほうが管理しやすくなります。

セットアップスクリプトの例

Laravel 案件で金額計算に bcmath を使うなら、次のように書きます。筆者は、実際のクラウドセッション上で apt-get update のあとに php8.3-bcmath が入れられることを確かめました。

#!/bin/bash
apt-get update
apt-get install -y php8.3-bcmath

公式ドキュメントが挙げる注意点は 3 つです。

• 0 で終わらせる：0 以外で終わると、セッションが始まらないか、入るはずのものが入らないまま始まります。なくてもよいコマンドには || true を付けます
• 5 分以内に終わらせる：およそ 5 分を超えるとキャッシュが作られず、毎回実行されます。独立したインストールは & と wait で並べます
• 環境変数はまだ使えない：スクリプトは環境変数が設定される前に動きます。必要な値はスクリプトの中に書きます

キャッシュは、スクリプトかネットワークの許可先を変えたとき、または約 7 日ごとに作り直されます。

SessionStart フックの例

依存のインストールはフックに書きます。公式の例にならい、CLAUDE_CODE_REMOTE が true のときだけ動くようにすると、ローカルの作業を邪魔しません。この変数はクラウドの仮想マシンでは true で、ローカルでは設定されていません。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/cloud_setup.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
  exit 0
fi

cd "$CLAUDE_PROJECT_DIR" || exit 1
composer install --no-interaction --prefer-dist
if [ ! -f .env ]; then
  cp .env.example .env
  php artisan key:generate --force
fi
exit 0

テスト用のデータベースは、MySQL がないので SQLite にするのが手軽です。Laravel の標準の phpunit.xml は、テスト時に SQLite のメモリ上のデータベースを使う設定になっています。PostgreSQL を使う案件なら、フックの中で service postgresql start を実行します（入ってはいますが、起動はしていません）。

フックは毎回動くので、重い処理は避けます。標準では 600 秒で打ち切られます。

つまずきやすい点

ローカルの未 push のコミットは届かない。 claude --cloud で始めると、手元の作業ツリーではなく GitHub 上のブランチが複製されます。先に push しておきます。

gh pr や gh issue が失敗する。 GitHub 用のプロキシは GraphQL を拒否するため、GraphQL を使うこれらのコマンドは通りません。gh api repos/{owner}/{repo}/pulls のように REST の API を使います。

手元の個人設定は引き継がれない。 ~/.claude/CLAUDE.md、ユーザー単位のスキルや MCP サーバーは、クラウドには持ち込まれません。リポジトリの CLAUDE.md や .claude/settings.json、.claude/skills は使われます。チームで共有したい設定は、リポジトリに入れておきます。

本番ブランチはプロキシでは守られない。 プロキシはブランチの削除やタグの push を拒否しますが、どのブランチに push できるかは制限しません。main を守るのは GitHub のブランチ保護ルールの役目です。

環境変数を変えても、動いているセッションには届かない。 環境変数はセッションの作成時と仮想マシンの再起動時に読まれます。ネットワークの設定は約 1 分で反映されるので、混同しないようにします。

ディスクとメモリには上限がある。 公式の目安は 4 vCPU・16 GB のメモリ・30 GB のディスクです。大きなビルドの成果物や Docker イメージをため込まないようにします。

まとめ

• クラウド環境は、ネットワーク・環境変数・ネットワークシークレット・セットアップスクリプトの 4 つで決まります。変更の反映のタイミングがそれぞれ違う点に注意します
• ネットワークは標準の「信頼済み」から始め、必要な外部 API だけをカスタムで足します。API キーは環境変数ではなくネットワークシークレットに置きます
• OS に近いものはキャッシュの効くセットアップスクリプト、リポジトリの依存は CLAUDE_CODE_REMOTE で絞った SessionStart フックに分けると、速さと管理のしやすさを両立できます

チームでのルールや権限の決め方は「AI コーディングエージェントを受託開発に組み込む ― AGENTS.md・権限・検証の設計」もあわせてご覧ください。

参考リンク

• Cloud environments（Claude Code 公式ドキュメント）
• Use Claude Code in the cloud（Claude Code 公式ドキュメント）
• Hooks reference（Claude Code 公式ドキュメント）
• Security（Claude Code 公式ドキュメント）