Claude Code с локальной моделью через Ollama: настройка и возврат в облако

Claude Code умеет работать с локальной моделью через Anthropic-compatible API Ollama. Но обычный ответ в чате еще не означает, что модель годится для задач coding-агента. Сначала проверьте три вещи: модель должна поддерживать tool calls, компьютер — удерживать context не меньше 64k, а сама задача — разбиваться на небольшой объем изменений с понятной проверкой.

Ниже — обратимый сценарий. Мы подключим qwen3.5 официальным способом Ollama, дадим Claude Code тест на один файл, проверим, где действительно выполняется inference, разберем границы совместимости и затем уберем локальный override перед возвратом в облако. Команды написаны для Bash в macOS, Linux или WSL. Это инструкция для самостоятельной проверки, а не заявление о тесте, выполненном на вашем железе.

Сначала решите, что запускать локально, а что оставить облаку

Локальная модель лучше всего подходит для ограниченной задачи, результат которой можно проверить командой и diff. Большой monorepo, межсервисная миграция или сложное расследование обычно выигрывают от облачной модели сильнее, чем от попытки заставить небольшую локальную модель работать с постоянным CPU offload.

Задача	С чего начать	Почему
Исправление одного файла, один новый тест, разбор локальной функции	С локальной модели	Контекст ограничен, результат виден по команде и diff
Небольшой или средний модуль с понятными зависимостями	Локально или в гибридном режиме	Сначала пройдите smoke test, затем расширяйте область
Большой monorepo, рефакторинг нескольких сервисов, сложная отладка	С облака	Нужны более надежное планирование tools и больший эффективный context
Модель не удерживает 64k без значительного CPU offload	С облака	Задержки и зависания убирают практический смысл локального запуска
Нужны prompt caching, Batches API, PDF-блоки или точный подсчет tokens	С облака	Ollama сейчас реализует только часть Anthropic Messages API
Код нельзя передавать удаленной модели	Локально, с отключением cloud-функций	Отдельно проверьте web tools, MCP servers и сетевое поведение shell-команд

Рабочая гибридная схема выглядит так: локально выполняются небольшие изменения с повторяемой проверкой, а задачи на весь репозиторий, неподдерживаемые API-возможности и случаи повторных ошибок переводятся в облако явно. Клиент остается один, но локальный и облачный backend не объявляются одинаковыми.

Шаг 1. Выберите модель с tools и выделите context 64k

Claude Code недостаточно обычной генерации текста. Модель должна стабильно создавать tool calls, чтобы клиент мог читать файлы, применять изменения и запускать команды. На странице Qwen3.5 в Ollama указана поддержка tools и приведена команда запуска Claude Code. Возможности именно скачанного тега можно дополнительно проверить через API model details.

Скачайте модель и посмотрите поле capabilities:

ollama pull qwen3.5

curl http://localhost:11434/api/show \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.5"}'

До следующего шага убедитесь, что в capabilities есть tools. Если его нет, не подменяйте проверку обычным ответом модели. Выберите в актуальной библиотеке Ollama модель, для которой явно заявлены tools, скачайте ее и повторите запрос.

Второй порог — context. В документации Ollama по context length для web search, agents и coding tools рекомендуется не меньше 64 000 tokens; увеличение context требует больше памяти. В приложении Ollama установите slider context length на 64000 или выше. Если сервер запускается из shell, сначала остановите текущий экземпляр, затем оставьте в отдельном терминале:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Этот терминал должен оставаться открытым. Дождитесь запуска сервера и продолжайте во втором терминале. Если порт уже занят, значит Ollama уже работает: измените context у существующего процесса, а не запускайте второй.

Шаг 2. Запустите Claude Code через официальную интеграцию Ollama

Самый короткий официальный путь:

ollama launch claude --model qwen3.5

Так проще всего получить рабочую конфигурацию. После запуска выполните /status в Claude Code и запомните, какие settings sources загружены. Если позже клиент продолжит ходить в Ollama после переключения на облако, эта информация покажет, где остался постоянный override.

Чтобы изменения жили только в текущем терминале, задайте переменные вручную. Это по-прежнему Bash:

read -rs ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL="http://localhost:11434"
claude --model qwen3.5

read -rs принимает ввод без отображения на экране. Введите ollama и нажмите Enter. Совместимый endpoint Ollama требует наличия переменной авторизации, но локальный сервер не проверяет ее значение. ANTHROPIC_BASE_URL направляет запросы модели на локальный Ollama, а --model qwen3.5 фиксирует модель теста и не оставляет результат на усмотрение старого ANTHROPIC_MODEL или сохраненного default.

Шаг 3. Проверьте чтение, правку и запуск команды на одном файле

Не используйте рабочий репозиторий для первого теста локальной модели. Создайте отдельную директорию, где результат можно увидеть по файлу, exit status и diff.

mkdir -p claude-ollama-smoke
cd claude-ollama-smoke
git init
cat > total.py <<'PY'
def total(values):
    return sum(values)

if __name__ == "__main__":
    assert total([2, 3]) == 5
PY
git add total.py
python3 total.py

python3 total.py должен завершиться с кодом 0 и без вывода. Запустите локальный Claude Code из этой директории и передайте задачу:

Измени только total.py.
Если среди values есть элемент, который не является int или float, функция total должна выбросить TypeError с точным текстом numbers only.
В __main__ добавь проверку для [2, "3"], которая подтверждает тот же TypeError и тот же текст.
Запусти python3 total.py.
Не меняй другие файлы. В конце покажи diff.

Задача маленькая намеренно, но она проверяет главный цикл coding-агента: прочитать файл, спланировать изменение, вызвать инструмент редактирования, запросить Bash-команду, увидеть результат и показать итоговый diff. Не отключайте permission prompts Claude Code. Локальная модель не делает неограниченное выполнение shell безопасным.

После ответа самостоятельно выполните:

python3 total.py
git status --short
git diff -- total.py
ollama ps

Критерии приемки:

1. python3 total.py завершается с кодом 0.
2. git status --short упоминает только total.py, а git diff -- total.py содержит только требуемую проверку типа и assertion.
3. В диалоге Claude Code видны вызовы файловых и Bash tools или запросы разрешений, а не только текстовый совет с кодом.
4. Пока выполняется задача, ollama ps показывает qwen3.5, значение CONTEXT не ниже 64000, а PROCESSOR показывает полный GPU, частичный offload или преимущественно CPU.

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

Шаг 4. Проверяйте границу выполнения, а не только localhost

ANTHROPIC_BASE_URL=http://localhost:11434 показывает, что запрос модели отправляется на локальный порт, но не доказывает, что весь процесс офлайн. Более сильный набор признаков: тег модели без :cloud, наличие модели в ollama ps во время задачи и локальные значения PROCESSOR и CONTEXT, соответствующие ресурсам вашего компьютера.

В FAQ Ollama сказано, что при локальном запуске Ollama не получает prompts и данные, а для cloud-hosted models prompts и responses обрабатывает облачный сервис. На текущей странице Qwen3.5 команда для Claude Code использует локальный тег qwen3.5. Не выводите имя облачной модели простым добавлением суффикса к локальному тегу; для проверки облачной границы используйте тег, который прямо указан в актуальном официальном каталоге Cloud или руководстве по интеграции, например gemma4:cloud. Фактическое место выполнения определяйте по действительному тегу, ollama ps и локальному распределению ресурсов.

Отдельно проверьте другие сетевые пути:

• Bash-команда, которую вызывает модель, может обращаться в сеть, загружать файл или запускать другой CLI.
• MCP server имеет собственный процесс, права и маршрут данных.
• Web search, web fetch и cloud models Ollama не являются локальным inference.
• Hooks репозитория, тестовые скрипты и package manager тоже могут подключаться к внешним сервисам.

Для более строгого local-only режима добавьте следующий ключ в существующий ~/.ollama/server.json, не удаляя другие настройки:

{
  "disable_ollama_cloud": true
}

Перезапустите Ollama и проверьте в логах строку Ollama cloud disabled: true. По документации это отключает cloud models и web search Ollama. Но такая настройка не контролирует сетевые обращения Claude Code, MCP servers и shell-команд.

Шаг 5. Учитывайте реальную границу совместимости

Ollama предоставляет слой совместимости с Anthropic Messages API, а не полную реализацию Anthropic API. В текущей документации среди поддерживаемых возможностей перечислены messages, streaming, system prompts, images, tool calls, tool results и thinking. Этого достаточно для базового цикла Claude Code.

Поддержка протокола не означает одинаковое поведение моделей. Качество выбора tools, точность patch, устойчивость длинной задачи и соблюдение инструкции зависят от конкретной модели, quantization, выделенного context и железа. Успешный тест на одном файле подтверждает только минимальный путь в вашей среде, но не равен паритету с облачной моделью Claude на большом репозитории.

Сейчас Ollama относит к неподдерживаемым /v1/messages/count_tokens, prompt caching, Batches API, citations, PDF-блоки document и server-sent errors в streaming. Token counts описаны как приближенные значения по tokenizer базовой модели. Если процесс зависит от одной из этих функций, облачный маршрут лучше оставить заранее, а не обнаруживать ограничение посреди работы.

Шаг 6. Вернитесь в облако явно

Если локальные переменные заданы только в текущей Bash-сессии, завершите Claude Code и выполните:

unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY ANTHROPIC_MODEL ANTHROPIC_DEFAULT_HAIKU_MODEL ANTHROPIC_DEFAULT_SONNET_MODEL ANTHROPIC_DEFAULT_OPUS_MODEL
claude

Новый процесс сможет использовать обычный вход в аккаунт или вашу облачную конфигурацию. После запуска проверьте /status и задайте один небольшой read-only вопрос. Сам факт запуска клиента еще не подтверждает, что облачный запрос прошел.

Если Claude Code по-прежнему обращается к Ollama, override, скорее всего, записан не в текущем shell, а в settings. Официальная документация Claude Code говорит, что значение из env в settings file перекрывает одноименную переменную shell. Посмотрите active sources через /status и удалите локальные ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY и model override из нужного уровня:

• ~/.claude/settings.json
• .claude/settings.json
• .claude/settings.local.json
• managed settings организации

После правки полностью завершите и снова запустите Claude Code. Значение из managed settings нельзя перекрыть нижним уровнем — его должен изменить администратор.

Если локальная модель не подходит, но вы хотите оставить Anthropic-compatible облачный API в том же Claude Code, используйте актуальную инструкцию BetterToken для Claude Code. Текущий Base URL — https://bettertoken.ai: без www и без /v1. Сначала скопируйте точный Model ID из model plaza. В текущей ручной настройке ANTHROPIC_MODEL задаёт основную модель, а три переменные ANTHROPIC_DEFAULT_*_MODEL сопоставляют псевдонимы Haiku, Sonnet и Opus. Для контролируемой проверки можно сначала направить все четыре переменные на один и тот же точный ID. Временная Bash-сессия настраивается без записи API Key в историю:

read -rsp "BetterToken API Key: " ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
read -rp $'\nBetterToken Model ID: ' ANTHROPIC_MODEL
export ANTHROPIC_MODEL
export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
export API_TIMEOUT_MS="3000000"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"
claude

Первый запрос скрывает ввод API Key; во втором вставьте точный Model ID, скопированный из model plaza. В этой проверке основная модель и три псевдонима направлены на один ID. Если для разных ролей действительно нужны разные модели, задайте каждой default-переменной свой точный ID. Не добавляйте /v1 к Base URL. После изменения постоянных settings полностью завершите и перезапустите Claude Code; для временной сессии также закройте старый процесс перед запуском этого блока. Затем отправьте один короткий read-only запрос. Переключение подтверждено только при обычном ответе без 401, ошибки соединения или модели и при ожидаемом active source в /status; это не означает полного совпадения функций локального и облачного маршрута.

Типовые ошибки и порядок проверки

ConnectionRefused или нет ответа от localhost:11434

Проверьте, запущен ли процесс Ollama и используется ли нужный порт. При необходимости выполните ollama serve. Если порт занят, найдите уже работающий экземпляр вместо второго запуска. Перед повторным стартом Claude Code убедитесь, что curl http://localhost:11434/api/ps возвращает JSON.

Чат отвечает, но Claude Code не читает и не меняет файлы

Снова вызовите /api/show и убедитесь, что у модели есть tools. Затем посмотрите, появляются ли permission prompts Claude Code. Если модель только пишет «можно изменить код так», но не создает tool call, выберите модель с явно заявленной поддержкой tools. Наличие поля в протоколе не гарантирует стабильное планирование tools каждой моделью.

Сессия очень медленная или теряет context на длинной задаче

Запустите ollama ps и посмотрите PROCESSOR и CONTEXT. Значительный CPU offload, context ниже 64k или постоянная нехватка памяти — повод сузить задачу, выбрать меньшую модель с tools или перейти в облако. Не убирайте permission и проверки только ради ощущения скорости.

Изменение shell не меняет endpoint или модель

Выполните /status в Claude Code. Значение env из settings file может заменить переменную shell, а --model и /model имеют приоритет над ANTHROPIC_MODEL. Очистите источник, который действительно побеждает по приоритету, полностью перезапустите клиент и повторите read-only запрос.

Практическое правило выбора

Считайте локальный Claude Code отдельным исполняемым маршрутом, которому нужно доказать готовность к большей задаче. Проверьте tools, выделите context не меньше 64k и на одном файле посмотрите tool calls, exit status, diff и ollama ps. Увеличивайте область только после стабильного результата.

Если задача превышает возможности компьютера, требует неподдерживаемой функции Anthropic или локальная модель снова и снова ошибается на реальном коде, удалите локальный endpoint и явно вернитесь в облако. Надежный путь отката полезнее, чем попытка любой ценой выполнять локально каждую coding-задачу.