Node.js + opencode 2: установка и настройка

Пошаговая инструкция: как установить Node.js и opencode 2, подключить провайдера моделей и запустить первого ИИ-агента в терминале.

Что такое opencode 2

opencode 2 — открытый ИИ-агент для терминала. Вы запускаете его в папке проекта и общаетесь с ним обычным текстом: он читает файлы, ищет по коду, вносит правки и выполняет команды. Работает не в браузере, а прямо там, где вы запускаете сборку и тесты.

Чем он отличается от Cline из предыдущего урока:

Cline opencode
Где работает внутри VS Code в терминале (TUI)
Интерфейс панель с кнопками текстовый интерфейс
Подходит для наглядной работы с файлами серверов, скриптов, SSH
Настройка через графические настройки через конфиг и команды

Оба инструмента могут работать с одним и тем же проектом — выбирайте тот, который удобнее в конкретной ситуации.

Что понадобится

Компонент Требование
Node.js LTS-версия, не ниже 20 (рекомендуется 22+)
npm Устанавливается вместе с Node.js
Терминал Windows Terminal, PowerShell 7, Terminal.app, GNOME Terminal и др.
Аккаунт провайдера OpenRouter, Anthropic, OpenAI, Google или локальная модель
Интернет Для облачной модели; локальная может работать офлайн

Шаг 1. Установите Node.js

Node.js нужен, чтобы запускать npm-пакеты и сам opencode.

Windows

Способ 1 — winget (рекомендуется). Откройте PowerShell:

winget install --id OpenJS.NodeJS.LTS -e

Способ 2 — установщик. Скачайте LTS-версию с nodejs.org, запустите .msi и оставьте галочку Add to PATH.

Способ 3 — nvm-windows. Удобно, если нужно переключать версии Node.js: установите nvm-windows, затем:

nvm install lts
nvm use lts

macOS

Скачайте .pkg с nodejs.org или используйте Homebrew:

brew install node

Linux

# Debian/Ubuntu — через NodeSource (пример для LTS-ветки 22)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Либо через nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts
nvm use --lts

Проверка

Закройте и снова откройте терминал, затем выполните:

node --version
npm --version

Должны появиться номера версий, например v22.x.x и 10.x.x. Если команды не найдены — Node.js не попал в PATH; переустановите его с галочкой «Add to PATH» или добавьте каталог вручную.

⚠️ Если версия Node.js ниже 20, обновитесь: старые версии не поддерживаются современными пакетами.

Шаг 2. Установите opencode 2

Основной способ — npm

npm install -g @opencode/cli

Флаг -g означает глобальную установку: команда opencode станет доступна в любом каталоге. Пакет @opencode/cli — это OpenCode 2.

Альтернативные способы

Скрипт установки (macOS/Linux):

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

Homebrew (macOS/Linux):

brew install anomalyco/tap/opencode-v2

Отдельный бинарник для Windows:

Скачайте архив для вашей архитектуры со страницы opencode.ai/v2/docs (Windows x64 или ARM64), распакуйте и добавьте папку с opencode.exe в PATH. Готовые пакеты winget, Chocolatey и Scoop для OpenCode 2 не поддерживаются.

Docker:

docker run -it --rm ghcr.io/anomalyco/opencode:2.0.0

Проверка

opencode --version

Если команда не найдена:

  1. Закройте и откройте терминал заново.

  2. Проверьте глобальный каталог npm:

    npm config get prefix
    
  3. Убедитесь, что он есть в PATH. На Windows обычно это C:\Users\<имя>\AppData\Roaming\npm.

📌 Это инструкция для OpenCode 2 — актуальной версии агента. Команда запуска у неё та же — opencode, но npm-пакет называется @opencode/cli. Документация: opencode.ai/v2/docs.

Шаг 3. Подключите модель

Без модели opencode не сможет отвечать. Начните с бесплатного варианта, а платный доступ подключите, если упрётесь в лимиты.

Бесплатные варианты

Начать можно без платной подписки:

Вариант Что бесплатно Ограничения
Бесплатные модели OpenCode Go Отдельные модели в рамках подписки Go (например, Beam Free и Iceman Contributor Free) Нужна подписка Go; акция временная, регионы ограничены; Beam Free недоступна в России
OpenRouter :free Модели с суффиксом :free Суточный лимит и очередь; часть моделей недоступна в России
Google AI Studio Бесплатный тариф Gemini API Лимиты запросов; в России официально недоступен
Ollama / LM Studio Полностью бесплатно локально Нужны 8–16 ГБ ОЗУ, модель слабее облачной

Как подключить бесплатный вариант:

  1. OpenRouter: получите ключ на openrouter.ai, выполните /connect, выберите OpenRouter и вставьте ключ. Затем /models и выберите модель с :free.
  2. Google Gemini: получите ключ в aistudio.google.com, подключите провайдера через /connect и выберите модель. В России сервис официально недоступен — используйте Ollama или OpenRouter.
  3. Локально: установите Ollama, выполните ollama pull qwen2.5-coder:7b — OpenCode 2 сам обнаружит локальный сервер и покажет модель в /models.

Локальная модель: подробнее

Самый независимый от региона бесплатный способ — запуск модели на своём компьютере:

ollama pull qwen2.5-coder:7b

Затем запустите opencode и откройте /models — OpenCode 2 сам находит Ollama по адресу http://127.0.0.1:11434. LM Studio обнаруживается на порту 1234, vLLM — на 8000.

⚠️ Бесплатные тарифы меняются: лимиты, список моделей и доступность по регионам могут отличаться. Проверяйте актуальные условия у провайдера.

Платные варианты

Когда бесплатных лимитов не хватает, подключите платного провайдера. Есть два способа передать ключ.

Способ A. Команда /connect (рекомендуется)

  1. Перейдите в папку проекта и запустите агент:

    cd C:\projects\my-project
    opencode
    
  2. В открывшемся интерфейсе введите:

    /connect
    
  3. Выберите провайдера. Для быстрого старта можно выбрать opencode — он предложит ссылку на opencode.ai/auth, где нужно войти, пополнить баланс и скопировать ключ.

  4. Вставьте ключ в поле ввода и нажмите Enter.

  5. Проверьте список доступных моделей командой /models и выберите подходящую.

Можно подключить и других провайдеров: OpenRouter, Anthropic, OpenAI, Google. Принцип тот же: выбрать провайдера и вставить ключ.

Способ B. Переменные окружения

Некоторые провайдеры читают ключ из переменной окружения, например:

# macOS/Linux
export OPENROUTER_API_KEY="sk-or-v1-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Windows PowerShell
$env:OPENROUTER_API_KEY = "sk-or-v1-..."

Чтобы переменная сохранялась между запусками, добавьте её в профиль терминала или в системные переменные Windows.

🔐 Не храните ключи в opencode.jsonc, который лежит в Git. Используйте переменные окружения или отдельный файл, добавленный в .gitignore.

Выбор модели

Модель задаётся в формате провайдер/модель, например opencode-go/deepseek-v4.1-flash. Актуальные идентификаторы смотрите в /models — они меняются чаще, чем выходят новые версии сайта.

Для учёбы:

  • бесплатная или быстрая дешёвая модель — для объяснений и мелких правок;
  • сильная модель с большим контекстом — для рефакторинга и больших проектов;
  • локальная модель через Ollama — если нужна работа без облака.

⚠️ Модели и сервисы, недоступные в России

Отметьте это до подключения и оплаты: часть моделей OpenCode Go и внешних провайдеров официально недоступна в РФ.

Сервис или модель Доступность в России Чем заменить
OpenCode Go: Beam Free 🔴 Недоступна в России (явно указано в документации) Iceman Contributor Free, OpenRouter :free, Ollama
OpenCode Go: Muse Spark 1.3 / 1.2 Contributor 🟠 Только разрешённые регионы (проверьте, входит ли ваша страна) другие модели Go или локальная модель
OpenCode Go: Iceman Contributor Free 🟢 Региональных ограничений в документации нет, но акция временная локальная модель после окончания акции
Google Gemini API / AI Studio 🔴 Официально не предоставляется Ollama/LM Studio
OpenAI API (модели GPT) 🔴 Официально не предоставляется локальная модель или провайдер, работающий в регионе
Anthropic API (модели Claude) 🔴 Официально не предоставляется локальная модель или провайдер, работающий в регионе
OpenRouter :free 🟠 Зависит от конкретной модели и провайдера модели, доступные в регионе, или Ollama
Ollama / LM Studio 🟢 ✅ Работают локально, без региональных ограничений —

OpenCode Go

OpenCode Go — это необязательная подписка от команды OpenCode: она даёт стабильный доступ к популярным моделям для кода по фиксированной цене. Обычный opencode работает и без неё — Go нужен, если вы хотите предсказуемые лимиты и не хотите отдельно регистрироваться у каждого провайдера.

Тарифы

План Цена Что входит
Go $10 в месяц Доступ к моделям Go с базовыми лимитами
Go Plus $40 в месяц Те же модели с повышенными лимитами
Go Teams $20 за участника в месяц Отдельные лимиты каждому участнику команды

Цены и состав моделей могут меняться — сверяйтесь с opencode.ai/v2/docs/console/go.

Как подключить

  1. Войдите в OpenCode Console и оформите подписку Go, Go Plus или Go Teams.

  2. Скопируйте API-ключ.

  3. Запустите opencode в проекте и выполните:

    /connect
    
  4. Выберите OpenCode Go и вставьте ключ.

  5. Выполните /models и выберите модель.

В конфиге модель Go записывается с префиксом opencode-go/:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode-go/kimi-k3"
}

Идентификатор модели берите из /models — список обновляется.

Бесплатные модели в Go

В подписке Go есть и бесплатные модели, например Beam Free и Iceman Contributor Free. Это временные предложения:

  • Beam Free доступна ограниченное время и не работает в ряде регионов, включая Россию;
  • Iceman Contributor Free доступна ограниченное время;
  • после исчерпания лимитов Go можно продолжать пользоваться бесплатными моделями.

Подробный список ограничений по России — в блоке «Модели и сервисы, недоступные в России» выше.

Если бесплатная модель недоступна в вашем регионе, используйте OpenRouter :free (модели, доступные в регионе) или локальную модель через Ollama.

Шаг 4. Первый запуск в проекте

Откройте проект

cd ~/projects/my-project
opencode

opencode смотрит на текущую папку и ближайший Git-репозиторий. Поэтому запускайте его именно из корня проекта, а не из домашнего каталога.

Создайте AGENTS.md

Создайте в корне проекта файл AGENTS.md — OpenCode 2 загружает его автоматически и учитывает в каждой задаче:

# Правила проекта

- Сборка: `npm run build`, тесты: `npm test`.
- Интерфейс и комментарии — на русском языке.
- Не редактируй файлы в `dist/`.

Этот файл стоит закоммитить в Git: так агент будет понимать проект при следующих запусках.

Спросите о проекте

Объясни, как устроен этот проект: какие основные файлы,
как запускается сборка и где лежит логика авторизации.

Чтобы добавить файл в контекст, начните ввод с @ и выберите файл через нечёткий поиск:

Как работает функция parseConfig в @src/config.js?

Попросите изменить код

Сначала полезно поработать с агентом Plan — он только исследует проект и предлагает план, не меняя файлы:

  1. Переключитесь на агента Plan в переключателе агентов.

  2. Опишите задачу:

    Добавь в проект страницу «О нас»: новый маршрут /about,
    шаблон с заголовком и текстом, ссылку в меню.
    Сначала покажи план, ничего не меняй.
    
  3. Обсудите и уточните план.

  4. Переключитесь обратно на агента Build.

  5. Попросите выполнить план. Агент покажет изменения; подтверждайте их.

Отмена и повтор

  • /undo — отменить последнее изменение и вернуть исходный запрос;
  • /redo — повторить отменённое;
  • /undo можно вызывать несколько раз подряд.

Настройка через opencode.jsonc

Конфиг можно положить в корень проекта — opencode.jsonc или .opencode/opencode.jsonc — тогда он действует только на этот проект. Глобальный конфиг лежит в ~/.config/opencode/opencode.jsonc (на Windows — %USERPROFILE%\.config\opencode\opencode.jsonc).

Пример безопасного проекта:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode-go/deepseek-v4.1-flash",
  "permissions": [
    { "action": "edit", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" }
  ]
}

Что здесь важно:

  • model — модель по умолчанию; в примере — deepseek-v4.1-flash через OpenCode Go, точный ID берите из /models (у другого провайдера будет другой префикс);
  • permissions — упорядоченные правила. action: "edit" отвечает за правки файлов, action: "shell" — за команды терминала;
  • effect: "ask" — спрашивать подтверждение перед каждым действием (вместо allow или deny).

Для учебного проекта безопаснее явно поставить ask для правок и команд, а не полагаться на настройки по умолчанию.

Другие полезные поля:

Поле Назначение
instructions дополнительные файлы с правилами, например ["AGENTS.md"]
mcp MCP-серверы в mcp.servers
formatter автоформатирование изменённых файлов
update проверка обновлений: notify, auto или disable
commands пользовательские slash-команды
plugins плагины OpenCode

Расширяемость

  • Правила — AGENTS.md в корне проекта: стиль кода, запреты, команды сборки.
  • Команды — файлы в .opencode/commands/: например, /test для запуска тестов.
  • Агенты — отдельные роли в .opencode/agents/: ревьюер, автор тестов, документалист.
  • Skills — переиспользуемые инструкции для типовых задач.
  • MCP-серверы — внешние инструменты: GitHub, базы данных, браузер.
  • Плагины — расширения на JavaScript/TypeScript.

Начинать стоит с AGENTS.md и нескольких команд — этого хватает большинству учебных проектов.

Безопасность

  1. Подтверждайте команды. Особенно rm, git push, npm publish, обращения к базе данных.
  2. Читайте diff. Агент может затронуть больше файлов, чем вы ожидали.
  3. Коммитьте до эксперимента. git add . && git commit -m "before AI" — и откат всегда под рукой.
  4. Ограничьте права. Правила permissions с effect: "ask" для edit и shell сильно снижают риск.
  5. Не давайте доступ к секретам. Ключи — в переменных окружения, .env — в .gitignore.
  6. Проверяйте результат. Запустите проект и тесты сами, не полагайтесь только на отчёт агента.

Типичные проблемы

Проблема Причина Решение
opencode: command not found Глобальный каталог npm не в PATH Добавьте npm config get prefix в PATH и перезапустите терминал
npm install -g падает с EACCES (macOS/Linux) Нет прав на системный каталог Используйте nvm или настройте пользовательский prefix
npm не работает в PowerShell Политика выполнения скриптов Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
node --version показывает старую версию В PATH другой Node.js Переустановите LTS или переключитесь через nvm
Ошибка 401 при запросе к модели Ключ неверный или не подключён Повторите /connect, проверьте ключ у провайдера
Ошибка 429 Лимит запросов Смените модель или подождите
Терминал «плывёт» на Windows Ограничения стандартной консоли Используйте Windows Terminal или PowerShell 7
Пакет не ставится через winget/choco/scoop Для OpenCode 2 эти менеджеры не поддерживаются npm install -g @opencode/cli или отдельный бинарник
Нет доступа к интернету из-за прокси Корпоративная сеть Задайте HTTPS_PROXY и HTTP_PROXY в переменных окружения

Проверьте себя

  1. Зачем для opencode нужен Node.js?
  2. Что делает команда npm install -g @opencode/cli?
  3. Чем /connect отличается от /models?
  4. Как открыть файл проекта в контексте запроса?
  5. Почему для учебного проекта лучше задать permissions с effect: "ask" для edit и shell?
  6. Что даёт подписка OpenCode Go и обязательна ли она?
  7. Назовите бесплатный способ поработать с opencode без подписки.
Ответы
  1. opencode распространяется как npm-пакет и запускается через Node.js; без Node.js команда не установится и не стартует.
  2. Ставит OpenCode 2 глобально, чтобы команда opencode была доступна в любом каталоге.
  3. /connect подключает провайдера и сохраняет учётные данные, /models выбирает модель для сессии.
  4. Начать ввод с @ и выбрать файл в нечётком поиске, например @src/config.js.
  5. Агент будет спрашивать разрешение перед каждой правкой и командой — меньше риск случайно удалить файлы или выполнить опасную команду.
  6. Стабильный доступ к популярным моделям по фиксированной цене ($10/мес у Go). Подписка необязательна: opencode работает с любым провайдером и без неё.
  7. Например, бесплатные модели OpenRouter с :free, бесплатный тариф Google AI Studio или локальная модель через Ollama.

Дополнительные ресурсы