gate-exchange-futures

解析 gate-cli（二进制文件路径）

按以下顺序解析 gate-cli：（1） command -v gate-cli 和 gate-cli --version 均成功；（2） 若 ${HOME}/.local/bin/gate-cli 可执行，则使用该路径；（3） 若 ${HOME}/.openclaw/skills/bin/gate-cli 可执行，则使用该路径。规范规则：exchange-runtime-rules.md §4（或 gate-runtime-rules.md §4）。

Gate 期货交易套件

通用规则

⚠️ 停止 — 继续操作前，必须阅读并严格遵守共享运行时规则。 在阅读完所有规则之前，不得选择或调用任何工具。这些规则具有最高优先级。 → 阅读 gate-runtime-rules.md

• 只能使用此技能中明确列出的 gate-cli 命令。 即使其他接口提供了此处未记录的命令，在这些工作流中也不得运行。

技能依赖

使用的 gate-cli 命令

查询操作（只读）

• gate-cli cex futures account get
• gate-cli cex futures market contract
• gate-cli cex futures position get-dual
• gate-cli cex futures order get
• gate-cli cex futures market orderbook
• gate-cli cex futures position get
• gate-cli cex futures price-trigger get
• gate-cli cex futures market tickers
• gate-cli cex futures order list
• gate-cli cex futures position list
• gate-cli cex futures price-trigger list

执行操作（写入）

• gate-cli cex futures order amend
• gate-cli cex futures order cancel
• gate-cli cex futures order cancel
• gate-cli cex futures price-trigger cancel
• gate-cli cex futures price-trigger cancel-all
• gate-cli cex futures order add; gate-cli cex futures order close; gate-cli cex futures order long; gate-cli cex futures order remove; gate-cli cex futures order short
• gate-cli cex futures price-trigger create
• gate-cli cex futures position update-dual-cross-mode
• gate-cli cex futures position update-dual-leverage
• gate-cli cex futures position update-cross-mode
• gate-cli cex futures position update-leverage
• gate-cli cex futures price-trigger update

身份验证

• **交互式文件设置：**当主机上未同时设置 GATE_API_KEY 和 GATE_API_SECRET 时，运行 gate-cli config init，完成 API 密钥、密钥、配置档案和默认值的向导设置（参见 gate-cli）。
• 环境变量／标志：如果已提供凭据，则无需运行 gate-cli config init——例如，主机上已设置 GATE_API_KEY 和 GATE_API_SECRET 两者，或在支持的情况下使用 --api-key／--api-secret；绝不可要求用户在聊天中粘贴密钥。
• **权限：**Fx:Write
• **门户：**在聊天之外创建或轮换密钥：https://www.gate.com/myaccount/profile/api-key/manage

安装检查

• 必需：gate-cli（如果缺失，请在此技能目录中运行 sh ./setup.sh；可选 GATE_CLI_SETUP_MODE=release）。
• 如果按名称调用 gate-cli，请将 $HOME/.openclaw/skills/bin 添加到 PATH（或添加 setup.sh 安装该程序的目录）。
• 凭据：当主机上同时设置了非空的 GATE_API_KEY 和 GATE_API_SECRET 时，不要要求运行 gate-cli config init——这对 gate-cli 来说是等效的有效配置。当两者均未设置或为空时，提醒操作人员运行 gate-cli config init，或在技能库中相应的匹配技能中配置 GATE_API_KEY／GATE_API_SECRET（绝不可要求用户在聊天中粘贴密钥）。
• **基本检查：**在执行经过身份验证的调用前，不要继续操作，直到 CLI 的行为符合预期（例如运行 gate-cli --version，或运行此技能中的只读 gate-cli cex ... 命令）；在执行任何变更操作前，确认凭据已正确解析。

执行模式

阅读并严格遵循 references/gate-cli.md，然后执行此 SKILL.md 中针对各模块的路由。

• SKILL.md 保留路由逻辑（Open/Close/Cancel/Amend/TP-SL/Conditional/Manage）。
• references/gate-cli.md 是 gate-cli 执行约定的权威文档，规定了工具约定、模式切换保护措施、确认关卡和降级处理。

模块概览

模块	描述	触发关键词
Open	限价/市价开多或开空、全仓/逐仓模式、涨幅最高/跌幅最大标的下单	long、short、buy、sell、open、top gainer、top loser
Close	全部平仓、部分平仓、反向持仓	close、close all、reverse
Cancel	取消一个或多个订单	cancel、revoke
Amend	修改订单价格或数量	amend、modify
TP/SL	为现有持仓设置止盈或止损；价格达到时触发平仓/减仓订单	take profit、stop loss、TP、SL、止盈、止损
Conditional Open	下达待触发的开仓订单，价格达到指定水平时触发	conditional order、when price reaches、breakout buy、dip buy、条件单、触价开仓
Manage Triggers	列出、取消或修改价格触发的未完成订单	list triggers、cancel TP、cancel SL、amend trigger、查询条件单、取消止盈止损

路由规则

意图	示例表述	路由至
开仓	“BTC 做多 1 张合约”、“ETH 市价做空”、“10 倍杠杆做多”、“涨幅最高的标的做多，金额 10U”	阅读 references/open-position.md
平仓	“BTC 全部平仓”、“平掉一半”、“反向开空”、“全部平仓”	阅读 references/close-position.md
取消订单	“取消那个买单”、“取消所有订单”、“列出我的订单”	阅读 references/cancel-order.md
修改订单	“将价格改为 60000”、“修改订单数量”	阅读 references/amend-order.md
设置止盈/止损	“将 BTC 止盈设为 70000”、“我的多仓止损设为 58000”、“止损 60000”	阅读 references/tp-sl.md
条件开仓	“BTC 跌到 60000 时买入”、“价格突破 68000 时开空”、“条件单做多”	阅读 references/conditional.md
管理触发订单	“列出我的止盈/止损订单”、“取消那个止损单”、“修改触发价格”、“查询条件单”	阅读 references/manage.md
不明确	“帮我处理期货”、“显示我的持仓”	澄清：查询持仓/订单，然后引导用户

gate-cli 命令索引

#	工具	用途
1	gate-cli cex futures market tickers	获取所有期货行情（用于涨幅榜／跌幅榜排序）
2	gate-cli cex futures market contract	获取单个合约信息（精度、乘数等）
3	gate-cli cex futures market orderbook	获取合约订单簿（最佳买价／卖价）
4	gate-cli cex futures account get	获取期货账户（持仓模式：单向／双向）
5	gate-cli cex futures position list	列出持仓（双向模式）
6	gate-cli cex futures position get-dual	获取某个合约的双向模式持仓
7	gate-cli cex futures position get	获取某个合约的单向模式持仓
8	gate-cli cex futures position update-dual-cross-mode	切换保证金模式（全仓／逐仓，双向模式）
9	gate-cli cex futures position update-cross-mode	在单向模式下切换保证金模式（双向模式下请勿使用）
10	gate-cli cex futures position update-dual-leverage	设置杠杆（双向模式）
11	gate-cli cex futures position update-leverage	设置杠杆（单向模式，双向模式下请勿使用）
12	gate-cli cex futures order add; gate-cli cex futures order close; gate-cli cex futures order long; gate-cli cex futures order remove; gate-cli cex futures order short	下单（开仓／平仓／反向）
13	gate-cli cex futures order list	列出订单
14	gate-cli cex futures order get	获取单个订单详情
15	gate-cli cex futures order cancel	取消单个订单
16	gate-cli cex futures order cancel	取消某个合约的所有订单
17	gate-cli cex futures order amend	修改订单（价格／数量）

执行工作流

1. 意图和参数

• 确定模块（开仓／平仓／取消／修改／止盈止损／条件单／管理）。
• 提取：contract、side、size、price、leverage（用于开仓／平仓）；trigger_price、trigger_rule、order_size、order_price、order_tif（用于止盈止损／条件单）。
• 涨幅榜／跌幅榜：如果用户要求查询“涨幅榜”／“跌幅榜”（或类似请求），而不是指定某个合约，则调用 gate-cli cex futures market tickers，按 changePercentage 排序（涨幅榜降序，跌幅榜升序），选出排名第一的合约。然后使用该合约继续开仓流程。
• 缺少参数：如果缺少必需参数（例如数量），则询问用户（澄清模式）。

2. 交易前检查

• 合约：调用 gate-cli cex futures market contract，确保合约存在且可交易。

• 账户：检查余额和冲突持仓（例如切换保证金模式时）。

• 风险：不要根据 order_price_deviate 预先计算有效限价（实际偏差限制取决于 risk_limit_tier）。遇到 PRICE_TOO_DEVIATED 时，显示错误消息中的有效范围。

• 结算币种：始终使用 usdt，除非用户明确指定以 BTC 结算的合约。

• 保证金模式与持仓模式（仅当用户明确要求的保证金模式与当前模式不同时）：调用 gate-cli cex futures account get 获取持仓模式。根据响应中的 position_mode：single = 单向持仓模式，dual = 双向（对冲）持仓模式。根据持仓查询保证金模式：按上述双向/单向模式查询持仓 → pos_margin_mode（全仓/逐仓）。如果用户未指定保证金模式，不要切换；按当前模式下单。

• 单向持仓（position_mode === "single"）：不要中断流程。提示用户："您已有一个 {currency} 持仓；切换保证金模式也会应用于此持仓。是否继续？"（例如，从合约 BTC_USDT 中获取 currency：BTC）。等待用户确认后再继续。

• 双向持仓（position_mode === "dual"）：中断流程。告知用户："请先平仓，然后再开新仓。"

• 双向模式与单向模式（API 选择）：先调用 gate-cli cex futures account get。如果 position_mode === "dual"（或 in_dual_mode === true）：

• 持仓/杠杆查询：使用 gate-cli cex futures position list 或 gate-cli cex futures position get-dual。双向模式下不要使用 gate-cli cex futures position get（这是单向模式 API，会返回错误的架构）。

• 切换保证金模式：使用 gate-cli cex futures position update-dual-cross-mode（双向模式下不要使用 gate-cli cex futures position update-cross-mode；这是单向模式 API）。

• 杠杆：使用 gate-cli cex futures position update-dual-leverage（双向模式下不要使用 gate-cli cex futures position update-leverage；这是单向模式 API，会返回错误的架构）。 如果是单向模式：使用 gate-cli cex futures position get 查询持仓；使用 gate-cli cex futures position update-cross-mode 切换模式；使用 gate-cli cex futures position update-leverage 设置杠杆。

3. 模块逻辑

模块 A：开仓

1. 单位换算：如果用户未以 contracts 指定数量，区分 USDT 成本（“花费 100U”）和 USDT 价值（“价值 100U”），通过 gate-cli cex futures market contract 获取 quanto_multiplier，并通过 gate-cli cex futures market orderbook 获取最佳买价/卖价：

• USDT 成本（基于保证金）：开多：contracts = cost / (0.0015 + 1/leverage) / quanto_multiplier / order_price；开空：contracts = cost / (0.0015 + 1.00075/leverage) / quanto_multiplier / max(order_price, best_bid)。order_price：限价 → 指定价格；市价 → 最佳卖价（多仓）或最佳买价（空仓）。leverage 必须来自当前持仓查询（步骤 5）；不得假定默认值。
• USDT 价值（基于名义价值）：买入/开多：contracts = usdt_value / price / quanto_multiplier；卖出/开空：contracts = usdt_value / max(best_bid, order_price) / quanto_multiplier。price：限价 → 指定价格；市价 → 最佳卖价（买入）或最佳买价（卖出）。
• 基础币（如 BTC、ETH）：contracts = 基础币数量 ÷ quanto_multiplier
• 向下取整为整数；必须满足 order_size_min。

2. 模式：仅当用户明确要求切换保证金模式时才切换：只有在用户明确要求逐仓（例如“isolated”）时才切换到逐仓；只有在用户明确要求全仓（例如“cross”）时才切换到全仓。如果用户未指定保证金模式，则不要切换——按当前保证金模式（来自持仓的 pos_margin_mode）下单。如果用户明确要求逐仓，请检查杠杆。
3. 模式切换：仅当用户明确要求的保证金模式与当前模式（来自持仓的 pos_margin_mode）不同时，才在调用 gate-cli cex futures position update-dual-cross-mode/gate-cli cex futures position update-cross-mode 之前，通过 gate-cli cex futures account get 获取持仓模式 → position_mode（single/dual）；如果 position_mode === "single"，显示提示 "You already have a {currency} position; switching margin mode will apply to this position too. Continue?"，并且仅在用户确认后继续；如果 position_mode === "dual"，不要切换——中断操作并告知用户 "Please close the position first, then open a new one."
4. 模式切换（无冲突）：仅当用户明确要求切换到全仓或逐仓，且目标模式与当前模式不同时才切换：如果没有持仓，或有单向持仓且用户已确认，则在双向模式下调用 gate-cli cex futures position update-dual-cross-mode（dual），或在单向模式下调用 gate-cli cex futures position update-cross-mode（single），并传入 mode "cross" 或 "isolated"。如果用户未明确要求保证金模式，则不要切换。
5. 杠杆：如果用户指定了杠杆，且该杠杆与当前杠杆（根据上述双向/单向模式，通过持仓查询获取）不同，则先在双向模式下调用 gate-cli cex futures position update-dual-leverage，或在单向模式下调用 gate-cli cex futures position update-leverage，然后继续。如果用户未指定杠杆，则不要更改——所有计算均使用从持仓查询获取的当前杠杆（例如 USDT 成本公式）。不得使用任何默认值（例如 10x 或 20x）。
6. 下单前确认：通过持仓查询获取合约和方向对应的当前杠杆（双向：gate-cli cex futures position list 或 gate-cli cex futures position get-dual；单向：gate-cli cex futures position get）。显示最终订单摘要（合约、方向、数量、价格或市价、模式、杠杆、预估保证金/强平价格）。请用户确认（例如：“回复‘confirm’以下单。”）。只有在用户确认后，才能下单。
7. 下单：调用 gate-cli cex futures order add; gate-cli cex futures order close; gate-cli cex futures order long; gate-cli cex futures order remove; gate-cli cex futures order short（市价：tif=ioc、price=0）。
8. 验证：通过持仓查询确认持仓（双向：gate-cli cex futures position list 或 gate-cli cex futures position get-dual；单向：gate-cli cex futures position get）。

模块 B：平仓

1. 持仓信息：通过持仓查询获取当前的 size 和方向（双向持仓：gate-cli cex futures position list 或 gate-cli cex futures position get-dual；单向持仓：gate-cli cex futures position get）。
2. 分支处理：全部平仓（查询后，使用 reduce_only 平仓）；部分平仓（计算 size，然后使用 reduce_only 执行 gate-cli cex futures order add; gate-cli cex futures order close; gate-cli cex futures order long; gate-cli cex futures order remove; gate-cli cex futures order short）；反向开仓（分两步操作：先平仓，再开反向仓位）。
3. 验证：使用与步骤 1 相同的持仓查询，确认剩余持仓。

模块 C：撤销订单

1. 查找：按 order_id 查找，或使用 gate-cli cex futures order list 并让用户选择。
2. 撤销：仅调用一次 gate-cli cex futures order cancel（不批量撤销）。
3. 验证：确认 finish_as == cancelled。

模块 D：修改订单

1. 检查：订单状态必须为 open。
2. 精度：根据合约验证新的价格/size。
3. 修改：调用 gate-cli cex futures order amend 更新价格或 size。

模块 E：止盈 / 止损

完整逻辑请阅读 references/tp-sl.md。要点如下：

1. 持仓检查：获取当前持仓，以确认方向和 size（适用预检中的双向/单向持仓模式规则）。
2. 自动选择触发规则：

• 多头止盈：trigger_rule = ">="（价格上涨至止盈价位）
• 多头止损：trigger_rule = "<="（价格下跌至止损价位）
• 空头止盈：trigger_rule = "<="（价格下跌至止盈价位）
• 空头止损：trigger_rule = ">="（价格上涨至止损价位）

3. 平仓标志（close、auto_size 和 order_type 取决于持仓模式和方向）：

• 单向持仓模式，全部平掉多头：order_type = "close-long-position"，close = true，不设置 auto_size，order_reduce_only = true。
• 单向持仓模式，全部平掉空头：order_type = "close-short-position"，close = true，不设置 auto_size，order_reduce_only = true。
• 单向持仓模式，部分平掉多头：order_type = "plan-close-long-position"，close = false，不设置 auto_size，order_reduce_only = true。
• 单向持仓模式，部分平掉空头：order_type = "plan-close-short-position"，close = false，不设置 auto_size，order_reduce_only = true。
• 双向持仓模式，全部平掉多头：order_type = "close-long-position"，close = false，auto_size = "close_long"，order_reduce_only = true。
• 双向持仓模式，全部平掉空头：order_type = "close-short-position"，close = false，auto_size = "close_short"，order_reduce_only = true。
• 双向持仓模式，部分平掉多头：order_type = "plan-close-long-position"，close = false，不设置 auto_size，order_reduce_only = true。
• 双向持仓模式，部分平掉空头：order_type = "plan-close-short-position"，close = false，不设置 auto_size，order_reduce_only = true。

4. 数量：如果用户说“全部平仓”或未指定数量，则使用全部平仓（size = 0）以及上文中适用的模式标志；如果部分平仓，则计算 size 并设置 order_reduce_only = true。
5. 市价还是限价：如果用户未指定执行价格，则使用市价单（order_price = "0"，order_tif = "ioc"）；否则使用限价单（order_tif = "gtc"）。
6. 确认：展示摘要（合约、方向、触发价、触发规则、执行类型、size 或“全部平仓”），并在调用 gate-cli cex futures price-trigger create 前请用户确认。

模块 F：条件开仓

阅读 references/conditional.md 了解完整逻辑。要点：

1. 无需持仓：触发时会开立新仓位。
2. 触发规则：用户指定方向——“跌到 X 时买入” → trigger_rule = "<="，“突破 X 时买入” → trigger_rule = ">="。
3. 数量换算：采用与模块 A 相同的单位换算规则（合约、USDT 成本、USDT 价值、基础资产数量）。使用 gate-cli cex futures market contract 获取 quanto_multiplier，使用 gate-cli cex futures market orderbook 获取最优买价／卖价。按成本换算时，如果用户未指定执行限价，则使用 trigger_price 作为参考 order_price。
4. 订单数量符号：正数 = 做多，负数 = 做空。
5. 确认：下单前显示完整摘要。

模块 G：管理已触发订单

阅读 references/manage.md 了解完整逻辑。支持：

• 列表：gate-cli cex futures price-trigger list
• 获取详情：gate-cli cex futures price-trigger get
• 取消单笔：gate-cli cex futures price-trigger cancel
• 全部取消：gate-cli cex futures price-trigger cancel-all
• 修改：gate-cli cex futures price-trigger update

修改限制：只有 TP/SL 订单（order_type 包含 plan-close-* 或具有 reduce_only/close 标志）支持通过 gate-cli cex futures price-trigger update 直接修改。通过 API 创建的条件开仓订单会返回 APIOrderNotSupportUpdateTouchOrder，无法修改——必须先取消，再重新创建。

报告模板

每次操作后，输出简短的标准化结果。

对于价格触发订单：

✓ [Operation] [Contract]
 Trigger: [rule] [trigger_price]
 Execute: [market/limit price] × [size or "close all"] [reduce_only/close]
 Order ID: [id]

领域知识

• USDT 永续合约：以 USDT 结算的线性合约。持仓大小以合约数量计量；每份合约代表 quanto_multiplier 个基础资产单位（例如 0.001 BTC）。
• 全仓与逐仓保证金：全仓模式以整个账户余额作为保证金；逐仓模式将保证金限制为分配给该仓位的金额。
• 单向与双向持仓模式：单向模式下，每个合约持有一个净仓位；双向模式（对冲）允许在同一合约上同时持有多头和空头仓位。两种模式使用不同的 API 端点。
• 价格触发订单：当市场价格越过触发价时执行的条件订单。用于 TP/SL（平掉现有仓位）和条件开仓（开立新仓位）。触发由服务端执行；客户端无需保持在线。
• 只减仓：确保订单只减少现有仓位，不会意外开立新仓位。TP/SL 订单始终应设置此项。
• 订单数量符号：对于价格触发平仓订单，负数量 = 卖出（平多），正数量 = 买入（平空）。对于开仓订单，正数 = 做多，负数 = 做空。

安全规则

确认

• 开仓：显示最终订单摘要（合约、方向、数量、价格／市价、模式、杠杆、预估强平价／保证金），然后在执行 gate-cli cex futures order add; gate-cli cex futures order close; gate-cli cex futures order long; gate-cli cex futures order remove; gate-cli cex futures order short 前请求确认。不要添加有关标记价格与限价、order_price_deviate 或建议调整价格的文字。示例："回复“confirm”以提交订单。"
• 全部平仓、反向开仓、批量取消：显示操作范围并请求确认。示例："平掉所有仓位？请回复确认。" / "取消此合约的所有订单。继续吗？"
• 创建 TP/SL／条件单：显示完整摘要（合约、触发规则 + 价格、执行价格／类型、数量），然后询问 "回复“confirm”以提交此订单。"
• 取消所有触发订单：显示操作范围（指定合约或全部），并询问 "取消 [contract] 的所有触发订单？请回复确认。"
• 修改触发订单：显示修改前后的值并请求确认。

订单 ID 精度

Gate 订单 ID 是超过 Number.MAX_SAFE_INTEGER（2^53-1）的 64 位整数。标准 JSON 解析器会静默地将其损坏。

• 始终将 order_id 作为字符串传递（例如，"728451920374819843"，而不是 728451920374819843）。
• 从 API 响应中读取订单 ID 时，将其作为原始字符串令牌复制，绝不要将其解析为数字。
• 向用户显示订单 ID 时，始终以字符串形式原样显示（不加逗号，也不使用科学计数法）。

错误

代码	操作
BALANCE_NOT_ENOUGH	建议充值或降低杠杆／仓位规模。
PRICE_TOO_DEVIATED	从错误消息中提取实际有效价格范围并展示给用户（不要依赖合约的 order_price_deviate；实际限值取决于 risk_limit_tier）。
POSITION_HOLDING（切换模式）	API 返回此错误（而不是 POSITION_NOT_EMPTY）。请用户先平仓。
CONTRACT_NOT_FOUND	合约无效或不可交易。确认合约名称（例如 BTC_USDT）和结算币种；建议列出合约。
ORDER_NOT_FOUND	订单已成交、已触发、已取消，或 order_id 错误。建议检查订单历史记录或列出已触发订单。
APIOrderNotSupportUpdateTouchOrder	通过 API 创建的条件开仓订单无法修改。请取消并重新创建。TP/SL 订单不受影响，可以正常修改。
SIZE_TOO_LARGE	订单规模超出限制。建议减小规模，或检查合约的 order_size_max。
ORDER_FOK	FOK 订单无法全部成交。建议更换价格／规模，或使用 GTC/IOC。
ORDER_POC	POC 订单会消耗流动性，因此被交易所拒绝。建议更换价格以确保仅作为挂单。
INVALID_PARAM_VALUE	双向持仓模式下通常是使用了错误的 API 或参数（例如，在双向持仓模式下使用 gate-cli cex futures position update-cross-mode 或 gate-cli cex futures position update-leverage；这些是单向持仓模式的 API）。请使用双向持仓模式 API：gate-cli cex futures position update-dual-cross-mode、gate-cli cex futures position update-dual-leverage；查询仓位时使用 gate-cli cex futures position list 或 gate-cli cex futures position get-dual。对于价格触发订单：检查 trigger_rule、order_size 的正负号以及 order_price 格式。