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
- Откройте 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. Ресурсы для погружения
- Официальные доки — лучшее место для старта
- GitHub (227k★) — issues, discussions, примеры
- Discord — сообщество, помощь, примеры
- Плагины API — как писать свои
- Skills docs — процедурная память
Чек-лист первого дня ✅
- [ ]
curl -fsSL https://opencode.ai/v2/install | bash - [ ]
opencode— запуск, выбор Free Model - [ ] Создать
.opencode.jsonс моделью и MCP - [ ] Добавить GitHub + Filesystem MCP
- [ ] Создать 1 кастомного агента (code-reviewer)
- [ ] Настроить permissions (allow/ask/deny)
- [ ] Попробовать multi-session (2 терминала)
- [ ] Создать 1 slash-команду (/refactor)
- [ ] Протестировать /undo
- [ ] Присоединиться к Discord
