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.toml（FastAPI 项目里放服务参数和模型配置）。两者指向同一个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_KEY="sk-你的Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

Windows PowerShell 用$env:TAOTOKEN_API_KEY="sk-你的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(encoding="utf-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 cfg

tomllib是 Python 3.11+ 标准库，课程用 3.12 正好自带，不用额外装包。这样两端读配置的逻辑就统一了。

4. 验证请求：一次调用确认双端配置生效

配置写完不能只看，要发一次真实请求。先验证 CLI 侧，用 OpenAI SDK 直接打 TaoToken 的接口：

import os from openai import OpenAI client = OpenAI( base_url=os.environ["TAOTOKEN_BASE_URL"], api_key=os.environ["TAOTOKEN_API_KEY"], ) resp = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "只回复两个字：通了"}], stream=False, ) print(resp.choices[0].message.content)

跑之前确认装了 SDK：pip 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_url=os.environ["TAOTOKEN_BASE_URL"], api_key=os.environ["TAOTOKEN_API_KEY"], ) class ChatIn(BaseModel): message: str @app.post("/chat") def chat(body: ChatIn): resp = client.chat.completions.create( model="gpt-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 节课的代码才有地方落。