README_zh.md
English README | 社区 | 安装 | 示例 | 论文 | 引用 | 贡献 | CAMEL-AI
</h4> <div align="center" style="background-color: #f0f7ff; padding: 10px; border-radius: 5px; margin: 15px 0;"> <h3 style="color: #1e88e5; margin: 0;"> 🏆 OWL 在 GAIA 基准测试中取得 <span style="color: #d81b60; font-weight: bold; font-size: 1.2em;">58.18</span> 平均分，在开源框架中排名 <span style="color: #d81b60; font-weight: bold; font-size: 1.2em;">🏅️ #1</span>！ 🏆 </h3> </div> <div align="center">🦉 OWL 是一个前沿的多智能体协作框架，推动任务自动化的边界，构建在 CAMEL-AI Framework。
我们的愿景是彻底变革 AI 智能体协作解决现实任务的方式。通过利用动态智能体交互，OWL 实现了跨多领域更自然、高效且稳健的任务自动化。
</div> </div> <!-- # Key Features -->加入我们的社区，见证您的创新想法被尖端AI技术实现。
此视频演示了如何在本地安装 OWL，展示了它作为一个前沿的多智能体协作框架，推动任务自动化边界的能力：https://www.youtube.com/watch?v=8XlqVyAZOr8
# 克隆 GitHub 仓库
git clone https://github.com/camel-ai/owl.git
# 进入项目目录
cd owl
# 如果你还没有安装 uv，请先安装
pip install uv
# 创建虚拟环境并安装依赖
# 我们支持使用 Python 3.10、3.11、3.12
uv venv .venv --python=3.10
# 激活虚拟环境
# 对于 macOS/Linux
source .venv/bin/activate
# 对于 Windows
.venv\Scripts\activate
# 安装 CAMEL 及其所有依赖
uv pip install -e .
# 完成后退出虚拟环境
deactivate
# 克隆 GitHub 仓库
git clone https://github.com/camel-ai/owl.git
# 进入项目目录
cd owl
# 创建虚拟环境
# 对于 Python 3.10（也适用于 3.11、3.12）
python3.10 -m venv .venv
# 激活虚拟环境
# 对于 macOS/Linux
source .venv/bin/activate
# 对于 Windows
.venv\Scripts\activate
# 从 requirements.txt 安装
pip install -r requirements.txt --use-pep517
# 克隆 GitHub 仓库
git clone https://github.com/camel-ai/owl.git
# 进入项目目录
cd owl
# 创建 conda 环境
conda create -n owl python=3.10
# 激活 conda 环境
conda activate owl
# 选项1：作为包安装（推荐）
pip install -e .
# 选项2：从 requirements.txt 安装
pip install -r requirements.txt --use-pep517
# 完成后退出 conda 环境
conda deactivate
OWL 需要各种 API 密钥来与不同的服务进行交互。owl/.env_template 文件包含了所有必要 API 密钥的占位符，以及可以注册这些服务的链接。
.env 文件（推荐）复制并重命名模板：
cd owl
cp .env_template .env
配置你的 API 密钥：
在你喜欢的文本编辑器中打开 .env 文件，并在相应字段中插入你的 API 密钥。
注意：对于最小示例（
examples/run_mini.py），你只需要配置 LLM API 密钥（例如，OPENAI_API_KEY）。
或者，你可以直接在终端中设置环境变量：
macOS/Linux (Bash/Zsh)：
export OPENAI_API_KEY="你的-openai-api-密钥"
Windows (命令提示符)：
set OPENAI_API_KEY="你的-openai-api-密钥"
Windows (PowerShell)：
$env:OPENAI_API_KEY = "你的-openai-api-密钥"
注意：直接在终端中设置的环境变量仅在当前会话中有效。
OWL可以通过Docker轻松部署，Docker提供了跨不同平台的一致环境。
# 克隆仓库
git clone https://github.com/camel-ai/owl.git
cd owl
# 配置环境变量
cp owl/.env_template owl/.env
# 编辑.env文件，填入您的API密钥
# 此选项从Docker Hub下载一个即用型镜像
# 最快速且推荐给大多数用户
docker compose up -d
# 在容器中运行OWL
docker compose exec owl bash
cd .. && source .venv/bin/activate
playwright install-deps
xvfb-python examples/run.py
# 适用于需要自定义Docker镜像或无法访问Docker Hub的用户：
# 1. 打开docker-compose.yml
# 2. 注释掉"image: mugglejinx/owl:latest"行
# 3. 取消注释"build:"部分及其嵌套属性
# 4. 然后运行：
docker compose up -d --build
# 在容器中运行OWL
docker compose exec owl bash
cd .. && source .venv/bin/activate
playwright install-deps
xvfb-python examples/run.py
# 导航到容器目录
cd .container
# 使脚本可执行并构建Docker镜像
chmod +x build_docker.sh
./build_docker.sh
# 使用您的问题运行OWL
./run_in_docker.sh "���的问题"
如果在Docker中使用MCP Desktop Commander，请运行：
npx -y @wonderwhy-er/desktop-commander setup --force-file-protocol
更多详细的Docker使用说明，包括跨平台支持、优化配置和故障排除，请参阅 DOCKER_README.md
运行以下示例：
python examples/run.py
我们还提供了一个最小化示例，只需配置LLM的API密钥即可运行：
python examples/run_mini.py
工具调用能力：OWL 需要具有强大工具调用能力的模型来与各种工具包交互。模型必须能够理解工具描述、生成适当的工具调用，并处理工具输出。
多模态理解能力：对于涉及网页交互、图像分析或视频处理的任务，需要具备多模态能力的模型来解释视觉内容和上下文。
有关配置模型的信息，请参阅我们的 CAMEL 模型文档。
注意：为获得最佳性能，我们强烈推荐使用 OpenAI 模型（GPT-4 或更高版本）。我们的实验表明，其他模型在复杂任务和基准测试上可能表现明显较差，尤其是那些需要多模态理解和工具使用的任务。
OWL 支持多种 LLM 后端，但功能可能因模型的工具调用和多模态能力而异。您可以使用以下脚本来运行不同的模型：
# 使用 Claude 模型运行
python examples/run_claude.py
# 使用 Qwen 模型运行
python examples/run_qwen_zh.py
# 使用 Deepseek 模型运行
python examples/run_deepseek_zh.py
# 使用 Gemini 模型运行
python examples/run_gemini.py
# 使用其他 OpenAI 兼容模型运行
python examples/run_openai_compatible_model.py
# 使用 Azure OpenAI模型运行
python examples/run_azure_openai.py
# 使用 Ollama 运行
python examples/run_ollama.py
你可以通过修改 examples/run.py 脚本来运行自己的任务：
# Define your own task
task = "Task description here."
society = construct_society(question)
answer, chat_history, token_count = run_society(society)
print(f"\033[94mAnswer: {answer}\033[0m")
上传文件时，只需提供文件路径和问题：
# 处理本地文件（例如，文件路径为 `tmp/example.docx`）
task = "给定的 DOCX 文件中有什么内容？文件路径如下：tmp/example.docx"
society = construct_society(question)
answer, chat_history, token_count = run_society(society)
print(f"答案：{answer}")
OWL 将自动调用与文档相关的工具来处理文件并提取答案。
你可以尝试以下示例任务：
OWL 的 MCP 集成为 AI 模型与各种工具和数据源的交互提供了标准化的方式。 在使用MCP前，需要先安装Node.js。
下载官方安装包：Node.js。
安装时，勾选 "Add to PATH" 选项。
sudo apt update
sudo apt install nodejs npm -y
brew install node
npm install -g @executeautomation/playwright-mcp-server
npx playwright install-deps
查看我们的MCP示例：
examples/run_mcp.py - 基础MCP功能演示 (本地调用，需要安装依赖)examples/run_mcp_sse.py - 使用SSE协议的示例 (使用远程服务，无需安装依赖)重要提示：有效使用工具包需要具备强大工具调用能力的模型。对于多模态工具包（Web、图像、视频），模型还必须具备多模态理解能力。
OWL支持多种工具包，可通过修改脚本中的tools列表进行自定义：
# 配置工具包
tools = [
*BrowserToolkit(headless=False).get_tools(), # 浏览器自动化
*VideoAnalysisToolkit(model=models["video"]).get_tools(),
*AudioAnalysisToolkit().get_tools(), # 需要OpenAI API密钥
*CodeExecutionToolkit(sandbox="subprocess").get_tools(),
*ImageAnalysisToolkit(model=models["image"]).get_tools(),
SearchToolkit().search_duckduckgo,
SearchToolkit().search_google, # 如果不可用请注释
SearchToolkit().search_wiki,
SearchToolkit().search_bocha,
SearchToolkit().search_baidu,
*ExcelToolkit().get_tools(),
*DocumentProcessingToolkit(model=models["document"]).get_tools(),
*FileWriteToolkit(output_dir="./").get_tools(),
]
关键工具包包括：
其他专用工具包：ArxivToolkit、GitHubToolkit、GoogleMapsToolkit、MathToolkit、NetworkXToolkit、NotionToolkit、RedditToolkit、WeatherToolkit等。完整工具包列表请参阅CAMEL工具包文档。
自定义可用工具的方法：
# 1. 导入工具包
from camel.toolkits import BrowserToolkit, SearchToolkit, CodeExecutionToolkit
# 2. 配置工具列表
tools = [
*BrowserToolkit(headless=True).get_tools(),
SearchToolkit().search_wiki,
*CodeExecutionToolkit(sandbox="subprocess").get_tools(),
]
# 3. 传递给助手代理
assistant_agent_kwargs = {"model": models["assistant"], "tools": tools}
选择必要的工具包可优化性能并减少资源使用。
OWL 现在包含一个基于网页的用户界面，使与系统交互变得更加容易。要启动网页界面，请运行：
# 中文版本
python owl/webapp_zh.py
# 英文版本
python owl/webapp.py
# 日文版本
python owl/webapp_jp.py
网页界面提供以下功能：
网页界面使用Gradio构建，在您的本地机器上运行。除了您配置的模型API调用所需的数据外，不会向外部服务器发送任何数据。
我们提供了一个脚本用于复现 GAIA 上的实验结果。 要复现我们在 GAIA 基准测试中获得的 58.18 分：
gaia58.18 分支：git checkout gaia58.18
python examples/run_gaia_roleplaying.py
我们正在不断努力改进 OWL。以下是我们的路线图：
源代码采用 Apache 2.0 许可证。
如果你觉得这个仓库对你有帮助，请引用：
@misc{owl2025,
title = {OWL: Optimized Workforce Learning for General Multi-Agent Assistance in Real-World Task Automation},
author = {{CAMEL-AI.org}},
howpublished = {\url{https://github.com/camel-ai/owl}},
note = {Accessed: 2025-03-07},
year = {2025}
}
我们欢迎社区的贡献！以下是您可以提供帮助的方式：
当前开放贡献的问题：
要认领一个问题，只需在该问题下留言表明您的兴趣即可。
加入我们的 (Discord 或 微信) 社区，一起探索智能体扩展规律的边界。
加入我们，参与更多讨论！
Q: 为什么启动示例脚本后，我没有看到本地运行Chrome浏览器？
A: 当OWL判断某个任务可以使用非浏览器工具（如搜索、代码分析等）完成时，浏览器就不会启动。只有在判断需要使用浏览器工具的时候，本地才会弹出浏览器窗口，并进行浏览器模拟交互。
Q: 我应该使用哪个Python版本？
A: OWL支持Python 3.10、3.11和3.12。为了与所有依赖项获得最佳兼容性，我们推荐使用Python 3.10。
Q: 我如何为项目做贡献？
A: 请参阅我们的贡献部分，了解如何参与的详细信息。我们欢迎各种形式的贡献，从代码改进到文档更新。
OWL 是基于 CAMEL 框架构建的，以下是如何探索 CAMEL 源代码并了解其与 OWL 的工作方式：
# 克隆 CAMEL 仓库
git clone https://github.com/camel-ai/camel.git
cd camel