OpenCode в Windows: от установки до первого исправления кода

OpenCode может изучить файлы проекта, найти ошибку и внести исправление прямо из терминала. Копировать исходный код в браузерный чат для этого не требуется: агент работает с доступными ему файлами и инструментами разработки.

Для первого знакомства достаточно небольшого учебного проекта. Ниже установим OpenCode 2 в Windows, подключим AI-модель, попросим её объяснить ошибку и разрешим исправить одну строку. Заодно разберём разрешения, ограничения отката и ситуации, в которых удобнее использовать WSL.

Что понадобится для работы

OpenCode — AI-агент для программирования с открытым исходным кодом. У него есть терминальный, графический и веб-интерфейсы. Здесь рассматривается терминальный вариант: команда opencode открывает интерактивный интерфейс внутри выбранного терминала.

Для установки через npm понадобятся Node.js и npm. Для обращения к AI-модели — подключение к поддерживаемому провайдеру или другой настроенный источник моделей. Стоимость запросов зависит от выбранного подключения.

Открыть PowerShell можно в Windows Terminal или во встроенном терминале редактора. Сам OpenCode не заменяет оболочку и терминальное приложение. Если используете Windows Terminal, лучше обновить его: например, в Windows Terminal 1.25 исправили ряд проблем стабильности.

Как установить OpenCode 2 в Windows

У OpenCode 1 и OpenCode 2 различаются установочные пакеты и настройки. При этом обе версии используют команду opencode, поэтому старую и новую установку легко перепутать.

Главные различия для терминального клиента:

Дальнейшие команды относятся к OpenCode 2. При переходе со старой версии учитывайте различия конфигурации и плагинов: простого переименования файлов может быть недостаточно.

Установка через npm

Если Node.js ещё не установлен, загрузите актуальную LTS-версию с официального сайта Node.js. Затем откройте новый сеанс PowerShell и проверьте инструменты:

node --version
npm --version

Обе команды должны вывести номера версий. После этого установите CLI:

npm install -g @opencode/cli

Параметр -g означает глобальную установку. Пакет использует установочный скрипт для подготовки нативного исполняемого файла, поэтому установка с отключёнными скриптами может не дать рабочего приложения.

Проверьте результат:

opencode --version

Если команда не найдена, откройте новый терминал. Если это не помогло, переходите к разделу устранения проблем ниже.

Установка без npm

В инструкции OpenCode 2 доступны отдельные CLI-сборки для Windows x64 и ARM64, а также вариант x64 baseline. Выбирайте файл под архитектуру компьютера и следуйте указаниям для соответствующей сборки.

Папка с исполняемым файлом должна находиться в PATH, если вы хотите запускать его короткой командой из любого каталога. Иначе потребуется указывать полный путь.

На общей странице загрузок есть и отдельное приложение Desktop. Оно отличается от терминального CLI. Команды установки через Scoop или Chocolatey из старых руководств также не стоит автоматически переносить на OpenCode 2: его документация пока не заявляет поддержку этих способов для Windows.

Первый запуск и подключение AI-модели

Запускать OpenCode удобнее из папки нужного проекта. Например:

Set-Location "$HOME\Projects\my-app"
opencode

Замените путь своим. Каталог запуска определяет исходный рабочий контекст агента.

В интерактивном интерфейсе выполните:

/connect

Выберите провайдера и предложенный способ авторизации. В зависимости от подключения это может быть API-ключ или вход через учётную запись. Точные шаги описаны в документации по провайдерам.

Затем откройте список моделей:

/models

Выберите доступную модель. Не публикуйте API-ключ в запросах агенту и не сохраняйте его в исходных файлах проекта.

Авторизацию можно начать и из обычной командной строки:

opencode auth login

Для просмотра сохранённых подключений предусмотрена команда:

opencode auth list

Открытый исходный код OpenCode не означает бесплатный доступ ко всем моделям. Перед работой проверьте тариф провайдера, доступный баланс и ограничения расходов. Подписка на чат-сервис также не гарантирует, что она покрывает обращения через API.

Как работать с терминальным интерфейсом

Введите задачу обычным текстом и отправьте её клавишей Enter. Чтобы добавить файл в контекст, наберите @, начните вводить имя и выберите нужный результат. Например:

Объясни, что делает @math.js и какие ошибки в нём есть.

Основные команды терминального интерфейса OpenCode 2:

• /connect — подключение провайдера;
• /models — выбор модели;
• /agents — выбор агента;
• /new — новый диалог;
• /sessions — переход к сохранённым сеансам;
• /undo — откат последнего запроса и связанных с ним действий в пределах доступных снимков;
• /redo — отмена подготовленного отката.

Shift+Tab переключает агентов, а Ctrl+P открывает палитру команд. Для выхода со стандартными настройками нажмите Ctrl+X, отпустите клавиши, затем нажмите Q.

Чем отличаются Plan и Build

Для первого задания полезно разделить анализ и изменение файлов.

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

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

Для знакомства можно явно включить подтверждение команд оболочки. Создайте в корне учебного проекта файл opencode.jsonc со следующим содержимым:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    {
      "action": "shell",
      "resource": "*",
      "effect": "ask"
    },
    {
      "action": "external_directory",
      "resource": "*",
      "effect": "ask"
    }
  ]
}

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

В OpenCode 2 используется массив permissions с эффектами allow, ask и deny. При совпадении нескольких правил действует последнее. Старый формат OpenCode 1 отличается — сверяйте изменения с актуальной схемой разрешений.

Практика: исправляем ошибку в JavaScript

Для первого задания используйте отдельную учебную папку. Следующие команды создают файл math.js, поэтому не выполняйте их поверх существующего проекта с таким файлом.

Создаём пример с ошибкой

В PowerShell выполните:

New-Item -ItemType Directory -Force "$HOME\Projects\opencode-demo" | Out-Null
Set-Location "$HOME\Projects\opencode-demo"
Set-Content -Path .\math.js -Encoding utf8 -Value 'function sum(a, b) { return a - b; } console.log(sum(2, 3));'
Copy-Item .\math.js .\math.original.txt
node .\math.js

Функция названа sum, но выполняет вычитание. Поэтому программа выводит -1, хотя при сложении двух и трёх ожидается 5. Копия исходного файла сохранена отдельно в math.original.txt.

При необходимости добавьте описанный выше opencode.jsonc, затем запустите:

opencode

Если провайдер ещё не подключён, выполните /connect и выберите модель через /models.

Просим Plan объяснить проблему

Через /agents выберите Plan и отправьте запрос, прикрепив файл через @:

Изучи @math.js. Функция sum должна складывать два числа.
Найди ошибку и предложи минимальное исправление.
Пока не изменяй файлы и не запускай команды.

Ожидаемое объяснение: вместо оператора сложения используется вычитание. Ответ модели нужно проверить — сам выбор Plan не гарантирует правильного анализа.

Разрешаем Build изменить одну строку

Переключитесь на Build и задайте ограниченную задачу:

В math.js замени вычитание на сложение в функции sum.
Не меняй другие файлы, включая math.original.txt.
Покажи изменение и проверь результат запуска программы.

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

function sum(a, b) { return a + b; } console.log(sum(2, 3));

Самостоятельно запустите программу в PowerShell:

node .\math.js

Теперь ожидается 5. Сравните изменённый файл с math.original.txt: в этом задании достаточно заменить один оператор, остальной код должен сохраниться.

В настоящем проекте полезно просматривать git diff и запускать подходящие тесты. Учитывайте, что обычный git diff не показывает содержимое новых неотслеживаемых файлов: их нужно проверять отдельно.

Почему /undo не заменяет Git и резервные копии

В OpenCode 2 откат файлов опирается на снимки состояния внутри Git-репозитория. В созданной выше учебной папке мы Git не настраивали, поэтому рассчитывать на восстановление math.js через /undo нельзя. Для сравнения и ручного восстановления оставлена отдельная копия.

Согласно правилам работы снимков, вне Git-репозитория /undo может откатывать историю диалога, но не файлы. Даже внутри репозитория восстановление зависит от того, удалось ли сохранить нужные снимки.

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

Команда /redo позволяет отменить подготовленный откат до отправки нового запроса. Для важных изменений сохраняйте обычные коммиты или резервные копии.

Нужен ли WSL для OpenCode в Windows

Для OpenCode 2 WSL не обязателен: доступны нативные Windows-сборки. Если проект использует PowerShell и Windows-инструменты, начать можно с них.

WSL удобен, когда сам проект рассчитан на Linux: использует Bash-скрипты, Linux-зависимости или соответствующие инструменты сборки. В таком случае Node.js и OpenCode устанавливаются отдельно внутри Linux-окружения. Для установки через npm там также используется:

npm install -g @opencode/cli

Из WSL диск C доступен через /mnt/c/. Например:

cd /mnt/c/Users/YourName/Projects/my-app
opencode

Замените имя пользователя и путь своими. Для регулярной работы Linux-инструментами Microsoft рекомендует хранить проект в файловой системе WSL, например в ~/code/my-app. Это уменьшает затраты на обращения между файловыми системами.

Выбирайте окружение по требованиям проекта. Переносить рабочие файлы в WSL только ради запуска OpenCode не требуется.

Расходы и передача данных

Расходы на модель могут зависеть от входных и выходных токенов, выбранного тарифа и дополнительных услуг провайдера. Большой проект и длинный диалог способны потреблять больше контекста, чем исправление одной функции.

Перед продолжительной работой проверьте тарификацию и доступные ограничения расходов. Для первых заданий выбирайте небольшой объём файлов и конкретный результат.

При использовании внешней модели запросы и необходимый контекст проекта могут передаваться её провайдеру. Условия хранения и обработки данных определяются выбранным сервисом. Доступ к закрытому рабочему коду следует согласовать с правилами проекта или организации.

Что делать, если OpenCode не работает

PowerShell не находит команду opencode

Проверьте установленные пакеты и найденные команды:

npm list -g --depth=0
npm prefix -g
Get-Command opencode -All
where.exe opencode

В Windows глобальные исполняемые файлы npm размещаются непосредственно в каталоге глобального префикса. Если установка прошла успешно, проверьте наличие этого каталога в PATH. После изменения PATH откройте новый сеанс терминала.

Если PowerShell отдельно жалуется на запрет запуска npm.ps1, можно попробовать установленную командную оболочку npm:

npm.cmd --version
npm.cmd install -g @opencode/cli

Для этого не требуется отключать политику выполнения сценариев во всей системе.

Запускается старая версия

Сопоставьте вывод opencode --version, список глобальных npm-пакетов и пути из where.exe opencode. Несколько найденных установок могут означать конфликт.

Пакет OpenCode 2 — @opencode/cli, а OpenCode 1 — opencode-ai. Прежде чем удалять старую установку, выясните её происхождение и сохраните нужные настройки.

Модель не отвечает

Проверьте авторизацию через opencode auth list, выбранную модель через /models, доступный баланс и текст ошибки. Причиной могут быть неверный ключ, отсутствие доступа к модели, ограничения тарифа или сетевой сбой.

Агент не видит нужные файлы

Проверьте, из какого каталога запущен OpenCode. Перейдите в корень проекта и откройте новый сеанс. Нужный файл можно явно прикрепить через @.

Интерфейс или фоновый сервис работает нестабильно

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

opencode service status
opencode api get /api/info

Дополнительные шаги описаны в руководстве по устранению проблем. Не начинайте исправление с удаления конфигурации и базы данных: так можно потерять настройки и историю, не устранив причину ошибки.