iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

release(v0.2.0): streaming, MCP protocol, Browser Hand, security enhancements

Browse Source 
## 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>
This commit is contained in:
iven
2026-03-24 03:24:24 +08:00
parent e49ba4460b
commit 3ff08faa56
78 changed files with 29575 additions and 1682 deletions
Download Patch File Download Diff File Expand all files Collapse all files

389
docs/knowledge-base/configuration.md
View File

@@ -1,302 +1,230 @@
# OpenFang 配置指南
# ZCLAW 模型配置指南
> 记录 OpenFang 配置文件位置、格式和最佳实践。
> 讌**重要变更**: ZCLAW 现在使用 UI 配置模型，不再需要编辑配置文件。
---
## 1. 配置文件位置
## 1. 配置方式
### 1.1 UI 配置（推荐）
在 ZCLAW 桌面应用中直接配置模型：
1. 打开应用，点击设置图标 ⚙️
2. 进入"模型与 API"页面
3. 点击"添加自定义模型"
4. 填写配置信息
5. 点击"设为默认"
### 1.2 配置存储位置
配置保存在浏览器的 localStorage 中：
```
~/.openfang/
├── config.toml # 主配置文件（启动时读取）
├── .env # API Key 环境变量
├── secrets.env # 敏感信息（可选）
├── daemon.json # 守护进程状态
└── data/
└── openfang.db # SQLite 数据库（持久化配置）
localStorage Key: zclaw-custom-models
```
---
## 2. 主配置文件 (config.toml)
## 2. 支持的 Provider
### 智谱 (Zhipu) 配置
### 2.1 国内 Provider
```toml
[default_model]
provider = "zhipu"
model = "glm-4-flash"
api_key_env = "ZHIPU_API_KEY"
| 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 |
[kernel]
data_dir = "C:\\Users\\szend\\.openfang\\data"
### 2.2 国际 Provider
[memory]
decay_rate = 0.05
```
| 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 |
### 百炼 (Bailian) 配置
### 2.3 本地 Provider
```toml
[default_model]
provider = "bailian"
model = "qwen3.5-plus"
api_key_env = "BAILIAN_API_KEY"
[kernel]
data_dir = "C:\\Users\\szend\\.openfang\\data"
[memory]
decay_rate = 0.05
```
### 配置项说明
| 配置项 | 说明 | 示例值 |
|--------|------|--------|
| `default_model.provider` | 默认 LLM 提供商 | `zhipu`, `bailian`, `gemini` |
| `default_model.model` | 默认模型名称 | `glm-4-flash`, `qwen3.5-plus` |
| `default_model.api_key_env` | API Key 环境变量名 | `ZHIPU_API_KEY` |
| `kernel.data_dir` | 数据目录 | `~/.openfang/data` |
| `memory.decay_rate` | 记忆衰减率 | `0.05` |
| Provider | 名称 | Base URL | 说明 |
|----------|------|----------|------|
| local | Ollama | `http://localhost:11434/v1` | Ollama 本地 |
| local | LM Studio | `http://localhost:1234/v1` | LM Studio 本地 |
---
## 3. API Key 配置
## 3. UI 配置步骤
### 方式 1: .env 文件（推荐）
### 3.1 添加模型
```bash
# ~/.openfang/.env
ZHIPU_API_KEY=sk-sp-xxxxx
BAILIAN_API_KEY=sk-sp-xxxxx
GEMINI_API_KEY=your_gemini_key
DEEPSEEK_API_KEY=your_deepseek_key
OPENAI_API_KEY=your_openai_key
GROQ_API_KEY=your_groq_key
```
在"模型与 API"页面：
### 方式 2: secrets.env 文件
1. **服务商**: 从下拉列表选择 Provider
2. **模型 ID**: 填写模型标识符（如 `kimi-k2-turbo`、`qwen-plus`）
3. **显示名称**: 可选，用于界面显示
4. **API Key**: 填写你的 API 密钥
5. **API 协议**: 选择 OpenAI（大多数 Provider）或 Anthropic
6. **Base URL**: 可选，使用自定义 API 端点
```bash
# ~/.openfang/secrets.env
ZHIPU_API_KEY=sk-sp-xxxxx
BAILIAN_API_KEY=sk-sp-xxxxx
```
### 3.2 设为默认
### 方式 3: 通过 API 设置
点击模型列表中的"设为默认"按钮。
```bash
# 设置智谱密钥
curl -X POST http://127.0.0.1:50051/api/providers/zhipu/key \
-H "Content-Type: application/json" \
-d '{"key":"your-zhipu-api-key"}'
### 3.3 修改配置
# 设置百炼密钥
curl -X POST http://127.0.0.1:50051/api/providers/bailian/key \
-H "Content-Type: application/json" \
-d '{"key":"your-bailian-api-key"}'
```
### 方式 4: 启动时指定环境变量
```bash
# Windows PowerShell
$env:ZHIPU_API_KEY = "your_key"
./openfang.exe start
# Linux/macOS
ZHIPU_API_KEY=sk-sp-xxx ./openfang start
```
点击"编辑"按钮修改已有配置。
---
## 4. 支持的 Provider
## 4. 可用模型
### 4.1 国内 Provider
### 4.1 Kimi Code
| Provider | 环境变量 | Base URL | 说明 |
|----------|----------|----------|------|
| zhipu | `ZHIPU_API_KEY` | `https://open.bigmodel.cn/api/paas/v4` | 智谱 GLM |
| zhipu_coding | `ZHIPU_API_KEY` | `https://open.bigmodel.cn/api/coding/paas/v4` | 智谱 CodeGeeX |
| bailian | `BAILIAN_API_KEY` | `https://coding.dashscope.aliyuncs.com/v1` | 百炼 Coding Plan |
| qwen | `DASHSCOPE_API_KEY` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | 通义千问 |
| volcengine | `VOLCENGINE_API_KEY` | `https://ark.cn-beijing.volces.com/api/v3` | 火山引擎 Doubao |
| moonshot | `MOONSHOT_API_KEY` | `https://api.moonshot.ai/v1` | Moonshot Kimi |
| deepseek | `DEEPSEEK_API_KEY` | `https://api.deepseek.com/v1` | DeepSeek |
| 模型 ID | 说明 | 适用场景 |
|---------|------|----------|
| kimi-k2-turbo | 快速模型 | 日常对话、快速响应 |
| kimi-k2-pro | 高级模型 | 复杂推理、深度分析 |
### 4.2 国际 Provider
### 4.2 百炼/通义千问 (Qwen)
| Provider | 环境变量 | Base URL | 说明 |
|----------|----------|----------|------|
| openai | `OPENAI_API_KEY` | `https://api.openai.com/v1` | OpenAI GPT |
| anthropic | `ANTHROPIC_API_KEY` | `https://api.anthropic.com` | Anthropic Claude |
| gemini | `GEMINI_API_KEY` | `https://generativelanguage.googleapis.com` | Google Gemini |
| groq | `GROQ_API_KEY` | `https://api.groq.com/openai/v1` | Groq |
| mistral | `MISTRAL_API_KEY` | `https://api.mistral.ai/v1` | Mistral AI |
| xai | `XAI_API_KEY` | `https://api.x.ai/v1` | xAI Grok |
| 模型 ID | 说明 | 适用场景 |
|---------|------|----------|
| qwen-turbo | 快速模型 | 日常对话 |
| qwen-plus | 通用模型 | 复杂任务 |
| qwen-max | 高级模型 | 深度分析 |
| qwen-coder-plus | 编码专家 | 代码生成 |
### 4.3 本地 Provider
### 4.3 DeepSeek
| Provider | 环境变量 | Base URL | 说明 |
|----------|----------|----------|------|
| ollama | - | `http://localhost:11434/v1` | Ollama 本地 |
| vllm | - | `http://localhost:8000/v1` | vLLM 本地 |
| lmstudio | - | `http://localhost:1234/v1` | LM Studio 本地 |
| 模型 ID | 说明 | 适用场景 |
|---------|------|----------|
| deepseek-chat | 通用对话 | 日常对话 |
| deepseek-coder | 编码专家 | 代码生成 |
---
## 5. 可用模型
### 智谱 (Zhipu)
### 4.4 智谱 GLM (Zhipu)
| 模型 ID | 说明 | 适用场景 |
|---------|------|----------|
| glm-4-flash | 快速模型 | 日常对话、快速响应 |
| glm-4-plus | 高级模型 | 复杂推理、深度分析 |
| glm-4 | 标准模型 | 通用场景 |
| glm-4-air | 轻量模型 | 简单任务 |
### 百炼 (Bailian)
| 模型 ID | 说明 | 适用场景 |
|---------|------|----------|
| qwen3.5-plus | 通用对话 | 日常对话 |
| qwen3-coder-next | 编码专家 | 代码生成 |
| glm-5-bailian | GLM-5 | 通用场景 |
| minimax-m2.5-bailian | 支持视觉 | 多模态任务 |
| kimi-k2.5-bailian | Kimi K2.5 | 长文本处理 |
### 其他推荐模型
| Provider | 模型 ID | 适用场景 |
|----------|---------|----------|
| gemini | gemini-2.5-flash | 开发任务 |
| deepseek | deepseek-chat | 快速响应 |
| groq | llama-3.1-70b | 开源模型 |
| glm-4-plus | 高级模型 | 复杂推理 |
| glm-4-airx | 轻量模型 | 简单任务 |
---
## 6. 快速切换 Provider
## 5. 配置示例
### 方法 A: 修改 config.toml
### 5.1 Kimi Code 配置
```toml
# 切换到智谱
[default_model]
provider = "zhipu"
model = "glm-4-flash"
api_key_env = "ZHIPU_API_KEY"
# 切换到百炼
[default_model]
provider = "bailian"
model = "qwen3.5-plus"
api_key_env = "BAILIAN_API_KEY"
```
服务商: kimi
模型 ID: kimi-k2-turbo
显示名称: Kimi K2 Turbo
API Key: 你的 Kimi API Key
API 协议: OpenAI
Base URL: https://api.kimi.com/coding/v1
```
**重要**: 修改后必须完全重启 OpenFang！
### 5.2 百炼 Qwen 配置
### 方法 B: 创建不同配置的 Agent
```
服务商: qwen
模型 ID: qwen-plus
显示名称: 通义千问 Plus
API Key: 你的百炼 API Key
API 协议: OpenAI
Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1
```
```bash
# 创建使用智谱的 Agent
curl -X POST http://127.0.0.1:50051/api/agents \
-H "Content-Type: application/json" \
-d '{"manifest_toml": "name = \"Zhipu Agent\"\nmodel_provider = \"zhipu\"\nmodel_name = \"glm-4-flash\""}'
### 5.3 DeepSeek 配置
# 创建使用百炼的 Agent
curl -X POST http://127.0.0.1:50051/api/agents \
-H "Content-Type: application/json" \
-d '{"manifest_toml": "name = \"Bailian Agent\"\nmodel_provider = \"bailian\"\nmodel_name = \"qwen3.5-plus\""}'
```
服务商: 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
```
---
## 7. 配置验证
## 6. 常见问题
### 检查当前配置
### Q: 如何获取 API Key？
```bash
# 检查 API 返回的配置
curl -s http://127.0.0.1:50051/api/config
| 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/) |
# 检查状态
curl -s http://127.0.0.1:50051/api/status | grep -E "default_provider|default_model"
### Q: API Key 存储在哪里？
# 检查所有 Provider 状态
curl -s http://127.0.0.1:50051/api/providers | grep -E "id|auth_status"
```
API Key 存储在浏览器的 localStorage 中，不会上传到服务器。
### 检查 Agent 配置
### Q: 如何切换模型？
```bash
# 列出所有 Agent 及其 Provider
curl -s http://127.0.0.1:50051/api/agents | grep -E "name|model_provider|ready"
```
在"模型与 API"页面，点击模型旁边的"设为默认"按钮。
### 测试聊天
### Q: 配置后没有生效？
```bash
# 测试 Agent 是否能正常响应
curl -X POST "http://127.0.0.1:50051/api/agents/{agentId}/message" \
-H "Content-Type: application/json" \
-d '{"message":"Hello"}'
```
1. 确保点击了"设为默认"
2. 检查 API Key 是否正确
3. 重新连接（点击"重新连接"按钮）
### Q: 显示"请先在模型与 API 设置页面配置模型"？
你需要先添加至少一个自定义模型并设为默认，才能开始对话。
---
## 8. 重要注意事项
## 7. 架构说明
### 8.1 配置热重载限制
### 7.1 数据流
**关键**: OpenFang 将配置持久化在 SQLite 数据库中，`config.toml` 只在启动时读取。
- `/api/config/reload` **不会**更新已持久化的默认模型配置
- 修改 `config.toml` 后必须**完全重启 OpenFang**
```bash
# 正确的重启方式
curl -X POST http://127.0.0.1:50051/api/shutdown
# 然后手动启动
./openfang.exe start
```
UI 配置 (localStorage)
│
▼
connectionStore.getDefaultModelConfig()
│
▼
KernelClient.setConfig()
│
▼
Tauri 命令: kernel_init()
│
▼
zclaw-kernel::Kernel::boot()
│
▼
LLM Driver (Kimi/Qwen/DeepSeek/...)
```
### 8.2 Agent 创建时的 Provider
### 7.2 关键文件
如果创建 Agent 时没有指定 Provider，OpenFang 会使用数据库中存储的默认配置，而不是 `config.toml` 中的配置。
### 8.3 API Key 验证
确保 API Key 格式正确：
- 智谱: `sk-sp-xxxxx` 或 `xxxxx.xxxxx.xxxxx`
- 百炼: `sk-xxxxx`
---
## 9. 常见问题
### Q: 修改 config.toml 后配置没有生效？
**A**: 必须完全重启 OpenFang，热重载不会更新持久化配置。
### Q: Agent 显示 ready: false？
**A**: 检查 Agent 使用的 Provider 是否配置了 API Key：
```bash
curl -s http://127.0.0.1:50051/api/agents | grep -E "auth_status|ready"
```
### Q: 如何查看所有可用的 Provider？
**A**:
```bash
curl -s http://127.0.0.1:50051/api/providers
```
### Q: 如何在不重启的情况下切换 Agent？
**A**: 前端可以通过选择不同 Provider 的 Agent 来切换，无需重启。
| 文件 | 职责 |
|------|------|
| `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 配置结构 |
---
@@ -304,4 +232,5 @@ curl -s http://127.0.0.1:50051/api/providers
| 日期 | 变更 |
|------|------|
| 2026-03-17 | 初始版本，记录配置热重载限制 |
| 2026-03-22 | 更新为 UI 配置方式，移除 TOML 文件配置 |
| 2026-03-17 | 初始版本 |