OpenClaw 源码解读:从「只会聊天」到「真正干活」的 AI 框架是怎么炼成的-夜雨聆风

OpenClaw 源码解读:从「只会聊天」到「真正干活」的 AI 框架是怎么炼成的

OpenClaw 源码解读：从「只会聊天」到「真正干活」的 AI 框架是怎么炼成的

编辑点评：OpenClaw 作为新一代 AI Agent 框架，最大的突破在于将 AI 从”聊天机器人”升级为”真正的生产力工具”。本文深入源码层面，解析其核心设计理念和实现细节，帮助开发者理解如何构建能够真正干活的 AI 系统。

一、痛点引入：为什么大多数 AI 框架只能聊天？

如果你用过市面上的 AI 助手，可能会发现一个共同问题：它们很会聊天，但不会干活。

Code

用户：帮我检查一下服务器的磁盘空间

AI：好的！磁盘空间管理很重要，建议您定期清理…

（但没有真正执行任何检查）

这种”只说不做”的 AI，本质上是一个高级聊天机器人，而不是真正的智能 Agent。

传统 AI 框架的三大痛点

• 工具调用能力弱 – 只能调用预设的简单 API

• 状态管理混乱 – 多轮对话后忘记上下文

• 安全边界模糊 – 要么权限过大危险，要么权限过小无用

OpenClaw 的源码设计，正是为了解决这些问题而生。

二、核心架构：OpenClaw 的三层设计

OpenClaw 的源码结构清晰，采用三层架构设计：

Code

┌─────────────────────────────────────┐

│ 会话管理层 (Session) │

│ – 会话状态维护 │

│ – 多轮对话上下文 │

│ – 子 Agent 协调 │

└─────────────────────────────────────┘

↓

┌─────────────────────────────────────┐

│ 工具执行层 (Tools) │

│ – 工具发现与注册 │

│ – 权限控制与安全沙箱 │

│ – 异步任务管理 │

└─────────────────────────────────────┘

↓

┌─────────────────────────────────────┐

│ 模型适配层 (Model) │

│ – 多模型统一接口 │

│ – Token 优化与缓存 │

│ – 流式响应处理 │

└─────────────────────────────────────┘

关键源码文件解析

1. 会话管理核心：`sessions.ts`

Code

// 会话状态机设计

classSessionManager{

privatesessions:Map<string,SessionState>=newMap();

asynccreateSession(config:SessionConfig):Promise<string>{

constsessionKey=generateSessionId();

constsession=newSessionState({

…config,

createdAt:Date.now(),

status:‘active’

});

// 关键：会话状态持久化

awaitthis.persistSession(sessionKey,session);

returnsessionKey;

}

asyncsendMessage(sessionKey:string,message:string):Promise<Response>{

constsession=awaitthis.getSession(sessionKey);

// 关键：上下文窗口管理

constcontext=this.buildContext(session,message);

// 关键：工具调用决策

constresponse=awaitthis.agent.process(context);

// 关键：状态更新与记忆

session.update(response);

awaitthis.persistSession(sessionKey,session);

returnresponse;

}

设计亮点：

• 会话状态机确保状态一致性

• 上下文窗口自动管理，避免 Token 超限

• 持久化存储支持跨会话恢复

2. 工具执行引擎：`tools/executor.ts`

Code

// 工具调用的安全执行器

classToolExecutor{

privatetoolRegistry:Map<string,Tool>=newMap();

privatepermissionMatrix:PermissionMatrix;

asyncexecute(toolName:string,params:any,context:ExecutionContext):Promise<any>{

consttool=this.toolRegistry.get(toolName);

if(!tool){

thrownewError(`工具未找到：${toolName}`);

}

// 关键：权限预检查

constpermission=this.permissionMatrix.check(

context.user,

tool.requiredPermission

);

if(!permission.granted){

thrownewPermissionDeniedError(`权限不足：${toolName}`);

}

// 关键：沙箱执行

if(tool.requiresSandbox){

returnawaitthis.executeInSandbox(tool,params,context);

}

// 关键：超时控制

returnawaitPromise.race([

tool.execute(params,context),

timeout(tool.timeout||30000)

]);

}

privateasyncexecuteInSandbox(tool:Tool,params:any,context:ExecutionContext):Promise<any>{

// 使用 Node.js Worker Threads 或子进程隔离

constsandbox=awaitSandbox.create({

memoryLimit:tool.memoryLimit||‘256MB’,

cpuLimit:tool.cpuLimit||‘50%’,

networkAccess:tool.networkAccess||false

});

try{

returnawaitsandbox.execute(tool.code,params);

}finally{

awaitsandbox.destroy();

}

设计亮点：

• 权限矩阵确保工具调用安全

• 沙箱隔离防止恶意代码执行

• 超时控制避免资源耗尽

3. 模型适配器：`models/adapter.ts`

typescript

// 统一模型接口设计

interfaceModelAdapter{

generate(prompt:string,options:GenerateOptions):Promise<GenerationResult>;

stream(prompt:string,options:GenerateOptions):AsyncIterable<Chunk>;

countTokens(text:string):number;

}

// 阿里云百炼适配器示例

classAliyunAdapterimplementsModelAdapter{

privateapiKey:string;

privatebaseUrl:string;

asyncgenerate(prompt:string,options:GenerateOptions):Promise<GenerationResult>{

constresponse=awaitfetch(`${this.baseUrl}/chat/completions`,{

method:‘POST’,

headers:{

‘Authorization’:`Bearer ${this.apiKey}`,

‘Content-Type’:‘application/json’

body:JSON.stringify({

model:options.model||‘qwen3.5-plus’,

messages:this.formatMessages(prompt),

max_tokens:options.maxTokens||4096,

stream:false

})

});

constdata=awaitresponse.json();

returnthis.parseResponse(data);

}

async*stream(prompt:string,options:GenerateOptions):AsyncIterable<Chunk>{

constresponse=awaitfetch(`${this.baseUrl}/chat/completions`,{

method:‘POST’,

headers:{/* … */},

body:JSON.stringify({/* … */,stream:true})

});

constreader=response.body.getReader();

constdecoder=newTextDecoder();

while(true){

const{done,value}=awaitreader.read();

if(done)break;

constchunk=decoder.decode(value);

// 解析 SSE 格式

for(constlineofchunk.split(‘\n’)){

if(line.startsWith(‘data: ‘)){

constdata=JSON.parse(line.slice(6));

yieldthis.parseChunk(data);

}

设计亮点：

• 统一接口支持多模型切换

• 流式响应优化用户体验

• Token 计数辅助上下文管理

三、关键方法 1：工具发现与动态注册

OpenClaw 的第一个关键方法是工具动态注册机制。

传统做法 vs OpenClaw 做法

对比项

传统框架

OpenClaw

工具注册

硬编码在源码中

运行时动态发现

新增工具

需要修改源码并重启

添加 SKILL.md 即可

权限控制

全局统一权限

工具级细粒度权限

版本管理

手动管理

支持 ClawHub 版本控制

实现细节

Code

// 工具发现器

classToolDiscovery{

privateskillPaths:string[]=[

‘~/.openclaw/skills’,

‘~/.local/share/openclaw/skills’,

‘./workspace/skills’

];

asyncdiscover():Promise<Tool[]>{

consttools:Tool[]=[];

for(constskillPathofthis.skillPaths){

constskills=awaitthis.scanDirectory(skillPath);

for(constskillofskills){

constmanifest=awaitthis.parseSkillManifest(skill);

consttool=this.manifestToTool(manifest);

tools.push(tool);

}

returntools;

}

privateasyncparseSkillManifest(skillDir:string):Promise<SkillManifest>{

constmanifestPath=path.join(skillDir,‘SKILL.md’);

constcontent=awaitfs.readFile(manifestPath,‘utf-8’);

// 解析 Frontmatter

constfrontmatter=this.extractFrontmatter(content);

return{

name:frontmatter.name,

description:frontmatter.description,

location:skillDir,

tools:this.parseToolsSection(content),

permissions:this.parsePermissions(content)

};

}

核心优势：

• 零代码扩展 – 新增工具无需修改框架源码

• 权限隔离 – 每个工具声明自己的权限需求

• 版本管理 – 支持 ClawHub 进行工具版本控制

四、关键方法 2：上下文窗口智能管理

OpenClaw 的第二个关键方法是上下文窗口智能管理。

问题背景

大模型有 Token 限制（如 Qwen3.5-plus 最大 32K），但对话历史可能无限增长。如何：
1. 保留重要上下文
2. 丢弃冗余信息
3. 避免 Token 超限

OpenClaw 的解决方案

typescript

// 上下文管理器

classContextManager{

privatemaxTokens:number=28000;// 预留空间给响应

privatecompressionThreshold:number=0.8;

asyncbuildContext(session:Session,newMessage:string):Promise<Context>{

constmessages=session.messages;

constcurrentTokens=this.countTokens(messages);

// 策略 1：如果未超限，直接返回

if(currentTokens<this.maxTokens*this.compressionThreshold){

returnthis.formatContext(messages,newMessage);

}

// 策略 2：压缩旧消息

constcompressed=awaitthis.compressOldMessages(messages);

returnthis.formatContext(compressed,newMessage);

}

privateasynccompressOldMessages(messages:Message[]):Promise<Message[]>{

// 保留最近的 N 条消息

constrecentCount=10;

constrecentMessages=messages.slice(–recentCount);

// 压缩早期消息为摘要

constoldMessages=messages.slice(0,–recentCount);

if(oldMessages.length===0)returnrecentMessages;

constsummary=awaitthis.generateSummary(oldMessages);

return[

{role:‘system’,content:`历史对话摘要：${summary}`},

…recentMessages

];

}

privateasyncgenerateSummary(messages:Message[]):Promise<string>{

// 使用小模型快速生成摘要

constprompt=`请总结以下对话的关键信息：

${messages.map(m=>`${m.role}: ${m.content}`).join(‘\n’)}

请用 200 字以内总结核心内容。`;

constresult=awaitthis.fastModel.generate(prompt);

returnresult.content;

}

核心策略：

• 分层管理 – 近期消息保留原文，早期消息压缩为摘要

• 智能摘要 – 使用小模型快速生成历史摘要

• 增量更新 – 只处理新增消息，避免重复计算

五、关键方法 3：子 Agent 协同与任务分解

OpenClaw 的第三个关键方法是子 Agent 协同机制。

为什么需要子 Agent？

单个 Agent 面临以下限制：

• 上下文窗口有限 – 复杂任务需要多次交互

• 专业领域知识 – 不同任务需要不同专家

• 并行执行需求 – 独立任务可以并行处理

OpenClaw 的子 Agent 架构

Code

// 子 Agent 管理器

classSubAgentManager{

privateagents:Map<string,SubAgent>=newMap();

asyncspawn(task:string,options:SpawnOptions):Promise<SubAgent>{

constagent=newSubAgent({

task,

runtime:options.runtime||‘subagent’,

mode:options.mode||‘run’,

timeout:options.timeout||300000

});

// 关键：继承父 Agent 的工作空间和权限

agent.inheritContext(this.parentContext);

// 关键：建立通信通道

constchannel=awaitthis.createChannel(agent);

agent.setChannel(channel);

this.agents.set(agent.id,agent);

returnagent;

}

asynccoordinate(task:string):Promise<Result>{

// 任务分解

constsubtasks=awaitthis.decomposeTask(task);

// 并行执行

constresults=awaitPromise.all(

subtasks.map(st=>this.spawn(st.task,st.options))

);

// 结果聚合

returnthis.aggregateResults(results);

}

privateasyncdecomposeTask(task:string):Promise<Subtask[]>{

// 使用 LLM 进行任务分解

constprompt=`将以下任务分解为可并行执行的子任务：

${task}

返回 JSON 格式的子任务列表。`;

constresult=awaitthis.model.generate(prompt);

returnJSON.parse(result.content);

}

实战案例：代码审查任务

typescript

// 用户请求：审查这个 PR

constresult=awaitagent.coordinate(`

审查 GitHub PR #123，包括：

1. 代码质量检查

2. 安全漏洞扫描

3. 性能影响评估

4. 测试覆盖率分析

`);

// 内部执行流程：

// 1. 分解为 4 个子任务

// 2. 并行启动 4 个子 Agent

// 3. 每个子 Agent 调用专业工具

// 4. 聚合结果生成综合报告

核心优势：

• 并行加速 – 独立任务并行执行

• 专业分工 – 每个子 Agent 专注特定领域

• 结果聚合 – 自动生成综合报告

六、实战演练：用 OpenClaw 构建自动化工作流

场景：每日安全情报自动收集

Code

# 工作流配置

name:每日安全情报

schedule:“08***”# 每天早上 8 点

steps:

–name:获取威胁情报

tool:tencent-security-api

params:

date:yesterday

types:[vulnerability,malware,apt]

–name:分析影响范围

tool:impact-analyzer

params:

assets:${company_assets}

threats:${step1.output}

–name:生成报告

tool:report-generator

params:

template:daily-briefing

data:${step2.output}

–name:发送通知

tool:message

params:

channel:security-team

content:${step3.output}

实现代码

typescript

// 工作流执行器

constworkflow=awaitWorkflow.fromConfig(‘daily-intel.yaml’);

constresult=awaitworkflow.execute();

// 输出：

// 获取威胁情报：发现 3 个高危漏洞

// 分析影响范围：2 个系统受影响

// 生成报告：/tmp/daily-briefing-20260407.md

// 发送通知：已发送到 security-team 频道

七、避坑指南：OpenClaw 使用中的常见问题

问题 1：工具调用超时

现象：工具执行时间过长导致超时

解决方案：

Code

// 方法 1：增加超时时间

tool.timeout=120000;// 2 分钟

// 方法 2：使用后台任务

constsession=awaitsessions.spawn(task,{background:true});

// 方法 3：分页/分批处理

constresults=awaitprocessInBatches(items,batchSize:100);

问题 2：上下文丢失

现象：多轮对话后 AI 忘记之前的内容

解决方案：

typescript

// 方法 1：显式保存关键信息

session.metadata.set(‘user_preference’,preference);

// 方法 2：使用记忆工具

awaitmemory_search(query);

awaitmemory_get(path);

// 方法 3：定期摘要压缩

if(session.messageCount%10===0){

awaitcontextManager.compress(session);

}

问题 3：权限配置错误

现象：工具调用被拒绝

解决方案：

Code

# 检查权限配置

openclawconfigshowpermissions

# 添加工具权限

openclawconfigsettools.my-tool.permissionallow

# 使用 allowlist 模式

openclawconfigsetsecurity.modeallowlist

openclawconfigsettools.allowlist“tool1,tool2,tool3”

八、总结与行动建议

OpenClaw 的三个关键方法

方法

解决的问题

实现效果

工具动态注册

扩展性差

零代码新增工具

上下文智能管理

Token 超限

无限对话长度

子 Agent 协同

复杂任务处理

并行加速 + 专业分工

给开发者的建议

• 从简单工具开始 – 先实现一个 SKILL.md，理解工具注册流程

• 善用记忆系统 – 将重要信息写入 MEMORY.md，避免上下文丢失

• 合理使用子 Agent – 复杂任务分解为独立子任务

• 关注安全边界 – 理解权限模型，避免过度授权

下一步行动

typescript

# 1. 安装 OpenClaw

npminstall-gopenclaw

# 2. 初始化工作空间

openclawinitmy-project

cdmy-project

# 3. 创建第一个技能

mkdir-pskills/my-first-skill

cat>skills/my-first-skill/SKILL.md<< ‘EOF’

—

name: my-first-skill

description: 我的第一个 OpenClaw 技能

—

## 触发条件

当用户说”你好”时触发

## 执行逻辑

1. 读取用户信息

2. 生成个性化问候

3. 返回问候语

EOF

# 4. 测试技能

openclawtestmy-first-skill

声明：本文基于 OpenClaw 公开源码分析，如有技术细节更新，请以官方文档为准。

参考资料：

• OpenClaw 官方文档：https://docs.openclaw.ai

• GitHub 仓库：https://github.com/openclaw/openclaw

• 技能市场：https://clawhub.ai

互动话题：你用过哪些 AI Agent 框架？OpenClaw 的哪些设计让你印象深刻？欢迎在评论区分享你的看法！

1. 会话管理核心：sessions.ts

2. 工具执行引擎：tools/executor.ts

3. 模型适配器：models/adapter.ts

1. 会话管理核心：`sessions.ts`

2. 工具执行引擎：`tools/executor.ts`

3. 模型适配器：`models/adapter.ts`