Claude Media
Claude CodeをDockerで動かす手順 — 認証の永続化とヘッドレス実行

Claude CodeをDockerで動かす手順 — 認証の永続化とヘッドレス実行

Claude CodeをDockerコンテナで動かす手順。Dockerfileの最小構成から、認証をコンテナの再起動をまたいで維持する設定と、CI向けのヘッドレス実行、docker-composeの構成例を扱います。

要点

Claude CodeはDockerコンテナ単体でも普通に動きます。VS CodeのDevContainer仕様に乗る必要はなく、Dockerfileでイメージを作って docker run するだけです。躓きどころは実行そのものより認証で、コンテナを作り直すたびにログインし直す状態を避けるには、設定の永続化と非対話実行の両方を最初に設計しておく必要があります。コンテナ化されたMCPサーバーを呼びたいだけならDocker MCP Toolkitの接続手順のほうが早く済みます。

ここで扱うのは、動かし続けるための実務です。認証の永続化、ヘッドレス実行、docker-composeでの日常運用、プロキシ配下での到達先を順に見ます。capability制限やネットワーク遮断といった隔離設計は、後半で紹介する記事のほうが詳しく書いています。

くらべる

使い捨てか、使い続けるか

--rm

使い捨て(CI・単発実行)

ANTHROPIC_API_KEY を -e で渡すだけです。ボリュームは要りません。ログイン状態を残す必要がないので、ENTRYPOINTで claude を固定する構成とも相性がよくなります。

永続化

使い続ける(日常の開発)

~/.claude を名前付きボリュームに置き、CLAUDE_CONFIG_DIR を合わせます。ログイン、設定、セッション履歴がコンテナの作り直しをまたいで残ります。

最小構成のDockerfileを用意する

VS Codeの拡張機能を前提にしないなら、DevContainer機能を使わず素のDockerfileで十分です。このDockerfile自体をマルチステージビルド化やレイヤー順序の観点で見直したい場合はClaude CodeでDockerfileを最適化する手順を参考にしてください。

FROM ubuntu:24.04
 
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    ca-certificates \
    git \
    && rm -rf /var/lib/apt/lists/*
 
# バージョンを固定してインストールする(再現性を優先する場合)
RUN curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89
 
ENV PATH="/root/.local/bin:${PATH}"
 
WORKDIR /workspace
CMD ["bash"]

ネイティブインストーラーは latest と stable の2チャネルか、具体的なバージョン番号を受け付けます。stable は「およそ1週間前のバージョンで、重大な不具合のあるリリースを飛ばす」チャネルです。固定ではなく動き続ける目標なので、イメージを作り直した日によって中身が変わります。ビルドの再現性まで求めるなら、上のように bash -s 2.1.89 と番号を渡します。

ネイティブインストーラーはmacOS / Linux / WSLで ~/.local/bin/claude にシンボリックリンクを作ります。実体は ~/.local/share/claude/versions/ 配下に置かれます。

自動更新は別の話です。DISABLE_AUTOUPDATER を 1 にするとバックグラウンドの確認だけが止まり、claude update と claude install は動き続けます。手動の更新経路も含めてすべて塞ぎたいときは DISABLE_UPDATES を使います。設定が効いたかは claude doctor で確かめます。Auto-updates 行が disabled (set by env: DISABLE_AUTOUPDATER) になっていれば有効です。

CMD ["bash"] にしているのは意図的です。ENTRYPOINT でいきなり claude を起動する構成もよく見ますが、それだとコンテナに入って別のシェルコマンドを試したいときに毎回上書きが要ります。日常的に使い続けるコンテナなら bash で起動しておき、必要なときに claude や claude -p を手で叩くほうが小回りが利きます。CIのように「1コマンド実行して終了する」用途に絞るなら ENTRYPOINT 固定のほうが呼び出し側は書きやすくなります。

コンテナ内のclaudeを実機で確かめる

イメージを作る前に、インストールされるコマンドの形を手元で見ておくと、Dockerfileに書く内容が決めやすくなります。v2.1.287で、ログインもモデル呼び出しもせず確認できる範囲を実行した結果です。

claude --version
claude install --help
claude setup-token --help

claude --version は 2.1.287 (Claude Code) と表示されました。claude install --help の説明は次のとおりです。

Install Claude Code native build. Use [target] to specify version (stable,
latest, or specific version)
 
Options:
  --force     Force installation even if already installed

claude setup-token --help は「Set up a long-lived authentication token (requires Claude subscription)」と出ます。

オプションは -h だけで、トークンの保存先や有効期間を指定する引数はありません。Dockerfileの中でトークンを発行する設計はできず、発行は別の場所で済ませて環境変数で渡す形になります。

claude --help のサブコマンド一覧には doctor・install・update が並びます。バックグラウンドセッション用の attach・logs・stop もあります。--bg の説明は「セッションをバックグラウンドで開始し、すぐに戻る。claude attach / logs / stop / rm が受け取るIDを表示する」です。コンテナを -it なしで起動して後から入る運用でも使える可能性があります。ただし --bg は開始前にワークスペースの信頼を確認するので、TTYのないコンテナで初回フォルダがどう扱われるかは実機で確かめてください。

認証をコンテナの再起動をまたいで維持する

docker run --rm で使い捨てるコンテナなら、起動のたびに ANTHROPIC_API_KEY を環境変数で渡すだけで済みます。

docker run --rm -it \
  -e ANTHROPIC_API_KEY \
  -v "$(pwd):/workspace" \
  my-claude-image

一方、同じコンテナやイメージを使い続けたい、あるいはサブスクリプションのOAuthログインを毎回やり直したくない場合は、設定ディレクトリごと永続化します。Claude Codeの認証・設定・セッション履歴は ~/.claude 配下に保存され、CLAUDE_CONFIG_DIR 環境変数でこのディレクトリの場所を変えられます。Linuxのログイン情報は ~/.claude/.credentials.json(権限 0600)に置かれます。CLAUDE_CONFIG_DIR を設定すると、そのディレクトリの下に移ります。つまり、ボリュームに載せるべき実体はこのディレクトリ1つです。

手順

ログイン状態を残すまでの流れ

  1. 1

    ボリュームを作る

    docker volume create claude-config で名前付きボリュームを用意します。

  2. 2

    マウント先と環境変数を揃える

    -v claude-config:/root/.claude と -e CLAUDE_CONFIG_DIR=/root/.claude をセットで渡します。ボリュームだけだと、ログイン中のアカウント情報を持つ ~/.claude.json がボリュームの外に残り、作り直しで消えます。環境変数を合わせると、このファイルもボリュームの中に書かれます。

  3. 3

    初回だけログインする

    コンテナ内で claude を起動し、ブラウザで承認します。コールバックが届かないときは、表示されたコードを Paste code here if prompted に貼ります。

  4. 4

    作り直して確かめる

    コンテナを破棄して同じボリュームで起動し直し、ログインを求められなければ成功です。

docker volume create claude-config
 
docker run --rm -it \
  -v claude-config:/root/.claude \
  -e CLAUDE_CONFIG_DIR=/root/.claude \
  -v "$(pwd):/workspace" \
  my-claude-image \
  claude

コードの貼り付けが必要になるのは、ブラウザがClaude Codeのローカルのコールバックサーバーに届かないときです。コンテナのほか、WSL2やSSHセッションでも起きます。

仕事用と個人用のように2つのアカウントを使い分けたいときも、同じ仕組みが使えます。CLAUDE_CONFIG_DIR を指すディレクトリごとに設定、セッション履歴、ログインまたはAPIキーが別になるので、アカウントごとにボリュームを分けます。

ブラウザでログインできないCIパイプラインでサブスクリプションを使うなら、claude setup-token で1年間有効なOAuthトークンを発行します。発行したトークンは CLAUDE_CODE_OAUTH_TOKEN としてCIのシークレットに登録します。このトークンはモデルへのリクエスト専用で、Remote Controlとclaude.aiのコネクタには使えません。ローカルで設定したMCPサーバーは動きます。コマンドは /login と同じブラウザ承認を開き、トークンは承認後に端末へ表示されるだけで、どこにも保存されません。ローカル環境で一度だけ実行し、表示された値をコピーしてシークレットに入れます。

複数の認証情報があるときの優先順位

コンテナではAPIキー、OAuthトークン、ボリューム上のログインが同時に存在しがちです。複数あると、次の順で1つが選ばれます。

認証

認証情報の優先順位(上ほど優先)

  • 1〜2: クラウド / 中継

    Bedrock・Vertex・Foundryの切り替え変数と、ANTHROPIC_AUTH_TOKEN が最上位です。

  • 3〜4: APIキー系

    ANTHROPIC_API_KEY、次に apiKeyHelper の出力です。

  • 5: 長期トークン

    CLAUDE_CODE_OAUTH_TOKEN です。/login より上に位置します。

  • 6: プロファイル / フェデレーション

    ant CLIのプロファイルなどの認証情報です。Dockerの運用では通常使いません。

  • 7: サブスクリプションのログイン

    /login で得た資格情報で、Pro・Max・Team・Enterpriseの既定です。

実務で効くのは、ANTHROPIC_API_KEY が CLAUDE_CODE_OAUTH_TOKEN より上にある点です。composeファイルやイメージにAPIキーが残ったまま、シークレットにOAuthトークンを足しても、使われるのはAPIキーのほうです。対話モードではAPIキーを使ってよいかを一度尋ねられ、答えが記憶されます。非対話モード(-p)では、キーがあれば常にそのキーが使われます。期限切れや無効な組織のキーが残っていると認証エラーになり、unset ANTHROPIC_API_KEY で消すとサブスクリプションに戻ります。どちらが使われているかは /status で確かめられます。

CIやスクリプトからヘッドレスで実行する

対話プロンプトを避けたい自動化では -p フラグの非対話モード(print mode)を使います。標準入力やコマンド引数でクエリを渡すと、結果を出力して終了します。--bgのバックグラウンド実行と-p/--printを同時に指定すると競合エラーになるので、両方を使い分けたいコンテナ構成では--bgと--printの競合エラーの解決法で正しいコマンドの組み方を確認してください。

docker run --rm \
  -e ANTHROPIC_API_KEY \
  -v "$(pwd):/workspace" \
  -w /workspace \
  my-claude-image \
  claude -p "READMEのタイポを直して" --output-format json

--output-format は -p と組み合わせたときだけ効き、既定は text です。claude --help では json(単一の結果)に加えて stream-json が選べると確認できます。

起動を速くしたいだけのスクリプト用途では --bare フラグも検討します。claude --help の説明では、設定やプラグイン由来のhooks、LSP、プラグイン同期、auto-memory、キーチェーンの読み取り、CLAUDE.mdの自動検出などを飛ばします。あわせて環境変数 CLAUDE_CODE_SIMPLE=1 が立ちます。公式のヘッドレス解説では、Skills、カスタムコマンド、サブエージェント、MCPサーバーの自動検出も省かれ、Claudeが使えるのはBashとファイルの読み書きだけです。Skillsは自動では読み込まれませんが、/skill-name で明示すれば解決され、--add-dir で渡したディレクトリのSkillsは読み込まれます。必要な文脈はフラグで明示的に渡します。使えるのは --system-prompt、--append-system-prompt、--add-dir、--mcp-config、--settings、--agents、--plugin-dir です。

認証にも制約があります。--bare はOAuthトークンもキーチェーンも読みません。永続化した CLAUDE_CODE_OAUTH_TOKEN を使うつもりの構成では動きません。認証は ANTHROPIC_API_KEY か、--settings で渡す apiKeyHelper で行います。BedrockやVertexなどの外部プロバイダーは、それぞれの認証情報をそのまま使います。

-p はワークスペースの信頼確認ダイアログを出しません。--bare なしでは、プロジェクトの .claude/settings.json のhooksと .mcp.json のサーバーが、信頼していないフォルダでも動きます。見知らぬリポジトリをコンテナにマウントして -p で回す構成では、--bare が速度だけでなく実行範囲を絞る意味も持ちます。

docker-composeで日常的な開発用途に使う

一時的なCI実行ではなく、日々のコーディングをコンテナの中で完結させたい場合はdocker-composeでボリュームとワークスペースをまとめて定義すると管理が楽になります。

services:
  claude:
    build: .
    volumes:
      - claude-config:/root/.claude
      - .:/workspace
    environment:
      - CLAUDE_CONFIG_DIR=/root/.claude
      - ANTHROPIC_API_KEY
    working_dir: /workspace
    stdin_open: true
    tty: true
 
volumes:
  claude-config:

docker compose run claude claude のように起動すれば、対話セッションのままコンテナに入れます。上の例は ANTHROPIC_API_KEY を渡しているので、サブスクリプションのログインを使いたいなら、この行を消さないと前節の優先順位でAPIキーが勝ちます。ホスト側の .ssh や .aws を安易にマウントしない設計は、通常のDocker利用でも最低限の防御になります。

同じCIジョブを大量に、継続的に捌く必要が出てきたら、コンテナを都度起動する構成は見直しどきです。Claude Code self-hosted-runnerとはが扱うself-hosted環境のほうが、管理コストを抑えられます。runnerはあなたのインフラ上で常駐し、claude.aiから始めたクラウドセッションを受け取って実行します。この記事のようにDockerfileを自分で書いて都度起動する運用とは前提が異なります。

社内プロキシ配下のDockerホストから使う

CIサーバーや踏み台ホストがプロキシ経由でしか外部に出られない構成では、Claude Codeの起動前に標準的なプロキシ環境変数を設定します。読む順序は https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY で、最初に見つかったものが使われます。認証が必要なプロキシならURLに http://username:password@proxy.example.com:8080 の形で資格情報を埋め込みます。SOCKSプロキシには対応していません。

ENV HTTPS_PROXY=https://proxy.example.com:8080
ENV NO_PROXY="localhost,127.0.0.1,.internal.example.com"

環境変数はプロセス起動時に一度だけ読み込まれるため、実行中のコンテナでシェルの環境を書き換えても反映されません。値を変えたら再起動します。プロキシ配下でも到達させる宛先は主に3つあります。モデル推論と認証の api.anthropic.com、OAuthログインの claude.ai と platform.claude.com、ネイティブインストーラーと自動更新の downloads.claude.ai です。npmやbunでインストールする場合は registry.npmjs.org も許可リストに加えます。ファイアウォールで最小限に絞りたいイメージほど、これらのドメインを先に確定させてからDockerfileを書き始めるほうが手戻りが少なくなります。

セキュリティを強めたい場合の分岐

ここまでの構成は「動かし続けること」を優先した設計で、--dangerously-skip-permissions を使う自動化やCIの隔離要件までは踏み込んでいません。ホストの認証情報から物理的に隔離したい、Linux capabilityを絞りたい、ネットワークを遮断したい。こうした要件にはDevContainer / Docker sandbox完全実装が向いています。capability drop、read-onlyファイルシステム、段階的な認証情報の扱いまで手順化しています。認証情報をコンテナ内でマスキングする設定はClaude Codeの認証情報マスキングも参照してください。

コンテナ境界があるという理由だけで --dangerously-skip-permissions が安全になるわけではありません。ホストの認証情報をマウントしていないか、ネットワークが不要に開いていないかを確認してから使うフラグです。claude --help の説明も、権限確認をすべて飛ばすこのフラグを「外部との接続がないサンドボックス向け」として案内しています。VS CodeやCodespacesの統合が必要ならDevContainer仕様のほうが手間は省けますが、DevContainerの中身も結局はDockerイメージです。

よくあるつまずき

  • コンテナを作り直すたびにログインし直す: CLAUDE_CONFIG_DIR を名前付きボリュームと合わせて設定していないケースです。ボリュームと環境変数は必ずセットで指定します
  • サブスクリプションなのにAPIキー扱いになる: シェルのどこかに古い ANTHROPIC_API_KEY が残っていると、OAuthログインより優先されます。イメージやcomposeファイルの環境変数を洗い直します。認証まわりの切り分けはClaude Codeでよくあるエラー10選も参考になります
  • docker.sock をマウントしてサンドボックスの意味が消える: コンテナ内からdocker daemonに到達できると、実質的にホストへ抜けられます。特別な理由がない限りマウントしません
  • メモリ制限の小さいコンテナでインストールが Installation was killed で止まる: Dockerfile内でのインストール中にメモリ不足で強制終了しています。exit code 137の意味とスワップ追加の手順はInstallation was killedエラーの原因と対処にまとめています

まとめ

ログインが残らない、APIキー扱いになる、のどちらも原因はコンテナに渡した環境変数にあります。症状が出たら、まず /status で使われている認証を見てから、ボリュームとcomposeの environment を疑うと切り分けが早く済みます。

参照した一次ソース

この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。

  1. code.claude.com/docs/en/setup
  2. code.claude.com/docs/en/authentication
  3. code.claude.com/docs/en/devcontainer
  4. code.claude.com/docs/en/cli-reference
  5. code.claude.com/docs/en/headless
  6. code.claude.com/docs/en/network-config
この記事を共有:XはてブLinkedIn