1. 为什么要在树莓派上跑 OpenClaw AI Agent
OpenClaw 是一套面向 AI Agent 场景的运行框架，它和普通聊天机器人的区别在于：在获得授权后，它可以读写文件、执行脚本、调用网络服务，甚至通过 GPIO 和传感器与物理世界交互。Raspberry Pi 则是一台功耗低、接口全、系统开放的边缘计算设备。把这两者放在一起，你得到的是一台能长期在线、能碰硬件、能自己执行任务的本地 AI Agent 节点。
我第一次把 OpenClaw 跑在树莓派 4B 上时，最直观的感受是：它不像云端服务那样需要一直联网等待响应，很多任务可以在本地闭环完成。比如定时读取温湿度传感器、整理下载目录、根据摄像头画面触发通知，这些都不需要把数据传到远端。对于边缘计算爱好者和嵌入式开发者来说，这种“AI 能力下沉到设备”的路径，比单纯调用云端 API 更有意思，也更可控。
这篇文章面向的是已经有一台树莓派、想动手把 AI Agent 真正跑起来的人。我会从系统准备、依赖安装、OpenClaw 配置、模型接入，到一次本地任务触发和日志验证，完整走一遍。过程中会给出可复制的命令和配置片段，也会说明我踩过的坑。你不需要是 Linux 专家，但需要能通过 SSH 或终端操作树莓派。
需要先明确一点：OpenClaw 本身是 Agent 框架，它需要一个大模型来提供推理能力。树莓派本地跑大模型不是不行，但 4B/5 的算力和内存有限，实际体验更好的方式是让 OpenClaw 通过 API 调用远端模型，把“思考”交给模型服务，把“执行”留在树莓派本地。这样既保留了边缘设备的硬件交互能力，又不会把树莓派压垮。后面我会用 TaoToken 作为模型接入层来演示，因为它兼容 OpenAI 风格的接口，配置起来比较直接。
在开始之前，先确认你的树莓派满足这些条件：Raspberry Pi 4B（4GB 及以上）或 Raspberry Pi 5，系统建议用 64 位 Raspberry Pi OS Bookworm，存储至少 16GB，并且已经能正常联网。如果你用的是 Zero 系列，内存会非常紧张，跑 Agent 框架会比较吃力，不建议作为第一台实验设备。
2. TaoToken 前置准备：拿到 Base URL、Key 和 Model ID
OpenClaw 要调用模型，就需要三个东西：接口地址（Base URL）、API Key、模型 ID。这三个缺一不可，而且必须和你的接入方式匹配。我见过不少人卡在第一步，不是 Key 错了，就是 Base URL 多写了路径，或者模型 ID 写成了展示名称。
TaoToken 的 API 地址是https://taotoken.net/api，注意这里不要加 UTM 参数，接口调用只需要干净的域名和路径。API Key 需要你在控制台里创建，创建后只显示一次，复制下来保存好。模型 ID 则取决于你要用哪个模型，通常在你选择模型的地方能看到对应的标识符。
具体操作路径是这样的：先打开https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite创建 API Key，然后在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite查看接口文档，确认 Base URL 和请求格式。如果你还不确定选哪个模型，可以到https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite里看看可用模型列表。
这里有一个容易混淆的点：Base URL 到底是https://taotoken.net/api还是https://taotoken.net/api/v1？这取决于 OpenClaw 或你使用的客户端如何拼接路径。大多数 OpenAI 兼容客户端会在 Base URL 后面自动加上/v1/chat/completions，所以 Base URL 填https://taotoken.net/api就够了。如果你填成https://taotoken.net/api/v1，有些客户端会拼成/api/v1/v1/chat/completions，直接 404。我建议先用文档里的示例请求测通，再写进 OpenClaw 配置。
另外，API Key 不要直接写死在代码里提交到 Git。树莓派上可以用环境变量，或者放在只有当前用户可读的配置文件里。后面配置 OpenClaw 时我会给出具体做法。
如果你打算长期在树莓派上跑编码类或 Agent 类任务，可以了解一下 Coding Plan，它更适合持续性的开发场景：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite。不过对于本文的验证流程，普通 API Key 就足够了。
在继续之前，请确保你已经在树莓派上能通过curl访问外网。可以执行一条最简单的测试命令，确认网络和 DNS 正常。如果这一步不通，后面所有配置都会失败。
3. 可复制配置：在树莓派上安装并启动 OpenClaw
这一节是全文的核心，我会给出从系统依赖到 OpenClaw 启动的完整步骤。你可以直接复制命令，但要注意根据自己的系统版本和路径做微调。
首先更新系统并安装基础依赖。树莓派上很多 Python 包需要编译工具，提前装好可以避免后面报错：
sudo apt update sudo apt upgrade -y sudo apt install -y python3 python3-pip python3-venv git curl build-essential libssl-dev libffi-dev python3-dev确认 Python 版本，建议 3.10 以上：
python3 --version接下来为 OpenClaw 创建独立的虚拟环境。不要直接装在系统 Python 里，否则依赖冲突会让你很头疼：
mkdir -p ~/openclaw && cd ~/openclaw python3 -m venv venv source venv/bin/activate虚拟环境激活后，命令行前面会出现(venv)。然后安装 OpenClaw。具体包名以官方文档为准，这里以常见的 pip 安装方式为例：
pip install --upgrade pip pip install openclaw如果安装过程中出现编译错误，多半是缺少系统库。树莓派上常见的是libjpeg-dev、zlib1g-dev这类，按报错提示补装即可。
安装完成后，创建配置目录和配置文件。OpenClaw 的配置通常是一个 JSON 或 TOML 文件，下面给出一个可复制的 JSON 配置示例，路径放在~/.openclaw/config.json：
{ "model": { "provider": "openai-compatible", "base_url": "https://taotoken.net/api", "api_key": "sk-你的实际Key", "model_id": "你的模型ID", "timeout": 60 }, "agent": { "name": "pi-edge-agent", "workspace": "/home/pi/openclaw/workspace", "max_steps": 10, "allow_shell": true, "allow_file_write": true }, "logging": { "level": "info", "file": "/home/pi/openclaw/logs/agent.log" } }注意几个关键字段：base_url填https://taotoken.net/api，不要带尾部斜杠；api_key换成你在控制台创建的真实 Key；model_id填模型标识符，不是展示名称。workspace是 Agent 的工作目录，建议单独建一个，不要直接指向用户主目录，避免误操作。
如果你不想把 Key 明文写在配置里，可以用环境变量。在~/.bashrc或 systemd 服务里设置：
export OPENCLAW_API_KEY="sk-你的实际Key"然后在配置里把api_key写成"${OPENCLAW_API_KEY}"，具体是否支持变量替换要看 OpenClaw 版本。如果不支持，就老老实实放在权限为 600 的文件里：
chmod 600 ~/.openclaw/config.json创建日志和工作目录：
mkdir -p ~/openclaw/logs ~/openclaw/workspace现在可以尝试启动 OpenClaw。先在前台运行，方便看日志：
openclaw run --config ~/.openclaw/config.json如果启动成功，你会看到 Agent 初始化、模型连接、工具注册之类的日志。如果报错，先别急着改配置，把错误信息完整读一遍。下一节我会列出常见错误和排查方法。
为了让 OpenClaw 在树莓派上长期稳定运行，建议用 systemd 托管。创建一个服务文件/etc/systemd/system/openclaw.service：
[Unit] Description=OpenClaw AI Agent After=network-online.target Wants=network-online.target [Service] Type=simple User=pi WorkingDirectory=/home/pi/openclaw Environment="OPENCLAW_API_KEY=sk-你的实际Key" ExecStart=/home/pi/openclaw/venv/bin/openclaw run --config /home/pi/.openclaw/config.json Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target然后启用并启动：
sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw sudo systemctl status openclaw用 systemd 的好处是崩溃后会自动重启，树莓派断电重启后也会自动拉起。对于边缘设备来说，这一点很重要，因为你不可能每次都手动登录去启动服务。
4. 验证请求：触发一次本地任务并检查日志
配置写好了，服务也起来了，但怎么确认 Agent 真的在工作？最直接的方式是触发一次本地任务，然后看日志和输出。这一节我会用一个简单的文件整理任务来演示。
首先确认 OpenClaw 服务正在运行：
sudo systemctl status openclaw如果状态是active (running)，说明进程活着。接着看实时日志：
sudo journalctl -u openclaw -f现在打开另一个终端，进入 OpenClaw 的工作目录，准备一个测试文件：
cd ~/openclaw/workspace echo "temperature=24.5 humidity=61" > sensor_readme.txt echo "device=pi4b status=ok" > device_info.txt然后通过 OpenClaw 的命令行接口触发一个任务。具体命令取决于 OpenClaw 的 CLI 设计，常见形式是：
openclaw task "读取 workspace 下的 txt 文件，汇总内容并生成一份 report.md"如果 OpenClaw 支持交互模式，也可以直接进入：
openclaw chat --config ~/.openclaw/config.json然后在对话里输入任务描述。Agent 应该会执行类似这样的步骤：列出目录、读取文件、调用模型生成汇总、写入report.md。你可以在日志里看到每一步的工具调用记录。
验证结果：
cat ~/openclaw/workspace/report.md如果文件存在且内容合理，说明 Agent 的“模型推理 + 本地执行”链路是通的。同时检查日志文件：
tail -n 50 ~/openclaw/logs/agent.log日志里应该能看到模型请求的耗时、工具调用的参数和返回。如果日志里出现choices相关的解析错误，说明模型返回格式和客户端预期不一致，下一节会讲。
为了更贴近边缘设备场景，可以再做一个 GPIO 相关的验证。前提是你已经装了gpiozero或RPi.GPIO，并且 Agent 有权限访问 GPIO：
pip install gpiozero然后触发任务：
openclaw task "读取 GPIO 17 的电平状态，并写入 gpio_status.txt"如果 Agent 能正确调用 Python 脚本并返回结果，说明它已经具备和硬件交互的能力。这一步不需要真的接传感器，用跳线把 GPIO 17 接高或接低就能看到变化。
验证完成后，建议把测试文件清理掉，保持工作目录干净。长期运行时，工作目录里的文件会越来越多，最好定期归档或清理。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
这一节列出我在树莓派上部署 OpenClaw 时真实遇到过的报错，以及对应的排查思路。你如果卡住了，可以先在这里找找。
401 Unauthorized：这是最常见的错误，基本可以确定是 API Key 问题。先检查 Key 是否复制完整，有没有多余空格或换行。然后确认 Key 没有过期或被禁用。如果 Key 没问题，检查 Base URL 是否正确。有些客户端会把 Base URL 和路径拼错，导致请求发到了错误的端点。你可以用 curl 直接测：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"你的模型ID","messages":[{"role":"user","content":"ping"}]}'如果这条命令返回 401，那就是 Key 或权限问题；如果返回正常，那就是 OpenClaw 配置里的 Base URL 或请求格式有问题。
local proxy failed：这个错误通常出现在客户端尝试走本地代理，但代理没有启动或端口不对。如果你没有配置代理，检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY之类的设置。树莓派上有些系统镜像会预置代理配置，导致请求被转发到不存在的本地端口。用env | grep -i proxy看一下，如果有，取消掉再重启服务。
reading choices 相关错误：这类报错通常是模型返回的 JSON 结构和客户端预期不一致。比如客户端期望choices[0].message.content，但实际返回里没有choices字段，或者字段名不同。先确认你用的模型 ID 是否支持 OpenAI 兼容格式。如果模型返回的是流式数据，而客户端按非流式解析，也会出问题。可以在配置里关闭流式，或者换一个兼容性更好的模型。
OAuth 相关报错：如果你用的是需要 OAuth 授权的客户端，比如某些编码工具，报错可能出现在 token 刷新环节。这类问题通常和系统时间有关。树莓派如果没有 RTC 电池，断电后时间会错乱，导致 OAuth token 校验失败。先同步时间：
sudo apt install -y ntpdate sudo ntpdate pool.ntp.org然后确认时区正确：
timedatectl如果 OpenClaw 本身不需要 OAuth，而是用 API Key，那就不用管这类报错。但如果你同时装了其他工具，比如 Claude Code 或 Cline，它们可能会走 OAuth 流程，报错信息会混在一起，需要分开排查。
另外，如果你在配置里同时用了 CC Switch、Cline MCP 或 Codex 的auth.json，一定要确保三件套完整：Base URL、Key、Model ID。缺任何一个都会导致连接失败。特别是auth.json这种文件，格式要求严格，多一个逗号都会解析失败。建议用python -m json.tool auth.json检查格式。
最后，树莓派的资源限制也可能导致一些看似奇怪的错误。比如内存不足时，Python 进程被 OOM Killer 杀掉，日志里可能只留下一句模糊的报错。用dmesg | tail看看有没有 OOM 记录。如果是内存问题，可以减少 Agent 的max_steps，或者换用更轻量的模型。
6. 把 Agent 留在边缘：长期运行与接入建议
树莓派跑 OpenClaw，真正的价值不在于跑分，而在于它能长期待在一个真实环境里，持续做那些不需要人盯着的小事。我现在的用法是让它每天定时汇总传感器数据、整理下载目录、在摄像头检测到变化时发通知。这些任务都不复杂，但放在云端要么成本高，要么涉及数据外传，放在本地就刚刚好。
如果你准备长期运行，有几个实用建议。第一，给树莓派配一个稳定的电源和散热，Agent 持续调用模型时 CPU 会有负载，过热会降频。第二，日志要轮转，不然agent.log会越来越大，可以用logrotate配置。第三，工作目录定期备份，尤其是 Agent 生成的文件，万一 SD 卡坏了还能恢复。第四，API Key 定期轮换，不要一个 Key 用到底。
模型接入方面，如果你主要做验证和轻量任务，用普通 API Key 就够了。如果后面要跑更长时间的编码或 Agent 任务，可以看看 Coding Plan，它在持续调用场景下更合适：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite。需要对话调试模型时，可以用模型对话页面：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite。如果你用 Claude Code 这类工具接入，可以参考 Anthropic 兼容配置：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite。
最后一步，确认你的 systemd 服务在重启后能自动恢复：
sudo reboot重启后等一分钟，重新登录，执行：
sudo systemctl status openclaw如果状态是active (running)，并且日志里有新的启动记录，说明你的边缘 Agent 已经可以无人值守运行了。到这里，OpenClaw 在树莓派上的配置与验证就完成了。接下来你可以把传感器、摄像头、GPIO 设备接上去，让 Agent 真正开始和物理世界打交道。
