树莓派 4B 部署 OpenClaw 实战：网络限制与模型配置

三、权限与配置优化

3.1 npm 权限问题

在树莓派上，全局安装 npm 包常遇到权限问题。采用用户级全局目录配置：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

3.2 时区配置

树莓派默认时区可能是 UTC，导致定时任务时间错误：

sudo timedatectl set-timezone Asia/Shanghai

3.3 系统依赖安装

确保所有编译依赖已安装：

sudo apt update
sudo apt install -y build-essential python3 libvips-dev

四、OpenClaw 安装与验证

4.1 最终安装命令

经过多次尝试，最终成功的安装命令是：

npm install -g @qingchencloud/openclaw-zh@latest

使用 --ignore-scripts 参数跳过了部分原生模块的编译，这在树莓派 ARM64 架构下是必要的妥协。

4.2 安装验证

安装成功后，验证 OpenClaw 是否正常工作：

openclaw --version
# 应显示：OpenClaw 中文版 2026.2.23 (b817600)

五、模型配置：DeepSeek API 的曲折之路

5.1 端点类型检测失败

在配置 DeepSeek API 时，遇到 Could not detect endpoint type 错误。最初尝试的配置如下：

• API Base URL：https://api.deepseek.com
• 模型 ID：DeepSeek-V3.2
• 错误信息：This endpoint did not respond to OpenAI or Anthropic style requests

根本原因：API 端点格式不正确，DeepSeek API 需要完整的聊天完成端点路径。

5.2 正确配置方案

正确的 DeepSeek API 配置应该是：

1. API Base URL：https://api.deepseek.com/v1/chat/completions
2. API Key：（确保无多余空格）
3. 端点兼容性：选择 OpenAI-compatible (Uses /chat/completions)
4. 模型 ID：deepseek-chat（官方标准名称）

5.3 API Key 验证

为确保 API Key 有效，可以使用以下 Python 脚本验证：

import requests
headers = {"Authorization": f"Bearer YOUR_API_KEY"}
response = requests.get("https://api.deepseek.com/v1/models", headers=headers)
print(response.status_code) # 应为 200

六、OpenClaw 基础配置与使用

6.1 运行配置向导

安装完成后，运行配置向导：

openclaw onboard --install-daemon

向导会引导完成以下步骤：

1. 安全警告确认
2. 选择 QuickStart 快速启动模式
3. 配置 AI 模型提供商
4. 完成 OAuth 授权（如使用 Qwen）
5. 选择默认模型
6. 配置消息频道（可先跳过）
7. 安装 Skills（技能）
8. 安装 Systemd 服务
9. 启用 Shell 自动补全

6.2 启动服务

openclaw gateway start # 默认端口：18789

6.3 访问 Web 控制台

通过 SSH 隧道从其他电脑访问 Dashboard：

# 在本地电脑执行
ssh -N -L 18789:127.0.0.1:18789 pi@树莓派 IP

然后在浏览器中打开：http://localhost:18789/?token=<你的 token>

七、树莓派性能优化建议

7.1 内存优化

树莓派 4B 的 4GB 内存有限，需要优化 OpenClaw 配置：

{
  "agents": {
    "defaults": {
      "maxConcurrent": 2,
      "subagents": {
        "maxConcurrent": 4
      }
    }
  }
}

7.2 磁盘空间管理

OpenClaw 会话日志会占用大量磁盘空间，建议设置日志轮转：

sudo vim /etc/logrotate.d/openclaw
# 添加配置：daily、rotate 7、compress 等

7.3 散热考虑

OpenClaw 持续运行会让树莓派发热，建议：

sudo apt install lm-sensors sensors
# 监控温度
# 考虑安装散热风扇或散热片

八、常见问题汇总与解决方案

8.1 命令找不到问题

# 重新加载.bashrc
source ~/.bashrc
# 或手动设置 PATH
export PATH=~/.npm-global/bin:$PATH

8.2 端口冲突问题

# 检查端口占用
lsof -i :18789
# 或修改端口
openclaw gateway start --port 18790

8.3 技能安装失败

许多 Skills 依赖 Homebrew，但树莓派上 Homebrew 支持有限。建议：

• 只安装不需要 brew 的技能：bird、clawhub、mcporter、oracle 等
• 通过 apt 手动安装对应工具，如 sudo apt install -y golang-go

8.4 网关健康检查失败

使用 openclaw doctor 命令进行诊断和自动修复。

九、总结与建议

9.1 关键经验总结

1. 网络环境是最大挑战：学校网络限制需要多策略应对
2. ARM64 架构的特殊性：需要从源码编译部分依赖
3. 权限管理很重要：避免使用 sudo，配置用户级全局目录
4. 模型配置需精确：API 端点格式和模型名称必须准确

9.2 给后来者的建议

1. 分步验证：每完成一步就验证是否成功
2. 耐心等待：树莓派性能有限，安装过程可能较慢
3. 备份配置：成功的配置及时备份
4. 社区求助：遇到问题时，查阅官方文档和社区讨论

9.3 推荐安装流程

基于我的经验，最可靠的安装流程是：

1. 环境准备（Python、Node.js、系统依赖）
2. 网络优化（Git 配置、镜像源）
3. 权限配置（npm 全局目录）
4. 使用 cnpm 安装 OpenClaw
5. 手动处理问题依赖（如 libsignal-node）
6. 运行配置向导
7. 模型配置（使用国产模型如 DeepSeek）
8. 性能优化调整

结语

在树莓派上部署 OpenClaw 是一次充满挑战但收获丰富的经历。虽然过程曲折，但最终成功运行个人 AI 助手的成就感是无与伦比的。希望这篇踩坑实录能帮助更多开发者顺利在树莓派上部署 OpenClaw，享受 AI 技术带来的便利。

重要提示：OpenClaw 具有强大的系统访问权限，使用时需注意安全风险。建议在受控环境中使用，并定期更新和维护。