# k10Claw

**Repository Path**: genvex/k10-claw

## Basic Information

- **Project Name**: k10Claw
- **Description**: EmbedClaw K10是面向ESP32‑S3的原生轻量化AI Agent运行时，继承OpenClaw「通道‑Agent‑推理‑工具」四层解耦架构，针对嵌入式硬件极致优化，首次在微控制器上实现完整AI Agent全闭环运行，是能独立思考、自主执行、长期记忆的硬件智能体，而非普通聊天机器人。
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-03-26
- **Last Updated**: 2026-05-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EmbedClaw K10：小龙虾的智能伙伴

# EmbedClawK10 运行在行空板K10上的小龙虾

## 项目概述

EmbedClaw K10是面向**ESP32‑S3**的原生轻量化AI Agent运行时，继承OpenClaw「通道‑Agent‑推理‑工具」四层解耦架构，针对嵌入式硬件极致优化，首次在微控制器上实现完整AI Agent全闭环运行，是能独立思考、自主执行、长期记忆的硬件智能体，而非普通聊天机器人。

---

## 一、项目核心定位

- 支持完整**ReAct多轮迭代决策**

- 支持工具链调用：联网搜索、文件读写、定时任务、硬件控制

- 支持**SD卡持久记忆**：长期记忆、会话、日记、技能

- 支持微信/飞书/WebSocket多通道接入，**无需公网IP**

- 支持Markdown技能热加载，不烧录、不改代码扩展能力

---

## 二、硬件平台：行空板K10（ESP32‑S3）

- 双核240MHz处理器，FreeRTOS实时调度

- 8MB PSRAM + 16MB Flash

- SD卡（FAT32）：配置、记忆、技能、会话全存储

- 240×320 LCD：本地交互与状态显示

- AHT20温湿度、WS2812 LED：典型IoT外设

- WiFi：联网接入大模型API与消息通道

在资源高度受限的嵌入式环境，实现云端级Agent体验。

---

## 三、四层架构：嵌入式优化的智能内核

### 1. Channel 消息通道层

- 多通道并行：WebSocket（本地调试，端口18789）、飞书（长连接）、微信（HTTP轮询，日常首选）

- 基于FreeRTOS异步调度，不抢占Agent核心资源

### 2. Agent 核心层：ReAct思考闭环

严格遵循**Thought → Action → Observation → Decision**流程：

1. 理解用户意图，规划执行步骤

2. 自动选择并调用工具

3. 接收结果并精简总结

4. 判断继续迭代或直接回答

嵌入式优化：

- 最大迭代10次，避免资源耗尽

- 结果轻量化压缩，降低内存占用

- 任务完成自动释放资源，稳定不掉线

### 3. LLM 推理层：云端大脑，边缘执行

兼容OpenAI标准API，支持主流模型：

- 通义千问（中文优先，推荐）

- DeepSeek（低成本高性价比）

- OpenAI GPT（通用能力强）

LLM负责决策与规划，边缘端负责执行与控制，平衡算力与成本。

### 4. Tools 工具层：AI×IoT物理操控

在OpenClaw基础上新增嵌入式硬件工具：

- 通用能力：联网搜索、记忆读写、文件操作、定时任务

- IoT能力：温湿度读取、LED控制

- 工具以JSON Schema标准化，支持自然语言快速扩展

---

## 四、存储设计：SD卡全解耦

采用**SD卡中心化存储**，固件与配置完全解耦，换卡即换“灵魂”。

### 存储目录结构

```Plain Text

/sdcard/embedclaw/
├── 📂 config/              # 配置目录
│   ├── 📄 config.json      # API Key、模型配置（取代NVS）
│   ├── 📄 config.json.template
│   ├── 📄 SOUL.md          # Agent人设定义
│   └── 📄 USER.md          # 用户信息
├── 📂 session/             # 会话历史（最多50条/会话）
│   └── 📄 se_<chat_hash>.jsonl
├── 📂 memory/              # 记忆系统
│   ├── 📄 MEMORY.md        # 长期记忆
│   └── 📄 YYYY-MM-DD.md    # 每日笔记
├── 📂 skills/              # Markdown技能文件（热加载）
│   └── 📄 *.md
└── 📄 cron.json            # 定时任务快照
```

### 核心优势

- 中文长文件名兼容，直接复用OpenClaw技能

- SPI模式兼容更多SD卡，硬件适配更强

- 建议使用优质SD卡，避免因存储故障导致设备重启

---

## 五、快速上手（5分钟部署）

### 步骤1：准备SD卡

1. 格式化为**FAT32**

2. 创建目录结构：`/embedclaw/config/`

3. 新建`config.json`，填写API密钥

**配置文件示例**

```JSON

{
  "llm": {
    "api_key": "sk-your-dashscope-key",
    "model": "qwen-plus",
    "api_url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions"
  },
  "search": {
    "api_key": "tvly-your-tavily-key"
  },
  "feishu": {
    "app_id": "cli_xxxxxx",
    "app_secret": "xxxxxx"
  }
}
```

- Tavily API：[https://tavily.com](https://tavily.com)（免费额度，支持实时联网搜索）

### 步骤2：编译烧录

```Bash

# 克隆项目
git clone https://gitee.com/genvex/k10-claw.git
cd k10-claw

# 设置目标
idf.py set-target esp32s3

# 编译
idf.py build

# 烧录
idf.py -p COM3 flash monitor
```

- 无编译条件可直接烧录固件，offset 0x0烧录

### 步骤3：WiFi配网

1. 长按A键进入config mode

2. 手机连接热点`EmbedClaw_XXXX`

3. 访问`192.168.4.1`配置WiFi

4. 保存后设备自动重启

### 步骤4：开始对话

联网后长按B键重启，屏幕显示微信二维码，扫码即可对话。

---

## 六、真实应用场景

### 场景1：远程智能环境管家

微信指令：“查看实验室温湿度，超标开报警灯，每小时记录”

- 自动读取温湿度→判断阈值→控制LED→创建定时任务→回传结果

- 无需APP、网关、公网IP

### 场景2：随身个人助理

指令：“查北京天气，明天7:30提醒带伞，记录带电脑”

- 联网搜索→设置定时提醒→写入长期记忆→跨会话保留

### 场景3：低成本IoT自动化节点

部署于教室/仓库：

- 实时监测环境数据

- 自动调节设备状态

- 定时上报到微信/飞书

- 自然语言添加规则，无需代码

### 场景4：嵌入式开发调试助手

- 自然语言添加硬件控制工具

- 自动记录调试日志到SD卡

- 远程查看设备状态

- 技能热加载，一键切换功能

---

## 七、2026年4月核心优化亮点

1. SD卡配置系统：统一入口，兼容OpenClaw

2. FAT长文件名：支持中文技能/人设文件

3. SD卡SPI模式：提升硬件兼容性

4. PWA配网页面：手机一键配网，状态可视

5. 内存精细化管理：预留128KB给SSL/DMA

6. 双核任务分离：UI与网络隔离，避免看门狗复位

系统从“可运行”升级为成品级稳定状态。

---

## 八、工具函数构建教程

### 1. 创建工具文件

在`components/embed_claw/tools/`新建`tools_<name>.c`，示例：

```C

#include "ec_config_internal.h"
#include "core/ec_tools.h"

static esp_err_t ec_tool_demo_execute(const char *input_json, char *output, size_t output_size) {
    // 解析参数、执行逻辑、返回JSON结果
    snprintf(output, output_size, "{\"result\":42,\"status\":\"success\"}");
    return ESP_OK;
}

static const ec_tools_t s_demo = {
    .name = "demo_tool",
    .description = "演示工具",
    .input_schema_json = "{\"type\":\"object\",\"properties\":{\"message\":{\"type\":\"string\"}},\"required\":[]}",
    .execute = ec_tool_demo_execute,
};

esp_err_t ec_tools_demo(void) {
    return ec_tools_register(&s_demo);
}
```

### 2. 注册工具

编辑`components/embed_claw/tools/ec_tools_reg.inc`，添加：

```C

EC_TOOLS_REG(demo)
```

### 3. 添加到构建

编辑`components/embed_claw/CMakeLists.txt`，在SRCS中添加：

```CMake

"tools/tools_demo.c"
```

### 4. 编译测试

```Bash

idf.py build
idf.py flash monitor
```

---

## 九、结语

EmbedClawK10基于ESP32-S3实现轻量化AI Agent运行，以ReAct循环、消息队列解耦、上下文分层管理为核心设计，在资源受限的嵌入式设备上落地对话式AI能力。未来AI Agent将全面渗透边缘硬件，EmbedClaw正是边缘智能革命的起点。

**项目仓库**：[gitee.com/genvex/k10-claw](http://gitee.com/genvex/k10-claw)

---

## 十、参考资料

- **EmbedClaw 官方仓库**：[https://github.com/wireless-tag-com/EmbedClaw](https://github.com/wireless-tag-com/EmbedClaw)
- **MimiClaw 项目**：[https://github.com/memovai/mimiclaw](https://github.com/memovai/mimiclaw)