OKX CEX 投资组合与账户 CLI 是做什么的?
查询 OKX 交易所的账户余额、持仓、盈亏、账单、手续费及资金划转。需要 API 凭证。
先决条件
- 安装
okxCLI:npm install -g @okx_ai/okx-trade-cli - 配置凭证:
或设置环境变量:okx config initexport OKX_API_KEY=your_key export OKX_SECRET_KEY=your_secret export OKX_PASSPHRASE=your_passphrase - 使用模拟盘模式测试:
okx --profile demo account balance
凭证与配置文件检查
在任何需要认证的命令之前执行此检查。
步骤 A — 验证凭证
okx config show # 验证配置状态(输出已脱敏)
- 如果命令返回错误或显示未配置:停止所有操作,引导用户运行
okx config init,等待设置完成后重试。 - 如果凭证已配置:进入步骤 B。
步骤 B — 确认交易模式(必需)
所有需要认证的命令都必须使用 --profile 参数。切勿隐式添加 profile。
| 值 | 模式 | 资金 |
|---|---|---|
live | 实盘 | 真实资金 |
demo | 模拟盘 | 模拟资金 |
决策规则:
- 当前消息意图明确(例如,“real”/“实盘”/“live” →
live;“test”/“模拟”/“demo” →demo)→ 使用该 profile 并告知用户:"使用 --profile live (实盘)"或"使用 --profile demo (模拟盘)" - 当前消息未明确声明 → 检查对话上下文中的历史 profile:
- 找到 → 使用它,告知用户:
"沿用之前的 --profile live (实盘)" - 未找到 → 询问:
"实盘还是模拟盘?"— 等待用户回答后再继续
- 找到 → 使用它,告知用户:
处理 401 身份验证错误
如果任何命令返回 401 / 身份验证错误:
- 立即停止 — 不要重试相同的命令
- 告知用户:“身份验证失败 (401)。您的 API 凭证可能无效或已过期。”
- 引导用户使用本地编辑器直接编辑文件来更新凭证:
在相应的 profile 下更新~/.okx/config.tomlapi_key、secret_key、passphrase字段。 不要将新凭证粘贴到聊天中。 - 用户确认文件已更新后,运行
okx config show进行验证(输出已脱敏) - 只有验证通过后,才能重试原始操作
模拟盘与实盘模式
Profile 是控制实盘/模拟盘切换的唯一机制 — 只有两个选项:
--profile | 模式 | 资金 |
|---|---|---|
live | 实盘 | 真实资金 |
demo | 模拟盘 | 模拟资金 |
okx --profile live account balance # 实盘
okx --profile demo account balance # 模拟盘 (模拟余额)
规则:
- 读取命令(余额、持仓、账单等):始终说明使用了哪个 profile
- 写入命令(
transfer、set-position-mode):执行前必须确认 profile(参见“凭证与配置文件检查”步骤 B);尤其是划转 — 错误的 profile 意味着错误的账户 - 每次执行命令后的响应都必须附加
[profile: live]或[profile: demo] - 不要使用
--demo标志 — 改为使用--profile
技能路由
- 市场数据(价格、图表、深度、资金费率) → 使用
okx-cex-market - 账户余额、盈亏、持仓、手续费、划转 → 使用
okx-cex-portfolio(本技能) - 常规现货/合约/期货/策略委托 → 使用
okx-cex-trade - 网格和 DCA 交易机器人 → 使用
okx-cex-bot
快速入门
# 交易账户余额(所有余额 > 0 的币种)
okx account balance
# 仅查询 USDT 余额
okx account balance USDT
# 资金账户余额
okx account asset-balance
# 所有当前持仓
okx account positions
# 历史平仓记录及已实现盈亏
okx account positions-history
# 最近账户账单(最近 100 条)
okx account bills
# 我的交易手续费等级
okx account fees --instType SPOT
# 从资金账户 (18) 划转 100 USDT 到交易账户 (6)
okx account transfer --ccy USDT --amt 100 --from 18 --to 6
命令索引
读取命令
| # | 命令 | 类型 | 描述 |
|---|---|---|---|
| 1 | okx account balance [ccy] | 读取 | 交易账户权益、可用、冻结 |
| 2 | okx account asset-balance [ccy] | 读取 | 资金账户余额 |
| 3 | okx account positions | 读取 | 当前合约/永续持仓 |
| 4 | okx account positions-history | 读取 | 历史平仓记录 + 已实现盈亏 |
| 5 | okx account bills | 读取 | 账户账本(充值、提现、交易) |
| 6 | okx account fees --instType <type> | 读取 | 我的交易手续费等级(maker/taker) |
| 7 | okx account config | 读取 | 账户等级、持仓模式、UID |
| 8 | okx account max-size --instId <id> --tdMode <mode> | 读取 | 当前价格下的最大买入/卖出数量 |
| 9 | okx account max-avail-size --instId <id> --tdMode <mode> | 读取 | 下一笔订单的可用数量 |
| 10 | okx account max-withdrawal [ccy] | 读取 | 每种币种的最大可提现金额 |
写入命令
| # | 命令 | 类型 | 描述 |
|---|---|---|---|
| 11 | okx account set-position-mode <mode> | 写入 | 切换净头寸/对冲持仓模式 |
| 12 | okx account transfer | 写入 | 在账户之间划转资金 |
跨技能工作流
交易前余额检查
用户:“我想买入 0.1 BTC — 我是否有足够的 USDT?”
1. okx-cex-portfolio okx account balance USDT → 检查可用权益
2. okx-cex-market okx market ticker BTC-USDT → 检查当前价格
↓ 用户确认
3. okx-cex-trade okx spot place --instId BTC-USDT --side buy --ordType market --sz 0.1
机器人启动前余额检查
用户:“我想用 1000 USDT 启动一个 BTC 网格机器人”
1. okx-cex-portfolio okx account balance USDT → 确认可用资金 ≥ 1000
2. okx-cex-market okx market candles BTC-USDT --bar 4H --limit 50 → 确定价格范围
↓ 用户确认
3. okx-cex-bot okx bot grid create --instId BTC-USDT --algoOrdType grid \
--minPx 90000 --maxPx 100000 --gridNum 10 --quoteSz 1000
查看当前持仓和盈亏
用户:“显示我当前的持仓以及它们的表现”
1. okx-cex-portfolio okx account positions → 当前持仓及未实现盈亏
2. okx-cex-portfolio okx account positions-history → 最近平仓记录
3. okx-cex-market okx market ticker BTC-USDT-SWAP → 检查当前价格与入场价的对比
划转与交易
用户:“从我的资金账户划转 500 USDT 来交易 BTC”
1. okx-cex-portfolio okx account asset-balance USDT → 确认资金余额 ≥ 500
↓ 用户确认
2. okx-cex-portfolio okx account transfer --ccy USDT --amt 500 --from 18 --to 6
3. okx-cex-portfolio okx account balance USDT → 确认交易余额已更新
↓ 准备交易
4. okx-cex-trade okx spot place ...
开仓前检查最大持仓量
用户:“使用全仓保证金我能买多少 BTC?”
1. okx-cex-portfolio okx account balance → 总权益
2. okx-cex-portfolio okx account max-size --instId BTC-USDT-SWAP --tdMode cross → 最大买入/卖出数量
3. okx-cex-market okx market ticker BTC-USDT-SWAP → 当前价格参考
操作流程
步骤 0 — 凭证与配置文件检查
在执行任何需要认证的命令之前:
确定交易模式(必需):
- 选项:
live(实盘)或demo(模拟盘)— 只有这两个值
- 当前消息意图明确(例如,“real”/“实盘”/“live” → live;“test”/“模拟”/“demo” → demo)→ 使用它,告知用户:
"使用 --profile live (实盘)" - 当前消息未明确声明 → 检查对话上下文中的历史 profile:
- 找到 → 使用它,告知用户:
"沿用之前的 --profile live (实盘)" - 未找到 → 询问:
"实盘还是模拟盘?"— 等待回答
- 找到 → 使用它,告知用户:
如果未配置凭证: 引导用户运行 okx config init,停止所有交易操作
每次命令执行后: 在响应中附加 [profile: live] 或 [profile: demo]
步骤 1:识别账户操作
- 查询余额 →
okx account balance(交易账户)或okx account asset-balance(资金账户) - 查看当前持仓 →
okx account positions - 查看历史平仓 + 盈亏 →
okx account positions-history - 查看交易历史 →
okx account bills - 检查手续费等级 →
okx account fees - 检查账户设置 →
okx account config - 计算订单数量 →
okx account max-size或okx account max-avail-size - 检查提现限额 →
okx account max-withdrawal - 划转资金 →
okx account transfer - 更改持仓模式 →
okx account set-position-mode
步骤 2:立即执行读取命令 — 确认交易模式(步骤 0),然后执行写入命令
读取命令(1–10):立即执行,无需确认。
ccy筛选:使用币种符号,如USDT、BTC、ETH--instType用于手续费/持仓:SPOT、SWAP、FUTURES、OPTION--archive用于账单:访问超出默认窗口的较旧记录--tdMode用于最大数量:cash(现货)、cross(全仓)或isolated(逐仓)
写入命令(11–12):执行前需确认一次。
set-position-mode:确认模式(net= 单向持仓,long_short_mode= 对冲模式);切换可能会影响当前持仓transfer:确认--ccy、--amt、--from、--to(账户类型:6=交易账户,18=资金账户);首先验证源账户余额
步骤 3:写入后验证
- 执行
set-position-mode后:运行okx account config以确认posMode已更新 - 执行
transfer后:运行okx account balance和okx account asset-balance以确认余额已更新
CLI 命令参考
账户余额 — 交易账户
okx account balance [ccy] [--json]
| 参数 | 必需 | 默认值 | 描述 |
|---|---|---|---|
ccy | 否 | - | 筛选单一币种(例如 USDT) |
返回表格:currency、equity、available、frozen。仅显示余额 > 0 的币种。
资产余额 — 资金账户
okx account asset-balance [ccy] [--json]
| 参数 | 必需 | 默认值 | 描述 |
|---|---|---|---|
ccy | 否 | - | 筛选单一币种 |
返回:ccy、bal、availBal、frozenBal。仅显示余额 > 0 的币种。
持仓 — 当前持仓
okx account positions [--instType <type>] [--instId <id>] [--json]
| 参数 | 必需 | 默认值 | 描述 |
|---|---|---|---|
--instType | 否 | - | 筛选:SWAP、FUTURES、OPTION |
--instId | 否 | - | 筛选至特定产品 |
返回:instId、instType、side (posSide)、pos、avgPx、upl(未实现盈亏)、lever。仅显示数量 ≠ 0 的持仓。
历史持仓 — 已平仓
okx account positions-history [--instType <type>] [--instId <id>] [--limit <n>] [--json]
返回:instId、direction、openAvgPx、closeAvgPx、realizedPnl、uTime。
账单 — 账户账本
okx account bills [--archive] [--instType <type>] [--ccy <ccy>] [--limit <n>] [--json]
| 参数 | 必需 | 默认值 | 描述 |
|---|---|---|---|
--archive | 否 | false | 访问较旧记录(归档接口) |
--instType | 否 | - | 按产品类型筛选 |
--ccy | 否 | - | 按币种筛选 |
--limit | 否 | 100 | 记录数量 |
返回:billId、instId、type、ccy、balChg、bal、ts。
手续费 — 交易费率等级
okx account fees --instType <type> [--instId <id>] [--json]
| 参数 | 必需 | 默认值 | 描述 |
|---|---|---|---|
--instType | 是 | - | SPOT、SWAP、FUTURES、OPTION |
--instId | 否 | - | 特定产品(可选) |
返回:level、maker、taker、makerU、takerU、ts。
配置 — 账户配置
okx account config [--json]
返回:uid、acctLv(账户等级)、posMode(net/long_short_mode)、autoLoan、greeksType、level、levelTmp。
最大数量 — 最大订单数量
okx account max-size --instId <id> --tdMode <mode> [--px <price>] [--json]
| 参数 | 必需 | 默认值 | 描述 |
|---|---|---|---|
--instId | 是 | - | 产品 ID |
--tdMode | 是 | - | cash(现货)、cross(全仓)或 isolated(逐仓) |
--px | 否 | - | 参考价格(省略时使用标记价格) |
返回:instId、maxBuy、maxSell。
最大可用数量
okx account max-avail-size --instId <id> --tdMode <mode> [--json]
返回:instId、availBuy、availSell — 下一笔订单的即时可用数量。
最大提现金额
okx account max-withdrawal [ccy] [--json]
返回表格:ccy、maxWd、maxWdEx(含借贷)。如果未筛选,则显示所有币种。
设置持仓模式
okx account set-position-mode <net|long_short_mode> [--json]
| 值 | 行为 |
|---|---|
net | 单向持仓(默认)— 多头和空头相互抵消 |
long_short_mode | 对冲模式 — 多头和空头可同时存在 |
警告:当存在持仓时切换模式可能导致意外行为。请先运行
okx account positions检查。
划转资金
okx account transfer --ccy <ccy> --amt <n> --from <acctType> --to <acctType> \
[--transferType <type>] [--subAcct <name>] [--json]
| 参数 | 必需 | 默认值 | 描述 |
|---|---|---|---|
--ccy | 是 | - | 要划转的币种(例如 USDT) |
--amt | 是 | - | 划转金额 |
--from | 是 | - | 源账户类型:6=交易账户,18=资金账户 |
--to | 是 | - | 目标账户类型:6=交易账户,18=资金账户 |
--transferType | 否 | 0 | 0=账户内转账,1=转至子账户,2=从子账户转入 |
--subAcct | 否 | - | 子账户名称(子账户转账必需) |
返回:transId、ccy、amt。
MCP 工具参考
| 工具 | 描述 |
|---|---|
account_get_balance | 交易账户余额 |
account_get_asse… | (内容已截断) |