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

一、OpenClaw 是什么

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

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

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

二、整体架构

┌─────────────────────────────────────────────────────┐
│                     用户侧                            │
│  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 适配器统一抽象：

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

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

3.2 消息路由引擎

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

// 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）：

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

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

"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+ 行）：

用户消息到达
    │
    ▼
┌─ 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 命令：

{
  "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 编码等绕过手段

第三层：人工审批

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

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

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

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

---
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）：

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 发送："帮我查下北京天气"

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 网关的架构设计与安全机制