
ANTHROPIC_API_KEY, OPENAI_API_KEY и т. п.) — сверьтесь с документацией.Термины, которые понадобятся дальше:
Проверьте базу одной пачкой команд:
node --version
npm --version
echo $SHELL
df -h . | tail -1
Пример ожидаемого вывода:
v20.11.1
10.2.4
/bin/zsh
/dev/disk3s1s1 460Gi 212Gi 180Gi 55% /
Если node --version отвечает command not found: node, установите Node.js LTS с официального сайта или через nvm и перезапустите терминал. Без Node npm-пакет агента просто некуда ставить.
Параллельно полезно прочитать как настроить лимиты расходов и бюджеты для ИИ-агентов — там разобраны общие принципы бюджетирования, которые ниже применяются к Opencode.
Что сделать: поставить пакет глобально и убедиться, что бинарник opencode доступен в PATH (PATH — список папок, где оболочка ищет команды).
Зачем: глобальная установка даёт команду opencode в любом каталоге, а не только внутри папки проекта.
npm install -g <имя-пакета-opencode>
opencode --version
Имя пакета и альтернативный способ установки (установочный скрипт одной строкой) сверьтесь с документацией — они менялись между крупными версиями. Не подставляйте имя «по памяти»: npm по неверному имени вернёт 404 Not Found.
Как проверить: команда opencode --version печатает строку с номером версии.
Пример:
$ opencode --version
2.x.x
Точный формат строки (с префиксом v или без) сверьтесь с документацией — важно не оформление, а то, что команда вообще находится и отвечает.
Почему это работает: npm кладёт исполняемый файл в глобальную папку bin, которая уже прописана в PATH — поэтому после установки команда видна из любого каталога проекта.
Если нужен второй консольный агент для сравнения поведения, посмотрите инструкцию по Oh-My-Pi (OMP) — установка и логика конфига там устроены похоже.
Что сделать: создать файл глобальной конфигурации и описать в нём модель основной сессии плюс отдельных субагентов под браузер и фоновые задачи.
Зачем: без разделения моделей каждая мелочь — открыть страницу, прочитать файл — уходит на самую дорогую модель. Разные модели под разные роли дают основной эффект по стоимости.
Путь на macOS и Linux:
mkdir -p ~/.config/opencode
test -f ~/.config/opencode/opencode.json || echo '{}' > ~/.config/opencode/opencode.json
На Windows путь и имя файла сверьтесь с документацией — не копируйте Unix-путь в настройки Windows-сборки.
Содержимое ~/.config/opencode/opencode.json (имена ключей и полей субагента сверьтесь с документацией: между версиями структура менялась):
{
"model": "<провайдер>/<сильная-модель>",
"agent": {
"browser": {
"description": "Открывает страницы и снимает с них текст",
"model": "<провайдер>/<дешёвая-модель>"
},
"background": {
"description": "Фоновый поиск по файлам и черновики",
"model": "<провайдер>/<дешёвая-модель>"
}
}
}
Пример подстановки: <провайдер>/<сильная-модель> → anthropic/<модель-для-планирования>, <провайдер>/<дешёвая-модель> → модель того же провайдера из дешёвой линейки. Конкретные идентификаторы моделей и цены за токен сверьтесь с документацией провайдера и прайсом — здесь они не приводятся.
Ориентир по распределению ролей:
| Роль в конфиге | Что делает | Как выбирать модель |
|---|---|---|
| Основная сессия | планирование, правки файлов, запуск команд | самая сильная из доступных вам |
| `browser` | открыть страницу, снять текст, найти фрагмент | дешёвая и быстрая, с большим контекстом |
| `background` | поиск по проекту, черновики, рутина | самая дешёвая, которая справляется |
Как проверить: провалидируйте JSON синтаксически — сломанная запятая в конфиге ломает запуск целиком.
python3 -m json.tool ~/.config/opencode/opencode.json > /dev/null && echo "JSON OK"
Ожидаемо: JSON OK. Если вместо этого выводится json.decoder.JSONDecodeError, конфиг не будет прочитан — см. раздел проблем ниже.
Почему это работает: агент при старте читает глобальный конфиг и берёт оттуда модель по умолчанию и описания субагентов; всё, что не описано явно, наследует модель основной сессии.
Дополнительно ограничьте расходы на уровне аккаунта провайдера — отдельным ключом с лимитом или бюджетом в консоли провайдера. Точные поля лимитов в конфиге Opencode сверьтесь с документацией; общая методика — в гайде по лимитам выше.

Что сделать: запустить агента в тестовом каталоге и дать задачу, которая заведомо требует и браузера, и фоновой работы.
Зачем: конфиг может быть валидным по JSON и при этом нерабочим — например, если у субагента нет доступа к инструментам.
mkdir -p /tmp/opencode-test && cd /tmp/opencode-test
opencode
Внутри TUI дайте задачу вида: «открой страницу с документацией проекта, выпиши список поддерживаемых версий в versions.md, параллельно найди в текущем каталоге все *.json и перечисли их в files.md».
Что должно появиться на экране: два потока работы — основная сессия продолжает отвечать, пока фоновый субагент выполняет вторую часть; в логе видно, какая модель обработала каждую часть (имена ролей browser и background из конфига). Точный вид индикатора фоновой задачи сверьтесь с документацией — в разных версиях он отличается.
Как проверить результат — файлы и расход:
ls -la /tmp/opencode-test
Ожидаемо: появились versions.md и files.md, оба непустые.
Чек-лист приёмки:
opencode --version отвечает номером версииpython3 -m json.tool .../opencode.json → JSON OKversions.md и files.md созданы и содержат текстПоследний пункт проверяется сравнением: прогоните ту же задачу с конфигом, где у всех ролей стоит сильная модель, и сравните итоговый расход. Конкретные цифры зависят от вашего провайдера — фиксируйте их у себя, а не берите из чужих замеров.
Проблема. Команда не находится после установки
zsh: command not found: opencodenpm prefix -g
export PATH="$(npm prefix -g)/bin:$PATH"
opencode --version
Чтобы не повторять вручную, допишите эту строку export PATH=... в ~/.zshrc или ~/.bashrc и перезапустите терминал.
Проблема. Агент стартует, но падает на конфиге
SyntaxError: Expected double-quoted property name in JSON at position 412// внутри opencode.json — JSON их не допускает.python3 -m json.tool ~/.config/opencode/opencode.json
Команда либо печатает отформатированный JSON (всё в порядке), либо указывает строку с ошибкой.
Проблема. Модель не отвечает, запросы отклоняются
401 Unauthorized или Error: no API key found for provideropencode (например, вы добавили его в другой профиль оболочки), либо у ключа нет доступа к выбранной модели.test -n "$ANTHROPIC_API_KEY" && echo "key set" || echo "key missing"
Если вывелось key missing — экспортируйте ключ в текущей сессии или пропишите в ~/.zshrc. Если ключ на месте, но 401 повторяется — сверьтесь с документацией провайдера: возможно, у ключа нет прав на эту модель.
Вы получили рабочую установку Opencode v2 с раздельными моделями для основной сессии, браузерного и фонового субагента, а также чек-лист приёмки, который ловит типовые поломки конфига. Дальше имеет смысл зафиксировать бюджет и алерты у провайдера, а затем расширять набор субагентов под свои повторяющиеся задачи.
Чем Opencode отличается от обычного чата с моделью?
Чат отвечает текстом, а Opencode работает в вашем терминале: читает файлы проекта, правит их и запускает команды. Поэтому ему нужны не только ключ, но и права на каталог проекта.
Нужен ли платный API-ключ?
Конкретные условия тарификации зависят от провайдера — сверьтесь с документацией. Практический минимум: один ключ с лимитом расходов, чтобы ошибка в конфиге не съела бюджет.
Фоновые субагенты тратят токены отдельно?
Да, это отдельные запросы к модели со своей моделью и своим расходом. Именно поэтому дешёвая модель на фоновых задачах — основной рычаг экономии.
Работает ли это на Windows?
Установка через npm возможна, но пути к конфигу и поддерживаемые версии сверьтесь с документацией; чаще всего на Windows рекомендуют WSL2 и установку по Unix-инструкции.
Статус: практическое руководство. Часть утверждений — заявления вендоров и проектов; проверяйте на своей среде.
Пошаговая настройка Opencode v2 на Windows, macOS и Linux: подключение API-ключей, включение фоновых субагентов, работа с браузером агента и оценка реальной стоимости запросов по моделям. Время выполнения: 25 минут Уровень сложности: Intermediate
Машинные данные публикации: Citation Map JSON · JSON-LD · Semantic Embeddings — отдельный этап.
| Сущность | Тип | Роль в публикации |
|---|---|---|
| opencode установка | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
| opencode v2 настройка | продукт/модель | упоминается в заголовке, TL;DR или разделах гайда |
| opencode субагенты | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
| браузер для ии-агента | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
| стоимость токенов opencode | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
| Windows | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| Linux | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| macOS | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| Node.js | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| npm | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
В материале нет отдельного независимого подтверждения; ниже разделены заявления источников и редакционные выводы.
| Источник | Тип | Роль |
|---|---|---|
| Внешние ссылки в материале не указаны | — | — |
Как цитировать: AI Release. Как установить и настроить Opencode v2: браузер для агента, фоновые субагенты и контроль стоимости моделей. ai-release.org.