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

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

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

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

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

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

Что такое OpenCode (и где он находится)

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

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

Если вы хотите сравнить его с другим ассистентом с открытым исходным кодом, который может выполнять многоэтапные планы в изолированной среде, см. Быстрый старт ассистента OpenHands.

opencode с самохостингом qwen3.5 27b LLM

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

  • глубокого погружения в CLI
  • поведения модели/провайдера и стоимости (сравнение LLM внутри OpenCode)
  • конфигурации и агентов
  • интеграций (GitHub/GitLab/Copilot)
  • шпаргалки
  • Oh My Opencode — слой оркестрации многоагентных систем, построенный поверх OpenCode

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

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

  • Современный эмулятор терминала (важно для опыта работы с 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.

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

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

OpenCode работает с любым API, совместимым с OpenAI. Для локальной разработки многие пользователи запускают Ollama и настраивают OpenCode на работу с ним. Недавно я сам получил отличный опыт настройки и запуска OpenCode с llama.cpp вместо этого — llama-server предоставляет endpoints, совместимые с 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 "Explain how closures work in JavaScript"

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

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

opencode run "Write a Go function ParsePort(envVar string, defaultPort int) (int, error). It should read the env var, parse an int, validate 1-65535, and return defaultPort if empty. Include 3 table-driven tests."

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

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

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

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

opencode run --agent plan --file ./src/auth.ts \
  "Refactor this file to reduce complexity. Output: (1) a short plan, (2) a unified diff patch, (3) risks/edge-cases to test. Do not run commands."

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

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

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

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

opencode run --agent explore \
  "In this repository, where is authentication validated for API requests? List likely files and explain the flow. If uncertain, say what you checked."

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

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

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

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

Терминал 1:

opencode serve --port 4096 --hostname 127.0.0.1

Терминал 2:

opencode run --attach http://localhost:4096 "Summarize the repo structure and main entrypoints."
opencode run --attach http://localhost:4096 "Now propose 3 high-impact refactors and why."

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

  • То же самое, что и 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: {
    // Формат строки модели: провайдер/модель (только пример)
    // 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: "Generate a small README section describing this repo." }],
  },
});

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     # sharing сессии (если включено)
/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

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

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

Три статьи подробно освещают эту тему:

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

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

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

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