3ff08faa56
## Major Features ### Streaming Response System - Implement LlmDriver trait with `stream()` method returning async Stream - Add SSE parsing for Anthropic and OpenAI API streaming - Integrate Tauri event system for frontend streaming (`stream:chunk` events) - Add StreamChunk types: Delta, ToolStart, ToolEnd, Complete, Error ### MCP Protocol Implementation - Add MCP JSON-RPC 2.0 types (mcp_types.rs) - Implement stdio-based MCP transport (mcp_transport.rs) - Support tool discovery, execution, and resource operations ### Browser Hand Implementation - Complete browser automation with Playwright-style actions - Support Navigate, Click, Type, Scrape, Screenshot, Wait actions - Add educational Hands: Whiteboard, Slideshow, Speech, Quiz ### Security Enhancements - Implement command whitelist/blacklist for shell_exec tool - Add SSRF protection with private IP blocking - Create security.toml configuration file ## Test Improvements - Fix test import paths (security-utils, setup) - Fix vi.mock hoisting issues with vi.hoisted() - Update test expectations for validateUrl and sanitizeFilename - Add getUnsupportedLocalGatewayStatus mock ## Documentation Updates - Update architecture documentation - Improve configuration reference - Add quick-start guide updates Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
237 lines
5.7 KiB
Markdown
237 lines
5.7 KiB
Markdown
# 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 | 初始版本 |
|