OpenCode в России — настройка CLI через AITUNNEL

OpenCode — open-source агентный CLI для программирования в терминале. Построен на Vercel AI SDK, поддерживает 75+ провайдеров «из коробки» и умеет подключаться к любым OpenAI-совместимым endpoints. В России самый простой способ использовать OpenCode — через AITUNNEL: один API-ключ, один baseURL, и в меню выбора модели появляются Claude, GPT-5, Gemini, Kimi, Qwen, DeepSeek и десятки других моделей — без VPN и зарубежных аккаунтов.

Что такое OpenCode?

OpenCode (opencode.ai, github.com/sst/opencode) — это терминальный AI-агент с TUI (text user interface), который умеет:

• Читать и редактировать файлы — автоматически вносит правки в код
• Выполнять shell-команды — запускает тесты, билды, git-команды
• Держать контекст всего проекта — анализирует структуру, импорты, зависимости
• Переключать модели — команда /models прямо в сессии
• Запускать headless-режим — opencode run для скриптов и CI
• Работать как HTTP-сервер — opencode serve и opencode web (UI в браузере)
• Читать файл правил — AGENTS.md (аналог CLAUDE.md или QWEN.md)
• Подключать кастомных агентов — .opencode/agents/ с отдельными промптами и tools

Почему OpenCode через AITUNNEL

Прямое подключение OpenCode к Anthropic, OpenAI или Google требует зарубежной карты и стабильного VPN. AITUNNEL предоставляет OpenAI-совместимый API с российским эндпоинтом api.aitunnel.ru — OpenCode подключается как custom provider:

• Без VPN — запросы идут через российский домен
• Оплата в рублях — пополнение от 399₽, карты МИР и СБП
• Один ключ — все модели — Claude, GPT-5, Gemini, Kimi K2, Qwen3-Coder, DeepSeek через один baseURL
• Для бизнеса — договор, акты, счета-фактуры
• Панель активности — все запросы и расходы видны в реальном времени

Установка OpenCode

Скрипт установки (macOS, Linux, WSL)

curl -fsSL https://opencode.ai/install | bash

Через npm

npm install -g opencode-ai

Требуется Node.js 18 или новее.

Через Homebrew (macOS, Linux)

brew install anomalyco/tap/opencode

Windows (Scoop)

scoop install opencode

Проверка установки

opencode --version

Настройка OpenCode с AITUNNEL

OpenCode подключает AITUNNEL как custom provider через AI SDK пакет @ai-sdk/openai-compatible. Настройка занимает две минуты.

Шаг 1: Добавление API-ключа

Есть два способа.

Способ A: через команду /connect (рекомендуется)

Запустите OpenCode и выполните /connect:

cd /path/to/your/project
opencode

В TUI введите:

/connect

1. Прокрутите список вниз и выберите Other (произвольный OpenAI-совместимый провайдер)
2. Введите ID провайдера — рекомендуем aitunnel
3. Введите ваш API-ключ (начинается с sk-aitunnel-)

OpenCode сохранит ключ в ~/.local/share/opencode/auth.json. ID провайдера должен совпадать с ключом в opencode.json на следующем шаге.

Способ B: прямо в конфиге

Пропустите /connect и укажите ключ через поле options.apiKey в opencode.json (см. ниже).

Шаг 2: Настройка `opencode.json`

Создайте файл ~/.config/opencode/opencode.json (глобально) или opencode.json в корне проекта:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aitunnel": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AITUNNEL",
      "options": {
        "baseURL": "https://api.aitunnel.ru/v1"
      },
      "models": {
        "claude-sonnet-4-5": {
          "name": "Claude Sonnet 4.5",
          "limit": { "context": 200000, "output": 64000 }
        },
        "gpt-5.2-pro": {
          "name": "GPT-5.2 Pro",
          "limit": { "context": 400000, "output": 128000 }
        },
        "moonshotai/kimi-k2": {
          "name": "Kimi K2",
          "limit": { "context": 200000, "output": 32000 }
        }
      }
    }
  },
  "model": "aitunnel/claude-sonnet-4-5",
  "small_model": "aitunnel/moonshotai/kimi-k2"
}

Что означает каждое поле

Актуальный список моделей и их ID — в каталоге AITUNNEL.

Шаг 3: Запуск

cd /path/to/your/project
opencode

Внутри TUI выполните /models, чтобы увидеть подключённые модели AITUNNEL и выбрать нужную. Запросы должны появиться в панели активности AITUNNEL — если их нет, проверьте baseURL и providerID.

Хранение ключа отдельно от конфига

Если вы не используете /connect, OpenCode поддерживает подстановку значений — можно не держать sk-aitunnel-xxx в JSON.

Через переменную окружения

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aitunnel": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AITUNNEL",
      "options": {
        "baseURL": "https://api.aitunnel.ru/v1",
        "apiKey": "{env:AITUNNEL_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-5": { "name": "Claude Sonnet 4.5" }
      }
    }
  },
  "model": "aitunnel/claude-sonnet-4-5"
}

Добавьте в ~/.zshrc или ~/.bashrc:

export AITUNNEL_API_KEY="sk-aitunnel-xxx"

Через файл с ключом

{
  "provider": {
    "aitunnel": {
      "options": {
        "apiKey": "{file:~/.secrets/aitunnel-key}"
      }
    }
  }
}

Где ~/.secrets/aitunnel-key — текстовый файл с одним ключом без переносов строк.

Приоритет конфигов

OpenCode объединяет конфиги из нескольких источников (более поздние переопределяют более ранние):

1. Удалённая конфигурация (.well-known/opencode у провайдера) — базовый слой для организаций
2. Глобальная — ~/.config/opencode/opencode.json
3. Пользовательский путь — переменная OPENCODE_CONFIG=/path/to/config.json
4. Проектная — opencode.json в корне проекта
5. Каталоги .opencode/ — агенты, команды, плагины
6. Встроенная — переменная OPENCODE_CONFIG_CONTENT

Удобный приём: держите провайдер AITUNNEL в глобальном ~/.config/opencode/opencode.json, а в opencode.json проекта переопределяйте только model — чтобы каждый проект использовал свою модель.

Быстрая `small_model` для экономии

OpenCode использует small_model для лёгких задач: генерация заголовков сессии, суммаризация контекста, быстрые ответы. По умолчанию туда стоит ставить быструю и дешёвую модель:

{
  "model": "aitunnel/gpt-5.2-pro",
  "small_model": "aitunnel/gemini-2.5-flash"
}

Это заметно экономит деньги, если основная модель — Opus 4.5 или GPT-5.2 Pro.

Файл правил `AGENTS.md`

OpenCode читает AGENTS.md в корне проекта как системные инструкции для агента — аналог CLAUDE.md или QWEN.md. Пример:

# Мой проект

## Стек
- Next.js 15 + TypeScript
- PostgreSQL, Redis
- Деплой через Vercel

## Правила
- Все новые публичные функции документируются JSDoc
- Писать тесты для новых route handlers
- Не коммитить секреты и .env файлы

OpenCode автоматически подхватит этот файл при старте сессии. Работает и глобальный ~/.config/opencode/AGENTS.md для личных предпочтений.

Рекомендуемые модели через AITUNNEL

Актуальные цены и полный список — в каталоге моделей AITUNNEL.

Полезные команды

В TUI (slash-команды)

В терминале

Headless-режим для CI/CD

OpenCode можно запускать без TUI — удобно для автоматизации:

export AITUNNEL_API_KEY="sk-aitunnel-xxx"

opencode run "Напиши unit-тесты для src/utils.ts и положи их в src/utils.test.ts"

Это читает глобальный opencode.json, выполняет одноразовую задачу и возвращает результат в stdout. Подходит для GitHub Actions, GitLab CI и любых других CI/CD систем.

Примеры задач

Рефакторинг

> Преобразуй все callback-функции в async/await в src/api/*.js

Генерация тестов

> Напиши vitest-тесты для всех публичных методов UserService

Code review

> Проверь код в src/auth/ на security-уязвимости и предложи правки

Документация

> Добавь JSDoc ко всем экспортируемым функциям в src/utils/

Устранение неполадок

Провайдер не появляется в `/models`

• Убедитесь, что ID в provider.<ID> совпадает с тем, что вы ввели в /connect (например, aitunnel)
• Проверьте opencode auth list — ваш провайдер должен быть в списке с сохранённым ключом
• Если используете options.apiKey напрямую, /connect не нужен
• Перезапустите OpenCode после изменения opencode.json

Ошибка 401 / 403

• Проверьте, что ключ действителен в личном кабинете AITUNNEL
• Убедитесь, что баланс положительный
• baseURL должен быть https://api.aitunnel.ru/v1 — с /v1, без слеша в конце
• Если ключ в auth.json устарел — удалите через opencode auth list и заново вызовите /connect

«Model not found» / 404

• Проверьте точный ID в каталоге моделей — у некоторых провайдеров есть префикс (например, moonshotai/kimi-k2, qwen/qwen3-coder)
• ID модели в models должен совпадать с тем, что отправляется в API. Отображаемое name — произвольное

Ошибка AI SDK / несовместимый формат ответа

• По умолчанию AITUNNEL работает через /v1/chat/completions → используйте "npm": "@ai-sdk/openai-compatible"
• Если нужно Responses API через /v1/responses — меняйте на "npm": "@ai-sdk/openai"
• Смешанный режим: можно переопределить npm для конкретной модели через provider.<id>.models.<model>.npm

Ошибка лимита контекста

• Увеличьте limit.context в конфиге модели
• Используйте модели с большим окном (Claude Sonnet 4.5 — 1M токенов, GPT-5.2 Pro — 400K)
• Убедитесь, что small_model выбрана компактная — она тоже берёт контекст на суммаризацию

Безопасность

• Не коммитьте opencode.json с прописанным ключом в публичный репозиторий. Используйте {env:AITUNNEL_API_KEY} или {file:~/.secrets/...}
• Ключ, сохранённый через /connect, лежит в ~/.local/share/opencode/auth.json — этот файл не попадает в git по умолчанию
• Для CI/CD передавайте ключ только через переменные окружения вашего runner'а

Сравнение с другими AI CLI

Дополнительные ресурсы

• Документация OpenCode
• Справочник провайдеров OpenCode
• Конфигурация OpenCode (RU)
• Репозиторий на GitHub
• Каталог моделей AITUNNEL
• Личный кабинет AITUNNEL