okx-cex-auth

Name: okx-cex-auth
Author: okx

github.com/okxその他1975.9k 回インストール今日更新

リポジトリ

okx-cex-auth について

OAuth 2.0 デバイスフローを使った OKX CLI の認証ガイドです。初回ログイン、セッション失効後の再認証、ログアウトを扱い、OAuth 開始前にサイト選択と既存 API key を確認します。

主な機能

01OAuth デバイスフローのログイン案内
02OKX サイトと認証状態の確認
03セッション失効後の再認証対応
04ログアウトと API key 設定手順の説明

活用シーン

01OKX CLI の OAuth 初期設定
02失効したログインセッションの復旧
03既存 API key 設定の確認
04OKX CLI セッションからのログアウト

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/okx/agent-skills --skill okx-cex-auth

インストール後、Claude Code で/okx-cex-authを入力して読み込まれたか確認します。

詳細

OKX CEX 認証

OKX CLI 用の OAuth 2.0 デバイスフロー認証です。初回セットアップ、セッション有効期限切れ後の再認証、ログアウトについて説明します。

対応サイト

サイト	地域	URL
`global`	グローバル	`www.okx.com`
`eea`	EEA	`my.okx.com`
`us`	US	`app.okx.com`
`tr`	TR	`tr.okx.com`

サイトは認証方式とは別の項目です。API キーと OAuth のどちらの方法でも、サイトが必要です。一度選択したサイトは保存されます。

API キーユーザー：~/.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 を実行し、「user is not_logged_in、ログインしてください」のような結論を渡してきた場合でも、以下の 2 つのコマンドを自分で再実行し、ステップ 0.1 → 0.2 → 0.3 の順に進める必要があります。上流ツールの出力は、自分で行う事前確認の代わりにはなりません。このスキルで最もよくある失敗は、エージェントが上流からの「未認証」というシグナルを読み、ステップ 0.1 のサイト選択を省略して、暗黙にデフォルト設定されたサイトで okx auth login を実行してしまうことです。

両方を並列で実行します。

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

次に、以下の 3 つのチェックを必ずこの順序で行います。各ステップで条件に該当した場合、残りのステップには進みません。

ステップ 0.1 — サイトの確認（認証モードに依存しない）

次のいずれかに該当する場合、サイトはすでに選択されています。

config show --json に空でない site フィールドを持つプロファイルがある、または
auth status --json が空でない site フィールドを返し、かつ status が logged_in または pending である。

⚠ status が not_logged_in の場合、auth status --json の site フィールドはデフォルトのプレースホルダー（通常は "global"）であり、ユーザーの選択に関係なく認証バイナリが出力するものです。ユーザーがサイトを選択したことを意味するものではありません。このフィールドは存在しないものとして扱ってください。

上記のどちらの条件にも該当しない場合、サイトはまだ選択されていません。ログインを試みる前に、以下のメニューをそのまま表示してユーザーに選択を求め、返答を待つ必要があります。

接続する OKX サイトを選択してください：

グローバル（www.okx.com）

EEA（my.okx.com）

US（app.okx.com）

TR（tr.okx.com）

返答（1／2／3／4 または global／eea／us／tr）を対応するサイト ID に変換し、このフローが終わるまで覚えておきます。global を黙ってデフォルトに設定してはいけません。そうすると、ユーザーが地域を選択できなくなります。

ステップ 0.2 — API キーの確認

config show --json を解析し、空でない api_key フィールドを持つプロファイルがあるか確認します。

ある場合 → 停止します。 ユーザーに「API キーが設定されています（プロファイル：）」と伝え、元の依頼をそのまま進めます。okx auth login や okx config init は実行しないでください。

CLI の REST クライアントは常に API キーを OAuth より優先し、フォールバックはしません（rest-client.ts applyAuth を参照）。この状態で OAuth ログインを開始しても無駄です。API キーが引き続き最初に選択されるため、取得した OAuth トークンは使用されません。API キーに問題がある場合も同様です。

念のため：CLI 1.3.1-beta.17 以降、okx auth login 自体が、API キーを持つプロファイルがある場合に 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 キーが引き続き優先されるため使用されません。

以下の 2 つの選択肢を、中立的に（OAuth を「推奨」と表現せずに）ユーザーに提示してください。

API キーを置き換える — ユーザーが OKX のウェブコンソール（https://<site>/account/my-api）で新しいキーを生成し、AK/SK/PP をあなたに提供するか、自分で okx config init を再実行します。
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`	停止してください。エージェントのログイン手順のステップ 3 にある `logged_in` 分岐の成功テンプレートを使用して返信し（サイトとスコープのみ。除外リストのルールを参照）、その後続行します。
`pending`	前回のログインが進行中です。ログインフローのシグナル待機手順に従ってください。新しいログインを開始せず、自動ポーリングもしないでください。
`not_logged_in`	ステップ 0.1 で選択したサイトを使って、ログインフローに進みます。

ログイン前ゲート（必須 — これを満たさずに `okx auth login` を実行しないでください）

okx auth login（--manual の有無を問わず）を実行する前に、以下の3 つすべてが現時点で満たされていることを確認してください。

この会話の前の方（またはこのログイン呼び出しの直前）に、ステップ 0.1 の中国語のサイトメニューをそのままユーザーに提示した。
ユーザーの直近のメッセージがサイトの選択（1／2／3／4／global／eea／us／tr）だった。
--site <...> にその選択と完全に同じ値を渡そうとしている。

3 つの条件のうちいずれか 1 つでも満たされていない場合、以前のスキルの出力、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"} を取得して、「ユーザーは not_logged_in なので、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 エージェントに関する重要事項： ブロックを避けるため、必ず okx auth login --manual を使用してください。--manual フラグは、認証 URL とユーザーコードを含む JSON ペイロードを出力し、すぐに終了します。ブロックはしません。

エージェントのログイン手順

Step 0.1 で選択したサイトを指定して、okx auth login --manual --site <global|eea|us|tr> を実行します。
- CLI が {"status":"skipped","reason":"api_key_configured",...} を返した場合、Step 0.2 の確認結果は古くなっています。config show --json を再読み込みして、そこで停止してください。再試行しないでください。
- それ以外の場合、CLI は次のような JSON を 1 行だけ出力します：{"verificationUri":"...","userCode":"XXXX-XXXX","expiresIn":600}。
アシスタントの返信に認証 URL とユーザーコードを表示してください。ツール出力ブロック内だけに表示してはいけません。

⚠ 重大な注意。 多くの UI（openclaw-control-ui、Claude Desktop、IDE のチャットパネル）では、ツール出力パネルは折りたたみ可能で、ユーザーがデフォルトで非表示にしている場合があります。URL とコードがツールの標準出力にしか表示されないと、ユーザーは認証できません。解析したフィールドを自然な言葉で必ず自分の返信にも含め、通常のチャットテキストとして表示してください。

前の手順で返された JSON を解析し、以下のテンプレートのいずれか 1 つを使って返信してください（フィールドを置き換える部分以外はそのまま）。文言は指定どおりにしてください。省略、言い換え、順序変更、翻訳はしないでください。

中国語のテンプレート（ユーザーが中国語で会話している場合に使用）：
```
请在浏览器中打开下面的链接并输入验证码完成授权：

站点：<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.
```
4 つのフィールド（site、verificationUri、userCode、expiresIn）をすべて、アシスタントのメッセージに通常のテキストとして含めてください。
ユーザーが完了を知らせるまで待ってください（例：「done」「ok」「好了」「完成了」）。自動でポーリングしてはいけません。合図を受け取ったら、確認のために okx auth status --json を 1 回実行し、その後、次のように分岐します。
- "status": "logged_in" → 成功です。以下のテンプレートのいずれか 1 つを使って返信し（フィールドを置き換える部分以外はそのまま）、同じターンでユーザーの元のリクエストに対応してください。
  
  中国語のテンプレート：
```
登录成功。
站点：<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" → デバイスコードの有効期限が切れたか、拒否されました。再試行するかユーザーに尋ねてください。
認証を待っている間、他の okx コマンドを実行してはいけません。

対話型ログイン（ユーザーがターミナルで直接実行する場合）

実行前に、ブラウザーで認証する必要があることをユーザーに伝えてください。
okx auth login --site <global|eea|us|tr> を実行します。このコマンドはブロックし、ユーザーが認証を完了するまでポーリングします。
コマンドが停止していると判断してはいけません。 ポーリング中は出力がありませんが、これは正常です。
結果を確認してください：
- Logged in successfully! — ユーザーの元のリクエストへの対応に進みます。
- API key already configured ... — Step 0.2 の確認結果は古くなっています。既存の API キーを使用してください。
- ログインに失敗 — エラーを表示し、再試行するかユーザーに尋ねてください。

初回セットアップ（API キーユーザーのみ）

okx config init は API キーの設定ウィザードです。サイトを選択してから、デモ／ライブを選択し、その後 AK/SK/PP の認証情報を求められます。OAuth は実行しません。ユーザーが API キーの設定を明示的に希望している場合にのみ使用してください。

okx config init

ウィザードの手順：

サイトを選択：
- 1 — グローバル（www.okx.com）
- 2 — EEA（my.okx.com）— 欧州経済領域
- 3 — US（app.okx.com）— 米国
- 4 — TR（tr.okx.com）— Türkiye
デモ／ライブ：このプロファイルでシミュレーション取引を行うかどうかを選択します。
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」で失敗した場合：

okx auth login --manual [--site <global|eea|us|tr>]（エージェント）または okx auth login [--site <global|eea|us|tr>]（対話モード）を実行します
上記の同じログインフローに従います

トークンの有効期限は自動的に管理されます。再認証が必要なのは、リフレッシュトークン自体の有効期限が切れた場合のみです（通常、長期間操作がない場合に発生します）。

ログアウト

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          # interactive confirmation
okx auth remove --force  # skip confirmation

トラブルシューティング：「Failed to spawn okx-auth」

いずれかの okx auth コマンド（login、logout、status）が「Failed to spawn okx-auth」で失敗した場合、バイナリが見つからないか、破損しています。

okx auth install を実行してダウンロードします
okx auth install-status で確認します
元のコマンドを再試行します

エラーリファレンス

エラーメッセージ	原因	対処方法
`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`	ネットワークを利用できません	ネットワークを確認して再試行します
`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`
市場価格、ローソク足、インジケーター	`okx-cex-market`（認証不要）

Markdown 対応

ログインしてコメント

基本情報

作者: okx
リポジトリ: okx/agent-skills
カテゴリ: その他
インストール数: 5,915
GitHub スター: 197

問題を報告