Cursor

内置的 cursor 提供方通过 Cursor 自己的 ConnectRPC/protobuf AgentService 触达你的 Cursor 订阅。kind = "cursor" 原生适配器将其桥接到 Anthropic Messages API —— 包括流式传输、流式响应中的推理、原生工具调用,以及 内联图像。登录和 token 刷新使用 api2.cursor.sh;agent 轮次通过 HTTP/2 对接 Cursor 当前的 agent 主机(agentn.global.api5.cursor.sh)。

快速开始

让编码 agent 为你完成接入 —— shunt add 会打印一份内置的设置蓝图 (离线且只读;配置由 agent 编辑,该命令绝不会修改配置):

shunt add upstream cursor --print | claude

或者按照下面的手动步骤操作。

1. 登录

shunt login cursor

这会运行 Cursor 的 OAuth 流程并写入 ~/.shunt/cursor-auth.json,shunt 会读取并 自动刷新它。如果该文件缺失或过期,shunt 会返回一个 authentication_error, 提示你再次运行 shunt login cursor。

2. 配置上游

该提供方默认已预置,因此无需配置表 —— 路由一个 cursor:* 模型 id 就完事了。要显式声明它(用于有序故障转移),cursor 预设提供了 原生适配器、base_url = "https://api2.cursor.sh" 和 auth = "cursor_oauth":

[[upstreams]]
name = "anthropic"
provider = "anthropic"   # 让 Anthropic 作为无路由匹配模型(例如 claude-*)的默认项

[[upstreams]]
name = "cursor"
provider = "cursor"

有序的 [[upstreams]] 会替换 shunt 的内置提供方(包括预置的 cursor),因此显式 配置还必须声明它仍然回退到的 anthropic 默认项 (server.default_provider 默认为 anthropic)。

旧的 [providers.cursor] 表形式仍然受支持 —— 但不要在同一个文件中混用 [[upstreams]] 和 [providers.*]。

3. 模型 id 与 agent 模式

前缀选择 Cursor 的 agent 模式(Agent / Plan / Ask),后缀通常是 Cursor 的模型 id。请使用 wire id,而不是 cursor-agent models 中的显示名:Auto 是 default (路由 cursor:auto 会以 Unknown model ID: auto 失败)。具名模型(例如 cursor:gpt-5.2) 需要一个授予其权限的付费套餐;免费套餐仅限 cursor:default。

Cursor 模型选择器中的 composer-2.5-fast 条目是一个参数化别名,而不是 wire id。 路由 cursor:composer-2.5-fast(或 cursor:composer-2.5[fast=true])时,shunt 会发送 composer-2.5 wire id 和 fast=true 模型元数据,与官方 CLI 一致。

旧式的裸名称同样被接受:cursor、cursor-agent、cursor-composer、 cursor-composer-fast(Agent);cursor-plan、composer-2.5(Plan);cursor-ask、 composer-2.5-fast(Ask)。其他任何模型 id 都会被以 invalid_request_error 拒绝。

直接路由,或者向 模型发现 暴露一个 Claude 命名的别名:

[[routes]]
model = "cursor:default"
provider = "cursor"

# 或者: 在一个声明中同时公开 + 路由
[[models]]
id = "claude-cursor-default"
display_name = "Cursor Auto"

[models.upstream_model]
cursor = "cursor:default"

适配器承载的内容

适配器流式传输助手的文本与推理,把你客户端的工具桥接为原生的 Cursor MCP 工具调用(模型调用的某个工具会以带 stop_reason: "tool_use" 的 Anthropic tool_use 块浮现;你运行它并把 tool_result 送回,shunt 会带着该结果在历史中重跑这一轮), 并转发内联图像(base64 源;URL 图像会被跳过)。Cursor 自己的 agentic 文件 / shell 工具 不会被暴露 —— 只有你的请求所声明的工具。

校验

shunt check    # -> config ok
shunt run
curl -sS http://127.0.0.1:3001/v1/messages \
  -H 'anthropic-version: 2023-06-01' \
  -H 'content-type: application/json' \
  -d '{"model":"cursor:default","max_tokens":16,"messages":[{"role":"user","content":"Reply with OK."}]}'

确认响应的 x-gateway-upstream 头写的是 cursor,然后 将 Claude Code 指向 shunt。