docs: add setup guides and error notification component

- Add OpenFang Kernel configuration guide (docs/setup/OPENFANG-SETUP.md) - Add Chinese models configuration guide (docs/setup/chinese-models.md) - Add quick start guide (docs/quick-start.md) - Add quick start scripts for Windows and Linux/macOS - Add ErrorNotification component for centralized error display These additions help users: - Quickly set up development environment - Configure OpenFang backend correctly - Configure Chinese LLM providers (GLM, Qwen, Kimi, MiniMax) - See error notifications in a consistent UI Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-21 00:17:44 +08:00
parent c5d91cf9f0
commit d3a4de2480
6 changed files with 1931 additions and 0 deletions
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -0,0 +1,233 @@
+# ZCLAW 快速启动指南
+
+> 5 分钟内启动 ZCLAW 开发环境
+
+---
+
+## 前置要求
+
+| 工具 | 最低版本 | 检查命令 |
+|------|----------|----------|
+| Node.js | 18.x | `node -v` |
+| pnpm | 8.x | `pnpm -v` |
+| Rust | 1.70+ | `rustc --version` |
+| OpenFang | - | `openfang --version` |
+
+---
+
+## 快速启动
+
+### Windows 用户
+
+```powershell
+# 在项目根目录执行
+.\scripts\quick-start-dev.ps1
+```
+
+### Linux/macOS 用户
+
+```bash
+# 在项目根目录执行
+./scripts/quick-start.sh
+```
+
+---
+
+## 手动启动步骤
+
+### 1. 安装依赖
+
+```bash
+# 根目录依赖
+pnpm install
+
+# 桌面端依赖
+cd desktop && pnpm install && cd ..
+```
+
+### 2. 启动 OpenFang 后端
+
+```bash
+# 方法 A: 使用 CLI
+openfang start
+
+# 方法 B: 使用 pnpm 脚本
+pnpm gateway:start
+```
+
+验证后端运行:
+```bash
+curl http://127.0.0.1:50051/api/health
+# 应返回: {"status":"ok"}
+```
+
+### 3. 启动开发环境
+
+```bash
+# 方法 A: 一键启动（推荐）
+pnpm start:dev
+
+# 方法 B: 仅启动桌面端（需要后端已运行）
+pnpm desktop
+
+# 方法 C: 分开启动
+# 终端 1 - 启动 Gateway
+pnpm dev
+
+# 终端 2 - 启动桌面端
+pnpm desktop
+```
+
+---
+
+## 测试环境启动
+
+### 单元测试
+
+```bash
+# 运行所有单元测试
+pnpm test
+
+# 监听模式
+pnpm test:watch
+
+# 桌面端测试
+cd desktop && pnpm test
+```
+
+### E2E 测试
+
+```bash
+# 运行 E2E 测试
+pnpm test:e2e
+
+# 带界面运行
+cd desktop && pnpm test:e2e:ui
+```
+
+---
+
+## 开发端口说明
+
+| 服务 | 端口 | 说明 |
+|------|------|------|
+| OpenFang 后端 | 50051 | API 和 WebSocket 服务 |
+| Vite 开发服务器 | 1420 | 前端热重载 |
+| Tauri 窗口 | - | 桌面应用窗口 |
+
+---
+
+## 常见问题排查
+
+### Q1: 端口被占用
+
+**症状**: `Port 1420 is already in use` 或 `Port 50051 is already in use`
+
+**解决**:
+```powershell
+# Windows - 查找并终止进程
+netstat -ano | findstr "1420"
+taskkill /PID <PID> /F
+
+# Linux/macOS
+lsof -i :1420
+kill -9 <PID>
+```
+
+### Q2: 后端连接失败
+
+**症状**: `Network Error` 或 `Connection refused`
+
+**排查步骤**:
+```bash
+# 1. 检查后端是否运行
+curl http://127.0.0.1:50051/api/health
+
+# 2. 检查端口监听
+netstat -ano | findstr "50051"
+
+# 3. 重启后端
+openfang restart
+```
+
+### Q3: API Key 未配置
+
+**症状**: `Missing API key: No LLM provider configured`
+
+**解决**:
+```bash
+# 编辑配置文件
+# Windows: %USERPROFILE%\.openfang\.env
+# Linux/macOS: ~/.openfang/.env
+
+# 添加 API Key
+echo "ZHIPU_API_KEY=your_key" >> ~/.openfang/.env
+
+# 重启后端
+openfang restart
+```
+
+### Q4: Tauri 编译失败
+
+**症状**: Rust 编译错误
+
+**解决**:
+```bash
+# 更新 Rust
+rustup update
+
+# 清理并重新构建
+cd desktop/src-tauri
+cargo clean
+cargo build
+```
+
+### Q5: 依赖安装失败
+
+**症状**: pnpm install 报错
+
+**解决**:
+```bash
+# 清理缓存
+pnpm store prune
+
+# 删除 node_modules 重新安装
+rm -rf node_modules desktop/node_modules
+pnpm install
+```
+
+---
+
+## 验证清单
+
+启动成功后，验证以下功能:
+
+- [ ] 后端健康检查通过: `curl http://127.0.0.1:50051/api/health`
+- [ ] 桌面端窗口正常显示
+- [ ] 可以发送消息并获得响应
+- [ ] 可以切换 Agent
+- [ ] 可以查看设置页面
+
+---
+
+## 停止服务
+
+```bash
+# 停止所有服务
+pnpm start:stop
+
+# 或手动停止
+# Ctrl+C 终止运行中的进程
+```
+
+---
+
+## 相关文档
+
+- [完整开发文档](./DEVELOPMENT.md)
+- [故障排查指南](./knowledge-base/troubleshooting.md)
+- [配置说明](./knowledge-base/configuration.md)
+
+---
+
+**最后更新**: 2026-03-21
--- a/docs/setup/OPENFANG-SETUP.md
+++ b/docs/setup/OPENFANG-SETUP.md
@@ -0,0 +1,512 @@
+# 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
--- a/docs/setup/chinese-models.md
+++ b/docs/setup/chinese-models.md
@@ -0,0 +1,472 @@
+# 中文模型配置指南
+
+> 本文档详细介绍 OpenFang Kernel 支持的中文大语言模型，以及如何获取和配置 API Key。
+
+---
+
+## 支持的中文模型
+
+OpenFang 通过 OpenAI 兼容 API 支持所有主流中文模型提供商：
+
+| 提供商 | 模型系列 | 特点 | 定价 |
+|--------|----------|------|------|
+| **智谱 AI** | GLM-4 | 国产领先，多模态支持 | 免费 + 付费 |
+| **阿里云** | 通义千问 (Qwen) | 性价比高，企业级 | 按量计费 |
+| **月之暗面** | Kimi | 长上下文（200K） | 按量计费 |
+| **MiniMax** | 海螺 AI | 语音能力强 | 按量计费 |
+| **百度** | 文心一言 | 企业应用广泛 | 按量计费 |
+| **DeepSeek** | DeepSeek | 编程能力强，低价 | 极低价格 |
+| **百川智能** | Baichuan | 中文优化 | 按量计费 |
+| **上海 AI Lab** | 书生浦语 | 开源模型 | 免费 |
+
+---
+
+## 1. 智谱 GLM
+
+### 模型列表
+
+| 模型 | 上下文 | 特点 | 适用场景 |
+|------|--------|------|----------|
+| `glm-4-flash` | 128K | 快速响应，免费额度 | 日常对话、快速问答 |
+| `glm-4` | 128K | 旗舰模型 | 复杂任务、推理 |
+| `glm-4-plus` | 128K | 增强版 | 专业应用 |
+| `glm-4-air` | 128K | 轻量版 | 简单任务 |
+| `glm-4v` | 8K | 多模态（图像理解） | 图像分析 |
+| `glm-4-long` | 1M | 超长上下文 | 长文档处理 |
+
+### API Key 获取
+
+1. 访问 [智谱开放平台](https://open.bigmodel.cn/)
+2. 注册/登录账号
+3. 进入「API Keys」页面
+4. 点击「创建 API Key」
+
+**免费额度**：新用户赠送 1000 万 tokens
+
+### 配置示例
+
+```toml
+[model.zhipu]
+provider = "zhipu"
+model = "glm-4-flash"
+api_key_env = "ZHIPU_API_KEY"
+base_url = "https://open.bigmodel.cn/api/paas/v4"
+```
+
+```bash
+# 设置环境变量
+export ZHIPU_API_KEY="your-zhipu-api-key"
+```
+
+---
+
+## 2. 通义千问 (Qwen)
+
+### 模型列表
+
+| 模型 | 上下文 | 特点 | 适用场景 |
+|------|--------|------|----------|
+| `qwen-turbo` | 8K | 快速版 | 快速问答 |
+| `qwen-plus` | 32K | 增强版 | 复杂任务 |
+| `qwen-max` | 32K | 旗舰版 | 高质量输出 |
+| `qwen-max-longcontext` | 200K | 长上下文 | 长文档 |
+| `qwen-vl-plus` | 8K | 多模态 | 图像理解 |
+| `qwen-vl-max` | 8K | 多模态增强 | 高精度图像 |
+
+### API Key 获取
+
+1. 访问 [阿里云百炼](https://dashscope.console.aliyun.com/)
+2. 登录阿里云账号
+3. 开通「灵积模型服务」
+4. 获取 API Key
+
+**免费额度**：部分模型有免费试用
+
+### 配置示例
+
+```toml
+[model.qwen]
+provider = "openai-compat"
+model = "qwen-turbo"
+api_key_env = "DASHSCOPE_API_KEY"
+base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+```
+
+```bash
+# 设置环境变量
+export DASHSCOPE_API_KEY="your-dashscope-api-key"
+```
+
+---
+
+## 3. Kimi (Moonshot)
+
+### 模型列表
+
+| 模型 | 上下文 | 特点 | 适用场景 |
+|------|--------|------|----------|
+| `moonshot-v1-8k` | 8K | 基础版 | 日常对话 |
+| `moonshot-v1-32k` | 32K | 长上下文 | 中等文档 |
+| `moonshot-v1-128k` | 128K | 超长上下文 | 长文档分析 |
+
+### API Key 获取
+
+1. 访问 [Moonshot AI 开放平台](https://platform.moonshot.cn/)
+2. 注册/登录账号
+3. 进入「API Key 管理」
+4. 创建新的 API Key
+
+**免费额度**：新用户赠送 15 元体验金
+
+### 配置示例
+
+```toml
+[model.kimi]
+provider = "openai-compat"
+model = "moonshot-v1-8k"
+api_key_env = "MOONSHOT_API_KEY"
+base_url = "https://api.moonshot.cn/v1"
+```
+
+```bash
+# 设置环境变量
+export MOONSHOT_API_KEY="your-moonshot-api-key"
+```
+
+---
+
+## 4. MiniMax
+
+### 模型列表
+
+| 模型 | 上下文 | 特点 | 适用场景 |
+|------|--------|------|----------|
+| `abab6.5-chat` | 8K | 旗舰对话 | 通用对话 |
+| `abab6.5s-chat` | 8K | 快速版 | 快速响应 |
+| `abab6.5g-chat` | 8K | 通用版 | 平衡场景 |
+| `abab5.5-chat` | 16K | 经典版 | 日常使用 |
+| `abab5.5s-chat` | 16K | 轻量版 | 简单任务 |
+
+### API Key 获取
+
+1. 访问 [MiniMax 开放平台](https://www.minimaxi.com/)
+2. 注册/登录账号
+3. 进入「账户管理」->「API Key」
+4. 创建 API Key
+
+**注意**：MiniMax 需要同时配置 Group ID
+
+### 配置示例
+
+```toml
+[model.minimax]
+provider = "openai-compat"
+model = "abab6.5-chat"
+api_key_env = "MINIMAX_API_KEY"
+base_url = "https://api.minimax.chat/v1"
+
+[model.minimax.headers]
+# MiniMax 需要 Group ID
+"x-minimax-group-id" = "your-group-id"
+```
+
+```bash
+# 设置环境变量
+export MINIMAX_API_KEY="your-minimax-api-key"
+```
+
+---
+
+## 5. DeepSeek
+
+### 模型列表
+
+| 模型 | 上下文 | 特点 | 适用场景 |
+|------|--------|------|----------|
+| `deepseek-chat` | 64K | 通用对话 | 日常使用 |
+| `deepseek-coder` | 16K | 代码专精 | 编程任务 |
+| `deepseek-reasoner` | 64K | 深度推理 | 复杂推理 |
+
+### API Key 获取
+
+1. 访问 [DeepSeek 开放平台](https://platform.deepseek.com/)
+2. 注册/登录账号
+3. 进入「API Keys」页面
+4. 创建 API Key
+
+**定价优势**：极低价格，性价比高
+
+### 配置示例
+
+```toml
+[model.deepseek]
+provider = "openai-compat"
+model = "deepseek-chat"
+api_key_env = "DEEPSEEK_API_KEY"
+base_url = "https://api.deepseek.com"
+```
+
+```bash
+# 设置环境变量
+export DEEPSEEK_API_KEY="your-deepseek-api-key"
+```
+
+---
+
+## 6. 百度文心一言
+
+### 模型列表
+
+| 模型 | 上下文 | 特点 | 适用场景 |
+|------|--------|------|----------|
+| `ernie-4.0-8k` | 8K | 旗舰版 | 复杂任务 |
+| `ernie-3.5-8k` | 8K | 标准版 | 日常使用 |
+| `ernie-speed-8k` | 8K | 快速版 | 快速响应 |
+| `ernie-lite-8k` | 8K | 轻量版 | 简单任务 |
+
+### API Key 获取
+
+1. 访问 [百度智能云千帆平台](https://console.bce.baidu.com/qianfan/)
+2. 登录百度账号
+3. 创建应用，获取 API Key 和 Secret Key
+
+**注意**：文心一言使用 access_token 认证，需要额外处理
+
+### 配置示例
+
+```toml
+[model.wenxin]
+provider = "openai-compat"
+model = "ernie-4.0-8k"
+api_key_env = "WENXIN_ACCESS_TOKEN"
+base_url = "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions"
+```
+
+---
+
+## 7. 百川智能
+
+### 模型列表
+
+| 模型 | 上下文 | 特点 | 适用场景 |
+|------|--------|------|----------|
+| `Baichuan4` | 128K | 旗舰版 | 复杂任务 |
+| `Baichuan3-Turbo` | 32K | 快速版 | 日常使用 |
+| `Baichuan3-Turbo-128k` | 128K | 长上下文 | 长文档 |
+
+### API Key 获取
+
+1. 访问 [百川智能开放平台](https://platform.baichuan-ai.com/)
+2. 注册/登录账号
+3. 获取 API Key
+
+### 配置示例
+
+```toml
+[model.baichuan]
+provider = "openai-compat"
+model = "Baichuan4"
+api_key_env = "BAICHUAN_API_KEY"
+base_url = "https://api.baichuan-ai.com/v1"
+```
+
+---
+
+## 8. 本地模型 (Ollama)
+
+如果你想在本地运行开源中文模型：
+
+### 支持的开源模型
+
+| 模型 | 参数量 | 内存需求 | 特点 |
+|------|--------|----------|------|
+| `qwen2:7b` | 7B | 8GB | 通用对话 |
+| `qwen2:14b` | 14B | 16GB | 高质量输出 |
+| `glm4:9b` | 9B | 12GB | 智谱开源版 |
+| `deepseek-coder:6.7b` | 6.7B | 8GB | 代码专精 |
+
+### 安装 Ollama
+
+```bash
+# macOS / Linux
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Windows
+# 访问 https://ollama.com/download 下载安装包
+```
+
+### 下载模型
+
+```bash
+# 下载通义千问
+ollama pull qwen2:7b
+
+# 下载 GLM4
+ollama pull glm4:9b
+```
+
+### 配置示例
+
+```toml
+[model.ollama]
+provider = "openai-compat"
+model = "qwen2:7b"
+base_url = "http://localhost:11434/v1"
+# 本地模型无需 API Key
+api_key_env = ""
+```
+
+---
+
+## 多模型配置
+
+OpenFang 支持同时配置多个模型，并自动路由：
+
+```toml
+# ~/.openfang/config.toml
+
+[model]
+# 默认模型
+provider = "zhipu"
+model = "glm-4-flash"
+
+# 备选模型
+[[model.alternates]]
+name = "coding"
+provider = "deepseek"
+model = "deepseek-coder"
+api_key_env = "DEEPSEEK_API_KEY"
+
+[[model.alternates]]
+name = "long-context"
+provider = "kimi"
+model = "moonshot-v1-128k"
+api_key_env = "MOONSHOT_API_KEY"
+
+[[model.alternates]]
+name = "local"
+provider = "openai-compat"
+model = "qwen2:7b"
+base_url = "http://localhost:11434/v1"
+
+# 模型路由规则
+[model.routing]
+# 编程任务使用 DeepSeek Coder
+coding = ["deepseek-coder", "glm-4"]
+# 长文档使用 Kimi
+long_context = ["moonshot-v1-128k", "glm-4-long"]
+# 快速响应使用 Flash 或本地模型
+fast = ["glm-4-flash", "qwen2:7b"]
+```
+
+---
+
+## 价格对比
+
+| 模型 | 输入价格 (元/百万 tokens) | 输出价格 (元/百万 tokens) |
+|------|---------------------------|---------------------------|
+| GLM-4-Flash | 免费 | 免费 |
+| GLM-4 | 100 | 100 |
+| 通义千问-Turbo | 2 | 6 |
+| 通义千问-Max | 40 | 120 |
+| Kimi-8K | 12 | 12 |
+| DeepSeek-Chat | 1 | 2 |
+| DeepSeek-Coder | 1 | 2 |
+
+*价格仅供参考，以官方最新公告为准*
+
+---
+
+## 最佳实践
+
+### 1. 模型选择建议
+
+| 场景 | 推荐模型 | 理由 |
+|------|----------|------|
+| 日常对话 | GLM-4-Flash | 免费且速度快 |
+| 编程任务 | DeepSeek-Coder | 专业代码能力 |
+| 长文档分析 | Kimi-128K | 超长上下文 |
+| 复杂推理 | GLM-4 / Qwen-Max | 高质量输出 |
+| 离线使用 | Ollama + Qwen2 | 本地运行 |
+
+### 2. API Key 安全
+
+- 永远不要在代码或配置文件中硬编码 API Key
+- 使用环境变量存储敏感信息
+- 定期轮换 API Key
+- 为不同项目使用不同的 API Key
+- 设置 API Key 使用额度限制
+
+### 3. 成本控制
+
+```toml
+[metering]
+# 每日最大花费（美元）
+daily_budget = 5.0
+# 每个 Agent 每小时最大 tokens
+hourly_token_limit = 100000
+# 超限行为：reject（拒绝）或 downgrade（降级）
+on_limit = "downgrade"
+# 降级到的模型
+fallback_model = "glm-4-flash"
+```
+
+---
+
+## 常见问题
+
+### Q: 如何测试 API Key 是否有效？
+
+```bash
+# 使用 curl 测试智谱 API
+curl -X POST https://open.bigmodel.cn/api/paas/v4/chat/completions \
+  -H "Authorization: Bearer $ZHIPU_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "glm-4-flash", "messages": [{"role": "user", "content": "你好"}]}'
+```
+
+### Q: 多个模型如何切换？
+
+在 Agent 配置中指定：
+
+```toml
+[agent.my-agent]
+[model]
+provider = "deepseek"
+model = "deepseek-coder"
+```
+
+### Q: 如何查看用量？
+
+```bash
+# 查看今日用量
+openfang usage --today
+
+# 查看本月用量
+openfang usage --month
+
+# 按模型分组
+openfang usage --group-by model
+```
+
+### Q: API Key 泄露了怎么办？
+
+1. 立即在对应平台撤销泄露的 Key
+2. 生成新的 API Key
+3. 更新环境变量
+4. 检查账单是否有异常使用
+
+---
+
+## 相关链接
+
+- [智谱开放平台](https://open.bigmodel.cn/)
+- [阿里云百炼](https://dashscope.console.aliyun.com/)
+- [Moonshot 平台](https://platform.moonshot.cn/)
+- [MiniMax 开放平台](https://www.minimaxi.com/)
+- [DeepSeek 平台](https://platform.deepseek.com/)
+- [Ollama 官网](https://ollama.com/)
+
+---
+
+*最后更新：2026 年 3 月*