1. 401 invalid_api_key 先别怪 Iris把 Search Agent 的 OpenAI 兼容调用拆成三层跑 AllSpark 开源的 Iris Search Agent 本地评测时遇到401 invalid_api_key先别急着换模型去 TaoToken 官网 拿一个 Key再把 OpenAI 兼容调用的base_url改到https://taotoken.net/api大多数 401 都能很快定位。Iris 这类 Search Agent 在评测时并不是只发一次请求搜索规划阶段要调用模型生成检索词、拆解子问题答案汇总阶段要把检索结果压缩成最终答复有些评测脚本还会额外做一次格式修复或引用对齐。这些步骤通常都走 OpenAI 兼容接口因此只要其中任意一处仍然使用旧地址、旧 Key 或错误 Header日志里就会冒出401 invalid_api_key。很多同学看到invalid_api_key会本能地认为“Key 失效了”但在本地评测场景里更常见的原因是配置没有真正生效。比如.env里改了OPENAI_API_KEY但评测进程读取的是 shell 里已经存在的旧变量或者代码里显式写死了base_urlhttps://api.openai.com/v1只在环境变量里改了地址又或者把 Anthropic 协议的ANTHROPIC_AUTH_TOKEN填进了 OpenAI SDK 的api_key参数。Iris 的评测代码通常是公开的搜索模块和汇总模块可能来自不同封装配置入口不止一个。你要做的第一件事不是改模型参数而是把“请求地址层、认证层、模型名层”拆开检查。一个典型的错误日志通常长这样openai.AuthenticationError: Error code: 401 - {error: {message: invalid_api_key, type: invalid_request_error}} Request URL: https://api.openai.com/v1/chat/completions Request headers: {Authorization: Bearer sk-***}注意Request URL。如果它仍然是api.openai.com说明base_url没有改成功如果 URL 已经变成 TaoToken 的地址但依旧 401说明 Key 或 Header 有问题如果 URL 正确、Key 也重新复制了但仍然报invalid_api_key那就要检查 Key 是否被引号、空格、换行污染或者环境变量是否被同名变量覆盖。本文按“先拿 Key再改 base_url最后对照日志”的顺序把 Iris 本地评测接入 TaoToken 的过程拆成可复制步骤。文中的命令都在你本地终端执行不要写进生产数据库或线上任务。2. 在 TaoToken 准备 Key 和端点base_url 固定为 https://taotoken.net/api第一步是准备认证信息。打开 TaoToken 官网 注册或登录然后进入控制台创建 API Key。创建完成后复制以YOUR_API_KEY为代表形式的 Key并把它只保存在本地环境变量或本地.env文件里。不要把它提交到 Git也不要写进公开的评测配置。如果你已经有账号可以直接打开 API Keys 页面创建或轮换 Key。这里有一个容易忽略的点TaoToken 的 OpenAI 兼容 Base URL 是https://taotoken.net/api注意这个地址在工具配置里不要附加 UTM 参数。UTM 只用于官网页面跳转统计不要写进 SDK 的base_url。也就是说你的配置应该是export TAOTOKEN_API_KEYYOUR_API_KEY export OPENAI_API_KEY$TAOTOKEN_API_KEY export OPENAI_BASE_URLhttps://taotoken.net/api如果你使用.env文件可以写成TAOTOKEN_API_KEYYOUR_API_KEY OPENAI_API_KEYYOUR_API_KEY OPENAI_BASE_URLhttps://taotoken.net/api为了让评测脚本和临时调试都读同一份配置建议在启动前先确认变量确实生效echo $OPENAI_BASE_URL echo ${OPENAI_API_KEY:0:6}第二行只打印前 6 位避免完整 Key 出现在终端历史里。正确情况下OPENAI_BASE_URL应该输出https://taotoken.net/api而不是https://api.openai.com/v1。如果输出为空说明当前 shell 没有加载.env需要在命令前加source .env或者在评测脚本里显式加载。接下来用一次最小请求验证 Key 和端点。下面命令中的模型名用MODEL_NAME占位你需要换成 TaoToken 控制台里可用的模型标识curl -sS https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { model: MODEL_NAME, messages: [ {role: user, content: 只回复 pong} ], temperature: 0 }如果返回中带有choices字段说明 Key、Base URL 和认证 Header 已经打通。如果仍然返回401 invalid_api_key按顺序检查Authorization是否为Bearer YOUR_API_KEYYOUR_API_KEY是否替换成了真实 KeyKey 前后是否有多余空格是否误用了其他平台的 Key请求地址是否被网关或本地代理改写。这里不涉及任何灰色中转也不需要额外网络工具核心就是让 OpenAI 兼容客户端把请求发到正确地址并带上正确认证信息。3. Iris 本地评测接入改 OpenAI SDK 初始化不改检索与答案汇总逻辑Iris Search Agent 的评测通常包含多个阶段但接入层面只需要改“模型调用入口”。如果你用 OpenAI Python SDK最常见的是找到OpenAI(或AsyncOpenAI(的初始化位置把api_key和base_url指向 TaoToken。不要改检索器、不要改评测数据集、不要改答案汇总的提示词结构先让请求能通。一个可复制的 OpenAI 兼容调用示例如下import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlhttps://taotoken.net/api, ) def call_model(prompt: str) - str: resp client.chat.completions.create( modelos.environ[IRIS_EVAL_MODEL], messages[ {role: system, content: 你是 Search Agent 的搜索规划器只输出检索计划。}, {role: user, content: prompt}, ], temperature0, ) return resp.choices[0].message.content if __name__ __main__: print(call_model(为评测问题生成三条检索式。))这段代码里有两个关键环境变量TAOTOKEN_API_KEY和IRIS_EVAL_MODEL。Key 来自 TaoToken 控制台模型名来自你在 TaoToken 侧确认可用的模型标识。不要把模型名写死成未知字符串也不要把 Anthropic 的ANTHROPIC_*变量塞进这里。OpenAI SDK 认的是api_key和base_url不是ANTHROPIC_AUTH_TOKEN。如果 Iris 的评测脚本通过环境变量读取 OpenAI 配置你可以不改 Python 文件直接在启动命令前注入TAOTOKEN_API_KEYYOUR_API_KEY \ OPENAI_API_KEY$TAOTOKEN_API_KEY \ OPENAI_BASE_URLhttps://taotoken.net/api \ IRIS_EVAL_MODELMODEL_NAME \ python your_iris_eval_entry.py \ --split local_smoke \ --max-samples 20这里的your_iris_eval_entry.py需要替换成你本地仓库真实的评测入口文件。不要凭空编造不存在的脚本名。你要观察的是两类日志一类是 HTTP 请求日志另一类是模型返回的 usage 日志。修复前请求日志可能显示POST https://api.openai.com/v1/chat/completions修复后应显示请求发往https://taotoken.net/api对应的路径。一个正常日志片段类似HTTP Request: POST https://taotoken.net/api/v1/chat/completions HTTP/1.1 200 OK usage: prompt_tokens... completion_tokens... total_tokens...Search Agent 的 Token 消耗点主要在这里搜索规划时每次拆解问题、生成检索式、决定是否继续搜索都会调用模型答案汇总时把检索结果压缩成最终答案也会调用模型。如果评测脚本开启多轮搜索同一个问题可能产生多次 API 调用。因此 401 修复后不要只看最终答案是否生成还要看 usage 字段是否按阶段出现。如果某一阶段没有 usage说明它可能没有走到模型调用或者在更早的认证环节失败了。还有一个常见坑代码里同时存在两套客户端。比如搜索规划用AsyncOpenAI答案汇总用OpenAI但只改了其中一个的base_url。结果就是前半段成功后半段仍然 401。排查时可以在两个客户端的初始化处各打一行日志print(planner base_url , planner_client.base_url) print(summary base_url , summary_client.base_url)如果输出不是https://taotoken.net/api就回到对应文件继续改。不要用全局 monkey patch 猜测 SDK 行为显式传参最稳。4. Claude Code 配置settings.json 和 ANTHROPIC_* 只服务 Anthropic 协议Iris 评测走的是 OpenAI 兼容接口但很多同学也会在同一台机器上用 Claude Code 做辅助排查。Claude Code 的配置与 OpenAI SDK 不是同一套协议它使用settings.json和ANTHROPIC_*环境变量。你可以在settings.json中这样配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: MODEL_NAME } }如果使用 shell 环境变量也可以写成export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELMODEL_NAME注意ANTHROPIC_*只给 Claude Code 这类 Anthropic 协议客户端使用不要把它写进 Codex 的config.toml也不要用它替换 OpenAI SDK 的api_key。如果你用 CC Switch 管理多套配置检查“三件套”base_url、API Key、模型名。三件套里只要有一个还指向旧供应商Claude Code 侧就可能出现认证失败或模型不存在。切换配置后重新打开一个终端确认变量没有残留echo $ANTHROPIC_BASE_URL echo ${ANTHROPIC_AUTH_TOKEN:0:6}如果 Claude Code 仍然报 401先确认当前使用的是哪套配置。CC Switch 的切换逻辑可能只改了配置文件没有重启 shell也可能同时存在系统级变量和项目级.env后者覆盖了前者。最直接的办法是在项目根目录新建一个干净的调试终端只加载你需要的那一份配置再启动 Claude Code。Claude Code 的具体配置字段和最新说明可以以 Claude Code 文档 为准不要凭记忆填字段。5. Codex 配置config.toml 里写 provider别混用 ANTHROPIC_*Codex 侧使用config.toml不要在里面出现ANTHROPIC_*。一个通用的 provider 配置思路如下model MODEL_NAME model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat然后在 shell 中提供TAOTOKEN_API_KEYexport TAOTOKEN_API_KEYYOUR_API_KEYCodex 启动时会根据model_provider找到model_providers.taotoken再用env_key指定的环境变量读取 Key。这里最容易出错的地方是变量名不一致config.toml里写的是TAOTOKEN_API_KEY但 shell 里导出的是OPENAI_API_KEY或者反过来。变量名对不上Codex 就读不到 Key表现可能是 401也可能是“缺少认证信息”。启动前先用printenv TAOTOKEN_API_KEY | cut -c1-6确认变量存在。不要打印完整 Key。如果这个命令没有输出说明当前终端没有加载配置需要重新source或重新打开终端。另外Codex 的base_url同样使用https://taotoken.net/api不要加 UTM 参数。wire_api chat表示走 Chat Completions 兼容形态如果你使用的 Codex 版本要求其他字段以实际版本文档为准。关键是不要把 Claude Code 的ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN复制到 Codex 配置里。两套协议字段不同混用只会让排障更复杂。6. 评测日志怎么对照搜索规划、答案汇总、重试调用分别看什么修复 401 之后建议打开调试日志按阶段对照请求。OpenAI Python SDK 可以通过环境变量打开 HTTP 日志export OPENAI_LOGdebug然后重新跑一个小规模评测。你重点看三件事观察点修复前典型表现修复后目标表现请求地址api.openai.com或旧供应商域名taotoken.net/api对应路径认证结果401 invalid_api_key200 OKusage 字段没有或请求提前失败搜索规划、答案汇总各自有 usage模型名与 TaoToken 侧不一致与IRIS_EVAL_MODEL一致重试日志反复 401 后退出偶发 429 后有限重试成功如果修复后搜索规划成功、答案汇总失败很可能是两处客户端配置不一致。如果单条问题成功、批量评测失败可能是并发过高触发限流不是 401。可以先把并发调低python your_iris_eval_entry.py \ --split local_smoke \ --max-samples 10 \ --concurrency 1--concurrency参数名以你的评测脚本实际支持为准。不要强行加不存在的参数。观察日志时把搜索规划调用和答案汇总调用分开看规划阶段的 prompt 通常包含问题拆解、检索式生成、是否继续搜索等指令汇总阶段的 prompt 通常包含检索结果、引用编号、最终回答格式要求。两段调用都可能消耗 Token也都有可能因为 Key 或base_url配错而返回 401。一个稳定的日志流应该类似[planner] POST https://taotoken.net/api/v1/chat/completions - 200 [planner] usage: prompt_tokens... completion_tokens... [search] local retrieval finished, docs... [summary] POST https://taotoken.net/api/v1/chat/completions - 200 [summary] usage: prompt_tokens... completion_tokens... [eval] sample 1 finished如果日志里出现Retrying request同时伴随 401不要让它无限重试。先中断回到配置层检查。401 不是网络抖动重试不会自动修好认证。只有当日志显示429或5xx时重试才有意义。7. 从 401 到稳定跑完 Iris 评测检查清单与 TaoToken 入口最后给你一张收尾检查清单。每次换机器、换终端、换评测分支都可以按这个顺序过一遍打开 TaoToken 官网确认账号可登录Key 状态正常。在 API Keys 创建或复制 Key确保没有多余空格和换行。OpenAI 兼容客户端统一设置base_urlhttps://taotoken.net/api不要加 UTM。Iris 评测入口、搜索规划客户端、答案汇总客户端三处都检查不要只改一处。Claude Code 使用settings.json和ANTHROPIC_*Codex 使用config.toml和 provider 配置两者不要混用字段。CC Switch 三件套base_url、API Key、模型名保持一致。先跑单条最小请求再跑--max-samples 10的小评测最后放大批量。对照日志确认请求地址、HTTP 状态、usage 字段区分 401 与 429。如果你还没有确定用哪个模型做 Search Agent 的规划与汇总可以先到 模型对话 页面做一次交互验证如果要把评测、调试、日常编码放在同一套配置里管理可以看 Coding Plan需要创建新 Key 时直接走 API KeysClaude Code 的字段细节参考 Claude Code 文档。把base_url改到https://taotoken.net/api回填YOUR_API_KEY再跑一次 Iris 评测命令日志里的401 invalid_api_key就会变成可定位、可复现的配置问题而不是一个模糊的认证报错。