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

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

Страница описывает OpenCode 2 (проверено на 2.2.2). Полная инструкция с разбором ошибок — в документации AITUNNEL.

Что такое OpenCode?

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

• Читать и редактировать файлы — автоматически вносит правки в код
• Выполнять shell-команды — запускает тесты, билды, git-команды
• Держать контекст проекта — структура, импорты, зависимости
• Переключать модели — команда /models прямо в сессии
• Работать без TUI — opencode run для скриптов и CI
• Читать файл правил — AGENTS.md
• Подключать кастомных агентов — .opencode/agents/ с отдельными промптами и правами

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

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

• Без VPN — запросы идут через российский домен
• Оплата в рублях — пополнение от 500₽, карты МИР и СБП
• Один ключ — все модели — Claude, GPT, Gemini, Kimi, GLM, Qwen, DeepSeek через один baseURL
• Кеш Claude без пресета — OpenCode 2 сам ставит cache_control
• Для бизнеса — счёт в кабинете, УПД через ЭДО
• Панель активности — запросы и расходы видны в реальном времени

Установка OpenCode 2

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

Или npm install -g @opencode/cli, или brew install anomalyco/tap/opencode-v2. Команды, которые давно в ходу — curl … opencode.ai/install, npm i -g opencode-ai, scoop install opencode — ставят старую ветку 1.x с другим форматом конфига. На Windows скачайте архив CLI с opencode.ai/v2/docs или используйте WSL.

opencode --version
# opencode v2.2.2

Уже стоит 1.x? opencode upgrade --major обновит до 2.

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

Шаг 1: Конфиг

Создайте ~/.config/opencode/opencode.jsonc (глобально; на Windows — %USERPROFILE%\.config\opencode\opencode.jsonc) или opencode.jsonc в корне проекта:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "aitunnel": {
      "name": "AITUNNEL",
      "env": ["AITUNNEL_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.aitunnel.ru/v1"
      },
      "models": {
        "claude-sonnet-4.6": {
          "name": "Claude Sonnet 4.6",
          "limit": { "context": 1000000, "output": 128000 },
          "capabilities": {
            "tools": true,
            "input": ["text", "image", "pdf"],
            "output": ["text"],
            "reasoning": { "supported": true, "effort": ["low", "medium", "high"] }
          },
          "compatibility": { "cacheFormat": "anthropic" }
        },
        "gpt-6-astra": {
          "name": "GPT-6 Astra",
          "limit": { "context": 1050000, "output": 128000 },
          "capabilities": {
            "tools": true,
            "input": ["text", "image"],
            "output": ["text"],
            "reasoning": { "supported": true, "effort": ["low", "medium", "high"] }
          }
        },
        "gemini-3.7-flash": {
          "name": "Gemini 3.7 Flash",
          "limit": { "context": 1048576, "output": 65535 },
          "capabilities": {
            "tools": true,
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        }
      }
    }
  },
  "model": "aitunnel/claude-sonnet-4.6",
  "agents": {
    "title": { "model": "aitunnel/gemini-3.7-flash" }
  }
}

Id моделей — как в каталоге AITUNNEL. Поля capabilities и limit лучше задавать честно: по ним OpenCode решает, отправлять ли картинку и сколько контекста осталось.

Шаг 2: Ключ

Создайте ключ в панели (sk-aitunnel-…) и сохраните его в OpenCode:

opencode auth login aitunnel

Выберите Manually enter API Key и вставьте ключ. То же в TUI — /connect → AITUNNEL. Провайдер должен быть описан в конфиге (шаг 1) — отдельного пункта «Other» в OpenCode 2 нет.

Шаг 3: Запуск

cd /path/to/your/project
opencode

В TUI выполните /models и выберите модель AITUNNEL. Запросы появятся в панели активности.

Если API отвечает 401

> Вы не указали токен в заголовке запроса (Authorization: Bearer sk-aitunnel-xxx)

В OpenCode 2 модели вызывает общий фоновый сервис, а переменные окружения он читает из окружения процесса, который его запустил. Поэтому export AITUNNEL_API_KEY=… в новом терминале не помогает, если сервис уже работает. Решение — сохранить ключ через opencode auth login aitunnel или положить его в окружение сервиса:

opencode service set env AITUNNEL_API_KEY "sk-aitunnel-xxx"
opencode auth list
# AITUNNEL  AITUNNEL_API_KEY  environment

Проверка — opencode auth list. Десктопное приложение не видит export из .zshrc: в нём используйте /connect. Другие варианты ({env:…}, {file:…}, --standalone) — в документации.

Кеш, рассуждения и картинки

• Кеш Claude. "compatibility": { "cacheFormat": "anthropic" } на модели — OpenCode ставит cache_control сам. Проверено на реальном API: первый запрос записал 6200 токенов в кеш, второй прочитал.
• Рассуждения. Объявите capabilities.reasoning со списком effort — в /models появятся варианты (low, high, max). Старое "reasoning": true из 1.x в версии 2 игнорируется.
• Картинки и PDF. Модель принимает то, что указано в capabilities.input. Если поле не задано, OpenCode 2 считает её мультимодальной — для текстовых моделей укажите ["text"].

Подробности и готовые блоки — в документации.

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

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

# AITUNNEL API CF

## Стек
- Cloudflare Workers + Hono
- TypeScript, деплой через Wrangler

## Правила
- Все обращения к провайдерам идут через единый failover-слой
- Писать тесты для новых route handlers
- Не коммитить секреты и `.dev.vars`

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

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

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

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

export AITUNNEL_API_KEY="sk-aitunnel-xxx"

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

--standalone запускает приватный сервер с окружением runner'а, --auto разрешает действия, не запрещённые правилами. Подходит для GitHub Actions, GitLab CI и любых других CI/CD систем.

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

Рефакторинг

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

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

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

Code review

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

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

• 401 «Вы не указали токен…» — ключ не дошёл до фонового сервиса, см. выше.
• Провайдера нет в /models — он не описан в opencode.jsonc (ключ providers, во множественном числе) или файл отброшен: opencode models --standalone --print-logs покажет rejected malformed JSON or JSONC document. Такое бывает с файлом в UTF-16 (Блокнот, PowerShell 5) — пересохраните в UTF-8.
• Нет мыслей — используйте capabilities.reasoning и флаг --thinking в opencode run.
• Model not found / 404 — id как в каталоге: claude-sonnet-4.6, без префикса провайдера.
• Лимит контекста — задайте limit.context: без него считается 200 000.

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

• Не коммитьте opencode.jsonc с прописанным ключом: {env:AITUNNEL_API_KEY} или {file:~/.secrets/…}
• Сохранённый через /connect ключ лежит в локальной базе OpenCode, не публикуйте её
• OpenCode 2 не спрашивает перед доступом вне папки проекта: при необходимости добавьте правило external_directory → ask
• Для CI/CD передавайте ключ только через переменные окружения runner'а

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

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

• Документация AITUNNEL — установка, конфиг, ключ, кеш, рассуждения, неполадки
• Документация OpenCode 2
• Провайдеры OpenCode
• Переход с V1
• Репозиторий на GitHub
• Каталог моделей AITUNNEL
• Личный кабинет AITUNNEL