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

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

1. Разделите два источника «ключей»

В Chatbox могут одновременно существовать две учётные сущности: аккаунт сервиса Chatbox AI и API-ключ, который вы вписываете для собственного провайдера. Плательщики у них разные, и диагностика тоже разная.

Источник Кто выставляет счёт Когда подходит Что учесть
Аккаунт Chatbox AI По тарифу клиента Не хочется управлять ключами Не связан с собственным ключом
Свой API-ключ Поставщик API Есть шлюз или аккаунт модели Нужно самому хранить и менять
Локальная модель Зависит от вашего железа Данные не должны покидать компьютер Удалённый ключ не нужен

Если появляется «вход выполнен, но пришёл 401», сначала проверьте, какой провайдер выбран в текущей сессии. Успешный вход в аккаунт не означает, что ключ собственного провайдера заполнен верно.

2. Создание ключа: имя, принадлежность и права

После регистрации в ZSQH AI Gateway создайте ключ в консоли. Лучше сразу сделать три вещи правильно:

  1. Прослеживаемое имя: формат «устройство-назначение-пользователь», например chatbox-mac-alice.
  2. Один ключ — одно назначение: компьютер, телефон и автоматизация отдельно, чтобы проще было найти источник проблемы.
  3. Фиксация принадлежности: во внутреннем реестре укажите дату создания, ответственного и назначение.

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

3. Несколько провайдеров и моделей в Chatbox

Несколько моделей не означают несколько ключей. Обычно у провайдера один ключ, а под ним несколько ID моделей:

  1. Откройте настройки и раздел «Поставщики моделей».
  2. Добавьте OpenAI-совместимого провайдера; в названии полезен префикс среды.
  3. Укажите Base URL, обычно https://ai.zhongshangqihang.com/v1.
  4. Вставьте API-ключ и проверьте, что по краям нет пробелов.
  5. Добавьте ID моделей вручную или попробуйте загрузить список.
  6. Выберите тип модели: чат, зрение, reasoning или вызов инструментов.
  7. Нажмите «Проверить», затем переключите модель в интерфейсе диалога.

ID модели сверяйте со страницей цены на модели. Отображаемое имя можно менять, но API-идентификатор должен совпадать посимвольно. Называйте чат и визуальные модели по-разному, например «чат-основная» и «зрение-скриншоты», чтобы не выбрать не ту.

Если команда параллельно использует Cherry Studio, LobeChat и другие клиенты, договоритесь об одинаковых названиях провайдеров и псевдонимах моделей — меньше путаницы, когда один человек в разных клиентах работает с разными моделями.

4. Где хранится ключ: локально, синхронизация и копии

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

В синхронизации различайте три вещи:

  • Синхронизация истории: поддерживается ли и в каком объёме, зависит от версии клиента и тарифа.
  • Синхронизация настроек: конфигурация провайдера может синхронизироваться с аккаунтом, а может оставаться локальной.
  • Синхронизация ключа: не путайте «синхронизируются настройки» с «ключ безопасно синхронизируется». Многие клиенты записывают ключ в конфигурацию или файл копии.

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

5. Минимальные права: ключ делает только положенное

API-ключ не должен быть «как можно меньшим», он должен иметь ясные границы. Практичные меры:

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

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

6. Ротация и отзыв: по фиксированному ритму

Меняйте ключ не реже раза в 90 дней; сразу — при смене сотрудника, потере устройства или подозрении на утечку. Порядок обратный недопустим:

  1. Создайте в консоли новый ключ с датой в названии.
  2. Замените ключ провайдера в Chatbox на новое значение.
  3. Отправьте тестовое сообщение и убедитесь, что модель отвечает.
  4. Убедившись, что новый ключ работает, отзовите старый.
  5. Проверьте расход на шлюзе — не появилось ли посторонних вызовов.
  6. Обновите внутренний реестр, записав дату ротации.

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

export ZSQH_API_KEY="sk-новый-ключ"

curl -sS -o /dev/null -w "%{http_code}\n" \
  "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY"

Код 200 означает, что авторизация прошла; при 401 проверьте, скопирован ли ключ полностью. Если шлюз не открывает интерфейс списка моделей, проверьте обычным диалоговым запросом. Во время ротации не меняйте одновременно Base URL и ID модели, иначе не понять, на каком шаге возникла проблема.

7. Типичные сбои: по статусным кодам

Симптом Частая причина Что делать
401 Ключ неверен, просрочен, отозван или содержит пробел Создайте заново и вставьте целиком
403 Forbidden Нет прав на модель, ограничение региона или политики Проверьте права и список моделей в консоли
404 Not Found Неверный путь Base URL Уточните, нужен ли /v1
429 Too Many Requests Ограничение параллелизма или лимита Снизьте параллелизм, проверьте расход и лимиты
5xx Сбой на стороне апстрима Повторите позже, сохраните время запроса

Меняйте за раз одну переменную. Сначала определите, «проблема в этом ключе» или «в этой модели»: замените ключ или модель для теста — это быстро разделит причины.

8. Чек-лист передачи дел в команде

Внесите в документ передачи несколько пунктов — это снимет большинство проблем «после смены человека ничего не работает»:

  • Ответственный за ключ, назначение, дата создания и дата следующей ротации.
  • Название провайдера, Base URL, список ID моделей.
  • На каких устройствах хранится ключ и какие из них общие.
  • Процедура отзыва при увольнении, переводе и потере устройства.
  • Точка проверки аномального расхода и контактное лицо.

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

Синхронизируется ли ключ вместе с историей на другие устройства?

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

Можно ли одним ключом пользоваться на компьютере и телефоне?

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

«Проверить» проходит, а чат выдаёт 401?

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

Нужно ли заново добавлять модели после смены ключа?

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

Можно ли вписать ключ в прокси-программу или расширение браузера?

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

Дальше

Управление ключами Chatbox сводится к правилу: один ключ — одно назначение, к конфигурации и копиям относятся как к чувствительным файлам, при ротации сначала создают новый ключ, потом отзывают старый. Если нужны единая точка входа, управление расходом и правами, можно зарегистрироваться в ZSQH AI Gateway; модели и цены — на странице цены на модели.

Полезное чтение: