OpenCode CLI: настройка, провайдеры и плагины

Аннотация

OpenCode CLI - это открытый агент для разработки, который запускается в терминале, умеет работать с кодовой базой, вызывать инструменты, редактировать файлы, запускать команды и использовать разные LLM-провайдеры через одну конфигурацию.¹ Ключевая особенность OpenCode - провайдер-агностичность: официальная документация указывает поддержку 75+ LLM-провайдеров через AI SDK и Models.dev, включая локальные модели.² На практике корректная настройка сводится к четырем слоям: выбрать интерфейс запуска, подключить провайдера через /connect или opencode auth login, зафиксировать модель в opencode.json/opencode.jsonc, затем ограничить права агента, инструкции, плагины и MCP под конкретный workflow.³

Главный вывод: для первого запуска лучше использовать OpenCode Zen или один из нативно поддержанных провайдеров, а кастомные OpenAI-compatible провайдеры добавлять только после понимания схемы provider -> models -> options.⁴ Из плагинов не стоит ставить все подряд: базовый полезный набор обычно состоит из плагина защиты секретов, управления контекстом, уведомлений и, при необходимости, изоляции рабочих окружений.⁵ Актуальная практическая проверка перед фиксацией модели в конфиге - выполнить opencode models --refresh, потому что список моделей и их deprecation dates меняются быстрее, чем большинство статей и README.⁶

Что такое OpenCode CLI

OpenCode позиционируется как open source AI coding agent для терминала, IDE и desktop-клиента.¹ Если запустить opencode без аргументов, CLI открывает TUI; для скриптов и автоматизации есть команды вроде opencode run "...", opencode models, opencode auth, opencode agent, opencode github, opencode mcp, opencode serve и opencode web.⁶

Функционально это не просто чат с моделью. Агент получает доступ к инструментам разработки: чтение и изменение файлов, shell, поиск, LSP, задачи, MCP и кастомные tools; набор доступных действий контролируется через permissions.⁷ Встроенная модель работы делит агентов на primary agents и subagents: build является основным агентом для разработки с полным доступом, plan ограничен для анализа и планирования, а general и explore используются как вспомогательные агенты.⁸

Важное отличие от многих CLI-оберток вокруг LLM - OpenCode делает провайдера заменяемой частью системы. Модель в конфиге указывается в формате provider/model, например opencode/gpt-5.5 или anthropic/claude-sonnet-4-5; тот же формат используется в CLI-флагах и agent-конфигах.⁹

Установка и первый запуск

Официальная страница предлагает установку через install script, npm, bun, Homebrew и AUR; минимальный быстрый вариант выглядит как curl -fsSL https://opencode.ai/install | bash.¹ После установки базовый цикл такой:

opencode

В TUI нужно выполнить /connect, выбрать провайдера, добавить credentials и затем выполнить /models, чтобы выбрать модель.² Для неинтерактивного использования можно вызвать:

opencode run "Проверь, какие тесты есть в этом проекте"
opencode -m opencode/gpt-5.5
opencode --continue
opencode --session <session-id>

Официальная CLI-документация отдельно подчеркивает, что запуск без аргументов стартует TUI, а opencode run нужен для программного взаимодействия с агентом.⁶

Где хранится конфигурация

Конфигурация OpenCode описывается JSON или JSONC-файлом и валидируется схемой https://opencode.ai/config.json.¹⁰ Основные настройки: глобальная модель, small_model, provider, agent, permission, mcp, plugin, instructions, disabled_providers, enabled_providers, compaction, watcher, formatter, share и autoupdate.¹⁰

Конфиги не заменяют друг друга целиком, а сливаются: более поздние источники переопределяют только конфликтующие ключи.¹⁰ Порядок загрузки такой: remote org config, глобальный ~/.config/opencode/opencode.json, путь из OPENCODE_CONFIG, проектный opencode.json, директории .opencode, inline config из OPENCODE_CONFIG_CONTENT, затем managed config и MDM-настройки на macOS.¹⁰ Поэтому проектный файл можно хранить в репозитории для team defaults, а личные credentials и предпочтения модели оставлять глобально или в environment variables.

Минимальный проектный opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/gpt-5.5",
  "small_model": "opencode/gpt-5-nano",
  "share": "disabled",
  "permission": {
    "*": "ask",
    "read": "allow",
    "edit": "ask",
    "bash": "ask"
  },
  "instructions": ["AGENTS.md", "CONTRIBUTING.md"]
}

Здесь model задает основную модель, small_model используется для легких задач вроде генерации заголовков, share: "disabled" отключает публикацию сессий, а permission переводит действия в режим подтверждения, оставляя чтение файлов разрешенным.¹¹ Для командной работы это более безопасная стартовая точка, чем полное auto-approve: страница Permissions описывает allow, ask и deny, а также поддерживает глобальный catch-all * и более точные правила по tool input.¹¹

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

OpenCode использует AI SDK и Models.dev, поэтому поддерживает широкий набор провайдеров и локальные модели.² Официальная документация и каталог AI SDK покрывают OpenAI, Anthropic, Google Generative AI, Google Vertex AI, Azure OpenAI, Amazon Bedrock, Groq, DeepInfra, Mistral, Together.ai, Cohere, Fireworks, DeepSeek, Cerebras, Perplexity, Hugging Face, LM Studio, NVIDIA NIM, Ollama, OpenRouter, Cloudflare Workers AI и другие провайдеры.¹²

Для новичка самый простой путь - OpenCode Zen: это beta-провайдер OpenCode с проверенным набором моделей, который работает как обычный provider: нужно получить API key, подключить его через /connect и выбрать модель через /models.¹³ На 29 апреля 2026 года страница Zen показывает, среди прочего, model IDs gpt-5.5, gpt-5.4, gpt-5.3-codex, gpt-5.2, gpt-5.1-codex, gpt-5-nano, claude-opus-4-7, claude-sonnet-4-6 и указывает формат opencode/<model-id>.¹³ Для пользователей с существующими подписками полезны OpenAI ChatGPT Plus/Pro, GitHub Copilot и Claude Pro/Max сценарии, если они доступны в вашем аккаунте и регионе; в документации OpenCode описывает вход в OpenAI через ChatGPT Plus/Pro и GitHub Copilot через device login.¹⁴ Для корпоративной среды типичны Azure OpenAI, Amazon Bedrock, Google Vertex AI, GitLab Duo и внутренние OpenAI-compatible gateways.¹⁵

Для локальной разработки есть Ollama, LM Studio, llama.cpp и NVIDIA NIM. В этих сценариях провайдер обычно описывается через @ai-sdk/openai-compatible, локальный baseURL и явный список моделей.¹⁶ Для Ollama документация дополнительно предупреждает, что при проблемах с tool calls может понадобиться увеличить num_ctx, примерно начиная с диапазона 16k-32k.¹⁶

Как настраивать провайдера

Базовый официальный алгоритм в TUI состоит из двух шагов: добавить credentials через /connect, затем при необходимости описать провайдера в секции provider конфига.² Эквивалент для терминала - opencode auth login; credentials сохраняются в ~/.local/share/opencode/auth.json, а при старте OpenCode также подхватывает ключи из переменных окружения и .env проекта.⁶

Пример настройки встроенного провайдера с переопределением endpoint:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.example.org/v1"
      }
    }
  },
  "model": "anthropic/claude-sonnet-4-5"
}

Параметр baseURL официально поддерживается для случаев proxy-сервисов и кастомных endpoints.¹⁷ Для Bedrock лучше использовать provider-specific настройки region, profile и endpoint, причем config file имеет приоритет над environment variables.¹⁵ Для Azure OpenAI важна привязка resource name и deployment name: документация OpenCode указывает, что deployment name должен совпадать с model name, иначе модель может не работать корректно.¹⁵

Кастомные провайдеры

Кастомный провайдер нужен, когда API нет в списке /connect, но сервис совместим с OpenAI API. Официальная инструкция: выбрать Other в /connect, задать уникальный provider id, сохранить API key, затем добавить в opencode.json секцию с тем же id.¹⁸

Шаблон:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Provider",
      "options": {
        "baseURL": "https://api.example.org/v1",
        "apiKey": "{env:MYPROVIDER_API_KEY}",
        "headers": {
          "X-Team": "engineering"
        }
      },
      "models": {
        "coder-large": {
          "name": "Coder Large",
          "limit": {
            "context": 200000,
            "output": 65536
          }
        }
      }
    }
  },
  "model": "myprovider/coder-large"
}

Для /v1/chat/completions совместимых сервисов документация рекомендует @ai-sdk/openai-compatible; для /v1/responses - @ai-sdk/openai.¹⁹ Поля limit.context и limit.output важны не только как документация: OpenCode использует лимиты, чтобы понимать остаток контекста, а для стандартных провайдеров эти данные подтягиваются из Models.dev.¹⁹

Практические проверки при ошибках: provider id в /connect должен совпадать с ключом в provider, npm должен соответствовать API-типу, options.baseURL должен указывать на правильный endpoint, а opencode auth list должен показывать сохраненные credentials.¹⁹

Модели и выбор default

OpenCode рекомендует выбирать модели, которые хорошо умеют и писать код, и вызывать tools.⁹ На странице Models перечислены GPT 5.2, GPT 5.1 Codex, Claude Opus 4.5, Claude Sonnet 4.5, Minimax M2.1 и Gemini 3 Pro, но сама документация предупреждает, что список не исчерпывающий и может устаревать.⁹ Поэтому для Zen и быстро обновляемых provider-списков лучше сверяться с /models и opencode models --refresh, а не копировать model id из старого конфига.⁶

Для практики это означает: не выбирать модель только по benchmark для чата. Для agentic coding важны tool calling, стабильное следование инструкциям, контекстное окно, цена, latency, качество патчей и поведение при длинных сессиях. Если провайдер дешевле, но плохо вызывает tools или часто теряет состояние, экономия быстро исчезает на повторных итерациях.⁹

Безопасность и privacy

В enterprise-документации OpenCode прямо говорит, что не хранит код и context data, а обработка происходит локально или через прямые API-вызовы к выбранному AI-провайдеру.²⁰ Это не означает, что выбранный провайдер ничего не хранит: страница Zen отдельно указывает разные политики для underlying providers, включая 30-дневное retention для OpenAI и Anthropic API и дополнительные исключения для некоторых free endpoints.¹³ Поэтому privacy-модель OpenCode нужно оценивать в два слоя: что хранит сам OpenCode и что делает выбранный provider или gateway.

Единственная оговорка в enterprise-документации OpenCode - функция /share, поэтому для приватных репозиториев разумно ставить share: "disabled" или как минимум оставлять ручной режим.²⁰

Отдельный слой безопасности - permissions. В конфиге можно выставить "ask", "allow" или "deny" для групп инструментов, включая read, edit, bash, grep, glob, task и webfetch.¹¹ Для рабочих проектов хороший baseline:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "webfetch": "ask"
  },
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  },
  "disabled_providers": ["some-unapproved-provider"]
}

Плагины могут усиливать это правило, например блокировать чтение .env через hook tool.execute.before.²¹ Но такой плагин не заменяет нормальную модель секретов: API-ключи лучше держать в password manager, environment variables или auth storage, а не в репозитории.⁶

Плагины: как устроены

Плагины в OpenCode - это JavaScript/TypeScript-модули, которые возвращают hooks и могут реагировать на события, менять поведение инструментов, добавлять custom tools, интегрироваться с внешними сервисами и модифицировать окружение shell.²¹ Их можно загружать двумя способами: локально из .opencode/plugins/ или ~/.config/opencode/plugins/, либо из npm через массив plugin в конфиге.²¹

Пример подключения npm-плагинов:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-helicone-session",
    "opencode-wakatime"
  ]
}

npm-плагины устанавливаются автоматически через Bun при старте и кэшируются в ~/.cache/opencode/node_modules/.²¹ Порядок загрузки: глобальный config, проектный config, глобальная директория плагинов, проектная директория плагинов.²¹ Это важно для диагностики, потому что несколько hooks выполняются последовательно, а проектный локальный плагин может менять поведение после глобальных настроек.²¹

Плагины подписываются на события command.executed, file.edited, permission.asked, session.compacted, session.idle, tool.execute.before, tool.execute.after, shell.env, tui.toast.show и другие.²² Кроме hooks, плагин может зарегистрировать custom tool через helper tool() из @opencode-ai/plugin.²³

Какие плагины есть

Официальная страница Ecosystem на 27 апреля 2026 года перечисляет несколько десятков community-плагинов.⁵ Их удобно разделить по задачам:

Официальный список - не знак безусловного качества. Это каталог community-проектов, который пополняется через PR.⁵ Поэтому перед установкой стоит проверять README, лицензию, активность репозитория, модель threat surface и то, какие hooks использует плагин.

Что рекомендуется использовать

Базовый набор для индивидуальной разработки:

1. opencode-dynamic-context-pruning - если часто доходите до лимита контекста. README плагина описывает автоматическое уменьшение token usage через compress tool, deduplication и purge errors; история сессии при этом не модифицируется, а pruned content заменяется placeholders перед отправкой к LLM.²⁴
2. opencode-vibeguard или локальный .env protection plugin - если в репозитории есть секреты, PII или production-конфиги. Официальная документация показывает, как hook tool.execute.before может запретить чтение .env.²¹
3. opencode-notifier или opencode-notify - если агент выполняет длинные задачи и нужно получать уведомления о завершении, ошибках или permission prompts.⁵
4. opencode-worktree, opencode-devcontainers или opencode-daytona - если вы часто запускаете несколько агентов параллельно или хотите изолировать изменения.⁵

Для команд и компаний:

1. opencode-helicone-session или аналог observability - если нужен аудит LLM-запросов, группировка сессий и контроль расходов через gateway.²⁵
2. opencode-sentry-monitor - если OpenCode используется в CI, GitHub Actions или как часть более крупной агентной системы.⁵
3. opencode-shell-strategy - если агенты часто зависают на интерактивных shell-командах; плагин/инструкции ориентированы на non-interactive flags и environment variables для headless-сред.²⁶
4. opencode-workspace или oh-my-opencode - если нужен готовый opinionated harness с агентами, hooks, MCP и workflow, но его стоит внедрять после пилота, потому что такие пакеты меняют сразу много поведения.⁵

Чего не стоит делать: ставить плагины для auth, shell, context pruning, memory и orchestration одновременно без проверки. Каждый плагин расширяет поверхность доверия: он может видеть события сессии, менять окружение shell, добавлять tools или модифицировать запросы.²²

Рекомендуемый opencode.jsonc

Для приватного проекта с осторожными permissions:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/gpt-5.5",
  "small_model": "opencode/gpt-5-nano",
  "share": "disabled",
  "permission": {
    "*": "ask",
    "read": "allow",
    "edit": "ask",
    "bash": "ask",
    "webfetch": "ask"
  },
  "instructions": [
    "AGENTS.md",
    "CLAUDE.md",
    "CONTRIBUTING.md",
    ".cursor/rules/*.md"
  ],
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**", "public/**"]
  },
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  },
  "plugin": [
    "opencode-notify"
  ]
}

Для локального OpenAI-compatible gateway:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local-gateway": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Local Gateway",
      "options": {
        "baseURL": "http://127.0.0.1:4000/v1",
        "apiKey": "{env:LOCAL_GATEWAY_API_KEY}"
      },
      "models": {
        "coder": {
          "name": "Local Coder",
          "limit": {
            "context": 131072,
            "output": 16384
          }
        }
      }
    }
  },
  "model": "local-gateway/coder",
  "share": "disabled"
}

Такой config явно задает provider id, npm adapter, endpoint, API key из окружения, модели и лимиты контекста.¹⁹

Практический workflow

Для повседневной работы лучше начинать с plan, когда нужно понять код или составить план без изменений, и переключаться на build только когда нужно править файлы.⁸ Для больших задач полезно настроить отдельного review-agent с edit: deny, потому что agent-specific permissions переопределяют глобальные настройки.⁸

Обычный цикл:

opencode
# /connect
# /models
# Tab -> plan
# попросить анализ
# Tab -> build
# попросить реализацию
# проверить diff и тесты

Для automation:

opencode run "Найди flaky-тесты и предложи минимальный фикс"
opencode models openai
opencode auth list
opencode mcp list

Команда opencode models [provider] показывает доступные модели в формате provider/model, что полезно перед фиксацией model в конфиге.⁶

Ограничения и спорные места

Первое ограничение - быстро меняющаяся матрица моделей. Даже официальная страница Models предупреждает, что список рекомендованных моделей не исчерпывающий и не обязательно актуален.⁹ Поэтому выбор модели надо периодически перепроверять через /models, opencode models --refresh, документацию провайдера и собственные тесты на реальной кодовой базе.⁶

Второе ограничение - плагины еще формируют экосистему. Официальная документация дает API hooks и каталог проектов, но качество community-плагинов неоднородно.⁵ Для production-проекта плагин должен проходить тот же review, что и dev dependency: pin version, read source, проверить hooks, посмотреть license и обновления.

Третье ограничение - локальные модели часто требуют ручной настройки контекста и tool calling. Документация по Ollama прямо указывает, что при проблемах с tool calls стоит увеличить num_ctx.¹⁶ У локального gateway также нужно честно указать limit.context и limit.output, иначе агент может неправильно оценивать остаток контекста.¹⁹

Итоговые рекомендации

Если нужно просто начать, используйте OpenCode Zen или нативного провайдера через /connect, задайте model, small_model, share: "disabled" и permissions ask для edit и bash.⁴ Если уже есть корпоративный AI gateway, добавьте его как custom provider через @ai-sdk/openai-compatible, environment-based API key и явные model limits.¹⁹

Плагины подключайте по одному и только под конкретную боль: context pruning для длинных сессий, secret redaction для приватных данных, notifications для долгих задач, worktree/devcontainer isolation для параллельной работы.⁵ В production-настройке важнее управляемая конфигурация и понятные permissions, чем максимальное количество расширений.¹¹

Quality Metrics