# 优宽量化 AI Agent 接入指南

本页面向 AI agent（Claude Code、Codex、Cursor、OpenClaw 等）。按顺序执行即可完成接入，用户只需在浏览器点一次“同意”。接入后你可以通过 MCP 工具在 优宽量化上写策略、回测、创建和管理实盘。

英文版：https://www.youquant.com/agent/setup.md

## 1. 申请授权

```
POST https://www.youquant.com/api/agent/device/code
Content-Type: application/json

{"name": "<你的名字 @ 机器名，例如 Claude Code @ MacBook>", "scopes": "read,backtest,write,trade"}
```

返回：

```json
{"device_code": "...", "user_code": "ABCD-EFGH",
 "verification_uri_complete": "https://www.youquant.com/agent/authorize?code=ABCD-EFGH",
 "expires_in": 600, "interval": 5, "scopes": "read,backtest,write,trade"}
```

把 `verification_uri_complete` 原样展示给用户，请用户在浏览器打开并同意。链接 10 分钟内有效。

`name` 同时是 key 的身份：同一个名字再次申请并被同意时，旧 key 会被吊销、换成新的，所以丢了配置重新接入不会堆出一堆 key；要在多台机器上并用，名字里带上机器名。

`scopes` 是逗号分隔的权限列表，用户在同意页上还可以勾掉其中一部分：

| scope | 能做什么 |
|---|---|
| read | 列表、详情、日志、消息、账户概览（不含任何密钥） |
| backtest | 发起 / 查询 / 停止回测 |
| write | 保存策略与版本、分组、告警开关、修改已停止实盘的配置 |
| trade | 创建 / 启动 / 停止实盘、给实盘发命令（会扣费并真实下单） |
| danger | 删除策略 / 实盘 / 节点、公开策略 |

留空默认是 `read,backtest,write,trade`。`danger` 不在默认里，需要时必须显式写上，并且先告诉用户为什么需要。

## 2. 轮询取 key

```
POST https://www.youquant.com/api/agent/device/token
Content-Type: application/json

{"device_code": "..."}
```

每 5 秒一次。`status` 为 `pending` 继续等；`slow_down` 放慢；`denied` 或 `expired` 结束并告知用户；`approved` 时返回：

```json
{"status": "approved", "access_key": "...", "secret_key": "...",
 "mcp_url": "https://www.youquant.com/api/mcp/<access_key>", "scopes": "read,backtest,write,trade"}
```

**只返回一次**。立即保存到你的配置里，不要写进对话、日志或代码仓库。

## 3. 接入 MCP

- URL：`mcp_url`
- Header：`Authorization: Bearer <secret_key>`
- 协议：MCP Streamable HTTP（2026-07-28，兼容 2025 各版）；密钥只能放 Header，不能放 URL。

Claude Code：

```bash
claude mcp add --transport http youquant "<mcp_url>" --header "Authorization: Bearer <secret_key>"
```

Cursor（`~/.cursor/mcp.json`）：

```json
{"mcpServers": {"youquant": {"url": "<mcp_url>", "headers": {"Authorization": "Bearer <secret_key>"}}}}
```

Claude Desktop（`claude_desktop_config.json`，需要 npx）：

```json
{"mcpServers": {"youquant": {"command": "npx", "args": ["mcp-remote", "<mcp_url>", "--header", "Authorization: Bearer <secret_key>"]}}}
```

其他客户端：在其 MCP 配置里填 Streamable HTTP 的 URL 和上述 Header 即可。

接上后先调 `tools/list` 看全部工具和说明；`server/discover`（老协议是 `initialize`）返回的 `instructions` 里有推荐工作流。

## 4. 规则

- 调用描述以 `[trade]` 或 `[danger]` 开头的工具前，先向用户确认。
- 交易所 API Key 不经 agent 配置：请用户在网页添加，然后用 `list_platforms` 按 id 选择。工具返回里不会出现任何密钥。
- 用户随时可以在 `https://www.youquant.com/m/account#apikey` 查看、修改权限或锁定这把 key。
- 用户让你断开、或者任务结束不再回来时，调 `revoke_my_key`（`confirm: true`）吊销自己这把 key；它只作用于当前连接用的 key。


## 手工配置（不能执行命令的客户端）

用户在 `https://www.youquant.com/m/account#apikey` 创建 key 后，按上面第 3 节的片段填入客户端配置即可；Cherry Studio 选 Streamable HTTP，URL 填 `mcp_url`，Headers 填 `Authorization=Bearer <secret_key>`。