# CodeWhale 接入指南

CodeWhale 是一款开源的终端 AI 编程工具，提供交互式 TUI 界面，支持代码编辑、推理流式输出及工作区修改审批。本文介绍如何让它通过 UModelverse 平台调用模型。

## **系统要求**

| 平台 | 要求 |
| --- | --- |
| Windows | Windows 10 或 Windows 11 |
| macOS | macOS 10.15 (Catalina) 或更高版本 |
| Linux | 主流发行版（Ubuntu、Debian 等） |

所有平台均需要网络连接。

## **1. 安装 CodeWhale**

推荐通过 npm 安装：

```
npm install -g codewhale
```

安装后验证：

```
codewhale --version
```

也可以通过 Cargo 安装（需要 Rust 1.88+）：

```
cargo install codewhale-cli --locked
cargo install codewhale-tui --locked
```

## **2. 配置 UModelverse API**

### 2.1 获取 API Key

访问 [UModelverse 控制台](https://console.ucloud.cn/modelverse/api) 获取您的 API 密钥。可用模型见 UModelverse 平台[支持的模型](https://api.modelverse.cn/v1/models)。

### 2.2 写入配置文件

编辑 `~/.codewhale/config.toml`，填入以下内容（将 `YOUR_API_KEY` 替换为实际 Key）：

```
[providers.umodelverse]
base_url = "https://api.modelverse.cn/v1"
api_key = "YOUR_API_KEY"
model = "deepseek-v4-pro"
```

也可以通过环境变量方式配置：

macOS / Linux：

```
export DEEPSEEK_BASE_URL=https://api.modelverse.cn/v1
export DEEPSEEK_API_KEY=YOUR_API_KEY
export DEEPSEEK_MODEL=deepseek-v4-pro
```

Windows（PowerShell）：

```
$env:DEEPSEEK_BASE_URL="https://api.modelverse.cn/v1"
$env:DEEPSEEK_API_KEY="YOUR_API_KEY"
$env:DEEPSEEK_MODEL="deepseek-v4-pro"
```

## **3. 启动 CodeWhale**

进入项目目录，通过 `--provider` 指定使用自定义提供商：

```
cd your-project-folder
codewhale --provider umodelverse
```

也可以直接在启动时指定模型：

```
codewhale --provider umodelverse --model deepseek-v4-pro
```

启动后进入交互式 TUI 界面即可开始编程。执行以下命令可验证配置与连接是否正常：

```
codewhale doctor
```

## **常见问题**

### 提示认证失败或无法连接？

请逐项确认：

1.  `api_key` 来自 UModelverse 平台，复制完整且无空格。

2.  `base_url` 为 `https://api.modelverse.cn/v1`（带 `/v1` 后缀）。

3.  `model` 是 UModelverse 平台[支持的模型](https://api.modelverse.cn/v1/models)之一，没有写错。