摘要
本文围绕 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 System
Agent 并不是单纯生成文本，而是会根据任务选择工具：
- 文件系统：创建、读取、修改文件；
- 代码解释器：运行 Python、处理数据；
- 浏览器工具：访问网页、搜索信息；
- MCP 工具：通过 Model Context Protocol 连接外部系统；
- 多智能体协作：Planner Agent 与 Worker Agent 分工执行。
这也是 Agent 与普通 LLM 应用最大的区别：LLM 负责"决策"，工具负责"执行"。
3. Observe-Think-Act 循环
典型 Agent Loop 可以抽象为：
text
用户目标
↓
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 思路：
让模型根据用户目标决定下一步动作，并通过本地工具写入文件。
环境准备
bash
pip install openai设置 API Key：
bash
export XDM_API_KEY="你的薛定猫AI API Key"完整代码示例
python
import os
import json
from pathlib import Path
from typing import Dict, Any
from openai import OpenAI
class MiniAgent:
"""
一个最小可运行的 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"
def call_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}"}
]
for item in history:
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:
return json.loads(content)
except json.JSONDecodeError as exc:
raise ValueError(f"模型未返回合法 JSON：{content}") from exc
def write_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")
return f"文件已写入：{target}"
def read_file(self, path: str) -> str:
"""
读取 workspace 下的文件内容。
"""
target = self.workspace / path
if not target.exists():
return f"文件不存在：{target}"
return target.read_text(encoding="utf-8")[:3000]
def run(self, goal: str, max_steps: int = 8):
"""
执行 Agent Loop。
"""
history = []
for step in range(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", {})
if action == "write_file":
observation = self.write_file(
path=action_input["path"],
content=action_input["content"]
)
elif action == "read_file":
observation = self.read_file(
path=action_input["path"]
)
elif action == "finish":
print("\n任务完成。")
print(decision.get("thought", ""))
return
else:
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)运行：
bash
python mini_agent.py执行后会在 workspace 目录生成 habit_tracker.html。这个示例虽然简单，但已经包含 Agent 的关键机制：任务规划、工具调用、结果观察和循环修正。
OpenManus 安装与运行方式
OpenManus 官方提供 Conda 与 uv 两种方式。uv 在 Python 依赖解析和安装速度上更有优势。
典型流程如下：
bash
# 安装 uv，macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# 克隆项目
git clone https://github.com/mannaandpoem/OpenManus.git
cd OpenManus
# 创建虚拟环境并安装依赖
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt配置模型时，只要服务兼容 OpenAI API 格式，即可设置：
toml
base_url = "https://xuedingmao.com/v1"
api_key = "你的 API Key"
model = "claude-opus-4-6"常见入口包括：
bash
python main.py # 标准 Agent
python 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 #机器学习 #技术实战