Agent 30 课程开发指南 - 第0课：用 TaoToken 统一 Key 打通 CLI 与 Web 双端配置

1. 第0课到底在准备什么CLI 与 Web 双端共用一套 Key如果你正在跟 Agent 30 课程第0课的目标很明确把环境准备好让后面 30 节课不用反复折腾密钥和接口地址。课程里会同时出现两种形态的 Agent——跑在终端里的 CLI 助手和跑在浏览器里的 Web 聊天界面。它们底层都要调用 LLM如果各自维护一套 Key、各自写一份配置后面做多提供者、故障转移、用量统计时会非常痛苦。所以第0课真正要解决的是「统一入口」问题用 TaoToken 作为统一的 API 通道CLI 端和 Web 端读同一份凭据只是配置文件格式不同。CLI 侧常见的是settings.json很多 Python Agent 框架用它存模型和密钥Web 侧常见的是config.tomlFastAPI 项目里放服务参数和模型配置。两者指向同一个base_url和同一个api_key切换模型时只改一处。这篇适合谁已经装好 Python 3.12、准备按课程顺序敲代码的开发者手里有 OpenAI 兼容或 Anthropic 兼容调用需求但不想在每节课里重复配环境的人。读完之后你应该能做到——写好两份配置骨架发一次真实请求看到模型正常返回确认双端都通了。下面所有命令和配置都可以直接复制改掉 Key 就能跑。2. 前置拿到 TaoToken 的 Key 与接口地址TaoToken 在这里扮演的角色是「统一的模型调用入口」。你不需要在 CLI 和 Web 里分别填不同厂商的地址只要拿到一个 Key两端都指向同一个 API 地址即可。对课程来说这能省掉大量「这节课换了个提供者配置又要重写」的重复劳动。先到控制台创建 Key。打开 https://taotoken.net/api-keys 登录后新建一个 API Key复制出来先存到临时地方。注意 Key 只在创建时完整显示一次关掉页面就看不全了建议直接写进环境变量而不是硬编码进代码。接口地址统一用https://taotoken.net/api这是 OpenAI 兼容风格的基础地址。也就是说任何支持自定义base_url的 OpenAI SDK 或框架把地址换成它就能用。Anthropic 兼容的调用也走同一套凭据体系课程后面讲 Claude 提供者时会用到。注意不要把 Key 提交到 Git。第0课就养成用环境变量的习惯后面课程 12 讲安全守卫、课程 27 讲脱敏时你会感谢现在的自己。建议先在 shell 里导出方便后面 CLI 直接读取export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的Key。导出后可以用echo $TAOTOKEN_API_KEY确认非空。这一步做完前置就齐了接下来写两份配置。3. 可复制配置settings.json 与 config.toml 骨架课程里 CLI 端和 Web 端读的配置文件不一样但核心字段是同一组base_url、api_key、model。先给 CLI 用的settings.json。放在项目根目录或者课程约定的config/目录下具体路径按你框架的加载逻辑来这里给的是通用骨架{ provider: openai-compatible, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, model: gpt-4o-mini, timeout: 60, max_retries: 2, stream: true }这里故意不写死api_key而是用api_key_env指向环境变量。好处是配置文件可以进版本库Key 留在本地环境里。model先填一个通用模型后面课程 6 讲提供者抽象、课程 7 讲 Anthropic 提供者时你会在这里扩展成多模型列表。再给 Web 端用的config.toml。FastAPI 项目通常用 TOML 存服务参数模型部分和 CLI 保持一致[server] host 127.0.0.1 port 8000 [llm] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model gpt-4o-mini timeout 60 stream true [llm.fallback] enabled true model claude-3-5-sonnet两份配置的base_url和api_key_env完全一致这就是「统一 Key」的落地方式。CLI 和 Web 各自解析自己的格式但拿到的凭据是同一份。后面课程 10 讲熔断器与故障转移时fallback段就能派上用场。读取配置的 Python 代码可以这样写CLI 和 Web 都能复用import json import os import tomllib from pathlib import Path def load_settings(path: str settings.json) - dict: data json.loads(Path(path).read_text(encodingutf-8)) data[api_key] os.environ[data[api_key_env]] return data def load_web_config(path: str config.toml) - dict: with open(path, rb) as f: cfg tomllib.load(f) cfg[llm][api_key] os.environ[cfg[llm][api_key_env]] return cfgtomllib是 Python 3.11 标准库课程用 3.12 正好自带不用额外装包。这样两端读配置的逻辑就统一了。4. 验证请求一次调用确认双端配置生效配置写完不能只看要发一次真实请求。先验证 CLI 侧用 OpenAI SDK 直接打 TaoToken 的接口import os from openai import OpenAI client OpenAI( base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 只回复两个字通了}], streamFalse, ) print(resp.choices[0].message.content)跑之前确认装了 SDKpip install openai。执行后如果打印出「通了」说明 CLI 侧的地址和 Key 都正确。这一步对应课程 1「向 LLM 问好」只是把提供者换成了统一入口。再验证 Web 侧。Web 端本质也是用同一组凭据发请求区别只是包在 FastAPI 里。可以先写一个最小接口测试from fastapi import FastAPI from pydantic import BaseModel from openai import OpenAI import os app FastAPI() client OpenAI( base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) class ChatIn(BaseModel): message: str app.post(/chat) def chat(body: ChatIn): resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: body.message}], ) return {reply: resp.choices[0].message.content}启动uvicorn main:app --reload然后另开终端发请求curl -X POST http://127.0.0.1:8000/chat \ -H Content-Type: application/json \ -d {message:只回复两个字通了}返回{reply:通了}就说明 Web 侧也通了。两端用的是同一个 Key、同一个base_url这就是第0课要的结果。想先在浏览器里直接对话确认模型可用可以打开 https://taotoken.net/models 试一下不用写代码就能验证 Key 是否有效。5. 本篇常见错排查配置阶段最容易踩的坑集中在几类。第一类是环境变量没生效load_settings里用os.environ[...]直接取值变量没导出会抛KeyError。排查方法是先echo $TAOTOKEN_API_KEY为空就重新 export注意 export 只在当前 shell 会话有效新开终端要重新执行或写进~/.bashrc。第二类是base_url写错。常见错误是写成https://taotoken.net/api/v1或漏掉/api。OpenAI SDK 会自己在后面拼/chat/completions所以基础地址到/api为止。如果报 404先检查这一项。第三类是 TOML 解析报错。tomllib.load要求以二进制模式打开文件写成open(path)会报TypeError。另外 TOML 里字符串必须用引号model gpt-4o-mini是错的要写model gpt-4o-mini。第四类是模型名不存在。不同提供者的模型命名不一样填错会返回模型不存在的错误。先在模型列表页确认可用模型名再写进配置。课程后面做多提供者时模型名会作为配置项传入所以现在就要养成「模型名可配置」的习惯。第五类是超时。默认超时太短时长回复会中断。配置里的timeout设成 60 秒比较稳流式输出场景可以更长。如果频繁超时先确认网络能正常访问接口地址再考虑调大超时。提示排障时把stream先设为false非流式返回更容易定位问题。确认通了再打开流式。6. 下一步把统一 Key 带进后续课程第0课做完你手里应该有两份能跑的配置、一个验证过的 Key、一次成功的请求记录。接下来课程 1 到 4 会在这个基础上加流式输出、工具调用和智能体循环配置结构不用大改只是往settings.json里加字段。课程 5 到 8 会正式做配置系统和多提供者抽象那时你会把现在这份骨架扩展成完整的 Pydantic 设置模型。如果你打算长期跟这套课程、后面还要做编码类 Agent 或自动化任务可以了解一下 Coding Plan它更适合持续性的开发调用场景https://taotoken.net/coding-plan 。接入细节和参数说明都在文档里https://taotoken.net/doc 。CLI 和 Web 双端配置的完整字段也可以对照控制台里的示例再核一遍https://taotoken.net/console 。现在最该做的一件事把上面那段验证脚本跑通看到「通了」两个字。第0课不追求功能多只追求环境干净、凭据统一。这一步稳了后面 30 节课的代码才有地方落。