1. 为什么 MySQL Shell for VS Code 会连不上

MySQL Shell for VS Code 是 Oracle 官方出的插件，把 MySQL Shell、数据库连接管理、SQL Notebook 都塞进了 VS Code 侧边栏。它的连接模型和普通 MySQL 客户端不太一样：插件本身不直接走 TCP 连数据库，而是先拉起一个本地 MySQL Shell 进程，再由这个进程去连目标 endpoint。所以一旦 endpoint 指向不对，报错往往不是「Access denied」这种直白的数据库错误，而是local proxy failed、401、reading choices这类看起来和数据库无关的提示。

我遇到这个问题的场景很典型：本地开发机想统一走一个 API 网关来管理模型调用和数据库相关请求，于是把插件里的 endpoint 从默认的localhost:3306改成了一个统一通道地址。改完之后插件就再也连不上了，侧边栏一直转圈，输出面板里刷local proxy failed。排查了半天才发现，问题不在数据库本身，而在插件的连接配置层——它把 endpoint 当成了 MySQL Shell 的--uri参数直接透传，而统一通道的地址格式和原生 MySQL URI 并不完全兼容。

这里要先说清楚一件事：MySQL Shell for VS Code 插件连不上，绝大多数情况是三类原因。第一类是 endpoint 地址写错，比如协议头、端口、路径拼错；第二类是认证信息没对上，Key 或 token 放错位置，触发 401；第三类是本地代理进程启动失败，插件拉不起 MySQL Shell 子进程，报local proxy failed。这三类的排查路径完全不同，混在一起查会浪费很多时间。

适合读这篇的人：正在用 VS Code 做数据库开发、已经把插件装好但连不上、或者想把数据库相关请求统一收敛到一个通道地址的开发者。如果你还没装插件，也可以先看后面的配置片段，照着填就能跑通。整篇的排查思路是「先确认 endpoint 改对了没有，再确认认证信息对不对，最后看本地进程有没有起来」，按这个顺序走，基本能覆盖 90% 的报错。

需要提前说明的是，TaoToken 在这里扮演的是统一通道的角色，它提供兼容 OpenAI 风格的 API 入口，插件侧只需要把 Base URL 指过去、把 Key 填对，请求就会走统一通道。下面所有配置都以这个为前提展开。

2. TaoToken 前置准备：拿到 Base URL 和 Key

在改插件配置之前，得先把两样东西准备好：Base URL 和 API Key。这两样东西决定了插件往哪里发请求、用什么身份发请求。很多人连不上就是因为这一步没做扎实，Key 复制多了空格、Base URL 少了/v1，都会导致后面 401 或者 404。

Base URL 的格式是https://taotoken.net/api，注意这里不带任何多余路径。有些教程会让你填https://taotoken.net/api/v1，但插件内部会自己拼/v1/chat/completions这类路径，你多填一层反而会变成/api/v1/v1/...，直接 404。所以记住：Base URL 就填到/api为止。

API Key 的获取路径是登录后在控制台里创建。具体操作是打开https://taotoken.net/api-keys，点创建新 Key，复制出来的一长串就是。这个 Key 只显示一次，复制完要立刻存到安全的地方，比如本地密码管理器或者环境变量文件里。我试过把 Key 直接写进settings.json，虽然能跑，但一旦这个文件被同步到 Git 仓库就泄露了，所以更推荐用环境变量引用。

模型 ID 这块，插件本身是数据库工具，不直接调模型，但如果你在插件里用到了 AI 辅助功能（比如 SQL 生成、自然语言查询），就需要指定模型 ID。常见的模型 ID 形如gpt-4o、claude-3-5-sonnet这类，具体以控制台里列出的为准。填的时候要和 Base URL 配套，不能一个指向 A 通道、一个指向 B 通道。

把这三样东西准备好之后，建议先在终端里用 curl 验证一遍，确认 Key 和 Base URL 是通的，再去改插件配置。这样能把「通道本身不通」和「插件配置不对」两个问题分开。验证命令很简单：

curl -s https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ | head -c 500

如果返回一串 JSON，里面有模型列表，说明通道是通的。如果返回 401，说明 Key 不对；如果返回 404，说明 Base URL 拼错了。这一步花两分钟，能省掉后面半小时的瞎猜。

另外提醒一句，TaoToken 的接入文档在https://taotoken.net/doc，里面有各语言 SDK 的示例，插件配置遇到不确定的字段名时可以去对照。文档里对 Base URL 和 Key 的说明是最权威的，比网上二手教程靠谱。

3. 可复制的 settings.json 与 Base URL 配置片段

这一节是核心，直接给可复制的配置。MySQL Shell for VS Code 插件的配置分两层：一层是 VS Code 的settings.json，管插件全局行为；另一层是插件内部的连接配置，管具体某个数据库连接。两层都要改，缺一不可。

先看settings.json。打开 VS Code，按Ctrl+Shift+P（Mac 是Cmd+Shift+P），输入Preferences: Open User Settings (JSON)，在打开的settings.json里加入下面这段：

{ "mysql-shell-for-vscode.connections": [ { "name": "taotoken-unified", "endpoint": "https://taotoken.net/api", "authMethod": "api-key", "apiKey": "${env:TAOTOKEN_API_KEY}", "modelId": "gpt-4o", "timeout": 30000 } ], "mysql-shell-for-vscode.defaultConnection": "taotoken-unified", "mysql-shell-for-vscode.proxy.enabled": false, "mysql-shell-for-vscode.logLevel": "debug" }

这里几个字段要重点解释。endpoint填的就是 Base URL，注意结尾不要带斜杠，插件内部会自己拼路径。apiKey用${env:TAOTOKEN_API_KEY}引用环境变量，这样 Key 不会硬编码在文件里。proxy.enabled设成false是因为统一通道本身已经是直连，再走本地代理会多一层，反而容易触发local proxy failed。logLevel设成debug是为了排查时能看到详细日志，问题解决后可以改回info。

环境变量怎么设？Linux/macOS 在~/.zshrc或~/.bashrc里加一行：

export TAOTOKEN_API_KEY="你的Key"

Windows 在 PowerShell 里执行：

[Environment]::SetEnvironmentVariable("TAOTOKEN_API_KEY", "你的Key", "User")

设完要重启 VS Code，让插件重新读取环境变量。这一步很多人漏掉，改完配置发现没生效，其实是 VS Code 还在用旧的环境。

再看插件内部的连接配置。在 VS Code 侧边栏点开 MySQL Shell 图标，找到 Connections 面板，点齿轮图标进入连接编辑。如果插件版本较新，会直接读写settings.json里的connections数组；如果版本较旧，会有一个独立的connections.json，路径通常在~/.mysqlsh/connections.json。两种情况下字段名基本一致，把endpoint、apiKey、modelId三个字段填对即可。

如果你用的是 Cline 或 Claude Code 这类也走统一通道的工具，配置逻辑是相通的，都是「Base URL + Key + Model ID」三件套。Cline 的 MCP 配置里，baseUrl填https://taotoken.net/api，apiKey填环境变量引用，model填模型 ID。Claude Code 的settings.json里则是ANTHROPIC_BASE_URL指向同一地址。三者的共同点是：Base URL 只到/api，不要多写路径。

配置改完，先别急着连数据库，先在插件里点「Test Connection」。如果这一步就报错，说明配置层有问题，回到上面检查字段。如果 Test Connection 通过，再去连具体数据库。

4. 验证请求是否已正确改到 TaoToken 通道

配置填好只是第一步，真正要确认的是「请求到底发到哪去了」。很多人以为改完settings.json就完事，结果请求还是打到默认地址，报错依旧。所以这一节讲怎么验证请求确实走了统一通道。

最直接的办法是看插件的输出日志。在 VS Code 里按Ctrl+Shift+U打开输出面板，右上角下拉选「MySQL Shell for VS Code」。如果logLevel设成了debug，你会看到每次连接尝试的详细日志，里面会打印实际请求的 URL。正确的日志应该长这样：

[debug] POST https://taotoken.net/api/v1/chat/completions [debug] Authorization: Bearer *** [debug] Response status: 200

如果看到的是http://localhost:3306或者别的地址，说明配置没生效，插件还在用默认 endpoint。这时候要检查两件事：一是settings.json有没有语法错误（VS Code 会用红色波浪线标出来），二是环境变量有没有被正确读取（可以在 VS Code 内置终端里echo $TAOTOKEN_API_KEY确认）。

第二个验证手段是抓包。在终端里跑：

sudo tcpdump -i lo0 -A 'tcp port 443' | grep -i taotoken

Linux 上把lo0换成lo。这条命令会打印所有走 443 端口的请求，如果看到taotoken.net的域名，说明请求确实发出去了。抓包适合排查「请求根本没发出去」的情况，比如插件卡在本地代理启动阶段。

第三个验证手段是直接调 API。在终端里跑：

curl -s -o /dev/null -w "%{http_code}" https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY"

返回200说明通道通，返回401说明 Key 有问题，返回404说明路径拼错。这个命令和插件用的是同一个 Base URL 和 Key，所以它的结果能直接反映插件侧的情况。

三个手段配合用：先看日志确认 URL 对不对，再用 curl 确认通道通不通，最后用抓包确认请求有没有真的发出去。三步都过了，基本可以确定请求已经正确改到统一通道。这时候再去连数据库，如果还报错，问题就在数据库侧，不在通道侧了。

验证通过后，建议把logLevel从debug改回info，避免日志刷屏。同时把proxy.enabled保持false，因为统一通道不需要本地代理。

5. 常见报错排查：401、local proxy failed、reading choices

这一节按报错类型逐个拆。每个报错都给出「现象—原因—解决」三段式，照着对号入座。

401 Unauthorized。现象是插件连接时直接弹 401，日志里显示Response status: 401。原因通常是 Key 不对：要么 Key 复制时多了空格或换行，要么环境变量没生效，插件读到的是空字符串，要么 Key 已经过期或被删除。解决办法是先在终端echo $TAOTOKEN_API_KEY确认变量有值，再用 curl 验证 Key 有效。如果 curl 也返回 401，就去控制台重新创建一个 Key，替换环境变量后重启 VS Code。注意 Key 只在创建时显示一次，如果忘了就重新建一个。

local proxy failed。现象是插件侧边栏一直转圈，输出面板刷local proxy failed to start。原因是插件尝试拉起本地 MySQL Shell 子进程失败，常见于proxy.enabled设成了true，或者本地 MySQL Shell 没装、版本不匹配。解决办法是把settings.json里的mysql-shell-for-vscode.proxy.enabled改成false，因为走统一通道不需要本地代理。如果改完还报错，检查本地有没有装 MySQL Shell，插件依赖它做 SQL 解析。在终端跑mysqlsh --version确认，没有的话去 Oracle 官网装一个。

reading choices 报错。现象是日志里出现error reading choices或failed to parse choices。原因是插件收到了响应，但响应格式和它预期的不一样。这通常发生在 Base URL 指向了一个不兼容 OpenAI 格式的通道，或者模型 ID 填错了。解决办法是确认 Base URL 是https://taotoken.net/api，模型 ID 是控制台里列出的有效值。如果模型 ID 填了一个不存在的名字，通道会返回错误结构，插件解析时就报reading choices。

OAuth 相关报错。现象是提示OAuth token expired或invalid_grant。原因是插件里配了 OAuth 认证方式，但统一通道用的是 API Key 认证，两者不匹配。解决办法是把authMethod从oauth改成api-key，并确保apiKey字段填了正确的 Key。OAuth 和 API Key 是两套认证体系，不能混用。

连接超时。现象是插件卡在「Connecting...」很久，最后报 timeout。原因是timeout设得太短，或者网络到统一通道的延迟高。解决办法是把timeout从默认的 10000 改成 30000，给足握手时间。如果还是超时，用 curl 测一下到https://taotoken.net/api的延迟，确认网络本身没问题。

排查时有个通用技巧：把logLevel设成debug，然后复现一次报错，把完整日志从头到尾读一遍。日志里通常会明确写出失败发生在哪一步——是 DNS 解析、TCP 连接、TLS 握手，还是 HTTP 响应解析。定位到具体步骤，解决起来就快了。

6. 把请求稳定收敛到统一通道的后续动作

配置跑通、报错排完，接下来要做的是让这套配置稳定下来，别过两天又出问题。几个实用动作。

第一，把环境变量写进 shell 的启动文件，而不是每次手动 export。Linux/macOS 写进~/.zshrc，Windows 写进系统环境变量。这样每次开终端和 VS Code 都能自动读到，不会因为忘了 export 而报 401。

第二，把settings.json里的连接配置做成模板，团队里其他人可以直接复制。模板里apiKey用环境变量引用，endpoint写死统一通道地址，modelId留一个占位符。新人拿到模板后只需要设自己的环境变量，不用改配置文件。

第三，定期检查 Key 的有效期。如果控制台里 Key 有有效期，设个日历提醒，到期前重新创建并替换环境变量。避免某天突然 401 却找不到原因。

第四，如果同时用多个走统一通道的工具（比如 VS Code 插件、Cline、Claude Code），把它们的 Base URL 统一成https://taotoken.net/api，Key 统一用同一个环境变量。这样管理起来简单，排查问题时也能快速排除「是不是某个工具的配置不一样」这个变量。

第五，长期做编码和 Agent 任务的话，可以考虑用 Coding Plan，它针对高频调用做了优化，比按次调用更划算。具体在https://taotoken.net/coding-plan看。如果只是偶尔验证模型效果，用模型对话页面就够了，地址是https://taotoken.net/chat。接入文档在https://taotoken.net/doc，配置字段不确定时去那里对照最准。

最后说一个我踩过的坑：改完settings.json后一定要完全退出 VS Code 再重开，而不是只关窗口。VS Code 有时会缓存插件配置，只关窗口的话插件进程还在后台跑，读的还是旧配置。完全退出（Ctrl+Q或菜单里 Quit）再启动，配置才会真正生效。这个细节看起来小，但坑过不少人。