Как установить 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/installOpenCode 2
Скрипт opencode.ai/installOpenCode 1
npm-пакет @opencode/cliOpenCode 2
npm-пакет opencode-aiOpenCode 1
Homebrew: anomalyco/tap/opencode-v2 и opencodeOpenCode 2
Arch Linux: pacman -S opencodeOpenCode 2
AUR: opencode-binOpenCode 1
Windows: Scoop и ChocolateyOpenCode 1 (1.19.5)

Установка на macOS и Linux

Скрипт установки

bash
curl -fsSL https://opencode.ai/v2/install | bash

Бинарник попадает в $HOME/.opencode/bin. Если сразу после установки терминал не находит команду, загляните в раздел про PATH ниже.

Homebrew

В README рекомендуемым назван отдельный tap:

bash
brew install anomalyco/tap/opencode-v2

Обычная формула brew install opencode тоже уже ставит V2.

npm, bun или pnpm

bash
npm install -g @opencode/cli
bun install -g --trust @opencode/cli
pnpm add -g --allow-build=@opencode/cli @opencode/cli

Команды для bun и pnpm приведены с флагами из документации. Флаги разрешают пакету выполнить свои скрипты при установке, убирать их не стоит.

Arch Linux

bash
# OpenCode 2, официальный пакет
sudo pacman -S opencode

# OpenCode 1, пакет из AUR
paru -S opencode-bin

Если нужна OpenCode 1

Первую ветку ставит тот же скрипт по адресу без /v2 или npm-пакет opencode-ai:

bash
curl -fsSL https://opencode.ai/install | bash
# или
npm install -g opencode-ai

Установка на Windows

Через WSL

Документация по Windows на 29 октября 2026 рекомендует WSL. Opencode ставится внутри Linux-окружения тем же curl-скриптом, а файлы с дисков Windows доступны по путям вида /mnt/c/.

bash
# внутри 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

bash
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.

Проверка, обновление и удаление

bash
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.

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

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

bash
export ZUKKO_API_KEY="fetch_..."

Windows, PowerShell:

bash
setx ZUKKO_API_KEY "fetch_..."

После setx значение появится только в новых окнах терминала.

Шаг 2. Конфиг

bash
{
  "$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 или окно терминала открыто до установки.

bash
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 на Windows, macOS и Linux: пошагово