# 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 Key？能。截至 2026-11-10，官方「自定义模型 / BYOK」页写明：桌面端在 **设置 → 用量与模型** 里添加自定义模型，`mcode` CLI 用 `mcode provider add` 添加。两边都支持三种 API 格式：`anthropic-messages`、`openai-completions`、`openai-responses`，QCode 三种都提供，一把 QCode 密钥就能在同一个工具里同时用 Claude、GPT 与国产模型。2026-11-10 按 mcode 0.7.6 实测：不登录 MiniMax 账号，`mcode provider add … --use` 之后 `mcode exec` 在三种格式上都正常返回。

## 接入速览

| 项目 | 说明 |
|---|---|
| 它是什么 | MiniMax Code 是 macOS / Windows 桌面端 AI Agent 应用；`mcode` 是它的终端 CLI（交互式 TUI、`mcode exec` 无头模式、`mcode acp`）。CLI 源码在 GitHub，采用 MIT 协议；仓库说明里写明不包含桌面端应用的源码 |
| 可用模型 | 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` · 三个都按 mcode 0.7.6 实测通过 ✅（2026-11-10） |
| 配置位置 | CLI：`mcode provider add`，写入 `~/.minimax/config.yaml`（默认数据目录）的 `custom_provider`。桌面端：**设置 → 用量与模型** → 自定义模型 → 添加模型 |
| API Key | 你的 QCode 密钥 `cr_xxx`。CLI 在添加服务商的那一刻，从 `MCODE_PROVIDER_API_KEY`（或 `--api-key-env` 指定的变量）读取它 |
| MiniMax 账号 | 用自己的密钥不需要登录；`mcode login` 只在使用 MiniMax 自家模型时才需要 |
| 官方文档 | [自定义模型 / BYOK](https://agent.minimaxi.com/docs/code/account/byok) · [Agent 的 BYOK 模型配置指南](https://agent.minimaxi.com/docs/code/account/byok-agent-setup) · [CLI 配置与模型](https://agent.minimaxi.com/docs/cli/configuration) · [CLI 快速开始（英文站）](https://code.minimax.io/docs/cli/quick-start) · [GitHub：MiniMax-AI/minimax-code](https://github.com/MiniMax-AI/minimax-code) |

## 用哪条协议

「API 格式」选哪个，MiniMax Code 就调用 QCode 的哪条端点。官方配置指南给了一张「三种协议如何配置地址」的表：

| API 格式 | 官方表里的 Base URL 形态 | 请求目标 | 接 QCode 时填 |
|---|---|---|---|
| `anthropic-messages` | `https://example.invalid`，或服务商指定的兼容接口前缀 | `<规范化后的 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 风格的 `/v1` 不会自动补齐，需要 `/v1` 时必须自己带上；Messages 会规范化末尾的 `/v1`、`/messages` 或 `/v1/messages`，不要自己反复拼接；网关已有的 `/proxy/anthropic` 等前缀不能随意删除（原文：「OpenAI 风格的 `/v1` 不会凭空补齐」「不要自己反复拼接这些后缀」）。落到 QCode 上：

- **`anthropic-messages`**：QCode 的 Anthropic 端点前缀是 `/api`，MiniMax Code 会自己补 `/v1/messages`，所以请求落在 `https://api.qcode.cc/api/v1/messages`。保留 `/api` 前缀，不要自己再写 `/v1/messages`。
- **`openai-completions`**：Base URL 必须自带 `/v1`，工具只补 `/chat/completions`。`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 路径。

表中最后一列的三个地址，2026-11-10 已按 mcode 0.7.6 逐一实测通过，每种格式各用一个型号（`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 与模型提供方文档里的写法一致，对 QCode 来说就是 /models 页上的 ID。当前在售的 ID 与各模型单价见 [qcode.cc/models](https://qcode.cc/models)。Claude 只在 Anthropic Messages 端点上提供，把 `claude-*` 放进 `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.cn/about`）或海外版（`code.minimax.io/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`，Global 账号 `mcode login --region global`。

## 配置 mcode CLI

先把密钥放进 `MCODE_PROVIDER_API_KEY`，再按格式各加一个服务商。下面就是 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>`。然后用选中的模型跑一个任务；只想在单次运行里换模型，用 `--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`** 会先测试第一个模型，再保存并设为默认模型；连接测试失败时命令以非零状态退出、什么都不保存。这次测试是一次真实的模型请求。每次 `--use` 都会改默认模型，所以想设为默认的那条最后加，或以后用 `/model` 切换。
- **多个模型。** `--model` 可以重复传入，给同一个服务商加多个模型，例如 `--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 上下文 Token、16,384 输出 Token。
- **就近接入点。** 亚洲（含中国大陆）可用 `asia.qcode.cc`，北美 / 欧洲可用 `us.qcode.cc`，路径不变，例如 `https://asia.qcode.cc/api`。

TUI 里用 `/model [filter]` 选模型，用 `/provider` 管理已保存的服务商。

## 配置桌面端

官方步骤（设置 → 用量与模型；海外版界面是 Settings → Usage & model）：

1. 打开 **设置 → 用量与模型**，在自定义模型中点击添加模型。
2. 搜索并选择预设提供商；列表里没有就选择 **其他**，填写提供商名称、接口地址、API Key 和 API 格式。
3. 输入模型 ID，或点击 **自动获取** 从列表里选。模型 ID 需要与提供方文档一致。
4. 点击 **保存**，回到消息输入框，从模型菜单中选择刚添加的模型。

选「其他」时可直接照填的值。地址与上面 CLI 实测的三个地址相同；桌面端本身不在 2026-11-10 的实测范围内，以应用内连通检测的结果为准。每种格式建一条，同一把 QCode 密钥可以建多条：

| 字段 | Claude | GPT | GLM / Kimi / DeepSeek / Qwen |
|---|---|---|---|
| 提供商名称 | `QCode Claude` | `QCode GPT` | `QCode CN` |
| 接口地址 | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` | `https://api.qcode.cc/openai/v1` |
| API Key | `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` |

按官方页的说明，「自动获取」只读取模型列表，不保存配置；「保存」不会自动测试，也不会切换当前任务的模型。正式使用前先点模型旁的检测按钮（连通检测）。

**配置文件在哪。** 自定义服务商保存在 macOS 的 `<dataDir>/config.yaml`、Windows 的 `<dataDir>\config.yaml` 里，键名是 `custom_provider`。官方指南提醒，自定义安装或启动配置可能改变数据目录，所以没有给桌面端写固定路径，本页也不写。这份指南是写给「让 Agent 去改文件」的场景，用上面的设置界面更省事。确实要手改时，把下面这样的条目合并进现有内容，先备份，并避免同时在应用里保存设置：

```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` 填正整数 Token 数，不要写 `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` 检查配置。

桌面端：点模型旁的检测按钮做连通检测，然后从模型菜单选中它，发一句短消息。官方页补充说，测试通过只说明这次测试请求成功；图片、视频等输入能力仍要用你自己的场景验证。

想脱离工具再确认一次，就对你所用格式对应的端点发一个请求（换成自己的密钥和模型）：

```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 错误体：路径写错、密钥不对、模型不在这条端点上，三类原因的报错各不相同。

## 常见问题与已知限制

前四行是官方「自定义模型」排查表里的内容：

| 现象 | 官方文档让你先查什么 | 接 QCode 时怎么办 |
|---|---|---|
| 保存后模型不出现 | 是否改错 dataDir；服务商和模型是否启用；是否写在 `custom_provider`；运行时是否已加载 | 手改过文件的话，重启桌面端再看 |
| 401 / 403 | 密钥是否属于该服务商、是否是掩码或未展开的占位符；自定义 Header 是否覆盖认证 | 粘贴完整的 `cr_` 密钥，不要用掩码值 |
| 404 | 「API 格式与 Base URL 是否匹配；是否遗漏 /v1 或丢失网关前缀；模型 ID 是否存在」 | `anthropic-messages` → `https://api.qcode.cc/api`；两种 OpenAI 格式 → `https://api.qcode.cc/openai/v1`；模型 ID 从 [qcode.cc/models](https://qcode.cc/models) 复制 |
| 测试失败但仍能选择 | 这是测试状态仅供诊断的行为，处理报错，不要伪造成功记录 | 按提示修正后重新测试 |
| `model_not_available_on_endpoint` | MiniMax 文档里没有；这是 QCode 对「把 Claude ID 发到 OpenAI 格式」的报错 | `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 停用远程 token 计数，对话本身照常进行 |

其它说明：

- BYOK 请求失败时，MiniMax Code 会保留你选的服务商并返回错误，不会静默改用托管模型或另一个服务商。
- CLI 还列了第四种格式 `google-generative-ai`（Google Gemini）。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，并说明不同应用版本的配置格式可能有差异。
- 什么任务用什么模型见[模型选择](/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)——同样在这三条端点上实测过的另一个终端代理
- [国产模型接入](/docs/usage/cn-models)——OpenAI Chat 端点上的模型 ID
- [模型选择](/docs/usage/model-selection)——什么任务用什么模型