Безопасная настройка Claude Code и лучшие практики relay API

Claude Code и пользовательские интеграции с API передают не только промпты — они отправляют метаданные окружения, выбор маршрутизации и поведение при повторах, которые upstream-системы могут сопоставлять со «здоровьем» аккаунта. В этом руководстве — операционная безопасность: единообразная конфигурация shell, выбор шлюза и плавный failover при ужесточении квот. Цель — надёжные инженерные процессы, а не обход политики Anthropic.

Начните с чистой базы: очистка окружения и настройка IP и выбор VPN и прокси, прежде чем настраивать переменные CLI. Если вы используете relay или мульти-модельные роутеры, прочитайте локальные и open-source альтернативы про пути деградации.

1. Параметры безопасности Claude Code

Claude Code при запуске читает переменные окружения shell. Несогласованные часовой пояс, прокси или base URL дают запутанные ошибки или заставляют клиент вести себя иначе, чем сеанс в браузере. Считайте терминал полноценным окружением, а не второстепенной деталью.

Основные переменные окружения

# ~/.zshrc or ~/.bashrc — load in every interactive shell

# 1. Declare custom Anthropic-compatible endpoints explicitly
export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_API_KEY="sk-your-key"

# 2. When using a trusted first-party-shaped gateway, reduce client mismatch warnings
export _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL=1

# 3. Align terminal timezone with your documented operating region
export TZ=Asia/Tokyo   # or America/Los_Angeles — match proxy geo

# 4. Route CLI HTTPS through the same clean proxy as your browser (if required)
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,.internal"

Чеклист конфигурации

1. Единый источник истины: храните переменные в ~/.zshrc (macOS) или в отдельном ~/.claude/env, подключаемом в shell — не экспортируйте их наудачу в одной вкладке терминала.
2. Проверка перед запуском: в том же окне, откуда стартуете Claude Code, выполните env | grep -E 'ANTHROPIC|TZ|PROXY'.
3. Согласуйте географию браузера и CLI: если профиль браузера через anti-detect задаёт часовой пояс Токио, CLI не должен сообщать Asia/Shanghai.
4. Фиксируйте смену base URL: при переходе с прямого Anthropic на relay обновите и ANTHROPIC_BASE_URL, и внутренние runbook, чтобы коллеги не смешивали endpoint.
5. Гигиена секретов: не коммитьте API keys; для env-файлов — chmod 600, ключи relay ротируйте ежеквартально.

Что делает и чего не делает _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL

Флаг говорит Claude Code для части клиентских проверок воспринимать нестандартный ANTHROPIC_BASE_URL как обычный endpoint Anthropic. Это снижает трение, когда в организации одобрен внутренний шлюз. Он не меняет серверную политику, биллинг или право на доступ. Как по-прежнему могут оценивать метаданные клиента — см. Claude: стеганография и модель риска.

Типичные сбои из-за неверной настройки

• Раздвоение прокси: браузер через VPN, CLI — нет; запросы из разных ASN. Симптом: веб-чат работает, CLI возвращает 403.
• Устаревший NO_PROXY: локальный шлюз на 127.0.0.1 должен обходить корпоративный прокси, иначе петля с connection reset.
• Неверная область API key: organization keys и project keys по-разному ведут себя при rate limits; тип ключа проверьте в консоли Anthropic.
• Интерактивный и неинтерактивный shell: CI, вызывающий Claude Code, должен подключать тот же env-файл; login shell на ноутбуке часто скрывает отсутствующие export.

2. Выбор API relay-шлюзов

Когда прямой доступ к api.anthropic.com ограничен маршрутизацией или закупками, relay может повысить доступность — если сохраняется точность протокола. Плохой шлюз беззвучно срезает заголовки, переписывает промпты или даёт всплески задержки, похожие на регресс качества модели.

Матрица оценки шлюза

Сохранение Prompt Cache (влияние на стоимость)

Prompt caching Anthropic может снизить стоимость повторного ввода до 90%. Relay без cache-заголовков тарифицирует полный input на каждом шаге — часто сюрприз 4×–10× на длинных system prompt. Проверьте тестом из двух запросов:

# Request 1: create cache
curl -s "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: prompt-caching-2024-07-15" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":64,
       "system":[{"type":"text","text":"'$(python3 -c "print('x'*5000)")'",
         "cache_control":{"type":"ephemeral"}}],
       "messages":[{"role":"user","content":"ping"}]}'

# Request 2: expect cache_read_input_tokens > 0 in usage

Глубокие паттерны оптимизации — в продвинутой оптимизации API.

Due diligence перед продакшеном

• 24 часа синтетических проб (сообщение каждые 15 минут), замер p95 задержки и error rate.
• Логируйте выборку request ID; убедитесь, что приложение связывает логи шлюза с upstream ID при инцидентах.
• Соглашение об обработке данных: часть relay логирует промпты для abuse detection — недопустимо для регулируемых нагрузок.
• Предпочитайте шлюзы под контролем организации (self-hosted LiteLLM, One-API в VPC) непрозрачным публичным reseller при работе с исходным кодом.

Стабильность на уровне аккаунта всё ещё зависит от гигиены регистрации — см. регистрацию аккаунта и оплату: антибан, если внедрение relay совпало с созданием новой org.

3. Rate limits (429) и плавный failover

Лимиты Anthropic действуют на уровне организации и тарифа модели, а не изолированно на один API key. Всплески agent, параллельные CI-задачи и неограниченные retry-циклы могут исчерпать общую квоту и заблокировать несвязанные сервисы той же org.

Классы ограничений (упрощённо)

Паттерн retry и failover

// TypeScript — retry 429/529, failover on sustained pressure
async function callClaudeWithFallback(prompt: string, opts: CallOpts) {
  const maxRetries = 4;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await callClaudeAPI(prompt, opts);
    } catch (error: any) {
      const status = error?.status;
      if (status === 429 || status === 529) {
        const delay = Math.min(30_000, 500 * 2 ** attempt + Math.random() * 250);
        await sleep(delay);
        continue;
      }
      if (status === 403) throw error; // surface auth issues
      throw error;
    }
  }
  console.warn('Claude quota saturated; failing over to backup upstream');
  return await callFallbackAPI(prompt, opts); // DeepSeek / GLM / local — see alternatives guide
}

Контроль параллелизма

• Token bucket в CI: лимит параллельных agent jobs (напр. макс. 3) на организацию.
• Объединение запросов: где возможно, пакетируйте мелкие lint-фиксы вместо одного API-вызова на файл.
• Circuit breaker: после N подряд 429 разомкнуть цепь на 60 с и автоматически failover — против retry storm.
• Наблюдаемость: метрики claude_requests_total{status}, fallback_invocations_total, p95 latency. Алерт, если доля fallback > 15% за 10 минут.

403 и 429: не смешивайте

429 — временное давление: отступите и продолжайте. 403 часто означает отзыв учётных данных, географическое ограничение или смену состояния аккаунта. Ретраить 403 с другими keys без диагностики может ускорить enforcement. Классифицируйте ошибки по руководству по устранению неполадок, прежде чем крутить инфраструктуру.

FAQ

Нужно ли задавать TZ, если системный часовой пояс уже верный?

Если часовой пояс ОС, geo выхода прокси и профиль браузера совпадают, явный TZ может быть лишним — но CI-контейнеры часто по умолчанию UTC. Явный export делает поведение предсказуемым на ноутбуках и серверах.

«Безопасен» ли публичный API reseller для корпоративного исходного кода?

Относитесь как к любому субпроцессору: логи, retention, список субпроцессоров. Для проприетарного кода self-hosted relay в VPC строго безопаснее анонимных reseller.

Почему экономия cache пропадает после смены шлюза?

Чаще всего relay срезает заголовки anthropic-beta или переставляет system blocks, ломая cache keys. После любой смены шлюза повторите двухзапросный cache-тест.

Можно ли разные прокси для браузера и Claude Code?

Технически да, но растёт риск расхождения. Предпочтительнее один задокументированный egress для всего трафика Claude, если только экспериментальные аккаунты не в отдельных профилях.

Какую fallback-модель использовать в Claude Code при 429?

В Claude Code нет встроенного multi-model failover — реализуйте на шлюзе (One-API/LiteLLM) или временно отключите Claude Code и используйте плагины IDE на backup API. Таблицы маршрутизации — в локальных и open-source альтернативах.

Как отладить «в curl работает, в Claude Code нет»?

1. Сравните заголовки: curl vs CLI через mitmproxy или access log шлюза.
2. Проверьте env в shell запуска: встроенные терминалы IDE иногда не читают login rc.
3. Проверьте proxy agents Node/fetch — в некоторых версиях HTTPS_PROXY игнорируется без GLOBAL_AGENT_HTTP_PROXY.
4. Проверьте TLS interception в корпоративной сети.

Влияет ли assume first-party base URL на биллинг Anthropic?

Нет. Биллинг идёт по API key и организации того upstream, который реально обслуживает запрос. Если шлюз форвардит в Anthropic, платите Anthropic; если подменяет модели — платите провайдеру, которого вызывает шлюз.