一分钟速览
- Claude Code 官方支持 Linux ARM64、内存 4 GB 起步——只要跑 64 位 Raspberry Pi OS,树莓派 4 / 5 都满足文档要求。
- 一条命令即可安装:curl -fsSL https://claude.ai/install.sh | bash,全程不需要 Node.js;只有走 npm 路线才要求 Node.js 22 以上。
- 首次开机前先在 Imager 里打开 SSH——就是这个开关,把树莓派变成以后全靠笔记本远程管理的无头助手。
- 用 Claude 订阅或 API 计费登录,日常任务切到 Haiku 省用量,把大模型留给真正的硬骨头。
Installing Claude Code on a Raspberry Pi (full agent setup walkthrough)
频道:Jason Welsh31:02
Running Claude Code on a Raspberry Pi
频道:akash.gg
Setup — official documentation
官方文档:code.claude.com/docs
本页的每一条系统要求、每一条命令和参数都核对过官方安装文档与 akash.gg 的《Running Claude Code on a Raspberry Pi》博文;上方视频是画面来源。
所有截图均署名原作者并深链到对应时间点,未使用任何人脸镜头。
从一张空 SD 卡到能干活的 Pi 助手
第一部分:备好树莓派和 SD 卡
- 1
用 Imager 烧录 64 位 Raspberry Pi OS
在一台常用电脑上安装 Raspberry Pi Imager,选好板子(4 GB 内存以上的 Pi 4 或 Pi 5 满足 Claude Code 官方的 ARM64、4 GB 内存要求),选择 Raspberry Pi OS(64 位)镜像,再选中你的 SD 卡。64 位镜像是这里唯一不能选错的一项——ARM64 版本的 Claude Code 跑不了 32 位系统。
在 Imager 里选板子,Pi 4 / Pi 5 都符合要求。看第 3:12 处 - 2
开机前先打开 SSH
在 Imager 的系统定制页设置用户名和密码、预填 Wi-Fi,并把 Enable SSH 打开。视频作者反复强调这一步「非常重要」,原因很简单:有了 SSH,之后才能拔掉显示器和键盘,全程用笔记本管理树莓派。
现在把 SSH 打开,以后省心。看第 4:16 处 - 3
首次开机,确认 64 位
推出 SD 卡插到树莓派上,通电启动,看到 Raspberry Pi OS 桌面欢迎画面就说明镜像没问题。如果接电视时字小得看不清,打开首选项里的 Screen Configuration,把 HDMI 分辨率调成 1024×768 一档,再点 Apply。
看到 64 位欢迎画面,说明镜像烧对了。看第 7:00 处 - 4
先要一份安装计划
在树莓派的浏览器里登录 claude.ai,让 Claude 给出「全新系统一步步安装 Claude Code」的步骤。这步可以跳过、直接用第 6 步的官方命令——不过照着屏幕上的计划走,确实更省心。
让 Claude 列计划,或者直接看第 6 步的命令。看第 12:00 处
第二部分:安装与授权
- 5
先把系统更新到位
打开终端,执行 sudo apt update && sudo apt full-upgrade -y。新镜像往往能拉出几十个 arm64 软件包,花上几分钟很正常。
新系统一上来就能更新出一大串包。看第 13:50 处 - 6
跑官方安装命令
一条命令装好 Claude Code:curl -fsSL https://claude.ai/install.sh | bash。这条路完全不需要 Node.js。(更习惯 npm?先装 ARM64 版 Node.js 22 以上,再执行 npm install -g @anthropic-ai/claude-code;官方文档明确提醒不要加 sudo。)
一行命令装完,这是官方推荐路径。看第 13:00 处 - 7
补上 PATH 并验证
安装器结束时会给出版本号和二进制位置。如果提示该目录不在 PATH 里,按它打印的命令把 export 追加进 .bashrc,再 source ~/.bashrc。最后跑一下 claude --version 确认。
安装成功的横幅,外加可能需要的 PATH 修复。看第 16:30 处 - 8
授权登录 Claude 账号
在项目目录里运行 claude,选个主题,然后选 Claude account with subscription(走 API 计费就选 Anthropic Console)。树莓派的浏览器会弹出授权页,点 Authorize,回到终端按回车。
授权页直接出现在树莓派自己的浏览器里。看第 17:05 处
第三部分:调优并转向无头模式
- 9
切到 Haiku 省用量
在树莓派上,大模型留给硬骨头。输入 /model 选 Haiku 处理日常配置和脚本——视频里登录完第一件事就是这个。需要时随时切回 Sonnet 或 Opus。
日常任务交给 Haiku,订阅用量更耐花。看第 18:30 处 - 10
拔掉线缆,用 SSH 远程
现在可以撤掉训练轮了:第 2 步开过 SSH,拔掉 HDMI 和键盘,在笔记本上 ssh 用户名@树莓派IP 登进去。还可以让 Claude Code 自查:「make sure SSH is fully working and what is my login and IP」——它会自己跑 whoami、查 IP 并确认 ssh 服务状态。想彻底无头,先在有浏览器的电脑上用 claude setup-token 生成长期令牌,再到树莓派上导出为 CLAUDE_CODE_OAUTH_TOKEN。
让 Claude 自己检查 SSH 配置,顺便报出 IP。看第 19:30 处 - 11
让这个 Pi 助手干活
装好之后,你就有了一台随时在线、功耗只有几瓦的编程助手:维护家里的自托管服务、SSH 到别的机器上改配置、编写并排期 rsync 备份、cron 定时任务这类运维脚本,或者给硬件项目里的微控制器写代码。从小事开始,盯紧它执行的每条命令,建立信任后再逐步放开权限。
哪些树莓派真能跑 Claude Code?
Claude Code 提供 ARM64 版本,官方底线是 4 GB 内存、Debian 10+ / Ubuntu 20.04+ 系的发行版。翻译成树莓派的型号语言:
- 1树莓派 5(4 / 8 / 16 GB)——最从容的选择,体验接近一台小笔记本。
- 2树莓派 4(4 GB 及以上)——本页攻略视频用的就是 Pi 4B,日常任务搭配 Haiku 很够用。
- 3树莓派 500 / 400——键盘一体形态内置 4 / 8 GB ARM64 内存,同样满足官方要求。
- 4树莓派 3、Zero 2 W 及更早——只有 1 GB 或 512 MB 内存,还常用 32 位镜像,低于官方规格,别把它们当支持目标。
- 5计算模块 CM4 / CM5——内存 4 GB 以上的型号同样符合要求,安装流程没有任何树莓派特有的障碍。
不确定手里的板子什么情况?跑一下 uname -m:输出 aarch64 就是安装器针对的 64 位 ARM;输出 armv7l 说明是 32 位系统,先用 64 位 Raspberry Pi OS 重新烧录。
树莓派安装翻车?对症下药
树莓派上的失败基本逃不出下面几类:
- 1装完提示 claude: command not found——二进制被放进了 ~/.local/bin,而这个目录还不在 PATH 里。按安装结束时的提示(第 7 步)追加 export 命令,重开终端即可。
- 2npm 安装时报 EBADENGINE——Node.js 低于要求的 22 版。要么升级树莓派上的 Node.js,要么改用 curl 安装器,它根本不经过 npm。
- 3安装或启动直接失败——先确认烧的是 64 位 Raspberry Pi OS;32 位系统跑不了 ARM64 版本,正如视频里那句「选 64 位,不然跑不起来」。
- 4千万别 sudo npm install -g——官方文档专门点名,会带来权限和安全问题;用原生安装器,或者修好 npm 的全局目录。
- 5无头机器上没有浏览器——OAuth 授权需要浏览器。先在有浏览器的机器上完成登录,或者用 claude setup-token 生成长期令牌,在树莓派上导出 CLAUDE_CODE_OAUTH_TOKEN。
还是卡住?把报错原文贴回给 Claude Code 自己(必要时在另一台机器上贴)——视频演示的核心工作流正是如此:先说清目标,然后反复贴报错,直到跑通。