okx-how-to-play

Onchain OS — 如何开始（入口路由器）

面向首次使用者或“不知道该做什么”的入口。在 ≤ 3 轮对话内，引导用户从空白提示词进入具体的 DApp 工作流。

指令优先级

带标签的区块表示规则的严重程度（冲突时优先级高者胜出）：

1. <NEVER> — 绝对禁止。
2. <MUST> — 必须执行的步骤。跳过会导致流程中断。
3. <SHOULD> — 最佳实践。

预检

> 阅读 `../okx-agentic-wallet/_shared/preflight.md`。如果该文件不存在，则改为阅读 `_shared/preflight.md`。

撰写模式 — 自由区与固定区

此流程中的大多数面向用户的文案都分为两部分：

• 自由区 — Agent 先用 1–5 句话，结合上下文回答用户实际提出的问题或回应用户的确认。不使用固定文案。避免让用户感觉像是在照本宣科。
• 固定区 — 标准英文模板块（欢迎横幅、登录选项、API Key 登录提示）。运行时：
  • 将所有自然语言文案转换为用户使用的语言。
  • 文案中的引述回复词（例如 "login"）必须随句子一起翻译。 在其他内容已翻译为中文、日语等语言的文案中保留英文引述词，是翻译错误——引号不会让该词变成字面触发词。
  • 保持以下内容不变：表情符号、{placeholders}、1–N、代码标识符 / 命令 / URL、Markdown 结构。

适用于：欢迎横幅、登录方式选择和 API Key 登录第 1 步提示。

**必须添加过渡句。** 自由区结尾必须用半句过渡语（例如“我来展示一下菜单”/“从这里开始 ↓”），绝不能以句号结束后直接接上无关的固定区内容。输出前请自检：将自由区结尾与固定区首行连起来读；如果感觉像是两条不相关的消息被拼在一起，就重写自由区结尾。

状态检查

在显示任何登录或欢迎文案**之前**运行 `onchainos wallet status`。根据 `loggedIn` 字段进行分支判断。

onchainos wallet status

• loggedIn: false → 显示未登录欢迎横幅。
• loggedIn: true → 显示已登录欢迎横幅。

---

欢迎横幅

根据 `references/welcome.md` 显示横幅 — 其中涵盖占位符（来自 `wallet balance` 的 `{evm_address}` / `{solana_address}` / `{balance}`；来自 `wallet geoblock` 的地理封锁变体）、模板和选项路由（第 4 步）。变体 A = 4 个选项（允许 Polymarket）；变体 B = 3 个选项（Polymarket 被地理封锁）。必须严格按照当前显示的菜单解释编号选项（依据 welcome.md §4 中的数字路由约定）。绝不能编造地址或余额。如果 `loggedIn: true`，但 `wallet balance` 失败（会话过期——刷新令牌已失效），则根据 welcome.md §2.2 提示用户重新登录，而不是显示不完整的横幅。

---

登录方式选择

当用户要求登录时进入此处（无论是回复未登录横幅中的 login，还是在未登录状态下从欢迎菜单中选择工作流选项）。

自由区（1–5 句话，使用 Agent 自己的措辞）： 回答用户实际提出的问题 / 确认。如果用户是通过选择工作流选项进入此处，简要说明登录即可启用该工作流。然后自然过渡到下方的固定区选项。

固定区 — 使用用户的语言显示以下模板：

Welcome to Agentic Wallet — the Onchain OS wallet built for agents. Pick a login method:

1. 📧 Email (recommended — 30 seconds)
2. 🔑 API Key (already an OKX developer? Fastest path)

Reply 1 or 2 ↓

如果用户回复 1 或“邮箱” → 邮箱登录。 如果用户回复 2 或“API Key” → API Key 登录。

邮箱登录

由 okx-agentic-wallet 技能的 Authentication 部分处理。步骤：

1. 询问邮箱 → onchainos wallet login <email> --locale <locale>
2. 询问 OTP 验证码 → onchainos wallet verify <code>
3. 成功后 → 下方的登录后路由。

API Key 登录

总共两步：（1）一次性提示，让用户知道要设置哪些环境变量以及在哪里获取它们；（2）用户确认后，运行一次 onchainos wallet login。

步骤 1 — 提醒（一次性，固定区域）

**自由区域（1–5 句话）：**如果用户还有其他问题，先回答。然后自然地过渡到提醒。

固定区域 — 使用用户的语言呈现以下模板：

You'll need to set three API Key environment variables before logging in:

1. `OKX_API_KEY` — API Key
2. `OKX_SECRET_KEY` — Secret Key
3. `OKX_PASSPHRASE` — Passphrase

You can find these at https://web3.okx.com/onchainos/dev-portal.

**Attention ⚠️:** Do not paste credentials into the chat — follow the dev-portal instructions and set them locally.

然后停止并等待用户确认已准备就绪（例如“完成 / 好 / 准备好了”）。

步骤 2 — 登录

用户确认后，运行：

onchainos wallet login

成功后 → 按下方的登录后路由处理。登录失败时，显示错误并请用户检查其环境变量（不要重新显示提醒——用户已经看过了）。

- 不要在聊天中接受 API Key / Secret / Passphrase。如果用户在聊天中粘贴了凭据：不要复述，也不要使用这些值；请其删除消息、更换密钥，并改为在本地设置环境变量。 - 不要指导用户生成密钥、打开 URL、创建 `.env` 文件、编辑 `.gitignore` 或执行任何其他多步设置。提醒仅显示一次——用户自行处理本地设置。 - 不要要求用户将浏览器 URL 或任何回调内容粘贴回 CLI。dev-portal 为只读。

登录后路由

登录成功后：

• 如果用户在未登录时选择了 OKX.AI 选项（回复 1）：自动加载 okx-ai-guide 并按其指引操作。不要重新呈现欢迎横幅。
• 如果用户在未登录时选择了 每日简报选项（变体 A 中选项 4 / 变体 B 中选项 3）：自动加载 ~/.onchainos/workflows/daily-brief.md 并按其指引操作。不要重新呈现欢迎横幅。
• 如果用户在未登录时选择了其他任何工作流选项：自动加载对应的工作流文件（~/.onchainos/workflows/<file>.md）并按其指引操作。不要重新呈现欢迎横幅。
• 如果用户回复未登录横幅中的 login（或同义表达）：呈现已登录欢迎横幅，以便用户查看其地址和余额。

---

自由输入回退

如果用户输入的内容不是编号选项或 login，请先在自由区域回答，然后路由到匹配的技能 / 工作流：

意图	路由到
抢购 meme 币 / pump.fun / 新项目发行	okx-dex-trenches
跟踪聪明钱 / KOL / 巨鲸	okx-dex-signal（或加载 smart-money-signals.md）
收益 / 赚取 / 质押 / DeFi	okx-defi-invest
登录（自由输入，而非回复横幅）	此技能的登录方式选择
指定 DApp + 操作动词（Aave / Hyperliquid / 等）	okx-dapp-discovery

---

验收标准

1. 横幅变体与认证状态匹配 — loggedIn: false 时呈现未登录变体（不含地址）；loggedIn: true 时呈现已登录变体（含地址和余额）。
2. 无需登录即可加载技能选项 — 即使未登录，也要加载 Polymarket（变体 A 中选项 2）和 USDC APY（变体 A 中选项 3 / 变体 B 中选项 2）；每个已加载的技能自行处理认证。
3. OKX.AI（回复 1）和每日简报（变体 A 中选项 4 / 变体 B 中选项 3）需要先登录 — 未登录时，先通过登录方式选择进行路由，然后自动恢复到所选目标（okx-ai-guide 或 daily-brief.md），不要重新呈现欢迎横幅。聪明钱 / 新代币意图不再作为编号选项，但仍可通过自由输入回退表（okx-dex-signal / okx-dex-trenches）触达。
4. 轮次数限制 — 新用户端到端不超过 3 轮；回访用户选择工作流并登录不超过 2 轮。
5. 免责声明位置 — 免责声明必须是每个已呈现横幅的最后一部分（两个变体、两种认证状态均适用）。
6. 会话过期回退 — 当 wallet status 返回 loggedIn: true，但 wallet balance 失败（例如刷新令牌过期）或缺少地址 / 余额字段时，流程应提示重新登录（路由到登录方式选择），而不是呈现不完整或伪造的已登录横幅；重新登录后呈现已登录横幅。