# ZCode カスタムモデル設定

> **最終確認**：2026-11-10 · 📄 公式ドキュメント準拠（ZCode デスクトップ版 v3.17.2、README と更新ログでは 2026-11-03 付）· ✅ QCode への接続は ZCode CLI 0.17.1 で実機確認（2026-11-10）

はい、ZCode では自分の API キーとエンドポイントを使えます。デスクトップ版は **Add Provider** から追加し、オープンソースの ZCode CLI は `~/.zcode/v2/provider_config.json` から読み込みます。2026-11-10 時点で ZCode CLI 0.17.1 で確認したところ、QCode の 3 つのプロトコル（Anthropic Messages、OpenAI Chat Completions、OpenAI Responses）はすべて動作し、Z.ai や BigModel へのサインインも不要でした。デスクトップ版の手順は公式ドキュメントに基づきます。

## 概要

| 項目 | 内容 |
|---|---|
| どんなツールか | README の言葉では「an AI coding workspace with desktop, browser, and terminal interfaces」。Z.ai（智譜）による Apache-2.0 のプロジェクトで、リポジトリは [zai-org/ZCode](https://github.com/zai-org/ZCode) です |
| 使えるモデル | Claude ✅ · GPT ✅ · GLM / Kimi / DeepSeek / Qwen ✅ · Gemini ❌（QCode は現在 Gemini モデルを提供していません） |
| Anthropic Messages | `https://api.qcode.cc/api`（ZCode が `/v1/messages` を付加）· ✅ CLI で確認済み |
| OpenAI Chat Completions | `https://api.qcode.cc/openai/v1` · ✅ CLI で確認済み |
| OpenAI Responses | `https://api.qcode.cc/openai/v1` · ✅ CLI で確認済み。デスクトップ版のドキュメントにはこのプロトコルの項目がありません |
| デスクトップ版 | **Manage Models** → **Settings -> Model Settings** → **Add Provider**。ファイルは `~/.zcode/v2/config.json` |
| ZCode CLI | ソースからビルド。ファイルは `~/.zcode/v2/provider_config.json`（`access.apiKey`、`api.type`、`api.baseUrl`） |
| 公式ドキュメント | [Connect Models](https://zcode.z.ai/en/docs/configuration) · [Install](https://zcode.z.ai/en/docs/install) · [FAQ](https://zcode.z.ai/en/docs/qa) · [CLI ガイド](https://github.com/zai-org/ZCode/blob/main/apps/zcode-cli/docs/usage/README.md) |

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

ZCode でモデルを使う方法は 3 つあり、利用量がどこに計上されるかが異なります。

| 方法 | 操作 | 利用量の計上先 |
|---|---|---|
| アカウントでサインイン | ウェルカム画面で Z.ai または BigModel を選ぶ | アカウントのプラン：「If your account has a GLM Coding Plan, ZCode uses the plan and quota from that account directly.」 |
| Z.ai / BigModel のプロバイダーページで API キー | ページを API Key モードに切り替えると、**OpenAI Base URL** と **Anthropic Base URL** の欄が表示されます | 入力した Z.ai または BigModel のキー |
| カスタムプロバイダー | 自分のエンドポイントとキーで **Add Provider**（デスクトップ）または `provider_config.json`（CLI） | 接続先のサービス。ここでは QCode |

このページは 3 つ目の方法を扱います。QCode では Claude は Anthropic プロトコルのみ、GPT は OpenAI プロトコルのみで提供され、GLM、Kimi、DeepSeek、Qwen は Anthropic と OpenAI Chat のどちらでも使えます（[エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths) を参照）。

| プロトコル | QCode の Base URL | モデル | CLI の `api.type` |
|---|---|---|---|
| Anthropic Messages | `https://api.qcode.cc/api` | Claude、GLM / Kimi / DeepSeek / Qwen | `anthropic-messages` |
| OpenAI Chat Completions | `https://api.qcode.cc/openai/v1` | GPT、GLM / Kimi / DeepSeek / Qwen | `openai-chat-completions` |
| OpenAI Responses | `https://api.qcode.cc/openai/v1` | GPT | `openai-responses` |

API パスは ZCode 自身が付加します。CLI のソース（`normalizeAnthropicBaseURL`）では、`/v1` で終わらない Anthropic の Base URL に `/v1` を付け、その後 SDK が `/messages` を付けるため、`https://api.qcode.cc/api` は `/api/v1/messages` に届きます。2 つの OpenAI タイプでは Base URL の後ろに `/chat/completions` または `/responses` を付けるので、どちらの値も `/openai/v1` で終わります。末尾に `/` は付けないでください。同じキーは `us.qcode.cc` と `asia.qcode.cc` でも使えます。ホスト名だけを替え、パスはそのままにしてください。

## デスクトップ版（📄 公式ドキュメント準拠）

以下の手順は v3.17.2 の公式ドキュメントに基づきます。同じ QCode のアドレスは ZCode CLI で動作を確認済みです。デスクトップ版では、最初に送るテスト指示の結果で接続を確かめてください。

### インストール

公式のインストールページには「Supports macOS (Apple Silicon / Intel), Windows (x64 / ARM64), and Linux (x64, ARM64, AppImage, DEB, RPM).」とあり、v3.17.2 が最新版と表示されています。

- macOS：ダウンロードした `ZCode.dmg` を開き、ZCode.app をアプリケーションフォルダにドラッグします。「壊れている」と表示された場合、公式の対処法は `xattr -dr com.apple.quarantine /Applications/ZCode.app` です。
- Windows：インストーラーをダウンロードしてダブルクリックし、ウィザードに従います。
- Linux：`.AppImage`、`.deb` または `.rpm` をダウンロードします。AppImage の場合は `chmod +x ZCode-*.AppImage` を実行します。

インストーラーは [zcode.z.ai](https://zcode.z.ai/en/docs/install) からダウンロードしてください。

### QCode をプロバイダーとして追加する

公式ドキュメントには、エンドポイントを 1 つだけ入力するプロバイダーの例と、両方を入力する DeepSeek の例がありますが、1 つのプロバイダーに 2 つのエンドポイントがある場合に ZCode がどちらを使うかは書かれていません。そのため、このページではプロトコルごとに 1 つのプロバイダーを作ります。

| プロバイダー名 | エンドポイント欄 | 値 | モデル ID（例） |
|---|---|---|---|
| `QCode Claude` | Anthropic endpoint | `https://api.qcode.cc/api` | `claude-sonnet-5-5`、`claude-opus-5-5`、`claude-haiku-5-5` |
| `QCode OpenAI` | OpenAI endpoint | `https://api.qcode.cc/openai/v1` | `gpt-6.1-sol`、`deepseek-v4-flash`、`glm-5.3`、`kimi-k3`、`qwen3.8-max` |

1. ZCode を開き、チャット欄のモデル名をクリックして、リスト下部の **Manage Models** をクリックします。**Settings -> Model Settings** が開きます。使えるモデルがない状態で初めて起動した場合は、ウェルカム画面の **Use API Key** からもモデルプロバイダーの設定に進めます。
2. 左側のプロバイダー一覧の下部にある **Add Provider** をクリックします。
3. 1 つ目のプロバイダー：
   - 名前：`QCode Claude`（名前は自由です。公式ページは claude や deepseek のような名前を例に挙げています）
   - Anthropic endpoint：`https://api.qcode.cc/api`（公式の表現は「Choose the vendor Base URL from the dropdown, or enter the API base URL manually」です。ここでは手入力します）
   - API Key：QCode のキー（`cr_` で始まります）
4. **Add Model** をクリックし、モデル ID を 1 つずつ入力します。例：`claude-sonnet-5-5`。公式の文言は「click Add Model and enter the model IDs supported by that service」です。
5. 有効化スイッチをオンにして（「Turn on the enable switch to start using it」）保存します。
6. 名前 `QCode OpenAI`、OpenAI endpoint `https://api.qcode.cc/openai/v1`、同じキー、`gpt-6.1-sol` や `deepseek-v4-flash` などのモデルで同じ手順を繰り返します。

モデル ID は [qcode.cc/models](https://qcode.cc/models) に掲載されているものを一字一句そのまま使ってください。モデルごとの料金も同じページにあります。中国系モデルは Anthropic エンドポイントでも使えるので、`QCode Claude` にまとめてもかまいません。デスクトップ版のドキュメントが挙げているのは Anthropic と OpenAI のエンドポイントで、Responses 用の項目はないため、Responses を使う場合は下の CLI を使ってください。

### デスクトップ版の設定ファイル

公式 FAQ では、`~/.zcode/v2/config.json` が「Model provider setup (API keys, base URLs, model lists)」を保存するファイルとされています。キーが含まれるので、秘密情報として扱い、コミットしないでください。公式ページにはこのファイルについて次のルールがあります：「a provider's options only recognizes connection settings such as apiKey, baseURL, apiKeyRequired, and headers; any other keys added by hand (e.g. reasoning_effort, vl_high_resolution_images) are silently ignored and never written into the request body.」ファイルを手で編集せず、UI でプロバイダーを設定してください。FAQ には、ターミナルの環境変数とデスクトップ版のモデル設定は別々の入口で、設定は自動では同期されないとも書かれています。

## ZCode CLI（✅ 2026-11-10 実機確認）

2026-11-10 時点で ZCode CLI 0.17.1 で確認したところ、`~/.zcode/v2/provider_config.json` を通じて QCode の 3 つのプロトコルがすべて動作しました。`zcode login` は不要です。

### ソースからビルドする

CLI はソースコードで配布されています。[クイックスタート](https://github.com/zai-org/ZCode/blob/main/apps/zcode-cli/docs/usage/01-quickstart.md)ではリポジトリからビルドし、Git、Node.js 24.14.0、pnpm 10.33.2 が必要です（正確なバージョンはリポジトリの `mise.toml` に従います）。リポジトリのルートで次を実行します。

```sh
git clone https://github.com/zai-org/ZCode.git
cd ZCode
pnpm install --frozen-lockfile
pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --version
node apps/zcode-cli/packages/cli/dist/zcode.cjs doctor --json
```

以下のコマンドの `zcode` は `node /absolute/path/to/zcode.cjs` を指します。ビルドで隣に生成されたファイルは残しておいてください。

### provider_config.json を書く

次の内容を `~/.zcode/v2/provider_config.json` として保存し、`cr_xxx` をご自分の QCode キーに置き換えます。確認に使った Anthropic の設定です。

```json
{
  "schemaVersion": 1,
  "config": {
    "providerConfigRules": {
      "providerRules": [
        {
          "providerId": "qcode",
          "providerName": "QCode",
          "config": {
            "group": "standard-personal",
            "access": { "type": "api-key", "apiKey": "cr_xxx" },
            "api": {
              "type": "anthropic-messages",
              "baseUrl": "https://api.qcode.cc/api"
            },
            "personalModelIds": ["claude-haiku-5-5"]
          }
        }
      ]
    },
    "modelConfigRules": {
      "providerModelRules": [],
      "manualProviderModelRules": []
    },
    "defaultModelSelection": {
      "providerId": "qcode",
      "modelId": "claude-haiku-5-5"
    }
  }
}
```

別のプロトコルにするには、`api.type`、`api.baseUrl`、モデル ID（`personalModelIds` と `defaultModelSelection.modelId` の両方）を変更します。

| プロトコル | `api.type` | `api.baseUrl` | 確認したモデル |
|---|---|---|---|
| Anthropic Messages | `anthropic-messages` | `https://api.qcode.cc/api` | `claude-haiku-5-5` ✅ |
| OpenAI Chat Completions | `openai-chat-completions` | `https://api.qcode.cc/openai/v1` | `deepseek-v4-flash` ✅ |
| OpenAI Responses | `openai-responses` | `https://api.qcode.cc/openai/v1` | `gpt-6.1-terra` ✅ |

公式 CLI ガイドから 2 点：

- 欄は `api.baseUrl` で、デスクトップ版のファイルの `options.baseURL` とは綴りが違います。CLI が読むのは `provider_config.json` で、`~/.zcode/v2/config.json` ではありません。
- ガイドは `apiKey` での `${ENV}` 置換を保証していないため、キーは平文でファイルに書き込まれます。ファイルの権限を絞り、Git には入れないでください。

```sh
chmod 600 ~/.zcode/v2/provider_config.json
```

### 非対話モードで確認する

```sh
zcode --prompt "Reply with one word: ready. Do not call tools." \
  --cwd /path/to/project --mode plan --json --no-color
```

`--json` は `sessionId`、`response` と実行情報を返します。`response` が `ready` ならプロバイダーは動作しています。`--mode` は必ず指定してください。指定しないと `--prompt` は `yolo` モードで動き、コマンドの実行やファイルの変更をそのまま行います。引数なしで `zcode` を実行すると対話型の TUI が起動します。

## 動作確認

1. デスクトップ版：チャット欄のモデルセレクターで新しいプロバイダーのモデルを選び、公式ページの案内どおり短いテスト指示を送ります（「send a short test instruction」）。
2. CLI：上の `--prompt` による確認を実行します。
3. [probe.qcode.cc](https://probe.qcode.cc) を開いて QCode のキーを入力し、そのモデルでのリクエストが表示されることを確認します。
4. ZCode を介さずにキーとパスを確かめるには：

```bash
KEY="cr_your_key"

# Anthropic Messages
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-haiku-5-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'

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

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

| 症状 | 原因 | 対処 |
|---|---|---|
| デスクトップ版：接続が読み込み中のまま | 公式 FAQ：マシンがモデルサービスに到達できない、またはキーに残高やモデルの権限がない | ネットワークを確認し、次にキーとモデル ID を確認します |
| `model_not_available_on_endpoint` | `claude-...` の ID を OpenAI エンドポイントまたは OpenAI 系の `api.type` に登録した | Claude の ID は Anthropic エンドポイント（CLI では `anthropic-messages`）に置きます |
| 404 | 末尾の `/`、または `/v1` のない OpenAI の Base URL | 上の値をそのまま使い、curl コマンドと比べます |
| CLI がキーやアドレスを使わない | CLI が読むのは `api.baseUrl` を持つ `provider_config.json` で、デスクトップ版の `config.json` ではない | `~/.zcode/v2/provider_config.json` を編集します |
| CLI：`ZCODE_BASE_URL` に QCode のアドレスを入れても効かない | 公式：`ZCODE_BASE_URL` は製品のサービスエンドポイントに関わるもので、モデル API 用ではない | アドレスは `api.baseUrl` に書きます |
| CLI：`apiKey` の `${QCODE_API_KEY}` が置換されない | 公式：`apiKey` での `${ENV}` 置換は保証されていない | キーそのものを書き、ファイルを `chmod 600` にします |
| CLI の初回実行で「ZCode Built-in」の更新に失敗したという通知が出る | 0.17.1 で確認。自分のプロバイダー経由の呼び出しは成功し、2 回目以降は skipped と表示される | 対処は不要です |
| 最上位の思考レベルで 400 パラメーターエラー | 公式：一部のサードパーティ環境は `xhigh` までしか受け付けないが、ZCode は DeepSeek V4 に `max` を送る | 代わりに `high` を選びます：「Picking high instead works fine.」 |
| モデルに細かい思考レベルがない | 公式：ZCode がそのモデルのレベル対応を把握していない。「the setting has not been lost」 | シンプルなオン／オフ切り替えを使います |
| デスクトップ版：`options` の `reasoning_effort` が効かない | 公式：それ以外のキーは「silently ignored」 | UI のレベル設定を使います |
| 画像が送られない | 公式の例：OpenAI Chat 互換エンドポイント経由の GLM-5.2 は「is treated as not supporting image input」。別のエンドポイントやプロトコルでは結果が変わることがある | モデル設定で画像対応を明示するか、そのモデルでは画像を使いません |

ZCode は選んだ思考レベルをエンドポイントに合わせて変換します：「OpenAI-compatible endpoints use the top-level reasoning_effort field, while Anthropic-compatible endpoints use thinking / effort.」

## 既知の制限

- デスクトップ版の部分は v3.17.2 の公式ドキュメントに基づき、メニュー名はバージョンによって変わることがあります。CLI の部分は 0.17.1 で、プロトコルごとに 1 つのモデルで確認しました。
- 公式ページによると、サードパーティモデル向けにカスタムのリクエストパラメーターを追加する機能はまだありません。
- デスクトップ版のドキュメントが挙げているのは Anthropic と OpenAI のエンドポイントです。Responses は CLI の `openai-responses` で使えます。QCode は現在 Gemini モデルを提供していません。
- CLI：キーは `provider_config.json` に平文で保存され、`--mode` なしの `--prompt` は `yolo` モードで動きます。

## 関連ドキュメント

- [エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths) — プロトコル × モデルファミリーの対応表
- [ツール互換性一覧](/docs/ide/tool-compatibility) — 各ツールが対応するプロトコル
- [Kimi Code CLI 設定](/docs/ide/kimi-code) — Anthropic、OpenAI Chat、Responses のプロバイダーを設定できるもう 1 つのターミナルエージェント
- [MiniMax Code の設定](/docs/ide/minimax-code) — デスクトップ版と `mcode` CLI。同じ 3 つの API 形式に対応
- [DeepSeek Harness（dsh）](/docs/ide/deepseek-harness) — カスタムモデルのフォームを備えた別のエージェントハーネス
- [中国系モデルの接続](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen の ID とパス