ClawChips 架构与原理

整体框图

QQ / Channel 消息
        │
        ▼
┌──────────────────┐
│     OpenClaw     │
│  Agent Gateway   │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐     ┌─────────────────┐
│    ClawChips     │────▶│   云端模型      │
│  Local Router    │     │  (deepseek 等)  │
└────────┬─────────┘     └─────────────────┘
         │
         ▼
┌──────────────────┐     ┌─────────────────┐
│    ModelHub      │────▶│  ASR / TTS /    │
│   Scheduler      │     │  VLM / Embedding│
└──────────────────┘     └────────┬────────┘
                                  │
                          ┌───────┴───────┐
                          │   RK182X NPU  │
                          │  (协处理器)    │
                          └───────────────┘

如果还没部署 OpenClaw，请先看 ch05 一键部署 QQ 机器人。

1. 整体架构

ClawChips 是视美泰基于 OpenClaw 框架适配的边缘 AI Agent 部署方案，专为 RK3588 + RK182X 平台优化。

模块	职责
OpenClaw Gateway	消息入口（QQ / Channel）+ Agent 调度
ClawChips Router	端云路由（LOCAL vs CLOUD）
ModelHub	模型服务调度（启动 / 停止 / 健康检查）
RK182X NPU	本地模型推理（LLM / VLM / ASR / TTS / Embedding）

2. 端云智能路由

实际部署暂以 OpenClaw 直连 MiniMax 为准。

路由策略在 ~/.openclaw/clawchips.yaml 中配置（启用后生效）。规则中的 provider 名称以 setup.sh 实际配置为准（可能是 minimax / deepseek / glm / 自定义等）：

router:
  strategy: rules # 或 memory
  rules:
    - LOCAL: <provider>/<model> # 本地模型，如 rkllm/Qwen3-1.7B
    - CLOUD: <provider>/<model> # 云端模型，如 deepseek/deepseek-chat
    - default: <provider>/<model>
  enable: true

模式	说明
`rules`	基于规则路由，按 LOCAL / CLOUD / default 标签匹配
`memory`	基于历史决策持续优化路由（配置方式见 OpenClaw 文档）

2.1 配置云端模型

编辑 ~/.openclaw/openclaw.json，在 models.providers 中添加 Provider：

以下为推荐配置示例（本地 rkllm + 云端 deepseek 两个 provider）。实际 provider 以 setup.sh 配置为准——当前部署仅配置了 MiniMax 一个 provider，且 rkllm 本地服务未安装。

{
  "models": {
    "providers": {
      "rkllm": {
        "baseUrl": "http://127.0.0.1:7878/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "Qwen3-1.7B",
            "name": "Qwen3-1.7B RKLLM",
            "contextWindow": 8192,
            "maxTokens": 512
          }
        ]
      },
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "sk-xxxxxxxxxxxx",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-chat",
            "contextWindow": 65536,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

同步更新 Agent 级配置 ~/.openclaw/agents/main/agent/models.json。

已知问题：setup.sh 当前不会同步写入 agents/main/agent/models.json（该文件内容为 {"providers": {}}），需手动从 openclaw.json 复制 / 合并；"自动同步"为计划中功能。

2.2 Dashboard 配置

访问 http://<开发板IP>:18789/plugins/clawchips/dashboard：

该路径仅在 clawchips 插件启用时可用。

ClawChips Dashboard

使能本地路由和记忆路由
选择 CLOUD model ID（下拉选项来自 providers 配置）
保存后重启：openclaw gateway restart

2.3 视美泰实践：端云协同

推荐方案：云端负责对话推理，本地 NPU 负责 VLM 图片识别。

真实路由取决于 clawchips.yaml 中 provider / 模型 ID 是否填对。配置错误会全部走云端或全部失败。

4. Token 消耗优化

将常用工具调用方式写在 ~/.openclaw/workspace/TOOLS.md 中，AI 可跳过"先读 SKILL.md"这一步，减少 API 调用轮数。

策略	效果
默认（先读 SKILL.md 再执行）	多一轮 API 调用
TOOLS.md 内联（直接调用）	省一轮 API 调用

具体 token 数取决于模型、上下文长度、对话复杂度。TOOLS.md 已在实际部署中验证有效。

5. 常见问题

5.1 路由始终覆盖到本地模型

现象：日志显示 [hooks] provider overridden to rkllm。

解决：将 LOCAL 规则指向云端模型：

router:
  rules:
    - LOCAL: deepseek/deepseek-chat
    - CLOUD: deepseek/deepseek-chat
    - default: deepseek/deepseek-chat

5.2 本地模型响应超时

原因：OpenClaw 系统提示词约 7000 tokens，本地小模型推理慢。

解决：

推荐用云端模型处理对话
或先跑 benchmark 测速：

rkllm3-server --help 2>&1 | head -20

再调高超时

5.3 NPU 设备找不到

# 1. 检查服务
sudo systemctl status rknn3.service --no-pager

输出：

● rknn3.service - rknn3 runtime service
     Loaded: loaded (/lib/systemd/system/rknn3.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-08-20 11:24:04 CST; 2h 55min ago
    Process: 516 ExecStart=/bin/rknn3_startup start (code=exited, status=0/SUCCESS)
   Main PID: 1396 (rknn3_transfer_)
        CPU: 43.212s
   CGroup: /system.slice/rknn3.service
             ├─1396 /bin/rknn3_transfer_proxy
             └─58359 rknn3_transfer_proxy_c36211b1 -s 0004:41:00.0

# 2. 检查 PCIe 设备（用 vendor:device 精确匹配）
lspci -d 1d87:182a

输出：

0004:41:00.0 Processing accelerators: Rockchip Electronics Co., Ltd Device 182a (rev 01)

5.4 常见问题速查

现象	原因	处理
路由覆盖到本地模型	LOCAL 规则配错	LOCAL/CLOUD 都指向云端
本地模型响应超时	系统 prompt 长 + 小模型慢	用云端对话 / 调高超时
NPU 设备找不到	卡没插 / 服务没起	`systemctl status rknn3.service` + `lspci -d 1d87:182a`
`agents/main/agent/models.json` 是 `{"providers": {}}`	`setup.sh` 没同步	手动从 `openclaw.json` 合并
Dashboard 返回 404	插件未启用	用 `openclaw channels list` 替代

6. 下一步

SKILL 使用手册 — 写自定义 Skill
LLM 推理 — 接入本地 rkllm3-server
AI Agent 应用 — 集成到 Agent 框架