zclaw_openfang/docs/archive/OPENFANG-SETUP-LEGACY.md

ZCLAW Kernel 配置指南

⚠️ 已归档: 此文档仅作历史参考。ZCLAW 现在使用内部 Kernel 架构，无需启动外部 ZCLAW 进程。请参阅 快速启动指南 和 模型配置指南。

本文档帮助你正确配置 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
iwr -useb https://zclaw.sh/install.ps1 | iex

macOS / Linux

curl -fsSL https://zclaw.sh/install.sh | bash

方式二：手动下载

1. 访问 GitHub Releases
2. 下载对应平台的二进制文件
3. 将文件放入 PATH 目录

Windows

# 下载后移动到用户目录
move zclaw.exe C:\Users\<你的用户名>\.local\bin\

macOS / Linux

chmod +x zclaw
sudo mv zclaw /usr/local/bin/

方式三：从源码编译

git clone https://github.com/RightNow-AI/zclaw.git
cd zclaw
cargo build --release
# 编译产物位于 target/release/zclaw

---

配置说明

1. 初始化配置

首次使用需要初始化配置文件：

zclaw init

这将在 ~/.zclaw/ 目录下创建以下结构：

~/.zclaw/
├── config.toml        # 主配置文件
├── zclaw.db        # SQLite 数据库
├── data/              # 数据目录
│   ├── agents/        # Agent 配置
│   ├── skills/        # 自定义技能
│   └── hands/         # Hand 配置
└── logs/              # 日志文件

2. 配置文件结构

编辑 ~/.zclaw/config.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)

# 临时设置（当前会话）
$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

# 临时设置（当前会话）
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 中配置中文模型提供商：

# 智谱 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. 启动服务

前台运行（调试用）

zclaw start

后台守护进程

# 启动守护进程
zclaw daemon start

# 查看状态
zclaw status

# 停止守护进程
zclaw daemon stop

检查健康状态

zclaw doctor

---

与 ZCLAW 集成

配置 ZCLAW 连接 ZCLAW

编辑 ZCLAW 配置文件 ~/.zclaw/config.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

验证连接

# 启动 ZCLAW
zclaw start

# 在另一个终端启动 ZCLAW
cd desktop && pnpm tauri dev

---

常见问题

1. 端口被占用

错误信息：Address already in use: 0.0.0.0:50051

解决方案：

# 查找占用端口的进程
# Windows
netstat -ano | findstr :50051

# macOS / Linux
lsof -i :50051

# 修改配置文件中的端口
[api]
port = 50052

2. API Key 无效

错误信息：Authentication failed 或 Invalid API key

排查步骤：

1. 确认环境变量已设置：

   # 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. 检查网络连接和代理设置

# 测试 API 连通性
curl -I https://open.bigmodel.cn/api/paas/v4/models

5. 中文乱码

解决方案：

确保系统 locale 设置正确：

# Windows
chcp 65001

# macOS / Linux
export LANG=zh_CN.UTF-8

6. 从 ZCLAW 迁移

如果你之前使用 ZCLAW，可以使用迁移工具：

# 迁移所有内容：代理、记忆、技能、配置
zclaw migrate --from zclaw

# 从特定路径迁移
zclaw migrate --from zclaw --path ~/.zclaw

# 先试运行查看变更
zclaw migrate --from zclaw --dry-run

---

进阶配置

配置 Hands

Hands 是 ZCLAW 的核心创新，每个 Hand 是一个预构建的自主能力包：

# ~/.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 服务器

# ~/.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" }

配置渠道适配器

# ~/.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"

---

性能调优

内存优化

[memory]
# 会话压缩阈值（token 数）
compaction_threshold = 80000
# 保留最近消息数
keep_recent = 20
# 向量嵌入缓存大小
embedding_cache_size = 1000

并发优化

[runtime]
# 最大并发工具调用
max_concurrent_tools = 10
# 工具执行超时（秒）
tool_timeout = 60
# Agent 循环最大迭代
max_iterations = 50

---

日志与监控

查看日志

# 实时日志
zclaw logs -f

# 按级别过滤
zclaw logs --level error

# 按时间范围
zclaw logs --since "2024-01-01" --until "2024-01-02"

监控指标

# 系统状态
zclaw status

# 详细健康检查
zclaw doctor --verbose

# 使用统计
zclaw usage --daily

---

相关链接

• ZCLAW 官方文档
• GitHub 仓库
• 中文模型配置
• ZCLAW 主文档

---

获取帮助

• 命令行帮助：zclaw --help 或 zclaw <command> --help
• GitHub Issues：https://github.com/RightNow-AI/zclaw/issues
• 社区讨论：https://deepseek.club/t/topic/996