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
הגדרת OpenCode
CodeNomad מתחבר לשירות OpenCode משותף במארח ההרצה. בחירת CLI, עדכון קבציו, הפעלה מחדש של אותו שירות וטעינת תצורה מחדש הן פעולות שונות; אף אחת אינה תחליף לאחרות.
בחירת ה־CLI או התקנתו
- פתחו הגדרות → OpenCode והשתמשו בכרטיס קובץ בינארי של OpenCode, מתחת ל־גרסת OpenCode, לבחירת קובץ ההרצה.
- השאירו את הרשומה האוטומטית נבחרת כדי להעדיף את PATH של השרת, אלא אם הוא מכיל OpenCode ישן יותר, ואחריו את התקנת OpenCode 2 של המשתמש ב־npm; או השתמשו ב־עיין אחר קובץ בינארי… או הזינו נתיב ובחרו הוסף.
- השתמשו ב־בדיקת מצב ועדכונים. אם OpenCode חסר, בחרו התקנה והפעלה של OpenCode; בדקו תחילה את המארח ואת היקף ההתקנה.
- אם ההגדרה מציעה התחברות והמשך, השתמשו בכך לאחר פתרון הבעיה שדווחה.
ההתקנה משתמשת ב־Node/npm הכלולים להתקנת משתמש רגילה המשותפת ללקוחות אחרים. התקנה עבור המשתמש והגדרת PATH משנה את הגדרת המסוף של אותו משתמש; פתחו מסוף חדש לאחר מכן. דפדפן מתחבר לשרת CodeNomad: בורר הקבצים ובחירת קובץ ההרצה שלו נוגעים לאותו שרת, לא למכשיר הגולש.
כש־OpenCode ישן יותר מופיע ראשון ב־PATH, הפעולה המוצעת תלויה באופן שבו הותקן. עבור 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. CLI של Windows ו־CLI של WSL אינם סביבות הרצה הניתנות להחלפה זו בזו.
OpenCode הוא הבעלים של רישום השירות הגלובלי, הסשנים, ההודעות ומסד הנתונים שלו. CodeNomad אינו יוצר מסד נתונים פרטי של OpenCode לכל חלון או פרויקט. סגירת לשונית פרויקט סוגרת את הפרויקט ב־CodeNomad; הסשנים ממשיכים ב־OpenCode ומופיעים שוב כשפותחים את הפרויקט מחדש. CodeNomad לעולם אינו פורק Locations מקוריים. סגירת חלון שלם, יציאה או טעינה מחדש משמרות את חיבורי הפרויקטים לשחזור; לא פעולות אלה ולא כיבוי שרת הקצה עוצרים את הדמון המשותף. ראו פרויקטים.
עדכון, הפעלה מחדש או טעינה מחדש
- ב־הגדרות → OpenCode, בחרו בדיקת מצב ועדכונים.
- להחלפת קובצי ה־CLI המותקנים, בחרו עדכון ל-OpenCode {version} כשמוצע. המתינו להשלמה.
- בדקו את מצב השירות הפועל. השתמשו ב־הפעלה מחדש של השירות המשותף רק כשבכוונתכם להפעיל את ההתקנה שנבחרה עבור כל לקוח מחובר.
- להפעלת התהליך מחדש בלי להתקין דבר, הרחיבו פתרון בעיות, בחרו הפעל מחדש את שירות OpenCode ואשרו.
| פעולה | היקף והשפעה | התאוששות בטוחה |
|---|---|---|
| עדכון CLI | משנה את קובץ ההרצה המותקן הנתמך; אינו מפעיל מחדש את הדמון הפועל במשתמע. | בדקו גם גרסה מותקנת וגם פועלת לאחר כשל; נסו שוב במפורש רק לאחר פתרון השגיאה. |
| הפעלה מחדש של השירות | מחליפה את התהליך המשותף וקוטעת עבודה פעילה בכל לקוחות OpenCode המחוברים; היסטוריית הסשנים נשארת. | התחברו מחדש ובדקו שיחות ומשימות מתוזמנות; הפעלה מחדש אינה המשך אוטומטי. |
| טעינה מחדש של תצורת OpenCode | משמרת את התהליך אך בונה מחדש כל Location טעון לכל הלקוחות. מבטלת אישורים/טפסים ממתינים וסוגרת מסופים/פקודות רקע; עבודה פעילה עלולה להיקטע. | בדקו מחדש משאבים ועבודה ממתינה לאחר טעינה מחדש. אל תחזרו על קלט או פעולת שינוי רק מפני שתשובתם אבדה. |
השתמשו ב־טעינה מחדש של תצורת OpenCode, תחת פתרון בעיות כשהשירות הפועל תומך בכך, במפורש כשתצורה שמורה או תוסף מותקן נשארים לא זמינים וההפרעה מקובלת. זה אינו רענון תצוגה תמים. CodeNomad לא ישתמש ב־CLI נבחר ישן יותר כדי לשנמך דמון פועל חדש יותר.
סביבת סשן
- פתחו הגדרות → מתקדם והרחיבו את משתני סביבה.
- הוסיפו, שנו או הסירו את דריסות הפרופיל; כל שינוי נשמר מיד.
- שלחו את הקלט, הפקודה המותאמת או בקשת מעטפת הסשן הבאים דרך CodeNomad כדי להחיל את הסביבה הנוכחית על אותה שיחה.
זו הגדרה של פרופיל תצורה, המוחלת בצד השרת לפני כל שליחה. פתיחה/קריאה של שיחה בלבד או שמירת הגדרות אינן משנות סשן מקורי. הסרת דריסה משחזרת את הערך שהתקבל בירושה ממארח ההרצה, או מסירה אותו אם אינו קיים שם. כשל בהחלת הסביבה חוסם את השליחה במקום להשתמש בערכים מיושנים.
הסביבה שולטת בהפעלות מעטפת מקומיות עתידיות באותו סשן מקורי. תהליכים שכבר פועלים שומרים את סביבתם. היא אינה מגדירה מחדש ספקים, שרתי MCP/LSP, מסופים עצמאיים או מעטפות רקע ברמת Location בלבד. קלטים בתור אינם מצלמים כל אחד סביבה משלו, ולקוח OpenCode אחר יכול להחליף את סביבת אותו סשן. אל תניחו שסשני־בת שנוצרו במלואם בתוך OpenCode מקבלים עדכון בזמן שליחה של CodeNomad.
משתנים מותרים מועברים גם בעת הפעלת שירות עצור; התחברות לדמון קיים אינה משנה את סביבת התהליך שלו. ב־WSL, ערכים משולבים בסביבת הריצה של Linux, לא ב־PATH/HOME של Windows. שינוי דריסות אלה אינו מעביר את מסד הנתונים או את רישום השירות של OpenCode.
עריכת קובצי תצורה מקוריים
- פתחו הגדרות → קובצי הגדרות ובחרו קובץ.
- בדקו את הנתיב המוצג, ערכו ואז בחרו שמור.
- השתמשו ב־טען מחדש לקריאה חוזרת של הקובץ; זו אינה טעינה מחדש של תצורת OpenCode.
עורך זה חושף רק את קובצי opencode.json ו־opencode.jsonc הגלובליים ברשימה תחת תיקיית .config/opencode של משתמש שרת CodeNomad. הוא אינו עורך קבצים שרירותיים, בורר תצורת פרויקט או הבטחה שדמון ב־WSL/בגילוי מותאם קורא את הקובץ. השתמשו בנתיב המוצג לאימות היעד; השתמשו בכלים של הדמון עצמו לשורשים אחרים.
שמירה כותבת את הקובץ כטקסט; היא אינה מאמתת את כל התצורה המקורית או מפעילה/טוענת מחדש את OpenCode. תאמו עריכות עם לקוחות אחרים: ממשק זה אינו מציע מיזוג שינוי חיצוני. שמרו עותק לפני החלפת תצורה משמעותית. מעבר בין קבצים או טעינה מחדש של טיוטה ששונתה שואלים אם להשליך אותה.
ראו שילובים, ספקים, משימות ו־תיעוד OpenCode לתהליכי עבודה לפי סוג תצורה.