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

> AI Release · @ai_release1 · https://ai-release.org/guides/kak-podklyuchit-lokalnuyu-model-k-claude-code-llama-ser.html

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

## Требования и подготовка
![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/kak-podklyuchit-lokalnuyu-model-k-claude-code-llama-ser-ru-1.jpg)


- Компьютер с 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`) — администратор обычно не нужен.

Если вы раньше вообще не запускали модели на своём компьютере, начните с общего материала: [Как запустить ИИ-модель локально на своём компьютере: гайд для начинающих](https://ai-release.org/guides/kak-zapustit-ii-model-lokalno-na-svoem-kompyutere-gayd.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

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

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

## Пошаговая инструкция
![Иллюстрация к разделу «Пошаговая инструкция»](https://ai-release.org/guides/img/kak-podklyuchit-lokalnuyu-model-k-claude-code-llama-ser-ru-2.jpg)


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

```bash
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. Запустите сервер:

```bash
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, поэтому клиентов менять не нужно.

```bash
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. Посмотрите список моделей:

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

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

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

```bash
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`:

```bash
#!/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
```

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

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

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

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

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

## Возможные проблемы и решения
![Иллюстрация к разделу «Возможные проблемы и решения»](https://ai-release.org/guides/img/kak-podklyuchit-lokalnuyu-model-k-claude-code-llama-ser-ru-3.jpg)


**Симптом: `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 для команды: как настроить субагентов и общий ИИ-суперагент](https://ai-release.org/guides/claude-code-dlya-komandy-kak-nastroit-subagentov-i-obsc.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

**Можно ли запускать локальную модель на телефоне?**
Технически да, но это отдельная история с приложениями и ограничениями мобильного железа — см. [Как запустить ИИ-модель локально на Android: приложения и настройка](https://ai-release.org/guides/kak-zapustit-ii-model-lokalno-na-android-prilozheniya-i.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).