OpenManus本地部署的图文教程分享

lichongyang

3 月前

以下是我为你整理的 OpenManus 本地部署图文教程 —— 包含从环境准备、安装、配置，到启动运行、常见问题与解决方案。适合想在本地（Windows / Linux / macOS／WSL）尝试这一开源 AI‑agent 框架的人。

1. 准备工作与环境要求

Python 版本：Python 3.12（多数用户反馈高于 3.12（如 3.13）可能出问题） (GitHub)
包管理器/虚拟环境工具：推荐使用 conda 或 uv + virtualenv 进行环境隔离。 (GitHub)
若你打算对接本地模型（如通过 Ollama）／大模型：建议显卡与内存资源足够，或至少能使用较轻量模型。 (CSDN博客)
如果计划使用自动化工具（例如浏览器自动化、文件 I/O、网页抓取等功能），建议同时安装附加依赖（如 playwright）以支持浏览器自动化功能。 (GitHub)

2. 获取源码 & 创建环境

步骤：

# 推荐使用 conda
conda create -n open_manus python=3.12
conda activate open_manus

然后，克隆源码：

git clone https://github.com/mannaandpoem/OpenManus.git
cd OpenManus

如果你无法使用 git，也可用 ZIP 包方式下载，但推荐保持 .git 信息以便后续更新。 (CSDN博客)

接着安装依赖：

pip install -r requirements.txt

如果你希望使用浏览器自动化等功能，可额外执行：

playwright install

> 这是可选但常用功能。 :contentReference[oaicite:9]{index=9}

---

## 3. 配置 OpenManus（尤其是 LLM / 模型配置）


::contentReference[oaicite:10]{index=10}


- 进入 `config/` 目录，将示例配置文件复制为实际配置文件：

```bash
cp config/config.example.toml config/config.toml

使用文本编辑器打开 config/config.toml，在 [[llm]] 或 [llm] 区块中填入你使用的模型／服务信息。举例（对接本地 Ollama）：

[llm]
api_type = "ollama"
model = "qwen2.5:14b"             # 或你本地部署／下载的模型名
base_url = "http://localhost:11434/v1"   # Ollama 服务地址
api_key = "ollama"                # Ollama 的默认 key（或空串）
max_tokens = 2048
temperature = 0.2

也可以配置视觉模型（image / vision）部分，若你希望使用图像 + LLM 联合的功能。 (CSDN博客)

注意：如果配置不正确（例如模型名称错误、base_url/端口错误、api_key 错误等），OpenManus 将无法连接 LLM，导致功能失败。建议先单独测试 LLM 服务是否可用后再配置。 (CSDN博客)

4. 启动 & 运行 OpenManus

最基础启动方式（命令行）：

python main.py

启动后，你会在终端看到提示，然后可以直接输入自然语言 prompt 与 Agent 对话／交互。 (GitHub)

如果你希望 Web 界面形式交互（而不是命令行），也有社区 → WebUI 支持／适配版本，例如可通过：

python web_run.py
# 或 uvicorn／FastAPI 等方式启动

然后通过浏览器访问 http://localhost:8000（或指定端口）操作。 (GitHub)

5. 常见问题 & 排查／避坑方案

问题 / 表现	可能原因 & 解决方法
LLM 服务连不上 / 报网络错误 / “function call not supported for this model”	模型配置有误（model 名称 / base_url / api_key /协议路径错误）；确认本地 LLM 服务（如 Ollama）已启动。 (Reddit)
路径或文件夹创建失败 / 无法写入 / 生成文件报错	在 Windows 下不要放在需要管理员权限的目录；建议放在用户目录 /普通文件夹，避免权限问题。 (Reddit)
Python 版本过高导致依赖冲突 / 报错	强制使用 Python 3.12 虚拟环境，不要使用系统默认 Python /版本过高 Python。 (GitHub)
功能模块不完整 / 浏览器自动化失败	如果不用浏览器功能，可跳过安装浏览器相关依赖；若需要，请确保 `playwright install` 成功。 (GitHub)
本地模型资源不足 / 推理缓慢或失败	使用轻量模型或降低上下文／token 数；如果机器性能有限，不建议尝试超大模型。 (CSDN博客)

6. 推荐 “新手 / 本地用户” 使用指南 & 最佳实践

优先用 命令行 + 本地模型（如 Ollama + 中小模型）进行测试与实验，这样不依赖云 API、延迟低、私密性高。
项目放在 普通用户目录，不要放在系统保护目录，也不要用管理员权限运行，以避免文件权限问题。
建议先测试基础对话／任务（如写文档、代码生成、简单工具调用） —— 等确认稳定后，再尝试复杂功能（浏览器抓取、多 agent 协作、文件操作等）。
如果你对多用户或长期使用感兴趣，可以将启动／停止封装成脚本、加入日志机制、定时备份工作目录。

7. 总结

OpenManus 是一个可以完全本地部署、免费、开箱即用的开源 AI‑agent 框架，非常适合希望探索 LLM + agent 功能但不依赖云服务的人。
通过上述步骤 —— 环境搭建 → 克隆 + 安装 → 配置 LLM → 启动运行 —— 通常能在 10–20 分钟内让系统跑起来。
虽然仍有兼容性、模型、资源、功能限制，但基于本地模型 + 本地代码 + 本地部署的开放性使其具有很强实用性和可玩性。