← Все гайды AI Release
EN Подписаться на @ai_release1

Как установить и настроить Opencode v2: браузер для агента, фоновые субагенты и контроль стоимости моделей

Обновлено: 16.11.2026 · AI Release · @ai_release1
Как установить и настроить Opencode v2: браузер для агента, фоновые субагенты и контроль стоимости моделей

TL;DR

Требования и подготовка

Иллюстрация к разделу «Требования и подготовка»
Иллюстрация к разделу «Требования и подготовка»

Термины, которые понадобятся дальше:

Проверьте базу одной пачкой команд:

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.

Шаг 1. Установка Opencode v2 и первый запуск

Что сделать: поставить пакет глобально и убедиться, что бинарник 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) — установка и логика конфига там устроены похоже.

Шаг 2. Конфиг: модель по умолчанию, браузерный и фоновый субагенты

Что сделать: создать файл глобальной конфигурации и описать в нём модель основной сессии плюс отдельных субагентов под браузер и фоновые задачи.

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

Путь на 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 сверьтесь с документацией; общая методика — в гайде по лимитам выше.

Шаг 3. Проверка: фоновый субагент, браузер и счётчик расхода

Иллюстрация к разделу «Шаг 3. Проверка: фоновый субагент, браузер и счётчик расхода»
Иллюстрация к разделу «Шаг 3. Проверка: фоновый субагент, браузер и счётчик расхода»

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

Зачем: конфиг может быть валидным по 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, оба непустые.

Чек-лист приёмки:

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

Возможные проблемы и решения

Проблема. Команда не находится после установки

npm prefix -g
export PATH="$(npm prefix -g)/bin:$PATH"
opencode --version

Чтобы не повторять вручную, допишите эту строку export PATH=... в ~/.zshrc или ~/.bashrc и перезапустите терминал.

Проблема. Агент стартует, но падает на конфиге

python3 -m json.tool ~/.config/opencode/opencode.json

Команда либо печатает отформатированный JSON (всё в порядке), либо указывает строку с ошибкой.

Проблема. Модель не отвечает, запросы отклоняются

test -n "$ANTHROPIC_API_KEY" && echo "key set" || echo "key missing"

Если вывелось key missing — экспортируйте ключ в текущей сессии или пропишите в ~/.zshrc. Если ключ на месте, но 401 повторяется — сверьтесь с документацией провайдера: возможно, у ключа нет прав на эту модель.

Резюме и следующие шаги

Вы получили рабочую установку Opencode v2 с раздельными моделями для основной сессии, браузерного и фонового субагента, а также чек-лист приёмки, который ловит типовые поломки конфига. Дальше имеет смысл зафиксировать бюджет и алерты у провайдера, а затем расширять набор субагентов под свои повторяющиеся задачи.

FAQ

Чем Opencode отличается от обычного чата с моделью?

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

Нужен ли платный API-ключ?

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

Фоновые субагенты тратят токены отдельно?

Да, это отдельные запросы к модели со своей моделью и своим расходом. Именно поэтому дешёвая модель на фоновых задачах — основной рычаг экономии.

Работает ли это на Windows?

Установка через npm возможна, но пути к конфигу и поддерживаемые версии сверьтесь с документацией; чаще всего на Windows рекомендуют WSL2 и установку по Unix-инструкции.

🤖 Кратко для ИИ

AI Release Knowledge Layer
Машинно-читаемое описание публикации · Версия 1.0

Статус: практическое руководство. Часть утверждений — заявления вендоров и проектов; проверяйте на своей среде.

1. Суть публикации

Пошаговая настройка Opencode v2 на Windows, macOS и Linux: подключение API-ключей, включение фоновых субагентов, работа с браузером агента и оценка реальной стоимости запросов по моделям. Время выполнения: 25 минут Уровень сложности: Intermediate

Внутри: прямые ответы, ключевые факты, участники, связи, достоверность, неизвестное и источники.

Машинные данные публикации: Citation Map JSON · JSON-LD · Semantic Embeddings — отдельный этап.

Полный Knowledge Layer: разделы 2–8

2. Прямые ответы

Что это за материал?
Пошаговая настройка Opencode v2 на Windows, macOS и Linux: подключение API-ключей, включение фоновых субагентов, работа с браузером агента и оценка реальной стоимости запросов по моделям. → подробнее (AR-GUIDE-KAKUSTANOV-001)
Что понадобится?
ОС: macOS 13+, Ubuntu 22.04+ или Windows 11 с WSL2 (минимальные версии — сверьтесь с документацией).; Node.js LTS и npm — Opencode ставится как npm-пакет, поэтому Node нужен обязательно.; API-ключ провайдера модели. Имя переменной окружения зависит от провайдера (ANTHROPIC_API_KEY, OPENAI_API_KEY и т. п.) — сверьтесь… → подробнее (AR-GUIDE-KAKUSTANOV-003)
Как это сделать?
Шаг 1. Установка Opencode v2 и первый запуск → Шаг 2. Конфиг: модель по умолчанию, браузерный и фоновый субагенты → Шаг 3. Проверка: фоновый субагент, браузер и счётчик расхода → подробнее (AR-GUIDE-KAKUSTANOV-004)
Что может пойти не так?
Ошибка: zsh: command not found: opencode → подробнее (AR-GUIDE-KAKUSTANOV-006)

3. Ключевые факты

  1. Время выполнения: 25 минут — подтверждение; статус: заявление источника.
  2. Уровень сложности: Intermediate — подтверждение; статус: заявление источника.
  3. Понадобится: Node.js LTS + npm, терминал (bash/zsh), API-ключ провайдера модели, ~1 ГБ свободного места. Имя установочного пакета, точные флаги и номера поддерживаемых версий сверьтесь с документацией проекта — в тексте они помечены явно. — подтверждение; статус: заявление источника.
  4. ОС: macOS 13+, Ubuntu 22.04+ или Windows 11 с WSL2 (минимальные версии — сверьтесь с документацией). — подтверждение; статус: заявление источника.
  5. Node.js LTS и npm — Opencode ставится как npm-пакет, поэтому Node нужен обязательно. — подтверждение; статус: заявление источника.
  6. API-ключ провайдера модели. Имя переменной окружения зависит от провайдера (ANTHROPIC_API_KEY, OPENAI_API_KEY и т. п.) — сверьтесь с документацией. — подтверждение; статус: заявление источника.
  7. Ошибка: zsh: command not found: opencode — подтверждение; статус: анализ AI Release.
  8. Причина: глобальная папка bin npm не входит в PATH (частая ситуация при установке Node через unofficially-сборки или при смене версии Node через nvm). — подтверждение; статус: анализ AI Release.

4. Участники и сущности

СущностьТипРоль в публикации
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 или разделах гайда

5. Связи и контекст

  • Гайд — описывает → Как установить и настроить Opencode v2: браузер для агента, фоновые субагенты и контроль стоимости моделей (AR-GUIDE-KAKUSTANOV-001).
  • Гайд — содержит шаг → Шаг 1. Установка Opencode v2 и первый запуск (AR-GUIDE-KAKUSTANOV-001).

6. Достоверность и происхождение информации

Подтверждено

В материале нет отдельного независимого подтверждения; ниже разделены заявления источников и редакционные выводы.

Заявление источника

  • Характеристики продуктов, версии, цены и лимиты — из описаний вендоров и материалов гайда.
  • Команды и шаги приведены как рекомендация, а не как гарантированный результат.

Анализ AI Release

  • Структура, сравнение и критерии выбора — редакционные.
  • Гайд не заменяет независимый аудит или юридическую консультацию.

7. Что пока неизвестно

  • Ошибка: zsh: command not found: opencode
  • Причина: глобальная папка bin npm не входит в PATH (частая ситуация при установке Node через unofficially-сборки или при смене версии Node через nvm).
  • Решение: узнайте путь и добавьте его в PATH.
  • Ошибка: SyntaxError: Expected double-quoted property name in JSON at position 412

8. Источники

ИсточникТипРоль
Внешние ссылки в материале не указаны——

Как цитировать: AI Release. Как установить и настроить Opencode v2: браузер для агента, фоновые субагенты и контроль стоимости моделей. ai-release.org.