Cardputer Agent Node

将 M5Stack Cardputer ADV 作为一个超轻量的便携 Agent 节点：设备侧负责语音采集、状态显示和最小交互，复杂推理与会话管理交给宿主机上的 OpenClaw。

项目定位

这个项目不是“把完整 Agent 塞进 ESP32”。

它的目标是：

• 用尽量小的硬件做一个可随身携带的 Agent 入口
• 把推理、会话、权限、模型调用放在宿主机侧
• 保留一个适合真实交互与方案验证的设备体验：按键说话、等待处理、屏幕读回文本

当前能力

• Cardputer 端按键录音
• 通过 Wi‑Fi 把音频发送到本地 Python bridge
• 通过阿里云 fun-asr-realtime 或 OpenClaw 做语音转写
• 通过 OpenClaw 专属 session 发送会话消息
• 在 Cardputer 屏幕上显示文本回复
• 支持键盘文本输入作为低延迟备用入口
• 支持串口配置 Wi‑Fi 与 bridge 地址
• 支持扫描周围 Wi‑Fi、选择已保存网络、手动输入 SSID / 密码
• 支持 bridge 断线后的有限重连
• 支持按需拉取 IMU 快照，不再持续向宿主机刷传感器数据
• 支持从 TF 卡选择节点固件并在设备内执行 OTA 安装

本次更新

这次公开版更新主要包含：

• 接入阿里云 DashScope 实时语音识别，默认推荐模型为 fun-asr-realtime
• 保留 OpenClaw 音频能力作为备用转写路径
• 清理旧的后台注释/隐藏消息路径，避免向 OpenClaw session 注入无关内容
• 增加设备端文本输入与对话框显示，降低纯语音链路的等待成本
• 将 IMU 改为按需请求模式，避免持续刷屏和污染会话上下文
• 增加 Wi‑Fi 选择界面、保存网络复用、手动输入配网流程
• 增加 TF 卡节点包与设备内 OTA 固件安装能力
• 对仓库默认值做去敏处理，移除个人 Wi‑Fi、局域网地址和本地路径

系统架构

Cardputer ADV
  ├── Mic -> WAV audio
  ├── Wi-Fi -> TCP -> bridge_service/bridge.py
  └── Screen <- status/text <- bridge

bridge.py
  ├── aliyun dashscope ASR (fun-asr-realtime)
  ├── openclaw capability audio transcribe (fallback)
  ├── openclaw gateway call sessions.send
  └── dedicated OpenClaw session: "cardputer"

设计原则：

• 设备轻
• 宿主机强
• 协议简单
• 适合迭代

仓库结构

cardputer-agent-adv-fix/
├── bridge_service/
│   ├── bridge.py
│   ├── requirements.txt
│   └── GATEWAY_SETUP.md
├── cardputer_firmware/
│   ├── platformio.ini
│   └── src/
├── docs/
│   ├── flash-guide.md
│   ├── gui-architecture.md
│   └── release-notes-v0.1.0.md
├── TODO.md
└── README.md

硬件与软件要求

硬件：

• M5Stack Cardputer ADV
• USB 数据线
• 可用的 2.4GHz Wi‑Fi

宿主机：

• Python 3.10+
• PlatformIO
• 本地可用的 openclaw CLI
• 正常运行的 OpenClaw Gateway

Python 依赖见 bridge_service/requirements.txt。

快速开始

1. 安装 Python 依赖

cd /path/to/cardputer-agent-adv-fix
python3 -m venv .venv
source .venv/bin/activate
pip install -r bridge_service/requirements.txt

2. 启动 bridge

DASHSCOPE_API_KEY=<your-key> ALIYUN_ASR_MODEL=fun-asr-realtime python bridge_service/bridge.py

3. 烧录固件

cd cardputer_firmware
pio run -t upload

4. 通过串口配置 Wi‑Fi 和 bridge

wifi,<ssid>,<password>
bridge,<host>,8766

更完整流程见：

• docs/flash-guide.md
• bridge_service/GATEWAY_SETUP.md

公开版默认值

为了适合公开发布，这个仓库已经做了默认去敏处理：

• 默认 bridge host 为 bridge.local
• 默认 OpenClaw session key 为 cardputer
• UI 文案使用通用名称 AGENT
• 不包含个人 Wi‑Fi 凭据
• 不包含本地 Gateway token
• 不包含个人局域网 IP

当前已知限制

• 仍然依赖宿主机上的 OpenClaw 环境
• 设备端是小屏幕，长回复只能显示截断后的摘要
• 当前交互以语音输入 + 文本输出为主
• 还不是最终硬件形态，当前主要用于验证便携节点架构与交互链路

对外介绍建议

推荐在演示时强调：

• 这不是独立算力终端，而是便携 Agent 节点
• 设备负责“入口”和“在场感”
• 真正的智能体运行在更强的宿主机上
• 以后可以替换成树莓派或自定义硬件继续演进

安全与发布提醒

当前工作区文件已经清理为公开版，但在推送到 GitHub 前，仍建议你额外检查：

• git 历史里是否存在旧敏感信息
• Release 附件中是否包含本地构建产物
• 文档截图里是否出现个人网络信息

发布说明

首个公开版本的发布说明草稿见：

• docs/release-notes-v0.1.0.md

这份文档可以直接作为 GitHub Release 描述的基础。