1. 为什么偏偏是树莓派和 Claude具身智能的性价比窗口做大模型和硬件结合这个方向绕不开“具身智能”这个词。工业级平台像法奥协作机器人、ABB工业机器人的控制柜无论是精度还是可靠性都没话说问题在于价格和门槛个人想在周末捣鼓出点东西基本不现实。反过来看树莓派加 Claude 的组合反而提供了一个很务实的答案一千块出头的硬件加上一个随时可用的云端大脑就能让大模型真正走出屏幕。1.1 大脑上云、身体下地把树莓派称为“身体”、把 Claude 称为“大脑”听起来像一句广告词但实操上确实是按这个边界拆分的。我的原则很简单一切需要实时响应、低延迟的事例如电机速度、关节角度、传感器紧急触发全部在树莓派本地完成一切需要理解、推理、长周期规划的事交给 Claude通过 API 调用完成。为什么这么分典型的大模型 API从发起请求到拿到完整响应通常需要 1 到 3 秒。这个延迟对紧急避障来说是致命的但不影响 Claude 处理“过一会儿去客厅巡逻一圈遇到障碍物就绕过去”这样的长周期任务。工业机器人里控制柜的思路其实一模一样运动控制由伺服和专用控制器实时完成上位机只负责下发轨迹和任务我们只是把“上位机”换成了 Claude。1.2 为什么是 Claude 而不是本地小模型树莓派本地不是不能跑大模型7B 级别的量化模型速度勉强能看但视觉理解和工具调用能力会明显缩水。Claude 最吸引我的点是函数调用tool use的稳定性。给它一份严格定义的 JSON 工具列表它基本能按照 schema 返回正确的参数。具身控制最怕的就是模型输出一大段散文式动作描述你还得在代码里做语义解析最后模型写高兴了参数还没填对。用 Claude 可以直接定义好动作函数让它按字段填写。比如“看到障碍物就左转 30 度再走 40 厘米”它会自动调用对应的函数并把参数补全。在这种场景下模型不是在“写作文”而是在“填表单”可靠性高得多。这一点也是我最后放弃本地小模型、转向 Claude API 的核心原因。2. 底座选型树莓派5、4B、Pico 各自承担什么角色这个项目本质上是一台“分布式机器人控制系统”。树莓派5 是主控树莓派 Pico 是关节控制器摄像头和传感器负责感知。三者的分工必须一开始就明确不然代码写到最后全堵在主控上实时性会非常难看。2.1 树莓派本体怎么选5 代和 4B 的差距在哪树莓派58GB 版本是我目前最顺手的选择。四核 A76主频 2.4GHz同时跑 Node.js、Python 和摄像头采集程序还有不少余量。它对比树莓派4B 的最大提升是 USB 3.0 和 PCIe 接口如果你打算后续加 SSD 或者外接高速传感器5 代明显更合理。代价是功耗。树莓派5 对电源的要求是 5V/5A4B 只需要 5V/3A 甚至更低。机器人上电瞬间如果电机和树莓派共用一条电源线欠压重启几乎是必然的。所以我的做法是树莓派单独用一路电源电机驱动单独一路两路电源的地线连在一起共地。这个细节后面专门讲。树莓派4B 也不是不能玩。8GB 版本现在二手价格便宜很多如果你的项目以验证代码逻辑为主4B 完全够如果要做视觉识别加多个舵机控制我建议直接上 5 代。严格说这次的机器人用的是树莓派5但同样的代码在 4B 上跑也不会有什么本质区别。散热方面树莓派5 必须装风扇不然高负载下半分钟就会触发降频。我第一次用普通散热片满载直接冲到 85 摄氏度后来换成带转速反馈的 5V PWM 风扇才稳定在 60 摄氏度上下。风扇转速别追求拉满70% 左右足够噪音小很多还能保证系统稳定。2.2 电机和舵机用 Pico 当“关节控制器”而不是直接上 PWM最早我试着在树莓派上直接输出 PWM遇到一个很实际的问题当 CPU 负载升高时PWM 时序会抖动。树莓派跑的是 Linux不是实时系统当摄像头和网络请求同时抢占 CPUGPIO 输出的方波周期可能从 20ms 漂到 20.7ms舵机跟着一抖一抖偶尔还发出刺耳的尖叫声。解决方式有两种。一是外接 PCA9685 这样的 PWM 驱动模块通过 I2C 控制16 路输出几块钱一个。二是像我这样用树莓派 Pico 做关节控制器。Pico 是单片机跑 MicroPythonGPIO 的 PWM 精度由硬件保证不受主控负载影响。树莓派5 通过 UART 向 Pico 发送简短指令比如“SG90_CH1 180”或“MOTOR_A 45”Pico 解析后输出对应占空比。指令频率不高几毫秒一条哪怕 Claude 的回答延迟 1 秒关节执行依然平滑。这种分工让我想到工业机器人控制柜的架构控制柜里有独立的运动控制器芯片上位机只做轨迹规划底层实时插补交给专用芯片。我们用树莓派加 Pico虽然简陋但架构上是一致的。你如果只做一个小车不搞机械臂那用 PCA9685 就行。但我个人建议用 Pico因为它还能把超声波传感器、编码器这些实时性要求高的外设接在自己身上主控统一通过串口读写减少 IO 线缆的混乱。这里给出一个常见的引脚使用表方便你对照树莓派 40Pin 排针接线功能BCM 引脚物理引脚说明舵机信号 1GPIO1812PWM接舵机信号线电机使能GPIO1711电机驱动板 IN1电机方向GPIO2713电机驱动板 IN2UART TXGPIO148连接 Pico RXUART RXGPIO1510连接 Pico TXGNDGND6/14/20必须共地2.3 摄像头模块 OV5647 的坑和替代方案视觉部分我用的是 OV5647 模块入门级 CMOS 摄像头500 万像素带 CSI 接口兼容树莓派官方摄像头软件。这个摄像头对应的就是热搜词里那个“树莓派 ov5647 摄像头模块”。几个坑先说明白。第一树莓派5 的 CSI 接口和 4B 不一样老的摄像头排线是 15pin树莓派5 的 CSI 接口是 16pin。如果你从老设备上拆摄像头必须买一根专用的转接线不然排线插不进或者方向不对。第二Bookworm 系统默认使用 libcamera 框架老的raspistill命令已经废弃现在抓一帧图的命令是rpicam-still -o image.jpg或者直接用 Python 的 picamera2 库。第三OV5647 对光线敏感暗光环境下噪点较多如果预算允许直接换 IMX219 会好一些。传感器方面我保留了三个HC-SR04 超声波模块做前向避障一个 MPU6050 做姿态检测还有一个光敏电阻做环境亮度判断。接传感器之前务必确认逻辑电平。HC-SR04 的 ECHO 脚输出 5V但树莓派 GPIO 只能容忍 3.3V必须加分压电阻否则长期使用可能烧坏 GPIO。我第一次做的时候没加测试没烧但心里一直不踏实后来还是补上了两个 10k 电阻组成的分压电路。3. 软件准备系统、软件源、Claude Code 与 MCP硬件搭好之后接下来就是软件层面的事。这部分看起来是配置但问题很多尤其是树莓派上跑 Node.js 和 Claude Code 的组合网上的教程七零八落我这里把流程完整走一遍。3.1 树莓派系统准备和软件源优化系统建议用 Raspberry Pi OS Bookworm 64 位版本。既然要做机器人不需要桌面版装 Lite 版即可省下的内存留给摄像头和 Claude 的进程。装完系统第一件事是修改软件源不然apt update能卡到怀疑人生。在树莓派上改源很简单打开/etc/apt/sources.list.d/下的源文件把源地址换成可用的镜像站然后执行sudo apt update。注意 Bookworm 和旧版系统的源路径不同别只改一个文件就以为完事了检查一下 sources.list.d 目录下有没有其他源文件需要一起改。然后安装基础依赖sudo apt update sudo apt upgrade -y sudo apt install -y python3-pip git python3-picamera2 python3-serial # Node.js 20Claude Code 和 MCP 都需要 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs我之所以单独装 Node.js是因为 Claude Code 和很多 MCP 服务器是基于 npm 的。如果你只用 Python SDK不装 Node 也能跑但 Claude Code 这个终端工具在调试机器人时非常趁手后面我会详细说。3.2 Claude Code 的安装、VSCode 配置和常见问题安装 Claude Code 只有一条命令npm install -g anthropic-ai/claude-code然后用环境变量或登录方式配置 API 密钥。我的习惯是写进~/.bashrcexport ANTHROPIC_API_KEYsk-ant-xxxx执行claude就能进入交互式终端。你可以在这个终端里让它帮你分析日志、改代码也可以把 Claude 当成机器人的远程大脑直接下达自然语言任务。实际使用中我遇到三个高频问题Node 版本太旧。树莓派 OS 自带的 Node 版本往往是 18 以下Claude Code 会启动失败解决办法是先升级 Node 到 20 或 22。在 VSCode 的 Remote-SSH 会话里启动 Claude Code有时提示找不到claude命令。这是 PATH 问题SSH 会话默认不加载~/.bashrc里的环境变量手动执行export PATH/usr/bin:$PATH即可。VSCode 配置 Claude Code 时还要在扩展设置里指定 Node 路径。在线升级导致版本不一致。Claude Code 会自动更新如果你的网络不稳定更新一半就报错。解决办法是安装固定版本比如npm install -g anthropic-ai/claude-code1.3.5版本号按需填写。进入正式调试阶段固定版本比追新稳定得多。顺便说一句热搜词里提到“claude workspace requires the virtual machine platform on windows. enable”那是 Windows 上的问题树莓派是 Linux 系统不涉及虚拟化平台这一环。你在树莓派上装不上 Claude Code先检查 Node 版本和网络别被 Windows 的报错带偏。3.3 用 MCP 让 Claude 直接调用硬件控制器MCP 全名 Model Context Protocol本质上是给大模型提供标准工具总线。Claude Code 支持配置外部 MCP 服务器一个 MCP 服务器可以暴露一组工具Claude 在对话中自动判断何时调用这些工具调用完成后把结果并入上下文。最简单的 MCP 服务器就是利用现成的 npm 包。比如我想让 Claude 能读机器人目录下的传感器记录文件npx modelcontextprotocol/server-filesystem /home/pi/mydata然后在 Claude Code 里添加claude mcp add myfs -- npx modelcontextprotocol/server-filesystem /home/pi/mydata配置完成后Claude 就可以读取mydata目录下的记录文件并根据内容做出判断。更实用的是自己写一个控制舵机和电机的 MCP 服务器。工具定义大概是move_base(speed, duration)、turn(angle, duration)、read_distance()这几个函数。Claude 会自动选择并填充这些工具比如你输入“发现前方有障碍绕过它”它会先调用read_distance确认距离再调用turn和move_base完成绕行。这比解析自然语言文本再转 JSON 要可靠得多。不过有一点要注意MCP 适合 Claude Code 交互式使用但如果你要写一个长期运行的机器人控制脚本直接用 Anthropic Python SDK 里的 tool_use 更合适。控制循环里不该依赖终端交互而应该用 SDK 把请求发出去看返回的工具调用指令再执行。Claude Code 更像“命令行司令塔”Python SDK 才是“行车电脑”。4. 感知—决策—动作怎么把“想”变成“动”这一步是整个项目的核心也是最容易写崩的地方。很多人把 Claude 接进机器人后直接用最简单的死循环读一次传感器问一次 Claude执行一次动作。结果机器人反应迟钝撞墙前还在等模型回复。4.1 为什么必须有一个本地反射层如果你让 Claude 控制机器人最直接的想法是每秒把传感器数据发给它等它返回动作指令。理论可行实际上很危险。一次 API 调用通常花 1 到 3 秒等待期间机器人还在执行上一帧的指令。如果障碍物已经近在眼前Claude 还没反应过来机器人已经撞上去了。所以必须有一个本地反射层。这层不经过大模型直接用树莓派或 Pico 上的 GPIO 轮询传感器一旦距离小于阈值立即停车或转向完全绕开 Claude。Claude 只负责调整长期目标比如“从卧室走到客厅”而“前方 20 厘米突然出现一条腿”这种紧急情况由反射层就近处理。类比很容易理解你的大脑不会每秒都做膝跳反射的决策那是脊髓的事。Claude 是大脑皮层树莓派和 Pico 是脊髓。分层控制是具身智能的基本架构不管热搜里提到的“机器人导航”还是“slam机器人”最后都会回到这个分层逻辑上。4.2 把摄像头画面变成 Claude 的眼睛让 Claude 看到环境最简单的路径是传图片。Claude API 支持视觉输入直接传 base64 编码的图片就行。在树莓派上抓一帧图的代码from picamera2 import Picamera2 import base64, io, time picam Picamera2() picam.configure(picam.create_still_configuration()) picam.start() time.sleep(2) buf io.BytesIO() picam.capture_file(buf, formatjpeg) buf.seek(0) img_b64 base64.b64encode(buf.getvalue()).decode()然后把img_b64放进 API 请求并给它一个严格的 system prompt要求返回结构化 JSON{ summary: 房间中有一张桌子和一个水杯, action: move_forward, parameter: {distance_cm: 30} }这里有几个实操要点。第一视频流不用每帧都送给 Claude我看到障碍物再抓帧都来得及通常每 3 到 5 秒送一帧就够了。第二图片分辨率不要太高800x600 就够分辨率越高 API 延迟越高对机器人决策并没有明显帮助。第三system prompt 里必须规定动作枚举只能返回move_forward、move_back、turn_left、turn_right、stop这几种模型在封闭选项里做决定错误率远低于自由文本。4.3 工具调用与结构化输出让模型输出直接驱动 GPIO用 Python SDK 实现工具调用的流程是先定义工具列表每个工具是一个 JSON Schema然后摄像头画面加传感器数据丢给 Claude让它决定调用哪个工具最后拿到 API 返回的tool_use块解析参数并执行。工具定义示例tools [ { name: move_base, description: 移动底盘指定距离, input_schema: { type: object, properties: { direction: {type: string, enum: [forward, backward]}, distance_cm: {type: integer, minimum: 5, maximum: 200}, speed: {type: integer, enum: [30, 60, 100]} }, required: [direction, distance_cm] } } ]我强烈建议一件事不要直接让 Claude 控制单个舵机角度而是给它高层动作原语比如“向前走 50 厘米”“左转 30 度”。高层原语在本地封装了电机控制和里程修正模型不用管底层细节调用也稳定得多。这就是语义动作接口把物理世界抽象成机器人能执行的指令集。动作执行的底层代码以电机为例import RPi.GPIO as GPIO import time GPIO.setmode(GPIO.BCM) in1, in2, pwm_pin 17, 27, 18 GPIO.setup(in1, GPIO.OUT) GPIO.setup(in2, GPIO.OUT) GPIO.setup(pwm_pin, GPIO.OUT) p GPIO.PWM(pwm_pin, 1000) p.start(0) def move_forward(speed, seconds): GPIO.output(in1, GPIO.HIGH) GPIO.output(in2, GPIO.LOW) p.ChangeDutyCycle(speed) time.sleep(seconds) stop()如果你用的是 Pico就把这段代码移植到 MicroPython 上再通过 UART 接收指令。整体架构不变只是执行端从树莓派 GPIO 变成了 Pico 引脚。5. 实测踩坑串口、风扇、电源和 Claude 客户端升级这部分是真正的干货也是我最想写的内容。以下问题全部来自真实调试每一个都让我浪费了不止一个晚上。5.1 树莓派5 串口和引脚问题UART 被蓝牙和系统控制台占用我用树莓派5 和 Pico 通信第一个踩的坑是串口设备名。树莓派 OS 默认把串口分配给蓝牙或系统控制台你写代码时发现/dev/ttyAMA0和/dev/ttyS0哪个都不稳定。解决方法是通过sudo raspi-config进入 Interface Options开启 Serial Port关闭 Serial Console然后重启。重启后执行ls /dev/ttyAMA*通常能看到/dev/ttyAMA0。注意树莓派5 的 PL011 和 mini UART 映射与 4B 不完全一样代码里不要硬编码设备名用环境变量SERIAL_PORT/dev/ttyAMA0以后切换板子只改一个变量。还有一个容易忽略的问题GPIO 电平。树莓派 GPIO 工作电平是 3.3VPico 也是 3.3V直接对接没问题。但如果你买的是 5V 舵机驱动板串口电平不匹配偶尔会收到乱码或通信中断这时需要加一个 3.3V 转 5V 的电平转换模块。5.2 机器人一动就重启电源问题排查链路这是最普遍的问题我 debug 最久。现象是树莓派正常启动但只要电机一转系统很快重启或者屏幕角落出现黄色闪电图标提示欠压。排查思路如下。第一测总线的实时电压。用带电压显示的 USB 电流表就能看接上电机后发现电压从 5.1V 瞬间掉到 4.2V这就是电源容量不够。树莓派5 满载可能吃掉 5V/3A 以上电机启动瞬间还要额外 2 到 3A一只勉强够用的电源根本供应不了。第二分两路供电。树莓派接一路用官方 5V/5A 电源或质量过硬的大功率电源电机和舵机接另一路用独立的 5V 大电流电源。两组电源的地线必须连在一起也就是共地不然 GPIO 信号没有参考地通信波形会乱指令执行错误率飙升。第三如果是电池供电方案可以在电机电源端并联一个 1000uF 以上的电解电容吸收启动浪涌。但双路独立电源依然是首选电容只能缓解症状治不了根。5.3 风扇转速和散热别把跑飞的车当成机器人大脑我在树莓派5 上用的风扇带转速反馈线系统可以通过 GPIO 读取 RPM。一开始风扇直接接 5V 常转声音很吵。后来在/boot/config.txt里配置了 PWM 控制50 度以下停转50 到 70 度之间低速转超过 70 度全速转。这里有个坑树莓派5 的官方风扇接口是 4pin PWM但很多第三方的 3pin 风扇插上去只能开或关没有转速反馈。如果你的程序一直读不到风扇转速先确认风扇是否真的带测速线别把电源线当测速线。另一个问题风扇转速周期性跳动通常是 PWM 频率设置太低导致的。把 PWM 频率提高到 25kHz 以上听不到噪音读数也会稳定很多。运行时看到温度异常升高先检查风扇是否被异物卡住再检查散热片是否贴紧。机器人在运行过程中振动散热片会慢慢松动我有一次就是散热片掉了温度直接飙到 80 度。5.4 Claude 客户端安装失败与升级管理在树莓派上安装 Claude Code最常见失败原因是 Node 版本太旧、npm 缓存权限不对或者 PATH 没配好。这三个问题分别在前面 3.2 节说过了这里不再重复。升级管理方面我再强调一次Claude Code 会自动更新网络差的时候千万不要在机器人跑任务时后台升级。升级导致进程重启对话上下文会丢失任务规划到一半就断了。我的做法是在机器人启动脚本里锁定版本执行npm install -g anthropic-ai/claude-code1.3.5固定版本等任务跑完再手动升级。如果你有多个机器人节点建议做出统一的版本策略不然线上设备行为不统一排查问题会非常痛苦。6. 从玩具到工具四条值得走的扩展路线写到这项目其实已经可以稳定跑起来了。但我个人觉得树莓派加 Claude 的乐趣不在于“跑通”而在于后面还能长出多少花样。这里给出四个我目前在折腾的方向也是热搜里反复出现的关键词。6.1 接上 SLAM让 Claude 拥有空间记忆现在这个机器人能感知前方障碍但没有空间地图。下一步可以加一个 2D 激光雷达模块跑 SLAM 建图把地图数据提供给 Claude。当你在对话里问“客厅里有哪些东西”它可以调用地图模块返回房间布局再结合摄像头判断具体物品。这个组合对应“slam机器人”和“机器人导航”两个方向。树莓派5 的算力跑小型 SLAM 绰绰有余配上低成本雷达再选一个建图算法就能出 2D 栅格地图。Claude 作为导航目标规划器告诉它“去厨房”它会计算目标点把导航目标发给路径规划模块剩下的路径搜索和避障由导航框架自己完成。这样Claude 不再只是做短时决策而是开始拥有空间记忆。6.2 具身机器人的训练和部署框架怎么选很多人问“具身机器人训练部署用什么框架”。我的经验是如果做演示和教学ROS2 是最大众化的选择如果只是这个树莓派项目不一定要上 ROS自己写一个简单的感知—决策—动作循环就够了。真正需要框架的时候通常是你同时要管理多个模块摄像头节流、传感器订阅、任务调度、日志回放。这时再引入 ROS2 或者更轻量的通信中间件把 Claude 当作一个独立节点接入系统。不必一上来就套框架先把手动管线跑通再考虑框架化。否则框架本身造成的调试负担可能比项目本身还大。6.3 向工业方案借一步想法工业机器人方向ABB、法奥这类协作机器人都使用独立控制柜控制柜内部是专用运动控制卡加实时总线。我们这套“树莓派加 Pico 加 Claude”的方案本质上也是分层控制只是实时层弱一些。如果想往真实应用走可以做个抽象层把 Claude 的规划结果通过标准接口导出让工业控制柜拾取形成“Claude 提供任务级智能工业控制柜执行运动级控制”的混合架构。这个想法现在还有点超前但值得持续跟进。6.4 低成本的传感器玩法如果你不想做复杂的导航也可以给机器人加一些便宜好玩的传感器。比如相扑机器人用的触须传感器两枚简单的微动开关接在车头左右两侧遇到碰撞就能精确判断来自哪个方向成本几乎为零。再比如光敏电阻判断室内明暗让 Claude 在晚上自动把机器人切换成巡视模式。如果你做管道机器人类似的东西Claude 的优势是分析管道内壁图像并发现异常不必一个个写死规则。这些玩法不复杂但能让 Claude 和物理世界的交互维度一下子丰富起来。我认为具身探索最有意思的地方就在这里大模型的智能加上一个不贵的身体就能组合出很多意想不到的应用。整套项目从硬件组装到软件跑通大概花了我两个周末。最大的教训是先想清楚“什么是实时响应什么是认知决策”再动手写代码不然会在中断、线程、串口乱码里反复失踪。我给自己的建议是永远保留一条人工遥控备降通道——当 Claude 突然陷入思考循环或 API 超时时按一个物理急停按钮立刻切断电机电源。这不只是为了安全也是让实验能持续下去的基础。