Руководство по началу работы с OpenCode

OpenCode — это открытый ИИ-агент для программирования, который поддерживает взаимодействие с ИИ в терминале, настольных приложениях и популярных IDE (например, VS Code) для выполнения задач, связанных с кодом.

OpenCode может помочь нам понимать кодовые базы, писать новые функции, рефакторить код, исправлять ошибки и многое другое, значительно повышая эффективность разработки.

OpenCode похож на режим Code от Claude или функцию Agent от Cursor, но он полностью открытый, ориентирован на приватность, поддерживает несколько больших языковых моделей (LLM) и делает акцент на работе в терминале.

OpenCode поддерживает 75+ поставщиков моделей, включает встроенные бесплатные модели, такие как GLM-4.7 и MiniMax M2.1, может подключаться к коммерческим моделям от OpenAI, Anthropic, Google и др., а также позволяет настраивать локальные модели (например, Llama 3), адаптируясь к разным сценариям — от лёгких скриптов до сложных архитектур — по мере необходимости.

Полное руководство по OpenCode см. здесь:https://www.example.com/opencode/opencode-tutorial.html

Ключевые особенности

Два встроенных режима агента:

  • Режим Build:Полные разрешения, можно напрямую редактировать файлы и выполнять команды.
  • Режим Plan:Планирование только для чтения, редактирование по умолчанию запрещено и требует подтверждения.

Набор инструментов:Выполнение bash, чтение/запись файлов, поиск grep, диагностика LSP и т. д.

Осведомлённость о контексте:Автоматически анализирует структуру проекта и создаёт рекомендации AGENTS.md.

Общий доступ и совместная работа:Создайте ссылку для совместного использования сеанса одним нажатием.


Установка OpenCode

OpenCode поддерживает установку на нескольких платформах: macOS / Windows / Linux.

Универсальный скрипт установки в один клик — это самый простой способ:

curl -fsSL https://opencode.ai/install | bash

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

opencode --version

Если вывод похож на1.1.19такую информацию о версии, установка прошла успешно.

Установка через менеджер пакетов

macOS / Linux

brew install opencode

Или:

npm install -g opencode-ai

Windows

choco install opencode

Или:


scoop bucket add extras
scoop install extras/opencode

Arch Linux

paru -S opencode-bin

OpenCode работает в терминале. Мы можем использовать терминал по умолчанию, входящий в систему, или воспользоваться некоторыми полезными современными терминальными инструментами:

  • WezTerm, кроссплатформенный
  • Alacritty, кроссплатформенный
  • Ghostty, Linux и macOS
  • Kitty, Linux и macOS

Настольное приложение

OpenCode также предоставляет десктопное приложение, которое можно скачать напрямую состраницы релизовилиopencode.ai/download.

Системная платформа Пакет для скачивания
macOS (Apple Silicon) opencode-desktop-darwin-aarch64.dmg
macOS (Intel) opencode-desktop-darwin-x64.dmg
Windows opencode-desktop-windows-x64.exe
Linux форматы .deb, .rpm или AppImage

Запуск и использование

Чтобы запустить OpenCode, просто введите команду запуска в терминале:

opencode

При первом запуске вам будет предложено пройти базовую настройку:

  • Выбор модели:По умолчанию отображается список доступных моделей. Вы можете напрямую выбрать бесплатные модели с пометкой Free (например, MiniMax M2.1, GLM-4.7) и использовать их без API Key.
  • Варианты входа:Вы можете пропустить вход и настроить API-ключ позже, когда потребуется подключить коммерческие модели. Также можно войти с аккаунтом Claude Code Pro, чтобы использовать эксклюзивные модели.

После успешного запуска вы попадаете в интерфейс TUI и можете начать использовать основные функции.

Мы можем ввести /models в терминале, чтобы просмотреть доступные бесплатные модели:

Во всплывающем окне те, у которых справа указано слово Free, являются бесплатными:

Настройка API-ключей и моделей

Если вы хотите подключить API-ключ AI-провайдера, например OpenAI или Anthropic Claude, выполните:

opencode auth login

Или после запуска в терминале введите:

/connect

Выберите модель. Следуйте подсказкам, чтобы войти и вставить ваш API-ключ.

Вы также можете использовать коллекцию моделейZen(высококачественные модели, официально рекомендованные и протестированные OpenCode), что избавит вас от необходимости самостоятельно управлять несколькими внешними аккаунтами.

Если вы больше не хотите это использовать, вы можете выйти с помощью следующей команды:

/exit 

Базовое использование

Запуск OpenCode

Введите каталог проекта, с которым хотите работать:

cd /path/to/your/project
opencode

Например, давайте создадим каталог opencode-example-test:

mkdir opencode-example-test
cd opencode-example-test

Затем выполните команду:

opencode

Если возникли проблемы с правами доступа, можно использовать:

sudo opencode

Это откроет терминальный пользовательский интерфейс OpenCode (TUI).

Инициализация проекта

В интерфейсе OpenCode выполните:

/init

Это создаст папку .opencode/ для хранения векторизованного индекса проекта и пользовательских инструкций.

Он просканирует структуру кода текущего каталога и создаст файл AGENTS.md для записи информации о проекте.

Вы можете увидеть файл AGENTS.md в каталоге opencode-example-test:

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

Create a login page in the current directory.

Далее большая модель начнёт думать и создаст страницу входа:

Сгенерированные файлы:

Задавайте вопросы и объясняйте код

Вы можете напрямую спрашивать OpenCode о деталях кодовой базы на естественном языке:

Какие функции содержит файл @index.html

где@@index.html используется для ссылки на пути к файлам в проекте.

Повседневное взаимодействие

  • Спросите напрямую: например, "Объясните логику аутентификации в src/main.ts".
  • Добавление функций: опишите требование, например "Добавьте API регистрации пользователя с подтверждением по email".
  • Переключение режимов: нажмите клавишу Tab, чтобы переключаться между режимами Plan/Build (Plan безопаснее и используется для планирования).
  • Отменить изменения: /undo
  • Повторить: /redo
  • Поделиться сессией: /share

Интерактивный режим (скриптовый):

opencode -p "修复 login 函数中的 bug"

Введение во встроенные инструменты

AI-агент OpenCode работает с кодовой базой через следующие инструменты (где вы можете управлять разрешениямиopencode.jsonс allow/deny/ask):

  • bash: Выполнение команд оболочки (например,git status、npm test)。
  • write/edit/patch: Создание/изменение/патчинг файлов.
  • read: Чтение содержимого файлов (поддерживает диапазоны строк).
  • grep/glob/list: Поиск и перечисление файлов (учитывает .gitignore).
  • webfetch: Получение содержимого веб-страницы (для документации).
  • lsp(экспериментально): навигация по коду, подсказки при наведении и т.д.
  • question: Запрос подтверждения у вас.
  • todo: Ведение списка задач.

Пользовательские инструменты и поддержка расширений сервера MCP (Model Context Protocol) (например, подключение к базам данных).

Продвинутое использование

  • Пользовательские команды: В~/.config/opencode/commands/создайте файл Markdown, напримерprime-context.md, содержимое — предварительно загруженные инструкции.
  • Тема и привязки клавиш: Настройте внешний вид и сочетания клавиш в настройках.
  • Несколько сессий: Запускайте несколько агентов одновременно для выполнения разных задач.
  • Интеграция с IDE: Сейчас поддерживается расширение для VS Code (ищите расширение OpenCode) или удалённое управление через архитектуру клиент/сервер.
  • Управление разрешениями: Настройте инструменты в файле конфигурации так, чтобыaskвручную подтверждать чувствительные операции.

Создайте простой API на Node.js

  1. Создать новый каталог:mkdir my-api && cd my-api
  2. Инициализация:npm init -y
  3. Запуск OpenCode:opencode
  4. Ввод/init
  5. Вопрос: Создайте сервис на Express.js, который поддерживает маршрут /hello, возвращающий JSON { message: 'Hello World' }, и добавьте README.

oh-my-opencode

oh-my-opencode — это мощный слой плагинов/расширений, разработанный для OpenCode (. Он превращает одного AI-агента в команду совместной работы нескольких агентов, предоставляя расширенные возможности из коробки.

Репозиторий GitHub:https://github.com/code-yeongyu/oh-my-opencode

Ключевые особенности включают:

  • SisyphusОсновной агент: отвечает за непрерывное выполнение сложных задач до завершения.
  • Поддерживает параллельное выполнение специализированных субагентов (таких как Oracle (Пророк), Librarian (эксперт по документации), Frontend-инженер, Explore (исследователь) и т. д.).
  • Встроенные инструменты LSP/AST (рефакторинг кода), MCP (плагины вызова моделей, такие как поиск, извлечение документов), система хуков (25+ триггеров событий).
  • Мультимодельное планирование: автоматически назначает задачи наиболее подходящей модели (например, Gemini для фронтенда, Claude для планирования).
  • Ключевое слово запускает полную автоматизацию (например,ultraworkилиulw), поддерживает фоновые задачи, принудительное выполнение Todo, инъекцию контекста и т. д.
  • Полностью совместим с рабочими процессами Claude Code, с акцентом на высокую производительность, автоматизацию и настраиваемость.

Установка

Рекомендуется позволить OpenCode автоматически выполнить установку. Скопируйте следующий запрос и вставьте его в диалоговое окно OpenCode:

按照以下说明安装和配置 oh-my-opencode:
https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/docs/guide/installation.md

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

Базовый триггер

Добавьте ключевое слово ultrawork (или его сокращение ulw) в промпт OpenCode, например:

ultrawork: 请帮我实现一个 React 组件,支持暗黑模式。

Это активирует полный режим: основной агент Sisyphus берёт управление на себя, автоматически назначает подзадачи специализированным агентам и выполняет их параллельно (фоновое картографирование кодовой базы, глубокое исследование, автоматический рефакторинг и т. д.), пока задача не будет завершена на 100%.


Шпаргалка по общим Slash-командам OpenCode TUI

Slash-команды OpenCode (начинающиеся с/) в основном используются в терминальном пользовательском интерфейсе (TUI) для быстрого управления сеансами, конфигурацией и операциями.

Основная конфигурация и инициализация

Команда Описание Псевдоним/сокращение
/connect Добавить или настроить провайдера LLM (API-ключ) Отсутствует
/init Создать или обновить проектAGENTS.mdфайл (анализ кодовой базы) Ctrl+X I
/models Показать доступные модели и переключиться Ctrl+X M

Управление сессиями

Команда Описание Псевдоним/сокращение
/new Начать новый сеанс (очистить текущий) /clear / Ctrl+X N
/sessions Список сессий и переключение между ними /resume / /continue / Ctrl+X L
/share Поделиться текущей сессией (сгенерировать ссылку) Ctrl+X S
/unshare Отменить общий доступ к текущей сессии Отсутствует
/compact Сжать/суммировать текущую сессию /summarize / Ctrl+X C

Редактирование и отмена

Команда Описание Псевдоним/сокращение
/undo Отменить последнюю операцию (требуется репозиторий Git, поддерживает откат изменений в файлах) Ctrl+X U
/redo Повторить отменённую операцию (требуется репозиторий Git) Ctrl+X R

Просмотр и помощь

Команда Описание Псевдоним/сокращение
/details Переключить отображение деталей выполнения инструментов Ctrl+X D
/thinking Переключить видимость процесса мышления/рассуждения Отсутствует
/theme Список тем и переключение между ними Ctrl+X T
/help Показать диалоговое окно справки Ctrl+X H
/editor Создать сообщение с помощью внешнего редактора Ctrl+X E
/export Экспортировать текущий разговор в Markdown и открыть для редактирования Ctrl+X X

Выход

Команда Описание Псевдоним/сокращение
/exit Выйти из OpenCode /quit / /q / Ctrl+X Q

Примечание:

  • Эти команды можно вызвать, непосредственно набрав/+ имя команды в интерфейсе чата TUI (появится автодополнение).
  • /undoи/redoПроект должен быть Git-репозиторием, чтобы откатить изменения файлов.
  • Вы можете создавать собственные Slash-команды (поместите их в~/.config/opencode/commands/или каталог проекта), которые переопределят встроенные команды.
  • См. официальную документацию для получения дополнительной информации:https://opencode.ai/docs/tui

Шпаргалка по общим параметрам OpenCode CLI

Интерфейс командной строки (CLI) OpenCode в основном используется для запуска TUI (терминального интерфейса), выполнения промптов в неинтерактивном режиме или установки базовых параметров. При запуске по умолчаниюopencodeсразу запустится интерактивный TUI.

Ниже приведены общие глобальные параметры (флаги):

Параметр Сокращение Описание Пример
--help -h Отобразить справочную информацию (список всех доступных параметров) opencode --help
--debug -d Включить режим отладки (выводить больше логов для устранения неполадок) opencode -d
--cwd -c Указать текущую рабочую директорию (переключиться на этот путь при запуске) opencode -c /path/to/your/project
--prompt -p Неинтерактивный режим: напрямую выполнить один запрос и вывести ответ (подходит для скриптов/автоматизации) opencode -p "修复这个 bug"
--output-format -f Формат вывода в неинтерактивном режиме (textилиjson, текст по умолчанию) opencode -p "解释代码" -f json
--quiet -q Скрыть анимацию загрузки (спиннер) в неинтерактивном режиме opencode -p "生成 README" -q

Примеры базового использования

  • Запустить интерактивный TUI:opencode
  • Запустить с отладкой:opencode -d
  • Запустить с указанной директорией проекта:opencode -c ~/my-app
  • Неинтерактивный одиночный запрос:opencode -p "添加一个登录接口" -f json

Примечание:

  • Эти параметры можно комбинировать.
  • Неинтерактивный режим (-p) особенно подходит для CI/CD, скриптов или быстрых запросов, без входа в TUI.
  • Более сложные конфигурации (например, выбор модели) обычно задаются через переменные среды или файлы конфигурации~/.opencode.json, а не через параметры CLI.
  • Запуститеopencode --helpчтобы просмотреть последний полный список (рекомендуется, так как инструмент может обновляться).

Ссылки

Другие расширения