安装

开始使用 CrewAI —— 安装、配置并构建你的第一个 AI crew

在你的编码智能体中设置 CrewAI

复制一段可直接粘贴的设置提示词，用于 Claude Code、Codex、Cursor 或任何编码智能体。它会安装官方 CrewAI 技能、检查 CLI，并在智能体修改代码之前将其指向正确的文档。

编码智能体设置

设置此环境，以便我可以使用 CrewAI 进行构建。

首先，如果此环境支持 npx，请安装官方 CrewAI 编码智能体技能：

npx skills add crewaiinc/skills

如果缺少 npx 或当前智能体无法加载技能，请不要让整个设置流程失败。报告确切的问题，并继续直接使用 CrewAI 文档。

在做出任何假设之前，请以下列 CrewAI 文档作为事实来源：
- https://skills.crewai.com
- https://docs.crewai.com/llms.txt
- https://docs.crewai.com/en/installation
- https://docs.crewai.com/en/guides/coding-tools/build-with-ai

设置步骤：
1. 检查 python3 --version。CrewAI 要求 Python >=3.10 且 <3.14。
2. 如果缺少 uv，请安装：
curl -LsSf https://astral.sh/uv/install.sh | sh
3. 如有需要，加载 uv 环境：
source "$HOME/.local/bin/env"
4. 安装 CrewAI CLI：
uv tool install crewai
5. 验证 CLI：
crewai version
crewai create --help
6. 创建项目：
CREWAI_DMN=true crewai create
7. 项目创建后，在编辑之前先检查生成的文件。
8. 运行：
crewai install
crewai run

不要硬编码 API 密钥。请使用 .env。
不要杜撰 CLI 参数。使用 crewai --help 或 crewai create --help 进行验证。
如果某个命令失败，请展示确切的命令和错误，解释可能的原因，修复你能安全修复的部分，然后重试一次。

查看编码智能体指南

观看：使用编码智能体技能构建 CrewAI 智能体与流程

视频教程

观看这段视频教程，了解安装过程的逐步演示：

文字教程

NOTE

Python 版本要求

CrewAI 要求 Python >=3.10 and <3.14。检查版本的方法如下：

python3 --version

如果你需要更新 Python，请访问 python.org/downloads

NOTE

OpenAI SDK 要求

CrewAI 0.175.0 要求 openai >= 1.13.3。如果你自行管理依赖，请确保你的环境满足该约束，以避免导入/运行时问题。

CrewAI 使用 uv 作为其依赖管理和包处理工具。它简化了项目的设置与执行，提供无缝体验。

如果你尚未安装 uv，请按照 步骤 1 快速在你的系统上完成设置，否则可以直接跳到 步骤 2。

Install uv

• 在 macOS/Linux 上：

  使用 curl 下载脚本并用 sh 执行：

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

  如果你的系统没有 curl，可以使用 wget：

  wget -qO- https://astral.sh/uv/install.sh | sh

• 在 Windows 上：

  使用 irm 下载脚本，使用 iex 执行它：

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

  如果遇到任何问题，请参阅 UV 安装指南 获取更多信息。

Install CrewAI 🚀

• 运行以下命令安装 crewai CLI：

  uv tool install crewai

WARNING

  如果遇到 `PATH` 警告，请运行以下命令更新你的 shell：

  ```shell
  uv tool update-shell
  ```

WARNING

  如果你在 Windows 上遇到 `chroma-hnswlib==0.7.6` 构建错误（`fatal error C1083: Cannot open include file: 'float.h'`），请安装带有 *Desktop development with C++* 的 [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/)。

• 要验证 crewai 是否已安装，请运行：

  uv tool list

• 你应该会看到类似这样的内容：

  crewai v0.102.0
  - crewai

• 如果你需要更新 crewai，请运行：

  uv tool install crewai --upgrade

NOTE

这仅会升级 全局 crewai CLI 工具。要升级项目虚拟环境中的 crewai 版本，请参阅 在项目中升级 CrewAI。

TIP

安装成功！你可以开始创建你的第一个 crew 了！🎉

创建 CrewAI 项目

crewai create crew 现在会创建一个 JSON 优先的 crew 项目。智能体位于 agents/*.jsonc，任务和 crew 级设置位于 crew.jsonc，crewai run 会直接加载该 JSON 定义。

Generate Project Scaffolding

• 运行 crewai CLI 命令：

  crewai create crew <your_project_name>

• 这会创建一个具有以下结构的新项目：

  my_project/
  ├── .gitignore
  ├── .env
  ├── agents/
  │   └── researcher.jsonc
  ├── crew.jsonc
  ├── knowledge/
  ├── pyproject.toml
  ├── README.md
  ├── skills/
  └── tools/

• 如果你需要带有 crew.py、config/agents.yaml 和 config/tasks.yaml 的旧版 Python/YAML 脚手架，请运行：

  crewai create crew <your_project_name> --classic

Customize Your Project

• 你的项目将包含这些关键文件：

  文件	用途
  crew.jsonc	配置 crew、任务顺序、流程以及输入默认值
  agents/*.jsonc	定义每个智能体的角色、目标、背景故事、LLM、工具和行为
  .env	存储 API 密钥和环境变量
  tools/	用于 custom:<name> 工具的可选 Python 文件
  knowledge/	智能体可选的知识文件
  skills/	应用于 crew 的可选技能文件

• 首先编辑 crew.jsonc 和 agents/ 中的文件，以定义你的 crew 的行为。

• 在智能体和任务文本中使用 {placeholder} 值，然后在 crew.jsonc 的 inputs 下设置默认值。当你运行 crewai run 时，CLI 会提示输入任何缺失的值。

• 将 API 密钥等敏感信息保存在 .env 中。

Run your Crew

• 在运行你的 crew 之前，请确保运行：

  crewai install

• 如果你需要安装额外的包，请使用：

  uv add <package-name>

NOTE

  作为供应链安全措施，CrewAI 的内部包在其 `pyproject.toml` 文件中使用 `exclude-newer = "3 days"`。这意味着 CrewAI 引入的传递依赖不会解析发布不足三天的包。你自己的直接依赖不受此策略影响。如果你发现某个传递依赖版本落后，可以在项目的依赖中显式固定你想要的版本。

• 要运行你的 crew，请在项目根目录下执行以下命令：

  crewai run

企业版安装选项

NOTE

对于团队和组织，CrewAI 提供企业版部署选项，可消除设置的复杂性：

CrewAI AMP（SaaS）

• 无需安装 —— 只需在 app.crewai.com 免费注册
• 自动更新与维护
• 托管的基础设施与扩缩容
• 无需代码即可构建 Crews

CrewAI Factory（自托管）

• 面向你的基础设施的容器化部署
• 支持包括本地部署在内的任何超大规模云服务商
• 与你现有的安全系统集成

•探索企业版选项

了解 CrewAI 的企业版产品并预约演示

下一步

{ }Quickstart: Flow + agent

按照快速入门搭建一个 Flow，运行一个单智能体 crew，并生成一份报告。

•Join the Community

与其他开发者交流、获取帮助，并分享你的 CrewAI 使用经验。