在边缘设备上部署AI助手已成为后端开发者的新宠。本文将手把手教你如何在树莓派（Linux）上安装OpenClaw，并接入智谱GLM-5模型，实现一个可局域网访问的智能服务端。无论你是想折腾硬件，还是需要轻量级AI中间件，这篇指南都能帮你少走弯路。

准备工作：硬件、系统与API Key

开始之前，请确保你具备以下条件：

  • 一台已安装Linux系统（推荐Raspberry Pi OS）的树莓派，并能通过SSH远程访问
  • 一个有效的模型API Key（本文以智谱GLM-5为例，你也可以选择其他兼容OpenAI接口的服务）
  • 基本的命令行操作经验

小提示：如果你手头没有树莓派，任何一台能跑Linux的旧电脑或云服务器也能胜任。OpenClaw对硬件要求不高，512MB内存即可流畅运行。

安装方式一：纯命令行安装（适合精细控制）

如果你喜欢每一步都了然于胸，推荐使用纯命令行方式。这种方式更透明，也方便后续排查问题。整体流程分为：连接设备、准备环境、安装核心、配置模型、启动服务五个阶段。

1. SSH连接与Node.js环境准备

首先通过SSH连接到你的树莓派：

ssh admin@192.168.12.119 #改为你的用户名和IP
# 密码: your_password

OpenClaw基于Node.js构建，因此需要Node.js 22+环境。检查系统当前的Node版本，如果低于22，请升级：

# 检查 Node.js 版本
node -v
# 如果未安装或版本过低，执行安装
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
# 验证安装
node --version
npm --version

⚠️ 注意：如果网络状况不佳，可以配置代理加速下载，避免超时：

# 如果网络较慢，设置代理连到你本机的*** verge(略)

2. 安装OpenClaw与配置环境变量

环境就绪后，使用npm全局安装OpenClaw：

# 方式 A：使用官方安装脚本（推荐）
curl -fsSL https://openclaw.ai/install.sh | bash
# 方式 B：通过 npm 全局安装
npm install -g openclaw@latest

安装完成后，需要设置环境变量，包括API Key、模型名称等。建议将配置写入~/.bashrc或~/.zshrc，以便持久生效：

# 将 npm 全局 bin 目录添加到 PATH
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 验证安装
openclaw --version

接下来运行初始化命令，生成默认配置文件：

# 运行初始化向导
openclaw setup
# 设置 Gateway 模式
openclaw config set gateway.mode local

3. 配置智谱GLM-5模型

编辑配置文件，将模型提供商设置为智谱，并填入你的API Key。这里以GLM-5为例：

# 设置默认模型
openclaw models set zai/glm-5
# 配置 API Key（推荐通过环境变量）
echo 'export ZAI_API_KEY="your_api_key_here"' >> ~/.bashrc
source ~/.bashrc

后端架构提示：OpenClaw本身作为服务端，通过API与模型服务通信。你可以将GLM-5视为一个远程的AI引擎，而OpenClaw是连接你的应用与引擎的中间件。

4. 启动Gateway与持久化运行

OpenClaw依赖Gateway服务来处理外部请求。安装并启动它：

# 安装 systemd 服务
openclaw gateway install
# 启动服务
systemctl --user enable --now openclaw-gateway
# 查看状态
systemctl --user status openclaw-gateway

默认情况下，SSH会话关闭后服务会终止。为了确保你的AI助手7x24小时在线，必须启用持久化运行（如systemd或pm2）：

# 允许用户会话在登出后继续运行
loginctl enable-linger $USER

5. 验证安装与访问Dashboard

启动后，通过健康检查接口验证服务是否正常：

# 运行诊断
openclaw doctor
# 查看网关状态
openclaw gateway status
# 查看模型状态
openclaw models status

一切正常后，通过浏览器访问Dashboard管理界面：

# 方式 1：直接在服务器上打开
openclaw dashboard
# 方式 2：通过 SSH 隧道远程访问
# 在本地机器执行：
ssh -L 18789:localhost:18789 admin@192.168.12.119
# 然后在本地浏览器打开：
# http://localhost:18789/

安装方式二：通过本机AI助手安装（推荐）

如果你已在本地电脑上配置了OpenCode、Codex等AI编程助手，那么安装过程可以大幅简化——只需一句话，AI会自动完成所有步骤。

复制以下提示词发给你的AI助手：

请帮我在远程服务器上安装 OpenClaw。
连接信息：
- SSH: admin@192.168.xx.xx（改成自己的IP和用户名）
- 密码: your_password
系统环境：
- Debian 13 x86_64（或者树莓派）
- Node.js 22 已安装
使用智谱 GLM-5 模型，API Key: your_api_key_here
模型教程：https://docs.bigmodel.cn/cn/guide/develop/openclaw#openclaw
最后让我能通过局域网访问 OpenClaw。

AI会依次完成：SSH连接、安装OpenClaw、配置GLM-5模型、设置局域网访问、启动服务并验证。完成后，它会返回访问地址和Token：

✅ OpenClaw 安装完成！
访问地址：http://192.168.xx.xx:18789/
Token: xxxxxxxxxxxxxxxxxxxx
常用命令：
- 查看状态：openclaw gateway status
- 查看日志：tail -f /tmp/openclaw/openclaw-*.log
- 重启服务：systemctl --user restart openclaw-gateway

在浏览器中打开Dashboard，输入Token即可开始使用：

在这里插入图片描述在这里插入图片描述

实践建议：这种方式非常适合快速原型验证。如果你需要深度定制，建议后续再通过命令行精细管理。

配置局域网访问与常见问题排查

默认配置下，OpenClaw只监听127.0.0.1（本地回环），外部设备无法访问。即使改为监听0.0.0.0，浏览器也会因非安全上下文（HTTP）拒绝连接，报错：

control ui requires device identity (use HTTPS or localhost secure context)

修改配置文件实现局域网访问

编辑配置文件opencrawl.json：

{
"gateway": {
"mode": "local",
"bind": "lan",
"controlUi": {
"dangerouslyAllowHostHeaderOriginFallback": true,
"dangerouslyDisableDeviceAuth": true
},
"auth": {
"mode": "token",
"token": "your_token_here"
}
}
}

关键参数说明如下：

配置项作用
监听所有网络接口（0.0.0.0）
允许 Host header origin 回退
禁用设备身份验证（新版本必需）

配置完成后重启服务：

# 1. 修改配置
openclaw config set gateway.bind lan
openclaw config set gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback true
openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true
# 2. 重启服务
systemctl --user restart openclaw-gateway
# 3. 验证
openclaw gateway status
# 应该显示：
# Gateway: bind=lan (0.0.0.0), port=18789
# Dashboard: http://192.168.xx.xx:18789/

两种访问方式

方式一：直接局域网访问（已配置）——适合家庭或办公内网：

http://192.168.xx.xx:18789/

方式二：SSH隧道（更安全）——适合远程调试，不暴露端口：

# 在本地电脑执行
ssh -N -L 18789:127.0.0.1:18789 admin@192.168.xx.xx
# 然后访问
http://localhost:18789/

常见问题速查

1. 端口被占用：

# 添加 npm 全局 bin 到 PATH
export PATH="$HOME/.npm-global/bin:$PATH"
# 永久添加
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2. API Key未生效：检查环境变量是否加载，或重启服务：

# 进入openclaw配置
openclaw config
# 重新设置models

3. 服务无法启动：查看日志定位错误：

# 查看详细日志
tail -100 /tmp/openclaw/openclaw-*.log
# 重新安装服务
openclaw gateway install --force
systemctl --user restart openclaw-gateway

4. 登出后服务停止：使用systemd或pm2守护进程：

# 启用 lingering
loginctl enable-linger $USER

5. 局域网无法访问：错误信息为：

control ui requires device identity (use HTTPS or localhost secure context)

这是新版的安全限制，需添加配置：

{
"gateway": {
"controlUi": {
"dangerouslyDisableDeviceAuth": true
}
}
}

参考：GitHub Issue #48

常用命令与配置文件参考

为了方便日常运维，这里汇总了高频命令：

# === 服务管理 ===
systemctl --user status openclaw-gateway    # 查看状态
systemctl --user restart openclaw-gateway   # 重启服务
systemctl --user stop openclaw-gateway      # 停止服务
systemctl --user start openclaw-gateway     # 启动服务
# === 诊断命令 ===
openclaw doctor                             # 健康检查
openclaw gateway status                     # 网关状态
openclaw models status                      # 模型状态
# === 访问方式 ===
openclaw tui                                # 终端聊天界面
openclaw dashboard                          # 打开 Web Dashboard
# === 日志查看 ===
tail -f /tmp/openclaw/openclaw-*.log        # 实时日志
# === 配置管理 ===
openclaw config get gateway                 # 查看配置
openclaw config set gateway.bind lan        # 修改配置
# === 重置 ===
openclaw reset                              # 重置配置（保留 CLI）

完整的配置文件示例（包含所有可选项）：

~/.openclaw/openclaw.json 
{
"meta": {
"lastTouchedVersion": "2026.2.26"
},
"agents": {
"defaults": {
"model": {
"primary": "zai/glm-5"
},
"workspace": "/home/admin/.openclaw/workspace",
"memorySearch": {
"enabled": false
}
}
},
"gateway": {
"mode": "local",
"bind": "lan",
"controlUi": {
"dangerouslyAllowHostHeaderOriginFallback": true,
"dangerouslyDisableDeviceAuth": true
},
"auth": {
"mode": "token",
"token": "your_secure_token_here"
}
}
}

安全建议与扩展玩法

⚠️ 当前配置的安全级别：使用allowInsecure会禁用设备身份验证，允许任何知道Token的人访问。

✅ 安全加固建议：

  • 仅在内网使用，不要暴露到公网
  • 定期更换Token，使用至少32位随机字符的强Token
  • 配合防火墙限制访问IP

此外，OpenClaw还支持接入QQ机器人，方便你在聊天中直接调用AI能力：

总结

本文详细介绍了在树莓派上安装OpenClaw的两种方式：纯命令行适合深度定制，AI辅助适合快速体验。通过配置GLM-5模型和局域网访问，你可以在任何设备上使用自己的AI助手。记住，安全永远是第一位的——内网使用、强Token、定期维护。现在，去享受你的AI助手吧！

[AFFILIATE_SLOT_1]

[AFFILIATE_SLOT_2]

bind: "lan"dangerouslyAllowHostHeaderOriginFallbackdangerouslyDisableDeviceAuth