# MimiCLaw-Embeded

**Repository Path**: unbt/mimi-claw-embeded

## Basic Information

- **Project Name**: MimiCLaw-Embeded
- **Description**: No description available
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-02
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MimiClaw for Linux

基于 Linux 的 AI Agent 实现，**支持 Linux 2.6.38.20120518+**

## ✨ v1.1.0 新功能

🚀 **完全重构为 WebSocket 模式！**
✅ **兼容 Linux 2.6.38+ 老版本系统**

- ❌ 已移除 Telegram Bot
- ✅ 飞书 WebSocket 服务器（端口 8080）
- ✅ 实时双向通信
- ✅ 支持多客户端并发连接
- ✅ Linux 2.6.38 兼容性优化

---

## 📋 目录

1. [Linux 兼容性](#linux-兼容性)
2. [快速开始](#快速开始)
3. [使用 WebSocket](#使用-websocket)
4. [项目结构](#项目结构)
5. [功能特性](#功能特性)
6. [配置说明](#配置说明)
7. [安装指南](#安装指南)
8. [飞书配置](#飞书配置)
9. [故障排除](#故障排除)
10. [技术细节](#技术细节)
11. [嵌入式部署](#嵌入式部署)

---

## 🐧 Linux 兼容性

### 支持的版本

- ✅ **Linux 2.6.38.20120518+** (推荐用于老旧系统)
- ✅ Linux 2.6.39+
- ✅ Linux 3.x+
- ✅ Linux 4.x+
- ✅ Linux 5.x+

### 兼容性改进

v1.1.0 针对老版本 Linux 进行了以下优化：

1. **时间函数**: 使用 `gettimeofday()` 代替 `clock_gettime()`
2. **POSIX 标准**: 添加 `-D_POSIX_C_SOURCE=200112L` 编译标志
3. **GNU 扩展**: 启用 `-D_GNU_SOURCE`
4. **依赖检测**: 自动检测 libcurl 等库

### 系统要求

**最低要求:**
- Linux Kernel >= 2.6.38
- GCC 4.4+
- 内存：至少 64MB
- 网络：访问 Claude API

**推荐配置:**
- Linux Kernel: 2.6.38.20120518+
- GCC: 4.5+
- 内存：128MB+
- 存储：50MB 可用空间

---

## 🚀 快速开始

### 1. 安装依赖

**CentOS/RHEL 5/6:**
```bash
sudo yum groupinstall "Development Tools"
sudo yum install libcurl-devel openssl-devel
```

**Ubuntu/Debian:**
```bash
sudo apt-get update
sudo apt-get install -y build-essential libcurl4-openssl-dev libcjson-dev libssl-dev pkg-config
```

### 2. 编译

```bash
cd mimiclaw-linux
make clean
make
```

编译成功后显示：
```
╔═══════════════════════════════════════╗
║   Build complete!                     ║
║   Run: ./mimiclaw                     ║
║   WebSocket: ws://localhost:8080      ║
║   Linux 2.6.38+ compatible            ║
╚═══════════════════════════════════════╝
```

### 3. 配置 API 密钥

```bash
cp config/secrets.h.example config/secrets.h
nano config/secrets.h
```

编辑以下内容：
```c
#define MIMI_SECRET_ANTHROPIC_API_KEY "sk-ant-api03-YOUR_API_KEY_HERE"
```

### 4. 运行

```bash
./mimiclaw
```

启动成功显示：
```
╔═══════════════════════════════════════╗
║   MimiClaw for Linux v1.1.0           ║
║   AI Agent with Feishu WebSocket      ║
║   Linux 2.6.38+ compatible            ║
╚═══════════════════════════════════════╝

[Main] ✓ Feishu WebSocket Server started on port 8080
```

---

## 💬 使用 WebSocket

### 方式 A: 使用 wscat

```bash
npm install -g wscat
wscat -c ws://localhost:8080

# 发送消息
{"content": "你好，AI！"}
```

### 方式 B: 使用 Python

```python
import websocket
import json

ws = websocket.WebSocket()
ws.connect("ws://localhost:8080")

ws.send(json.dumps({"content": "你好！"}))
print(ws.recv())

ws.close()
```

### 方式 C: 使用 Node.js

```javascript
const WebSocket = require('ws');
const ws = new WebSocket('ws://localhost:8080');

ws.on('message', (data) => {
    console.log('Received:', data.toString());
});

ws.send(JSON.stringify({content: "你好！"}));
```

### 消息格式

**客户端 → 服务器:**
```json
{
    "content": "你的问题或消息内容",
    "chat_id": "可选的聊天 ID"
}
```

**服务器 → 客户端:**
```json
{
    "type": "response",
    "content": "AI 的回复内容",
    "chat_id": "会话 ID"
}
```

---

## 📁 项目结构

```
mimiclaw-linux/
├── src/
│   ├── main.c                  # 主程序入口
│   ├── agent/                  # Agent 循环（ReAct 模式）
│   │   ├── agent_loop.h
│   │   └── agent_loop.c
│   ├── channels/               # 通信频道
│   │   └── feishu/             # 飞书 WebSocket 服务器
│   │       ├── feishu_bot.h
│   │       └── feishu_bot.c
│   ├── llm/                    # Claude API 代理
│   │   ├── llm_proxy.h
│   │   └── llm_proxy.c
│   ├── tools/                  # 工具实现
│   │   ├── tool_registry.*
│   │   ├── tool_gpio.c
│   │   └── tool_web_search.c
│   ├── memory/                 # 会话和记忆管理
│   │   ├── session_mgr.*
│   │   └── ...
│   ├── bus/                    # 消息队列
│   │   ├── queue.h
│   │   └── queue.c
│   └── utils/                  # 配置和工具函数
│       └── config.h
├── config/                     # 配置文件
│   ├── secrets.h.example
│   ├── SOUL.md
│   └── USER.md
├── Makefile                    # 编译脚本
└── README.md                   # 本文档
```

---

## 🎯 功能特性

### 核心功能

- ✅ **WebSocket 服务器** - 实时双向通信（端口 8080）
- ✅ **Claude API** - 集成 Anthropic Claude 大模型  
- ✅ **工具调用** - web_search、gpio_write 等工具
- ✅ **会话管理** - JSONL 格式持久化存储
- ✅ **GPIO 控制** - Linux sysfs 接口操作硬件
- ✅ **多客户端** - 支持最多 10 个并发连接

### Linux 2.6.38 特性

- ✅ gettimeofday() 时间处理
- ✅ POSIX 标准兼容
- ✅ pthread 线程支持
- ✅ Socket 编程优化

### WebSocket 特性

- ✅ 文本帧传输
- ✅ 基础握手协议
- ✅ JSON 消息格式
- ✅ 广播和单播支持

---

## 🔧 配置说明

### 修改 WebSocket 端口

编辑 `config/secrets.h`:
```c
#define FEISHU_WS_PORT  9000  // 改为其他端口
```

### 内存优化（小内存系统）

对于 < 256MB 内存的系统，编辑 `src/utils/config.h`:
```c
#define FEISHU_WS_MAX_CLIENTS  5  // 减少到 5 个
#define MIMI_MAX_CONTEXT_SIZE  4096  // 减小上下文
```

### GPIO 控制（可选）

```bash
# 导出 GPIO 引脚
echo 4 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio4/direction

# 运行程序（需要 root）
sudo ./mimiclaw
```

### Web 搜索（可选）

在 `config/secrets.h` 中配置 Brave Search API：
```c
#define MIMI_SECRET_SEARCH_KEY "your_search_api_key"
```

---

## �� 安装指南

### 详细步骤

#### 1. 检查系统

```bash
# 查看内核版本
uname -r

# 查看 GCC 版本
gcc --version

# 检查依赖
pkg-config --exists libcurl && echo "libcurl OK" || echo "libcurl missing"
pkg-config --exists libcjson && echo "cJSON OK" || echo "cJSON missing"
pkg-config --exists openssl && echo "OpenSSL OK" || echo "OpenSSL missing"
```

#### 2. 安装缺失的依赖

**如果缺少 cJSON:**
```bash
cd /tmp
wget https://github.com/DaveGamble/cJSON/archive/v1.7.14.tar.gz
tar xzf v1.7.14.tar.gz
cd cJSON-1.7.14
mkdir build && cd build
cmake ..
make
sudo make install
```

#### 3. 编译项目

```bash
cd /home/ubuntu/myfile/project/mimiclaw-linux
make clean
make
```

#### 4. 测试运行

```bash
./mimiclaw
```

#### 5. 安装到系统（可选）

```bash
sudo make install
# 安装到 /usr/local/bin/mimiclaw
```

---

## 🪶 飞书配置

### 在飞书开放平台创建应用

1. 访问 [飞书开放平台](https://open.feishu.cn/app)
2. 登录企业账号
3. 点击"创建应用"
4. 选择"自建应用"
5. 填写应用名称和描述

### 获取 App ID 和 App Secret

1. 进入应用管理页面
2. 在"凭证与基础信息"中找到：
   - **App ID** (cli_开头)
   - **App Secret** (点击获取)

### 配置应用权限

添加以下权限：
- `im:message` - 发送消息
- `im:chat` - 获取聊天信息
- `contact:contact` - 读取联系人（可选）

### 配置事件订阅

#### 方式 A: 公网 URL（生产环境）

1. 准备公网服务器
2. 配置 HTTPS 回调地址
3. 在"事件订阅"中填写请求网址
4. 验证并保存

#### 方式 B: 本地测试（开发环境）

使用 ngrok 内网穿透：
```bash
npm install -g ngrok
ngrok http 8080
```

---

## 🐛 故障排除

### 编译错误

**问题 1: clock_gettime undefined**

解决：
```bash
# 代码已使用 gettimeofday 替代
# 如仍有问题，添加实时库链接
echo "LDFLAGS += -lrt" >> Makefile
make clean && make
```

**问题 2: 找不到头文件**

解决：
```bash
# Ubuntu/Debian
sudo apt-get install libcurl4-openssl-dev libcjson-dev libssl-dev

# CentOS/RHEL
sudo yum install libcurl-devel cJSON-devel openssl-devel
```

### 运行错误

**问题 1: WebSocket 无法连接**

检查：
```bash
# 查看端口监听
netstat -tlnp | grep 8080

# 查看进程
ps aux | grep mimiclaw

# 检查防火墙
iptables -L -n | grep 8080
```

**问题 2: 收不到响应**

检查：
- Claude API Key 是否正确
- 网络连接是否正常
- 查看终端日志

### 性能问题

**老系统优化:**
```bash
# 增加堆栈大小
ulimit -s 8192

# 调整文件描述符
ulimit -n 4096
```

---

## 🔬 技术细节

### 兼容性实现

#### 时间函数

```c
// Linux 2.6.38 兼容
struct timeval now;
gettimeofday(&now, NULL);
ts.tv_sec = now.tv_sec + timeout_ms / 1000;
ts.tv_nsec = now.tv_usec * 1000 + (timeout_ms % 1000) * 1000000;
```

#### 编译标志

```makefile
-D_GNU_SOURCE
-D_POSIX_C_SOURCE=200112L
```

### WebSocket 协议

当前实现支持：
- ✅ 文本帧（Text Frames）
- ✅ 基础握手（Basic Handshake）
- ✅ 简单帧处理

### 已知限制

⚠️ **注意:**

1. **epoll**: 未使用，采用简单的 accept 模式
   - 原因：简化代码，减少依赖
   - 影响：并发连接数受限（最多 10 个）

2. **TCP_NODELAY**: 未启用
   - 可能轻微延迟
   - 可手动添加优化

3. **IPv6**: 仅支持 IPv4
   - 如需 IPv6 需修改 socket 创建部分

### 性能对比

| Linux 版本 | 最大连接数 | 响应延迟 | 稳定性 |
|-----------|-----------|---------|--------|
| 2.6.38    | 10        | ~50ms   | ✅ 良好 |
| 2.6.39+   | 10        | ~45ms   | ✅ 良好 |
| 3.x+      | 10        | ~40ms   | ✅ 优秀 |

---

## 🎯 嵌入式部署

### 概述
MimiClaw 专门针对 Linux 2.6.38+ 嵌入式设备进行了优化，可在资源受限的环境中运行。

### 嵌入式设备要求
- **内核**: Linux 2.6.38.20120518+
- **内存**: 64MB RAM (推荐128MB+)
- **存储**: 32MB 可用空间
- **网络**: 访问 Claude API 的网络连接

### 交叉编译
#### 1. 配置工具链
```bash
export CROSS_COMPILE=arm-linux-gnueabihf-
export CC=${CROSS_COMPILE}gcc
```

#### 2. 编译依赖库
- **cJSON**: 静态链接减小体积
- **libcurl**: 最小配置，禁用不需要的功能
- **OpenSSL**: 基础TLS支持

#### 3. 构建 MimiClaw
```bash
make clean
make
```

### 资源优化配置
#### 内存优化
编辑 `src/utils/config.h`:
```c
#define MIMI_MAX_CONTEXT_SIZE 4096      // 减小上下文大小
#define FEISHU_WS_MAX_CLIENTS 3         // 减少并发连接
```

### 系统集成
#### 启动脚本
创建 `/etc/init.d/mimiclaw`:
```bash
#!/bin/sh
DAEMON=/usr/bin/mimiclaw
start-stop-daemon --start --background --exec $DAEMON
```

#### 开机启动
添加到 `/etc/rc.local`:
```bash
/usr/bin/mimiclaw > /var/log/mimiclaw.log 2>&1 &
```

### 性能调优
| 参数 | 默认值 | 嵌入式推荐值 |
|------|--------|--------------|
| 上下文大小 | 8192 | 4096 |
| 并发连接数 | 10 | 3 |
| 工具调用次数 | 10 | 5 |

### 故障排除
#### 内存不足
```bash
# 优化交换空间
dd if=/dev/zero of=/swapfile bs=1M count=64
mkswap /swapfile
swapon /swapfile
```

#### 网络连接失败
```bash
# 检查防火墙
iptables -L -n | grep 8080
```

### 详细文档
完整嵌入式部署指南请参考: [EMBEDDED_DEPLOYMENT.md](docs_backup/EMBEDDED_DEPLOYMENT.md)

---

## 📝 许可证

MIT License

---

## 🎉 祝你使用愉快！

如有问题，请查阅本文档或提交 Issue。

**Happy Coding!** 🚀