OpenCode: чек-лист идеального старта

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

1. Установка — 30 секунд

# Один линк для всех платформ
curl -fsSL https://opencode.ai/v2/install | bash

# Проверка
opencode --version
# OpenCode v0.x.x

Работает на macOS, Linux, Windows (WSL2), в Docker, в CI.

2. Выбор модели: бесплатно vs BYOK

ОпцияПлюсыМинусыДля кого
Free Models (встроенные)Нет ключей, сразу работает, приватноМеньше контекст, слабее качествоТесты, обучение, пет-проекты
OpenRouter (1 ключ = 100+ моделей)GPT-4o, Claude, Gemini, Llama, бесплатные :freeНужен аккаунт OpenRouterПродакшн, выбор модели под задачу
Anthropic DirectЛучший Claude 3.5 SonnetТребует подписку $20/месСерьезный код, рефакторинг
Ollama / LM Studio (локально)Полная приватность, бесплатно, офлайнНужно железо (16-32GB RAM)Приватные проекты, офлайн
OpenCode Go ($10/мес)Курированные модели, без лимитов, без ключейПлатноКоманды, продакшн без BYOK

Совет: Начните с Free Models → переходите на OpenRouter когда понадобится качество.

3. Конфиг: .opencode.json

Создайте в корне проекта:

{
  "model": "openrouter/anthropic/claude-3.5-sonnet",
  "theme": "dark",
  "permissions": {
    "allow": ["read", "grep", "glob", "list"],
    "ask": ["write", "edit", "bash"]
  },
  "mcpServers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
  }
}

Глобальный конфиг: ~/.config/opencode/config.json — для настроек по умолчанию.

4. MCP — подключите свои инструменты за 2 минуты

Создайте .opencode/mcp.json:

{
  "mcpServers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
    "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "$DATABASE_URL"] },
    "brave-search": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search", "$BRAVE_API_KEY"] }
  }
}

Перезапустите opencode — агент видит ваш GitHub, файлы, БД, веб-поиск.

5. Создайте первого кастомного агента

Файл .opencode/agents/code-reviewer.md:

---
name: code-reviewer
description: "Use for code review before commit. Checks bugs, style, security."
model: "anthropic/claude-3.5-sonnet"
tools: [read, grep, glob, bash]
---

You are a senior code reviewer. Focus on:
1. Security (SQLi, XSS, path traversal)
2. Performance (N+1, re-renders)
3. Style consistency
4. Test coverage gaps
5. Error handling

Output format:
- **Critical**: must fix
- **Warning**: should fix
- **Nitpick**: optional

Использование: /agent code-reviewer "Review my changes"

6. Permissions — настройте доверие

Не давайте полные права сразу. Начните с консервативных:

{
  "allow": ["read", "grep", "glob", "list"],
  "ask": ["write", "edit", "bash"],
  "deny": ["bash(rm -rf*)", "bash(sudo*)", "write(*.env)", "write(*.key)"]
}

По мере доверия переносите из ask в allow.

7. Первый Multi-Session

  1. Откройте 2 терминала в одной папке
  2. \li>В первом: opencode → "Напиши тесты для user service"\li>Во втором: opencode → "Рефакторни user controller"\li>Наблюдайте как они работают параллельно над разными файлами

8. Полезные алиасы

# ~/.bashrc / ~/.zshrc
alias oc='opencode'
alias ocs='opencode serve'
alias oca='opencode auth login'
alias ocp='opencode -p'

# Быстрый запуск с моделью
alias oc-claude='opencode -m anthropic/claude-3.5-sonnet'
alias oc-gpt='opencode -m openai/gpt-4o'
alias oc-free='opencode -m free'

9. Типичные ошибки новичков

  • Дают все права сразу → агент может удалить важное. Начинайте с ask.
  • Не настраивают MCP → агент не видит GitHub, БД, веб. Добавьте хотя бы GitHub + Filesystem.
  • Используют бесплатные модели для продакшн-кода → качество ниже. Переключайтесь на платные для важного.
  • Не создают .opencode.json в проекте → настройки сбрасываются при перезапуске.
  • Не используют /undo → боятся экспериментировать. Экспериментируйте смело — откат одной командой.

10. Ресурсы для погружения

Чек-лист первого дня ✅

  1. [ ] curl -fsSL https://opencode.ai/v2/install | bash
  2. [ ] opencode — запуск, выбор Free Model
  3. [ ] Создать .opencode.json с моделью и MCP
  4. [ ] Добавить GitHub + Filesystem MCP
  5. [ ] Создать 1 кастомного агента (code-reviewer)
  6. [ ] Настроить permissions (allow/ask/deny)
  7. [ ] Попробовать multi-session (2 терминала)
  8. [ ] Создать 1 slash-команду (/refactor)
  9. [ ] Протестировать /undo
  10. [ ] Присоединиться к Discord