JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.
Quick Start
⚠️ Version Sync: This document should be kept in sync with
docs/zh/Quickstart.md. When updating one, please update the other.
Installation
Prerequisites
Before installing JiuwenSwarm, ensure your system meets the following requirements:
| Dependency | Version | Description |
|---|---|---|
| Operating System | Windows 10/11, macOS 10.15+, Linux | Supports mainstream operating systems |
| Python | ≥3.11, <3.14 | Python 3.11 recommended |
| Node.js | 18.x or higher | For frontend interface |
| Git | Latest | For source code installation |
Check Node.js version:
node --version
# Expected output: v18.x.x or higher
pip Install
# Create virtual environment
python -m venv jiuwenswarm
# Activate virtual environment
# Windows:
jiuwenswarm\Scripts\activate
# Linux/Mac:
source jiuwenswarm/bin/activate
# Install JiuwenSwarm
pip install jiuwenswarm
Start Service
# Initialize (first run)
jiuwenswarm-init
# Start service
jiuwenswarm-start
After successful startup, the terminal will display backend service status:
[INFO] Starting JiuwenSwarm server...
[INFO] API server running at http://localhost:8000
[INFO] Web server running at http://localhost:5173
When you see similar output, the service is ready. Open http://localhost:5173 in your browser to use.
Automatic Port Conflict Resolution
JiuWenSwarm uses a fixed set of default ports (18092 / 19000 / 19001 / 5173). If a port is already in use when starting (e.g. a previous run did not fully stop, or another app occupies it), the launcher automatically scans upward for the next free port group and uses it instead of failing:
[start_services] ⚠️ Original ports conflict. Falling back to alternative port group (index 1):
[start_services] Using ports:
agent_server: 19092
web: 20000
gateway: 20001
frontend: 6173
[start_services] TUI/CLI connect with:
jiuwenswarm-tui --url ws://127.0.0.1:20001/tui
jiuwenswarm chat (auto-reads GATEWAY_PORT)
The chosen ports are persisted, so the next launch and the TUI/CLI read them automatically — no need to memorize. If no free group is found within the scan range, the command prints conflict-resolution hints and exits.
To force specific ports, two options:
Stop the occupying process:
jiuwenswarm-start --stop default(orlsof -i :19001on Linux/macOS; on Windowsnetstat -ano | findstr :19001thentaskkill /PID <pid> /F).Override base ports via env vars (Docker / container-friendly):
# Override base ports (index-0 starting ports; named instances add index×1000) export JIUWENSWARM_GATEWAY_PORT=29001 export JIUWENSWARM_AGENT_SERVER_PORT=28092 export JIUWENSWARM_FRONTEND_PORT=15173 export JIUWENSWARM_WEB_PORT=29000 jiuwenswarm-start
Terminal CLI
You can also chat with JiuwenSwarm directly from the terminal:
jiuwenswarm chat "Hello, introduce yourself"
For details, see CLI / Terminal Chat.
Remote Access (Optional)
For remote access, run the following commands:
# Start web service
jiuwenswarm-web --host 0.0.0.0 --port <custom-port>
# Start backend service
jiuwenswarm-app
Configuration Directory Auto-Creation: After first starting the service, the system automatically creates the configuration directory:
- Windows:
C:\Users\<your-username>\.jiuwenswarm - Linux/Mac:
~/.jiuwenswarm/
Configuration files, memory files, and other data will be stored in this directory.
The following installation methods are suitable for users who want to perform secondary development and adaptation based on JiuwenSwarm.
First, clone the repository and enter the project directory:
git clone https://gitcode.com/openJiuwen/jiuwenswarm.git
cd jiuwenswarm
Install via uv
Create a new virtual environment using
uv# Create virtual environment with uv (supports any of Python 3.11, 3.12, 3.13) uv venv --python=3.11 # or uv venv --python=3.12 # or uv venv --python=3.13Run uv sync
Enter the project root directory
jiuwenswarm/and run:uv syncInstall frontend dependencies
Enter the frontend directory
channels/web/frontendto install dependencies:cd channels/web/frontend npm installRun frontend service
Two ways to run the frontend service:
Static run (suitable for production deployment)
npm run build # Copy build output into the user workspace # Windows: xcopy /E /I dist %USERPROFILE%\.jiuwenswarm\channels\web\frontend\dist # macOS/Linux: cp -r dist ~/.jiuwenswarm/channels/web/frontend/dist cd ../../../ uv run jiuwenswarm-init uv run jiuwenswarm-startDynamic run (suitable for development debugging)
cd ../../../ uv run jiuwenswarm-init uv run jiuwenswarm-start dev
After running, you can access the JiuwenSwarm service via the web frontend.
Install via conda
Create a new virtual environment using
conda# Create virtual environment with Anaconda (supports any of Python 3.11, 3.12, 3.13) conda create -n JiuwenSwarm python=3.11 # or conda create -n JiuwenSwarm python=3.12 # or conda create -n JiuwenSwarm python=3.13Activate the conda environment
conda activate JiuwenSwarmInstall Python dependencies
Enter the project root directory
jiuwenswarm/and run:# Mode 1: Development mode installation (recommended, easier to modify code) pip install -e . # Mode 2: Normal installation pip install .Note: This installation method depends on the project's installable package (
pyproject.toml), and will also installjiuwenswarmitself by default.Install frontend dependencies
Navigate to the frontend directory
channels/web/frontendand install dependencies:cd channels/web/frontend npm installRun frontend service
Two ways to run the frontend service:
Static run (suitable for production deployment)
npm run build cd ../../../ jiuwenswarm-init jiuwenswarm-startDynamic run (suitable for development debugging)
cd ../../../ # Start directly (without uv run) jiuwenswarm-init jiuwenswarm-start dev
After running, you can access the JiuwenSwarm service via the web frontend.
Quick Start
1️⃣ Conversation Modes
| Method | Description |
|---|---|
| Web Frontend | After starting the service, visit http://localhost:5173 to chat directly via browser |
| Xiaoyi Channel | Huawei phone users can directly wake up Xiaoyi to chat with JiuwenSwarm |
| Feishu Channel | After completing channel configuration, chat with JiuwenSwarm in Feishu |
2️⃣ Configure Model
See the Configure Model section below.
Configure Model
In the left sidebar of the Web UI, find "Configuration" and enter the configuration page:

Complete the following basic configuration, then click "Save" in the top right:

Configuration Items:
| Field | Environment variable | Description | Required |
|---|---|---|---|
model_name |
MODEL_NAME |
Model name, e.g., deepseek-chat, gpt-4o |
✅ Required |
api_base |
API_BASE |
Model API base URL, e.g., https://api.deepseek.com |
✅ Required |
api_key |
API_KEY |
Model API key | ✅ Required |
model_provider |
MODEL_PROVIDER |
Model provider, e.g., OpenAI, DeepSeek, Anthropic |
✅ Required |
Test After Configuration:
After filling in the configuration, click the "Test" button to verify model availability. A successful test shows ✅, if failed check:
- Whether API Key is correct
- Whether API Base URL is accessible
- Whether model name and Provider match
Notes:
- Auto-restart after save: Backend automatically restarts to load new configuration
- Required fields: The four fields above are basic configuration required for normal operation
- Model Providers:
OpenAI,DashScope,SiliconFlow,InferenceAffinity
Start Conversation
In the left sidebar of the Web UI, find "Chat" and enter your question to start:

Session Management
Click the "+" button below to clear the current session and start a new one:

Page display after clearing:

When to clear a session?
| Scenario | Description |
|---|---|
| Topic Switch | Current conversation is complete, want to start a completely new topic |
| Context Confusion | Too much content in current session, model understanding deviates |
| Repeated/Wrong Response | Model falls into loop response or gives irrelevant answers |
| Privacy/Sensitive Info | Current session contains temporary sensitive information that needs immediate clearing |
Comparison: Clear vs Not Clear Session:
| Comparison | Not Clear (Continue Session) | Clear (New Session) |
|---|---|---|
| Context Retention | ✅ Keep all history, model knows full context | ❌ No history retained, model starts from scratch |
| Token Consumption | ⚠️ Grows with conversation, consumes more tokens | ✅ Initial tokens minimal, cost controllable |
| Answer Relevance | Early topics may interfere with current understanding | Each question processed independently, no interference |
| Privacy Security | History persists in current session | Sensitive info not carried to new session |
Clear Memory
When you need JiuwenSwarm to forget all conversation history and user information, you can clear memory files.
⚠️ Risk Warning: Clearing memory is permanent, deleted memory files cannot be recovered. Before proceeding, confirm:
- Whether important memories are backed up
- Whether you really need to delete (or just want to start a new session)
Difference from Session Clearing:
| Operation | Scope | Impact | Use Case |
|---|---|---|---|
| New Session | Current chat window | Does not delete any memory, only starts new thread | Want to switch topics but keep historical memory for reference |
| Clear Memory | All memory files | Permanently deletes all history, user info, project memory | Completely clear all history, protect privacy, or reset to initial state |
Use Cases:
- Privacy Protection: Clear history containing sensitive information
- Fresh Start: Start a completely different project or topic, avoid historical interference
- Debug Troubleshooting: Reset when memory files are corrupted or content is abnormal
- User Switching: Clear previous user info in multi-user environments
Steps to Clear Memory:
Memory files are stored in:
- Windows:
C:\Users\<your-username>\.jiuwenswarm\agent\workspace\memory\ - Linux/Mac:
~/.jiuwenswarm/agent/jiuwenclaw_workspace/memory/
Method 1: Delete via Agent
Tell JiuwenSwarm: "Please delete all memory files" or "Clear my memory", Agent will call file tools to delete files in the memory directory.

Method 2: Manual Delete
Stop JiuwenSwarm service, then directly delete all Markdown files in the memory/ directory.

⚠️ Note: Memory cannot be recovered after clearing, proceed with caution. Regularly backup important memory files.