1. 科研 Agent 查天气 API：先让 Agent 筛 Auth、HTTPS，再跑最小请求
科研 Agent 查天气 API 时，TaoToken 官网（https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=weather_agent_intro）是模型调用前先拿 Key 的入口，Base URL 用 https://taotoken.net/api。真正卡住采集流程的，往往不是模型不会写请求，而是候选接口在 Auth、HTTPS、CORS 上不一致：本地 curl 返回 200，浏览器页面却被跨域拦下；文档写着免费，请求回来 401；链接看着还在，打开却是 404。
对科研数据采集者来说，最怕的不是接口少，而是“看起来能用”。一个天气接口能不能进你的实验流程，至少要先过四关：鉴权方式、加密访问、浏览器跨域、免费层条款。public-apis 这类社区维护目录的价值，是把天气、地理编码、财经、新闻、开放数据等入口按分类摆出来，让你先缩小范围，而不是在搜索广告和旧教程之间来回跳。它本身不是一个统一 API 平台，也不是接上就能生产使用的数据总线。更合理的用法是：把目录当候选池，让 Agent 先读 Auth、HTTPS、CORS 三列，筛出 3 到 5 个候选，再逐个跑最小请求，最后根据返回字段、限流、文档完整度决定是否进入正式采集。
这条工作流里，模型可以帮你读文档、改 curl、解释 JSON 字段、生成字段映射表，但模型调用需要稳定的 Base URL 和 Key。TaoToken 在这里的角色是提供模型调用入口，不替代天气数据服务本身。天气数据仍然由 Open-Meteo、OpenWeatherMap、WeatherAPI 等天气服务返回；TaoToken 负责的是 Agent 的模型侧调用。把这两层分清，后面排障才不会混：401 可能来自天气服务，也可能来自模型服务；CORS 报错发生在浏览器，不一定发生在服务端脚本。
下面按“候选表 → 最小请求 → 返回字段 → 模型配置 → 排障”的顺序走一遍，尽量让每个步骤都能本地复现。
2. 天气 API 候选表：从 public-apis 的 Auth、HTTPS、CORS 三列开始
public-apis 目录里，天气分类的每个条目通常会给三列关键信息：Auth、HTTPS、CORS。很多人的第一反应是找“免费”，但更稳的顺序是先看 Auth 和 HTTPS，再看 CORS，最后才看免费额度和文档。
Auth 表示鉴权方式。No 代表请求本身不强制带认证信息；apiKey 代表通常要申请 Key；OAuth 代表要走授权流程。注意，Auth=No 不等于没有频率限制、商用限制或数据授权限制。HTTPS 表示是否提供加密访问。做科研数据采集，建议优先选 HTTPS=Yes，避免在脚本、日志、代理层暴露明文请求。CORS 影响浏览器端调用：Yes 通常前端更省事；No 往往只能在服务端使用；Unknown 需要自己实测，不能只看目录。
给 Agent 的筛选提示词可以这样写，让它在本地处理候选，不要直接连接生产数据库：
你是科研数据采集助手。任务：从本地 public-apis 仓库的 Weather 分类中筛出 5 个天气 API 候选。 筛选顺序： 1. Auth 为 No 或 apiKey；OAuth 暂时跳过。 2. HTTPS 必须为 Yes。 3. CORS 为 Yes 优先；Unknown 标记为待验证；No 只用于服务端。 4. 对每个候选输出：名称、Auth、HTTPS、CORS、文档入口、最小 curl 示例、可能返回字段。 5. 不确定的字段写 Unknown，不要编造。 6. 不要直接连接任何生产数据库，只输出候选表和本地验证命令。让 Agent 按这个提示词跑完后，你可以得到一张候选表。下面是一个示例结构，实际字段以你本地目录和官方文档为准：
| 候选 | Auth | HTTPS | CORS | 适合的科研场景 | 最小请求前要确认 |
|---|---|---|---|---|---|
| Open-Meteo | No | Yes | Yes | 快速拿预报/历史，做时间序列试验 | 时间区、变量名、历史数据范围 |
| wttr.in | No | Yes | Unknown | 终端可视化、人工核对 | CORS 需实测，更适合服务端 |
| OpenWeatherMap | apiKey | Yes | Yes | 当前天气、城市名查询 | 免费层限额、Key 激活延迟 |
| WeatherAPI | apiKey | Yes | Yes | 预报+历史+空气质量 | 免费层字段权限 |
| Visual Crossing | apiKey | Yes | Yes | 历史天气、批量日期 | 免费额度、商用条款 |
| 和风天气 | apiKey | Yes | Yes | 国内城市天气、生活指数 | 控制台项目、Key 类型 |
这张表不是让你直接选第一个，而是让 Agent 先把“能跑通”和“能长期用”分开。做 Demo 时，可以优先试 Auth=No 且 HTTPS=Yes 的接口；准备写论文或做长期采集时，必须回到原始文档核对配额、价格、隐私政策、数据授权和稳定性。尤其是历史天气，不同服务对过去日期、时间粒度、站点覆盖差异很大，只看“免费天气 API”几个字很容易踩坑。
候选表产出后，不要急着批量抓。先选一个无 Key 接口跑最小请求，再选一个 apiKey 接口跑最小请求，把两条路径都验证一遍。这样你能同时确认：无鉴权接口是否稳定、带 Key 接口的 Key 传递方式、返回字段是否符合实验需求。
3. curl 最小请求：无 Key 与 apiKey 两套模板
最小请求的目标不是拿全量数据，而是确认三件事：请求能否成功、鉴权是否生效、返回结构是否可解析。第一套模板用无 Key 接口，适合快速验证网络和 JSON 结构。
curl -sS "https://api.open-meteo.com/v1/forecast?latitude=39.9042&longitude=116.4074&hourly=temperature_2m,relative_humidity_2m,precipitation&forecast_days=1&timezone=Asia%2FShanghai"这条命令只取北京一天的小时级温度、湿度和降水。如果返回 JSON，说明网络、DNS、HTTPS、基础参数都通。可以用 jq 截取前三个小时，减少输出：
curl -sS "https://api.open-meteo.com/v1/forecast?latitude=39.9042&longitude=116.4074&hourly=temperature_2m,relative_humidity_2m,precipitation&forecast_days=1&timezone=Asia%2FShanghai" \ | jq '{time: .hourly.time[0:3], temp: .hourly.temperature_2m[0:3], humidity: .hourly.relative_humidity_2m[0:3]}'第二套模板用 apiKey 接口。Key 不要写进代码仓库，先放环境变量，再在 curl 中引用：
export WEATHER_API_KEY="你的天气服务Key" curl -sS "https://api.openweathermap.org/data/2.5/weather?q=Beijing&appid=${WEATHER_API_KEY}&units=metric&lang=zh_cn"如果返回 401，先检查 Key 是否复制完整、是否激活、参数名是不是 appid，以及请求里有没有多余空格。如果返回 429，说明触发限流或免费层额度，先降低请求频率。如果返回 404，通常是城市名、接口路径或参数拼写问题。不要一看到失败就换接口，先把错误码和响应体读清楚。
最小请求跑通后，建议把命令写进一个本地脚本，并加两个约束：一是固定时间区，二是限制输出行数。科研采集最怕的是“今天能跑，明天字段变了”。固定 timezone 可以避免 UTC 和本地时间混用；限制输出可以让你在 Agent 里快速看结构，而不是把大 JSON 全塞进上下文。
4. 返回字段怎么读：把天气 JSON 变成科研 Agent 可用表
以 Open-Meteo 的返回为例，常见顶层字段包括：
| 字段 | 含义 | 科研用途 |
|---|---|---|
| latitude / longitude | 请求点纬度、经度 | 记录采集位置，做空间对齐 |
| generationtime_ms | 服务生成耗时 | 监控接口性能 |
| utc_offset_seconds | UTC 偏移秒数 | 时间统一 |
| timezone | 时区名 | 避免本地时间歧义 |
| timezone_abbreviation | 时区缩写 | 展示和日志 |
| elevation | 海拔 | 温度、气压解释变量 |
| hourly_units | 小时级字段单位 | 单位换算 |
| hourly.time | 小时时间数组 | 时间索引 |
| hourly.temperature_2m | 2 米温度数组 | 温度序列 |
| hourly.relative_humidity_2m | 2 米相对湿度数组 | 湿度序列 |
| hourly.precipitation | 降水量数组 | 降水事件 |
这些数组是对齐的：hourly.time[0]对应hourly.temperature_2m[0]、hourly.relative_humidity_2m[0]。写入 CSV 或 DataFrame 前，先检查数组长度是否一致。Agent 可以帮你生成字段映射表，比如把hourly.temperature_2m重命名为temp_c，把hourly.relative_humidity_2m重命名为rh_pct，但重命名规则要由你确认，不要让模型猜单位。
OpenWeatherMap 当前天气接口的常见字段又是另一套：
| 字段 | 含义 |
|---|---|
| coord.lat / coord.lon | 城市经纬度 |
| weather[0].main | 天气主状态 |
| weather[0].description | 天气描述 |
| main.temp | 温度 |
| main.feels_like | 体感温度 |
| main.humidity | 相对湿度 |
| main.pressure | 气压 |
| wind.speed / wind.deg | 风速、风向 |
| clouds.all | 云量 |
| dt | 数据时间戳 |
| sys.sunrise / sys.sunset | 日出日落 |
| timezone | 时区偏移 |
| name | 城市名 |
| cod | 响应状态码 |
科研数据采集者最好保留原始 JSON，再在上层做字段映射。原始 JSON 是证据，映射表是方便分析。Agent 可以在你给出三到五条样本后，自动生成字段说明和缺失值报告。比如某个小时温度数组有null，不要直接填 0，要先确认是接口缺测还是请求变量不支持。
这里可以加一条本地 jq 命令，快速检查数组长度：
curl -sS "https://api.open-meteo.com/v1/forecast?latitude=39.9042&longitude=116.4074&hourly=temperature_2m,relative_humidity_2m&forecast_days=1&timezone=Asia%2FShanghai" \ | jq '{time_len: (.hourly.time | length), temp_len: (.hourly.temperature_2m | length), humidity_len: (.hourly.relative_humidity_2m | length)}'如果三个长度不一致，先不要入库，先回到文档确认变量和日期范围。
5. 模型调用前换到 TaoToken：Claude Code、Codex、CC Switch 配置
天气 API 负责数据，模型负责筛选、解释和生成采集脚本。模型调用前，先到 TaoToken 官网（https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=weather_agent_key_setup）完成 Key 相关操作，控制台入口和申请步骤以官网为准。Base URL 使用：
https://taotoken.net/apiClaude Code 可以用settings.json配ANTHROPIC_*环境变量。示例路径是~/.claude/settings.json：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "YOUR_API_KEY" } }如果你的 Claude Code 版本读取的是ANTHROPIC_AUTH_TOKEN，把键名换成它即可，Base URL 不变。不要同时塞入多个来源的 Key，否则排障时很难判断实际生效的是哪一个。
Codex 用config.toml，不要套用ANTHROPIC_*。示例路径是~/.codex/config.toml：
model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY"终端里设置对应环境变量：
export TAOTOKEN_API_KEY="YOUR_API_KEY"CC Switch 可以把供应商配置集中管理，但三件套要一起切换：
供应商名称：TaoToken Base URL：https://taotoken.net/api API Key：YOUR_API_KEY只改 Key，不改 Base URL，Agent 可能还在请求旧服务；只改 Base URL，不改 Key，可能直接 401。三件套同时更新后，重启终端或编辑器，再让 Agent 跑一次“只输出模型配置是否生效”的轻量请求。确认模型侧通了，再去跑天气 API 的最小请求。两条链路分开验证，比混在一起猜错误更省时间。
6. 排障清单：401、403、CORS、404/410 在天气 API 场景怎么定位
天气 API 和模型 API 都可能返回 401，但来源不同。先看请求域名：如果是天气服务域名，检查天气 Key、参数名、是否激活；如果是模型服务域名，检查 TaoToken Key、Base URL 和 Claude Code / Codex 配置。排障时可以把官网（https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=weather_agent_troubleshoot）作为模型侧配置核对入口。
403 常见于服务端限制、地区限制、User-Agent 限制或免费层不允许。不要急着换代理，先读响应体和文档。科研采集要遵守服务条款，不要绕过限制。CORS 报错通常发生在浏览器：控制台提示跨域，但本地 curl 正常。这时看 public-apis 条目的 CORS 列：Yes 优先，Unknown 要实测，No 就放到服务端调用。把采集逻辑从浏览器挪到后端脚本，往往比找“跨域头”更稳。
404 和 410 在公共 API 目录里很常见。社区曾有人对目录做过扫描，报告过一批链接返回 404 或 410，并排除了 403、429、超时等可能由扫描环境造成的情况。这个反馈提醒我们：目录是线索，不是可用性保证。你选中的天气接口，今天能打开文档，明天可能迁移路径。正式采集前，把文档入口、最小请求、返回样本三件事一起存进本地验证记录。
429 是限流。不要用并发硬顶，先加缓存、降频、合并请求。比如小时级天气不需要每秒拉一次，可以按小时落盘。超时和 DNS 失败先检查网络、重试次数和超时设置，不要和鉴权错误混为一类。建议做一个排障表：
| 现象 | 优先检查 | 处理方式 |
|---|---|---|
| 401 | Key、Header、环境变量 | 重新复制 Key，确认参数名 |
| 403 | 服务条款、地区、User-Agent | 读文档，合规调整 |
| CORS | 浏览器控制台、CORS 列 | 改服务端调用 |
| 404/410 | 文档链接、接口路径 | 重新在目录找候选 |
| 429 | 免费额度、频率 | 加缓存、降频 |
| 超时 | DNS、网络、超时时间 | 重试并记录日志 |
排障完成后，把可复现结果写回候选表：接口名、Auth、HTTPS、CORS、最小 curl、返回字段、错误码。这样下一个 Agent 接手时，不用从零开始。
7. 从候选表到可复现数据：科研 Agent 的工作流封装
最终工作流可以固定成五步：
- 本地读取 public-apis 天气分类，让 Agent 输出候选表。
- 按 Auth、HTTPS、CORS 筛选，保留 3 到 5 个候选。
- 对每个候选跑最小 curl，记录成功/失败、响应时间、字段结构。
- 用 jq 或本地脚本检查数组长度和缺失值，写字段映射表。
- 模型侧用 TaoToken 的 Base URL 和 Key，天气侧用各服务自己的 Key，分开配置、分开排障。
不建议一上来就让 Agent 批量抓取，也不建议让 Agent 直接连接生产数据库。正确顺序是先本地验证请求，再把数据落到文件或测试库。科研数据采集需要可复现，所以每个天气接口至少保留：请求命令、请求时间、原始响应、字段说明、异常记录。模型可以帮你整理，但最终判断仍由你完成。
如果要把这套流程交给 Codex 或 Claude Code，建议在项目根目录放一个weather_api_candidates.md，内容就是候选表；再放一个verify_weather.sh，里面只有最小 curl 和 jq 检查。Agent 每次改动后，先跑verify_weather.sh，再更新候选表。这样天气 API 的变更不会悄悄污染模型侧配置。
8. 文末 CTA：模型对话 → Coding Plan → 创建 Key → Claude Code 文档
如果你还没把模型调用链路配好，可以按下面顺序走：
- 先试模型对话：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=weather_agent_chat
- 再看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=weather_agent_plan
- 然后创建 Key：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=weather_agent_keys
- 最后对照 Claude Code 文档改配置：https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=weather_agent_claude_code_doc
模型侧配置统一使用 Base URL：https://taotoken.net/api，Key 占位符用YOUR_API_KEY。天气侧仍然按 public-apis 候选表逐个验证，先筛 Auth 和 HTTPS，再跑最小请求，最后看返回字段。把“找接口”变成“候选表 + 最小请求 + 字段说明 + 排障记录”，科研 Agent 查天气 API 这件事才会从一次性的尝试，变成可复现的数据采集流程。
