Skip to content

configuration.md

Latest commit

 

History

History
838 lines (636 loc) · 21.7 KB

configuration.md

File metadata and controls

838 lines (636 loc) · 21.7 KB
Raw

Configuration

One-Line Install

For a guided installation that handles Node.js checking, package installation, and MCP client detection:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/okx/agent-tradekit/master/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/okx/agent-tradekit/master/scripts/install.ps1 | iex

The installer will:

  1. Check Node.js >= 18 (with install guidance if missing)
  2. Install @okx_ai/okx-trade-mcp and @okx_ai/okx-trade-cli globally
  3. Verify installation
  4. Detect installed MCP clients (Claude Desktop, Cursor, Windsurf)
  5. Auto-configure detected clients

After installation, configure your API credentials:

okx config init

API Credentials

All credentials are stored in ~/.okx/config.toml. The client config only needs the profile name.

The easiest way to set this up is the interactive wizard:

okx config init

Or configure manually with a minimal single-profile setup:

default_profile = "demo"

[profiles.demo]
api_key = "your-demo-api-key"
secret_key = "your-demo-secret-key"
passphrase = "your-demo-passphrase"
demo = true

Demo key: Create API Key (Demo Trading)

Live key: Create API Key (Live Trading)

EEA users: replace www.okx.com with my.okx.com · US users: use app.okx.com · TR users: use tr.okx.com

Required API permissions: Read + Trade. Withdraw permission is not required or recommended.

Site Configuration

OKX operates independent regional sites. Users must use the API of the site where their account is registered.

Site User URL API Base URL
global (default) www.okx.com https://www.okx.com
eea my.okx.com https://eea.okx.com
us app.okx.com https://us.okx.com
tr tr.okx.com https://tr.okx.com

Set the site in your profile:

[profiles.main]
site = "global"          # global | eea | us | tr  (default: global)
api_key = "your-api-key"
secret_key = "your-secret-key"
passphrase = "your-passphrase"

Or override at startup via flag or env var:

# Flag
agent-tradekit-mcp --site eea

# Environment variable (useful in Docker / CI)
OKX_SITE=us agent-tradekit-mcp

Priority: --site flag > OKX_SITE env var > site in toml > OAuth login site > default global

OAuth login site: When you authenticate via OAuth (okx auth login --site <x>), the token is issued for that specific site. If you do not set a site explicitly (flag / env / toml), requests are automatically routed to your OAuth login site instead of global. If you do set a site that conflicts with your login site, the CLI warns and honors your explicit choice (private requests may then return 401). To force the global dataset, pass --site global explicitly.

Note: OKX_API_BASE_URL / base_url in toml still override the site mapping entirely — useful for testing against a custom endpoint.

Proxy Configuration

Configure an HTTP/HTTPS proxy in your profile:

[profiles.default]
api_key = "your-api-key"
secret_key = "your-secret-key"
passphrase = "your-passphrase"
proxy_url = "http://127.0.0.1:7890"

Authenticated proxies are supported — include credentials in the URL:

[profiles.default]
proxy_url = "http://user:password@proxy.example.com:8080"

# Special characters in password need URL encoding, e.g. p@ss → p%40ss
# proxy_url = "http://user:p%40ss@proxy.example.com:8080"

Note: Only HTTP/HTTPS proxies are supported. SOCKS proxies are not supported.

Multiple profiles

You can define as many profiles as you like. Each MCP server instance uses one profile, so you can run demo and live side by side:

default_profile = "demo"

[profiles.demo]
api_key = "your-demo-api-key"
secret_key = "your-demo-secret-key"
passphrase = "your-demo-passphrase"
demo = true

[profiles.live]
api_key = "your-live-api-key"
secret_key = "your-live-secret-key"
passphrase = "your-live-passphrase"

# Optional: a second live account (e.g. sub-account)
[profiles.live-sub]
api_key = "your-sub-api-key"
secret_key = "your-sub-secret-key"
passphrase = "your-sub-passphrase"

Then register each as a separate MCP server in your client config:

{
  "mcpServers": {
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    },
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-live-sub": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live-sub", "--modules", "all"]
    }
  }
}

Your AI can switch between them simply by calling tools on the appropriate server.

Setup Command

The fastest way to configure a client is the setup subcommand — no manual JSON editing required.

# Configure Claude Desktop
okx-trade-mcp setup --client claude-desktop

# Configure Cursor
okx-trade-mcp setup --client cursor

# Configure VS Code (writes .mcp.json in current directory)
okx-trade-mcp setup --client vscode

# Configure Claude Code CLI
okx-trade-mcp setup --client claude-code

# Use a specific profile and modules
okx-trade-mcp setup --client claude-desktop --profile live --modules market,spot,account

Also available as okx setup --client <client> if okx-trade-cli is installed.

--client Target
claude-desktop ~/Library/Application\ Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\... (Windows)
cursor ~/.cursor/mcp.json
windsurf ~/.codeium/windsurf/mcp_config.json
vscode .mcp.json in current directory
claude-code runs claude mcp add

The command reads existing config and merges the new entry — it will not overwrite other MCP servers.

Client Setup (Manual)

Claude Desktop

Config file:

  • macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

Restart Claude Desktop after updating the config.

Cursor

Config file: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-level)

⚠️ Cursor tool limit: Cursor enforces a client-side limit of ~40 tools per MCP server and ~80 tools total (as of early 2026). okx-trade-mcp exposes 128 tools across 13 modules — loading --modules all will cause all MCP servers to show Error status. You must select a subset using --modules.

Recommended module combinations:

Use case Modules Tools
Trading (spot + swap) market,account,spot,swap 61
Contract + Bot market,account,swap,bot.grid,bot.dca 55
Earn market,account,earn.savings,earn.onchain,earn.dcd,earn.autoearn 48
Minimal (market data + account) market,account 27

Tip: If you need more modules than fit in one server, register multiple server instances with different --modules sets. Tool counts from all servers are pooled toward the ~80-tool total, so plan your splits accordingly.

{
  "mcpServers": {
    "okx-trade": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "market,account,spot,swap"]
    }
  }
}

Or use the setup command with an explicit module list:

okx-trade-mcp setup --client cursor --modules market,account,spot,swap

Claude Code CLI

claude mcp add --transport stdio okx-trade-mcp -- okx-trade-mcp --profile demo --modules all

Or create .mcp.json in your project root:

{
  "mcpServers": {
    "okx-trade-mcp": {
      "type": "stdio",
      "command": "okx-trade-mcp",
      "args": ["--profile", "demo", "--modules", "all"]
    }
  }
}

VS Code

Create .mcp.json in your project root (or ~/.claude.json for global scope):

{
  "mcpServers": {
    "okx-trade-mcp": {
      "type": "stdio",
      "command": "okx-trade-mcp",
      "args": ["--profile", "demo", "--modules", "all"]
    }
  }
}

Windsurf

Config file:

  • macOS/Linux: ~/.codeium/windsurf/mcp_config.json
  • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
{
  "mcpServers": {
    "okx-trade-mcp": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

openCxxW

Config file: openCxxW.json

{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

Startup Scenarios

Market data only (no API key required)

Watch prices, orderbook, candles without any credentials:

{
  "mcpServers": {
    "okx-market": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--modules", "market"]
    }
  }
}

Read-only account monitoring

Has API key but prevents any order placement:

{
  "mcpServers": {
    "okx-readonly": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all", "--read-only"]
    }
  }
}

Spot trading only

Minimal setup for spot trading — skips swap, futures, and bot modules:

{
  "mcpServers": {
    "okx-spot": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "market", "spot", "account"]
    }
  }
}

Demo (simulated trading)

Safe environment for testing — uses OKX paper trading, no real funds at risk:

{
  "mcpServers": {
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

Note: Grid bot tools (bot module) are not supported in demo mode — OKX does not expose those endpoints for simulated trading.

Full setup (live + demo side by side)

Register both as separate MCP servers. Your AI can switch between them:

{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

All Startup Options

Option Description
--profile <name> Profile from ~/.okx/config.toml (default: value of default_profile)
--modules <list> Comma-separated module names, or all. Default: spot swap account. all includes every module including earn sub-modules.
--read-only Disable all write operations (orders, position changes, bot creation)
--no-log Disable audit logging to ~/.okx/logs/
--log-level <level> Minimum log level: debug, info, warn, error (default: info)

配置（中文）

API 凭证

所有凭证存储在 ~/.okx/config.toml，客户端配置只需指定 Profile 名称。

最简单的单账号配置：

default_profile = "demo"

[profiles.demo]
api_key = "your-demo-api-key"
secret_key = "your-demo-secret-key"
passphrase = "your-demo-passphrase"
demo = true

模拟盘 Key： 创建 API Key（模拟盘）

实盘 Key： 创建 API Key（实盘）

EEA 用户：将 www.okx.com 替换为 my.okx.com；US 用户：使用 app.okx.com；TR 用户：使用 tr.okx.com

所需 API 权限： 读取 + 交易。无需也不建议开启提币权限。

站点配置

OKX 运营多个独立的区域站点，用户需要使用其账号所在站点的 API。

站点 用户网址 API Base URL
global（默认） www.okx.com https://www.okx.com
eea my.okx.com https://eea.okx.com
us app.okx.com https://us.okx.com
tr tr.okx.com https://tr.okx.com

在 Profile 中指定站点：

[profiles.main]
site = "global"          # global | eea | us | tr（默认：global）
api_key = "your-api-key"
secret_key = "your-secret-key"
passphrase = "your-passphrase"

也可以通过命令行参数或环境变量覆盖：

# 命令行参数
agent-tradekit-mcp --site eea

# 环境变量（适用于 Docker / CI）
OKX_SITE=us agent-tradekit-mcp

优先级：--site 参数 > OKX_SITE 环境变量 > toml 中的 site > OAuth 登录站点 > 默认 global

OAuth 登录站点： 通过 OAuth 登录（okx auth login --site <x>）时，token 是按该站点签发的。如果你没有显式指定站点（参数 / 环境变量 / toml），请求会自动路由到你的 OAuth 登录站点，而不是 global。如果你显式指定了一个与登录站点不一致的站点，CLI 会打印警告并按你的显式选择执行（此时私有请求可能返回 401）。如需强制使用全球数据集，请显式传入 --site global。

注意： OKX_API_BASE_URL 环境变量 / toml 中的 base_url 仍然优先级最高，会完全覆盖站点映射——适合高级用户或自定义测试场景。

代理配置

在 Profile 中配置 HTTP/HTTPS 代理：

[profiles.default]
api_key = "your-api-key"
secret_key = "your-secret-key"
passphrase = "your-passphrase"
proxy_url = "http://127.0.0.1:7890"

支持带认证的代理——在 URL 中包含用户名和密码：

[profiles.default]
proxy_url = "http://user:password@proxy.example.com:8080"

# 密码中的特殊字符需要 URL encode，例如 p@ss → p%40ss
# proxy_url = "http://user:p%40ss@proxy.example.com:8080"

注意： 仅支持 HTTP/HTTPS 代理，不支持 SOCKS 代理。

多账号配置

可以定义多个 Profile，每个 MCP Server 实例使用一个 Profile，模拟盘和实盘可以并行运行：

default_profile = "demo"

[profiles.demo]
api_key = "your-demo-api-key"
secret_key = "your-demo-secret-key"
passphrase = "your-demo-passphrase"
demo = true

[profiles.live]
api_key = "your-live-api-key"
secret_key = "your-live-secret-key"
passphrase = "your-live-passphrase"

# 可选：第二个实盘账号（如子账号）
[profiles.live-sub]
api_key = "your-sub-api-key"
secret_key = "your-sub-secret-key"
passphrase = "your-sub-passphrase"

然后在客户端配置中分别注册为独立的 MCP Server：

{
  "mcpServers": {
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    },
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-live-sub": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live-sub", "--modules", "all"]
    }
  }
}

AI 可以直接通过调用对应 Server 的工具来切换账号。

Setup 命令

最快的配置方式是 setup 子命令，无需手动编辑 JSON。

# 配置 Claude Desktop
okx-trade-mcp setup --client claude-desktop

# 配置 Cursor
okx-trade-mcp setup --client cursor

# 配置 VS Code（在当前目录写 .mcp.json）
okx-trade-mcp setup --client vscode

# 配置 Claude Code CLI
okx-trade-mcp setup --client claude-code

# 指定 profile 和模块
okx-trade-mcp setup --client claude-desktop --profile live --modules market,spot,account

安装了 okx-trade-cli 的话，也可以用 okx setup --client <client>。

--client 目标
claude-desktop macOS: ~/Library/Application\ Support/Claude/... / Windows: %APPDATA%\Claude\...
cursor ~/.cursor/mcp.json
windsurf ~/.codeium/windsurf/mcp_config.json
vscode 当前目录下的 .mcp.json
claude-code 调用 claude mcp add

命令会读取现有配置并合并写入，不会覆盖其他已有的 MCP Server 条目。

客户端配置（手动）

Claude Desktop

配置文件路径：

  • macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

修改配置后重启 Claude Desktop 生效。

Cursor

配置文件：~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目级）

⚠️ Cursor 工具数量限制：Cursor 客户端限制每个 MCP Server 最多约 40 个工具，所有 Server 合计不超过约 80 个（截至 2026 年初）。okx-trade-mcp 共有 128 个工具（13 个模块），使用 --modules all 将导致所有 MCP Server 显示 Error 状态。必须通过 --modules 参数选择子集。

推荐模块组合：

使用场景 模块 工具数
交易（现货 + 合约） market,account,spot,swap 61
合约 + 机器人 market,account,swap,bot.grid,bot.dca 55
赚币 market,account,earn.savings,earn.onchain,earn.dcd,earn.autoearn 48
最小化（行情 + 账户） market,account 27

提示： 如果需要的模块超出单个 Server 的工具上限，可以注册多个 Server 实例，每个实例指定不同的 --modules。所有实例的工具数量合计计入约 80 个总限额，规划时需综合考虑。

{
  "mcpServers": {
    "okx-trade": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "market,account,spot,swap"]
    }
  }
}

也可以用 setup 命令指定模块列表：

okx-trade-mcp setup --client cursor --modules market,account,spot,swap

Claude Code CLI

claude mcp add --transport stdio okx-trade-mcp -- okx-trade-mcp --profile demo --modules all

或在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "okx-trade-mcp": {
      "type": "stdio",
      "command": "okx-trade-mcp",
      "args": ["--profile", "demo", "--modules", "all"]
    }
  }
}

VS Code

在项目根目录创建 .mcp.json（或 ~/.claude.json 用于全局配置）：

{
  "mcpServers": {
    "okx-trade-mcp": {
      "type": "stdio",
      "command": "okx-trade-mcp",
      "args": ["--profile", "demo", "--modules", "all"]
    }
  }
}

Windsurf

配置文件：

  • macOS/Linux: ~/.codeium/windsurf/mcp_config.json
  • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
{
  "mcpServers": {
    "okx-trade-mcp": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

openCxxW

配置文件：openCxxW.json

{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

启动场景

仅行情（无需 API Key）

查看价格、盘口、K线，无需任何凭证：

{
  "mcpServers": {
    "okx-market": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--modules", "market"]
    }
  }
}

只读账户监控

有 API Key 但禁止任何下单操作：

{
  "mcpServers": {
    "okx-readonly": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all", "--read-only"]
    }
  }
}

仅现货交易

最小化配置，跳过永续/交割/Bot 模块：

{
  "mcpServers": {
    "okx-spot": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "market", "spot", "account"]
    }
  }
}

模拟盘（模拟交易）

用 OKX 模拟盘安全测试，不涉及真实资金：

{
  "mcpServers": {
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

注意： 网格机器人工具（bot 模块）不支持模拟盘——OKX 不对模拟交易账号开放相关端点。

完整配置（实盘 + 模拟盘并行）

同时注册两个 MCP Server，AI 可自由切换：

{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

全部启动参数

参数 说明
--profile <name> 指定 ~/.okx/config.toml 中的 Profile（默认：default_profile 的值）
--modules <list> 逗号分隔的模块名，或 all。默认：spot swap account。all 包含所有模块（含赚币子模块）。
--read-only 禁用所有写操作（下单、改单、修改仓位、创建/停止 Bot 等）
--no-log 禁用审计日志（默认写入 ~/.okx/logs/）
--log-level <level> 最低日志级别：debug、info、warn、error（默认：info）