Zero to Agent

Русский

中文
English
Español
Français
हिन्दी
العربية
Português

Русский

中文
English
Español
Français
हिन्दी
العربية
Português

Переменные окружения: скрытые системные переключатели ​

📚 Навигация по серии: Предыдущая статья 41 Параллельные задачи научила вас распределять независимые задачи по изолированным копиям git worktree для параллельного запуска сессий Claude. Эта статья спускается на уровень ниже — мы разберем системные переключатели, управляющие авторизацией, сетевыми прокси, лимитами таймаутов и логированием. Все эти параметры настраиваются через переменные окружения. Они скрыты от глаз в меню настроек, но прописываются в вашем shell и конфигурационных файлах settings.json. Разберем их работу подробно.

Часто говорят, что переменные окружения — это «инструмент для профессионалов», но на самом деле такое отношение лишь усложняет работу новичкам.

Многие разработчики при каждом запуске сессии вручную вводят /model для выбора модели, перенастраивают прокси или меняют параметры лимитов, тратя время впустую, вместо того чтобы один раз прописать эти настройки в системе. Причина проста — «переменные окружения звучат слишком сложно, боюсь сломать настройки».

Но если оглянуться на предыдущие 41 статью — настройка API-ключа в статье 04, подключение сторонних моделей в статье 05, управление памятью в статье 19 и отключение телеметрии в статье 21 — все эти действия на системном уровне управляются одним механизмом: переменными окружения. Вы уже использовали их, просто они не были собраны в одном руководстве.

Переменные окружения — это не сложная теория, а набор переключателей по принципу «один раз настроил — и забыл». Разобравшись, какие переменные за что отвечают и как вернуть настройки назад при ошибке, вы сможете легко управлять поведением программы.

Прочитав эту статью, вы получите:

  • Понимание того, какими процессами в Claude Code управляют переменные окружения и почему их стоит настроить.
  • Три способа объявления переменных (временный экспорт в shell, запись в автозагрузку профиля терминала, использование поля env в settings.json) с разбором их различий.
  • Правила распределения переменных по четырем типам файлов settings.json (какие файлы добавляются в git, а какие предназначены только для локального использования) в продолжение темы статьи 31.
  • Справочник наиболее важных переменных: авторизация, таймауты, приватность, пути к файлам кэша с примерами значений.
  • Правила приоритета: что произойдет при одновременной настройке параметра в переменной окружения, файле конфигурации и команде чата.
  • Практическое упражнение: объявим переменную в системе и проверим её считывание программой Claude Code.

01 Что настраивают переменные окружения в Claude Code ​

Переменные окружения представляют собой пары «ключ-значение» в вашей операционной системе, считываемые Claude Code при запуске для настройки авторизации, адресов серверов, лимитов ожидания и параметров приватности.

Большинство настроек в чате (команда /model для смены модели, /config для изменения тем оформления, /mcp для авторизации инструментов) действуют только в рамках активной сессии. Но есть системные правила, которые вы хотите зафиксировать раз и навсегда: «всегда отправлять запросы через рабочий прокси-сервер», «увеличить время ожидания ответов сети до 20 минут» или «никогда не отправлять данные телеметрии разработчикам». Такие глобальные параметры настраиваются через переменные окружения.

Официальное определение гласит:

Переменные окружения позволяют управлять поведением Claude Code: от выбора используемой модели и авторизации до маршрутизации запросов сети и переключения экспериментальных функций.

Аналогия: предустановленные рецепты в кофемашине. Вы можете настраивать параметры каждой чашки кофе вручную — регулировать объем воды, крепость, количество молока перед каждым запуском. Но удобнее сохранить любимый рецепт в памяти кофемашины под отдельной кнопкой, чтобы получать готовый напиток одним нажатием. Переменные окружения работают так же: они фиксируют ваши предпочтения, и Claude Code считывает их при каждом старте, избавляя вас от ручной настройки.

Вам потребуются переменные окружения в следующих случаях:

  • Интеграция сторонних моделей (например, DeepSeek) — чтобы не указывать путь к API-серверу при каждом перезапуске (основа настроек из статьи 05).
  • Медленное интернет-соединение — когда стандартного таймаута в 10 минут не хватает для получения ответа от модели, и нужно увеличить лимит ожидания.
  • Корпоративные требования к безопасности — когда необходимо принудительно отключить отправку любых логов и отчетов об ошибках на внешние сервера (тема статьи 21).
  • Работа под разными учетными записями (личная и рабочая) — для разделения кэша, истории и MCP-инструментов по разным системным папкам.

Эти задачи объединяет требование «один раз настроить для долгой работы». Именно для этого и предназначены переменные окружения.

💡 Резюме в одной фразе: Переменные окружения — это системные переключатели Claude Code, считываемые при старте для настройки авторизации, лимитов таймаутов, адресов API и параметров приватности, избавляющие от ручной конфигурации в чате.

02 Три способа объявления переменных ​

Разберем, где именно прописываются переменные. Для этого есть три основных пути, различающиеся временем жизни настроек и областью их видимости.

Документация разграничивает их следующим образом:

Переменные, объявленные в shell, действуют только в рамках текущей сессии терминала. Переменные, сохраненные в конфигурационных файлах, считываются при каждом запуске claude.

Сравним три способа объявления настроек:

Способ 1: Временное объявление в терминале (shell) ​

Переменная экспортируется в консоли непосредственно перед запуском claude. Настройки действуют только в текущем окне терминала и сбрасываются при его закрытии.

Для macOS / Linux / WSL:

bash
export API_TIMEOUT_MS="1200000"
claude

Для Windows PowerShell:

powershell
$env:API_TIMEOUT_MS = "1200000"
claude

Этот способ удобен по принципу «проверить поведение один раз» — вы временно увеличиваете таймаут или меняете адрес API, а после закрытия окна консоли система возвращается к исходным настройкам.

Способ 2: Запись в автозагрузку профиля терминала ​

Чтобы переменная автоматически создавалась при каждом открытии консоли, добавьте команду экспорта в конфигурационный файл вашего командного интерпретатора. На macOS по умолчанию используется файл ~/.zshrc, на большинстве дистрибутивов Linux — ~/.bashrc:

bash
# Добавляем строку в конец файла ~/.zshrc
export API_TIMEOUT_MS="1200000"

Для применения изменений перезапустите терминал или выполните команду source ~/.zshrc. Этот способ задает глобальные настройки для вашего пользователя на этой машине во всех папках и терминалах.

На Windows для постоянного сохранения используйте команду setx API_TIMEOUT_MS "1200000" (в CMD) или команду [Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "1200000", "User") (в PowerShell). Для применения настроек откройте новое окно терминала.

Способ 3: Использование поля env в settings.json ​

Это наиболее удобный способ — запись переменных в блок env файла конфигурации settings.json. Преимущество этого способа:

Claude Code считывает эти значения напрямую из конфигурационного файла, поэтому они будут применены независимо от того, каким образом была запущена программа claude.

Пример структуры файла:

json
{
  "env": {
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

Пути к файлам settings.json мы подробно разбирали в статье 31. Поле env зарезервировано специально для системных переменных. Записанные сюда параметры считываются при каждом запуске программы, избавляя вас от необходимости прописывать команды экспорта в терминалах.

Сравним три подхода к настройке:

Способ объявленияОбласть действияСохранение при перезапускеПрименение
Экспорт в терминале (export)Только текущее окно консоли❌ Сбрасывается при закрытииРазовое тестирование параметров
Профиль терминала (~/.zshrc)Все сессии консоли текущего пользователя✅ СохраняетсяГлобальные личные настройки на машине
Блок env в settings.jsonВ рамках проекта или пользователя (по структуре папок)✅ СохраняетсяНастройки проекта или команды, независимые от типа консоли

Рекомендуемый подход: для проверки работоспособности экспортируйте переменную в терминале временно, а убедившись в корректности настроек — запишите её в блок env файла settings.json. Почему предпочтительнее использовать settings.json, а не профиль терминала ~/.zshrc? Файл settings.json позволяет гибко разделять область действия переменных (только для вас, для конкретного проекта или для всей команды), что невозможно сделать через глобальные настройки терминала.

💡 Резюме в одной фразе: Задать переменные можно тремя способами: временно в текущей консоли (export), глобально для терминалов пользователя (~/.zshrc) или в блоке env файла конфигурации settings.json. Последний способ наиболее удобен для постоянных настроек проектов.

03 Распределение по файлам settings.json: безопасность и git ​

Поскольку блок env прописывается в файлах settings.json, важно помнить правила их размещения из статьи 31. Настройки Claude Code могут храниться в четырех разных файлах, и выбор файла определяет, кто именно увидит ваши переменные и попадут ли они в git.

Небрежное отношение к этому правилу может привести к утечке данных: если прописать персональный ключ API в файл конфигурации проекта и отправить коммит в git, ваш ключ станет доступен всем участникам разработки.

Аналогия: объявление на доске vs личная записка. Руководитель вешает объявление «офис закрывается в 18:00» на общую доску информации — это публичное правило для всех сотрудников. Но свои личные заметки о пароле от сейфа он оставляет в своем закрытом блокноте — это конфиденциальные данные, которые не должны видеть другие. Выбор файла для переменных окружения — это выбор между доской объявлений и личным блокнотом.

Область действия конфигурационных файлов:

ФайлОбласть примененияДобавление в git
~/.claude/settings.jsonДля вашего пользователя во всех проектах❌ Нет
.claude/settings.json (в корне проекта)Для всех разработчиков текущего проекта✅ Да
.claude/settings.local.json (в корне проекта)Только для вас в текущем проекте❌ Нет
Хостинговые настройки (managed configs)Принудительно для сотрудников организации❌ Нет

Правила просты:

  • ~/.claude/settings.json — файл в домашней директории пользователя. Содержит ваши личные глобальные настройки для всех проектов.
  • .claude/settings.json (в корне проекта) — содержит настройки проекта для всех разработчиков. Этот файл добавляется в git, и изменения скачиваются коллегами.
  • .claude/settings.local.json (в корне проекта) — содержит ваши личные настройки для текущего проекта. Этот файл не добавляется в git (суффикс .local по умолчанию прописан в исключениях git). Предназначен для конфиденциальных данных текущей рабочей копии.

Критически важное правило: никогда не записывайте персональные ключи авторизации, пароли или адреса закрытых прокси-серверов в файл .claude/settings.json в корне проекта, так как он будет зафиксирован в git. Для личных ключей текущего проекта всегда используйте файл .claude/settings.local.json, а для глобальных настроек — файл в домашней директории ~/.claude/settings.json.

Тип данных в переменнойВ какой файл записывать
Личные настройки форматирования, общие для всех проектов~/.claude/settings.json (домашняя папка)
Общие правила сборки и тестов проекта для всей команды.claude/settings.json (в корне проекта, git)
Персональные ключи доступа, токены и прокси текущего проекта.claude/settings.local.json (в корне проекта, без git)

💡 Резюме в одной фразе: Файлы settings.json делятся по уровням доступа. Никогда не сохраняйте личные ключи авторизации и пароли в файл проекта .claude/settings.json, предназначенный для git. Используйте локальные файлы с суффиксом .local или настройки домашней папки.

04 Справочник ключевых переменных окружения ​

Официальный список системных переменных Claude Code огромен и содержит параметры для тонкой настройки AWS Bedrock, OpenTelemetry и сетевых протоколов, большинство из которых вам не понадобятся. Мы выделили наиболее важные переменные, сгруппировав их по четырем категориям.

Категория 1: Авторизация и подключение к моделям ​

Эти переменные лежат в основе интеграции сторонних моделей (статьи 04 и 05):

bash
ANTHROPIC_API_KEY      # Персональный ключ доступа к API Anthropic
ANTHROPIC_BASE_URL     # Перенаправление сетевых запросов (для прокси или сторонних API)
ANTHROPIC_MODEL        # Модель по умолчанию при запуске сессии
  • ANTHROPIC_API_KEY — ваш персональный ключ. Важная особенность: при наличии объявленной переменной ANTHROPIC_API_KEY программа Claude Code переключится на тарификацию по API-ключам, даже если у вас оформлена активная подписка. Для возврата к использованию подписки удалите переменную командой unset ANTHROPIC_API_KEY. В интерактивном режиме программа выдаст запрос на подтверждение использования ключа с возможностью запомнить выбор; в безголовом режиме -p ключ применится автоматически без предупреждения (подробнее о выборе схемы оплаты в статье 04).
  • ANTHROPIC_BASE_URL — изменяет адрес API-сервера. Используется при настройке сетевых прокси-серверов или подключении к сторонним API-интерфейсам (например, при интеграции DeepSeek из статьи 05).
  • ANTHROPIC_MODEL — задает модель по умолчанию. Обратите внимание: флаг запуска --model или команда /model в чате переопределяют это значение (подробнее в разделе 05).

Категория 2: Лимиты времени ожидания (Таймауты) ​

Настройки длительности ожидания ответов сети или выполнения команд:

ПеременнаяНазначениеЗначение по умолчанию
API_TIMEOUT_MSМаксимальное время ожидания ответа от API Anthropic600000 (10 минут)
BASH_DEFAULT_TIMEOUT_MSВремя ожидания завершения команд, запущенных в bash120000 (2 минуты)
  • API_TIMEOUT_MS — лимит ожидания сетевого запроса. Рекомендуется увеличивать при нестабильном интернет-соединении или долгой обработке запроса на прокси-сервере. Учитывайте ограничение: значение переменной не должно превышать 2147483647, иначе произойдет переполнение целочисленного таймера в коде программы, и все сетевые запросы будут завершаться ошибкой мгновенно (популярная ошибка из-за опечатки с лишним нулем).
  • BASH_DEFAULT_TIMEOUT_MS — лимит времени на выполнение команд сборки или тестов силами Claude. Если компиляция проекта занимает больше 2 минут, увеличьте это значение, чтобы сессия не прерывалась по таймауту.

Категория 3: Приватность и телеметрия ​

Переменные для отключения отправки логов и отчетов разработчикам (статья 21):

bash
DISABLE_TELEMETRY=1      # Отключение отправки данных телеметрии
DO_NOT_TRACK=1           # Универсальный флаг отключения отслеживания
  • DISABLE_TELEMETRY — при значении 1 блокирует отправку отчетов. Согласно документации, телеметрия не содержит ваш код или пути к файлам, но в корпоративных сетях её отключение часто является обязательным требованием безопасности.
  • DO_NOT_TRACK — при значении 1 работает аналогично DISABLE_TELEMETRY. Это стандартное соглашение для консольных утилит (CLI), поддерживаемое многими инструментами разработки.

Вы можете использовать переменную CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 для полного отключения любых необязательных сетевых запросов. Это эквивалентно одновременной установке флагов DISABLE_AUTOUPDATER (отключение автообновлений), DISABLE_FEEDBACK_COMMAND (отключение отправки отзывов), DISABLE_ERROR_REPORTING (отключение отчетов об ошибках) и DISABLE_TELEMETRY. Полезно для изолированных сетевых контуров.

Категория 4: Системные пути и память ​

Полезные переменные для настройки окружения:

  • CLAUDE_CONFIG_DIR — изменяет путь к папке настроек программы (по умолчанию ~/.claude). В этой папке хранятся файлы кэша, истории переписок, настройки MCP-серверов и установленные плагины. Основной сценарий использования — работа под разными учетными записями:
bash
# Создаем алиас для запуска рабочей сессии в изолированной папке настроек
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

Теперь запуск команды claude будет использовать личный профиль, а команда claude-work — рабочий профиль с изолированной историей, настройками MCP и авторизацией.

  • DISABLE_AUTO_COMPACT — при значении 1 отключает автоматическое сжатие контекста при достижении лимита рабочей памяти (механизм сжатия из статьи 19). При этом ручной вызов команды /compact остается доступным. Используется, если вы хотите лично контролировать моменты сброса истории диалога.

⚠️ Важная системная деталь: программа Claude Code считывает значения переменных окружения только в момент запуска сессии. Если вы изменили переменную в терминале или файле настроек, обязательно перезапустите программу claude (выйдите и зайдите заново), иначе новые параметры не будут применены.

💡 Резюме в одной фразе: Чаще всего используются четыре группы переменных: авторизация (ANTHROPIC_API_KEY/BASE_URL), таймауты (API_TIMEOUT_MS), настройки приватности (DISABLE_TELEMETRY) и пути конфигурации (CLAUDE_CONFIG_DIR). Для применения изменений требуется перезапуск сессии.

05 Приоритет параметров: правила разрешения конфликтов ​

Что произойдет, если настроить один и тот же параметр (например, используемую модель) в переменной окружения ANTHROPIC_MODEL, файле конфигурации settings.json и выбрать в чате через команду /model?

Для таких ситуаций в системе действуют правила приоритета (precedence). Их понимание избавляет от вопросов вида «почему настройки в файле не применяются».

Базовое правило системы: переменные окружения приоритетнее параметров файла настроек settings.json.

При совпадении параметров приоритет отдается значению из переменной окружения. Например, переменная ANTHROPIC_MODEL перезапишет параметр model из файла settings.json. Файл настроек используется только в том случае, если соответствующая переменная окружения не объявлена в системе.

Аналогия: устное распоряжение руководства vs регламент. Письменный регламент компании (файл settings.json) указывает лимит расходов на поездку в 1000 рублей. Но руководитель лично перед выездом говорит вам: «в этот раз поездка срочная, лимит увеличен до 2000 рублей» (переменная окружения). Вы будете следовать личному указанию руководителя для этой поездки. Переменная окружения выступает в роли такого приоритетного личного распоряжения.

Но из этого правила есть важное исключение, касающееся работы в чате. При выборе модели приоритеты выстраиваются следующим образом:

Флаг запуска CLI --model или команда /model в чате имеют приоритет над переменной окружения ANTHROPIC_MODEL.

Цепочка приоритетов для параметров модели:

text
Команда в чате /model или флаг --model    ← Высший приоритет (ваше текущее действие)
               ↓ Перезаписывает
Переменная окружения ANTHROPIC_MODEL      ← Средний приоритет (системная настройка)
               ↓ Перезаписывает
Параметр model в файле settings.json      ← Низший приоритет (значение по умолчанию)

Такая логика естественна: если вы вручную переключаете модель командой /model в процессе диалога, система считает это вашим явным текущим желанием и переопределяет глобальные настройки.

Суммируем правила приоритета для выбора модели в таблице:

Способ настройкиУровень приоритетаОписание
Команда /model или флаг --modelВысшийТекущее явное указание пользователя в сессии
Переменная ANTHROPIC_MODELСреднийСистемный параметр окружения на машине
Поле model в файле settings.jsonНизшийНастройка по умолчанию при отсутствии других параметров

Обратите внимание: правило «команда чата приоритетнее переменной окружения» действует не для всех параметров. Например, переменная CLAUDE_CODE_EFFORT_LEVEL (уровень усилий модели) на системном уровне переопределяет команду /effort. При возникновении сомнений сверяйтесь со справочной таблицей переменных в официальной документации.

Типичная ошибка: разработчик прописывает модель в файле настроек settings.json, затем в процессе работы переключает её в чате командой /model и забывает об этом, удивляясь, почему программа продолжает использовать старую модель в следующих запросах. Помните, что ручной выбор имеет наивысший приоритет.

💡 Резюме в одной фразе: Общее правило — переменные окружения приоритетнее файлов конфигурации settings.json. Однако ручные команды в чате (например, /model) переопределяют глобальные переменные окружения, так как отражают текущее намерение разработчика.

06 Практика: настройка переменной и проверка считывания ​

Проверим работу переменных окружения на практике. Мы объявим переменную в системе, запустим Claude Code и убедимся, что программа видит новое значение. Мы будем использовать переменную BASH_DEFAULT_TIMEOUT_MS (таймаут команд bash) — это безопасный параметр, изменение которого не сломает подключение к сети.

Шаг 1: Проверяем исходное значение по умолчанию

Запустите обычную сессию:

bash
claude

После запуска спросите Claude о текущем лимите таймаута:

text
Какое значение установлено для переменной BASH_DEFAULT_TIMEOUT_MS в моей сессии? Если переменная не задана в системе, назови стандартное значение по умолчанию.

Ожидаемый результат: Claude ответит, что переменная не объявлена в системе, и используется значение по умолчанию 120000 (120 000 миллисекунд или 2 минуты). Выйдите из программы командой /exit или двойным нажатием Ctrl+C.

Шаг 2: Объявляем переменную в консоли и запускаем сессию

В терминале экспортируем новое значение (установим лимит в 5 минут — 300 000 миллисекунд) и запустим Claude Code:

Для macOS / Linux:

bash
export BASH_DEFAULT_TIMEOUT_MS="300000"
claude

Для Windows PowerShell:

powershell
$env:BASH_DEFAULT_TIMEOUT_MS = "300000"
claude

Задайте тот же вопрос:

text
Какое значение установлено для переменной BASH_DEFAULT_TIMEOUT_MS?

Ожидаемый результат: Claude должен прочитать системную переменную и вывести значение 300000 (5 минут). Это подтверждает, что программа успешно считала настройки окружения при запуске.

Шаг 3: Проверяем временный характер настройки

Выйдите из чата, полностью закройте текущее окно терминала, откройте новое окно и запустите программу claude без предварительного объявления экспорта. Задайте вопрос о значении переменной еще раз.

Ожидаемый результат: значение вернулось к стандартному 120000. Это подтверждает правило: команда export в консоли действует только до закрытия окна терминала.

Шаг 4 (опционально): Сохраняем настройку постоянно в settings.json

Для постоянного сохранения параметра пропишите его в блок env вашего локального файла настроек .claude/settings.local.json в корне проекта (этот файл не попадет в git):

json
{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

После сохранения файла откройте новый терминал и запустите claude без вызова export. Спросите о значении таймаута. Программа считает значение 300000 напрямую из конфигурационного файла, и это значение будет применяться при каждом последующем запуске.

Пройдя эти шаги, вы изучили весь цикл работы: от временного тестирования до постоянного сохранения настроек в файлах конфигурации.

💡 Резюме в одной фразе: Проверить считывание настроек можно простым вопросом в чате о значении переменной. Для временного использования применяйте экспорт в консоли, для постоянного — прописывайте параметр в блок env в settings.json.

07 Заключение ​

Мы разобрали назначение и способы настройки переменных окружения в Claude Code.

Резюмируем ключевые выводы статьи:

ТемаОписаниеГлавная деталь
НазначениеГлобальные настройки Claude Code при стартеУправляют авторизацией, таймаутами, адресами API и приватностью
Способы настройкиВ терминале (временный экспорт) или в блоке env файлов settings.jsonДля постоянного использования рекомендуется settings.json
БезопасностьРазделение по конфигурационным файламЛичные ключи и токены прописывайте в локальные файлы .local, не добавляемые в git
Ключевые переменныеANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, API_TIMEOUT_MS, DISABLE_TELEMETRYИзменение параметров вступает в силу только после перезапуска сессии
ПриоритетыПеременные окружения приоритетнее файлов settings.jsonКоманды в чате (например, /model) имеют наивысший приоритет над системными переменными

Понимание принципов работы переменных окружения позволяет гибко настраивать поведение Claude Code на системном уровне, обеспечивая стабильное подключение к API, безопасность персональных ключей и автоматизацию рутинных параметров.

В следующей статье 43 «Git-воркфлоу» мы перейдем к интеграции Claude Code с системой контроля версий. Как поручить AI ведение истории проекта? Мы разберем, как заставить Claude правильно формулировать сообщения коммитов, создавать ветки, готовить описания пул-реквестов и безопасно сливать изменения под вашим контролем.

Рекомендуемое чтение ​