{"skill":{"slug":"openclaw-reporter","displayName":"OpenClaw Reporter","summary":"Opt-in reporter for the OpenClaw global claw heatmap. On first use, ASKS the user for consent before registering. Heartbeat (platform + model only) is sent o...","description":"---\nname: openclaw-reporter\ndescription: |\n  Opt-in reporter for the OpenClaw global claw heatmap.\n  On first use, ASKS the user for consent before registering.\n  Heartbeat (platform + model only) is sent only after confirming prior consent\n  (i.e. ~/.openclaw/config.json exists from a previous registration).\n  Task reports are only sent when the user explicitly mentions completing a task.\n  Data collected: user-chosen claw name, OS platform, model name, generic task category.\n  Credentials: the server returns an apiKey on registration, which is stored locally\n  in ~/.openclaw/config.json and sent as a Bearer token in subsequent requests.\n  No file paths, code, tool names, or project-specific data is ever sent.\nrequirements:\n  network: true\n  writeFiles:\n    - \"~/.openclaw/config.json\"\n  binaries:\n    - claw-market\n  env:\n    - name: CLAUDE_MODEL\n      required: false\n      description: \"Current Claude model identifier. Used to report which model is active. Falls back to 'unknown' if not set.\"\n---\n\n# OpenClaw Reporter\n\nThis skill lets you participate in the OpenClaw global claw activity heatmap. It reports **minimal, non-code** activity data to visualize worldwide AI agent usage. Note: as with any HTTPS request, the server can observe your IP address.\n\n## Prerequisites\n\nThis skill requires the `claw-market` CLI tool. Install it globally:\n\n```bash\nnpm install -g @ricardweii/claw-market\n```\n\n## How It Works\n\n- **Heartbeat**: Sent once per session, but **only** if `~/.openclaw/config.json` already exists (meaning the user previously consented and registered). There are no automatic hooks — the agent checks for prior consent before sending. No `PostToolUse` or `Stop` hooks are used.\n- **Task report**: Sent **only** when the user explicitly mentions completing a task or asks for a report. The agent calls the task API directly — no automated scripts.\n- **Registration**: One-time setup requiring explicit user consent (see below).\n\n## Session Start (Consent-Gated)\n\nWhen this skill is loaded, follow these steps **in order**:\n\n1. Check if `~/.openclaw/config.json` exists:\n   ```bash\n   test -f ~/.openclaw/config.json && echo \"REGISTERED\" || echo \"NOT_REGISTERED\"\n   ```\n2. **If REGISTERED** (user previously consented): send a heartbeat:\n   ```bash\n   claw-market heartbeat 2>/dev/null || true\n   ```\n3. **If NOT_REGISTERED**: do **nothing** automatically. Only proceed with the First-Time Setup below if the user initiates registration or the agent needs to ask.\n\n## Data Disclosure\n\nThis skill sends the following data to `https://kymr.top/` (the OpenClaw Market production server; server-side source code is in this repository under `app/api/v1/`):\n\n| Data Field | Example | Purpose |\n|---|---|---|\n| Claw Name | `CoolClaw42` (user-chosen) | Your display name on the heatmap |\n| Platform | `darwin`, `linux` | OS type for heatmap stats |\n| Model | `claude-sonnet-4-6` | Model usage stats |\n| Task summary | `\"Completed a task\"` | Generic activity indicator |\n\n**Stored locally:** Registration returns an `apiKey` from the server, saved in `~/.openclaw/config.json` with `chmod 600` (owner-only access). The endpoint URL (`https://kymr.top/`) is hardcoded — not read from the config file — so a modified config cannot redirect telemetry.\n\n**Visible to the server:** Your IP address is visible on every HTTPS request (inherent to any network call). The server uses IP for approximate geolocation on the heatmap — no more precise than city-level.\n\n**Never sent:** system usernames, file paths, code snippets, project names, tool names, tool arguments, tool results, or secrets.\n\n## Configuration\n\nConfig is stored at `~/.openclaw/config.json` (permissions `600`). Managed by the `claw-market` CLI tool.\n\n## First-Time Setup (Requires User Consent)\n\nIf `~/.openclaw/config.json` does not exist, follow these steps:\n\n### Step 1: Check CLI availability\n\nFirst, verify `claw-market` is installed:\n\n```bash\nwhich claw-market || echo \"NOT_INSTALLED\"\n```\n\nIf not installed, inform the user: \"The openclaw-reporter skill requires the claw-market CLI. Install with: `npm install -g @ricardweii/claw-market`\"\n\n### Step 2: Ask for consent\n\nUse the AskUserQuestion tool:\n\n- Question: \"OpenClaw Reporter wants to register a claw name and send a heartbeat (platform + model only) to https://kymr.top/ when the skill loads. Task reports are only sent when you explicitly mention completing a task. The server will issue an API key stored locally at ~/.openclaw/config.json. No file paths, code, tool names, or project data is sent. Allow?\"\n- Options: \"Yes, register\" / \"No, skip\"\n\n**If the user selects \"No, skip\":** do NOT register and do NOT ask again in this session. Stop here.\n\n### Step 3: Ask for a claw name\n\nIf the user consented, use AskUserQuestion again:\n\n- Question: \"Pick a name for your claw on the heatmap! (1-30 chars, letters/numbers/hyphens/underscores only, e.g. CoolClaw, NightCrawler, CodeClaw)\"\n- Let the user type a custom name via the \"Other\" option (no preset options needed, but provide a few fun suggestions as options)\n- Options: \"CoolClaw\" / \"CodeClaw\" / \"NightCrawler\"\n\nUse whatever the user provides as the claw name.\n\n### Step 4: Register using CLI\n\nAfter receiving the name, validate and register:\n\n```bash\n# Validate claw name: only allow alphanumeric, hyphens, underscores (1-30 chars).\nCLAW_NAME=\"USER_CHOSEN_NAME_HERE\"\n\nif ! echo \"$CLAW_NAME\" | grep -qE '^[A-Za-z0-9_-]{1,30}$'; then\n  echo \"Error: Claw name must be 1-30 characters, alphanumeric/hyphens/underscores only.\"\n  exit 1\nfi\n\n# Register using CLI\nclaw-market register \"$CLAW_NAME\"\n```\n\n## Task Reporting (Manual Only)\n\nTask reports are **never sent automatically**. Only send a task report when the user explicitly mentions completing a task, finishing work, or asks to report activity.\n\nWhen triggered, run:\n\n```bash\n# Estimate task duration (ask user or use a default)\nDURATION_MS=60000  # Default 1 minute, adjust based on actual task time\n\nclaw-market task \"Completed a task\" --duration \"$DURATION_MS\" || echo \"Task report failed (non-blocking).\"\n```\n\n## Opt-Out / Unregister\n\nTo stop all OpenClaw reporting:\n\n```bash\nclaw-market config clear\n```\n\nAfter deletion, no heartbeats or task reports will be sent. The skill will ask for consent again if re-enabled.\n\n## Behavior Rules\n\n1. **User consent is REQUIRED** before first registration — never register silently\n2. If the user declines registration, respect the decision and do not ask again in the same session\n3. **Heartbeat is consent-gated** — only sent if `~/.openclaw/config.json` exists (proof of prior consent). There are NO automatic hooks; the agent checks for prior consent before any network call\n4. **Task reports are manual only** — only send when the user explicitly mentions completing a task or asks to report\n5. If any OpenClaw request fails, continue normally — never interrupt the user's workflow\n6. Never include identifying information in task summaries\n7. **No system-level modifications**: never write to `~/.claude/settings.json` or any file outside `~/.openclaw/`\n\n## CLI Reference\n\nThe `claw-market` CLI provides these commands:\n\n| Command | Description |\n|---------|-------------|\n| `claw-market register <name>` | Register a new claw |\n| `claw-market heartbeat` | Send a heartbeat |\n| `claw-market task <summary> -d <ms>` | Report a completed task |\n| `claw-market token <input> <output>` | Report token usage |\n| `claw-market stats` | Show your token usage statistics |\n| `claw-market config show` | Show current configuration |\n| `claw-market config path` | Show config file path |\n| `claw-market config clear` | Delete configuration (unregister) |\n\nGlobal options: `--lang <en\\|zh>`, `--json`, `--endpoint <url>`\n\n## Token Usage Reporting\n\nAgents can report their token usage to contribute to the global leaderboard.\n\n### When to Report\n\nReport token usage when:\n1. The user explicitly asks to report tokens\n2. At the end of a significant session (optional, if user has consented)\n\n### How to Get Token Usage\n\nAs an AI agent, you can track token usage from the API responses. The usage data includes:\n- `input_tokens`: Tokens in your prompts and context (including previous turns)\n- `output_tokens`: Tokens in your responses\n\nYou can estimate or track cumulative token usage throughout a session.\n\n### CLI Commands\n\n```bash\n# Report today's token usage\nclaw-market token <inputTokens> <outputTokens>\n\n# Report for a specific date\nclaw-market token <inputTokens> <outputTokens> --date YYYY-MM-DD\n\n# View your token statistics\nclaw-market stats\n```\n\n### Example\n\nIf you've used 50,000 input tokens and 12,000 output tokens today:\n```bash\nclaw-market token 50000 12000\n```\n\n### Session-End Reporting (Optional)\n\nAt the end of a session, you may offer to report token usage:\n\n1. Ask the user: \"Would you like me to report today's token usage to the OpenClaw leaderboard?\"\n2. If yes, report using the token command with your estimated usage\n3. If no, continue normally\n\n**Note:** Token reporting is always optional and requires user consent. Never report tokens without asking.\n","tags":{"latest":"1.0.13"},"stats":{"comments":0,"downloads":789,"installsAllTime":1,"installsCurrent":1,"stars":0,"versions":14},"createdAt":1773367466809,"updatedAt":1778998679098},"latestVersion":{"version":"1.0.13","createdAt":1773585655319,"changelog":"- Heartbeat is now sent only if prior user consent is confirmed (i.e. ~/.openclaw/config.json already exists from previous registration).\n- Removed automated SessionStart hook; no automatic network calls are made unless the user has previously registered.\n- First-time registration and consent process is unchanged, but heartbeats are now strictly consent-gated.\n- Task reports remain manual and opt-in; no change to task reporting procedures.\n- Documentation updated to clarify that no network activity happens without existing user consent.","license":"MIT-0"},"metadata":null,"owner":{"handle":"richardwei195","userId":"s171n1p45jpwh9wds7n9m1jrms884wnq","displayName":"richardwei195","image":"https://avatars.githubusercontent.com/u/10277079?v=4"},"moderation":null}