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

> AI Release · @ai_release1 · https://ai-release.org/guides/kak-ustanovit-i-nastroit-opencode-v2-brauzer-dlya-agent.html

## TL;DR

- Время выполнения: 25 минут
- Уровень сложности: Intermediate
- Понадобится: Node.js LTS + npm, терминал (bash/zsh), API-ключ провайдера модели, ~1 ГБ свободного места. Имя установочного пакета, точные флаги и номера поддерживаемых версий сверьтесь с документацией проекта — в тексте они помечены явно.

## Требования и подготовка
![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/kak-ustanovit-i-nastroit-opencode-v2-brauzer-dlya-agent-ru-1.jpg?v=1794818652)


- ОС: macOS 13+, Ubuntu 22.04+ или Windows 11 с WSL2 (минимальные версии — сверьтесь с документацией).
- Node.js LTS и npm — Opencode ставится как npm-пакет, поэтому Node нужен обязательно.
- API-ключ провайдера модели. Имя переменной окружения зависит от провайдера (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY` и т. п.) — сверьтесь с документацией.
- Права на глобальную установку npm-пакетов (или Node, поставленный через nvm — тогда sudo не нужен).
- Свободное место: около 1 ГБ под пакет и кэш.

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

- **Opencode** — консольный (TUI) ИИ-агент: программа в терминале, которая читает файлы проекта, правит их и запускает команды по вашему заданию.
- **Субагент** — отдельный экземпляр агента со своей моделью и своим набором прав, которому основная сессия поручает подзадачу.
- **Браузер агента** — режим, в котором агент открывает веб-страницы и работает с их содержимым, а не только с локальными файлами.
- **TUI** — текстовый интерфейс в терминале (то, что вы видите после запуска команды).

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

```bash
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-пакет агента просто некуда ставить.

Параллельно полезно прочитать [как настроить лимиты расходов и бюджеты для ИИ-агентов](https://ai-release.org/guides/kak-nastroit-limity-rashodov-i-byudzhety-dlya-ii-agento.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide) — там разобраны общие принципы бюджетирования, которые ниже применяются к Opencode.

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

**Что сделать:** поставить пакет глобально и убедиться, что бинарник `opencode` доступен в PATH (PATH — список папок, где оболочка ищет команды).

**Зачем:** глобальная установка даёт команду `opencode` в любом каталоге, а не только внутри папки проекта.

```bash
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)](https://ai-release.org/guides/kak-ustanovit-i-nastroit-oh-my-pi-omp-konsolnyy-ii-agen.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide) — установка и логика конфига там устроены похоже.

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

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

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

Путь на macOS и Linux:

```bash
mkdir -p ~/.config/opencode
test -f ~/.config/opencode/opencode.json || echo '{}' > ~/.config/opencode/opencode.json
```

На Windows путь и имя файла сверьтесь с документацией — не копируйте Unix-путь в настройки Windows-сборки.

Содержимое `~/.config/opencode/opencode.json` (имена ключей и полей субагента сверьтесь с документацией: между версиями структура менялась):

```json
{
  "model": "<провайдер>/<сильная-модель>",
  "agent": {
    "browser": {
      "description": "Открывает страницы и снимает с них текст",
      "model": "<провайдер>/<дешёвая-модель>"
    },
    "background": {
      "description": "Фоновый поиск по файлам и черновики",
      "model": "<провайдер>/<дешёвая-модель>"
    }
  }
}
```

**Пример подстановки:** `<провайдер>/<сильная-модель>` → `anthropic/<модель-для-планирования>`, `<провайдер>/<дешёвая-модель>` → модель того же провайдера из дешёвой линейки. Конкретные идентификаторы моделей и цены за токен сверьтесь с документацией провайдера и прайсом — здесь они не приводятся.

Ориентир по распределению ролей:

| Роль в конфиге | Что делает | Как выбирать модель |
|---|---|---|
| Основная сессия | планирование, правки файлов, запуск команд | самая сильная из доступных вам |
| `browser` | открыть страницу, снять текст, найти фрагмент | дешёвая и быстрая, с большим контекстом |
| `background` | поиск по проекту, черновики, рутина | самая дешёвая, которая справляется |

**Как проверить:** провалидируйте JSON синтаксически — сломанная запятая в конфиге ломает запуск целиком.

```bash
python3 -m json.tool ~/.config/opencode/opencode.json > /dev/null && echo "JSON OK"
```

Ожидаемо: `JSON OK`. Если вместо этого выводится `json.decoder.JSONDecodeError`, конфиг не будет прочитан — см. раздел проблем ниже.

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

Дополнительно ограничьте расходы на уровне аккаунта провайдера — отдельным ключом с лимитом или бюджетом в консоли провайдера. Точные поля лимитов в конфиге Opencode сверьтесь с документацией; общая методика — в гайде по лимитам выше.

## Шаг 3. Проверка: фоновый субагент, браузер и счётчик расхода
![Иллюстрация к разделу «Шаг 3. Проверка: фоновый субагент, браузер и счётчик расхода»](https://ai-release.org/guides/img/kak-ustanovit-i-nastroit-opencode-v2-brauzer-dlya-agent-ru-3.jpg?v=1794818670)


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

**Зачем:** конфиг может быть валидным по JSON и при этом нерабочим — например, если у субагента нет доступа к инструментам.

```bash
mkdir -p /tmp/opencode-test && cd /tmp/opencode-test
opencode
```

Внутри TUI дайте задачу вида: «открой страницу с документацией проекта, выпиши список поддерживаемых версий в `versions.md`, параллельно найди в текущем каталоге все `*.json` и перечисли их в `files.md`».

**Что должно появиться на экране:** два потока работы — основная сессия продолжает отвечать, пока фоновый субагент выполняет вторую часть; в логе видно, какая модель обработала каждую часть (имена ролей `browser` и `background` из конфига). Точный вид индикатора фоновой задачи сверьтесь с документацией — в разных версиях он отличается.

**Как проверить результат** — файлы и расход:

```bash
ls -la /tmp/opencode-test
```

Ожидаемо: появились `versions.md` и `files.md`, оба непустые.

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

- [ ] `opencode --version` отвечает номером версии
- [ ] `python3 -m json.tool .../opencode.json` → `JSON OK`
- [ ] В логе видно разные модели для основной сессии и субагентов
- [ ] Файлы `versions.md` и `files.md` созданы и содержат текст
- [ ] Счётчик токенов/стоимости после задачи вырос, но меньше, чем при прогоне той же задачи на одной сильной модели

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

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

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

- Ошибка: `zsh: command not found: opencode`
- Причина: глобальная папка bin npm не входит в PATH (частая ситуация при установке Node через unofficially-сборки или при смене версии Node через nvm).
- Решение: узнайте путь и добавьте его в PATH.

```bash
npm 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 их не допускает.
- Решение: уберите запятую перед закрывающей скобкой и любые комментарии, затем перепроверьте:

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

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

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

- Ошибка: `401 Unauthorized` или `Error: no API key found for provider`
- Причина: ключ не экспортирован в той же сессии терминала, из которой запущен `opencode` (например, вы добавили его в другой профиль оболочки), либо у ключа нет доступа к выбранной модели.
- Решение: проверьте, что переменная видна процессу, и перезапустите агента.

```bash
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-инструкции.
