CH 07 · トラブルシューティング早見表
この章の目標
起動して使い始めた後、問題にぶつかったら、慌てずこの地図と照合してください。よくある起動・設定・実行時のもろもろの問題を 1 か所にまとめました。
起動できない
dsh web の起動でよくある落とし穴は 3 つだけです:
| 症状 | 原因 | 対処 |
|---|---|---|
| 起動時にポートが占有されていると表示される | 3080 が別プログラムに使われている | 起動時にポートを変える: dsh web --port 8080(これは起動コマンドの一部で、実行中に変更するものではありません) |
| ブラウザが自動で開かない | 一部の環境では自動でブラウザを開けない | 手動で http://127.0.0.1:3080 を開く(ポート変更した場合は対応するポート) |
| 使っている途中で dsh サービスが勝手に終了する | dsh サービスは時々自分で終了する | 故障ではない、必要になったらもう一度起動してください |
設定関連のエラー
モデルの設定中、エラーはいくつかのカテゴリに分類されます—— 該当するものを探してください:
| エラー | 意味 | 対処 |
|---|---|---|
MISSING_CREDENTIAL | キーが未設定 | 設定 → モデル でキーを保存、または参照される環境変数を設定 |
INVALID_CREDENTIAL | キーの形式が誤り | 余分なスペースや欠落文字がないか確認 |
UNKNOWN_MODEL | モデルが存在しないか未設定 | Model ID が設定済みか確認、またこのプロバイダがそのモデルをサポートしているか確認 |
UNSUPPORTED_REASONING_EFFORT | 推論レベルがサポート対象外 | off / low / high / max のいずれかを使う |
| 利用可能モデルの取得が 401 を返す | キーが誤り | キーを確認。モデル検出は OpenAI 互換の GET /models を呼び出す。そのエンドポイントを提供しないサービスの場合は手動でモデルを入力 |
実行時のリクエストエラー
リクエスト送信後に HTTP エラーコードが出た場合、それはほぼ DeepSeek サーバ側のステータスであり、設定とは無関係です。公式のエラーコード早見表:
| コード | 意味 | 対処 |
|---|---|---|
| 401 | 認証失敗 | API Key が有効か、期限切れでないか確認 |
| 402 | 残高不足 | DeepSeek 開放プラットフォームでチャージ |
| 422 | パラメータエラー | エラーメッセージに従ってリクエストパラメータを修正 |
| 429 | リクエスト過多 | リクエスト頻度を下げ、少し待って再試行(連打しない) |
| 500 | サーバ内部エラー | 少し待って再試行、繰り返し失敗するなら公式チームに連絡 |
| 502 | ゲートウェイエラー | 上流のモデルサービスが利用不可、しばらく待って再試行 |
| 503 | サーバ混雑 | サーバ側負荷が高い、後で再試行 |
dsh は内部的にエラーをいくつかの安定コード(AUTH 認証失敗、QUOTA クォータ、RATE_LIMIT レート制限、CONTEXT_WINDOW_EXCEEDED 文脈オーバーフロー、TRANSPORT ネットワーク転送失敗など)にも分類しています。これらのコードを見かけたら、文字通り受け止めてください —— ほぼ書いてある通りの意味です。
界面の小さな落とし穴 2 つ
- モデルセレクタが「モデルを選択」と表示され、入力欄が入力を受け付けない:以前設定したデフォルトモデルが、削除済みのプロバイダを指しています。もう一度モデルを選び直せば回復します。
- headless で走らせたタスクが見つからない:セッション一覧の未分類を見てください(CH 05 で説明済み:ファイル保存は作業ディレクトリ別、界面表示は未分類 —— 別の話)。
まず試したい 3 つの手段
問題にぶつかったがうまく言語化できないときは、この順で試してください —— 多くの問題はこれで解決します:
- ログを確認する:起動時のターミナル出力、またはリダイレクトした起動ログ(例:
dsh web > .dsh-startup.log 2>&1)、エラーコードがそのまま出ています。 - AI 自身に設定ツリーを確認させる:セッションで
--dump-configを使って設定を確認するよう依頼し、「なぜデフォルトモデルが望みのものにならないのか」のような質問を投げれば、AI 自身が定位してくれます(CH 05 でこのコツを扱いました)。 - サービスを再起動する:dsh サービスはもともと自分で終了するので、もう一度起動すれば直ることが多いです。
それでも駄目なら、レベルの応じて 2 通り:
- 完全な初心者(dsh が初めての Agent):公式リポジトリの Issues で同じエラーキーワードを検索、誰かが同じ問題に遭遇している可能性が高い。
- すでに Claude Code や Codex を使ったことがある:そのままそれらに Troubleshooting を手伝わせてください。
この章で学んだこと
- [ ] 起動時の 3 つの落とし穴(ポート占有 / ブラウザ未起動 / サービスの自己終了)を知り、それぞれ対処できる
- [ ] 設定エラーの表を使って
MISSING_CREDENTIAL、UNKNOWN_MODEL、UNSUPPORTED_REASONING_EFFORTに対処できる - [ ] よくある実行時 HTTP エラーコード(401 / 402 / 429 / 500 / 502 / 503)の意味を認識し、基本的な対処ができる
- [ ] 「モデルを選択」と表示されて入力欄がロックされるのは、デフォルトモデルが削除済みプロバイダを指しているためだと知っている
- [ ] 新しい問題に出くわしたら、まず 3 つの手段(ログ確認 / dump-config / 再起動)を試す