Fitbit Connector Skill (Tool Provider)

Use this skill when OpenClaw needs Fitbit or unified health data.

This is the canonical front door for health / Fitbit retrieval in OpenClaw. If a user asks for latest Fitbit numbers, recovery signals, readiness trends, sleep/HRV/resting-HR patterns, or recent health metrics for training interpretation, start here.

This skill is data-plane only:

• it authenticates,
• fetches Fitbit data,
• syncs/cache stores normalized metrics,
• returns compact JSON.

OpenClaw handles interpretation, decisions, and coaching language.

Canonical usage rule

For ordinary question-answering, prefer this skill first. Do not start by searching the workspace for Fitbit paths if this skill is available. Do not prefer older opinionated helper scripts over this interface.

For training questions, combine this skill with memory/training-continuity.md:

• this skill = latest health/recovery data
• memory/training-continuity.md = training state, progression rules, recent workout context

Setup

1. Create Fitbit developer app (type Personal).
2. Redirect URI: http://127.0.0.1:8787/callback.
3. Create .env from references/env.example.
4. Run auth bootstrap:
   • python3 scripts/fitbit_auth.py auth-url
   • approve in browser, copy code + returned state
   • python3 scripts/fitbit_auth.py exchange --code \x3CCODE> --state \x3CSTATE>

Primary front-door interface (recommended)

For most OpenClaw usage, call the narrow front door first:

• node ../skills/health-training-frontdoor/scripts/request.js '{"action":"latest_recovery"}'

This keeps retrieval typed and low-ambiguity.

Backend tool interface (compact JSON)

Direct backend contract/schema:

• python3 scripts/fitbit_tools.py schema
• Auth status:
  • python3 scripts/fitbit_tools.py auth-status
• Endpoint catalog (broad API surface):
  • python3 scripts/fitbit_tools.py catalog
• Capability discovery across last N days (rate-limit aware):
  • python3 scripts/fitbit_tools.py discover-capabilities --days 14 --sleep-ms 500 --stop-on-429
• Direct Fitbit endpoint fetch (generic exposure):
  • python3 scripts/fitbit_tools.py fetch-endpoint --path sleep/date/YYYY-MM-DD.json --normalize
• Fetch API day payload:
  • python3 scripts/fitbit_tools.py fetch-day --date YYYY-MM-DD
  • add --raw for full Fitbit payload
• Fetch cached date range (field-filtered):
  • python3 scripts/fitbit_tools.py fetch-range --start YYYY-MM-DD --end YYYY-MM-DD --metrics hrv_rmssd,resting_hr,sleep_minutes,data_quality
  • add --ensure-fresh to auto-sync that range before reading
• Fetch latest N cached days:
  • python3 scripts/fitbit_tools.py fetch-latest --days 5 --metrics hrv_rmssd,resting_hr,sleep_minutes,data_quality
  • add --ensure-fresh to auto-sync the last N days before reading
• Sync one day from Fitbit API to cache:
  • python3 scripts/fitbit_tools.py store-sync-day --date YYYY-MM-DD
• Sync date range from Fitbit API to cache:
  • python3 scripts/fitbit_tools.py store-sync-range --start YYYY-MM-DD --end YYYY-MM-DD
• Query sync quality flags:
  • python3 scripts/fitbit_tools.py quality-flags --days 7
• Unified DB status (Apple + Fitbit):
  • python3 scripts/fitbit_tools.py unified-status
• Unified latest daily rows with source preference:
  • python3 scripts/fitbit_tools.py unified-fetch-latest --days 14 --source best

Canonical QA patterns

Latest Fitbit / recovery snapshot

For questions like:

• "What do my latest Fitbit numbers suggest?"
• "How does recovery look today?"
• "Give me my newest HRV / sleep / resting HR"

Prefer:

• python3 scripts/fitbit_tools.py fetch-latest --days 3 --metrics hrv_rmssd,resting_hr,sleep_minutes,data_quality --ensure-fresh

Unified health snapshot

For questions that may blend Fitbit + Apple Health:

• python3 scripts/fitbit_tools.py unified-fetch-latest --days 14 --source best

Trend / confidence checks

When freshness or quality confidence matters:

• python3 scripts/fitbit_tools.py quality-flags --days 7

Training interpretation

For questions like:

• "Should I train today?"
• "How did yesterday compare to recovery?"
• "Has recovery improved since earlier this week?"

Use both:

1. this skill for current/recent health signals
2. memory/training-continuity.md for training rules, progression, and recent exercise context

Notes

• Output contract: compact JSON (machine-optimized, minimal token usage).
• Prefer narrow --metrics lists to keep token usage low.
• SQLite cache is local reliability layer; Fitbit API remains source-of-truth.
• No medical diagnosis. This skill only provides data.

Anti-patterns

If this skill is available, avoid these failure modes:

• searching the workspace first just to locate Fitbit functionality
• asking the user where the connector lives
• preferring fitbit_query.py over fitbit_tools.py for normal QA
• treating memory references as the primary source of live Fitbit data
• using orchestrator files as the first discovery surface for ordinary health questions

Legacy scripts

Older opinionated scripts remain only for backward compatibility and should be treated as non-canonical for ordinary OpenClaw reasoning:

• fitbit_query.py
• fitbit_coach_view.py

If a normal user question can be answered through fitbit_tools.py, do that instead.