OpenClaw с локальной Ollama: как подключить модель и проверить вызов инструмента

Что здесь означает «локально»?

В этом сценарии OpenClaw — приложение агента, а Ollama — сервер выбранной модели на той же машине. Документация OpenClaw описывает режим Local only отдельно от Cloud only и Cloud + Local. Даже когда Ollama работает на 127.0.0.1, другие включённые у агента инструменты, каналы, плагины или поиск могут обращаться в сеть: локальный адрес одного API не является доказательством офлайн-работы всего стека s1s2s5. Если задача — закрытый контур, после настройки проведите отдельный сетевой тест, а не полагайтесь на название провайдера.

OpenClaw использует нативный маршрут Ollama /api/chat. В baseUrl нужен адрес хоста без /v1, например http://127.0.0.1:11434; в документации прямо предупреждают, что OpenAI-compatible /v1 может сломать tool calling и выдать JSON вызова обычным текстом s1. Сервер модели, клиент агента и инструмент чтения файла — три разных звена. По описанию Ollama модель предлагает вызов; приложение решает, исполнять ли его и как вернуть результат модели s7.

Что подготовить до настройки OpenClaw?

На машине должны быть установлены Ollama и OpenClaw, совместимые с вашей ОС и версиями их документации. Для начала возьмите пустую рабочую папку без ключей, чужих документов и доступа к production. Руководство по установке Ollama отдельно разбирает локальный API. Не устанавливайте скрипт из интернета только потому, что он попал в пример; проверьте источник и политику собственной машины. Ни установка, ни скачивание весов в этой статье Modelium не выполнялись.

В официальном локальном рецепте OpenClaw примером служит тег gemma4. Сначала оцените свободное место, память и нужный контекст по характеристикам вашей машины, а затем только при согласии на скачивание выполните ollama pull gemma4. Это загрузка весов по сети; она не является бесплатным тестом по времени или диску. Здесь нет утверждения, что тег влезет на любой компьютер либо что он точно справится с агентной задачей: пригодность проверяется отдельно s3s8. Для иной модели заменяйте тег одновременно в Ollama и OpenClaw, не переводя размер файла в минимальную RAM/VRAM.

Если Ollama уже запущена системой или приложением, второй ollama serve не нужен. Проверьте локальный адрес и список тегов до работы агента s3s6:

curl -fsS http://127.0.0.1:11434/api/tags
ollama list
# Только после проверки ресурсов и выбора модели:
ollama pull gemma4

Первый запрос должен вернуть доступный ответ сервера; ollama list после загрузки — содержать точный тег. Если список есть, но модель не отвечает на реальный запрос, проверка ещё не пройдена. Наличие весов на диске не является доказательством достаточной рабочей памяти или поддержки инструментов s3s6s8.

Как связать локальную модель с OpenClaw без облачного fallback?

По официальному мастеру выполните openclaw onboard, выберите Ollama → Local only, укажите адрес локального сервера и установленную модель. Не выбирайте Cloud + Local и не оставляйте облачный fallback, если хотите тестировать исключительно локальный маршрут. Мастер может предложить скачать модель, если не найдёт подходящей: сначала проверьте размер, права и доступность ресурсов на своём хосте s2. Если уже настроен другой профиль, не переписывайте его молча — используйте отдельный тестовый профиль или сверяйте реальную конфигурацию до переключения.

После настройки подтвердите, что активная модель совпадает с локальным тегом, а не только красиво отображается в интерфейсе s2s3:

openclaw models list --provider ollama
openclaw models set ollama/gemma4
openclaw models status

Команда models set меняет выбранную модель в конфигурации пользователя; запускайте её только если согласны переключить текущий профиль. При ручном подключении используйте baseUrl: "http://127.0.0.1:11434" и api: "ollama", без /v1. Локальный хост не требует настоящего облачного API-ключа; маркер ollama-local в документации нужен для обнаружения/настройки, не делает сервер защищённым от других процессов на том же хосте s1s2s6.

Для отдельного узкого smoke-теста модели, без полного агентного набора инструментов, OpenClaw приводит openclaw infer model run --model ollama/gemma4 --prompt "Reply with exactly: ok" s3. Если здесь нет ответа, не переходите к тесту инструмента. Если ответ есть, это подтверждает лишь маршрут модели, а не право агента и не способность модели действительно вызвать файловый инструмент.

Как проверить настоящий tool call на безопасном файле?

Для первого теста ограничьте агента одним действием: чтением только файла-маркера в новой пустой папке. Отключите облачные fallbacks, каналы, плагины и доступ к секретам в используемой тестовой конфигурации. Документация OpenClaw рекомендует сочетать allowlist инструментов и ограничения файловой области; одно текстовое «ничего не удаляй» в промпте не является политикой безопасности s4s5. Проверяйте файл конфигурации перед запуском, не наследуйте рабочий профиль с разрешёнными exec, browser, write и внешними сообщениями.

Создайте marker.txt со случайной строкой, неизвестной модели, в отдельной папке. --cwd у agent exec задаёт рабочую область, а --config загружает отдельный проверенный JSON5; параметры описаны в CLI-справке. Пример ниже сужает список доступных инструментов до read; для более строгой изоляции используйте отдельную песочницу или одноразовую машину. Даже ограничение инструментов не является доказательством сетевой изоляции или отсутствия загрузки установленных плагинов s4s5:

mkdir openclaw-smoke
cd openclaw-smoke
node -e 'require("node:fs").writeFileSync("marker.txt", require("node:crypto").randomBytes(12).toString("hex") + "\n")'
cat > local.json5 <<'JSON5'
{
models: { providers: { ollama: {
baseUrl: "http://127.0.0.1:11434", api: "ollama", models: []
} } },
agents: { defaults: { model: { primary: "ollama/gemma4" } } },
tools: { allow: ["read"], deny: ["write", "edit", "apply_patch", "exec", "process", "browser", "gateway", "cron", "sessions_spawn", "sessions_send"] }
}
JSON5
# Просмотрите local.json5; не копируйте сюда ключи или секреты.
OLLAMA_API_KEY=ollama-local openclaw agent exec \
--config "$PWD/local.json5" \
--cwd "$PWD" \
--model ollama/gemma4 \
--code-mode direct \
--json \
'Прочитай marker.txt инструментом read; верни строку дословно.'
# Сравните результат с локальным файлом только после просмотра трассы вызовов.
node -e 'console.log(require("node:fs").readFileSync("marker.txt","utf8").trim())'

Критерий успеха: в журнале или трассе выполнения виден именно вызов read с marker.txt, содержимое совпало с файлом и финальный ответ содержит его случайную строку. Если трасса не показывает tool call, проверка не пройдена, даже при правильном ответе. Успешный API-ответ Ollama без записи о вызове инструмента также недостаточен s4s7.

Это инструкция для читателя, а не демонстрация нашего работающего стенда. Модель может не поддерживать tools, ошибиться в имени инструмента или остановиться на текстовом ответе; не объявляйте её пригодной для автоматизации, пока не проверите трассу и безопасное выполнение. У agent exec заданная конфигурация имеет приоритет над его умолчаниями, поэтому перед стартом проверьте фактический allowlist; отсутствие рабочего --config — повод не запускать тест, а не обходить ограничения s4s5.

Что делать, если каталог видит модель, но вызова нет?

Если curl к /api/tags отвечает, а OpenClaw пишет connection refused, проверьте, откуда работает агент: внутри контейнера 127.0.0.1 означает этот контейнер, не Ollama на хосте. Сверьте baseUrl и доступность API из той же среды, где запущен Gateway или изолированный агент; не открывайте порт наружу без отдельной проверки доступа s6.

Если вместо инструментального события появляется «JSON вызова» в обычном тексте, первым делом уберите /v1 и убедитесь в api: "ollama". Если нативный маршрут исправен, следующий кандидат — модель, которая не справляется со схемой инструмента. Флаг compat.supportsTools: false в официальной инструкции отключает tools и годится для текстового режима, а не исправляет агентную проверку s1s3s6. Сверяйте точное имя тега в ollama list и openclaw models status s3.

Если агент отвечает медленно или завершается по памяти, не назначайте контекст «на глаз»: Ollama предупреждает, что больший контекст увеличивает память. После загрузки модели ollama ps показывает столбцы CONTEXT и PROCESSOR, но не универсальное минимальное требование VRAM. Подробный разбор — в гайде по контексту s8. Для модели и инструментов в одном процессе требуется реальный тест на своём железе, не вывод из размера файла.

Как остановить тест и что делать дальше?

После проверки остановите тестовый процесс и при необходимости локальный сервер способом вашей установки; удаляйте только специально созданную openclaw-smoke после проверки текущего пути и содержимого. Не запускайте агент на рабочих документах до отдельной оценки прав, сетевых выходов и журналирования. Для полного цикла «предложение вызова → действие приложения → результат в истории» откройте разбор tool calling локальных моделей s7. Если закрытый контур обязателен, выполните сетевую проверку; локальная модель сама по себе её не заменяет.