# Cline 集成

> **最后核实**：2026-09-18 · 📄 依据官方文档（VS Code 扩展 4.1.19，2026-09-17 发布；Cline Desktop 见下文）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（方式 A：Anthropic provider）· GPT ✅ · 国产 ✅（方式 B：OpenAI Compatible）· Gemini ❌（本页未写 Gemini 接法） |
| 协议与 Base URL | Anthropic：`https://api.qcode.cc/api` · OpenAI：`https://api.qcode.cc/openai/v1` |
| 配置位置 | VS Code 扩展设置面板（API Provider + Use custom base URL 勾选）；桌面版同逻辑 |
| 官方文档 | [cline.bot](https://cline.bot) · [GitHub](https://github.com/cline/cline) |

[Cline](https://github.com/cline/cline) 是一款 VS Code AI 编程扩展（数百万安装量），支持任意 AI 模型和自定义 API 端点。它内置 Plan / Act 双模式、文件编辑预览、终端执行和 MCP 工具调用。通过 Cline 配合 QCode.cc API，你可以在 VS Code 中以低成本使用 Claude、GPT 以及 [国产模型](/docs/usage/cn-models)。

## 为什么选择 Cline？

- **零加价**：不对模型费用加价，你只需支付 QCode.cc API 费用

- **多模型灵活切换**：同一个界面切换 `claude-sonnet-5`、`claude-opus-5`、`gpt-5.6-terra` 等模型（4.x 仍可用）

- **VS Code 深度集成**：侧边栏面板、内联代码操作、文件编辑 diff 预览、自动审批

- **Plan / Act 双模式**：先规划再执行，复杂改动可控

- **完全开源**：代码透明，社区活跃

- **MCP 支持**：通过 Model Context Protocol 接入数据库、浏览器、文档等外部工具

## 安装与配置

### 步骤 1：安装 Cline 扩展

在 VS Code 中：

1. 打开扩展面板（`Ctrl+Shift+X` / `Cmd+Shift+X`）

2. 搜索 **"Cline"**

3. 点击 **安装**

4. 安装后，左侧活动栏会出现 Cline 图标

> Cline 也提供命令行版本（Cline CLI），同一套配置可在终端复用；本文以 VS Code 扩展为主。

### 步骤 2：配置 QCode.cc API

QCode.cc 同一把 API 密钥（`cr_` 开头）同时兼容 Anthropic 协议和 OpenAI 协议。Cline 提供两种对接方式，**任选其一**即可：

#### 方式 A：Anthropic 兼容（推荐用于 Claude 模型）

在 Cline 设置（齿轮图标）的 **API Provider** 下拉菜单中选择 **"Anthropic"**，然后填入：

| 配置项 | 值 |
|--------|-----|
| API Key | 你的 QCode.cc API 密钥（`cr_` 开头） |
| Use custom base URL | 勾选并填 `https://api.qcode.cc/api` |
| Model | `claude-sonnet-5`（日常默认）或 `claude-opus-5`（难任务）。`claude-sonnet-4-6` / `claude-opus-4-8` 仍在售 |

> SDK 会在 Base URL 之后自动追加 `/v1/messages`，因此 Base URL 填到 `/api` 即可，**不要**写成 `/api/v1/messages`，也**不要**带末尾斜杠。

#### 方式 B：OpenAI 兼容

在 **API Provider** 下拉菜单中选择 **"OpenAI Compatible"**，然后填入：

| 配置项 | 值 |
|--------|-----|
| Base URL | `https://api.qcode.cc/openai/v1` |
| API Key | 你的 QCode.cc API 密钥（`cr_` 开头） |
| Model ID | `gpt-5.6-terra`、`gpt-5.5`，或 [国产 id](/docs/usage/cn-models) 如 `glm-5.2`。**不能填 `claude-*`** |

> 🔴 **OpenAI 兼容模式用不了 Claude。** QCode 的 OpenAI 端点只服务 GPT 系与国产四家族，填 `claude-*` 会返回 `model_not_available_on_endpoint`。要用 Claude 请回到上面的**方式 A（Anthropic）**，Base URL 填 `https://api.qcode.cc/api`。对照表见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

### 步骤 3：验证连接

在 Cline 聊天框中输入一条简单消息（如 "Hello"），如果收到回复则配置成功。

你也可以在终端用 curl 自检（返回 `401` 说明路径正确、仅缺鉴权）：

```bash
# Anthropic 协议
curl -i https://api.qcode.cc/api/v1/messages \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

# OpenAI 协议（注意：这条腿只能填 GPT 系或国产 id）
curl -i https://api.qcode.cc/openai/v1/chat/completions \
  -H "content-type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"hi"}]}'
```

## 备用节点

同一把密钥可用于 4 个接入域名，互为备份。如主域名连接不稳定，把 Base URL 中的 `api` 换成下表对应的子域即可：

| 节点 | Anthropic 协议 Base URL | OpenAI 协议 Base URL |
|------|--------------------------|----------------------|
| 默认 | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` |
| 亚太（中国大陆优先） | `https://asia.qcode.cc/api` | `https://asia.qcode.cc/openai/v1` |
| 美国 | `https://us.qcode.cc/api` | `https://us.qcode.cc/openai/v1` |
| 欧洲 | `https://eu.qcode.cc/api` | `https://eu.qcode.cc/openai/v1` |

> 中国大陆用户建议优先使用 `asia.qcode.cc`，通常延迟最低。更多说明见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

## Cline Desktop

2026-09-14，Cline 发布桌面版（[官方公告](https://cline.bot/blog/cline-desktop-an-open-source-app-for-open-weight-models)，原文：*"Bring your own API key and connect natively to any provider — Anthropic, OpenAI, Gemini, open-weight models, or a local endpoint"*；[产品页](https://cline.bot/desktop) 未标发布日期）。桌面版沿用与扩展一致的 provider 配置思路（选 API Provider + 自定义 Base URL）；官方文档未单列桌面端的字段名称，以应用内实际界面为准。下载与平台支持见 [cline.bot/desktop](https://cline.bot/desktop)。

## Plan / Act 双模式

Cline 在聊天框下方提供 **Plan** 与 **Act** 两个模式切换：

- **Plan（规划）**：Cline 先阅读代码、提问、给出实现方案，但**不**修改文件。适合在动手前对齐需求。

- **Act（执行）**：Cline 实际创建/编辑文件、运行命令、调用工具，每步改动以 diff 形式展示，由你审批或自动批准。

典型工作流：先在 **Plan** 模式让模型梳理方案并确认，再切到 **Act** 模式逐步落地。复杂任务建议用 `claude-opus-5` 做规划，再用 `claude-sonnet-5` 执行。4.x 仍可当对照。

## 使用技巧

### 1. 模型选择建议

| 场景 | 推荐模型 | 说明 |
|------|---------|------|
| 日常编码 | `claude-sonnet-5` | 当前平衡档，1M / 128K；写本文时输入单价低于 4.6 |
| 复杂架构设计 / Plan 规划 | `claude-opus-5` | 当前旗舰。`claude-opus-4-8` 仍在售 |
| 轻量任务 / 改文案 | `claude-haiku-4-5` | 费用最低 |
| 需要 GPT 风格 | `gpt-5.6-terra` | OpenAI 协议下可直接选用 |
| 国产对照 / 更低单价 | `glm-5.2` / `deepseek-v4-pro` | 见 [国产模型接入](/docs/usage/cn-models) |

完整价格见 [计费说明](/docs/reference/billing)。

### 2. 配置 MCP 工具

Cline 支持 Model Context Protocol（MCP），可让模型调用外部工具（数据库查询、浏览器、文档检索等）。在 Cline 的 **MCP Servers** 面板中添加服务器配置：

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    }
  }
}
```

MCP 服务器与上游模型解耦，无论你用 Anthropic 还是 OpenAI 协议接入 QCode.cc，工具调用都正常工作。具体服务器的安装与参数请以各工具官方文档为准。

### 3. 项目级自定义指令（.clinerules）

在项目根目录创建 `.clinerules` 文件，可为该仓库注入固定上下文，例如代码风格、技术栈约定、目录结构说明。Cline 每次对话都会带上这些规则，无需重复粘贴：

```text
# .clinerules
- 全部使用 TypeScript，严格模式
- 优先复用 src/lib 下的工具函数
- 提交前运行 `pnpm test`
```

规则文件的字段与高级用法以 Cline 官方文档为准。

### 4. 图像输入（读图）

`claude-opus-5`、`claude-sonnet-5`（以及仍在售的 4.8 / 4.6）与 GPT-5.x 均支持视觉输入。你可以把界面截图、报错截图或架构图直接拖入 Cline 聊天框，让模型据图编码或排错。

> 注意：这里说的是让模型**读图**。如需**生成图像**，请使用 [gpt-image-2 图像生成](/docs/usage/image-2)，模型名 `gpt-image-2`。

### 5. 自动审批与成本控制

- 在设置中可为「读文件」「写文件」「执行命令」分别开启 **Auto-approve**，减少打断；高风险操作建议保留人工确认。

- Cline 会显示每次请求的 token 用量与估算费用，便于控制开销。复杂任务用 Plan 先收敛范围，可避免无谓的来回。

- 对大型代码库，建议用 `@`（提及文件/文件夹/URL）精确投喂上下文，而不是让模型盲读整个工程，既省 token 又更聚焦。

### 6. 与 Claude Code CLI 配合

Cline 和 Claude Code CLI 各有优势，推荐配合使用：

| 场景 | 推荐工具 |
|------|----------|
| VS Code 内快速编辑 | Cline |
| 复杂项目分析 | Claude Code CLI |
| 多文件重构 | Cline |
| Git 操作、代码审查 | Claude Code CLI |
| 大规模代码库迁移/审查 | Claude Code CLI（[子代理](/docs/advanced/subagents)） |
| CI/CD 自动化 | Claude Code CLI（[headless 模式](/docs/advanced/headless)） |

### 7. 共享配额

Cline 和 Claude Code CLI 使用同一个 QCode.cc API 密钥，共享套餐配额，无需为不同工具单独申请密钥。

## 常见问题

### 连接失败 / 401 / 404？

1. 确认 Base URL 末尾**没有**多余的 `/`

2. Anthropic 模式 Base URL 应填到 `/api`（SDK 自动补 `/v1/messages`），不要手动写全路径

3. OpenAI 模式 Base URL 应填到 `/openai/v1`

4. 检查 API 密钥是否以 `cr_` 开头且复制完整

5. 尝试切换备用节点（如改用 `asia.qcode.cc`）

6. 确认网络可以访问 QCode.cc 服务

### 模型列表为空？

OpenAI 兼容模式下，手动在 Model ID 输入框中填写模型名称（如 `glm-5.3`），不需要从列表选择。

### Plan 模式不改文件？

这是预期行为。Plan 模式只规划不落地，切换到 Act 模式后改动才会写入。

### 报错 401 但配置看起来正确？

`401` 通常表示路径正确、仅鉴权失败。请重新核对 API Key 是否完整、是否选对了 Provider 类型（Anthropic vs OpenAI Compatible）与对应 Base URL。

## 下一步

- 查看 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) 了解全部协议与域名

- 查看 [Aider 集成](/docs/ide/aider) 了解另一个兼容 QCode.cc 的开源工具

- 查看 [VS Code 集成](/docs/ide/vscode) 使用 Claude Code 官方扩展

- 查看 [国产模型接入](/docs/usage/cn-models) 用同一套 OpenAI 兼容填法调 GLM / Kimi / DeepSeek / Qwen

- 查看 [计费说明](/docs/reference/billing) 了解定价详情

> 还没有 API 密钥？[查看 QCode.cc 套餐与定价 →](https://qcode.cc/pricing)