1. 为什么要在树莓派上跑 OpenclawOpenclaw 是一套面向边缘设备的 AI 工具链运行时它把模型调用、工具编排、本地任务执行整合在一个轻量进程里。你可以在树莓派这种功耗低、常年开机的小盒子上跑它用来做家庭自动化里的自然语言指令解析、局域网内的文档问答、或者给自建服务加一个对话入口。适合谁适合手头有 RaspberryPi 3B/4B/5、想折腾边缘 AI、又不想把每台设备都单独维护一套模型密钥的人。真正上手后第一个卡点往往不是 Openclaw 本身而是模型接入。树莓派上跑本地大模型对 3B 来说太重4B 勉强5 才舒服所以多数人会选择走云端 API。问题来了Openclaw 的配置文件里要填 base_url、api_key、model 三样东西如果你同时用几个模型供应商每换一个就要改一次配置、重启一次服务在树莓派上反复 ssh 进去改文件非常烦。我试过把不同供应商的 Key 硬编码在 config.toml 里结果就是配置文件越写越长还容易把 Key 提交到 git。后来改成用 TaoToken 做统一入口一个 Key、一个 base_url 覆盖多个模型config.toml 骨架固定下来基本不用动。这篇就把这套配置骨架、环境变量写法和连通性验证命令完整交付出来你照着改 IP 和 Key 就能跑。2. TaoToken 前置统一 Key 与通道准备TaoToken 在这里扮演的角色是「统一模型网关」Openclaw 只认一个 OpenAI 兼容的 base_url 和一个 Key背后具体调哪个模型由请求里的 model 字段决定。这样树莓派上的配置就稳定了换模型不用改接入层。你需要先拿到两样东西API Key 和确认 base_url。Key 在控制台的 API Keys 页面创建建议给树莓派单独建一个 Key方便日后按设备吊销。base_url 用https://taotoken.net/api注意这个地址不带任何查询参数直接写进配置即可。创建 Key 的入口在这里控制台 API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenclaw_rpi接入文档OpenAI 兼容写法、model 名称列表在这里配置前建议扫一眼确认当前可用的模型标识接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenclaw_rpi关于 Key 的存放我的建议是不要写进 config.toml。Openclaw 支持从环境变量读取树莓派上把 Key 放进 systemd 的 EnvironmentFile 或者~/.openclaw/env权限设成 600比明文躺在配置文件里安全得多。下面第三节会给出两种写法。3. 可复制的 config.toml 配置骨架先确认 Openclaw 的配置目录。默认在~/.openclaw/config.toml如果你用 systemd 跑工作目录可能不同用openclaw --print-config-path确认一下最稳。3.1 基础骨架下面这份骨架覆盖了模型接入、超时、重试三个最常调的块。把api_key那行留空走环境变量注入# ~/.openclaw/config.toml [server] host 0.0.0.0 port 8787 log_level info [model] # 统一走 TaoToken 的 OpenAI 兼容通道 provider openai-compatible base_url https://taotoken.net/api api_key # 留空由环境变量 OPENCLAW_API_KEY 注入 model claude-sonnet-4-20250514 timeout_seconds 60 max_retries 3 [model.params] temperature 0.3 max_tokens 2048 [tools] enable_shell false enable_http true workdir /home/pi/openclaw-workspace几个参数说明。provider固定写openai-compatibleTaoToken 的接口按 OpenAI 格式对齐Openclaw 用这个 provider 就能直接对接。timeout_seconds在树莓派上别设太小3B 处理 TLS 握手偏慢60 秒比较稳。max_retries设 3边缘网络抖动时能自动重试。3.2 环境变量写法方式一直接 export适合手动调试export OPENCLAW_API_KEYsk-你的TaoToken密钥 export OPENCLAW_BASE_URLhttps://taotoken.net/api方式二写进 env 文件适合 systemd 常驻。先建文件并收紧权限mkdir -p ~/.openclaw cat ~/.openclaw/env EOF OPENCLAW_API_KEYsk-你的TaoToken密钥 OPENCLAW_BASE_URLhttps://taotoken.net/api EOF chmod 600 ~/.openclaw/env然后在 systemd unit 里引用# /etc/systemd/system/openclaw.service [Unit] DescriptionOpenclaw edge runtime Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple Userpi WorkingDirectory/home/pi EnvironmentFile/home/pi/.openclaw/env ExecStart/usr/local/bin/openclaw serve --config /home/pi/.openclaw/config.toml Restarton-failure RestartSec5 [Install] WantedBymulti-user.target重载并启动sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclaw --no-pager3.3 多模型切换的写法如果你想让树莓派按任务类型选模型可以在 config.toml 里定义 profile请求时指定[model.profiles.fast] model claude-haiku-4-20250514 max_tokens 1024 [model.profiles.smart] model claude-sonnet-4-20250514 max_tokens 4096这样轻量任务走 fast复杂推理走 smartKey 和 base_url 还是同一套不用改接入层。4. 验证请求与成功结果配置写完别急着上业务先做三层验证网络通、鉴权通、模型通。第一层确认树莓派能到 TaoTokencurl -sS -o /dev/null -w %{http_code}\n https://taotoken.net/api返回 401 或 404 都说明网络可达因为没带 Key如果卡住或报Could not resolve host先查 DNS 和路由。第二层带 Key 发一个最小对话请求curl -sS https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $OPENCLAW_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 只回复两个字通了}], max_tokens: 16 }成功时你会拿到一段 JSONchoices[0].message.content里是模型回复。如果返回401是 Key 问题返回404多半是 model 名称写错去接入文档核对。第三层让 Openclaw 自己跑一次自检openclaw doctor --config ~/.openclaw/config.toml这个命令会依次检查配置文件语法、环境变量注入、base_url 连通性、模型可用性。全绿输出类似[ok] config parsed [ok] api key loaded from env [ok] base_url reachable (200) [ok] model claude-sonnet-4-20250514 available到这一步模型调用链路就算在树莓派上跑通了。你可以再发一条真实业务请求比如让 Openclaw 解析一句自然语言指令确认工具编排也正常。5. 本篇常见报错排查树莓派上跑这套东西报错集中在网络、鉴权、配置解析三类。下面这张表是我踩过的坑整理出来的对照着查基本能定位。报错信息可能原因处理方式Could not resolve host: taotoken.netDNS 未配置或 WiFi 未连nmcli connection show --active确认联网必要时在连接配置里补ipv4.dns401 UnauthorizedKey 未注入或写错echo $OPENCLAW_API_KEY确认非空检查 env 文件权限与 systemd EnvironmentFile 路径404 model not foundmodel 名称拼写错误对照接入文档的模型标识注意日期后缀SSL certificate problem系统时间不对导致证书校验失败timedatectl检查时间sudo timedatectl set-ntp true开启同步context deadline exceeded超时太短或网络慢把timeout_seconds调到 60 以上max_retries设 3config parse error: unknown fieldconfig.toml 字段名写错用openclaw doctor定位行号对照骨架逐字段核对permission denied: /home/pi/.openclaw/env文件属主或权限不对chown pi:pi并chmod 600服务启动后立刻退出WorkingDirectory 或 ExecStart 路径错journalctl -u openclaw -n 50看具体报错几个排查习惯值得养成。第一改完配置先openclaw doctor比直接重启服务快。第二systemd 服务出问题第一时间看journalctl -u openclaw -f日志比状态输出详细。第三树莓派 3B 内存小如果 Openclaw 进程被 OOM killer 干掉dmesg | grep -i oom能看到记录这时候要么换 4B/5要么把max_tokens调小。还有一个容易忽略的点树莓派默认的wlan0省电模式会在空闲时降频导致长连接偶发超时。可以在/etc/rc.local里加一行关掉省电iw dev wlan0 set power_save off6. 后续怎么用这套配置配置骨架稳定之后日常维护基本只剩两件事换模型和看用量。换模型改 config.toml 里的model字段或者切 profileKey 和 base_url 不动。看用量去控制台按 Key 维度能看到每台树莓派的调用情况方便判断是不是某台设备在异常刷量。如果你打算把 Openclaw 用在长期跑的编码助手或者 Agent 场景建议了解一下 Coding Plan它按订阅方式计费比按量更适合常驻设备Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenclaw_rpi想先在浏览器里验证模型输出是否符合预期可以用模型对话页面直接试模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenclaw_rpi树莓派这套跑通之后最实用的一个技巧是把~/.openclaw/config.toml和~/.openclaw/env分开管理config.toml 可以进 git 做版本控制env 永远不进仓库。这样你换设备、重装系统时clone 配置 重新填 Key 就能恢复几分钟搞定。