Earn Hunter

Earn Hunter

Automated monitor for OKX Flash Earn, Fixed Earn, and Flexible Earn (Simple Earn) opportunities.

`{baseDir}` = the directory containing this SKILL.md file. All relative paths (references/, templates/, config/) are resolved from here.

Preflight

1. Verify okx CLI installed: which okx. If missing, install via npm install -g @okx_ai/okx-trade-cli. On OpenClaw, also verify the in-session cron tool is available in the agent tool list (used for scheduling — not the openclaw CLI).
2. Check optional dependent skills: ``bash okx skill list --json `` Optional skills (not required for scanning/notifications):

• okx-cex-earn — needed for purchase guide (subscription execution)
• okx-cex-auth — needed for authentication recovery

If either is missing, attempt to install but do not block if installation fails:

   okx skill add okx-cex-earn
   okx skill add okx-cex-auth

• Install succeeds → continue
• Install fails (network error, marketplace unavailable, etc.) → warn and continue: "⚠ {skill_name} 安装失败，扫描和通知功能不受影响。申购引导和认证恢复需要该 skill，后续可手动安装。"
• Preflight continues regardless of skill installation result

1. Auth mode detection — run both, first match wins:

• okx config show --json → has non-empty api_key field → API Key mode. Add --profile live to all commands.
• No API key + okx auth status --json → "status":"logged_in" → OAuth mode. No --profile flag needed.
• Neither → stop. Load okx-cex-auth skill and follow login steps.

1. Init config and state:

• If ~/.okx/earn-hunter/ directory does not exist → mkdir -p ~/.okx/earn-hunter
• If ~/.okx/earn-hunter/config.json does not exist → copy {baseDir}/config/default.json to it
• If ~/.okx/earn-hunter/state.json does not exist → write {"flash":{},"fixed":{},"flexible":{},"consecutive_failures":0,"last_error":""}
• If ~/.okx/earn-hunter/platform.json does not exist → run Platform Detection
• Always (re)install the scan script: cp {baseDir}/scripts/scan.sh ~/.okx/earn-hunter/scan.sh && chmod +x ~/.okx/earn-hunter/scan.sh. This is the script cron and interactive scans both call.
• Write ~/.okx/earn-hunter/env.snapshot with resolved tool paths (cron cannot rely on the user's login PATH): ``bash cat > ~/.okx/earn-hunter/env.snapshot << SNAP # auto-generated by earn-hunter activation — $(date -Iseconds) OKX_BIN=$(command -v okx) NODE_BIN=$(command -v node) JQ_BIN=$(command -v jq) ACTIVATION_PATH=$PATH SNAP ` The scan script sources this file to resolve tool paths even under cron's minimal PATH=/usr/bin:/bin`.

Config/state/platform JSON read-write done by the agent is only for activation/config management. The recurring scan itself is performed entirely by `scripts/scan.sh` (shell + jq) — jq is required for scanning. Verify with which jq; if missing, install (brew install jq / apt-get install jq).

Platform & Channel Detection

Three independent dimensions: platform (where the agent runs), scheduler (what triggers scans), notification channel (where alerts go).

Platform Detection (active probe + user confirmation)

First run (no `platform.json` exists):

1. Probe environment clues:

• OPENCLAW_HOME env var exists? → hint: OpenClaw
• Agent tool list contains cron / delivery tools? → hint: OpenClaw
• HERMES_HOME env var exists or which hermes succeeds? → hint: Hermes Agent
• Running inside Claude Code session? → hint: Claude Code
• None of the above matched → hint: Generic

1. Present detection result and ask user to confirm:

• "检测到你正在使用 {detected_platform}，是否正确？"
• User confirms → proceed
• User says no → ask: "你使用的是哪个平台？1) OpenClaw 2) Claude Code 3) Hermes Agent 4) 其他"

1. Initialize platform config:

• OpenClaw / Claude Code → copy {baseDir}/config/<confirmed_platform>.default.json to ~/.okx/earn-hunter/platform.json
• Hermes Agent → copy {baseDir}/config/claude-code.default.json as base, set .platform to "hermes", .scheduler.type to "cron"
• Generic → copy {baseDir}/config/claude-code.default.json as base, set .platform to "generic", .scheduler.type to "manual"

1. Result written to ~/.okx/earn-hunter/platform.json, subsequent runs skip detection.

Subsequent runs (platform.json exists): Read ~/.okx/earn-hunter/platform.json and extract the .platform field (returns "openclaw", "claude-code", "hermes", or "generic").

No scheduler available on detected platform (only applies to platforms that should have one but don't) → error: "当前客户端不支持定时任务，请升级到最新版本。" Generic platform → no automatic scheduler. Inform: "当前平台不支持自动调度，你可以手动说'执行 earn-hunter 扫描'来触发。"

Configuration Files

Core config (config.json) is identical across platforms. Platform config (platform.json) differs — the scheduler.type field determines how scans are triggered:

OpenClaw (`openclaw.default.json`):

• scheduler.type = "openclaw-cron" — scheduled via the in-session `cron` agent tool (no OS crontab, no CLI commands). The job runs as an isolated, light-context agent turn and delivers its output back to the conversation channel via cron `announce` delivery. notify.channel defaults to "session" so the scan prints to stdout for announce to push (avoids double-send).

Claude Code / Hermes / Generic (`claude-code.default.json`):

• scheduler.type = "cron" — scheduled via OS crontab → `scripts/scan.sh` (zero LLM token cost), notification via TG / Lark curl from the script itself.

Notification Channels (independent of platform)

Detect in priority order (PRD requirement: TG first):

1. Telegram — $TELEGRAM_BOT_TOKEN and $TELEGRAM_CHAT_ID both set → TG ready
2. Lark — platform.notify.lark_webhook non-empty → Lark ready
3. Session — fallback, only works in interactive mode

TG and Lark are standalone push channels — they work regardless of whether the agent client is open. On OS-crontab platforms, scheduled scans send notifications via direct curl. On OpenClaw, the scheduled scan runs in an isolated cron agent turn and delivers via cron `announce` to the conversation channel (channel = "session"); TG/Lark curl is not used unless the user explicitly switches the channel.

Skill Routing

Activation Flow

First-time setup. Only confirm platform — everything else uses smart defaults.

Step 1 — Platform Detection & Confirmation

See Platform Detection. Probe environment → ask user to confirm → write platform.json.

Step 2 — Detect Notification Channel & Confirm

Must actively check available channels before proceeding. Do NOT silently fall back to session.