每日备份 2026-06-10 12:57:13

doc/SYSTEM.md

@@ -0,0 +1,196 @@
+# OpenClaw 系统架构和设计模式
+
+## 📊 系统概览
+
+### 核心组件
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    OpenClaw Gateway                     │
+│  - 单进程架构 (single source of truth)                  │
+│  - WebSocket 控制平面                                   │
+│  - 通道连接管理                                         │
+└────────────────────────┬────────────────────────────────┘
+                         │
+        ┌────────────────┼────────────────┐
+        ▼                ▼                ▼
+   ┌─────────┐     ┌─────────┐     ┌─────────┐
+   │Telegram │     │WhatsApp │     │ Discord │
+   │  Bot    │     │  Web    │     │   Bot   │
+   └─────────┘     └─────────┘     └─────────┘
+```
+
+### 目录结构
+
+```
+~/.openclaw/
+├── openclaw.json          # 主配置文件
+├── openclaw.log           # 运行日志
+├── agents/               # 智能体配置
+│   └── main/
+│       └── agent/
+│           ├── models.json
+│           └── config.json
+├── workspace/             # 工作空间
+├── canvas/                # Canvas文件
+├── extensions/            # 扩展插件
+└── credentials/           # 凭据存储
+```
+
+## 🏗️ 设计模式
+
+### 1. 单网关架构
+
+**原则**: 每个主机一个网关进程
+- 负责所有通道连接
+- WebSocket 控制平面
+- 唯一的真相来源
+
+**多机部署**: 每个实例独立网关，使用不同端口
+
+### 2. 通道插件架构
+
+```javascript
+// 通道接口
+interface Channel {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  sendMessage(target: string, content: string): Promise<void>;
+  onMessage(callback: (message: Message) => void): void;
+}
+```
+
+**支持通道**:
+- Telegram (Bot API)
+- WhatsApp (Baileys Web)
+- Discord (Bot API)
+- iMessage (imsg CLI)
+- Mattermost (插件)
+
+### 3. 智能体路由
+
+```json
+{
+  "agents": {
+    "list": [
+      { "id": "main", "workspace": "~/.openclaw/workspace" },
+      { "id": "guardian", "workspace": "/shared/guardian" }
+    ]
+  },
+  "bindings": [
+    { "agentId": "main", "match": { "channel": "telegram" } },
+    { "agentId": "guardian", "match": { "channel": "whatsapp" } }
+  ]
+}
+```
+
+### 4. 配置验证
+
+**严格模式**: OpenClaw 使用 JSON Schema 验证
+- 不匹配 schema 的配置会被拒绝
+- 使用 `openclaw doctor` 修复配置问题
+
+## 🔧 配置架构
+
+### 根配置结构
+
+```json
+{
+  "meta": { /* 元数据 */ },
+  "models": { /* 模型提供者 */ },
+  "agents": { /* 智能体配置 */ },
+  "channels": { /* 通道配置 */ },
+  "gateway": { /* 网关配置 */ },
+  "plugins": { /* 插件配置 */ }
+}
+```
+
+### 配置优先级
+
+1. **CLI 参数** (最高)
+2. **环境变量**
+3. **配置文件** (`~/.openclaw/openclaw.json`)
+4. **默认值** (最低)
+
+## 🌐 网络模型
+
+### 单机模式
+
+```
+localhost:18789 (WebSocket)
+    │
+    ▼
+┌─────────────────────────────┐
+│     Gateway 进程           │
+│     - 通道连接              │
+│     - 消息路由              │
+└─────────────────────────────┘
+```
+
+### 远程模式
+
+```
+远程主机                    本地主机
+┌─────────────┐            ┌─────────────┐
+│  Gateway    │  ───SSH──▶ │  CLI/Nodes  │
+│  :18789     │  隧道      │             │
+└─────────────┘            └─────────────┘
+```
+
+## 🔐 安全模型
+
+### 认证机制
+
+1. **网关Token**: WebSocket 认证
+2. **OAuth**: 第三方API认证
+3. **本地凭据**: 加密存储
+
+### 访问控制
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "allowFrom": ["tg:123456789"],
+      "groupPolicy": "allowlist"
+    }
+  }
+}
+```
+
+## 📈 性能优化
+
+### 建议配置
+
+| 配置项 | 推荐值 | 说明 |
+|--------|--------|------|
+| `contextWindow` | 最大可能 | 更多上下文 |
+| `maxTokens` | 8192 | 充足输出空间 |
+| `chunkMode` | length | 按长度分块 |
+| `historyLimit` | 50 | 平衡上下文和性能 |
+
+### 资源管理
+
+- **内存**: Gateway 进程监控
+- **CPU**: 模型推理优化
+- **网络**: 连接池和重试
+
+## 🔄 更新机制
+
+### 版本检查
+
+```bash
+openclaw update check
+openclaw update run
+```
+
+### 回滚
+
+```bash
+openclaw update rollback
+```
+
+---
+
+*最后更新: 2026-02-04 23:50 GMT+8*
+*版本: OpenClaw v2026.2.3*