Как использовать Claude Code с любой моделью: настройка SKILL.md

Claude Code может стать намного полезнее, когда он знает, как работает ваш слой маршрутизации ИИ. Настройка SKILL.md — это аккуратный способ обучить его этому рабочему процессу: где находится маршрутизатор Flatkey, как находить актуальные идентификаторы моделей, как вызывать поддерживаемые модели и инструменты, а также какие правила безопасности соблюдать перед тратой баланса или изменением продакшн-систем.

Сразу есть один важный нюанс. Собственный цикл рассуждений Claude Code по-прежнему работает на Claude. В документации Anthropic для gateway сказано, что Claude Code может подключаться к LLM gateway, но он не поддерживает маршрутизацию самого Claude Code на не-Claude-модели через gateway. Используйте это руководство для практической версии How to Use Claude Code with Any Model: The SKILL.md Setup: оставьте Claude Code своим кодинговым агентом, а затем дайте ему навык Flatkey, чтобы он мог обнаруживать и вызывать любую поддерживаемую Flatkey модель или тарифицируемый инструмент из вашего проекта, когда этого требует задача.

Публичный SKILL.md от Flatkey создан именно для этой задачи. В нём агентам предлагается использовать https://router.flatkey.ai, совместимый с OpenAI базовый URL https://router.flatkey.ai/v1, актуальный каталог моделей, marketplace инструментов, небольшие первые запросы, request ID и контрольные точки одобрения для операций записи, отправки, покупок, удалений, публикации или изменения прав доступа.

Если вы только начинаете работать с самим маршрутизатором, держите Flatkey API quickstart открытым рядом с этим руководством. Если вы сравниваете это с более широкой миграцией провайдера, руководства OpenAI API alternative и unified AI API workflow подробнее объясняют шаблон базового URL.

Краткий ответ

Используйте эту настройку, когда хотите, чтобы Claude Code работал с Flatkey из вашего репозитория:

1. Создайте API-ключ Flatkey в Flatkey Console.
2. Установите навык Flatkey в Claude Code как ~/.claude/skills/flatkey/SKILL.md или .claude/skills/flatkey/SKILL.md.
3. Сохраните FLATKEY_API_KEY в вашей shell-среде или локальном менеджере секретов, а не в закоммиченном файле.
4. Попросите Claude Code использовать навык Flatkey, получить актуальный каталог моделей и выполнить небольшой тестовый вызов через https://router.flatkey.ai/v1.
5. Проверьте Flatkey Usage Logs на модель, количество токенов, задержку, статус и стоимость.

Если вы хотите, чтобы трафик Claude Code семейства Claude проходил через Flatkey, используйте руководство Flatkey для Claude Code вместо совместимого с OpenAI базового URL /v1:

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

Этот путь предназначен для маршрутизации Claude Code через gateway. Путь SKILL.md предназначен для обучения Claude Code тому, как использовать модели и инструменты Flatkey из проекта.

Что меняет SKILL.md в Claude Code

Навык Claude Code — это директория с файлом SKILL.md. Claude Code загружает метаданные навыка при запуске, а затем читает тело навыка только когда задача совпадает или когда вы вызываете навык напрямую. Это делает навык лучшим местом, чем CLAUDE.md, для повторяемых процедур вроде «найти модели Flatkey, выбрать поддерживаемый маршрут, выполнить небольшой вызов и проверить Usage Logs».

С Flatkey навык должен заставлять Claude Code последовательно делать пять вещей:

Это и есть практическое ядро Как использовать Claude Code с любой моделью: настройка SKILL.md. Claude Code по-прежнему остается оркестратором. Flatkey становится слоем моделей и инструментов, с которым он может работать осознанно.

Шаг 1: выберите личную или проектную установку

Установите навык глобально, если хотите, чтобы он был доступен в каждом репозитории:

mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o ~/.claude/skills/flatkey/SKILL.md

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

mkdir -p .claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o .claude/skills/flatkey/SKILL.md

Для общего проектного навыка просмотрите файл перед коммитом:

sed -n '1,200p' .claude/skills/flatkey/SKILL.md

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

Шаг 2: безопасно задайте ключ Flatkey

Используйте переменную окружения:

Вы должны увидеть flatkey в списке навыков. Если вы установили навык во время работающей сессии Claude Code, а он не отображается, перезапустите Claude Code. Claude Code может обнаруживать многие изменения навыков во время сессии, но перезапуск — это самый простой способ убрать неоднозначность во время настройки.
Теперь попросите выполнить первую безвредную задачу:
Use the flatkey skill. Verify that FLATKEY_API_KEY is available without printing it, fetch the live model catalog from Flatkey, and summarize the first five text-capable model IDs you see. Do not run a generation yet.
Это проверяет обнаружение без расходования бюджета на генерацию.
Шаг 4: Получите актуальный каталог моделей
Навык Flatkey instructs Claude Code to fetch the live model catalog before selecting a model. The direct command is:
curl -fsS https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $FLATKEY_API_KEY"
Для реального рабочего процесса попросите Claude Code выбирать только из возвращённых идентификаторов:
Use the flatkey skill. Fetch the live model catalog, choose one low-cost text model returned by the catalog for a one-sentence smoke test, and explain why you chose it before running the request.
Это позволяет избежать распространённой ошибки агента: использовать имя модели из памяти или из старой статьи. Каталог — это источник истины о том, что ваш ключ может вызвать в данный момент.
Шаг 5: Выполните маленький пробный вызов, совместимый с OpenAI
Когда каталог вернётся, выполните небольшой запрос через OpenAI-совместимый API Flatkey:
curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "replace-with-a-model-id-from-the-live-catalog",
    "messages": [
      {
        "role": "user",
        "content": "Reply with one sentence: Flatkey smoke test passed."
      }
    ],
    "max_tokens": 40
  }'
Пусть первый вызов будет скучным. Вы проверяете аутентификацию, ID модели, базовый URL, форму ответа и видимость в журнале. Оставьте длинные контекстные запросы, вызовы инструментов, генерацию изображений и пакетные задания на потом, когда базовый путь заработает.
Шаг 6: Позвольте Claude Code вызывать любую поддерживаемую модель из задачи
После успешного пробного теста вы можете попросить Claude Code направлять работу к модели, которая подходит для задачи.
Например:
Use the flatkey skill. I need a second-model review of this function. Fetch the live catalog, select a coding-capable model returned by the catalog, run a small review request through Flatkey, and report the model ID, request result, and any request ID or usage fields returned. Do not print secrets.
Или:
Use the flatkey skill. Compare two Flatkey-supported text models on this prompt. Keep both calls under 200 output tokens. Show the outputs side by side and tell me which one I should use for this low-risk internal summarization task.
Это и есть паттерн «любой модели», который хорошо работает с Claude Code: Claude Code координирует задачу, читает файлы, учитывает контекст репозитория и использует Flatkey как контролируемый внешний маршрут к модели, когда полезна вторая модель или другая семейство моделей.
Для выбора модели в продакшене сочетайте это с руководством по каталогу моделей ИИ, чтобы Claude Code перед рекомендацией маршрута проверял тип эндпоинта, единицу тарификации, доступность и статус верификации.
Шаг 7: Используйте инструменты Flatkey только после проверки
SKILL.md от Flatkey также охватывает инструменты с тарификацией по использованию. Важное правило: Claude Code должен изучить инструмент перед запуском. Он не должен придумывать ID инструментов, обязательные поля, цены, имена провайдеров или единицы биллинга.
Хороший первый запрос:
Use the flatkey skill. Open the Flatkey tools marketplace in the browser, inspect the search-related tools available to my account, and summarize the required fields and billing unit for one candidate tool. Do not execute the tool yet.
Затем, когда будете готовы:
Use the flatkey skill. Run the inspected tool with a small limit and an idempotency key. Before execution, repeat the exact tool, required fields, expected billing unit, and maximum budget for my approval.
Это позволяет Claude Code быть полезным, не давая агенту уйти в неконтролируемые платные вызовы.
Шаг 8: При необходимости направляйте трафик Claude Code Claude через Flatkey
Настройка SKILL.md — это не то же самое, что маршрутизация самого Claude Code через шлюз. Если ваша цель — пропускать запросы Claude Code к семейству Claude через Flatkey, настройте Claude Code как клиент шлюза в формате Anthropic:
export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"
Для этого пути не используйте завершающий /v1. Claude Code и Anthropic SDK добавят нужный маршрут. После установки переменных запустите Claude Code из той же оболочки и выполните:
/status
Ищите базовый URL Anthropic и источник учетных данных. Затем отправьте короткий запрос и проверьте журналы использования Flatkey Usage Logs. Если базовый URL не отображается, Claude Code не получил переменную окружения.
Используйте этот путь, когда хотите, чтобы использование Claude Code Claude попадало в баланс и ledger Flatkey. Используйте путь через skill, когда хотите, чтобы Claude Code вызывал поддерживаемые Flatkey модели и инструменты из вашего репозитория.
Для смежных решений по маршрутизации см. маршрутизацию Claude vs GPT API. Если ваш сценарий — это агент, который вызывает внешние инструменты, чеклист Gemini API для ИИ-агентов полезен даже при смене семейства моделей, потому что контрольные меры похожи: точные ID моделей, ограниченные повторы, валидация инструментов и проверка использования.
Распространенные ошибки
Ошибка 1: Предполагать, что SKILL.md меняет «мозг» Claude Code
Нет. Навык даёт Claude Code повторно используемые инструкции и процедуры. Он не превращает собственный агентный цикл Claude Code в GPT, Gemini, DeepSeek, Qwen или другую модель.
Ошибка 2: использование /v1 с ANTHROPIC_BASE_URL
Базовый URL Flatkey, совместимый с OpenAI, выглядит так:
https://router.flatkey.ai/v1
Маршрутизация через шлюз Claude Code использует:
https://router.flatkey.ai
Держите их отдельно.
Ошибка 3: коммит учётных данных в настройках Claude
Проектный .claude/settings.json обычно распространяется вместе с репозиторием. Не помещайте туда ключи. Используйте экспорт в shell, vault или .claude/settings.local.json только если ваш репозиторий его игнорирует и ваша команда принимает такой локальный рабочий процесс.
Ошибка 4: позволять агенту угадывать идентификаторы моделей
Всегда сначала запрашивайте /v1/models. Если идентификатора модели нет в живом ответе каталога для вашего ключа, не используйте его.
Ошибка 5: запуск платных инструментов до их проверки
Для Flatkey Tools сначала проверьте обязательные поля, примеры, единицу биллинга и точную цену. Затем используйте ключ идемпотентности и запросите одобрение перед выполнением.
Чек-лист настройки, который можно скопировать
Используйте этот чек-лист для одной машины разработчика:
# 1. Установите навык Flatkey для Claude Code
mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o ~/.claude/skills/flatkey/SKILL.md

# 2. Проверьте его
sed -n '1,200p' ~/.claude/skills/flatkey/SKILL.md

# 3. Экспортируйте свой ключ Flatkey
export FLATKEY_API_KEY="sk-fk-your-key"

# 4. Запустите Claude Code
claude
Затем введите запрос:
Use the flatkey skill. Confirm the Flatkey skill is loaded, verify that FLATKEY_API_KEY is available without printing it, fetch the live model catalog, and run one tiny chat-completions smoke test through https://router.flatkey.ai/v1 using a model ID returned by the catalog.
После вызова откройте Flatkey Usage Logs и подтвердите, что запрос отображается с ожидаемой моделью, статусом, количеством токенов, задержкой и стоимостью.
FAQ
Может ли Claude Code использовать любую модель через SKILL.md?
Сам Claude Code по-прежнему работает на Claude. Настройка SKILL.md позволяет Claude Code обнаруживать и вызывать поддерживаемые Flatkey модели и инструменты из вашего проекта, так что задача при необходимости может использовать другие модели через API Flatkey.
Это то же самое, что изменить ANTHROPIC_BASE_URL?
Нет. ANTHROPIC_BASE_URL=https://router.flatkey.ai направляет трафик Claude Code семейства Claude через шлюз. Установка https://flatkey.ai/SKILL.md учит Claude Code тому, как работать с API и инструментами Flatkey во время выполнения задачи.
Стоит ли устанавливать навык Flatkey глобально или в репозиторий?
Используйте ~/.claude/skills/flatkey/ для личного использования в разных проектах. Используйте .claude/skills/flatkey/, когда репозиторий должен содержать общий командный рабочий процесс. Коммитите только проверенный файл навыка, никогда не добавляйте учетные данные.
Почему руководство сначала запрашивает /v1/models?
Потому что доступность моделей меняется. Актуальный каталог Flatkey безопаснее, чем название модели, скопированное по памяти, из ответа в чате или из старого документа.
Что следует проверить после настройки?
Проверьте три вещи: Claude Code видит навык, запрос к каталогу Flatkey выполняется успешно, а в Usage Logs отображается пробный запрос с моделью, статусом, токенами, задержкой и стоимостью.
Официальные ссылки

Flatkey SKILL.md: https://flatkey.ai/SKILL.md
Flatkey quickstart: https://docs.flatkey.ai/quickstart.md
Flatkey Claude Code guide: https://docs.flatkey.ai/guides/claude-code.md
Flatkey OpenAI SDK guide: https://docs.flatkey.ai/guides/openai-sdk.md
Anthropic Claude Code skills: https://code.claude.com/docs/en/skills
Anthropic Claude Code gateway docs: https://docs.anthropic.com/en/docs/claude-code/llm-gateway.md
Anthropic gateway connection guide: https://docs.anthropic.com/en/docs/claude-code/llm-gateway-connect.md
Anthropic Agent Skills overview: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview