AlertClaw | 观潮听舆

AlertClaw is the main product in this repository. It includes:

1. A FastAPI backend for auth, monitoring subscriptions, reports, PDF export, and the web ClawBot 2. A React + Vite frontend for the dashboard, monitoring center, analysis workspace, account page, and web ClawBot 3. Supporting runtime services such as MongoDB and DailyHot API 4. AlertClaw ClawBridge, a separate Weixin ClawBot compatibility ingress service

Architecture position

AlertClaw is the product system.

AlertClaw ClawBridge is not the whole platform runtime. It is a self-developed ingress tool used only for the official Weixin ClawBot path. Its job is:

1. Weixin QR binding 2. Weixin identity mapping 3. Message polling and forwarding 4. Calling back into the AlertClaw backend

OpenClaw remains only a compatibility kernel used inside ClawBridge. It is not the business core of AlertClaw.

See docs/clawbridge-architecture.md for the detailed story and layering.

Current phase

Path 1 is now in phase 3.

Implemented:

1. ClawBridge can expose QR start and QR status APIs 2. ClawBridge can persist Weixin bot sessions and account state 3. The backend can switch between openclaw and clawbridge providers 4. ClawBridge can deliver inbound Weixin messages to a dedicated internal backend chat endpoint 5. Monitoring alert push can now go back out through ClawBridge 6. The backend still remains the only business brain for monitoring, reports, and PDF logic 7. Weixin ClawBot can query the current overall Top10 hotboard through the shared backend brain 8. Weixin ClawBot can receive generated PDF reports directly as file replies

Not implemented yet:

1. Rich outbound media beyond image and PDF delivery 2. Production cutover playbook for the Weixin channel 3. Real-account end-to-end validation for the Weixin path

Main routes

1. / hotboard 2. /clawbot web ClawBot 3. /monitoring monitoring center 4. /analysis analysis workspace 5. /account Weixin binding 6. /login and /register

Backend quick start

pip install -r requirements.txt
copy .env.example .env
uvicorn app.main:app --reload

Backend default URL: http://127.0.0.1:8000

Frontend quick start

cd frontend
npm install
npm run dev

Frontend default URL: http://127.0.0.1:5173

ClawBridge quick start

cd clawbridge
npm install
npm run start

ClawBridge default URL: http://127.0.0.1:8787

Main internal routes:

1. /health 2. /ready 3. /manifest 4. /api/v1/weixin/qr/start 5. /api/v1/weixin/qr/status 6. /api/v1/weixin/accounts/{account_id} 7. /api/v1/weixin/messages 8. /api/v1/weixin/files

Important environment variables

Shared runtime

1. MONGO_URI 2. MONGO_DB_NAME 3. AUTH_SESSION_COOKIE_NAME 4. AUTH_SESSION_TTL_HOURS 5. AUTH_WEIXIN_QR_TTL_MINUTES 6. AUTH_INTERNAL_OPENCLAW_SECRET

Gateway provider switch

1. CLAW_GATEWAY_PROVIDER 2. OPENCLAW_GATEWAY_URL 3. OPENCLAW_GATEWAY_TOKEN 4. OPENCLAW_GATEWAY_DEVICE_TOKEN

Use CLAW_GATEWAY_PROVIDER=clawbridge for the new phase-2 path. Use CLAW_GATEWAY_PROVIDER=openclaw if you need to roll back temporarily.

ClawBridge

1. CLAWBRIDGE_SERVICE_NAME 2. CLAWBRIDGE_INSTANCE_ID 3. CLAWBRIDGE_PORT 4. CLAWBRIDGE_PUBLIC_BASE_URL 5. CLAWBRIDGE_INTERNAL_BASE_URL 6. CLAWBRIDGE_BACKEND_BASE_URL 7. CLAWBRIDGE_INTERNAL_SECRET 8. CLAWBRIDGE_RUNTIME_DIR 9. CLAWBRIDGE_REQUEST_TIMEOUT_MS 10. CLAWBRIDGE_API_TIMEOUT_MS 11. CLAWBRIDGE_QR_STATUS_TIMEOUT_MS 12. CLAWBRIDGE_LONG_POLL_TIMEOUT_MS 13. CLAWBRIDGE_CHAT_DISPATCH_TIMEOUT_MS 14. CLAWBRIDGE_MAX_IMAGE_BYTES 15. CLAWBRIDGE_MAX_ATTACHMENT_BYTES

Web ClawBot

1. CHATBOX_LLM_API_KEY 2. CHATBOX_LLM_BASE_URL 3. CHATBOX_LLM_MODEL_NAME 4. CHATBOX_VISION_MODEL_NAME 5. CHATBOX_LLM_ENABLE_THINKING

Reporting

1. REPORT_LLM_API_KEY 2. REPORT_LLM_BASE_URL 3. REPORT_LLM_MODEL_NAME 4. REPORT_LLM_ENABLE_SEARCH

Internal backend protocol

The backend keeps all browser APIs unchanged.

The new internal ClawBridge protocol is exposed at:

1. GET /api/v1/internal/clawbridge/bootstrap 2. POST /api/v1/internal/clawbridge/chatbox/messages

These routes are internal only and require the ClawBridge secret header.

ClawBridge itself now also exposes an internal proactive send route for backend-triggered Weixin alerts:

1. POST /api/v1/weixin/messages 2. POST /api/v1/weixin/files

Docker compose

docker compose up -d --build

The default compose stack now runs:

1. frontend 2. app 3. mongo 4. dailyhot-api 5. clawbridge

The backend talks to clawbridge over the container network by default.

Useful commands

pytest
cd frontend && npm run build
cd clawbridge && npm test
docker compose config

my-plugin

Summary

Install to Claude Code