# Cline 自定义 API Key 配置

> 在 Cline 中配置自定义 API Key、OpenAI 兼容 Base URL 与 Model ID，并排查无效密钥、401、404、模型不存在和连接失败。

- Canonical HTML: https://omniakey.com/zh/blog/cline-custom-api-key
- Markdown: https://omniakey.com/zh/blog/cline-custom-api-key.md
- Published: 2026-08-11 (updated 2026-09-21)
- Author: Kiki, COO at OmniaKey
- Language: zh
- Category: API setup
- Reading time: 9 min
- All posts: https://omniakey.com/blog/llms.txt

---

Cline 是编程客户端，API provider 负责提供模型、校验请求并按 Token 计费。Cline 自定义 API Key 配置只是把两层连接起来，不会让付费模型变免费，也不能绕过 provider 的权限规则。

Cline 官方的 OpenAI Compatible 配置正好提供这条连接需要的字段：API Provider、Base URL、API Key 和 Model ID。通过 OmniaKey，可以用同一把 Key 调用已支持的 Claude、GPT、Gemini、DeepSeek 等模型。

> **核验日期：2026 年 8 月 11 日。** Cline 官方文档明确列出了 OpenAI Compatible provider、Base URL、API Key、Model ID 和 Verify 流程。模型供应与价格会变化，请从 OmniaKey 当前模型目录复制 ID。

## Cline 自定义 API Key 应该怎么填

在 VS Code 打开 Cline，进入设置后填写：

|字段|值|
|-|-|
|API Provider|`OpenAI Compatible`|
|Base URL|`https://api.omniakey.com/v1`|
|API Key|在 OmniaKey Dashboard 创建的 Key|
|Model ID|准确的已支持 ID，例如 `gpt-5.6-terra`|

`/v1` 是 OpenAI 兼容 Base URL 的一部分。这里不要只填裸域名，也不要手动追加 `/chat/completions`，具体请求路径由 Cline 生成。

## 分步配置 Cline

### 1. 单独创建一把 API Key

登录 OmniaKey，充值预付余额，然后新建 API Key。为 Cline 单独用一把 Key，比所有工具共用凭据更容易限额、轮换和查用量。

不要把 Key 写进源码、仓库文件、Issue 或截图，只粘贴到 Cline 的 API Key 字段。

### 2. 选择 OpenAI Compatible

打开 Cline 设置，在 API Provider 中选择 `OpenAI Compatible`。如果 Key 来自其它 provider，不要选择官方 OpenAI 项；provider 类型会决定 Cline 使用哪些字段和请求入口。

### 3. 填写 Base URL

准确填写：

```text
https://api.omniakey.com/v1
```

常见错误包括少写 `/v1`、重复成 `/v1/v1`，以及填入完整的 `/v1/chat/completions` 请求路径。

### 4. 填写准确的 Model ID

先从 [OmniaKey 模型目录](https://omniakey.com/zh/models)选一个当前存在的模型：

|Model ID|适合先从什么任务开始|
|-|-|
|`claude-opus-5`|需要深入调查的复杂仓库任务|
|`gpt-5.6-terra`|能力与成本较平衡的日常编程|
|`gemini-3.1-pro-preview`|需要 Gemini 系列的长上下文实验|
|`deepseek-v4-flash`|更看重成本和速度的编程、Agent 任务|

这些不是模糊别名。大小写、连接符和版本后缀都有意义，最好直接复制，不要凭记忆手打。

### 5. 正式改代码前先验证

如果当前 Cline 界面显示 Verify，先点它验证连接。然后运行一个窄且可逆的任务：

```text
读取 package.json，告诉我项目使用哪个包管理器。不要修改文件。
```

一次有效验证应确认：

1. Cline 接受了自定义 provider 配置。
2. provider 接受了 API Key。
3. 当前 Key 能访问准确的模型 ID。
4. 简单响应能正常返回，没有进入编辑或工具循环。

确认后再交付会改仓库的任务。更完整的工作流见 [编程 Agent 接入总览](https://docs.omniakey.com/cn/coding)。

## Cline BYOK 怎么计费

BYOK 即 Bring Your Own Key。Cline 用你提供的 provider 配置发送请求，模型用量由该 provider 账号结算。它不是把收费 API 变成免费接口。

复盘时要看输入、缓存输入和输出 Token，不能只看最终答案长度。Agent 还会产生仓库上下文、工具调用、重试与中间步骤。[透明计费指南](https://omniakey.com/zh/blog/transparent-billing)解释了为什么按完成任务成本比较更可靠。

如果模型还没选定，先看 [编程 Agent 模型对比](https://omniakey.com/zh/blog/best-llm-coding-agents)，再优化 Cline 配置。 接的不是 IDE 插件而是桌面客户端的话，见[Cherry Studio 第三方 API 配置](https://omniakey.com/zh/blog/cherry-studio-api-setup)和[WorkBuddy 自定义模型配置](https://omniakey.com/zh/blog/workbuddy-custom-model-setup)。Claude Code 的话，见[Claude Code 配置教程](https://omniakey.com/zh/blog/claude-code-setup)。

## Cline API Key 不工作怎么排查

### Invalid API Key 或 HTTP 401

`401` 表示 endpoint 没有接受请求携带的凭据。检查：

- Key 是否来自 Base URL 对应的同一个 provider；
- 粘贴时是否带了前后空格；
- Key 是否仍有效、未被轮换或删除；
- 账号是否有可用余额；
- Cline 是否仍选择 `OpenAI Compatible`。

鉴权失败时更换 Model ID 没有用。

### Model Not Found 或 HTTP 404

`404` 既可能是 Base URL 错误，也可能是 Model ID 不存在。先确认 URL 只以一个 `/v1` 结尾，再从目录复制准确 ID。

如果同一个 endpoint 能调用另一款已列出的模型，说明连接本身有效，剩下就是模型命名或权限问题。

### Connection error

确认运行 Cline 的同一台机器能访问 `https://api.omniakey.com/v1`。VPN、代理、DNS、TLS 检查和防火墙都可能影响 IDE，即使另一台设备上的浏览器能打开官网。

不要通过关闭 TLS 校验来掩盖证书错误，应修复网络或信任配置。

### 能回答文字，但工具调用失败

一次文本回复只证明基础生成成功。Cline 还依赖结构化工具调用去读文件、编辑和执行命令。先测只读仓库任务，再做大规模自主修改。

如果模型反复生成错误工具调用，应换用明确适合 Agent 的模型比较，而不是盲目提高输出上限。

### 消耗比预期高

仓库上下文很长时，即使最终回答很短，输入也可能主导账单。收窄任务，排除无关目录，并按被接受的改动比较成本。

实验使用独立 Key 或限额。限额只控制最大财务风险，不会减少低效任务已经消耗的 Token。

## 安全检查清单

- Cline 使用独立 Key，不和生产服务共用。
- 按项目和任务规模设置合理限额。
- Key 若进入仓库、录屏、截图或 Issue，立即轮换。
- 允许 Shell 命令或文件编辑前检查工具权限。
- 新仓库或不可信仓库先从只读任务开始。
- 第一次成功会话后检查 provider 用量记录。

API Key 控制模型访问；Cline 的文件和命令权限控制 Agent 在本机能做什么。这是两条独立安全边界。如果应用是用 Lovable 做的，可以看[Lovable API Key 填在哪](https://omniakey.com/zh/blog/lovable-api-key)。

## 常见问题

### Cline 能使用我自己的 API Key 吗？

可以。选择 `OpenAI Compatible`，然后填写 provider 的 Base URL、API Key 和准确 Model ID。provider 需要提供 Cline 所需的兼容接口。

### Cline 自定义 API Key 是免费的吗？

不是。BYOK 只是改变模型请求由谁鉴权和结算，provider 仍可对输入、缓存输入与输出 Token 收费。

### Cline 接 OmniaKey 的 Base URL 是什么？

使用 `https://api.omniakey.com/v1`。不要追加 `/chat/completions`，也不要重复 `/v1`。

### Cline 应该选择哪个模型？

从目录中选择适合任务的当前模型。`gpt-5.6-terra` 可作为较平衡的起点，再根据真实任务验收结果决定换更强或更便宜的模型。

### 为什么 Cline 显示 Model Not Found？

核对 Model ID 和 Base URL。API Key 有效不代表能访问每个模型，错误 URL 也会返回 `404`。

### Cline 会把 Key 存进仓库吗？

provider 凭据应该只放在 Cline 设置中，不写入项目文件。无论客户端内部如何保存，都不要把 Key 复制进源码、Prompt、截图或 Issue。

## 核验来源

- [Cline：OpenAI Compatible provider](https://docs.cline.bot/provider-config/openai-compatible)
- [Cline：Authorization 与 BYOK](https://docs.cline.bot/getting-started/authorizing-with-cline)
- [OmniaKey Cline 配置参考](https://docs.omniakey.com/cn/guides/cline)
- [OmniaKey 模型目录](https://omniakey.com/zh/models)
