Content
# AOS - Enterprise Virtual Assistant PoC
> Multi-Agent Collaborative Virtual Assistant Platform based on OpenClaw
## 🚀 Quick Start
### Prerequisites
- Python 3.11+
- Node.js 18+
- OpenClaw (pre-installed)
- LLM API Key (OpenAI / DeepSeek / Any one)
### Installation
**Windows:**
```bat
install.bat
```
**Linux/macOS:**
```bash
chmod +x install.sh start.sh stop.sh
./install.sh
```
### Configure LLM
Edit `backend/.env`:
```env
# Use OpenAI
LLM_PROVIDER=openai
LLM_API_KEY=sk-your-key-here
LLM_MODEL=gpt-4o-mini
# Or use DeepSeek
LLM_PROVIDER=deepseek
LLM_API_KEY=sk-your-key-here
LLM_MODEL=deepseek-chat
# Or use Qwen
LLM_PROVIDER=qwen
LLM_API_KEY=sk-your-key-here
LLM_MODEL=qwen-plus
```
### Start
**Windows:** `start.bat`
**Linux/macOS:** `./start.sh`
Open browser and visit http://localhost:5173
### Stop
**Windows:** `stop.bat`
**Linux/macOS:** `./stop.sh`
---
## 🏗️ System Architecture
```
┌──────────────────────────────────────────────────────────┐
│ User Interface Layer │
│ Web UI (React + Vite) │ OpenClaw CLI/App │
├──────────────────────────────────────────────────────────┤
│ MCP Protocol Layer (Bidirectional) │
│ ┌──────────────┐ ┌──────────────────┐ │
│ │ MCP Server │◄────JSON-RPC─►│ OpenClaw Gateway │ │
│ │ (AOS→External) │ stdio/HTTP │ (External→AOS) │ │
│ └──────────────┘ └──────────────────┘ │
├──────────────────────────────────────────────────────────┤
│ API Gateway Layer │
│ FastAPI (REST API + MCP Tools) │
├──────────────────────────────────────────────────────────┤
│ Agent Collaboration Layer │
│ 🧠Architect ✍️Scribe 📂Sorter 🔍Seeker │
│ 🔗Connector 📚Librarian 🎙️Transcriber 📮Postman │
├──────────────────────────────────────────────────────────┤
│ Core Standard Layer │
│ Memory Standard | Strategy Standard | Personality Standard | Workflow Standard │
│ Object Standard | Tool Standard | OpenClaw Bridge │
├──────────────────────────────────────────────────────────┤
│ Data Storage Layer │
│ SQLite | Local File System | Vector Index │
└──────────────────────────────────────────────────────────┘
```
---
## 🔌 OpenClaw MCP Integration
AOS integrates with OpenClaw through **MCP (Model Context Protocol)** for bidirectional communication.
### Bidirectional Integration Mode
| Integration Direction | Role | Implementation File | Description |
|---------|------|---------|------|
| OpenClaw → AOS | AOS is MCP Server | `backend/app/mcp_server.py` | OpenClaw calls AOS's knowledge/task/memory/conversation tools |
| AOS → OpenClaw | AOS is MCP Client | `backend/app/adapters/openclaw.py` | AOS Agent borrows OpenClaw's file/browser/Git tools |
### Mode 1: AOS as MCP Server (Core)
OpenClaw discovers and connects to AOS through `openclaw.json`:
```json
{
"mcpServers": {
"aos": {
"command": "python",
"args": ["-m", "app.mcp_server"],
"cwd": "./backend",
"transport": "stdio"
}
}
}
```
AOS exposes MCP tools (15 in total):
| Tool Name | Description |
|--------|------|
| `aos_chat` | Send message to AOS (auto-routing or specify Agent) |
| `aos_list_agents` | List all Agents |
| `aos_switch_agent` | Switch Agent |
| `aos_create_knowledge` | Create knowledge entry |
| `aos_search_knowledge` | Search knowledge base |
| `aos_get_knowledge` | Get document content |
| `aos_create_task` | Create task |
| `aos_list_tasks` | List tasks |
| `aos_update_task` | Update task |
| `aos_store_memory` | Store memory (6 layers) |
| `aos_recall_memory` | Recall memory |
| `aos_system_status` | System status |
| `aos_health_check` | Health check |
| `aos_list_sessions` | List sessions |
| `aos_export_data` | Export data |
**Test MCP Server separately:**
```bash
cd aos-poc/backend
python -m app.mcp_server
```
### Mode 2: AOS Agent Calls OpenClaw Tools
AOS Agent embeds `[TOOL_CALL: ...]` instructions in replies, and the system executes through OpenClaw Bridge:
```
# Agent reply example
Let me help you check the local file...
[TOOL_CALL: read_file(path="/Users/xx/notes.md")]
# System execution:
1. Parse [TOOL_CALL: ...] instruction
2. Execute tools/call through OpenClaw CLI
3. Inject result into context
4. Agent continues reasoning based on tool result
```
### OpenClaw Workspace Files
| File | Description |
|------|------|
| `SKILL.md` | AOS skill definition + MCP tool list |
| `SOUL.md` | AOS identity/principles/memory strategy |
| `AGENTS.md` | Agent coordination rules |
| `openclaw.json` | MCP Server registration configuration |
---
## 🤖 Agent Team
| Agent | Role | Responsibility |
|-------|------|------|
| 🧠 Architect | Mentor | System brain, new user guidance, workflow planning |
| ✍️ Scribe | Assistant | Consciousness → structured notes, extract to-do |
| 📂 Sorter | Assistant | Inbox cleaning, file classification, archiving |
| 🔍 Seeker | Assistant | Cross-knowledge base retrieval, comprehensive answering |
| 🔗 Connector | Mentor | Discover hidden associations, cross-domain insights |
| 📚 Librarian | Assistant | Weekly warehouse physical examination, data quality analysis |
| 🎙️ Transcriber | Assistant | Recording → meeting minutes, extract action items |
| 📮 Postman | Avatar | Email draft return, calendar management |
## 🧠 6-Layer Memory Model
| Layer | Description |
|------|------|
| ShortTerm | Session-level context window |
| LongTerm | Persistent knowledge (vector retrieval) |
| Episodic | Key event records |
| Procedural | Workflow preferences |
| Profile | User profile (device-side storage) |
| Policy | Strategic learning memory |
## 🔒 Security Strategy
- High-risk operations (delete/send/pay/sign/permission change) automatically require confirmation
- User profile stored only on device-side
- Data export supports encryption
- Full operation audit log
## 📁 Directory Structure
```
aos-poc/
├── SKILL.md # OpenClaw skill definition (MCP tool list)
├── SOUL.md # OpenClaw soul definition
├── AGENTS.md # Agent coordination rules
├── openclaw.json # OpenClaw MCP Server registration
├── backend/ # FastAPI backend
│ ├── app/
│ │ ├── agents/ # 8 Agent implementations
│ │ ├── adapters/ # OpenClaw Bridge (MCP Client)
│ │ ├── api/ # REST API routes
│ │ ├── core/ # Core standard layer
│ │ ├── mcp_server.py # MCP Server (for OpenClaw connection)
│ │ └── main.py # Application entry
│ ├── data/ # Local data storage
│ └── .env # Environment configuration
├── frontend/ # React frontend
│ └── src/
│ ├── components/ # UI components
│ ├── stores/ # State management
│ └── api/ # API client
├── agents/ # Agent SKILL.md/SOUL.md
│ ├── architect/
│ ├── scribe/
│ └── ...
├── install.bat/.sh
├── start.bat/.sh
├── stop.bat/.sh
└── README.md
```
## 📡 API Endpoints
| Method | Path | Description |
|------|------|------|
| POST | `/api/chat` | Send message |
| GET | `/api/chat/sessions` | Session list |
| GET | `/api/agents` | Agent list |
| POST | `/api/agents/switch` | Switch Agent |
| GET/POST | `/api/knowledge` | Knowledge base CRUD |
| GET/POST | `/api/tasks` | Task CRUD |
| GET/POST | `/api/memory` | Memory management |
| POST | `/api/data/export` | Export data |
| POST | `/api/data/import` | Import data |
| GET | `/api/mcp/tools` | MCP tool discovery (compliant with MCP specification) |
| GET | `/api/system` | System information (including OpenClaw status) |
| GET | `/health` | Health check |
## 📄 License
AOS Virtual Assistant © 2026. All rights reserved.
