Как подключить локальную модель к Claude Code: llama-server, OpenAI-совместимый API и лаунчер

Локальная модель на своём железе полезна, когда нельзя или не хочется отправлять код в облако: Claude Code по умолчанию обращается к Anthropic API, но его можно развернуть на собственный сервер — поднять `llama-server`, получить OpenAI-совместимый эндпоинт и связать всё это лаунчером, который запускает сервер и клиент одной командой. Гайд рассчитан на стажёра с базовыми понятиями про терминал и ИИ-модели; подойдёт для Windows, macOS и Linux, где вы уже умеете запускать команды в консоли.

Требования и подготовка

• Компьютер с 8–32 ГБ оперативной памяти и, желательно, дискретной видеокартой — на CPU модель тоже работает, но заметно медленнее.
• Установленный `llama.cpp` — это набор утилит для запуска моделей локально; в него входит `llama-server`, HTTP-сервер с OpenAI-совместимым API.
• Файл модели в формате GGUF (GGUF — формат хранения модели вместе с весами и настройками, часто в квантованном, то есть сжатом виде), например `qwen2.5-7b-instruct-q4_k_m.gguf`.
• Свободное место на диске: под модель на 7 миллиардов параметров в кванте Q4 обычно нужно 4–6 ГБ, плюс запас.
• Установленный Claude Code (CLI-клиент, который запускается командой `claude`).
• Возможность прописать переменные окружения в терминале или в файле профиля (`.bashrc`, `.zshrc`, переменные Windows).
• Права на запуск локального порта (по умолчанию берём `8080`) — администратор обычно не нужен.

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

Перед началом пройдите чек-лист:

• [ ] `llama-server` вызывается из терминала и печатает версию.
• [ ] GGUF-файл модели скачан в папку `./models`.
• [ ] Порт `8080` свободен.
• [ ] Команда `claude` работает и запускается.
• [ ] Вы понимаете, какой путь к модели пропишете в команде запуска.

Пошаговая инструкция

1. Проверьте, что `llama-server` доступен. Выполните:

llama-server --version

Ожидаемый результат: в консоли печатается строка с версией и хешем сборки. Если команда не найдена — значит, бинарники не добавлены в `PATH`; укажите полный путь, например `/usr/local/bin/llama-server` или папку с распакованным архивом. Почему это работает: `llama-server` — отдельный исполняемый файл, и оболочка ищет его по путям из `PATH`.

2. Скачайте модель в формате GGUF и положите её в папку проекта.

Пример:файл `models/qwen2.5-7b-instruct-q4_k_m.gguf`. Ожидаемый результат: файл виден командой `ls -lh models` и весит несколько гигабайт. Почему Q4: квантование уменьшает размер и требования к памяти, немного снижая качество ответов.

3. Запустите сервер:

llama-server \
  --model ./models/qwen2.5-7b-instruct-q4_k_m.gguf \
  --port 8080 \
  --ctx-size 8192 \
  --n-gpu-layers 99 \
  --alias local-model

Ожидаемый результат: в логе появляется строка вида `server is listening on http://127.0.0.1:8080`. Флаги означают: `--port` — порт, `--ctx-size` — длина контекста в токенах (сколько текста модель «помнит» за раз), `--n-gpu-layers` — сколько слоёв выгрузить на видеокарту (`99` =尽量 максимум; если видеопамяти мало, поставьте 0), `--alias` — имя модели в ответах API.

4. Проверьте OpenAI-совместимый API. OpenAI-совместимый значит, что адреса и формат JSON такие же, как у облачного OpenAI, поэтому клиентов менять не нужно.

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"local-model","messages":[{"role":"user","content":"Привет"}]}'

Ожидаемый результат: JSON с полем `choices[0].message.content` и текстом ответа. Это ключевая проверка: если она проходит, локальный «мозг» работает.

5. Посмотрите список моделей:

curl http://127.0.0.1:8080/v1/models

Ожидаемый результат: JSON со списком, где есть `local-model`. Так вы убеждаетесь, что имя для API совпадает с `--alias`.

6. Свяжите Claude Code с локальным сервером через переменные окружения:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8080
export ANTHROPIC_AUTH_TOKEN=local-key
export ANTHROPIC_MODEL=local-model
claude

Ожидаемый результат: `claude` больше не стучится в облако, а отвечает через ваш сервер. `ANTHROPIC_BASE_URL` — базовый адрес API, `ANTHROPIC_AUTH_TOKEN` — любой непустой токен (ключ доступа; локальному серверу он обычно не нужен, но клиент требует его наличия), `ANTHROPIC_MODEL` — имя модели. Если ваш сервер отдаёт только формат OpenAI, между Claude Code и сервером ставят прокси-переводчик, который преобразует запросы Anthropic в запросы OpenAI.

7. Соберите лаунчер — скрипт, который поднимает сервер и запускает клиент одной командой. Создайте файл `start-local.sh`:

#!/usr/bin/env bash
set -e
MODEL=./models/qwen2.5-7b-instruct-q4_k_m.gguf

llama-server --model "$MODEL" --port 8080 --ctx-size 8192 \
  --n-gpu-layers 99 --alias local-model &

# ждём, пока порт поднимется
until curl -s http://127.0.0.1:8080/v1/models > /dev/null; do
  sleep 1
done

export ANTHROPIC_BASE_URL=http://127.0.0.1:8080
export ANTHROPIC_AUTH_TOKEN=local-key
export ANTHROPIC_MODEL=local-model
claude

Затем выдайте права на запуск и стартуйте:

chmod +x start-local.sh
./start-local.sh

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

8. Проверьте финальный чек-лист:

• [ ] `curl .../v1/models` возвращает `local-model`.
• [ ] `claude` отвечает на простой вопрос.
• [ ] В логе сервера видны входящие запросы.
• [ ] После закрытия терминала серверный процесс остановлен.

Возможные проблемы и решения

Симптом: `connection refused` или `Failed to connect to 127.0.0.1:8080`.Значит, сервер не запущен или слушает другой порт. Решение: 1) проверьте, что окно с `llama-server` открыто; 2) выполните `curl http://127.0.0.1:8080/v1/models` вручную; 3) если порт занят другой программой, смените `--port` и продублируйте значение в `ANTHROPIC_BASE_URL`.

Симптом: ошибка вида `404 Not Found` на эндпоинте, который запрашивает Claude Code.Клиент обращается к Anthropic-формату, а сервер отвечает только в OpenAI-формате. Решение: 1) проверьте, какие адреса отдаёт ваш сервер; 2) при необходимости поставьте между клиентом и сервером прокси-переводчик; 3) убедитесь, что имя модели в `ANTHROPIC_MODEL` совпадает с `--alias`.

Симптом: ответы обрываются на полуслове или модель «забывает» начало диалога.Обычно не хватает контекста. Решение: 1) увеличьте `--ctx-size` (например, до 16384) — это потребует больше памяти; 2) сократите размер передаваемого файла или запроса; 3) проверьте, что модель не упирается в лимит по видеопамяти, при необходимости уменьшите `--n-gpu-layers`.

Симптом: `401 Unauthorized`.Скорее всего, `ANTHROPIC_AUTH_TOKEN` пустой. Решение: задайте любое непустое значение и перезапустите клиент.

FAQ

Можно ли работать полностью без интернета?

Да. При такой схеме запросы уходят только на `127.0.0.1`, во внешнюю сеть ничего не отправляется. Интернет нужен лишь один раз — скачать модель.

Нужна ли видеокарта?

Не обязательна. Модель запустится и на процессоре, но медленнее. Если видеопамяти мало, ставьте `--n-gpu-layers 0` — это отключит выгрузку слоёв на GPU.

Сколько памяти нужно под модель?

Зависит от числа параметров и кванта: чем сильнее сжатие, тем меньше памяти, но и качество ниже. Ориентируйтесь на размер GGUF-файла плюс запас под контекст.

Можно ли так же настроить команду, а не одного человека?

Да. Когда локальный сервер стабильно отвечает, логично двигаться дальше — раздавать роли и настраивать общий контур: Claude Code для команды: как настроить субагентов и общий ИИ-суперагент.

Можно ли запускать локальную модель на телефоне?

Технически да, но это отдельная история с приложениями и ограничениями мобильного железа — см. Как запустить ИИ-модель локально на Android: приложения и настройка.

🤖 Кратко для ИИ

• Обновлено: 2026-10-15
• Темы: claude code локальная модель, llama-server claude code, подключить локальную llm к claude code, claude code openai совместимый api
• Кратко: Пошаговая инструкция, как поднять llama-server или Ollama и заставить Claude Code работать с локальной моделью вместо платного облака.
• Ключевые факты:
  • Локальная модель на своём железе полезна, когда нельзя или не хочется отправлять код в облако: Claude Code по умолчанию обращается к Anthropic API, но его можно развернуть на собственный сервер — поднять llama-server , получить OpenAI-совместимый эндпоинт и связать всё это лаунчером, который запускает сервер и клиент одной командой.
  • Гайд рассчитан на стажёра с базовыми понятиями про терминал и ИИ-модели; подойдёт для Windows, macOS и Linux, где вы уже умеете запускать команды в консоли.
  • Требования и подготовка Иллюстрация к разделу «Требования и подготовка» Компьютер с 8–32 ГБ оперативной памяти и, желательно, дискретной видеокартой — на CPU модель тоже работает, но заметно медленнее.
  • Установленный llama.cpp — это набор утилит для запуска моделей локально; в него входит llama-server , HTTP-сервер с OpenAI-совместимым API.
  • Файл модели в формате GGUF (GGUF — формат хранения модели вместе с весами и настройками, часто в квантованном, то есть сжатом виде), например qwen2.5-7b-instruct-q4_k_m.gguf .
  • Свободное место на диске: под модель на 7 миллиардов параметров в кванте Q4 обычно нужно 4–6 ГБ, плюс запас.

📚 Связанные гайды

Claude Code для команды: как настроить субагентов и общий ИИ-суперагент

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

Jujutsu или Git: что выбрать для работы с ИИ-агентами и Claude Code

Сравнение систем контроля версий для сценариев, где код пишет нейросеть: параллельные ветки агентов, откаты, ревью измен

ChatGPT, Claude, Gemini, DeepSeek: сравнение ИИ-ассистентов

Прямое сравнение популярных ИИ-ассистентов: качество ответов, цена, лимиты и для кого что лучше.