Claude Code — консольный инструмент для программирования от Anthropic, который по умолчанию подключается к официальному интерфейсу Anthropic. На практике команды в Китае часто направляют его на собственный или сторонний шлюз, чтобы решить вопросы стабильности доступа, единого биллинга и управления лимитами. «Подключение собственного API» по сути означает изменение трёх вещей: куда уходит запрос (Base URL), какая используется аутентификация (ключ) и какая модель вызывается (имя модели).

Ниже — воспроизводимый порядок подключения: установка, переменные окружения, файлы конфигурации, выбор модели, проверка соединения, внедрение в команде и безопасность. Команды ориентированы на macOS и Linux; для Windows есть отдельные пометки.

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

1. Перед подключением проверьте три вещи

Claude Code использует протокол Anthropic Messages, а не Chat Completions от OpenAI. Поэтому собственный API должен как минимум удовлетворять двум требованиям: предоставлять Anthropic-совместимую точку /v1/messages и использовать те же имена моделей, которые реально доступны в шлюзе. На шлюз только с OpenAI-совместимой точкой нельзя напрямую переключить Claude Code, если у шлюза нет и Anthropic-совместимого маршрута.

Перед началом подготовьте три вещи:

  • Base URL — корневой адрес шлюза, например https://ai.zhongshangqihang.com. Нужен ли /v1, зависит от реализации шлюза; смотрите внутреннюю инструкцию.
  • API-ключ — создаётся в консоли, с лимитом и сроком действия. Не используйте для тестов долгоживущий ключ без ограничений.
  • Имя модели — копируйте из консоли или со страницы тарифов, не пишите вручную. Одна ошибка в регистре или дефисе может привести к сообщению о несуществующей модели.

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

2. Установка Claude Code

Claude Code обычно распространяется через npm, но есть и другие способы установки. Ниже — самый распространённый порядок:

  1. Убедитесь, что установлен Node.js. Рекомендуется поддерживаемая версия LTS; минимальную версию смотрите в официальной документации.
  2. Выполните глобальную установку: npm install -g @anthropic-ai/claude-code.
  3. Выполните claude --version, убедитесь, что команда доступна, и запишите номер версии.
  4. Перейдите в тестовый каталог проекта, запустите claude и завершите первичную настройку: тему, доверие к каталогу и т. п.
  5. Если в команде принято управление версиями, зафиксируйте версию и внесите её во вводную документацию; перед обновлением проверяйте новую версию на тестовом проекте.
node --version
npm install -g @anthropic-ai/claude-code
claude --version
cd /path/to/your-project
claude

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

3. Переменные окружения: BASE_URL и AUTH_TOKEN

Claude Code читает две распространённые переменные аутентификации:

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

Достаточно одной из двух последних. Если шлюз использует Bearer, применяйте ANTHROPIC_AUTH_TOKEN; если нативную схему — ANTHROPIC_API_KEY. При одновременной установке обеих переменных приоритет в разных версиях может отличаться, и возникает ситуация «всё заполнено верно, но приходит 401». Оставляйте только одну.

export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_AUTH_TOKEN="sk-ваш-ключ"
claude

Запись в ~/.zshrc или ~/.bashrc делает настройку постоянной; после изменения выполните source ~/.zshrc. В Windows PowerShell используется $env:ANTHROPIC_BASE_URL="...", что действует только в текущем окне; для постоянного хранения применяйте системные переменные или setx, после чего перезапустите терминал.

Не записывайте export в скрипт проекта и не коммитьте его. После попадания ключа в историю Git удаление файла не равно удалению записи.

4. settings.json: закрепляем конфигурацию в файле

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

  • Пользовательский: ~/.claude/settings.json, действует для всех проектов на машине.
  • Проектный: .claude/settings.json, можно коммитить в репозиторий, подходит для общих несекретных настроек.
  • Локальный проектный: .claude/settings.local.json, не коммитится, подходит для личных переопределений.

Пример:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.zhongshangqihang.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-ваш-ключ"
  },
  "model": "claude-sonnet-4-5"
}

Важно: ключ в settings.json хранится в открытом виде. На личном компьютере это допустимо, но на общих машинах, в CI и репозиториях так делать нельзя. В проектном файле размещайте только Base URL и имя модели, а ключ передавайте через переменные окружения или хранилище секретов. Приоритет настроек примерно таков: корпоративная конфигурация, параметры командной строки, локальный проект, проект, пользователь — каждый следующий уровень перекрывается предыдущим; точный порядок смотрите в документации текущей версии.

5. Выбор модели: разбиваем по задачам

Модели Claude обычно делятся на три уровня, подходящие для разных задач:

Уровень Типичное применение Компромисс
Opus Сложный рефакторинг, анализ нескольких файлов, длинные агентные цепочки Выше возможности, обычно выше стоимость и возможна меньшая скорость
Sonnet Повседневное программирование, исправление ошибок, ревью кода Баланс возможностей и стоимости, подходит как уровень по умолчанию
Haiku Простое автодополнение, форматирование, небольшие пакетные задачи Высокая скорость и низкая стоимость, но сложные задачи могут оказаться не по силам

В Claude Code можно задать основную модель через ANTHROPIC_MODEL, а также переопределить соответствие уровней через ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL и ANTHROPIC_DEFAULT_HAIKU_MODEL. Набор поддерживаемых переменных зависит от версии; перед настройкой проверьте claude --help или официальную документацию.

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

6. Проверка соединения: сначала curl, затем Claude Code

Сначала в обход Claude Code проверьте сам шлюз через curl:

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Ответь только OK"}]
  }'

Если шлюз использует Bearer, замените x-api-key на Authorization: Bearer $ANTHROPIC_AUTH_TOKEN. Ответ 200 с нормальным содержимым означает, что хотя бы одна комбинация Base URL, ключа и модели работает.

Затем вернитесь в Claude Code и проверьте по порядку:

  1. claude --version — клиент запускается.
  2. В каталоге проекта выполните claude doctor (если команда есть в текущей версии) и проверьте установку и конфигурацию.
  3. Запустите claude и посмотрите текущую модель и данные аккаунта через /status.
  4. Дайте безопасную задачу, например «объясни структуру этого каталога, не изменяя файлы».
  5. Посмотрите, приходит ли нормальный ответ и не появляются ли ошибки 401, 404 или «модель не найдена».

Типичные симптомы:

Симптом Что проверять в первую очередь Что делать
401 Ключ, имя переменной, заголовок запроса Скопируйте ключ заново; оставьте одну переменную аутентификации
404 Лишний или недостающий /v1 в Base URL Приведите адрес к корневому или совместимому входу по документации шлюза
model not found Имя модели не совпадает с каталогом шлюза Скопируйте имя из консоли или со страницы тарифов
Таймаут запроса Сеть, DNS, прокси Проверьте на другой сети; убедитесь, что прокси не переписывает заголовки
429 Ограничение параллелизма или лимита Снизьте параллелизм; проверьте лимит ключа

7. Внедрение в команде: один ключ на человека, единая точка входа

Для командной работы не рекомендуется общий ключ. Надёжнее так:

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

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

8. Границы безопасности: ключи, код и данные

Несколько базовых правил:

  • ключ не попадает в Git, образы, клиентский код, скриншоты и переписку;
  • добавьте в проект .gitignore, как минимум для .env, .env.* и .claude/settings.local.json;
  • при подозрении на утечку сначала отзовите старый ключ, затем проверьте расход, а не только меняйте пароль;
  • задавайте ключам срок действия и меняйте их при кадровых изменениях;
  • на общих машинах используйте хранилище секретов или apiKeyHelper, не храните открытый текст в settings.json;
  • устанавливайте Claude Code только из доверенных источников и читайте описание изменений перед обновлением.

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

Обязательно ли входить в аккаунт Anthropic для Claude Code?

Нет. После настройки рабочего Base URL и переменных аутентификации клиент может работать с собственным API напрямую; однако первичные шаги вроде выбора темы и доверия к каталогу всё равно могут появиться. Необходимость входа зависит от версии и конфигурации; при проблемах сначала проверьте, действуют ли переменные окружения в shell запуска.

Чем отличаются ANTHROPIC_API_KEY и ANTHROPIC_AUTH_TOKEN?

Первая обычно отправляется в заголовке x-api-key, вторая — как Authorization: Bearer. Выбор зависит от схемы аутентификации шлюза; задавайте только одну переменную, чтобы избежать конфликта заголовков.

В Base URL указывать корневой адрес или адрес с /v1?

Claude Code обычно принимает корневой адрес, а /v1/messages добавляет сам клиент; некоторые шлюзы требуют сразу совместимый вход. Проверка простая: запросите curl корневой адрес плюс /v1/messages. Если работает — оставляйте корневой, иначе действуйте по документации шлюза.

Почему curl работает, а Claude Code выдаёт ошибку?

Частая причина — переменные shell не передаются в графическую среду или встроенный терминал IDE, либо одновременно заданы две переменные аутентификации. Сначала выполните echo $ANTHROPIC_BASE_URL в том же терминале, из которого запускается Claude Code.

Можно ли команде использовать один общий ключ?

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

Что дальше

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

Читайте также: