OpenClaw 深度解析：30万星开源 AI Agent 框架的技术内核——从 Gateway 到 Memory 的完整架构革命
2026年最火爆的开源项目，30万 Star 背后的技术密码。一个本地运行的 AI 助手，如何让 AI 从「回答问题」升级为「执行任务」？万字长文拆解 Gateway、Agent、Skills、Memory 四大核心模块。
一、为什么 OpenClaw 能在 2026 年引爆技术圈？
2026年初，GitHub 上出现了一个现象级项目——OpenClaw。短短数周，Star 数突破 30 万，成为年度最火爆的开源 AI Agent 框架。它的口号很简单：「把事做完」。
这不是又一个 LLM 应用壳子。OpenClaw 的本质是一个本地优先的 AI 执行框架，它让 AI 真正具备「动手能力」——在你的电脑上点击、输入、拖拽、删除文件、发送邮件、操作浏览器。
与之对比，2023年的 AutoGPT 开启了自主 Agent 的想象，但很快暴露出问题：执行不稳定、难以落地、生产环境不可用。LangChain 提供了开发框架，但离「开箱即用」还有距离。
OpenClaw 的突破在于：它不是框架，而是一个完整的运行时。你不需要写代码，只需要配置。它的设计哲学是「无额外应用」——不强迫用户安装新的聊天 App，而是接入你已经在用的渠道：微信、WhatsApp、Telegram、Discord、飞书、Slack……
让我们深入它的技术内核。
二、架构总览：四大核心模块的协作逻辑
OpenClaw 的架构可以用一句话概括：
Gateway 接收消息 → Agent 调用 LLM 推理 → Skills 提供执行能力 → Memory 提供上下文
这是一个经典的感知-决策-执行-记忆闭环。
┌─────────────────────────────────────────────────────────────┐
│ OpenClaw Architecture │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ WhatsApp │ │ Telegram │ │ Discord │ ... │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └───────────────┼───────────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Gateway │ ← WebSocket 服务 │
│ │ (网关中枢) │ localhost:18789 │
│ └───────┬────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌───────────┐ ┌─────────────┐ │
│ │ Auth │ │ Session │ │ Router │ │
│ │ (认证) │ │ (会话) │ │ (路由) │ │
│ └─────────┘ └───────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Agent │ ← LLM 推理引擎 │
│ │ (智能体) │ Claude/GPT/Gemini │
│ └───────┬────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌───────────┐ ┌─────────────┐ │
│ │ Skills │ │ Tools │ │ Memory │ │
│ │ (技能) │ │ (工具) │ │ (记忆) │ │
│ └─────────┘ └───────────┘ └─────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────┐ │
│ │ Sandbox / Host OS │ ← 执行环境 │
│ │ (沙箱/本地系统) │ │
│ └─────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
2.1 Gateway：中央控制平面
Gateway 是 OpenClaw 的心脏。它是一个长期运行的 Node.js 守护进程，监听 localhost:18789，通过 WebSocket 与各渠道通信。
核心职责：
- 消息路由：接收来自不同渠道的消息，统一格式后分发给 Agent
- 认证鉴权：管理 API Key、Token、OAuth 认证状态
- 会话管理：维护多轮对话的状态和上下文
- 工具策略：根据安全配置决定哪些工具可用
// Gateway 消息处理伪代码
interface GatewayMessage {
channelId: string; // 渠道标识
userId: string; // 用户标识
sessionId: string; // 会话 ID
content: string; // 消息内容
attachments?: Media[]; // 附件
}
async function handleIncomingMessage(msg: GatewayMessage) {
// 1. 认证检查
const auth = await verifyAuth(msg.channelId, msg.userId);
if (!auth.valid) return sendAuthPrompt(msg.channelId);
// 2. 加载会话上下文
const session = await loadSession(msg.sessionId);
// 3. 查找匹配的 Agent
const agent = await resolveAgent(auth.profile, session);
// 4. 注入 Skills 和 Tools
const tools = await resolveTools(agent, auth.permissions);
// 5. 调用 LLM
const response = await agent.execute(msg.content, { session, tools });
// 6. 返回结果
await sendMessage(msg.channelId, response);
}
2.2 Agent：LLM 推理引擎
Agent 是 OpenClaw 的「大脑」。它的核心是基于 Pi Agent 框架的极简执行循环，代码总量不足 150 行。
执行循环的五个阶段：
// Agent 执行循环核心逻辑
async function runAgentLoop(agent: Agent, input: string) {
let context = await buildContext(agent);
let turnCount = 0;
const maxTurns = 50; // 防止无限循环
while (turnCount < maxTurns) {
// 1. 构建 Prompt
const prompt = await buildPrompt(agent, context);
// 2. 调用 LLM
const response = await callLLM(agent.model, prompt);
// 3. 解析工具调用
const toolCalls = parseToolCalls(response);
if (toolCalls.length === 0) {
// 无工具调用，返回最终答案
return response.content;
}
// 4. 执行工具
const toolResults = await Promise.all(
toolCalls.map(call => executeTool(agent, call))
);
// 5. 更新上下文
context = updateContext(context, response, toolResults);
turnCount++;
}
throw new Error('Max turns exceeded');
}
关键设计：身份与个性化
每个 Agent 都有独立的身份定义文件：
workspace/
├── IDENTITY.md # 身份标识（我是谁）
├── SOUL.md # 个性设定（说话风格）
├── USER.md # 用户信息（我在帮谁）
├── MEMORY.md # 长期记忆（重要经验）
├── TOOLS.md # 工具配置（我能用什么）
└── AGENTS.md # 工作区规则（行为准则）
这种设计让每个 Agent 都有独特的「人格」，而不是千篇一律的聊天机器人。
2.3 Skills：可复用的能力单元
Skills 是 OpenClaw 最具特色的设计之一。它解决了 AI Agent 的一个核心难题：如何让 Agent 具备领域专业知识，而不需要把所有知识写进系统提示词？
Skill 的本质是一个 Markdown 文件：
# SKILL.md
---
name: qclaw-text-file
description: 跨平台文本文件写入，自动处理编码、BOM、换行符
---
## 触发规则
当用户要求写入文本文件时，必须使用此技能。
## 核心能力
1. 自动检测目标平台（Windows/macOS/Linux）
2. 自动推断编码（UTF-8/UTF-8-BOM/GBK）
3. 自动适配换行符（CRLF/LF）
## 执行流程
1. 解析用户意图
2. 调用 `scripts/write_file.py`
3. 返回执行结果
Skills 的加载机制：
OpenClaw 采用分层索引 + 按需加载策略：
优先级（高 → 低）：
1. 工作区 Skills： <workspace>/skills/
2. 全局 Skills： ~/.openclaw/skills/
3. 内置 Skills： (随 OpenClaw 预装)
4. 扩展目录： skills.load.extraDirs 配置
启动时只加载元数据索引，当任务需要时才加载完整 Skill。这种设计让 OpenClaw 保持轻量，同时支持无限扩展。
2.4 Memory：三级记忆系统
OpenClaw 的 Memory 系统是它「越用越聪明」的关键。它采用三级架构：
┌─────────────────────────────────────────────────────────┐
│ Memory System │
├─────────────────────────────────────────────────────────┤
│ │
│ Level 1: Working Memory (工作记忆) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ • 当前对话上下文 │ │
│ │ • 最近 N 轮交互 │ │
│ │ • 会话状态 │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Level 2: Session Memory (会话记忆) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ • JSONL 格式的历史会话 │ │
│ │ • 自动压缩与摘要 │ │
│ │ • 按时间索引 │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Level 3: Long-term Memory (长期记忆) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ • MEMORY.md (用户维护的核心记忆) │ │
│ │ • memory/*.md (按日期的原始日志) │ │
│ │ • 向量索引 (语义检索) │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
记忆索引管线：
// 记忆索引流程
async function indexMemory(workspace: string) {
// 1. 发现文件
const files = await discoverFiles(workspace, ['MEMORY.md', 'memory/*.md']);
// 2. 变更检测
const changed = await detectChanges(files);
// 3. 文本分块
const chunks = await Promise.all(
changed.map(file => chunkText(file.content))
);
// 4. 向量嵌入
const embeddings = await embedBatch(chunks);
// 5. 写入索引
await writeIndex(embeddings);
}
三、Gateway 深度解析：消息路由的艺术
Gateway 是 OpenClaw 的中央枢纽，它的设计决定了系统的扩展性和稳定性。
3.1 适配器模式：统一多渠道接口
OpenClaw 支持 50+ 通讯平台，但它不是为每个平台写独立逻辑，而是采用适配器模式：
// 渠道适配器接口
interface ChannelAdapter {
// 渠道标识
readonly channelId: string;
// 初始化连接
connect(config: ChannelConfig): Promise<void>;
// 发送消息
sendMessage(target: string, content: MessageContent): Promise<void>;
// 接收消息（回调注册）
onMessage(handler: MessageHandler): void;
// 处理富媒体
handleMedia(attachment: Media): Promise<ProcessedMedia>;
// 连接状态
getStatus(): ConnectionStatus;
}
// WhatsApp 适配器示例
class WhatsAppAdapter implements ChannelAdapter {
readonly channelId = 'whatsapp';
async connect(config: WhatsAppConfig) {
this.client = new Client({
authStrategy: new LocalAuth({ clientId: config.clientId }),
puppeteer: { headless: true }
});
await this.client.initialize();
}
onMessage(handler: MessageHandler) {
this.client.on('message', async (msg) => {
const normalized: GatewayMessage = {
channelId: this.channelId,
userId: msg.from,
sessionId: getSessionId(msg.from),
content: msg.body,
attachments: await this.processMedia(msg)
};
handler(normalized);
});
}
}
这种设计让新增渠道变得极其简单——只需实现 ChannelAdapter 接口。
3.2 认证与会话管理
认证流程：
┌─────────┐ ┌──────────┐ ┌───────────┐
│ User │────▶│ Channel │────▶│ Gateway │
└─────────┘ └──────────┘ └─────┬─────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌──────────┐ ┌───────────┐ ┌──────────┐
│ Pairing │ │ Auth │ │ Session │
│ Check │ │ Profile │ │ Lookup │
└──────────┘ └───────────┘ └──────────┘
│ │ │
└──────────────────┼──────────────────┘
▼
┌────────────────┐
│ Auth Decision │
│ ✓/✗ │
└────────────────┘
安全机制：
- 配对验证：首次连接需要配对码确认
- 冷却期：认证失败后进入冷却期，防止暴力破解
- Token 轮换：支持动态 Token 轮换
- 权限隔离：不同用户有不同的工具权限
// 认证配置
interface AuthProfile {
userId: string;
channels: string[]; // 授权渠道
permissions: Permission[]; // 权限列表
rateLimit: RateLimit; // 速率限制
sandbox: SandboxConfig; // 沙箱配置
}
// 权限检查
async function checkPermission(
auth: AuthProfile,
tool: string,
action: string
): Promise<boolean> {
const policy = await loadToolPolicy(auth.userId);
// 检查工具是否在允许列表
if (!policy.allowedTools.includes(tool)) return false;
// 检查危险操作是否需要审批
if (policy.elevatedActions.includes(action)) {
return requestApproval(auth.userId, tool, action);
}
return true;
}
3.3 路由与负载均衡
当多个 Agent 同时运行时，Gateway 需要正确路由消息：
// Agent 路由逻辑
async function routeToAgent(
msg: GatewayMessage,
session: Session
): Promise<Agent> {
// 1. 检查会话是否已绑定 Agent
if (session.boundAgent) {
return await getAgent(session.boundAgent);
}
// 2. 检查渠道默认 Agent
const channelDefault = await getChannelDefaultAgent(msg.channelId);
if (channelDefault) {
return channelDefault;
}
// 3. 检查用户默认 Agent
const userDefault = await getUserDefaultAgent(msg.userId);
if (userDefault) {
return userDefault;
}
// 4. 返回全局默认 Agent
return await getGlobalDefaultAgent();
}
四、Agent 执行循环：从理解到行动
Agent 是 OpenClaw 的核心执行单元。它的执行循环决定了 AI 如何将用户意图转化为实际行动。
4.1 Prompt 构建：多源信息融合
每个 Agent 调用都需要构建完整的 Prompt，包含多个信息源：
async function buildPrompt(agent: Agent, context: Context): Promise<Prompt> {
const parts: PromptPart[] = [];
// 1. 系统提示词（基础能力定义）
parts.push({
role: 'system',
content: await loadSystemPrompt(agent)
});
// 2. 身份设定（IDENTITY.md + SOUL.md）
parts.push({
role: 'system',
content: await loadIdentity(agent.workspace)
});
// 3. 用户信息（USER.md）
parts.push({
role: 'system',
content: await loadUserInfo(agent.workspace)
});
// 4. 长期记忆（MEMORY.md）
const memory = await recallMemory(agent.workspace, context.query);
if (memory) {
parts.push({
role: 'system',
content: `相关记忆：\n${memory}`
});
}
// 5. 可用工具列表
parts.push({
role: 'system',
content: formatToolsPrompt(context.availableTools)
});
// 6. 加载的 Skills
for (const skill of context.loadedSkills) {
parts.push({
role: 'system',
content: await loadSkillContent(skill)
});
}
// 7. 历史对话
parts.push(...context.history);
// 8. 当前输入
parts.push({
role: 'user',
content: context.currentInput
});
return parts;
}
4.2 工具调用协议
OpenClaw 采用标准的 Tool Use 协议：
interface ToolCall {
id: string; // 调用 ID
name: string; // 工具名称
parameters: object; // 参数
}
interface ToolResult {
toolCallId: string; // 对应的调用 ID
result: any; // 执行结果
error?: string; // 错误信息
}
// 工具执行
async function executeTool(agent: Agent, call: ToolCall): Promise<ToolResult> {
// 1. 查找工具定义
const tool = agent.tools.find(t => t.name === call.name);
if (!tool) {
return { toolCallId: call.id, result: null, error: 'Tool not found' };
}
// 2. 参数校验
const validation = validateParameters(tool.schema, call.parameters);
if (!validation.valid) {
return { toolCallId: call.id, result: null, error: validation.error };
}
// 3. 权限检查
const hasPermission = await checkPermission(agent.auth, call.name, call.parameters);
if (!hasPermission) {
return { toolCallId: call.id, result: null, error: 'Permission denied' };
}
// 4. 执行工具
try {
const result = await tool.execute(call.parameters, {
agent,
sandbox: agent.sandbox,
timeout: tool.timeout || 30000
});
return { toolCallId: call.id, result };
} catch (error) {
return { toolCallId: call.id, result: null, error: error.message };
}
}
4.3 错误处理与重试
Agent 执行过程中的错误处理至关重要：
async function executeWithRetry(
agent: Agent,
call: ToolCall,
maxRetries: number = 3
): Promise<ToolResult> {
let lastError: Error;
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const result = await executeTool(agent, call);
if (result.error) {
// 可恢复错误，重试
if (isRecoverableError(result.error)) {
await delay(1000 * attempt); // 指数退避
continue;
}
// 不可恢复错误，直接返回
return result;
}
return result;
} catch (error) {
lastError = error;
if (isNetworkError(error)) {
await delay(1000 * attempt);
continue;
}
throw error;
}
}
return {
toolCallId: call.id,
result: null,
error: `Max retries exceeded: ${lastError.message}`
};
}
五、Skills 技能系统：知识外置的艺术
Skills 是 OpenClaw 最具创新性的设计之一。它解决了 AI Agent 的「知识诅咒」问题——如果把所有知识写进系统提示词，会导致 Token 消耗巨大且难以维护。
5.1 Skill 的设计哲学
核心思想：知识外置，按需加载
传统方案：
┌────────────────────────────────────────┐
│ System Prompt (10万+ tokens) │
│ ├─ 编程最佳实践 │
│ ├─ 文件处理规范 │
│ ├─ 网络请求规则 │
│ ├─ 浏览器操作指南 │
│ └─ ...所有领域知识 │
└────────────────────────────────────────┘
问题：每次调用都要加载，成本高，更新难
OpenClaw 方案：
┌────────────────────────────────────────┐
│ System Prompt (核心能力，5千 tokens) │
└────────────────────────────────────────┘
│
│ 按需加载
▼
┌────────────────────────────────────────┐
│ Skills (动态加载) │
│ ├─ 编程技能 (任务相关时加载) │
│ ├─ 文件处理 (任务相关时加载) │
│ ├─ 浏览器操作 (任务相关时加载) │
│ └─ ... │
└────────────────────────────────────────┘
优势：轻量启动，按需扩展，独立更新
5.2 SKILL.md 规范
每个 Skill 都是一个独立目录，核心文件是 SKILL.md：
my-skill/
├── SKILL.md # 技能定义（必需）
├── scripts/ # 执行脚本
│ ├── main.py
│ └── utils.sh
├── templates/ # 模板文件
│ └── report.md
└── references/ # 参考文档
└── guide.md
SKILL.md 五要素：
# SKILL.md
---
name: browser-automation
description: 浏览器自动化操作，支持页面导航、元素交互、截图
trigger:
keywords: [浏览器, 打开网页, 点击, 截图]
patterns: [打开.*, 访问.*, 截图]
---
## 1. 触发条件
当用户请求以下操作时触发：
- 打开/访问网页
- 点击页面元素
- 填写表单
- 截图/录屏
## 2. 核心能力
### 2.1 页面导航
```typescript
async function navigate(url: string): Promise<Page> {
// 实现代码...
}
2.2 元素交互
async function click(selector: string): Promise<void> {
// 实现代码...
}
3. 使用示例
示例 1：打开网页并截图
用户：打开百度首页并截图
执行流程：
- 调用 navigate('https://baidu.com')
- 等待页面加载完成
- 调用 screenshot()
4. 注意事项
- 需要浏览器驱动（Chrome/Edge）
- 复杂操作可能需要用户确认
- 敏感操作会触发审批流程
### 5.3 技能调用流程
```typescript
async function loadAndApplySkill(
agent: Agent,
task: string
): Promise<void> {
// 1. 分析任务，识别可能需要的 Skills
const taskKeywords = extractKeywords(task);
// 2. 从索引中查找匹配的 Skills
const matchedSkills = await searchSkillIndex(taskKeywords);
// 3. 按优先级排序
const sortedSkills = prioritizeSkills(matchedSkills, {
workspaceSkills: agent.workspace + '/skills',
globalSkills: '~/.openclaw/skills',
builtinSkills: 'openclaw://builtin/skills'
});
// 4. 加载 Skill 内容
for (const skill of sortedSkills.slice(0, 3)) { // 最多加载 3 个
const skillContent = await readSkillFile(skill.path + '/SKILL.md');
agent.context.loadedSkills.push({
name: skill.name,
content: skillContent
});
}
// 5. 注册 Skill 提供的工具
for (const skill of sortedSkills) {
const tools = await loadSkillTools(skill.path);
agent.tools.push(...tools);
}
}
5.4 实战案例：文本文件写入技能
这是一个真实的 Skill 案例，解决了跨平台文件编码问题：
# SKILL.md
---
name: qclaw-text-file
description: 跨平台纯文本文件写入，自动处理编码、BOM、换行符
---
## ⚠️ WRITE 工具拦截规则（最高优先级）
当准备调用内置 `write` 工具写入任何文本文件时，必须先执行此检查：
> 这个文件是最终目标文件吗？
> → 是 → 立即停止，改用此技能的脚本
> → 否（临时文件）→ 允许使用 write 工具
## 决策规则
❌ 禁止直接使用 write 工具写入：
- 代码文件（.ts, .js, .py, .go 等）
- 配置文件（.json, .yaml, .toml 等）
- 数据文件（.csv, .txt 等）
✅ 必须使用此技能的场景：
1. 写入、创建、保存任意文本文件
2. 涉及编码、BOM、换行符问题
## 核心能力
### 自动编码推断
| 平台 | 默认编码 | BOM |
|------|---------|-----|
| macOS | UTF-8 | 无 |
| Linux | UTF-8 | 无 |
| Windows | UTF-8-BOM / GBK | 有（Excel 兼容） |
### 换行符适配
| 平台 | 换行符 |
|------|--------|
| macOS/Linux | LF (\n) |
| Windows | CRLF (\r\n) |
## 执行脚本
```bash
python3 scripts/write_file.py \
--file /path/to/file.txt \
--content "内容" \
--platform windows \
--encoding utf-8-sig
这个 Skill 解决了一个真实痛点：在 Windows 上用 Python 的 `open()` 写 CSV，Excel 打开时中文乱码。通过将知识外置为 Skill，Agent 在处理文件写入时自动应用最佳实践。
---
## 六、Memory 记忆系统：让 AI 拥有长期记忆
Memory 系统是 OpenClaw 「越用越聪明」的关键。它不只是存储对话历史，而是构建了一个**可检索的知识库**。
### 6.1 三级记忆架构
┌─────────────────────────────────────────────────────────┐
│ Memory Hierarchy │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Level 1: Working Memory (工作记忆) │ │
│ │ │ │
│ │ • 容量：最近 N 轮对话 (N 可配置) │ │
│ │ • 存储：内存 │ │
│ │ • 访问：O(1) │ │
│ │ • 生命周期：会话结束即清空 │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Level 2: Session Memory (会话记忆) │ │
│ │ │ │
│ │ • 格式：JSONL (压缩存储) │ │
│ │ • 存储：本地文件系统 │ │
│ │ • 访问：按时间索引 + 向量检索 │ │
│ │ • 生命周期：永久保存（可配置过期） │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Level 3: Long-term Memory (长期记忆) │ │
│ │ │ │
│ │ • 格式：Markdown (人类可读) │ │
│ │ • 存储：MEMORY.md + memory/*.md │ │
│ │ • 访问：向量索引 + 关键词检索 │ │
│ │ • 生命周期：永久保存 │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
### 6.2 记忆索引与检索
**索引管线：**
```typescript
interface MemoryIndexer {
// 发现文件
discover(): Promise<MemoryFile[]>;
// 检测变更
detectChanges(files: MemoryFile[]): Promise<ChangedFile[]>;
// 文本分块
chunk(file: MemoryFile): Promise<TextChunk[]>;
// 向量嵌入
embed(chunks: TextChunk[]): Promise<Embedding[]>;
// 写入索引
index(embeddings: Embedding[]): Promise<void>;
}
// 分块策略
async function chunkText(content: string): Promise<TextChunk[]> {
const chunks: TextChunk[] = [];
// 1. 按段落分块
const paragraphs = content.split(/\n\n+/);
for (const para of paragraphs) {
// 2. 大段落再按句子分
if (para.length > 500) {
const sentences = para.match(/[^。！？.!?]+[。！？.!?]+/g) || [para];
for (const sentence of sentences) {
chunks.push({
text: sentence.trim(),
metadata: { length: sentence.length }
});
}
} else {
chunks.push({
text: para.trim(),
metadata: { length: para.length }
});
}
}
return chunks;
}
检索策略：
async function recallMemory(
workspace: string,
query: string
): Promise<string | null> {
// 1. 语义检索（向量相似度）
const semanticResults = await vectorSearch(query, {
collection: workspace,
topK: 5,
threshold: 0.75
});
// 2. 关键词检索（BM25）
const keywordResults = await keywordSearch(query, {
collection: workspace,
topK: 5
});
// 3. 融合排序
const fused = reciprocalRankFusion(
semanticResults,
keywordResults,
{ semanticWeight: 0.7, keywordWeight: 0.3 }
);
// 4. 格式化返回
if (fused.length === 0) return null;
return fused
.map((r, i) => `[${i + 1}] ${r.text}`)
.join('\n\n');
}
6.3 记忆压缩与摘要
长对话会占用大量 Token，OpenClaw 采用滚动摘要策略：
async function compressSession(
history: Message[],
targetTokens: number
): Promise<CompressedHistory> {
// 1. 保留最近 N 轮完整对话
const recentMessages = history.slice(-10);
// 2. 早期对话压缩为摘要
const oldMessages = history.slice(0, -10);
if (oldMessages.length === 0) {
return { messages: recentMessages, summary: null };
}
// 3. 调用 LLM 生成摘要
const summary = await generateSummary(oldMessages, {
maxLength: targetTokens,
preserveKeyFacts: true
});
return {
messages: recentMessages,
summary: {
content: summary,
originalRange: [0, oldMessages.length],
compressedAt: new Date().toISOString()
}
};
}
七、安全架构：本地优先的安全边界
OpenClaw 的安全设计遵循「安全默认」原则。
7.1 四层安全模型
┌─────────────────────────────────────────────────────────┐
│ Security Layers │
├─────────────────────────────────────────────────────────┤
│ │
│ Layer 1: 入口安全 (Gateway Security) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ • 配对验证（防止未授权访问） │ │
│ │ • 认证冷却期（防止暴力破解） │ │
│ │ • Token 轮换（防止凭证泄露） │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ Layer 2: 权限控制 (Permission Control) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ • 工具白名单（最小权限原则） │ │
│ │ • 危险操作审批（用户确认机制） │ │
│ │ • 速率限制（防止滥用） │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ Layer 3: 执行隔离 (Execution Sandbox) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ • Docker 容器隔离（可选） │ │
│ │ • 进程级沙箱（默认） │ │
│ │ • 文件系统隔离（限制访问范围） │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ Layer 4: 数据安全 (Data Security) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ • 本地存储（数据不出本机） │ │
│ │ • 加密存储（敏感信息加密） │ │
│ │ • 无云端依赖（离线可用） │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
7.2 审批流程
对于危险操作（如删除文件、发送邮件），OpenClaw 采用审批流程：
interface ApprovalRequest {
id: string;
userId: string;
tool: string;
parameters: object;
risk: 'low' | 'medium' | 'high';
reason: string;
createdAt: Date;
expiresAt: Date;
}
async function requestApproval(
userId: string,
tool: string,
parameters: object
): Promise<boolean> {
const risk = assessRisk(tool, parameters);
// 低风险操作自动通过
if (risk === 'low') return true;
// 中风险操作需用户确认
if (risk === 'medium') {
const approved = await askUserConfirmation(
userId,
`即将执行 ${tool}，参数：${JSON.stringify(parameters)}，是否继续？`
);
return approved;
}
// 高风险操作需双因素确认
if (risk === 'high') {
const code = generateConfirmationCode();
await sendNotification(userId, `确认码：${code}，有效期 5 分钟`);
const userInput = await waitForUserInput(userId, 300000);
return userInput === code;
}
return false;
}
7.3 沙箱隔离
OpenClaw 支持多种沙箱级别：
enum SandboxLevel {
// 无隔离：直接在本机执行
NONE = 'none',
// 进程级：限制进程权限
PROCESS = 'process',
// 容器级：Docker 容器隔离
CONTAINER = 'container',
// 虚拟机级：独立虚拟机
VM = 'vm'
}
// 沙箱配置
interface SandboxConfig {
level: SandboxLevel;
// 文件系统限制
filesystem: {
allowedPaths: string[];
deniedPaths: string[];
readOnlyPaths: string[];
};
// 网络限制
network: {
allowOutbound: boolean;
allowedDomains: string[];
deniedDomains: string[];
};
// 资源限制
resources: {
maxCpuPercent: number;
maxMemoryMB: number;
maxDiskMB: number;
timeoutMs: number;
};
}
八、实战案例：构建一个自动化工作流
让我们通过一个真实案例，演示如何使用 OpenClaw 构建自动化工作流。
8.1 场景描述
目标：每天早上 8 点，自动从 GitHub 拉取最新代码、运行测试、生成报告并发送到指定邮箱。
8.2 配置步骤
步骤 1：创建工作区
mkdir -p ~/openclaw-workspaces/daily-report
cd ~/openclaw-workspaces/daily-report
# 创建工作区文件
cat > AGENTS.md << 'EOF'
# 每日代码报告工作区
## 任务
每天早上 8 点：
1. 拉取 GitHub 仓库最新代码
2. 运行测试套件
3. 生成测试报告
4. 发送邮件到 team@example.com
EOF
# 创建用户配置
cat > USER.md << 'EOF'
# 用户信息
- 邮箱：team@example.com
- GitHub 仓库：myorg/myproject
- 分支：main
EOF
步骤 2：配置 Cron Job
// 在 OpenClaw 配置中添加定时任务
{
"crons": [
{
"name": "daily-code-report",
"schedule": "0 8 * * *",
"timezone": "Asia/Shanghai",
"sessionTarget": "isolated",
"payload": {
"kind": "agentTurn",
"message": "执行每日代码报告任务：拉取最新代码、运行测试、发送报告"
}
}
]
}
步骤 3：创建执行脚本
# scripts/daily_report.sh
#!/bin/bash
REPO_DIR="/path/to/myproject"
REPORT_FILE="/tmp/daily_report_$(date +%Y%m%d).md"
# 1. 拉取最新代码
cd $REPO_DIR
git pull origin main >> $REPORT_FILE 2>&1
# 2. 运行测试
echo "## 测试结果" >> $REPORT_FILE
npm test >> $REPORT_FILE 2>&1
# 3. 生成摘要
echo -e "\n## 摘要" >> $REPORT_FILE
echo "- 执行时间: $(date)" >> $REPORT_FILE
echo "- 仓库状态: $(git status -s | wc -l) 个文件变更" >> $REPORT_FILE
echo "- 测试状态: $(grep -c 'PASS' $REPORT_FILE || echo '0') 通过" >> $REPORT_FILE
cat $REPORT_FILE
8.3 执行流程
08:00 ─┬─ Cron 触发
│
▼
├─ Gateway 创建隔离会话
│
▼
├─ Agent 加载工作区配置
│
▼
├─ 执行 exec 工具
│ └─ bash scripts/daily_report.sh
│
▼
├─ 分析执行结果
│
▼
├─ 使用 message 工具发送邮件
│ └─ 发送到 team@example.com
│
▼
└─ 会话结束，记录日志
九、性能优化与生产部署
9.1 性能优化策略
1. 记忆索引优化
// 增量索引，避免全量重建
async function incrementalIndex(workspace: string) {
const lastIndexTime = await getLastIndexTime(workspace);
const changedFiles = await findChangedFiles(workspace, lastIndexTime);
if (changedFiles.length === 0) return; // 无变更
// 只处理变更文件
for (const file of changedFiles) {
await indexFile(file);
}
await updateIndexTime(workspace, Date.now());
}
2. 技能懒加载
// 启动时只加载元数据
async function preloadSkillMetadata() {
const skills = await discoverSkills();
for (const skill of skills) {
// 只读取 SKILL.md 前 50 行（元数据部分）
const metadata = await readSkillMetadata(skill.path);
skillIndex.set(skill.name, metadata);
}
}
// 按需加载完整内容
async function loadSkillContent(skillName: string) {
const metadata = skillIndex.get(skillName);
if (!metadata) return null;
// 检查缓存
if (skillCache.has(skillName)) {
return skillCache.get(skillName);
}
// 加载完整内容
const content = await readFile(metadata.path + '/SKILL.md');
skillCache.set(skillName, content);
return content;
}
3. 对话历史压缩
// 滚动压缩策略
const COMPRESSION_CONFIG = {
// 保留最近 10 轮完整对话
keepRecentTurns: 10,
// 早期对话压缩为摘要
compressionThreshold: 20, // 超过 20 轮触发压缩
// 摘要最大 Token 数
maxSummaryTokens: 500
};
9.2 生产部署架构
┌─────────────────────────────────────────────────────────┐
│ Production Deployment │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Nginx │────▶│ Gateway │ │
│ │ (反向代理) │ │ (主节点) │ │
│ └──────────────┘ └──────┬───────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Agent 1 │ │ Agent 2 │ │ Agent N │ │
│ │ (工作线程)│ │ (工作线程)│ │ (工作线程)│ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ └───────────────┼───────────────┘ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Redis │ │
│ │ (会话缓存) │ │
│ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ PostgreSQL │ │
│ │ (持久化存储) │ │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
高可用配置：
# docker-compose.yml
version: '3.8'
services:
gateway:
image: openclaw/gateway:latest
replicas: 2
environment:
- NODE_ENV=production
- REDIS_URL=redis://redis:6379
- DATABASE_URL=postgresql://user:pass@postgres:5432/openclaw
deploy:
resources:
limits:
cpus: '2'
memory: 4G
agent-worker:
image: openclaw/agent:latest
replicas: 4
environment:
- GATEWAY_URL=ws://gateway:18789
deploy:
resources:
limits:
cpus: '1'
memory: 2G
redis:
image: redis:7-alpine
volumes:
- redis-data:/data
postgres:
image: postgres:15-alpine
volumes:
- postgres-data:/var/lib/postgresql/data
environment:
- POSTGRES_DB=openclaw
- POSTGRES_USER=user
- POSTGRES_PASSWORD=pass
volumes:
redis-data:
postgres-data:
十、生态与未来展望
10.1 社区生态
截至 2026 年 6 月，OpenClaw 已形成完整的生态系统：
官方 Skills 库：
| 技能 | 功能 | Stars |
|---|---|---|
| browser-control | 浏览器自动化 | 12K+ |
| file-manager | 文件管理增强 | 8K+ |
| email-skill | 邮件发送 | 6K+ |
| web-scraper | 网页抓取 | 5K+ |
| database-tools | 数据库操作 | 4K+ |
渠道适配器：
- WhatsApp、Telegram、Discord、Slack、飞书
- 微信（通过企业微信 API）
- iMessage（macOS 专属）
- Signal、Matrix
模型支持：
- Anthropic Claude（默认推荐）
- OpenAI GPT 系列
- Google Gemini
- 本地模型：Ollama、LocalAI
10.2 与竞品对比
| 特性 | OpenClaw | LangChain | AutoGPT | Dify |
|---|---|---|---|---|
| 开箱即用 | ✅ | ❌ | ✅ | ✅ |
| 本地优先 | ✅ | ✅ | ✅ | ❌ |
| 多渠道支持 | 50+ | 需自建 | 无 | 有限 |
| Skills 扩展 | ✅ | Chains | ❌ | ✅ |
| 记忆系统 | 三级 | 向量库 | 有限 | 向量库 |
| 安全隔离 | 多层 | 无 | 无 | 有限 |
| 生产就绪 | ✅ | 需定制 | ❌ | ✅ |
10.3 未来发展方向
短期（2026 H2）：
- 增强多模态能力：支持图像理解、语音交互
- 改进记忆系统：引入更高效的向量索引
- 扩展 Skills 库：覆盖更多垂直领域
长期（2027+）：
- 联邦学习：多个 Agent 协作学习
- 知识图谱集成：结构化知识管理
- 自主能力进化：Agent 自我改进
十一、总结
OpenClaw 的成功不是偶然。它解决了一个核心痛点：让 AI 从「回答问题」升级为「执行任务」。
它的四大设计原则——Gateway 集中管控、Agent 极简执行、Skills 知识外置、Memory 三级记忆——构成了一个完整的 AI Agent 运行时。
对于开发者来说，OpenClaw 提供了一条清晰的路径：
- 从安装向导快速上手
- 通过配置而非代码定制行为
- 使用 Skills 扩展领域知识
- 利用 Memory 构建专属助手
对于企业来说，OpenClaw 的安全设计和生产就绪性使其成为可靠的自动化平台。
2026 年，AI Agent 正在从概念走向落地。OpenClaw 用 30 万 Star 证明了：本地优先、安全可靠、开箱即用的 AI 助手，才是开发者和企业的真实需求。
参考资料
- OpenClaw 官方文档：https://openclawcn.com/
- GitHub 仓库：https://github.com/openclaw/openclaw
- Pi Agent 框架：https://github.com/openclaw/pi-agent
- Skill 开发指南：https://openclawcn.com/skills/development
本文写于 2026 年 6 月 30 日，基于 OpenClaw v2.5 版本。