OpenCode Quickstart: Установка, Настройка и Использование Терминального ИИ-Агента для Программирования

Как установить, настроить и использовать OpenCode

Содержимое страницы

OpenCode — это открытый AI-кодинговый агент, который можно запускать в терминале (TUI + CLI) с опциональными настольными и IDE-интерфейсами. Это быстрый старт OpenCode: установка, проверка, подключение модели/провайдера и запуск реальных рабочих процессов (CLI + API).

Примечание о версии: OpenCode обновляется быстро. Команды «последней версии» здесь стабильны, но вывод и настройки могут меняться — всегда сверяйтесь с официальной документацией CLI и changelog (ссылки ниже).

Эта статья является частью Инструментов разработки ИИ: Полное руководство по разработке с использованием ИИ.

Что такое OpenCode (и где он применяется)

OpenCode предназначен для кодинга с акцентом на терминал, сохраняя при этом гибкость в выборе провайдера/модели. На практике это слой рабочего процесса, который может:

  • запускать терминальный интерфейс при выполнении команды opencode
  • выполнять неинтерактивные «одноразовые» запросы через opencode run (скрипты/автоматизация)
  • запускать головной HTTP-сервер через opencode serve (и веб-интерфейс через opencode web)
  • управлять программно через официальный SDK для JS/TS @opencode-ai/sdk

opencode с самонастроенной моделью qwen3.5 27b LLM

Если вы создаете кластер /ai-devtools/, OpenCode — это сильный кандидат для подкластера, так как он естественно расширяется до:

  • углубленного изучения CLI
  • поведения и стоимости моделей/провайдеров (сравнение LLM внутри OpenCode)
  • конфигурации и агентов
  • интеграций (GitHub/GitLab/Copilot)
  • шпаргалки

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

Вам понадобятся:

  • Современный эмулятор терминала (важно для опыта TUI).
  • Доступ хотя бы к одной модели/провайдеру (ключи API или аутентификация по подписке, в зависимости от провайдера).

Установка OpenCode (копировать и вставлять)

Официальный скрипт установки (Linux/macOS/WSL):

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

Опции установки через менеджеры пакетов (официальные примеры):

# Глобальная установка через Node.js
npm install -g opencode-ai

# Homebrew (рекомендуется OpenCode для самых актуальных релизов)
brew install anomalyco/tap/opencode

# Arch Linux (стабильная версия)
sudo pacman -S opencode

# Arch Linux (последняя версия из AUR)
paru -S opencode-bin

Примечания для Windows (официальные рекомендации обычно советуют WSL для лучшей совместимости). Альтернативы включают Scoop/Chocolatey или npm.

# chocoloatey (Windows)
choco install opencode

# scoop (Windows)
scoop install opencode

Docker (полезно для быстрого тестирования):

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

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

opencode --version
opencode --help

Ожидаемый вывод (может варьироваться в зависимости от версии):

# Пример:
# <выводит номер версии, например vX.Y.Z>
# <выводит справку с доступными командами/подкомандами>

Подключение провайдера (два практичных пути)

Путь A: TUI /connect (интерактивный)

Запустите OpenCode:

opencode

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

/connect

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

Путь B: CLI opencode auth login (ключи провайдера)

OpenCode поддерживает настройку провайдеров через:

opencode auth login

Примечания:

  • Учетные данные сохраняются в ~/.local/share/opencode/auth.json.
  • OpenCode также может загружать ключи из переменных окружения или файла .env в вашем проекте.

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

Из вашего репозитория:

cd /path/to/your/repo
opencode

Затем инициализируйте:

/init

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

Основные рабочие процессы CLI (примеры для копирования)

OpenCode поддерживает неинтерактивные запуски:

opencode run "Объясните, как работают замыкания в JavaScript"

Рабочий процесс: генерация кода (CLI)

Цель: сгенерировать небольшую, тестируемую функцию с минимальным контекстом.

opencode run "Напишите функцию на Go ParsePort(envVar string, defaultPort int) (int, error). Она должна читать переменную окружения, разбирать целое число, проверять диапазон 1-65535 и возвращать defaultPort, если она пуста. Включите 3 теста с таблицей."

Ожидаемый вывод:

  • Объяснение плюс блоки кода (функция + тесты). Точный код варьируется в зависимости от модели/провайдера и запроса.

Рабочий процесс: безопасная рефакторизация файла (CLI + агент Plan)

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

opencode run --agent plan --file ./src/auth.ts \
  "Рефакторинг этого файла для уменьшения сложности. Вывод: (1) краткий план, (2) патч в формате unified diff, (3) риски/граничные случаи для тестирования. Не выполняйте команды."

Ожидаемый вывод:

  • Раздел плана + блок патча в формате diff --git ... + список проверок.
  • Содержимое варьируется. Если не создается diff, перезапросите: «Верните только unified diff» или «Используйте формат diff --git».

Рабочий процесс: вопросы по репозиторию (CLI)

Цель: быстро найти детали реализации.

opencode run --agent explore \
  "В этом репозитории, где проверяется аутентификация для API-запросов? Перечислите вероятные файлы и объясните поток. Если не уверены, укажите, что вы проверили."

Ожидаемый вывод:

  • Краткая карта путей к файлам + описание потока.
  • Вывод зависит от размера репозитория и инструментов контекста модели/провайдера.

Рабочий процесс: ускорение повторных запусков CLI с постоянным сервером

Если вы скриптуете или выполняете несколько вызовов opencode run, вы можете один раз запустить головной сервер:

Терминал 1:

opencode serve --port 4096 --hostname 127.0.0.1

Терминал 2:

opencode run --attach http://localhost:4096 "Суммируйте структуру репозитория и основные точки входа."
opencode run --attach http://localhost:4096 "Теперь предложите 3 высокоэффективных рефакторинга и объясните почему."

Ожидаемый вывод:

  • Как и opencode run, но обычно с меньшими повторяющимися накладными расходами на запуск.

Программное использование (официальный SDK для JS/TS)

OpenCode предоставляет HTTP-сервер (OpenAPI) и типобезопасный клиент для JS/TS.

Установка:

npm install @opencode-ai/sdk

Пример: запуск сервера + клиента, затем запрос

Создайте scripts/opencode-sdk-demo.mjs:

import { createOpencode } from "@opencode-ai/sdk";

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    // Формат строки модели: провайдер/модель (пример только)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`Сервер работает по адресу: ${opencode.server.url}`);

// Базовая проверка здоровья/версии
const health = await opencode.client.global.health();
console.log("Здоровый:", health.data.healthy, "Версия:", health.data.version);

// Создание сессии и запрос
const session = await opencode.client.session.create({ body: { title: "SDK quickstart demo" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Сгенерируйте небольшой раздел README, описывающий этот репозиторий." }],
  },
});

console.log(result.data);

// Закрытие сервера по завершении
opencode.server.close();

Запуск:

node scripts/opencode-sdk-demo.mjs

Ожидаемый вывод:

  • «Сервер работает по адресу …»
  • Ответ о здоровье, включая строку версии
  • Объект ответа сеанса запроса (точная структура зависит от responseStyle и версии SDK)

Минимальная конфигурация OpenCode, которую можно скопировать

OpenCode поддерживает конфигурации в форматах JSON и JSONC. Это разумная отправная точка для локальной конфигурации проекта.

Создайте opencode.jsonc в корне репозитория:

{
  "$schema": "https://opencode.ai/config.json",

  // Выберите модель по умолчанию (провайдер/модель). Сохраняйте согласованность с тем, что показывает `opencode models`.
  "model": "provider/model",

  // Опционально: более дешевая «маленькая модель» для легких задач (заголовки и т.д.)
  "small_model": "provider/small-model",

  // Опционально: настройки сервера OpenCode по умолчанию (используются для serve/web)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

  // Опционально: безопасность: требуйте подтверждения перед редактированием/командами
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Короткая шпаргалка (быстрая справка)

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

opencode                       # запуск TUI
opencode run "..."             # неинтерактивный запуск (автоматизация)
opencode run --file path "..." # присоединение файлов к запросу
opencode models --refresh      # обновление списка моделей
opencode auth login            # настройка учетных данных провайдера
opencode serve                 # головной HTTP-сервер (OpenAPI)
opencode web                   # головной сервер + веб-интерфейс
opencode session list          # список сессий
opencode stats                 # статистика токенов/стоимости

Команды TUI, которые стоит запомнить

/connect   # подключение провайдера
/init      # анализ репозитория, генерация AGENTS.md
/share     # общий доступ к сессии (если включено)
/undo      # отмена изменения
/redo      # повтор изменения
/help      # справка/сокращения

Концепция «лидерского ключа» по умолчанию (TUI)

OpenCode использует настраиваемый «лидерский» ключ (обычно ctrl+x) для избежания конфликтов в терминале. Многие сокращения — это «Лидер + ключ».

Одностранный печатный чизшит OpenCode

Эта версия специально сжата и «удобна для печати». (Вы можете позже вставить её на страницу /ai-devtools/opencode/cheatsheet/)

Задача Команда / сочетание клавиш Примечания
Запуск TUI opencode По умолчанию запускается терминальный интерфейс
Запуск одноразового запроса opencode run "..." Неинтерактивный режим для скриптов/автоматизации
Прикрепление файлов к запросу opencode run --file path/to/file "..." Используйте несколько флагов --file для нескольких файлов
Выбор модели для запуска opencode run --model provider/model "..." Строки моделей имеют формат provider/model
Выбор агента opencode run --agent plan "..." План предназначен для более безопасной работы «без изменений» (ограниченные разрешения)
Список моделей opencode models [provider] Используйте --refresh для обновления кэшированного списка
Настройка учетных данных провайдера opencode auth login Сохраняет учетные данные в ~/.local/share/opencode/auth.json
Список аутентифицированных провайдеров opencode auth list / opencode auth ls Подтверждает, что OpenCode видит
Запуск сервера в фоновом режиме opencode serve --port 4096 --hostname 127.0.0.1 OpenAPI спецификация доступна по адресу http://host:port/doc
Прикрепление запусков к серверу opencode run --attach http://localhost:4096 "..." Полезно для избежания повторных холодных запусков
Включение базовой аутентификации OPENCODE_SERVER_PASSWORD=... opencode serve Имя пользователя по умолчанию opencode, если не переопределено
Веб-интерфейс opencode web Запускает сервер + открывает браузер
Экспорт сессии opencode export [sessionID] Полезно для архивирования или обмена контекстом
Импорт сессии opencode import session.json Можно также импортировать из URL-адреса для обмена
Просмотр глобальных флагов CLI opencode --help / opencode --version --print-logs + --log-level для отладки
Концепция лидирующего ключа TUI ключ лидера по умолчанию часто ctrl+x Настраивается в tui.json

Источники (официальные в первую очередь)

Официальные:

Авторитетный справочник интеграции:

Надежные сравнения/уроки: