Полное руководство по переменным окружения Claude Code: исправление ошибки совместимости AWS Bedrock всего одной настройкой

Примечание автора: Подробный разбор всех 60+ переменных окружения Claude Code, их ролей и способов настройки. Особое внимание уделено CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS для решения ошибки заголовка anthropic-beta на сторонних платформах.

При использовании Claude Code для подключения к AWS Bedrock, Google Vertex AI или другим сторонним шлюзам LLM вы, скорее всего, сталкивались с ошибкой: "Unexpected value(s) for the anthropic-beta header". Корень проблемы в том, что Claude Code по умолчанию отправляет специфические экспериментальные Beta-заголовки Anthropic API, которые сторонние платформы вроде AWS Bedrock просто не распознают.

Решение занимает всего одну строку: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

Однако переменных окружения в Claude Code гораздо больше — официальная документация насчитывает более 60 параметров, охватывающих конфигурацию аутентификации, выбор модели, настройку производительности, переключатели функций и многое другое. В этой статье мы систематизируем эти переменные, чтобы вы могли быстро находить и устранять любые проблемы с конфигурацией Claude Code.

Основная ценность: Прочитав эту статью, вы полностью разберетесь в системе переменных окружения Claude Code, сможете мгновенно решать проблемы совместимости с AWS Bedrock/Vertex AI и научитесь оптимизировать работу с Claude Code, экономя время и ресурсы.

Ключевые переменные окружения Claude Code

Более 60 переменных окружения Claude Code можно разделить на 6 основных категорий. Вот те, на которые стоит обратить внимание в первую очередь:

Два способа настройки переменных окружения Claude Code

Способ 1: Переменные Shell (временный эффект)

Установите переменную в терминале перед запуском Claude Code. Действует только для текущей сессии:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export ANTHROPIC_API_KEY="ваш-api-ключ"
claude

Способ 2: Конфигурация settings.json (постоянный эффект)

Настройте поле env в файле ~/.claude/settings.json. Настройки будут загружаться автоматически при каждом запуске:

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "ANTHROPIC_API_KEY": "ваш-api-ключ"
  }
}

🎯 Рекомендация: Для настроек, которые должны действовать постоянно (например, API-ключ или исправление совместимости платформ), лучше использовать settings.json, чтобы не вводить export каждый раз. Если ваш API-ключ получен через стороннюю платформу, например APIYI apiyi.com, настраивайте его здесь же.

Переменные окружения Claude Code: решение проблем совместимости с AWS Bedrock

Подробно о CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS

Это главный герой нашей статьи. Когда вы используете Claude Code через сторонние шлюзы, такие как AWS Bedrock, Google Vertex AI или LiteLLM, Claude Code автоматически добавляет в заголовки запроса метки экспериментальных функций (Beta) от Anthropic, например:

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

Эти Beta-метки — особенность прямого API от Anthropic. Сторонние платформы, такие как 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 перестанет отправлять эти экспериментальные заголовки, что обеспечит совместимость со всеми сторонними платформами.

Известные проблемы и временные решения

Согласно записям в 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: отключение кэширования промптов поможет избежать появления Beta-заголовков, связанных с prompt-caching-scope.

# Настройки для полной совместимости
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1

Полный справочник переменных окружения Claude Code

Категория 1: Аутентификация и конфигурация API

Это самые базовые и часто используемые переменные, которые управляют подключением Claude Code к API-сервисам:

🎯 Внимание пользователям сторонних платформ: При использовании сторонних API-сервисов, таких как APIYI (apiyi.com), необходимо одновременно установить ANTHROPIC_API_KEY и ANTHROPIC_BASE_URL. Claude Code будет отдавать приоритет API-ключу из переменных окружения, даже если вы вошли в аккаунт с подпиской Anthropic.

Категория 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

Минимальный пример: настройка Claude Code для работы со сторонними API-платформами

# Установите переменные окружения в терминале и запустите 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, можно использовать всю линейку моделей Claude напрямую через APIYI (apiyi.com). Достаточно установить всего две переменные — API-ключ и Base URL, и вам не придется разбираться с аутентификацией облачных платформ и вопросами совместимости.

Часто задаваемые вопросы

Итоги

Основные моменты по переменным окружения Claude Code:

1. Решение ошибок AWS Bedrock: установите CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, чтобы отключить экспериментальные Beta-заголовки. Эта настройка в одну строку исправляет ошибку «Unexpected value(s) for the anthropic-beta header».
2. 60+ переменных окружения в 6 категориях: аутентификация, выбор модели, совместимость с платформами, переключатели функций, управление контекстом и прочие настройки.
3. Два способа настройки: через Shell export (временный вариант) и в файле settings.json (постоянный вариант). Для стабильной работы рекомендуем прописывать настройки в settings.json.
4. Упрощенное решение через сторонние платформы: при использовании единых API-платформ, таких как APIYI (apiyi.com), достаточно настроить всего две переменные — ANTHROPIC_API_KEY и ANTHROPIC_BASE_URL. Это избавляет от необходимости возиться со сложной аутентификацией облачных гигантов и проблемами совместимости Beta-заголовков.

Рекомендуем попробовать подключить Claude Code через APIYI (apiyi.com). Платформа предоставляет бесплатные лимиты и единый интерфейс, что позволяет избежать множества «подводных камней» при настройке AWS Bedrock или Vertex AI.

📚 Справочные материалы

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).

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 — Управление Beta-заголовками Claude Code: фильтрация заголовков на уровне шлюза.

   • Ссылка: docs.litellm.ai/docs/tutorials/claude_code_beta_headers
   • Описание: тонкая настройка Beta-заголовков при использовании шлюза LiteLLM.

Автор: Техническая команда APIYI
Обсуждение: Делитесь своим опытом настройки Claude Code в комментариях. Больше обучающих материалов можно найти в центре документации APIYI на docs.apiyi.com.