# MiniMax Code の設定

> **最終確認**：2026-11-10 · 📄 公式ドキュメント準拠（デスクトップ版 BYOK ページ 2026-09-16 更新、mcode CLI ドキュメント、npm `@minimax-ai/code` 0.7.6）· ✅ QCode 接続は mcode 0.7.6 で実測（2026-11-10）

MiniMax Code で自分の API キーは使えますか？ 使えます。2026-11-10 時点の公式 BYOK（"bring your own key"）ページによると、デスクトップアプリでは **Settings → Usage & model** からカスタムモデルのプロバイダーを追加でき、`mcode` CLI では `mcode provider add` で同じことができます。どちらも `anthropic-messages`、`openai-completions`、`openai-responses` の 3 つの API 形式に対応しており、QCode は 3 つすべてを提供しているので、QCode のキー 1 本で Claude・GPT・中国系モデルを同じツールの中で使えます。2026-11-10 に mcode 0.7.6 で実測したところ、MiniMax にログインしないまま `mcode provider add … --use` のあと `mcode exec` を実行し、3 形式とも応答が返りました。

## 概要

| 項目 | 内容 |
|---|---|
| どんなツールか | MiniMax Code は macOS / Windows 向けのデスクトップ AI Agent アプリで、`mcode` はそのターミナル版 CLI です（対話型 TUI、`mcode exec` のヘッドレスモード、`mcode acp`）。CLI のソースは MIT ライセンスで GitHub に公開されており、リポジトリにはデスクトップアプリのソースは含まれないと明記されています |
| 使えるモデル | Claude ✅（`anthropic-messages`）· GPT ✅（`openai-completions` または `openai-responses`）· GLM / Kimi / DeepSeek / Qwen ✅（`anthropic-messages` または `openai-completions`）· Gemini ❌（QCode は Gemini 系列を提供していません。Claude、GPT または中国系モデルをお使いください） |
| 形式ごとの Base URL | `anthropic-messages`：`https://api.qcode.cc/api` · `openai-completions`：`https://api.qcode.cc/openai/v1` · `openai-responses`：`https://api.qcode.cc/openai/v1` · 3 つとも mcode 0.7.6 で実測済み ✅（2026-11-10） |
| 設定する場所 | CLI：`mcode provider add`。`~/.minimax/config.yaml`（既定のデータディレクトリ）の `custom_provider` に保存されます。デスクトップ：**Settings → Usage & model** → Custom model → Add model |
| API キー | QCode のキー `cr_xxx`。CLI はプロバイダーを追加する時点で、`MCODE_PROVIDER_API_KEY`（または `--api-key-env` で指定した変数）からキーを読み取ります |
| MiniMax へのログイン | 自分のキーを使うだけなら不要です。`mcode login` は MiniMax 自身のモデルを使うときだけ必要です |
| 公式ドキュメント | [Custom Models / BYOK](https://code.minimax.io/docs/code/account/byok) · [Configure BYOK Models with an Agent](https://code.minimax.io/docs/code/account/byok-agent-setup) · [CLI configuration](https://code.minimax.io/docs/cli/configuration) · [CLI quick start](https://code.minimax.io/docs/cli/quick-start) · [GitHub: MiniMax-AI/minimax-code](https://github.com/MiniMax-AI/minimax-code) |

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

選んだ `API format` によって、MiniMax Code が呼び出す QCode のエンドポイントが決まります。公式の設定ガイドには、Base URL からリクエスト先がどう組み立てられるかを示す表があります。

| API 形式 | 公式の表の Base URL 例 | リクエスト先 | QCode で入力する値 |
|---|---|---|---|
| `anthropic-messages` | `https://example.invalid`、またはプロバイダー指定の互換プレフィックス | `<normalized base>/v1/messages` | `https://api.qcode.cc/api` |
| `openai-completions` | `https://example.invalid/v1` | `<base>/chat/completions` | `https://api.qcode.cc/openai/v1` |
| `openai-responses` | `https://example.invalid/v1` | `<base>/responses` | `https://api.qcode.cc/openai/v1` |

ガイドの原文は次のとおりです。"OpenAI-style endpoints do not automatically acquire `/v1`; include it when required. Messages normalizes trailing `/v1`, `/messages`, or `/v1/messages`. Do not append these repeatedly or remove a gateway prefix such as `/proxy/anthropic`." つまり OpenAI 形式では /v1 は自動で補われないので必要なら自分で付け、Messages 形式では末尾の /v1 などは正規化されるので重ねて付けない、ということです。QCode に当てはめると次のようになります。

- **`anthropic-messages`**：QCode の Anthropic エンドポイントはプレフィックス `/api` で、`/v1/messages` は MiniMax Code が自動で付けます。リクエストは `https://api.qcode.cc/api/v1/messages` に届きます。`/api` は残し、`/v1/messages` は自分で書き足さないでください。
- **`openai-completions`**：ツールが付けるのは `/chat/completions` だけなので、Base URL には `/v1` まで含めます。`https://api.qcode.cc/openai/v1` は `https://api.qcode.cc/openai/v1/chat/completions` になります。
- **`openai-responses`**：同じ考え方で、Base URL に `/v1` まで含め、ツールが `/responses` を付けます。`https://api.qcode.cc/openai/v1` は `https://api.qcode.cc/openai/v1/responses` になり、これは[エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths)に載っている Responses のパスです。

右端の列の 3 つの値は、2026-11-10 に mcode 0.7.6 で形式ごとに 1 モデルずつ（`claude-haiku-5-5`、`deepseek-v4-flash`、`gpt-6.1-terra`）実測し、すべて通っています。

モデルと形式の組み合わせ：

| モデル | `anthropic-messages` | `openai-completions` | `openai-responses` |
|---|:--:|:--:|:--:|
| Claude（`claude-opus-5-5`、`claude-sonnet-5-5`、`claude-haiku-5-5`） | ✅ | ❌ | ❌ |
| GPT（`gpt-6.1-sol`、`gpt-6.1-terra`） | ❌ | ✅ | ✅ |
| GLM / Kimi / DeepSeek / Qwen（例：`glm-5.3`、`kimi-k3`、`deepseek-v4-flash`、`qwen3.8-max`） | ✅ | ✅ | ❌ |

モデル ID は QCode の ID と完全に一致させます。公式ページにも "The model ID must match the ID in the provider's documentation." とあります。現在の ID とモデルごとの単価は [qcode.cc/models](https://qcode.cc/models) で確認できます。Claude モデルは Anthropic Messages エンドポイントでのみ提供しているため、`claude-*` の ID を `openai-completions` や `openai-responses` で使うと `model_not_available_on_endpoint` が返ります（[エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths)を参照）。

公式の CLI ドキュメントによると、認証ヘッダーは形式で決まります。`openai-completions` と `openai-responses` は `Authorization: Bearer <key>` を送り、`anthropic-messages` はキーを `x-api-key` として送ります。どちらも QCode のエンドポイントページにある curl 例と同じ形です。

## インストール

**デスクトップ版。** MiniMax Code は macOS 12 以降と Windows 10 以降に対応しています。グローバルサイト（`code.minimax.io/about`）または中国サイト（`code.minimax.cn/about`）からダウンロードするか、macOS では Homebrew も使えます。

```bash
# 中国本土向け
brew install --cask minimax-ai/tap/minimax-code

# 海外向け
brew install --cask minimax-ai/tap/minimax-code --language=en
```

**CLI（`mcode`）。** 公式のインストーラーに `sudo` は不要です。

```bash
# macOS / Linux / WSL
curl -fsSL https://filecdn.minimax.chat/public/install.sh | bash

# Windows（PowerShell）
irm https://filecdn.minimax.chat/public/install.ps1 | iex

# npm の場合：Node.js 22.19.0 以降（22.x）、または Node.js 24、25、26
npm install -g @minimax-ai/code
```

ターミナルを開き直して確認します（2026-11-10 の実測は npm で導入し、`mcode --version` の出力は `0.7.6` でした）。

```bash
mcode --version
mcode --help
```

自分のキーを使うだけなら MiniMax へのログインは不要です。リポジトリの README にも "BYOK does not require a MiniMax login." とあり、2026-11-10 の実測も `mcode login` を実行せずに行いました。MiniMax 自身のモデルも使いたい場合だけ、`mcode login`（中国本土のアカウント）または `mcode login --region global`（Global アカウント）でサインインしてください。

## mcode CLI の設定

キーを `MCODE_PROVIDER_API_KEY` に入れてから、形式ごとにプロバイダーを 1 つずつ追加します。以下は 2026-11-10 に mcode 0.7.6 で実測したコマンドそのもので、キーだけがプレースホルダーです。

```bash
export MCODE_PROVIDER_API_KEY="cr_xxx"

# Anthropic Messages：Claude
mcode provider add --name qcode-a \
  --base-url https://api.qcode.cc/api \
  --api-format anthropic-messages \
  --model claude-haiku-5-5 --use

# OpenAI Chat Completions：GPT と中国系モデル
mcode provider add --name qcode-c \
  --base-url https://api.qcode.cc/openai/v1 \
  --api-format openai-completions \
  --model deepseek-v4-flash --use

# OpenAI Responses：GPT
mcode provider add --name qcode-r \
  --base-url https://api.qcode.cc/openai/v1 \
  --api-format openai-responses \
  --model gpt-6.1-terra --use
```

成功すると、それぞれ `Provider added and selected: <name>` と表示されます。続いて選択中のモデルでタスクを 1 つ実行します。1 回の実行だけモデルを変えたいときは `--model custom_provider:<name>/<model-id>` を指定します。

```bash
mcode exec "Reply with exactly: OK"

mcode exec --model custom_provider:qcode-a/claude-haiku-5-5 \
  "Reply with exactly: OK"
```

これらのコマンドについて知っておきたい点：

- **キーの保存先。** `MCODE_PROVIDER_API_KEY` と `--api-key-env <name>` が読まれるのは、プロバイダーを追加するその時だけです。その後 mcode はキーを `~/.minimax/config.yaml` の `options.apiKey` に平文で保存します。このファイルは他人と共有しないでください。あとでキーを変えるときは、プロバイダーを追加し直すか、この値を書き換えます。
- **自分で決めた変数名を使う。** `--api-key-env QCODE_API_KEY` を付けると、キーを `QCODE_API_KEY` から読み取ります（`openai-completions` のエントリーで実測済み）。
- **`--use`** は最初のモデルをテストしてからプロバイダーを保存し、そのモデルを既定にします。接続テストに失敗すると 0 以外の終了コードで終わり、何も保存されません。このテストは実際のモデルリクエスト 1 回分です。`--use` のたびに既定が切り替わるので、既定にしたいプロバイダーを最後に追加するか、あとで `/model` で切り替えてください。
- **複数のモデル。** `--model` を繰り返すと 1 つのプロバイダーに複数のモデルを登録できます（例：`--model claude-haiku-5-5 --model claude-sonnet-5-5`）。プロバイダー ID は `custom_provider:` に `--name` の値を続けたもので、例えば `custom_provider:qcode-a` です。
- **上限値。** カスタムモデルには `--context-limit` と `--output-limit` を指定できます（正の整数。繰り返した `--model` すべてに適用）。指定しないと、未知のカスタムモデルはコンテキスト 200,000 トークン、出力 16,384 トークンとして扱われます。
- **地域別のホスト。** アジア（中国本土を含む）では `asia.qcode.cc`、北米・欧州では `us.qcode.cc` も使えます。パスはそのまま、例えば `https://asia.qcode.cc/api` です。

TUI の中では `/model [filter]` でモデルを選び、`/provider` で保存済みのプロバイダーを管理できます。

## デスクトップアプリの設定

公式の手順（Settings → Usage & model。中国版では同じ場所が中国語表示になります）：

1. **Settings → Usage & model** を開き、Custom model の **Add model** を選びます。
2. プリセットのプロバイダーを検索するか、**Others** を選んでプロバイダー名、Base URL、API キー、API 形式を入力します。
3. モデル ID を入力するか、**Fetch** でプロバイダーの一覧から選びます。モデル ID はプロバイダーのドキュメントの表記と一致させます。
4. **Save** を選び、メッセージ入力欄に戻ってモデルメニューから追加したモデルを選びます。

「Others」フォームに入力する値です。Base URL は上の CLI で実測した 3 つと同じですが、デスクトップアプリ自体は 2026-11-10 の実測に含まれていないため、アプリ内の接続テストの結果を優先してください。形式ごとに 1 件ずつ作成し、QCode のキー 1 本を複数の項目で使えます。

| 項目 | Claude | GPT | GLM / Kimi / DeepSeek / Qwen |
|---|---|---|---|
| プロバイダー名 | `QCode Claude` | `QCode GPT` | `QCode CN` |
| Base URL | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` | `https://api.qcode.cc/openai/v1` |
| API キー | `cr_xxx` | `cr_xxx` | `cr_xxx` |
| API 形式 | `anthropic-messages` | `openai-completions`（または `openai-responses`） | `openai-completions`（または `anthropic-messages` と `https://api.qcode.cc/api`） |
| モデル ID | `claude-sonnet-5-5` | `gpt-6.1-sol` | `deepseek-v4-flash` |

公式ページによると、「Fetch」はプロバイダーのモデル一覧を読むだけで設定は保存しません。「Save」はテストを行わず、実行中のタスクのモデルも切り替えません。本格的に使う前に、モデル横のテストボタン（接続テスト）で確認してください。

**設定ファイルの場所。** カスタムプロバイダーは、macOS では `<dataDir>/config.yaml`、Windows では `<dataDir>\config.yaml` の `custom_provider` キーに保存されます。公式ガイドは、インストール方法や起動設定によってデータディレクトリが変わることがあるとして、デスクトップアプリの固定パスを示していません。このページも同様に固定パスは書きません。このガイドはエージェントにファイルを編集させる場面向けで、通常は上の設定画面から操作するほうが簡単です。ファイルを直接編集する場合は、事前にバックアップを取り、次のような項目を既存の内容にマージしてください。編集中はアプリで設定を保存しないようにします。

```yaml
custom_provider:
  qcode-claude:
    name: "QCode Claude"
    kind: custom
    enabled: true
    api: anthropic-messages
    options:
      baseURL: "https://api.qcode.cc/api"
      apiKey: "cr_xxx"
    models:
      "claude-sonnet-5-5":
        name: "Claude Sonnet 5.5"
        enabled: true
        limit:
          context: 200000
          output: 8192
        modalities:
          input: [text]
          output: [text]
```

`context` と `output` の数値は仮の値です。公式ガイドは、フォームの既定値はモデルの能力を示すものではないこと、`limit` は `128K` のような文字列ではなく正の整数で書くことを求めています。実際に確認したモデルの上限値を入れてください。`${API_KEY}` は展開されないので、`apiKey` には実際のキーを書きます。

## 動作確認

まず CLI で確認します。`provider test` は実際のリクエストを送るからです。

```bash
mcode provider list
mcode provider test custom_provider:qcode-a
```

完全な書式は `mcode provider test <provider-id> [--model <id>] [--json]` です。2026-11-10 の実測では `Provider available: custom_provider:qcode-a` と表示され、終了コードは 0 でした。`mcode provider list` ではキーが伏せ字で表示されます。一覧には組み込みの `minimax_oauth`（マネージドログイン）の行もありますが、追加したカスタムプロバイダーには影響しません。TUI では `/status` でアカウントとモデルを、`/doctor` で設定を確認できます。

デスクトップ版：モデル横の接続テストを実行してから、モデルメニューでそのモデルを選び、短いメッセージを送ります。公式ページによると、テストに通ってもテストリクエストが成功したことを示すだけなので、画像や動画などの入力は実際の用途に合わせて別途確認する必要があります。

ツールの外でも確認したい場合は、使う形式のエンドポイントにリクエストを 1 件送ります（キーとモデルは置き換えてください）。

```bash
curl -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: cr_xxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'
```

内容のある JSON が返れば、キーとパスは正しく設定されています。エラーの場合は JSON のエラー本文を見てください。パスやキーの誤りと、そのエンドポイントで提供していないモデルとを見分けられます。

## トラブルシューティングと既知の制限

最初の 4 行は、カスタムモデルについての公式トラブルシューティング表の内容です。

| 症状 | 公式ドキュメントの確認項目 | QCode での対処 |
|---|---|---|
| 保存したモデルが表示されない | データディレクトリが正しいか、プロバイダーとモデルが有効か、`custom_provider` の下にあるか、アプリが変更を読み込んだか | ファイルを手で編集した場合は、デスクトップアプリを開き直します |
| 401 / 403 | キーがこのプロバイダーのものか、伏せ字や展開されないプレースホルダーではないか、カスタムヘッダーが認証を上書きしていないか | 伏せ字ではなく、`cr_` で始まる完全なキーを貼り付けます |
| 404 | "Matching API format and Base URL; required `/v1` and gateway prefix preserved; exact model ID exists" | `anthropic-messages` → `https://api.qcode.cc/api`、OpenAI の 2 形式 → `https://api.qcode.cc/openai/v1`。モデル ID は [qcode.cc/models](https://qcode.cc/models) からコピーします |
| テストに失敗したのにモデルを選べる | テストの状態は診断用です。成功扱いにせず、テストが示したエラーを直します | 表示されたエラーを直してから、もう一度テストします |
| `model_not_available_on_endpoint` | MiniMax のドキュメントにはありません。Claude の ID を OpenAI 形式に送ったときの QCode のエラーです | `claude-*` には `anthropic-messages` を使います |
| テキストは動くが、添付やツールが失敗する | 宣言した機能は、プロバイダーとプロトコルが実際に対応している必要があります | 確認済みの機能だけを宣言します |
| QCode のキーを変えたのに、mcode が古いキーを送る | キーはプロバイダー追加時に `config.yaml` へコピーされています | プロバイダーを追加し直すか、`~/.minimax/config.yaml` の `options.apiKey` を書き換えます |
| ログに `token counter endpoint missing; disabling remote counting for this base url` と出る | MiniMax のドキュメントにはありません。2026-11-10 の実測で表示されました | 情報メッセージです。mcode はその Base URL でのリモートのトークン計数を止めるだけで、会話はそのまま続きます |

その他の注意点：

- BYOK のリクエストが失敗しても、選択中のプロバイダーはそのままでエラーが表示されます。MiniMax Code がマネージドモデルや別のプロバイダーに黙って切り替えることはありません。
- CLI には 4 つ目の API 形式として Google Gemini 用の `google-generative-ai` もあります。QCode は Gemini 系列を提供していないため、これに対応する QCode の設定はありません。
- QCode は `gpt-6-luna` と `gpt-5.6-luna` を提供していません。`gpt-6.1-sol` または `gpt-6.1-terra` をお使いください。
- バージョン（2026-11-10）：このページの実測は mcode 0.7.6 で行いました。これは npm `@minimax-ai/code` の `latest` です。GitHub Releases ページでは、まだタグ v0.7.2 が最新リリースとして表示されています。お使いのバージョンは `mcode --version` で確認できます。デスクトップ版の BYOK ページは 2026-09-16 付で、設定形式は "may differ between app versions" としています。
- 用途に合ったモデルは[モデル選択](/docs/usage/model-selection)、このツール以外の原因で失敗する場合は[トラブルシューティングガイド](/docs/reference/troubleshooting)を参照してください。

## 関連ドキュメント

- [エンドポイントと API パス](/docs/getting-started/endpoints-and-api-paths)：プロトコルとモデル系列の対応
- [ツール互換性一覧](/docs/ide/tool-compatibility)：どのツールがどのプロトコルを使うか
- [Kimi Code CLI 設定](/docs/ide/kimi-code)：同じ 3 つのエンドポイントで実測した別のターミナルエージェント
- [中国系モデルの接続](/docs/usage/cn-models)：OpenAI Chat エンドポイントで使うモデル ID
- [モデル選択](/docs/usage/model-selection)：タスクに合ったモデルの選び方