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: ```bash 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: ```mermaid 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: ```bash 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: ```bash 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: ```bash ~/.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: ```bash ~/.openclaw/skills/mailhub/setup --no-encryption ``` Rotate systemd dbkey explicitly (default setup reuses existing credential to avoid breaking old DB key): ```bash ~/.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](./PROVIDERS.md) 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` ```bash 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` ```bash 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