feat: openclaw-style secrets (env.vars + \) and per-task model routing
- Replace python-dotenv with config.json env.vars block + \ substitution - Add models section for per-task model routing (heartbeat, subagent, default) - Heartbeat/subagent tasks can use different models/providers than main chat - Remove python-dotenv from dependencies - Update all docs to reflect new config approach - Reorganize docs into project/ and research/ subdirectories
This commit is contained in:
243
docs/research/comparison.md
Normal file
243
docs/research/comparison.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# ⚔️ Aetheel vs. Inspiration Repos — Comparison & Missing Features
|
||||
|
||||
> A detailed comparison of Aetheel with Nanobot, NanoClaw, OpenClaw, and PicoClaw — highlighting what's different, what's missing, and what can be added.
|
||||
|
||||
---
|
||||
|
||||
## Feature Comparison Matrix
|
||||
|
||||
| Feature | Aetheel | Nanobot | NanoClaw | OpenClaw | PicoClaw |
|
||||
|---------|---------|---------|----------|----------|----------|
|
||||
| **Language** | Python | Python | TypeScript | TypeScript | Go |
|
||||
| **Channels** | Slack only | 9 channels | WhatsApp only | 15+ channels | 5 channels |
|
||||
| **LLM Runtime** | OpenCode / Claude Code (subprocess) | LiteLLM (multi-provider) | Claude Agent SDK | Pi Agent (custom RPC) | Go-native agent |
|
||||
| **Memory** | Hybrid (vector + BM25) | Simple file-based | Per-group CLAUDE.md | Workspace files | MEMORY.md + sessions |
|
||||
| **Config** | `config.json` with `env.vars` + `${VAR}` | `config.json` | Code changes (no config) | JSON5 config | `config.json` |
|
||||
| **Skills** | ❌ None | ✅ Bundled + custom | ✅ Code skills (transform) | ✅ Bundled + managed + workspace | ✅ Custom skills |
|
||||
| **Scheduled Tasks** | ⚠️ Action tags (remind only) | ✅ Full cron system | ✅ Task scheduler | ✅ Cron + webhooks + Gmail | ✅ Cron + heartbeat |
|
||||
| **Security** | ❌ No sandbox | ⚠️ Workspace restriction | ✅ Container isolation | ✅ Docker sandbox + pairing | ✅ Workspace sandbox |
|
||||
| **MCP Support** | ❌ No | ✅ Yes | ❌ No | ❌ No | ❌ No |
|
||||
| **Web Search** | ❌ No | ✅ Brave Search | ✅ Via Claude tools | ✅ Browser control | ✅ Brave + DuckDuckGo |
|
||||
| **Voice** | ❌ No | ✅ Via Groq Whisper | ❌ No | ✅ Voice Wake + Talk Mode | ✅ Via Groq Whisper |
|
||||
| **Browser Control** | ❌ No | ❌ No | ❌ No | ✅ Full CDP control | ❌ No |
|
||||
| **Companion Apps** | ❌ No | ❌ No | ❌ No | ✅ macOS + iOS + Android | ❌ No |
|
||||
| **Session Management** | ✅ Thread-based (Slack) | ✅ Session-based | ✅ Per-group isolated | ✅ Full sessions + agent-to-agent | ✅ Session-based |
|
||||
| **Docker Support** | ❌ No | ✅ Yes | ❌ (uses Apple Container) | ✅ Full compose setup | ✅ Yes |
|
||||
| **Install Script** | ✅ Yes | ✅ pip/uv install | ✅ Claude guides setup | ✅ npm + wizard | ✅ Binary / make |
|
||||
| **Identity Files** | ✅ SOUL.md, USER.md, MEMORY.md | ✅ AGENTS.md, SOUL.md, USER.md, etc. | ✅ CLAUDE.md per group | ✅ AGENTS.md, SOUL.md, USER.md, TOOLS.md | ✅ Full set (AGENTS, SOUL, IDENTITY, USER, TOOLS) |
|
||||
| **Subagents** | ❌ No | ✅ Spawn subagent | ✅ Agent Swarms | ✅ sessions_send / sessions_spawn | ✅ Spawn subagent |
|
||||
| **Heartbeat/Proactive** | ❌ No | ✅ Heartbeat | ❌ No | ✅ Cron + wakeups | ✅ HEARTBEAT.md |
|
||||
| **Multi-provider** | ⚠️ Via OpenCode/Claude | ✅ 12+ providers | ❌ Claude only | ✅ Multi-model + failover | ✅ 7+ providers |
|
||||
| **WebChat** | ❌ No | ❌ No | ❌ No | ✅ Built-in WebChat | ❌ No |
|
||||
|
||||
---
|
||||
|
||||
## What Aetheel Does Well
|
||||
|
||||
### ✅ Strengths
|
||||
|
||||
1. **Advanced Memory System** — Aetheel has the most sophisticated memory system with **hybrid search (0.7 vector + 0.3 BM25)**, local embeddings via `fastembed`, and SQLite FTS5. None of the other repos have this level of memory sophistication.
|
||||
|
||||
2. **Local-First Embeddings** — Zero API calls for memory search. Uses ONNX-based local model (BAAI/bge-small-en-v1.5).
|
||||
|
||||
3. **Dual Runtime Support** — Clean abstraction allowing switching between OpenCode and Claude Code with the same `AgentResponse` interface.
|
||||
|
||||
4. **Thread Isolation in Slack** — Each Slack thread gets its own AI session, providing natural conversation isolation.
|
||||
|
||||
5. **Action Tags** — Inline `[ACTION:remind|minutes|message]` tags are elegant for in-response scheduling.
|
||||
|
||||
6. **File Watching** — Memory auto-reindexes when `.md` files are edited.
|
||||
|
||||
---
|
||||
|
||||
## What Aetheel Is Missing
|
||||
|
||||
### 🔴 Critical Gaps (High Priority)
|
||||
|
||||
#### 1. Multi-Channel Support
|
||||
**Current:** Slack only
|
||||
**All others:** Multiple channels (3-15+)
|
||||
|
||||
Aetheel is locked to Slack. Adding at least **Telegram** and **Discord** would significantly increase usability. All four inspiration repos treat multi-channel as essential.
|
||||
|
||||
> **Recommendation:** Follow Nanobot's pattern — each channel is a module in `channels/` with a common interface. Start with Telegram (easiest — just a token).
|
||||
|
||||
#### 2. Skills System
|
||||
**Current:** None
|
||||
**Others:** All have skills/plugins
|
||||
|
||||
Aetheel has no way to extend agent capabilities beyond its hardcoded memory and runtime setup. A skills system would allow:
|
||||
- Bundled skills (GitHub, weather, web search)
|
||||
- User-created skills in workspace
|
||||
- Community-contributed skills
|
||||
|
||||
> **Recommendation:** Create a `skills/` directory in the workspace. Skills are markdown files (`SKILL.md`) that get injected into the agent's context.
|
||||
|
||||
#### 3. Scheduled Tasks (Cron)
|
||||
**Current:** Only `[ACTION:remind]` (one-time, simple)
|
||||
**Others:** Full cron systems with persistent storage
|
||||
|
||||
The action tag system is clever but limited. A proper cron system would support:
|
||||
- Recurring cron expressions (`0 9 * * *`)
|
||||
- Interval-based scheduling
|
||||
- Persistent job storage
|
||||
- CLI management
|
||||
|
||||
> **Recommendation:** Add a `cron/` module with SQLite-backed job storage and an APScheduler-based execution engine.
|
||||
|
||||
#### 4. Security Sandbox
|
||||
**Current:** No sandboxing
|
||||
**Others:** Container isolation (NanoClaw), workspace restriction (PicoClaw), Docker sandbox (OpenClaw)
|
||||
|
||||
The AI runtime has unrestricted system access. At minimum, workspace-level restrictions should be added.
|
||||
|
||||
> **Recommendation:** Follow PicoClaw's approach — restrict tool access to workspace directory by default. Block dangerous shell commands.
|
||||
|
||||
---
|
||||
|
||||
### 🟡 Important Gaps (Medium Priority)
|
||||
|
||||
#### 5. Config File System (JSON with env.vars — ✅ Done)
|
||||
**Current:** `config.json` with `env.vars` block and `${VAR}` substitution for secrets
|
||||
**Others:** JSON/JSON5 config files
|
||||
|
||||
Aetheel now uses a single config.json with an `env.vars` block for secrets and `${VAR}` references, matching openclaw's approach.
|
||||
|
||||
> **Status:** ✅ Implemented — no separate `.env` file needed.
|
||||
|
||||
#### 6. Web Search Tool
|
||||
**Current:** No web search
|
||||
**Others:** Brave Search, DuckDuckGo, or full browser control
|
||||
|
||||
The agent can't search the web. This is a significant limitation for a personal assistant.
|
||||
|
||||
> **Recommendation:** Add Brave Search API integration (free tier: 2000 queries/month) with DuckDuckGo as fallback.
|
||||
|
||||
#### 7. Subagent / Spawn Capability
|
||||
**Current:** No subagents
|
||||
**Others:** All have spawn/subagent systems
|
||||
|
||||
For long-running tasks, the main agent should be able to spawn background sub-tasks that work independently and report back.
|
||||
|
||||
> **Recommendation:** Add a `spawn` tool that creates a background thread/process running a separate agent session.
|
||||
|
||||
#### 8. Heartbeat / Proactive System
|
||||
**Current:** No proactive capabilities
|
||||
**Others:** Nanobot and PicoClaw have heartbeat systems
|
||||
|
||||
The agent only responds to messages. A heartbeat system would allow periodic check-ins, proactive notifications, and scheduled intelligence.
|
||||
|
||||
> **Recommendation:** Add `HEARTBEAT.md` file + periodic timer that triggers agent with heartbeat tasks.
|
||||
|
||||
#### 9. CLI Interface
|
||||
**Current:** Only `python main.py` with flags
|
||||
**Others:** Full CLI with subcommands (`nanobot agent`, `picoclaw cron`, etc.)
|
||||
|
||||
> **Recommendation:** Add a CLI using `click` or `argparse` with subcommands: `aetheel chat`, `aetheel status`, `aetheel cron`, etc.
|
||||
|
||||
#### 10. Tool System
|
||||
**Current:** No explicit tool system (AI handles everything via runtime)
|
||||
**Others:** Shell exec, file R/W, web search, spawn, message, etc.
|
||||
|
||||
Aetheel delegates all tool use to the AI runtime (OpenCode/Claude Code). While this works, having explicit tools gives more control and allows sandboxing.
|
||||
|
||||
> **Recommendation:** Define a tool interface and implement core tools (file ops, shell, web search) that run through the aetheel process with sandboxing.
|
||||
|
||||
---
|
||||
|
||||
### 🟢 Nice-to-Have (Lower Priority)
|
||||
|
||||
#### 11. MCP Server Support
|
||||
Only Nanobot supports MCP. Would allow connecting external tool servers.
|
||||
|
||||
#### 12. Multi-Provider Support
|
||||
Currently relies on OpenCode/Claude Code for provider handling. Direct multi-provider support (like Nanobot's 12+ providers via LiteLLM) would add flexibility.
|
||||
|
||||
#### 13. Docker / Container Support
|
||||
No Docker compose or containerized deployment option.
|
||||
|
||||
#### 14. Agent-to-Agent Communication
|
||||
OpenClaw's `sessions_send` allows agents to message each other. Useful for multi-agent workflows.
|
||||
|
||||
#### 15. Gateway Architecture
|
||||
Moving from a direct Slack adapter to a gateway pattern would make adding channels much easier.
|
||||
|
||||
#### 16. Onboarding Wizard
|
||||
OpenClaw's `onboard --install-daemon` provides a guided setup. Aetheel's install script is good but could be more interactive.
|
||||
|
||||
#### 17. Voice Support
|
||||
Voice Wake / Talk Mode (OpenClaw) or Whisper transcription (Nanobot, PicoClaw).
|
||||
|
||||
#### 18. WebChat Interface
|
||||
A browser-based chat UI connected to the gateway.
|
||||
|
||||
#### 19. TOOLS.md File
|
||||
A `TOOLS.md` file describing available tools to the agent, used by PicoClaw and OpenClaw.
|
||||
|
||||
#### 20. Self-Modification
|
||||
From `additions.txt`: "edit its own files and config as well as add skills" — the agent should be able to modify its own configuration and add new skills.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Comparison
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph Aetheel["⚔️ Aetheel (Current)"]
|
||||
A_SLACK["Slack\n(only channel)"]
|
||||
A_MAIN["main.py"]
|
||||
A_MEM["Memory\n(hybrid search)"]
|
||||
A_RT["OpenCode / Claude\n(subprocess)"]
|
||||
end
|
||||
|
||||
subgraph Target["🎯 Target Architecture"]
|
||||
T_CHAN["Multi-Channel\nGateway"]
|
||||
T_CORE["Core Agent\n+ Tool System"]
|
||||
T_MEM["Memory\n(hybrid search)"]
|
||||
T_SK["Skills"]
|
||||
T_CRON["Cron"]
|
||||
T_PROV["Multi-Provider"]
|
||||
T_SEC["Security\nSandbox"]
|
||||
end
|
||||
|
||||
A_SLACK --> A_MAIN
|
||||
A_MAIN --> A_MEM
|
||||
A_MAIN --> A_RT
|
||||
|
||||
T_CHAN --> T_CORE
|
||||
T_CORE --> T_MEM
|
||||
T_CORE --> T_SK
|
||||
T_CORE --> T_CRON
|
||||
T_CORE --> T_PROV
|
||||
T_CORE --> T_SEC
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prioritized Roadmap Suggestion
|
||||
|
||||
Based on the analysis, here's a suggested implementation order:
|
||||
|
||||
### Phase 1: Foundation (Essentials)
|
||||
1. **Config system** — ✅ Done: `config.json` with `env.vars` + `${VAR}` substitution
|
||||
2. **Skills system** — `skills/` directory with `SKILL.md` loading
|
||||
3. **Tool system** — Core tools (shell, file, web search) with sandbox
|
||||
4. **Security sandbox** — Workspace-restricted tool execution
|
||||
|
||||
### Phase 2: Channels & Scheduling
|
||||
5. **Channel abstraction** — Extract adapter interface from Slack adapter
|
||||
6. **Telegram channel** — First new channel
|
||||
7. **Cron system** — Full scheduled task management
|
||||
8. **CLI** — Proper CLI with subcommands
|
||||
|
||||
### Phase 3: Advanced Features
|
||||
9. **Heartbeat** — Proactive agent capabilities
|
||||
10. **Subagents** — Spawn background tasks
|
||||
11. **Discord channel** — Second new channel
|
||||
12. **Web search** — Brave Search + DuckDuckGo
|
||||
|
||||
### Phase 4: Polish
|
||||
13. **Self-modification** — Agent can edit config and add skills
|
||||
14. **Docker support** — Dockerfile + compose
|
||||
15. **MCP support** — External tool servers
|
||||
16. **WebChat** — Browser-based chat UI
|
||||
Reference in New Issue
Block a user