ZCode AI カスタム API セットアップ

ZCode は、Anthropic または OpenAI プロトコルを実装するサービスをカスタム プロバイダーとして追加できます。このガイドは、ZCode の公式 Connect Models → Custom Providers (Anthropic / OpenAI Compatible) フローの実際の順序に従い、https://us-api.tokenhub.com/v1 で OpenAI-compatible プロバイダーとして TokenHub を構成します。

モデル設定を開く

初回起動時、使用可能なモデルがない場合は、Use API Key を選択します。 ZCode がすでに開いている場合は、プロンプト ボックスでモデル名をクリックし、Manage Models を選択して、Settings → Model Settings を開きます。

TokenHub カスタム プロバイダーを追加します。

ZCode のカスタム プロバイダー フローの 7 つのステップに従います。

1. Settings → Model Settings を開きます。
2. プロバイダー リストの下部にある Add Provider をクリックします。
3. プロバイダーに TokenHub という名前を付けます。
4. OpenAI-compatible を選択します。 [ベース URL] メニューで、カスタム アドレスを選択するか、手動で https://us-api.tokenhub.com/v1 を入力します。
5. API Key に TokenHub API キーを入力します。
6. [Add Model] をクリックし、TokenHub モデル カタログから正確なモデル ID を入力します。追加モデルを個別に追加します。
7. 設定を保存し、プロバイダーの Enable スイッチをオンにします。使用するすべてのモデルも有効になっていることを確認してください。

ZCode は、サードパーティのモデル ID を推測しません。プロバイダーがモデル リストを返さない場合は、Add Model を使用して正確な ID を手動で追加します。

1 つのプロバイダー内で Anthropic プロトコル設定と OpenAI プロトコル設定を混在させないでください。 Anthropic Messages 用の別のプロバイダーを作成し、そのプロトコルで必要なルート URL を使用します。

1 つのモデルの詳細設定を構成する

Settings → Model Providers で、追加したモデルを開き、Advanced を展開します。

• Max output tokens: は通常、これを空のままにして、モデル サービスにサポートされている値を報告させます。対象機種の制限を確認の上、手動で設定してください。
• Context window: これはカスタム プロバイダー モデルで編集可能で、保存された値は新しい会話にのみ適用されます。別のモデルの値ではなく、TokenHub モデル仕様を使用してください。
• Thinking effort: 表示レベルはモデルとプロトコルによって異なります。 OpenAI-compatible リクエストは reasoning_effort を使用します。サードパーティの展開では、ZCode で示される一部のレベルが拒否される場合があります。 400 パラメータ エラーの後は、レベルを下げるか、オプションを無効にしてください。
• Custom request parameters: ZCode は、ローカル プロバイダー options に手動で追加された任意の値をリクエスト本文に自動的に挿入しません。追加の推論やイメージ パラメーターを追加するために、~/.zcode/v2/config.json の編集に依存しないでください。

ZCode が画像入力が利用可能かどうかを決定する方法

ZCode は、イメージを処理する際のプロバイダー、モデル ID、モデル カタログ機能、アクティブ プロトコルを組み合わせます。

• サポートが判明すると、ZCode はイメージを保持し、モデル サービスに送信します。
• モデルがサポートされていないとマークされている場合、ZCode は画像を削除し、テキスト通知に置き換えます。
• 能力が不明な場合、ZCode は事前に画像をブロックしません。 TokenHub が最終決定を行い、リクエストを拒否する場合があります。

同じモデルでも、別のプロバイダーまたはプロトコルを通じて異なる方法で処理することができます。最初にテキストをテストし、TokenHub モデル ページに画像入力が明示的にリストされている場合にのみ画像を送信します。

モデルを選択して確認してください

1. プロンプト ボックスのモデル セレクターに戻ります。
2. TokenHub プロバイダーと追加したモデルを選択します。
3. 「現在のファイルを変更せずに説明してください」などの短い指示を送信します。
4. TokenHub リクエスト ログで、リクエストが /v1/chat/completions を使用していることを確認し、モデル ID、ステータス コード、および使用法を確認します。
5. テキスト応答が安定したら、編集、ツール呼び出し、長いコンテキスト、画像入力を個別にテストします。

これは、ZCode の公式 Verify The Setup ガイダンスに従います。新しいチャネルを選択し、短いテスト命令を送信し、実際の作業の前に安定した応答を確認します。

ZCode の組み込み HTTP プロキシのスコープ

ZCode Settings で構成された HTTP プロキシは、モデル API、MCP、WebFetch、ターミナルの子プロセス、拡張機能マーケットプレイス、およびアプリ内ページの読み込みをカバーします。デスクトップ アカウントのサインイン、Wiki の生成、Web リモート コントロール WebSocket、または SSH リモート接続についてはカバーされていません。また、ZCode は、デフォルトではシステム HTTP_PROXY / HTTPS_PROXY 変数を介してすべてのリクエストをルーティングしません。アプリ内プロキシを変更した後、ZCode を再起動します。

トラブルシューティング

• モデルがありません: プロバイダーとモデルの両方が有効になっていることを確認してください。
• 404: エンドポイントが /chat/completions を繰り返さないことを確認します。
• リクエスト形式の不一致: プロバイダーが OpenAI-compatible か Anthropic かを確認してください。
• テキストは機能しますが、コード編集は機能しません。選択したモデルには信頼できるネイティブ ツール呼び出しがない可能性があります。
• 思考努力は 400 を返します。デプロイメントが受け入れない可能性があるため、レベルを下げるか無効にします。
• イメージ要求が失敗する: 正規モデル ID を使用し、プロバイダー、プロトコル、および TokenHub モデルがすべてイメージをサポートしていることを確認します。
• プロキシの変更は効果がありません。ZCode を再起動し、トラフィック タイプが ZCode の組み込みプロキシによってカバーされていることを確認します。

公式リファレンス

• ZCode: モデルの接続