深度解析 OpenClaw：一个自托管 AI Agent 网关的架构设计与安全机制

一、OpenClaw 是什么

想象这样的场景：你在微信里发"帮我查下北京天气"，几秒后收到精准天气预报；在 Telegram 里说"帮我创建一个 Python 项目"，AI 就在你的服务器上执行了 mkdir 和 pip install；在 Discord 里问"我的 GitHub 有哪些待处理 issue"，它直接帮你查了。

OpenClaw 就是让这一切发生的基础设施。

它是一个自托管的多渠道 AI Agent 网关系统 ，运行在你自己的机器上，连接 20+ 种聊天工具，让 AI 模型能操控操作系统、执行命令、管理文件、调用 API --- 一个真正意义上的个人 AI 助手。

二、整体架构

scss 复制代码

┌─────────────────────────────────────────────────────┐
│                     用户侧                            │
│  WhatsApp │ Telegram │ Slack │ Discord │ Signal │ ... │
└──────┬──────────┬───────┬────────┬────────┬─────────┘
       ▼          ▼       ▼        ▼        ▼
┌─────────────────────────────────────────────────────┐
│                  Gateway 网关层                       │
│  Channel Registry │ Routing │ Session │ Plugins      │
│  WebSocket + HTTP API │ Web UI │ 认证 & 安全          │
└────────────────────────┬────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────┐
│                  Agent 运行时层                       │
│  System Prompt 构建 │ Tool Catalog │ LLM Provider    │
│  Context Engine │ Compaction │ Failover & Retry      │
└────────────────────────┬────────────────────────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
   ┌──────────┐  ┌───────────┐  ┌──────────┐
   │ Sandbox  │  │  Skills   │  │ Memory   │
   │ (Docker) │  │ (52 技能)  │  │ (向量)   │
   └──────────┘  └───────────┘  └──────────┘

系统由三大层组成：Gateway 网关层 、Agent 运行时层 、能力层。

三、Gateway 网关层：消息的入口与出口

3.1 多渠道接入

Gateway 统一管理所有聊天渠道。9 个核心内置渠道（Telegram、WhatsApp、Discord、Slack、Signal、iMessage、LINE、IRC、Google Chat），加上 40+ 插件扩展渠道（飞书、Teams、Matrix 等）。

每个渠道通过 ChannelDock 适配器统一抽象：

typescript 复制代码

// src/channels/dock.ts
type ChannelDock = {
  id: ChannelId;
  capabilities: ChannelCapabilities;   // 支持的能力
  streaming?: ChannelDockStreaming;     // 流式输出
  groups?: ChannelGroupAdapter;         // 群组管理
  threading?: ChannelThreadingAdapter;  // 线程支持
};

不管消息来自哪个渠道，经过适配后进入统一处理流水线。

3.2 消息路由引擎

路由引擎决定每条消息该交给哪个 Agent 、归属哪个会话：

typescript 复制代码

// src/routing/resolve-route.ts
type ResolveAgentRouteInput = {
  channel: string;         // 来源渠道
  accountId?: string;      // 账号 ID
  peer?: RoutePeer;        // 对话对象
  guildId?: string;        // Discord 服务器
  memberRoleIds?: string[]; // 角色级路由
};

匹配优先级：精确 Peer 绑定 > Guild/Team > 账号 > 渠道 > 默认路由。你可以配置"Discord 的某个服务器用 Agent A，Telegram 私聊用 Agent B"。

3.3 安全门控

消息到达 Agent 前经过多层检查：发送者白名单、@提及门控、命令权限控制、入站防抖。

四、Agent 运行时层：AI 的大脑

4.1 System Prompt 动态构建

每次 Agent 收到消息，都会动态组装 System Prompt（src/agents/system-prompt.ts）：

sql 复制代码

┌─ System Prompt 结构 ─────────────────────┐
│  1. 身份声明 --- "You are a personal       │
│     assistant running inside OpenClaw"    │
│  2. 工具列表 --- 当前可用工具及说明          │
│  3. 技能指引 --- 可用技能 + 选择方式         │
│  4. 记忆指引 --- memory_search 使用方式     │
│  5. 安全宪章 --- 行为约束                   │
│  6. 沙箱信息 --- 容器路径映射               │
│  7. 用户身份 --- 授权发送者列表             │
│  8. 运行时上下文 --- OS/架构/Shell/模型     │
└───────────────────────────────────────────┘

其中安全宪章采用 Constitutional AI 思路：

typescript 复制代码

"You have no independent goals: do not pursue self-preservation,
 replication, resource acquisition..."
"Prioritize safety and human oversight over completion..."

4.2 工具目录：24 个核心工具

类别	工具	说明
Files	`read`/`write`/`edit`/`apply_patch`	文件读写编辑
Runtime	`exec`/`process`	命令执行、进程管理
Web	`web_search`/`web_fetch`	搜索和抓取网页
Memory	`memory_search`/`memory_get`	向量记忆检索
Sessions	`sessions_*`/`subagents`	会话管理、子 Agent
UI	`browser`/`canvas`	浏览器控制、画布
Messaging	`message`	跨渠道发消息
Automation	`cron`/`gateway`	定时任务
Nodes	`nodes`	远程设备控制
Media	`image`/`tts`	图像生成、语音合成

工具通过 LLM 的 Function Calling 机制暴露给模型，并经过多层策略管道过滤（Profile → 渠道 → 模型厂商 → Agent 级 → Group 分组）。

4.3 Agent 运行循环

核心执行引擎在 src/agents/pi-embedded-runner/run.ts（1500+ 行）：

markdown 复制代码

用户消息到达
    │
    ▼
┌─ Agent Loop ─────────────────────────────┐
│  1. 加载会话历史                           │
│  2. 构建 System Prompt + 可用工具          │
│  3. 上下文装配（Context Engine）            │
│  4. 上下文过长 → Compaction 压缩           │
│  5. 发送给 LLM                            │
│  6. LLM 回复：                            │
│     ├─ 纯文本 → 返回给用户 ✓              │
│     └─ tool_calls → 执行工具              │
│        → 结果放回上下文 → 回到步骤 5       │
│                                           │
│  异常：API 报错 → 退避重试                 │
│       配额耗尽 → Failover 备选模型         │
│       上下文超长 → 自动 Compaction          │
└───────────────────────────────────────────┘

Failover 是一大亮点：当 LLM 提供商不可用（限速/宕机），自动切换到备选 Auth Profile，最多重试 160 次。

4.4 上下文压缩（Compaction）

长对话会超出 LLM 的上下文窗口。src/agents/compaction.ts 实现了自适应压缩：

分块 --- 按 token 数将历史消息分块（自适应 chunk ratio：0.15~0.4）
逐块摘要 --- 调用 LLM 生成每个块的摘要，保留关键信息
合并 --- 多块摘要合并为单一连贯摘要
替换 --- 用摘要替换原始历史，腾出上下文空间

压缩指令强调保留"活跃任务、批处理进度、最后用户请求、决策、TODO"等关键信息。

五、命令执行：AI 如何安全操控你的机器

5.1 `exec` 工具

LLM 通过 exec 工具执行 Shell 命令：

json 复制代码

{
  "name": "exec",
  "arguments": {
    "command": "curl 'wttr.in/Beijing?format=3'",
    "host": "sandbox",
    "security": "allowlist",
    "ask": "on-miss",
    "timeout": 30
  }
}

5.2 三层安全防线

第一层：Docker 沙箱隔离

默认在 Docker 容器内执行，src/agents/sandbox/docker.ts 实现：

只读根文件系统 （--read-only）
受限 bind mount --- 仅挂载工作区
安全校验 （validateSandboxSecurity()）--- 阻止危险配置
环境变量清洗 （sanitizeEnvVars()）--- 过滤密钥

第二层：命令白名单

src/infra/exec-approvals-allowlist.ts 实现深度命令分析，不是简单字符串匹配：

Shell 解析 --- 解析管道、重定向、子命令
命令链拆分 --- 处理 &&、||、;
路径验证 --- 验证二进制文件实际路径
混淆检测 --- 防止 Base64 编码等绕过手段

第三层：人工审批

bash 复制代码

LLM 想执行: rm -rf /tmp/old-cache
    → 白名单检查: rm 不在白名单 ❌
    → 推送审批请求到用户聊天渠道
    → 用户选择: allow-once / allow-always / deny

三种模式：off（不问）、on-miss（默认，白名单未命中时问）、always（每次都问）。

六、技能系统：52 个可插拔能力

技能定义在 skills/ 目录下，每个技能的核心是一个 SKILL.md 文件：

yaml 复制代码

---
name: weather
description: Get weather forecasts. Use when user asks about weather.
metadata:
  binaries:
    - name: curl
      install: "apt-get install curl"
---
# Weather Skill
Use `curl wttr.in/{location}?format=3` to get weather...

本质上是给 AI 的说明书 --- 用 Markdown 写的操作指令。Agent 在 System Prompt 中看到可用技能列表，根据用户需求选择加载对应的 SKILL.md，然后按照其中的指令执行。

覆盖领域包括：笔记（Apple Notes/Notion/Obsidian）、编码（GitHub/Coding Agent）、媒体（图像生成/语音识别）、智能家居（灯光/音响）、通信（邮件/消息转发）等。

七、向量记忆系统

Agent 可以跨会话记住信息。基于 Context Engine 抽象（src/context-engine/types.ts）：

typescript 复制代码

interface ContextEngine {
  ingest(params):    Promise<IngestResult>;    // 写入记忆
  assemble(params):  Promise<AssembleResult>;  // 装配上下文
  compact(params):   Promise<CompactResult>;   // 压缩历史
  dispose?():        Promise<void>;            // 清理资源
}

支持多种嵌入模型（OpenAI/Gemini/Ollama/Voyage），存储后端为 SQLite-vec 或 LanceDB。

八、插件系统

40+ 扩展包，每个是独立 npm 包，支持运行时热加载/卸载。Plugin Registry 管理所有插件的生命周期，包括渠道插件（新增聊天渠道）和技能插件（新增 Agent 能力）。

九、完整请求流程示例

用户在 WhatsApp 发送："帮我查下北京天气"

css 复制代码

1. WhatsApp → Gateway Channel Dock → 消息标准化
2. 路由引擎 → 匹配到默认 Agent，生成 session key
3. 安全门控 → 发送者在白名单中 ✓
4. Agent Loop 启动：
   a. 构建 System Prompt（含工具列表 + weather 技能）
   b. 发送给 LLM（如 GPT-4o）
   c. LLM 返回 tool_call:
      { name: "exec", arguments: { command: "curl 'wttr.in/Beijing?format=3'" } }
   d. exec 工具处理:
      - host: sandbox → Docker 容器
      - security: allowlist → curl 在白名单 ✓
      - ask: on-miss → 已命中，无需审批
      - 在容器中执行命令，获取天气数据
   e. 结果返回给 LLM
   f. LLM 组织自然语言回复
5. 回复 → Gateway → WhatsApp → 用户看到天气信息

十、技术栈总结

项目	技术
语言	TypeScript（ESM）
运行时	Node 22+（兼容 Bun）
包管理	pnpm
测试	Vitest + V8 Coverage
Lint	Oxlint + Oxfmt
网关	WebSocket + HTTP
沙箱	Docker 容器
存储	SQLite（会话/记忆）
客户端	macOS/iOS（Swift）、Android（Kotlin）

结语

OpenClaw 的设计哲学可以用三个关键词概括：

自主权 --- 运行在你自己的机器上，数据不经过第三方
开放性 --- 20+ 渠道、50+ 技能、40+ 插件，高度可扩展
安全性 --- 沙箱隔离 + 命令白名单 + 人工审批，三层防线确保 AI 不会失控

它不只是一个聊天机器人框架，而是一个让 AI 真正成为你的操作系统代理人的基础设施。

深度解析 OpenClaw：一个自托管 AI Agent 网关的架构设计与安全机制

一、OpenClaw 是什么

二、整体架构

三、Gateway 网关层：消息的入口与出口

3.1 多渠道接入

3.2 消息路由引擎

3.3 安全门控

四、Agent 运行时层：AI 的大脑

4.1 System Prompt 动态构建

4.2 工具目录：24 个核心工具

4.3 Agent 运行循环

4.4 上下文压缩（Compaction）

五、命令执行：AI 如何安全操控你的机器

5.1 exec 工具

5.2 三层安全防线

第一层：Docker 沙箱隔离

第二层：命令白名单

第三层：人工审批

六、技能系统：52 个可插拔能力

七、向量记忆系统

八、插件系统

九、完整请求流程示例

十、技术栈总结

结语

5.1 `exec` 工具