# 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](https://github.com/geekan/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](#1-quick-start)
2. [Installation](#2-installation)
3. [Configuration](#3-configuration)
4. [The Ways to Run OpenManus](#4-the-ways-to-run-openmanus)
5. [What OpenManus Can Do — Tools & Capabilities](#5-what-openmanus-can-do--tools--capabilities)
6. [The Agents](#6-the-agents)
7. [Common Tasks & Recipes](#7-common-tasks--recipes)
8. [Working With Different LLM Providers](#8-working-with-different-llm-providers)
9. [Advanced Usage](#9-advanced-usage)
10. [How It Works (Concepts)](#10-how-it-works-concepts)
11. [Troubleshooting](#11-troubleshooting)
12. [FAQ](#12-faq)
13. [Reference](#13-reference)

---

## 1. Quick Start

Get a working agent in four steps.

```bash
# 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:

```text
Enter your prompt:
```

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

```text
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:
> ```bash
> python main.py --prompt "Summarize the README in this repo and save it to summary.txt"
> ```

---

## 2. Installation

### Requirements

| Requirement | Detail |
|---|---|
| Python | **3.12** recommended. The package metadata requires `>=3.12`; the runtime prints a warning outside the 3.11–3.13 range. |
| LLM API key | An API key for any OpenAI-compatible endpoint (OpenAI, Anthropic, Azure OpenAI, Ollama, Google Gemini, and others — see [§8](#8-working-with-different-llm-providers)). |
| OS | Windows, macOS, or Linux. |
| Node.js ≥ 18 | **Only** if you use the data-analysis / chart-visualization agent (see [§9](#9-advanced-usage)). |
| Docker | **Only** if you enable the optional Docker sandbox. |

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"

    ```bash
    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"

    ```bash
    # 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](#error-modulenotfounderror-no-module-named-tiktoken).

### Browser automation (optional)

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

```bash
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](#error-dependency-resolution-failure-with-crawl4ai-and-pillow).

---

## 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.

```bash
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

```toml
# 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

| Key | Meaning | Default |
|---|---|---|
| `model` | Model name to call. | — (required) |
| `base_url` | API endpoint URL. | — (required) |
| `api_key` | Your API key. | — (required) |
| `max_tokens` | Maximum tokens in each response. | `4096` |
| `max_input_tokens` | Cap on cumulative input tokens across the whole run (omit for unlimited). | unlimited |
| `temperature` | Sampling randomness. `0.0` = deterministic. | `1.0` |
| `api_type` | `azure`, `aws`, `ollama`, etc. Leave unset for standard OpenAI-compatible APIs. | `""` |
| `api_version` | Required only for Azure OpenAI. | `""` |

> [!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.

```toml
# 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](https://modelcontextprotocol.io) servers, create `config/mcp.json`:

```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](#9-advanced-usage).

---

## 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.

| Command | What it runs | Use it when… |
|---|---|---|
| `python main.py` | The **Manus** general-purpose agent | You want one capable agent that can browse, code, edit files, and search. **Start here.** |
| `python run_flow.py` | The **planning flow** (multi-agent) | You want the system to break a complex task into a plan and execute it step by step. |
| `python run_mcp.py` | The **MCP client agent** | You want an agent that connects to an MCP server and uses its tools. |
| `python run_mcp_server.py` | OpenManus **as an MCP server** | You want to expose OpenManus's tools (bash, browser, editor, terminate) to *another* MCP client. |
| `python sandbox_main.py` | The **SandboxManus** agent | You want tools to run inside a remote [Daytona](https://www.daytona.io) cloud sandbox instead of on your machine. |
| `python protocol/a2a/app/main.py` | The **A2A** agent server | You want to expose Manus over the Agent-to-Agent (A2A) protocol as an HTTP service. |

### `main.py` — the everyday agent

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

| Flag | Type | Default | Description |
|---|---|---|---|
| `--prompt` | string | _(interactive)_ | The request for the agent. If omitted, you are prompted at the terminal. |

### `run_flow.py` — planning across agents

```bash
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.

```text
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

```bash
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
```

| Flag | Alias | Default | Description |
|---|---|---|---|
| `--connection` | `-c` | `stdio` | Connection type: `stdio` or `sse`. |
| `--server-url` | | `http://127.0.0.1:8000/sse` | URL for an SSE connection. |
| `--interactive` | `-i` | off | Run an interactive chat loop (type `exit`, `quit`, or `q` to leave). |
| `--prompt` | `-p` | | Run a single prompt and exit. |

### `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.

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

| Flag | Default | Description |
|---|---|---|
| `--transport` | `stdio` | Communication method. |

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

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

| Flag | Type | Default | Description |
|---|---|---|---|
| `--host` | string | `localhost` | Host address to bind. |
| `--port` | int | `10000` | Port to listen on. |

> [!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.

| Tool | Name in logs | What it does |
|---|---|---|
| Web browser | `browser_use` | Drives a real browser: navigate, click, type, scroll, read dropdowns, switch/open/close tabs, extract page content, run a web search and open the top result. |
| Web search | `web_search` | Searches Google / Baidu / DuckDuckGo / Bing (with automatic fallback) and returns titles, URLs, snippets, and optionally fetched page text. |
| Web crawler | `crawl4ai` | Crawls one or more URLs and returns clean, AI-ready Markdown — good for reading articles and docs. |
| Python execution | `python_execute` | Runs a Python code string and captures `print` output. Used for calculations, data wrangling, and scripting. |
| Shell | `bash` | Executes shell commands in a persistent bash session (supports long-running and interactive commands). |
| File editor | `str_replace_editor` | Views, creates, and edits files with surgical string replacement, line insertion, and undo. |
| Planning | `planning` | Creates and tracks multi-step plans (create / update / mark_step / list / get / delete). |
| Ask a human | `ask_human` | Pauses and asks you a question at the terminal when the agent needs help or a decision. |
| Terminate | `terminate` | Ends the run when the task is complete (or impossible). |
| Structured output | `create_chat_completion` | Produces a response in a specific structured format. |
| Computer use | `computer_use` | Controls a full desktop (mouse, keyboard, screenshots) — used by the sandbox agent. |
| Chart visualization | `data_visualization`, `visualization_preparation` | Generates charts and data reports (data-analysis agent only). |
| MCP tools | `mcp_*` | Any tools exposed by connected MCP servers, added dynamically. |

### Browser actions in detail

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

| Action | Purpose |
|---|---|
| `go_to_url` | Navigate to a URL. |
| `go_back` | Go back one page. |
| `web_search` | Search the web and open the first result. |
| `click_element` | Click the element at a given index. |
| `input_text` | Type text into an element. |
| `scroll_down` / `scroll_up` | Scroll by a pixel amount. |
| `scroll_to_text` | Scroll until specific text is visible. |
| `send_keys` | Send raw keyboard keys (e.g. `Enter`, `Escape`). |
| `get_dropdown_options` / `select_dropdown_option` | Read and choose `<select>` options. |
| `extract_content` | Use the LLM to extract information from the page toward a goal. |
| `open_tab` / `switch_tab` / `close_tab` | Manage browser tabs. |
| `wait` | Pause for a number of seconds. |

> [!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.

| Agent | Run mode | Default tools | Best for |
|---|---|---|---|
| **Manus** | `main.py` | python_execute, browser_use, str_replace_editor, ask_human, terminate (+ any MCP tools) | The default all-rounder: browse, code, edit files, search. |
| **DataAnalysis** | `run_flow.py` (when enabled) | python_execute, visualization_preparation, data_visualization, terminate | Analyzing data and generating charts/reports. |
| **BrowserAgent** | (library) | browser_use, terminate | Web-only automation tasks. |
| **SWEAgent** | (library) | bash, str_replace_editor, terminate | Acting as an autonomous programmer in the shell. |
| **MCPAgent** | `run_mcp.py` | tools from the connected MCP server | Using a remote toolset over MCP. |
| **SandboxManus** | `sandbox_main.py` | ask_human, terminate + Daytona sandbox tools (shell, files, browser, vision) | Running everything inside an isolated cloud sandbox. |

> [!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

```bash
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

```bash
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

```bash
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

```bash
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](#9-advanced-usage) for the Node.js prerequisite), then:

```bash
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`:

```text
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.

| Provider | Example file | `api_type` | Notes |
|---|---|---|---|
| OpenAI | `config.example.toml` | _(unset)_ | Standard `https://api.openai.com/v1`. |
| Anthropic (Claude) | `config.example-model-anthropic.toml` | _(unset)_ | Uses Anthropic's OpenAI-compatible endpoint. |
| Azure OpenAI | `config.example-model-azure.toml` | `azure` | Requires `api_version` and a deployment URL. |
| AWS Bedrock | `config.example-daytona.toml` (commented block) | `aws` | Uses your AWS credentials; `api_key` is required but unused. |
| Google Gemini | `config.example-model-google.toml` | _(unset)_ | Uses Gemini's OpenAI-compatible endpoint. |
| Ollama (local) | `config.example-model-ollama.toml` | `ollama` | Point `base_url` at `http://localhost:11434/v1`. |
| Jiekou.AI | `config.example-model-jiekouai.toml` | `jiekou` | Aggregator endpoint. |
| PPIO | `config.example-model-ppio.toml` | `ppio` | Aggregator endpoint. |

> [!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)

```toml
[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

```toml
[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](#error-gemini-20-doesnt-work)). 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](https://github.com/VisActor/VMind) and [@visactor/vchart](https://github.com/VisActor/VChart)) under the hood.

1. Install Node.js ≥ 18.
2. Install the JS dependencies:

   ```bash
   cd app/tool/chart_visualization
   npm install
   ```

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

   ```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:

```bash
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](https://www.daytona.io) sandbox rather than on your machine — useful when you don't want the agent touching your local filesystem or running shell commands locally.

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

```bash
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:

```text
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.**

```bash
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

| Command | Agent / workflow |
|---|---|
| `python main.py [--prompt TEXT]` | Manus general agent |
| `python run_flow.py` | Planning flow (multi-agent) |
| `python run_mcp.py [-c stdio\|sse] [-i] [-p TEXT] [--server-url URL]` | MCP client agent |
| `python run_mcp_server.py [--transport stdio]` | OpenManus as an MCP server |
| `python sandbox_main.py [--prompt TEXT]` | SandboxManus (Daytona) |
| `python protocol/a2a/app/main.py [--host H] [--port P]` | A2A server (default port 10000) |

### Configuration sections

| Section | Purpose |
|---|---|
| `[llm]` | Main model: `model`, `base_url`, `api_key`, `max_tokens`, `temperature`, `api_type`, `api_version`, `max_input_tokens`. |
| `[llm.vision]` | Vision model (screenshots / images). |
| `[browser]` | `headless`, `disable_security`, `extra_chromium_args`, `chrome_instance_path`, `wss_url`, `cdp_url`, `max_content_length`. |
| `[browser.proxy]` | `server`, `username`, `password`. |
| `[search]` | `engine`, `fallback_engines`, `retry_delay`, `max_retries`, `lang`, `country`. |
| `[sandbox]` | `use_sandbox`, `image`, `work_dir`, `memory_limit`, `cpu_limit`, `timeout`, `network_enabled`. |
| `[daytona]` | `daytona_api_key`, `daytona_server_url`, `daytona_target`, `sandbox_image_name`, `VNC_password`. |
| `[mcp]` | `server_reference`; plus `config/mcp.json` for server connections. |
| `[runflow]` | `use_data_analysis_agent`. |

### Default ports & timeouts

| Item | Value |
|---|---|
| A2A server port | `10000` |
| MCP SSE default URL | `http://127.0.0.1:8000/sse` |
| Planning-flow total timeout | 3600 s (60 min) |
| Default agent step limit | 20 |
| Bash command timeout | 120 s |
| Default sandbox command timeout | 300 s |

### 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](https://github.com/OpenManus/OpenManus-RL) (RL tuning for agents)

---

_Generated June 2026 from FoundationAgents/OpenManus at 52a13f2. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._