# DeepSeek Harness（dsh）を QCode に接続

> **最終確認**：2026-11-09 · 📄 公式ドキュメント準拠（DeepSeek Harness 0.2.2-rc.1、2026-11-04 に npm と GitHub で公開。リポジトリのドキュメントは 2026-11-09 に確認）

## 概要

| 項目 | 内容 |
|---|---|
| それは何か | DeepSeek Harness（`dsh`）は DeepSeek AI が開発したオープンソースの agent harness で、`dsh web` で Web UI を起動します |
| 利用できるモデル | Claude ✅（Anthropic Messages provider）· GPT ✅ · GLM / Kimi / DeepSeek / Qwen ✅（OpenAI Chat Completions provider）· Gemini ❌（QCode は現在 Gemini モデルを提供していません） |
| プロトコルと Base URL | OpenAI Chat Completions：`https://api.qcode.cc/openai/v1` · Anthropic Messages：`https://api.qcode.cc/api` |
| 設定場所 | **Settings → Models** → **Add model provider** → **Custom model API** |
| 書き込み先 | `$DSH_HOME/profiles/<profile>/cordis.patch.yml`。キーは `$DSH_HOME/.credentials.yaml` |
| 公式ドキュメント | [Configure models](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.md) · [リポジトリ](https://github.com/deepseek-ai/deepseek-harness) |

DeepSeek Harness は開発者プレビューです。公式 README には "THERE WILL BE COMPATIBILITY-BREAKING CHANGES." とあります。お使いのバージョンを本ページと照らし合わせてください。

## どのプロトコルを使うか

カスタム provider の **API protocol** は、ゲートウェイが話すプロトコルと一致している必要があります。選択肢は OpenAI Chat Completions、OpenAI Responses、Anthropic Messages の 3 つで、それぞれ `openai-completions`、`openai-responses`、`anthropic-messages` として保存されます。1 つの provider が話せるプロトコルは 1 つなので、2 つのプロトコルを扱うゲートウェイには provider が 2 つ必要です。

QCode では Claude は Anthropic プロトコルのみ、GPT は OpenAI 系プロトコルのみで、中国系 4 ファミリーはどちらでも使えます。[エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths) を参照。そこで provider を 2 つ作ります。

| Provider | API protocol | Base URL | モデル ID（例） |
|---|---|---|---|
| `qcode` | OpenAI Chat Completions（`openai-completions`） | `https://api.qcode.cc/openai/v1` | `gpt-6-sol`、`deepseek-v4-pro`、`glm-5.3`、`kimi-k3`、`qwen3.8-max` |
| `qcode-claude` | Anthropic Messages（`anthropic-messages`） | `https://api.qcode.cc/api` | `claude-sonnet-5`、`claude-opus-5` |

Provider ID は自分で付ける名前です。モデル ID は [qcode.cc/models](https://qcode.cc/models) の表記を一字一句そのまま使います。中国系の ID は [中国系モデル連携](/docs/usage/cn-models) にもあります。base URL の末尾に `/` を付けず、`claude-…` の ID を OpenAI の base URL に置かないでください。

## インストール

DeepSeek Harness には Node.js 24.9 以降が必要です（npm パッケージは `node >=24.9.0` を宣言し、v0.2.2-rc.1 のリリースノートには "Raise the minimum supported Node.js version to 24.9." とあります）。Node.js を入れてから次を実行します。

```sh
npx @deepseek-ai/dsh web
```

このコマンドは既定で `http://127.0.0.1:3080` に Web UI を起動し、ローカル起動なら既定のブラウザーで開きます。SSH 起動ではホスト URL を表示するだけです。ブラウザーを開かずにサーバーを動かすには `--no-open` を付けます。

リポジトリのチェックアウトから動かす場合は次のとおりです。

```sh
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
```

`$DSH_HOME` は harness のデータ置き場で、環境変数 `DSH_HOME` を設定しない限り既定は `~/.dsh` です。実行前に公式の [安全上の注意](https://github.com/deepseek-ai/deepseek-harness/blob/master/SAFETY.md) を確認してください。

## 設定

モデルの変更は次のリクエストから反映され、サーバーの再起動は不要です。

Web UI の表示言語はブラウザーの言語に従います。以下の手順は英語表示の名称で書いています。日本語表示では次のとおりです。

| 英語表示 | 日本語表示 |
|---|---|
| Settings → Models | 設定 → モデル |
| Add model provider · Custom model API | モデルプロバイダーを追加 · カスタムモデルAPI |
| Provider ID · Display name · Base URL | プロバイダーID · 表示名 · ベースURL |
| API protocol · API key | APIプロトコル · APIキー |
| Models · Add model · Fetch available models | モデル · モデルを追加 · 利用可能なモデルを取得 |
| Create provider | プロバイダーを作成 |
| Model options · Reasoning levels · Image | モデルオプション · 推論レベル · 画像 |

1. Web UI を開き、**Settings → Models** から **Add model provider** を選びます。
2. カードを **Custom model API** に切り替えます。中継、社内ゲートウェイ、自前のサーバー、インストール済みカタログにない provider 向けの項目です。
3. 最初の provider のフォームを埋めます。
   - **Provider ID**：`qcode`（小文字。後から変更できないので慎重に選びます）
   - **Display name**：`QCode`（任意）
   - **Base URL**：`https://api.qcode.cc/openai/v1`
   - **API protocol**：OpenAI Chat Completions
   - **API key**：あなたの QCode キー（`cr_` で始まる）
4. フォームの **Models** の一覧（公式ガイドではモデルカタログと呼びます）で **Add model** を選び、モデル ID を 1 つずつ入力します。例は `deepseek-v4-pro` と `gpt-6-sol`。**Fetch available models** はエンドポイントに提供モデルを問い合わせる便利機能で、公式ガイドによれば失敗や空リストのときも ID を手動で入れれば同じように動きます。QCode の OpenAI エンドポイントが一覧に出すのは GPT モデルなので、中国系の ID は手動で追加します。
5. **Create provider** を選びます。続けて Provider ID `qcode-claude`、Display name `QCode Claude`、Base URL `https://api.qcode.cc/api`、API protocol **Anthropic Messages**、同じキー、モデル `claude-sonnet-5` で同じ作業を繰り返し、もう一度 **Create provider** を選びます。
6. モデル選択を開いてモデルを選びます。選んだモデルは新しいセッションの既定にもなります。

キーは書き込み専用です。保存後にページが受け取るのはマスクされた記述だけで、キー本体は返りません。キーは `$DSH_HOME/.credentials.yaml` に保存され、設定には参照だけが残ります。

### ページが書き込む内容

参考までに、同じ 2 つの provider を `$DSH_HOME/profiles/<profile>/cordis.patch.yml` に書くと次のようになります。標準の `dsh web` 起動では `<profile>` が `web` なので、パスは `$DSH_HOME/profiles/web/cordis.patch.yml` です。この文書はページが代わりに書き出します。手動で編集するのは、フォームにない設定が必要な場合だけにしてください。

```yaml
- id: llm-pi-ai
  config:
    providers:
      qcode:
        displayName: QCode
        apiKeyEnv: QCODE_API_KEY
        api: openai-completions
        baseURL: https://api.qcode.cc/openai/v1
        models:
          - id: deepseek-v4-pro
          - id: gpt-6-sol
      qcode-claude:
        displayName: QCode Claude
        apiKeyEnv: QCODE_CLAUDE_API_KEY
        api: anthropic-messages
        baseURL: https://api.qcode.cc/api
        models:
          - id: claude-sonnet-5
```

`apiKeyEnv` は認証情報への参照です。ページは Provider ID からこの名前を作り（`qcode` → `QCODE_API_KEY`、`qcode-claude` → `QCODE_CLAUDE_API_KEY`）、入力したキーをその名前で保存します。公式の `MISSING_CREDENTIAL` のトラブルシューティングには、Models 画面で provider のキーを保存するか、参照先の環境変数を用意するよう書かれています。Cordis の設定上書きはエントリの設定全体を置き換えるため、既存の上書きを編集するときは他の provider を残してください。

## 疎通確認

1. 追加したモデルをモデル選択で選び、`ping` のような短いメッセージを送ります。
2. [probe.qcode.cc](https://probe.qcode.cc) を開き、QCode キーを入力して、そのモデルでリクエストが表示されることを確認します。
3. dsh を使わずにキーとパスを確認する場合：

```bash
KEY="cr_your_key"

# OpenAI Chat Completions provider
curl -sS https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"model":"deepseek-v4-pro","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'

# Anthropic Messages provider
curl -sS https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

## トラブルシューティング

| 症状 | 原因 | 対処 |
|---|---|---|
| `MISSING_CREDENTIAL` | キーが保存されていない、または参照先の環境変数が空 | **Settings → Models** でキーを保存するか、`dsh` の起動前に `apiKeyEnv` に書いた変数を export します |
| `UNKNOWN_MODEL` | 選んだモデルが provider のリストにない | 設定済みのモデルを選ぶか、モデル ID を provider に追加します |
| Fetch available models が 401 を返す | キーが違う | キーを確認します。モデル検出は OpenAI 互換の `GET /models` を呼びます |
| 取得結果が空、または失敗 | エンドポイントの一覧が検出機能の読めない形式 | モデル ID を手動で入力します |
| `model_not_available_on_endpoint` | OpenAI Chat Completions provider に `claude-…` の ID を追加した | Claude の ID は Base URL `https://api.qcode.cc/api` の Anthropic Messages provider に置きます |
| 404 | base URL 末尾の `/`、またはパス接頭辞の誤り | [エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths) と照合します |
| キーと URL が正しいのにゲートウェイが全リクエストを拒む | リクエストの形が OpenAI と違う | 公式の助言：まず該当 route に `compat.supportsDeveloperRole: false` と `compat.maxTokensField: max_tokens` を設定します |
| 推論モデルだけが失敗する | pi-ai がそれらのシステムプロンプトを `developer` ロールで送る | `compat.supportsDeveloperRole: false` を設定します |
| 手動で入れたモデルに Effort メニューが出ない | そのモデルが推論レベルを宣言していない | モデルの **Model options** で **Reasoning levels** をオンにします |

## 既知の制限

- 開発者プレビュー：設定項目や挙動はリリース間で変わる可能性があります。本ページは 2026-11-09 に npm が `latest` とする 0.2.2-rc.1 で確認しました。
- フォームには `compat` スイッチの欄がありません。公式ガイドに沿って `cordis.patch.yml` の route に設定してください。
- 手動で追加したモデルは、推論レベルを宣言するまでメニューを持たず、モデルの **Model options** で **Image** を選ぶまでテキスト専用として扱われます（公式ガイドの画像入力と推論強度の節を参照）。

## 関連ドキュメント

- [エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths) — プロトコル × モデルファミリー対応表
- [中国系モデル連携](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen の ID とパス
- [CodeWhale（DeepSeek-TUI）](/docs/ide/deepseek-tui) — 両方のプロトコルに対応する別のターミナル agent
- [ツール互換性一覧](/docs/ide/tool-compatibility) — 各ツールが対応するプロトコル
- [T3 Code](/docs/ide/t3code) — Claude Code と Codex を動かす制御面
- [qcode.cc の DeepSeek Harness ガイド](https://qcode.cc/ja/deepseek-harness-guide) — 背景とユースケース