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.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 流程，代理必須在對話中記住使用者的選擇，並在 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。上游工具輸出不能取代您自己的預先檢查。此技能最常見的失敗模式是代理讀取了上游的「未驗證」訊號，跳過步驟 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: <name>)」，然後直接繼續處理原始請求。請勿執行 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 key（401 / 簽章錯誤）

如果步驟 0.2 偵測到 api_key 設定檔，且後續 API 呼叫回傳驗證錯誤（401 Unauthorized、Invalid Sign、Invalid API-KEY、OKX 錯誤碼 50111/50113），則 API key 已損壞 — OAuth 登入並非有效的補救措施。根據 rest-client.ts applyAuth，之後取得的任何 OAuth 權杖仍不會被使用，因為損壞的 API key 仍會被優先選取。

向使用者提供以下兩個選項，保持中立（請勿標示 OAuth 為「建議」）：

1. 更換 API key — 使用者在 OKX 網頁控制台（https://<site>/account/my-api）產生新的金鑰，並提供 AK/SK/PP 給您，或自行重新執行 okx config init。
2. 完全切換至 OAuth — 先移除損壞的 API-key 設定檔（okx config use <other-profile> 或刪除 ~/.okx/config.toml 中的設定檔區塊），然後從步驟 0.3 開始執行 OAuth 登入流程。

選項 2 需要先移除設定檔。如果您在 API key 設定檔仍然存在時嘗試 okx auth login，CLI 防護會以 {"status":"skipped","reason":"api_key_configured",...} 跳過 OAuth，且不會有任何改變。

等待使用者選擇。請勿替他們決定。

步驟 0.3 — OAuth 檢查

使用 auth status --json：

status 值	動作
logged_in	停止。 使用 代理登入程序 步驟 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 的選單，等待使用者回覆，然後重新檢查此閘道。當 status 為 not_logged_in 時，auth status --json 中的 site 欄位是佔位符（通常是 "global"），不滿足條件 1。

反例（反模式）：

上游的 portfolio 技能執行 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 <user's choice>。

登入流程

先決條件： 步驟 0 已完成且上述登入前閘道已通過。您已取得使用者剛在聊天中選擇的站點，並確認不存在 api_key 設定檔。

沒有 --manual 的 okx auth login 是阻塞式指令 — 它會輪詢直到使用者在瀏覽器中完成授權。

對 AI 代理至關重要： 您必須使用 okx auth login --manual 以避免阻塞。--manual 旗標會輸出包含驗證 URL 和使用者驗證碼的 JSON 負載，然後立即退出 — 它不會阻塞。

代理登入程序

1. 使用步驟 0.1 選擇的站點執行 okx auth login --manual --site <global|eea|us|tr>。

   • 如果 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 key。
   • 登入失敗 — 顯示錯誤並詢問是否要重試。

首次設定（僅限 API-key 使用者）

okx config init 是一個 API-key 精靈。它會提示站點，然後是模擬/實盤，然後要求 AK/SK/PP 憑證。它不會執行 OAuth。僅在使用者明確想要配置 API key 時使用。

okx config init

精靈步驟：

1. 選擇站點：
   • 1 — Global (www.okx.com)
   • 2 — EEA (my.okx.com) — 歐洲經濟區
   • 3 — US (app.okx.com) — 美國
   • 4 — TR (tr.okx.com) — 土耳其
2. 模擬 / 實盤：此設定檔是否應針對模擬交易。
3. AK / SK / 密碼短語：在 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>]（代理）或 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 代理重要： 請勿手動檢查平台、CDN 可用性或二進位檔路徑。始終使用下面的 CLI 指令 — 它們會在內部處理平台偵測和下載。

安裝 / 更新

okx auth install

下載或更新 okx-auth 二進位檔。如果已是最新，則報告「up to date」。使用 --json 取得機器可讀的輸出。

檢查安裝

okx auth install-status

顯示二進位檔是否已安裝且為最新。使用 --json 取得機器可讀的輸出。

移除

okx auth remove          # 互動式確認
okx auth remove --force  # 跳過確認

疑難排解：「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（無需驗證）