Что такое 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
Если команда не найдена:
-
Закройте и откройте терминал заново.
-
Проверьте глобальный каталог npm:
npm config get prefix -
Убедитесь, что он есть в 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 ГБ ОЗУ, модель слабее облачной |
Как подключить бесплатный вариант:
- OpenRouter: получите ключ на openrouter.ai, выполните
/connect, выберите OpenRouter и вставьте ключ. Затем/modelsи выберите модель с:free. - Google Gemini: получите ключ в aistudio.google.com, подключите
провайдера через
/connectи выберите модель. В России сервис официально недоступен — используйте Ollama или OpenRouter. - Локально: установите 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 (рекомендуется)
-
Перейдите в папку проекта и запустите агент:
cd C:\projects\my-project opencode -
В открывшемся интерфейсе введите:
/connect -
Выберите провайдера. Для быстрого старта можно выбрать opencode — он предложит ссылку на opencode.ai/auth, где нужно войти, пополнить баланс и скопировать ключ.
-
Вставьте ключ в поле ввода и нажмите Enter.
-
Проверьте список доступных моделей командой
/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.
Как подключить
-
Войдите в OpenCode Console и оформите подписку Go, Go Plus или Go Teams.
-
Скопируйте API-ключ.
-
Запустите opencode в проекте и выполните:
/connect -
Выберите OpenCode Go и вставьте ключ.
-
Выполните
/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 — он только исследует проект и предлагает план, не меняя файлы:
-
Переключитесь на агента Plan в переключателе агентов.
-
Опишите задачу:
Добавь в проект страницу «О нас»: новый маршрут /about, шаблон с заголовком и текстом, ссылку в меню. Сначала покажи план, ничего не меняй. -
Обсудите и уточните план.
-
Переключитесь обратно на агента Build.
-
Попросите выполнить план. Агент покажет изменения; подтверждайте их.
Отмена и повтор
/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 и нескольких команд — этого хватает большинству учебных проектов.
Безопасность
- Подтверждайте команды. Особенно
rm,git push,npm publish, обращения к базе данных. - Читайте diff. Агент может затронуть больше файлов, чем вы ожидали.
- Коммитьте до эксперимента.
git add . && git commit -m "before AI"— и откат всегда под рукой. - Ограничьте права. Правила
permissionsсeffect: "ask"дляeditиshellсильно снижают риск. - Не давайте доступ к секретам. Ключи — в переменных окружения,
.env— в.gitignore. - Проверяйте результат. Запустите проект и тесты сами, не полагайтесь только на отчёт агента.
Типичные проблемы
| Проблема | Причина | Решение |
|---|---|---|
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 в переменных окружения |
Проверьте себя
- Зачем для opencode нужен Node.js?
- Что делает команда
npm install -g @opencode/cli? - Чем
/connectотличается от/models? - Как открыть файл проекта в контексте запроса?
- Почему для учебного проекта лучше задать
permissionsсeffect: "ask"дляeditиshell? - Что даёт подписка OpenCode Go и обязательна ли она?
- Назовите бесплатный способ поработать с opencode без подписки.
Ответы
- opencode распространяется как npm-пакет и запускается через Node.js; без Node.js команда не установится и не стартует.
- Ставит OpenCode 2 глобально, чтобы команда
opencodeбыла доступна в любом каталоге. /connectподключает провайдера и сохраняет учётные данные,/modelsвыбирает модель для сессии.- Начать ввод с
@и выбрать файл в нечётком поиске, например@src/config.js. - Агент будет спрашивать разрешение перед каждой правкой и командой — меньше риск случайно удалить файлы или выполнить опасную команду.
- Стабильный доступ к популярным моделям по фиксированной цене ($10/мес у Go). Подписка необязательна: opencode работает с любым провайдером и без неё.
- Например, бесплатные модели OpenRouter с
:free, бесплатный тариф Google AI Studio или локальная модель через Ollama.
Дополнительные ресурсы
- Документация OpenCode 2: opencode.ai/v2/docs
- Локальная справка:
opencode --helpиopencode --version - Node.js: nodejs.org
- nvm-windows: github.com/coreybutler/nvm-windows
- nvm (macOS/Linux): github.com/nvm-sh/nvm
- OpenRouter: openrouter.ai
- OpenCode Go (тарифы и модели): opencode.ai/v2/docs/console/go
- Google AI Studio (бесплатный тариф Gemini): aistudio.google.com
- Ollama (локальные модели): ollama.com