OpenClaw 架构解析：单进程应用与插件式扩展设计

核心组件详解

1. 接入层 Channel（通道适配器）

通道适配器负责接收来自即时通讯工具的消息并进行预处理。不同的 IM 平台都配有专属适配器，主要职责包括消息标准化、提取附件及发送者信息，生成统一的内部事件后交给 Router 分发。

反向通路同样重要，适配器需将 Agent 的回复格式化为目标平台所需的格式（如 Markdown 转富文本、长文本分段等），并通过原通道发回。

2. 网关服务器：路由与会话层 Router + Session

Gateway 是整个系统的控制中心，作为单机唯一实例的常驻守护进程。

• Router：负责鉴权、去重、限流，并将消息分发给对应的 Agent 或工作流。
• Session：负责查找或创建会话（conversation_id），取出最近对话和用户信息等上下文。

通信协议方面，所有组件间通过 WebSocket + JSON 进行交互，消息分为三种类型：req（客户端请求）、res（服务端响应）、event（单向推送）。连接建立时需经过挑战 - 响应机制，包含 nonce 和时间戳以防止重放攻击。

会话映射规则根据场景不同有所区分，私聊默认共享主会话，群组和定时任务则拥有独立的会话空间。

3. Agent 核心 Orchestrator（编排器）

Agent Runtime 是系统的决策核心，负责推理与编排。它决定下一步是直接回答还是调用工具，并维护对话回合直到产出最终回复。

该模块会确定待调用的模型及 API 密钥，若主模型调用失败，会自动切换至备用模型。智能体运行器结合可用工具、技能和记忆内容动态生成系统提示词，加入会话历史后传入上下文窗口防护机制。若上下文空间即将耗尽，系统会选择压缩会话内容或优雅降级终止执行。

系统提示词由多层动态组合而成，包括基础身份、工具声明、动态技能列表、安全策略提示、用户记忆及压缩后的会话历史。

4. LLM 适配层 LLM Provider（模型网关）

这一层将'调用模型'统一成一个接口，屏蔽各厂商 API 差异，处理流式输出、重试、超时和并发等问题。

上下文窗口守护 (Context Window Guard)

这是确保输入不超过模型上下文限制的关键机制。完整提示词会先经过校验：若空间充足直接发送；若紧张则压缩会话历史；若耗尽则告知用户开启新会话。支持剪枝（Pruning）和压缩（Compression）策略。

模型调用与容错

选择主模型匹配 API Key，若 Key 失效则标记冷却尝试下一个，主模型故障时自动切换备用模型（Fallback）。

支持的模型提供商包括 Anthropic、OpenAI、DeepSeek、OpenRouter 及本地部署的 Ollama 等。配置集中在 models.json，支持热切换模型，无需重启 Gateway。

5. 设备节点与技能系统

Nodes 是运行在各类设备上的能力提供者，通过 WebSocket 以 role: "node" 连接 Gateway。提供的能力涵盖系统命令执行、文件读写、浏览器控制、摄像头操作及 UI 画布操作等。

Skills（技能系统）是 OpenClaw 的插件式扩展机制，本质上是对工具的语义封装。技能来源包括本地目录、Agent Workspace 内嵌及 ClawHub 在线市场。Sandbox（沙箱隔离）对于非主会话（如群聊场景）默认启用 Docker 沙箱隔离执行，确保安全性。

6. 智能体循环（Agent Loop）

若大模型返回工具调用指令，系统会在本地执行该指令，并将结果补充至对话中。这一过程反复执行，直至大模型返回最终文本结果或达到最大循环次数（默认约 20 次）。

高危命令（如 system.run）可配置为需要人工审批。当 Agent 请求执行危险工具时，Gateway 广播事件，Operator 在 Web UI 或 IM 中确认或拒绝，随后决定是否继续执行。

7. 记忆系统

OpenClaw 的记忆系统遵循'文件即记忆'的设计哲学，Markdown 是真相的来源。

• 会话记忆（短期）：存储格式为 .jsonl，记录用户消息、工具调用指令、执行结果及模型回复。
• 长期记忆（持久）：存储格式为 Markdown 文件，包含用户偏好、Agent 身份定义及工具声明等。

选择 Markdown + SQLite 而非向量数据库的原因在于可读性、可编辑性、可审计性及轻量级。记忆文件可被 Git 追踪，支持回溯和协作。

认证机制与部署架构

认证机制

OpenClaw 提供两层防护，无需依赖 Nginx Basic Auth。

1. Device Identity：保护 Control UI 界面。首次访问需发起配对请求，在服务器终端执行授权命令批准设备，类似 SSH 的 trust-on-first-use 机制。
2. Gateway Auth Token：保护 API/WebSocket 接口。所有请求必须携带 Bearer Token。

配置项 dangerouslyDisableDeviceAuth 用于跳过 Device Identity 验证，由于名称中包含 dangerously，建议保持关闭状态以确保安全。

安装部署架构

典型的生产部署架构如下：

┌──────────┐
│ 浏览器   │
│ (Web UI) │
└────┬─────┘
     │ HTTPS
     ▼
┌─────────────────────────────────────────────────────────────┐
│ Nginx 反代层 (:443)                                         │
│ • SSL 终止 • WebSocket 代理                                 │
│ • Origin 覆写 • 信任边界                                    │
└──────────┬───────────────────────────────────┬──────────────┘
           │ proxy_pass                        │ http://127.0.0.1:18789
           ▼                                   ▼
┌──────────────────────────┐                  ┌─────────────────────────────────────────────────────────────┐
│ IM 通道 Webhook 回调      │                  │ OpenClaw Gateway (:18789 仅本地监听)                      │
│ 企业微信/QQ/钉钉/飞书     │                  │ • Channel Adapters → Router → Session → Agent Runtime     │
└──────────┬───────────────┘                  │ ↕                                                               │
           │                                  │ • LLM Provider                                                  │
           ▼                                  │ ↕                                                               │
┌─────────────────────────────────────────────────────────────┐
│ OpenClaw Gateway (:18789 仅本地监听)                        │
│ • Channel Adapters → Router → Session → Agent Runtime       │
│ ↕                                                           │
│ • LLM Provider                                              │
│ ↕                                                           │
│ • Tool Execution (Nodes / Sandbox)                          │
│ ↕                                                           │
│ • Memory System (.jsonl + .md)                              │
└─────────────────────────────────────────────────────────────┘

端口说明：:443 为 Nginx HTTPS 对外入口，:18789 为 OpenClaw Gateway 仅本地监听，:18790 为多设备局域网发现通道。

配置示例

以配置企业微信通道为例，需在 openclaw.json 中添加相应配置。注意插件 ID 需匹配 npm 包名，例如 openclaw-wecom 而非通道 ID wecom。

{
  "channels": {
    "wecom": {
      "enabled": true,
      "token": "<你的企业微信 Token>",
      "encodingAESKey": "<你的企业微信 EncodingAESKey>"
    }
  },
  "plugins": {
    "entries": {
      "openclaw-wecom": {
        "enabled": true
      }
    }
  }
}

此外，可通过 bind: "lan" 限制只监听局域网，进一步提升安全性。