# Как пользоваться opencode: пошаговое руководство URL: https://agentvera.dev/ru/blog/how-to-use-opencode/ · Опубликовано: 2026-10-27 Как пользоваться opencode: установка, подключение провайдера, выбор модели, переключение между Build и Plan, opencode.json, AGENTS.md, MCP-серверы и команды. **Коротко:** - Установите opencode официальным скриптом или через npm, запустите opencode в проекте, подключите провайдера через /connect и выберите модель через /models; подходит любой провайдер, включая локальные модели. - Tab переключает между агентом Build, который правит файлы и запускает команды, и агентом Plan, который не может менять ваш код и нужен, чтобы сначала продумать изменение. - Настройки хранятся в opencode.json (глобальном и проектном), правила проекта — в AGENTS.md; MCP-серверы задаются под ключом mcp, а свои команды — в .opencode/commands/. Чтобы пользоваться opencode, установите его одной командой, запустите `opencode` в папке проекта, подключите провайдера моделей через `/connect`, выберите модель через `/models` и опишите, что вам нужно. Агент Build, работающий по умолчанию, читает ваш код, правит файлы и запускает команды. Нажмите Tab, чтобы переключиться на агента Plan, когда хотите продумать изменение, не трогая код. Это основной цикл. Остальное — в этом руководстве: провайдеры и локальные модели, команды TUI на каждый день, два встроенных агента, `opencode.json`, `AGENTS.md`, MCP-серверы, свои команды и запуск opencode рядом с другими агентами. Всё здесь опирается на официальную документацию opencode по состоянию на октябрь 2026 года. ## Что такое opencode opencode — это [агент для программирования](/ru/glossary/coding-agent/ "Что такое агент для программирования") в терминале, не привязанный к одной AI-компании. Claude Code использует модели Anthropic, Codex — модели OpenAI. opencode построен на AI SDK и Models.dev, поэтому работает с десятками провайдеров и с локальными моделями. Можно взять одну модель для планирования, другую для реализации и сменить провайдера, не осваивая новый инструмент. Несколько слов о версиях: вышел opencode 2 со своей документацией. Обе версии устанавливают команду `opencode`, и держать обе под этим именем нельзя. Это руководство описывает версию 1 — её устанавливает npm-пакет `opencode-ai`. Большая часть подходит и для версии 2. Если вы ставили его через основную формулу Homebrew или основной репозиторий Arch, у вас, скорее всего, версия 2, так что сверяйтесь с соответствующей документацией. ## Шаг 1: установите opencode | Платформа | Команда | | --- | --- | | macOS, Linux | `curl -fsSL https://opencode.ai/install \| bash` | | Любая платформа с Node.js | `npm install -g opencode-ai` | | macOS, Linux (Homebrew, версия 1) | `brew install anomalyco/tap/opencode` | | Windows | `choco install opencode` или `scoop install opencode` | `bun`, `pnpm` и `yarn global add opencode-ai` тоже работают. В Windows документация советует запускать opencode внутри WSL — так удобнее всего. Лучше всего TUI отображается в современном терминале, например WezTerm, Alacritty, Ghostty или Kitty. opencode никогда не обновляется сам в фоне. Внутри сессии `/update` устанавливает более новый релиз версии 1 или, если у вас уже последняя версия 1, предлагает перейти на версию 2. Из оболочки то же самое делает `opencode upgrade`. ## Шаг 2: подключите провайдера и выберите модель Перейдите в проект и запустите opencode: ```bash cd my-project opencode ``` Затем выполните `/connect` и выберите провайдера. То же можно сделать из оболочки командой `opencode auth login`. Учётные данные сохраняются в `~/.local/share/opencode/auth.json`, а `opencode auth list` показывает, что подключено. opencode также берёт API-ключи из переменных окружения и из файла `.env` в проекте. Несколько распространённых вариантов: - **OpenCode Zen:** отобранный список моделей, которые команда opencode проверила с агентом. Войдите на opencode.ai/auth, добавьте способ оплаты, скопируйте ключ и вставьте его в `/connect`. Документация советует этот вариант новичкам. - **Anthropic:** вставьте API-ключ из Claude Console. Вход через подписку Claude Pro или Max не предлагается. Anthropic не разрешает сторонним инструментам так использовать эти тарифы, и opencode перестал поставлять плагины, которые это делали. - **OpenAI:** выберите «ChatGPT Plus/Pro», чтобы войти через браузер, или введите API-ключ вручную. - **GitHub Copilot:** войдите по коду устройства на github.com/login/device. Некоторым моделям нужен более высокий тариф Copilot. - **Локальные модели:** добавьте свой провайдер, указывающий на OpenAI-совместимый сервер (см. ниже). Когда провайдер подключён, `/models` (или `ctrl+x m`) открывает выбор модели. Из оболочки `opencode models` выводит все модели ваших провайдеров, а `opencode models anthropic` — модели одного провайдера. Модели записываются как `provider/model`, например `anthropic/claude-sonnet-5-5`. У многих моделей есть варианты, например с более высоким reasoning effort, и `ctrl+t` переключает их по кругу. ### Локальные модели через Ollama Локальная модель — это свой провайдер в `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama (local)", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "llama2": { "name": "Llama 2" } } } } } ``` Если с локальной моделью не проходят вызовы инструментов, документация советует поднять `num_ctx` в Ollama примерно до 16k–32k. Обычная причина — слишком маленькое контекстное окно. О том, как вообще выбрать локальную модель, читайте в статье [локальные LLM для агентов программирования](/ru/blog/local-llm-coding-agent/ "Локальные LLM для агентов программирования"). ## Шаг 3: основы TUI Экран opencode — это чат с вашим проектом. Несколько вещей, которыми вы будете пользоваться постоянно: - **`@`** ищет файлы нечётким поиском и добавляет их в сообщение. - **`!`** в начале строки выполняет команду оболочки, например `!npm test`, и кладёт вывод в разговор. - **`ctrl+x`** — leader-клавиша. Большинство сочетаний — это `ctrl+x`, а затем буква. - Изображения можно перетащить в терминал, чтобы приложить их. | Команда | Сочетание | Что делает | | --- | --- | --- | | `/connect` | | Добавить провайдера | | `/models` | `ctrl+x m` | Выбрать модель | | `/new` | `ctrl+x n` | Начать новую сессию | | `/sessions` | `ctrl+x l` | Открыть прошлую сессию | | `/compact` | `ctrl+x c` | Сжать сессию в краткое изложение, освобождая контекст | | `/undo` | `ctrl+x u` | Отменить последнее сообщение и его изменения в файлах | | `/redo` | `ctrl+x r` | Вернуть отменённое | | `/editor` | `ctrl+x e` | Написать длинный запрос в вашем `$EDITOR` | | `/export` | `ctrl+x x` | Экспортировать разговор в Markdown | | `/init` | | Создать или обновить `AGENTS.md` | | `/exit` | `ctrl+x q` | Выйти | `/undo` откатывает изменения в файлах с помощью Git, поэтому проект должен быть Git-репозиторием. Чтобы продолжить с того места, где вы остановились, из оболочки: `opencode -c` открывает последнюю сессию, а `opencode -s ` — конкретную. Для скриптов и CI `opencode run "your prompt"` выполняет одну задачу без TUI. ## Шаг 4: агенты Build и Plan У opencode два основных агента, и Tab переключает между ними: - **Build** работает по умолчанию. У него включены все инструменты: он правит файлы, выполняет команды оболочки и вызывает MCP-серверы. - **Plan** ограничен. Он не может менять ваш код; единственные файлы, которые ему можно писать, — Markdown-планы в `.opencode/plans/`. Он может задавать вам уточняющие вопросы. Для всего нетривиального полезная привычка — начать в Plan, договориться о подходе, затем нажать Tab и поручить Build его выполнить. Есть ещё два субагента, которых вызывают через `@`: `@general` для многошаговых исследований и изменений и `@explore` для быстрого поиска по кодовой базе только на чтение. Каждый работает в дочерней сессии. `ctrl+x`, а затем стрелка вниз открывает её, а стрелка вверх возвращает к родительской. Статья глоссария про [субагента](/ru/glossary/subagent/ "Что такое субагент") объясняет, почему это экономит контекст. Одна ловушка: Plan сам по себе не ограничивает `bash`. Команды оболочки подчиняются вашим настройкам прав. Кроме того, `"edit": "allow"` на верхнем уровне конфига действует и на Plan, потому что побеждают более поздние совпавшие правила. Если хотите полностью закрыть Plan, задайте ему права напрямую: ```json { "$schema": "https://opencode.ai/config.json", "agent": { "plan": { "permission": { "edit": "deny", "bash": "ask" } } } } ``` Своих агентов можно создавать командой `opencode agent create` или Markdown-файлами в `.opencode/agents/` (для проекта) либо `~/.config/opencode/agents/` (глобально). Имя файла становится именем агента. Frontmatter задаёт его `description`, `mode` (`primary` или `subagent`), `model` и `permission`. ## Шаг 5: файл конфигурации opencode читает `opencode.json` (или `opencode.jsonc`, где можно писать комментарии). Обычно он лежит в одном из двух мест: - **Глобально:** `~/.config/opencode/opencode.json`, для ваших настроек по умолчанию. - **В проекте:** `opencode.json` в корне проекта, коммитится вместе с кодом. Файлы объединяются, а не заменяют друг друга, и при пересечении побеждают проектные настройки. Практичный конфиг проекта: ```json { "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-5-5", "small_model": "anthropic/claude-haiku-5-5", "permission": { "edit": "allow", "bash": { "*": "ask", "git status *": "allow", "npm test *": "allow" } }, "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"] } ``` - `model` — модель по умолчанию. `small_model` используется для лёгких задач, например заголовков сессий. - `permission` принимает `allow`, `ask` или `deny` для каждого инструмента, а для `bash` — шаблоны. Побеждает последний совпавший шаблон, поэтому ставьте `"*"` первым. - `instructions` добавляет файлы с правилами поверх `AGENTS.md`. Работают glob-шаблоны и URL. Значения можно брать из окружения через `{env:VAR}` или из файла через `{file:path}`, так что ключам не нужно лежать в конфиге. По умолчанию большинство действий разрешено. Перед чтением файлов `.env` и обращением к папкам за пределами проекта opencode спрашивает. `opencode --auto` одобряет всё, что явно не запрещено, поэтому используйте его только там, где вы спокойно оставили бы агента работать без присмотра. Настройки TUI, такие как тема и сочетания клавиш, хранятся в отдельном `tui.json`. ## Шаг 6: AGENTS.md В `AGENTS.md` хранятся правила проекта: как собирать, тестировать и запускать линтер, каких соглашений держаться, в какие папки не лезть. Выполните `/init`, и opencode просканирует проект и напишет файл за вас. Прочитайте его, сократите и закоммитьте. ```markdown # Project rules - Package manager: pnpm. Run `pnpm test` before you finish a task. - TypeScript strict mode; no `any` in new code. - API handlers live in src/api/; one file per route. - Never edit files in src/generated/. ``` Глобальные правила для всех проектов кладите в `~/.config/opencode/AGENTS.md`. Если вы переходите с Claude Code: когда `AGENTS.md` нет, opencode берёт проектный `CLAUDE.md`, а также читает `~/.claude/CLAUDE.md` и `~/.claude/skills/`. Задайте `OPENCODE_DISABLE_CLAUDE_CODE=1`, чтобы это отключить. Что стоит писать в этот файл, объясняет статья [как написать CLAUDE.md и AGENTS.md](/ru/blog/claude-md-agents-md/ "Как написать CLAUDE.md и AGENTS.md"). ## Шаг 7: MCP-серверы [MCP-серверы](/ru/blog/what-is-mcp-server/ "Что такое MCP-сервер") дают opencode новые инструменты: браузер, трекер задач, поиск по документации. Они задаются под ключом `mcp`. Локальный сервер — это команда, которую запускает opencode; удалённый — это URL: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "mcp_everything": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-everything"] }, "my-remote": { "type": "remote", "url": "https://my-mcp-server.com", "enabled": true, "headers": { "Authorization": "Bearer {env:MY_MCP_TOKEN}" } } } } ``` `opencode mcp add` добавляет сервер в интерактивном режиме, а `opencode mcp list` показывает, что настроено и подключается ли оно. Удалённые серверы с OAuth входят автоматически, а `opencode mcp auth ` выполняет вход вручную. `opencode mcp debug ` помогает, когда сервер не подключается. Каждый сервер добавляет свои инструменты в контекст каждого запроса, а некоторые крупные, например GitHub MCP-сервер, добавляют много. Включайте только нужные серверы, а `"enabled": false` позволяет оставить сервер настроенным, но выключенным. ## Шаг 8: свои команды Своя команда — это запрос, который иначе пришлось бы набирать снова и снова. Положите Markdown-файл в `.opencode/commands/` (для проекта) или `~/.config/opencode/commands/` (глобально); имя файла становится командой: ```markdown --- description: Run tests with coverage agent: build --- Run the full test suite with coverage report and show any failures. Focus on the failing tests and suggest fixes. ``` Сохранённый как `.opencode/commands/test.md`, этот файл становится командой `/test`. Команды принимают аргументы: `$ARGUMENTS` — всё после имени команды, `$1`, `$2` и так далее — отдельные аргументы, `` !`git diff --staged` `` вставляет вывод команды оболочки, а `@src/file.ts` подключает файл. Команды можно также описать под ключом `command` в `opencode.json` с полем `template`. Если своя команда называется так же, как встроенная, побеждает встроенная. ## Частые ошибки - **«No provider» при первом запуске.** Ещё ничего не подключено. Выполните `/connect`. - **Правки в режиме Plan.** Глобальный `"edit": "allow"` действует и на Plan. Задайте `agent.plan.permission` явно. - **`/undo` не откатывает файлы.** Папка не является Git-репозиторием. - **Конфликт двух версий opencode.** Основная формула Homebrew ставит версию 2, а npm — версию 1 под тем же именем команды. Проверьте `opencode --version` и оставьте одну. - **Медленные и дорогие сессии.** Слишком много MCP-серверов или слишком длинная сессия. Отключите серверы и используйте `/compact` или `/new`. ## opencode в панелях AgentVera За одной сессией opencode следить легко. Несколько агентов сразу — часть на opencode, часть на Claude Code или Codex — и вкладки терминала начинают мешать. AgentVera — десктопное приложение, которое запускает эти CLI рядом друг с другом в настоящих терминалах, используя ваши собственные установки и входы. [Поддержка opencode](/ru/agents/opencode/ "opencode в AgentVera") устроена так: - **Ваши провайдеры, ваш вход.** Вы входите к провайдерам в самом opencode (`/connect` или `opencode auth login`), и каждый подключённый провайдер, включая локальные модели, появляется в списке моделей AgentVera, сгруппированный по провайдерам. Варианты моделей отображаются как варианты effort. Если opencode не установлен, AgentVera устанавливает его командой `npm i -g opencode-ai`. - **Одна сессия на агента.** У каждого агента opencode своя сессия, поэтому дублирование агента ответвляет его разговор, а не делит его. `/compact` работает как обычно. - **Ваш opencode.json остаётся нетронутым.** Роль агента, MCP-серверы, добавленные в [менеджере MCP](/ru/features/mcp-manager/ "Менеджер MCP") AgentVera, и браузер AgentVera передаются как дополнительная конфигурация и объединяются с вашей. - **Панели и worktree.** Запускайте opencode рядом с Claude Code в сетке [Workspace](/ru/features/workspace/ "Workspace"), каждого агента в своём [git worktree](/ru/glossary/git-worktree/ "Что такое git worktree"), чтобы они не мешали друг другу в файлах. - **Ревью и flows.** Агенты opencode работают с [автоматическим код-ревью](/ru/features/code-review/ "Автоматическое код-ревью"), а во [flows](/ru/features/flows/ "Flows") (Pro и Team) ответ одного агента может автоматически уходить другому. Например, дешёвая модель планирует, а более сильная реализует. Сетка, worktree, код-ревью и менеджер MCP доступны на бесплатном тарифе. [Скачайте AgentVera](/ru/download/ "Скачать AgentVera") и попробуйте. Если ваша команда ещё и запускает Claude в CI, об этом рассказывает статья [Claude Code GitHub Actions](/ru/blog/claude-code-github-actions/ "Claude Code GitHub Actions"), а [как пользоваться Codex CLI](/ru/blog/how-to-use-codex-cli/ "Как пользоваться Codex CLI") — такое же руководство для агента OpenAI. ## Подведём итог Чтобы пользоваться opencode, установите его, запустите `opencode` в проекте, подключите провайдера через `/connect` и выберите модель через `/models`. Думайте в Plan, меняйте код в Build и переключайтесь между ними через Tab. Настройки по умолчанию храните в `opencode.json`, правила проекта — в `AGENTS.md`, инструменты — под ключом `mcp`, а повторяющиеся запросы — в `.opencode/commands/`. Дальше работа с opencode сводится в основном к выбору подходящей модели для каждой задачи, и сменить её можно когда угодно. ## Частые вопросы **opencode бесплатный?** Установка CLI бесплатна. Вы платите за модели, которыми пользуетесь через провайдера: API-ключ с оплатой за токены, уже имеющаяся подписка вроде GitHub Copilot или ChatGPT Plus/Pro либо OpenCode Zen. Локальные модели через Ollama ничего не стоят, кроме вашего собственного железа. **Какие модели может использовать opencode?** Любого поддерживаемого провайдера: Anthropic, OpenAI, Google, GitHub Copilot, OpenRouter, OpenCode Zen и многих других, а также локальные модели через OpenAI-совместимый сервер, например Ollama. Выполните opencode models, чтобы увидеть, что предлагают подключённые провайдеры. **Чем отличаются агенты Build и Plan?** Build — агент по умолчанию, у него есть все инструменты, поэтому он правит файлы и запускает команды. Plan не может менять ваш код; ему разрешено только писать Markdown-планы в .opencode/plans/. Продумайте изменение в Plan, затем нажмите Tab, чтобы переключиться на Build и выполнить его. **Читает ли opencode CLAUDE.md?** Да, как запасной вариант. Если в проекте нет AGENTS.md, opencode читает CLAUDE.md, а для глобальных правил также обращается к ~/.claude/CLAUDE.md. Задайте OPENCODE_DISABLE_CLAUDE_CODE=1, чтобы отключить эту совместимость с Claude Code. **Где opencode хранит настройки и входы?** Глобальные настройки лежат в ~/.config/opencode/opencode.json, проектные — в opencode.json в корне проекта; они объединяются. Учётные данные провайдеров из /connect хранятся в ~/.local/share/opencode/auth.json. --- **Об AgentVera.** AgentVera — настольное приложение для macOS, Windows и Linux от Solviera Teknoloji. Оно запускает 18 ИИ-агентов для программирования (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) рядом, по проектам, в настоящих терминалах с собственными установками CLI и входами пользователя. В бесплатном тарифе количество агентов не ограничено. Скачать: https://agentvera.dev/ru/download/ · Цены: https://agentvera.dev/ru/pricing/