Skip to content

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.

Python
11.6 KB
Raw Blame

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:

  1. Stop the occupying process: jiuwenswarm-start --stop default (or lsof -i :19001 on Linux/macOS; on Windows netstat -ano | findstr :19001 then taskkill /PID <pid> /F).

  2. 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.13
    
  • Run uv sync

    Enter the project root directory jiuwenswarm/ and run:

    uv sync
    
  • Install frontend dependencies

    Enter the frontend directory channels/web/frontend to install dependencies:

    cd channels/web/frontend
    npm install
    
  • Run 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-start
      
    • Dynamic 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.13
    
  • Activate the conda environment

    conda activate JiuwenSwarm
    
  • Install 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 install jiuwenswarm itself by default.

  • Install frontend dependencies

    Navigate to the frontend directory channels/web/frontend and install dependencies:

    cd channels/web/frontend
    npm install
    
  • Run frontend service

    Two ways to run the frontend service:

    • Static run (suitable for production deployment)

      npm run build
      cd ../../../
      jiuwenswarm-init
      jiuwenswarm-start
      
    • Dynamic 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.