1. 断档现场COSMIC 查询跑到第 3 步Agent 为什么忽然“失联”在 TaoToken 官网 拿到 Key、并把 Base URL 固定成https://taotoken.net/api之前我那条 COSMIC 突变查询的 Agent 任务已经连续断在第三个阶段两次了。作为一个肿瘤方向的博士后我给一批肺癌样本做耐药位点注释任务本身并不复杂把 EGFR 的 L858R、T790M、19 外显子缺失这几个高频位点按 GRCh38 坐标去 COSMIC 里捞记录再和 ClinVar 的临床意义对一遍最后汇总成一张突变频谱表。Agent 的规划看起来也很像样五步流程排得清清楚楚可每次跑到第 3 步流式输出就没了只剩一个还在转的 spinner。终端里大致是这个样子[skill] cosmic-mutation → 命中 [step 1] 解析基因与蛋白位点 ✓ [step 2] 映射 GRCh38 坐标 ✓ [step 3] 拉取 COSMIC 记录 ✗ 请求中断一开始我以为是 Skill 本身的参数没写对把 SKILL.md 翻了两遍把基因名、转录本、坐标版本逐个核对还是断。后来才反应过来问题根本不在 Skill而在模型调用这一环。Agent 执行 Skill 的过程不是一次请求就能干完的它是「模型 → 工具 → 模型 → 工具」的多轮回环。每调一次工具、每读一次本地文件、每写一次中间结果客户端都要重新向模型端点发起一轮请求。只要这个端点在某一轮里返回 401、超时或者连接被重置整条流水线就冻结在那一节点上——后面的参数再精确也接不上因为已经没有“后面的模型调用”了。所以这两天我的排查方向从一开始就是错的。我在查 Skill、查参数、查依赖真正该查的是客户端到底把请求发到了哪个 Base URL以及那个 Key 有没有真的被进程读到。2. 先把两个常量定下来Key 和 Base URL在动任何客户端配置文件之前先把两个常量确定下来后面所有操作都只是把它们填到不同位置的问题。常量值说明Base URLhttps://taotoken.net/api三个客户端统一填这一条API KeyYOUR_API_KEY在控制台创建后替换成自己的Key 的获取入口只有一个从 TaoToken 官网 进控制台在 API Keys 页面新建一个。拿到之后先别急着往配置里粘贴先在本地终端做一次最朴素的连通性确认# 本地执行确认端点可达只发 HEAD 请求不消耗额度 curl -sS -I https://taotoken.net/api | head -n 3这条命令在你自己机器上跑作用是排除「域名解析失败」「出口被代理拦掉」这两类最底层的故障。如果这里就连不上后面改配置文件全是白费功夫。另一个容易踩的点Base URL 只写到/api这一层不要在末尾自己补/v1或者别的路径段。客户端会按自身协议去拼接具体端点你多写一段请求就会打到不存在的路径上表现同样是“跑两步就断”。3. Claude Codesettings.json 里的 env 才是真正生效的地方Claude Code 读的是ANTHROPIC_*这一组环境变量。写法有两种推荐写进settings.json因为它跟着项目走、可版本化、可复现{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY } }文件放哪里决定了它的作用范围# 用户级所有项目生效 ~/.claude/settings.json # 项目级只对当前课题目录生效推荐给科研项目 your-project/.claude/settings.json临时排查的话也可以直接在 shell 里 exportexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY两种方式二选一即可不要同时写又互相打架。还有一点必须记住已经在运行的 Claude Code 进程不会自动重读 settings.json。改完配置要彻底退出再重启否则进程里持有的还是旧端点。这恰好能解释那个很迷惑的现象——你明明把配置改对了再跑一次还是断在第 3 步因为进程压根没读到你的修改。ANTHROPIC_MODEL不是必须项不填就按客户端默认模型走要指定的话模型名以控制台模型列表里实际可用的为准写错会直接报模型不存在。4. Codexconfig.toml 的 model_providers别把 ANTHROPIC_* 塞进去这一节是我踩过最久的坑。Codex 不认识ANTHROPIC_*这组变量硬塞进去不会报错只会静默失效——然后你就得到一个“配置看起来改了、但其实完全没生效”的假象。Codex 的正确写法是在~/.codex/config.toml里声明一个自定义 provider# ~/.codex/config.toml model YOUR_MODEL_NAME # 与 TaoToken 模型列表里可用的名称保持一致 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY # 这里填的是「环境变量名」不是 Key 本身 wire_api chat关键点在env_keyCodex 不会把 Key 明文写进配置文件而是去读这个名字对应的环境变量。所以你还得在 shell 里把这个变量设上export TAOTOKEN_API_KEYYOUR_API_KEY想让它长期生效就追加到~/.zshrc或~/.bashrc然后 source 一下。验证变量在不在别回显完整 Key[ -n $TAOTOKEN_API_KEY ] echo TAOTOKEN_API_KEY present || echo missing把两个客户端放在一起对照就不容易搞混了客户端配置文件端点写在哪Key 写在哪Claude Code~/.claude/settings.jsonANTHROPIC_BASE_URLANTHROPIC_AUTH_TOKENCodex~/.codex/config.tomlprovider 段内的base_urlenv_key指向的环境变量一句话原则ANTHROPIC_*只属于 Claude CodeCodex 走config.tomlenv_key。两边混用轻则静默失效重则报一堆看起来像网络问题的错。5. CC Switch三件套填完直接切不动客户端文件如果同一台机器上既要跑 Claude Code、又要跑 Codex来回改两套文件确实烦。CC Switch 这类配置切换工具就是干这个的把「名称 / Base URL / API Key」三件套填一次之后在不同客户端之间点一下切换。字段填什么备注名称TaoToken只是个标识随意起Base URLhttps://taotoken.net/api末尾不要带斜杠API KeyYOUR_API_KEY从控制台 API Keys 页面创建填完之后有两件事必须做。第一切完重启对应客户端理由和上一节一样运行中的进程不会自动重读配置。第二确认切换目标是谁——切换工具改的是“当前激活的那一个”的配置文件切错了就会出现「在 Codex 里找ANTHROPIC_*找不到」或者反过来的怪现象。三件套的价值在于可复现换机器、换课题组服务器、重装系统照这张表再填一次就恢复不用回忆当初到底改了哪个文件。6. 断档任务重跑把 COSMIC 查询参数固化成文件配置理清之后重跑的关键是别再让任务从零开始。把查询参数固化成一份 JSONAgent 每次读它就行也方便你 diff 两次运行到底差在哪{ database: COSMIC, genome_build: GRCh38, genes: [EGFR], protein_changes: [p.L858R, p.T790M, p.E746_A750del], primary_site: lung, histology: adenocarcinoma, sample_type: tumour, min_sample_count: 2, exclude_germline: true, return_fields: [ cosmic_id, mutation_aa, mutation_cds, sample_count, primary_site, pubmed_pmid ] }保存成cosmic_egfr_query.json放在课题目录下然后在 Agent 里显式指定技能名并指向这份参数文件使用 cosmic-mutation 技能读取 ./cosmic_egfr_query.json 里的参数执行查询。 只做数据库注释与汇总不要自行改写参数每一步的实际请求与返回值写进 ./cosmic_run_log/ 目录。最后一句很关键。Agent 默认只给你最终答案不给过程一旦中途断档你手上什么都没有。要求它把每一步的请求与返回值落到日志目录断了也有东西可查——这次我就是靠日志才定位到断点发生在第 3 轮模型调用而不是数据库侧。重跑记录我按这个格式留档出问题直接对着表查顺序阶段现象定位到的原因处理1工具调用第 3 轮请求中断客户端 Base URL 未生效进程仍用旧端点退出并重启 Claude Code2工具调用第 3 轮401Key 未写入 settings.json补上ANTHROPIC_AUTH_TOKEN3全流程正常无保留参数文件与日志目录第 3 行跑通之后我把cosmic_egfr_query.json、settings.json和cosmic_run_log/一起放进了课题仓库。下次换样本、换基因只改参数文件配置这一层完全不用再动。7. 写对了没有四步校验清单每次改完配置按这四步过一遍基本不会再有“改了不生效”的情况。第一步确认文件落点ls -l ~/.claude/settings.json ~/.codex/config.toml 2/dev/null第二步确认进程里的变量Key 一律掩码不要回显完整值echo ANTHROPIC_BASE_URL${ANTHROPIC_BASE_URL:-unset} [ -n $ANTHROPIC_AUTH_TOKEN ] echo ANTHROPIC_AUTH_TOKENset || echo ANTHROPIC_AUTH_TOKENunset [ -n $TAOTOKEN_API_KEY ] echo TAOTOKEN_API_KEYset || echo TAOTOKEN_API_KEYunset第三步确认端点可达仍是本地执行curl -sS -I https://taotoken.net/api | head -n 3第四步看 Agent 日志里第一轮请求是否成功。第一轮就失败是配置问题跑到中间才断多半是长任务里某一轮被中断需要看那一轮的具体返回码。顺带说一句安全边界。Skill 这类东西权限不小能执行代码、发起网络请求、读写本地文件所以未发表的实验数据、患者隐私数据、涉密项目不要直接丢给云端 Agent 处理数据库查询和命令都在你自己机器上本地执行Agent 输出的代码和结论必须人工复核。AI 在这儿只是加速器科研结论的最终责任还是研究者本人的。8. 结语把 Base URL 当成科研环境的一部分这次断档给我的最大教训不是某个参数写错了而是一个认知上的偏差我一直把「模型接口配置」当成装完就忘的一次性动作但实际上它和 conda 环境、参考基因组版本、样本命名规则一样是科研环境的一部分需要显式记录、显式固定、显式可复现。Agent 的多轮工具调用把这一点放大了——环境里有任何一处不稳整条流水线都会断在中间而且断得毫无提示。所以现在的做法很简单Key 从 TaoToken 官网 建一次Base URL 全平台统一https://taotoken.net/api配置文件跟着课题仓库走任务参数固化成 JSON运行日志落到本地目录。这四样齐了换样本、换基因、换机器重跑都只是改一个参数文件的事。如果你手上也有一条卡在中间的数据库查询任务按这个顺序走一遍通常就能通先在模型对话页确认模型调用本身是通的长任务场景看一眼 Coding Plan确认调用量够撑完整条流水线到创建 Key页面生成YOUR_API_KEY最后照 Claude Code 文档把settings.json落好重启客户端重跑你那条断掉的任务。把接口这一层一次性钉死剩下的时间才真正属于科学问题本身。