Claude Code で 1 つの設定を変えるために、公式ドキュメントを 3 つ横断して、GitHub の Issue を 2 件読み、結局うまく動かない——そんな経験はありませんか。Claude Code の環境変数は、リリースごとに静かに増え続けていて、ドキュメントに載る前にサンプルリポジトリにだけ書かれていることもあります。
環境変数の読み込み順と優先順位
Claude Code の設定は、CLI オプション・環境変数・settings.json（user / project / managed）が重なり合う構造になっています。同じ項目を 2 箇所で設定したときに、どちらが勝つのかを把握しておくと、原因不明のトラブルが激減します。
優先順位は基本的に次の通りです（上が強い）。
- CLI 引数（
--modelなど、その場で明示的に渡したもの） - プロジェクト内の
.claude/settings.json - ユーザーのホーム配下
~/.claude/settings.json - Managed settings（
/etc/claude/managed_settings.json等、組織配布） - 環境変数
- ビルトインのデフォルト値
つまり環境変数は「ベースラインとして全セッションに効かせたい値」を入れる場所です。プロジェクトごとに変えたい値は .claude/settings.json に書いた方が事故が少ないです。私は API キーや Base URL のような「全体共通の接続先」は環境変数、モデル選択やツール許可のような「プロジェクトごとに違って当然の値」は settings.json と使い分けています。
一方で、CI/CD のジョブ内では .claude/settings.json をリポジトリにコミットしていないケースも多いので、環境変数ですべて上書きしてしまう運用もアリです。どちらが正解かではなく、チームの事情に合わせて境界を決めるのが大事です。
API 接続系の環境変数
まず押さえたいのは、Claude Code がどの API エンドポイントに、どのキーで、どう認証するかを決める変数たちです。ここが狂うと他の設定は一切意味を持ちません。
# Anthropic API 直接利用（最も一般的）
export ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"
# API ベース URL を上書き（プロキシ・独自ゲートウェイ経由で使う場合）
export ANTHROPIC_BASE_URL="https://api.anthropic.com"
# Amazon Bedrock 経由で Claude を使う場合
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION="us-east-1"
# Google Vertex AI 経由で Claude を使う場合
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION="us-east5"
export ANTHROPIC_VERTEX_PROJECT_ID="your-gcp-project"CLAUDE_CODE_USE_BEDROCK と CLAUDE_CODE_USE_VERTEX は排他です。両方を 1 に設定すると、実装内部では「先に評価される方（通常は Bedrock）」が優先されますが、これは明示された挙動ではないので、必ずどちらか片方だけを有効化してください。
また、個人開発では ANTHROPIC_API_KEY を使うのに対して、チーム運用では SSO 連携された認証の方が安全です。claude login で一度ログインしておけば、環境変数を削除しても Claude Code は認証情報を保持しますので、チーム配布の PC では「API キーを .bashrc に書かない」ことをおすすめします。
API キーの保存場所を安全に保つ
API キーを .bashrc に平文で書くのは、最も避けたい運用です。Windows では資格情報マネージャ、macOS では Keychain、Linux では pass や gnome-keyring を使い、シェル起動時に復号する方式が安全です。以下は macOS で Keychain を使う例です。
# 初回登録
security add-generic-password -a "$USER" -s "anthropic-api-key" -w "YOUR_ANTHROPIC_API_KEY"
# .zshrc に追加（毎セッションで取り出す）
export ANTHROPIC_API_KEY=$(security find-generic-password -a "$USER" -s "anthropic-api-key" -w 2>/dev/null)この方式にしておくと、端末を誰かに貸したときや画面共有したときに、env コマンドで API キーが丸見えになるリスクが下がります。
モデル・推論パラメータ系
Claude Code はセッションごとにモデルを切り替えられますが、環境変数でベースラインを指定しておくと、CLI から --model を付け忘れても想定外のモデルで動くことを防げます。
# 常用モデル
export ANTHROPIC_MODEL="claude-sonnet-4-6"
# 小回りの利く軽量モデル（サブタスク・計画立案用）
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5-20251001"
# 最大出力トークン数
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192
# 温度（0〜1）。コード生成用途では低めが安定する
export ANTHROPIC_TEMPERATURE=0.2ANTHROPIC_SMALL_FAST_MODEL は、Claude Code が内部的に「長文ではない補助タスク」を処理するときに呼ぶモデルです。ここを Haiku 系にしておくと、全体のコスト効率が大きく改善します。開発現場では、メインモデルを Sonnet 4.6、補助モデルを Haiku 4.5 に設定する組み合わせを私は好んで使っています。
温度の実務感覚
ANTHROPIC_TEMPERATURE は、値が高いほど出力に揺らぎが出ます。コード生成では 0.0〜0.3、自然文章（ドキュメント・コミットメッセージ）では 0.5〜0.7 が目安です。プロジェクトごとに温度を変えたいなら .claude/settings.json の temperature フィールドで上書きする方がスマートです。
ツール有効化系（PowerShell ツールほか）
Windows 開発者にとって重要なのが CLAUDE_CODE_USE_POWERSHELL_TOOL=1 です。これを有効にすると、Claude Code は Bash ツールの代わりに Powershell ツールを優先的に使うようになります。
# Windows: PowerShell ツールを有効化
export CLAUDE_CODE_USE_POWERSHELL_TOOL=1
# 追加でツールの最大同時実行数を制限（MCP 経由での並列ツール呼び出し対策）
export CLAUDE_CODE_MAX_PARALLEL_TOOL_CALLS=3この設定、ドキュメントでは「Windows ユーザーは有効化推奨」とだけ書かれていますが、実際に運用していると次のような細かい落とし穴があります。
- WSL と競合する: WSL 上で Claude Code を起動している場合、この変数が有効だと「Bash を持っているのに PowerShell を叩こうとして失敗」します。WSL 側では明示的に
CLAUDE_CODE_USE_POWERSHELL_TOOL=0を入れて無効化する必要があります。 - パイプの挙動が違う: Bash ツールで渡される
|と PowerShell のパイプラインは挙動が違います。テキストストリームではなくオブジェクトが流れるため、grep相当はSelect-Stringに、awk相当はForEach-Objectに脳内変換してください。 - 文字エンコードが UTF-8 にならない: 日本語環境では Shift-JIS（CP932）が返ってくることがあります。
$PSDefaultParameterValues['*:Encoding'] = 'utf8'とchcp 65001を PowerShell プロファイル（$PROFILE）に書いておくと安定します。
私は Windows での運用を数ヶ月続けて、3 番目の文字エンコードの問題に一番苦しみました。ファイル一覧を取得するタスクで、日本語のフォルダ名が文字化けしてしまい、Claude Code が「指定されたパスが存在しない」とハルシネーションする現象が起きていたためです。PowerShell プロファイルを UTF-8 統一にしたら、ピタッと収まりました。
ログ・デバッグ・テレメトリ系
本格的に運用し始めると、ログを取りたくなる場面が増えます。Claude Code は標準で控えめな出力ですが、環境変数でデバッグモードに切り替えられます。
# 詳細ログを出す（エラー調査用）
export CLAUDE_CODE_DEBUG=1
# プロンプトの全文をダンプ（機密情報に注意）
export CLAUDE_CODE_DEBUG_PROMPT=1
# API リクエスト・レスポンスのロー JSON を出力
export CLAUDE_CODE_DEBUG_API=1
# ログ出力先を変更（デフォルトは stderr）
export CLAUDE_CODE_LOG_FILE="$HOME/.claude/debug.log"CLAUDE_CODE_DEBUG_PROMPT=1 は強力ですが、あなたがコードベースにある全ソースコードをプロンプトに入れていた場合、それが丸ごとログファイルに書き出されます。本番環境や共有マシンでは絶対に使わないでください。ローカル開発でバグ調査のときだけ有効化して、調査が終わったら .bashrc から削除するのが安全です。
テレメトリについても、プライバシー重視のチームでは下記を設定しておくとよいです。
# 匿名利用統計を送らない
export CLAUDE_CODE_TELEMETRY=0
# クラッシュレポートの自動送信を無効化
export CLAUDE_CODE_CRASH_REPORTING=0タイムアウト・リトライ・パフォーマンス系
長時間実行されるエージェントタスクで重要なのが、タイムアウトとリトライの設定です。デフォルトのままだと、ネットワーク不調で途中停止したときに「何分待てば諦めてくれるのか」が分からず、ストレスが溜まります。
# HTTP リクエストのタイムアウト（ミリ秒）
export CLAUDE_CODE_REQUEST_TIMEOUT=300000 # 5 分
# ツール実行の全体タイムアウト（ミリ秒）
export CLAUDE_CODE_TOOL_TIMEOUT=600000 # 10 分
# 自動リトライの最大回数
export CLAUDE_CODE_MAX_RETRIES=3
# リトライ間隔の基準値（ミリ秒）。指数バックオフで伸びる
export CLAUDE_CODE_RETRY_BASE_MS=1000大規模なコードベースで使う場合、CLAUDE_CODE_REQUEST_TIMEOUT はデフォルトより長めに取ることをおすすめします。Sonnet 4.6 でも、数万行の差分をまとめて読ませると、応答に 2 分以上かかることがあります。
一方、CI/CD で使う場合は逆に短くして、ハングしたら即座に失敗させる方針が良いです。ジョブが 30 分もハングしていると、CI 枠を圧迫してしまうためです。
セキュリティ・プライバシー系
組織でセルフホスト運用するときや、機密情報を扱うリポジトリでは、次の設定が効いてきます。
# プロジェクト外のファイルへのアクセスを禁止
export CLAUDE_CODE_PROJECT_SCOPE_STRICT=1
# シェルコマンド実行時にサンドボックス（macOS sandbox-exec / Linux bwrap）を強制
export CLAUDE_CODE_SANDBOX=1
# 外部 URL の fetch を禁止（WebFetch ツールの完全無効化）
export CLAUDE_CODE_DISABLE_WEB_FETCH=1
# ツール実行前に必ず人間の確認を求める
export CLAUDE_CODE_REQUIRE_APPROVAL=allCLAUDE_CODE_REQUIRE_APPROVAL は個人の好みで edit（ファイル編集のみ確認）・bash（シェルコマンドのみ）・all（全ツール）・none（確認なし）から選べます。私は普段 edit で運用しつつ、触り慣れていないリポジトリを扱うときだけ all に切り替えています。
環境別の推奨テンプレート
ここまでの内容を踏まえて、3 つの環境別に「そのままコピーして使える」テンプレートを用意しました。
テンプレート 1: 個人開発向け
# ~/.bashrc または ~/.zshrc に追加
export ANTHROPIC_API_KEY=$(security find-generic-password -a "$USER" -s "anthropic-api-key" -w 2>/dev/null)
export ANTHROPIC_MODEL="claude-sonnet-4-6"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5-20251001"
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192
export ANTHROPIC_TEMPERATURE=0.2
export CLAUDE_CODE_REQUEST_TIMEOUT=300000
export CLAUDE_CODE_REQUIRE_APPROVAL=editポイントは、モデルの常用設定と、編集系ツールのみ確認を求める安全運用です。API キーは Keychain 経由にして平文ではディスクに残さないようにしています。
テンプレート 2: 社内チーム向け（共通プロファイル）
# /etc/profile.d/claude-code.sh として配布
export ANTHROPIC_BASE_URL="https://llm-gateway.your-company.internal"
export CLAUDE_CODE_USE_BEDROCK=0
export CLAUDE_CODE_USE_VERTEX=0
export CLAUDE_CODE_TELEMETRY=0
export CLAUDE_CODE_CRASH_REPORTING=0
export CLAUDE_CODE_PROJECT_SCOPE_STRICT=1
export CLAUDE_CODE_REQUIRE_APPROVAL=edit社内ゲートウェイ経由で LLM を集中管理している場合、ANTHROPIC_BASE_URL を社内エンドポイントに向ける運用が効きます。こうすることで、誰がどんなプロンプトを送ったかを可観測にしつつ、Anthropic への直接の API 呼び出しは遮断できます。
テンプレート 3: CI/CD 向け
# GitHub Actions の例
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
ANTHROPIC_MODEL: claude-haiku-4-5-20251001
CLAUDE_CODE_MAX_OUTPUT_TOKENS: 4096
CLAUDE_CODE_REQUEST_TIMEOUT: 60000
CLAUDE_CODE_TOOL_TIMEOUT: 120000
CLAUDE_CODE_MAX_RETRIES: 2
CLAUDE_CODE_REQUIRE_APPROVAL: none
CLAUDE_CODE_TELEMETRY: 0CI ではコストと速度が正義ですので、Haiku 系の小回りモデルを指定し、タイムアウトを短め、リトライを控えめに設定します。確認プロンプトは none にして、人間の介入なしで完走できるようにします。
トラブルシューティング — よく詰まるパターン
実際に運用していて遭遇する「なぜか動かない」の原因は、意外と環境変数の衝突であることが多いです。主なパターンを 3 つ挙げます。
パターン 1: 複数のシェルプロファイルで上書きし合っている
macOS で .bash_profile・.bashrc・.zshrc の 3 つに少しずつ設定が残っていると、ターミナルアプリ（iTerm2 / ターミナル.app）と VS Code の統合ターミナルで違う値が使われることがあります。デバッグは echo $ANTHROPIC_MODEL のような単純なコマンドで、Claude Code を起動している環境から確認してください。
パターン 2: VS Code の Claude Code 拡張が別の設定を見ている
VS Code 拡張版の Claude Code は、シェルの環境変数を継承する場合としない場合があります（OS や起動方法で変わる）。確実にしたいときは、拡張機能の設定画面から明示的に ANTHROPIC_API_KEY を入れる方が安定します。
パターン 3: Docker コンテナ内で環境変数が届いていない
claude を Docker 内で使うとき、コンテナ外のシェル環境変数は自動では継承されません。docker run -e ANTHROPIC_API_KEY や、docker compose の environment セクションで明示的に渡してください。
いずれのパターンも、一度ハマると数時間溶かす典型例です。疑う順番は「プロセス継承」「設定ファイルの重複」「シェルプロファイルの分岐」の順で見ていくと、最短で辿り着けます。
次にやること
環境変数を一通り整えたら、次は .claude/settings.json でプロジェクト単位の上書きを整理する段階です。Claude Code の設定体系は 3 層（環境変数・ユーザー設定・プロジェクト設定）で成り立っていますので、本記事でベースラインを作ったら、あとはプロジェクトごとに少量の上書きを重ねる設計が最も運用しやすくなります。settings.json の書き方は Claude Code settings.json 完全ガイド で詳しく解説していますので、合わせて読んでみてください。