opencode-cursor-agent/README.md

# Total 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 重置**：內建反偵測功能，可重置機器識別碼
- **連線池**：最佳化的連線管理

---

## 🐳 Docker Compose 部署（推薦，跨電腦通用）
使用 Docker Compose 可以讓代理在任何有 Docker 的電腦上一鍵啟動，**無需安裝 Go 環境**。
> **前提**：宿主機需已安裝 Cursor CLI（`agent` 二進位檔），且已登入至少一個帳號。

### Step 1 下載 cursor cli (如果你沒有) 
```bash
    curl https://cursor.com/install -fsS | bash
```
### Step 2 下載 claude (如果你沒有)
    windows 請參考 https://code.claude.com/docs/en/quickstart#native-install-recommended
```bash
    curl -fsSL https://claude.ai/install.sh | bash
```

### Step 3 下載 proxy

```bash
# 1. Clone 專案
git clone https://code.30cm.net/daniel.w/opencode-cursor-agent.git
cd cursor-api-proxy-go

# 2. 建立並編輯 .env（首次執行會提示你先填寫設定）
make docker-setup
```

第一次執行 `make docker-setup` 時，若尚未有 `.env`，它會自動幫你從 `.env.example` 複製，然後提示你填入必要設定後再執行一次。

```bash
# 3. 編輯 .env 後再次啟動
vim .env
make docker-setup
```

啟動後確認運作：

```bash
curl http://localhost:8766/health
```

### .env 關鍵設定

| 變數 | 說明                             | 範例 |
|------|--------------------------------|------|
| `CURSOR_AGENT_HOST_BIN` | 宿主機 Cursor agent 二進位檔的**完整路徑** | `/usr/local/bin/agent` |
| `CURSOR_ACCOUNTS_DIR` | 宿主機帳號資料目錄                      | `~/.cursor-api-proxy` |
| `WORKSPACE_DIR` | 要掛載進容器的工作區目錄                   | `/home/user/projects` |
| `CURSOR_BRIDGE_PORT` | 監聽連接埠（預設 8766）                 | `8766` |
| `CURSOR_BRIDGE_API_KEY` | API 鑑別金鑰（選用，建議設定）              | `my-secret-key` |
| `CURSOR_BRIDGE_TIMEOUT_MS` | 超時建議必選，否則可能用到一半被截斷             | `3600000` |

### 尋找 Cursor agent 路徑

```bash
# macOS / Linux
which agent 2>/dev/null || find /usr/local -name agent 2>/dev/null | head -5

# 如果 Cursor 是透過 AppImage 或自訂路徑安裝
find ~/.cursor -name agent 2>/dev/null | head -5
```

### Docker Compose 常用指令

```bash
make docker-setup       # 首次設定並啟動（自動複製 .env + build + up）
make docker-env         # 僅複製 .env.example 為 .env
make docker-build       # 重新建置映像檔
make docker-up          # 啟動容器（需已有 .env）
make docker-down        # 停止並移除容器
make docker-logs        # 查看即時日誌
make docker-restart     # 重新建置並啟動
make docker-shell       # 進入容器 shell（除錯用）
```

### 接入 Claude Code（Docker 模式）
```bash
# 代理啟動後，設定 Claude Code 使用代理
export ANTHROPIC_BASE_URL=http://localhost:8766
export ANTHROPIC_API_KEY=my-secret-key   # 若有設定 CURSOR_BRIDGE_API_KEY

# 或一鍵寫入 ~/.claude/settings.json
make claude-settings PORT=8766 ANTHROPIC_BASE_HOST=localhost
make claude-onboarding

claude
```

## 本機直接執行（pm2 模式）

### 1. 建置

```bash
git clone https://code.30cm.net/daniel.w/opencode-cursor-agent.git
cd cursor-api-proxy-go
go build -o cursor-api-proxy .
```

### 2. 登入 Cursor 帳號

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

### 3. 啟動伺服器

```bash
# 用 pm2 背景執行
make env PORT=8766 API_KEY=mysecret
make pm2
```

### 4. 設定 Claude Code

```bash
make claude-settings PORT=8766
make claude-onboarding
claude
```

---

## 接入 Claude Code

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

```bash
# 1. 啟動代理（Docker 或 pm2，確認已在背景執行）

# 2. 設定環境變數
export ANTHROPIC_BASE_URL=http://127.0.0.1:8766
export ANTHROPIC_API_KEY=my-secret-key   # 若未設定 API_KEY，填任意值

# 3. 啟動 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`（自動生成） |

---

## 接入 OpenCode

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

1. 啟動代理伺服器
2. 編輯 `~/.config/opencode/opencode.json`：

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

或使用指令一次設定：

```bash
make opencode PORT=8766
make opencode-models PORT=8766
```

---

## 模型對映原理

```
Claude Code                    OpenCode
  │                              │
  │  claude-opus-4-6             │  opus-4.6
  ▼                              ▼
┌──────────────────────────────────────┐
│        ResolveToCursorModel          │
│  claude-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 |

Cursor CLI 新增模型時自動生成對應 `claude-*` ID，無需手動更新。

---

## 帳號管理

```bash
# 登入
./cursor-api-proxy login myaccount

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

# 列出所有帳號
./cursor-api-proxy accounts

# 登出
./cursor-api-proxy logout myaccount

# 重置 HWID（反BAN）
./cursor-api-proxy reset-hwid

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

---

## API 端點

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

---

## 環境變數

### 伺服器設定

| 變數 | 預設值 | 說明 |
|------|--------|------|
| `CURSOR_BRIDGE_HOST` | `127.0.0.1` | 監聽位址（Docker 模式固定 `0.0.0.0`） |
| `CURSOR_BRIDGE_PORT` | `8766` | 監聽連接埠 |
| `CURSOR_BRIDGE_API_KEY` | _(無)_ | API 鑑別金鑰 |
| `CURSOR_BRIDGE_TIMEOUT_MS` | `3600000` | 請求逾時毫秒數（預設 1 小時） |
| `CURSOR_BRIDGE_MULTI_PORT` | `false` | 啟用多連接埠模式 |
| `CURSOR_BRIDGE_VERBOSE` | `false` | 啟用詳細日誌輸出 |

### Agent / 模型設定

| 變數 | 預設值 | 說明 |
|------|--------|------|
| `CURSOR_AGENT_BIN` | `agent` | Cursor CLI 二進位檔路徑 |
| `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` | _(自動探索)_ | 帳號設定目錄，多個用逗號分隔 |

### Docker 專用（.env 設定）

| 變數 | 說明 |
|------|------|
| `CURSOR_AGENT_HOST_BIN` | 宿主機 Cursor agent 二進位檔路徑（掛載進容器） |
| `CURSOR_ACCOUNTS_DIR` | 宿主機帳號資料目錄（掛載進容器） |
| `WORKSPACE_DIR` | 宿主機工作區目錄（掛載進容器） |

---

## 常見問題

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

**Q: Docker 容器裡找不到 agent？**
A: 確認 `.env` 的 `CURSOR_AGENT_HOST_BIN` 填的是宿主機上正確的路徑，容器會把它掛載到 `/usr/local/bin/agent`。

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

**Q: 可以在其他設備上使用嗎？**
A: 可以。Docker 模式下 `CURSOR_BRIDGE_HOST` 預設為 `0.0.0.0`，開放區域網路存取。其他設備將 `ANTHROPIC_BASE_URL` 指向這台電腦的 IP 即可。

**Q: 模型列表多久更新一次？**
A: 每次呼叫 `GET /v1/models` 時即時更新，自動生成對應的 `claude-*` ID。

---

## 授權

MIT License