수도권 버스 도착 알림 (Clawdbot cron)
Scheduled bus arrival alerts powered by 국토교통부 TAGO OpenAPI.
This skill is designed for users running Clawdbot Gateway + Clawdbot cron. Users register rules like:
- "평일 오전 7시, 인천 한빛초등학교, 535"
- "평일 오후 5시30분, 고양 향동초등학교, 730, 503"
Then the system sends arrival summaries to the registering user (DM) on schedule.
Note (MVP): stop resolution is done via stop name search (cityCode + keyword). GPS-based nearby lookup exists but may return 0 results depending on key/region.
Prerequisites
- A running Clawdbot Gateway (Telegram/Slack/etc. already configured)
- Clawdbot cron enabled/usable
- A data.go.kr API key for TAGO
- (setup 자동화 사용 시)
systemctl --user가 동작하는 환경 (systemd user service) - (rule_wizard에서 cron 등록까지 하려면)
clawdbotCLI
One-time setup: TAGO API key
You must set a TAGO service key in your environment (never commit or paste it into markdown).
Recommended env var:
TAGO_SERVICE_KEY
Option A (fastest): one-off test in your current shell
Good for quick manual tests; cron jobs will NOT inherit this unless the Gateway service has it.
export TAGO_SERVICE_KEY='...'
Option B (recommended): one-command setup (auto-detect systemd unit)
This is the most “set it once and forget it” flow.
Run:
python3 korea-metropolitan-bus-alerts/scripts/setup.py
If your network blocks the endpoint or TAGO returns 403 during the smoke test, you can still complete setup:
python3 korea-metropolitan-bus-alerts/scripts/setup.py --skip-smoke
It will:
- Auto-detect your Gateway systemd user service (supports custom unit names)
- Prompt for
TAGO_SERVICE_KEY(hidden input) - Save it to
~/.clawdbot/secrets/tago.env(chmod 600) - Write a systemd override to load that env file
- Restart the Gateway
- Run a small TAGO smoke test
(Advanced/manual) If you prefer shell scripts, korea-metropolitan-bus-alerts/scripts/set_tago_key.sh is still available, but setup.py is the recommended UX.
Safety notes
- Never commit
.env/tago.env. - Avoid sharing outputs of
docker compose configor similar commands that may print env values.
Quick start
A) Test TAGO connectivity (manual)
export TAGO_SERVICE_KEY='...'
python3 korea-metropolitan-bus-alerts/scripts/tago_bus_alert.py nearby-stops --lat 37.5665 --long 126.9780
B) Register an alert rule (interactive)
Tell the agent something like:
- "평일 07:00, 인천 한빛초등학교, 535 알림 등록해줘"
If the stop name is ambiguous (e.g., opposite side of road), the agent MUST ask a follow-up question to pick the correct direction/stop candidate before creating the rule.
C) List rules
- "버스 알림 목록 보여줘"
D) Delete a rule
- "버스 알림 3번 삭제해줘" (confirm before delete)
E) Test a rule (run now)
- "방금 등록한 규칙 테스트해줘" (one-time message)
Supported schedule expressions (MVP)
- 매일 HH:MM
- 평일 HH:MM
- 주말 HH:MM
(Phase 2: arbitrary cron expressions)
Cron implementation notes
- Use isolated cron jobs (
sessionTarget: isolated) +deliver: true. - Delivery is DM-only to the registering user.
- See
references/cron_recipe.mdandscripts/cron_builder.py.
Interactive registration helper (server-side)
For integration testing (and for power users), use:
scripts/rule_wizard.py register
It will:
- Ask for schedule/time/routes
- Resolve stop candidates via GPS nearby lookup (direction disambiguation)
- Generate the job JSON
- Optionally call
clawdbot cron addto register it
Data source
Single provider only (MVP):
- 정류장 조회: BusSttnInfoInqireService (15098534)
- 도착 조회: ArvlInfoInqireService (15098530)
Safety / Security
- Never write API keys/tokens/passwords into markdown files.
- For browser automation on logged-in pages: require explicit user confirmation.
- For destructive operations (cron delete): confirm before acting.
- DM-only delivery (MVP): do not broadcast to groups/channels.
Implementation notes
- Prefer scripts under
scripts/for deterministic behavior. - Put detailed API field mappings in
references/api_reference.md.
Deterministic helper script
Use scripts/tago_bus_alert.py for deterministic TAGO lookups:
nearby-stops(GPS → stop candidates)arrivals(cityCode+nodeId → arrivals; optional route filtering)