my-project/doc/SYSTEM.md

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. 通道插件架构

// 通道接口
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. 智能体路由

{
  "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 修复配置问题

🔧 配置架构

根配置结构

{
  "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. 本地凭据: 加密存储

访问控制

{
  "channels": {
    "telegram": {
      "allowFrom": ["tg:123456789"],
      "groupPolicy": "allowlist"
    }
  }
}

📈 性能优化

建议配置

配置项	推荐值	说明
contextWindow	最大可能	更多上下文
maxTokens	8192	充足输出空间
chunkMode	length	按长度分块
historyLimit	50	平衡上下文和性能

资源管理

• 内存: Gateway 进程监控
• CPU: 模型推理优化
• 网络: 连接池和重试

🔄 更新机制

版本检查

openclaw update check
openclaw update run

回滚

openclaw update rollback

---

最后更新: 2026-02-04 23:50 GMT+8 版本: OpenClaw v2026.2.3