opencode.json: как настроить агента под проект
Где лежит конфиг OpenCode, чем глобальные настройки отличаются от проектных, что в него класть и почему ключи и токены туда попадать не должны.
Пока агент работает с одним провайдером и одним репозиторием, настройки можно не трогать.
Вопросы начинаются, когда проектов становится два: в одном нужна локальная модель, в
другом облачная, а MCP-сервер должен подниматься только там, где он к месту. Всё это
живёт в opencode.json.
Глобальный конфиг и проектный
Настройки читаются из двух мест: общего файла в домашнем каталоге и файла рядом с проектом. Проектный перекрывает общий — это и есть основной приём.
В глобальный клади то, что одинаково везде: твой основной провайдер, привычную модель, личные предпочтения интерфейса. В проектный — то, что относится к репозиторию: модель под его задачи, нужные этому проекту MCP-серверы, ограничения на команды.
Практическое следствие, которое экономит время при отладке: если правка не применяется, сначала проверь, не перекрывает ли её файл другого уровня. Точные имена и приоритет файлов сверь с документацией конфигурации для своей версии — схема меняется между релизами.
Что обычно указывают
{
"$schema": "https://opencode.ai/config.json",
"model": "провайдер/имя-модели",
"mcp": {
"servers": {
"docs": {"type": "local", "command": ["npx", "-y", "example-mcp-server"]}
}
}
}
Это форма, а не рабочий файл: имя модели подставь то, которое показывает твой провайдер,
а команду сервера возьми из его документации. Строка $schema в начале нужна не агенту, а
редактору — с ней он подсказывает допустимые ключи и подсвечивает опечатки, а опечатка в
имени ключа иначе просто игнорируется молча.
Раздел mcp.servers подробнее разобран в статье про
MCP-сервер в OpenCode, а выбор самой модели — в
«Какую модель выбрать для OpenCode».
Чего в конфиге быть не должно
Ключей, токенов и паролей. Проектный opencode.json обычно лежит в репозитории, а значит
уезжает в историю Git, в CI и к каждому, у кого есть доступ. Удалить секрет из истории
заметно дороже, чем сразу передать его переменной окружения.
Если без локального файла с секретами не обойтись, держи его отдельно от конфига проекта
и добавь в .gitignore до первого коммита, а не после.
Перед тем как коммитить конфиг, открой его и перечитай глазами. Токен, вставленный «на минуту, чтобы проверить», — самая частая утечка в проектах с агентами.
Как менять настройки, чтобы потом понимать, что сломалось
Схема настроек живёт вместе с проектом и иногда меняется. Отсюда два правила.
Первое: меняй по одному. Переехал на другую модель, поднял новый MCP-сервер и подкрутил права одновременно — при первой же ошибке придётся откатывать всё сразу.
Второе: после обновления OpenCode проверь конфиг, даже если ничего в нём не трогал. Ключ, переименованный в новой версии, не вызывает ошибку — он просто перестаёт действовать, и агент тихо работает на значениях по умолчанию. Если после апдейта поведение изменилось без видимой причины, начни с разбора ошибок OpenCode.
Когда конфига не хватает
Конфиг описывает окружение: провайдера, инструменты, доступы. Но он не объясняет агенту, как у тебя принято работать — для этого есть skills, а для изменения самого поведения программы — плагины. Разделение простое: настройки отвечают на вопрос «с чем работать», навыки — «как».
Если настраивать всё это в JSON не хочется, а агент нужен, у Доки те же вещи — модель, инструменты и разрешения — переключаются в интерфейсе.