OpenClaw 架构原理：单进程应用与插件式扩展

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

通道适配器接收用户消息并进行预处理，包括消息标准化、提取附件等。不同的即时通讯工具和输入流，都配有专属的适配器。

每个通道适配器还负责反向通路：将 Agent 的回复格式化为目标平台所需的格式（如 Markdown 转 IM 富文本、长文本分段、文件直链等），并通过原通道发回。

流程：

1. 用户在 IM 发送消息
2. 平台服务器回调/推送
3. Gateway Channel Adapter 接收
4. 消息标准化（提取文本、附件、发送者信息等）
5. 生成统一的内部事件
6. 交给 Router 分发

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

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

• Router：鉴权、去重、限流、把消息分发给对应 Agent/工作流
• Session：找到/创建会话（conversation_id），取出最近对话、用户信息等上下文

通信协议采用 WebSocket + JSON，消息分三种类型：

• req：客户端 → 服务端，请求，包含唯一 id（UUID）
• res：服务端 → 客户端，对 req 的响应，含 ok 状态
• event：服务端 → 客户端，单向推送（消息到达、状态变更等）

连接鉴权流程：

1. 客户端发起 WebSocket 连接
2. 服务端发送 connect.challenge（含 nonce + 时间戳，防重放）
3. 客户端发送 req: connect（含协议版本、角色、权限范围、设备签名）
4. 若配置了 Token，验证 Bearer Token
5. 若是新设备，进入 Device Pairing 配对流程
6. 鉴权通过，连接建立

会话映射规则：

3. Agent 核心 Orchestrator（编排器）——'大脑'

Agent Runtime 是系统的决策核心，负责推理与编排。

• 决定下一步做什么：直接回答还是调用工具
• 维护对话回合：模型→工具→模型→…直到产出最终回复
• 包含提示词组装、策略、错误恢复、输出格式化

该模块会确定待调用的模型、匹配对应的 API 密钥（若密钥失效，会将该配置标记为冷却状态并尝试下一个），若主模型调用失败，会自动切换至备用模型。

系统提示词由多层动态组合而成：

最终 Prompt = 基础身份（AGENTS.md） + 工具声明（TOOLS.md，紧凑 XML 格式以节省 Token） + 动态技能列表 + 安全策略提示 + 用户记忆（USER.md 等 Markdown 文件） + 压缩后的会话历史 + 当前用户消息

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

• 把'调用模型'统一成一个接口
• 适配不同厂商/本地模型；处理流式输出、重试、超时、并发等

Context Window Guard（上下文窗口守护）

这是确保输入不超过模型上下文限制的关键机制：

• Pruning（剪枝）：在发送给模型前，自动裁剪过时的工具调用中间结果
• Compression（压缩）：将冗长的历史对话替换为总结摘要
• Graceful Degradation（优雅降级）：空间不足时终止执行并通知用户

模型调用与容错

1. 选择主模型 → 匹配 API Key
2. 调用成功 → 流式返回结果
3. Key 失效 → 标记冷却，尝试下一个 Key
4. 主模型故障 → 自动切换备用模型（Fallback）

支持的模型提供商

模型管理支持 CLI 命令（openclaw models list/set/scan），支持热切换模型，无需重启 Gateway，配置集中在 models.json。

Nodes（设备节点）——能力提供者

Nodes 是运行在各类设备上的能力提供者，通过 WebSocket 以 role: 'node' 连接 Gateway。 提供的能力：

• system.run：执行系统命令（Bash/Shell）
• file.read / file.write：文件读写
• browser.*：浏览器控制（Computer Use）
• camera.*：摄像头操作
• canvas.*：UI 画布操作

执行流程：Agent 决定调用工具 → Gateway 检查权限/安全策略 → Gateway 通过 node.invoke 转发指令给目标 Node → Node 在本地执行 → 执行结果返回 Gateway → Gateway 将结果传回 Agent Runtime。

Skills & Sandbox（技能系统与沙箱隔离）

Skills 是 OpenClaw 的插件式扩展机制，本质上是对工具的语义封装。 结构如下：

skill/
├── SKILL.md # 技能描述（LLM 可读的说明文档）
├── tools/ # 工具脚本（Bash/Python/Node.js）
└── prompts/ # 可选的提示词模板

技能来源包括本地目录、Agent Workspace 内嵌及在线市场。

Sandbox（沙箱隔离）对于非主会话（如群聊场景），默认启用 Docker 沙箱隔离执行。

5. 智能体循环（Agent Loop）

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

审批机制：高危命令（如 system.run 执行危险操作）可配置为需要人工审批。

1. Agent 请求执行危险工具
2. Gateway 广播 exec.approval.requested 事件
3. Operator（用户）在 Web UI 或 IM 中确认/拒绝
4. Gateway 将审批结果传回 Agent → 继续或终止执行

6. 记忆系统

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

会话记忆（短期）

存储格式：.jsonl（JSON Lines），每行一个 JSON 对象。记录内容：用户消息、工具调用指令、执行结果、模型回复。元数据存储在 sessions.json。

长期记忆（持久）

存储格式：Markdown 文件。关键文件包括 USER.md（用户偏好）、AGENTS.md（Agent 身份定义）、TOOLS.md（工具声明）等。

记忆管理策略

OpenClaw 有意选择 Markdown + SQLite 而非向量数据库，原因是可读性、可编辑性、可审计性及轻量级。

认证机制 - 公网暴露的最佳实践

OpenClaw 自身的两层防护就足够，不需要 Nginx Basic Auth。

最佳实践是打开 Device Auth，关掉 dangerouslyDisableDeviceAuth。

1. Gateway Auth Token（API 层认证）

配置位置：

{"auth":{"mode":"token","token":"xxxxxxxxxxxxxxxxxxxxxxx"}}

所有 API/WebSocket 请求必须携带 Authorization: Bearer ，否则拒绝。这保护了你的 AI Agent 不被随意调用。

2. Device Identity（Control UI 层认证）

专门保护 Web 控制面板。正常流程：

1. 浏览器首次打开 UI → 提示 device identity required
2. 在服务器终端运行授权命令，批准该设备
3. 浏览器获得设备凭证，之后都能访问

3. Bind 范围限制

{"bind":"lan"}

只监听局域网。

4. dangerouslyDisableDeviceAuth 的作用

{"gateway":{"controlUi":{"dangerouslyDisableDeviceAuth":true}}}

这个配置的意思是跳过 Device Identity 验证，任何人打开 UI 都不需要设备授权就能直接使用。名字带 dangerously 是因为这意味着只要知道 URL 的人都能控制你的 AI Agent。

安装部署架构

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

┌──────────┐
│ 浏览器   │
│ (Web UI) │
└────┬─────┘
     │ HTTPS
     ▼
┌─────────────────────────────────────────────────────────────┐
│ Nginx 反代层 (:443)                                          │
│ • SSL 终止 • WebSocket 代理                                  │
│ • Origin 覆写 • 信任边界                                     │
└──────────┬───────────────────────────────────┬──────────────┘
           │ proxy_pass                          │ http://127.0.0.1:18789
           ▼                                     ▼
┌──────────────────────────┐
│ IM 通道 Webhook 回调       │
│ 企业微信/QQ/钉钉/飞书    │
└──────────┬───────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│ 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（仅 127.0.0.1，不对外暴露）
:18790 — OpenClaw Bridge（多设备局域网发现通道）

使用总结

配置企业微信通道

编辑 openclaw.json，配置文件位于 data/.openclaw/openclaw.json（相对于 docker-compose.yml 目录）。

在 channels 中添加 wecom 配置：

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

手动注册插件（关键步骤）：OpenClaw 的 doctor 会自动尝试在 plugins.entries 中以通道 ID（wecom）注册插件，但实际的插件 ID 是 openclaw-wecom，导致 plugin not found: wecom 错误。

必须手动在 openclaw.json 中添加：

{"plugins":{"entries":{"openclaw-wecom":{"enabled":true}}}}

注意：plugins.entries 的 key 必须是 openclaw-wecom（npm 包名去掉 @marshulll/ 前缀），而不是 wecom（通道 ID）。