Skip to content

openclaw-research.md

Latest commit

 

History

History
256 lines (195 loc) · 9.1 KB

openclaw-research.md

File metadata and controls

256 lines (195 loc) · 9.1 KB

OpenClaw 集成调研

什么是 OpenClaw？

OpenClaw 是一个开源的个人 AI 助手框架（前身叫 Clawdbot / Moltbot），由 Peter Steinberger 开发。2026 年 1 月底发布后一周内 GitHub 星标突破 10 万，是 GitHub 历史上增长最快的开源项目之一。

核心架构：

消息平台 (WhatsApp/Telegram/Slack/...)
        ↓
  Gateway Daemon（常驻进程，路由消息、管理会话）
        ↓
  Agent Runtime（推理循环、记忆、插件、Skills）
        ↓
  LLM Provider (Claude / GPT / DeepSeek / ...)
  • 本地优先：运行在你的机器或 VPS 上
  • 多渠道：WhatsApp、Telegram、Slack、Discord、Signal、iMessage 等
  • 多模型：Claude、GPT、DeepSeek 均可
  • 可执行动作：发邮件、创建文件、爬网页、设提醒、调 API、定时任务

ESP32 上的 OpenClaw 生态

已有多个项目把 OpenClaw 搬到了 ESP32 硬件上：

1. MimiClaw — 最成熟的方案

  • 仓库: memovai/mimiclaw
  • 硬件: ESP32-S3（和我们的 Cardputer 同芯片）
  • 特点:
    • 99.2% 纯 C 裸金属实现，无需 Linux/Node.js
    • 双核运行（网络 I/O + AI 处理分开）
    • WebSocket gateway 端口 18789
    • 支持 Anthropic Claude 和 OpenAI GPT
    • ReAct agent loop + tool calling
    • 通过 Telegram 交互
    • 功耗约 0.5W，USB 供电即可
    • OTA 空中升级
  • 技术栈: ESP-IDF（非 Arduino）
  • Flash 配置: 16MB Flash QIO, 8MB Octal PSRAM, 240MHz

2. ZClaw — 最小方案

  • 特点: 888KB 极小体积，专为资源受限设备优化
  • 报道: Geeky Gadgets
  • GPIO 直接控制，可读传感器、控制继电器

3. openclaw-esp32 — Arduino 方案

4. HeyClawy — 语音伴侣

  • 仓库: omeriko9/HeyClawy
  • 特点: 语音优先的 ESP32 OpenClaw 伴侣
    • 按键说话 或 唤醒词（默认 "Hey Jarvis"）
    • TTS 语音回复
    • 内置 Web 设置页面

OpenClaw 扩展机制

Skills（技能）

Skills 是 OpenClaw 的核心扩展方式，有两种类型：

  1. SKILL.md（自然语言技能）: Markdown 文件 + YAML 前置数据，描述任务流程
  2. TypeScript 技能: 完整编程能力，可调 API、执行复杂逻辑

社区已有 5400+ 技能，通过 ClawHub 管理。

创建自定义技能：

openclaw skills create my-skill
cd my-skill && npm install && npm run dev

MCP Server（模型上下文协议）

OpenClaw 原生支持 MCP，在 openclaw.json 中配置 MCP server：

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"]
    }
  }
}

MCP server 作为独立进程运行，通过 JSON-RPC 2.0 与 OpenClaw 通信，暴露的工具可被任何 agent 调用。

ClawPuter × OpenClaw 集成方案

方案 A：Cardputer 作为 OpenClaw 的物理终端（推荐起步）✅ 已验证可行

Cardputer (ESP32-S3)  ←── HTTP (OpenAI 兼容) ──→  OpenClaw Gateway (Mac)
   键盘输入                                          Agent Runtime
   屏幕显示                                          Skills / MCP / 记忆
   像素角色反应                                       LLM 调用 (Kimi/Claude/GPT)

关键发现：OpenClaw Gateway 自带 OpenAI 兼容 HTTP API，端点为 POST /v1/chat/completions。这意味着我们现有调 Kimi K2.5 的代码 几乎不用改 就能对接 OpenClaw。

请求格式（和 Kimi K2.5 完全一样）：

curl http://<YOUR_MAC_IP>:<your-port>/v1/chat/completions \
  -H 'Authorization: Bearer <gateway-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openclaw",
    "messages": [{"role":"user","content":"你好"}],
    "stream": false
  }'

会话保持：在请求中加 "user": "cardputer" 字段，Gateway 会自动生成稳定的 session key，实现跨请求对话记忆。

做法：

  1. Mac 端：openclaw.json 中启用 HTTP API + 改绑定为 LAN
  2. Cardputer 端：ai_client.cpp 改 URL 指向 Mac 的局域网 IP
  3. 键盘输入 → OpenClaw Agent → Skills/Tools/记忆 → 回复到 Cardputer
  4. 像素小龙虾根据回复类型做出不同反应

优点：改动极小（只改 URL 和 token），复用 OpenClaw 5400+ skills + 持久记忆 + 多模型切换 缺点：依赖同局域网的 Mac 运行 OpenClaw

方案 B：Cardputer 运行精简 OpenClaw Agent

Cardputer (ESP32-S3)
   ├── 精简 Agent Loop (ReAct)
   ├── 基础 Tool Calling
   ├── 键盘 + 屏幕 + 像素角色
   └── WiFi → LLM API

做法：

  • 参考 MimiClaw / ZClaw 的架构，在 Cardputer 上跑精简版 agent loop
  • 支持基础 tool calling（获取天气、设提醒、简单计算）
  • 像素角色 + 键盘交互作为独特的物理界面

优点：完全独立，无需外部服务器 缺点：开发量大，受限于 ESP32 资源（8MB PSRAM）

方案 C：混合模式（最终目标）

Cardputer
   ├── 离线模式：本地精简 agent（基础功能）
   └── 在线模式：连接 OpenClaw Gateway（完整能力）

做法：

  • 默认本地运行基础 agent（时钟、提醒、简单聊天）
  • 检测到 OpenClaw Gateway 时自动升级为完整终端
  • Cardputer 特有的 skill：物理按键快捷操作、屏幕通知、像素角色状态

当前环境（已验证）

你的 Mac 上已有 OpenClaw 运行：

项 值
版本 2026.2.26
Gateway ws://127.0.0.1:<your-port>（当前仅 loopback）
认证 token 模式
主模型 Kimi K2.5（回退 Gemini 3 Pro / GPT 5.2）
渠道 Telegram + 飞书
Mac 局域网 IP <YOUR_MAC_IP>
Agent 1 个 (main)，32 个活跃 session

实施步骤

第一步：启用 HTTP API + LAN 绑定（Mac 侧，5 分钟）

修改 ~/.openclaw/openclaw.json：

{
  "gateway": {
    "bind": "lan",           // ← 从 "loopback" 改为 "lan"
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true    // ← 新增：启用 OpenAI 兼容 API
        }
      }
    }
  }
}

然后重启 Gateway：openclaw gateway restart

验证：

curl http://<YOUR_MAC_IP>:<your-port>/v1/chat/completions \
  -H 'Authorization: Bearer <gateway-token>' \
  -H 'Content-Type: application/json' \
  -d '{"model":"openclaw","messages":[{"role":"user","content":"hi"}]}'

第二步：修改 Cardputer 固件（10 分钟）

ai_client.cpp 改动极小，因为 OpenClaw HTTP API 和 Kimi K2.5 格式完全兼容：

当前 (Kimi) 改为 (OpenClaw)
https://api.moonshot.cn/v1/chat/completions http://<YOUR_MAC_IP>:<your-port>/v1/chat/completions
Authorization: Bearer <kimi-key> Authorization: Bearer <gateway-token>
"model": "kimi-k2.5" "model": "openclaw"
HTTPS + setInsecure() HTTP（局域网，无需 TLS）

额外可加 "user": "cardputer" 字段实现会话保持。

第三步：写 Cardputer Skill（未来）

为 OpenClaw 写一个 cardputer skill，让 OpenClaw 能：

  • 推送通知到 Cardputer 屏幕（角色举牌）
  • 触发像素角色特定动画
  • 读取 Cardputer 的按键输入作为快捷指令

第四步：探索本地 Agent（未来）

参考 MimiClaw 的 ReAct loop 实现，在 Cardputer 上跑基础 tool calling。

方案 A 的优势（对比直接调 Kimi API）

能力 直接调 Kimi 通过 OpenClaw
模型 仅 Kimi K2.5 Kimi + Claude + GPT + Gemini 自动切换
对话记忆 无持久化 OpenClaw 自带 session 管理 + 持久记忆
工具调用 无 5400+ skills（发邮件、查天气、控设备...）
System Prompt 硬编码 OpenClaw agent 配置，可随时调整
安全 API key 存在设备上 token 只访问本地 Gateway
延迟 公网 RTT 局域网 <10ms

参考资源