企业官网建设流程全解析

1. 微软 Agent 课跑通后，最先炸的不是 RAG 逻辑，是 Key

把微软那套 AI Agent 入门课（RAG、MCP、多智能体都有配套代码）拉到本地跑第一个示例时，多数人遇到的第一颗雷并不是检索写得不对，而是openai.AuthenticationError: Error code: 401 - invalid_api_key。TaoToken 在这里的作用很单纯：它只提供统一入口，你在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=rag_multiagent_key 拿到一个 Key，把 Base URL 填成https://taotoken.net/api，剩下 RAG 怎么切块、多智能体怎么分角色，全都归你自己的代码管。

这套课之所以在 GitHub 上被反复 star，是因为它把 RAG、MCP、多智能体三块拆成了可运行的 notebook，每一块都能单独跑。但拆得越细，配置就越散：RAG 那一章要一个 embedding/chat 客户端，MCP 那一章要给工具层配一个客户端，多智能体那一章又是每个角色一个client = OpenAI(...)。于是常见的一幕出现了：

• 01_rag.ipynb里 base_url 写的是默认官方地址；
• 02_mcp.ipynb里改了环境变量名，OPENAI_API_KEY和API_KEY混着用；
• 03_multi_agent.ipynb干脆把 key 硬编码在 cell 里，跑完忘了删。

等到你想把三个 notebook 串成一条流水线，就会在同一个进程里看到三种不同的鉴权来源。本文不重复讲课程内容，只解决一件事：把 RAG 生成阶段和多智能体角色调用的 Token 出口统一到一个 Key、一个 Base URL 上，并且给出可以直接粘贴的配置片段、运行命令和排障顺序。

2. 统一 Key 的接入骨架：一个 Base URL、一个 Key、一份模型名映射

先把结论写清楚，后面所有章节都围绕这三行展开：

TAOTOKEN_API_KEY=YOUR_API_KEY TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=<你在模型列表里看到的模型ID>

Base URL 统一填https://taotoken.net/api，不要再在代码里写任何第三方域名。Key 全部从环境变量读，任何 notebook、任何 agent 构造函数、任何 MCP server 的工具层都不允许出现字面量 Key。

为什么强调"只提供入口"这件事？因为 RAG 和多智能体的 Token 消耗形态完全不同，把供应商差异抽象掉之后，你才有精力去优化真正费钱的地方：

• RAG 阶段：一次问答是"1 次 embedding（可选）+ 1 次生成"，生成阶段的输入 Token 随top_k和 chunk 长度线性膨胀。检索回来的 5 段文本，每段 500 token，输入侧直接就是 2500 token 起步。
• 多智能体阶段：一次任务可能是N 个角色 × M 轮协作次调用。规划者一次、检索者一次、写作者一次、审阅者再回给写作者一次，四个角色两轮就是 8 次请求。每次请求都带完整系统提示词，系统提示词的重复计费是最容易被忽略的部分。

统一 Key 之后，这两类消耗会汇总到同一份用量视图里，你才能回答"到底是检索拖长了输入，还是角色轮数太多"这种问题。想先看模型清单和可用模型 ID，从 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=model_catalog 进控制台对照着填。

环境变量落盘建议分两层：项目级.env给 Python 用，用户级 shell profile 给 Claude Code / Codex 这类 CLI 用。两层共用同一个 Key，避免"notebook 能跑、CLI 报 401"。

3. Claude Code 侧：settings.json 与 ANTHROPIC_* 环境变量

Claude Code 的读取优先级是「settings.json里的env块」优先于「shell 里已有的同名环境变量」，所以最稳的做法是把它写进用户级配置文件~/.claude/settings.json：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "<你的模型ID>", "ANTHROPIC_SMALL_FAST_MODEL": "<你的轻量模型ID>" } }

几点容易踩的细节：

1. ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY是两个不同的键。前者用于 Bearer 风格的鉴权头，后者走x-api-key。如果你的请求一直返回 401，先确认你填的是哪一个，然后两个都试一遍，观察哪一个不再报错，之后固定下来。
2. settings.json必须是合法 JSON，不能有注释、不能有尾逗号。Claude Code 解析失败时会静默回退到默认配置，症状就是"我明明改了，怎么还在连原来的地址"。
3. ANTHROPIC_SMALL_FAST_MODEL用于后台的轻量任务（比如生成对话标题）。如果留空，某些版本会因为找不到模型而把错误堆到主流程里，建议显式指定一个便宜的模型。
4. 改完settings.json需要重开一次终端会话，环境变量不会热加载。

如果你更习惯用 shell 变量管理，等价写法是：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY" export ANTHROPIC_MODEL="<你的模型ID>"

验证是否生效，直接在项目目录里跑一次最简单的对话请求，观察它有没有在启动日志里打出你配置的 Base URL。完整的 CLI 配置说明和常见问题在 https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code_doc 里，遇到字段不确定就对着文档改，不要凭记忆猜键名。

4. Codex 侧：config.toml 里的 model_provider 写法

Codex 不吃ANTHROPIC_*这一套。它的配置入口是~/.codex/config.toml，通过model_provider指定一个自定义 provider，再在[model_providers.*]表里描述连接信息。写错的最典型症状是"Key 明明是对的，但 Codex 一直说找不到 provider"。

正确形态如下：

model = "<你的模型ID>" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat"

要点逐条解释：

• model_provider的值必须和下面表名model_providers.taotoken的后缀完全一致，大小写敏感。
• env_key写的是环境变量的名字，不是 Key 本身。所以你还需要在 shell 里export TAOTOKEN_API_KEY="YOUR_API_KEY"。把 Key 直接写进config.toml会导致它被提交进 Git。
• wire_api决定请求体的形状。走 Chat Completions 风格就填chat，如果你的模型只支持别的协议，需要按实际支持情况调整，不要照抄。
• 修改config.toml后同样需要新开终端。Codex 启动时会做一次配置解析，解析失败通常会给出具体行号，照着行号看。

一个实用的自检方法：先用curl在终端里验证 Key 和 Base URL 是否可用，再把同样的值搬进config.toml。这样能立刻区分"是 Key/地址不对"还是"是配置文件格式不对"。

curl -sS https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"<你的模型ID>","messages":[{"role":"user","content":"ping"}]}'

如果这条命令返回 401，问题在 Key；返回 404，问题在路径或模型 ID；返回 200 但 Codex 仍报错，问题在config.toml的字段拼写。Key 的创建和管理入口在 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys_console ，建议给 CLI 和 notebook 各建一个 Key，出问题好区分、也好单独吊销。

5. CC Switch 三件套：配置文件、环境变量、切换命令

同时跑 Claude Code 和 Codex 的人，迟早会遇到一个需求：白天要用一套配置做调试，晚上要切回另一套做长任务，手动改 JSON 和 TOML 很容易改错。CC Switch 这类工具解决的就是这个切换问题，它通常由三部分组成：

第一件：providers 定义。把每个连接目标写成一个具名条目，包含 base_url、env_key 名称、备注。这样切换时只换引用，不换内容。

{ "providers": [ { "id": "taotoken", "name": "TaoToken", "baseUrl": "https://taotoken.net/api", "envKey": "TAOTOKEN_API_KEY", "note": "RAG / 多智能体 / CLI 统一入口" } ] }

第二件：profile 绑定。一个 profile 描述"哪套 provider 配哪个工具"。因为 Claude Code 和 Codex 的配置格式不同，profile 需要分别指向~/.claude/settings.json和~/.codex/config.toml，由切换工具去写入对应的键值，而不是让用户手动同时维护两份。

第三件：切换命令与环境变量落盘。切换动作要做两件事：改写目标工具的配置文件，以及把对应的 Key 注入到当前 shell 会话。只做前者的话，CLI 进程能读到新配置，但你在同一个终端里跑的 Python 脚本还是旧 Key。

使用这类工具时有两条纪律：

• 切换工具只负责"把值写对位置"，不负责替你保管 Key。Key 本身仍然应该来自环境变量或系统的密钥存储，配置文件里只留变量名。
• 每次切换后跑一次最小验证命令，确认当前生效的 base_url 就是预期值。切了一半的配置比不切更糟。

需要说明的是，不同版本的 CC Switch 实现字段命名可能有差异，字段名以你安装的那个版本自带示例为准。上面这段 JSON 表达的是结构，不是某个版本的逐字照抄。

6. 回到 RAG 与多智能体：Python 侧统一 Key 的可运行片段

配置统一之后，代码层面要做的是"一个进程一个 client，所有角色复用"。先建一个最小的公共模块：

# taotoken_client.py import os from openai import OpenAI def get_client() -> OpenAI: base_url = os.environ.get("TAOTOKEN_BASE_URL", "https://taotoken.net/api") api_key = os.environ["TAOTOKEN_API_KEY"] return OpenAI(api_key=api_key, base_url=base_url) MODEL = os.environ.get("TAOTOKEN_MODEL", "<你的模型ID>") _usage = {"prompt": 0, "completion": 0, "calls": 0} def chat(messages, **kwargs): client = get_client() resp = client.chat.completions.create( model=MODEL, messages=messages, **kwargs, ) usage = getattr(resp, "usage", None) if usage is not None: _usage["prompt"] += getattr(usage, "prompt_tokens", 0) or 0 _usage["completion"] += getattr(usage, "completion_tokens", 0) or 0 _usage["calls"] += 1 return resp.choices[0].message.content def usage_snapshot(): return dict(_usage)

RAG 的生成阶段就变成了"拼上下文 + 一次chat调用"：

def answer_with_context(question, docs, top_k=4): picked = docs[:top_k] context = "\n\n".join( f"[片段 {i+1}] {d}" for i, d in enumerate(picked) ) system = ( "你是一个严谨的文档问答助手。" "只能依据提供的资料作答；资料不足时直接说明缺少哪些信息，不要编造。" ) user = f"资料：\n{context}\n\n问题：{question}" return chat( [ {"role": "system", "content": system}, {"role": "user", "content": user}, ] )

多智能体这边，关键是把角色提示词集中管理，并让所有角色共用同一个 client：

ROLE_PROMPTS = { "planner": "你是任务规划者。把目标拆成不超过 5 个可执行步骤，只输出步骤列表。", "retriever": "你是检索整理者。基于给定资料提炼要点，标注来源片段编号。", "writer": "你是撰写者。根据要点写出结构化答案，不要引入资料外的信息。", "reviewer": "你是审阅者。检查事实一致性与遗漏，输出修改建议，不重写全文。", } def run_role(role: str, payload: str) -> str: if role not in ROLE_PROMPTS: raise ValueError(f"unknown role: {role}") return chat( [ {"role": "system", "content": ROLE_PROMPTS[role]}, {"role": "user", "content": payload}, ] ) def run_pipeline(question: str, docs: list[str]) -> str: plan = run_role("planner", question) facts = run_role("retriever", f"资料：{docs}\n\n问题：{question}") draft = run_role("writer", f"计划：{plan}\n\n要点：{facts}") review = run_role("reviewer", f"草稿：{draft}\n\n要点：{facts}") final = run_role("writer", f"草稿：{draft}\n\n审阅意见：{review}") return final

运行命令就三步：

# 1. 准备环境变量 export TAOTOKEN_API_KEY="YOUR_API_KEY" export TAOTOKEN_BASE_URL="https://taotoken.net/api" export TAOTOKEN_MODEL="<你的模型ID>" # 2. 安装依赖 pip install openai python-dotenv # 3. 跑一次流水线并打印用量 python -c " from taotoken_client import run_pipeline, usage_snapshot out = run_pipeline('总结这份文档的核心结论', ['片段A', '片段B']) print(out) print(usage_snapshot()) "

注意最后一行打印出来的用量数字。run_pipeline一次调用就是 5 次模型请求，其中writer被调用了两次。这就是多智能体最典型的成本结构：角色越多，系统提示词被重复计费的次数越多。如果你的角色提示词每段 300 token，5 次调用光系统提示词就是 1500 token 的固定开销，跟任务复杂度无关。

关于 MCP：如果你在课程基础上接了自己的工具层，让工具层只做只读查询和参数校验。涉及数据库的 SQL 语句一律由你在本地客户端手工执行并核对结果，不要让 Agent 拿着高权限连接直接打到生产库上，这既是安全边界，也是防止误删的底线。

7. Token 消耗观测与报错定位顺序

统一入口之后，排障顺序可以固定成一条线，从下往上查：

几个提高可观测性的实践：

给每次调用打标签。在chat()里加一个tag参数，把rag/planner/writer这些来源记下来，用量按来源分组统计。这样你一眼就能看出成本是在检索侧还是协作侧。

限制上下文膨胀。RAG 的top_k不是越大越好。多取一段带来的边际信息量，往往小于它带来的输入 token 增量。先把top_k从 4 调到 3 跑一轮，对比答案质量有没有明显下降。

截断协作轮数。给多智能体流水线设一个最大轮数上限，超过就强制收尾。没有上限的"审阅→修改→再审阅"循环是费用失控最常见的来源。

区分调试与正式调用。调试阶段用轻量模型跑通链路，确认逻辑无问题后再切到主力模型。两个模型 ID 分别放在TAOTOKEN_MODEL和TAOTOKEN_SMALL_MODEL里，用环境变量切换，不改代码。

8. 小结与下一步

整篇文章其实只做了一件事：把散落在 RAG notebook、MCP 工具层、多智能体角色里的鉴权信息，收敛成一个 Key 加一个 Base URL。做完之后，你会得到三个可复用的东西：

1. 一份环境变量模板（TAOTOKEN_API_KEY/TAOTOKEN_BASE_URL/TAOTOKEN_MODEL）；
2. 一份 Python 公共模块（get_client+chat+usage_snapshot）；
3. 一条固定的排障路径（先 curl 验 Key，再看配置文件字段，最后看模型 ID 和用量分布）。

接下来按这条路径走一遍即可：

• 先在 https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat_entry 里做一次最小对话，确认 Key 和模型 ID 是可用的；
• 如果要长期跑批量任务，看 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan 里适合你调用强度的方案；
• 到 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=create_key 创建独立的 Key，给 CLI 和脚本分开用；
• 需要配置 Claude Code 的话，照着 https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code_final 把settings.json补全，然后用一次真实请求验证生效。

RAG 怎么召回、多智能体怎么分工，这些是你要在自己的代码里决定的事；而"用哪个地址、拿哪个 Key"这一类重复劳动，交给统一入口就够了。