Fitbit Connector

Fitbit data connector skill for OpenClaw. Exposes compact auth/fetch/store/quality tools; OpenClaw performs all coaching reasoning.

Security Scan

The skill mostly matches its stated purpose (Fitbit data connector) but contains several inconsistencies and risky artifacts — most notably embedded backup files with what look like real OAuth tokens and personal calendar data, plus mismatches between declared and required configuration — so review and remediation are needed before use.

Purpose & Capability

The name/description and runtime instructions align with a Fitbit connector (OAuth, fetch, local SQLite cache, sync/import tooling). However the registry metadata claims no required environment variables or primary credential while SKILL.md and scripts clearly require an OAuth client and a .env; this mismatch is unexpected and reduces trust. The repo also bundles backup/token files and personal calendar caches which are not required to describe the connector capability and should not be published with the skill.

Instruction Scope

SKILL.md instructs the agent to create a Fitbit developer app, run auth bootstrap, and run many local scripts that read/write local DBs and backups — that is coherent for a connector. Concerns: SKILL.md references creating a .env and uses local paths but the declared skill metadata omitted those env requirements; it also contains an anti-pattern admonition ("Do not start by searching the workspace...") that could be trying to influence discovery behavior. The shipped file manifest includes many runtime artifacts (backups, caches, runs) containing tokens and personal data which the runtime instructions do not justify transmitting or exposing.

Install Mechanism

There is no install spec (instruction-only), which is low risk for installation mechanics. But the package contains many executable scripts and many existing backups/runs written into the bundle. Because there is no install step, those scripts will run from workspace files as-is — bundling sensitive runtime artifacts into a skill archive is risky even if not installed via a network download.

Credentials

The registry lists no required env vars, but SKILL.md and README clearly expect a .env (OAuth client id/secret and FITBIT_SCOPES). Worse: the file manifest includes multiple backups with access_token and refresh_token JSON files and caches with personal calendar events. Including long-lived tokens and personal data inside the skill bundle is disproportionate and dangerous. If those tokens are valid they should be considered compromised and rotated immediately. Required credential access is understated in metadata.

Persistence & Privilege

always:false and model invocation allowed (defaults) — no excessive privilege by manifest. The skill suggests installing a cron job and references absolute user paths (e.g., /Users/joao/.openclaw/...), which implies it expects write/read access to the user's workspace; this is plausible for a local connector but should be explicit and examined before granting persistence or adding crons.

Scan Findings in Context

[base64-block] unexpected: A base64-block injection pattern was found in SKILL.md. There is no legitimate reason for a connector README to include prompt-injection payloads; this may be noise or an accidental inclusion, but it increases risk and should be inspected and removed.

What to consider before installing

This skill appears to implement a real Fitbit connector, but the package contains sensitive artifacts and inconsistent metadata. Before installing or using it: 1) Treat any embedded refresh/access tokens as compromised — rotate/revoke them immediately if they correspond to your accounts. 2) Do not run scripts until you inspect them locally; look for hard-coded endpoints, network calls, or filesystem paths. 3) Remove any 'backups/*.json' token files and personal caches from the skill bundle and ensure the skill requires and documents the expected env vars (client id/secret, FITBIT_SCOPES, DB path) correctly. 4) If you want to use the connector, create a dedicated Fitbit developer app and keep client secrets out of the repo (.env must be local and excluded from publishing). 5) Avoid blindly installing suggested cron jobs or running pipeline scripts until you confirm they operate only on intended local paths. 6) If you already ran this skill against your real Fitbit account, rotate OAuth client credentials and account tokens now. Given these issues, do not enable the skill for autonomous/always-on use until the sensitive files and metadata mismatches are fixed.

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 <CODE> --state <STATE>

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.