摘要本文围绕 OpenManus 这类开源 AI Agent 框架解析其任务规划、工具调用、自我校验机制并通过 OpenAI 兼容 API 构建一个最小可运行 Agent 示例帮助开发者理解智能体底层运行逻辑。背景介绍从“聊天机器人”到“执行型智能体”Manus 这类 AI Agent 的核心价值不在于生成一段文本回答而在于能够围绕用户目标自动拆解任务、选择工具、执行操作并验证结果。例如构建一个网页应用生成数据表格和可视化图表编写桌面工具执行互联网调研创建演示文稿传统 ChatBot 更像“问答系统”而 Agent 更接近“自动化工作流执行器”。用户只需要给出一个目标系统会自动完成从规划到落地的过程。视频中提到的 Manus 在 GAIA 等通用智能体评测中表现较强但其问题也很明显闭源、不可修改 Agent Loop、无法自由切换模型、数据需经过托管服务器。对于开发者来说这意味着可控性不足。OpenManus 正是为了解决这一问题出现的。它不是一个成熟的商业产品而是一个开源 Agent 框架开发者可以在本地运行、修改执行逻辑、接入自己的模型 API并观察每一步推理与工具调用过程。核心原理OpenManus 的 Agent Loop 如何工作1. 目标拆解从自然语言到任务计划OpenManus 的第一步是将用户输入的自然语言目标拆解成多个可执行步骤。例如用户输入创建一个简洁的习惯追踪器 HTML 页面支持标记每日完成状态。Agent 可能会拆解为确定页面结构设计 CSS 样式编写 JavaScript 交互逻辑保存为 HTML 文件检查文件是否生成成功。这一步依赖大语言模型的规划能力。模型质量越高任务拆解越稳定。2. 工具选择Browser / Code / File SystemAgent 并不是单纯生成文本而是会根据任务选择工具文件系统创建、读取、修改文件代码解释器运行 Python、处理数据浏览器工具访问网页、搜索信息MCP 工具通过 Model Context Protocol 连接外部系统多智能体协作Planner Agent 与 Worker Agent 分工执行。这也是 Agent 与普通 LLM 应用最大的区别LLM 负责“决策”工具负责“执行”。3. Observe-Think-Act 循环典型 Agent Loop 可以抽象为用户目标 ↓ Plan制定计划 ↓ Act调用工具 ↓ Observe读取执行结果 ↓ Reflect判断是否完成或修正 ↓ 继续执行 / 输出结果视频中提到的“自纠错机制”是 Agent 框架最关键的能力。它不是一次性输出而是会检查执行结果再决定是否继续修复。技术资源与工具选型OpenManus 支持 OpenAI API 格式的模型服务这意味着只要服务商兼容base_url api_key model的接入方式就可以快速替换底层模型。我个人在 AI 开发和多模型调试中常用 薛定猫AIxuedingmao.com。它的价值主要体现在工程集成层面聚合 500 主流大模型包括 GPT-5.4、Claude 4.6、Gemini 3.1 Pro 等新模型实时首发开发者可以较早验证前沿模型 API统一 OpenAI 兼容接口减少多模型适配成本对 Agent 框架而言切换模型只需要修改model字段便于横向评估推理、规划和工具调用能力。下面实战代码默认使用claude-opus-4-6。该模型在复杂推理、长上下文理解、代码生成和任务规划方面表现突出适合用作 Agent 的核心决策模型。实战演示用 Python 构建一个最小 Agent Loop下面示例实现一个简化版 OpenManus 思路让模型根据用户目标决定下一步动作并通过本地工具写入文件。环境准备pipinstallopenai设置 API KeyexportXDM_API_KEY你的薛定猫AI API Key完整代码示例importosimportjsonfrompathlibimportPathfromtypingimportDict,AnyfromopenaiimportOpenAIclassMiniAgent: 一个最小可运行的 Agent Loop 示例 - 使用 OpenAI 兼容 API 调用大模型 - 支持 write_file / read_file / finish 三类动作 - 通过 Plan-Act-Observe 循环完成任务 def__init__(self,workspace:strworkspace):self.workspacePath(workspace)self.workspace.mkdir(exist_okTrue)self.clientOpenAI(api_keyos.getenv(XDM_API_KEY),base_urlhttps://xuedingmao.com/v1)self.modelclaude-opus-4-6defcall_llm(self,goal:str,history:list)-Dict[str,Any]: 调用大模型让模型输出结构化 JSON 指令。 system_prompt 你是一个严谨的 AI Agent。你需要根据用户目标和历史观察结果选择下一步动作。 你只能输出 JSON不要输出 Markdown不要添加解释。 JSON 格式如下 { thought: 你的简要思考, action: write_file | read_file | finish, action_input: { path: 文件路径, content: 写入内容仅 write_file 需要 } } 规则 1. 如果需要创建文件使用 write_file。 2. 如果需要检查文件使用 read_file。 3. 如果任务完成使用 finish。 4. 文件路径必须是相对路径。 messages[{role:system,content:system_prompt},{role:user,content:f用户目标{goal}}]foriteminhistory:messages.append({role:assistant,content:json.dumps(item,ensure_asciiFalse)})responseself.client.chat.completions.create(modelself.model,messagesmessages,temperature0.2)contentresponse.choices[0].message.content.strip()try:returnjson.loads(content)exceptjson.JSONDecodeErrorasexc:raiseValueError(f模型未返回合法 JSON{content})fromexcdefwrite_file(self,path:str,content:str)-str: 将内容写入 workspace 下的文件避免越权写入系统目录。 targetself.workspace/path target.parent.mkdir(parentsTrue,exist_okTrue)target.write_text(content,encodingutf-8)returnf文件已写入{target}defread_file(self,path:str)-str: 读取 workspace 下的文件内容。 targetself.workspace/pathifnottarget.exists():returnf文件不存在{target}returntarget.read_text(encodingutf-8)[:3000]defrun(self,goal:str,max_steps:int8): 执行 Agent Loop。 history[]forstepinrange(1,max_steps1):print(f\n Step{step})decisionself.call_llm(goal,history)print(模型决策)print(json.dumps(decision,ensure_asciiFalse,indent2))actiondecision.get(action)action_inputdecision.get(action_input,{})ifactionwrite_file:observationself.write_file(pathaction_input[path],contentaction_input[content])elifactionread_file:observationself.read_file(pathaction_input[path])elifactionfinish:print(\n任务完成。)print(decision.get(thought,))returnelse:observationf未知动作{action}print(执行结果)print(observation)history.append({decision:decision,observation:observation})print(\n达到最大执行步数任务终止。)if__name____main__:agentMiniAgent()user_goal 创建一个单文件 habit_tracker.html。 要求 1. 页面设计简洁 2. 使用 HTML CSS JavaScript 3. 支持点击按钮标记今天是否完成 4. 使用 localStorage 保存状态 5. 文件生成后检查内容。 agent.run(user_goal)运行python mini_agent.py执行后会在workspace目录生成habit_tracker.html。这个示例虽然简单但已经包含 Agent 的关键机制任务规划、工具调用、结果观察和循环修正。OpenManus 安装与运行方式OpenManus 官方提供 Conda 与 uv 两种方式。uv 在 Python 依赖解析和安装速度上更有优势。典型流程如下# 安装 uvmacOS / Linuxcurl-LsSfhttps://astral.sh/uv/install.sh|sh# 克隆项目gitclone https://github.com/mannaandpoem/OpenManus.gitcdOpenManus# 创建虚拟环境并安装依赖uv venvsource.venv/bin/activate uv pipinstall-rrequirements.txt配置模型时只要服务兼容 OpenAI API 格式即可设置base_url https://xuedingmao.com/v1 api_key 你的 API Key model claude-opus-4-6常见入口包括python main.py# 标准 Agentpython run_mcp.py# MCP 工具模式python run_flow.py# 多智能体模式其中 MCP 模式适合连接外部工具多智能体模式适合数据分析、复杂任务拆解等场景。注意事项开发者需要关注的工程问题1. 模型质量直接影响 Agent 表现Agent 每一步都依赖模型决策。较弱模型容易出现计划不完整工具选择错误陷入循环无法正确修复错误。复杂任务中应优先关注模型的推理、代码和工具调用能力。2. API 成本可能快速增长Agent 的每一步通常都是一次完整 LLM 调用。一个任务执行 10 步就可能产生 10 次以上请求。因此需要设置最大执行步数控制上下文长度对 API 账户设置消费上限对重复失败动作做熔断处理。3. 本地运行不等于完全离线OpenManus 在本地运行文件和执行逻辑在自己机器上但模型推理仍然需要访问外部 API。真正离线运行需要接入本地大模型但效果通常取决于模型规模和工具调用能力。4. 开源框架更适合二次开发相比 Manus 这类托管产品OpenManus 缺少精致 UI 和深度调优体验但它的优势是透明、可控、可扩展。对于想理解 Agent 内部机制、构建私有自动化工作流的开发者开源框架更具研究和工程价值。总结OpenManus 的意义不在于完全复刻 Manus 的产品体验而在于把 Agent 的底层机制暴露给开发者任务拆解、工具调用、执行观察、自我修正、多模型接入。它更像一个可组装的智能体开发套件适合用于学习、实验和构建企业内部自动化原型。随着 MCP、多智能体协作、强化学习优化工具使用等方向持续发展AI Agent 正从“能聊天”走向“能执行”。闭源产品负责展示上限开源框架则推动技术真正进入开发者工作流。#AI #大模型 #Python #机器学习 #技术实战