mirror of
https://github.com/NeuralNomadsAI/CodeNomad.git
synced 2026-10-24 15:21:21 +00:00
39c0fa5833
## Summary
- Qualify OpenCode **2.1.4** (latest stable, 23 October) with the
existing locked **2.1.0 client/plugin** dependencies, and **recommend**
it.
- Keep the technical **minimum at 2.1.2**: no consumed contract changed,
so the minimum has no new reason to move.
- 2.1.2 and 2.1.3 daemons stay ready and get an optional upgrade offer.
2.1.4 is the `tested` version. Newer and custom labels keep
authenticated contract recognition.
- The reviewed-contract fast path lists the 2.1.2 minimum and the 2.1.4
target.
- The recommended version is updated in the help (all ten locales), both
READMEs, `CONTRIBUTING.md`, `dev-docs/OPENCODE_COMPATIBILITY.md` and the
architecture skill.
## Contract review (v2.1.3 → v2.1.4, 72 commits)
- **Authenticated OpenAPI:** 121 → **124 paths**, 146 → **149
operations**. No operation changed. The changes:
- added `POST /api/experimental/client-mcp/token`;
- added `GET /api/experimental/client-mcp` (WebSocket);
- added `POST /api/debug/heap-dump`;
- `Config.InfoEncoded` gains the opt-in
`experimental.background_compaction`.
The session event (`V2EventEncoded`) and message schemas are unchanged.
None of the new routes is on the instance proxy allowlist, and the proxy
relays WebSockets only for SideCars and previews.
- **Published declarations:**
- the client adds `mcp.client.token` and `debug.heapDump`;
- the schema and plugin changes are type refactors and unused-export
removals, among them `SessionID.descending`, `SessionEvent.Source` and
`PromptInput.FileAttachment.create`; `Session.Message.ID.fromEvent` now
takes any string instead of an event ID. CodeNomad uses none of these,
and every host module its native plugin bundles import
(`@opencode/plugin`, `/effect`, `/promise/adapter`, `/rpc`,
`@opencode/schema/location`, `/session`) still exists.
- **MCP elicitation forms**
([#58184](https://github.com/anomalyco/opencode/pull/58184)): an MCP
server asking for input during a tool call now creates a global-session
Form whose `form.created` event carries the server's location.
CodeNomad's live path requires that location for global Forms and shows
them as a **Project request**. Review found that the live path dropped
the location from the queued Form, so its reply lacked
`x-opencode-directory` and failed for a worktree or subdirectory until a
pending-request rescan. **#1127** fixes that; recovery already kept it.
A native probe (minimal stdio MCP server, a real Code Mode `execute`
call, CodeNomad-style reply) gives:
| Runtime | Form listed for the location | `form.created` carries the
location | Reply completes the tool |
| --- | --- | --- | --- |
| 2.1.3 | yes | **no** | yes |
| 2.1.4 | yes | **yes** | yes (`action: accept`, `channel: stable`) |
On 2.1.3 such a request only appeared after a pending-request rescan; on
2.1.4 it appears live. The probe sends the location header itself, so it
checks the runtime contract; #1127 covers CodeNomad's live reply path.
- **Other changes** are covered by the native suites below:
- compaction (oldest-first shortening, ignored buffers, overflow
detection);
- the agent's model for sessions without one;
- V2 agent files;
- V1 global-session import attribution;
- MCP lifecycle fixes.
- **Live check:** this machine's shared daemon runs 2.1.4, and the
CodeNomad desktop session works through it.
## Isolated Windows qualification
Base: dev `9ac792fff`; Node **24.20.0**; exact official CLI **2.1.4**;
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 (10/10):**
- history from **2.0.3, beta-19271, 2.0.32, 2.1.0, 2.1.1, 2.1.2 and
2.1.3** to 2.1.4;
- Git degraded/init;
- temporary workspaces.
- **Installation (3/3), with the 2.1.4 recommendation:**
- fresh install of the 2.1.2 minimum;
- native **2.0.15 → 2.1.4** upgrade, after which the already-running
daemon keeps its PID and 2.0.15 version;
- explicit OpenCode **1.18.10 → 2.1.4** replacement.
- **After the recommendation change:**
- admission, transport, update, installation and instance proxy units
**116 passed, 1 POSIX-only skipped**;
- full server **2,471 passed, 8 skipped**, no failure or cancellation;
- UI units **1,699/1,699**;
- 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 (**9/9**).
This is Windows automation evidence. In CI, `latest` resolves to 2.1.4:
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.
71 lines
12 KiB
Markdown
71 lines
12 KiB
Markdown
# OpenCode のセットアップ
|
||
|
||
CodeNomad は、実行ホストの共有 OpenCode サービスに接続します。CLI の選択、そのファイルの更新、サービスの再起動、設定の再読み込みは別の操作であり、互いの代わりにはなりません。
|
||
|
||
## CLI の選択・インストール {#select-cli}
|
||
|
||
1. **設定 → OpenCode** を開き、**OpenCode バージョン** の下にある **OpenCode バイナリ** カードで実行ファイルを選びます。
|
||
2. 自動の項目を選択したままにすると、サーバーの PATH（古い OpenCode がある場合を除く）、次にユーザーの npm の OpenCode 2 インストールを優先します。または、**バイナリを参照…** を使うか、パスを入力して **追加** を選びます。
|
||
3. **状態と更新を確認** を使用します。OpenCode がなければ **OpenCode をインストールして起動** を選びます。先にホストとインストール範囲を確認してください。
|
||
4. セットアップに **接続して続行** が表示される場合は、報告された問題を解決してから使用します。
|
||
|
||
インストールでは同梱の Node/npm を使用し、他のクライアントと共有する標準のユーザーインストールを行います。**ユーザー用にインストールして PATH を設定** は、そのユーザーのターミナル設定を変更します。後で新しいターミナルを開いてください。ブラウザーは CodeNomad サーバーに接続するため、ファイルピッカーと実行ファイル選択の対象は、閲覧端末ではなくそのサーバーです。
|
||
|
||
PATH の先頭に古い OpenCode がある場合、提示される操作はそのインストール方法によって異なります。npm でインストールした OpenCode 1.x では、**OpenCode {version} を OpenCode 2 に置き換える** が確認を求めたうえで、その npm パッケージを削除し、同じ npm フォルダーに OpenCode 2 をインストールします。OpenCode のデータフォルダーは保持され、OpenCode 2 が 1.x の会話を自動で取り込みます。別の方法（winget、Homebrew、手動）でインストールされた古いまたは使用できない OpenCode は変更されません。**CodeNomad 用に OpenCode 2 をインストール** がその横のユーザー npm フォルダーに OpenCode 2 をインストールし、以後 CodeNomad はそのコピーを使用します。その古いコマンド自体がユーザー npm フォルダーにある場合（たとえば `~/.local/bin` 内のリンク）や、そのフォルダーに書き込めない場合は、この操作の代わりに理由が表示されます。コマンドを移動するか名前を変更する、またはフォルダーの権限を修正してから、**状態と更新を確認** を選択してください。ターミナルの `opencode` コマンドは、引き続き古いバージョンを起動する場合があります。明示的に選択したカスタム実行ファイルが置き換えられることはありません。
|
||
|
||
インストール済み実行ファイルと、実行中のサービスは、バージョンが異なる場合があります。別の実行ファイルを選ぶと稼働中のデーモンも置き換わったと思わず、**OpenCode バージョン** カードの **インストール済みバージョン** と **実行中のサービス** を比較してください。**バージョンの詳細** には最低バージョンと推奨バージョンが記載されています。インストール中や実行ファイルのロック中は、インストーラーやプロセスが解放するまで待ち、状態を確認してから再試行します。競合するインストーラーを実行しないでください。
|
||
|
||
## 必須、推奨、未検証のバージョン {#versions}
|
||
|
||
| 分類 | 現在の要件 | 意味 |
|
||
| --- | --- | --- |
|
||
| 最低 | OpenCode **2.1.2** | Code Mode の JavaScript ジョブの正しい実行順序と、2.1 のネイティブ再生・圧縮形式。以前のバージョンで保存した会話は、更新後も読み込めます。 |
|
||
| 推奨 | OpenCode **2.1.4** | 検証済みの対象。技術的な最低要件とは別です。 |
|
||
| 未検証 | 完全には検証していない、新しいまたはカスタムのバージョン | 未テストという理由だけで拒否せず、接続先サービスの実際の API 契約を確認します。 |
|
||
|
||
必要なセッション、権限、Form、受信箱、セッション環境の契約も利用可能である必要があります。実行ファイルのバージョンだけでは、接続先サービスの対応を証明できません。セットアップが実行中のサービスを未対応と報告した場合は、対応する CLI を選択／インストールし、準備ができたら明示的に共有サービスを再起動します。
|
||
|
||
## ホスト、WSL、共有サービスの範囲 {#execution-host}
|
||
|
||
Windows で WSL の実行ファイルを選ぶと、選択したディストリビューション内で実行します。そこでインストール／更新し、そのディストリビューション内で意味のあるパスを使用してください。WSL の接続は Windows の localhost 転送に依存します。Windows CLI と WSL CLI は、交換可能な実行環境ではありません。
|
||
|
||
グローバルなサービス登録、セッション、メッセージ、データベースは OpenCode が管理します。CodeNomad は、ウィンドウやプロジェクトごとに専用の OpenCode データベースを作りません。プロジェクトタブを閉じると CodeNomad 内でそのプロジェクトが閉じられますが、セッションは OpenCode で続き、プロジェクトを開き直すと再び表示されます。CodeNomad がネイティブの Location を解放することはありません。ウィンドウ全体を閉じる、終了する、再読み込みする場合は、復元のためにプロジェクト接続が保持されます。これらの操作も、バックエンドの終了も、共有デーモンを停止しません。[プロジェクト](projects.md)を参照してください。
|
||
|
||
## 更新、再起動、再読み込み {#maintenance}
|
||
|
||
1. **設定 → OpenCode** で、**状態と更新を確認** を選びます。
|
||
2. インストール済み CLI のファイルを置き換えるには、提示された **OpenCode {version} に更新** を選び、完了を待ちます。
|
||
3. 実行中サービスの状態を確認します。接続中の全クライアントで選択したインストールを有効にしたい場合にのみ、**共有サービスを再起動** を使用します。
|
||
4. 何もインストールせずにプロセスを再起動するには、**トラブルシューティング** を展開し、**OpenCode サービスを再起動** を選んで確認します。
|
||
|
||
| 操作 | 範囲と効果 | 安全な復旧 |
|
||
| --- | --- | --- |
|
||
| CLI の更新 | 対応するインストール済み実行ファイルを変更します。実行中のデーモンは暗黙に再起動しません。 | 失敗後はインストール済みと稼働中の両バージョンを確認し、エラー解決後にのみ明示的に再試行します。 |
|
||
| サービスの再起動 | 共有プロセスを置き換え、接続中の全 OpenCode クライアントの作業を中断します。セッション履歴は残ります。 | 再接続し、会話とスケジュール済みミッションを確認します。再起動は自動続行ではありません。 |
|
||
| OpenCode の設定を再読み込み | プロセスは維持しますが、全クライアントの **読み込み済みのすべての Location** を再構築します。保留中の権限／Form をキャンセルし、ターミナル／バックグラウンドコマンドを閉じます。進行中の作業が中断される場合があります。 | 再読み込み後にリソースと保留中の作業を再確認します。応答が失われたという理由だけで、プロンプトや変更操作を繰り返さないでください。 |
|
||
|
||
保存した設定やインストール済みプラグインがまだ利用できず、中断を許容できる場合に、明示的に **OpenCode の設定を再読み込み**（実行中のサービスが対応していれば **トラブルシューティング** の下にあります）を使用します。無害な表示更新ではありません。CodeNomad は、古い選択済み CLI を使って、新しい実行中デーモンをダウングレードしません。
|
||
|
||
## セッション環境 {#session-environment}
|
||
|
||
1. **設定 → 詳細設定** を開き、**環境変数** を展開します。
|
||
2. プロファイルの上書き値を追加、変更、削除します。各変更はすぐに保存されます。
|
||
3. CodeNomad から次のプロンプト、カスタムコマンド、セッションシェルリクエストを送信すると、その会話に現在の環境が適用されます。
|
||
|
||
これは設定プロファイルの設定であり、毎回の送信前にサーバー側で適用します。会話を開く／読むだけ、または設定の保存だけではネイティブセッションは変わりません。上書きを削除すると、実行ホストから継承する値に戻り、そこにない場合は削除します。環境を適用できない場合は、古い値を使わず送信をブロックします。
|
||
|
||
環境は、そのネイティブセッションで今後起動するローカルシェルを制御します。実行済みのプロセスは自分の環境を保持します。プロバイダー、MCP/LSP サーバー、独立したターミナル、Location のみのバックグラウンドシェルは再設定 **しません**。キューの各プロンプトが独自の環境を記録するわけではなく、別の OpenCode クライアントが同じセッション環境を置き換える場合もあります。OpenCode 内だけで作られた子セッションが CodeNomad の送信時更新を受けるとは想定しないでください。
|
||
|
||
許可された変数は、停止中のサービスを起動するときにも渡されます。既存デーモンへの接続では、そのプロセス環境は変更しません。WSL では、Windows の PATH/HOME ではなく、Linux の実行環境と値を組み合わせます。これらの上書きを変えても、OpenCode のデータベースやサービス登録の場所は移動しません。
|
||
|
||
## ネイティブ設定ファイルを編集する {#configuration-files}
|
||
|
||
1. **設定 → 設定ファイル** を開き、**ファイル** を選びます。
|
||
2. 表示されたパスを確認して編集し、**保存** を選びます。
|
||
3. **再読み込み** はファイルを読み直します。**OpenCode の設定を再読み込み** とは異なります。
|
||
|
||
このエディターが公開するのは、**CodeNomad サーバーユーザーの** `.config/opencode` ディレクトリにある、一覧に記載されたグローバルな `opencode.json` と `opencode.jsonc` のみです。任意のファイルのエディターやプロジェクト設定セレクターではなく、WSL／独自検出ルートのデーモンがそのファイルを読む保証もありません。表示パスで対象を確認し、ほかのルートにはデーモン自身のツールを使ってください。
|
||
|
||
保存はファイルをテキストとして書き込みます。ネイティブ設定全体の検証や OpenCode の再起動／再読み込みはしません。この画面には外部変更のマージ機能がないため、他クライアントと編集を調整してください。大幅な置き換えの前にコピーを保持します。ファイル切り替えや未保存下書きの再読み込み時には、破棄するか確認します。
|
||
|
||
設定固有の手順は、[連携](integrations.md)、[プロバイダー](providers.md)、[ミッション](missions.md)、[OpenCode ドキュメント](https://opencode.ai/v2/docs/)を参照してください。
|