开发板：Orange Pi 5 (RK3588, 8/16GB RAM) 或 Firefly 等。

必须支持 Function Calling：OpenClaw 的 Agent 能力依赖工具调用。Qwen2.5-Coder、Llama3.1 等系列均可，但需使用 Instruct 或 -tools 微调版。

OpenClaw 本地部署大模型使用教程

Q: 二、模型准备与转换（rkllama 篇）

三、rkllama 服务部署与加载

Q: 2.1 获取模型

从 HuggingFace 下载原始模型（如 Qwen2.5-Coder-7B-Instruct）。如果使用 rkllama，必须将 HF 模型转换为 .rkllm 格式。

在 ARM 开发板（RK3588 / Orange Pi 5）上部署 OpenClaw 并接入本地大模型的全流程指南，涵盖模型转换、服务编排、配置调优及踩坑经验。

📑 目录

一、部署架构与选型

1.1 硬件与软件

开发板：Orange Pi 5 (RK3588, 8/16GB RAM) 或 Firefly 等。
操作系统：Armbian (Bookworm) 或官方 Ubuntu。
OpenClaw 版本：建议使用稳定版 2026.4.23+，但新版配置变化频繁，需注意兼容性。
本地模型服务：
- rkllama：专为 RK3588 NPU 优化的推理服务，提供 Ollama 兼容 API。
- Ollama：通用方案，但 NPU 利用率低，适合 CPU 小模型。

1.2 模型选择

必须支持 Function Calling：OpenClaw 的 Agent 能力依赖工具调用。Qwen2.5-Coder、Llama3.1 等系列均可，但需使用 Instruct 或 -tools 微调版。
参数量：7B 模型在 RK3588 上运行较慢，3B 是更均衡的选择；1.5B 仅适合简单任务。
上下文长度：至少 4096，建议 8192 以上。模型原生 32K 最佳。

二、模型准备与转换（rkllama 篇）

2.1 获取模型

从 HuggingFace 下载原始模型（如 Qwen2.5-Coder-7B-Instruct）。如果使用 rkllama，必须将 HF 模型转换为 .rkllm 格式。

2.2 转换工具安装

# 在 x86 主机或开发板上安装 rkllm-toolkit
python3 -m venv rkllm_venv
source rkllm_venv/bin/activate
pip install rkllm-toolkit

注意：包名是 rkllm-toolkit，但导入模块名是 rkllm；不同版本 API 差异大。

2.3 转换脚本（以 3B/7B 为例）

import os
os.environ['TMPDIR'] = '/path/to/large/tmp'  # 防止 /tmp 空间不足

from rkllm.api import RKLLM

model_path = "/path/to/model"
output_path = "/path/to/model.rkllm"

llm = RKLLM()
ret = llm.load_huggingface(model=model_path)
if ret != 0: exit(1)

ret = llm.build(
    do_quantization=True,
    optimization_level=1,
    target_platform="rk3588",
    quantized_dtype="w8a8"   # 可改为 w4a16 减少空间
)
if ret != 0: exit(1)

ret = llm.export_rkllm(export_path=output_path)
if ret != 0: exit(1)
print("Done")

2.4 常见转换问题

空间不足：设置 TMPDIR 到大分区，并确保输出目录有足够空间（7B 约需 15GB）。
导入错误：若 from rkllm.api import RKLLM 失败，可尝试 import rkllm; rkllm.RKLLM 或查看 dir(rkllm) 找到正确入口。
NPU 驱动版本：rkllama 要求 NPU 驱动 ≥0.9.8，旧版需升级。

三、rkllama 服务部署与加载

3.1 安装 rkllama

git clone https://github.com/notpunchnox/rkllama
cd rkllama
bash setup.sh

如遇 Git 网络问题，可下载 ZIP 或用镜像站。

3.2 启动服务

rkllama serve &

3.3 加载本地模型

rkllama load /path/to/model.rkllm

绝对不要使用 rkllama run model_name（会去 HuggingFace 下载），必须加载本地文件。

3.4 验证

curl http://127.0.0.1:8080/api/tags
# 应返回已加载的模型列表

四、OpenClaw 安装与基础配置

4.1 安装 OpenClaw

推荐：使用 npm install -g openclaw@版本号（网络不稳时用国内镜像）
备选：下载 ARM64 离线二进制包，解压后软链到 /usr/local/bin。

4.2 初始化配置

openclaw onboard --mode local

或手动创建 ~/.openclaw/openclaw.json。

4.3 模型服务配置（连接 rkllama）

{
  "models": {
    "providers": {
      "rkllama": {
        "baseUrl": "http://192.168.18.32:8080/v1",
        "api": "openai-completions",
        "apiKey": "no-key",
        "request": {
          "allowPrivateNetwork": true
        },
        "models": [
          {
            "id": "Qwen2.5-Coder-7B-Instruct",
            "name": "Qwen2.5-Coder-7B-Instruct",
            "contextWindow": 8192,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "rkllama/Qwen2.5-Coder-7B-Instruct"
      }
    }
  }
}

重点：request.allowPrivateNetwork 是访问局域网 IP 的关键；id 必须与 rkllama 返回的模型名完全一致。

4.4 工作区 MD 文件

在 ~/.openclaw/workspace 下配置：

AGENTS.md：核心操作手册，精简指令。
IDENTITY.md：身份定义。
SOUL.md：性格（可禁用）。
USER.md：用户信息。
TOOLS.md：工具清单。
MEMORY.md：长期记忆。

示例 AGENTS.md：

# 身份
你是本地 AI 助手，只使用允许的工具。

## 规则
1. 安全第一，禁止危险操作。
2. 回答简洁，每次不超过 4 句话。
3. 工具仅在用户要求时使用。

五、飞书集成（可选）

5.1 配置飞书插件

"channels": {
  "feishu": {
    "enabled": true,
    "appId": "cli_xxx",
    "appSecret": "xxx",
    "verificationToken": "xxx",
    "encryptKey": "",
    "connectionMode": "websocket",
    "dmPolicy": "pairing",
    "allowFrom": ["ou_xxx"],
    "streaming": true,
    "apiTimeoutMs": 30000
  }
},
"plugins": {
  "allow": ["@openclaw/feishu"],
  "entries": {
    "@openclaw/feishu": {
      "enabled": true
    }
  }
}

5.2 飞书开放平台配置

事件订阅模式改为 长连接（WebSocket）。
添加权限：im:message、im:message:send。
确保 App Secret 和 Verification Token 正确。

5.3 常见错误

Verification failed: This operation was aborted：回调地址不可达或 Token 不匹配。
bot open_id unknown：网络无法访问飞书 API，检查 DNS 和超时设置。

六、局域网访问控制台

6.1 配置监听与认证

"gateway": {
  "bind": "lan",
  "mode": "local",
  "port": 18789,
  "auth": {
    "mode": "password",
    "password": "你的密码"
  },
  "controlUi": {
    "allowedOrigins": ["http://192.168.18.32:18789"],
    "allowInsecureAuth": true
  }
}

6.2 设备配对

从局域网其他设备访问时，OpenClaw 会要求配对。
在开发板上执行 openclaw devices list 查看待审批请求，openclaw devices approve <ID> 批准。
若内网安全，可设置 "dangerouslyDisableDeviceAuth": true 跳过配对。

6.3 无法打开网页

确认 openclaw gateway status 监听地址为局域网 IP。
检查防火墙：sudo ufw allow 18789/tcp。
浏览器安全上下文问题：建议使用 SSH 隧道 ssh -L 18789:localhost:18789 user@IP 后用 http://localhost:18789 访问。

七、systemd 服务与自动重启

7.1 正确的用户级服务

OpenClaw 内部会检查 systemd 状态，如果使用系统级服务会导致 Cannot access user instance remotely 错误。必须使用用户级 systemd。

创建 ~/.config/systemd/user/openclaw-gateway.service：

[Unit]
Description=OpenClaw Gateway Service
After=network.target

[Service]
Type=simple
ExecStart=/home/firefly/.npm-global/bin/openclaw gateway start
ExecStop=/home/firefly/.npm-global/bin/openclaw gateway stop
Restart=on-failure
RestartSec=10s
Environment="PATH=/usr/local/bin:/usr/bin:/bin:/home/firefly/.npm-global/bin"
Environment="OPENCLAW_SKIP_SYSTEMD_CHECK=1"

[Install]
WantedBy=default.target

启用：

systemctl --user daemon-reload
systemctl --user enable openclaw-gateway.service
systemctl --user start openclaw-gateway.service
sudo loginctl enable-linger firefly   # 允许无登录运行

7.2 启动失败排查

status=203/EXEC：ExecStart 路径错误，which openclaw 确认。
status=1/FAILURE 且日志提示 systemctl restart failed：OpenClaw 内部管理冲突，添加 OPENCLAW_SKIP_SYSTEMD_CHECK=1 环境变量，或使用 openclaw gateway 命令作为 ExecStart。
仍失败：尝试 openclaw gateway install --restart always 让 OpenClaw 自己创建服务。

八、踩坑经验总结

网络问题是最大障碍：开发板访问 GitHub/HuggingFace 经常超时或 SSL 错误。解决方案：使用国内镜像、离线下载、Git 设置 http.sslVerify false 或 SSH 协议。
配置键名随版本变化：dangerouslyAllowPrivateNetwork 在 2026.5.12 中无效，需放在 Provider 的 request.allowPrivateNetwork。不要乱加字段，否则报 Unrecognized key。使用 openclaw doctor --fix 清理。
模型连接被 SSRF 拦截：日志显示 Blocked hostname。在 Provider 配置中加 "request": {"allowPrivateNetwork": true}，或同机用 localhost 绕过。
工具调用失败：模型必须支持 Function Calling，否则只返回文本。使用 -tools 微调模型，确保 maxTokens 足够。
上下文管理：工作区 MD 文件极度精简，设置 historyLimit 和 compaction。
飞书插件超时：增加 apiTimeoutMs 到 30000。网络差时先用 Web 控制台验证模型。
systemd 服务：永远使用用户级服务，配合 loginctl enable-linger，用 OPENCLAW_SKIP_SYSTEMD_CHECK=1 跳过内部检查。
配置重置：修改配置后启动失败，OpenClaw 可能自动恢复备份。先用 openclaw doctor --fix 验证再重启，并备份 ~/.openclaw。

九、调试流程速查

确认模型服务：curl http://<IP>:8080/api/tags 返回模型列表。
测试模型 API：curl http://<IP>:8080/v1/chat/completions 发送简单消息。
检查 OpenClaw 配置：openclaw doctor 查看配置错误。
查看日志：journalctl --user -u openclaw-gateway.service -f 或 openclaw logs --follow。
Web 控制台测试：绕过飞书，直接浏览器访问 http://IP:18789 对话，定位问题。
若模型超时：调整 agents.defaults.timeoutSeconds 和 Provider 的 api.timeout。

十、最佳实践建议

关注版本更新：OpenClaw 配置键名变化快，升级前查看 Release Notes 或 openclaw

模型服务独立部署：rkllama 或 Ollama 单独运行，OpenClaw 通过 API 调用。

使用 Docker（可选）：隔离环境，但需注意 NPU 设备映射。

分阶段调试：先模型服务 → 再 OpenClaw 核心 → 再渠道集成。

记录配置变更：每次修改前备份，用 openclaw config set 更安全。

文章作者: luanpacom

文章链接: http://www.luanpa.com/2026/08/openclaw-lla/

OpenClaw 本地部署大模型使用教程

一、部署架构与选型

1.1 硬件与软件

1.2 模型选择

二、模型准备与转换（rkllama 篇）

2.1 获取模型

2.2 转换工具安装

2.3 转换脚本（以 3B/7B 为例）

2.4 常见转换问题

三、rkllama 服务部署与加载

3.1 安装 rkllama

3.2 启动服务

3.3 加载本地模型

3.4 验证

四、OpenClaw 安装与基础配置

4.1 安装 OpenClaw

4.2 初始化配置

4.3 模型服务配置（连接 rkllama）

4.4 工作区 MD 文件

五、飞书集成（可选）

5.1 配置飞书插件

5.2 飞书开放平台配置

5.3 常见错误

六、局域网访问控制台

6.1 配置监听与认证

6.2 设备配对

6.3 无法打开网页

七、systemd 服务与自动重启

7.1 正确的用户级服务

7.2 启动失败排查

八、踩坑经验总结

九、调试流程速查

十、最佳实践建议

📖 相关推荐

发表回复 取消回复

发表回复取消回复