# Kimi Code CLI 接入

> **最后核实**：2026-10-13 · 📄 依据官方文档（Kimi Code CLI 2.1.1）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（`type = "anthropic"`）· GPT ✅ · 国产模型 ✅（`type = "openai"`）· Gemini ❌（QCode 暂不提供 Gemini 系列，请使用 Claude、GPT 或国产模型） |
| 协议与 Base URL | Anthropic Messages：`https://api.qcode.cc/api` · OpenAI Chat Completions：`https://api.qcode.cc/openai/v1` |
| 配置位置 | `~/.kimi-code/config.toml`——每种协议一个 `[providers.<name>]` 表，每个模型一条 `[models.<alias>]` |
| 官方文档 | [moonshotai.github.io/kimi-code](https://moonshotai.github.io/kimi-code/en/) |

[Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) 是 Moonshot AI 跑在终端里的编码代理。官方文档把模型来源分成三种：Kimi Code 托管服务一键登录、「connecting Claude with an Anthropic API key, or connecting third-party inference services via the OpenAI-compatible protocol」——后两种正好对应 QCode 开放的两条端点，因此一把 QCode 密钥就能在同一个工具里同时用 Claude、GPT 与国产模型。写作时最新版本是 2.1.1（2026-09-24）。

## 用哪条协议

`[providers.<name>]` 里的 `type` 字段决定用哪套协议实现。官方字段说明一共列了六个取值——`kimi`、`anthropic`、`openai`、`openai_responses`、`google-genai`、`vertexai`——接 QCode 只用其中两个：

| 想用的模型 | `type` | `base_url` |
|---|---|---|
| `claude-sonnet-5`、`claude-opus-5`、`claude-haiku-5-5` | `anthropic` | `https://api.qcode.cc/api` |
| `gpt-6.1-sol`、`gpt-6-sol` 以及国产家族 | `openai` | `https://api.qcode.cc/openai/v1` |

🔴 **不要把 Claude 模型指向 OpenAI 兼容端点。** QCode 只在 Anthropic Messages 这条端点上提供 Claude 家族，把 `claude-*` 发到 `https://api.qcode.cc/openai/v1` 会被拒绝。两条端点不能互换，详见[接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

Base URL 按上表原样填：写到 `/api` 或 `/openai/v1` 就停，**不要**再补 `/v1/messages` 或 `/chat/completions`，也**不要**留结尾斜杠。

## 安装

官方给两条路：安装脚本（推荐，无需预装 Node.js）与 npm 全局安装。

```sh
# macOS / Linux
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

# Windows（PowerShell）
irm https://code.kimi.com/kimi-code/install.ps1 | iex

# npm——先用 node --version 确认运行时
npm install -g @moonshot-ai/kimi-code
```

npm 这条路**要求 Node.js 22.19.0 及以上**。脚本会自动下载最新发布版、校验 checksum，并把 `kimi` 可执行文件放进 `PATH`。确认命令可用后，进入项目目录运行 `kimi` 打开交互界面：

```sh
kimi --version
cd your-project
kimi
```

## 配置 Claude（`type = "anthropic"`）

凭据只从配置文件读。官方说得很直接：CLI「does **not** fall back to shell environment variables automatically: running `export KIMI_API_KEY` in the terminal does not give any provider its key」——要么把密钥写进文件，要么用 `api_key_env` 指定一个变量名，由 CLI 每次请求时重新读取。

```toml
# ~/.kimi-code/config.toml
default_model = "claude-sonnet-5"

[providers.qcode]
type = "anthropic"
base_url = "https://api.qcode.cc/api"
api_key_env = "QCODE_API_KEY"

[models."claude-sonnet-5"]
provider = "qcode"
model = "claude-sonnet-5"
max_context_size = 262144
```

```sh
export QCODE_API_KEY=cr_your_qcode_key
```

`qcode` 只是你自己起的 provider 名，每条 `[models.<alias>]` 通过必填的 `provider` 字段指回它。如果不想用环境变量，把 `api_key_env` 换成 `api_key = "cr_your_qcode_key"`；官方注明这个值是明文写进配置文件的，而且 `api_key` 与 `api_key_env` 互斥——只能设一个。

| 字段 | 所在表 | 填什么 |
|---|---|---|
| `type` | providers | `anthropic`，官方定位是「For connecting to the Claude API」 |
| `base_url` | providers | `https://api.qcode.cc/api`；不填就跟随 Anthropic SDK 默认 |
| `api_key` / `api_key_env` | providers | 密钥本身，或存密钥的变量名 |
| `custom_headers` | providers | 可选，给每个请求附加的自定义 HTTP 头 |
| `provider` | models | 必填——上面定义的 provider 名 |
| `model` | models | 必填——发给服务端的模型 ID，如 `claude-sonnet-5` |
| `max_context_size` | models | 必填、至少 1 token——上面示例里的 `262144` 只是占位值，请填该模型自己标明的上下文长度 |
| `max_output_size` | models | 可选，对应 `max_tokens`；目前只有 `anthropic` provider 会读它 |

> **中国大陆**：Anthropic 这条端点也响应 `https://asia.qcode.cc/api` 与 `https://us.qcode.cc/api`，用的是同一把密钥——只把 `base_url` 里的主机名换掉，其余不动。
> **能力标记**：标准 Claude 模型名会自动启用视觉、工具调用与 Thinking；官方没收录的模型名要在 `[models.<alias>]` 上显式声明 `capabilities`（`thinking`、`image_in`、`tool_use` 等），而且这些标签只增不减。

## 配置 GPT 与国产模型（`type = "openai"`）

同一个文件，换另一条端点。`openai` 这个类型官方写的是「For connecting to the OpenAI Chat Completions protocol, as well as any third-party service compatible with that protocol (override `base_url` as needed)」——正因为它的内置默认是 `https://api.openai.com/v1`，覆盖 `base_url` 才是把连接指向 QCode 而不是 OpenAI 自己。

```toml
[providers.qcode-openai]
type = "openai"
base_url = "https://api.qcode.cc/openai/v1"
api_key_env = "QCODE_API_KEY"

[models."gpt-6.1-sol"]
provider = "qcode-openai"
model = "gpt-6.1-sol"
max_context_size = 262144

[models."deepseek-v4.1-flash"]
provider = "qcode-openai"
model = "deepseek-v4.1-flash"
max_context_size = 262144

[models."qwen3.8-max"]
provider = "qcode-openai"
model = "qwen3.8-max"
max_context_size = 262144
```

- **带点的别名要加引号。** `gpt-6.1-sol`、`qwen3.8-max` 必须写成 `[models."qwen3.8-max"]`；不加引号时 TOML 会把点当成嵌套表分隔符。字段名本身一律 snake_case（`default_model`、`max_context_size`）。
- 上面的数字只是必填字段的占位值——真实上下文长度以该模型自身的规格为准。计费按 token，各模型单价见 [qcode.cc/models](https://qcode.cc/models)。
- 两个 provider 可以共存于同一份配置。单次会话用 `-m <别名>` 指定模型（官方把它排在配置文件之上，但只对当次启动生效），或在 TUI 里用 `/model` 切换。`default_model` 必须是你在 `models` 里定义过的别名。
- 推理输出：第三方推理模型的 `reasoning_content` 字段与 `reasoning_effort` 注入由 CLI 自己处理；如果你的网关用的是非标准字段名，在模型别名上设 `reasoning_key` 覆盖。
- 这条端点上更多可用 ID 见[国产模型接入](/docs/usage/cn-models)。`claude-*` 在这里**不可用**。

## 验证

不启动 TUI 先查文件：

```sh
kimi doctor
kimi doctor config
```

`kimi doctor` 会「Validate `config.toml` and `tui.toml` without starting the TUI or modifying either file」，所有被检查的文件有效或被跳过时退出码为 `0`，有缺失或无效时为 `1`。官方写明的检查范围就是这两个 TOML 文件；文档没有说它会探测端点是否应答。

再看 CLI 实际登记了什么：

```sh
kimi provider list
```

然后进 TUI 输入 `/provider`，那是交互式 provider manager，可以查看、新增、删除已配置的 provider；`kimi provider` 是它在脚本与 CI 里的非交互等价命令。

最后直接打一次端点（换成你自己的密钥）：

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

本页依据官方文档整理，**上面的请求没有用真实密钥跑过**，因此不承诺任何状态码。请看返回的 JSON 错误体：路径写错、密钥不对、模型不在这条端点上，三类原因的报错各不相同。

> 官方另有一条第三方目录的快捷路径：`kimi provider catalog add anthropic --api-key sk-ant-... --default-model claude-opus-4-7`，协议类型、base URL 与模型清单都由目录给出，`--base-url` 用来覆盖目录端点（`--default-model` 会把 `default_model` 写成 `<providerId>/<modelId>`）。官方示例里的模型 ID 来自那个公开目录、不是 QCode 的模型，本页也没有核实 QCode 是否收录在该目录中，因此仍推荐走上面的 TOML 写法。

## 已知限制与排错

| 现象 | 官方文档怎么说 | 怎么处理 |
|---|---|---|
| 一启动就报某个 provider 缺凭据 | 优先级是 `api_key` 或 `api_key_env`（二者只能设一个），再看 `[providers.<name>.env]` 子表里的键，全都缺失则启动失败并报错 | `anthropic` 类型的惯例键名是 `ANTHROPIC_API_KEY` 与 `ANTHROPIC_BASE_URL`，写在 `[providers.qcode.env]` 里——它们是配置文件里的键，不是去 shell 里查。`/models` 刷新时，声明的变量未设或为空的 provider 会单独报错，不影响其它 provider |
| `export ANTHROPIC_API_KEY=…` 像没生效 | shell 变量不是通用的后备；确实读 shell 的只有 provider 的 `api_key_env` 与 `KIMI_MODEL_*` 这两条显式通道 | 用 `api_key_env`。`KIMI_MODEL_PROVIDER_TYPE` 接受 `kimi`、`anthropic`、`openai`；设了 `KIMI_MODEL_NAME` 就在内存里临时合成一个 provider，重启即消失 |
| 改文件没反应 | 启动选项优先级高于配置文件且只作用于当次会话，配置文件在启动时读取 | 重启 `kimi`，或在会话里执行 `/reload` 应用最新的 `config.toml` |
| 含点号的别名没加引号时，报配置错误或找不到该模型 | `default_model` 必须是 `models` 里定义过的别名；含点的别名不加引号会被当成嵌套表 | 给别名加引号：`[models."qwen3.8-max"]` |
| 报 404 或路径错误 | 官方未说明第三方网关的路径拼接细节 | `base_url` 写到 `/api`（Claude）或 `/openai/v1`（GPT、国产）就停，不留结尾斜杠，也不手写 API 路径 |
| Claude 在 `openai` provider 上被拒绝 | — | QCode 不在这条端点上提供 Claude 家族，改回 `type = "anthropic"` |
| 不同项目要用不同端点 | 目前只有单一用户级配置文件，没有项目级配置机制；文件放在哪儿都叫 `config.toml` | 启动前把 `KIMI_CODE_HOME` 指向按项目分开的数据目录 |

工具之外还要注意：

- **Gemini**：Kimi Code 有直连 Google Gemini API 的 `google-genai` 类型，但 QCode 暂不提供 Gemini 系列，请使用 Claude、GPT 或国产模型。
- **luna 系**：QCode 暂不提供 `gpt-6-luna`、`gpt-5.6-luna`，请改用 `gpt-6.1-sol`、`gpt-6-sol`、`gpt-5.6-terra` 等其它 GPT 模型。
- `max_output_size` 只有 `anthropic` provider 会读，所以在 `openai` 别名下设置输出上限不起作用。
- 按任务挑模型见[模型选择](/docs/usage/model-selection)；如果报错不在这个工具范围内，按[故障排查指南](/docs/reference/troubleshooting)的顺序查。

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)——协议与模型家族的对应表
- [工具兼容总览](/docs/ide/tool-compatibility)——哪些工具走哪条端点
- [国产模型接入](/docs/usage/cn-models)——OpenAI 这条端点上的 ID 与路径
- [模型选择](/docs/usage/model-selection)——什么任务用什么模型
- [OpenCode 接入](/docs/ide/opencode)——同样走这两条端点的另一个终端代理