OpenManus User Guide

OpenManus is an open-source framework for building and running general-purpose AI agents — autonomous assistants that take a plain-language request, decide which tools to use, and work through the task step by step until it is done. It is the no-invite-code, fully open alternative to Manus, built by contributors from the MetaGPT community.

You describe a goal in natural language ("research the best laptops under $1000 and save a comparison to a file", "fix this failing test", "analyze sales.csv and chart the trend"). OpenManus's agent reasons about the goal, calls tools — a real browser, a Python interpreter, a shell, a file editor, web search — observes the results, and keeps going until it either finishes or you stop it.

Note

OpenManus is intentionally "a simple implementation" (the authors' words). It is a framework and a runnable agent, not a hosted product or a polished desktop app. You run it from your own terminal with your own LLM API key.

Table of Contents

1. Quick Start
2. Installation
3. Configuration
4. The Ways to Run OpenManus
5. What OpenManus Can Do — Tools & Capabilities
6. The Agents
7. Common Tasks & Recipes
8. Working With Different LLM Providers
9. Advanced Usage
10. How It Works (Concepts)
11. Troubleshooting
12. FAQ
13. Reference

1. Quick Start

Get a working agent in four steps.

# 1. Get the code
git clone https://github.com/FoundationAgents/OpenManus.git
cd OpenManus

# 2. Create an environment (Python 3.12 recommended) and install
conda create -n open_manus python=3.12 -y
conda activate open_manus
pip install -r requirements.txt

# 3. Add your LLM API key
cp config/config.example.toml config/config.toml
#    then edit config/config.toml and paste your api_key

# 4. Run it
python main.py

You will be prompted at the terminal:

Enter your prompt:

Type what you want done and press Enter. The agent starts thinking out loud, calling tools, and reporting results:

Processing your request...
Executing step 1/20
✨ Manus's thoughts: I'll start by searching the web for...
🧰 Tools being prepared: ['web_search']
🎯 Tool 'web_search' completed its mission! Result: ...
Executing step 2/20
...
Request processing completed.

Tip

You can skip the interactive prompt by passing the request on the command line:

python main.py --prompt "Summarize the README in this repo and save it to summary.txt"

2. Installation

Requirements

OpenManus has no GPU requirement and runs no model locally — all intelligence comes from the LLM API you point it at.

Method 1 — conda

conda

conda create -n open_manus python=3.12
conda activate open_manus

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

pip install -r requirements.txt

Method 2 — uv (recommended for speed)

uv

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

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

uv venv --python 3.12
source .venv/bin/activate          # Unix/macOS
# .venv\Scripts\activate           # Windows

uv pip install -r requirements.txt

Important

Always install from requirements.txt, not from setup.py (pip install -e .). The setup.py dependency list is missing tiktoken, which the token counter needs — installing that way produces ModuleNotFoundError: No module named 'tiktoken' at first run. See Troubleshooting.

Browser automation (optional)

If you want the agent to drive a real browser, install the Playwright browser binaries once:

playwright install

Warning

requirements.txt pins many libraries (browser-use, crawl4ai, pillow, browsergym, …) to exact versions. On some platforms uv reports a resolution conflict between crawl4ai and pillow. If that happens, install with pip inside a clean Python 3.12 environment, or relax the pillow pin. See Troubleshooting.

3. Configuration

All configuration lives in config/config.toml. There is no config.toml in a fresh clone — you create it by copying one of the provided examples.

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

Note

If config/config.toml does not exist, OpenManus automatically falls back to config/config.example.toml. Because the example file has a placeholder api_key = "YOUR_API_KEY", you must create your own config.toml with a real key before the agent can talk to an LLM.

Minimum working configuration

# Global LLM configuration
[llm]
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."          # your real key
max_tokens = 4096
temperature = 0.0

# Vision model (used when the agent needs to "see" screenshots, e.g. browsing)
[llm.vision]
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."

What each LLM setting does

Tip

Set temperature = 0.0 for agent work. Agents follow instructions and call tools more reliably when the model is deterministic.

Optional configuration sections

These sections are all optional; omit any you don't need.

# Browser behaviour
[browser]
headless = false              # set true to hide the browser window
disable_security = true       # relaxes browser security flags

# Route browser traffic through a proxy
[browser.proxy]
server = "http://proxy-server:port"
username = "proxy-username"
password = "proxy-password"

# Web-search engine preferences
[search]
engine = "Google"                                   # Google | Baidu | DuckDuckGo | Bing
fallback_engines = ["DuckDuckGo", "Baidu", "Bing"]  # tried in order if primary fails
retry_delay = 60                                    # seconds before retrying all engines
max_retries = 3
lang = "en"
country = "us"

# Optional Docker sandbox for tool execution
[sandbox]
use_sandbox = false
image = "python:3.12-slim"
work_dir = "/workspace"
memory_limit = "1g"
cpu_limit = 2.0
timeout = 300
network_enabled = true

# Model Context Protocol (MCP)
[mcp]
server_reference = "app.mcp.server"

# Multi-agent run_flow options
[runflow]
use_data_analysis_agent = false   # set true to add the data-analysis agent

Caution

The default browser settings are headless = false and disable_security = true. That means a visible browser window opens on your desktop and runs with security features relaxed. On a server or in CI, set headless = true. Only point the agent at sites you trust.

Connecting MCP servers (optional)

To let the agent use tools from external Model Context Protocol servers, create config/mcp.json:

{
    "mcpServers": {
        "server1": {
            "type": "sse",
            "url": "http://localhost:8000/sse"
        }
    }
}

Each entry supports type (sse or stdio), url (for SSE), and command + args (for stdio). See §9.

4. The Ways to Run OpenManus

OpenManus is not a single command — it ships several run modes, each backed by a different agent or workflow. Pick the one that matches your task.

main.py — the everyday agent

python main.py
# or
python main.py --prompt "Find the current weather in Tokyo and write it to weather.txt"

run_flow.py — planning across agents

python run_flow.py

This creates a planning flow: the system first asks the LLM to draft a step-by-step plan, then executes each step with an appropriate agent, marking steps complete as it goes. There is a built-in 60-minute timeout for the whole run.

Enter your prompt: Build a small report comparing three note-taking apps and save it as report.md
Processing your request...
Plan: ... (ID: plan_...)
0. [→] Research the three apps
1. [ ] Compare features
2. [ ] Write report.md
...

run_mcp.py — connect to an MCP server

python run_mcp.py                          # default: stdio, single prompt
python run_mcp.py --interactive            # interactive chat loop
python run_mcp.py --prompt "list my tools" # one prompt then exit
python run_mcp.py --connection sse --server-url http://127.0.0.1:8000/sse

run_mcp_server.py — be an MCP server

Exposes OpenManus's bash, browser, editor (str-replace), and terminate tools over MCP so other MCP-aware clients can call them.

python run_mcp_server.py                    # stdio transport (default)
python app/mcp/server.py --transport stdio  # equivalent

protocol/a2a/app/main.py — A2A server

python protocol/a2a/app/main.py --host localhost --port 10000

Note

The A2A server advertises Manus's skills (Python execution, browser use, file editing, ask-human, terminate) to other agents that speak the Agent-to-Agent protocol. Each task is capped at 3 steps by default in this mode.

5. What OpenManus Can Do — Tools & Capabilities

An OpenManus agent is only as capable as the tools it is given. Below is the full toolbox. The agent decides which to call; you rarely invoke them directly.

Browser actions in detail

When the agent browses, it issues browser_use actions. The full set:

Tip

You don't list these actions yourself. Just tell the agent the outcome you want ("open the GitHub trending page and list the top 5 repos") and it chooses the actions.

6. The Agents

Different run modes use different agents. They share the same think-act loop but carry different tools and personalities.

Note

Most agents run up to 20 steps by default before stopping. Each "step" is one think-then-act cycle (the agent reasons, then calls one or more tools).

7. Common Tasks & Recipes

All of these use python main.py (the Manus agent) unless noted. Provide the request either interactively or with --prompt.

Research and save findings to a file

python main.py --prompt "Research the top 3 open-source vector databases, compare them in a table, and save it as vectordbs.md"

The agent will web-search, browse or crawl pages, and use the file editor to write vectordbs.md in your working directory.

Analyze a local file with Python

python main.py --prompt "Read data.csv, compute the average of the 'price' column, and print the result"

The agent reads the file and runs python_execute to do the math.

Automate a website task

python main.py --prompt "Go to news.ycombinator.com and give me the titles and links of the top 5 stories"

Important

Browser tasks open a real browser (visible unless headless = true). Make sure Playwright is installed (playwright install).

Let the system plan a complex job

python run_flow.py
# Enter your prompt: Plan and write a 3-part blog series outline about RAG, saving each part to its own file

The planning flow drafts a plan, then executes the steps.

Data analysis with charts

First enable the data-analysis agent (see §9 for the Node.js prerequisite), then:

python run_flow.py
# Enter your prompt: Analyze sales.csv, find the monthly trend, and produce a chart

Charts are written under workspace/visualization.

Have the agent ask you when unsure

If a task is ambiguous, the agent may call ask_human:

Bot: Which output format do you want — Markdown or PDF?

You:

Type your answer and press Enter to continue.

8. Working With Different LLM Providers

One of OpenManus's strongest features is that it works with any OpenAI-compatible API, plus first-class Azure and AWS Bedrock support. You switch providers entirely through config/config.toml. The repo ships ready-made example files in config/ — copy one to config/config.toml and add your key.

Note

Internally, only api_type = "azure" and api_type = "aws" use special clients (Azure OpenAI and AWS Bedrock). Every other value — including ollama, jiekou, ppio, and unset — uses the standard OpenAI-compatible client pointed at your base_url. That's why so many providers "just work": they all expose an OpenAI-style API.

Example: use a local Ollama model (no API costs)

[llm]
api_type = 'ollama'
model = "llama3.2"
base_url = "http://localhost:11434/v1"
api_key = "ollama"
max_tokens = 4096
temperature = 0.0

[llm.vision]
api_type = 'ollama'
model = "llama3.2-vision"
base_url = "http://localhost:11434/v1"
api_key = "ollama"
max_tokens = 4096
temperature = 0.0

Example: Anthropic Claude

[llm]
model = "claude-3-7-sonnet-latest"
base_url = "https://api.anthropic.com/v1/"
api_key = "YOUR_API_KEY"
max_tokens = 8192
temperature = 0.0

Tip

The [llm.vision] block is used whenever the agent needs to interpret an image (most often a browser screenshot). Point it at a vision-capable model. If you don't browse with images, it can mirror your main [llm] block.

Warning

Some providers and models are reported not to work cleanly with the OpenAI-compatible tool-calling path OpenManus uses (for example, Gemini 2.0 has known issues — see Troubleshooting). If tool calls fail with a new model, try a model with strong function-calling support first.

9. Advanced Usage

Enable the data-analysis / chart agent

The chart-visualization toolchain uses Node.js packages (@visactor/vmind and @visactor/vchart) under the hood.

1. Install Node.js ≥ 18.

2. Install the JS dependencies:

   cd app/tool/chart_visualization
   npm install
   

3. Enable the agent in config/config.toml:

   [runflow]
   use_data_analysis_agent = true
   

4. Run via python run_flow.py.

Outputs (charts and reports) are written to workspace/visualization, as PNG or interactive HTML.

Use OpenManus's tools from another MCP client

Run OpenManus as an MCP server:

python run_mcp_server.py

It registers bash, browser, editor, and terminate as MCP tools over stdio. Any MCP-aware client (another agent, an IDE, etc.) can then call them.

Run in an isolated cloud sandbox (Daytona)

sandbox_main.py runs all tool execution inside a remote Daytona sandbox rather than on your machine — useful when you don't want the agent touching your local filesystem or running shell commands locally.

[daytona]
daytona_api_key = "your-daytona-key"

python sandbox_main.py --prompt "Set up a Python project skeleton and run the tests"

Caution

The sandbox agent needs a valid Daytona API key. Without one, it fails at startup with password must be provided / a Daytona authentication error.

Per-task step limits

Agents stop after a fixed number of steps (20 for most). If a task needs more, that's a code-level setting on the agent class — see the Admin Guide. For long planning jobs, prefer run_flow.py, which carries its own 60-minute wall-clock timeout.

10. How It Works (Concepts)

You don't need this section to use OpenManus, but it explains why the agent behaves the way it does.

The think–act loop. Every agent runs a loop: it thinks (sends the conversation plus available tools to the LLM and gets back either a message or tool calls), then acts (executes those tool calls and feeds the results back). This repeats until the agent calls terminate, finishes the task, or hits its step limit.

Memory. The agent keeps a running list of messages (your request, its thoughts, tool calls, and tool results). This memory is what it "sees" on each step. By default it retains up to 100 messages.

Tools as functions. Each tool advertises a name, description, and JSON parameter schema to the model. The model picks tools by name and supplies arguments; OpenManus runs the matching tool and returns an observation.

Stuck detection. If the agent repeats the same response too many times, it notices it is "stuck" and injects a prompt nudging it to try a different strategy:

Agent detected stuck state. Added prompt: Observed duplicate responses. Consider new strategies...

Planning flow. In run_flow.py, a planning layer first asks the LLM to produce a numbered plan, then walks the plan step by step, dispatching each step to an agent and marking it [✓] when done.

11. Troubleshooting

Errors are shown with the exact message below. Find yours.

Error: ModuleNotFoundError: No module named 'tiktoken'

Cause. You installed via setup.py (pip install -e .), whose dependency list omits tiktoken. The token counter imports it at startup.

Solution.

pip install -r requirements.txt
# or, just the missing package:
pip install tiktoken

Prevention. Always install from requirements.txt, not setup.py.

Error: ollama local model fails on Windows

Cause. Local models served via Ollama sometimes return responses the OpenAI-compatible tool-calling path can't parse, or the endpoint/model name is wrong.

Solution. Verify Ollama is running (ollama serve) and that base_url = "http://localhost:11434/v1" and api_type = 'ollama' are set. Use a model that supports tool/function calling. Smaller models often fail to produce valid tool calls.

Prevention. Start with a known-good cloud model to confirm your setup, then switch to Ollama.

Error: Docker Initialization failing

Cause. The Docker sandbox is enabled ([sandbox] use_sandbox = true) but Docker isn't running or the image can't be pulled.

Solution. Start Docker Desktop / the Docker daemon, confirm docker ps works, and make sure the configured image (default python:3.12-slim) can be pulled. Or disable the sandbox: use_sandbox = false.

Error: Daytona authentication crash on startup

Cause. sandbox_main.py requires a Daytona API key; without it you get password must be provided or a Daytona SDK auth error.

Solution. Add [daytona] daytona_api_key = "..." to config/config.toml, or run a non-sandbox mode (python main.py) instead.

Error: Dependency resolution failure with crawl4ai and pillow

Cause. The exact pins in requirements.txt can conflict during resolution (notably crawl4ai vs pillow), especially under uv.

Solution. Install inside a fresh Python 3.12 environment with pip install -r requirements.txt. If it still fails, relax the pillow pin or install crawl4ai separately. The crawl4ai tool also self-reports: Crawl4AI is not installed. Please install it with: pip install crawl4ai.

Error: Gemini 2.0 doesn't work

Cause. Gemini's OpenAI-compatible endpoint has known incompatibilities with the tool-calling flow.

Solution. Use the provided config.example-model-google.toml settings, and prefer a Gemini model with solid function-calling support. If tool calls keep failing, switch to an OpenAI or Anthropic model to confirm the rest of your setup works.

Error: Web search returns nothing / results look wrong

Cause. All configured search engines failed (rate limits or network), or content fetching is blocked. OpenManus logs All search engines failed... Giving up. after retries.

Solution. Set a different primary engine in [search] (e.g. engine = "DuckDuckGo"), increase max_retries, and check your network/proxy. Search still returns titles/URLs even when page-content fetching fails.

Note

There is a known bug in page-content fetching: the HTTP request sends a header keyed WebSearch instead of User-Agent, which some sites reject (GitHub issue #1334). Titles, URLs, and snippets are unaffected; only full-page content fetching is. See the Admin Guide for details.

Error: Agent gets stuck or loops

Cause. The model repeats the same unproductive response. OpenManus detects this and nudges it, but it can still stall.

Solution. Stop with Ctrl+C, rephrase your prompt to be more specific, lower temperature to 0.0, and break large goals into smaller ones. For multi-part jobs use python run_flow.py.

Error: Too many log files are created

Cause. OpenManus writes a timestamped log file under logs/ on each run.

Solution. Periodically clean the logs/ directory. This is expected behavior, not a failure.

Error: Tool calls required but none provided

Cause. An agent configured to require a tool call received a plain text response from the model instead.

Solution. Use a model with strong function-calling support and keep temperature = 0.0. Retry the request.

The browser window pops up unexpectedly

Cause. [browser] headless = false is the default, so a visible browser opens.

Solution. Set headless = true in [browser] for unattended/server runs.

12. FAQ

Q: Do I need a GPU or a local model? No. OpenManus runs no model itself — it calls an external LLM API. Any machine that runs Python 3.12 works.

Q: Which LLM should I use? A strong tool-calling model (e.g. GPT-4o or Claude 3.7 Sonnet) gives the most reliable agent behavior. Smaller or local models work but may produce malformed tool calls.

Q: How much will it cost? You pay your LLM provider per token. Agent runs can make many calls across up to 20 steps, so costs add up faster than a single chat. Set max_input_tokens to cap cumulative input, and use cheaper models for simple tasks.

Q: Where do files the agent creates end up? In the directory you run from, unless you tell the agent otherwise. The project's own scratch area is workspace/ (and workspace/visualization for charts).

Q: Is it safe to let it run shell commands and Python code? The agent can execute code and shell commands on your machine by default. Treat it like running scripts you didn't fully review. For isolation, enable the Docker [sandbox] or use sandbox_main.py (Daytona). See the Admin Guide's security section.

Q: What's the difference between main.py and run_flow.py? main.py runs a single capable agent (Manus). run_flow.py adds a planning layer that breaks the task into steps and executes them — better for complex, multi-stage jobs.

Q: Can it use my own tools? Yes — connect an MCP server via config/mcp.json and the agent picks up those tools automatically. You can also run OpenManus as an MCP server to share its tools.

Q: How do I stop a run? Press Ctrl+C. The agent cleans up resources (closes the browser, disconnects MCP) before exiting.

Q: Why did it stop after 20 steps? That's the default step limit. The run ends with Terminated: Reached max steps (20). Simplify the task, or use the planning flow for longer jobs.

Q: Does it support languages other than English? Yes. The agent works in any language the LLM supports, and the README ships in English, 中文, 한국어, and 日本語. Web search has lang and country settings.

Q: Can other agents talk to OpenManus? Yes — run the A2A server (protocol/a2a/app/main.py) to expose Manus over the Agent-to-Agent protocol, or the MCP server to expose its tools.

13. Reference

Run commands at a glance

Configuration sections

Default ports & timeouts

Example config files in config/

config.example.toml, config.example-daytona.toml, config.example-model-anthropic.toml, config.example-model-azure.toml, config.example-model-google.toml, config.example-model-jiekouai.toml, config.example-model-ollama.toml, config.example-model-ppio.toml, mcp.example.json.

Links

• Repository: https://github.com/FoundationAgents/OpenManus
• License: MIT
• Community: Discord and Feishu groups (linked from the repository README)
• Related: OpenManus-RL (RL tuning for agents)