API Key для Claude Code: переменные, файлы настроек и защита (2026)

API Key в Claude Code — не просто строка. Он определяет, от чьего имени тарифицируются запросы, какие модели доступны и насколько велик ущерб при утечке. Большинство ошибок 401 связаны не с недействительным ключом, а с именем переменной, заголовком запроса или уровнем конфигурации.

Ниже — порядок «цепочка аутентификации, создание ключа, переменные и файлы настроек, несколько конфигураций, ротация, защита от утечек, CI и команда, разбор 401» в виде инструкции, которую можно повторить. Конкретные имена переменных и параметры зависят от текущей версии Claude Code и документации шлюза.

Примечание: Claude и Anthropic — товарные знаки соответствующих правообладателей. Статья носит технический характер и не означает аффилированности с производителем; интерфейсы, права и цены смотрите в официальной документации платформ и на страницах сайта.

1. Сначала разберитесь в цепочке аутентификации Claude Code

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

ANTHROPIC_AUTH_TOKEN: отправляется как Authorization: Bearer, часто используется при подключении через шлюз.
ANTHROPIC_API_KEY: отправляется как x-api-key, ближе к нативному способу Anthropic.

Шлюз получает запрос, находит аккаунт по ключу, затем проверяет баланс, квоту, права на модель и срок действия. Сбой на любом шаге может проявиться как 401, 403 или 429. Поэтому при диагностике не стоит смотреть только на строку ключа.

Ещё одно распространённое заблуждение — привязка ключа к модели. Ключ — это идентичность, модель — параметр запроса; один ключ обычно может вызывать несколько моделей, в зависимости от прав аккаунта и политики шлюза.

2. Создание ключа: пять шагов

Откройте ZSQH AI Gateway или используемую вами платформу, зарегистрируйтесь и войдите в консоль.
Перейдите на страницу «API-ключи» и нажмите «Создать». Укажите среду и назначение, например claude-code-work-mac.
Задайте лимит и срок действия. Для тестового ключа сначала ставьте небольшой лимит, корректируйте после подтверждения реального расхода.
Если платформа поддерживает белый список моделей или область проекта, отметьте только модели, нужные Claude Code.
Скопируйте полный ключ и сразу сохраните в менеджер паролей или сервис управления секретами. Большинство консолей показывают полное значение только один раз.

Ключи часто начинаются с sk-, но префикс не доказывает подлинность и не описывает права. При копировании следите за пробелами и переводами строк в начале и конце — это частая причина 401.

После создания проверьте ключ минимальным curl-запросом и только потом раздавайте команде. Метод проверки — в разделе «Разбор 401».

3. Переменные окружения и файлы настроек: что выбрать

Способ	Когда подходит	Плюсы	На что обратить внимание
Переменные shell	Личная машина разработчика, временные переключения	Не попадают в проект, удобно переключать	Новый терминал или IDE может их не увидеть
Пользовательский settings.json	Личное постоянное использование	Настраивается один раз, действует глобально	Ключ хранится в открытом виде
Проектный settings.local.json	Переопределение для одного проекта	Не влияет на другие проекты, можно добавить в gitignore	При смене машины нужно настраивать заново
apiKeyHelper или менеджер секретов	Команда, общие машины, комплаенс	Ключ не появляется в файле настроек напрямую	Нужны дополнительные скрипты и управление правами
Секреты CI	Автоматические конвейеры	Отделены от кода, поддаются аудиту	Нужна маскировка логов и права на ветки

Переменные окружения подходят для «хочу попробовать сейчас»; settings.json — для «на этой машине так работают постоянно»; менеджер секретов — для «ключ не должен лежать на диске в открытом виде». Их можно сочетать, но нужно понимать, что что перекрывает. Приоритет в Claude Code примерно такой: корпоративные настройки, параметры командной строки, локальные проектные, проектные, пользовательские — версии могут немного отличаться, ориентируйтесь на официальную документацию.

Частая ловушка: переменная экспортирована в ~/.zshrc, но Claude Code, запущенный из Dock или IDE, её не видит. Графические программы наследуют среду входа и не обязательно загружают конфигурацию shell. В этом случае перенесите настройку в settings.json или явно задайте переменную в стартовом скрипте.

4. Несколько конфигураций: как разделить личное, проектное и командное

Рекомендуется минимум три набора ключей: личный повседневный, проектный и автоматизационный. У них разные лимиты, права и циклы ротации; при смешивании сложно понять и расход, и причину сбоя.

Если не хочется поддерживать несколько файлов, можно задавать окружение через функции shell:

# ~/.zshrc
claude_work() {
  ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com" \
  ANTHROPIC_AUTH_TOKEN="$ZSQH_WORK_KEY" \
  claude "$@"
}

claude_test() {
  ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com" \
  ANTHROPIC_AUTH_TOKEN="$ZSQH_TEST_KEY" \
  claude "$@"
}

Настоящие ключи храните в ~/.zshrc.local или в менеджере секретов, а основной файл конфигурации пусть ссылается только на переменные. Тогда для смены среды достаточно поменять имя функции, не трогая код проекта.

Для изоляции на уровне проекта используйте .claude/settings.local.json и убедитесь, что файл добавлен в .gitignore. Общий командный .claude/settings.json должен содержать только неконфиденциальные параметры: Base URL, имя модели, права. Ключ туда класть нельзя.

5. Ротация ключей: когда и как

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

Создайте в консоли новый ключ с датой в имени, например claude-code-prod-2026-10.
Сначала запишите новый ключ в менеджер секретов или переменные окружения, старый пока не удаляйте.
Проверьте новый ключ через curl и Claude Code: модель, лимит и права должны работать.
Посмотрите логи расхода старого ключа и убедитесь, что им не пользуются забытые скрипты или сотрудники.
Отключите старый ключ и наблюдайте уровень ошибок ещё один-два дня.
Зафиксируйте время ротации, ответственного и область влияния для следующей передачи.

Не выполняйте ротацию в пик production-нагрузки. Параллельная работа двух ключей безопаснее, чем «удалить и создать заново».

6. Защита от утечек: от машины разработчика до репозитория

Ключи утекают чаще не из-за хакерских атак, а из-за собственных коммитов, скриншотов, записи экрана, сообщений в чатах и логов. Помогут несколько правил:

.gitignore должен покрывать .env, .env.*, .claude/settings.local.json, *.pem и подобные файлы.
Перед коммитом проверяйте шаблоны вроде sk- через secret scanning или pre-commit hook.
Не пишите ключ по умолчанию в коде и не отлаживайте через echo $ANTHROPIC_AUTH_TOKEN.
Маскируйте в логах заголовки Authorization, x-api-key и другие.
Перед демонстрацией экрана и скриншотами очищайте историю терминала или экран.
На машине разработчика задайте права на файлы, например chmod 600 ~/.claude/settings.json.
Используйте ключи со сроком действия и лимитом, чтобы уменьшить потери от одной утечки.

Если утечка подтверждена, порядок такой: сначала отключите или удалите ключ, затем создайте новый, после этого проверьте логи расхода и историю репозитория. Сменить пароль или удалить файл недостаточно: старый ключ могли уже скопировать в другое место.

7. CI и командное использование

Принцип для CI: «ключ не попадает в код, в образ и в логи». Практические шаги:

Используйте секреты или переменные окружения платформы, не пишите ключ открытым текстом в YAML.
Ограничьте секрет защищёнными ветками или доверенными workflow.
Перед выводом логов убедитесь, что заголовки запросов не печатаются; большинство HTTP-библиотек по умолчанию их не выводят, но собственные логи могут.
Для автоматизации используйте отдельный ключ с отдельным лимитом, чтобы легче находить аномалии.
Один ключ на сотрудника, отключение в день увольнения; не экономьте на общем ключе.
Регулярно выгружайте расход и сверяйте по сотрудникам, проектам и моделям.

Если платформа поддерживает краткосрочные учётные данные или OIDC, предпочитайте их, чтобы меньше хранить долгоживущие ключи. Возможность зависит от платформы; перед подключением читайте документацию.

8. Разбор 401: порядок проверки

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

Убедитесь, на какой Base URL уходит запрос: выполните echo $ANTHROPIC_BASE_URL. Пустое значение или старый адрес приведут к ошибке.
Проверьте, что в ключе нет пробелов, переводов строк и лишних кавычек; скопируйте его из консоли заново.
Проверьте имя переменной: ANTHROPIC_AUTH_TOKEN или ANTHROPIC_API_KEY. Не задавайте обе одновременно.
Сверьте заголовок с требованием шлюза: Bearer или x-api-key.
Убедитесь, что ключ не просрочен и не отключён, а на аккаунте есть баланс.
Проверьте, что имя модели есть в каталоге шлюза; некоторые платформы возвращают 401 или 403 для моделей без прав.
Если используется прокси, проверьте, не удаляет и не переписывает ли он заголовок Authorization.
Воспроизведите минимальным curl-запросом, исключив влияние версии Claude Code и уровня конфигурации.

Частые ошибки и решения:

Ошибка	Частая причина	Что делать
401 Unauthorized	Неверный ключ, имя переменной или заголовок	Скопируйте ключ заново; оставьте одну переменную аутентификации
403 Forbidden	У ключа нет прав на модель или ограничение по IP	Проверьте белые списки и права на модель
404 Not Found	Неверный Base URL или путь	Проверьте корневой адрес и `/v1` по отдельности
429 Too Many Requests	Превышен параллелизм или квота	Снизьте параллелизм; проверьте лимит ключа
insufficient quota	Недостаточно средств	Пополните баланс или замените ключ

Если curl работает, а Claude Code всё равно даёт 401, смотрите среду запуска: встроенный терминал IDE, Docker, systemd и launchd могут не наследовать переменные shell. Запись настроек в settings.json или стартовый скрипт обычно решает проблему.

Частые вопросы

Ключ Claude Code и подписка на сайт Claude — это одно и то же?

Нет. Подписка на сайте — это доступ к чат-продукту, а API Key — учётные данные интерфейса. Claude Code работает через API, поэтому подписка не заменяет ключ.

Можно ли использовать один ключ и в Claude Code, и в Cursor?

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

Безопасно ли хранить ключ в settings.json?

На личном компьютере допустимо, потому что файл находится только на этой машине. На общих машинах, в репозиториях и CI открытый ключ хранить нельзя — используйте переменные окружения, apiKeyHelper или менеджер секретов.

Нужно ли останавливать сервис при ротации ключа?

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

Почему вчера всё работало, а сегодня внезапно 401?

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

Что дальше

Если ключа ещё нет, создайте тестовый ключ с небольшим лимитом через регистрацию и настройте его по порядку из статьи. Модели, лимиты и биллинг смотрите на странице тарифов; цены меняются вместе с версиями моделей и политикой поставщиков, ориентируйтесь на актуальные данные страницы.