OpenClaw 简介
OpenClaw 是一款开源自托管的个人 AI 代理网关，本质是运行在用户自有设备上的自主式智能体助手。项目主打'本地优先、隐私可控'的设计理念，通过自然语言指令实现 PC 全功能自动化。
架构概览
OpenClaw 的核心是一个基于 TypeScript 开发的命令行应用（CLI），核心理念是：常驻控制平面 + 可插拔大模型大脑 + 可扩展工具技能 + 会话/记忆/安全策略。
┌─────────────────────────────────────────────────────────────────┐
│ 消息渠道（Channels） │
│ ┌──────┐ ┌──────┐ ┌────┐ ┌────┐ ┌────────┐ ┌──────┐ │
│ │企业微信│ │Telegram│ │飞书│ │QQ │ │WhatsApp│ │Web UI│ ... │
│ └───┬──┘ └───┬──┘ └──┬─┘ └──┬─┘ └───┬────┘ └───┬──┘ │
│ └────────┴───────┴───────┴───────┴──────────┘ │
│ ▼ │
│ 统一内部事件格式 │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Gateway（网关守护进程）:18789 │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Router │ │ Session │ │ Security │ │ │
│ │ │ 路由分发 │ │ 会话管理 │ │ 安全策略 │ │ │
│ │ │ 鉴权/限流│ │ 上下文恢复│ │ 审批机制 │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ └───────────────────────┬─────────────────────────────────┘ │
│ │ │
│ ┌─────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌───────────┐ ┌──────────────┐ │
│ │ Agent Runtime│ │ Nodes │ │ Skills & │ │
│ │ 智能体运行时 │ │ 设备节点 │ │ Sandbox │ │
│ │ │ │ │ │ 技能系统+沙箱│ │
│ │ ┌────────┐ │ │ macOS │ │ SKILL.md │ │
│ │ │Prompt │ │ │ iOS │ │ Docker 隔离 │ │
│ │ │Builder│ │ │ Android │ │ ClawHub 市场 │ │
│ │ ├────────┤ │ │ Linux │ │ │ │
│ │ │Context│ │ │ │ │ │ │
│ │ │Guard │ │ └───────────┘ └──────────────┘ │
│ │ ├────────┤ │
│ │ │Tool │ │
│ │ │Executor│ │
│ │ └──────┬──────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ LLM Provider（模型适配层） │ │
│ │ Claude │ GPT │ DeepSeek │ Ollama │ ... │ │
│ └──────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ Memory（记忆系统） │ │
│ │ .jsonl 会话历史 │ Markdown 长期记忆 │ │
│ │ SQLite 索引 │ Git 版本管理 │ │
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
1. 接入层 Channel（通道适配器）
通道适配器接收用户消息并进行预处理，包括消息标准化、提取附件等。不同的即时通讯工具和输入流，都配有专属的适配器。
每个通道适配器还负责反向通路：将 Agent 的回复格式化为目标平台所需的格式（如 Markdown 转 IM 富文本、长文本分段、文件直链等），并通过原通道发回。
流程：
- 用户在 IM 发送消息
- 平台服务器回调/推送
- Gateway Channel Adapter 接收
- 消息标准化（提取文本、附件、发送者信息等）
- 生成统一的内部事件
- 交给 Router 分发
2. 网关服务器：路由与会话层 Router + Session
Gateway 是整个系统的控制中心，是单机唯一实例的常驻守护进程。
- Router：鉴权、去重、限流、把消息分发给对应 Agent/工作流
- Session：找到/创建会话（conversation_id），取出最近对话、用户信息等上下文
通信协议采用 WebSocket + JSON，消息分三种类型：
req：客户端 → 服务端，请求，包含唯一 id（UUID）res：服务端 → 客户端，对 req 的响应，含 ok 状态event：服务端 → 客户端，单向推送（消息到达、状态变更等）
连接鉴权流程：
- 客户端发起 WebSocket 连接
- 服务端发送 connect.challenge（含 nonce + 时间戳，防重放）
- 客户端发送 req: connect（含协议版本、角色、权限范围、设备签名）
- 若配置了 Token，验证 Bearer Token
- 若是新设备，进入 Device Pairing 配对流程
- 鉴权通过，连接建立
会话映射规则：
| 场景 | Session Key | 说明 |
|---|---|---|
| 私聊（DM） | dmScope: 'main' | 默认共享主会话，可配 per-peer 隔离 |
| 群组 | agent:::group: | 每个群独立会话 |
| 定时任务 | cron:: | 独立会话 |
| Webhook | webhook:: | 独立会话 |
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（优雅降级）：空间不足时终止执行并通知用户
模型调用与容错
- 选择主模型 → 匹配 API Key
- 调用成功 → 流式返回结果
- Key 失效 → 标记冷却，尝试下一个 Key
- 主模型故障 → 自动切换备用模型（Fallback）
支持的模型提供商
| Provider | 示例模型 | 备注 |
|---|---|---|
| Anthropic | Claude 3.5/4 | 原生支持 |
| OpenAI | GPT-4o/o1 | 原生支持 |
| DeepSeek | DeepSeek-V3/R1 | 兼容 OpenAI 格式 |
| OpenRouter | 多模型聚合 | 统一入口 |
| Ollama | Llama/Qwen 等 | 本地模型 |
模型管理支持 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 沙箱隔离执行。
| 会话类型 | 执行环境 | 权限 |
|---|---|---|
| 主对话（DM） | 本地直接执行 | 完整权限 |
| 群组对话 | Docker 沙箱 | 受限工具（bash, read 等） |
| Webhook 触发 | Docker 沙箱 | 受限 |
5. 智能体循环（Agent Loop）
若大模型返回工具调用指令，系统会在本地执行该指令，并将执行结果补充至对话中。这一过程会反复执行，直至大模型返回最终文本结果，或达到最大循环次数（默认约 20 次）。
审批机制：高危命令（如 system.run 执行危险操作）可配置为需要人工审批。
- Agent 请求执行危险工具
- Gateway 广播 exec.approval.requested 事件
- Operator（用户）在 Web UI 或 IM 中确认/拒绝
- Gateway 将审批结果传回 Agent → 继续或终止执行
6. 记忆系统
OpenClaw 的记忆系统遵循'文件即记忆'的设计哲学，Markdown 是真相的来源（Source of Truth）。
会话记忆（短期）
存储格式：.jsonl（JSON Lines），每行一个 JSON 对象。记录内容：用户消息、工具调用指令、执行结果、模型回复。元数据存储在 sessions.json。
长期记忆（持久）
存储格式：Markdown 文件。关键文件包括 USER.md（用户偏好）、AGENTS.md（Agent 身份定义）、TOOLS.md（工具声明）等。
记忆管理策略
| 策略 | 说明 |
|---|---|
| Pruning（剪枝） | 发送给模型前裁剪过时的工具调用中间结果 |
| Compression（压缩） | 将冗长历史替换为总结摘要 |
| Lifecycle（生命周期） | 按空闲时间/固定时间重置，或 /new 命令手动重置 |
| Git 版本管理 | 记忆文件可被 Git 追踪，支持回溯和协作 |
OpenClaw 有意选择 Markdown + SQLite 而非向量数据库，原因是可读性、可编辑性、可审计性及轻量级。
认证机制 - 公网暴露的最佳实践
OpenClaw 自身的两层防护就足够，不需要 Nginx Basic Auth。
| 层级 | 机制 | 保护什么 |
|---|---|---|
| 第 1 层 | Device Identity（设备配对） | Control UI 界面 |
| 第 2 层 | Gateway Token | API/WebSocket 调用 |
最佳实践是打开 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 控制面板。正常流程：
- 浏览器首次打开 UI → 提示 device identity required
- 在服务器终端运行授权命令，批准该设备
- 浏览器获得设备凭证，之后都能访问
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）。
