Быстрый старт OpenCode: установка, настройка и использование терминального ИИ-агента для программирования

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

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

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

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

Эта статья является частью материала Инструменты ИИ для разработчиков: Полное руководство по разработке с помощью ИИ. Если вы также поддерживаете самохостингуемый ассистент, например Nous Hermes, то Шпаргалка по CLI агента Hermes описывает набор команд hermes наряду с этим быстрым стартом OpenCode.

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

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

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

Если вы хотите сравнить его с другим агентным ассистентом с открытым исходным кодом, способным выполнять многошаговые планы в песочнице, посмотрите Быстрый старт с CLI OpenHands.

Для терминально-ориентированного агента от Anthropic с такой же историей «локальная модель через HTTP» (Ollama или llama.cpp, разрешения, ценообразование) смотрите Установка и настройка Claude Code для Ollama, llama.cpp, ценообразование.

Для намеренно минималистичного подхода к той же идее терминального агента — четыре инструмента по умолчанию, без встроенной песочницы, всё остальное через расширения — смотрите Обзор агент Pi Coding Agent.

opencode with self-hosted qwen3.5 27b LLM

Требования

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

  • Современная эмуляция терминала (важно для опыта использования TUI).
  • Доступ хотя бы к одной модели/провайдеру (API-ключи или подписка, в зависимости от провайдера). Локальные варианты, такие как Ollama или llama.cpp работают без 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.

# chocolatey (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 в вашем проекте.

Локальное хостингование LLM (Ollama, llama.cpp)

OpenCode работает с любым API, совместимым с OpenAI. Для локальной разработки многие пользователи запускают Ollama и направляют на него OpenCode. Недавно у меня был очень хороший опыт настройки и запуска OpenCode с llama.cpp вместо этого — llama-server предоставляет конечные точки, совместимые с OpenAI, поэтому вы можете использовать GGUF-модели с тем же рабочим процессом. Если вы предпочитаете тонкий контроль над памятью и средой выполнения или хотите более лёгкий стек без Python (кстати, ollama реализован на Go), llama.cpp стоит попробовать. Я действительно наслаждался возможностью конфигурирования выгруженных слоёв, удобством использования моделей в формате GGUF и гораздо лучшей/быстрее реализованной совместимостью с новыми моделями, такими как Qwen3.5. Если вы хотите знать, какие модели действительно хорошо работают внутри OpenCode — по задачам программирования и точности структурированного вывода — смотрите мое практическое сравнение LLM для OpenCode.

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

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

cd /path/to/your/repo
opencode

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

/init

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

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

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

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

Для шаблонов рабочего процесса командной строки — пайпинг вывода git, цели Makefile и CI, политики разрешений для автономных запусков — и ожидаемых режимов отказа, смотрите Практическое руководство по CLI OpenCode. Оно строится на основе этого быстрого старта, а не дублирует его.

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

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

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

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

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

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

Цель: подтвердить, что более ограничительный агент plan выполняется, прежде чем вы полагаться на него.

opencode run --agent plan --file ./src/auth.ts \
  "Рефакторьте этот файл, чтобы снизить сложность. Выведите только короткий план. Не выполняйте команды."

Ожидаемый вывод: раздел с планом, без редактирования файлов, без выполнения команд.

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

Цель: подтвердить, что агент explore может локализовать детали реализации.

opencode run --agent explore \
  "Где в этом репозитории валидируется аутентификация для API-запросов?"

Ожидаемый вывод: краткая карта путей файлов и описание потока.

Оба этих варианта — одноразовые смоук-тесты. Для ограниченной, производственной версии тех же задач — явный вывод рисков/краевых случаев, патчи в формате unified-diff, запросы для исследования с учётом разрешений и что делать, когда модель не подчиняется — смотрите раздел “Лучшие случаи использования CLI OpenCode” в Практическом руководстве по CLI OpenCode.

Рабочий процесс: ускорение повторяющихся запусков 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, но обычно с меньшим накладным расходом на повторный запуск.

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

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: {
    // Формат строки модели — provider/model (только пример)
    // 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" } });

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",

  // Выберите модель по умолчанию (provider/model). Держите это в соответствии с тем, что показывает `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 run, смотрите Практическое руководство по CLI OpenCode.

Память проекта между сессиями — это отдельная установка. Hindsight Memory для OpenCode, Cursor и других агентов кодинга добавляет плагин в пользовательский файл ~/.config/opencode/opencode.json, отличный от проектного opencode.jsonc, приведённого выше.

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

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

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), чтобы избежать конфликтов с терминалом. Многие горячие клавиши имеют вид «Leader + клавиша».

Одностраничная печатная таблица-шпаргалка по OpenCode

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

Задача Команда / горячая клавиша Примечания
Запуск TUI opencode Поведение по умолчанию — запуск терминального UI
Выполнение одноразового промпта opencode run "..." Неинтерактивный режим для скриптов/автоматизации
Прикрепление файлов к промпту opencode run --file path/to/file "..." Используйте несколько флагов --file для нескольких файлов
Выбор модели для запуска opencode run --model provider/model "..." Строки моделей имеют вид provider/model
Выбор агента opencode run --agent plan "..." 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

Oh My Opencode — возьмите OpenCode за грань с многоагентной оркестрацией

Как только OpenCode запущен, естественным следующим шагом является Oh My Opencode — общинный плагин, который обёртывает OpenCode в многоагентную конструкцию. Основная идея: введите ultrawork (или ulw) в сессии, и оркестратор (Sisyphus) возьмёт управление на себя, делегируя подзадачи специализированным агентам, которые работают параллельно, каждый на семействе моделей, под которое настроены их промпты.

Три статьи подробно это покрывают:

OpenCode был одним из первых инструментов, пострадавших от политики Anthropic по блокировке стороннего доступа к подписке Claude — шаг, сделанный в январе 2026 года, за месяц до того, как то же ограничение ударило по OpenClaw. Хронология восхода и падения OpenClaw документирует оба события и более широкий паттерн, который они представляют для агентных инструментов, построенных на вычислительных мощностях по подписке.

Источники (сначала официальные)

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

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

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

Подписаться

Получайте новые материалы про системы, инфраструктуру и AI engineering.