zclaw_openfang/docs/setup/OPENFANG-SETUP.md

# 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