Claude Code 環境変数完全ガイド：AWS Bedrock 互換性エラーをたった1つの設定で解決

著者注：Claude Code の全 60 以上の環境変数の役割と設定方法を詳しく解説します。特に、サードパーティプラットフォームでの anthropic-beta ヘッダーのエラーを解決する CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS について重点的に取り上げます。

Claude Code を AWS Bedrock、Google Vertex AI、またはその他のサードパーティ LLM ゲートウェイに接続して使用する際、次のようなエラーに遭遇することがよくあります："Unexpected value(s) for the anthropic-beta header"。この問題の根本的な原因は、Claude Code がデフォルトで Anthropic API 特有の実験的な Beta ヘッダーを送信することにあります。AWS Bedrock などのサードパーティプラットフォームは、これらのヘッダーを認識できません。

解決策は、設定を一行追加するだけです：CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。

しかし、Claude Code の環境変数はこれだけではありません。公式ドキュメントには 60 以上の環境変数がリストされており、認証設定、モデル選択、パフォーマンス調整、機能のオン/オフなど、あらゆる側面をカバーしています。この記事では、これらの環境変数を体系的に整理し、Claude Code のさまざまな設定問題を迅速に特定して解決できるようサポートします。

この記事の価値: 読み終える頃には、Claude Code の環境変数体系を完全に把握し、AWS Bedrock/Vertex AI との互換性問題を即座に解決できるようになります。また、環境変数を通じて Claude Code の使用体験とコストを最適化する方法も学べます。

Claude Code 環境変数のコアポイント

Claude Code の 60 以上の環境変数は 6 つのカテゴリに分類できます。特に注目すべき主要な変数は以下の通りです：

Claude Code 環境変数の 2 つの設定方法

方法 1：シェル環境変数（一時的）

ターミナルで設定してから Claude Code を起動します。現在のセッションのみ有効です：

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export ANTHROPIC_API_KEY="your-api-key"
claude

方法 2：settings.json 設定（永続的）

~/.claude/settings.json の env フィールドに設定します。起動するたびに自動的に読み込まれます：

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "ANTHROPIC_API_KEY": "your-api-key"
  }
}

🎯 推奨される方法: APIキーやプラットフォーム互換性の修正など、長期的に有効にしたい設定には settings.json を使用することをお勧めします。毎回手動で export する手間が省けます。APIキーを APIYI (apiyi.com) などのサードパーティプラットフォームから取得している場合も、ここで設定すれば OK です。

Claude Code 環境変数の重点解説：AWS Bedrock 互換性問題の解決

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 詳解

この記事の核心となる変数です。AWS Bedrock、Google Vertex AI、LiteLLM などのサードパーティ製ゲートウェイを介して Claude Code を使用する場合、Claude Code はリクエストヘッダーに Anthropic の実験的な Beta 識別子を自動的に追加します。例：

anthropic-beta: prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20

これらの Beta 識別子は Anthropic の直接接続 API 専用の機能であるため、AWS Bedrock などのサードパーティプラットフォームでは認識できず、以下のエラーが返されます。

Error: Unexpected value(s) for the anthropic-beta header

解決方法：

# 方法1：Shell コマンド
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# 方法2：settings.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

この値を 1 に設定すると、Claude Code はこれらの実験的な Beta ヘッダーを送信しなくなり、すべてのサードパーティプラットフォームとの互換性が確保されます。

既知の問題と一時的な解決策

GitHub Issues の記録によると、一部の Claude Code バージョン（2.1.18 以降）では、この環境変数が完全に機能しない問題が報告されています。CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 を設定していても、新しく追加された一部の Beta ヘッダー（advanced-tool-use-2025-11-20 など）が依然として送信される場合があります。

引き続き問題が発生する場合は、以下の追加対策を試してください：

• Claude Code のバージョンをダウングレードする: 2.1.68 など、動作が安定していることが確認されているバージョンに戻す。
• LiteLLM ゲートウェイを使用する: LiteLLM は anthropic_beta_headers_config.json 設定ファイルを提供しており、どの Beta ヘッダーを転送するかを細かく制御できます。
• 同時に DISABLE_PROMPT_CACHING を設定する: プロンプトキャッシュを無効にすることで、prompt-caching-scope 関連の Beta ヘッダーの送信を回避できます。

# 包括的な互換性設定
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1

Claude Code 環境変数 完全分類クイックリファレンス

第1カテゴリ：認証と API 設定

これは最も基本的かつ頻繁に使用される環境変数で、Claude Code が API サービスにどのように接続するかを制御します。

🎯 サードパーティプラットフォーム利用者の注意: APIYI apiyi.com などのサードパーティ API プラットフォームを使用する場合は、ANTHROPIC_API_KEY と ANTHROPIC_BASE_URL の両方を設定する必要があります。Claude Code は、Anthropic のサブスクリプションアカウントにログインしていても、環境変数の API キーを優先的に使用します。

第2カテゴリ：モデルの選択と設定

Claude Code が使用するモデルと、モデルの動作パラメータを制御します。

第3カテゴリ：プラットフォーム互換性とゲートウェイ設定

これらの変数は、Claude Code と異なるクラウドプラットフォームや大規模言語モデル（LLM）ゲートウェイとの互換性問題を解決するために特化しています。

第4カテゴリ：機能スイッチ

DISABLE_ または CLAUDE_CODE_DISABLE_ プレフィックスを持つ変数を使用して、特定の機能をオフにします。

第5カテゴリ：コンテキストとパフォーマンス管理

Claude Code がコンテキストウィンドウとリソース使用をどのように管理するかを制御します。

🎯 パフォーマンス最適化のアドバイス: 長い会話の中で Claude Code が頻繁にコンテキストを圧縮していると感じる場合は、CLAUDE_AUTOCOMPACT_PCT_OVERRIDE をより低い値（例：50）に設定することで、圧縮を早めに実行させ、情報の損失を減らすことができます。APIYI apiyi.com を介して呼び出す場合も、これらの環境変数設定が同様にサポートされます。

Claude Code 環境変数のクイックスタートガイド

シンプルな例：サードパーティAPIプラットフォームに接続するための Claude Code 設定

# ターミナルで環境変数を設定してから Claude Code を起動します
export ANTHROPIC_API_KEY="sk-your-api-key"
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-api-key",
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com/v1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80",
    "DISABLE_TELEMETRY": "1"
  },
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": []
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1",
    "ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION": "us-east-1"
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_BASE_URL": "https://my-resource.services.ai.azure.com/anthropic",
    "ANTHROPIC_FOUNDRY_API_KEY": "your-foundry-key",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

おすすめ: AWS Bedrock や Azure の複雑な設定に煩わされたくない場合は、APIYI (apiyi.com) を通じて Claude 全シリーズのモデルを直接利用できます。APIキーと Base URL の2つの変数を設定するだけで、クラウドプラットフォームの認証や互換性の問題を処理する必要はありません。

よくある質問

まとめ

Claude Code 環境変数の主なポイント：

1. AWS Bedrock のエラー解決: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 を設定して試験的な Beta ヘッダーを無効化することで、「Unexpected value(s) for the anthropic-beta header」エラーを一行の設定で解決できます。
2. 60以上の環境変数を6つのカテゴリに分類: 認証設定、モデル選択、プラットフォーム互換性、機能スイッチ、コンテキスト管理、その他の設定。
3. 2つの設定方法: Shell export（一時的）と settings.json（永続的）。永続的な設定には settings.json への記述を推奨します。
4. サードパーティプラットフォームによる簡素化: APIYI (apiyi.com) などの統合 API プラットフォームを利用すれば、ANTHROPIC_API_KEY と ANTHROPIC_BASE_URL の2つの変数を設定するだけで済み、複雑なクラウドプラットフォームの認証や Beta ヘッダーの互換性問題を回避できます。

AWS Bedrock や Vertex AI の設定における様々な互換性の罠を避けるため、APIYI (apiyi.com) を通じて Claude Code を素早く体験することをお勧めします。プラットフォームは無料枠と統一されたインターフェースを提供しています。

📚 参考文献

1. Claude Code 公式ドキュメント – 環境変数: 環境変数の完全なリストと説明

   • リンク: code.claude.com/docs/en/env-vars
   • 説明: 60以上の全環境変数に関する公式のリファレンス

2. Claude Code 公式ドキュメント – 設定: 設定のスコープと settings.json の仕様

   • リンク: code.claude.com/docs/en/settings
   • 説明: Managed/User/Project/Local の4段階の設定体系の理解

3. Claude Code 公式ドキュメント – Amazon Bedrock: AWS Bedrock 統合ガイド

   • リンク: code.claude.com/docs/en/amazon-bedrock
   • 説明: Bedrock 専用の設定と一般的な問題の解決策

4. GitHub Issue #22893 – DISABLE_EXPERIMENTAL_BETAS が完全に機能しない: コミュニティのバグ報告

   • リンク: github.com/anthropics/claude-code/issues/22893
   • 説明: この環境変数の既知の制限と一時的な回避策の確認

5. LiteLLM – Claude Code Beta Headers 管理: ゲートウェイ層での Beta ヘッダーフィルタリング案

   • リンク: docs.litellm.ai/docs/tutorials/claude_code_beta_headers
   • 説明: LiteLLM ゲートウェイを使用する際のきめ細かな Beta ヘッダー制御

著者: APIYI 技術チーム
技術交流: コメント欄で Claude Code の設定経験についてぜひ議論しましょう。さらなるチュートリアルは APIYI docs.apiyi.com ドキュメントセンターをご覧ください。