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.
12 KiB
Sorun giderme
Önce başarısız işlemin sahibini kontrol ederek kurtarın: tarayıcı, CodeNomad arka ucu, OpenCode hizmeti veya sağlayıcısı. Kayıp bir yanıt, değişiklik işleminin başarısız olduğunu kanıtlamaz; tekrarlamadan önce mevcut durumu yeniden okuyun.
Masaüstü başlatma sorunları
macOS karantinası
CodeNomad'ın macOS sürümleri Apple tarafından noter onayından (notarization) geçirilmez; bu nedenle macOS, resmi depodan doğruladığınız bir kopya bile olsa indirilen kopyanın ilk açılışını engelleyebilir: "CodeNomad" Not Opened iletisini (Apple kötü amaçlı yazılım içermediğini doğrulayamadı) gösterebilir veya uygulamanın zarar gördüğünü bildirebilir.
- İndirmenin kaynağını ve yüklü uygulama yolunu kontrol edin.
- Uygulama aşağıdaki yola yüklendiyse karantina özelliğini kaldırın:
xattr -dr com.apple.quarantine /Applications/CodeNomad.app
- Tekrar başlatın. Not Opened iletisinde bunun yerine, engellenen açılıştan sonra System Settings → Privacy & Security içinde CodeNomad için Open Anyway seçeneğini seçip yönetici parolanızla onaylayabilirsiniz.
Bu, söz konusu uygulamadaki macOS karantina özelliğini değiştirir. Bozuk bir indirmeyi onarmaz veya bilinmeyen bir ikili dosyayı güvenilir hale getirmez.
Linux grafikleri ve FUSE
Wayland/NVIDIA'dan hemen çıkan bir Tauri AppImage, WebKitGTK'nin DMA-BUF/GBM görüntü görüntü oluşturucusundan etkilenebilir. İndirilen AppImage'ı hedeflenen ortam geçersiz kılmayla çalıştırın:
WEBKIT_DISABLE_DMABUF_RENDERER=1 ./CodeNomad-Tauri-linux-x64-<version>.AppImage
Electron, Chromium'u kullanır ve aynı ana bilgisayardaki bir alternatiftir. FUSE kullanılamadığı için AppImage bağlanamıyorsa --appimage-extract-and-run'yi kullanın; bkz. Linux kurulumu. Bu düzeltmeler Electron korumalı alanının devre dışı bırakılmasını gerektirmez.
Git ve çalışma alanı kullanılabilirliği
- Git'i yalnızca aracının kabuğunun içinde değil, arka uç hesabının
PATH'sinde de kontrol edin. - Eksikse bu ana bilgisayara/hesaba Git yükleyin, ardından güncellenen ortamı devralması için CodeNomad arka ucunu yeniden başlatın.
- Çalışma alanını yeniden açın/yenileyin ve depo durumunu kontrol edin.
Yalnızca dizin konuşmaları Git olmadan kullanılabilir durumda kalır; Worktree ve Git kontrolleri bunu yapmaz. Windows'ta, yalnızca WSL içine yüklenen Git, Windows arka ucu için yeterli değildir. Deposu olmayan bilinen bir klasör Git'i başlat öğesini açığa çıkarabilir; eksik bir Git yürütülebilir dosyası farklı bir durumdur ve öncelikle düzeltilmesi gerekir. Bkz. gereksinimler ve Dosyalar.
Sahip olunan bir çalışma ağacı veya konuşma yerleşimi doğrulanamıyorsa, rastgele yolları denemek veya yerel depolamayı düzenlemek yerine fiziksel klasörünü açıkça açın. Hangi yerleşimin gerçekte mevcut olduğunu görmek için belirsiz bir taşıma/kaldırma işleminden sonra yenileyin. Bir çalışma ağacının zorla kaldırılması commit edilmemiş dosyaları yok edebilir; bağlantı onarımı olarak kullanmayın.
OpenCode çalışma zamanı ve WSL
- Preferences → OpenCode öğesini açın ve OpenCode sürümü kartını (kurulu sürüm ve çalışan hizmet durumu), ardından OpenCode Binary altındaki seçili yürütülebilir dosyayı kontrol edin.
- Gerekli çalışma zamanı yoksa desteklenen kurulum/güncelleme eylemini kullanın. Güncel alt sınır: 2.1.2; önerilen/doğrulanan: 2.1.3.
- Kurulu CLI, çalışan hizmetten farklıysa, paylaşılan hizmetin yeniden başlatılıp başlatılmayacağına açıkça karar verin.
OpenCode hizmetini yeniden başlat, Sorun giderme altında mevcuttur ve onay gerektirir. Bağlı her istemcideki aktif çalışmayı kesintiye uğratır ancak oturum geçmişini korur. Yapılandırmanın yeniden yüklenmesi ayrı bir eylemdir: süreci korur ancak yüklenen Konumları yeniden oluşturur ve bekleyen soruları/izinleri iptal eder. Zararsız bir yenileme de değildir.
WSL yürütülebilir dosyasında amaçlanan dağıtımı ve Windows localhost yönlendirmesini doğrulayın. Hizmet yaşam döngüsü Linux içinde çalışır; CodeNomad yine de Windows'tan loopback uç noktasına erişmelidir. Hizmet kaydını/veritabanını asla düzenlemeyin veya Windows'tan tahmini Linux süreç kimliklerine sinyal göndermeyin.
Özel/daha yeni sürüm, uyumsuz olmadan da doğrulanmamış olabilir. Sürüm değiştirmeden önce gerçek sözleşme hatasını okuyun. Oturum ortamı eşitlemesi başarısızsa yürütme ana bilgisayarının ortamını/bağlantısını düzeltin: CodeNomad bu eşitleme olmadan istem göndermez. Bkz. OpenCode.
Oturum açma, TLS ve doğrudan bağlantı
| Belirti | Güvenli kontrol ve kurtarma |
|---|---|
| CodeNomad’a yeniden giriş yapın | Sayfayı açık tutun, sunucu kullanıcı adını/şifresini girin ve Giriş yap öğesini seçin. Taslakları tutmak için kurtarma yeniden bağlanır; başarısız olan eylemi tekrarlamaz. |
| Sunucuya ulaşılamıyor | Arka ucun çalıştığını doğrulayın ve yazdırılan adresini/gerçek bağlantı noktasını kullanın. Ulaşılamayan bir kontrol tek başına giriş bilgilerinizin süresinin dolduğunu kanıtlamaz. |
| Sağlayıcı kimlik doğrulamayı reddediyor | Sağlayıcının giriş bilgilerini sahibi aracılığıyla onarın; sağlayıcı OAuth'yi onarmak için CodeNomad sunucu şifresini değiştirmeyin. |
| Sertifika adı/güven hatası | Gerçek ana bilgisayar adını/IP'yi SANs sertifikasına göre kontrol edin ve amaçlanan CA güvenini veya geçerli bir sunucu sertifikasını yükleyin. TLS doğrulamasını devre dışı bırakmayın. |
| Doğrudan bağlantı reddedildi | Etkili HTTP/HTTPS bağlamayı, güvenlik duvarını ve yönlendirmeyi kontrol edin. HTTP masaüstü veya çift dinleyici modunda geri döngüde kalır; bağımsız HTTP-yalnızca farklı bağlanma davranışına sahiptir. |
Kimlik doğrulama kurtarıldıktan sonra, yanıtı belirsiz olan bir değişiklik işlemini manuel olarak yeniden denemeden önce durumu inceleyin. Çalışma zamanı parolaları her arka uç başlangıcında sağlanmalıdır; ayarlar aracılığıyla kaydedilen şifre kalır. Bkz. güvenlik, TLS/bağlama kuralları ve sunucu referansı.
Uzaktan Kontrol eşleştirme
- Ana bilgisayarda Ayarlar → Uzak Erişim öğesini açın ve Uzaktan Kontrol'ün çalıştığını kontrol edin.
- Yeni bir eşleştirme bağlantısı oluşturun ve süresi dolmadan bu bağlantıyı amaçlanan cihazda açın.
- İstemci Bu cihazı yeniden eşleştirin gösteriyorsa, ana bilgisayardan eşleştirin ve ardından istemcide Bağlantıyı kontrol et öğesini seçin.
Eşleştirme bağlantıları tek kullanımlıktır ve kısa ömürlüdür; doğrudan erişim şifresi onun yerine geçmez. İptal edilen veya etkinliğin sona erdiği cihaz kimlik bilgilerinin yeniden eşleştirilmesi gerekir. Son masaüstü penceresinin kapatılması, arka ucunu ve dolayısıyla Uzaktan Kontrolü durdurur; Etkinleştirilmiş bir hizmet, bir sonraki uygulama açılışında devam eder. Kullanılamayan yalnızca ana bilgisayar yüzeyleri ve iptal için Uzaktan Kontrol bölümüne bakın.
Sağlayıcı, eklenti ve uzantı durumu
| Sorun | Kurtarma |
|---|---|
| Yanlış sağlayıcı hesabı/kota | Seçilen yerel hesabı ve Kullanım öğesini kontrol edin. Kota ekranı bir belirteç/maliyet toplamı değildir. Belirsiz bir hesap değişikliğinden sonra yenileyin; seçim o hizmetin diğer istemcilerini etkileyebilir. |
| Süresi dolmuş harici mülkiyetli OAuth | OpenCode, Claude Code veya ilgili kimlik bilgisi sahibi aracılığıyla tekrar oturum açın. CodeNomad yenileme jetonlarını değiştirmez. |
| Otomatik hesap seçimi geçiş yapmıyor | Özelliğin açık ve hesabın uygun olduğunu, mevcut kotanın tamamen dolduğunu kontrol edin. Bu, devam eden isteğe müdahale veya hemen yeniden yürütme değil, kabul öncesi ilkedir. |
| Eklenti durumu eski görünüyor | Plugin denetimlerini yenile öğesini kullanın ve eklenti ipucunun kapsamını/hedefini inceleyin; çalışma zamanı aktivasyonu yerel yenilemeyi bekleyebilir. Belirsiz bir yazmayı tekrar tekrar değiştirmeyin. |
| Görev Kontrolü kullanılamıyor | Belirtilen nedeni izleyin. OpenCode Görevler eklentisini yüklemediyse yenileyin, sorun sürerse OpenCode yapılandırmasını yeniden yükle eylemini kullanın; eklenti yüklenemediyse hatasını Eklentiler listesinde okuyun; sunucu yerel Görevler bağlantısını açamadıysa sunucu günlüğünü kontrol edin, çünkü OpenCode'u yeniden yüklemek işe yaramaz. Görevler bağımsız sunucuda da çalışır. |
| Yüklü uzantı eksik | Panel özelleştirmesinde tek etkinleştirme onay kutusunu işaretleyin. Kurulum/değiştirme işlemi, siz açıkça etkinleştirip gerekli onayı onaylayana kadar onu devre dışı bırakır. |
| Uzantı öğeleri reddedildi | Geçerli bağlı oturum için API 2 varlık okuma iznini onaylayın. Bir uzantı yüklemek, rastgele dosyaları/geçmişi okuma izni değildir. |
Bkz. Sağlayıcılar, Entegrasyonlar ve Uzantılar.
Geçmiş, bekleyen istekler ve temizleme
Tam geçmiş araması, halihazırda yüklü olan konuşma dökümü satırlarıyla sınırlı değildir. Görüntüleme filtresi içeriği silmeden gizler; Arama, sıkıştırma, teknik temizleme ve silme işlemlerini ayırt etmek için Geçmiş'yi kullanın.
Bekleyen istek kurtarma işlemi tamamlanmadıysa CodeNomad, eksik kapsamı boş bir kuyruk olarak ele almak yerine bilinen kuyrukları ve yanıt taslaklarını korur. Art arda iki eksik kurtarma sonrasında projeyi, nedeni, klasörleri ve etkilenen oturumları belirterek bir kez uyarır; uyarı Projeler ve sekmeler bildirim kategorisine aittir (varsayılan olarak ekranda ve geçmişte görünür; bkz. Ayarlar → Bildirimler). Geçici arızalar canlılık kontrolü tarafından yeniden denenir. Sıkıştırmayla ilgili erteleme, talebin iptal edildiği anlamına gelmez. Taslağı olduğu gibi bırakın, hizmet bağlantısını doğrulayın ve tekrar yanıtlamadan önce isteğin mevcut durumunu kullanın.
İptal edilmiş veya kısmi temizlikte başka silme başlatmadan önce ilerlemeyi/karar kayıtlarını okuyun. İptal gönderilmiş toplu işlemi geri almaz. Geçmişi OpenCode veritabanını düzenleyerek onarmayın. Görev belirsizliğinde yeni çalıştırma oluşturmak veya işi otomatik tekrarlamak yerine Durumu denetle/yenileme kurtarmasını kullanın; Görevler yeniden başlatma ve çalışma ömrü sınırlarını açıklar.
Günlükler ve güvenli tanılama
- Durumunu incelemek için Instance Bilgisi öğesini açın; Sunucu log'larını göster mevcut çıktıyı ortaya çıkarır.
- Preferences → OpenCode bölümünde amaçlanan Varsayılan log seviyesi öğesini yalnızca daha fazla ayrıntıya ihtiyaç duyulduğunda seçin. Bağımsız CodeNomad günlük kaydı için sunucu CLI günlük kaydı seçenekleri'yi kullanın.
- Ayarlar → Bilgi → Tanılama öğesini açın ve Hata bildir, Panoya kopyala veya .txt indir öğesini kullanın.
Günlüğe kaydetme ayrıntıları yolları, çıktıları ve uygulama verilerini ortaya çıkarabilir. Günlükleri/yakalamaları paylaşmadan önce kimlik bilgilerini, eşleştirme bağlantılarını, ağ adreslerini, özel yolları ve konuşma içeriğini çıkarın. Tam teşhis raporu yolları/adresleri içerir; önceden doldurulmuş hata formu bunları kasıtlı olarak hariç tutar. Bkz. Destek.