03 - Миграция с V1
OpenCode 1 и OpenCode 2 используют команду opencode и больше не устанавливаются рядом по умолчанию. Удалите установку V1 из пакетного менеджера перед установкой V2; установщик V2 curl заменит бинарный файл V1.
Изменения, нарушающие обратную совместимость
V2 имеет три преднамеренных изменения, нарушающих обратную совместимость:
- Плагины используют новый API плагинов.
- API сервера и клиенты имеют новые контракты.
- Конфигурация терминального клиента перемещается из слоистых файлов tui.json(c) к одному глобальному файлу cli.json (авто миграция).
Поддерживаемая функциональность V1 вне этих областей должна остаться совместимой с V1. Некоторые поля, принимаемые схемой V1, никогда не имели эквивалента V2 и намеренно игнорируются; они перечислены в разделе Принятые, но неподдерживаемые поля.
Существующие поддерживаемые поля конфигурации сервера, определения агентов, определения команд, навыки и другие файлы в .opencode/ продолжат работать без изменений. Если поддерживаемое поведение, описанное в этом руководстве, перестанет работать в V2, рассматривайте это как баг совместимости, а не как ожидаемое требование миграции.
Установка V2
Установите терминальный клиент V2 с помощью руководства по запуску терминала.
Вам не нужно переписывать всё перед запуском V2. Практическая миграция:
- Сохраните существующую конфигурацию и файловые определения.
- Запустите V2 и проверьте модели, учётные данные, агентов, разрешения и MCP-серверы.
- Перенесите плагины, поскольку реализации плагинов V1 не работают в V2.
- Перенесите интеграции, вызывающие API сервера.
- Преобразуйте конфигурацию в нативный формат V2, когда будете готовы. Этот шаг необязателен.
Сохраните копию вашей настройки V1 во время проверки миграции. V1 и V2 используют одни и те же расположения конфигурации, поэтому не указывайте V1 на файлы после их преобразования в нативные форматы только для V2.
Конфигурация
Этот раздел охватывает как JSON/JSONC конфигурацию, так и файловые определения в .opencode/.
Используйте вашу существующую конфигурацию
V2 читает существующую системную, глобальную и проектную конфигурацию из тех же расположений, что и V1:
/Library/Application Support/opencode/opencode.json(c) /etc/opencode/opencode.json(c) %ProgramData%\opencode\opencode.json(c) /Library/Managed Preferences/<user>/ai.opencode.managed.plist /Library/Managed Preferences/ai.opencode.managed.plist ~/.config/opencode/opencode.json(c) <project>/opencode.json(c) <project>/.opencode/opencode.json(c)
V2 читает эти же расположения. Он нормализует поддерживаемые поля V1 и нативные поля V2 в памяти без перезаписи исходного файла. Существующая поддерживаемая конфигурация V1 должна продолжать работать, поэтому вам не нужно её преобразовывать, чтобы попробовать или принять V2.
Как и в V1, системная конфигурация и управляемые настройки macOS имеют наивысший приоритет, поэтому их настройки переопределяют глобальные и проектные файлы. Их политики, включая перенесённые enabled_providers и disabled_providers, также имеют приоритет над глобальными и проектными политиками. Переопределение настройки не может помешать пользователям добавлять провайдеров, MCP-серверы, агентов или плагины, поэтому выражайте административные ограничения как policies, а не обычные настройки, такие как permissions.
Попросите OpenCode выполнить миграцию
Формат конфигурации V1 остаётся поддерживаемым. Нативный формат V2 необязателен и делает многие настройки более явными и удобными.
Рекомендуемый путь миграции — попросить OpenCode обновить конфигурацию за вас:
Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format. Preserve its behavior and all unrelated settings.
OpenCode может проверить полный файл, применить соответствующие изменения ниже и избежать перезаписи настроек, которые не нуждаются в изменении. Преобразование не должно происходить всё сразу: поддерживаемые поля V1 и нативные поля V2 могут сосуществовать на верхнем уровне. Когда обе формы устанавливают одно каноническое значение, действительное нативное значение V2 имеет приоритет независимо от порядка ключей JSON.
Вложенное смешивание намеренно ограничено. OpenCode распознаёт смешанные члены V1 и V2 в mcp, compaction и experimental, но не рекурсивно выводит форматы внутри отдельных агентов, провайдеров, команд или моделей. Сохраняйте каждый из этих вложенных элементов полностью в одном формате. Поддерживаемый синтаксис V1 остаётся тихим сам по себе; недействительные значения, неподдерживаемые устаревшие поля и конфликтующие значения V1/V2 производят предупреждения, в то время как другие действительные настройки продолжают загружаться.
Разрешения и инструменты
V1 группирует эффекты разрешений по инструментам. V2 использует один упорядоченный массив permissions, делая приоритет и исключения явными:
// V1
{
"permission": {
"bash": {
"git push *": "ask"
},
"edit": "allow"
},
"tools": {
"websearch": false
}
}
// V2
{
"permissions": [
{ "action": "shell", "resource": "git push *", "effect": "ask" },
{ "action": "edit", "resource": "*", "effect": "allow" },
{ "action": "websearch", "resource": "*", "effect": "deny" }
]
}
Действия разрешений также изменились: bash теперь shell, task теперь subagent, а write и patch теперь edit. См. Разрешения для упорядоченного формата правил V2.
Задачи отключены по умолчанию в V2. Чтобы включить их, используйте экспериментальный флаг. Он может измениться или быть удалён в будущем релизе; см. Экспериментальные.
{
"experimental": {
"todo": true,
},
}
Агенты и режимы
Одиночные карты agent и устаревший mode становятся agents. Поля агентов становятся более согласованными с остальной конфигурацией V2:
// V1
{
"agent": {
"reviewer": {
"prompt": "Проверьте на правильность и отсутствующие тесты.",
"model": "anthropic/claude-sonnet-5-5",
"variant": "high",
"disable": false,
"permission": {
"edit": "deny"
}
}
}
}
// V2
{
"agents": {
"reviewer": {
"system": "Проверьте на правильность и отсутствующие тесты.",
"model": "anthropic/claude-sonnet-5-5#high",
"disabled": false,
"permissions": [
{ "action": "edit", "resource": "*", "effect": "deny" }
]
}
}
}
prompt становится system, disable становится disabled, а отдельный variant присоединяется к ссылке на модель после #. maxSteps становится steps. Записи из старой карты mode становятся основными агентами.
Агент request.body сохранён, но не отправляется модели, поэтому V1 temperature, top_p и options не имеют эффекта там. Установите их на варианте модели. DeepSeek применяет temperature только с отключённым мышлением, поэтому этот вариант также отключает мышление:
{
"providers": {
"opencode": {
"models": {
"deepseek-v4.1-flash": {
"variants": [{ "id": "review", "body": { "thinking": { "type": "disabled" }, "temperature": 0.2 } }],
},
},
},
},
"agents": {
"reviewer": { "model": "opencode/deepseek-v4.1-flash#review" },
},
}
Используйте body для полей JSON провайдера и settings для параметров пакета провайдера. См. параметры модели.
Снимки
Переименуйте одиночное поле snapshot в snapshots. Его булево значение не меняется:
// V1
{ "snapshot": false }
// V2
{ "snapshots": false }
Медиа
Переименуйте одиночный объект attachment в media. Вложенные настройки изображений сохраняют те же имена:
// V1
{ "attachment": { "image": { "auto_resize": true } } }
// V2
{ "media": { "image": { "auto_resize": true } } }
MCP-серверы
V2 группирует серверы под mcp.servers, заменяет enabled на обратный disabled и разделяет цели таймаутов:
// V1
{
"mcp": {
"playwright": {
"type": "local",
"command": ["npx", "@playwright/mcp"],
"enabled": true,
"timeout": 30000
}
}
}
// V2
{
"mcp": {
"servers": {
"playwright": {
"type": "local",
"command": ["npx", "@playwright/mcp"],
"disabled": false,
"timeout": {
"catalog": 30000,
"execution": 30000
}
}
}
}
}
Удалённые поля OAuth используют snake case: clientId становится client_id, clientSecret становится client_secret, callbackPort становится callback_port, а redirectUri становится redirect_uri. Значение V1 experimental.mcp_timeout также становится значениями по умолчанию mcp.timeout.catalog и mcp.timeout.execution. См. MCP-серверы.
Компактизация
V2 группирует бюджет токенов сохраняемого контекста под keep и даёт резерву более явное название:
// V1
{
"compaction": {
"preserve_recent_tokens": 8000,
"reserved": 20000
}
}
// V2
{
"compaction": {
"keep": {
"tokens": 8000
},
"buffer": 20000
}
}
auto сохраняет своё название. V2 не имеет нативных полей tail_turns или prune; оба устаревших поля игнорируются с предупреждением. Недавний контекст сохраняется по бюджету токенов. См. Компактизация.
Навыки
V1 разделяет дополнительные пути и URL навыков. V2 объединяет оба в один упорядоченный массив:
// V1
{
"skills": {
"paths": ["./team-skills"],
"urls": ["https://example.com/skills/"]
}
}
// V2
{
"skills": ["./team-skills", "https://example.com/skills/"]
}
Существующие файлы навыков и автоматическое обнаружение .opencode/skills/ не меняются. См. Навыки.
Команды
Переименуйте одиночную карту command в commands и subtask в subagent. Присоедините отдельный вариант модели variant к ссылке на модель:
// V1
{
"command": {
"review": {
"template": "Проверьте текущие изменения.",
"model": "anthropic/claude-sonnet-5-5",
"variant": "high",
"subtask": true
}
}
}
// V2
{
"commands": {
"review": {
"template": "Проверьте текущие изменения.",
"model": "anthropic/claude-sonnet-5-5#high",
"subagent": true
}
}
}
template, description и agent сохраняют свои названия. Устаревший subtask остаётся принятым; делегированные команды теперь запускаются автоматически в фоне и сообщают свои результаты родительской сессии. Существующие определения команд Markdown остаются поддерживаемыми. См. Команды.
Ссылки
Переименуйте устаревшую одиночную карту reference в references:
// V1
{ "reference": { "docs": "../docs" } }
// V2
{ "references": { "docs": "../docs" } }
V1 уже принимает references, поэтому изменений не требуется, когда файл использует его. Записи ссылок сохраняют те же формы. См. Ссылки.
Провайдеры
Переименуйте одиночную карту provider в providers. V2 разделяет пакет рантайма, конечную точку и настройки запросов:
// V1
{
"provider": {
"acme": {
"npm": "@ai-sdk/openai-compatible",
"api": "https://llm.example.com/v1",
"options": {
"apiKey": "{env:ACME_API_KEY}"
}
}
}
}
// V2
{
"providers": {
"acme": {
"package": "aisdk:@ai-sdk/openai-compatible",
"settings": {
"baseURL": "https://llm.example.com/v1",
"apiKey": "{env:ACME_API_KEY}"
}
}
},
}
V1 npm становится package, а пакеты AI SDK получают префикс aisdk:. api становится settings.baseURL. Провайдер options разделяются на settings, headers и body в зависимости от их роли запроса. options.setCacheKey становится compatibility.supportsPromptCacheKey на провайдере. См. Провайдеры.
V2 консолидировал два устаревших пространства имён провайдеров:
|
ID провайдера V1 |
Канонический ID провайдера V2 |
|---|---|
|
azure-cognitive-services |
azure |
|
google-vertex-anthropic |
google-vertex |
Миграция неоднозначных полей провайдера V1, агента, команды и фильтра провайдера использует эти канонические ID. Общий топ-уровень model сохраняет свой точный ID провайдера, поскольку тот же синтаксис действителен в нативной конфигурации V2; обновите это поле на канонический ID при миграции устаревшего встроенного провайдера.
Модели и варианты
Модели остаются вложенными под своим провайдером, но несколько полей модели становятся более явными:
- id становится modelID.
- tool_call и modalities становятся capabilities.tools, capabilities.input и capabilities.output.
- status со значением "deprecated" становится disabled: true.
- Стоимость кэша перемещается из cache_read и cache_write в cache.read и cache.write.
- Специфичные для провайдера options становятся settings.
- Объект вариантов V1 становится массивом V2 с id для каждой записи.
// V1
{
"variants": {
"high": {
"reasoningEffort": "high"
}
}
}
// V2
{
"variants": [
{
"id": "high",
"settings": {
"reasoningEffort": "high"
}
}
]
}
См. Модели для полной нативной формы модели.
Поддерживаемые поля без прямых нативных эквивалентов
Большинство полей, сохраняющих ту же форму, включая shell, model, default_agent, watcher, formatter, instructions, enterprise и tool_output, не требуют миграции.
V2 принимает и сохраняет конфигурацию lsp, но не запускает языковые серверы, не раскрывает LSP-инструменты и не производит LSP диагностику. Замените рабочие процессы, зависящие от этих возможностей, на линтинг, проверку типов или команды компилятора проекта.
Фильтры провайдеров V1 не имеют полей нативной конфигурации V2 один-к-одному, но их поведение остаётся поддерживаемым через политики:
- enabled_providers становится внутренней политикой провайдера deny-by-default, за которой следуют allows для перечисленных провайдеров.
- disabled_providers становится внутренними deny-политиками для перечисленных провайдеров.
- autoupdate становится update: false отображается на "disable", "notify" отображается на "notify", а true отображается на "auto".
- small_model становится выбором model для встроенного агента title. Нативная конфигурация V2 должна использовать agents.title.model вместо этого.
Вы можете сохранить эти поля в синтаксисе V1. OpenCode нормализует их без предупреждения.
Принятые, но неподдерживаемые поля
Схема V1 также принимала поля, не имеющие поддерживаемого поведения V2. V2 игнорирует эти значения и выдаёт предупреждение, чтобы они не были приняты за активную конфигурацию:
- logLevel: используйте OPENCODE_LOG_LEVEL при запуске OpenCode.
- server: используйте сервис V2 и явные параметры сервера; API сервера — преднамеренное изменение, нарушающее обратную совместимость.
- subagent_depth верхнего уровня: используйте вместо этого experimental.subagent_depth.
- compaction.tail_turns и compaction.prune: V2 использует compaction.keep.tokens и компактизацию на основе контрольных точек.
- name агента внутри конфигурации V1 JSON.
- Включённая только запись V1 MCP без type.
- Экспериментальные поля V1 batch_tool, openTelemetry, primary_tools и continue_loop_on_deny.
- Поля провайдера V1 id, whitelist и blacklist.
- Поля модели провайдера V1 release_date, attachment, reasoning, temperature, experimental, не-deprecated status и булево interleaved.
Игнорирование этих полей намеренно и не является регрессией совместимости. Если V2 не сохраняет поведение, идентифицированное как поддерживаемое в другом месте этого руководства, следуйте руководству по сообщению об ошибках в Устранении неполадок.
Файлы агентов
Файлы агентов V1 могут использовать agent/, agents/, mode/ или modes/. V2 всё ещё обнаруживает все четыре директории. Предпочтительное расположение V2:
.opencode/agents/<name>.md
Файлы под директорией V1 mode/ или modes/ представляют основных агентов. При перемещении одного в agents/ добавьте mode: primary в его frontmatter. Файлы под agent/ могут перемещаться в agents/ без изменения их ID, выведенного из пути.
При преобразовании frontmatter в нативные поля V2:
- Сохраните тело Markdown как системные инструкции агента.
- Переименуйте prompt в system, когда он появляется в JSON-конфигурации; тела файлов не нуждаются в поле system.
- Переименуйте disable в disabled и permission в permissions.
- Присоедините model и variant как provider/model#variant.
- Установите параметры сэмплирования и провайдера на варианте модели, как показано выше.
Frontmatter агента V1 устарел, но всё ещё автоматически переводится. Каждый файл читается как один формат. Файл, использующий любые из permissions, request, system или disabled, читается как V2, и поля V1 в нём, такие как name, tools, permission или temperature, игнорируются с предупреждением в логе. Другие файлы, использующие поля V1, читаются как V1. Преобразуйте frontmatter файла всё сразу, а не смешивайте два формата. См. Агенты.
Файлы команд
Файлы команд V1 могут использовать command/ или commands/. V2 обнаруживает оба. Предпочтительное расположение:
.opencode/commands/<name>.md
Переместите файлы из command/ в тот же относительный путь под commands/, чтобы сохранить имена команд. Тело Markdown остаётся шаблоном команды, а description и agent frontmatter сохраняют те же имена. Переименуйте subtask в subagent, чтобы использовать нативное название для фоновой делегации. Если frontmatter имеет отдельные поля model и variant, присоедините вариант к модели и удалите variant:
# V1 model: anthropic/claude-sonnet-5-5 variant: high subtask: true # V2 model: anthropic/claude-sonnet-5-5#high subagent: true
См. Команды.
Файлы навыков
V2 обнаруживает навыки из .opencode/skill/ и .opencode/skills/. Предпочительная структура:
.opencode/skills/<skill-id>/SKILL.md
Переместите полную директорию навыка, а не только SKILL.md, чтобы относительные скрипты, ссылки и другие вспомогательные файлы оставались доступными. Сохраняйте название директории стабильным, чтобы сохранить ID навыка. Существующий frontmatter навыков и тела Markdown не требуют переписывания V2. См. Навыки.
Файлы инструкций
Существующие файлы AGENTS.md остаются на месте. V2 обнаруживает глобальный ~/.config/opencode/AGENTS.md и фоновые файлы AGENTS.md от текущей директории до домашней. Для проектов вне домашней директории обнаружение останавливается на корне проекта.
Если настройка V1 полагалась на резервный CLAUDE.md, переместите эти указания в соответствующий AGENTS.md. V2 в настоящее время обнаруживает только AGENTS.md; поскольку поведение V1, не связанное с API, должно остаться совместимым, также создайте issue совместимости с подробностями затронутого проекта. См. Инструкции.
Конфигурация терминального клиента
V2 заменяет слоистые файлы V1 tui.json(c) одним глобальным файлом конфигурации терминального клиента:
~/.config/opencode/cli.json
Терминальный клиент владеет этим файлом; фоновый сервис не загружает его. Когда cli.json отсутствует, первый запуск терминального клиента V2 мигрирует поддерживаемые глобальные настройки tui.json и сохранённые предпочтения, оставляя файлы V1 без изменений. Локальная конфигурация клиента проекта не мигрируется, поскольку конфигурация клиента V2 глобальна. См. Настройки CLI для справочника текущих настроек клиента.
Плагины
Переименуйте plugin в plugins. Замените кортеж пакета и параметров на объект:
// V1
{
"plugin": ["opencode-example-plugin", ["./plugin/local.ts", { "enabled": true }]]
}
// V2
{
"plugins": [
"opencode-example-plugin",
{
"package": "./plugin/local",
"options": { "enabled": true }
}
]
}
V2 обнаруживает локальные плагины из .opencode/plugin/ и .opencode/plugins/; используйте .opencode/plugins/ для файлов V2. Настроенные локальные пути должны быть директориями, поэтому переместите перенесённый плагин в ./plugin/local/index.ts.
Перенесите точки входа, хуки, инструменты, события и экспорты пакетов с помощью специального руководства по миграции плагинов.
API сервера и клиенты
OpenCode 2 имеет пересмотренный, более удобный API сервера и новый набор клиентов. Интеграции, вызывающие API сервера V1, должны мигрировать на API V2.
Используйте пакет @opencode/client для доступа к выпущенному API V2. См. сгенерированную справку по API для его конечных точек, типов запросов и ответов.
Проверка настройки
Проверьте вашу модель, учётные данные провайдера, агентов, разрешения, MCP-серверы и плагины в проекте перед использованием V2 для повседневной работы. Сохраните вашу настройку V1 до тех пор, пока вы не подтвердите нужное поведение V2, и не указывайте V1 на конфигурацию, которую вы преобразовали в нативный формат V2.