ZCode カスタムモデル設定

ZCode をカスタムプロバイダーで QCode.cc に接続します。デスクトップ版は公式ドキュメント準拠、ZCode CLI 0.17.1 は 3 プロトコルで実機確認済み。

API キーが必要ですか？ 登録する →·エンドポイントと Base URL →

最終確認：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 へのサインインも不要でした。デスクトップ版の手順は公式ドキュメントに基づきます。

概要¶

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

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

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

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 からダウンロードしてください。

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

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

1. ZCode を開き、チャット欄のモデル名をクリックして、リスト下部の Manage Models をクリックします。Settings -> Model Settings が開きます。使えるモデルがない状態で初めて起動した場合は、ウェルカム画面の Use API Key からもモデルプロバイダーの設定に進めます。
2. 左側のプロバイダー一覧の下部にある Add Provider をクリックします。

3. 1 つ目のプロバイダー：

4. 名前：QCode Claude（名前は自由です。公式ページは claude や deepseek のような名前を例に挙げています）

5. Anthropic endpoint：https://api.qcode.cc/api（公式の表現は「Choose the vendor Base URL from the dropdown, or enter the API base URL manually」です。ここでは手入力します）
6. API Key：QCode のキー（cr_ で始まります）
7. Add Model をクリックし、モデル ID を 1 つずつ入力します。例：claude-sonnet-5-5。公式の文言は「click Add Model and enter the model IDs supported by that service」です。
8. 有効化スイッチをオンにして（「Turn on the enable switch to start using it」）保存します。
9. 名前 QCode OpenAI、OpenAI endpoint https://api.qcode.cc/openai/v1、同じキー、gpt-6.1-sol や deepseek-v4-flash などのモデルで同じ手順を繰り返します。

モデル ID は 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 はソースコードで配布されています。クイックスタートではリポジトリからビルドし、Git、Node.js 24.14.0、pnpm 10.33.2 が必要です（正確なバージョンはリポジトリの mise.toml に従います）。リポジトリのルートで次を実行します。

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 の設定です。

{
  "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 の両方）を変更します。

公式 CLI ガイドから 2 点：

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

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

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

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 を開いて QCode のキーを入力し、そのモデルでのリクエストが表示されることを確認します。
4. ZCode を介さずにキーとパスを確かめるには：

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"}]}'

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

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 パス — プロトコル × モデルファミリーの対応表
• ツール互換性一覧 — 各ツールが対応するプロトコル
• Kimi Code CLI 設定 — Anthropic、OpenAI Chat、Responses のプロバイダーを設定できるもう 1 つのターミナルエージェント
• MiniMax Code の設定 — デスクトップ版と mcode CLI。同じ 3 つの API 形式に対応
• DeepSeek Harness（dsh） — カスタムモデルのフォームを備えた別のエージェントハーネス
• 中国系モデルの接続 — GLM / Kimi / DeepSeek / Qwen の ID とパス

企業版 →