0d4fa96b82
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
515 lines
9.6 KiB
Markdown
515 lines
9.6 KiB
Markdown
# ZCLAW Kernel 配置指南
|
||
|
||
> ⚠️ **已归档**: 此文档仅作历史参考。ZCLAW 现在使用内部 Kernel 架构，无需启动外部 ZCLAW 进程。请参阅 [快速启动指南](../quick-start.md) 和 [模型配置指南](../knowledge-base/configuration.md)。
|
||
|
||
> 本文档帮助你正确配置 ZCLAW Kernel，作为 ZCLAW 的后端执行引擎。
|
||
|
||
## 概述
|
||
|
||
ZCLAW 是一个用 Rust 构建的生产级 Agent 操作系统（Agent Operating System）。与传统的聊天机器人框架不同，ZCLAW 采用"主动执行"范式：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+ |
|
||
|
||
### 依赖项
|
||
|
||
ZCLAW 是一个独立的单二进制文件（~32MB），无外部依赖。但以下工具可能对某些功能必要：
|
||
|
||
- **FFmpeg**：视频处理 Hand (Clip) 需要
|
||
- **yt-dlp**：YouTube 视频下载需要
|
||
|
||
---
|
||
|
||
## 安装步骤
|
||
|
||
### 方式一：官方安装脚本（推荐）
|
||
|
||
#### Windows
|
||
|
||
```powershell
|
||
# 使用 PowerShell
|
||
iwr -useb https://zclaw.sh/install.ps1 | iex
|
||
```
|
||
|
||
#### macOS / Linux
|
||
|
||
```bash
|
||
curl -fsSL https://zclaw.sh/install.sh | bash
|
||
```
|
||
|
||
### 方式二：手动下载
|
||
|
||
1. 访问 [GitHub Releases](https://github.com/RightNow-AI/zclaw/releases)
|
||
2. 下载对应平台的二进制文件
|
||
3. 将文件放入 PATH 目录
|
||
|
||
#### Windows
|
||
|
||
```powershell
|
||
# 下载后移动到用户目录
|
||
move zclaw.exe C:\Users\<你的用户名>\.local\bin\
|
||
```
|
||
|
||
#### macOS / Linux
|
||
|
||
```bash
|
||
chmod +x zclaw
|
||
sudo mv zclaw /usr/local/bin/
|
||
```
|
||
|
||
### 方式三：从源码编译
|
||
|
||
```bash
|
||
git clone https://github.com/RightNow-AI/zclaw.git
|
||
cd zclaw
|
||
cargo build --release
|
||
# 编译产物位于 target/release/zclaw
|
||
```
|
||
|
||
---
|
||
|
||
## 配置说明
|
||
|
||
### 1. 初始化配置
|
||
|
||
首次使用需要初始化配置文件：
|
||
|
||
```bash
|
||
zclaw init
|
||
```
|
||
|
||
这将在 `~/.zclaw/` 目录下创建以下结构：
|
||
|
||
```
|
||
~/.zclaw/
|
||
├── config.toml # 主配置文件
|
||
├── zclaw.db # SQLite 数据库
|
||
├── data/ # 数据目录
|
||
│ ├── agents/ # Agent 配置
|
||
│ ├── skills/ # 自定义技能
|
||
│ └── hands/ # Hand 配置
|
||
└── logs/ # 日志文件
|
||
```
|
||
|
||
### 2. 配置文件结构
|
||
|
||
编辑 `~/.zclaw/config.toml`：
|
||
|
||
```toml
|
||
# ZCLAW 主配置文件
|
||
|
||
[general]
|
||
# 默认语言
|
||
language = "zh-CN"
|
||
# 日志级别: trace, debug, info, warn, error
|
||
log_level = "info"
|
||
# 数据目录
|
||
data_dir = "~/.zclaw/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
|
||
zclaw start
|
||
```
|
||
|
||
#### 后台守护进程
|
||
|
||
```bash
|
||
# 启动守护进程
|
||
zclaw daemon start
|
||
|
||
# 查看状态
|
||
zclaw status
|
||
|
||
# 停止守护进程
|
||
zclaw daemon stop
|
||
```
|
||
|
||
#### 检查健康状态
|
||
|
||
```bash
|
||
zclaw doctor
|
||
```
|
||
|
||
---
|
||
|
||
## 与 ZCLAW 集成
|
||
|
||
### 配置 ZCLAW 连接 ZCLAW
|
||
|
||
编辑 ZCLAW 配置文件 `~/.zclaw/config.toml`：
|
||
|
||
```toml
|
||
[gateway]
|
||
# ZCLAW API 端点
|
||
endpoint = "http://127.0.0.1:50051"
|
||
# WebSocket 端点
|
||
ws_endpoint = "ws://127.0.0.1:50051/ws"
|
||
# 连接超时（秒）
|
||
timeout = 30
|
||
|
||
[model]
|
||
# 使用 ZCLAW 的模型路由
|
||
use_gateway_routing = true
|
||
```
|
||
|
||
### 验证连接
|
||
|
||
```bash
|
||
# 启动 ZCLAW
|
||
zclaw 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. 从 ZCLAW 迁移
|
||
|
||
如果你之前使用 ZCLAW，可以使用迁移工具：
|
||
|
||
```bash
|
||
# 迁移所有内容：代理、记忆、技能、配置
|
||
zclaw migrate --from zclaw
|
||
|
||
# 从特定路径迁移
|
||
zclaw migrate --from zclaw --path ~/.zclaw
|
||
|
||
# 先试运行查看变更
|
||
zclaw migrate --from zclaw --dry-run
|
||
```
|
||
|
||
---
|
||
|
||
## 进阶配置
|
||
|
||
### 配置 Hands
|
||
|
||
Hands 是 ZCLAW 的核心创新，每个 Hand 是一个预构建的自主能力包：
|
||
|
||
```toml
|
||
# ~/.zclaw/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
|
||
# ~/.zclaw/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
|
||
# ~/.zclaw/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
|
||
# 实时日志
|
||
zclaw logs -f
|
||
|
||
# 按级别过滤
|
||
zclaw logs --level error
|
||
|
||
# 按时间范围
|
||
zclaw logs --since "2024-01-01" --until "2024-01-02"
|
||
```
|
||
|
||
### 监控指标
|
||
|
||
```bash
|
||
# 系统状态
|
||
zclaw status
|
||
|
||
# 详细健康检查
|
||
zclaw doctor --verbose
|
||
|
||
# 使用统计
|
||
zclaw usage --daily
|
||
```
|
||
|
||
---
|
||
|
||
## 相关链接
|
||
|
||
- [ZCLAW 官方文档](https://zclaw.sh/)
|
||
- [GitHub 仓库](https://github.com/RightNow-AI/zclaw)
|
||
- [中文模型配置](./chinese-models.md)
|
||
- [ZCLAW 主文档](../../README.md)
|
||
|
||
---
|
||
|
||
## 获取帮助
|
||
|
||
- **命令行帮助**：`zclaw --help` 或 `zclaw <command> --help`
|
||
- **GitHub Issues**：https://github.com/RightNow-AI/zclaw/issues
|
||
- **社区讨论**：https://deepseek.club/t/topic/996
|