# Cursor API Proxy

一個讓你可以透過標準 OpenAI/Anthropic API 格式存取 Cursor AI 編輯器的代理伺服器。

可以把 Cursor 的模型無縫接入 **Claude Code**、**OpenCode** 或任何支援 OpenAI/Anthropic API 的工具。

## 功能特色

- **API 相容**：支援 OpenAI 格式和 Anthropic 格式的 API 呼叫
- **多帳號管理**：支援新增、移除、切換多個 Cursor 帳號
- **動態模型對映**：自動將 Cursor CLI 支援的所有模型轉換為 `claude-*` 格式，供 Claude Code / OpenCode 使用
- **Tailscale 支援**：可綁定到 `0.0.0.0` 供區域網路存取
- **HWID 重置**：內建反偵測功能，可重置機器識別碼
- **連線池**：最佳化的連線管理

## 快速開始

### 1. 建置

```bash
git clone https://github.com/your-repo/cursor-api-proxy-go.git
cd cursor-api-proxy-go
go build -o cursor-api-proxy .
```

### 2. 登入 Cursor 帳號

```bash
./cursor-api-proxy login myaccount
```

### 3. 啟動伺服器

```bash
./cursor-api-proxy
```

預設監聽 `127.0.0.1:8765`。

### 4. 設定 API Key（選用）

如果需要外部存取，建議設定 API Key：

```bash
export CURSOR_BRIDGE_API_KEY=my-secret-key
./cursor-api-proxy
```

---

## 接入 Claude Code

Claude Code 使用 Anthropic SDK，透過環境變數設定即可改用你的代理。

### 步驟

```bash
# 1. 啟動代理（確認已在背景執行）
./cursor-api-proxy &

# 2. 設定環境變數，讓 Claude Code 改用你的代理
export ANTHROPIC_BASE_URL=http://127.0.0.1:8765

# 3. 如果代理有設定 CURSOR_BRIDGE_API_KEY，這裡填相同的值；沒有的話隨便填
export ANTHROPIC_API_KEY=my-secret-key

# 4. 啟動 Claude Code
claude
```

### 切換模型

在 Claude Code 中輸入 `/model`，即可看到你 Cursor CLI 支援的所有模型。

代理會自動將 Cursor 模型 ID 轉換為 `claude-*` 格式：

| Cursor CLI 模型 | Claude Code 看到的 |
|---|---|
| `opus-4.6` | `claude-opus-4-6` |
| `sonnet-4.6` | `claude-sonnet-4-6` |
| `opus-4.5-thinking` | `claude-opus-4-5-thinking` |
| `sonnet-4.7` (未來新增) | `claude-sonnet-4-7` (自動生成) |

### 也可直接指定模型

```bash
claude --model claude-sonnet-4-6
```

---

## 接入 OpenCode

OpenCode 透過 `~/.config/opencode/opencode.json` 設定 provider，使用 OpenAI 相容格式。

### 步驟

1. 啟動代理伺服器

```bash
./cursor-api-proxy &
```

2. 編輯 `~/.config/opencode/opencode.json`，在 `provider` 中新增一個 provider：

```json
{
  "provider": {
    "cursor": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Cursor Agent",
      "options": {
        "baseURL": "http://127.0.0.1:8765/v1",
        "apiKey": "unused"
      },
      "models": {
        "auto": { "name": "Cursor Auto" },
        "sonnet-4.6": { "name": "Sonnet 4.6" },
        "opus-4.6": { "name": "Opus 4.6" },
        "opus-4.6-thinking": { "name": "Opus 4.6 Thinking" }
      }
    }
  }
}
```

若代理有設定 `CURSOR_BRIDGE_API_KEY`，把 `apiKey` 改成相同的值。

3. 在 `opencode.json` 中設定預設模型：

```json
{
  "model": "cursor/sonnet-4.6"
}
```

### 查看可用模型

```bash
curl http://127.0.0.1:8765/v1/models | jq '.data[].id'
```

代理的 `/v1/models` 端點會回傳 Cursor CLI 目前支援的所有模型 ID，把結果加到 `opencode.json` 的 `models` 中即可。

### 在 OpenCode 中切換模型

OpenCode 的模型切換使用 `/model` 指令，從 `opencode.json` 的 `models` 清單中選擇。

---

## 模型對映原理

兩端使用不同的模型 ID 格式：

```
Claude Code                    OpenCode
  │                              │
  │  claude-opus-4-6             │  opus-4.6 (Cursor 原生 ID)
  │  (Anthropic alias)           │  (OpenAI 相容格式)
  ▼                              ▼
┌──────────────────────┐   ┌──────────────────────┐
│ ResolveToCursorModel │   │ 直接傳給代理          │
│ claude-opus-4-6      │   │ opus-4.6             │
│         ↓            │   │         ↓            │
│ opus-4.6             │   │ opus-4.6             │
└──────────────────────┘   └──────────────────────┘
              │                      │
              └──────────┬───────────┘
                         ▼
              Cursor CLI (agent --model opus-4.6)
```

### Anthropic 模型對映表（Claude Code 使用）

| Cursor 模型 | Anthropic ID | 說明 |
|---|---|---|
| `opus-4.6` | `claude-opus-4-6` | Claude 4.6 Opus |
| `opus-4.6-thinking` | `claude-opus-4-6-thinking` | Claude 4.6 Opus (Thinking) |
| `sonnet-4.6` | `claude-sonnet-4-6` | Claude 4.6 Sonnet |
| `sonnet-4.6-thinking` | `claude-sonnet-4-6-thinking` | Claude 4.6 Sonnet (Thinking) |
| `opus-4.5` | `claude-opus-4-5` | Claude 4.5 Opus |
| `opus-4.5-thinking` | `claude-opus-4-5-thinking` | Claude 4.5 Opus (Thinking) |
| `sonnet-4.5` | `claude-sonnet-4-5` | Claude 4.5 Sonnet |
| `sonnet-4.5-thinking` | `claude-sonnet-4-5-thinking` | Claude 4.5 Sonnet (Thinking) |

### 動態對映（自動）

Cursor CLI 新增模型時（如 `opus-4.7`、`sonnet-5.0`），代理自動生成對應的 `claude-*` ID，無需手動更新。

規則：`<family>-<major>.<minor>` → `claude-<family>-<major>-<minor>`

---

## 帳號管理

### 登入帳號

```bash
./cursor-api-proxy login myaccount

# 使用代理登入
./cursor-api-proxy login myaccount --proxy=http://127.0.0.1:7890
```

### 列出帳號

```bash
./cursor-api-proxy accounts
```

### 登出帳號

```bash
./cursor-api-proxy logout myaccount
```

### 重置 HWID（反BAN）

```bash
# 基本重置
./cursor-api-proxy reset-hwid

# 深度清理（清除 session 和 cookies）
./cursor-api-proxy reset-hwid --deep-clean
```

### 啟動選項

| 選項 | 說明 |
|------|------|
| `--tailscale` | 綁定到 `0.0.0.0` 供區域網路存取 |
| `-h, --help` | 顯示說明 |

---

## API 端點

| 端點 | 方法 | 說明 |
|------|------|------|
| `http://127.0.0.1:8765/v1/chat/completions` | POST | OpenAI 格式聊天完成 |
| `http://127.0.0.1:8765/v1/models` | GET | 列出可用模型 |
| `http://127.0.0.1:8765/v1/chat/messages` | POST | Anthropic 格式聊天 |
| `http://127.0.0.1:8765/health` | GET | 健康檢查 |

---

## 環境變數

### 伺服器設定

| 變數 | 預設值 | 說明 |
|------|--------|------|
| `CURSOR_BRIDGE_HOST` | `127.0.0.1` | 監聽位址（設為 `0.0.0.0` 可供區域網路存取） |
| `CURSOR_BRIDGE_PORT` | `8765` | 監聽連接埠 |
| `CURSOR_BRIDGE_API_KEY` | _(無)_ | API 鑑別金鑰，設定後所有請求需帶此金鑰 |
| `CURSOR_BRIDGE_TIMEOUT_MS` | `300000` | 請求逾時毫秒數（預設 5 分鐘） |
| `CURSOR_BRIDGE_MULTI_PORT` | `false` | 啟用多連接埠模式 |
| `CURSOR_BRIDGE_VERBOSE` | `false` | 啟用詳細日誌輸出 |

### Agent / 模型設定

| 變數 | 預設值 | 說明 |
|------|--------|------|
| `CURSOR_AGENT_BIN` / `CURSOR_CLI_BIN` / `CURSOR_CLI_PATH` | `agent` | Cursor CLI 二進位檔路徑 |
| `CURSOR_AGENT_NODE` | _(無)_ | Node.js 執行檔路徑（Windows 使用） |
| `CURSOR_AGENT_SCRIPT` | _(無)_ | Agent 腳本路徑（Windows 使用） |
| `CURSOR_BRIDGE_DEFAULT_MODEL` | `auto` | 預設使用的模型 ID |
| `CURSOR_BRIDGE_STRICT_MODEL` | `true` | 嚴格模式：禁止使用不在清單中的模型 |
| `CURSOR_BRIDGE_MAX_MODE` | `false` | 啟用 Max Mode（消耗更多額度） |
| `CURSOR_BRIDGE_FORCE` | `false` | 強制執行，不詢問確認 |
| `CURSOR_BRIDGE_APPROVE_MCPS` | `false` | 自動核准 MCP 工具呼叫 |

### 工作區與帳號

| 變數 | 預設值 | 說明 |
|------|--------|------|
| `CURSOR_BRIDGE_WORKSPACE` | _(目前目錄)_ | 工作目錄路徑 |
| `CURSOR_BRIDGE_CHAT_ONLY_WORKSPACE` | `true` | 限制 agent 只能存取工作目錄 |
| `CURSOR_CONFIG_DIRS` / `CURSOR_ACCOUNT_DIRS` | _(自動探索)_ | 帳號設定目錄，多個用逗號分隔 |

### TLS / HTTPS

| 變數 | 預設值 | 說明 |
|------|--------|------|
| `CURSOR_BRIDGE_TLS_CERT` | _(無)_ | TLS 憑證檔路徑（啟用 HTTPS） |
| `CURSOR_BRIDGE_TLS_KEY` | _(無)_ | TLS 私鑰檔路徑（啟用 HTTPS） |

### 記錄與 Windows 特定

| 變數 | 預設值 | 說明 |
|------|--------|------|
| `CURSOR_BRIDGE_SESSIONS_LOG` | `~/.cursor-api-proxy/sessions.log` | Session 記錄檔路徑 |
| `CURSOR_BRIDGE_WIN_CMDLINE_MAX` | `30000` | Windows 命令列最大長度（4096–32700） |
| `COMSPEC` | `cmd.exe` | Windows 命令直譯器路徑 |

---

## 常見問題

**Q: 為什麼需要登入帳號？**
A: Cursor API 需要驗證才能使用，請先登入你的 Cursor 帳號。

**Q: 如何處理被BAN的問題？**
A: 使用 `reset-hwid` 命令重置機器識別碼，加上 `--deep-clean` 進行更徹底的清理。

**Q: 可以在其他設備上使用嗎？**
A: 可以，使用 `--tailscale` 選項啟動伺服器，然後透過區域網路 IP 存取。

**Q: 模型列表多久更新一次？**
A: 每次呼叫 `GET /v1/models` 時，代理會即時呼叫 Cursor CLI 的 `--list-models` 取得最新模型，並自動生成對應的 `claude-*` ID。

**Q: 未來 Cursor 新增模型怎麼辦？**
A: 不用改任何東西。只要新模型符合 `<family>-<major>.<minor>` 命名規則，代理會自動生成對應的 `claude-*` ID。

---

## 授權

MIT License