企业官网建设流程全解析

1. 从三台刑天机器人说起：语音集群控制到底难在哪

DIABLO 刑天机器人集群语音控制系统，简单说就是让一台 ESP32S3 语音终端听懂人话，再把「前进、后退、左转、站立」这类指令分发给多台 ROS2 机器人，让它们同时或分组执行。它适合手里已经有刑天轮式机器人、树莓派小车、松灵底盘这类跑 ROS2 的硬件玩家，也适合想搞明白「语音助手怎么和机器人中间件打通」的嵌入式开发者。整套链路的核心检索词就是 ESP32S3 语音采集、ROS2 多机话题分发、MCP Tool Call 指令映射。

我一开始的想法很朴素：三台机器人都在同一个局域网，都跑 ROS2，那直接在一个 ROS_DOMAIN_ID 里发/diablo/MotionCmd不就行了。结果第一次联调就翻车——三台机器人同时收到同一条前进指令，我想让 Robot2 单独后退根本做不到，因为话题是广播语义，谁订阅谁就动。

那换成三台用不同 ROS_DOMAIN_ID 呢？比如 Robot1 用 51、Robot2 用 52、Robot3 用 53。这样确实隔离了，但新的问题来了：Robot1 上的调度节点默认没法直接往 Robot2 的 domain 发消息。你要么起多个 domain bridge，要么开多进程分别绑定不同 domain，折腾下来跨机器的 DDS 数据面又开始不稳定——ros2 node list能看到节点，ros2 topic list也能看到话题，但真正的数据就是不送达，或者延迟忽大忽小。

这里必须说清楚一个工程现实：ROS2 底层用的 DDS 在单机内非常可靠，但一到多机局域网，尤其是家用路由器、WiFi 和有线混连的环境，发现协议和实际数据面经常对不上。你看到的是「发现成功」，实际是「通信失败」。这不是配置写错了，而是 DDS 多播发现和单播数据在不同网段、不同网卡优先级下的常见表现。

所以这套 DIABLO 刑天机器人集群语音控制系统采用了一个很实用的折中方案：跨机器只走简单 UDP 控制请求，真正的 ROS2 MotionCmd 永远在机器人本机发布。也就是说，Robot1 作为调度端，收到语音指令后，本机直接发/diablo/MotionCmd控制自己；对 Robot2 和 Robot3，则通过 UDP relay 发一条轻量请求，它们收到后各自在本机发布/diablo/MotionCmd。这样既避开了跨机 DDS 的不稳定，又保留了每台机器人原有的 ROS2 控制架构，底层驱动一行都不用改。

整个控制逻辑可以概括为：小智语音指令 → MCP Tool Call → ROS2 MotionCmd → diablo_ctrl_node → 下位机控制板。ESP32S3 负责语音采集和指令下发，ROS2 负责多机话题分发与状态回传。下面我就按实际部署顺序，把可复制的固件配置、ROS2 节点和联调验证步骤拆开讲。

2. TaoToken 前置：给语音指令接一个大模型大脑

ESP32S3 本身只做语音采集和唤醒，真正把「让二号车往后退一点」这种自然语言翻译成结构化工具调用的，是大模型。小智固件默认走的是 MCP 协议，模型侧需要提供一个兼容 OpenAI 接口的接入点。我实测下来，用 TaoToken 的 API 接入最省事，因为它同时支持模型对话和工具调用，配置里只要改 Base URL、Key 和 Model ID 三件套就行。

先说你需要在 TaoToken 控制台拿到什么。打开 https://taotoken.net/api-keys ，创建一个 API Key，复制下来。这个 Key 就是后面 ESP32S3 固件和 ROS2 桥接层都要用的凭证。注意不要把它提交到 Git 仓库，我一般放在设备本地的环境变量或者单独的secrets.h里，并且把secrets.h加进.gitignore。

然后是 Base URL。TaoToken 的 API 地址是 https://taotoken.net/api ，注意这个地址不带任何查询参数，直接作为 OpenAI 兼容接口的 base。模型 ID 方面，工具调用能力比较稳的是claude-sonnet-4-20250514这类，你也可以在 https://taotoken.net/models 看当前可用的模型列表。选模型的原则很简单：要支持 function calling / tool use，否则 MCP 工具根本调不起来。

如果你只是想先验证模型能不能正常对话和调用工具，可以直接用 https://taotoken.net/chat 这个模型对话页面，把系统提示词和工具定义贴进去试一轮。确认模型能正确返回工具调用参数后，再往 ESP32S3 固件里写，能省掉很多「到底是固件问题还是模型问题」的排查时间。

对于长期要跑编码和 Agent 任务的场景，比如你想让语音助手顺便能查机器人状态、生成简单的控制脚本，可以考虑 Coding Plan，地址是 https://taotoken.net/coding-plan 。它的定位是给持续性的编码和 Agent 调用提供额度，和单次对话的计费方式不一样。我自己的做法是：调试阶段用模型对话页面快速验证，正式部署时把 Key 写进固件配置，长期跑就用 Coding Plan 兜底。

这里要提醒一句：TaoToken 是模型接入层，不是机器人控制器，也不是编辑器替代品。它只负责把语音转成工具调用参数，真正的运动控制还是由 ROS2 节点和刑天下位机完成。把这个边界搞清楚，后面排查问题的时候就不会跑偏——语音没反应，先查模型和 MCP；模型返回了但机器人不动，查 ROS2 话题和 UDP relay。

3. 可复制配置：ESP32S3 固件与 ROS2 桥接层

这一节是整套系统能不能跑通的关键。我把它拆成三块：ESP32S3 固件的模型配置、ROS2 工作空间的编译配置、以及 MCP 工具到 ROS2 话题的映射配置。每一块都给可复制的片段，路径和原文保持一致。

先说 ESP32S3 固件侧。小智固件里模型接入点通常在一个配置文件里，你需要改的是 Base URL、API Key 和 Model ID。以常见的config.h或secrets.h为例，配置片段长这样：

// secrets.h —— 不要提交到公开仓库 #define TAOTOKEN_BASE_URL "https://taotoken.net/api" #define TAOTOKEN_API_KEY "sk-你的TaoToken密钥" #define TAOTOKEN_MODEL_ID "claude-sonnet-4-20250514" // MCP 服务地址，指向 Robot1 上运行的桥接层 #define MCP_SERVER_HOST "192.168.1.101" #define MCP_SERVER_PORT 8765

这里MCP_SERVER_HOST填的是 Robot1 的局域网 IP，因为 Robot1 承担集群调度和命令分发。三台机器人建议在路由器里做静态 IP 绑定，否则每次重启 IP 变了，固件里的地址就得跟着改。

然后是 ROS2 工作空间。三台机器人各自拉取对应分支的代码，主分支给 Robot1，robot2 和 robot3 分支给另外两台。拉取和编译命令如下：

cd ~/diablo_ws/src git clone -b main https://github.com/yan-gd/xiaozhi-diablo_ros2.git # Robot2 上执行 git clone -b robot2 https://github.com/yan-gd/xiaozhi-diablo_ros2.git # Robot3 上执行 git clone -b robot3 https://github.com/yan-gd/xiaozhi-diablo_ros2.git

每台机器都要完整编译一次。第一次部署建议全量编译，确认依赖都装齐：

cd ~/diablo_ws source /opt/ros/foxy/setup.bash colcon build --symlink-install source install/setup.bash

如果你只想编译小智控制包，可以只选xiaozhi_robot_control：

cd ~/diablo_ws source /opt/ros/foxy/setup.bash colcon build --symlink-install --packages-select xiaozhi_robot_control source install/setup.bash

接下来是 MCP 工具到 ROS2 话题的映射。这是整个桥接层的核心，xiaozhi_robot_control目录里定义了一组工具，每个工具背后对应一个 ROS2 控制逻辑。默认适配刑天机器人时，控制话题是/diablo/MotionCmd。工具和动作的对应关系可以用一张表说清楚：

集群控制的分发逻辑在 Robot1 的代码里。Robot1 收到语音指令后，先判断是单机控制还是集群控制。单机控制直接本机发布/diablo/MotionCmd；集群控制则通过 UDP 向 Robot2 和 Robot3 的固定端口发一条 JSON 请求，内容大致是：

{ "target": "robot2", "action": "move_forward", "speed": 0.3, "duration_ms": 1500 }

Robot2 和 Robot3 上的接收节点监听 UDP 端口，收到请求后在本机发布/diablo/MotionCmd。这样每台机器人的 ROS2 数据面都只在本机活动，跨机只走 UDP，彻底绕开了多机 DDS 的不稳定问题。

如果你用的是其他 ROS2 机器人，比如树莓派小车，只需要把话题从/diablo/MotionCmd改成/cmd_vel，消息类型换成geometry_msgs/Twist，工具名和动作语义可以保持不变。这就是xiaozhi_robot_control作为通用接入模板的价值：不依赖特定机器人本体，保留原有 ROS2 控制架构，通过 MCP 工具暴露机器人能力。

4. 验证请求：从语音到多机动作的完整联调

配置写完，接下来是验证。我建议按「单机 → 双机 → 三机」的顺序逐步放开，不要一上来就三台一起联调，否则出问题很难定位是哪一层。

第一步，先验证模型和 MCP 工具调用。在 Robot1 上启动桥接层，然后在 TaoToken 模型对话页面里发一句「让一号车前进」，看模型返回的工具调用参数是不是move_forward，目标是不是robot1。如果模型返回的是自然语言而不是工具调用，说明模型不支持 function calling，换一个支持 tool use 的模型 ID。

第二步，验证 Robot1 单机控制。启动 Robot1 的 ROS2 节点：

cd ~/diablo_ws source install/setup.bash ros2 run xiaozhi_robot_control xiaozhi_bridge_node

另开一个终端，手动发一条控制消息，确认刑天机器人能动：

source /opt/ros/foxy/setup.bash source ~/diablo_ws/install/setup.bash ros2 topic pub /diablo/MotionCmd diablo_msg/MotionCmd "{action: 'move_forward', speed: 0.3}"

如果机器人不动，先用ros2 topic list确认话题存在，再用ros2 topic echo /diablo/MotionCmd看消息有没有真正发出去。这一步能过，说明 ROS2 控制链路是通的。

第三步，验证 UDP relay。在 Robot2 上启动接收节点，然后在 Robot1 上手动触发一次集群控制请求。Robot2 的终端应该能看到收到 UDP 请求并本机发布/diablo/MotionCmd的日志。如果 Robot2 没反应，先检查两台机器的防火墙有没有拦 UDP 端口，再确认 Robot1 配置里的 Robot2 IP 是不是写对了。

第四步，三机联调。三台都启动后，用语音说「所有车前进」，观察三台是否同时动作；再说「二号车后退」，观察是否只有 Robot2 后退。这里有个容易忽略的点：语音识别本身有延迟，模型工具调用也有延迟，所以从你说完到机器人动作，大概有 1 到 2 秒的间隔，这是正常的，不要以为是卡住了。

第五步，验证状态回传。刑天机器人会把当前状态通过 ROS2 话题回传，桥接层可以把状态转成 MCP 工具的返回结果，让语音助手能回答「现在几号车在动」。你可以用ros2 topic echo看状态话题，确认数据在更新。

整个联调过程中，我踩过最大的坑是开机自启。源代码里有系统服务文件，目的是让小智桥接程序开机自启，不必每次都进图形界面或者 SSH 远程连接。安装命令是：

cd ~/diablo_ws/src/xiaozhi_robot_control bash ./scripts/install_simple_startup.sh

如果需要未登录桌面也能开机启动用户服务，执行一次：

sudo loginctl enable-linger diablo

查看状态和日志：

systemctl --user status xiaozhi-diablo-startup.service journalctl --user -u xiaozhi-diablo-startup.service -f

初次部署会遇到脚本权限问题，给 scripts 目录下脚本加执行权限：

cd ~/diablo_ws/src/xiaozhi-diablo_ros2/xiaozhi_robot_control chmod +x scripts/*.sh

最后查看系统服务状态时 RUNNING 就行了。如果服务起不来，先看journalctl的报错，大概率是环境变量没加载，或者 ROS2 的 setup.bash 没 source。

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

这一节把我实际遇到过的报错和排查路径列出来，你对照着看，能省不少时间。

第一个高频报错是 401 Unauthorized。这个基本是 TaoToken API Key 的问题。先确认secrets.h里的 Key 没有多余空格，再确认这个 Key 在控制台里是启用状态。如果你用的是环境变量，检查固件启动时环境变量有没有正确注入。还有一种情况是 Key 复制时漏了前缀，TaoToken 的 Key 通常以sk-开头，少一位都会 401。

第二个报错是 local proxy failed。这个通常出现在 ESP32S3 固件侧，意思是固件连不上你配置的 MCP 服务地址。排查顺序是：先 ping 一下MCP_SERVER_HOST的 IP，确认网络通；再确认 Robot1 上的桥接层真的在监听MCP_SERVER_PORT，可以用netstat -tunlp | grep 8765看端口；最后确认固件和 Robot1 在同一个局域网，没有跨网段。如果用的是 WiFi，注意有些路由器开了 AP 隔离，设备之间不能互访，这个要在路由器设置里关掉。

第三个报错是 reading choices 相关的解析错误。这个一般出现在模型返回的 JSON 格式不对，或者工具调用参数缺字段。先确认你用的模型 ID 支持 tool use，再检查 MCP 工具定义里的参数 schema 是不是和模型返回的对得上。我遇到过模型返回action字段但工具定义里写的是command，结果解析失败。统一字段名之后就好了。

第四个是 OAuth 相关报错。如果你在配置里用了 OAuth 流程，报错通常是 token 过期或者回调地址不对。TaoToken 的 API Key 方式不需要 OAuth，直接用 Key 就行，所以如果你不是特别需要 OAuth，建议直接用 Key 接入，少一层复杂度。如果确实要用 OAuth，确认回调地址和你在控制台配置的一致，token 过期就重新走一遍授权。

还有一个容易被忽略的报错是 ROS2 话题存在但数据不送达。这个前面讲过，是多机 DDS 的典型表现。解决办法就是这套系统采用的方案：跨机走 UDP，本机发 ROS2。如果你坚持要用 DDS 跨机，可以试试配置单播、指定网卡、调整 DDS 发现参数，但稳定性不如 UDP relay 方案。

最后提醒一个配置层面的坑：CC Switch、Cline MCP、Codex auth.json 这类工具如果出现在你的链路里，一定要把 Base URL、Key、Model ID 三件套写全。Base URL 是 https://taotoken.net/api ，Key 是你的 TaoToken 密钥，Model ID 是支持工具调用的模型。少任何一个，工具调用都会失败。我见过有人只填了 Key 没填 Base URL，结果请求发到了默认的 OpenAI 地址，自然 401。

6. 继续往下走：接入文档与模型验证入口

如果你已经按上面的步骤把三台刑天机器人跑通了，接下来可以做的事还有很多。比如把xiaozhi_robot_control迁移到其他 ROS2 机器人上，把话题从/diablo/MotionCmd换成/cmd_vel，工具名保持不变，就能用同一套语音控制逻辑驱动树莓派小车或者松灵底盘。再比如给桥接层加状态查询工具，让语音助手能回答「现在几号车在动、电量多少」。

接入过程中如果遇到 Key 配置、模型选择、工具调用参数的问题，可以直接看接入文档：https://taotoken.net/doc 。里面把 Base URL、Key、Model ID 的填写方式和常见报错都列清楚了。想先验证模型能不能正确调用工具，用模型对话页面最快：https://taotoken.net/chat ，把工具定义贴进去试一轮，比直接烧固件省时间。

如果你打算长期跑语音控制和 Agent 任务，比如让机器人集群定时执行巡逻、自动回充、状态上报，Coding Plan 会比单次对话更合适：https://taotoken.net/coding-plan 。它的额度模型更适合持续性调用，不用每次担心额度用完。

最后说一个我自己的经验：这套系统里最不稳定的环节往往不是 ROS2，也不是 ESP32S3，而是局域网本身。WiFi 信号抖动、路由器 AP 隔离、IP 冲突，都会让 UDP relay 时通时断。我的做法是给三台机器人做静态 IP 绑定，能插网线就插网线，WiFi 只留给 ESP32S3 语音终端。这样跑下来，连续几个小时的控制都很稳。