OpenManus Setup Guide

What you are setting up

Best beginner setup

1. Install Python 3.12, Git, and a terminal you are comfortable using.
2. Clone OpenManus from GitHub.
3. Create a virtual environment with uv.
4. Install dependencies from requirements.txt.
5. Copy config/config.example.toml to config/config.toml.
6. Choose one model backend: Ollama, Claude, or OpenAI.
7. Run python main.py and type a small test task.

Windows install

1. Install Git for Windows.
2. Install Python 3.12 and enable the option that adds Python to PATH.
3. Open PowerShell and confirm the tools work.

git --version
python --version
py --version

4. Install uv.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

5. Close and reopen PowerShell, then clone and install OpenManus.

git clone https://github.com/FoundationAgents/OpenManus.git
cd OpenManus
uv venv --python 3.12
.\.venv\Scripts\activate
uv pip install -r requirements.txt

If PowerShell blocks script activation, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, open a fresh terminal, and activate the environment again.

macOS install

1. Install Homebrew if you do not already have it.
2. Install Python 3.12 and Git.

brew install python@3.12 git

3. Install uv.

curl -LsSf https://astral.sh/uv/install.sh | sh

4. Open a new Terminal window, then clone and install OpenManus.

git clone https://github.com/FoundationAgents/OpenManus.git
cd OpenManus
uv venv --python 3.12
source .venv/bin/activate
uv pip install -r requirements.txt

Conda install option

The OpenManus README also documents a conda path. Use this if your machine already uses Anaconda or Miniconda.

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

Enable browser automation

OpenManus can use browser automation for web tasks. Install the Playwright browser package after dependencies finish.

playwright install

You can also set browser options in config/config.toml, including headless mode, a Chrome executable path, a WebSocket URL, a CDP URL, or proxy settings.

[browser]
headless = false
disable_security = true
chrome_instance_path = ""
cdp_url = ""

Create the config file

OpenManus reads model settings from config/config.toml. Start by copying the example file.

# macOS or Linux
cp config/config.example.toml config/config.toml

# Windows PowerShell
Copy-Item config\config.example.toml config\config.toml

Keep real API keys out of screenshots, Git commits, and shared zip files. If you test multiple providers, change one provider block at a time and restart OpenManus after each change.

Power OpenManus with Ollama

1. Install Ollama for Windows or macOS.
2. Pull a model that can follow tool instructions well.
3. Confirm Ollama is listening locally.

ollama pull llama3.2
ollama list
ollama serve

Then edit config/config.toml like this:

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

For vision tasks, use a vision-capable local model and add an [llm.vision] section with the same Ollama base URL. Local models are best for private drafting, simple browsing, and experiments; larger hosted models usually handle long, tool-heavy tasks more reliably.

Power OpenManus with Claude

The OpenManus example config includes Claude-style settings. Put your Anthropic API key into config/config.toml and use a model available to your account.

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

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

Claude is a strong choice when the task needs planning, careful writing, long-context reasoning, or safer browser decisions. If a model name changes, check the Claude models page and replace the model value only.

Power OpenManus with OpenAI or Codex

OpenManus does not run inside the Codex desktop app. The clean connection is to use an OpenAI API model in OpenManus, then use Codex separately to edit, inspect, and improve the OpenManus project files.

[llm]
model = "YOUR_OPENAI_MODEL"
base_url = "https://api.openai.com/v1"
api_key = "YOUR_OPENAI_API_KEY"
max_tokens = 4096
temperature = 0.0

If you use a local or hosted provider that exposes an OpenAI-compatible endpoint, set base_url, model, and api_key to that provider's values.

Run your first task

1. Activate the virtual environment.
2. Confirm config/config.toml has one working model provider.
3. Start OpenManus.

python main.py

Start with a small prompt so you can verify the model, tools, and terminal output before asking for a long workflow.

Read the homepage of example.com and summarize what the site does.

Use MCP mode

The README includes an MCP tool version. Use it when you want OpenManus to work through Model Context Protocol tooling instead of only the normal terminal agent path.

python run_mcp.py

The config example points MCP at a default server module, and the project also reads optional MCP server settings from config/mcp.json. Add external tool servers only after the base agent runs correctly.

Use run-flow mode

OpenManus also includes an unstable multi-agent path. Turn on the data analysis agent when you want spreadsheet, data, chart, or visualization help.

[runflow]
use_data_analysis_agent = true

python run_flow.py

Treat this mode as experimental. Use it after the normal python main.py workflow is already working on your machine.

Practical use cases

Troubleshooting

Source links

• OpenManus repository
• OpenManus README
• OpenManus config example
• Ollama OpenAI-compatible API docs
• Claude OpenAI SDK compatibility docs
• OpenAI Codex CLI docs