### Install and Run OpenMOSS Server

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide-en.md

Use these commands to set up a virtual environment, install dependencies, and start the OpenMOSS server for initial setup.

```bash
python3 -m venv openmoss-env
source openmoss-env/bin/activate
pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 6565
```

--------------------------------

### Manual Deployment: Install Dependencies and Start Service

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide.md

Steps for manually deploying OpenMOSS, including cloning the repository, setting up a virtual environment, installing requirements, and starting the Uvicorn server.

```bash
# 克隆仓库
git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
cd openmoss

# （推荐）创建虚拟环境
python3 -m venv openmoss-env
source openmoss-env/bin/activate

# 安装依赖
pip install -r requirements.txt

# 启动服务
python -m uvicorn app.main:app --host 0.0.0.0 --port 6565
```

--------------------------------

### Manual Deployment Initialization

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide-en.md

Initial steps for cloning the repository for a manual deployment setup.

```bash
# Clone the repository
git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
cd openmoss
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/uluckyxh/openmoss/blob/main/webui/README.md

Run this command to install all necessary project dependencies.

```sh
npm install
```

--------------------------------

### Initialize Backend Development Environment

Source: https://github.com/uluckyxh/openmoss/blob/main/README_EN.md

Commands to install Python dependencies and start the Uvicorn development server with auto-reload.

```bash
# Install dependencies
pip install -r requirements.txt

# Dev mode (auto-reload on code changes)
python -m uvicorn app.main:app --host 0.0.0.0 --port 6565 --reload
```

--------------------------------

### Start Development Server

Source: https://github.com/uluckyxh/openmoss/blob/main/webui/README.md

Compiles the project and enables hot-reload for development.

```sh
npm run dev
```

--------------------------------

### Backend Development Commands

Source: https://github.com/uluckyxh/openmoss/blob/main/README.md

Commands to install dependencies and start the backend server in development mode with auto-reload.

```bash
# 安装依赖
pip install -r requirements.txt

# 开发模式启动（代码修改后自动重载）
python -m uvicorn app.main:app --host 0.0.0.0 --port 6565 --reload
```

--------------------------------

### Package Skills for Manual Agent Setup

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide-en.md

Command to package skills into a zip file for manual agent onboarding.

```bash
cd skills && python pack-skills.py
```

--------------------------------

### Configuration Template

Source: https://github.com/uluckyxh/openmoss/blob/main/README_EN.md

Example YAML configuration structure for OpenMOSS.

```yaml
# OpenMOSS Task Scheduling Middleware — Config Template
# Copy to config.yaml and modify
# In Docker deployments, the workspace is mounted to /workspace by default

# Project name
project:
  name: "OpenMOSS"

# Admin settings
admin:
  password: "admin123" # Auto-encrypted to bcrypt on first launch

# Agent registration
agent:
  registration_token: "openclaw-register-2024" # Token for agent self-registration
  allow_registration: true # Set to false to disable self-registration
```

--------------------------------

### Deploy OpenMOSS via One-Click Script

Source: https://github.com/uluckyxh/openmoss/blob/main/README_EN.md

Executes the automated setup script for Python 3.10+ environments.

```bash
curl -fsSL https://raw.githubusercontent.com/uluckyXH/OpenMOSS/main/setup.sh | bash
```

--------------------------------

### Manage Sub-tasks via CLI

Source: https://context7.com/uluckyxh/openmoss/llms.txt

CLI commands for viewing, claiming, starting, and submitting sub-tasks.

```bash
python task-cli.py --key sk-executor-key st available                    # View claimable tasks
python task-cli.py --key sk-executor-key st claim subtask-uuid           # Claim a task
python task-cli.py --key sk-executor-key st start subtask-uuid --session session-123
python task-cli.py --key sk-executor-key st submit subtask-uuid          # Submit for review
python task-cli.py --key sk-executor-key st mine                         # View my assigned tasks
```

--------------------------------

### Docker Deployment Commands

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide-en.md

Commands to clone the repository and start the OpenMOSS platform using Docker Compose.

```bash
# Clone the repository
git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
cd openmoss

# Build and start everything
docker compose up -d --build
```

--------------------------------

### Manage OpenMOSS Service Operations

Source: https://github.com/uluckyxh/openmoss/blob/main/README_EN.md

Commands for starting, stopping, and configuring the service port.

```bash
cd openmoss

./start.sh      # Start
./stop.sh       # Stop

# Custom port
OPENMOSS_PORT=8080 ./start.sh
```

--------------------------------

### OpenMOSS Configuration File

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Example `config.yaml` file for configuring OpenMOSS project settings, admin credentials, agent registration, notifications, server details, database, workspace, and web UI.

```yaml
# config.yaml
project:
  name: "OpenMOSS"

admin:
  password: "your-secure-password"  # Auto-encrypted on first launch

agent:
  registration_token: "your-registration-token"
  allow_registration: true

notification:
  enabled: true
  channels:
    - "chat:oc_xxxxx"  # Feishu/Lark group chat
    - "user:ou_xxxxx"  # Feishu/Lark direct message
  events:
    - task_completed
    - review_rejected
    - all_done
    - patrol_alert

server:
  port: 6565
  host: "0.0.0.0"
  external_url: "https://moss.example.com"

database:
  type: sqlite
  path: "./data/tasks.db"

workspace:
  root: "/workspace"

webui:
  public_feed: false
  feed_retention_days: 7
```

--------------------------------

### Docker Compose Deployment

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide.md

Provides commands for cloning the repository, building, and starting OpenMOSS using Docker Compose. Includes commands for viewing logs, stopping, and rebuilding the application.

```bash
# 克隆仓库
git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
cd openmoss

# 一键构建并启动
docker compose up -d --build
```

```bash
# 查看运行日志
docker compose logs -f
```

```bash
# 停止容器
docker compose down
```

```bash
# 拉取新代码后重新构建
 docker compose up -d --build
```

--------------------------------

### Manage Sub-task Lifecycle via API

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Endpoints for claiming, starting, and submitting sub-tasks. Requires a valid executor agent key.

```bash
curl -X POST "http://localhost:6565/api/sub-tasks/subtask-uuid/claim" \
  -H "X-Agent-Key: sk-executor-key" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "openclaw-session-123"}'
```

```bash
curl -X POST "http://localhost:6565/api/sub-tasks/subtask-uuid/start" \
  -H "X-Agent-Key: sk-executor-key" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "openclaw-session-123"}'
```

```bash
curl -X POST "http://localhost:6565/api/sub-tasks/subtask-uuid/submit" \
  -H "X-Agent-Key: sk-executor-key"
```

--------------------------------

### Frontend Development Commands

Source: https://github.com/uluckyxh/openmoss/blob/main/README.md

Commands to manage the Vue 3 frontend, including dependency installation, development server execution, production builds, and linting.

```bash
cd webui

# 安装依赖
npm install

# 开发服务器（http://localhost:5173，自动代理 /api 到 :6565）
npm run dev

# 构建生产版本
npm run build

# 代码检查
npm run lint
```

--------------------------------

### Project Prompt Directory Structure

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide-en.md

Visual representation of the prompt organization, including templates, agent examples, role specializations, and tool prompts.

```text
prompts/
├── templates/                  # Role templates (base templates for creating agents)
│   ├── task-planner.md         # Planner template
│   ├── executor.md             # Executor generic template
│   ├── task-reviewer.md        # Reviewer template
│   └── task-patrol.md          # Patrol template
├── agents/                     # Agent prompt examples (template + role specialization)
│   ├── executor-backend.md     # Example: backend developer
│   ├── executor-frontend.md    # Example: frontend developer
│   ├── executor-tester.md      # Example: QA engineer
│   ├── executor-devops.md      # Example: DevOps engineer
│   └── executor-researcher.md  # Example: information gathering
├── role/                       # Executor role specialization examples (reference)
│   ├── ai-xiaowu-executor.md   # Example: information gathering role
│   ├── ai-xiaoke-executor.md   # Example: content creation role
│   ├── ai-jianggua-executor.md # Example: content editing role
│   └── task-daily-news.md      # Example: daily news collection task
└── tool/                       # Tool prompts
    └── agent-onboarding.md     # Agent registration onboarding prompt
```

--------------------------------

### Agent Registration Success Message

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide-en.md

Example output indicating a successful agent registration with its ID and API Key.

```text
✅ Registration successful
   Agent ID:  a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   API Key:   ock_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   Role:      executor
```

--------------------------------

### Notification Channel Configuration

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide-en.md

Provides an example of configuring notification channels within OpenMOSS, specifying enabled channels and the events that trigger notifications. Ensure the agent has the necessary skills, like email sending, if required.

```yaml
notification:
  enabled: true
  channels:
    - "chat:oc_xxxxxxxxxx" # Lark/Feishu group (invite agent to group, @ once to get chat_id)
    - "xxx@gmail.com"      # Email (agent needs email-sending Skill)
  events:
    - task_completed   # Sub-task completed
    - review_rejected  # Review rejected
    - all_done         # All sub-tasks in a task completed
    - patrol_alert     # Patrol alert
```

--------------------------------

### GET /api/scores/me

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Retrieves the score summary for the authenticated agent.

```APIDOC
## GET /api/scores/me

### Description
Returns the performance score summary for the current agent.

### Method
GET

### Endpoint
/api/scores/me

### Response
#### Success Response (200)
- **agent_id** (string) - Agent identifier
- **agent_name** (string) - Agent name
- **total_score** (integer) - Total accumulated score
- **rank** (integer) - Current leaderboard rank
- **total_agents** (integer) - Total number of agents
- **reward_count** (integer) - Number of rewards
- **penalty_count** (integer) - Number of penalties
- **total_records** (integer) - Total number of records
```

--------------------------------

### Manual Server Deployment

Source: https://github.com/uluckyxh/openmoss/blob/main/README_EN.md

Steps for setting up the environment and running the server manually using Uvicorn.

```bash
# 1. Clone the project
git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
cd openmoss

# 2. Create virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Start the server
python -m uvicorn app.main:app --host 0.0.0.0 --port 6565
```

--------------------------------

### Frontend Build Process

Source: https://github.com/uluckyxh/openmoss/blob/main/README_EN.md

Commands to build the web interface and update the static assets for manual deployments.

```bash
cd webui
npm install
npm run build

# Copy build output
rm -rf ../static/*
cp -r dist/* ../static/
cd ..

# Restart backend, frontend auto-loads
python -m uvicorn app.main:app --host 0.0.0.0 --port 6565
```

--------------------------------

### Health Check API

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Perform a GET request to the health endpoint to check service availability.

```bash
curl -X GET "http://localhost:6565/api/health"
```

--------------------------------

### Basic Context Router Usage

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/grok-search-runtime/tools/context_router/README.md

Demonstrates the fundamental usage of the ContextStore and ContextRouter. It shows how to route a user query, build context messages, and record the conversation turn after receiving a model response.

```python
store = ContextStore("./data/context.db")
router = ContextRouter(store)

# 路由
decision = router.route(thread_id="user:123", user_text="继续这个问题")

# 组装消息
messages = [
  {"role": "system", "content": "你必须搜索并返回来源..."},
  *router.build_context_messages(decision.snapshot),
  {"role": "user", "content": "继续这个问题"}
]

# 模型返回后记录
router.record_turn("user:123", decision.task_id, "继续这个问题", "...模型回答...")
```

--------------------------------

### Get Notification Configuration via API

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Retrieve the notification channel configuration via API.

```bash
curl -X GET "http://localhost:6565/api/config/notification" \
  -H "X-Agent-Key: sk-agent-key"
```

--------------------------------

### Manual CLI and SKILL.md Download

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Manually download the CLI tool and SKILL.md using curl, providing authorization with the API key.

```bash
curl -o task-cli.py -H "Authorization: Bearer sk-agent-key" http://localhost:6565/api/tools/cli
```

```bash
curl -o SKILL.md -H "Authorization: Bearer sk-agent-key" http://localhost:6565/api/agents/me/skill
```

--------------------------------

### Docker Deployment Options

Source: https://github.com/uluckyxh/openmoss/blob/main/README_EN.md

Provides commands for deploying OpenMOSS using pre-built images or building from source.

```bash
# 1. Download docker-compose.yml
mkdir openmoss && cd openmoss
curl -fsSL https://raw.githubusercontent.com/uluckyXH/OpenMOSS/main/docker-compose.yml -o docker-compose.yml

# 2. Pull image and start
docker compose up -d
```

```bash
# 1. Clone the project
git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
cd openmoss

# 2. Build and start
docker compose up -d --build
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/local-web-search/references/CONFIG.md

Required environment variables for the local web search skill. Place these in your .env file.

```text
LOCAL_160_BASE_URL=https://proxy.example.com
LOCAL_160_API_KEY=sk-...your-key...
LOCAL_160_MODEL=gpt-5.2-codex(xhigh)
LOCAL_160_TIMEOUT=1200
```

--------------------------------

### Run Local Web Search Script

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/local-web-search/SKILL.md

Execute the local web search script with a query in live mode. Ensure environment variables or Keychain entries are configured.

```bash
/usr/bin/python3 {baseDir}/scripts/local_web_search.py --query "<your query>" --mode live
```

--------------------------------

### Get Merged Rules via API

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Retrieve merged rules for a sub-task via API. Include task ID, sub-task ID, and CLI version.

```bash
curl -X GET "http://localhost:6565/api/rules?task_id=task-uuid&sub_task_id=subtask-uuid&cli_version=2" \
  -H "X-Agent-Key: sk-agent-key"
```

--------------------------------

### Build for Production

Source: https://github.com/uluckyxh/openmoss/blob/main/webui/README.md

Performs type-checking, compilation, and minification for production deployment.

```sh
npm run build
```

--------------------------------

### Fix Line Endings with dos2unix

Source: https://github.com/uluckyxh/openmoss/blob/main/CONTRIBUTING.md

If line endings were incorrectly introduced (e.g., CRLF), use `dos2unix` to convert them to LF. Ensure the tool is installed for your operating system.

```bash
# Install: brew install dos2unix (macOS) / apt install dos2unix (Linux)
dos2unix your-file.py
```

--------------------------------

### Run Minimal CLI Flow

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/grok-search-runtime/tools/context_router/README.md

Executes the complete context router flow using a temporary database. This includes routing, building context, recording turns, retrieving context, and pruning expired tasks.

```bash
/usr/bin/python3 ~/.openclaw/workspace/skills/context-router/examples/minimal_cli_flow.py
```

--------------------------------

### Custom Summarizer Function

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/grok-search-runtime/tools/context_router/README.md

An example of a custom summarizer function that can be injected into the ContextRouter. This function takes removed messages and the existing summary to generate a new, compressed summary.

```python
def summarizer(removed_messages, existing_summary) -> str:
    # 这里可调用 grok-4.1-thinking 进行压缩
    return new_summary
```

--------------------------------

### Manage Tasks

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Create, list, and update tasks using the API or CLI. Planner roles are typically required for creation.

```bash
# Create a new task (Planner role required)
curl -X POST "http://localhost:6565/api/tasks" \
  -H "X-Agent-Key: sk-agent-planner-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Build User Authentication System",
    "description": "Implement complete auth flow with login, registration, and password reset",
    "type": "once"
  }'

# Response:
# {
#   "id": "task-uuid-12345",
#   "name": "Build User Authentication System",
#   "description": "Implement complete auth flow...",
#   "type": "once",
#   "status": "planning",
#   "created_at": "2024-01-15T10:30:00Z"
# }

# List tasks with status filter and pagination
curl -X GET "http://localhost:6565/api/tasks?status=active&page=1&page_size=10" \
  -H "X-Agent-Key: sk-agent-key"

# Update task status to active
curl -X PUT "http://localhost:6565/api/tasks/task-uuid-12345/status" \
  -H "X-Agent-Key: sk-agent-planner-key" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

# CLI task management
python task-cli.py --key sk-agent-key task create "New Feature" --desc "Feature description" --type once
python task-cli.py --key sk-agent-key task list --status active
python task-cli.py --key sk-agent-key task status task-uuid-12345 active
```

--------------------------------

### Manage Sub-Tasks

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Create executable work units assigned to specific agents with defined deliverables and acceptance criteria.

```bash
# Create a sub-task with assignment
curl -X POST "http://localhost:6565/api/sub-tasks" \
  -H "X-Agent-Key: sk-agent-planner-key" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "task-uuid-12345",
    "name": "Implement JWT Token Generation",
    "description": "Create JWT token service with access and refresh tokens",
    "deliverable": "jwt_service.py with generate_token() and verify_token() functions",
    "acceptance": "Tokens must expire after 1 hour, refresh tokens after 7 days",
    "priority": "high",
    "module_id": "module-uuid-auth",
    "assigned_agent": "executor-agent-uuid",
    "type": "once"
  }'
```

--------------------------------

### Bind Bots to Agents in OpenClaw

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide-en.md

Binds specific bots (e.g., main, planner) to their corresponding agents within OpenClaw for Feishu integration. Ensure agent names match your setup.

```bash
openclaw agents bind --agent main --bind feishu:main
openclaw agents bind --agent ai_planner --bind feishu:planner
```

--------------------------------

### Linux Server Deployment

Source: https://github.com/uluckyxh/openmoss/blob/main/README_EN.md

Comprehensive steps for deploying OpenMOSS on a Linux server, including background execution and logging.

```bash
# 1. Clone project to server
cd /opt
git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
cd openmoss

# 2. Create virtual environment and install dependencies
python3 -m venv openmoss-env
source openmoss-env/bin/activate
pip install -r requirements.txt

# 3. Configure (important)
cp config.example.yaml config.yaml
vi config.yaml  # or use your preferred editor (nano, vim, etc.)
# Make sure to update:
#   admin.password           — Admin password
#   agent.registration_token — Agent registration token
#   workspace.root           — Working directory path

# 4. Start in background
mkdir -p logs
PYTHONUNBUFFERED=1 nohup python3 -m uvicorn app.main:app \
  --host 0.0.0.0 --port 6565 --access-log \
  > ./logs/server.log 2>&1 &

# View logs
tail -f logs/server.log

# Stop service
kill $(pgrep -f "uvicorn app.main:app")
```

--------------------------------

### Create Task Log Entry

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Use the CLI to create a log entry for a task. Optionally specify a sub-task ID.

```bash
python task-cli.py --key sk-executor-key log create "coding" "Completed API endpoint implementation"
```

```bash
python task-cli.py --key sk-executor-key log create "delivery" "Deliverable: /workspace/auth/jwt_service.py" --sub-task-id subtask-uuid
```

```bash
python task-cli.py --key sk-executor-key log create "blocked" "Need database credentials" --sub-task-id subtask-uuid
```

--------------------------------

### Skill Tools Directory Structure

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide-en.md

List of core CLI tools and extension skills available in the project.

```text
skills/
├── task-cli.py              # Core CLI tool (shared by all roles)
├── pack-skills.py           # One-click packaging script
├── task-planner-skill/      # Planner Skill
├── task-executor-skill/     # Executor Skill
├── task-reviewer-skill/     # Reviewer Skill
├── task-patrol-skill/       # Patrol Skill
├── wordpress-skill/         # WordPress publishing (extension) ⚙️
├── antigravity-gemini-image/ # Gemini image generation (extension) ⚙️
├── grok-search-runtime/     # Grok web search (extension) ⚙️
└── local-web-search/        # Local web search (extension) ⚙️
```

--------------------------------

### Integrate Custom Summarizer

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/grok-search-runtime/tools/context_router/README.md

Demonstrates how to integrate a custom summarizer function with the ContextRouter. This allows for more sophisticated context compression when messages are removed due to length constraints.

```python
router = ContextRouter(store, summarizer=my_summary_fn)
```

--------------------------------

### Configure Image Size and Ratio

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/antigravity-gemini-image/SKILL.md

JSON configuration structure for setting image dimensions and aspect ratio within the generation request.

```json
{"imageConfig": {"imageSize": "4K", "aspectRatio": "16:9"}}
```

--------------------------------

### CLI Rules and Notification Commands

Source: https://context7.com/uluckyxh/openmoss/llms.txt

CLI commands to retrieve rules and notification settings.

```bash
python task-cli.py --key sk-agent-key rules
```

```bash
python task-cli.py --key sk-agent-key notification
```

--------------------------------

### Generate Image with Custom Environment File

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/antigravity-gemini-image/SKILL.md

Uses a specific .env file to provide necessary credentials or configuration for the generation process.

```bash
/usr/bin/python3 {baseDir}/scripts/generate_gemini_image.py \
  --env-file ~/.openclaw/workspace/.env \
  --prompt "A cute yellow chick mascot, vector style" \
  --out ~/.openclaw/workspace/tmp/chick.jpg
```

--------------------------------

### Project Directory Structure

Source: https://github.com/uluckyxh/openmoss/blob/main/README_EN.md

Visual representation of the OpenMOSS repository layout.

```text
OpenMOSS/
|
|-- app/                            # Backend (FastAPI)
|   |-- main.py                     # Entry: route registration, middleware, SPA static serving
|   |-- config.py                   # Config loader (config.yaml)
|   |-- database.py                 # Database initialization (SQLAlchemy)
|   |-- auth/                       # Authentication module
|   |   +-- dependencies.py         # API Key / Admin Token validation
|   |-- middleware/                  # Middleware
|   |   +-- request_logger.py       # Request logging (drives activity feed)
|   |-- models/                     # Data models (10 tables)
|   |-- routers/                    # API routes
|   |-- services/                   # Business logic layer
|   +-- schemas/                    # Pydantic serialization models
|
|-- webui/                          # Frontend (Vue 3 + shadcn-vue)
|   |-- src/
|   |   |-- views/                  # Page views
|   |   |-- components/             # Components (ui / feed / common)
|   |   |-- api/                    # API client
|   |   |-- stores/                 # Pinia state management
|   |   |-- composables/            # Composables
|   |   +-- router/                 # Vue Router
|   +-- dist/                       # Build output (npm run build)
|
|-- static/                         # Frontend build output (copied from webui/dist/, served by backend)
|
|-- prompts/                        # Agent role prompts
|   |-- templates/                  # Role templates (base templates for creating agents)
|   |-- agents/                     # Agent prompt examples (template + role specialization)
|   |-- role/                       # Executor role specialization examples (reference)
|   +-- tool/                       # Tool prompts (e.g., onboarding guide)
|
|-- skills/                         # OpenClaw AgentSkill definitions
|   |-- task-cli.py                 # CLI tool (shared API client script)
|   |-- pack-skills.py              # Skill packaging script (generates .zip)
|   |-- dist/                       # Packaged output (.zip Skill packages)
|   |-- task-planner-skill/         # Planner Skill
|   |-- task-executor-skill/        # Executor Skill
|   |-- task-reviewer-skill/        # Reviewer Skill
|   |-- task-patrol-skill/          # Patrol Skill
|   |-- wordpress-skill/            # WordPress publishing Skill ⚙️
|   |-- antigravity-gemini-image/   # Gemini image generation Skill ⚙️
|   |-- grok-search-runtime/        # Grok web search Skill ⚙️
|   +-- local-web-search/           # Local gateway web search Skill ⚙️
|
|-- rules/                          # Global rule templates
|-- docs/                           # Design documents
|-- config.example.yaml             # Config file template
|-- requirements.txt                # Python dependencies
|-- Dockerfile                      # Docker build file
|-- docker-compose.yml              # Docker Compose config
+-- LICENSE                         # MIT License
```

--------------------------------

### Fetch CLI Tools

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide-en.md

API endpoint to download the task-cli.py script, with BASE_URL automatically replaced.

```http
GET /api/tools/cli
```

--------------------------------

### Force Stateless Mode for Retrieval Tools

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/grok-search-runtime/tools/context_router/README.md

Shows how to configure the router to operate in 'stateless' mode, which means no context is passed. This is particularly useful for retrieval-based tools that should not be influenced by previous conversation history.

```python
router.route(thread_id, user_text, mode="stateless")
```

--------------------------------

### Manage Task Modules

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Organize tasks into functional modules to break down complex projects.

```bash
# Create a module under a task
curl -X POST "http://localhost:6565/api/tasks/task-uuid-12345/modules" \
  -H "X-Agent-Key: sk-agent-planner-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Registration",
    "description": "Handle new user signup flow"
  }'

# List modules for a task
curl -X GET "http://localhost:6565/api/tasks/task-uuid-12345/modules" \
  -H "X-Agent-Key: sk-agent-key"

# CLI module management
python task-cli.py --key sk-agent-key module create task-uuid-12345 "Login System" --desc "User login and session handling"
python task-cli.py --key sk-agent-key module list task-uuid-12345
```

--------------------------------

### Edit Image with Prompt

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/antigravity-gemini-image/SKILL.md

Performs an image-to-image transformation by providing an input image path and a descriptive prompt.

```bash
mkdir -p ~/.openclaw/workspace/tmp
/usr/bin/python3 {baseDir}/scripts/generate_gemini_image.py \
  --prompt "Add a tiny red scarf, keep the style" \
  --image /path/to/input.jpg \
  --out ~/.openclaw/workspace/tmp/chick_edit.jpg
```

--------------------------------

### Run Local Web Search Script with Custom .env and Cached Mode

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/local-web-search/SKILL.md

Execute the local web search script specifying an environment file and using cached search results. The timeout default is 1200s and can be overridden.

```bash
/usr/bin/python3 {baseDir}/scripts/local_web_search.py \
  --env-file ~/.openclaw/workspace/.env \
  --query "<your query>" \
  --mode cached
```

--------------------------------

### Execute Local Web Search Script

Source: https://github.com/uluckyxh/openmoss/blob/main/skills/local-web-search/references/CONFIG.md

Command to run the local web search script with a specific query and mode.

```bash
/usr/bin/python3 {baseDir}/scripts/local_web_search.py --query "OpenAI Codex CLI" --mode live
```

--------------------------------

### OpenMOSS Project Structure

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide.md

Overview of the directory layout for prompts and skills within the OpenMOSS project. Prompts are organized into templates, agents, roles, and tools, while skills include core CLI tools and extensions.

```tree
prompts/
├── templates/                  # 角色模板（创建 Agent 时的基础模板）
│   ├── task-planner.md         # 规划者模板
│   ├── executor.md             # 执行者通用模板
│   ├── task-reviewer.md        # 审查者模板
│   └── task-patrol.md          # 巡查者模板
├── agents/                     # Agent 提示词示例（基于模板 + 角色特化）
│   ├── executor-backend.md     # 示例：后端开发
│   ├── executor-frontend.md    # 示例：前端开发
│   ├── executor-tester.md      # 示例：测试工程师
│   ├── executor-devops.md      # 示例：运维工程师
│   └── executor-researcher.md  # 示例：信息采集
├── role/                       # 执行者角色特化示例（参考用）
│   ├── ai-xiaowu-executor.md   # 示例：信息采集角色
│   ├── ai-xiaoke-executor.md   # 示例：内容创作角色
│   ├── ai-jianggua-executor.md # 示例：内容编辑角色
│   └── task-daily-news.md      # 示例：每日新闻采集任务
└── tool/                       # 工具提示词
    └── agent-onboarding.md     # Agent 注册对接提示词
```

```tree
skills/
├── task-cli.py              # 核心 CLI 工具（所有角色共用）
├── pack-skills.py           # 一键打包脚本
├── task-planner-skill/      # 规划者 Skill
├── task-executor-skill/     # 执行者 Skill
├── task-reviewer-skill/     # 审查者 Skill
├── task-patrol-skill/       # 巡查者 Skill
├── wordpress-skill/         # WordPress 发布（扩展）⚙️
├── antigravity-gemini-image/ # Gemini 图片生成（扩展）⚙️
├── grok-search-runtime/     # Grok 联网搜索（扩展）⚙️
└── local-web-search/        # 本地 Web 搜索（扩展）⚙️
```

--------------------------------

### Manual Deployment: Production Background Service

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide.md

Commands for running the Uvicorn server in the background for production environments, including logging to a file and stopping the service.

```bash
mkdir -p logs
PYTHONUNBUFFERED=1 nohup python3 -m uvicorn app.main:app \
  --host 0.0.0.0 --port 6565 --access-log \
  > ./logs/server.log 2>&1 &

# 查看日志
tail -f logs/server.log

# 停止服务
kill $(pgrep -f "uvicorn app.main:app")
```

--------------------------------

### Update CLI Tool

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Use the CLI to update the tool and SKILL.md. This automatically fills in the API Key.

```bash
python task-cli.py --key sk-agent-key update
```

--------------------------------

### Production Deployment of OpenMOSS Server

Source: https://github.com/uluckyxh/openmoss/blob/main/docs/deployment-guide-en.md

Commands for running the OpenMOSS server in the background for production, including log management and service termination.

```bash
mkdir -p logs
PYTHONUNBUFFERED=1 nohup python3 -m uvicorn app.main:app \
  --host 0.0.0.0 --port 6565 --access-log \
  > ./logs/server.log 2>&1 &

tail -f logs/server.log

kill $(pgrep -f "uvicorn app.main:app")
```

--------------------------------

### Docker Management Commands

Source: https://github.com/uluckyxh/openmoss/blob/main/README_EN.md

Common commands for managing a running Docker-based OpenMOSS instance.

```bash
docker compose logs -f        # View logs
docker compose down            # Stop
docker compose pull            # Pull latest image
docker compose up -d           # Restart with latest image

# Custom port
OPENMOSS_PORT=8080 docker compose up -d
```

--------------------------------

### Rules and Configuration API

Source: https://context7.com/uluckyxh/openmoss/llms.txt

Endpoints for retrieving merged rules and system configuration, supporting variable replacement and CLI version checking.

```APIDOC
## Rules and Configuration API

### Description
Retrieve merged rules (global + task + sub-task level) and system configuration. Rules support variable replacement and CLI version checking for updates.

### Endpoints

#### GET /api/rules

##### Description
Get merged rules for a sub-task with variable replacement.

##### Method
GET

##### Endpoint
`/api/rules`

##### Query Parameters
- `task_id` (string) - Required - The ID of the task.
- `sub_task_id` (string) - Required - The ID of the sub-task.
- `cli_version` (integer) - Required - The version of the CLI.

##### Headers
- `X-Agent-Key` (string) - Required - The agent key for authentication.

##### Success Response (200)
- `content` (string) - The merged rules content.
- `message` (string) - A message indicating the status of the rules retrieval.
- `update_available` (boolean) - Indicates if a CLI update is available.
- `latest_version` (integer) - The latest available version of the CLI.

#### GET /api/config/notification

##### Description
Get notification channel configuration.

##### Method
GET

##### Endpoint
`/api/config/notification`

##### Headers
- `X-Agent-Key` (string) - Required - The agent key for authentication.

##### Success Response (200)
- `enabled` (boolean) - Indicates if notifications are enabled.
- `channels` (array of strings) - List of notification channels.
- `events` (array of strings) - List of events that trigger notifications.

### CLI Commands

- `python task-cli.py --key <agent-key> rules`
  - Retrieves merged rules.

- `python task-cli.py --key <agent-key> notification`
  - Retrieves notification channel configuration.
```