夜雨聆风
OpenClaw 调用大模型的核心是 「统一抽象层 + 上下文组装 + 工具调用循环 + 结果标准化」，本质是把大模型从“纯文本生成”升级为“可执行任务的决策大脑”，前端做 AI 应用时可直接复用这套架构与流程。
一、核心定位：大模型是“决策大脑”，OpenClaw 是“执行身体”
• 大模型（LLM）：只负责 意图理解、任务拆解、工具选择、结果整合，不直接操作本地/网络资源。 • OpenClaw：负责 上下文管理、模型调用、工具执行、结果反馈、循环调度，是连接用户、大模型与本地能力的“执行网关”。 • 前端借鉴点：AI 应用必须做“决策层（LLM）与执行层（前端/后端）分离”，前端只做交互与结果渲染，不承担复杂推理。
二、整体架构：四层抽象，解耦模型与业务
OpenClaw 把大模型调用拆为 4 层标准化模块，前端可直接参考分层设计：
| Gateway 网关层 | |||
| Agent 智能体层 | |||
| LLM 适配层 | |||
| Skill/工具层 |
三、核心流程：Agent 循环（input → context → model → tools → repeat → reply）
这是 OpenClaw 调用大模型的 标准执行链路，前端做 AI 对话/工具调用时可完全复用：
1. 输入接收与会话管理（Gateway 层）
• 用户通过前端界面发送指令（如“帮我整理桌面文件”）。 • Gateway 识别会话 ID，合并历史消息，按会话序列化处理（避免并发冲突）。 • 前端借鉴：用会话 ID 隔离不同用户/对话，前端维护会话状态，后端/AI 服务只处理单会话逻辑。
2. 上下文组装（Agent 层，最关键一步）
Agent 把 所有必要信息拼接成高质量 Prompt，发给大模型，决定模型理解与决策的准确性：
• 系统提示（System Prompt）：定义角色、能力边界、输出格式（如“你是文件管理助手，可调用 file_rename 技能”）。 • 会话历史：用户与 AI 的多轮对话，保持上下文连贯性。 • 可用工具列表：把所有 Skill 转为 OpenAI Function Calling 格式（ tools数组），告诉大模型能调用哪些能力。• 记忆/配置：用户偏好、系统配置、历史任务结果，增强个性化。 • 前端借鉴：前端负责收集用户上下文（历史、偏好），传给后端/AI 服务，不直接拼接 Prompt，避免前端逻辑过重。
3. 大模型调用（LLM 适配层）
• 统一请求格式：Agent 把组装好的上下文转为 OpenAI 兼容格式（ model、messages、tools、temperature等参数）。• 模型调度：根据配置选择模型（GPT/通义/Llama），支持自动降级、负载均衡。 • 发送请求：通过 HTTP/SDK 调用模型 API，支持流式响应（前端实时展示打字效果）。 • 前端借鉴：封装统一的 LLM 请求函数，前端只传“用户输入 + 会话 ID”，由服务层处理模型选择与参数格式化。
4. 响应解析与决策（Agent 层）
大模型返回两种结果，Agent 分别处理：
• 纯文本结果：直接返回给用户，结束流程。 • 工具调用结果（Function Calling）：模型返回需要调用的 Skill 名称 + 参数，Agent 解析并触发工具执行。 • 前端借鉴：前端统一处理两种响应：文本直接渲染；工具调用显示“执行中”状态，等待结果返回。
5. 工具执行与结果反馈（Skill/Agent 层）
• Agent 调用对应 Skill（如 file_rename_batch），执行本地操作（文件/API/代码）。• 工具执行结果（成功/失败 + 数据）返回给 Agent。 • Agent 把工具结果 重新拼接到上下文，再次调用大模型，让模型基于结果做下一步决策（多轮工具调用）。 • 前端借鉴：前端不执行工具逻辑，只展示执行状态；工具执行由后端/Node 层处理，前端只接收最终结果。
6. 循环终止与结果返回
• 终止条件：模型返回纯文本、达到最大轮次（默认 20 轮）、工具执行失败无法恢复。 • Agent 整合所有结果，生成最终回复，通过 Gateway 返回给前端。 • 前端借鉴：前端设置超时与最大轮次限制，避免无限循环，提升用户体验。
四、LLM 适配层：统一接口，屏蔽模型差异（前端核心借鉴点）
OpenClaw 最值得前端复用的是 「模型无关的统一调用层」，无论对接 GPT、通义千问还是本地 Llama，上层逻辑完全不变：
1. 统一请求格式（OpenAI 兼容）
所有模型都转为 OpenAI Chat Completions 格式，前端/服务层只需要对接这一种格式：
{
"model":"qwen-turbo",// 模型名，可配置
"messages":[
{"role":"system","content":"你是文件管理助手，可调用文件操作技能"},
{"role":"user","content":"帮我批量重命名桌面图片"}
],
"tools":[
{
"type":"function",
"function":{
"name":"file_rename_batch",
"description":"批量重命名指定目录文件",
"parameters":{
"type":"object",
"properties":{
"fileDir":{"type":"string","description":"文件目录"},
"prefix":{"type":"string","description":"文件名前缀"}
},
"required":["fileDir"]
}
}
}
],
"temperature":0.7,
"stream":true// 流式响应，前端实时展示
}2. 统一响应解析
无论模型返回格式如何，都解析为标准化结构：
// 标准化响应类型（前端可直接使用）
interfaceLLMResponse {
type: "text" | "tool_call"; // 文本/工具调用
content?: string; // 文本内容
toolCalls?: Array<{
name: string; // 技能名称
parameters: Record<string, any>; // 技能参数
}>;
error?: string; // 错误信息
}3. 模型适配器设计（前端可直接复用）
用 策略模式 封装不同模型的适配逻辑，新增模型只需加一个适配器，不修改上层代码：
// 统一 LLM 接口（前端/服务层通用）
interfaceLLMProvider {
generate(messages: Message[], tools: Tool[]): Promise<LLMResponse>;
generateStream(messages: Message[], tools: Tool[]): AsyncGenerator<LLMResponse>;
}
// 通义千问适配器
classQianwenProviderimplementsLLMProvider {
privateapiKey: string;
constructor(apiKey: string) {
this.apiKey = apiKey;
}
asyncgenerate(messages: Message[], tools: Tool[]): Promise<LLMResponse> {
// 转为通义格式 → 调用 API → 解析为标准化响应
// 通义千问API请求格式
const res = await axios.post(
"https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation",
{
model: "qwen-turbo",
input: { messages },
parameters: {
tools: tools.map(tool => ({
type: "function",
function: tool.function,
})),
},
},
{
headers: { Authorization: `Bearer ${this.apiKey}` },
}
);
// 解析响应
const text = res.data.output.text;
returnparseAIResponse(text);
}
}
// GPT 适配器
classOpenAIProviderimplementsLLMProvider {
privateapiKey: string;
constructor(apiKey: string) {
this.apiKey = apiKey;
}
asyncgenerate(messages: Message[], tools: Tool[]): Promise<LLMResponse> {
// 直接用 OpenAI 格式 → 调用 API → 解析
const res = await axios.post(
"https://api.openai.com/v1/chat/completions",
{
model: "gpt-3.5-turbo",
messages,
tools: tools.map(tool => ({
type: "function",
function: tool.function,
})),
temperature: 0.7,
},
{
headers: { Authorization: `Bearer ${this.apiKey}` },
}
);
// 解析响应
const text = res.data.choices[0].message.content;
returnparseAIResponse(text);
}
}
// 模型工厂（前端/服务层调用）
classLLMFactory {
staticgetProvider(type: "openai" | "qianwen" | "llama", config: any): LLMProvider {
switch (type) {
case"openai":
returnnewOpenAIProvider(config.apiKey);
case"qianwen":
returnnewQianwenProvider(config.apiKey);
default:
thrownewError("不支持的模型类型");
}
}
}4. 前端调用示例（极简代码）
// 前端调用 AI 服务（只传用户输入 + 会话 ID）
asyncfunctioncallAI(userInput: string, sessionId: string) {
try {
// 1. 前端收集上下文（历史消息，从状态管理中取）
const messages = getSessionHistory(sessionId);
messages.push({ role: "user", content: userInput });
// 2. 调用统一 LLM 服务（后端/Node 层封装）
const response = awaitfetch("/api/llm/generate", {
method: "POST",
body: JSON.stringify({ messages, sessionId, stream: true }),
});
// 3. 处理流式响应（前端实时渲染）
if (!response.ok) thrownewError(`API错误：${response.status}`);
const reader = response.body.getReader();
const decoder = newTextDecoder();
let finalText = "";
while (true) {
const { done, value } = await reader.read();
if (done) break;
finalText += decoder.decode(value);
// 前端渲染文本/工具执行状态
renderAIResponse(finalText);
}
} catch (error) {
renderAIError(error.message);
}
}五、Skill 与大模型的联动原理（前端工具调用核心）
OpenClaw 让大模型调用 Skill 的核心是 「Skill 自动转 Function Calling + 执行结果回传」，前端做工具调用时可完全复用：
1. Skill 自动注册为工具
OpenClaw 启动时扫描 src/skills 目录，把每个 Skill 的 id、name、description、parameters 自动转为 OpenAI tools 格式，发给大模型。
• 前端借鉴：前端工具/组件自动注册为 AI 可调用能力，无需手动写 Prompt 告诉模型有哪些工具。
2. 工具调用流程（前端可直接复用）
1. 大模型返回 tool_call，包含 Skill 名称与参数。2. Agent 校验参数合法性（与 Skill 的 parameters匹配）。3. 执行 Skill 逻辑（文件/API/代码操作）。 4. 把执行结果（成功/失败 + 数据）拼回 messages，再次调用大模型。5. 大模型基于结果生成下一步决策或最终回复。
• 前端借鉴：前端工具调用完全由 AI 决策，前端只负责执行与状态展示，不干预决策逻辑。
六、前端开发核心借鉴点（直接落地）
1. 架构分层（必做）
• 交互层：前端页面、会话管理、消息渲染、状态展示。 • 服务层：统一 LLM 调用、上下文组装、工具调度、循环控制（Node/后端）。 • 能力层：Skill/工具封装（文件/API/代码），与业务解耦。
2. 上下文管理（关键）
• 前端维护 会话历史，每次请求传给服务层。 • 服务层拼接 系统提示 + 历史 + 工具列表，生成高质量 Prompt。 • 避免前端直接拼接 Prompt，保持前端轻量化。 • 上下文截断：前端/服务层应设置最大消息数（如最近10轮），超过后自动截断早期消息，避免上下文过长导致模型报错。
3. 统一模型接口（核心）
• 用 策略模式 封装不同模型适配器，支持一键切换模型。 • 所有模型请求/响应转为 标准化格式，上层逻辑不变。 • 前端只对接统一接口，不关心底层模型类型。
4. 工具调用联动（落地）
• 前端工具/组件自动注册为 AI 可调用能力。 • AI 决策调用工具，前端执行并返回结果。 • 支持 多轮工具调用，实现复杂任务自动化。
5. 流式响应与状态管理（体验优化）
• 开启 stream: true，前端实时展示 AI 打字效果。• 工具执行时显示“执行中”状态，提升用户感知。 • 设置 超时与最大轮次，避免无限循环。
七、常见问题与避坑（前端开发必看）
1. 模型响应格式不兼容：用统一适配器解析，前端只处理标准化响应。 2. 上下文过长导致模型报错：前端/服务层做 上下文截断，保留最近 N 轮对话。 3. 工具调用参数错误：服务层做 参数校验，与 Skill 定义一致，前端只传用户输入。 4. 流式响应乱码：前端用 TextDecoder正确解码，按 chunk 逐步渲染。5. 多轮调用超时：设置合理的超时时间，前端友好提示“任务执行中”。
八、总结
OpenClaw 调用大模型的本质是 「把大模型从文本生成器升级为任务决策器」，核心是 统一抽象、上下文驱动、工具联动、循环执行。前端开发 AI 应用时，直接复用这套架构：分层设计、统一模型接口、上下文管理、工具自动注册、多轮循环执行，就能快速打造出可落地、易扩展、体验好的 AI 应用。
