MailHub

MailHub (OpenClaw Skill)

Unified multi-account mail/calendar/contacts connector.

English

1) Overall

MailHub provides one CLI surface for mail, calendar, summary, and OpenClaw bridge workflows.

What it can do:

• Mail polling, triage, reply draft, send queue, auto-reply.
• Calendar view/add/delete/sync/remind/summary.
• Unified summary for mail + calendar by flexible datetime range.
• OpenClaw-oriented structured output for downstream agent UX.

TUI preview placeholder (replace with your real screenshot later):

If command usage is unclear:

mailhub --help
mailhub tui --help
mailhub mail --help
mailhub calendar --help
mailhub summary --help
mailhub openclaw --help

2) Run Modes

Two runtime modes are supported through the same command surface.

• openclaw: OpenClaw agent drives orchestration/reasoning.
• standalone: MailHub runs local scheduling and local agent bridge.

Execution path:

flowchart TD
    A["User / Trigger"] --> B["mailhub CLI entrypoint"]
    B --> C{"runtime mode"}
    C -->|"openclaw"| D["OpenClaw orchestrates"]
    C -->|"standalone"| E["local agent_bridge + standalone.models.json"]
    D --> F["MailHub pipelines"]
    E --> F
    F --> G["SQLCipher SQLite + KV + JSON output"]

openclaw mode

Pros:

• Better natural-language orchestration in OpenClaw conversations.

Tradeoffs:

• Depends on OpenClaw runtime availability and routing.

standalone mode

Pros:

• Suitable for daemon-style operation and scheduled processing.
• Can reuse OpenClaw-style runner config or fully custom models config.

Tradeoffs:

• Requires local runner/models setup and health checks.
• Loop path is checkpoint-driven (provider remote-id vs local stored state), not poll-window driven.
• MailHub no longer performs model heartbeat checks at loop start. Provider/model detection and fallback run only after a real inference call fails.
• New-mail pipeline in standalone loop: poll new messages -> one classify_email LLM call per message (summary+tag+reply suggestion) -> optional auto-draft/send.

Daemon management

Foreground loop command:

mailhub mail loop --interval-seconds 60

setup can install service automatically in standalone mode:

• macOS: launchd
• Linux: systemd --user

Logs for daemon mode:

• Linux (systemd --user): journalctl --user -u mailhub-loop.service -f
• macOS (launchd): tail -f ~/Library/Logs/mailhub-loop.log (if redirected) or log stream --predicate 'process CONTAINS "mailhub"'

3) Primary Entrypoints

Configuration / Diagnostics:

• mailhub wizard: unified configuration wizard.
• mailhub config: first-run review/confirm gate.
• mailhub doctor: health checks (including standalone models link checks and dbkey backend evidence).
• mailhub dbkey-setup: SQLCipher dbkey bootstrap (detect/select/write/read/verify).

Account binding:

• mailhub bind: provider binding and account capability management.

Business entrypoints:

• mailhub tui: unified Textual TUI entrypoint.
• mailhub mail: mail workflow entrypoint.
• mailhub calendar: calendar workflow entrypoint.
• mailhub summary: summary workflow entrypoint.
• mailhub openclaw: OpenClaw bridge entrypoint.
• mailhub test: integration test entrypoint (interactive menu + direct case execution).

Interactive behavior:

• In standalone mode, mailhub mail|calendar|summary|test opens TUI menus when called without subcommands.
• In openclaw mode, use explicit subcommands for deterministic skill routing.
• Launcher behavior on Linux/systemd:
  • TTY interactive commands run through systemd-run --pty (low-latency terminal I/O).
  • Non-TTY calls keep systemd-run --pipe for script-friendly output capture.

4) Setup

Clone into skill directory and run setup wizard:

git clone https://github.com/Nonosword/openclaw-skill-mailhub ~/.openclaw/skills/mailhub && ~/.openclaw/skills/mailhub/setup --wizard --source env

Setup flow (current implementation):

1. Create venv + launcher, and initialize settings/models templates when missing.
2. Security strategy:
   • default (recommended): keep SQLCipher encryption, run dbkey bootstrap first (mailhub dbkey-setup)
   • fallback (unsafe): setup --no-encryption to skip dbkey and use plaintext SQLite
3. Detect dbkey methods and show only usable choices:
   • Keychain (macOS Keychain / Linux Secret Service)
   • systemd credentials (CREDENTIALS_DIRECTORY/dbkey or MAILHUB_DBKEY_FILE)
   • Local dbkey.enc fallback
4. After user selection, immediately verify:
   • read dbkey from selected backend
   • open SQLCipher DB
   • read/write health probe
5. If verification fails, rollback and provide actionable hints.
6. If dbkey backend changes, setup attempts DB rekey migration automatically.
7. Continue mode/setup flow: choose mode openclaw or standalone.
8. If standalone, choose model source:
   • openclaw: reuse OpenClaw-style runner preset, then provide OpenClaw JSON path, and auto-fill standalone.models.json with OpenClaw defaults (agent.id, defaults.primary_model, providers when empty).
   • own: generate default standalone.models.json, then fill it manually.
9. Optionally install and start background service (platform-aware).
10. mailhub wizard quick start section applies full config, reloads/restarts mailhub-loop.service, then exits wizard automatically.

Non-interactive example:

~/.openclaw/skills/mailhub/setup \
  --dir ~/.openclaw/skills/mailhub \
  --source env \
  --mode standalone \
  --model-source own \
  --standalone-models ~/.openclaw/state/mailhub/standalone.models.json \
  --install-service \
  --interval-seconds 60

Unsafe plaintext example:

~/.openclaw/skills/mailhub/setup --no-encryption

Rotate systemd dbkey explicitly (default setup reuses existing credential to avoid breaking old DB key):

~/.openclaw/skills/mailhub/setup --dbkey-backend systemd --rotate-systemd-dbkey

If setup doctor reports file is not a database, setup now auto-runs mailhub db-rebuild --backup once and reruns doctor.

Doctor checks for standalone models link

mailhub doctor (and --all) checks:

• models file exists / JSON valid
• runner.command can be resolved/executed
• openclaw_json_path existence if referenced by runner args/template

4.2) Provider setup details

Provider-specific onboarding is moved to:

• Provider Binding Guide

LLM prompt assets are centralized in config/prompts/:

• task prompts: classify_email.md, draft_reply.md, summarize_bucket.md
• write prompts: write_auto_format.md, write_auto_optimize.md
• contract definitions: task_contracts.json

5) Engineering Entry

5.1 wizard / config / doctor / bind / dbkey-setup

mailhub wizard
mailhub config
mailhub config --confirm
mailhub doctor
mailhub doctor --all
mailhub dbkey-setup
mailhub dbkey-setup --auto --non-interactive
mailhub db-rekey --old-backend local --new-backend systemd
mailhub db-rebuild --backup
mailhub bind
mailhub bind --list
mailhub bind --provider google --scopes gmail,calendar,contacts

5.2 mail

mailhub mail
mailhub mail run
mailhub mail run --confirm-config
mailhub mail loop --interval-seconds 60
mailhub mail inbox poll --since 15m
mailhub mail inbox ingest --date today
mailhub mail inbox list --date today --limit 20
mailhub mail inbox read --id "<mailhub_message_id>"
mailhub mail reply compose --message-id "<mailhub_message_id>" --mode auto
mailhub mail reply revise --id 2352 --mode optimize --content "<instructions>"
mailhub mail reply send --id 2352 --confirm-text "send" --message '{"Subject":"<subject>","to":"<to>","from":"<from>","context":"<context>"}'
mailhub send --id 2352 --confirm --message '{"Subject":"<subject>","to":"<to>","from":"<from>","context":"<context>"}'
mailhub send --list --confirm --bypass-message

Key logic:

• Increm