Earn Hunter

SKILL.md

---
name: earn-hunter
description: "Automatically monitors OKX Flash Earn, Fixed Earn and Flexible Earn opportunities, sends push notifications, and guides subscription. 自动监控 OKX 闪赚、定期和活期赚币机会，推送通知并引导申购。Use when user says: 有闪赚通知我, 监控赚币, monitor earn, notify me about earn, 定时检查理财, 执行 earn-hunter 扫描, earn-hunter scan, 活期年化高了通知我, 监控活期."
license: MIT
metadata:
  author: okx
  version: "1.3.7"
  homepage: "https://www.okx.com"
  agent:
    requires:
      bins: ["okx"]
    install:
      - id: okx-cli
        kind: node
        package: "@okx_ai/okx-trade-cli@1.3.7"
        bins: ["okx"]
        label: "Install okx CLI (npm)"
---

# 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:
   ```bash
   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
4. 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.
5. 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](#platform-detection-active-probe--user-confirmation)
   - 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
2. 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) 其他"
3. 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"`
4. 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

| File | Scope | Content |
|---|---|---|
| `config.json` | Shared | Scan scope (flash/fixed/flexible), currencies, APY thresholds, terms, language, verboseLog |
| `platform.json` | Platform-specific | Scheduler type/interval, notification channel, TG/Lark credentials |
| `state.json` | Shared | Dedup state |

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

| User intent | Route |
|---|---|
| "有闪赚通知我" / "monitor earn" / "帮我监控赚币" / "活期年化高了通知我" | → [Activation Flow](#activation-flow) |
| "改 APY 阈值" / "只看 USDT" / "change config" / "活期加上 BTC" | → [Config Management](#config-management) |
| "申购 USDT 定期 7D" / "subscribe" / "我要买" | → [Purchase Guide](#purchase-guide) |
| "执行 earn-hunter 扫描" (cron OR interactive) | → [Scan Cycle](#scan-cycle) — run `scripts/scan.sh` and relay its output |
| "停止监控" / "暂停" / "stop" | → [Pause/Resume](#pauseresume) |
| "卸载 earn-hunter" / "uninstall" | → [Uninstall](#uninstall) |
| "测试 earn-hunter" / "smoke test" / "测试定时任务" | → [Test Mode](#test-mode) |

---

## Activation Flow

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

### Step 1 — Platform Detection & Confirmation

See [Platform Detection](#platform-detection-active-probe--user-confirmation). 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.

On OS-crontab platforms, scheduled notifications go out via direct curl; on OpenClaw they go out via cron `announce` to the conversation. Detection order (check each, report status for all):
1. Check `$TELEGRAM_BOT_TOKEN` and `$TELEGRAM_CHAT_ID` env vars:
   - Both set → TG ready
   - Token set but chat_id missing → warn: "Telegram 配置不完整（缺少 TELEGRAM_CHAT_ID），跳过 TG" → continue to next channel
   - Neither set → TG not available
2. Check `platform.notify.lark_webhook` or Lark MCP tools:
   - Webhook set and valid (starts with `https://` and contains `/hook/`) → Lark ready
   - Webhook set but format invalid (does not start with `https://` or missing `/hook/`) → warn: "Lark webhook 格式无效，跳过 Lark" → continue to next channel
   - Not configured and no Lark MCP → Lark not available

**Always ask the user to confirm notification channel — never silently default to session.** For a monitoring tool, notification is critical; defaulting to session means alerts are lost when the user is not in the conversation.

**If one or more external channels detected:**

"检测到以下推送渠道可用：
- {list of detected channels, e.g. Telegram / Lark}

你希望通知发到哪里？
1. {detected channel 1}
2. {detected channel 2, if any}
3. 仅在当前会话显示（离线收不到）"

**If no external channel detected:**

"新机会才能推送到你手上。你希望通知发到哪里？
1. Telegram — 需要提供 Bot Token 和 Chat ID（通过环境变量）
2. Lark/飞书 — 需要提供 Webhook URL
3. 仅在当前会话显示（⚠ 离线收不到通知）

推荐配置 Telegram 或 Lark，这样即使不在对话中也能收到提醒。"

- If user picks Telegram → guide setting `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` env vars
- If user picks Lark → ask for webhook URL, validate format (starts with `https://`, contains `/hook/`), write to `platform.notify.lark_webhook`
- If user picks session → write `"session"` and warn: "⚠ 离线状态下不会收到通知，建议后续配置外部渠道。"

Write confirmed channel to `platform.json` `notify.channel`.

### Step 3 — Confirm Scan Config (3-step with defaults)

Present default config and ask user to confirm or customize. Each step offers a default — user can press enter to accept.

**Step 1/3 — 扫描范围：**
"扫描范围（可多选）：
 [1] Flash Earn（闪赚）
 [2] Fixed Earn（定期赚币）
 [3] Flexible Earn（活期赚币）
 默认：全选"
- Default: all three enabled
- If user picks specific items → disable the others
- If user only picks [1] → set `config.fixed.enabled = false`, `config.flexible.enabled = false`; skip Step 2/3 and 3/3
- If user only picks [3] → set `config.flash.enabled = false`, `config.fixed.enabled = false`; go to flexible-specific config (Step 2/3 asks flexible currencies, Step 3/3 asks flexible APY threshold)

**Step 2/3 — 监控币种：**
For Fixed Earn: "定期监控币种：全部（默认，按回车）或输入指定币种（如 USDT, SOL）"
- Default: `"all"` (all currencies)
- If user specifies → set `config.currencies` to array (e.g. `["USDT", "SOL"]`)

For Flexible Earn: "活期监控币种：USDT, USDC（默认，按回车）或输入指定币种"
- Default: `["USDT", "USDC"]`
- If user specifies → set `config.flexible.currencies` to array
- Note: flexible requires per-currency API calls, so recommend keeping the list small

**Step 3/3 — APY 阈值：**
For Fixed Earn: "定期最低 APY 阈值：不限（默认，按回车）或输入百分比（如 8）"
- Default: `0` (no limit)
- If user specifies → set `config.fixed.globalMinApy` to `value / 100` (e.g. 8 → `0.08`)

For Flexible Earn: "活期最低 APY 阈值：8%（默认，按回车）或输入百分比"
- Default: `0.08` (8%)
- If user specifies → set `config.flexible.globalMinApy` to `value / 100`

Auto-detect language from conversation and write to `config.json` `notify.language`.

Write config to `~/.okx/earn-hunter/config.json`.

Display summary using `{baseDir}/templates/activation.md` template (in user's language).

### Step 4 — Smoke Test & Delivery Confirmation

**Smoke test always sends a notification, regardless of `verboseLog` setting.**

1. Run one scan cycle immediately with `verboseLog` forced on so output is always produced, even when there are no opportunities. Temporarily flip `verboseLog`, run the script, then restore it — and use `EH_TEST_NAMESPACE=1` so smoke-test dedup keys go under the `test:` prefix and don't pollute production state:
   ```bash
   jq '.verboseLog=true' ~/.okx/earn-hunter/config.json > ~/.okx/earn-hunter/config.tmp \
     && mv ~/.okx/earn-hunter/config.tmp ~/.okx/earn-hunter/config.json
   EH_TEST_NAMESPACE=1 OKX_PROFILE=live ~/.okx/earn-hunter/scan.sh
   # then restore verboseLog to the user's original value (e.g. false)
   ```
2. **If new opportunities found** → the script sends the normal notification (rendered from templates)
3. **If no opportunities found** → with `verboseLog` forced on, the script sends the brief status. Optionally append the activation confirmation message:
   "Earn Hunter 已激活，当前暂无新机会，将在下一轮自动扫描。"
   (Use `{baseDir}/templates/activation.md` as base, append the no-opportunity note)
4. TG or Lark channel → **ask:** "已向 {channel} 发送测试消息，请确认是否收到？"
5. User confirms → proceed to Step 5
6. Not received → troubleshoot (see `notify-channels.md`)
7. 5 min no response → ping once
8. Session channel → skip confirmation

**Note:** The smoke test ignores `verboseLog` setting — it always produces output to verify the full pipeline works end-to-end.

### Step 4b — Cron Environment Smoke Test (OS-crontab platforms only)

**Critical:** The user's interactive shell has a full PATH, but cron does not. Run a second smoke test simulating cron's minimal environment to verify `env.snapshot` works:

```bash
env -i HOME="$HOME" PATH=/usr/bin:/bin \
  EH_TEST_NAMESPACE=1 OKX_PROFILE=live \
  bash ~/.okx/earn-hunter/scan.sh
```

- If exit 0 → cron will work. Proceed to Step 5.
- If exit 127 / "FATAL: 'okx' not found" → `env.snapshot` is incomplete or missing. Re-run Preflight step to regenerate it. **Do NOT proceed to Step 5** — the cron job will fail silently.
- Show the user: "已验证 cron 最小环境下可正常执行。如果此步失败，说明 env.snapshot 中的工具路径有误。"

### Step 5 — Set Up Scheduler

The scheduling mechanism depends on `platform.json` `.scheduler.type`. Branch on the platform.

#### OpenClaw (`scheduler.type = "openclaw-cron"`)

On OpenClaw, scheduling is done **inside the conversation** by calling the in-session **`cron` agent tool** — never an OS command or `openclaw cron` CLI (the CLI path has permission issues in this context). Encourage the user to set it up right here in the chat: the cron job you create inherits the current session's channel, so its scan output is delivered straight back to this conversation.

Call the `cron` tool with `action: "add"` and a `job` shaped like this (read `.scheduler.interval` from `platform.json` for the frequency):

- `name`: `"earn-hunter-hourly"`
- `schedule`: `{ "kind": "every", "everyMs": 3600000 }` — derive `everyMs` from `scheduler.interval` (`"1h"` → 3600000, `"30m"` → 1800000, `"2h"` → 7200000)
- `sessionTarget`: `"isolated"` — run in an isolated session, not the main one
- `payload`: `{ "kind": "agentTurn", "message": "执行 earn-hunter 扫描", "lightContext": true }`
  - `lightContext: true` runs the turn with a lightweight bootstrap context (skips workspace bootstrap files) → lower token cost per tick.
  - **Token budget:** OpenClaw cron jobs have **no per-job tool-whitelist field** (the old `--tools exec,read,write` flag no longer exists). The scan stays cheap because it runs the `okx` CLI through `exec` and does **not depend on** the 160+ okx MCP tools — so as long as the isolated cron agent isn't configured to load the okx MCP server, only the regular tools (exec/read/write) are in play. Which tools load is governed by the agent's config, not by this job.
- `delivery`: `{ "mode": "announce" }` — pushes the turn's output back to the conversation channel that created the job.

When it fires, the isolated agent runs the prompt `"执行 earn-hunter 扫描"` → [Scan Cycle](#scan-cycle) (which runs `scripts/scan.sh` with channel `session`/stdout) → relays the result → `announce` delivers it here. Any new opportunity is therefore sent automatically.

**Do NOT** emit any shell/`openclaw cron` CLI command in the conversation — drive scheduling only through the `cron` tool.

#### OS-crontab platforms (`scheduler.type = "cron"` or `"launchagent"` — Claude Code / Hermes / Generic)

These use **OS scheduler → `scripts/scan.sh`**. The script does everything (CLI calls, filter, dedup, render, curl notifications) with **zero LLM cost**.

**Install the script** — copy the skill's `scripts/scan.sh` into the state dir so the scheduler has a stable path:

```bash
mkdir -p ~/.okx/earn-hunter
cp {baseDir}/scripts/scan.sh ~/.okx/earn-hunter/scan.sh
chmod +x ~/.okx/earn-hunter/scan.sh
```

**Set up scheduler** — try crontab first, fallback to LaunchAgent on macOS if cron daemon is not running:

```bash
# Resolve tool directories from the current shell
NODE_DIR=$(dirname "$(command -v node)")
OKX_DIR=$(dirname "$(command -v okx)")
JQ_DIR=$(dirname "$(command -v jq)")
CRON_PATH=$(printf '%s\n' "$NODE_DIR" "$OKX_DIR" "$JQ_DIR" /usr/bin /bin | awk '!seen[$0]++' | paste -sd: -)
```

**Step A: Try crontab + verify cron daemon (macOS)**

```bash
(crontab -l 2>/dev/null; echo "0 * * * * PATH=$CRON_PATH OKX_PROFILE=live ~/.okx/earn-hunter/scan.sh >> ~/.okx/earn-hunter/cron.log 2>&1") | crontab -
```

On macOS (`uname -s` == `Darwin`), immediately check if the cron daemon is running:

```bash
if [[ "$(uname -s)" == "Darwin" ]] && ! launchctl list com.vix.cron >/dev/null 2>&1; then
  # cron daemon not running — fallback to LaunchAgent
fi
```

- If cron daemon is running → done, `scheduler.type = "cron"`.
- If cron daemon is **not** running → remove the crontab entry and proceed to Step B.
- On Linux → skip the check (cron is always available), `scheduler.type = "cron"`.

**Step B: macOS LaunchAgent fallback** (`scheduler.type = "launchagent"`)

Generate `~/Library/LaunchAgents/com.okx.earn-hunter.plist` with the resolved paths:

```bash
SCAN_SCRIPT="$HOME/.okx/earn-hunter/scan.sh"
LOG_FILE="$HOME/.okx/earn-hunter/cron.log"
INTERVAL=3600  # derive from scheduler.interval: "1h"→3600, "30m"→1800, "10m"→600

cat > ~/Library/LaunchAgents/com.okx.earn-hunter.plist << PLIST
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.okx.earn-hunter</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>${SCAN_SCRIPT}</string>
    </array>
    <key>StartInterval</key>
    <integer>${INTERVAL}</integer>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>${CRON_PATH}</string>
        <key>OKX_PROFILE</key>
        <string>live</string>
        <key>HOME</key>
        <string>${HOME}</string>
    </dict>
    <key>StandardOutPath</key>
    <string>${LOG_FILE}</string>
    <key>StandardErrorPath</key>
    <string>${LOG_FILE}</string>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
PLIST

launchctl load ~/Library/LaunchAgents/com.okx.earn-hunter.plist
```

Write `scheduler.type = "launchagent"` to `platform.json`. Inform user:

"macOS cron 服务未运行，已自动切换为 LaunchAgent 调度（无需 sudo，重启自动恢复）。"

**Notes:**
- **OAuth mode** → omit `OKX_PROFILE` from the plist `EnvironmentVariables` (or set to empty).
- LaunchAgent plist paths must be absolute (no `~`). The activation flow expands `$HOME` at generation time.
- `RunAtLoad: true` means the first scan runs immediately after loading.
- The script reads `config.json` / `platform.json`, writes `state.json` / `notify.log`, and sends notifications via curl to TG Bot API or Lark Webhook itself. No agent involvement needed at tick time.
- The script exits 0 and produces **no output** when there are no new opportunities and `verboseLog=false` — this is the intended silent behavior.

**IMPORTANT: On OS-scheduler platforms, do NOT use agent-platform `/loop` / Routines** (Claude Code `/loop`, cloud Routines). These spawn LLM sessions per tick and cannot reliably push external notifications. (OpenClaw is the exception above — it uses its in-session `cron` tool with `announce` delivery by design.)

---

## Scan Cycle

**The entire Scan Cycle is implemented by `scripts/scan.sh` (pure shell + jq, zero LLM cost).** Whether triggered by OS crontab, by an OpenClaw isolated cron agent turn, or by a user in an interactive session ("执行 earn-hunter 扫描"), the cycle is the **same**: run the script and relay its output. Do NOT re-implement the scan steps in natural language — the script is the single source of truth.

**OpenClaw isolated cron turn:** the job's prompt routes here. Run `scripts/scan.sh` (with `platform.json` `notify.channel = "session"`, the script prints any notification to stdout); relay that stdout as the turn's response. The cron job's `announce` delivery then pushes it to the conversation channel. Do not curl TG/Lark from this turn — delivery is handled by `announce`.

### How the agent runs a scan (interactive trigger)

```bash
# Profile: pass OKX_PROFILE only in API Key mode (omit for OAuth mode).
OKX_PROFILE=live ~/.okx/earn-hunter/scan.sh
```

Then **relay the script's stdout verbatim** to the user:
- If the script prints a notification (Flash / Fixed / mixed / verbose status), show it.
- If the script prints **nothing** (silent exit 0, the no-new-opportunity + `verboseLog=false` case), tell the user "本轮扫描完成，无新机会" — do NOT fabricate a "scan complete" message into a channel; the silence is intentional.

### What the script does (see `references/scan-logic.md` for the spec it implements)

1. Reads `~/.okx/earn-hunter/config.json`
2. Runs scan commands (based on `flash.enabled` / `fixed.enabled` / `flexible.enabled`):
   - Flash: `okx [--profile live] earn flash-earn projects --status 0,100 --json`
   - Fixed: `okx [--profile live] earn savings fixed-products --json` (auto-fallback to `rate-history` + `fixedOffers` on CLI <1.3.3)
   - Flexible: for each currency in `flexible.currencies`, `okx [--profile live] earn savings rate-history --ccy <ccy> --limit 1 --json`
3. Filters (two-layer APY threshold, terms filter, currency filter; flexible uses threshold-crossing model)
4. Dedups against `~/.okx/earn-hunter/state.json` (`state.flash["<id>:<status>"]`, `state.fixed["<ccy>:<term>:<rate>"]`, `state.flexible["<ccy>"]`)
5. If new opportunities → renders the matching template (flash / fixed / flexible / mixed) and sends via the detected channel (TG → Lark → session), logging to `notify.log`
6. Updates `state.json` (write new keys; flash ID-level diff cleanup; fixed key-level diff cleanup; flexible threshold-crossing diff cleanup; 7-day TTL; failure counter)
7. If no new opportunities: `verboseLog=true` → brief status; `verboseLog=false` → **silent exit 0, no output, nothing sent**
8. Error handling: consecutive-failure counter (alert at 3, then reset); 401/session-expired → credential alert + stop

**Channel routing inside the script:** detection order TG (`$TELEGRAM_BOT_TOKEN`+`$TELEGRAM_CHAT_ID`) → Lark (`platform.json` `.notify.lark_webhook`) → session (stdout). A `notify.channel` of `telegram`/`lark`/`session` in `platform.json` forces that channel.

**Auth / profile:** the script never reads or prints credentials. It delegates all auth to the `okx` CLI (which reads `~/.okx/config.toml`). Profile is injected only via the `OKX_PROFILE` env var.

**Flexible Earn dedup model:** Unlike Flash/Fixed which dedup by specific opportunity, Flexible uses a **threshold-crossing** model — key is just `<ccy>`. Notifies once when APY crosses above threshold; stays silent while it remains above; resets when APY drops below threshold (diff cleanup removes the key). This avoids frequent notifications from rate fluctuations.

---

## Purchase Guide

When user wants to subscribe to a Fixed Earn product after receiving a notification.

Read `{baseDir}/references/purchase-guide.md` for the complete flow.

Summary:

1. Parallel balance check (funding + trading + flexible earn)
2. Compare fixed APR vs flexible lendingRate
3. Calculate recommended amount: `min(idle + movable_simple_earn, lendQuota)`
4. Present recommendation with comparison hint
5. User confirms → **re-check offer availability** (soldOut guard) → hand off to `okx-cex-earn`

Edge cases covered in purchase-guide.md:
- Balance < minLend → show deficit
- Amount > lendQuota → auto-cap with notice
- Redeem succeeded but subscribe failed → warn user, funds are in funding account
- Offer sold out between notification and subscription → inform user

**Important:** earn-hunter does NOT execute write operations directly. It transfers control to `okx-cex-earn`.

---

## Config Management

Read `{baseDir}/references/config-reference.md` for field definitions and natural language examples.

When user wants to change settings:
1. Parse intent → map to config field (see `config-reference.md` for field mapping)
2. Read the target JSON file (`config.json` or `platform.json`) → modify the field → write back
3. Read the updated file → confirm the change to user

**Exception:** TG credentials cannot be changed via natural language. Tell user to set environment variables directly.

---

## Pause/Resume

Branch on `platform.json` `.scheduler.type`:

**OpenClaw (`openclaw-cron`)** — manage via the in-session `cron` tool (no CLI):
- **Pause:** call `cron` with `action: "update"`, targeting the `earn-hunter-hourly` job, patch `{ "enabled": false }` (or `action: "remove"` to delete it).
- **Resume:** `action: "update"` with `{ "enabled": true }` (or re-create as in Activation Step 5).
- Use `action: "list"` to find the job id.

**OS-crontab platforms (`cron`):**
- **Pause:** `crontab -l | grep -v 'earn-hunter' | crontab -`
- **Resume:** Re-add the crontab entry (same as Activation Step 5).

**macOS LaunchAgent (`launchagent`):**
- **Pause:** `launchctl unload ~/Library/LaunchAgents/com.okx.earn-hunter.plist`
- **Resume:** `launchctl load ~/Library/LaunchAgents/com.okx.earn-hunter.plist`

Config and state are preserved — resuming picks up where it left off.

---

## Uninstall

When user says "卸载" / "uninstall":
1. Stop the scheduler (same as Pause). For LaunchAgent, also remove the plist:
   `launchctl unload ~/Library/LaunchAgents/com.okx.earn-hunter.plist && rm -f ~/Library/LaunchAgents/com.okx.earn-hunter.plist`
2. Ask: "是否保留配置和历史数据？"
   - Yes → only remove scheduler
   - No → also remove `~/.okx/earn-hunter/` directory

---

## Test Mode

Trigger phrases: "测试 earn-hunter" / "earn-hunter smoke test" / "测试定时任务触发"

Behavior — run the script with the Test Mode hooks (no separate logic needed):

```bash
# Force verbose so output is always produced; write dedup keys under test: prefix.
EH_TEST_NAMESPACE=1 OKX_PROFILE=live ~/.okx/earn-hunter/scan.sh   # with config.verboseLog temporarily set to true
```

1. **Execute a full Scan Cycle** — the script runs the same scan, but `EH_TEST_NAMESPACE=1` isolates state writes
2. **Force-send notification** — temporarily set `config.verboseLog=true` so the script always sends output regardless of whether opportunities are found (restore afterwards)
3. **Dedup writes to test namespace** — `EH_TEST_NAMESPACE=1` prefixes dedup keys with `test:` (e.g. `test:flash:12345:100`); these keys are immune to diff cleanup (only TTL removes them), so test runs do not pollute production state
4. **Output diagnostics** after scan completes:
   - okx auth status (logged in / expired / not configured)
   - Scan command results (flash project count + fixed product count + flexible rate count)
   - Post-filter results (how many passed filters per type)
   - Notification channel status (which channel is configured, send result)
   - Scheduler status (OS-crontab platforms: crontab entry exists? / OpenClaw: `cron` tool `action: "list"` shows the `earn-hunter-hourly` job?)
   - Last 5 lines of `~/.okx/earn-hunter/notify.log`
5. **Completion message:** "测试完成。test: 前缀的 state 不影响正式去重，正式扫描不受影响。"

---

## Error Handling

Read `{baseDir}/templates/error-alert.md` for exact alert message templates.

| Error | Action |
|---|---|
| `okx` 401 / "Session expired" | Stop scan. Send alert (凭证失效 template). Load `okx-cex-auth` if interactive. |
| Network error / timeout | Retry once silently. If still fails, skip this cycle. |
| 3 consecutive scan failures | Send alert (连续失败 template). Counter stored in `state.consecutive_failures`, reset after alert. |
| `state.json` corrupted | Reset by writing `{"flash":{},"fixed":{},"consecutive_failures":0,"last_error":""}`. May cause one round of duplicate notifications. |
| Notification send fails | Log to `notify.log`, continue scan. Dedup key NOT added (next cycle retries). |
| `config.json` missing at runtime | Send alert: "earn-hunter 未配置，请运行首次激活流程。" |
| Dual-client suspected (user mentions both platforms) | Warn: "建议仅在一个客户端运行 earn-hunter，避免重复通知。" |
| `verboseLog = true` + no hits | Send brief status (not silent). |

---

## i18n

- **All notifications rendered in user's language** (detected at activation, stored in `config.notify.language`)
- **Locked terms (never translate):** Flash Earn, Fixed Earn, Simple Earn, DCD, APY, APR, OKX, earn-hunter, Telegram, project names, currency codes (USDT, BTC, etc.)
- **Fallback:** If LLM rendering fails, send Chinese template + append `(translation unavailable, sent in zh-CN)`

---

## Global Notes

- **Security:** Never accept credentials in chat. TG token only via env vars. Guide users to `okx config init` for OKX auth.
- **Output:** Use `--json` for all okx commands. Render results as markdown tables.
- **Logging:** All notification send results logged to `~/.okx/earn-hunter/notify.log`.
- **Scope:** Covers Flash Earn, Simple Earn Fixed, and Simple Earn Flexible (活期). DCD, on-chain, auto-earn are out of scope.
- **Mode:** Live trading only. `config.simulatedTrading` is always `false`.

## Defensive Design Principles

These constraints apply to all changes to earn-hunter:

1. **cron PATH ≠ user shell PATH.** Any cron-triggered script must resolve tool paths independently — never assume cron inherits the user's login PATH. The script uses `env.snapshot` + `resolve_bin` fallback.
2. **Sanity check first.** Before running any CLI command, verify the binary exists. Missing tool → immediate exit with clear error, not silent failure.
3. **Never swallow stderr.** Use `2>&1` (capture into variable) instead of `2>/dev/null` for CLI calls. Otherwise error messages vanish and `last_error` is empty.
4. **Smoke test must simulate production.** Activation smoke test runs twice: once in user shell (verify credentials/network), once in minimal `env -i PATH=/usr/bin:/bin` (verify cron can run). Don't pass Step 5 if cron smoke fails.
5. **Alert templates must handle empty fields.** If `last_error` is empty string, append "check `~/.okx/earn-hunter/cron.log`; empty error usually means PATH issue" guidance.
6. **Tool paths use snapshot + fallback, not global PATH.** `env.snapshot` written at activation with exact paths; `resolve_bin` tries snapshot → `command -v` → hardcoded common paths. Survives `nvm switch` / Homebrew upgrades.