Desic OKX Agent

简体中文 | English

面向 Codex、Claude Code 及其他 MCP 客户端的独立 OKX 本地 Runtime、MCP Server、CLI 和 Agent Skills。

安装

要求 Node.js 22.12 或更高版本，以及能够访问 OKX 的网络或 HTTP/HTTPS 代理。

首次安装只需两条命令：

npm install --global desic-okx-agent
desic-okx setup

两条命令作用不同：

1. npm install 安装 desic-okx 程序。

2. desic-okx setup 接入 AI 客户端、安装 Skills、检查网络，并询问是否配置 OKX API 账户。

首次安装后需要运行一次 setup。以后正常升级无需重复运行；只有新增 AI 客户端、修复配置或重新配置代理时才需要再次运行。

完成后重启已选择的 AI 客户端，并验证：

desic-okx doctor

Related MCP server: seashail

Setup 会做什么

交互式向导会依次完成：

1. 选择 Codex、Claude Code、Cursor、VS Code / GitHub Copilot、Cline，或全部客户端。

2. 注册 desic-okx MCP Server，保留已有 MCP 配置。

3. 为 Codex 和 Claude Code 自动安装全部 9 个 Skills。

4. 检查 OKX REST 与 WebSocket；连接失败时引导测试并保存 HTTP 代理。

5. 解释不同功能的 API Key 要求，并让用户选择“现在配置”或“以后配置”。

6. 如果现在配置，隐藏凭证输入，自动识别实盘或模拟盘，验证成功后才写入本地配置。

API 账户是可选的。跳过后公共行情和公共衍生品仍可使用，以后运行下面的命令即可配置：

desic-okx account add

自动化或无人值守安装可以指定客户端；该模式不会询问或保存 API 凭证：

desic-okx setup --targets codex --yes
desic-okx setup --targets codex,claude-code --yes
desic-okx setup --all --yes
desic-okx setup --targets codex --yes --skip-network-check

配置 OKX API

在 OKX 官方网站或 App 中创建 API Key。实盘账户与模拟交易账户使用各自环境的 API Key，Desic OKX Agent 会通过只读验证自动识别，不需要用户选择实盘或模拟盘。

按实际用途授予权限：

本项目不提供提现、充值、资金划转、资产转出或 API Key 管理工具，不需要为此授予相关权限。建议先使用 OKX 模拟交易账户验证交易流程，并按自己的安全策略在 OKX 配置 IP 白名单。

交互式添加账户：

desic-okx account add --name demo
desic-okx account add --name main

输入 API Key、Secret Key 和 Passphrase 时终端会隐藏文本。account add 会先连接 OKX 验证，验证失败不会保存凭证。凭证保存在系统配置目录的 config.json 中；Unix 权限为 0600：

desic-okx config-path

也支持环境变量覆盖同名账户：

OKX_ACCOUNT
OKX_API_KEY
OKX_API_SECRET
OKX_API_PASSPHRASE

三个凭证变量必须同时提供。Runtime 会自动探测账户环境；能否交易完全取决于 OKX 为该 API Key 配置的官方权限。

让 AI 自动安装

可将下面的提示词交给 Codex、Claude Code、Cursor、VS Code / GitHub Copilot 或 Cline。将 codex 替换为 claude-code、cursor、vscode、cline 或 all：

请为我安装 Desic OKX Agent：
1. 检查 Node.js 是否为 22.12 或更高版本。
2. 运行 npm install --global desic-okx-agent。
3. 运行 desic-okx setup --targets codex --yes。
4. 运行 desic-okx doctor 验证 MCP、Skills 和 OKX 网络。
5. 不要要求我在聊天中发送任何 API Key、Secret 或 Passphrase。
6. 告诉我公共工具已可使用；如果我需要账户、News、Smart Money 或交易功能，引导我直接在自己的终端运行 desic-okx account add，并由我在隐藏输入框中填写凭证。

快速开始

公共行情不需要账户：

desic-okx call market_get_ticker --json '{"instId":"BTC-USDT-SWAP"}'
desic-okx call market_get_decision_snapshot --json '{"instId":"BTC-USDT-SWAP","bar":"1m"}'

Runtime 会在 MCP 或 CLI 首次调用时自动启动，通常不需要手动运行 desic-okx start。

常用命令：

desic-okx status
desic-okx doctor
desic-okx tools
desic-okx tool market_get_decision_snapshot
desic-okx account list
desic-okx update --check

status 显示 Runtime 版本、运行时间、代理路径、WebSocket 状态、订阅与数据年龄、账户和数据库状态。doctor 主动检查安装、网络、SQLite、行情、账户、MCP 客户端和 Skills。两者均支持 --json。

主要能力

• 共享单例 Runtime，可被多个 MCP 和 CLI 客户端复用

• 内存中的 ticker、盘口、逐笔成交、K 线、资金费率、标记价格和持仓量

• 带新鲜度、交易所时间和一致性元数据的统一决策快照

• 公共行情、指标扫描和公共衍生品分析

• 账户余额、持仓、委托、成交、账单及风险摘要

• 仅限永续合约的普通单、策略单、杠杆、改单、撤单和平仓操作

• 实验性的 News 与 Smart Money 能力，以及 SQLite 历史回退

• SQLite WAL 持久化已收盘 K 线、情报历史、派生事件和执行记录

• Python 策略研究：1 分钟历史数据、回测、参数调优、多次回测对比

• 实盘执行：把已回测的策略绑到账户，每根 1 分钟收线自动决策，八道风控闸门前置

一条链，不是两个产品

上面的能力不是并列的清单，而是同一条链上的几段。手动做和让 AI 做，走的是同一条链：

分析行情 ──→ 写成策略 ──→ 回测 ──→ 调参 ──→ 建 Profile ──→ 模拟盘验证 ──→ 实盘
  行情/衍生品      Python        7:3 切分   验证段排名     不会开始交易    真实下单    真钱
  News/资金流      策略文件                                              （需你同意）

两种用法的区别只在谁按键：

默认情况下 agent 只能读和停，创建与启用不在它的工具列表里。要让 AI 跑完整条链：

desic-okx live agent-access on    # 需重启 MCP 客户端
desic-okx live agent-access       # 查看当前设置

开启后 agent 仍被要求在启用实盘 Profile 前停下来问你 —— 这条约束写在 Skill 里，不是系统闸门。系统能验证的是"这个 Profile 能不能跑"，不能验证"该不该投真钱"。

策略研究

用 Python 写策略，在本地 1 分钟历史数据上回测、调参、对比：

desic-okx strategy env --setup
desic-okx data download --inst BTC-USDT-SWAP --days 90
desic-okx strategy new --out ema.py --template ema-trend
desic-okx strategy backtest --file ema.py --inst BTC-USDT-SWAP --days 30 --follow

调参会把窗口按 7:3 切分，用候选从未见过的那一段排名，因此过拟合是可见的而不是被埋掉的。每次回测自动比较同杠杆永续多头、空头和现金基准，并拆成 3–6 个时间段评估稳定性；交易点可追溯到策略原因。strategy portfolio 可把 2–12 个策略按固定资金权重跑成一个组合结果。TUI 同样支持 /portfolio、实验名称/备注和 /annotate，并可从 /report 打开完整报告。对比会在两次运行数据、合约、区间或成本不同时给出警告。

完整说明见 策略研究使用指南。

实盘执行

把已验证的策略接到真实账户，每根 1 分钟收线自动执行：

desic-okx live create --file ema.py --inst BTC-USDT-SWAP --account demo \
  --environment demo --entry-budget 100 --side-budget 200 --daily-loss 500
desic-okx live readiness --id lp_xxxx
desic-okx live start --id lp_xxxx
desic-okx live signals --id lp_xxxx

启用需要该源码 + 该合约已完成回测（按源码 hash 匹配，不是文件名），并会把 Profile 的杠杆写到交易所 —— 预算按杠杆折算张数，两边不一致预算就不成立。风控闸门只拒绝、不修正，过期 cutoff 不追单，被拒绝的信号会完整保留。崩溃后按确定性客户端订单号向交易所对账，绝不重发可能已存在的订单；未知订单状态会阻断重新启用。持久化全局 kill switch 可一次停止全部 Profile，追加式审计事件即使删除 Profile 后仍保留。TUI 的 /live audit、/live kill 和 /live reconcile 提供同一套操作员入口；清除停止与人工对账要求显式 --yes。

这部分会用真钱下单。 完整说明与限制见 实盘执行使用指南。

Skills

desic-okx setup 会为 Codex 和 Claude Code 自动安装：

• okx-market-analysis

• okx-derivatives-analysis

• okx-news-intelligence

• okx-smart-money-analysis

• okx-account-analysis

• okx-trading

• okx-strategy-research

• okx-live-trading

• trading-philosophy

升级后 Skills 会自动同步。也可手动检查或同步；被修改的旧版本会先备份：

desic-okx skills status
desic-okx skills sync
desic-okx skills sync --targets codex --dry-run

账户管理

desic-okx account list
desic-okx account verify --name main
desic-okx account verify --all
desic-okx account set-default main
desic-okx account rename main primary
desic-okx account edit primary
desic-okx account remove primary

account add 和 account edit 均在写入配置前验证凭证。工具参数只接受账户别名，不接受 API Key、Secret 或 Passphrase。

工具帮助

desic-okx tools
desic-okx tool news_search
desic-okx tool trade_place_order
desic-okx tool trade_place_order --json

帮助会显示用途、账户要求、输入 Schema 和可直接运行的调用示例。远程 News 与 Smart Money 接口属于实验性能力，上游兼容性问题会返回 CAPABILITY_UNAVAILABLE，不会影响行情、账户和交易模块。

代理

REST 以及公共、业务和私有 WebSocket 统一按以下顺序解析代理：

1. config.json 中的 proxy.url

2. HTTPS_PROXY、HTTP_PROXY 或 ALL_PROXY，并支持 NO_PROXY

3. Windows 或 macOS 已启用的系统 HTTP/HTTPS 代理

4. 直接连接

只支持 HTTP/HTTPS 代理 URL。仅有 PAC 或 SOCKS 的环境需要提供 HTTP 代理入口。示例：

{
  "proxy": {
    "url": "http://127.0.0.1:7890"
  }
}

修改配置后重启 Runtime：

desic-okx stop

更新

desic-okx update --check
desic-okx update
desic-okx update --yes

更新器会检查 npm 官方 Registry、停止 Runtime、等待 Windows 释放 SQLite 原生模块、执行全局升级、同步已安装 Skills，最后运行 Doctor。新版 CLI 或 MCP 适配器遇到旧 Runtime 时也会自动切换版本。

手动接入客户端

推荐使用 desic-okx setup。只注册 MCP 时，可运行：

codex mcp add desic-okx -- desic-okx mcp
claude mcp add --transport stdio --scope user desic-okx -- desic-okx mcp

Codex 的手动配置：

[mcp_servers.desic-okx]
command = "desic-okx"
args = ["mcp"]

从源码开发

git clone https://github.com/xiazhi88/desic-okx-agent.git
cd desic-okx-agent
npm ci
npm run check
npm link

检查流程包含 TypeScript 类型检查、单元测试、Skill 校验、敏感信息扫描、生产构建和 MCP 传输冒烟测试。普通测试不会提交订单；真实交易端到端测试仅允许 OKX Demo 环境。

运行机制

• Runtime 绑定 127.0.0.1 随机端口，并以私有状态文件保存 PID、端口和访问令牌。

• 默认预热 BTC-USDT-SWAP 和 ETH-USDT-SWAP，其他合约按需订阅并在空闲 15 分钟后释放。

• 热数据从内存返回，冷数据或过期数据由 REST 补齐。

• WebSocket 自动重连；盘口序列、校验失败时重新建立快照。

• market_get_decision_snapshot 对齐多个数据组件并报告最大时间偏差；交易预检拒绝不一致快照。

• 交易写操作使用稳定 executionKey。超时或结果不明确时先查询远端状态，不直接重复提交。

交易软件可能造成资金损失。本项目不提供投资建议，也不保证执行结果。

状态与许可

当前为 0.3.2 预发布版本。正式发布 1.0.0 前，应在目标网络环境中完成 OKX Demo 交易验证。策略研究与实盘执行已在 OKX 模拟盘上端到端验证过，实盘执行尚未经过长期真钱运行。

MIT License，详见 LICENSE。OKX 及相关商标归其各自权利人所有。