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

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

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

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

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

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

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

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

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

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

Для терминального агента от 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 "Explain how closures work in JavaScript"

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

Рабочий процесс: генерация кода (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)

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

opencode run --agent plan --file ./src/auth.ts \
  "Refactor this file to reduce complexity. Output a short plan only. Do not run commands."

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

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

Цель: убедиться, что агент explore может найти детали реализации.

opencode run --agent explore \
  "Where is authentication validated for API requests in this repository?"

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

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

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

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

Терминал 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 run, см. практическое руководство по CLI OpenCode.

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

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

opencode                       # запуск TUI
opencode run "..."             # неинтерактивный запуск (автоматизация)
opencode run --file path "..." # прикрепление файлов к промпту
opencode models --refresh      # обновление списка моделей
opencode auth login            # настройка учетных данных провайдера
opencode serve                 # headless HTTP-сервер (OpenAPI)
opencode web                   # headless-сервер + веб-интерфейс
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
Запуск headless-сервера 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.