OpenManus源码部署实战：从零搭建本地AI Agent并解决浏览器路径问题

前阵子Manus刷屏朋友圈的时候，邀请码还是一码难求的状态。说实话我也试过抢，但没抢到，后来索性转投了开源方案。OpenManus就是那会儿冒出来的替代品——一个完全开源的通用AI Agent项目，把Manus的核心玩法搬到本地，让你用自己的模型、自己的工具、自己的浏览器，跑一套属于自己的智能体系统。

这篇文章把我从零开始部署OpenManus的完整过程写下来，包括源码拉取、Python环境构建、依赖编译安装、模型接入配置，以及最折磨人的浏览器路径优化问题。为什么浏览器路径值得单独拿出来讲？因为十个人里面至少有七个会在这上面翻车。全文都是实操记录，适合正在折腾AI大模型本地部署的朋友，尤其是想在Linux服务器上跑Agent的同学。

1. 源码部署前，先把OpenManus的定位和部署链路理清楚

1.1 它到底是什么：一个完全由你掌控的通用Agent

OpenManus本质上是开源社区对Manus工作方式的一次完整复刻。Manus当年的惊艳之处在于，你丢给它一句"帮我把这个文件夹里的简历全部看一遍，整理出一个排名表"，它能自己拆分任务、调用各种工具、一步步把活干完。但Manus是云端闭源的，排队、邀请码、按用量计费，这些门槛直接把很多人挡在门外。

OpenManus把核心逻辑开源了出来：它维持一套"大模型决策+多工具执行"的循环机制。大模型负责拆解指令、决定下一步调用什么，工具负责真正动手做事——执行Python代码、抓网页、跑浏览器、读写文件。这套机制跑在你自己控制的机器上，模型可以用云端API，也可以接本地Ollama，数据全程不出服务器。

部署之前我建议你先想清楚一件事：你要的是开箱即用的"工具"，还是一个可以随手改造的"框架"。如果是前者，直接去用网页版就好；如果是后者，愿意花半天时间去打磨配置、深入了解每一个组件的协作方式，那源码部署这条路就非常值得走。OpenManus的代码量不大，核心Agent逻辑集中在app/agent目录下，属于那种"你完全读得懂"的项目，这对后续做二次开发非常友好。

1.2 为什么我不推荐直接上Docker，而是走源码部署

网上其实有不少OpenManus的Docker部署方案，一条docker run命令就能拉起来。但我在实际对比之后，还是选择了从源码编译部署。原因很简单：Docker容器里的浏览器调用、宿主机网络代理、文件系统挂载，每一个环节都隔着一层抽象，报错的时候排查起来特别费劲。

源码部署最大的优势是透明。Python依赖装在哪个虚拟环境里、浏览器二进制放在哪个路径、config.toml里的配置有没有生效，这些问题都能直接看到。做浏览器路径优化的时候，你甚至可以直接改OpenManus源码里调用浏览器的参数，这个灵活度是Docker方案给不了的。

当然，源码部署也有代价。依赖冲突、Python版本匹配、底层包的编译失败，这些都是绕不开的坎。不过这篇文章后面把这些问题都整理成了具体的解决方案，你照着走的话，大概是能少走很多弯路。我的建议是：如果你想长期使用OpenManus，并且有改代码的需求，源码部署是唯一合理的选择；如果只是临时跑个demo，那Docker也不是不行，但本文接下来的所有路径优化内容，默认你是源码部署。

1.3 整个部署要经过哪些环节

我先把整条链路放在前面，让你心里有个全局感。OpenManus的部署不是一条命令搞定的事，它至少包含下面五个环节：

• 基础环境准备：安装Python运行环境，建议3.10及以上版本，配置虚拟环境。
• 源码获取：从GitHub克隆OpenManus仓库，切到稳定的release分支。
• 依赖安装：用pip安装requirements.txt里的依赖，这一步可能遇到pydantic-core等底层包的编译问题。
• 模型接入配置：编辑config.toml，填入模型服务商、API Key、模型名称。
• 工具链验证：启动项目，至少跑通一次浏览器调用和一次Python代码执行。

前四个环节其实是比较标准的Python项目部署流程，只要耐心一点，普通开发者都能搞定。真正让很多人卡住的是最后一个环节——浏览器调用。OpenManus默认的浏览器工具依赖browser-use这个库，而browser-use本身不内置浏览器，它需要你指定一个Chromium或者Chrome的可执行文件路径。这个路径怎么找、怎么配置、怎么在无图形界面的服务器上让它跑起来，就是文章第四章要解决的核心问题。

2. 环境规划与模型接入：部署前最容易忽略的两件事

2.1 硬件配置要求与我的实测运行环境

先说结论：OpenManus本身对硬件的要求非常低，因为它只是一个Agent编排框架，真正吃资源的是底层的大模型。如果你用云端API（比如DeepSeek、OpenAI），那本地硬件基本没有压力，2核CPU、4G内存的轻量服务器就能流畅跑。如果你打算用Ollama跑本地大模型，那配置要求就转移到显卡和内存上了。

照着我当时的实测环境说，我部署在一台Linux服务器上，配置是4核CPU、16G内存，没有独立GPU。模型接的是DeepSeek的云端API，跑Agent任务的时候CPU占用率不高，主要开销集中在浏览器渲染和Python执行上。如果你要在本地跑7B参数级别的模型，16G内存是底线，最好有8G以上显存的GPU，否则推理速度会非常折磨。

不同部署方式对应的配置参考如下：

我的建议是，如果你是第一次接触OpenManus，先别一上来就搞本地模型，直接用DeepSeek的API跑通全流程，成本很低，体验也最流畅。等整个链路跑通之后，再慢慢尝试接入Ollama本地模型。

2.2 Python虚拟环境与依赖管理工具的选择

OpenManus是纯Python项目，依赖管理的好坏直接决定部署是否顺利。不少人在部署时图省事，直接在系统Python环境里pip install，结果要么是权限问题，要么是和系统已有的包产生冲突，最后环境一团糟。我自己在部署时用的是venv，这也是官方文档推荐的方式。

Python版本方面，我建议3.10或者3.11。OpenManus用到了较新的类型注解语法和Pydantic特性，Python 3.9及以下版本可能会在安装依赖时出现兼容性问题。3.12和3.13目前虽然也能跑，但某些底层依赖（比如pydantic-core）没有预编译的wheel包，可能强制走本地编译，既慢又容易出错。所以卡在3.10或者3.11是最稳的选择。

创建环境很简单，三条命令搞定：

python3.11 -m venv openmanus_env source openmanus_env/bin/activate pip install --upgrade pip

这里有个经验，激活虚拟环境之后，我建议顺手把pip换到国内镜像源，否则安装一些大体积包（比如playwright的浏览器驱动）时，等待时间会让你怀疑人生。国内镜像源的配置方式是在当前shell里设置环境变量，或者直接写到~/.pip/pip.conf里。

2.3 模型后端怎么选：云API还是本地Ollama

这是部署前必须想清楚的决策点，因为OpenManus的Agent能力上限完全取决于模型本身。核心要求是：模型必须支持工具调用（function calling / tool use）。如果模型不支持工具调用，Agent就无法决定何时调用浏览器、何时执行Python代码，整个系统就瘫痪了。

云API方案里，DeepSeek是目前性价比非常高的选择。它支持OpenAI兼容格式的API，在OpenManus里只需要改一下base_url和model名称，就能直接接入。OpenAI的GPT系列同样兼容，但成本相对高一些。其他比如通义千问、Kimi、智谱GLM，也都提供OpenAI兼容接口，接入方式大同小异。

本地方案主要就是通过Ollama跑开源模型。Ollama本身支持OpenAI兼容接口，OpenManus只需要把base_url指向本地Ollama服务地址，填入一个假的api_key就能跑。但要注意，不是所有Ollama上的模型都支持工具调用。我实测下来，qwen2.5系列和llama3.1系列的工具调用能力是可用的，而一些通用聊天模型即使参数很大，也不一定能正确解析工具调用协议。

我整理了三种典型方案的区别：

我的建议是，第一遍部署用DeepSeek API跑通，后面再切换到本地Ollama。这样即使出问题，你也知道是模型的问题还是部署的问题，排查范围能缩小一半。

3. 从拉取源码到首次运行：一步一步完整实操

3.1 克隆代码并读懂项目目录结构

环境准备好之后，第一步是把代码拉下来。OpenManus的仓库地址是GitHub上的mannaandpoem/OpenManus，网络正常情况下直接用git clone就行。

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

拉下来之后建议立刻切到最新的稳定tag，避免开发分支上有未验证的代码影响使用。我当时的操作是通过git tag查看版本，然后checkout最新的release。这一步能让后续排错时参考的文档、issue跟代码版本对得上，非常重要。

接下来看一下目录结构，理解每个模块的职责比直接跑起来更值钱。核心目录和文件的作用如下：

• main.py：项目入口，命令行交互的主程序。
• app/agent/：Agent核心逻辑，manus.py是主Agent，sandbox.py负责工具调用循环。
• app/tool/：工具集，python_execute.py执行Python代码，browser_use_tool.py封装浏览器调用，还有web_search、web_fetch、file_operation等。
• app/config.py：配置加载逻辑，负责读取和校验配置文件。
• config/config.toml：真正的配置文件，所有模型参数都在这里改。
• requirements.txt：Python依赖清单。

我建议你打开app/agent/manus.py扫一眼，不要求全懂，但至少看看prompt是怎么写的、工具是怎么注册的。这样后面浏览器报错的时候，你会知道该去哪里改代码，而不是手足无措。

3.2 安装依赖：踩过编译坑之后的正确姿势

依赖安装是整个部署过程中最容易翻车的一步。OpenManus的核心依赖包括openai、pydantic、httpx、rich、playwright等。这里重点说两个坑。

第一个坑是pydantic版本冲突。OpenManus对pydantic的版本有一定要求，而很多服务器上已经装了其他版本的pydantic。我用venv就是为了隔离这些冲突，但即便如此，还是建议严格按照下面的顺序来安装依赖：

pip install -r requirements.txt

如果安装过程中报pydantic-core相关的编译错误，大概率是因为Python版本太新，没有对应的预编译wheel。解决办法是换到Python 3.11，而不是去装Rust工具链硬编译，否则你会在编译过程中浪费掉起码四十分钟。

第二个坑是playwright的安装。OpenManus的浏览器工具依赖playwright驱动浏览器，而pip install playwright并不会自动下载浏览器二进制文件，你需要手动执行：

playwright install chromium

这一步会下载约150MB的浏览器文件，如果网络不好，很容易失败。下载成功后，playwright会把Chromium安装到当前用户目录下的缓存路径。记住这个路径，第四章配置浏览器路径时会用到，它通常是~/.cache/ms-playwright/下的一个带版本号的子目录。

安装完依赖后，验证一下是否都装好了：

python -c "from openai import OpenAI; print('openai ok')" python -c "from pydantic import BaseModel; print('pydantic ok')" python -c "import playwright; print('playwright ok')"

三条命令都有输出，说明基础依赖没问题了。

3.3 config.toml配置实战：三种模型接入示例

依赖装好之后，开始配模型。OpenManus读取的是config/config.toml文件。首次拉取代码时，仓库里有一个config.toml.example，需要先复制一份再改动：

cp config/config.toml.example config/config.toml

config.toml的原始结构大致是这些内容（不同版本字段可能略有差异）：

[llm] model = "gpt-4o" base_url = "https://api.openai.com/v1" api_key = "sk-xxx" max_tokens = 4096 temperature = 1.0 [llm.vision] model = "gpt-4o" base_url = "https://api.openai.com/v1" api_key = "sk-xxx" max_tokens = 4096 temperature = 1.0

如果你用DeepSeek，把[llm]部分改成这样：

[llm] model = "deepseek-chat" base_url = "https://api.deepseek.com/v1" api_key = "sk-你的deepseek密钥" max_tokens = 8192 temperature = 1.0 [llm.vision] model = "deepseek-chat" base_url = "https://api.deepseek.com/v1" api_key = "sk-你的deepseek密钥" max_tokens = 8192 temperature = 1.0

如果你要用Ollama跑本地模型，base_url指向本地服务，api_key随便填一个非空字符串就行：

[llm] model = "qwen2.5:14b" base_url = "http://localhost:11434/v1" api_key = "ollama" max_tokens = 8192 temperature = 1.0 [llm.vision] model = "qwen2.5:14b" base_url = "http://localhost:11434/v1" api_key = "ollama" max_tokens = 8192 temperature = 1.0

注意，配置完成后最好用命令验证一下API连通性，避免启动之后才发现配置错误。DeepSeek的接口可以用一条curl命令测试，Ollama则确认一下服务有没有启动：

curl http://localhost:11434/v1/models

另外，api_key这个字段如果没有设置，在部分OpenManus版本里不会报错，但会在调用时返回401。如果Agent提示认证失败，第一个排查点就是这里。

3.4 首次启动：跑通第一个Agent任务

配置写好后，激动人心的时刻来了。启动OpenManus：

python main.py

如果一切正常，你会看到一个交互式命令行界面，提示你输入任务描述。我当时输的第一个任务是：帮我写一个Python脚本，计算斐波那契数列前20项并输出。

这个任务非常简单，主要目的是验证两点：模型能不能正确理解指令，以及Python执行工具能不能正常工作。OpenManus会先调用大模型生成代码，然后调用python_execute工具去执行，最后把执行结果返回给用户。整个流程跑通之后，输出里应该能看到类似"已完成任务"的提示。

首次运行很可能不会这么顺利，常见的情况是卡在某一步不执行、或者模型反复调用同一个工具。别慌，这多半是模型参数或者工具配置问题，第五章会集中讲排查方案。我的经验是，第一次跑通简单任务之后，再逐渐增加任务复杂度，不要一上来就给Agent一个包含多步骤的复杂任务，否则你会被各种异常搞到崩溃。

4. 浏览器路径优化：解决Agent"看不见网页"的老大难

4.1 为什么明明装了浏览器，Agent还是报错

这个问题是我在部署过程中花时间最长、查资料最多的地方，也是这篇文章的重点。OpenManus的浏览器工具用的是browser-use这个库，它不像Selenium那样自带引擎，而是需要通过Playwright来驱动一个真正的浏览器实例。换句话说，你的机器上必须有一个可以被Playwright控制的浏览器，而且这个浏览器的路径必须能被正确找到。

很多人在本地部署时，明明电脑上有Chrome，Agent却报错说找不到浏览器。原因在于browser-use默认去固定的位置找浏览器，而这个位置可能不是你的Chrome实际安装路径。Windows下Chrome安装在Program Files，macOS下在/Applications目录，Linux下可能在/usr/bin，各种发行版还不一样。你装了一个火狐，它却在本能地找谷歌浏览器，自然就找不到了。

还有一个容易忽略的点是无头服务器。很多人的OpenManus部署在云服务器上，服务器没有图形界面，也没有安装任何浏览器。这时候就算你配了API、装好了依赖，浏览器工具依然会报错，因为系统里压根没有浏览器这东西。解决办法不是装Chrome（它需要太多系统依赖），而是安装Chromium，再通过Playwright驱动它。

4.2 三种典型场景下的浏览器路径配置方案

我根据自己的部署经历，把浏览器路径问题分成了三种场景，每种场景的配置方式都不一样。

场景一：本地桌面系统（Windows/macOS）部署。这种场景最简单，因为你机器上大概率已经有Chrome或者Edge。关键是要找到浏览器的真实可执行文件路径。Windows下的Chrome路径通常是C:\Program Files\Google\Chrome\Application\chrome.exe，macOS下是/Applications/Google Chrome.app/Contents/MacOS/Google Chrome。拿到路径后，用下面的Python脚本测试能否被Playwright正常启动：

from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch( executable_path="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", headless=False ) page = browser.new_page() page.goto("https://example.com") print(page.title()) browser.close()

如果这个脚本能正常输出example.com的标题，说明浏览器本身没问题，接下来只需要把这个路径配置到OpenManus源码里。

场景二：Linux服务器部署（无图形界面）。这是最需要优化的场景。没有一个现成的Chrome可复用，需要单独安装Chromium。Ubuntu/Debian系的安装命令是：

sudo apt update sudo apt install -y chromium-browser

装完之后用which chromium-browser确认路径，通常会输出/usr/bin/chromium-browser。但这里有个坑：apt安装的chromium-browser在部分系统上只是一个过渡包，实际指向的可能是snap安装的版本，路径会特别长而且带snap前缀。这个版本在受限环境下经常出问题。

更稳妥的方式是用Playwright自带的Chromium。前面执行过playwright install chromium之后，浏览器驱动已经下载到本地了，路径在~/.cache/ms-playwright/下面。找到具体的可执行文件路径（一般在chromium-*/chrome-linux/chrome这一层），然后在代码里指定它。

场景三：Docker容器内部署。如果你非得用Docker，那浏览器路径问题会更麻烦。容器内通常没有任何浏览器，需要自己在Dockerfile里安装Playwright及其浏览器依赖。官方Playwright镜像会预先装好这些，所以最省事的方式是直接用playwright/python镜像作为基础镜像，再安装OpenManus依赖。这种方式我实际测试下来也能跑，但路径配置和宿主机是独立的，别指望容器内能访问宿主机路径。

4.3 沙箱、无头模式与路径优化的组合拳

找到浏览器路径只是第一步，真正让浏览器工具在OpenManus里稳定运行，还需要处理几个关联问题。

首先是无头模式。服务器上没有显示器，浏览器必须以headless模式运行。browser-use库默认可能会尝试启动有头模式，一旦检测不到显示环境就直接崩溃。此时需要在代码里显示指定headless=True。其次是沙箱问题。在Linux服务器上以root用户运行Chromium时，Chromium默认的沙箱机制会拒绝启动，报错信息里会有明显的"Running as root without --no-sandbox is not supported"字样。解决办法是在启动参数里加上--no-sandbox，但这有安全隐患，生产环境建议用普通用户运行。

我自己实际修改的方案是直接改OpenManus源码里调用浏览器的文件。在app/tool/目录下找到browser相关的工具实现，找到BrowserConfig初始化的地方，修改成类似这样：

from browser_use import BrowserConfig import os _browser_config = BrowserConfig( headless=True, executable_path=os.environ.get( "OPENMANUS_CHROME_PATH", "/usr/bin/chromium" ), extra_args=["--no-sandbox", "--disable-dev-shm-usage"] )

把启动参数和浏览器路径都集中定义在环境变量里，这样以后换机器、换环境，只需要重新设置环境变量，不用再改代码。我强烈建议所有做源码部署的人都采用这个模式。

对应的环境变量设置：

export OPENMANUS_CHROME_PATH="/usr/bin/chromium"

然后重新启动OpenManus，跑一个带网页抓取的任务测试。我当时的测试任务是让Agent去访问某个新闻网站首页，把标题列表提取出来。跑通之后，浏览器路径这块基本就稳了。

4.4 实测优化效果与性能对照

完成上述配置之后，我特意做了优化前后的对照。优化前，Agent一旦需要访问网页就卡在浏览器启动环节，报错后工具调用循环会中断，一个简单的抓取任务要反复重试五六次才能碰巧成功，耗时基本超过三分钟。优化后，浏览器能以无头模式秒开，首屏加载一般在两秒左右，简单的网页信息提取任务全程在二十秒内完成。

除了这些硬指标，还有一个体验上的提升：日志变得正常了。优化前每次报错都是半屏红色的Traceback，优化后日志干净清晰，Agent的每一步操作都能正常打印出来，这对后续调试Agent任务帮助非常大。

5. 常见报错排查与部署避坑实录

5.1 高频问题速查表

我把部署过程中最常见的报错和解决方案整理成了一张速查表，你如果遇到类似问题，可以直接按表排查。

表格里列的都是我实际遇到或者能在社区里高频看到的问题。尤其要强调第一行，api_key的问题出现的频率超乎想象。很多人以为填了密钥就一定对，但实际上OpenManus在某些版本里配置文件里的api_key如果为空字符串，它会静默用环境变量里的OPENAI_API_KEY去覆盖，导致你以为填对了其实用的是旧的。

5.2 我总结的几条独门部署经验

最后分享几条我自己的部署经验，这些是官方文档里不会写的。

第一条，用uv替代pip做依赖管理。uv是一个用Rust写的Python包管理器，解析依赖和安装的速度比pip快好几倍。处理OpenManus这种中等体量的依赖列表，等从几分钟缩短到几十秒。安装uv只需要一条命令，之后用uv pip install -r requirements.txt代替pip即可，虚拟环境仍然用venv管理，两者不冲突。

第二条，启动之前先单独测试各个工具是否可用。不要一上来就跑完整Agent。单独测试Python执行环境、单独测试浏览器驱动，两个工具各自没问题再组装起来。这样一旦运行时报错，你至少能确定问题不在工具层而在Agent逻辑层。

第三条，注意日志级别和输出。OpenManus用rich库做了很漂亮的终端输出，但有时候漂亮是漂亮，实际信息密度不高。调试阶段可以临时把日志级别调到DEBUG，看一下大模型的原始返回内容，往往能一眼看出是不是工具调用协议出了问题。这比我教你一百句"你换个模型试试"都好用。

第四条，给Agent的任务指令要具体。这一点很多人以为是模型问题，其实不是。OpenManus的Agent能力很大程度上取决于用户输入的任务描述质量。你让它"帮我查一下这个网站"，它可能无所适从；你说"访问xxx网站的新闻板块，提取前五条新闻的标题和发布时间，整理成表格返回"，它的执行成功率高得多。好的任务描述本身就是部署成功的一部分。

OpenManus这套东西，说到底是把大模型的决策能力和工具的执行能力串在了一起。部署的过程本身也是一次很好的系统性锻炼，你会同时接触到环境管理、模型接入、浏览器自动化、配置设计这些基础设施层面的知识。我个人在实际操作中的体会是，一旦把浏览器路径这个最大的拦路虎解决掉，整个Agent系统就跑得非常顺了。后续你可以在这个基础上继续扩展，比如给OpenManus加更多自定义工具，或者把模型从云端换成本地Ollama，最终打造出一套真正属于自己、完全可控的智能体工作流。