Установка OpenCode: Windows, macOS и Linux без сюрпризов

Установка OpenCode занимает одну команду, а вот следующие пятнадцать минут уходят на то, что команда opencode не находится, ставится не та версия или агент запускается, но не видит проект. Разберём по порядку и отдельно про Windows: там расхождений больше всего.

Что нужно до установки

OpenCode — терминальная программа, поэтому ставится она не в папку «Программы», а в систему. Перед началом проверь три вещи:

• Терминал, в который ты будешь ставить. На Windows это принципиально: PowerShell и WSL — разные окружения, и агент, поставленный в одно, не появится в другом.
• Версию Node, если ставишь через npm. Старый Node — самая частая причина ошибок прямо на этапе установки.
• Каталог проекта. Агент работает с той папкой, из которой запущен, а не со всем диском.

Точные способы установки и минимальные версии смотри в документации OpenCode — проект обновляется быстро, и команда из чужого поста годичной давности может уже не работать.

Windows: WSL или PowerShell

Здесь стоит решить заранее, потому что переезжать потом неудобно.

WSL даёт линуксовое окружение, и большинство инструкций, примеров и MCP-серверов написаны именно под него. Но у WSL своя файловая система: проект, лежащий в C:\Users\..., виден как /mnt/c/..., работает медленнее, и права на файлы ведут себя не так, как в Windows.

Нативная установка в PowerShell избавляет от этого слоя, зато чаще ловит различия в путях и в поведении команд, которые агент запускает сам. Если проект и так собирается в WSL, ставь туда же. Если вся работа идёт в Windows — ставь нативно и не перемешивай.

Команда не находится после установки

Установка прошла, а opencode отвечает command not found или не является внутренней или внешней командой. Это не сломанная установка, а PATH: файл лежит на диске, но оболочка не знает, где его искать.

Что проверить:

1. Перезапусти терминал. Переменные окружения читаются при старте сессии.
2. Посмотри, куда установщик положил файл, — путь он печатает в конце вывода.
3. Сверь, что этот каталог есть в PATH твоей оболочки.
4. Если ставил глобально через npm, проверь права: установка, упавшая на EACCES, команду не создаёт, хотя сообщение об ошибке легко пролистать.

Отдельный случай — ставил в одном терминале, запускаешь в другом. Тогда всё на месте, просто не там, где смотришь.

Первый запуск

Перейди в каталог проекта и запусти агента оттуда. Сразу после старта он ещё ничего не умеет: нужен провайдер модели. Дальше два пути — облачный API или локальная модель через Ollama.

Первую задачу бери маленькую и проверяемую: попроси прочитать один файл и объяснить, что там происходит. Так ты отделишь проблемы установки от проблем с моделью и доступами. Если на этом шаге посыпались ошибки провайдера, их разбор есть в статье «OpenCode не работает».

Обновление и удаление

Обновляйся тем же способом, каким ставил: смешивать менеджеры пакетов — надёжный путь получить две версии и потом гадать, какая из них запускается. После обновления проверь, что конфиг всё ещё валиден: схема настроек меняется между версиями, и старый ключ может молча перестать читаться.

Удаление агента не убирает его настройки. Файлы конфигурации и данные сессий остаются в домашнем каталоге и в папках проектов — если чистишь начисто, удали и их. Что именно лежит в этих файлах, разобрано в статье про opencode.json.

Если терминал не нужен

OpenCode ставится в систему и живёт в командной строке — это его формат, а не недостаток. Но если ты пришёл сюда за агентом, который читает проект и правит файлы, а терминал терпишь вынужденно, посмотри Доку: то же самое в обычном десктопном приложении, с установщиком и без настройки PATH. Локальную модель она качает из своего каталога, без отдельной связки с Ollama.