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

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

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

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

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

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

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

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

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

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

Для агента 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 (stable)
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 "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, запросите повторно: «Вернуть только unified 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: {
    // Формат строки модели: provider/model (только пример)
    // 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",

  // Выберите модель по умолчанию (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                       # запустить 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 Поведение по умолчанию — запуск интерфейса терминала
Запустить одноразовый промпт 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) возьмет управление на себя, делегируя подзадачи специализированным агентам, которые работают параллельно, каждый на семействе моделей, под которые настроены их промпты.

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

  • Oh My Opencode Quickstart
    Установите через bunx oh-my-opencode install, настройте провайдеров и запустите свою первую задачу ultrawork менее чем за десять минут.

  • Specialised Agents Deep Dive
    Все 11 агентов объяснены — Сизиф, Гефест, Оракул, Прометей, Библиотекарь и другие — с маршрутизацией моделей, цепочками резервного копирования и практическими рекомендациями для локальных моделей.

  • Oh My Opencode Experience: Honest Results and Billing Risks
    Реальные бенчмарки, инцидент с бесконечным циклом Gemini на сумму $350 и четкий вердикт о том, когда OMO оправдывает свои накладные расходы.

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

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

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

Авторитетная ссылка на интеграцию:

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

Подписаться

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