iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
worktree-saas-backend
zclaw_openfang/docs/knowledge-base/configuration.md
iven 3ff08faa56 release(v0.2.0): streaming, MCP protocol, Browser Hand, security enhancements 
## 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>
2026-03-24 03:24:24 +08:00

5.7 KiB
Raw Permalink Blame History

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 注册
Qwen 访问 百炼平台
DeepSeek 访问 platform.deepseek.com
Zhipu 访问 open.bigmodel.cn
OpenAI 访问 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 初始版本