# CodeBuddy カスタムモデル

> **最終確認**：2026-11-10 · 📄 公式ドキュメント準拠（CodeBuddy IDE 4.12.4、2026-11-06 リリース。CLI は v2.182.0 のドキュメント）· ✅ QCode への接続は CodeBuddy Code CLI 2.182.0 で実機確認（2026-11-10）

はい、CodeBuddy では自分のキーを使えます。カスタムモデルは `models.json`（ユーザーレベルは `~/.codebuddy/models.json`）に書き、公式ドキュメントには「Currently only supports OpenAI interface format API」とあります。2026-11-10 時点で CodeBuddy Code CLI 2.182.0 で確認したところ、QCode は OpenAI Chat Completions（`url` は完全なパス）と OpenAI Responses（`url` はベース）の両方で動作し、CLI は Tencent アカウントにサインインしなくてもこれらのモデルを使えました。IDE の手順は公式ドキュメントに基づきます。

## 概要

| 項目 | 内容 |
|---|---|
| 自分のキーを使えるか | はい。IDE と CLI はどちらも `models.json` を読み込みます。CLI はサインインなしで使えます（✅ 実機確認） |
| 使えるモデル | Claude ❌（このプロトコルは Anthropic エンドポイントではありません） · GPT ✅ · 中国系モデル ✅ · Gemini ❌（QCode は現在 Gemini を提供していません） |
| Chat Completions | `url`：`https://api.qcode.cc/openai/v1/chat/completions`（完全なパス）· ✅ CLI で確認済み |
| Responses（CLI） | `"api": "openai-responses"`、`url`：`https://api.qcode.cc/openai/v1` · ✅ CLI で確認済み |
| 環境変数（CLI） | `CODEBUDDY_BASE_URL=https://api.qcode.cc/openai/v1`（OpenAI Chat）· ✅ CLI で確認済み |
| 設定ファイル | ユーザーレベル `~/.codebuddy/models.json`、プロジェクトレベル `<project-root>/.codebuddy/models.json` |
| 公式ドキュメント | [IDE の models.json](https://www.codebuddy.ai/docs/ide/Features/models) · [CLI の models.json](https://www.codebuddy.ai/docs/cli/models) · [CLI の環境変数](https://www.codebuddy.ai/docs/cli/env-vars) |

CodeBuddy は Tencent Cloud の AI コーディングツールです。VS Code と JetBrains の IDE 向けプラグイン、単体の CodeBuddy IDE、コマンド `codebuddy` で動くコマンドラインツール CodeBuddy Code の 3 つの形態があります。サイトは [codebuddy.cn](https://www.codebuddy.cn)（中国本土）と [codebuddy.ai](https://www.codebuddy.ai)（インターナショナル）で、カスタムモデルのファイルパスはどちらのドキュメントでも同じです。同じチームのオフィスエージェント WorkBuddy は基盤を共有しています。設定は [WorkBuddy のカスタムモデル](/docs/ide/workbuddy) を参照してください。

QCode.cc は Tencent や CodeBuddy とは提携関係にありません。UI と項目はお使いのビルドに従います。

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

| 入口 | プロトコル | QCode の値 | モデル |
|---|---|---|---|
| `models.json`（IDE と CLI） | OpenAI Chat Completions | `url`：`https://api.qcode.cc/openai/v1/chat/completions` | GPT、DeepSeek / GLM / Kimi / Qwen |
| `"api": "openai-responses"` を付けた `models.json`（CLI） | OpenAI Responses | `url`：`https://api.qcode.cc/openai/v1` | GPT |
| `CODEBUDDY_BASE_URL`（CLI） | OpenAI Chat Completions | `https://api.qcode.cc/openai/v1` | GPT、DeepSeek / GLM / Kimi / Qwen |

これらのプロトコルでは、QCode の GPT と中国系モデルを使えます。Claude モデルは Anthropic エンドポイントで提供され、CodeBuddy のカスタムモデルはこのプロトコルを使いません。Claude が必要な場合は、[Claude Code](/docs/getting-started/installation)、[ZCode](/docs/ide/zcode)、[Qoder](/docs/ide/qoder) など Anthropic エンドポイントに対応したツールを使ってください。3 つのプロトコルの比較は [エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths) にあります。中国本土からは `api.qcode.cc` の代わりに `asia.qcode.cc` も使えます。パスは変わらず、同じキーで動作します。

## CodeBuddy Code CLI のインストール

公式のインストールガイドに記載されている方法です（前提条件：Node.js 18.20 以上）。2026-11-10 の確認でもこの方法を使いました。

```bash
npm install -g @tencent-ai/codebuddy-code
```

Node.js がない場合、ガイドは Homebrew とネイティブバイナリ（Beta）も案内しています。

```bash
curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash
```

Windows PowerShell では `irm https://www.codebuddy.cn/cli/install.ps1 | iex` を使います。インストールは `codebuddy --version` で確認してください（確認時のバージョンは 2.182.0）。以下のカスタムモデルは Tencent アカウントにサインインしなくても使えます。IDE やプラグインは [codebuddy.ai](https://www.codebuddy.ai) からダウンロードしてください。IDE だけを使う場合、このセクションは飛ばしてかまいません。

## models.json の設定

### ファイルの場所

ドキュメントには 2 つのレベルが記載されています。

- ユーザーレベル：`~/.codebuddy/models.json`。グローバルで、すべてのプロジェクトに適用
- プロジェクトレベル：`<project-root>/.codebuddy/models.json`。ユーザーレベルより優先

マージの優先順位は、プロジェクトレベル、ユーザーレベル、組み込みの既定値の順です。同じ `id` のモデルは上書きされ、異なる `id` のモデルは追加されます。IDE と CLI は同じパスを読み込みます。

### CLI：最小構成の models.json（✅ 実機確認）

次の内容を `~/.codebuddy/models.json` として保存します。1 つ目のエントリは Chat Completions、2 つ目は Responses を使い、キーは環境変数から読み込みます。

```json
{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    },
    {
      "id": "gpt-6.1-terra",
      "name": "QCode GPT-6.1 Terra",
      "vendor": "QCode",
      "api": "openai-responses",
      "url": "https://api.qcode.cc/openai/v1",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ],
  "availableModels": ["deepseek-v4-flash", "gpt-6.1-terra"]
}
```

続いてキーをエクスポートし、それぞれのモデルに 1 行のテストを送ります。

```bash
export QCODE_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash
codebuddy -p "Reply with exactly: OK" --model gpt-6.1-terra
```

`OK` と返ればそのモデルは動作しています。`id` はモデル名として QCode に送られるため、[qcode.cc/models](https://qcode.cc/models) に掲載中の id を一字一句そのまま指定してください。Chat のエントリには `gpt-6.1-sol`、`deepseek-v4-pro`、`glm-5.3`、`kimi-k3`、`qwen3.8-max` も使えます（[中国系モデル](/docs/usage/cn-models) を参照）。Responses のエントリには GPT の id を使います。モデルごとの料金は https://qcode.cc/models にあります。`maxInputTokens`、`maxOutputTokens`、画像や推論のフラグは、選んだモデルが実際に対応する内容に合わせてください。

### `url` の 2 つのルール

Chat Completions（既定）について、公式の表現は「url field must be the complete interface path, typically ending with /chat/completions」で、次の誤った例が挙げられています。

```text
❌ https://api.openai.com/v1
❌ https://api.myservice.com
❌ http://localhost:11434
```

`api` を `openai-responses` にするとルールが逆になります。公式の表現：「With api set to openai-responses, the model uses the OpenAI Responses API: requests go to {url}/responses」、「url takes the base URL; a trailing /responses is optional.」

| `url` の値 | 結果 |
|---|---|
| `https://api.qcode.cc/openai/v1/chat/completions` | ✅ Chat Completions（確認済み） |
| `https://api.qcode.cc/openai/v1` | ✅ `"api": "openai-responses"` と組み合わせた場合（確認済み）。Chat では完全なパスになりません |
| `https://api.qcode.cc/api` | ❌ Anthropic Messages の接頭辞で、OpenAI のパスではありません |

Responses では `https://api.qcode.cc/openai` でも確認が通りました。このページでは 2 つのエントリでベースをそろえるため `/openai/v1` を使います。ドキュメントには、モデルのエントリに明示的に書いた `api` だけがプロトコルを切り替えるともあります。

### CodeBuddy IDE（📄 公式ドキュメント準拠）

IDE のドキュメントには、同じファイルパスと Chat 用の項目が記載されています。IDE のページは `apiKey` を「actual key value, not environment variable name」と説明しているので、キーそのものを書きます。IDE 用の Chat エントリ：

```json
{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "cr_xxx",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ]
}
```

IDE の項目一覧には `api` がないため、Responses のエントリは CLI 用です。IDE と CLI で同じ `~/.codebuddy/models.json` を使う場合は、すべてのエントリにキーそのものを書いてください。CLI も直接書かれたキーを受け付けます。公式のアドバイス：実際のキーを含む `models.json` をバージョン管理にコミットせず、ファイルのパーミッションを 600（所有者のみ読み書き可）にしてください。

### フィールド一覧

| フィールド | 型 | 説明（公式の表現） |
|---|---|---|
| `id` | string | 必須。モデルの一意識別子 |
| `name` | string | モデルの表示名 |
| `vendor` | string | モデルのベンダー（例：OpenAI、Google） |
| `apiKey` | string | API キー。IDE のページには「actual key value, not environment variable name」、CLI のページには「supports environment variable references」とあります |
| `maxInputTokens` | number | 最大入力トークン数 |
| `maxOutputTokens` | number | 最大出力トークン数 |
| `url` | string | API エンドポイント URL（完全なインターフェースパスであること。通常は /chat/completions で終わる） |
| `supportsToolCall` | boolean | ツール呼び出しに対応しているか |
| `supportsImages` | boolean | 画像入力に対応しているか |
| `supportsReasoning` | boolean | 推論モードに対応しているか |

CLI のページには 3 つのフィールドが追加されています：`api`（リクエストプロトコル。`openai-responses` で Responses API に切り替え）、`temperature`（サンプリング温度、0-2）、`relatedModels`（lite や推論などの場面で使うモデル id）。トップレベルの `availableModels` は文字列の配列で、ここに列挙した id だけがドロップダウンに表示されます。空または未指定ならすべてのモデルが表示されます。

### `${VAR_NAME}` で環境変数を参照する（CLI）

CLI のページには、`apiKey` と `url` の各フィールドが参照構文 `${VAR_NAME}` に対応しているとあります。上の設定の `apiKey` の参照は確認で動作しました。公式の注記：環境変数は CLI の起動時に解決されます。環境変数が存在しない場合は元のプレースホルダーがそのまま残り、API 呼び出しが失敗します。

### ホットリロード

ドキュメントによると、設定ファイルはホットリロードに対応しています。上の 2 つの `models.json` のどちらも、変更は 1 秒のデバウンスで自動的に検出されます。

## CLI の環境変数

公式の環境変数ページには、サードパーティのモデルに関わる 3 つの変数があります。

| 変数 | 公式の説明 |
|---|---|
| `CODEBUDDY_API_KEY` | API キー。モデルの API 呼び出しに使うキーを設定します。非対話モード（-p）では常にこのキーを使います |
| `CODEBUDDY_BASE_URL` | API エンドポイントのアドレスを上書きします。通常は `CODEBUDDY_API_KEY` と組み合わせて使います |
| `CODEBUDDY_MODEL` | 既定のエージェントモデルを上書きします |

2026-11-10 時点で CodeBuddy Code CLI 2.182.0 で確認したところ、`CODEBUDDY_BASE_URL` には OpenAI Chat Completions のベースを指定し、CLI がその後ろに `/chat/completions` を付けます。`https://api.qcode.cc/openai/v1` を設定し、GPT か中国系モデルを選んでください。このルートでは `models.json` は不要です。

```bash
export CODEBUDDY_BASE_URL="https://api.qcode.cc/openai/v1"
export CODEBUDDY_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash
```

`CODEBUDDY_BASE_URL` は `/openai/v1` までにしてください。`https://api.qcode.cc/api` にするとリクエストは `/api/chat/completions` に送られ、QCode は HTTP 400 を返します。

## 動作確認

まず、お使いのネットワークから QCode の OpenAI パスに届くことを確認します（[エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths) と同じ確認です）。

```bash
KEY="cr_xxx"

curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY"
# 400 = path and key both work (empty body is expected)
# 401 = bad key; 404 = wrong path prefix
```

次に：

1. CLI：上の `codebuddy -p` のテストを実行し、`OK` が返れば成功です。対話的に使うには `codebuddy --model deepseek-v4-flash` を起動します。
2. IDE：モデルのドロップダウンを開きます。ドキュメントによると、`models.json` で追加したモデルには自動的に `custom` タグが付き、見つけたり絞り込んだりしやすくなります。新しいモデルに短いメッセージを送ってください。
3. [probe.qcode.cc](https://probe.qcode.cc) にキーを入力すると、リクエストと応答したモデルを確認できます。

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

### 設定が反映されない

公式のチェックリスト：JSON の形式が正しいか確認する、ファイルパスを確認する、ログで設定が読み込まれたか確認する、環境変数の API キーが設定されているか確認する。ホットリロードには 1 秒のデバウンスがあるので、ファイルが実際にディスクに保存されていることを確かめてください。

### ドロップダウンにモデルが表示されない

ドキュメントによると、モデル ID が `availableModels` に列挙されているか、`models` の設定が正しいかを確認します。プロジェクトレベルの `availableModels` はユーザーレベルのものを完全に上書きし、マージされません。公式のトラブルシューティングは必須フィールドとして「id, name, provider」を挙げ、フィールド一覧では `id` だけを必須とし、項目名を `vendor` としています。`id`、`name`、`vendor` をすべて入力すれば、どちらの記載も満たせます。

### HTTP 404

Chat のエントリの `url` が `/chat/completions` まで届いていないか、`https://api.qcode.cc/api` になっています。Chat のエントリには常に完全なパス `https://api.qcode.cc/openai/v1/chat/completions` を使い、`"api": "openai-responses"` を付けたエントリだけを `/openai/v1` で止めます。

### HTTP 400 `model_not_available_on_endpoint`

`claude-…` の id が OpenAI のパスに送られています。たとえば `models.json` のエントリに書いた場合や、`CODEBUDDY_BASE_URL` を `https://api.qcode.cc/api` にした場合です。Claude モデルは Anthropic エンドポイントでのみ提供されるので、ここでは GPT か中国系モデルを使うか、[Claude Code](/docs/getting-started/installation) などのツールに切り替えてください。このエラーはキーの問題ではありません。

### HTTP 401

キーは `cr_` で始まり、空白を含まないものにしてください。環境変数の参照を使う場合は、変数が実際にエクスポートされているか確認します。ドキュメントによると、存在しない変数は元のプレースホルダーのまま残るため、`${QCODE_API_KEY}` という文字列がそのままキーとして送られます。

### Tencent アカウントへのサインインは必要か

これらのモデルには不要です。2.182.0 での確認では、`codebuddy -p` は `models.json` 経由でも `CODEBUDDY_BASE_URL` 経由でも、サインインなしで応答しました。

### カスタムモデルは Tencent のプラットフォーム識別ヘッダーを送るか

公式の CLI v2.180.0 リリースノートには、カスタムモデルはプラットフォーム識別のリクエストヘッダーを付けなくなったとあります。カスタムモデルがサードパーティのエンドポイントに直接接続する場合、識別情報は設定したサービスに送られません。

## 関連ドキュメント

- [WorkBuddy カスタムモデル設定](/docs/ide/workbuddy) — 同じチームのオフィスエージェント。こちらも OpenAI Chat Completions を使います
- [ZCode カスタムモデル設定](/docs/ide/zcode) — Anthropic と OpenAI のプロトコルに対応したカスタムプロバイダー。Claude も使えます
- [エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths) — 3 つのプロトコル、3 つのドメイン、`BASE_URL` の対応表
- [中国系モデルの接続](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen のモデル id
- [ツール互換性一覧](/docs/ide/tool-compatibility) — ツールごとのプロトコルと Claude の可否
- 掲載中の id と料金：[qcode.cc/models](https://qcode.cc/models)