01b20b5b78
## Summary
- Qualify OpenCode **2.1.3** (latest stable, 22 October) with the
existing locked **2.1.0 client/plugin** dependencies, and **recommend**
it.
- Keep the technical **minimum at 2.1.2**: nothing CodeNomad consumes
changed, so the minimum has no new reason to move.
- A 2.1.2 daemon stays ready and gets an optional upgrade offer. 2.1.3
is the `tested` version. Newer and custom labels keep authenticated
contract recognition.
- The reviewed-contract fast path lists 2.1.3 beside the 2.1.2 minimum.
- The recommended version is updated in the help (all ten locales), both
READMEs, `dev-docs/OPENCODE_COMPATIBILITY.md` and the architecture
skill.
## Contract review (v2.1.2 → v2.1.3, 66 commits)
- **Authenticated OpenAPI:** 119 → **121 paths**, 144 → **146
operations**. Every consumed operation is unchanged. The only changes:
- added `GET /api/experimental/voice/models`;
- added `POST /api/experimental/voice/session/{sessionID}/instructions`;
- an optional hosted `session.id` in the `POST
/api/experimental/voice/session` response.
None of these is on the instance proxy allowlist, so they stay closed.
- **Published declarations:** the client adds only `voice.models` /
`voice.instructions`. The schema changes only typing (agent `color`
decoding, `Durable` as a tagged union). The plugin is unchanged.
- **Windows managed services** move their default port from **45278 to
28894** ([#57428](https://github.com/anomalyco/opencode/pull/57428)).
CodeNomad discovers the daemon through the selected CLI's `service
status` and the service registration, and assumes no port.
- Live check: this machine's shared daemon was upgraded to 2.1.3 and
restarted on 28894, and the running CodeNomad desktop kept working
through it.
- **Core:** mostly refactors, plus behaviour fixes that the native
suites below exercise:
- compaction summary output limit;
- `keepID` validated as a message ID;
- MCP media kept out of attachments;
- only changed instruction entries resent;
- relative-directory V1 migration;
- legacy `apply_patch` permission mapped to `edit`.
## Isolated Windows qualification
Base: dev `333d73452`, rebased on `853b14f2f` (#1097) for the final UI
unit run; Node **24.20.0**; exact official CLI **2.1.3**; unchanged
locked client/plugin **2.1.0**.
- **Build and checks:** production server/UI/native plugin builds,
server and root typechecks, native bundle guard.
- **Native runtime (9/9):**
- Code Mode job ordering, plugin runtime, automation;
- complete pruning, history, ownership, worktree and event relay;
- loaded-only pending snapshot;
- Missions contract, family control, native and Compare/Wayfinder
trajectory.
- **Sessions (15/15):** environment, fork, aside, interrupt, lifecycle,
blank cleanup, prompt skills, provider usage/accounts/selection, service
usage, web search, plugin packages, output limit, Promise-tool failure.
- **Recurring (5/5):** all **11 recurring Mission journeys**, subagent
depth, **2 MiB** compaction, permission receipts.
- **Migrations (9/9):**
- history from **2.0.3, beta-19271, 2.0.32, 2.1.0, 2.1.1 and 2.1.2** to
2.1.3;
- Git degraded/init;
- temporary workspaces.
- **Installation (3/3), with the 2.1.3 recommendation:**
- fresh install of the 2.1.2 minimum;
- native **2.0.15 → 2.1.3** upgrade, after which the already-running
daemon keeps its PID and 2.0.15 version;
- explicit OpenCode **1.18.10 → 2.1.3** replacement.
- **After the recommendation change:**
- admission/transport/update/setup units **36/36**;
- full server **2,463 passed, 8 skipped**, no failure or cancellation;
- UI units **1,694/1,694** (with #1097);
- focused browser **126/126**;
- native pruning with the real rendered UI;
- the exact CI invocation of the Code Mode regression (without tsx);
- ten-locale help checks.
The UI unit run on `333d73452` itself had two failures, in
`instances-pending-compaction.test.ts` (`toast.dismiss is not a
function`). They come from #1096 and also fail on unmodified `dev`;
#1097 fixes that fixture.
This is Windows automation evidence. In CI, `latest` now resolves to
2.1.3: the compatibility job runs the native suites against the minimum
and latest on Windows, and the migration and Git-degraded certification
runs them on Ubuntu, Windows and macOS. WSL, packaged desktop,
installers/updater end-to-end and real mobile devices keep their
separate release gates.
16 KiB
Настройка OpenCode
CodeNomad подключается к общей службе OpenCode на хосте выполнения. Выбор CLI, обновление его файлов, перезапуск службы и перезагрузка конфигурации — разные операции; ни одна не заменяет остальные.
Выбор или установка CLI
- Откройте Настройки → OpenCode и используйте карточку Бинарник OpenCode под Версия OpenCode для выбора исполняемого файла.
- Оставьте выбранной автоматическую запись, чтобы предпочитать PATH сервера (если там не старый OpenCode), затем его пользовательскую установку OpenCode 2 через npm; либо используйте Выбрать бинарник… или введите путь и нажмите Добавить.
- Нажмите Проверить состояние и обновления. Если OpenCode отсутствует, выберите Установить и запустить OpenCode; сначала проверьте хост и область установки.
- Если настройка предлагает Подключиться и продолжить, используйте после устранения указанной проблемы.
Установка использует встроенные Node/npm для стандартной пользовательской установки, общей с другими клиентами. Установить для пользователя и настроить PATH меняет настройку терминала этого пользователя; после этого откройте новый терминал. Браузер подключается к серверу CodeNomad: выбор файла и исполняемого файла относится к серверу, не к устройству просмотра.
Когда первым в PATH стоит более старый OpenCode, предлагаемое действие зависит от способа его установки. Для OpenCode 1.x, установленного через npm, Заменить OpenCode {version} на OpenCode 2 запрашивает подтверждение, удаляет этот пакет npm и устанавливает OpenCode 2 в ту же папку npm; папка данных OpenCode сохраняется, а OpenCode 2 сам импортирует беседы 1.x. Старый или неработоспособный OpenCode, установленный иначе (winget, Homebrew, вручную), никогда не изменяется: Установить OpenCode 2 для CodeNomad устанавливает OpenCode 2 в пользовательскую папку npm рядом с ним, и затем CodeNomad использует эту копию. Если сама эта старая команда находится в пользовательской папке npm (например, ссылка в ~/.local/bin) или эта папка недоступна для записи, настройка вместо этого действия объясняет причину: переместите или переименуйте команду либо исправьте права на папку, затем выберите Проверить состояние и обновления. Команда opencode в терминале может по-прежнему запускать старую версию. Явно выбранный пользовательский исполняемый файл никогда не заменяется.
Установленный исполняемый файл и работающая служба могут иметь разные версии. Сравните Установленная версия с Работающая служба в карточке Версия OpenCode, не предполагая, что выбор другого файла заменил живой демон; Сведения о версиях перечисляет минимальную и рекомендуемую версии. Если установка занята или файл заблокирован, дождитесь освобождения установщиком или процессом и проверьте состояние перед повтором; не запускайте конкурирующие установщики.
Требуемые, рекомендуемые и непроверенные версии
| Классификация | Текущее требование | Значение |
|---|---|---|
| Минимум | OpenCode 2.1.2 | Правильный порядок выполнения задач JavaScript в Code Mode и нативный формат воспроизведения и сжатия версии 2.1; беседы, сохранённые более ранними версиями, остаются доступными после обновления. |
| Рекомендуемая | OpenCode 2.1.3 | Проверенная цель, отличная от технического минимума. |
| Непроверенная | Новая или пользовательская версия, не прошедшая полную проверку | Не отклоняется лишь из-за отсутствия тестирования; проверяются реальные API-контракты подключённой службы. |
Необходимые контракты сессий, разрешений, форм, входящих и окружения сессий тоже должны быть доступны. Одна версия исполняемого файла не доказывает их поддержку подключённой службой. Если настройка сообщает о неподдерживаемой работающей службе, выберите/установите поддерживаемый CLI и выполните явный перезапуск общей службы, когда будете готовы.
Хост, WSL и общая служба
В Windows выбранный исполняемый файл WSL работает в своём дистрибутиве. Устанавливайте/обновляйте его там и используйте пути этого дистрибутива. Подключение WSL зависит от перенаправления localhost Windows. Windows CLI и WSL CLI — не взаимозаменяемые среды выполнения.
OpenCode владеет глобальной регистрацией службы, сессиями, сообщениями и базой данных. CodeNomad не создаёт отдельную базу OpenCode для окна или проекта. Закрытие вкладки проекта закрывает этот проект в CodeNomad; сессии продолжают работать в OpenCode и снова появляются при повторном открытии проекта. CodeNomad никогда не выгружает нативные Location. Закрытие всего окна, выход или перезагрузка сохраняют подключения проектов для восстановления; ни эти действия, ни завершение серверной части не останавливают общий демон. См. проекты.
Обновление, перезапуск и перезагрузка
- В Настройки → OpenCode выберите Проверить состояние и обновления.
- Для замены установленных файлов CLI выберите Обновить до OpenCode {version}, когда предложено. Дождитесь завершения.
- Проверьте статус работающей службы. Используйте Перезапустить общую службу, только если хотите активировать выбранную установку для всех подключённых клиентов.
- Для перезапуска процесса без установки раскройте Устранение неполадок, выберите Перезапустить службу OpenCode и подтвердите.
| Действие | Область и эффект | Безопасное восстановление |
|---|---|---|
| Обновить CLI | Меняет поддерживаемый установленный исполняемый файл; не перезапускает работающий демон неявно. | После сбоя проверьте установленную и работающую версии; повторяйте явно только после устранения ошибки. |
| Перезапустить службу | Заменяет общий процесс и прерывает активную работу всех подключённых клиентов OpenCode; история сессий остаётся. | Переподключитесь и проверьте разговоры и миссии по расписанию; перезапуск не означает автоматического продолжения. |
| Перезагрузить конфигурацию OpenCode | Сохраняет процесс, но пересоздаёт все загруженные Location для всех клиентов. Отменяет ожидающие разрешения/формы и закрывает терминалы/фоновые команды; активная работа может прерваться. | Перепроверьте ресурсы и ожидающую работу после перезагрузки. Не повторяйте запрос или изменение лишь из-за потерянного ответа. |
Используйте Перезагрузить конфигурацию OpenCode (в Устранение неполадок, если работающая служба это поддерживает) явно, если сохранённая конфигурация или установленный плагин остаются недоступны и прерывание допустимо. Это не безобидное обновление отображения. CodeNomad не использует старый выбранный CLI для понижения версии нового работающего демона.
Окружение сессии
- Откройте Настройки → Расширенные и раскройте Переменные окружения.
- Добавьте, измените или удалите переопределения профиля; каждое изменение сохраняется сразу.
- Отправьте следующий запрос, пользовательскую команду или запрос оболочки сессии через CodeNomad для применения текущего окружения к разговору.
Это настройка профиля конфигурации, применяемая на серверной стороне перед каждой отправкой. Простое открытие/чтение разговора или сохранение настроек не меняет нативную сессию. Удаление переопределения восстанавливает унаследованное значение хоста выполнения или удаляет переменную, если её там нет. Ошибка применения окружения блокирует отправку вместо использования устаревших значений.
Окружение управляет последующими локальными запусками оболочки в нативной сессии. Уже работающие процессы сохраняют окружение. Оно не перенастраивает провайдеров, MCP/LSP-серверы, независимые терминалы или фоновые оболочки только Location. Каждый запрос очереди не фиксирует собственное окружение, а другой клиент OpenCode может заменить окружение той же сессии. Не предполагайте, что дочерние сессии, полностью созданные внутри OpenCode, получают обновление CodeNomad при отправке.
Разрешённые переменные также передаются при запуске остановленной службы; подключение к существующему демону не меняет окружение его процесса. В WSL значения объединяются с Linux-окружением, а не Windows PATH/HOME. Изменение переопределений не перемещает базу OpenCode или регистрацию службы.
Редактирование нативных файлов конфигурации
- Откройте Настройки → Файлы конфигурации и выберите Файл.
- Проверьте показанный путь, внесите правки и нажмите Сохранить.
- Используйте Перезагрузить для повторного чтения файла; это не Перезагрузить конфигурацию OpenCode.
Этот редактор предоставляет только перечисленные глобальные файлы opencode.json и opencode.jsonc в каталоге .config/opencode пользователя сервера CodeNomad. Это не редактор произвольных файлов, не выбор проектной конфигурации и не гарантия чтения файла демоном WSL/с пользовательскими путями обнаружения. Проверьте цель по показанному пути; для других корней используйте инструменты самого демона.
Сохранение записывает файл как текст; оно не проверяет всю нативную конфигурацию и не перезапускает/перезагружает OpenCode. Согласуйте правки с другими клиентами: слияния внешних изменений здесь нет. Сделайте копию перед существенной заменой конфигурации. При переключении файлов или перезагрузке изменённого черновика запрашивается подтверждение его отбрасывания.
Специальные процедуры настройки описаны в разделах Интеграции, Провайдеры, Миссии и документации OpenCode.