Deep Agents 里用 Qwen3-MAX 报 401，先别急着怀疑模型，问题多半在 agent.py 那行 ChatOpenAI 的 base_url 和 api_key。把 base_url 指向https://taotoken.net/api，Key 从 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建，TaoToken 作为统一模型通道，能让 create_deep_agent 的 Qwen3-MAX 调用恢复正常。这个错在 Deep Agents 的 Text-to-SQL 项目里很典型：AGENT.md、skills/、SQLDatabaseToolkit 都配好了，模型却在第一次规划时抛认证失败，整条「查表结构→写 SQL→执行查询」链路还没开始就断了。下面按原文 agent.py 的结构，把 401 拆成可复制的排障步骤。
1. 先定位 401：agent.py 里 ChatOpenAI 还连着 DashScope
1.1 报错现场：create_deep_agent 第一次规划就认证失败
Deep Agents 的 401 通常不会在create_deep_agent()这一行当场抛出，而是等你调用agent.stream()或agent.invoke()时，LangChain 向模型发出第一条消息才报出来。错误信息大多长这样：AuthenticationError: Error code: 401 - invalid_api_key，或者带Incorrect API key provided字样。看到这个不要先去翻 AGENT.md，也不要怀疑 skills/ 目录没被扫描，先回到 agent.py 里看 ChatOpenAI 实例。
原文的模型配置是这样的：
model = ChatOpenAI( base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", api_key=os.getenv("DASHSCOPE_API_KEY"), model="qwen3-max", temperature=0, )这段代码走的是 DashScope 的 OpenAI 兼容模式。只要DASHSCOPE_API_KEY没写进 .env、Key 被停用、复制时带了空格换行，或者 base_url 被改成了别的路径，运行时就会在模型调用处 401。Deep Agents 的规划器、文件系统中间件、子 Agent 调度都还没拿到模型返回，流程自然卡死。
1.2 只改模型入口，不动 AGENT.md、skills/ 和 SQLDatabaseToolkit
排障最怕把问题面扩大。Deep Agents 的 Text-to-SQL 项目里，真正和认证相关的只有 ChatOpenAI 这一个对象；AGENT.md管角色和安全约束，skills/query-writing/SKILL.md与skills/schema-exploration/SKILL.md管技能声明，SQLDatabaseToolkit管数据库工具，它们都不负责模型鉴权。你把 ChatOpenAI 的base_url和api_key换掉，后面create_deep_agent(model=model, memory=["./AGENT.md"], skills=["./skills/"], tools=sql_tools)的参数可以原样保留。这样排障范围就收窄成三行：base_url、api_key、model。
注意：如果 401 发生在
create_deep_agent()之前，比如单独 import 时就报错，那多半是环境变量没加载，或者.env文件不在当前工作目录。先确认load_dotenv()读到了你的配置。
2. 把 Qwen3-MAX 的入口切到 TaoToken：改 .env 和 ChatOpenAI
2.1 去官网创建 YOUR_API_KEY，写进 .env
先打开 TaoToken 官网，注册并进入控制台，创建一个 API Key。这个 Key 在本文里统一写成占位符YOUR_API_KEY，你不要把它提交到 Git，也不要写进代码字符串。拿到 Key 之后，在 Deep Agents 项目根目录的 .env 里加三行：
TAOTOKEN_API_KEY=YOUR_API_KEY TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=qwen3-maxTAOTOKEN_BASE_URL只写https://taotoken.net/api，末尾不要加/v1。官网落地页和接口 Base URL 是两件事：注册、建 Key、查模型广场、看用量去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end ；填进 ChatOpenAI 的地址是https://taotoken.net/api。把这两个地址混用，是后面 404 和路径错误的常见来源。
模型 ID 这一行先写qwen3-max只是为了对齐原文示例，实际用哪个 ID 要以模型广场当时列表为准。如果模型广场给出的名称带版本后缀，就照着复制，不要自己拼日期。
2.2 ChatOpenAI 的 base_url 写成 https://taotoken.net/api
改完 .env，回到 agent.py，把模型实例替换成下面这段。数据库连接部分仍然按原文的 MySQL 写法保留，只动 ChatOpenAI 这一块：
import os from dotenv import load_dotenv from deepagents import create_deep_agent from deepagents.backends import FilesystemBackend from langchain_openai import ChatOpenAI from langchain_community.agent_toolkits import SQLDatabaseToolkit from langchain_community.utilities import SQLDatabase load_dotenv() def create_sql_deep_agent(): base_dir = os.path.dirname(os.path.abspath(__file__)) db_host = os.getenv("DB_HOST", "127.0.0.1") db_port = os.getenv("DB_PORT", "3306") db_user = os.getenv("DB_USER") db_pwd = os.getenv("DB_PASSWORD") db_name = os.getenv("DB_NAME") mysql_uri = ( f"mysql+pymysql://{db_user}:{db_pwd}@{db_host}:{db_port}/{db_name}" "?charset=utf8mb4" ) db = SQLDatabase.from_uri( database_uri=mysql_uri, sample_rows_in_table_info=3, include_tables=["user", "orders"], ) model = ChatOpenAI( base_url=os.getenv("TAOTOKEN_BASE_URL", "https://taotoken.net/api"), api_key=os.getenv("TAOTOKEN_API_KEY"), model=os.getenv("TAOTOKEN_MODEL", "qwen3-max"), temperature=0, ) toolkit = SQLDatabaseToolkit(db=db, llm=model) sql_tools = toolkit.get_tools() agent = create_deep_agent( model=model, memory=["./AGENT.md"], skills=["./skills/"], tools=sql_tools, subagents=[], backend=FilesystemBackend(root_dir=base_dir, virtual_mode=False), ) return agent agent = create_sql_deep_agent() if __name__ == "__main__": with open("./graph.png", "wb") as f: f.write(agent.get_graph().draw_mermaid_png()) print("智能体架构图已生成 graph.png") user_input = {"messages": [{"role": "user", "content": "本地测试库里有多少条订单"}]} for step in agent.stream(user_input, stream_mode="values"): step["messages"][-1].pretty_print()这里最容易改错的是base_url。它必须是https://taotoken.net/api，不能写成https://taotoken.net/api/v1，也不能把官网的 UTM 参数带进去。api_key读的是.env里的TAOTOKEN_API_KEY，不是原来的DASHSCOPE_API_KEY。如果你还在用原文的os.getenv("DASHSCOPE_API_KEY")，就算 .env 里已经放了新 Key，运行时照样 401。
2.3 重跑 create_deep_agent 前，先单独验证模型实例
不要一上来就跑完整 Deep Agents 流程。先写一个最小脚本，只测 ChatOpenAI 能不能通。这样能把「模型鉴权」和「Deep Agents 调度」分开：
import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() llm = ChatOpenAI( base_url="https://taotoken.net/api", api_key=os.getenv("TAOTOKEN_API_KEY"), model=os.getenv("TAOTOKEN_MODEL", "qwen3-max"), temperature=0, ) print(llm.invoke("只回复 ok").content)这段跑通，说明 Key、Base URL、模型 ID 三件事至少已经对上了。如果这里仍然 401，先别去改create_deep_agent的参数，回头检查 .env 的加载路径和 Key 本身。最小脚本能省掉大量在 Deep Agents 中间件里绕圈的时间。
3. AGENT.md 与 skills/ 不用重写，Deep Agents 调度链路保持原样
3.1 memory=["./AGENT.md"] 和 skills=["./skills/"] 的加载顺序不变
原文的 Deep Agents 项目结构里，AGENT.md放在根目录，skills/query-writing/SKILL.md和skills/schema-exploration/SKILL.md各管一个技能。create_deep_agent()传入memory=["./AGENT.md"]和skills=["./skills/"]后，框架会自动读取全局角色说明，再扫描技能目录。你把模型通道切到 TaoToken，这些文件一个字都不用动。AGENT.md 里写的「先探查表结构→再生成 SQL→执行只读查询」仍然有效，skills/ 下的安全规则也照常注入。
真正变化的是模型请求的出口：以前 Qwen3-MAX 的请求发往 DashScope 兼容地址，现在发往https://taotoken.net/api。Deep Agents 看到的仍然是一个 LangChain ChatModel，规划器、Todo 中间件、技能调度器不需要知道底层通道换了。
3.2 SQLDatabaseToolkit 四个工具仍由 Qwen3-MAX 驱动
SQLDatabaseToolkit(db=db, llm=model)会生成四个常用工具：sql_db_list_tables、sql_db_schema、sql_db_query、sql_db_query_checker。它们依赖model做 SQL 生成和检查，但工具本身不关心模型走哪个 Base URL。你换掉 ChatOpenAI 的地址后，create_deep_agent(tools=sql_tools)这一行不变，四个工具照常注册给技能调用。
需要留意的是，工具执行 SQL 的能力要和真实环境匹配。本地开发可以连接本地 MySQL 或测试库；生产库不要直接交给 Agent 执行查询。更稳的做法是只给一个只读账号，并用include_tables限定可访问表。这样即使模型生成了越界 SQL，工具层也会把它限制在白名单内。
3.3 只读安全：生产库别给 Agent 写权限，诊断 SQL 本地执行
原文 AGENT.md 里已经写了禁止 INSERT、UPDATE、DELETE、DROP、ALTER、TRUNCATE，这个约束不要删。切换 Base URL 只解决认证问题，不改变权限模型。SQLDatabase.from_uri()连接的账号最好是只读账号，include_tables只列业务允许查询的表。不要把生产库的写权限账号放进 .env。
如果你要排查 SQL 本身的问题，比如执行计划、索引命中、锁等待，正确做法是让 Deep Agents 生成或解释 SQL，然后你自己在本地 MySQL 客户端或只读副本上执行EXPLAIN、SHOW INDEX，把输出贴回对话让模型分析。不要让 Agent 直接连生产库执行诊断语句，也不要把 DDL、DML 交给它跑。模型通道解决的是请求认证，不是数据库权限。
4. 验证 Qwen3-MAX 不再 401：从 python agent.py 到模型对话
4.1 运行 python agent.py，看第一条消息是否还报认证错误
配置保存后，在项目根目录执行python agent.py。如果前面的最小脚本已经跑通，这里通常不会再看到 401。你会先看到graph.png生成，然后agent.stream()逐条打印消息。观察第一条模型消息是否返回，以及有没有继续调用sql_db_list_tables或sql_db_schema。如果仍然停在认证错误，错误栈里会明确写AuthenticationError，那就回到第 2 节的 .env 和 ChatOpenAI 参数重新对。
另一个容易忽略的点是启动目录。load_dotenv()默认从当前工作目录找 .env。如果你在上一级目录执行python deepagents_sql/agent.py，而 .env 在deepagents_sql/里面，它可能读不到。此时可以用load_dotenv(dotenv_path=os.path.join(base_dir, ".env"))，或者先cd到项目根目录再运行。
4.2 用同一把 Key 在模型对话里核对模型 ID
跑通 agent.py 之后，建议用同一把 Key 去 TaoToken 模型对话 发一条测试消息。这一步的目的不是替代 Deep Agents，而是确认模型 ID 在模型广场当时列表里确实可用，并且这把 Key 有权限调用它。模型广场里展示的名称就是你应该写进TAOTOKEN_MODEL的值；如果列表里没有qwen3-max这个写法，就换成实际展示的 ID，不要自己加日期后缀。
对话里返回正常，但 agent.py 里仍然报模型不存在，通常是 .env 没被读取，或者TAOTOKEN_MODEL被别的环境变量覆盖了。用python -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv('TAOTOKEN_MODEL'))"可以打印当前进程实际读到的值。
4.3 去控制台看这次调用是否记上账
验证的最后一步是打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end ，进入控制台看用量记录。如果刚才的llm.invoke和agent.stream都成功返回，但控制台没有对应调用，先检查 Key 是否复制完整，以及请求是否真的发到了https://taotoken.net/api。控制台还能帮你确认当前 Key 的可用模型范围，避免把「模型不可用」误判成「Base URL 写错」。
提示：排障时不要同时改 Key、Base URL、模型 ID 和数据库连接串。一次只动一个变量，才能知道是哪一个修复了 401。
5. 改完还报错的几种情况：401、404、模型 ID、环境变量
5.1 仍然 401：旧 Key、空格、.env 没加载
如果最小脚本仍然 401，按这个顺序查：第一，.env里是否还是DASHSCOPE_API_KEY，而代码已经改成TAOTOKEN_API_KEY；第二，YOUR_API_KEY有没有被真实 Key 替换，复制时有没有把空格、换行、引号带进去；第三，load_dotenv()是否在os.getenv()之前执行；第四，终端里是否已经存在同名的旧环境变量。把 Key 打印出来对长度是土办法，但比重启十次 IDE 有效。
还有一种情况是 Key 被删除或轮换过。控制台里重新创建一个，替换 .env 后再跑最小脚本。不要用已经暴露在聊天记录或截图里的 Key。
5.2 404 或路径错误：base_url 多了 /v1
401 是认证失败，404 一般是路径不对。ChatOpenAI 的base_url应该写https://taotoken.net/api，末尾不要加/v1。如果你写成https://taotoken.net/api/v1或者多了一个斜杠，请求路径会拼错，表现可能是 404，也可能是模型返回空。检查方式很简单：在代码里打印model.openai_api_base，确认它和 .env 里的值一致。官网链接带 UTM，但 Base URL 不能带 UTM，也不能带/v1。
5.3 模型不可用：模型 ID 以模型广场当时列表为准
qwen3-max是原文里的写法，本文沿用它只是为了对齐排障场景。实际配置时，打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 看模型广场当时列表，复制可用 ID 到TAOTOKEN_MODEL。如果模型广场显示的是另一个名称，而代码里硬编码了qwen3-max，可能会收到模型不存在或无权限的错误。这类错误不一定是 401，但会表现成调用失败，容易和认证问题混在一起。把模型 ID 收敛到 .env 一个变量里，后面切换最省事。
5.4 SQL 工具报权限错：只读账号和 include_tables
模型通道通了之后，下一个可能遇到的错来自数据库。sql_db_query执行失败时，先看 MySQL 账号有没有对应表的 SELECT 权限，再看include_tables是否把表排除掉了。原文的sample_rows_in_table_info=3只是给模型看样本行，不等于放开全表权限。生产环境建议只读副本或本地测试库，诊断 SQL 由你在本地执行，把报错原文贴回对话让模型解释。不要把写权限账号写进 .env，也不要让 Agent 执行CREATE、ALTER这类语句。
6. 把这次排障固化下来：Deep Agents 项目的 .env 模板与下一步
6.1 一份可复制的 .env 模板
把这次改动用 .env 固化，下次换模型或换 Key 不需要翻 agent.py：
TAOTOKEN_API_KEY=YOUR_API_KEY TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=qwen3-max DB_HOST=127.0.0.1 DB_PORT=3306 DB_USER=readonly_user DB_PASSWORD=your_db_password DB_NAME=your_db_nameKey 从 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建，Base URL 保持https://taotoken.net/api，不要加/v1。把 .env 加到 .gitignore，不要提交到仓库。
6.2 下次换模型只改 TAOTOKEN_MODEL
Deep Agents 的项目里，模型实例被SQLDatabaseToolkit和create_deep_agent同时引用，如果每换一次模型就改 agent.py，很容易漏掉一处。现在 ChatOpenAI 的base_url、api_key、model都从环境变量读，换模型只需要改.env里的TAOTOKEN_MODEL，然后重启进程。新模型 ID 仍然以官网模型广场当时列表为准，复制准确名称，不要自己拼版本号。
6.3 跑通后去模型对话、Coding Plan、控制台
agent.py 已经指向https://taotoken.net/api之后，别急着把生产库接进去。先用同一把 Key 在 TaoToken 模型对话 发一条测试消息，确认 Qwen3-MAX 的模型 ID 和返回都正常；如果 Deep Agents 要长期跑长任务，可以打开 Coding Plan 看额度是否够用；Key 的创建和轮换在 控制台 API Keys。把这次 401 的 .env 模板留在项目里，下次换模型只动TAOTOKEN_MODEL，不再回头改 ChatOpenAI 的 base_url。
