# 用一条自定义 OpenAI 兼容端点，把 CrewAI agent 接到 Router One

> https://router.one/zh/integrations/crewai 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-07

CrewAI 是用 Python 构建角色化 agent 的框架，多个 agent 以 crew 的形式依次完成任务。Agent 循环、任务顺序、委派、工具和记忆都由 CrewAI 在你的应用内运行，Router One 只是这些 agent 调用的模型端点。本指南使用 CrewAI 官方文档中的自定义 OpenAI 兼容端点模式：GPT、Claude、Gemini、Grok 系列共用一个 base URL 和一个 Key，走 Chat Completions，每次模型请求都在 Dashboard → Logs 留下 Trace。先跑通一个 agent、一个任务、返回纯文本的 crew，再说明环境变量方式，以及加入工具、结构化输出或更多 agent 前要核对什么。

## 安装 CrewAI 并设置凭证

CrewAI 要求 Python 3.10 到 3.13。在该环境安装 crewai 包即可：本配置使用的 OpenAI Python SDK 是 crewai 的核心依赖，不需要 crewai[litellm] 扩展。下面是 macOS/Linux 的 shell 示例。运行前替换两个占位符，分别填入 Router One Key，以及当前目录中支持 Chat Completions 的精确模型 ID；ID 自带的前缀（例如 anthropic/）要一并保留。ROUTER_ONE_* 是本示例定义并在 Python 文件中显式读取的环境变量，运行时需沿用同一环境。本页描述的行为已按 crewai 1.15.20 核对。

`terminal`

```bash
python -m pip install crewai
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
export ROUTER_ONE_MODEL_ID="<exact-model-id-from-/models>"
```

## 把 CrewAI 配置到 Router One base URL

保存为 crewai_router_one.py，再运行 python crewai_router_one.py。LLM(custom_openai=True, base_url=..., api_key=...) 是 CrewAI 官方文档给自定义 OpenAI 兼容端点的写法：无论模型 ID 以什么开头，都固定走 OpenAI SDK 的 Chat Completions 路径，即 POST /v1/chat/completions。模型字符串写成 openai/ 加精确目录 ID：此模式下 CrewAI 只去掉最前面的一个 openai/ 段，其余原样发送，所以 anthropic/claude-sonnet-5 或 openai/gpt-5.5 到达网关时与目录完全一致。agent 没有工具、任务要求纯文本，首个请求只包含 model 和 messages。crew.kickoff() 执行任务并返回 CrewOutput，result.raw 就是模型文本。

`crewai_router_one.py`

```python
import os

from crewai import Agent, Crew, LLM, Task

llm = LLM(
    model="openai/" + os.environ["ROUTER_ONE_MODEL_ID"],
    custom_openai=True,
    base_url="https://api.router.one/v1",
    api_key=os.environ["ROUTER_ONE_API_KEY"],
)
greeter = Agent(
    role="Greeter",
    goal="Reply with one short greeting.",
    backstory="You keep answers short and literal.",
    llm=llm,
)
task = Task(
    description="Reply with one short greeting.",
    expected_output="One short greeting sentence.",
    agent=greeter,
)
crew = Crew(agents=[greeter], tasks=[task])
result = crew.kickoff()
print(result.raw)
```

## 改用环境变量，而不是 LLM 对象

用 crewai create crew 生成的项目从 config/agents.yaml 构建 agent，默认没有 llm 字段，CrewAI 会从环境读取模型和端点：MODEL 选模型，OPENAI_API_BASE（也接受 OPENAI_BASE_URL）设端点，OPENAI_API_KEY 提供 Key。CrewAI 导入 LLM 模块时会调用 load_dotenv()；在 shell 里直接 export 这些变量，对任何项目布局都有效。MODEL 同样写成 openai/ 加目录 ID：base URL 来自这些变量时，CrewAI 构建 LLM 时会一并带上，识别出该 ID 不是官方 OpenAI 名称后走同一条自定义端点路径，精确 ID 原样发出。agents.yaml 里的纯字符串（llm: openai/anthropic/claude-sonnet-5）或 Agent(llm="...") 在构建时拿不到 base URL，会被交给 CrewAI 的 LiteLLM 兜底路径，而该依赖默认并未安装；模型请放在 MODEL 或 LLM 对象里。

`.env`

```bash
# 项目目录下的 .env，或在 shell 里 export 同名变量
MODEL=openai/<exact-model-id-from-/models>
OPENAI_API_BASE=https://api.router.one/v1
OPENAI_API_KEY=sk-your-router-one-key
```

## 加入工具、结构化输出或更多 agent 前要核对什么

Agent 工具（包括 allow_delegation=True 时加入的委派工具，以及 crewai-tools 包里的工具）会作为 function tool schema 随同一个 Chat Completions 请求发送，启用前先在模型详情页核对工具调用能力。Task 的 output_pydantic、output_json 和 LLM(response_format=...) 会发送 JSON schema 形式的 response_format，先核对精确模型的结构化输出支持。每个 Agent 可以各自传入 LLM 对象，一个 crew 可在同一把 Key 下混用多个模型，所有调用仍落在同一份 Trace 里。LLM(stream=True) 路径不变，只是加上 stream_options，用量在最后一个分块返回。api 保持默认值：api="responses" 会让同一个对象改走 POST /v1/responses，网关只对详情页列出该端点的 GPT 系列 ID 原生提供。多个 agent、任务或重试意味着多次模型请求，crew.usage_metrics 是 CrewAI 自己统计的 token 数，不是账单。给 crew 单独建 Key 并设置 maxSpend，再到 Dashboard → Logs 按 Key、时间、精确模型和 request_id 核账。

## CrewAI 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 CrewAI 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

## CrewAI 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

## 在 trace 里验证 CrewAI 的调用

先在 CrewAI 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### 模型字符串为什么要写 openai/ 加目录 ID，还要加 custom_openai=True？

CrewAI 规定每个模型字符串都带 provider 前缀，并按前缀选择客户端：anthropic/ 或 google/ 开头的 ID 会走 CrewAI 自带的对应 SDK 路径，要求该家的 API 和 Key，而不是 OpenAI 兼容端点；对应扩展没有安装时，请求发出前就会报 ImportError。custom_openai=True 覆盖这一选择，让任何 ID 都固定走 OpenAI SDK 的 Chat Completions 路径；此模式下 CrewAI 只去掉最前面的一个 openai/ 段，其余原样发送。所以给精确目录 ID 加上 openai/ 前缀，网关收到的才是目录里的 ID：GPT 系列的 openai/gpt-5.5 要写成 openai/openai/gpt-5.5，只写一层前缀会被去掉，发出去的就是不带前缀的 gpt-5.5。到 Dashboard → Logs 确认：model 一列应显示完整的目录 ID。

### 需要安装 crewai[litellm] 扩展或 LiteLLM 吗？

本配置不需要。自定义端点模式使用 OpenAI Python SDK（crewai 的核心依赖），不会导入 LiteLLM。LiteLLM 只是 CrewAI 对「不属于任何原生 provider」的模型字符串的兜底路径——agents.yaml 里的纯字符串 llm: openai/anthropic/claude-sonnet-5 在 CrewAI 构建 LLM 时没有附带 base URL，正是这种情况。看到「did not match any supported native provider」和「LiteLLM fallback package is not installed」时，把模型改放到 MODEL 或 LLM(custom_openai=True, ...) 里，而不是去安装扩展；请求随后会带着精确 ID 走 /v1/chat/completions。

### CrewAI 自己的 tracing（CREWAI_TRACING_ENABLED、crewai traces）就是 Router One 的 Trace 吗？

不是。CrewAI 的 tracing 和遥测是 CrewAI 自己的功能，由它自己的设置控制（例如 CREWAI_TRACING_ENABLED 和 crewai traces 命令），与网关无关。Router One 的 Trace 是网关为每一次到达的模型请求写入 Dashboard → Logs 的记录，包含模型、tokens、花费、延迟、状态和 request_id，无论 CrewAI tracing 是否开启都会生成。本页不需要 CrewAI 账号、付费方案或托管平台：LLM 类和这些变量都属于开源的 crewai 包。

### CrewAI 能通过网关用哪些模型？

选用当前目录中同时支持 CrewAI 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只证明模型发现成功，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- CrewAI 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Spring AI 接入：https://router.one/zh/integrations/spring-ai
- Cline 接入：https://router.one/zh/integrations/cline
- OpenAI Python SDK 接入：https://router.one/zh/integrations/openai-sdk
- LangChain 接入：https://router.one/zh/integrations/langchain
- 工具调用的 API 要求：https://router.one/zh/llm-tool-calling
- 结构化输出的 API 要求：https://router.one/zh/llm-structured-outputs
- 按 Key 追踪模型调用成本：https://router.one/zh/llm-cost-tracking
- CrewAI 官方文档：LLM 配置：https://docs.crewai.com/en/concepts/llms
- CrewAI 官方文档：连接任意 LLM：https://docs.crewai.com/en/learn/llm-connections
- 网关层负责什么：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/crewai
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md