1. 为什么 vscode+platformio 的 Key 配置总是散落各处

如果你正在用 vscode 配合 platformio 做 esp32 arduino 开发，大概率遇到过这种局面：platformio.ini 里写了一套上传参数，vscode 扩展设置里又藏着一份工具链路径，串口监视器还要单独指定端口，而一旦涉及需要联网的组件（比如某些依赖下载、远程编译、AI 辅助补全），Key 和 Base URL 又得在另一个地方填。三四个入口各管一摊，改一个忘一个，最后编译报错都不知道是哪层配置没对上。

这个问题的本质是：platformio 本身是一个构建系统，vscode 是编辑器外壳，esp32 的 arduino 框架又是第三方平台包，三者各自维护自己的配置域。初学者最容易踩的坑就是「以为改了一处就全局生效」，结果 platformio.ini 改了 upload_port，扩展设置里的默认端口没动，上传时还是往旧端口发。

我试过把整个链路拆开看，其实只需要理清三条线：第一条是 platformio.ini 负责的构建与烧录参数，第二条是 vscode 扩展设置负责的 IDE 行为，第三条是 API 通道负责的联网请求（Key、Base URL、Model ID）。前两条是本地配置，第三条是网络配置。把这三条线的对应关系一次性理清，后面换板子、换项目、换 Key 都不会乱。

这篇面向嵌入式初学者和 IoT 原型开发者，目标很明确：给你可复制的 platformio.ini 片段、扩展配置项、串口烧录验证动作，并说明如何把相关 endpoint 统一改到 TaoToken 后跑通 blink 示例。你不需要先成为 platformio 专家，跟着步骤走就能把环境跑起来。

核心检索词先摆出来：vscode+platformio 搭建 esp32 arduino 开发环境，重点解决 Key 与 Base URL 配置分散的问题。适合谁？适合已经装好 vscode、想用 platformio 而不是 Arduino IDE 来写 esp32 的人，也适合做 IoT 原型时需要在多个项目间复用同一套 API 通道的开发者。

2. TaoToken 前置：统一 Key 与 Base URL 的接入准备

在动手改配置之前，先把 TaoToken 这一侧的准备工作做完。TaoToken 在这里扮演的角色是统一的 API 通道：你不需要在 platformio、vscode 扩展、串口工具里各填一套不同的 Key，而是把需要联网的请求都指向同一个 Base URL，用同一个 Key 鉴权。这样配置域就从「多处分散」收敛成「一处定义、多处引用」。

第一步，拿到你的 API Key。访问 API Keys 管理页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，登录后创建一个新的 Key。建议按项目命名，比如 esp32-platformio-dev，方便后面区分。创建后立即复制保存，页面刷新后不会再完整显示。

第二步，确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api ，注意这个地址不带任何查询参数，直接作为 Base URL 使用。如果你用的是 OpenAI 兼容的客户端或插件，Base URL 就填这个；如果某个工具要求填完整的 chat completions 路径，则在其后拼接 /v1/chat/completions。

第三步，确认 Model ID。不同工具对模型名称的写法要求不一样，有的要 gpt-4o 这种短名，有的要带前缀。建议先在模型对话页面确认当前可用的模型标识：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。把你要用的 Model ID 记下来，后面配置里会反复用到。

这里要强调一个原则：Base URL、API Key、Model ID 这三件套，在任何需要联网的配置里都必须同时出现且保持一致。少一个就会报 401 或 model not found。很多初学者只填了 Key 没改 Base URL，请求还是发到默认地址，自然鉴权失败。

如果你后续要做长期编码或 Agent 类任务，可以考虑 Coding Plan，它适合需要持续调用、多项目复用的场景：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。对于本篇的 esp32 blink 示例，用按量 Key 就够了。

准备工作做完，你手里应该有三样东西：一个 API Key、Base URL https://taotoken.net/api、一个确认可用的 Model ID。接下来进入实际配置。

3. 可复制配置：platformio.ini 与扩展设置对应关系

这一节是全文的核心，把 platformio.ini、vscode 扩展设置、API 通道三者的配置项一一对应起来。先给结论：platformio.ini 管构建和烧录，扩展设置管 IDE 行为和工具链路径，API 通道管联网请求。三者互不覆盖，但需要保持端口、路径、Key 的一致性。

先看 platformio.ini。这是 platformio 项目的核心配置文件，放在项目根目录。一个能跑通 esp32 arduino blink 的最小配置如下：

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
upload_speed = 921600
upload_port = COM3
monitor_port = COM3
monitor_speed = 115200
build_flags =
    -DCORE_DEBUG_LEVEL=1

逐项说明。platform = espressif32 指定平台包，第一次编译时会自动下载，如果下载慢，可以在 platformio 的包源设置里换成国内镜像。board = esp32dev 是通用 ESP32 Dev Module 的板子标识，如果你用的是 ESP32-S3 或 C3，要换成对应的 board ID。framework = arduino 表示用 arduino 框架而不是 ESP-IDF。upload_speed = 921600 是烧录波特率，部分廉价板子在这个速率下会失败，可以降到 460800 或 115200。upload_port 和 monitor_port 都填 COM3，实际端口在 Windows 设备管理器里查看，Linux/macOS 下是 /dev/ttyUSB0 或 /dev/ttyACM0。

这里就是第一个配置分散点：upload_port 在 platformio.ini 里，但 vscode 的串口监视器扩展可能还有自己的默认端口设置。两边不一致时，上传成功但监视器连不上。

再看 vscode 扩展设置。打开设置，搜索 platformio，重点看这几项：

扩展设置项	作用	建议值
platformio-ide.pioHomeDir	platformio 核心目录	D:\PLATFORMIO_CORE
platformio-ide.useBuiltinPIOCore	是否用内置核心	true
platformio-ide.autoRebuildAutocompleteIndex	自动重建索引	true
platformio-ide.defaultBaudRate	默认波特率	115200

如果你把 platformio 核心装到了 D 盘，pioHomeDir 必须指向 D:\PLATFORMIO_CORE，否则扩展会去默认的 C 盘用户目录找，找不到就重新下载。这个路径和系统环境变量 PLATFORMIO_CORE_DIR 要一致。

第三个配置域是 API 通道。platformio 本身不直接调用大模型 API，但你在 vscode 里用的 AI 辅助插件（比如代码补全、注释生成）需要填 Base URL 和 Key。以常见的 OpenAI 兼容插件为例，配置片段如下：

{
  "openai.baseUrl": "https://taotoken.net/api",
  "openai.apiKey": "sk-你的TaoToken密钥",
  "openai.model": "gpt-4o"
}

如果你用的是 Cline 或类似支持 MCP 的插件，配置项名称可能不同，但三件套不变：Base URL 填 https://taotoken.net/api，API Key 填你的 TaoToken Key，Model ID 填确认可用的模型名。Cline 的配置通常写在 settings.json 里，路径是 .vscode/settings.json 或用户级 settings。

这里要提醒：不要把生产库的 Key 直接写进项目里的 settings.json 并提交到 git。建议用环境变量或本地不提交的配置文件。MCP 直连生产库是明确禁止的，配置时只连开发用的 API 通道。

三者的对应关系总结成一句话：platformio.ini 里的端口要和设备管理器一致，扩展设置里的核心目录要和环境变量一致，API 通道里的 Base URL 和 Key 要和 TaoToken 控制台一致。任何一处改了，另外两处要同步检查。

4. 验证请求：编译烧录 blink 并确认串口输出

配置写完，必须验证。这一节给出完整的编译、烧录、串口验证动作，以及如何确认 API 通道真的通了。

先写 blink 代码。在 platformio 项目的 src/main.cpp 里放入以下内容：

#include "Arduino.h"

#define led 2

void setup() {
    Serial.begin(115200);
    pinMode(led, OUTPUT);
    Serial.println("boot ok");
}

void loop() {
    digitalWrite(led, HIGH);
    delay(1000);
    Serial.println("led is high");
    digitalWrite(led, LOW);
    delay(1000);
    Serial.println("led is low");
}

注意 #define led 2，ESP32 Dev Module 的板载 LED 通常接在 GPIO2。如果你用的是其他板子，查一下原理图确认 LED 引脚。

编译。在 vscode 里点击 platformio 的勾号图标，或者终端执行：

pio run

第一次编译会下载 espressif32 平台包和工具链，5 到 10 分钟。如果卡在下载，检查 D:\PLATFORMIO_CORE\penv\pip.conf 是否配了国内镜像：

[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
[install]
trusted-host = mirrors.aliyun.com

编译成功后，烧录：

pio run --target upload

如果报 Failed to connect to ESP32，按住板子上的 BOOT 键再点上传，或者降低 upload_speed。烧录成功后，打开串口监视器：

pio device monitor --baud 115200

你应该看到循环输出：

boot ok
led is high
led is low
led is high
led is low

同时板载 LED 每秒闪烁一次。到这里，本地开发环境就通了。

接下来验证 API 通道。如果你在 vscode 里装了 AI 辅助插件，触发一次补全或对话请求，观察是否返回正常内容。如果插件报错，先在终端用 curl 直接测 Base URL：

curl https://taotoken.net/api/v1/chat/completions \
  -H "Authorization: Bearer sk-你的TaoToken密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "ping"}]
  }'

返回 JSON 里带 choices 字段就说明 Key 和 Base URL 都对了。如果返回 401，检查 Key 是否复制完整；如果返回 model not found，检查 Model ID 拼写。

这一步的意义是把「本地烧录」和「联网请求」分开验证。本地通了不代表 API 通，API 通了也不代表串口配置对。两条线都验证过，才算环境真正可用。

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

配置过程中最容易撞上的几类报错，这里逐个对照真实错误信息给出排查路径。

401 Unauthorized。这是鉴权失败，九成是 Key 问题。检查三点：Key 是否复制完整（前后不能有空格）、Key 是否已过期或被删除、请求头格式是否是 Authorization: Bearer sk-xxx。如果你在 platformio.ini 或扩展设置里填了 Key，但实际请求走的是另一个通道，也会 401。确认你改的是真正生效的那份配置。

local proxy failed / connection refused。这类报错通常出现在插件尝试连接 Base URL 时。先确认 Base URL 写的是 https://taotoken.net/api，不要多写或少写 /v1。有些插件要求 Base URL 不带 /v1，有些要求带，看插件文档。另外检查本机网络是否能正常访问该地址，用 curl 测一下最直接。如果 curl 通但插件不通，多半是插件自己的代理设置或证书校验问题，检查插件的网络配置项。

reading choices 报错 / choices 字段缺失。这通常意味着返回的 JSON 结构不符合预期。可能原因：Model ID 填错导致返回了错误对象、请求体格式不对、或者 Base URL 指向了一个不兼容的端点。先用 curl 确认返回结构，再对照插件的期望格式调整。如果返回里有 error 字段，优先看 error message。

OAuth 相关报错。部分工具用 OAuth 而不是 API Key 鉴权，如果你混用了两种方式，会出现 token 无效。确认你的工具是走 Key 还是走 OAuth，走 Key 就填 Key，不要同时填 OAuth token。

串口相关报错。could not open port COM3 说明端口被占用或不存在。检查设备管理器，确认板子已识别，关闭其他占用串口的程序（比如另一个串口监视器）。wrong boot mode 通常是烧录时没进下载模式，按住 BOOT 再试。

编译报错 Unknown board ID。board 名称写错了。ESP32 Dev Module 是 esp32dev，ESP32-S3 DevKitC 是 esp32-s3-devkitc-1，去 platformio 的 boards 列表查准确名称。

排查的核心思路是分层：先确认本地编译烧录这条线，再确认 API 请求这条线，最后确认两者之间的配置是否一致。不要一上来就怀疑 Key，很多时候是端口或路径没对上。

6. 把 endpoint 统一到 TaoToken 后的长期用法

环境跑通之后，真正省心的地方在于后续复用。把 endpoint 统一到 TaoToken 之后，你新建项目时不需要重新找 Key、重新配 Base URL，只需要复制同一套三件套：Base URL https://taotoken.net/api、你的 API Key、确认可用的 Model ID。

具体做法：在用户级 settings.json 里维护一份全局配置，项目级 settings.json 只覆盖必要的差异项。这样换项目时，API 通道不用动，只改 platformio.ini 里的 board 和 port。对于做 IoT 原型的开发者，经常要在 ESP32、ESP32-S3、ESP32-C3 之间切换，board ID 和 upload_port 是变的，但 API 通道是稳定的。

如果你需要长期编码或跑 Agent 任务，Coding Plan 提供了更适合持续调用的方案：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言和各工具的接入示例，遇到配置项不确定时先查文档。

最后给一个实用技巧：把 platformio.ini 里的 upload_port 和 monitor_port 用变量抽出来，放在项目根目录的 platformio_override.ini 里，主配置文件保持通用。这样同一份代码在不同机器上只需要改 override 文件，不会污染主配置。同理，API Key 放在环境变量或本地不提交的文件里，主配置只引用变量名。这套做法在多个 esp32 项目间切换时特别省事，也是我踩过端口冲突的坑之后固定下来的习惯。