diff --git a/README.md b/README.md index b5bf0d5..4c9ba7a 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ # MimiClaw: Pocket AI Assistant on a $5 Chip +**[English](README.md) | [中文](README_CN.md)** +

MimiClaw

-**The world's first AI assistant on a $5 chip. No Linux. No Node.js. Just pure C** +**The world's first AI assistant(OpenClaw) on a $5 chip. No Linux. No Node.js. Just pure C** MimiClaw turns a tiny ESP32-S3 board into a personal AI assistant. Plug it into USB power, connect to WiFi, and talk to it through Telegram — it handles any task you throw at it and evolves over time with local memory — all on a chip the size of a thumb. @@ -81,7 +83,9 @@ That's it. After restart, find your bot on Telegram and start chatting. ``` mimi> wifi_status # am I connected? -mimi> set_model claude-sonnet-4-5-20241022 # use a different model +mimi> set_model claude-opus-4-6 # use a different model +mimi> set_proxy 10.0.0.1 7897 # optional: route through HTTP proxy +mimi> clear_proxy # optional: remove proxy, connect directly mimi> memory_read # see what the bot remembers mimi> heap_info # how much RAM is free? mimi> session_list # list all chat sessions @@ -106,6 +110,7 @@ MimiClaw stores everything as plain text files you can read and edit: - **WebSocket gateway** on port 18789 — connect from your LAN with any WebSocket client - **OTA updates** — flash new firmware over WiFi, no USB needed - **Dual-core** — network I/O and AI processing run on separate CPU cores +- **HTTP proxy** — CONNECT tunnel support for restricted networks ## For Developers @@ -120,4 +125,4 @@ MIT ## Acknowledgments -Inspired by [OpenClaw](https://github.com/openclaw/openclaw). MimiClaw reimplements the core AI agent architecture for embedded hardware — no Linux, no server, just a $5 chip. +Inspired by [OpenClaw](https://github.com/openclaw/openclaw) and [Nanobot](https://github.com/HKUDS/nanobot). MimiClaw reimplements the core AI agent architecture for embedded hardware — no Linux, no server, just a $5 chip. diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 0000000..d921599 --- /dev/null +++ b/README_CN.md @@ -0,0 +1,151 @@ +# MimiClaw: $5 芯片上的口袋 AI 助理 + +**[English](README.md) | [中文](README_CN.md)** + +

+ MimiClaw +

+ +**$5 芯片上的 AI 助理（OpenClaw）。没有 Linux，没有 Node.js，纯 C。** + +MimiClaw 把一块小小的 ESP32-S3 开发板变成你的私人 AI 助理。插上 USB 供电，连上 WiFi，通过 Telegram 跟它对话 — 它能处理你丢给它的任何任务，还会随时间积累本地记忆不断进化 — 全部跑在一颗拇指大小的芯片上。 + +## 认识 MimiClaw + +- **小巧** — 没有 Linux，没有 Node.js，没有臃肿依赖 — 纯 C +- **好用** — 在 Telegram 发消息，剩下的它来搞定 +- **忠诚** — 从记忆中学习，跨重启也不会忘 +- **能干** — USB 供电，0.5W，24/7 运行 +- **可爱** — 一块 ESP32-S3 开发板，$5，没了 + +## 工作原理 + +``` + ┌─────────────── Agent Loop ───────────────┐ + │ │ + ┌───────────┐ ┌─────▼─────┐ ┌─────────┐ ┌─────────┐ │ + │ Channels │ │ Message │ │ Claude │ │ Tools │ │ + │ │────▶│ Queue │────▶│ (LLM) │────▶│ │──┘ + │ Telegram │ └───────────┘ └────┬─────┘ └────┬────┘ + │ WebSocket │◀──────────────────────────-│ │ + └───────────┘ Response │ │ + ┌─────▼────────────────▼────┐ + │ Context │ + │ ┌──────────┐ ┌────────┐ │ + │ │ Memory │ │ Skills │ │ + │ │ SOUL.md │ │ OTA │ │ + │ │ USER.md │ │ CLI │ │ + │ │ MEMORY.md │ │ ... │ │ + │ └──────────┘ └────────┘ │ + └───────────────────────────┘ + ESP32-S3 Flash +``` + +你在 Telegram 发一条消息，ESP32-S3 通过 WiFi 收到后送进 Agent 循环 — Claude 思考、调用工具、读取记忆 — 再把回复发回来。一切都跑在一颗 $5 的芯片上，所有数据存在本地 Flash。 + +## 快速开始 + +### 你需要 + +- 一块 **ESP32-S3 开发板**，16MB Flash + 8MB PSRAM（如小智 AI 开发板，~¥30） +- 一根 **USB Type-C 数据线** +- 一个 **Telegram Bot Token** — 在 Telegram 找 [@BotFather](https://t.me/BotFather) 创建 +- 一个 **Anthropic API Key** — 从 [console.anthropic.com](https://console.anthropic.com) 获取 + +### 安装 + +```bash +# 需要先安装 ESP-IDF: +# https://docs.espressif.com/projects/esp-idf/en/stable/esp32s3/get-started/ + +git clone https://github.com/memovai/mimiclaw.git +cd mimiclaw + +idf.py set-target esp32s3 +idf.py build +idf.py -p /dev/ttyACM0 flash monitor +``` + +### 设置 + +烧录后会出现串口终端，输入以下命令： + +``` +mimi> wifi_set YourWiFiName YourWiFiPassword +mimi> set_tg_token 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 +mimi> set_api_key sk-ant-api03-xxxxx +mimi> restart +``` + +就这样。重启后在 Telegram 找到你的 Bot，开始聊天。 + +### 代理配置（国内用户） + +在国内需要代理才能访问 Telegram 和 Anthropic API。MimiClaw 内置 HTTP CONNECT 隧道支持。 + +**前提**：局域网内有一个支持 HTTP CONNECT 的代理（Clash Verge、V2Ray 等），并开启了「允许局域网连接」。 + +``` +mimi> set_proxy 10.0.0.1 7897 +mimi> restart +``` + +- `10.0.0.1` — 代理机器的局域网 IP +- `7897` — 代理的 HTTP 端口（不是 SOCKS 端口） + +设置后所有 HTTPS 请求通过 CONNECT 隧道发出，TLS 证书正常验证。清除代理恢复直连： + +``` +mimi> clear_proxy +mimi> restart +``` + +> **提示**：确保 ESP32-S3 和代理机器在同一局域网。Clash Verge 在「设置 → 允许局域网」中开启。 + +### 更多命令 + +``` +mimi> wifi_status # 连上了吗？ +mimi> set_model claude-opus-4-6 # 换个模型 +mimi> set_proxy 10.0.0.1 7897 # 可选：通过 HTTP 代理 +mimi> clear_proxy # 可选：清除代理，直连 +mimi> memory_read # 看看它记住了什么 +mimi> heap_info # 还剩多少内存？ +mimi> session_list # 列出所有会话 +mimi> session_clear 12345 # 删除一个会话 +mimi> restart # 重启 +``` + +## 记忆 + +MimiClaw 把所有数据存为纯文本文件，可以直接读取和编辑： + +| 文件 | 说明 | +|------|------| +| `SOUL.md` | 机器人的人设 — 编辑它来改变行为方式 | +| `USER.md` | 关于你的信息 — 姓名、偏好、语言 | +| `MEMORY.md` | 长期记忆 — 它应该一直记住的事 | +| `2026-02-05.md` | 每日笔记 — 今天发生了什么 | +| `tg_12345.jsonl` | 聊天记录 — 你和它的对话 | + +## 其他功能 + +- **WebSocket 网关** — 端口 18789，局域网内用任意 WebSocket 客户端连接 +- **OTA 更新** — WiFi 远程刷固件，无需 USB +- **双核** — 网络 I/O 和 AI 处理分别跑在不同 CPU 核心 +- **HTTP 代理** — CONNECT 隧道，适配受限网络 + +## 开发者 + +技术细节在 `docs/` 文件夹： + +- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — 系统设计、模块划分、任务布局、内存分配、协议、Flash 分区 +- **[docs/TODO.md](docs/TODO.md)** — 功能差距和路线图 + +## 许可证 + +MIT + +## 致谢 + +灵感来自 [OpenClaw](https://github.com/openclaw/openclaw) 和 [Nanobot](https://github.com/HKUDS/nanobot)。MimiClaw 为嵌入式硬件重新实现了核心 AI Agent 架构 — 没有 Linux，没有服务器，只有一颗 $5 的芯片。 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7e31ff8..b85b072 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -119,9 +119,13 @@ main/ │ ├── ws_server.h WebSocket server API │ └── ws_server.c ESP HTTP server with WS upgrade, client tracking │ +├── proxy/ +│ ├── http_proxy.h Proxy connection API +│ └── http_proxy.c HTTP CONNECT tunnel + TLS via esp_tls +│ ├── cli/ │ ├── serial_cli.h CLI init API -│ └── serial_cli.c esp_console REPL with 12 commands +│ └── serial_cli.c esp_console REPL with 14 commands │ └── ota/ ├── ota_manager.h OTA update API @@ -134,9 +138,9 @@ main/ | Task | Core | Priority | Stack | Description | |--------------------|------|----------|--------|--------------------------------------| -| `tg_poll` | 0 | 5 | 8 KB | Telegram long polling (30s timeout) | -| `agent_loop` | 1 | 6 | 8 KB | Message processing + Claude API call | -| `outbound` | 0 | 5 | 4 KB | Route responses to Telegram / WS | +| `tg_poll` | 0 | 5 | 12 KB | Telegram long polling (30s timeout) | +| `agent_loop` | 1 | 6 | 12 KB | Message processing + Claude API call | +| `outbound` | 0 | 5 | 8 KB | Route responses to Telegram / WS | | `serial_cli` | 0 | 3 | 4 KB | USB serial console REPL | | httpd (internal) | 0 | 5 | — | WebSocket server (esp_http_server) | | wifi_event (IDF) | 0 | 8 | — | WiFi event handling (ESP-IDF) | @@ -208,9 +212,11 @@ Session files are JSONL (one JSON object per line): | `wifi_config` | `password` | WiFi password | | `tg_config` | `bot_token` | Telegram Bot API token | | `llm_config` | `api_key` | Anthropic API key | -| `llm_config` | `model` | Model ID (default: claude-opus-4-5-20251101) | +| `llm_config` | `model` | Model ID (default: claude-opus-4-6) | +| `proxy_config`| `host` | HTTP proxy hostname/IP | +| `proxy_config`| `port` | HTTP proxy port | -All configured via Serial CLI commands: `wifi_set`, `set_tg_token`, `set_api_key`, `set_model`. +All configured via Serial CLI commands: `wifi_set`, `set_tg_token`, `set_api_key`, `set_model`, `set_proxy`, `clear_proxy`. --- @@ -257,7 +263,7 @@ Endpoint: `POST https://api.anthropic.com/v1/messages` Request format (Anthropic-native, not OpenAI): ```json { - "model": "claude-opus-4-5-20251101", + "model": "claude-opus-4-6", "max_tokens": 4096, "stream": true, "system": "", @@ -295,6 +301,7 @@ app_main() ├── memory_store_init() Verify SPIFFS paths ├── session_mgr_init() ├── wifi_manager_init() Init WiFi STA mode + event handlers + ├── http_proxy_init() Load proxy config from NVS ├── telegram_bot_init() Load bot token from NVS ├── llm_proxy_init() Load API key + model from NVS ├── agent_loop_init() @@ -323,6 +330,8 @@ If WiFi credentials are missing or connection times out, the CLI remains availab | `set_tg_token ` | Save Telegram bot token | | `set_api_key ` | Save Anthropic API key | | `set_model ` | Set LLM model identifier | +| `set_proxy ` | Set HTTP CONNECT proxy | +| `clear_proxy` | Remove proxy, use direct connection | | `memory_read` | Print MEMORY.md contents | | `memory_write ` | Overwrite MEMORY.md | | `session_list` | List all session files |