Kimi Code CLI 中转站配置教程

# Kimi Code CLI 中转站配置教程

> 适用：`kimi`（Moonshot 的 Kimi Code CLI）  
> 中转站地址：`https://api.zaimod.com/v1`（**带 `/v1`**）  
> 主线：装 CLI → 写 `~/.kimi-code/config.toml` → 建令牌（KIMI-自部署）→ `kimi` 发一句话，约 8 分钟

---

## 一、先弄清这是哪条线

Kimi Code CLI 是月之暗面（Moonshot）的终端编程智能体，命令就是 `kimi`。它和 Kimi 网页版、Kimi 会员是两套东西：**本教程走 API Key 计费**，请求打到中转站，扣中转站余额，不需要 Kimi 账号，也不消耗网页版额度。

几个容易搞混的身份关系：

| 说法                 | 实际是什么                                                     |
| ------------------ | --------------------------------------------------------- |
| `kimi` 命令          | Kimi Code CLI，2.x 起是**单个原生二进制**（Rust），不再需要 Python         |
| PyPI 上的 `kimi-cli` | 旧的 Python 版，**已归档**，只指向新版本；安装器会自动处理残留                     |
| `type = "kimi"`    | 配置里的**协议类型**，指 Moonshot 的 OpenAI 兼容接口，不是"官方订阅"            |
| 官方订阅 provider      | 首次运行生成的配置里带一个受管 provider，走订阅额度；我们要做的是**外加**一个自己的 provider |

`type = "kimi"` 这一点很关键：它意味着请求走 `{base_url}/chat/completions`，所以 `base_url` 必须写到 `/v1` —— 这跟 Claude Code 那种"纯域名"的写法**正好相反**，是这一篇最容易配错的地方。

---

## 二、一分钟速查表

| 项目   | 填什么                                                                         |
| ---- | --------------------------------------------------------------------------- |
| 配置文件 | `~/.kimi-code/config.toml`（Windows：`C:\Users\<用户名>\.kimi-code\config.toml`） |
| 服务地址 | `[providers.xxx] base_url = "https://api.zaimod.com/v1"` —— **必须带 `/v1`**    |
| 协议类型 | `type = "kimi"`（OpenAI 兼容）                                                  |
| 凭证   | `api_key = "你的API_KEY"`，或 `api_key_env = "环境变量名"`                           |
| 默认模型 | `default_model = "kimi-k3"` —— 填的是**别名**，不是模型 ID                            |
| 令牌分组 | **KIMI-自部署**                                                                |
| 验证   | `kimi doctor config` → `kimi -p "只回复 ok"` → `kimi` 里发一句话                    |

**三个反直觉的点：**

1. **凭证以 `config.toml` 为准**。provider 的 Key 从配置里的 `api_key`，或你显式指定的 `api_key_env` 读。旧文档提过 `KIMI_*` 环境变量可以覆盖，新版文档却明确写了"不会自动回落环境变量"，两边不一致 —— 所以别赌环境变量：写在配置里，或者用 `api_key_env` 点名一个变量。
2. **`default_model` 填的是别名**。它必须能在 `[models.<别名>]` 里找到对应区块；填成"你想要的那个模型 ID"而没建对应区块，启动就报找不到模型。
3. **`max_context_size` 只是声明**。写 `1048576` 不会真的把窗口变成 100 万，它告诉 CLI "按这个大小算预算、什么时候压缩"。上游实际更小的话，长对话会在上游报上下文超限。

---

## 三、第一步：安装

### 3.1 Windows（PowerShell）

Kimi Code CLI 在 Windows 上**需要 Git Bash** —— 它的工具调用（执行 shell 命令）依赖 bash，Windows 自带的 PowerShell 顶不上。所以先确认 git 在：

```powershell
git --version
```

有输出再装，没输出先装 Git for Windows，然后**重开 PowerShell**（PATH 是新窗口才生效）：

```powershell
irm https://code.kimi.com/kimi-code/install.ps1 | iex
```

### 3.2 macOS / Linux

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

> 注意：`install.sh` **不能**在 Git Bash / MSYS / Cygwin 里跑，脚本第一件事就会拒绝并提示你改用 `install.ps1`。Windows 上只走 PowerShell 那条路。

### 3.3 装了什么、装在哪

- 装到 `~/.kimi-code/bin`，可执行文件叫 `kimi`；想换位置在运行前设 `KIMI_INSTALL_DIR`。  
  |  |  |  
  | --- | --- |
- **不需要 Node.js，也不需要 root**。要用 root 装到系统目录时才显式指定：`curl ... | sudo env KIMI_INSTALL_DIR=/usr/local bash`。
- 安装时按 `latest` 指针取版本、校验 SHA256，装完把 `~/.kimi-code/bin` 写进你的 shell 配置（zsh 写 `.zshrc`，bash 写 `.bashrc`）。
- 如果机器上还留着旧的 Python 版 `kimi-cli`，安装器会把那个 shim 改名，避免它继续排在 PATH 前面抢 `kimi` 这个名字。
- 会在 `~/.kimi-code/region` 记一个区域标记（从 `code.kimi.com` 装的写 `mainland-cn`），首次登录后被账号信息取代。

**Alpine 等 musl 系统装不上**（官方只发 glibc 二进制），会直接报错让你改用 npm 版：`npm install -g @moonshot-ai/kimi-code`。macOS 上也可以用 Homebrew：`brew install kimi-code` —— 公式名就是 `kimi-code`，不存在同名陷阱。

### 3.4 验证

**关掉终端重开一个**，然后：

```console
kimi --version
```

能输出版本号就继续。若提示 `kimi: command not found`，说明 shell 配置里的 PATH 没生效 —— 这条 PATH 只写进了 `.bashrc` / `.zshrc`，**非交互的脚本和 `bash -lc` 读不到**，这也是自动化场景里最常见的"明明装了却找不到"。

---

## 四、第二步：写 `config.toml`

配置文件在 `~/.kimi-code/config.toml`（设了 `KIMI_CODE_HOME` 就是 `$KIMI_CODE_HOME/config.toml`）。`kimi` 首次运行会自动生成这份文件，里面预置了官方订阅用的 provider —— 所以**第一次打开时它不是空的**，别惊讶。

**Windows（PowerShell）**

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.kimi-code" | Out-Null
notepad "$env:USERPROFILE\.kimi-code\config.toml"
```

**macOS**

```bash
mkdir -p ~/.kimi-code
touch ~/.kimi-code/config.toml
open -e ~/.kimi-code/config.toml
```

**Linux**

```bash
mkdir -p ~/.kimi-code
nano ~/.kimi-code/config.toml
```

nano 里粘完按 `Ctrl+O` 保存、回车确认、`Ctrl+X` 退出。

### 4.1 粘贴这段

```toml
default_model = "kimi-k3"

[providers.cxhao]
type = "kimi"
base_url = "https://api.zaimod.com/v1"
api_key = "你的API_KEY"

[models.kimi-k3]
provider = "cxhao"
model = "kimi-k3"
max_context_size = 1048576
max_output_size = 131072
capabilities = ["thinking", "always_thinking", "image_in", "video_in", "tool_use"]
support_efforts = ["low", "high", "max"]
default_effort = "max"
```

把 `你的API_KEY` 换成下一章（第五章）复制的 Key。

如果文件里**已经有别的 provider 配置**（比如官方订阅那条），做法是：保留原有内容，只把 `[providers.cxhao]` 和 `[models.kimi-k3]` 两个区块追加进去，再把顶部的 `default_model` 改成 `kimi-k3`。**别在文件里留下第二行 `default_model`** —— TOML 里同一个键出现两次是硬错误，整份配置会读不进去。

### 4.2 每一段在做什么

| 字段                     | 作用                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| `default_model`        | 启动时用哪个模型，值必须是某个 `[models.<别名>]` 的别名                                                                           |
| `providers.<名字>`       | 一个上游。名字随便起（这里是 `cxhao`），后面 `models` 里要用它引用                                                                    |
| `type`                 | 协议类型：`kimi` / `anthropic` / `openai` / `openai_responses` / `google-genai` / `vertexai`。我们用 `kimi`（OpenAI 兼容） |
| `base_url`             | 上游地址。`type = "kimi"` 时**要带到 `/v1`**                                                                           |
| `api_key`              | 明文 Key。也可以换成 `api_key_env = "变量名"`，二选一                                                                        |
| `models.<别名>.provider` | 指向上面 provider 的名字                                                                                             |
| `models.<别名>.model`    | 真正发给 API 的模型 ID，以模型广场为准                                                                                       |
| `max_context_size`     | 声明的上下文长度，影响压缩时机与用量百分比，不改变上游真实上限                                                                               |
| `max_output_size`      | 单次回复的最大 token 数                                                                                               |
| `capabilities`         | 告诉 CLI 这个模型支持什么。`always_thinking` = 思考关不掉                                                                     |
| `support_efforts`      | 可用的思考档位。K3 是 `low` / `high` / `max`                                                                           |
| `default_effort`       | 默认档位。截图里底部显示的 `thinking: max` 就是它                                                                             |

### 4.3 三个细节

**① 别名带点号要加引号。** `kimi-k3` 里只有连字符，裸写 `[models.kimi-k3]` 合法；但如果你换成 `kimi-k3.1-pro` 这种带点的名字，必须写成 `[models."kimi-k3.1-pro"]` —— 否则 TOML 会把点当成层级分隔符，别名就散架了，而**不会报错**。

**② 不想把 Key 写在文件里**，就把 `api_key` 换成：

```toml
api_key_env = "KIMI_KEY"
```

然后设环境变量（Windows PowerShell）：

```powershell
[Environment]::SetEnvironmentVariable("KIMI_KEY", "你的API_KEY", "User")
```

```bash
export KIMI_KEY="你的API_KEY"
echo 'export KIMI_KEY="你的API_KEY"' >> ~/.zshrc
```

`api_key_env` 填的是**变量名**。变量没设或为空时，请求会失败并明确告诉你是哪个变量名找不到；`/models` 刷新时这类 provider 会被标成 failed，不会影响其它 provider。

**③ `max_context_size` 别乱写。** 截图里右下角 `context: 2% (19.6k/1M)` 的 `1M` 就来自这里。声明得比上游实际更大，平时看着没事，一到长对话就在上游爆上下文超限；如果真遇到，把这一行改成模型广场标注的实际值。

---

## 五、第三步：建令牌（KIMI-自部署）

**1. 控制台 → 令牌管理 → 创建令牌**

**2. 名称**随意，建议 `kimi`。

**3. 令牌分组选「默认分组」或者智能自由**

**4.「模型限制列表」留空**

**5. 提交 → 回到令牌列表 →「密钥」列 → 复制密钥**

菜单里两项别混：**复制密钥** 得到一串纯 Key；**复制连接信息** 得到的是带 `Base URL`、`Bearer` 前缀的一整段，粘进 `api_key` 会直接 401。

---

## 六、第四步：启动与验证

保存后**重新打开终端**（配置在启动时读），然后：

```console
kimi
```

发一句：

```console
你好
```

![](/uploads/editor/20261101/img_6ae62fd0e56c50.35335888.png)

### 6.1 三处判据

| 位置    | 正常表现                                   | 说明                                                  |
| ----- | -------------------------------------- | --------------------------------------------------- |
| 顶部信息卡 | `Model: kimi-k3`                       | 说明 `default_model` 指向的别名被正确解析了                      |
| 底部左   | `kimi-k3  thinking: max  C:\Users\...` | 模型 + 思考档位（来自 `default_effort`）+ 工作目录                |
| 底部右   | `context: 2% (19.6k/1M)`               | `max_context_size` 生效的证据；百分比不涨或直接跳 100%，说明上游窗口比声明的小 |

最硬的还是后台：控制台「使用日志」里出现这次调用，才算真的走了中转。

### 6.2 两条命令行自查

```console
kimi doctor config
kimi -p "只回复 ok"
```

- `kimi doctor config`：只校验**文件结构**（TOML 是否合法、字段名是否认识），输出 `Kimi doctor OK` 即通过。它**不验证** Key 和模型 ID 能不能用。
- `kimi -p`：不进交互界面，跑一条最小请求，端到端验证 Key + 模型 + 网络。

两者配合用：结构错看第一个，能用与否看第二个。

---

## 七、进阶：多模型、思考档、界面偏好

### 7.1 一次登记多个模型

```toml
default_model = "kimi-k3"

[providers.cxhao]
type = "kimi"
base_url = "https://api.zaimod.com/v1"
api_key = "你的API_KEY"

[models.kimi-k3]
provider = "cxhao"
model = "kimi-k3"
max_context_size = 1048576
capabilities = ["thinking", "always_thinking", "image_in", "video_in", "tool_use"]
support_efforts = ["low", "high", "max"]
default_effort = "max"

[models."kimi-k3-fast"]
provider = "cxhao"
model = "kimi-k3-fast"
display_name = "K3 (fast)"
max_context_size = 262144
capabilities = ["thinking", "image_in", "tool_use"]
support_efforts = ["low", "high"]
default_effort = "high"
```

`display_name` 只管显示；别名带点号记得加引号。TUI 里用 `/model` 切换，或启动时 `kimi -m kimi-k3-fast`。切换模型后如果档位不对，多半是 `support_efforts` 里没有当前 `default_effort`。

### 7.2 思考档位

`support_efforts` 决定可选哪些档，`default_effort` 决定默认。K3 只有 `low` / `high` / `max` 三档；配置里写 `medium` 或 `xhigh` 也能存下来，但上游会把 `medium` 折到 `high`、`xhigh` 折到 `max` —— 看到"设了 medium 却显示 high"不是 bug。

想让 CLI 记住上一轮的思考内容（长任务里很有用），在配置里加：

```toml
[thinking]
enabled = true
effort = "high"
keep = "all"
```

### 7.3 界面偏好与数据目录

- 终端外观、键位这类偏好写在同目录的 `tui.toml`，别塞进 `config.toml`。
- MCP 服务器写在 `~/.kimi-code/mcp.json`（项目级放 `.kimi-code/mcp.json`）。
- 整个数据目录想搬家：设 `KIMI_CODE_HOME`，配置文件路径随之变成 `$KIMI_CODE_HOME/config.toml`。

---

## 八、常见问题

**8.1 报 `provider.auth_error: 401`**

Key 不对。按顺序查：占位文字有没有替换干净、复制时有没有带上 `Bearer ` 前缀、令牌是否被禁用、`api_key_env` 写的是变量名还是 Key 本身。Kimi Code 遇到 401 会很快失败并明确指出是 provider 的认证错误，不会静默回落到官方订阅。

如果你在终端里 `export KIMI_API_KEY=...` 而没改配置，那大概率没用 —— 不同版本对环境变量的支持不一致，配置里的 `api_key` / `api_key_env` 才是稳定解。

**8.2 报找不到模型 / 别名不存在**

这种错误通常在**本地**就被拒掉（根本不出网），说明 `default_model` 或 `-m` 用的别名在 `[models.*]` 里没有对应区块。检查三处拼写：`default_model` 的值、`[models.<别名>]` 的表名、`model` 字段的 ID —— 前两个是别名（自定），第三个才是发给 API 的模型 ID。

**8.3 长对话突然报上下文超限**

`max_context_size` 声明得比上游实际大。改成模型广场标注的真实值。声明值只影响预算计算与压缩时机，不会向上游"申请"到更大窗口。

**8.4 每轮都在想，关不掉**

`capabilities` 里带了 `always_thinking` —— 它的意思就是"这个模型不允许关闭思考"。去掉它才能用 `/think off` 之类的方式关；如果模型本身就不支持关，去掉也没用，只是让 UI 允许你切换。

**8.5 `kimi: command not found`**

三种情况：没重开终端；PATH 只写进了 `.bashrc` / `.zshrc` 而你是在脚本或 `bash -lc` 里跑（非交互 shell 不读这些文件）；装到了自定义 `KIMI_INSTALL_DIR` 但没加 PATH。先 `ls ~/.kimi-code/bin` 确认二进制在，再 `which -a kimi` 看有没有旧版本抢在前面。

**8.6 以前装过 Python 版 kimi-cli**

安装器会把旧的 `kimi` shim 改名（不是删除），确保新的排在前面。如果没生效，`which -a kimi` 会列出所有同名命令，把旧的那个换掉或从 PATH 里移走。旧版的数据可以用 `kimi migrate` 导入。

**8.7 Windows 上工具调用报错 / 找不到 bash**

Kimi Code 执行 shell 命令依赖 Git Bash。只装 PowerShell 不够，需要 Git for Windows，并且 `git --version` 在 PowerShell 里能跑通。装完重开窗口再启动 `kimi`。

**8.8 改完配置没变化**

配置在**启动时**读。`Ctrl+C` 退出再 `kimi`，别在原会话里试。

---

上一篇：GLM Claude Code 配置{else}上一篇：没有了下一篇：CC-Switch 下载安装{else}下一篇：没有了