ZCode は初回起動時に内蔵プロバイダーが選択された状態で立ち上がります。そのままでも会話はできますが、手元にあるのが複数モデルをまとめて叩けるゲートウェイのキーだと、内蔵カードでは接続できません。住所・プロトコル・モデル一覧がカード側で固定されているためです。
この記事は、カスタムプロバイダーを作って自前のキーで動かすまでの手順を、実際に画面を操作した順番でまとめたものです。入力する項目は4つだけで、残りはUI操作です。
環境
| 項目 | 値 |
|---|---|
| OS | Windows 11 |
| クライアント | ZCode デスクトップ版（2026年10月時点のUI） |
| 使用モデル | glm-5.3 |
| 入力する項目 | Base URL / API 形式 / API キー / モデル ID |
ZCode のデスクトップ版は公式サイト（https://zcode.z.ai/）から Windows・macOS・Linux 向けに配布されています。本記事の画面はすべて Windows 版です。
前提：入力する4項目の意味
カスタムプロバイダーのフォームは6項目ありますが、実質的に効くのは次の4つです。
- Base URL：ゲートウェイのルートアドレス。ドメインまでで止める。
-
API 形式：
/v1/messagesを含む項目を選ぶ。 - API キー：コンソールで発行したトークン。ログインパスワードではない。
- モデル一覧：モデル ID をコピーして追加する。
名前と有効化スイッチは表示と ON/OFF のためだけの項目です。
手順1：インストールと最初の2画面
インストーラーを実行し、スタートメニューから起動します。初回は2画面続きます。
1画面目は「主要な作業方向」を12個の選択肢から選ぶものですが、クライアントの提案の出し方が変わるだけで、外部プロバイダーの接続可否には影響しません。左下の「跳过」（スキップ）で進めます。
2画面目はアカウント接続で、プロバイダーのドロップダウンは内蔵サービスを指し、下に API キー入力欄があります。ここに入れるのは内蔵サービスのキーなので、今回は使いません。下部の「暂时跳过」（後で）で閉じます。
どちらも設定ではなくオンボーディングです。あとから同じ設定画面でプロバイダーを追加できるので、戻って埋め直す必要はありません。
手順2：API キーを発行する
コンソールにログインし、トークン管理の画面で新規作成します。名前は zcode など識別しやすいもので構いません。作成直後に一度だけ全文が表示される実装が多いので、その場でコピーします。
権限・残高・有効期限はコンソール側の情報です。クライアントはキーを要求に載せるだけなので、使う予定のモデルに対して権限があるかを先に確認しておきます。今回の例では Crazyrouter のコンソールを使用しました。課金は従量制で、チャージやキャンペーンの内容はコンソールの表示が基準です。
手順3：カスタムプロバイダーを作る
設定を開くと、左側が「基本設定」と「Agent 機能」の2グループに分かれています。基本設定の下に「常规」「外观」「模型设置（モデル設定）」「浏览器控制」などが並ぶので、模型设置 を選びます。
右上の「新增供应商」（プロバイダーを追加）を押すとパネルが開き、上半分が内蔵カード、下半分の「其他」に一般的なベンダーが並びます。その先頭が「创建自定义供应商」です。
内蔵カードとの違いは、接続パラメーターを誰が持つかだけです。カードは住所とプロトコルが固定、カスタムは両方を自分で入力します。ゲートウェイや自前のエンドポイントはこちらを使います。一度作ったプロバイダーは左側に残るので、名前をクリックすれば編集できます。
手順4：フォームに4項目を入れる
フォームは「名称」「有効化スイッチ」「Base URL」「API 形式」「API キー」「モデル一覧」の6項目です。
名称 は既定の「新供应商」のままだと一覧で見分けにくいので、「团队网关」のような名前に変えておきます。
Base URL はドメインまでです。今回の値は次のとおりです。
https://api.crazyrouter.com
末尾に /v1 や /messages を足してはいけません。アドレスとプロトコルは別項目で、パスは下の形式選択が決めます。自分でパスを足すと 404 になりやすい典型的なパターンです。
API 形式 は /v1/messages を含む項目を選びます。この1項目がリクエストのパスとレスポンスの解釈方法の両方を決めるため、ゲートウェイが実際に開いているプロトコルと一致させる必要があります。間違えると 400 か 404 になり、認証エラーにはなりません。また /v1/messages と /v1/chat/completions は別のペイロード形式で、住所が正しくても形式が違えば通りません。
API キー は手順2でコピーしたトークンです。入力欄右の目のアイコンで確認し、前後に空白が入っていたり末尾が欠けていると 401 になります。キーはローカル設定に保存されるので、チャット欄やスクリーンショットに貼らないようにします。
モデル一覧 は「+ 新增模型」を押して ID を入れます。最初は1つで十分です。行ごとにスイッチと削除ボタンがあり、OFF にしたモデルは会話の選択肢に出てきません。
入力後、パネル上部の有効化スイッチが ON になっていることを確認します。保存せずに閉じると入力は消えます。
手順5：モデルを追加して会話で確認する
モデル ID は手入力せず、コンソールのモデル一覧からコピーします。検索欄に glm と入れると絞り込まれ、スクリーンショットでは170件中の10件が表示されています。各カード右上の「Details」の隣にあるアイコンで ID をコピーし、フォームに貼り付けます。大文字小文字は変えません。
同じプロバイダーに複数のモデルをぶら下げられます。住所とキーは共通で、違うのは ID だけです。住所とキーがゲートウェイを決め、ID がその中のモデルを決める、という分担なので、モデルを増やしても認証情報を入れ直す必要はありません。
保存したら新しい会話を開き、モデル選択でプロバイダーのグループを選んでからモデルを選びます。短い指示を送り、返答があれば接続できています。入力欄の右下に現在のモデル名が表示され、その隣の文字が思考強度の段階です。
ここで一度つまずきやすいのが、設定は終わっているのに会話が古いプロバイダーのままというケースです。すでに開いている会話は新しいプロバイダーに自動で切り替わりません。会話下部のモデル選択でグループを切り替える必要があります。
モデルの選び方
glm 系は名前が規則的です。バージョン番号のあとに接尾辞が付き、flash は低コスト、flashx はその高速版、v は視覚、ocr は文書解析、legal は法務向けです。
| モデル | 位置づけ | コンテキスト / 出力 | 用途 |
|---|---|---|---|
| glm-5.3 | フラッグシップ | 1M / 128K | プロジェクト全体の改修、長いデバッグ |
| glm-5.3-flash | マルチモーダル・低コスト | 1M / 128K | 画面を見ながらのコーディング、資料作成 |
| glm-5.3-flashx | flash の高速版（約200 tokens/s） | 1M / 128K | 小さなタスクの一括処理 |
| glm-5.3-flashx-legal | 法務向け | 1M / 128K | 契約書レビュー、条文検索 |
| glm-5.2 | 前世代のフラッグシップ | 1M / 128K | 既存フローを変えたくない場合 |
| glm-ocr | 軽量な文書解析 | 画像10MB / PDF 50MB、最大100ページ | スキャン、領収書、複雑なレイアウト |
| glm-5v-turbo | 初期のマルチモーダル | カードの記載による | 画像だけ読ませたい場合 |
glm-5.1、glm-5、glm-5-turbo、glm-3-turbo は旧世代です。既存の処理が依存していなければ 5.3 系から選ぶのが無難です。なお glm-5.3 は常に思考が有効で、low・high・max の3段階があります。簡単な質問は low、重い改修は max が向いています。
ハマりどころ
-
アドレスにパスを足す：
/v1や/messagesを書くと 404。パスは形式選択が持つ。 - 形式の取り違え：400 か 404 になり、認証エラーに見えない。住所ではなく形式を疑う。
- キーの前後の空白：401 になり、キーが違う場合と区別がつかない。
- 保存漏れ：フォームを閉じる前に保存しないと、プロバイダー自体が作られない。
- グループ未切り替え：設定が正しくても、開いている会話は古いプロバイダーのまま。
まとめ
必要な入力は Base URL・API 形式・API キー・モデル ID の4つで、住所はドメインまで、形式は /v1/messages、キーはコンソールのトークン、ID はコピー。この4点を押さえれば、あとは会話側でグループを切り替えるだけで動きます。
設定と会話が別物であること、そして切り替えてもエラーが出ないことが、この手順で唯一分かりにくい部分です。エラーの有無ではなく、入力欄右下のモデル名で判断するのが確実です。