# 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*