Перейти к основному содержанию

Как установить и использовать OpenCode: полный гид

BlogsOpenCodeAITerminalCLIОколо 8 мин

Как установить и использовать OpenCode: полный гид

OpenCode — это открытый AI-ассистент для программирования, который приносит возможности искусственного интеллекта прямо в ваш терминал. В отличие от традиционных AI-инструментов для кодирования, работающих в редакторах или браузерах, OpenCode предоставляет терминальный интерфейс, настольное приложение и расширение для IDE — всё для повышения вашей продуктивности как разработчика. В этом подробном руководстве мы подробно рассмотрим всё, что нужно знать, чтобы эффективно установить, настроить и использовать OpenCode.

Что такое OpenCode?

OpenCode — AI-ассистент для программирования, который помогает вам:

  • Писать код быстрее с помощью интеллектуальной генерации и автодополнения
  • Эффективно отлаживать код, анализируя ошибки и предлагая исправления
  • Понимать кодовую базу через запросы на естественном языке
  • Добавлять функционал с помощью автоматизированного планирования и реализации
  • Проверять код с помощью AI-анализа и рекомендаций
  • Автоматизировать рабочие процессы с AI-агентами и кастомными инструментами

Он поддерживает множество провайдеров LLM, включая Anthropic, OpenAI, Google и других, давая вам свободу выбора моделей, которые лучше всего подходят под ваши задачи.

Системные требования

Предварительные требования

Перед установкой OpenCode убедитесь, что у вас есть:

  1. Современный эмулятор терминала (для работы с TUI):

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

  2. Node.js (для установки через npm/bun/pnpm/yarn):

    • Рекомендуется Node.js версии 18 и выше

  3. API-ключи для провайдеров LLM:

    • Ключ Anthropic API (для моделей Claude)
    • Ключ OpenAI API (для моделей GPT)
    • Или ключи от других поддерживаемых провайдеров

Методы установки

Метод 1: Скрипт установки (рекомендуется)

Самый быстрый способ установить OpenCode — использовать официальный скрипт установки:

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

Этот метод работает на macOS, Linux и Windows (с Git Bash или WSL).

Метод 2: Использование менеджеров пакетов Node.js

Через npm:

npm install -g opencode-ai

Через Bun:

bun install -g opencode-ai

Через pnpm:

pnpm install -g opencode-ai

Через Yarn:

yarn global add opencode-ai

Метод 3: Использование Homebrew (macOS и Linux)

brew install opencode

Метод 4: Использование Paru (Arch Linux)

paru -S opencode-bin

Метод 5: Установки, специфичные для Windows

Через Chocolatey:

choco install opencode

Через Scoop:

scoop bucket add extras
scoop install extras/opencode

Через Mise:

mise use -g github:sst/opencode

Метод 6: Docker

Для работы в контейнере:

docker run -it --rm ghcr.io/sst/opencode

Метод 7: Скачивание бинарного файла

Вы можете скачать скомпилированный бинарник напрямую с страницы релизов на GitHub.

Проверка установки

После установки проверьте, что всё работает:

opencode --version

Должен отобразиться номер версии.

Начальная настройка

Подключение к OpenCode Zen (рекомендуется для новичков)

OpenCode Zen — это курируемый список моделей, протестированных и подтверждённых командой OpenCode. Это самый простой способ начать работу.

  1. Запустите OpenCode:
cd /path/to/your/project
opencode
  1. Выполните команду connect в TUI:
/connect

  1. Выберите "opencode" из списка провайдеров

  2. Перейдите по URL для аутентификации: opencode.ai/auth

  3. Войдите в систему и добавьте данные для оплаты (или используйте бесплатные кредиты, если доступны)

  4. Скопируйте ваш API-ключ и вставьте его в терминал по запросу

Подключение к другим провайдерам

Вы также можете подключить OpenCode к другим провайдерам LLM:

Используя команду /connect:

/connect

Выберите предпочитаемого провайдера (Anthropic, OpenAI, Google и т. д.) и следуйте шагам аутентификации.

Через CLI аутентификацию:

opencode auth login

Этот процесс поможет настроить API-ключи для любого провайдера на Models.dev.

Просмотр списка настроенных провайдеров:

opencode auth list

или коротко:

opencode auth ls

Выход из учётной записи провайдера:

opencode auth logout

Настройка контекста проекта

После настройки провайдера инициализируйте OpenCode для вашего проекта:

  1. Перейдите в папку проекта:
cd /path/to/your/project
  1. Запустите OpenCode:
opencode
  1. Выполните команду init:
/init

Это проанализирует структуру вашего проекта и создаст файл AGENTS.md в корне проекта. Этот файл помогает OpenCode лучше понять ваши шаблоны кодирования, фреймворки и архитектуру.

Совет: Добавьте AGENTS.md в Git. Это поможет поддерживать консистентность команды и улучшит понимание проекта OpenCode со временем.

Использование терминального пользовательского интерфейса (TUI)

TUI OpenCode предлагает интерактивный опыт прямо в терминале.

Запуск TUI

Просто запустите:

opencode

Или с дополнительными параметрами:

# Продолжить последнюю сессию
opencode --continue

# Продолжить определённую сессию
opencode --session <session-id>

# Запустить с подсказкой
opencode --prompt "Explain this codebase"

# Использовать конкретную модель
opencode --model anthropic/claude-sonnet-4-5

# Использовать определённого агента
opencode --agent plan

Основы навигации в TUI

  • Прокрутка: колёсиком мыши или стрелками клавиатуры
  • Переключение режимов: нажмите Tab для переключения между режимом Планирования и Режимом Создания
  • Выполнение команд: введите / для вызова командной палитры
  • Поиск файлов: используйте @ для нечёткого поиска файлов в проекте
  • Выход: нажмите Ctrl+C или введите /exit

Задание вопросов

Вы можете задавать OpenCode вопросы о вашем коде:

How is authentication handled in @packages/functions/src/api/index.ts

Используйте символ @, чтобы ссылаться на конкретные файлы. OpenCode анализирует эти файлы и предоставляет подробные объяснения.

Добавление функционала

OpenCode отлично подходит для добавления новых функций через двухрежимный рабочий процесс:

Шаг 1: Режим Планирования

  1. Переключитесь в Режим Планирования, нажав Tab
  2. Опишите, что хотите:
When a user deletes a note, we'd like to flag it as deleted in the database.
Then create a screen that shows all the recently deleted notes.
From this screen, the user can undelete a note or permanently delete it.
  1. Просмотрите предложенный план
  2. Вносите правки, давая обратную связь:
We'd like to design this new screen using a design I've used before.
[Image #1] Take a look at this image and use it as a reference.

Совет: Вы можете перетаскивать изображения в терминал — OpenCode отсканирует и проанализирует их.

Шаг 2: Режим Создания

  1. Переключитесь в Режим Создания, снова нажав Tab
  2. Одобрите реализацию:
Sounds good! Go ahead and make the changes.

OpenCode реализует функцию, создавая и изменяя файлы по необходимости.

Прямые изменения

Для простых изменений можно пропустить планирование:

We need to add authentication to the /settings route.
Take a look at how this is handled in the /notes route
in @packages/functions/src/notes.ts and implement the same logic
in @packages/functions/src/settings.ts

Отмена и повтор изменений

Сделали ошибку? Используйте команду отмены:

/undo

Она отменит последние изменения и позволит уточнить запрос.

Чтобы повторить отменённые изменения:

/redo

Команду /undo можно использовать несколько раз для отмены множества изменений.

Команды CLI

OpenCode предоставляет мощный CLI для программного доступа и автоматизации.

Выполнение запросов напрямую

Запускайте OpenCode без интерактива:

opencode run "Explain how closures work in JavaScript"

Полезно для скриптов, автоматизации или быстрых ответов без запуска TUI.

Управление моделями

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

opencode models

Фильтрация по провайдеру:

opencode models anthropic

Обновить кэш моделей (полезно при добавлении новых моделей):

opencode models --refresh

Показать подробную информацию о моделях, включая стоимость:

opencode models --verbose

Запуск безголового сервера

Поднять HTTP-сервер для API доступа:

opencode serve

С указанием порта:

opencode serve --port 3000

Это удобно для интеграции OpenCode в веб-приложения или для ускорения откликов в скриптах (без «холодного» старта MCP сервера).

Подключение к серверу

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

opencode serve

В другом терминале подключитесь к нему для быстрого выполнения:

opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

Управление агентами

Создать нового кастомного агента:

opencode agent create

Пошаговая инструкция для создания агента с кастомными системными подсказками и настройками инструментов.

Интеграция с GitHub

Установить агента GitHub для автоматизации репозитория:

opencode github install

Настроит workflows GitHub Actions для автоматического ревью кода и управления issue.

Обновление OpenCode

Обновиться до последней версии:

opencode upgrade

Или до конкретной версии:

opencode upgrade v0.1.48

Указать метод установки при необходимости:

opencode upgrade --method brew

Конфигурация

OpenCode поддерживает гибкую конфигурацию через JSON-файлы.

Расположение конфигураций

Файлы конфигураций объединяются (не заменяются), что позволяет иметь глобальные, проектные и пользовательские настройки.

  1. Глобальная конфигурация: ~/.config/opencode/opencode.json

    • Для тем, провайдеров, хоткеев и общих настроек

  2. Проектная конфигурация: opencode.json в корне проекта

    • Для специфичных провайдеров, агентов или настроек проекта
    • Можно безопасно коммитить в Git

  3. Путь к пользовательской конфигурации: задаётся переменной окружения OPENCODE_CONFIG

  4. Путь к директории конфигураций: задаётся переменной OPENCODE_CONFIG_DIR

Пример базовой конфигурации

Создайте конфиг с такой структурой:

{
  "$schema": "https://opencode.ai/config.json",
  
  // Выбор темы
  "theme": "opencode",
  
  // Основная модель
  "model": "anthropic/claude-sonnet-4-5",
  
  // Лёгкая модель для простых задач
  "small_model": "anthropic/claude-haiku-4-5",
  
  // Настройка автообновления
  "autoupdate": true
}

Настройка провайдеров

Конфигурируйте API-ключи напрямую в конфиге:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

Рекомендуется использовать переменные окружения для безопасности. Синтаксис: {env:ИМЯ_ПЕРЕМЕННОЙ}.

Использование ссылок на файлы

Можно указывать файлы с чувствительными данными:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Кастомные команды

Определяйте повторяющиеся задачи через пользовательские команды:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run full test suite with coverage report and show any failures.\nFocus on failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

Используйте их в TUI, вводя /test или /component MyComponent.

Кастомные агенты

Создавайте специализированных агентов:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Настройка прав доступа

Контролируйте, что OpenCode может делать без запроса:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Потребуется подтверждение пользователя для операций редактирования и выполнения bash.

Форматтеры кода

Настройте автоматическое форматирование кода:

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": false
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Настройки TUI

Настройте интерфейс терминала:

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

Продвинутые возможности

Совместное использование разговоров

Делитесь диалогами с командой:

/share

Создаёт ссылку для общего доступа и копирует её в буфер обмена. Разговоры по умолчанию не публикуются.

Настройка поведения шаринга:

{
  "share": "manual"  // "manual", "auto" или "disabled"
}

MCP-серверы

Протокол Model Context Protocol (MCP) расширяет возможности OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  }
}

Инструкции и правила

Задавайте проектно-специфичные инструкции:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

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

Переменные окружения

Настраивайте OpenCode через переменные окружения:

# Автоматически делиться сессиями
export OPENCODE_AUTO_SHARE=true

# Путь к конфигу
export OPENCODE_CONFIG=/path/to/config.json

# Путь к директории конфигов
export OPENCODE_CONFIG_DIR=/path/to/config-dir

# Отключить автообновление
export OPENCODE_DISABLE_AUTOUPDATE=true

# Отключить стандартные плагины
export OPENCODE_DISABLE_DEFAULT_PLUGINS=true

# Включить экспериментальные модели
export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true

# Включить веб-поиск Exa
export OPENCODE_ENABLE_EXA=true

Экспериментальные функции

Включить экспериментальные функции:

export OPENCODE_EXPERIMENTAL=true

Конкретные экспериментальные возможности:

# Включить обнаружение иконок
export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true

# Отключить копирование по выделению в TUI
export OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT=true

# Максимальная длина вывода для bash-команд
export OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH=10000

# Таймаут по умолчанию для bash-команд (мс)
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=30000

Лучшие практики

Эффективное составление запросов (prompt)

  1. Будьте конкретны: давайте чёткие и подробные инструкции
  2. Используйте контекст: ссылайтесь на файлы с помощью @ для лучшего понимания
  3. Приводите примеры: показывайте образцы желаемого результата
  4. Разбивайте сложные задачи: лучше делать поэтапно

Работа с большими проектами

  1. Используйте /init: чтобы OpenCode понял структуру проекта
  2. Ссылайтесь на конкретные файлы: через @ для ограничения контекста
  3. Используйте Режим Планирования: для ревью планов перед реализацией
  4. Делайте изменения постепенно: маленькими управляемыми шагами

Оптимизация затрат

  1. Используйте лёгкие модели: настройте small_model для простых задач
  2. Планируйте перед реализацией: чтобы сократить количество итераций
  3. Кастомные команды: настройте эффективные сценарии для стандартных задач
  4. Контролируйте использование: проверяйте статистику в панелях провайдеров

Рекомендации по безопасности

  1. Никогда не коммитьте API-ключи: используйте переменные окружения
  2. Настраивайте права: используйте параметр permission для подтверждения чувствительных операций
  3. Проверяйте изменения: всегда просматривайте предлагаемые OpenCode коррекции
  4. Используйте отдельные ключи: создавайте ключи специально для OpenCode с ограничениями по доступу

Устранение неполадок

Проблемы с установкой

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

Решение:

  • Проверьте установку: which opencode
  • Проверьте PATH: echo $PATH
  • Попробуйте полный путь: ~/.local/bin/opencode
  • Переустановите другим способом

Проблемы с аутентификацией

Проблема: API-ключ не распознаётся

Решение:

  • Проверьте корректность ключа: opencode auth list
  • Проверьте переменные окружения: echo $ANTHROPIC_API_KEY
  • Повторите аутентификацию: opencode auth login

Проблемы с производительностью

Проблема: Медленные отклики

Решение:

  • Используйте opencode serve для ускорения
  • Переключитесь на более быструю модель
  • Используйте меньшие контексты
  • Отключите неиспользуемые инструменты в конфиге

Проблемы с TUI

Проблема: Ошибки отображения в терминале

Решение:

  • Используйте современный эмулятор терминала (WezTerm, Alacritty и др.)
  • Убедитесь, что терминал поддерживает 24-битные цвета
  • Попробуйте другую тему
  • Отключите ускорение прокрутки при проблемах

Проблемы с моделями

Проблема: Модель не найдена

Решение:

  • Обновите список моделей: opencode models --refresh
  • Проверьте, что провайдер настроен: opencode auth list
  • Проверьте формат имени модели: provider/model
  • Убедитесь, что модель доступна у провайдера

Встраивание OpenCode в ваш рабочий процесс

Ежедневная разработка

  1. Утро: запускайте /init для синхронизации с последними изменениями кода
  2. Работа над функционалом: используйте Режим Планирования для проектирования, затем Режим Создания для реализации
  3. Отладка: задавайте вопросы об ошибках с ссылками на файлы
  4. Код-ревью: применяйте кастомного агента для проверки кода
  5. Документация: генерируйте документацию через кастомные команды

Совместная работа в команде

  1. Делитесь конфигами: коммитьте opencode.json и AGENTS.md в Git
  2. Делитесь диалогами: используйте /share для обсуждения реализаций
  3. Кастомные команды: определяйте командные сценарии для всей команды в конфиге проекта
  4. Консистентные агенты: используйте общие описания агентов для единообразия

Интеграция CI/CD

  1. Агент GitHub: установите для автоматического ревью PR
  2. Тестирование: используйте кастомные команды тестирования в CI
  3. Качество кода: настройте форматтеры и права доступа

Заключение

OpenCode представляет новый подход к разработке с помощью AI, предоставляя мощные AI-возможности прямо в вашем терминале. Благодаря гибкой настройке, поддержке множества LLM провайдеров и интуитивному интерфейсу TUI он создан для повышения вашей продуктивности без нарушения привычного процесса работы.

Основные выводы:

  • Устанавливайте через скрипт установки или предпочитаемый менеджер пакетов
  • Настраивайте API-ключи через /connect или opencode auth login
  • Инициализируйте проекты с помощью /init для лучшего понимания контекста
  • Используйте Режим Планирования для сложных функций, Режим Создания — для прямых изменений
  • Кастомизируйте с помощью конфигураций, команд и агентов
  • Автоматизируйте задачи через CLI-команды
  • Соблюдайте правила безопасности с ключами и правами доступа

Дальнейшие шаги:

  • Изучите документацию OpenCode для продвинутых возможностей
  • Присоединяйтесь к сообществу OpenCode в Discord
  • Настройте темы и хоткеи под себя
  • Экспериментируйте с разными провайдерами LLM и моделями
  • Интегрируйте OpenCode в рабочий процесс вашей команды

Готовы прокачать ваш процесс разработки?
Посмотрите решения LightNode для AI-оптимизированного хостинга — развертывайте AI-приложения на выделенных GPU инстансах с масштабируемой инфраструктурой.

OpenCode — это open source проект, который постоянно развивается. Вносите свой вклад, сообщайте об ошибках или делитесь опытом, чтобы сделать его ещё лучше для всех. Удачного кодинга!

Сэкономьте на дешевом VPS-хостинге。