# ZCLAW 模型配置指南

> 讌**重要变更**: ZCLAW 现在使用 UI 配置模型，不再需要编辑配置文件。

---

## 1. 配置方式

### 1.1 UI 配置（推荐）

在 ZCLAW 桌面应用中直接配置模型：

1. 打开应用，点击设置图标 ⚙️
2. 进入"模型与 API"页面
3. 点击"添加自定义模型"
4. 填写配置信息
5. 点击"设为默认"

### 1.2 配置存储位置

配置保存在浏览器的 localStorage 中：

```
localStorage Key: zclaw-custom-models
```

---

## 2. 支持的 Provider

### 2.1 国内 Provider

| Provider | 名称 | Base URL | 说明 |
|----------|------|----------|------|
| kimi | Kimi Code | `https://api.kimi.com/coding/v1` | Kimi 编程助手 |
| qwen | 百炼/通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | 阿里云百炼 |
| deepseek | DeepSeek | `https://api.deepseek.com/v1` | DeepSeek |
| zhipu | 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | 智谱 AI |
| minimax | MiniMax | `https://api.minimax.chat/v1` | MiniMax |

### 2.2 国际 Provider

| Provider | 名称 | Base URL | 说明 |
|----------|------|----------|------|
| openai | OpenAI | `https://api.openai.com/v1` | OpenAI GPT |
| anthropic | Anthropic | `https://api.anthropic.com` | Anthropic Claude |
| gemini | Google Gemini | `https://generativelanguage.googleapis.com` | Google Gemini |

### 2.3 本地 Provider

| Provider | 名称 | Base URL | 说明 |
|----------|------|----------|------|
| local | Ollama | `http://localhost:11434/v1` | Ollama 本地 |
| local | LM Studio | `http://localhost:1234/v1` | LM Studio 本地 |

---

## 3. UI 配置步骤

### 3.1 添加模型

在"模型与 API"页面：

1. **服务商**: 从下拉列表选择 Provider
2. **模型 ID**: 填写模型标识符（如 `kimi-k2-turbo`、`qwen-plus`）
3. **显示名称**: 可选，用于界面显示
4. **API Key**: 填写你的 API 密钥
5. **API 协议**: 选择 OpenAI（大多数 Provider）或 Anthropic
6. **Base URL**: 可选，使用自定义 API 端点

### 3.2 设为默认

点击模型列表中的"设为默认"按钮。

### 3.3 修改配置

点击"编辑"按钮修改已有配置。

---

## 4. 可用模型

### 4.1 Kimi Code

| 模型 ID | 说明 | 适用场景 |
|---------|------|----------|
| kimi-k2-turbo | 快速模型 | 日常对话、快速响应 |
| kimi-k2-pro | 高级模型 | 复杂推理、深度分析 |

### 4.2 百炼/通义千问 (Qwen)

| 模型 ID | 说明 | 适用场景 |
|---------|------|----------|
| qwen-turbo | 快速模型 | 日常对话 |
| qwen-plus | 通用模型 | 复杂任务 |
| qwen-max | 高级模型 | 深度分析 |
| qwen-coder-plus | 编码专家 | 代码生成 |

### 4.3 DeepSeek

| 模型 ID | 说明 | 适用场景 |
|---------|------|----------|
| deepseek-chat | 通用对话 | 日常对话 |
| deepseek-coder | 编码专家 | 代码生成 |

### 4.4 智谱 GLM (Zhipu)

| 模型 ID | 说明 | 适用场景 |
|---------|------|----------|
| glm-4-flash | 快速模型 | 日常对话、快速响应 |
| glm-4-plus | 高级模型 | 复杂推理 |
| glm-4-airx | 轻量模型 | 简单任务 |

---

## 5. 配置示例

### 5.1 Kimi Code 配置

```
服务商: kimi
模型 ID: kimi-k2-turbo
显示名称: Kimi K2 Turbo
API Key: 你的 Kimi API Key
API 协议: OpenAI
Base URL: https://api.kimi.com/coding/v1
```

### 5.2 百炼 Qwen 配置

```
服务商: qwen
模型 ID: qwen-plus
显示名称: 通义千问 Plus
API Key: 你的百炼 API Key
API 协议: OpenAI
Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1
```

### 5.3 DeepSeek 配置

```
服务商: deepseek
模型 ID: deepseek-chat
显示名称: DeepSeek Chat
API Key: 你的 DeepSeek API Key
API 协议: OpenAI
Base URL: https://api.deepseek.com/v1
```

### 5.4 本地 Ollama 配置

```
服务商: local
模型 ID: llama3.2
显示名称: Llama 3.2 Local
API Key: (留空)
API 协议: OpenAI
Base URL: http://localhost:11434/v1
```

---

## 6. 常见问题

### Q: 如何获取 API Key？

| Provider | 获取方式 |
|----------|----------|
| Kimi | 访问 [kimi.com/code](https://kimi.com/code) 注册 |
| Qwen | 访问 [百炼平台](https://bailian.console.aliyun.com/) |
| DeepSeek | 访问 [platform.deepseek.com](https://platform.deepseek.com/) |
| Zhipu | 访问 [open.bigmodel.cn](https://open.bigmodel.cn/) |
| OpenAI | 访问 [platform.openai.com](https://platform.openai.com/) |

### Q: API Key 存储在哪里？

API Key 存储在浏览器的 localStorage 中，不会上传到服务器。

### Q: 如何切换模型？

在"模型与 API"页面，点击模型旁边的"设为默认"按钮。

### Q: 配置后没有生效？

1. 确保点击了"设为默认"
2. 检查 API Key 是否正确
3. 重新连接（点击"重新连接"按钮）

### Q: 显示"请先在模型与 API 设置页面配置模型"？

你需要先添加至少一个自定义模型并设为默认，才能开始对话。

---

## 7. 架构说明

### 7.1 数据流

```
UI 配置 (localStorage)
        │
        ▼
connectionStore.getDefaultModelConfig()
        │
        ▼
KernelClient.setConfig()
        │
        ▼
Tauri 命令: kernel_init()
        │
        ▼
zclaw-kernel::Kernel::boot()
        │
        ▼
LLM Driver (Kimi/Qwen/DeepSeek/...)
```

### 7.2 关键文件

| 文件 | 职责 |
|------|------|
| `desktop/src/components/Settings/ModelsAPI.tsx` | UI 配置组件 |
| `desktop/src/store/connectionStore.ts` | 读取配置并传递给 Kernel |
| `desktop/src/lib/kernel-client.ts` | Tauri 命令客户端 |
| `desktop/src-tauri/src/kernel_commands.rs` | Rust 命令实现 |
| `crates/zclaw-kernel/src/config.rs` | Kernel 配置结构 |

---

## 更新历史

| 日期 | 变更 |
|------|------|
| 2026-03-22 | 更新为 UI 配置方式，移除 TOML 文件配置 |
| 2026-03-17 | 初始版本 |