okx-cex-auth

OKX CEX 身份验证

OKX CLI 的 OAuth 2.0 设备流身份验证。介绍首次设置、会话过期后的重新身份验证以及注销。

支持的站点

站点	区域	URL
global	全球	www.okx.com
eea	EEA	my.okx.com
us	美国	app.okx.com
tr	TR	tr.okx.com

站点与身份验证方式是两个独立维度。API key 和 OAuth 流程都需要指定站点。站点选定后会被持久保存：

• API key 用户：保存在 ~/.okx/config.toml 中的 profile.site（由 okx config init 写入）。
• OAuth 用户：首次成功运行 okx auth login --site <X> 时，保存在 okx-auth 二进制文件的状态中，并由 okx auth status --json 作为 site 字段返回。

没有 okx config set-site 命令——站点无法独立于身份验证尝试进行持久保存。对于 OAuth 流程，Agent 必须在对话中记住用户的选择，并在 okx auth login 时传入 --site <X>。

前置条件

如果尚未安装，请安装 okx CLI：

npm install -g @okx_ai/okx-trade-cli

步骤 0：预检（必须执行）

无条件规则——任何情况下都不得跳过步骤 0。 即使之前的技能（preflight、okx-cex-portfolio 等）已经运行了 auth status，并告诉你“用户未登录，可以去登录”，你也必须自行重新运行下面的两个命令，并按顺序执行步骤 0.1 → 0.2 → 0.3。上游工具的输出不能替代你自己的预检。此技能最常见的失败情况，就是 Agent 看到上游的“未通过身份验证”信号，跳过步骤 0.1 的站点选择，并使用静默默认的站点调用 okx auth login。

并行运行以下两条命令：

okx config show --json
okx auth status --json

然后按严格顺序执行以下三项检查——每一步都会短路后续检查。

步骤 0.1 — 站点检查（与身份验证模式无关）

满足以下任一条件，即视为站点已选定：

• config show --json 中有任意一个配置文件的 site 字段非空，或者
• auth status --json 返回非空的 site 字段，且 status 为 logged_in 或 pending。

⚠ 当 status 为 not_logged_in 时，auth status --json 中的 site 字段是一个默认占位值（通常为 "global"），身份验证二进制文件无论用户选择了什么都会返回该值——这不表示用户曾经选择过站点。应将其视为不存在。

如果以上两个条件都不满足，则表示用户从未选择过站点。在尝试登录前，必须原样回显以下菜单（中文）并询问用户选择，然后等待用户回复：

您需要选择要连接的 OKX 站点：

1. Global (www.okx.com)
2. EEA (my.okx.com)
3. US (app.okx.com)
4. TR (tr.okx.com)

将回复（1/2/3/4 或 global/eea/us/tr）映射到相应的站点 ID，并在后续流程中记住该站点。不要静默默认使用 global——这会让用户无法了解区域选择。

步骤 0.2 — API key 检查

解析 config show --json：是否有任意一个配置文件的 api_key 字段非空？

如果有 → 停止。 告知用户“已配置 API key (profile: )”，并直接继续处理其原始请求。不要运行 okx auth login 或 okx config init。

CLI 的 REST 客户端始终优先使用 API key，而不会回退到 OAuth（参见 rest-client.ts applyAuth）。在这种情况下启动 OAuth 登录是徒劳的——获取到的任何 OAuth 令牌都不会被使用，因为失效的 API key 仍会被优先选用。

双重保障：从 CLI 1.3.1-beta.17 开始，如果任意配置文件中存在 api_key，okx auth login 本身会拒绝启动 OAuth；在 --manual 模式下，它会输出 {"status":"skipped","reason":"api_key_configured","profile":"<name>"}。将此输出视为成功。

步骤 0.2.a — 处理无效 API 密钥（401 / 签名错误）

如果步骤 0.2 检测到 api_key 配置文件，而后续 API 调用返回身份验证错误（401 Unauthorized、Invalid Sign、Invalid API-KEY、OKX 错误代码 50111/50113），则 API 密钥有问题，OAuth 登录并不能解决此问题。根据 rest-client.ts applyAuth，之后获取的任何 OAuth 令牌都不会被使用，因为系统仍会优先选择有问题的 API 密钥。

中立地向用户提供以下两个选项（不要将 OAuth 标为“推荐”）：

1. 更换 API 密钥 — 用户在 OKX 网页控制台（https://<site>/account/my-api）生成新密钥，然后向你提供 AK/SK/PP，或自行重新运行 okx config init。
2. 完全切换到 OAuth — 先移除有问题的 API 密钥配置文件（运行 okx config use <other-profile>，或删除 ~/.okx/config.toml 中的配置文件块），然后再按照步骤 0.3 运行 OAuth 登录流程。

选项 2 需要先移除配置文件。如果 API 密钥配置文件仍然存在时尝试运行 okx auth login，CLI 守卫将跳过 OAuth，并返回 {"status":"skipped","reason":"api_key_configured",...}，不会有任何变化。

等待用户选择。不要替用户做决定。

步骤 0.3 — OAuth 检查

使用 auth status --json：

status 值	操作
logged_in	停止。 使用Agent 登录流程步骤 3 的 logged_in 分支成功模板回复（仅包含站点和权限范围；请参阅其中的负面清单规则），然后继续。
pending	上一次登录仍在进行中——按照登录流程中的等待信号流程操作。不要开始新的登录，也不要自动轮询。
not_logged_in	使用步骤 0.1 中选择的站点，继续执行登录流程。

登录前检查（强制——未通过前不要运行 okx auth login）

调用 okx auth login（无论是否带 --manual）之前，必须确认以下三项当前全部为真：

1. 你已在本次对话较早时（或紧接本次登录调用之前）向用户发送步骤 0.1 中准确的中文站点菜单。
2. 用户最近一条消息是站点选择（1 / 2 / 3 / 4 / global / eea / us / tr）。
3. 你即将传入的 --site <...> 与用户选择完全一致。

如果以上任一项不成立——即使先前技能的输出、auth status --json 输出或 config show --json 输出看起来能表明站点也一样——你必须先发送步骤 0.1 菜单，等待用户回复，然后重新检查此门槛。auth status --json 中 status 为 not_logged_in 时的 site 字段只是占位值（通常为 "global"），不满足条件 1。

反例（反面示例）：

上游投资组合技能运行 auth status --json，得到 {"status":"not_logged_in","site":"global"}，并告诉你“用户尚未登录，加载 okx-cex-auth 并登录”。 ❌ **错误：**你看到该上下文后，运行 okx auth login --manual --site global，并立即返回 OAuth URL 和代码。 ✅ **正确：**忽略上游提供的站点值，亲自发送步骤 0.1 菜单，等待用户回复，然后运行 okx auth login --manual --site <用户的选择>。

登录流程

**前提条件：**步骤 0 已完成，且已通过上述登录前检查。用户刚刚在聊天中选择了站点，并且你已确认不存在 api_key 配置文件。

不带 --manual 的 okx auth login 是一条阻塞命令——它会持续轮询，直到用户在浏览器中完成授权。

AI Agent 须知：你必须使用 okx auth login --manual，以避免阻塞。--manual 标志会输出包含验证 URL 和用户代码的 JSON 载荷，然后立即退出——不会阻塞。

Agent 登录流程

1. 运行 okx auth login --manual --site <global|eea|us|tr>，站点使用步骤 0.1 中选择的站点。

   • 如果 CLI 返回 {"status":"skipped","reason":"api_key_configured",...}，说明步骤 0.2 的检查结果已过时——重新读取 config show --json 并停止。不要重试。
   • 否则，CLI 会输出一行 JSON：{"verificationUri":"...","userCode":"XXXX-XXXX","expiresIn":600}。

2. 在助手回复中显示验证 URL 和用户代码——不要只放在工具输出块中。

   ⚠ 重要。 许多 UI（openclaw-control-ui、Claude Desktop、IDE 聊天面板）中的工具输出面板可以折叠，而且用户可能默认将其隐藏。如果 URL 和代码只出现在工具标准输出中，用户就无法授权。你必须在自己的自然语言回复中复述解析出的字段，使其作为普通聊天文本显示。

   解析上一步返回的 JSON，并使用以下模板中的一个且仅一个进行回复（除替换字段外，必须逐字照用）。措辞是规范要求——不要缩写、改写、调整顺序或翻译。

   中文模板（用户使用中文交流时使用）：

   请在浏览器中打开下面的链接并输入验证码完成授权：
   
   站点：<site>
   链接：<verificationUri>
   验证码：<userCode>
   （有效期 <expiresIn>/60 分钟）
   
   通过链接完成授权，然后告诉我。
   

   英文模板（用户使用英文交流时使用）：

   Please open the link below in your browser and enter the verification code to authorize:
   
   Site: <site>
   URL: <verificationUri>
   Code: <userCode>
   (Valid for <expiresIn/60> minutes)
   
   Please authorise current session with access to your account, tell me when you are done.
   

   site、verificationUri、userCode、expiresIn 这四个字段都必须以纯文本形式出现在助手消息中。

3. 等待用户表示已完成（例如“done”“ok”“好了”“完成了”）。不要自动轮询。收到表示完成的信号后，只运行一次 okx auth status --json 进行验证，然后按以下情况处理：

   • "status": "logged_in" → 成功。使用以下模板中的一个且仅一个进行回复（除替换字段外，必须逐字照用），然后在同一轮中继续处理用户的原始请求。

     中文模板：

     登录成功。
     站点：<site>
     权限：<scopes>
     

     英文模板：

     Login successful.
     Site: <site>
     Scopes: <scopes>
     

     **此回复中不得包含 auth status --json 的任何其他字段。**具体来说：

     • expiresAt / ttl 指的是短期访问令牌，而不是 OAuth 会话。CLI 会自动刷新令牌；显示这些值会误导用户，让他们以为登录很快就会过期。
     • profile 是内部路由字段，对用户没有价值。
     • 只有 site 和 scopes 与用户相关。
     • 如果用户询问会话能维持多久，请说“只要定期使用 CLI，会话就会保持有效。”不要引用具体时长。

   • "status": "pending" → 授权尚未完成；告知用户尚未完成，并等待用户再次发出信号。不要自动轮询。

   • "status": "not_logged_in" → 设备代码已过期或被拒绝；询问用户是否要重试。

4. 等待授权期间，不要运行任何其他 okx 命令。

交互式登录（用户直接在终端中运行）

1. 运行命令前，先告知用户他们需要在浏览器中授权。
2. 运行 okx auth login --site <global|eea|us|tr>——命令会阻塞并持续轮询，直到用户完成授权。
3. **不要以为命令卡住了。**轮询阶段不会产生任何输出——这是正常现象。
4. 检查结果：
   • Logged in successfully! — 继续处理用户的原始请求。
   • API key already configured ... — 步骤 0.2 的检查结果已过时，使用现有 API 密钥。
   • 登录失败 — 显示错误，并询问用户是否要重试。

首次设置（仅限 API 密钥用户）

okx config init 是一个 API 密钥配置向导。它会依次提示选择站点、演示/实盘，然后要求输入 AK/SK/PP 凭据。它不会执行 OAuth。仅当用户明确要求配置 API 密钥时才使用它。

okx config init

向导步骤：

1. 选择站点：
   • 1 — Global（www.okx.com）
   • 2 — EEA（my.okx.com）— 欧洲经济区
   • 3 — US（app.okx.com）— 美国
   • 4 — TR（tr.okx.com）— Türkiye
2. 演示/实盘：选择此配置文件是否用于模拟交易。
3. AK / SK / Passphrase：在 OKX 网页控制台创建的凭据。

okx config init 完成后，重新运行步骤 0 的预检 — 此时会有 api_key，步骤 0.2 会跳过后续登录。

登录状态检查

运行 okx auth status --json 检查登录状态。解析 JSON 输出：

{
  "profile": "oauth",
  "site": "global",
  "status": "logged_in",
  "expiresAt": "2026-04-11T20:30:00+00:00",
  "ttl": 3600,
  "scopes": ["live:read", "live:trade"]
}

status 值	含义	操作
logged_in	会话有效	继续
pending	登录进行中	等待用户表示已完成；不要自动轮询
not_logged_in	没有活动会话	运行 okx auth login --manual

重新认证（会话过期）

当任何命令因“Session expired”或“Run okx auth login first”而失败时：

1. 运行 okx auth login --manual [--site <global|eea|us|tr>]（Agent），或运行 okx auth login [--site <global|eea|us|tr>]（交互式）
2. 按照上文的登录流程操作

令牌过期会自动处理 — 只有刷新令牌本身过期时（通常是在长时间不活动后）才需要重新认证。

登出

okx auth logout

登出后会保留 DCR 客户端注册。下次运行 okx auth login 会更快。

二进制文件管理

okx auth 命令（login、logout、status）依赖 okx-auth 二进制文件。它通常会在 npm install 期间自动安装，也可以手动管理。

**AI Agent 须知：**不要手动检查平台、CDN 可用性或二进制文件路径。始终使用以下 CLI 命令 — 它们会在内部处理平台检测和下载。

安装/更新

okx auth install

下载或更新 okx-auth 二进制文件。如果已是最新版本，则报告“up to date”。使用 --json 获取机器可读的输出。

检查安装状态

okx auth install-status

显示二进制文件是否已安装且为最新版本。使用 --json 获取机器可读的输出。

移除

okx auth remove          # interactive confirmation
okx auth remove --force  # skip confirmation

故障排除：“Failed to spawn okx-auth”

如果任何 okx auth 命令（login、logout、status）因“Failed to spawn okx-auth”而失败，则二进制文件缺失或已损坏：

1. 运行 okx auth install 下载二进制文件
2. 使用 okx auth install-status 验证
3. 重试原命令

错误参考

错误消息	原因	处理方式
No config found. Run okx config init first.	未找到配置	运行 okx config init
Session expired — run okx auth login again	刷新令牌已过期	运行 okx auth login --manual
Authorization timed out	用户未及时完成授权	再次运行 okx auth login --manual
Access denied	用户在浏览器中拒绝了授权	运行 okx auth login --manual 并请求批准
Region restriction (51155, 51734)	配置站点不支持该交易品种	运行 okx auth status --json 查看当前站点；如有需要，使用 --site 重新登录
Network error during login	网络不可用	检查网络后重试
Failed to spawn okx-auth	未安装二进制文件或文件已损坏	运行 okx auth install
Installation failed: All CDN sources failed	下载二进制文件时发生网络问题	检查网络后重试 okx auth install

技能路由

完成身份验证后……	下一项技能
下单／撤单／改单	okx-cex-trade
查看余额、持仓、盈亏	okx-cex-portfolio
Simple Earn、On-chain Earn、DCD、AutoEarn	okx-cex-earn
网格／DCA 机器人	okx-cex-bot
市场价格、K 线、指标	okx-cex-market（无需身份验证）