【技术干货】OpenManus 智能体框架深度解析：从 Agent Loop 到本地可控 AI 工作流实战

摘要

本文围绕 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 可能会拆解为：

1. 确定页面结构；
2. 设计 CSS 样式；
3. 编写 JavaScript 交互逻辑；
4. 保存为 HTML 文件；
5. 检查文件是否生成成功。

这一步依赖大语言模型的规划能力。模型质量越高，任务拆解越稳定。

2. 工具选择：Browser / Code / File System

Agent 并不是单纯生成文本，而是会根据任务选择工具：

• 文件系统：创建、读取、修改文件；
• 代码解释器：运行 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 开发和多模型调试中常用 薛定猫AI（xuedingmao.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 Key：

exportXDM_API_KEY="你的薛定猫AI API Key"

完整代码示例

importosimportjsonfrompathlibimportPathfromtypingimportDict,AnyfromopenaiimportOpenAIclassMiniAgent:""" 一个最小可运行的 Agent Loop 示例： - 使用 OpenAI 兼容 API 调用大模型 - 支持 write_file / read_file / finish 三类动作 - 通过 Plan-Act-Observe 循环完成任务 """def__init__(self,workspace:str="workspace"):self.workspace=Path(workspace)self.workspace.mkdir(exist_ok=True)self.client=OpenAI(api_key=os.getenv("XDM_API_KEY"),base_url="https://xuedingmao.com/v1")self.model="claude-opus-4-6"defcall_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_ascii=False)})response=self.client.chat.completions.create(model=self.model,messages=messages,temperature=0.2)content=response.choices[0].message.content.strip()try:returnjson.loads(content)exceptjson.JSONDecodeErrorasexc:raiseValueError(f"模型未返回合法 JSON：{content}")fromexcdefwrite_file(self,path:str,content:str)->str:""" 将内容写入 workspace 下的文件，避免越权写入系统目录。 """target=self.workspace/path target.parent.mkdir(parents=True,exist_ok=True)target.write_text(content,encoding="utf-8")returnf"文件已写入：{target}"defread_file(self,path:str)->str:""" 读取 workspace 下的文件内容。 """target=self.workspace/pathifnottarget.exists():returnf"文件不存在：{target}"returntarget.read_text(encoding="utf-8")[:3000]defrun(self,goal:str,max_steps:int=8):""" 执行 Agent Loop。 """history=[]forstepinrange(1,max_steps+1):print(f"\n========== Step{step}==========")decision=self.call_llm(goal,history)print("模型决策：")print(json.dumps(decision,ensure_ascii=False,indent=2))action=decision.get("action")action_input=decision.get("action_input",{})ifaction=="write_file":observation=self.write_file(path=action_input["path"],content=action_input["content"])elifaction=="read_file":observation=self.read_file(path=action_input["path"])elifaction=="finish":print("\n任务完成。")print(decision.get("thought",""))returnelse:observation=f"未知动作：{action}"print("执行结果：")print(observation)history.append({"decision":decision,"observation":observation})print("\n达到最大执行步数，任务终止。")if__name__=="__main__":agent=MiniAgent()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 依赖解析和安装速度上更有优势。

典型流程如下：

# 安装 uv，macOS / 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 #机器学习 #技术实战