トラブルシューティング

まず spec.jev doctor、またはセッション内で /doctor を実行します。インストール、モデル、判定器、各接続を確認し、何を直せばよいかを示します。デスクトップアプリでは、設定 → 情報からワンクリックでログを開けます。

どれも役に立たなければ、バージョン、プラットフォーム、spec.jev doctor の出力を添えて issue を作成してください。

インストールと起動

spec.jev needs Node >= 22.19 (found v20…)。 コマンドラインには Node.js 22.19 以降が必要です。nvm install 24 か、お使いのシステムのパッケージでインストールしてください。デスクトップアプリは自前の Node を内蔵しているので、何も要りません。

Windows で SmartScreen の警告が出る。 Windows 版はまだコード署名がありません。詳細情報を選び、実行を選んでください。すべてのダウンロードのチェックサムは、リリースページの SHA256SUMS にあります。

Windows：会話に Git for Windows がないと表示される。 spec.jev は Windows で、POSIX シェルでコマンドを実行します。Git for Windows をインストールして、新しい会話を始めてください。

C:\Program Files\spec.jev にインストールしたアプリが spec.jev を起動できない。 0.1.5 で修正しました。最新のリリースを古いものに上書きインストールしてください。データは残ります。

spec.jev install、spec.jev list、spec.jev config を実行するとセッションが始まってしまう。 spec.jev 0.1.8 とデスクトップ 0.1.7 で修正済みです。最新のリリースに更新してください。

モデルとネットワーク

モデルが設定されていない。 spec.jev setup かアプリの初回ガイドを実行し、API キーを貼り付けるか、サブスクリプションでサインインしてください。

ターミナルでは問題ないのに、アプリで "User location is not supported" と出る、またはリクエストがタイムアウトする。 モデルのサービスがあなたのネットワークの地域を拒否しているか、アプリがプロキシを認識していません。0.1.5 以降、アプリは HTTPS_PROXY が設定されていなければシステムのプロキシに従います。プロキシがオンになっているかを確認するか、spec.jev 用に HTTPS_PROXY を設定してください。

判定器

判定器が何もしていないように見える。 シャドーの判定ポイントは判定を記録するだけで何も変えず、オフの判定ポイントには問い合わせません。/status で各判定ポイントのモードがわかります。~/.spec.jev/agent/spec.jev.json に "default": "shadow" や "off" がないか、環境に SPECJEV_JUDGE_MODE がないかを確認してください。

「まだ使える判定器がないため、spec.jev はステップごとにあなたに確認します。」 「Jev が承認」モードでは、答えられる判定器がないとき、承認が必要なすべてのステップで spec.jev があなたに確認します。キーがなく無料の Jev も使えない、アカウントの利用枠を使い切った、承認を任されないローカルの判定器しかない、といった場合です。Jev のキーを設定する（spec.jev setup）か、/permissions でモードを切り替えてください。

無料の Jev が答えなくなった。 これは OpenCode Zen の期間限定の提供で、終了したときは spec.jev がそのことを知らせます。Jev のサービスのどれかにキーを設定するか、別の判定器を選んでください。

判定が遅い。 どの判定ポイントにも制限時間があり、それを過ぎると spec.jev は判定なしで先に進みます。長く止まることはありません。spec.jev ledger --json で各判定のレイテンシがわかります。遅い判定器や遠い判定器は、routes で判定ポイントごとに置き換えられます。

ローカルの判定器がモデルをダウンロードしようとする。 Laya のモデルは約 930 MB あります。spec.jev がダウンロードするのは、spec.jev judge setup またはアプリであなたが同意したあとだけです。

ターミナル

サブエージェントが起動すると、ターミナル UI が "Rendered line … exceeds terminal width" でクラッシュする。 spec.jev 0.1.8 とデスクトップ 0.1.7 で修正済みです。最新のリリースに更新してください。

最初からやり直す

spec.jev setup は、変更するファイルをすべて先に ~/.spec.jev/backups/<time>/ にコピーします。spec.jev 自身の設定をリセットするには、~/.spec.jev/agent/spec.jev.json を別の場所に移します。spec.jev は既定値で起動します。セッション、サインイン、教訓は別のファイルなので、そのまま残ります。