1. 命令行里到底有哪些 agents 可以调用
很多人第一次接触 Claude Code 的 agents 概念时，会以为它像插件市场一样有个可视化列表，点开就能看到全部。实际不是。Claude Code 的 agents 分两层：一层是内置的通用 agent，另一层是你自己或团队在项目里定义的 subagents。它们平时藏在配置目录和命令行输出里，不主动查就看不见。
先说清楚这几个词的关系，不然后面排查会绕晕。Claude Code是命令行工具本体；agents是它能调用的执行单元，可以理解成"带独立上下文的小助手"；subagents是 agents 的子集，通常由主 agent 在任务里派生出来，用来并行处理子任务，比如一个负责读代码、一个负责查文档。你问"有哪些 agents"，本质是在问：当前这个项目、这套配置下，Claude Code 能识别到哪些可用的执行单元。
为什么这件事值得单独写一篇？因为当出现 401、local proxy failed、reading choices 这类报错时，新手第一反应是"网络挂了"或"Key 错了"，但真实原因经常是 agent 配置缺失或 endpoint 指错，导致列表根本没加载出来。分不清是认证问题还是 agent 配置问题，就会在错误的方向上反复折腾。
这篇适合三类人：刚装好 Claude Code 想确认 agents 是否正常加载的；遇到报错想快速定位是认证还是配置的；以及想把 endpoint 统一到 TaoToken 后验证 agents 列表是否正常返回的。全程命令行操作，复制即可跟做。
核心检索词先记住：Claude Code 查看 agents 列表、subagents 命令行排查、401 与 local proxy failed 定位。下面从最直接的查看命令开始，一步步把配置和验证串起来。
2. 用 TaoToken 统一 Key 前的准备与 endpoint 认知
在动手查 agents 之前，得先理解 Claude Code 是怎么找到"有哪些 agents"的。它主要看两个地方：一是内置 agent 定义，随工具版本走；二是项目级和用户级的配置文件，里面用 JSON 或 TOML 声明了自定义 subagents。命令行执行查看命令时，工具会把这些来源合并后输出。
那 TaoToken 在这里扮演什么角色？它是一个统一的模型接入层，把不同模型的调用收敛到同一个 endpoint 和同一把 Key 上。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。对 Claude Code 来说，你只需要把它的请求地址指向这个 endpoint，再用一把 Key 认证，agents 列表的加载和后续调用就走同一条通道。
这里有个关键认知：agents 列表能不能正常返回，和认证是否通过是两件事，但经常同时出问题。如果 endpoint 写错，请求发不出去，你会看到 local proxy failed 或连接类错误；如果 endpoint 对了但 Key 无效，会看到 401；如果认证过了但 agent 配置文件格式错了，列表会缺项或报 reading choices 相关错误。所以排查顺序应该是：先确认 endpoint 通不通，再确认 Key 对不对，最后确认 agent 配置全不全。
准备阶段你需要三样东西：一把 TaoToken 的 API Key（在控制台创建，地址 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ），一个确认可用的模型 ID，以及 Claude Code 的配置文件路径。Key 的创建入口在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
注意：不要把 Key 硬编码进会提交到 Git 的文件里。用环境变量或本地未跟踪的配置文件，这是后面所有步骤的前提。
模型 ID 这块，Claude Code 场景下常用的是 Anthropic 系列模型标识，具体以你控制台里可用的为准。TaoToken 的模型对话入口在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，可以先在那里确认模型名再填进配置。如果你打算长期跑编码和 Agent 任务，Coding Plan 入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合高频调用场景。
把这三样准备好，下一步就是写配置。配置写对了，agents 列表才有机会正常返回；配置写错，后面所有查看命令都会以各种报错收场。
3. 可复制的配置片段与 agents 查看命令
这一节是全文最需要动手的部分。先给配置，再给查看命令，顺序不要颠倒，因为查看命令依赖配置生效。
Claude Code 的配置通常放在用户目录下的.claude文件夹里，项目级配置放在项目根目录的.claude下。下面是一个可复制的 settings 片段，把 endpoint 指向 TaoToken，并声明一个自定义 subagent。路径按你实际环境调整，这里以用户级配置为例：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥" }, "agents": { "code-reader": { "description": "负责阅读和总结代码文件", "model": "claude-sonnet-4-20250514", "prompt": "你是一个代码阅读助手，专注解释文件结构和依赖关系。" }, "doc-searcher": { "description": "负责检索项目文档", "model": "claude-sonnet-4-20250514", "prompt": "你是一个文档检索助手，返回最相关的文档片段。" } } }如果你用的是 TOML 风格的配置（部分版本或团队约定会这样写），等价片段如下：
[env] ANTHROPIC_BASE_URL = "https://taotoken.net/api" ANTHROPIC_API_KEY = "sk-你的TaoToken密钥" [agents.code-reader] description = "负责阅读和总结代码文件" model = "claude-sonnet-4-20250514" prompt = "你是一个代码阅读助手，专注解释文件结构和依赖关系。" [agents.doc-searcher] description = "负责检索项目文档" model = "claude-sonnet-4-20250514" prompt = "你是一个文档检索助手，返回最相关的文档片段。"配置里三个要素必须齐全，缺一不可：Base URL指向https://taotoken.net/api，Key用你的 TaoToken 密钥，Model ID填控制台确认过的模型名。这三件套是后面所有验证的基础。
配置写好后，查看 agents 有两种方式。第一种是在 Claude Code 交互式命令行里直接输入斜杠命令：
/agents它会列出当前识别到的全部 agents，包括内置的和你在配置里声明的。第二种是在系统 shell 里直接调用：
claude agents这条命令不进入交互模式，适合脚本化检查。实测下来，claude agents的输出更干净，适合贴进排查记录。
查看 subagents 稍微不同。subagent 是在任务执行时动态派生的，不会一直挂在列表里。调用 subagent 时，Claude Code 会创建新实例并返回一个 agent id，历史记录落在 transcript 文件里。路径形如：
/Users/你的用户名/.claude/projects/{projectdir}/20ed7031-28fb-4b23-9f6d-aa02c33a8b9a/subagents你可以直接进这个目录看有哪些 subagent 跑过：
ls -la ~/.claude/projects/*/*/subagents每个子目录对应一次 subagent 调用记录。想确认某个 subagent 的完整行为，读它目录下的 transcript 文件即可。这里要理解一个设计：subagent 之间不直接通信，它们通过共享文件和父级协调间接协作。所以你在列表里看不到"A 和 B 在对话"，只能看到各自的 transcript 和父级派生的 agent id。
把配置和命令都跑一遍，如果/agents能列出你声明的code-reader和doc-searcher，说明配置生效了。如果列不出来，先别急着改 Key，往下看验证和排障。
4. 验证请求与 agents 列表是否正常返回
配置写完不代表生效，得实际发一次请求验证。这一步的目标是确认三件事：endpoint 通、Key 有效、agents 列表能正常返回。
最直接的验证是跑一次最小调用。在 shell 里执行：
curl -s https://taotoken.net/api/v1/messages \ -H "x-api-key: sk-你的TaoToken密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 64, "messages": [{"role": "user", "content": "ping"}] }'如果返回里带content字段和正常文本，说明 endpoint 和 Key 都没问题。如果返回 401，是 Key 的问题；如果连接超时或报 local proxy failed，是 endpoint 或本地网络配置的问题。这一步把认证问题和网络问题彻底分开，后面排查就不会混。
认证通了之后，回到 Claude Code 里验证 agents 列表。先执行：
claude agents正常返回应该能看到你配置的 agent 名称和描述。如果这里报reading choices相关错误，通常是配置文件格式有问题，比如 JSON 少了逗号、TOML 段落写错，或者 model 字段填了不存在的模型名。把配置贴进任意 JSON/TOML 校验器过一遍，能快速定位。
再进交互模式跑一次：
claude进去后输入/agents，对比两次输出是否一致。一致说明配置在两种模式下都生效。然后触发一次 subagent 调用，比如让它读一个文件，再去看 transcript 目录：
ls -lt ~/.claude/projects/*/*/subagents | head能看到新生成的子目录和 agent id，说明 subagent 机制正常工作。整个链路就通了：endpoint 指向 TaoToken，Key 认证通过，agents 列表正常返回，subagent 调用留下记录。
提示：验证阶段建议用最小请求，别一上来就跑大任务。小请求返回快，出错信息也更干净，排查成本低。
如果这一步全部通过，你就有了一条可复用的验证流程。以后换 Key、换模型、加新 agent，都按这个顺序走一遍即可。
5. 常见报错排查：401、local proxy failed、reading choices
这一节对照真实报错逐个拆。每个报错都给出触发原因和对应动作，照着做基本能定位。
401 未授权。返回体里通常带authentication_error或invalid api key。原因有三种：Key 拼错、Key 已失效、Key 没带上。检查顺序是先确认环境变量ANTHROPIC_API_KEY的值和 TaoToken 控制台里的一致，再确认请求头里确实带了x-api-key。如果用的是配置文件里的env段，确认 Claude Code 读取的是你改的那个文件，而不是另一个路径下的旧配置。改完重启 Claude Code 再试。
local proxy failed。这个报错说明请求根本没发到 TaoToken，卡在本地代理或网络层。常见原因是ANTHROPIC_BASE_URL写成了本地地址，或者系统里残留了指向本地的代理设置。检查配置里的 Base URL 是不是https://taotoken.net/api，再检查 shell 里有没有HTTP_PROXY、HTTPS_PROXY之类的环境变量指向了不可用的地址。清掉这些变量再跑一次 curl 验证。
reading choices 相关错误。这类错误出现在解析响应或配置时，通常是 agent 配置的 model 字段填了不存在的模型 ID，或者 agents 段落结构不对。对照第 3 节的 JSON/TOML 片段逐字段核对，重点看 model 名是否和控制台一致、agents 下每个子项的description和prompt是否齐全。格式错误用校验器一跑就现形。
OAuth 相关报错。如果你之前用过 OAuth 方式登录，配置里可能残留了旧的认证字段，和新的 Key 认证冲突。把配置里跟 OAuth 有关的字段清掉，只保留 Base URL、Key、Model ID 三件套。三件套齐全且一致，是避免这类冲突的最简做法。
agents 列表为空。命令能跑但什么都不返回，说明配置没被加载。确认配置文件放在 Claude Code 会读取的路径下，用户级在~/.claude/，项目级在项目根目录的.claude/。放错位置等于没写。
把这几类报错和动作整理成对照表，排查时直接查：
| 报错 | 大概率原因 | 对应动作 |
|---|---|---|
| 401 | Key 错/失效/未带 | 核对 Key，确认请求头 |
| local proxy failed | Base URL 错或本地代理残留 | 改回 TaoToken endpoint，清代理变量 |
| reading choices | 配置格式或 model 名错 | 校验 JSON/TOML，核对模型 ID |
| OAuth 冲突 | 旧认证字段残留 | 只保留三件套 |
| 列表为空 | 配置文件路径错 | 放到正确目录 |
排查的核心逻辑始终是：先分认证和网络，再分配置和模型。分清楚层次，就不会在一个方向上死磕。
6. 把 agents 排查固化成日常习惯
跑通一次之后，建议把验证流程固化成几条命令，放进你的日常检查清单。每次换 Key、加 agent、升级 Claude Code 版本后，按顺序跑一遍：先 curl 最小请求确认认证，再claude agents确认列表，最后触发一次 subagent 调用确认 transcript 生成。三步都过，说明链路健康。
对于长期跑编码和 Agent 任务的场景，把 endpoint 统一到 TaoToken 后，Key 和模型管理都收敛到一处，排查时变量更少。需要看模型可用性去模型对话入口，需要建 Key 去 API Keys 页面，需要查接入细节去文档。Coding Plan 适合高频调用，Claude Code 相关的接入说明在文档里也有对应章节。
最后留一个实用习惯：把~/.claude/projects/*/*/subagents这个路径记下来，遇到 subagent 行为异常时，直接读 transcript 文件，比猜要快得多。agents 和 subagents 的排查，本质就是把配置、认证、记录三样东西对齐，对齐了，问题自然浮出来。
