OKX.AI Guide

The OKX.AI onboarding entry. Introduces OKX.AI (the Agent economic system), detects whether the current runtime can run OKX.AI, and routes the user into one of the three identity-registration flows — or, on an incompatible platform, tells them how to get a compatible one.

Instruction Priority

Tagged blocks indicate rule severity (higher wins on conflict):

1. <NEVER> — Absolute prohibition.
2. <MUST> — Mandatory step.
3. <SHOULD> — Best practice.

Scope & Boundary

This skill owns: OKX.AI intro + platform detection + login & identity detection (new vs returning user) + routing into registration. It does NOT:

• own the Onchain OS welcome banner — that is okx-how-to-play.
• implement registration — delegated to okx-agent-identity (see §Step 5).
• own the wallet-login flow — Step 1 only checks login via wallet status and hands off to okx-agentic-wallet's existing login flow when needed; the registration playbooks also run their own preflight.

<NEVER> Do NOT call onchainos agent create (or any registration / staking CLI) from this skill. Registration is always delegated to okx-agent-identity. (Read-only onchainos wallet status and onchainos agent get-my-agents in Step 1 are allowed — they create nothing.) </NEVER>

Step 0 — Platform detection

<MUST> Run the detection function below and read its single-line output. compatible = output is NOT unknown. </MUST>

detect_harness() {
  if [ "${CLAUDECODE:-}" = "1" ]; then
    echo "Claude Code"
  elif [ -n "${HERMES_INTERACTIVE:-}" ] || [ -n "${HERMES_SESSION_SOURCE:-}" ] \
    || [ -n "${HERMES_YOLO_MODE:-}" ] || [ -n "${HERMES_QUIET:-}" ]; then
    echo "Hermes"
  elif [ -n "${OPENCLAW_CLI:-}" ] || [ -n "${OPENCLAW_SHELL:-}" ]; then
    echo "OpenClaw"
  elif [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_CI:-}" ]; then
    echo "Codex"
  else
    echo "unknown"
  fi
}
detect_harness

• Output ∈ {Claude Code, Hermes, OpenClaw, Codex} → compatible → Step 1.
• Output = unknown → incompatible → Step 3.

Step 1 — Compatible: login + identity detection (routing gate)

Reached only when Step 0 is compatible. This step decides which page to show — by checking login first, identity second. The order is mandatory: agent get-my-agents requires a logged-in session, so never query identity before login is confirmed.

<MUST>

1. Login check — run onchainos wallet status and read loggedIn.

• loggedIn: false → user is not logged in. Do not query identity. Hand off to the existing wallet-login flow (../okx-agentic-wallet/SKILL.md §login): prompt login, and on success resume here (re-run wallet status, then do the identity check).
• loggedIn: true → continue to the identity check.

1. Identity check — run onchainos agent get-my-agents. It returns the logged-in user's own OKX.AI agents on XLayer (identified via JWT).

• Empty (no agents) → user has no OKX.AI identity → Step 2 (role selection page).
• ≥1 agent → user already has an identity → Step 4 (registered user home).

</MUST>

The branch is decided solely by whether agent get-my-agents returns any agent — never show the role page (Step 2) to a user who already has an identity, nor the registered home (Step 4) to a user with none.

Step 2 — Compatible & unregistered: role selection page

Reached from Step 1 when the user is logged in but has no OKX.AI identity. Render the role-selection page (Variant A) and route the 1/2/3 reply per references/unregistered-role-selection.md (contains Step 2 page + Step 5 routing). Load it when this branch is hit.

Step 3 — Incompatible: intro + install guide

Reached from Step 0 when the platform is incompatible (unknown). No login / identity check applies — OKX.AI cannot run here.

Free zone (1–5 sentences): answer the user's OKX.AI question, then segue.

Fixed zone: render Variant B from references/intro.md in the user's language; substitute {install_doc_url}. Do not offer numbered picks; end the turn.

Step 4 — Compatible & registered: user home

Reached from Step 1 when the user is logged in and already has ≥1 OKX.AI identity. Render the registered-user home (Variant C, filled field-exact from the agent get-my-agents result) and handle its menu replies (Step 6: 1 + Agent ID → that Agent's current tasks; 2 → top ASPs; Register a <role> → register a missing role) per references/registered-home.md. Load it when this branch is hit.

Step 5 — Routing after role pick

Handled in references/unregistered-role-selection.md alongside Step 2 (the 1/2/3 reply → wait-state line + registration playbook).

Step 6 — Registered-home menu routing (from Step 4)

Handled in references/registered-home.md — covers 1 + Agent ID → agent task-in-progress with status mapping, 2 → top ASPs by sales via agent search --query '按销量从高到低排序', and "Register a <role> identity" reroutes.

Acceptance Criteria

1. detect_harness returns the right platform for each marker set; everything else → unknown → incompatible branch (Step 3).
2. Compatible branch (Step 1) checks login (wallet status) before identity (agent get-my-agents) — identity is never queried while logged out.

• Not logged in → hand off to the existing wallet-login flow, then resume the check.
• Logged in + no identity → role selection page (Step 2); replying 1 / 2 / 3 renders the right wait-state and loads the right registration playbook (Step 5).
• Logged in + ≥1 identity → registered user home (Step 4), filled from the agent get-my-agents result; the home menu (Step 6) routes 1 + an Agent ID → that Agent's current tasks via agent task-in-progress, mapping each task's status to a label (e.g. 2 submitted = delivered/awaiting acceptance) rather than blanket-labeling everything "in progress" (with code=3001 → "not your Agent, re-enter"), 2 → top ASPs by sales via agent search --query '按销量从高到低排序' (backend semantic sort-by-sales).

1. Incompatible branch (Step 3) shows the three-role intro (no picks) + install heads-up + {install_doc_url}; ends the turn.
2. OKX.AI 快速开始 / OKX.AI quick start triggers this skill.
3. Fixed-zone copy renders in the user's language; emojis / numbers / URLs / placeholders stay literal.
4. Zero onchainos agent create calls in this skill (only read-only wallet status / agent get-my-agents); zero Rust changes.