1. VS Code 智能体自定义里 applyTo 与 YAML 配置为什么会撞上 401

你在 VS Code 里折腾 agent-customization，本来是想让智能体按项目规范干活：.instructions.md限定到某个目录、.agent.md定义专用工作流、copilot-instructions.md兜底全局偏好。结果文件都写好了，applyTo 也配了，一发起请求却弹 401。这个场景我见得太多了，问题往往不在 YAML 语法本身，而在「智能体自定义文件里声明的模型端点」和「实际发请求用的凭据」对不上。

先把概念捋清楚。agent-customization 是围绕 VS Code 智能体配置文件的一套工作流能力，覆盖.instructions.md、.prompt.md、.agent.md、SKILL.md、copilot-instructions.md、AGENTS.md这几类文件。它的价值在于：把编码偏好、领域知识、工具限制、生效范围（applyTo）沉淀成可复用配置，让智能体在指定文件或目录下才生效，避免跨项目串味。applyTo 就是那个「范围开关」，用 glob 模式限定指令作用域，比如applyTo: "src/api/**/*.ts"。

那 401 从哪来？401 是「未认证」，翻译成人话就是：请求发出去了，但服务端不认你的身份。在 VS Code 智能体自定义场景里，常见触发链条是这样的——你在配置文件或 settings 里指定了自定义模型端点（比如把默认端点换成了自建或第三方兼容端点），但 Key 没同步更新、endpoint 路径写错、或者环境变量没被读到。YAML frontmatter 里如果混入了模型相关字段，而 applyTo 又把这份配置限定到了某个子目录，就会出现「只有在这个目录下触发智能体时才 401」的诡异现象，因为别的目录走的是另一套配置。

我实测下来，最容易踩的坑是「改了 endpoint 没改 Key」和「Key 写在了错误的层级」。VS Code 的模型配置可能分散在用户 settings、工作区 settings、以及智能体自定义文件的 frontmatter 里，三者优先级和读取时机不同。你以为改了一处，实际生效的是另一处。所以排查 401 的核心思路不是「重写配置」，而是「逐项核对 endpoint 与 Key 的对应关系」，把请求真正用到的凭据找出来。

这篇就按这个思路走：先讲清楚问题场景和 applyTo/YAML 的坑位，再给出可复制的 settings 片段，然后一步步验证请求、确认报错消失，最后把常见报错对照表列出来。适合正在用 VS Code 智能体自定义、被 401 卡住、想快速定位而不是盲目重装的人。核心检索词就三个：agent-customization、applyTo、YAML 配置 401 排查。

2. 接入前的准备：TaoToken 端点与 Key 的对应关系

在动手改配置之前，得先把「请求到底发给谁、用什么身份」这件事定下来。VS Code 智能体自定义本身不生产模型能力，它只是把配置和请求组织起来，真正响应的是你配置的模型服务端点。所以 401 排查的第一步，是确认你的端点地址和 Key 是配套的。

这里我用 TaoToken 作为示例端点来演示，因为它的接入方式对 VS Code 这类工具比较友好，Base URL 和 Key 的对应关系清晰，便于逐项核对。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （这个地址不加 UTM 参数，配置时直接用）。

你需要准备两样东西：Base URL 和 API Key。Base URL 就是上面那个https://taotoken.net/api，注意它通常需要配合具体的路径后缀使用，比如对话补全的路径。API Key 则要去控制台生成，入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，生成后复制保存，它只显示一次。如果你还没生成，先去 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 创建。

关键点来了：Base URL 和 Key 必须来自同一个账号、同一套环境。401 的高发原因就是「endpoint 指向 A 服务，Key 却是 B 服务的」。在 VS Code 智能体自定义里，这个错配可能藏在三个地方：用户级 settings.json、工作区级.vscode/settings.json、以及智能体自定义文件的 YAML frontmatter。applyTo 决定哪些文件触发这份配置，但不决定用哪个 Key——Key 的来源是 settings 或环境变量。

所以准备阶段要做的事很具体：打开你的 VS Code，找到当前生效的 settings 文件，把里面所有跟模型端点、API Key 相关的字段列出来，逐个标注来源。同时确认你的 Key 没有多余空格、没有换行、没有把Bearer前缀重复写进去。这些细节看着小，但 401 里相当一部分就是它们造成的。

另外提醒一句，智能体自定义文件里的 YAML frontmatter 主要用于声明 applyTo、description、tools 这类元数据，不建议把 API Key 直接写进 frontmatter。Key 应该放在 settings 或环境变量里，frontmatter 只负责「这份指令在哪些文件生效」。把 Key 写进 frontmatter 不仅容易泄露，还会因为读取时机问题导致 401——智能体加载 frontmatter 时可能还没读到 Key，请求就发出去了。

准备清单可以这样记：Base URL 一个（https://taotoken.net/api）、API Key 一个（控制台生成）、settings 文件位置确认、环境变量确认（如果用了的话）。这四样对齐了，再进配置环节，401 的排查范围就缩小了一大半。

3. 可复制的 settings 与 YAML 配置片段

这一节直接给可复制的片段，路径和字段名保持和 VS Code 实际读取的一致。你按自己的环境替换 Key 即可。

先看用户级或工作区级的settings.json。VS Code 里跟模型端点相关的配置，通常放在settings.json的顶层。下面是一个可复制的片段，注意 JSON 不能有注释，我这里用引用块单独说明每个字段：

{ "github.copilot.chat.customOAIModel": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "modelId": "claude-3-5-sonnet" } }

注意：baseUrl填https://taotoken.net/api，不要在后面多加斜杠或/v1，具体路径由客户端拼接。apiKey填控制台生成的完整 Key。modelId填你要用的模型 ID，这个 ID 要和端点支持的模型一致，写错模型 ID 有时也会返回 401 或 404，别混淆。

如果你用的是环境变量方式，settings 里可以只写引用，Key 放系统环境变量：

{ "github.copilot.chat.customOAIModel": { "baseUrl": "https://taotoken.net/api", "apiKey": "${env:TAOTOKEN_API_KEY}", "modelId": "claude-3-5-sonnet" } }

然后在系统里设置TAOTOKEN_API_KEY。这种方式的好处是 Key 不进版本库，团队协作时每人配自己的。坏处是环境变量没生效时，${env:...}会解析成空字符串，直接 401。所以用这种方式，排查时要先确认环境变量真的被 VS Code 读到了——重启 VS Code 是常见动作，因为环境变量在进程启动时读取。

再看智能体自定义文件的 YAML frontmatter。以.instructions.md为例，applyTo 的写法：

--- applyTo: "src/api/**/*.ts" description: "API 层编码规范，限定在 src/api 目录下的 TypeScript 文件生效" ---

.agent.md的 frontmatter 可能还包含 tools 限制：

--- applyTo: "src/**/*.ts" description: "前端智能体，限定 src 目录" tools: - read_file - write_file ---

注意：frontmatter 里不要写apiKey、baseUrl这类字段。它们不属于智能体自定义的元数据规范，写了也不会被正确读取，反而可能干扰解析。Key 和端点统一放 settings。

如果你用的是 Codex 风格的auth.json，它的结构是这样的，路径通常在用户目录下的.codex/auth.json：

{ "OPENAI_API_KEY": "sk-你的Key", "OPENAI_BASE_URL": "https://taotoken.net/api" }

这三件套——Base URL、Key、Model ID——在任何一种配置方式里都要对齐。Base URL 是https://taotoken.net/api，Key 是控制台生成的，Model ID 是端点支持的模型名。三者缺一或错配，401 就来了。

配置改完后，别急着测。先做一件事：确认你改的是「实际生效」的那个文件。VS Code 的 settings 有用户级和工作区级，工作区级优先。如果你在用户级改了，但工作区级有覆盖，那改了个寂寞。用命令面板打开「Preferences: Open User Settings (JSON)」和「Preferences: Open Workspace Settings (JSON)」分别看一眼，确认没有冲突。

4. 验证请求：从复现 401 到确认报错消失

配置改完，接下来是验证。验证的目标很明确：先复现 401，再确认它消失。这样你才知道自己改对了地方，而不是碰巧。

第一步，复现。在改配置之前，先触发一次智能体请求，把 401 的完整报错记下来。触发方式取决于你的场景：可以在 applyTo 限定的目录下打开一个文件，让智能体补全或对话；也可以直接调用一次模型对话。报错信息里通常包含状态码 401 和一段 message，比如401 Unauthorized或invalid api key。把这段原文记下来，后面排查要用。

第二步，核对 endpoint。打开你的 settings 文件，确认baseUrl是https://taotoken.net/api。这里有个细节：有些客户端会自动在 baseUrl 后面拼/v1/chat/completions，有些不会。如果你在 baseUrl 里已经写了/v1，客户端再拼一次就变成/v1/v1/...，路径错了可能返回 404，也可能因为路由问题返回 401。所以 baseUrl 保持干净，只写https://taotoken.net/api。

第三步，核对 Key。把 settings 里的 Key 复制出来，和 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 里显示的做对比。注意 Key 通常以sk-开头，复制时容易带上首尾空格。可以用一个简单方法验证 Key 本身是否有效：用 curl 直接打一次对话接口。

curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-5-sonnet", "messages": [{"role": "user", "content": "ping"}] }'

如果这条命令返回正常响应，说明 Key 和 endpoint 本身没问题，401 出在 VS Code 的配置读取环节。如果这条命令也 401，那问题就在 Key 或 endpoint 本身，跟 applyTo、YAML 无关。这一步能把问题范围一刀切开，非常有用。

第四步，回到 VS Code 重新触发请求。如果 curl 通了但 VS Code 还 401，重点查三件事：settings 文件是不是生效的那个、环境变量有没有被读到、frontmatter 有没有混入非法字段。改完 settings 后，建议重启 VS Code，因为部分配置在启动时加载。

第五步，确认报错消失。重新在 applyTo 限定的目录下触发智能体，观察是否还有 401。如果变成正常响应，说明修好了。如果报错变了，比如从 401 变成 404 或 400，那是另一个问题，但至少认证过了。把新的报错记下来，对照下一节的排查表。

验证模型是否正常工作，也可以直接在模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 里发一条消息，确认账号和 Key 状态正常。这一步能排除「Key 被禁用或额度耗尽」这类账号级问题。

整个验证流程的核心是「隔离变量」：先用 curl 隔离出 Key/endpoint 问题，再用 VS Code 隔离出配置读取问题。不要一上来就重写所有配置，那样你永远不知道是哪一处修好的。

5. 本篇常见报错对照与排查路径

这一节把真实会遇到的报错列出来，对照着查。每个报错都给出可能原因和动作。

401 Unauthorized / invalid api key：最常见。原因通常是 Key 错配、Key 带空格、Key 已失效、或 endpoint 和 Key 不属于同一服务。动作：用第 4 节的 curl 命令直接验证 Key；确认 settings 里的 baseUrl 是https://taotoken.net/api；确认 Key 从 API Keys 页面复制且无首尾空格。

local proxy failed / connection refused：这个报错说明请求根本没发到远端，卡在本地。常见于配置了本地代理端口但代理没启动，或者 baseUrl 写成了localhost。动作：检查 settings 里有没有残留的本地代理配置；确认 baseUrl 是远端地址而不是本地地址；如果你之前配过代理，把它清掉再试。

reading 'choices' / cannot read properties of undefined：这个报错通常出现在响应解析阶段，说明请求发出去了但返回结构不符合预期。常见原因是 endpoint 路径拼错，返回了 HTML 错误页而不是 JSON，客户端去读choices字段就报错。动作：确认 baseUrl 没有多余路径；用 curl 看返回的原始内容是不是 JSON；检查 modelId 是否是端点支持的模型。

OAuth / token expired：如果你用的是 OAuth 方式而不是 API Key，报错会指向 token 过期。动作：重新走一遍授权流程；或者干脆切换到 API Key 方式，更直接。在 VS Code 智能体自定义场景里，API Key 方式比 OAuth 更容易排查，因为 Key 是静态的，不会过期。

applyTo 不生效 / 指令被忽略：这个不是 401，但常和 401 一起出现。原因是 applyTo 的 glob 模式没匹配到目标文件，或者 frontmatter 语法错误导致整份配置没被加载。动作：检查 applyTo 的路径模式，src/api/**/*.ts匹配src/api下所有层级的 ts 文件；确认 frontmatter 的---闭合正确；YAML 缩进用空格不用 Tab。

YAML frontmatter 解析失败：报错可能不直接说 YAML，而是说配置加载失败。常见原因是冒号后没空格、字符串没加引号、缩进不一致。动作：把 frontmatter 贴到 YAML 校验工具里过一遍；applyTo 的值建议用引号包起来，避免特殊字符问题。

排查顺序建议这样：先看报错原文，判断是认证类（401/OAuth）还是连接类（proxy/refused）还是解析类（choices/YAML）。认证类走 Key/endpoint 核对，连接类走 baseUrl/代理检查，解析类走路径/模型 ID 检查。不要跳步，一层层隔离。

如果你在排查过程中需要更完整的接入说明，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有各客户端的配置示例。长期做编码和 Agent 场景的话，Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 有更细的说明。

6. 把配置沉淀成可复用的智能体自定义文件

401 修好之后，别急着关掉。把这次排查的结论沉淀下来，下次换项目或换同事接手时能省很多时间。具体做法是：把「端点 + Key 引用 + 模型 ID」这套配置从散落的 settings 里抽出来，形成一份可复用的智能体自定义文件。

比如建一个.agent.md，用 applyTo 限定到需要自定义模型的项目目录，frontmatter 里只写元数据，Key 通过环境变量引用。这样团队成员拉下代码后，只需要配一次环境变量，不用改任何文件。applyTo 的 glob 模式按项目结构调整，比如applyTo: "packages/**/*.ts"覆盖 monorepo 里的所有包。

再比如把常见的编码规范写进.instructions.md，applyTo 限定到对应目录。这样智能体在写这个目录的代码时，会自动带上规范，不需要每次手动提示。YAML frontmatter 保持干净，只放 applyTo 和 description，不放任何凭据。

如果你用的是 Claude Code 这类工具，配置方式类似，Base URL 填https://taotoken.net/api，Key 用控制台生成的，Model ID 按需选。三件套对齐的原则不变。Claude Code 的接入说明在 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，有需要可以对照。

最后说个实用技巧：把 curl 验证命令存成一个脚本，比如check-key.sh，每次改完配置先跑一遍。脚本里只放 endpoint 和 Key 的引用，不硬编码。这样 401 一出现，先跑脚本，三秒定位是 Key 问题还是配置问题。这个习惯比任何排查文档都管用。

配置这东西，写对了是资产，写错了是负债。applyTo 和 YAML 本身不复杂，复杂的是它们和凭据、环境、优先级的交互。把交互关系理清楚，401 就不再是玄学。