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

Установка, настройка и использование OpenCode

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

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

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

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

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

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

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

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

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

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.

# 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 предоставляет совместимые с 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 agent)

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

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, повторите запрос: «Верните только объединенный diff» или «Используйте формат 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(`Server running at: ${opencode.server.url}`);

// Базовая проверка здоровья/версии
const health = await opencode.client.global.health();
console.log("Healthy:", health.data.healthy, "Version:", 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

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

  • «Server running at …»
  • Ответ о здоровье, включающий строку версии
  • Объект ответа сессии (точная структура зависит от 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 "..." 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) возьмет управление на себя, делегируя подзадачи специализированным агентам, которые работают параллельно, каждый на семействе моделей, для которых настроены их запросы.

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

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

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

Авторитетный референс интеграции:

Авторитетные сравнения/туториалы:

Подписаться

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