Skip to content

README.md

Latest commit

 

History

History
333 lines (256 loc) · 8.17 KB

README.md

File metadata and controls

333 lines (256 loc) · 8.17 KB

gois-lite — QClaw Monitor (Lite)

License: MIT GitHub

Generative Orchestration Artificial Intelligence Swarm — lite edition

Health monitor, HTTP dashboard, and AI orchestration for QClaw, OpenClaw, and Hermes — with development-focused skills only (default port 9102). Full edition: gois.

Language Document
🇺🇸 English You are here
🇧🇷 Português README.pt.md
🇨🇳 简体中文 README.zh-CN.md

Overview

gois watches QClaw (and related services) on macOS and Windows. It periodically checks process health and HTTP endpoints; after repeated failures, an LLM recovery agent diagnoses logs and attempts self-healing. It exposes an HTTP dashboard, Prometheus metrics, and deep integration with Hermes, OpenClaw, RuFlo, Kanban, WhatsApp, and 300+ QClaw skills.

flowchart TB
    subgraph Clients["Clients & Channels"]
        UI["Browser Dashboard :9101"]
        WA["WhatsApp (wacli)"]
        Cursor["Cursor IDE + MCP"]
    end

    subgraph Gois["gois Monitor"]
        MON["Health Monitor"]
        AGT["LLM Recovery Agent"]
        DASH["HTTP Dashboard"]
        MCP["MCP Servers"]
    end

    subgraph Stack["Vendor Stack (.stack/)"]
        OC["OpenClaw"]
        HM["Hermes Agent"]
        DB[("MongoDB / Redis / SQLite")]
    end

    subgraph External["External"]
        LLM["DeepSeek / OpenAI-compat"]
        PROM["Prometheus"]
    end

    UI --> DASH
    WA --> DASH
    Cursor --> MCP
    MON -->|"pgrep + HTTP + hang"| OC
    MON -->|"failure threshold"| AGT
    AGT --> LLM
    AGT --> OC
    DASH --> OC
    DASH --> HM
    DASH --> DB
    MCP --> DASH
    MON --> PROM
Loading

What it does

Component Role
Monitor pgrep, HTTP health probes, optional UI hang detection, log scanning
Recovery agent OpenAI-compatible LLM (default DeepSeek) with tools to read logs, restart QClaw, etc.
Dashboard UI at http://127.0.0.1:9101/ — status, chat, Hermes roles, Kanban, skills
MCP servers qclaw-skills, qclaw-cards, qclaw-jobs, qclaw-swarm for Cursor / IDE
Metrics Prometheus endpoint (configurable in config.yaml)
Skills 300+ QClaw skills — slides, AWS, WhatsApp, research, content, and more

Health-check flow

sequenceDiagram
    participant M as Monitor
    participant Q as QClaw / Gateway
    participant A as LLM Agent
    participant L as Logs

    loop Every interval_seconds
        M->>Q: pgrep + HTTP GET health_url
        alt Healthy
            M->>M: Reset failure counter
        else Unhealthy
            M->>M: Increment failures
            alt failures >= threshold
                M->>L: Tail log_paths
                M->>A: Diagnose + recover
                A->>L: Read evidence
                A->>Q: Restart (if needed)
            end
        end
    end
Loading

Requirements

Item Version Required
Python 3.11+ Yes
Git 2.x Yes
DeepSeek API key — Yes (LLM agent + chat)
Node.js 22+ Yes (OpenClaw vendor)
MongoDB 7.x Recommended
Redis 7.x Recommended
macOS / Windows — Native install
Docker + Compose v2 Optional (Linux / server)

Quick start

The repo is self-contained: Hermes (vendor/hermes-agent) and OpenClaw (vendor/openclaw) ship as Git submodules. ./scripts/start.sh bootstraps everything on first run.

git clone --recurse-submodules <repo-url> gois
cd gois
./scripts/start.sh

start.sh is idempotent. It:

  1. Creates ./.venv and installs gois (pip install -e .[dev])
  2. Runs ./scripts/unify-stack.sh (submodules, .stack/, vendor deps)
  3. Ensures ./config.yaml and ./.env
  4. Starts the monitor

Dashboard: http://127.0.0.1:9101/

Fast restart (skip vendor reinstall):

./scripts/start.sh --skip-vendor

Full install guide: docs/INSTALACAO.md

Docker

cp .env.example .env   # set DEEPSEEK_API_KEY
docker compose up -d --build

DeepSeek API key

Never commit .env. Copy from example:

DEEPSEEK_API_KEY=sk-your-key
DEEPSEEK_API_BASE=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

Or sync from a sibling project:

.venv/bin/python scripts/sync_deepseek_env.py

Project layout

flowchart LR
    subgraph Repo["Repository"]
        SRC["src/gois/"]
        SKL["skills/ (300+)"]
        VND["vendor/"]
        SCR["scripts/"]
    end

    subgraph Runtime[".stack/ (gitignored)"]
        SH["hermes/"]
        SO["openclaw/state/"]
        SB["openclaw/bundle/"]
        ACC["accounts/"]
        CH["chat/"]
    end

    VND --> HM["hermes-agent"]
    VND --> OC["openclaw"]
    SRC --> Runtime
    SCR --> Runtime
Loading 
gois/
├── src/gois/           ← Python monitor + dashboard + MCP
├── skills/             ← QClaw skills (chat tools, batch slides, AWS, …)
├── vendor/
│   ├── hermes-agent/   ← Hermes (git submodule)
│   └── openclaw/       ← OpenClaw (git submodule)
├── .stack/             ← Runtime state (generated at boot)
│   ├── hermes/
│   ├── openclaw/
│   ├── accounts/
│   └── chat/
└── scripts/
    ├── start.sh
    └── unify-stack.sh

Migrate legacy state from ~/.hermes or ~/.qclaw-oversea:

./scripts/unify-stack.sh --migrate

Environment overrides:

Variable Default
GOIS_STACK_ROOT ./.stack
GOIS_HERMES_HOME / HERMES_HOME .stack/hermes
GOIS_OPENCLAW_SOURCE ./vendor/openclaw
GOIS_OPENCLAW_STATE_DIR .stack/openclaw/state

MCP integration (Cursor / IDE)

flowchart LR
    Cursor["Cursor IDE"]
    SK["qclaw-skills"]
    CR["qclaw-cards"]
    JB["qclaw-jobs"]
    SW["qclaw-swarm"]
    RF["ruflo"]

    Cursor --> SK
    Cursor --> CR
    Cursor --> JB
    Cursor --> SW
    Cursor --> RF

    SK -->|"slides, AWS, files"| Gois
    CR -->|"Kanban, teams"| Gois
    JB -->|"cron, health"| Gois
    SW -->|"multi-agent"| Gois
Loading
MCP server Tools (examples)
qclaw-skills team_files_search, slides_batch_images, aws_overview, monitor_update
qclaw-cards get_cards, move_card, list_teams, get_errors
qclaw-jobs jobs_health, jobs_list_running, jobs_cron_list
qclaw-swarm swarm_create, swarm_health, run_team_swarm
ruflo Swarm orchestration for development

Setup RuFlo for Cursor:

./scripts/setup-ruflo-dev.sh

Dashboard URLs

URL Description
/ Monitor status
/chat OpenClaw / QClaw chat (DeepSeek + skills)
/chat/ruflo RuFlo-integrated chat
/chat?whatsapp=1 WhatsApp session
/skills OpenClaw skills catalog
/roles Hermes role profiles
/kanban Team Kanban boards
/whatsapp/status wacli queue and listener state

WhatsApp bridge

flowchart LR
    Phone["Phone"]
    WACLI["wacli"]
    WH["POST /whatsapp/inbound"]
    Chat["/chat session"]
    Agent["DeepSeek + skills"]
    Send["wacli-send.sh"]

    Phone --> WACLI
    WACLI --> WH
    WH --> Chat
    Chat --> Agent
    Agent --> Send
    Send --> Phone
Loading

Enable in config.yaml under whatsapp_digest. See README.pt.md for detailed Portuguese setup notes, or config.example.yaml.

macOS auto-start

./scripts/start.sh --launchd

Logs: gois.stdout.log, gois.stderr.log

Tests

.venv/bin/pytest

Security

  • Never commit .env, sk-… keys, or filled config.yaml
  • Use config.example.yaml as template; revoke exposed keys immediately
  • See SECURITY.md

License

See repository; treat as internal use until a LICENSE file is added.