OpenClaw 调用大模型原理（前端开发可直接借鉴）

OpenClaw 调用大模型的核心是 「统一抽象层 + 上下文组装 + 工具调用循环 + 结果标准化」，本质是把大模型从“纯文本生成”升级为“可执行任务的决策大脑”，前端做 AI 应用时可直接复用这套架构与流程。

一、核心定位：大模型是“决策大脑”，OpenClaw 是“执行身体”

• 大模型（LLM）：只负责 意图理解、任务拆解、工具选择、结果整合，不直接操作本地/网络资源。
• OpenClaw：负责 上下文管理、模型调用、工具执行、结果反馈、循环调度，是连接用户、大模型与本地能力的“执行网关”。
• 前端借鉴点：AI 应用必须做“决策层（LLM）与执行层（前端/后端）分离”，前端只做交互与结果渲染，不承担复杂推理。

二、整体架构：四层抽象，解耦模型与业务

OpenClaw 把大模型调用拆为 4 层标准化模块，前端可直接参考分层设计：

层级	核心职责	前端对应模块	关键作用
Gateway 网关层	接收用户输入、统一消息格式、会话管理、结果返回	前端请求拦截器、会话状态管理、消息收发组件	屏蔽渠道差异（Web/APP/CLI），统一入口出口
Agent 智能体层	上下文组装、模型调度、工具注册、循环控制	AI 对话核心服务、上下文管理器、工具调度器	大模型调用的“大脑”，控制整个流程
LLM 适配层	统一模型接口、参数格式化、响应解析、异常处理	大模型 API 封装类、请求适配器、响应转换器	屏蔽不同模型（GPT/通义/Llama）差异，即插即用
Skill/工具层	封装本地能力（文件/API/代码）、参数校验、执行逻辑	前端工具函数、API 调用模块、本地操作封装	大模型的“手”，把决策变成可执行动作

三、核心流程：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. 统一响应解析

无论模型返回格式如何，都解析为标准化结构：

// 标准化响应类型（前端可直接使用）
interface LLMResponse {
    type: "text" | "tool_call"; // 文本/工具调用
    content?: string; // 文本内容
    toolCalls?: Array<{
        name: string; // 技能名称
        parameters: Record<string, any>; // 技能参数
    }>;
    error?: string; // 错误信息
}

3. 模型适配器设计（前端可直接复用）

用 策略模式 封装不同模型的适配逻辑，新增模型只需加一个适配器，不修改上层代码：

// 统一 LLM 接口（前端/服务层通用）
interface LLMProvider {
    generate(messages: Message[], tools: Tool[]): Promise<LLMResponse>;
    generateStream(messages: Message[], tools: Tool[]): AsyncGenerator<LLMResponse>;
}

// 通义千问适配器
class QianwenProvider implements LLMProvider {
    private apiKey: string;
    constructor(apiKey: string) {
        this.apiKey = apiKey;
    }
    async generate(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;
        return parseAIResponse(text);
    }
}

// GPT 适配器
class OpenAIProvider implements LLMProvider {
    private apiKey: string;
    constructor(apiKey: string) {
        this.apiKey = apiKey;
    }
    async generate(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;
        return parseAIResponse(text);
    }
}

// 模型工厂（前端/服务层调用）
class LLMFactory {
    static getProvider(type: "openai" | "qianwen" | "llama", config: any): LLMProvider {
        switch (type) {
            case "openai":
                return new OpenAIProvider(config.apiKey);
            case "qianwen":
                return new QianwenProvider(config.apiKey);
            default:
                throw new Error("不支持的模型类型");
        }
    }
}

4. 前端调用示例（极简代码）

// 前端调用 AI 服务（只传用户输入 + 会话 ID）
async function callAI(userInput: string, sessionId: string) {
    try {
        // 1. 前端收集上下文（历史消息，从状态管理中取）
        const messages = getSessionHistory(sessionId);
        messages.push({ role: "user", content: userInput });

        // 2. 调用统一 LLM 服务（后端/Node 层封装）
        const response = await fetch("/api/llm/generate", {
            method: "POST",
            body: JSON.stringify({ messages, sessionId, stream: true }),
        });

        // 3. 处理流式响应（前端实时渲染）
        if (!response.ok) throw new Error(`API错误：${response.status}`);
        const reader = response.body.getReader();
        const decoder = new TextDecoder();
        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 应用。