# Cline 配置教程：Claude、GPT、Gemini、Grok 自定义 API

> 在 VS Code 安装 Cline，通过 Passion8 API Key 和自定义 Base URL 配置 Claude、GPT、Gemini、Grok，核对 Plan/Act、模型协议及工具调用。

URL: https://docs.passion8.cc/docs/cline
Language: zh-CN
Publisher: Passion8
Last updated: 2026-10-11

Cline 是可以读取项目、修改文件和运行命令的 VS Code 编程助手。你可以在同一个扩展里切换 Claude、GPT、Gemini 和 Grok；模型请求统一经过 Passion8。先准备控制台 API Key 和账号可用的模型 ID，再安装和配置扩展。

## 选对 Provider 与地址

Provider 决定请求协议，模型 ID 决定要调用的模型。名字带 GPT 不代表一定支持 Chat Completions，名字带 Gemini 也不代表必须选择 Google Provider。

| 模型 | Cline 的 API Provider | Base URL | 模型填写 |
| --- | --- | --- | --- |
| Claude | `Anthropic`，开启 `Use custom base URL` | `https://passion8.cc` | 控制台可用的 Claude ID，例如 `claude-sonnet-5-5` |
| GPT | `OpenAI Compatible` | `https://passion8.cc/v1` | 控制台支持 Chat Completions 的 GPT ID |
| Gemini | `OpenAI Compatible` | `https://passion8.cc/v1` | 控制台可用的 Gemini ID，例如 `gemini-3.8-flash-high` |
| Grok | `OpenAI Compatible` | `https://passion8.cc/v1` | 控制台可用的 Grok ID，例如 `grok-4.7` |

四种配置都填写 **Passion8 API Key**。表中的型号用于说明填写格式，是否可用取决于令牌权限与当前路由。




Cline 的 `OpenAI Compatible` 路径使用 Chat Completions；Codex 官方扩展使用 Responses。某个 GPT 模型能在 Codex 中用，不代表同一模型 ID 已开放 Chat Completions。若控制台只为该 ID 提供 Responses，使用 [Codex 官方扩展](https://docs.passion8.cc/docs/codex/ide)。不要把 `/responses` 或 `/chat/completions` 拼进 Base URL。




## 1. 安装扩展

在 VS Code 的扩展面板搜索 **Cline**，核对 [官方扩展条目](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev)，然后安装。打开项目文件夹，在活动栏打开 Cline 面板，点击设置图标进入 API 配置。

也可以在已经配置 `code` 命令的终端安装：

```bash
code --install-extension saoudrizwan.claude-dev
```

选择填写自己的 API Provider 和 Key 的入口即可。下面的教程直接连接 Passion8，不需要创建厂商账号。

## 2. 配置 Claude

在 Cline 设置中填写：

| 字段 | 值 |
| --- | --- |
| API Provider | `Anthropic` |
| Anthropic API Key | 你的 Passion8 API Key |
| Use custom base URL | 开启 |
| Base URL | `https://passion8.cc` |
| Model | 与控制台一致的 Claude 模型 ID |

`Anthropic API Key` 是扩展里的字段名称，这里填的是 Passion8 密钥。自定义地址必须开启，否则请求会发到默认 Anthropic 地址。

原生 Anthropic 路径有利于保留 Claude 的消息、工具和缓存语义。如果 Cline 的 Model 下拉还没有控制台的新型号，先更新扩展；若更新后仍未列出，不要把旧型号的能力参数套到新型号上。可以选择账号已开放、扩展也支持的 Claude 型号，或使用 [Claude Code 官方扩展](https://docs.passion8.cc/docs/claude-code/vscode) 显式配置模型。

## 3. 配置 GPT、Gemini 或 Grok

三者的填写方式一致，只更换模型 ID：

| 字段 | 值 |
| --- | --- |
| API Provider | `OpenAI Compatible` |
| Base URL | `https://passion8.cc/v1` |
| API Key | 你的 Passion8 API Key |
| Model ID | 从控制台复制、支持 Chat Completions 的精确模型 ID |

如果模型列表没有所需 ID，使用 **Use custom model ID…** 或版本中对应的手动输入框。列表刷新失败不等于推理一定失败，可以先手填准确 ID 再发一个小请求验证。

首次连接保持默认高级选项：不用填写 Azure API version，也不用开启 Azure Identity Authentication；不要附加官方账号凭据。只有遇到模型明确要求的参数时，再按该模型说明调整。

### Gemini 的原生 Provider 怎么选

本教程推荐 Gemini 使用上面的 OpenAI Compatible 路径。Cline 官方 Gemini 配置页没有列出稳定通用的自定义地址步骤；部分版本的底层实现支持 Gemini Base URL，但设置界面会随版本变化。

只有已安装版本明确提供 Gemini 的自定义 Base URL，并且能填写控制台的精确模型 ID 时，才使用原生路径：Provider 选 Google Gemini，自定义根地址填 `https://passion8.cc`，Key 填 Passion8 Key。原生路径会请求 Gemini `/v1beta/models/...`；这里不要填 `https://passion8.cc/v1`。找不到自定义地址入口时，继续使用 OpenAI Compatible 即可。

## 4. 核对 Plan 和 Act

Cline 的 **Plan** 用于讨论方案和读取上下文，**Act** 用于执行已确认的改动。设置可以允许两个模式使用不同 Provider 与模型。

首次配置建议两种模式使用同一套 Passion8 地址、Key 和模型。若已开启分别配置，请切到 Plan 和 Act 各检查一次；只改一个模式，切换后可能仍然调用旧 Provider。

之后可以用响应快的模型梳理需求，再用更适合复杂修改的模型执行。但跨厂商切换会改变工具、推理和上下文格式，切换模型后优先新建任务，并把已确认的方案写入项目文件或下一条提示。

## 5. 重启并验证

保存设置后执行 VS Code 命令 **Developer: Reload Window**，重新打开 Cline，建立新任务。先发送：

```text
用一句话回复“连接成功”。不要读取文件、修改文件或执行命令。
```

正常返回后，到 Passion8 控制台核对同一时间的请求记录、模型和用量。模型自述身份不能证明实际路由，控制台记录更直接。

接着验证项目读取：

```text
只读取 package.json，说明项目使用的框架和测试命令。不要修改文件或运行命令。
```

最后再给一个范围明确的小改动：要求它先说明计划、只修改指定文件、运行已有的相关检查，再审阅 diff。文本聊天正常不等于该模型的工具调用和流式响应都已兼容，文件读取与小改动可以分别验证这两步。

## 项目规则与任务上下文

在项目根目录创建 `.clinerules/project.md`，把构建命令、代码约定和验收要求写进去。当前 Cline 支持 `.clinerules/` 和 `.cline/rules/` 两种目录，选择一种即可；VS Code 的 Rules 面板默认在 `.clinerules/` 创建项目规则。

```markdown title=".clinerules/project.md"
# Project rules

- Read the existing implementation before changing it.
- Preserve unrelated local changes.
- Use the package manager specified by the lockfile.
- Keep each change within the requested file scope.
- Run the relevant existing checks and report the actual results.
```

在 Cline 的 Rules 面板确认规则已启用。把项目真实的启动、测试命令补进去，不要照抄不存在的命令。规则文件不包含 Key；同一份项目规则可以用于不同模型。

新任务中先引用需要处理的文件，说明目标和验收条件，再让模型读取实现。大项目先搜索定位，再读取相关文件，避免每次发送整个仓库。不要假定 Grok Build 的 `AGENTS.md` 或 Gemini CLI 的 `GEMINI.md` 与 Cline 的规则入口相同。

## 模型能力和成本设置

`Model Configuration` 中的 **Context Window Size**、**Max Output Tokens**、图片能力和价格用于帮助 Cline 管理任务与估算成本。它们不会扩大上游模型能力，也不会改变 Passion8 的实际计费。

| 设置 | 怎么填 |
| --- | --- |
| Context Window Size | 当前模型与路由实际支持的窗口；不要统一填 100 万 |
| Max Output Tokens | 不超过当前模型的输出上限；长输出会增加延迟和用量 |
| 图片能力 | 只有所选模型和路由确实支持时才启用 |
| 推理选项 | 只选模型支持的档位；不要给所有厂商照搬同一字段 |
| 输入/输出价格 | 用于本地估算，账单以 Passion8 控制台为准 |
| Prompt caching | 是否命中取决于协议、模型和请求前缀，不能只靠开关保证 |

自动批准读取、写入和终端命令是独立权限。第一次使用保留人工批准，确认工具请求和修改范围后再调整。

## 常见问题

| 现象 | 先检查 |
| --- | --- |
| `401` / Invalid API Key | Key 是否完整、有效；Provider 地址是否仍是默认官方域名 |
| `403` / 模型无权限 | 令牌模型限制、账号分组和控制台可用模型 |
| `404` / Model not found | 精确模型 ID；地址是否误填完整端点；GPT 是否只开放 Responses |
| 聊天成功但无法读写文件 | 工具调用是否被所选模型和路由支持；是否在等待人工批准 |
| 切换到 Act 后失败 | 两个模式是否都保存了 Passion8 配置 |
| 提示 Azure API version | 是否误开 Azure 选项或选了 Azure Provider |
| Gemini 请求到了 Google | 原生 Provider 没有真正应用自定义地址；改用 OpenAI Compatible |
| 长任务报上下文超限 | 校正窗口、缩小上下文；总结进度后新建任务 |
| 估算费用与账单不同 | 本地价格与缓存估算不是网关结算；查看控制台实际用量 |

## 配置问答

### Cline 是 Claude、GPT、Gemini 或 Grok 的官方插件吗？

不是。Cline 是第三方客户端，可以连接不同厂商的模型。希望使用官方客户端时，Claude 可选择 [Claude Code VS Code 扩展](https://docs.passion8.cc/docs/claude-code/vscode)，GPT 可选择 [Codex IDE 扩展](https://docs.passion8.cc/docs/codex/ide)；两者有各自的配置入口。Gemini 与 Grok 在本站的编辑器路径见 [Gemini VS Code](https://docs.passion8.cc/docs/gemini/vscode) 和 [Grok VS Code](https://docs.passion8.cc/docs/grok/vscode)。

### 填 Passion8 Key 后，为什么仍打开厂商登录？

这里使用 API Key 配置，不需要厂商账号。检查是否选择了官方登录 Provider，或没有启用自定义 Base URL；同时核对 Plan 和 Act 两种模式。还没有本站 Key 时，先按 [快速开始](https://docs.passion8.cc/docs/quickstart) 创建令牌。

### Codex 能使用的 GPT 模型，为什么在 Cline 中报错？

Codex 使用 Responses，Cline 的 OpenAI Compatible 使用 Chat Completions。同一模型 ID 是否同时支持两种协议，取决于本站当前路由。先核对控制台的模型与协议，再按错误正文排查；只有 Responses 路径时，使用 [Codex IDE 配置](https://docs.passion8.cc/docs/codex/ide)。

## 接着看



- [Claude 官方 VS Code 扩展](https://docs.passion8.cc/docs/claude-code/vscode): 原生 Claude Code 面板，用 Passion8 网关变量完成配置。
- [Codex 官方 IDE 扩展](https://docs.passion8.cc/docs/codex/ide): 共享 config.toml 和 API Key，使用 Responses 路径。
- [Gemini 接入](https://docs.passion8.cc/docs/gemini): 编辑器、API 与保留的 CLI 接入路径。
- [Grok 接入](https://docs.passion8.cc/docs/grok): Grok 的客户端选择、模型和配置。



## 官方参考

- [Cline OpenAI Compatible](https://docs.cline.bot/provider-config/openai-compatible)
- [Cline Anthropic / Claude Code](https://docs.cline.bot/provider-config/anthropic)
- [Cline Google Gemini](https://docs.cline.bot/provider-config/google-gemini)
- [Cline Plan and Act](https://docs.cline.bot/features/plan-and-act)

- [Cline Rules](https://docs.cline.bot/features/cline-rules)