CrewAI 报 litellm.Timeout 与 APITimeoutError：把 Base URL 改到 TaoToken 的排查清单

1. CrewAI 跑任务突然抛 RuntimeError 与 litellm.Timeout 的真实链路你写了一个 CrewAI 多智能体流程本地调试时 Agent 之间还能正常对话结果一跑完整任务就炸RuntimeError: Task execution failed: litellm.Timeout: APITimeoutError第一反应通常是去调max_execution_time把它从默认值一路拉到 1000 秒甚至 3000 秒结果报错时间点几乎没变。这个现象本身就说明问题不在任务跑得久而在请求根本没到达一个能应答的模型端点。CrewAI 本身不直接发 HTTP 请求它把 LLM 调用委托给 LiteLLM 这一层统一适配。LiteLLM 负责把gpt-4、claude-3-5-sonnet、ollama/qwen这类模型名翻译成对应厂商的 API 调用。当 Agent 没有显式指定llm参数时CrewAI 会回落到默认模型历史上是gpt-4LiteLLM 就会尝试连默认的 OpenAI 端点。如果你的网络环境访问不到那个端点TCP 连接阶段就会卡住直到 LiteLLM 的请求超时抛出APITimeoutErrorCrewAI 再把它包装成RuntimeError: Task execution failed。所以这条报错的链路是Agent 缺省 llm → LiteLLM 用默认模型和默认 Base URL → 请求发不出去或长时间无响应 → LiteLLM 超时 → CrewAI 任务失败。max_execution_time管的是任务整体允许跑多久它管不了单次 HTTP 请求连不上这件事这就是为什么你把超时调到 1000 秒也没用。这篇排查清单面向的场景很具体CrewAI 多智能体任务执行时抛出RuntimeError: Task execution failed并伴随litellm.Timeout / APITimeoutError需要从 llm 调用超时、并发与重试配置切入定位。适合已经在写 CrewAI 的CrewBase类、agents.yaml/tasks.yaml配置但被超时卡住的人。核心动作只有一个把每个 Agent 的llm显式指向一个可达的 Base URL并配上合理的超时与重试参数。下面按先定位、再配置、后验证的顺序走一遍。2. 把 Base URL 指向 TaoToken 的前置准备与 llm 参数补齐在动手改代码前先把为什么默认会超时这件事想清楚否则你改完一个 Agent 还是会漏。CrewAI 的 Agent 定义里llm是可选项。你不写它就用框架默认值。默认值指向的是公共 OpenAI 端点这个端点在部分网络环境下不可达于是 LiteLLM 在连接阶段就超时。解决办法不是去改max_execution_time而是给每一个 Agent 都显式指定llm并且这个llm的 Base URL 必须是你当前环境能稳定访问的。我试过在同一个 Crew 里只给主 Agent 配了 llm结果负责汇总的那个 Agent 忘了配整个任务还是在最后一步超时。所以这里的关键词是每个——agent装饰的方法返回的每个Agent(...)都要带llm。TaoToken 在这里扮演的角色是提供一个统一的、兼容 OpenAI 协议风格的 API 入口让 LiteLLM 把请求发到https://taotoken.net/api而不是默认端点。你需要在 TaoToken 控制台创建一个 API Key然后在代码里把它作为api_key传给 LLM 对象同时把base_url指向 TaoToken 的 API 地址。前置准备清单一个可用的 TaoToken API Key在控制台的 API Keys 页面创建确认你要用的模型 ID比如gpt-4o-mini、claude-3-5-sonnet-20241022这类具体以控制台模型列表为准CrewAI 与 LiteLLM 已安装pip install crewai litellm环境变量里准备好 Key避免硬编码进仓库关于 Key 的获取和模型列表可以直接看接入文档里面有当前支持的模型 ID 和调用示例。控制台地址是 https://taotoken.net/console API Keys 管理在 https://taotoken.net/api-keys 。这两个页面建议先打开后面配置要用到里面的 Key 和模型名。有一点要提醒不要把生产库直连、也不要把 Key 提交到 Git。用.env加python-dotenv是最省事的做法。CrewAI 和 LiteLLM 都会读环境变量所以你可以把OPENAI_API_KEY和OPENAI_API_BASE设好让 LiteLLM 自动接管但更推荐在代码里显式传参因为显式传参不会被其他库的环境变量覆盖排查时也更清楚。3. 可复制的 CrewAI LiteLLM 超时与 Base URL 配置片段这一节是核心直接给可复制的配置。分三块环境变量、LLM 对象构造、Agent 定义。先看环境变量放在项目根目录的.env# .env TAOTOKEN_API_KEYsk-你的TaoToken密钥 TAOTOKEN_BASE_URLhttps://taotoken.net/api然后是 LLM 对象的构造。CrewAI 支持直接传 LiteLLM 风格的模型字符串也支持传一个LLM实例。推荐用crewai.LLM显式构造这样超时、重试、Base URL 都能一次配好# llm_config.py import os from crewai import LLM def build_llm(model: str gpt-4o-mini) - LLM: return LLM( modelmodel, base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], timeout120, # 单次请求超时单位秒 max_retries3, # 失败重试次数 temperature0.3, )这里的timeout是 LiteLLM 传给底层 HTTP 客户端的单次请求超时和 CrewAI 的max_execution_time不是一回事。max_retries让 LiteLLM 在遇到瞬时网络抖动时自动重试而不是直接把异常抛给 CrewAI。这两个参数配合起来能挡掉大部分偶发超时。接下来是 Agent 定义。注意每个agent方法都要带llm# crew.py from crewai import Agent, Crew, Process, Task from crewai.project import CrewBase, agent, crew, task from llm_config import build_llm CrewBase class ExpandIdeaCrew: ExpandIdea crew agents_config config/agents.yaml tasks_config config/tasks.yaml shared_llm build_llm(gpt-4o-mini) agent def senior_idea_analyst_agent(self) - Agent: return Agent( configself.agents_config[senior_idea_analyst], allow_delegationFalse, llmself.shared_llm, max_execution_time300, verboseTrue, ) agent def idea_summarizer_agent(self) - Agent: return Agent( configself.agents_config[idea_summarizer], allow_delegationFalse, llmself.shared_llm, # 别漏这个 max_execution_time300, verboseTrue, ) task def analyze_task(self) - Task: return Task(configself.tasks_config[analyze_task]) task def summarize_task(self) - Task: return Task(configself.tasks_config[summarize_task]) crew def crew(self) - Crew: return Crew( agentsself.agents, tasksself.tasks, processProcess.sequential, verboseTrue, )如果你更习惯用 YAML 配置模型也可以在agents.yaml里写llm: gpt-4o-mini然后在代码里通过环境变量注入 Base URL。但 YAML 里没法直接写base_url所以还是推荐在 Python 侧构造LLM实例再传进去。对于用settings风格配置的项目比如某些模板会生成settings.py或config/settings.json可以这样写{ llm: { model: gpt-4o-mini, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, timeout: 120, max_retries: 3 } }三件套记牢Base URL Key Model ID。Base URL 是https://taotoken.net/apiKey 从控制台拿Model ID 用控制台里列出的可用模型。三者缺一LiteLLM 要么连不上要么认证失败要么找不到模型。4. 用最小任务验证请求是否真正跑通配置改完别急着跑完整的多智能体流程。先用一个最小任务验证链路这样出问题时能快速定位是配置问题还是任务逻辑问题。最小验证脚本# verify.py import os from dotenv import load_dotenv from crewai import Agent, Task, Crew, Process from llm_config import build_llm load_dotenv() llm build_llm(gpt-4o-mini) agent Agent( roleEcho, goal原样返回用户输入, backstory你是一个只做回声的助手。, llmllm, verboseTrue, ) task Task( description请返回这句话链路已通, expected_output链路已通, agentagent, ) crew Crew( agents[agent], tasks[task], processProcess.sequential, verboseTrue, ) result crew.kickoff() print(RESULT:, result)运行python verify.py。如果配置正确你会看到 LiteLLM 的请求日志最后打印出RESULT: 链路已通。如果还是超时日志里会显示它尝试连接的 URL对照一下是不是https://taotoken.net/api。验证成功的标志有三个终端里能看到 LiteLLM 发出的请求目标地址是 TaoToken 的 API 地址没有APITimeoutError抛出crew.kickoff()正常返回结果如果这一步通了再回去跑你的完整 Crew。完整 Crew 里如果还有 Agent 漏配llm那个 Agent 会单独超时报错信息里通常能看到是哪个 task 失败。这时候回到第 3 节把漏掉的llm补上。对于想验证更多模型行为的场景可以打开模型对话页面手动发一条请求确认 Key 和模型 ID 本身是有效的。这一步能帮你区分是 Key 问题还是是 CrewAI 配置问题。5. 本篇常见报错对照401、local proxy failed、reading choices、OAuth排查时最怕报错信息长得像但原因完全不同。下面按真实报错逐条对照。401 Unauthorized / invalid_api_keyKey 没传对或者环境变量没加载。检查.env是否被load_dotenv()读取检查api_key是不是空字符串。LiteLLM 有时会优先读OPENAI_API_KEY如果你环境里有个旧的、失效的OPENAI_API_KEY它会覆盖你传的值。解决办法是在构造LLM时显式传api_key或者临时unset OPENAI_API_KEY再跑。local proxy failed / connection refused请求发到了本地某个代理端口但没人监听。常见于你之前配过HTTP_PROXY/HTTPS_PROXY环境变量或者 LiteLLM 读到了某个本地代理配置。检查env | grep -i proxy把无关的代理变量清掉。注意这里说的是环境变量层面的排查不涉及任何网络工具的使用。litellm.Timeout: APITimeoutError就是本篇主问题。先确认 Base URL 是不是指向了可达端点再确认timeout是不是设得太短比如 5 秒最后确认模型 ID 是否有效。如果 Base URL 正确、Key 正确、模型 ID 正确还超时那大概率是并发太高把连接池打满了把max_retries调到 3、并发任务数降下来再试。Error reading choices / KeyError: choices请求返回了非预期结构通常是端点返回了错误页或空响应LiteLLM 按 OpenAI 格式去取choices就报错。根因往往是 Base URL 写错比如漏了/api或多了斜杠或者模型 ID 不存在导致服务端返回错误 JSON。对照控制台里的模型列表核对一遍。OAuth / authentication_error如果你用的是 Claude Code 或某些需要 OAuth 的客户端报 OAuth 相关错误说明认证方式不对。CrewAI 走的是 API Key 认证不需要 OAuth。如果你在 CrewAI 里看到 OAuth 报错检查是不是误配了某个需要 OAuth 的 provider 前缀。关于 CC Switch / Cline MCP / Codex auth.json如果你同时在用这些工具配置时同样要写全三件套。CC Switch 里配置自定义 provider 时Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填控制台里的模型名。Cline 的 MCP 配置里如果涉及模型调用也是同样的三件套。Codex 的auth.json里如果配自定义端点同样要保证 Base URL、Key、Model ID 三者一致。任何一处缺失都会退化成类似本篇的超时或认证错误。排查顺序建议先看报错类型 → 对照上面归类 → 检查三件套 → 用第 4 节的最小脚本复现 → 定位到具体参数。不要一上来就改max_execution_time那个参数在连接层问题面前基本无效。6. 长期跑多智能体任务时的接入选择单次验证跑通之后如果你打算长期用 CrewAI 跑多智能体任务接入方式可以按使用强度分一下。偶尔跑几个任务、主要用来验证模型行为的用 API Key 直接调就行配合模型对话页面手动测几条确认模型 ID 和返回格式符合预期。这种方式最轻适合调试阶段。需要长期编码、跑 Agent 流程、做批量任务的可以看 Coding Plan 这类方案它更适合持续性的调用场景不用每次担心额度或 Key 轮换。具体适不适合你的用量去页面看说明比在这里猜准。接入文档里有完整的 Base URL、认证方式和各语言示例配置时对照着写能少踩坑。API Keys 页面用来创建和管理 Key建议给不同项目建不同的 Key方便出问题时快速定位是哪个项目在超时。最后留一个实操建议把第 4 节的最小验证脚本存成verify.py放进项目里每次改完 LLM 配置先跑它。这个脚本 30 秒能跑完但能帮你挡掉 90% 的改了配置反而更糟的情况。多智能体任务的报错往往被包装好几层与其在完整流程里猜不如用最小脚本把链路先钉死。