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>
This commit is contained in:
iven
@@ -1,512 +0,0 @@
|
||||
# OpenFang Kernel 配置指南
|
||||
|
||||
> 本文档帮助你正确配置 OpenFang Kernel，作为 ZCLAW 的后端执行引擎。
|
||||
|
||||
## 概述
|
||||
|
||||
OpenFang 是一个用 Rust 构建的生产级 Agent 操作系统（Agent Operating System）。与传统的聊天机器人框架不同，OpenFang 采用"主动执行"范式：Agent 能够按计划自主唤醒、完成任务并报告结果，而无需用户持续提示。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **高性能**：冷启动 < 200ms，空闲内存 ~40MB
|
||||
- **Hands 机制**：7 个预构建的自主能力包，即插即用
|
||||
- **40+ 渠道适配器**：支持 Telegram、Discord、飞书、钉钉等
|
||||
- **27+ LLM 提供商**：包括中文模型（智谱、通义千问、Kimi、MiniMax）
|
||||
- **16 层安全防护**：WASM 沙箱、Merkle 审计追踪、Ed25519 签名等
|
||||
|
||||
---
|
||||
|
||||
## 前置要求
|
||||
|
||||
### 系统要求
|
||||
|
||||
| 要求 | 最低配置 | 推荐配置 |
|
||||
|------|----------|----------|
|
||||
| **操作系统** | Windows 10 / macOS 10.15 / Linux | Windows 11 / macOS 13+ / Ubuntu 22.04+ |
|
||||
| **CPU 架构** | x86_64 或 ARM64 | x86_64 |
|
||||
| **内存** | 64MB | 256MB+ |
|
||||
| **磁盘空间** | 100MB | 500MB+ |
|
||||
|
||||
### 依赖项
|
||||
|
||||
OpenFang 是一个独立的单二进制文件（~32MB），无外部依赖。但以下工具可能对某些功能必要：
|
||||
|
||||
- **FFmpeg**：视频处理 Hand (Clip) 需要
|
||||
- **yt-dlp**：YouTube 视频下载需要
|
||||
|
||||
---
|
||||
|
||||
## 安装步骤
|
||||
|
||||
### 方式一：官方安装脚本（推荐）
|
||||
|
||||
#### Windows
|
||||
|
||||
```powershell
|
||||
# 使用 PowerShell
|
||||
iwr -useb https://openfang.sh/install.ps1 | iex
|
||||
```
|
||||
|
||||
#### macOS / Linux
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openfang.sh/install.sh | bash
|
||||
```
|
||||
|
||||
### 方式二：手动下载
|
||||
|
||||
1. 访问 [GitHub Releases](https://github.com/RightNow-AI/openfang/releases)
|
||||
2. 下载对应平台的二进制文件
|
||||
3. 将文件放入 PATH 目录
|
||||
|
||||
#### Windows
|
||||
|
||||
```powershell
|
||||
# 下载后移动到用户目录
|
||||
move openfang.exe C:\Users\<你的用户名>\.local\bin\
|
||||
```
|
||||
|
||||
#### macOS / Linux
|
||||
|
||||
```bash
|
||||
chmod +x openfang
|
||||
sudo mv openfang /usr/local/bin/
|
||||
```
|
||||
|
||||
### 方式三：从源码编译
|
||||
|
||||
```bash
|
||||
git clone https://github.com/RightNow-AI/openfang.git
|
||||
cd openfang
|
||||
cargo build --release
|
||||
# 编译产物位于 target/release/openfang
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置说明
|
||||
|
||||
### 1. 初始化配置
|
||||
|
||||
首次使用需要初始化配置文件：
|
||||
|
||||
```bash
|
||||
openfang init
|
||||
```
|
||||
|
||||
这将在 `~/.openfang/` 目录下创建以下结构：
|
||||
|
||||
```
|
||||
~/.openfang/
|
||||
├── config.toml # 主配置文件
|
||||
├── openfang.db # SQLite 数据库
|
||||
├── data/ # 数据目录
|
||||
│ ├── agents/ # Agent 配置
|
||||
│ ├── skills/ # 自定义技能
|
||||
│ └── hands/ # Hand 配置
|
||||
└── logs/ # 日志文件
|
||||
```
|
||||
|
||||
### 2. 配置文件结构
|
||||
|
||||
编辑 `~/.openfang/config.toml`：
|
||||
|
||||
```toml
|
||||
# OpenFang 主配置文件
|
||||
|
||||
[general]
|
||||
# 默认语言
|
||||
language = "zh-CN"
|
||||
# 日志级别: trace, debug, info, warn, error
|
||||
log_level = "info"
|
||||
# 数据目录
|
||||
data_dir = "~/.openfang/data"
|
||||
|
||||
[model]
|
||||
# 默认模型提供商
|
||||
provider = "zhipu"
|
||||
# 默认模型
|
||||
model = "glm-4-flash"
|
||||
# API Key 环境变量名（不直接写 Key）
|
||||
api_key_env = "ZHIPU_API_KEY"
|
||||
# 可选：自定义 API 端点
|
||||
# base_url = "https://open.bigmodel.cn/api/paas/v4"
|
||||
|
||||
[api]
|
||||
# API 服务端口
|
||||
port = 50051
|
||||
# 绑定地址（0.0.0.0 允许外部访问）
|
||||
bind = "127.0.0.1"
|
||||
# 启用 OpenAI 兼容 API
|
||||
openai_compat = true
|
||||
|
||||
[security]
|
||||
# 启用能力门控
|
||||
capability_gates = true
|
||||
# 启用审计追踪
|
||||
audit_trail = true
|
||||
# 启用 WASM 沙箱
|
||||
wasm_sandbox = true
|
||||
|
||||
[memory]
|
||||
# 会话保留天数
|
||||
session_retention_days = 30
|
||||
# 向量嵌入模型
|
||||
embedding_model = "text-embedding-3-small"
|
||||
```
|
||||
|
||||
### 3. 配置 API Key
|
||||
|
||||
**重要**：永远不要在配置文件中直接写入 API Key，使用环境变量：
|
||||
|
||||
#### Windows (PowerShell)
|
||||
|
||||
```powershell
|
||||
# 临时设置（当前会话）
|
||||
$env:ZHIPU_API_KEY = "your-api-key-here"
|
||||
$env:DASHSCOPE_API_KEY = "your-dashscope-key" # 通义千问
|
||||
$env:MOONSHOT_API_KEY = "your-moonshot-key" # Kimi
|
||||
|
||||
# 永久设置（写入配置文件）
|
||||
[Environment]::SetEnvironmentVariable("ZHIPU_API_KEY", "your-api-key", "User")
|
||||
```
|
||||
|
||||
#### macOS / Linux
|
||||
|
||||
```bash
|
||||
# 临时设置（当前会话）
|
||||
export ZHIPU_API_KEY="your-api-key-here"
|
||||
export DASHSCOPE_API_KEY="your-dashscope-key"
|
||||
export MOONSHOT_API_KEY="your-moonshot-key"
|
||||
|
||||
# 永久设置（写入 shell 配置文件）
|
||||
echo 'export ZHIPU_API_KEY="your-api-key"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
### 4. 配置中文模型
|
||||
|
||||
在 `config.toml` 中配置中文模型提供商：
|
||||
|
||||
```toml
|
||||
# 智谱 GLM
|
||||
[model.zhipu]
|
||||
provider = "zhipu"
|
||||
model = "glm-4-flash"
|
||||
api_key_env = "ZHIPU_API_KEY"
|
||||
base_url = "https://open.bigmodel.cn/api/paas/v4"
|
||||
|
||||
# 通义千问
|
||||
[model.qwen]
|
||||
provider = "openai-compat"
|
||||
model = "qwen-turbo"
|
||||
api_key_env = "DASHSCOPE_API_KEY"
|
||||
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||||
|
||||
# Kimi (Moonshot)
|
||||
[model.kimi]
|
||||
provider = "openai-compat"
|
||||
model = "moonshot-v1-8k"
|
||||
api_key_env = "MOONSHOT_API_KEY"
|
||||
base_url = "https://api.moonshot.cn/v1"
|
||||
|
||||
# MiniMax
|
||||
[model.minimax]
|
||||
provider = "openai-compat"
|
||||
model = "abab6.5-chat"
|
||||
api_key_env = "MINIMAX_API_KEY"
|
||||
base_url = "https://api.minimax.chat/v1"
|
||||
```
|
||||
|
||||
### 5. 启动服务
|
||||
|
||||
#### 前台运行（调试用）
|
||||
|
||||
```bash
|
||||
openfang start
|
||||
```
|
||||
|
||||
#### 后台守护进程
|
||||
|
||||
```bash
|
||||
# 启动守护进程
|
||||
openfang daemon start
|
||||
|
||||
# 查看状态
|
||||
openfang status
|
||||
|
||||
# 停止守护进程
|
||||
openfang daemon stop
|
||||
```
|
||||
|
||||
#### 检查健康状态
|
||||
|
||||
```bash
|
||||
openfang doctor
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 与 ZCLAW 集成
|
||||
|
||||
### 配置 ZCLAW 连接 OpenFang
|
||||
|
||||
编辑 ZCLAW 配置文件 `~/.zclaw/config.toml`：
|
||||
|
||||
```toml
|
||||
[gateway]
|
||||
# OpenFang API 端点
|
||||
endpoint = "http://127.0.0.1:50051"
|
||||
# WebSocket 端点
|
||||
ws_endpoint = "ws://127.0.0.1:50051/ws"
|
||||
# 连接超时（秒）
|
||||
timeout = 30
|
||||
|
||||
[model]
|
||||
# 使用 OpenFang 的模型路由
|
||||
use_gateway_routing = true
|
||||
```
|
||||
|
||||
### 验证连接
|
||||
|
||||
```bash
|
||||
# 启动 OpenFang
|
||||
openfang start
|
||||
|
||||
# 在另一个终端启动 ZCLAW
|
||||
cd desktop && pnpm tauri dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 1. 端口被占用
|
||||
|
||||
**错误信息**：`Address already in use: 0.0.0.0:50051`
|
||||
|
||||
**解决方案**：
|
||||
|
||||
```bash
|
||||
# 查找占用端口的进程
|
||||
# Windows
|
||||
netstat -ano | findstr :50051
|
||||
|
||||
# macOS / Linux
|
||||
lsof -i :50051
|
||||
|
||||
# 修改配置文件中的端口
|
||||
[api]
|
||||
port = 50052
|
||||
```
|
||||
|
||||
### 2. API Key 无效
|
||||
|
||||
**错误信息**：`Authentication failed` 或 `Invalid API key`
|
||||
|
||||
**排查步骤**：
|
||||
|
||||
1. 确认环境变量已设置：
|
||||
```bash
|
||||
# Windows
|
||||
echo $env:ZHIPU_API_KEY
|
||||
|
||||
# macOS / Linux
|
||||
echo $ZHIPU_API_KEY
|
||||
```
|
||||
|
||||
2. 确认 API Key 格式正确（无多余空格或引号）
|
||||
|
||||
3. 确认 API Key 未过期
|
||||
|
||||
### 3. 内存不足
|
||||
|
||||
**错误信息**：`Out of memory` 或系统卡顿
|
||||
|
||||
**解决方案**：
|
||||
|
||||
1. 关闭不必要的服务
|
||||
2. 降低并发 Agent 数量
|
||||
3. 增加系统交换空间
|
||||
|
||||
### 4. 模型调用失败
|
||||
|
||||
**错误信息**：`Model not found` 或 `Provider error`
|
||||
|
||||
**排查步骤**：
|
||||
|
||||
1. 检查模型名称是否正确
|
||||
2. 确认 API 端点可访问
|
||||
3. 检查网络连接和代理设置
|
||||
|
||||
```bash
|
||||
# 测试 API 连通性
|
||||
curl -I https://open.bigmodel.cn/api/paas/v4/models
|
||||
```
|
||||
|
||||
### 5. 中文乱码
|
||||
|
||||
**解决方案**：
|
||||
|
||||
确保系统 locale 设置正确：
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
chcp 65001
|
||||
|
||||
# macOS / Linux
|
||||
export LANG=zh_CN.UTF-8
|
||||
```
|
||||
|
||||
### 6. 从 OpenClaw 迁移
|
||||
|
||||
如果你之前使用 OpenClaw，可以使用迁移工具：
|
||||
|
||||
```bash
|
||||
# 迁移所有内容：代理、记忆、技能、配置
|
||||
openfang migrate --from openclaw
|
||||
|
||||
# 从特定路径迁移
|
||||
openfang migrate --from openclaw --path ~/.openclaw
|
||||
|
||||
# 先试运行查看变更
|
||||
openfang migrate --from openclaw --dry-run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 进阶配置
|
||||
|
||||
### 配置 Hands
|
||||
|
||||
Hands 是 OpenFang 的核心创新，每个 Hand 是一个预构建的自主能力包：
|
||||
|
||||
```toml
|
||||
# ~/.openfang/data/hands/researcher.toml
|
||||
|
||||
[hand]
|
||||
name = "researcher"
|
||||
description = "深度研究助手"
|
||||
enabled = true
|
||||
|
||||
[hand.schedule]
|
||||
# 执行模式：continuous, periodic, manual
|
||||
mode = "manual"
|
||||
# 定时执行（cron 表达式）
|
||||
# cron = "0 9 * * *" # 每天早上 9 点
|
||||
|
||||
[hand.config]
|
||||
# 最大搜索深度
|
||||
max_depth = 5
|
||||
# 输出格式
|
||||
output_format = "markdown"
|
||||
# 引用格式
|
||||
citation_style = "apa"
|
||||
```
|
||||
|
||||
### 配置 MCP 服务器
|
||||
|
||||
```toml
|
||||
# ~/.openfang/config.toml
|
||||
|
||||
[[mcp_servers]]
|
||||
name = "filesystem"
|
||||
command = "mcp-filesystem"
|
||||
args = ["--root", "/path/to/allowed/dir"]
|
||||
|
||||
[[mcp_servers]]
|
||||
name = "postgres"
|
||||
command = "mcp-postgres"
|
||||
env = { DATABASE_URL = "postgresql://localhost/mydb" }
|
||||
```
|
||||
|
||||
### 配置渠道适配器
|
||||
|
||||
```toml
|
||||
# ~/.openfang/config.toml
|
||||
|
||||
[[channels]]
|
||||
type = "feishu"
|
||||
enabled = true
|
||||
|
||||
[channels.config]
|
||||
app_id = "cli_xxx"
|
||||
app_secret_env = "FEISHU_APP_SECRET"
|
||||
# 加密密钥（可选）
|
||||
encrypt_key_env = "FEISHU_ENCRYPT_KEY"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 性能调优
|
||||
|
||||
### 内存优化
|
||||
|
||||
```toml
|
||||
[memory]
|
||||
# 会话压缩阈值（token 数）
|
||||
compaction_threshold = 80000
|
||||
# 保留最近消息数
|
||||
keep_recent = 20
|
||||
# 向量嵌入缓存大小
|
||||
embedding_cache_size = 1000
|
||||
```
|
||||
|
||||
### 并发优化
|
||||
|
||||
```toml
|
||||
[runtime]
|
||||
# 最大并发工具调用
|
||||
max_concurrent_tools = 10
|
||||
# 工具执行超时（秒）
|
||||
tool_timeout = 60
|
||||
# Agent 循环最大迭代
|
||||
max_iterations = 50
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 日志与监控
|
||||
|
||||
### 查看日志
|
||||
|
||||
```bash
|
||||
# 实时日志
|
||||
openfang logs -f
|
||||
|
||||
# 按级别过滤
|
||||
openfang logs --level error
|
||||
|
||||
# 按时间范围
|
||||
openfang logs --since "2024-01-01" --until "2024-01-02"
|
||||
```
|
||||
|
||||
### 监控指标
|
||||
|
||||
```bash
|
||||
# 系统状态
|
||||
openfang status
|
||||
|
||||
# 详细健康检查
|
||||
openfang doctor --verbose
|
||||
|
||||
# 使用统计
|
||||
openfang usage --daily
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相关链接
|
||||
|
||||
- [OpenFang 官方文档](https://openfang.sh/)
|
||||
- [GitHub 仓库](https://github.com/RightNow-AI/openfang)
|
||||
- [中文模型配置](./chinese-models.md)
|
||||
- [ZCLAW 主文档](../../README.md)
|
||||
|
||||
---
|
||||
|
||||
## 获取帮助
|
||||
|
||||
- **命令行帮助**：`openfang --help` 或 `openfang <command> --help`
|
||||
- **GitHub Issues**：https://github.com/RightNow-AI/openfang/issues
|
||||
- **社区讨论**：https://deepseek.club/t/topic/996
|
||||
Reference in New Issue
Block a user