okx-cex-bot

OKX CEX 机器人交易

在 OKX 上管理网格和 DCA（现货与合约马丁格尔）机器人。所有机器人均由 OKX 原生服务器端运行——它们在 OKX 上运行，无需本地进程。

运行前检查

运行任何命令前，请遵循 ../_shared/preflight.md。 使用此文件 frontmatter 中的 metadata.version 作为步骤 2 的参考。

前提条件

npm install -g @okx_ai/okx-trade-cli
okx config init   # select site -> follow browser OAuth flow

安全：绝不要在聊天中收集凭证。引导用户使用 okx config init 进行设置。

凭证与配置文件检查

每次执行需要身份验证的命令前都要运行。 身份验证方式会在运行前检查步骤 2 中检测，并在本次会话中记住。

步骤 A — 验证凭证

运行以下两条命令——okx auth status --json 中的 apiKey 字段是 auth-binary 的内部状态，无论 ~/.okx/config.toml 中是否存在 API 密钥配置文件，它始终为 false。okx config show --json 是唯一可靠的 API 密钥存在性信息来源。

okx config show --json      # reveals API-key profiles (TOML config)
okx auth status --json      # reveals OAuth session state (auth-binary state)

按以下顺序判断——以第一个匹配项为准：

• config show --json 中存在任意 api_key 字段非空的配置文件 → API 密钥模式。继续步骤 B。
• 没有 API 密钥配置文件，且 auth status --json 返回 "status":"logged_in" → OAuth 模式。继续步骤 B。
• 没有 API 密钥配置文件，且 "status":"pending" — 登录正在进行，等待其完成。
• 没有 API 密钥配置文件，且 "status":"not_logged_in" — 停止，加载 okx-cex-auth skill 并按步骤登录，等待完成。

步骤 B — 确认交易模式

判定方式：

1. 用户意图明确（“real”/“实盘”/“live” → live；“test”/“模拟”/“demo” → demo）→ 使用该模式，并告知用户
2. 未明确声明 → 查看对话上下文中之前的选择 → 如果找到则沿用
3. 未找到 → 询问：“Live（实盘）还是 Demo（模拟盘）？”——继续前等待用户回复

模式的应用方式取决于身份验证方法（在步骤 A 中检测）：

身份验证方式	Live（实盘）	Demo（模拟盘）
API 密钥	--profile <live-profile>	--profile <demo-profile>
OAuth	（无需标志，默认使用 live）	--demo

• API 密钥用户：运行 okx config show --json，查看可用的配置文件名称及其 demo 设置。
• OAuth 用户：live 模式不添加标志；模拟交易时添加 --demo。

每条命令执行后：追加 [mode: live] 或 [mode: demo]

处理 401 错误

身份验证错误（错误中包含“401”、“Session expired”或“Run okx auth login first”）：

1. 立即停止
2. 加载 okx-cex-auth skill 并按步骤重新验证身份
3. 重试原始命令

Skill 路由

需求	Skill
市场数据、价格、深度	okx-cex-market
账户余额、持仓、费用	okx-cex-portfolio
常规现货/掉期/期货订单	okx-cex-trade
网格 / DCA 机器人	okx-cex-bot（本 skill）

命令索引

网格机器人

命令	类型	描述
okx bot grid create	WRITE	创建网格机器人（现货或合约）
okx bot grid amend	WRITE	修改运行中网格机器人的价格区间、网格数量或 TP/SL
okx bot grid stop	WRITE	停止网格机器人
okx bot grid positions	READ	查询未平仓的合约网格持仓（强平价格、保证金率、未实现盈亏）
okx bot grid liquidate-price	READ	估算合约网格机器人的强平价格
okx bot grid close-position	WRITE	机器人以 stopType=2 停止后平掉剩余持仓
okx bot grid orders	READ	列出活跃或历史网格机器人
okx bot grid details	READ	网格机器人详情 + 盈亏
okx bot grid sub-orders	READ	单笔网格成交或待处理订单

DCA Bot（现货和合约）

Command	Type	Description
okx bot dca create	WRITE	创建 DCA（马丁格尔）Bot（现货或合约）
okx bot dca stop	WRITE	停止 DCA Bot（现货或合约）
okx bot dca orders	READ	列出活动或历史 DCA Bot（默认：contract_dca）
okx bot dca details	READ	DCA Bot 详情及盈亏
okx bot dca sub-orders	READ	DCA 周期及周期内的订单
okx bot dca add-margin	WRITE	为运行中的合约 DCA Bot 增加保证金
okx bot dca reduce-margin	WRITE	减少运行中的合约 DCA Bot 的保证金
okx bot dca update-tp	WRITE	更新运行中的合约 DCA Bot 的止盈价格

Smart Portfolio Bot

注意：使用 --modules bot.smartportfolio 或 bot.all 加载（不包含在默认模块中）。

Command	Type	Description
okx bot smart-portfolio create	WRITE	创建 Smart Portfolio Bot（2–10 种资产，比例总和为 1.0，设置 deltaRatio 阈值）
okx bot smart-portfolio stop	WRITE	停止运行中的 Smart Portfolio Bot
okx bot smart-portfolio orders	READ	列出 Smart Portfolio Bot（默认：运行中；添加 --history 可查看已停止的 Bot）
okx bot smart-portfolio details	READ	获取 Smart Portfolio Bot 详情和当前配置比例
okx bot smart-portfolio amend-rebalance	WRITE	更新再平衡阈值和间隔（必须同时提供 --deltaRatio 和 --interval）
okx bot smart-portfolio instant-rebalance	WRITE	立即触发再平衡
okx bot smart-portfolio recommend-zones	READ	浏览 OKX 推荐的投资组合区域配置
okx bot smart-portfolio zones-backtest	READ	获取推荐区域的历史回测结果

操作流程

第 1 步 — 确定 Bot 类型和操作

解析用户请求 → 确定模块（Grid / DCA / Smart Portfolio）和操作（create / stop / list / details）。

第 2 步 — 执行

READ 命令（orders、details、sub-orders）：确认账户配置后立即运行。

WRITE 命令（create、amend、stop）：执行前与用户确认一次关键参数。

第 3 步 — 写入操作后验证

• 创建后 → 运行对应的 orders 命令，确认 Bot 处于活动状态
• 修改后 → 运行 details --algoId <id>，确认配置已更新
• 停止 Grid/DCA 后 → 运行 orders --history，确认 Bot 已停止
• 停止 Smart Portfolio 后 → 运行 smart-portfolio orders --history，确认 Bot 已停止

关键规则

• 绝不自动划转资金。 如果余额不足以创建 Bot，请报告资金缺口（当前可用余额与所需余额），并询问用户如何处理：(1) 手动划转资金；(2) 减小规模；或 (3) 取消。
• algoId 是 Bot 的算法订单 ID（来自创建或列表输出）。它不是普通的 ordId。绝不可伪造，必须始终从先前的命令中获取。
• Grid 的 algoOrdType 必须与 Bot 的实际类型一致。始终使用 bot grid orders 中的值，不要仅根据用户描述推断。不匹配会导致错误 50016。
• 操作现有 Bot 时，始终先列出 Bot 以获取正确的 ID，除非用户已明确提供 ID。
• TP/SL 限制：tpTriggerPx/tpRatio 和 slTriggerPx/slRatio 是互斥参数对。

CLI 命令参考

有关 Grid Bot 命令语法、参数表、快速入门示例和边缘情况， 请阅读 {baseDir}/references/grid-commands.md。

有关 DCA Bot 命令语法、参数表、快速入门示例和边缘情况， 请阅读 {baseDir}/references/dca-commands.md。

有关 Smart Portfolio Bot 命令语法、参数表和示例， 请阅读 {baseDir}/references/smart-portfolio-commands.md。

有关跨技能工作流示例（将 okx-cex-market/okx-cex-portfolio 与 Bot 创建流程串联），请阅读 {baseDir}/references/workflows.md。

沟通指南

• Grid/DCA：使用“机器人”，不要使用“策略”（例如“网格机器人”“DCA 机器人”）
• DCA：始终使用“DCA”或“Martingale”——DCA 同时支持现货 DCA 和合约 DCA
• 中文：Grid = “网格”，Spot DCA = “现货马丁”，Contract DCA = “合约马丁”，Smart Portfolio = “智能组合”
• 参数使用自然语言表达——“价格范围是多少？”而不是“输入 minPx 和 maxPx”
• 如果用户已经提供了数值，直接对应使用——不要再次询问

{base} 和 {quote}：通过按 - 分割 instId 提取。例如，BTC-USDT-SWAP → base=BTC，quote=USDT。

全局说明

• 所有机器人都在 OKX 服务器上运行——停止 CLI 不会影响它们
• 身份验证方式和交易模式由“凭证与配置文件检查”决定；参数规则请参阅该部分
• --json 默认返回原始 OKX API v5 响应。添加 --env 可将输出包装为 {"env": "<live|demo>", "profile": "<name>", "data": <response>}
• 速率限制：每个 UID 每 2 秒 20 次请求
• Grid --gridNum 范围：2–100