企业官网建设流程全解析

1. 为什么要在 ESP32 上跑 MCP：嵌入式 AI 的真实痛点

如果你手上有一块 ESP32-S3 开发板，想让它变成一个能听懂人话、还能控制舵机和继电器的语音助手，2025 年最省事的路径基本就是 xiaozhi-esp32 加 MCP 协议这套组合。MCP 全称 Model Context Protocol，是一个把大语言模型和外部工具连接起来的开源标准，说白了就是给 LLM 定义了一套「怎么描述工具、怎么调用工具、怎么拿回结果」的通用语言。xiaozhi-esp32 则是虾哥开源的一个嵌入式 AI 项目，把语音唤醒、流式对话、设备控制打包成了一套能在 ESP32 上跑的固件，目前在 GitHub 上已经有两万多 Star。

这两个东西凑在一起解决的核心问题是：大模型怎么可靠地控制一块只有几百 KB 内存的芯片。在 MCP 出现之前，每个框架都有自己的工具描述格式，LangChain 用一套 Schema，别的框架用另一套，工具没法跨平台复用，边缘设备更是难以解析那些非结构化的指令。MCP 把工具调用统一成 JSON-RPC 2.0 格式，设备端只需要实现 initialize、tools/list、tools/call 这几个方法，就能被任何支持 MCP 的客户端发现和调用。

这篇文章适合三类人看：一是手里有 ESP32 开发板、想把语音助手跑起来的硬件爱好者；二是做嵌入式 AI 产品、需要一套标准化设备控制协议的工程师；三是想理解 MCP 在资源受限设备上到底怎么落地的人。我会从协议格式讲到源码实现，再给出可复制的服务端配置和 TaoToken 统一通道的接入示例，最后附上串口日志的验证步骤，让你能在自己的硬件上把整条链路复现出来。

需要提前说明的是，MCP 在 xiaozhi-esp32 里的角色是「设备端作为 MCP 服务端」。也就是说，ESP32 把自己能做的事情（调音量、看状态、控制底盘）注册成一个个工具，后台的 API 服务作为 MCP 客户端来发现和调用这些工具。这个方向和很多人第一反应的「设备去调用云端工具」是反过来的，理解这一点对后面看代码很关键。

2. TaoToken 统一通道前置准备：Key、Base URL 与模型 ID

在把设备端跑通之前，你需要一个能作为 MCP 客户端、同时能调用大模型的云端通道。这里我用 TaoToken 来做统一接入，原因是它同时提供了 OpenAI 兼容的对话接口和 API Key 管理，省得你在设备固件、后台服务、模型调用之间来回切换不同的鉴权方式。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api ，注意 API 地址后面不加任何 UTM 参数。

前置准备分三步。第一步是拿到 API Key，进入控制台后创建密钥，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，创建完记得立刻复制，页面刷新后就看不到了。第二步是确认你要用的模型 ID，这个在模型对话页面能看到当前可用的模型列表，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。第三步是把 Base URL 记下来，后面配置里统一用 https://taotoken.net/api 。

这里有个容易踩的坑：很多人把 Base URL 写成 https://taotoken.net/api/v1 或者带上一堆路径，结果请求直接 404。正确的做法是 Base URL 只写到 /api，具体的 /v1/chat/completions 由 SDK 或客户端自己拼接。如果你用的是 OpenAI 官方 SDK，把 base_url 设成 https://taotoken.net/api 就行，SDK 会自动补全后面的路径。

对于长期要跑编码任务或者 Agent 场景的，可以看一下 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，它更适合持续性的调用而不是单次对话。如果你只是想先验证模型通不通，用模型对话页面发一条消息最快。API 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 ，遇到鉴权问题先翻文档比瞎试快。

把这三样东西准备好——Base URL、API Key、Model ID——后面无论是配置后台服务还是写测试脚本，都围绕这三个值展开。我建议你先在电脑上用 curl 把模型调通，再去折腾 ESP32 固件，这样能把「网络和鉴权问题」和「硬件问题」分开排查，省很多时间。

3. 可复制的 MCP 服务端配置与 TaoToken 接入片段

这一节给你可以直接抄的配置。先说明整体结构：ESP32 设备通过 WebSocket 连到你的后台服务，后台服务作为 MCP 客户端，同时通过 TaoToken 的 API 调用大模型。所以你需要配置两块，一块是后台服务的模型接入，一块是设备端的 MCP 相关参数。

先看后台服务的模型接入配置。如果你用 Python 写后台，可以用一个 config.json 来管理，路径放在项目根目录的 config/config.json：

{ "llm": { "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥", "model": "你的模型ID", "timeout": 30, "max_retries": 2 }, "mcp": { "enabled": true, "protocol_version": "2024-11-05", "transport": "websocket", "tool_call_timeout": 10 }, "server": { "websocket_port": 8000, "host": "0.0.0.0" } }

如果你更习惯用 TOML，等价的写法是这样，放在 config/config.toml：

[llm] base_url = "https://taotoken.net/api" api_key = "sk-你的TaoToken密钥" model = "你的模型ID" timeout = 30 max_retries = 2 [mcp] enabled = true protocol_version = "2024-11-05" transport = "websocket" tool_call_timeout = 10 [server] websocket_port = 8000 host = "0.0.0.0"

注意 api_key 这一行，实际使用时替换成你在控制台创建的那串。base_url 严格写成 https://taotoken.net/api ，不要加 /v1，不要加结尾斜杠。model 填你在模型对话页面看到的那个 ID，填错了会返回模型不存在的错误。

再看设备端的配置。xiaozhi-esp32 的固件里，WebSocket 地址和鉴权信息是通过 menuconfig 或者 sdkconfig 配置的。关键几项是：

CONFIG_WEBSOCKET_URL="ws://你的后台服务IP:8000/ws" CONFIG_WEBSOCKET_ACCESS_TOKEN="你的设备接入token" CONFIG_MCP_ENABLED=y CONFIG_MCP_PROTOCOL_VERSION="2024-11-05"

这里的 ACCESS_TOKEN 是设备连你后台服务的凭证，和 TaoToken 的 API Key 是两回事，别搞混。设备端不直接持有 TaoToken 的 Key，Key 只存在后台服务里，这样即使设备被拆了也拿不到你的模型额度。

如果你用的是 Claude Code 或者类似的编码工具来辅助开发后台，可以在 settings 里配置模型通道。以 Claude Code 的 settings.json 为例，路径在 ~/.claude/settings.json：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥", "ANTHROPIC_MODEL": "你的模型ID" } }

这三件套——Base URL、Key、Model ID——在 Claude Code、Cline、Codex 的 auth.json 里都是同样的逻辑，只是字段名不同。Codex 的 auth.json 一般放在 ~/.codex/auth.json，里面写的是 openai 相关的字段，但值还是这三个。Cline 的 MCP 配置则在插件设置里，填的也是同样的 Base URL 和 Key。

配置写完先别急着烧录，用下面的命令在电脑上验证一下模型通道通不通：

curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -d '{ "model": "你的模型ID", "messages": [{"role": "user", "content": "回复ok两个字"}] }'

返回里能看到 choices 数组和内容，就说明模型通道没问题。这一步过了再去调设备，能省掉一半的排查时间。

4. 验证请求与串口日志：从 hello 到 tools/call 的完整链路

配置就绪后，把固件烧进 ESP32，打开串口监视器，波特率一般设 115200。你会看到设备启动、连 WiFi、连 WebSocket 的日志。关键节点是设备发出 hello 消息，里面带一个 features 字段，标记 mcp 为 true，告诉服务端「我支持 MCP」。这个 hello 消息长这样：

{ "type": "hello", "version": 1, "features": { "mcp": true }, "transport": "websocket", "audio_params": { "format": "opus", "sample_rate": 16000, "channels": 1, "frame_duration": 60 } }

服务端收到后回一个 hello，通信正式建立。紧接着服务端会发 initialize 来初始化 MCP 会话，设备端在 mcp_server.cc 的 ParseMessage 里处理，回一个包含 protocolVersion 和 serverInfo 的结果。串口日志里你会看到类似MCP initialize received和ReplyResult的输出。

然后是 tools/list。服务端发请求，设备端把注册好的工具列表返回。这一步能不能成功，取决于你在固件里有没有调用 AddTool 把工具加进去。如果你自己加了新工具但没注册，tools/list 里就不会出现，后面调用自然失败。返回的结构里每个工具都有 name、description 和 inputSchema，inputSchema 就是参数的 JSON Schema，服务端靠它知道该传什么参数。

最后是 tools/call。服务端指定工具名和参数，设备端执行后返回结果。比如调音量：

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "self.audio_speaker.set_volume", "arguments": { "volume": 50 } }, "id": 3 }

设备端执行完返回：

{ "jsonrpc": "2.0", "id": 3, "result": { "content": [ { "type": "text", "text": "true" } ], "isError": false } }

串口日志里对应会打印工具名、参数、执行结果。如果你在日志里看到tools/call: Missing params或者Invalid arguments，说明参数格式不对，检查 arguments 是不是对象、参数名和 Schema 里定义的是否一致。

整个链路验证下来，你应该能在串口里看到这样一条完整的时间线：设备启动 → WiFi 连接成功 → WebSocket 连接成功 → 发送 hello → 收到服务端 hello → 收到 initialize → 回复 initialize 结果 → 收到 tools/list → 回复工具列表 → 收到 tools/call → 执行并回复结果。任何一环断了，日志里都会有对应的错误，按顺序排查就行。

5. 本篇常见错误排查：401、local proxy failed 与 OAuth 报错

实际跑的时候，报错基本集中在几个地方。我按出现频率排一下，你对照着看。

第一个是 401 Unauthorized。这个几乎都是 API Key 的问题。要么是 Key 复制的时候带了空格，要么是 Key 已经失效或者被删了，要么是 Authorization 头没写对。正确的格式是Authorization: Bearer sk-xxx，Bearer 和 Key 之间有一个空格，别漏了。如果你用的是 Claude Code 或者 Cline，检查 settings.json 或 auth.json 里的字段名对不对，有些工具用的是 ANTHROPIC_API_KEY，有些用 OPENAI_API_KEY，填错字段名也会 401。

第二个是 local proxy failed 或者 connection refused。这个通常出现在你本地起了个代理去转发请求的场景。报错说明代理没起来，或者端口不对，或者 Base URL 指向了代理但代理没配好。最直接的排查方法是先绕过代理，直接用 curl 打 https://taotoken.net/api/v1/chat/completions ，能通就说明是代理配置的问题，不能通就是网络或 Key 的问题。另外注意 Base URL 不要写成带 /v1 的形式，SDK 会自己拼，写重了会变成 /v1/v1/chat/completions，直接 404。

第三个是 reading choices 相关的报错，比如cannot read property 'choices' of undefined或者reading '0'。这个说明返回的 JSON 里没有 choices 字段，通常是请求本身失败了，返回的是错误对象而不是正常的对话结果。常见原因是 model 字段填错、请求体格式不对、或者 max_tokens 之类的参数超了限制。把完整的返回打印出来看，错误信息一般写在 error 字段里，照着改就行。

第四个是 OAuth 相关的报错。MCP 在 2025-03-26 版本引入了 OAuth 2.1，2025-11-25 版本又加了 OpenID Connect Discovery。如果你用的客户端要求走 OAuth 流程，但服务端没配授权服务器，就会报授权失败。对于 xiaozhi-esp32 这种设备端作为 MCP 服务端的场景，鉴权主要靠 WebSocket 连接时的 Access Token，一般不走完整的 OAuth 流程。如果你在日志里看到 OAuth 相关的错误，先确认你的客户端是不是强制要求 OAuth，是的话要么换客户端，要么在服务端补上授权配置。

还有一个容易忽略的是协议版本不匹配。设备端 hello 里报的版本和服务端期望的不一致，会导致 initialize 失败。xiaozhi-esp32 目前实现的是 2024-11-05 规范的核心方法，如果你的服务端要求 2025-06-18 的新特性比如 Elicitation，设备端不支持就会报错。排查方法是看 initialize 的返回里 protocolVersion 是什么，和服务端要求的是否一致。

排查顺序建议是：先 curl 验证模型通道 → 再看设备 WebSocket 是否连上 → 再看 hello 和 initialize 是否成功 → 最后看 tools/list 和 tools/call。一层一层往下，别跳步。

6. 把链路跑通之后：统一通道带来的实际收益

设备端跑通之后，你会发现 TaoToken 统一通道的价值在于「一个 Key 管所有」。后台服务调模型用它，编码工具辅助开发用它，验证模型通不通也用它，不用在多个平台之间切换鉴权。对于嵌入式 AI 这种涉及固件、后台、模型三层的场景，减少一层鉴权切换就少一类排查问题。

如果你要长期跑编码或者 Agent 任务，Coding Plan 比按次调用更划算，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。如果只是偶尔验证，用模型对话页面就够了。API 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 。

最后给一个实用技巧：在后台服务里把每次 tools/call 的请求和响应都记一份日志，包括时间戳、工具名、参数、结果。设备端串口日志只保留最近一段，服务端日志才是你排查历史问题的依据。我试过在设备端加了一堆打印，结果串口刷太快根本看不清，后来把详细日志挪到服务端，排查效率高了很多。