Как установить opencode на Windows, macOS и Linux: пошагово
Официальные способы установить opencode на macOS, Linux и Windows, выбор между OpenCode 1 и 2, первый запуск и настройка Zukko с ключом в переменной окружения.
7 мин · · opencode · агенты · подключение
Чтобы установить opencode на macOS или Linux, выполните в терминале curl -fsSL https://opencode.ai/v2/install | bash. Скрипт ставит OpenCode 2, которую рекомендуют README и страница загрузки. На Windows для второй версии есть два официальных пути: установка внутри WSL тем же скриптом или zip-архив с бинарником. После установки проверьте opencode --version, запустите opencode в каталоге проекта и подключите провайдера.
Ниже команды для каждой ОС, обновление и удаление, настройка Zukko через opencode.json и разбор типичных проблем с запуском. Что умеет сам агент, описано в статье opencode: что это за агент и как подключить к нему свои модели.
Какую версию выбрать
Сейчас параллельно существуют две ветки. По README репозитория на 29 октября 2026 это OpenCode 1 (v1.19.5 от 28.10.2026) и OpenCode 2 (v2.2.1 от 29.10.2026). Обе ставят команду opencode и по умолчанию не уживаются рядом, поэтому выберите одну.
Если особых причин держаться за первую ветку нет, ставьте V2. Официальный репозиторий теперь находится на github.com/anomalyco/opencode, старый адрес sst/opencode перенаправляет туда.
Какой способ какую версию ставит:
| Способ установки | Версия |
|---|---|
Скрипт opencode.ai/v2/install | OpenCode 2 |
Скрипт opencode.ai/install | OpenCode 1 |
npm-пакет @opencode/cli | OpenCode 2 |
npm-пакет opencode-ai | OpenCode 1 |
Homebrew: anomalyco/tap/opencode-v2 и opencode | OpenCode 2 |
Arch Linux: pacman -S opencode | OpenCode 2 |
AUR: opencode-bin | OpenCode 1 |
| Windows: Scoop и Chocolatey | OpenCode 1 (1.19.5) |
Установка на macOS и Linux
Скрипт установки
curl -fsSL https://opencode.ai/v2/install | bashБинарник попадает в $HOME/.opencode/bin. Если сразу после установки терминал не находит команду, загляните в раздел про PATH ниже.
Homebrew
В README рекомендуемым назван отдельный tap:
brew install anomalyco/tap/opencode-v2Обычная формула brew install opencode тоже уже ставит V2.
npm, bun или pnpm
npm install -g @opencode/cli
bun install -g --trust @opencode/cli
pnpm add -g --allow-build=@opencode/cli @opencode/cliКоманды для bun и pnpm приведены с флагами из документации. Флаги разрешают пакету выполнить свои скрипты при установке, убирать их не стоит.
Arch Linux
# OpenCode 2, официальный пакет
sudo pacman -S opencode
# OpenCode 1, пакет из AUR
paru -S opencode-binЕсли нужна OpenCode 1
Первую ветку ставит тот же скрипт по адресу без /v2 или npm-пакет opencode-ai:
curl -fsSL https://opencode.ai/install | bash
# или
npm install -g opencode-aiУстановка на Windows
Через WSL
Документация по Windows на 29 октября 2026 рекомендует WSL. Opencode ставится внутри Linux-окружения тем же curl-скриптом, а файлы с дисков Windows доступны по путям вида /mnt/c/.
# внутри WSL
curl -fsSL https://opencode.ai/v2/install | bash
cd /mnt/c/Users/<имя>/projects/my-app
opencodeКак включить и настроить саму WSL, подробно описано в статье Claude Code на Windows: нативно или в WSL. Дальше шаги для opencode те же, что для Linux.
Нативно: OpenCode 2 из zip-архива
Пакетные менеджеры Windows для V2 официально не поддерживаются. На странице документации V2 на 29 октября 2026 есть zip-бинарники для Windows x64 и ARM64.
Скачайте архив под свою архитектуру и распакуйте его в постоянную папку внутри профиля пользователя. Добавьте эту папку в переменную PATH пользователя и откройте новое окно терминала.
Нативно: OpenCode 1 через Scoop, Chocolatey или npm
scoop install opencode
choco install opencode
npm install -g opencode-aiПо документации V1 на 29 октября 2026 Scoop и Chocolatey отдают версию 1.19.5.
Десктопное приложение
Кроме CLI есть OpenCode Desktop для macOS, Windows и Linux, в README оно помечено как BETA. Его скачивают со страницы загрузки (проверено 29 октября 2026), на macOS также через brew install --cask opencode-desktop.
Проверка, обновление и удаление
opencode --version # или opencode -v
opencode upgrade # алиас: opencode update
opencode uninstall --dry-run
opencode uninstall--version печатает номер установленной версии. По справке CLI V2 на 29 октября 2026 uninstall --dry-run показывает, что будет удалено, а данные сессий и конфиг при удалении остаются на месте.
Переход с V1 на V2
По руководству по миграции на 29 октября 2026 действуют три правила:
- V1, поставленную пакетным менеджером, перед установкой V2 удалите тем же менеджером;
- curl-установщик V2 сам заменяет бинарник V1;
opencode upgrade --majorпереводит V1 на V2 и удаляет V1.
Первый запуск
cd ~/projects/my-app
opencodeВ интерфейсе opencode доступны команды:
/connectвыбирает провайдера и принимает ключ;/modelsвыбирает модель;/initсоздаётAGENTS.mdв корне проекта.
Подключение Zukko через opencode.json
Для opencode Zukko использует адрес с суффиксом /v1, тот же, что для OpenAI-совместимых клиентов вроде Cursor и Codex: https://api.zukko.pro/v1. Ключ вида fetch_... указывается в поле API key.
По документации Zukko для opencode модели Claude подключаются через встроенного провайдера anthropic с переопределённым baseURL. Здесь /v1 нужен, хотя в Claude Code и Anthropic SDK адрес Zukko пишется без него.
Конфиг кладут в ~/.config/opencode/opencode.json для всех проектов или в opencode.json в корне конкретного проекта. Чтобы ключ не лежал в файле, opencode подставляет значение из переменной окружения записью {env:ИМЯ}, это описано в документации по конфигу на 29 октября 2026.
Шаг 1. Переменная с ключом
macOS, Linux и WSL, строка для ~/.zshrc или ~/.bashrc:
export ZUKKO_API_KEY="fetch_..."Windows, PowerShell:
setx ZUKKO_API_KEY "fetch_..."После setx значение появится только в новых окнах терминала.
Шаг 2. Конфиг
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"baseURL": "https://api.zukko.pro/v1",
"apiKey": "{env:ZUKKO_API_KEY}"
},
"models": {
"claude-opus-5-5": {},
"claude-sonnet-5": {}
}
}
}
}Шаг 3. Выбор модели
Перезапустите opencode и выполните /models → Anthropic → claude-sonnet-5.
У OpenCode 2 официальный формат провайдера другой (providers, package, settings.baseURL). Но V2 читает конфиги формата V1 из тех же мест и нормализует их в памяти, не переписывая файл, так что конфиг выше работает в обеих ветках.
| Модель | Вход, за 1M токенов | Выход, за 1M токенов |
|---|---|---|
| claude-sonnet-5 | $0.4 | $2 |
| claude-opus-5-5 | $0.8 | $4 |
Актуальный каталог с ценами отдаёт GET https://api.zukko.pro/v1/models. Короткая версия настройки есть в статье opencode: подключение к API-шлюзу за пять минут.
Если opencode не запускается
command not found и PATH
Если оболочка не находит opencode, каталог с бинарником не попал в PATH или окно терминала открыто до установки.
which -a opencode
echo $PATH
# для curl-установщика V2, строка в ~/.zshrc или ~/.bashrc
export PATH="$HOME/.opencode/bin:$PATH"На Windows то же проверяет Get-Command opencode в PowerShell. При установке через npm глобальные команды лежат в каталоге из npm prefix -g (на macOS и Linux в его подкаталоге bin).
Если which -a показывает две копии, у вас одновременно стоят V1 и V2 разными способами. Удалите лишнюю тем же способом, которым она ставилась.
Права
Curl-скрипт ставит opencode в домашний каталог, sudo для него не нужен. Если npm install -g требует прав администратора, лучше выбрать curl-скрипт или перенести глобальный префикс npm в домашний каталог. Установка через sudo npm оставляет файлы владельца root, и последующие обновления тоже потребуют повышенных прав.
На Windows по той же причине держите папку с zip-бинарником в профиле пользователя.
Прокси и сеть
За корпоративным прокси curl и npm сами его не найдут. Задайте переменную HTTPS_PROXY для curl и npm config set https-proxy для npm, большинство консольных инструментов учитывает эту переменную.
Доступность шлюза проверяется запросом curl -sS https://api.zukko.pro/v1/models. Если адрес открывается в браузере, но не из терминала, прокси не передан в окружение оболочки.
Частые вопросы
Где скачать opencode из официальных источников?
Установочные скрипты на opencode.ai, страница загрузки для десктопного приложения и репозиторий anomalyco/opencode (проверено 29 октября 2026). Пакеты npm, Homebrew, Arch, Scoop и Chocolatey перечислены в таблице выше.
Можно ли держать OpenCode 1 и OpenCode 2 рядом?
По умолчанию нет: обе ставят команду opencode. Перед установкой V2 удалите V1 или переведите её командой opencode upgrade --major.
Обязательно ли ставить WSL на Windows?
Нет. WSL рекомендована документацией, но V2 можно запустить из zip-архива, а V1 поставить через Scoop, Chocolatey или npm. Сравнение с другим консольным агентом есть в статье opencode или Codex CLI.
Сколько стоит работа opencode через Zukko?
Списываются только использованные токены, абонентской платы нет. Например, 2 млн входных и 0,5 млн выходных токенов на claude-sonnet-5: 2 × $0.4 + 0.5 × $2 = $0.8 + $1 = $1.8. Баланс пополняется от $1 через СБП, криптовалюту или иностранную карту. На ключ можно поставить дневной и месячный лимит расхода.
Что делать, если opencode не принимает ключ?
Проверьте, что переменная ZUKKO_API_KEY видна в том терминале, где запущен opencode, и что baseURL заканчивается на /v1. Остальные причины разобраны в статье Invalid API key в opencode, а если не помогло, напишите в поддержку Zukko.
zukko
Платите в 25×
меньше
за Claude Code & ChatGPT
Один ключ fetch_* и base URL api.zukko.pro — в Cursor, Claude Code, Codex и любом SDK.
Похожие статьи
- Конфиг opencode.json: провайдеры, модели и ключи по шагамСправочник по opencode.json: расположение файлов, порядок слияния, основные поля и пошаговое подключение своего OpenAI-совместимого провайдера с ключом из переменной окружения.
- Codex на Windows: установка нативно и в WSL с подключением к шлюзуCodex CLI на Windows можно запускать нативно или внутри WSL. Показываем установку, где лежит config.toml, как подключить ключ Zukko и что делать при ошибках.
- Claude CLI на Linux и macOS: установка и подключение к шлюзуСтавим Claude Code на Linux и macOS, прописываем адрес и ключ в профиль оболочки и проверяем соединение запросом curl. Отдельно разобраны ошибки PATH и прав доступа.
- OpenCode Go и Zen: подписка, цены, лимиты и альтернатива со своим ключомOpenCode Go — подписка с долларовыми лимитами по моделям, Zen — оплата по факту из предоплаченных кредитов. Разбираем цены, лимиты и оплату по документации на 29.10.2026 и считаем, когда выгоднее свой ключ.
- Opencode бесплатно: какие модели доступны и где их ограниченияСам opencode бесплатный, а встроенный провайдер даёт набор бесплатных моделей, включая Big Pickle. Разбираем, какие это модели, что они делают с данными и сколько стоит работа агента, когда бесплатного перестаёт хватать.
- Агенты opencode: как настроить роли, модели и инструментыСвой агент в opencode — это роль, модель и список разрешений. Показываем конфиг и пример, где рутину делает дешёвая модель, а код правит сильная.