NagaAgent

<div align="center"> # NagaAgent **Your 2D Superpowered AI Assistant** Streaming Tool Calls · Knowledge Graph Memory · Live2D Virtual Avatar · Voice Interaction · Naga Network Community The Naga Protocol includes conversation, memory, MCP, skills, and openclaw integration to build a rich and easy-to-use AI tool as a core, becoming a user's side 2D superpowered AI assistant. The software contains the following features: 1. One-click login and automatic configuration of all API keys, interact with Naga, the Live2D avatar, through mouse interactions and intimate conversations; 2. Quickly explore the knowledge domain you need through the built-in OpenClaw, or list task directions and let it automatically explore and execute; 3. Automatically construct a three-dimensional memory cloud sea based on conversation history and inject memories into subsequent conversations; 4. Explore the mysterious Naga world in the Naga network through the clues left behind in the conversation; 5. Built-in game strategy function, can understand the details of the game through interaction or automatic identification of the game screen, and provide suggestions. You can use MAA and other game operation plugins to play games automatically; 6. It also has rich components such as self-configuration, browser manipulation, and music box. The future of Naga is waiting for you to explore. [English](README_en.md) | [简体中文](README.md) | [日本語](README_ja.md)     [](https://github.com/Xxiii8322766509/NagaAgent) [](https://github.com/Xxiii8322766509/NagaAgent) [](https://github.com/Xxiii8322766509/NagaAgent/issues) [](https://nerq.ai/safe/RTGS2017/NagaAgent) **[QQ Robot Linkage：Undefined QQbot](https://github.com/69gg/Undefined/)** </div> --- **Dual Licensing** · Open source uses [AGPL-3.0](LICENSE), and closed source uses [Proprietary License](LICENSE-CLOSED-SOURCE) (written authorization required). Commercial cooperation: contact@nagaagent.com / bilibili【柏斯阔落】 --- ## Update Log | Date | Version | Content | |------|------|------| | 🛰️ 2026-03-14 | — | Operator communication record upgraded to setting pop-up (name / character setting / engine / soul document / proprietary MCP·Skill); skill workshop connected to NagaHub and universal MCP preheating; exploration link added QQ / Feishu to complete notification; cloud memory priority no longer falls back to local Neo4j | | 🧩 2026-03-13 | — | OpenClaw orchestration link and packaging integration continue to expand; backend spec fixes Windows console Unicode output error | | 🧱 2026-03-11 | — | OpenClaw Skill automatic execution; independent workspace for operators; model selector and pricing display access Default / Deepseek-V3.2 / Kimi-K2.5 | | 🛠️ 2026-03-09 | — | Deep integration of OpenClaw vendor source code compilation and unified configuration; forum 401 storm repair; Windows tray icon repair | | 📦 2026-03-08 | — | naga-backend.spec continuous correction; application scanner supports environment variables and macOS; tool results default collapse; hub market removes memory cloud migration / MCP tool / intelligent body skill three plates | | 🚦 2026-03-07 | — | Node.js and uv runtime are distributed with the package; MCP command parser unified; OpenClaw Gateway startup diagnosis enhanced; packaged version music / wake-up voice / memory cloud sea and other issues fixed | | 🧰 2026-03-06 | — | GitHub Actions build and release pipeline; Electron automatic update replaces old patch system; CI build resource and charset_normalizer packaging repair; forum and integral polling details optimization | | 🔊 2026-03-05 | — | TTS switch, message queue and serial send refactoring; RAG memory recall enhancement; Gemini / automatic Function Calling support; recharge interface and remote memory stability repair | | 🧠 2026-03-04 | — | Migration to native Function Calling; DogTag takes over heartbeat / proactive vision; front and rear end hot patch system and 4-layer security protection; streaming text and progressive TTS optimization | | 🔎 2026-03-03 | — | web_search directly accesses NagaBusiness search agent; forum connection, TTS streaming playback and OpenClaw polling degradation repair; Live2D and Electron stability repair | | ❤️ 2026-03-02 | — | Heartbeat v3 event-driven refactoring; naga_control self-orchestration tool; agent-browser embedded at startup; startup diagnosis, health check and OpenClaw configuration path repair | | 🌐 2026-03-01 | — | Logged-in users use NagaBusiness, and unlogged-in users use Brave / OpenClaw search agent; OpenClaw tool direct call and automatic startup improvement; game strategy and character tone configuration update | | 🗂️ 2026-02-28 | — | Persistent storage unified migration to `~/.naga` user directory; ForumQuotaView network exploration control center; travel module and voice interaction comprehensive upgrade | | 🎙️ 2026-02-27 | — | Access to ASR voice recognition (MediaRecorder + NagaBusiness agent); conversation style, Electron background, MCP vision and server configuration | | 🎆 2026-02-26 | 5.1.0 | Naga network community forum online; setting three-in-one refactoring; travel mode; integral allocation page; hub market and main panel update | | ⚡ 2026-02-25 | 5.1.0 | TTS full link repair (CORS / asyncio); build.py cross-platform construction; context compression persistence; character system update; prompt word injection architecture refactoring | | 🎵 2026-02-24 | — | Neo4j connection timeout repair; unified BGM player; music factory song list editing; MCP management UI; floating ball transparent window + hover brightness | | 🏗️ 2026-02-23 | — | Cross-platform construction improvement; version number unified pyproject.toml management; prompt word / screenshot / visual optimization; character file packaging migration | | 💕 2026-02-22 | — | Integral affection system (sign-in / affection / integral); floating ball shadow and drag repair; login automatic recovery; OpenClaw hooks repair | | 🎶 2026-02-21 | — | Music factory icon update; MCP Agents update; floating ball small button | | 🗜️ 2026-02-20 | — | Context compression three-level refactoring (`<compress>` tag / cross-session inheritance); MCP management UI; floating ball transparent window; music factory function correction | | 🔄 2026-02-19 | — | SSE removes base64 direct JSON transmission; removes redundant background intention analyzer; config_manager automatic detection coding | | 🔧 2026-02-17 | — | Floating ball sequence frame path changed to relative path, repair package after avatar does not display | | 🚀 2026-02-16 | 5.0.0 | NagaModel gateway unified access; DeepSeek reasoning chain real-time display; memory cloud sea UI adaptive repair | | 🧠 2026-02-15 | — | Unified additional knowledge block + eliminate historical pollution; LLM streaming retry; seven-day automatic login; boot automatic startup | | 🌊 2026-02-14 | — | NagaMemory cloud remote memory; consciousness sea 3D rewriting; startup particle animation; version update check pop-up; user use agreement | | ✨ 2026-02-13 | — | Floating ball 4-state mode; screenshot multi-modal visual switching; skill workshop refactoring; Live2D expression channel independence | | 🎨 2026-02-12 | — | NagaCAS authentication; Live2D 4-channel orthogonal animation architecture; Agentic Tool Loop;明日方舟 style startup interface | | 📦 2026-02-11 | — | Embedded OpenClaw packaging; startup automatic generation of configuration file from template | | 🛠️ 2026-02-10 | — | Backend packaging optimization; skill workshop MCP status repair; removal of redundant Agent/MCP only retaining OpenClaw | | 🌱 2026-02-09 | — | Frontend refactoring; Live2D disable eye tracking; OpenClaw renamed AgentServer | --- ## Table of Contents 1. [Quick Start](#quick-start) 2. [Function Overview (Main Panel)](#function-overviewmain-panel) 3. [Conversation](#1-conversation--messageview) 4. [Memory Cloud Sea](#2-memory-cloud-sea--mindview) 5. [Skill Workshop](#3-skill-workshop--skillview) 6. [Naga Network](#4-naga-network--forum-community) 7. [Hub Market](#5-hub-market--marketview) 8. [Terminal Settings](#6-terminal-settings--configview) 9. [Music Factory](#7-music-factory--musicview) 10. [Floating Ball](#8-floating-ball--floatingview) 11. [Global Function](#global-function) 12. [Backend Architecture](#backend-architecture) 13. [Optional Configuration](#optional-configuration) 14. [Port List](#port-list) 15. [Troubleshooting](#troubleshooting) --- ## Quick Start ### Environmental Requirements - Python 3.11 (`>=3.11, <3.12`) - Optional: [uv](https://github.com/astral-sh/uv) — Accelerate dependency installation - Optional: Neo4j — Local knowledge graph memory ### Installation ```bash git clone https://github.com/Xxiii8322766509/NagaAgent.git cd NagaAgent # Frontend installation cd frontend npm install cd .. # Backend installation # Method 1: setup script (automatic environment detection, virtual environment creation, dependency installation) python setup.py # Method 2: uv uv sync # Method 3: manual python -m venv .venv source .venv/bin/activate # Windows: .\.venv\Scripts\activate pip install -r requirements.txt ``` ### Minimum Configuration Copy `config.json.example` to `config.json` and fill in LLM API information: ```json { "api": { "api_key": "your-api-key", "base_url": "https://api.deepseek.com", "model": "deepseek-v3.2" } } ``` Supports all OpenAI compatible APIs (DeepSeek, Tongyi Qianwen, OpenAI, Ollama, etc.). ### Start ```bash cd frontend && npm run dev (configured one-click startup) ``` --- ## Function Overview (Main Panel) After startup, enter the **Main Panel (PanelView)**, which uses a 3D parallax effect (mouse movement triggers perspective rotation). All functions are expanded from the eight entry buttons on the main panel: | # | Entrance | Route | Function Summary | |---|------|------|----------| | 1 | **Conversation** | `/chat` | AI conversation, streaming tool calls, context compression | | 2 | **Memory Cloud Sea** | `/mind` | Knowledge graph 3D visualization and GRAG memory management | | 3 | **Skill Workshop** | `/skill` | MCP tool management and community skill installation | | 4 | **Naga Network** | `/forum` / `/forum/quota` | Community forum, integral affection | | 5 | **Hub Market** | `/market` | Background, music, character, memory migration, recharge | | 6 | **Terminal Settings** | `/config` | Model connection, memory connection, audio-visual configuration (three-in-one) | | 7 | **Music Factory** | `/music` | BGM player and song list management | | 8 | **Floating Ball** | — | Enter lightweight floating ball window mode | --- ## 1. Conversation · MessageView ### Streaming Tool Calls The conversation engine outputs through SSE streaming, and simultaneously delivers to the frontend display and TTS sentence playback. Tool calls do not rely on OpenAI Function Calling API; LLM embeds JSON in the text as a ` ```tool``` ` code block, **any OpenAI compatible provider can use**. **Single tool call process:** ``` LLM streaming output ──SSE──▶ Frontend real-time display │ ▼ parse_tool_calls_from_text() ├─ Phase 1: Extract ```tool``` code block └─ Phase 2: Fallback extract bare JSON │ ▼ Route by agentType ├─ "mcp" → MCPManager.unified_call() ├─ "openclaw" → Agent Server /openclaw/send └─ "live2d" → UI animation notification │ ▼ asyncio.gather() parallel execution of all tools │ ▼ Result injection messages, enter the next round of LLM calls (up to 5 rounds) ``` - Text parsing: `json5` fault-tolerant parsing, full-angle character automatic standardization - SSE format: `data: {"type":"content"|"reasoning","text":"..."}\n\n` (direct JSON, no base64) - Loop limit: `max_loop_stream = 5` (configurable) Source code: [`apiserver/agentic_tool_loop.py`](apiserver/agentic_tool_loop.py) ### Context Compression Session token exceeds 100k automatically triggers compression to avoid context overflow: | Stage | Trigger timing | Behavior | |------|----------|------| | **Start compression** | Session loading | Immediate compression of previous message segment if history exceeds threshold | | **Runtime compression** | After each conversation | Compress and inject `<compress>` tag if exceeded | | **Cross-session inheritance** | New session starts | Read last summary, scroll accumulated context | Summary structure (6 partitions): key facts / user preferences / important decisions / to-do items / background information / recent status. `<compress>` tag persists to session file, not counted in LLM token statistics. ### DeepSeek Reasoning Chain Display When using DeepSeek, the `reasoning` field is pushed in real-time through SSE, and the frontend displays it with an independent style. --- ## 2. Memory Cloud Sea · MindView ### GRAG Knowledge Graph Memory GRAG (Graph-RAG) automatically extracts quintuples from conversations and stores them in Neo4j, and retrieves them as LLM context during conversations. **Quintuple structure:** `(subject, subject type, predicate, object, object type)` **Extraction process:** 1. Structured extraction (priority): `beta.chat.completions.parse()` + Pydantic `QuintupleResponse`, `temperature=0.3`, retry 3 times 2. JSON fallback: extract content from first `[` to last `]` if parsing fails 3. Filtering rules: only retain facts (behavior, relationship, status, preference), filter metaphors, assumptions, pure emotions **Entity types:** `person` / `location` / `organization` / `item` / `concept` / `time` / `event` / `activity` **Task manager:** - 3 asyncio workers consume `asyncio.Queue(maxsize=100)` - SHA-256 deduplication: duplicate tasks with the same text are skipped - Clean up tasks that have been completed for over 24 hours every hour **Dual storage:** - Local: `logs/knowledge_graph/quintuples.json` - Cloud: Neo4j graph database, `graph.merge()` upsert **RAG retrieval:** keyword extraction → Cypher query → format as `subject(type) —[predicate]→ object(type)` inject context **Remote memory:** logged-in users prioritize NagaMemory cloud; unlogged users can use local GRAG. To avoid performance loss, the cloud link no longer automatically falls back to local Neo4j. Source code: [`summer_memory/`](summer_memory/) ### Consciousness Sea 3D Visualization Canvas 2D + hand-drawn 3D projection (not WebGL), spherical coordinate camera, perspective division `700 / depth`. **7-layer rendering order:** background gradient → ground grid → water surface plane → volume light (3 beam columns) → particle system (3 layers 125 particles) → biological fluorescence plankton (10 with trailing) → knowledge graph nodes and edges (depth sorting) **Graph mapping:** `subject/object` → nodes, `predicate` → directed edges, degree centrality → node height weight, up to 100 nodes **Interaction:** drag rotation, middle button translation, wheel zooming, node click/drag, keyword search filtering --- ## 3. Skill Workshop · SkillView ### Built-in MCP Agent Based on [Model Context Protocol](https://modelcontextprotocol.io/), the plug-in tool architecture, each tool runs as an independent agent: | Agent | Function | |-------|------| | `weather_time` | Weather query / forecast, system time, automatic city / IP detection | | `open_launcher` | Scan system installed applications, natural language launch program | | `game_guide` | Game strategy Q&A, damage calculation, team recommendation, automatic screenshot injection | | `online_search` | SearXNG-based web search | | `crawl4ai` | Web content extraction based on Crawl4AI | | `playwright_master` | Browser automation based on Playwright | | `vision` | Screenshot analysis and visual Q&A | | `mqtt_tool` | MQTT protocol IoT device control | | `office_doc` | docx / xlsx content extraction | **Registration and discovery:** `mcp_registry.py` glob scans `**/agent-manifest.json`, `importlib.import_module` dynamic instantiation. Source code: [`summer_memory/`](summer_memory/) MCP Management UI The front-end `McpAddDialog.vue` provides a graphical MCP tool management interface, supporting online addition/deletion of tools (no restart required). ### Community Skill Installation The skill workshop supports one-click installation of community-released skills (Agent Browser, Brainstorming, Context7, Firecrawl Search, etc.). Backend interface: `GET /openclaw/market/items`, `POST /openclaw/market/items/{id}/install` Source code: [`mcpserver/`](mcpserver/) ## 4. Naga Network · Forum Community ### Community Forum Enter from the main panel "Naga Network" block, embedding complete community functions: | View | Route | Function | |------|------|------| | `ForumListView` | `/forum` | Post list, category filtering | | `ForumPostView` | `/forum/post/:id` | Post details browsing (current version is read-only, no front-end commenting and "want to know" operation) | | `ForumMessagesView` | `/forum/messages` | Private message | | `ForumMyPostsView` | `/forum/my-posts` | My posts | | `ForumMyRepliesView` | `/forum/my-replies` | My replies | | `ForumQuotaView` | `/forum/quota` | Credit quota and exploration entrance | Source code: [`frontend/src/forum/`](frontend/src/forum/) ### Credit and Affinity System A gamified interaction system exclusive to logged-in users: | Dimension | Description | |------|------| | **Credits** | Sign-in/continuous sign-in rewards accumulation, used for exchanging model quotas | | **Affinity** | Increases with each sign-in, reflecting the depth of relationship with Naga | | **Daily Sign-in** | User menu one-click sign-in, continuous sign-in triggers additional rewards | Related API (proxied to Naga portal via API Server): `/api/checkin`, `/api/affinity`, `/api/credits` ## 5. MarketView The market integrates all resource acquisition and management entrances, divided into seven tabs: | Tab | Description | |-----|------| | **Interface Background** | Switch application theme background | | **Music Street** | Purchase/unlock music albums (current: The Book of Sands) | | **Character Registration** | Bind/switch AI characters (requires login) | | **Memory Cloud Migration** | Cloud memory data migration and management | | **MCP Tools** | Graphical MCP tool management | | **Smart Body Skills** | Community Skill one-click installation | | **Model Recharge** | Naga portal credit recharge | ## 6. ConfigView The settings page is reconstructed in three tabs, with original scattered configurations centralized in a single page: | Tab | Content | |-----|------| | **Model Connection** | LLM API Key, Base URL, model selection | | **Memory Connection** | Neo4j connection parameters, NagaMemory cloud configuration | | **Audio and Visual Configuration** | Character profile, Live2D model and SSAA, TTS voice, chat font size | ### Character Card System The `characters/` directory manages switchable AI characters, each described by a JSON configuration file: ```json { "ai_name": "Nadja", "user_name": "User", "live2d_model": "NagaTest2/NagaTest2.model3.json", "prompt_file": "conversation_style_prompt.txt", "portrait": "Naga.png", "bio": "An AI assistant created by developer Berserker to assist users." } ``` - Each character directory contains independent conversation style prompts, Live2D model resources, and portrait images - After activating a character, the AI name and Live2D model are uniformly managed by the character JSON and cannot be manually overridden on the interface - Default character: **Nadja** Source code: [`characters/`](characters/) ## 7. MusicView An independent music player sharing the same playback instance as the main interface BGM: - **Playlist editing** (`MusicEditView`): Manage track lists, save and synchronize to the global player in real-time - **Playback status synchronization**: Play/pause icons and audio events are linked in real-time - **List looping**: Automatically play the next song after the current song ends - **Live2D lip sync**: During TTS playback, `AdvancedLipSyncEngineV2` drives Live2D mouth shapes at 60FPS ## 8. FloatingView Click the "Floating" button on the main panel to enter a lightweight floating window mode, cycling through four states: ``` ball (100×100 ball) → compact (420×100 folded bar) → full (420×N expanded) → classic (normal window) ``` **Appearance and dynamic effects:** - Sequence frame blink animation: 5 frames (open → half-closed → closed → half-closed → open), 70ms/frame, triggered at random intervals - When generating a reply: Ball glow pulse effect - When hovering: Brightness enhancement effect - Transparent borderless window, supporting free drag and drop positioning **Functions:** - Direct input conversation in floating state, historical messages can be recalled in compact/full state - Screenshot capture panel: Select a screen window as an image attachment - File upload support - Right-click menu implemented through Electron native menu (avoiding small window cropping) ## Global Functions ### Voice Interaction **TTS (Text-to-Speech)** - Engine: Edge-TTS, OpenAI compatible interface `/v1/audio/speech` - Architecture: 3-thread pipeline — sentence queue → TTS call (Semaphore(2) concurrency) → pygame playback - Live2D lip sync: 60FPS extracting 5 parameters (mouth_open/mouth_form/mouth_smile/eye_brow_up/eye_wide) - Port cleanup: Automatically detect and release occupied ports at startup **ASR (Speech Recognition)** - Local engine: FunASR, supporting VAD endpoint detection and WebSocket real-time streaming - Three-mode automatic switching: `LOCAL` (FunASR) → `END_TO_END` (Qwen Omni) → `HYBRID` **Real-time Voice Conversation** (requires DashScope API Key) - Full-duplex WebSocket voice interaction based on Qwen Omni - Echo cancellation, VAD detection, audio chunking (200ms), conversation cooling control ```json { "voice_realtime": { "enabled": true, "provider": "qwen", "api_key": "your-dashscope-key", "model": "qwen3-omni-flash-realtime" } } ``` Source code: [`voice/`](voice/) ### Live2D Virtual Image Using **pixi-live2d-display** + **PixiJS WebGL** to render Cubism Live2D models. SSAA super sampling anti-aliasing: Canvas rendered by `width × ssaa`, CSS `transform: scale(1/ssaa)` scaling. **4-channel orthogonal animation system** (`live2dController.ts`): | Channel | Control content | Features | |------|----------|------| | **State** | idle/thinking/talking cycle | Hermite smooth interpolation, loaded from `naga-actions.json` | | **Action** | Head movements like nod/ shake | FIFO queue, single execution | | **Emotion** | `.exp3.json` emotion files | Add/Multiply/Overwrite three mixing modes, exponential decay transition | | **Tracking** | Mouse gaze tracking | Configurable delay start, `tracking_hold_delay_ms` | Merge order: State → mouth shape → action → manual override → emotion mix → tracking mix ### OpenClaw Computer Control Connects to OpenClaw Gateway (port 18789), scheduling AI programming assistants to execute local tasks through natural language. - **Three-stage fallback startup:** Built-in embedding → global `openclaw` command → automatic `npm install -g openclaw` - Supports sessionKey hooks (2026.2.17+), configurable custom hooks path - `POST /openclaw/send` sends instructions, maximum waiting 120 seconds **Task Scheduler (`TaskScheduler`):** - Task step recording (purpose/content/output/analysis/success/failure) - Automatic extraction of "key findings" markers - Memory compression: When the number of steps exceeds the threshold, invoke LLM to generate `CompressedMemory` (key_findings/failed_attempts/current_status/next_steps) - `schedule_parallel_execution()` executes task lists in parallel through `asyncio.gather()` Source code: [`agentserver/`](agentserver/) ### Boot Animation | Stage | Content | |------|------| | **Title stage** | Black mask + 40 golden rising particles + title picture 2.4s CSS keyframe; automatic playback of wake-up voice when title appears | | **Progress stage** | Neural Network particle background + Live2D reveal box + golden progress bar (`requestAnimationFrame` interpolation, minimum speed | | **Stagnation detection** | 3-second no-progress change displays restart prompt; polls backend `/health` every second after progress 25% | | **Wake-up** | Displays "click to wake up" pulse prompt after 100% progress | ## Backend Architecture NagaAgent consists of four independent microservices, with `main.py` uniformly orchestrating startup: ``` ┌─────────────────────────────────────────────────────────┐ │ Electron / PyQt5 Frontend │ │ Vue 3 + Vite + UnoCSS + PrimeVue + pixi-live2d-display │ │ │ │ PanelView · MessageView · MindView · SkillView │ │ MarketView · ConfigView · MusicView · FloatingView │ │ ForumListView · ForumPostView · ForumQuotaView … │ └──────────┬─────────────┬──────────────┬─────────────────┘ │ │ │ ┌───────▼──────┐ ┌────▼────┐ ┌─────▼──────┐ │ API Server │ │ Agent │ │ Voice │ │ :8000 │ │ Server │ │ Service │ │ │ │ :8001 │ │ :5048 │ │ Conversation │ │ │ │ │ │ Tool calls │ │ Task │ │ TTS / ASR │ │ Context │ │ OpenClaw│ │ Real-time │ │ Document │ │ │ │ voice │ │ authentication│ └────┬────┘ └────────────┘ │ Memory API │ │ │ Skill market │ ┌───▼──────────┐ │ Configuration│ │ OpenClaw │ └──────┬───────┘ │ Gateway │ │ │ :18789 │ ┌──────▼──────┐ └─────────────┘ │ MCP Server │ │ :8003 │ │ Tool registry│ │ Agent discovery│ │ Parallel │ │ scheduling │ └──────┬──────┘ │ ┌───────┴───────────────────────┐ │ MCP Agents (pluggable) │ │ Weather | Search | Crawl | Vision│ │ Launcher | Guide | Document | MQTT│ └───────────────────────────────┘ │ ┌──────▼──────┐ │ Neo4j │ │ :7687 │ │ Knowledge │ └─────────────┘ ``` ### Directory Structure ``` NagaAgent/ ├── main.py # Unified entry, orchestrating all services ├── build.py # Cross-platform build script ├── config.json # Runtime configuration (copied from config.json.example) ├── pyproject.toml # Version 5.1.0, project metadata and dependencies │ ├── apiserver/ # API Server (:8000) │ ├── api_server.py # FastAPI main application │ ├── agentic_tool_loop.py # Multi-turn tool call loop │ ├── llm_service.py # LiteLLM unified LLM call │ └── streaming_tool_extractor.py # Streaming sentence + TTS dispatch │ ├── agentserver/ # Agent Server (:8001) │ ├── agent_server.py │ └── task_scheduler.py # Task orchestration + compressed memory │ ├── mcpserver/ # MCP Server (:8003) │ ├── mcp_server.py │ ├── mcp_registry.py # Manifest scanning + dynamic registration │ ├── mcp_manager.py # unified_call() routing │ ├── agent_weather_time/ │ ├── agent_open_launcher/ │ ├── agent_game_guide/ │ ├── agent_online_search/ │ ├── agent_crawl4ai/ │ ├── agent_playwright_master/ │ ├── agent_vision/ │ ├── agent_mqtt_tool/ │ └── agent_office_doc/ │ ├── summer_memory/ # GRAG knowledge graph memory │ ├── quintuple_extractor.py │ ├── quintuple_graph.py │ ├── quintuple_rag_query.py │ ├── task_manager.py │ ├── memory_manager.py │ └── memory_client.py # NagaMemory remote client │ ├── voice/ # Voice service (:5048) │ ├── output/ # TTS + lip sync │ └── input/ # ASR + real-time voice │ ├── characters/ # Character configuration directory │ └── Nadja/ # prompt / Live2D model / portrait │ ├── frontend/ # Electron + Vue 3 frontend │ ├── electron/ # Main process │ │ └── modules/ # backend / hotkeys / menu / tray / updater / window │ └── src/ │ ├── views/ # All page views │ ├── forum/ # Forum module │ ├── components/ # General components │ ├── composables/ # useAuth / useBackground / useAudio … │ └── utils/ # live2dController / session / config │ ├── system/ # Configuration loading, environment detection, system prompts ├── guide_engine/ # Game guide engine └── logs/ # Running logs, knowledge graph files ## Optional Configuration <details> <summary><b>Knowledge Graph Memory (Neo4j)</b></summary> Install Neo4j ([Docker](https://hub.docker.com/_/neo4j) or [Neo4j Desktop](https://neo4j.com/download/)), and configure `config.json`: ```json { "grag": { "enabled": true, "neo4j_uri": "neo4j://127.0.0.1:7687", "neo4j_user": "neo4j", "neo4j_password": "your-password" } } ``` Without Neo4j configuration, GRAG will only use local JSON files for storage, and functionality will not be affected. </details> <details> <summary><b>Voice Interaction (TTS / ASR)</b></summary> ```json { "system": { "voice_enabled": true }, "tts": { "port": 5048, "default_voice": "zh-CN-XiaoxiaoNeural" } } ``` Real-time full-duplex voice conversation (requires Tongyi Qianwen DashScope API Key): ```json { "voice_realtime": { "enabled": true, "provider": "qwen", "api_key": "your-dashscope-key", "model": "qwen3-omni-flash-realtime" } } ``` </details> <details> <summary><b>Live2D Virtual Avatar (Custom Model)</b></summary> ```json { "web_live2d": { "ssaa": 2, "model": { "source": "./models/your-model/model.model3.json", "x": 0.5, "y": 1.3, "size": 6800 }, "face_y_ratio": 0.13, "tracking_hold_delay_ms": 100 } } ``` After enabling character cards, `ai_name` and `model.source` will be automatically overridden by the character JSON, and manual modification is not required. </details> <details> <summary><b>MQTT IoT Control</b></summary> ```json { "mqtt": { "enabled": true, "broker": "mqtt-broker-address", "port": 1883, "topic": "naga/agent/topic", "client_id": "naga-agent-client" } } ``` </details> --- ## Port Overview | Service | Port | Description | |------|------|------| | API Server | 8000 | Main interface: conversation, configuration, authentication, Skill market | | Agent Server | 8001 | Task scheduling, OpenClaw | | MCP Server | 8003 | MCP tool registration and scheduling | | Voice Service | 5048 | TTS / ASR | | Neo4j | 7687 | Knowledge graph (optional) | | OpenClaw Gateway | 18789 | AI computer control (optional) | --- ## Troubleshooting | Issue | Solution | |------|----------| | Python version error | Must use Python 3.11; recommend using uv for automatic version management | | Port occupied | Check if 8000, 8001, 8003, and 5048 are available | | Neo4j connection timeout / hang | Fixed in 2.24; confirm Neo4j service is started | | TTS no sound / CORS error | Fixed in 2.25; confirm `voice_enabled: true` | | Startup stuck on progress bar | Check if API Key is correct; wait 3 seconds for restart prompt | | Floating ball avatar not displayed | Fixed in 2.17; confirm using the latest packaged version | | config.json garbled | Fixed in 2.19; config_manager automatically detects file encoding | | OpenClaw startup failure | Fixed in 2.24; global mode missing configuration file issue | ```bash python main.py --check-env --force-check # Complete environment diagnosis python main.py --quick-check # Quick check python update.py # Automatic git pull + dependency synchronization ``` --- ## Contribution Welcome to submit Issues and Pull Requests. If you have any questions, you can join QQ channel **nagaagent1**. --- ## Star History [](https://www.star-history.com/#RTGS2017/NagaAgent&type=date&legend=top-left)