# 第二章：基础概念
了解 VelaClaw 的核心概念，帮助你更好地使用它。
---
## 目录
1. [核心架构](#核心架构)
2. [关键概念](#关键概念)
3. [工作流程](#工作流程)
4. [数据存储](#数据存储)
---
## 核心架构
VelaClaw 采用模块化设计，主要包含以下部分：
```
┌─────────────────────────────────────────────────────────────┐
│ 用户 │
│ (你、Telegram、Discord等) │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ VelaClaw 核心 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Agent │ │ Channels │ │ Tools │ │ Memory │ │
│ │ (对话) │ │ (渠道) │ │ (工具) │ │ (记忆) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Providers (AI 模型) │
│ OpenAI Anthropic DeepSeek 其他 28+ 提供商 │
└─────────────────────────────────────────────────────────────┘
```
### 四大核心模块
| **Agent** | 管理 AI 对话 | 接收消息、调用模型、返回响应 |
| **Channels** | 连接各种平台 | Telegram、Discord、微信等 |
| **Tools** | 执行具体任务 | 读文件、搜索网页、运行代码 |
| **Memory** | 记住对话内容 | 存储历史、检索相关记忆 |
---
## 关键概念
### 1. Provider（AI 提供商）
Provider 是 AI 模型的来源。VelaClaw 支持多种 Provider：
| OpenAI | GPT-4、GPT-4o | 稳定可靠，生态完善 |
| Anthropic | Claude 系列 | 擅长长文本和编程 |
| OpenRouter | 聚合多种模型 | 一个密钥访问多模型 |
| DeepSeek | DeepSeek Chat | 国产，价格便宜 |
| Groq | Mixtral 等 | 速度极快 |
### 2. Model（模型）
每个 Provider 提供多个模型，各有特点：
```
Provider: OpenAI
├── gpt-4o (最强，适合复杂任务)
├── gpt-4o-mini (平衡，日常使用)
├── o1 (推理增强)
└── gpt-4-turbo (高速版)
```
**选择建议**：
| 简单对话 | gpt-4o-mini、deepseek-chat |
| 编程任务 | claude-sonnet、gpt-4o |
| 复杂推理 | o1、claude-sonnet |
| 长文本处理 | claude-sonnet |
| 省钱 | deepseek-chat、gpt-4o-mini |
### 3. Channel（通信渠道）
Channel 让你通过不同平台使用 VelaClaw：
```
支持的渠道：
├── Telegram (最成熟，推荐)
├── Discord (游戏社区友好)
├── Slack (团队协作)
├── Matrix (开源协议)
├── 微信 (通过企业微信)
├── 邮件 (SMTP/IMAP)
├── IRC (传统聊天)
├── Signal (隐私优先)
├── WhatsApp (通过 Web 或 API)
├── iMessage (苹果生态)
├── 钉钉 (国内企业)
├── 飞书/Lark (字节跳动)
├── QQ (腾讯)
└── Mattermost (开源团队协作)
```
### 4. Tool（工具）
Tool 是 AI 可以调用的能力：
| 文件操作 | 读取文件、写入文件 |
| 网络访问 | 搜索网页、发送 HTTP 请求 |
| 系统操作 | 运行命令、执行脚本 |
| 代码执行 | 运行 Python、Bash 等 |
| 浏览器 | 打开网页、截图 |
| 记忆管理 | 存储信息、检索记忆 |
| 定时任务 | 创建、管理定时任务 |
| 硬件控制 | GPIO 控制、传感器读取 |
### 5. Memory（记忆）
Memory 让 AI 能够记住之前的对话：
```
记忆类型：
├── 短期记忆 (当前对话上下文)
├── 长期记忆 (持久化存储)
└── 语义检索 (智能查找相关记忆)
```
**存储后端**：
| SQLite | 本地数据库，性能好 |
| Markdown | 纯文本，方便查看编辑 |
| 向量数据库 | 支持语义检索 |
### 6. Skill（技能）
Skill 是预定义的任务模板，让 AI 更擅长处理特定场景：
```
例子技能：
├── code-review (代码审查)
├── translate (翻译)
├── summarize (摘要)
├── data-analysis (数据分析)
└── custom-skill (自定义)
```
---
## 工作流程
### 基本对话流程
```
1. 用户发送消息
│
▼
2. VelaClaw 接收消息
│
├──► 检索相关记忆
│
├──► 构建上下文
│
▼
3. 调用 AI 模型
│
├──► AI 决定是否使用工具
│ │
│ ├──► 调用工具
│ │ │
│ │ ▼
│ │ 返回工具结果
│ │ │
│ └─────────┘
│
▼
4. 生成回复
│
├──► 存储到记忆
│
▼
5. 返回给用户
```
### 工具调用流程
```
用户: "帮我查看 weather.txt 文件的内容"
VelaClaw:
1. AI 分析请求 → 需要读取文件
2. 调用 file_read 工具
3. 工具执行：读取 weather.txt
4. 工具返回：文件内容
5. AI 生成回复："weather.txt 的内容是..."
```
---
## 数据存储
### 目录结构
```
~/.velaclaw/
├── config.yaml # 主配置文件
├── auth/ # 认证信息
│ └── profiles/ # 各 Provider 的认证
├── memory/ # 记忆存储
│ ├── memory.db # SQLite 数据库
│ └── embeddings/ # 向量嵌入
├── skills/ # 自定义技能
├── cache/ # 缓存
└── logs/ # 日志
```
### 配置文件
主配置文件 `~/.velaclaw/config.yaml`：
```yaml
# 默认 Provider 和模型
provider: openrouter
model: openrouter/auto
# 记忆配置
memory:
backend: sqlite
max_context_tokens: 8000
# 渠道配置
channels:
telegram:
enabled: true
token: "YOUR_BOT_TOKEN"
# 网关配置
gateway:
host: 127.0.0.1
port: 8080
```
---
## 安全概念
### 认证与授权
```
安全层级：
├── 用户认证 (谁可以使用)
│ ├── Telegram 用户白名单
│ ├── Discord 服务器限制
│ └── 密码保护
│
├── 操作授权 (能做什么)
│ ├── 工具权限控制
│ ├── 文件访问范围
│ └── 网络访问限制
│
└── 数据安全 (数据保护)
├── 本地加密存储
├── 敏感信息过滤
└── API 密钥保护
```
### 配对机制
首次在新渠道使用 VelaClaw 时，需要配对：
```
1. 用户发送消息
2. VelaClaw 返回配对码
3. 用户在命令行确认
4. 配对成功，可以正常使用
```
---
## 下一步
现在你了解了基础概念，可以：
1. **开始与 AI 对话** → [与 AI 对话](./03-chat-with-ai.md)
2. **深入了解模型** → [AI 模型与 Provider](./04-providers.md)
3. **设置通信渠道** → [通信渠道概览](./06-channels.md)
---
[← 上一章：快速入门](./01-getting-started.md) | [返回目录](./README.md) | [下一章：与 AI 对话 →](./03-chat-with-ai.md)