Cline 怎么配置 API 密钥？从 Provider 到首次请求
简答：Cline 不一定需要单独填写 API 密钥：选择 Cline Provider 可以登录使用，Ollama 或 LM Studio 等本地运行时通常不需要云端 Key；只有选择 Anthropic、OpenAI、Gemini、OpenRouter 或 OpenAI Compatible 等 BYOK Provider 时，才需要填写对应服务商的 API Key。VS Code 中打开 Cline 面板的设置图标，选择 API Provider，再按服务商填写 API Key、Base URL 和 Model ID，最后用 Verify 或一个最小任务测试。
定义：Cline 的 API 密钥配置，是把服务商、认证密钥、接口根地址和真实模型 ID 四项信息绑定到 Cline 的 Provider 设置中。
先看配置对照表：你是否真的需要 API Key
截至 2026 年 10 月 27 日，Cline 官方文档把接入方式分为账号登录、BYOK 云服务商密钥和本地运行时等路径。先按下面的场景选择，不要把 Cline 登录凭证和 Anthropic、OpenAI 等服务商的 API Key 混为一谈。具体 Provider 名称和界面可能随 Cline 版本变化，应以当前设置页为准。参考 Cline 官方 Authorization 文档。
| 使用场景 | Provider 选择 | 是否需要 API Key | 需要填写的内容 |
|---|---|---|---|
| Cline 账号提供的模型服务 | Cline | 通常不需要单独粘贴服务商 Key | 登录并完成授权 |
| 自带 Anthropic 密钥 | Anthropic | 需要 | API Key、模型 ID；其他字段按当前页面要求 |
| 自带 OpenAI 密钥 | OpenAI | 需要 | API Key、模型 ID |
| 通过统一网关调用多个模型 | OpenRouter | 需要 | API Key、模型 ID；Base URL 按 Provider 预置或官方文档填写 |
| Google Gemini API | Google Gemini | 需要 | Gemini API Key 和可用模型 |
| 本机运行模型 | Ollama 或 LM Studio | 通常不需要云端 Key | 本地服务地址和本地模型名称 |
| 其他兼容接口 | OpenAI Compatible 或相近名称 | 通常需要 | Base URL、API Key、Model ID |
如果你的目标只是让 Cline 开始工作，优先先确认 Provider，而不是直接反复更换 Key。Provider 选错时，即使密钥本身有效，也可能出现 401、404 或模型不可用。
VS Code 插件中配置 Cline API Key 的步骤
- 打开 Cline 设置。在 VS Code 的 Cline 面板中点击齿轮图标，进入当前版本的模型或 Provider 设置。Cline 官方安装说明也要求安装扩展后在 Cline 设置中完成 Provider 配置，参见 Cline 官方安装文档。
- 选择 API Provider。如果使用自己的云端密钥，选择对应的 Anthropic、OpenAI、Google Gemini、OpenRouter 或 OpenAI Compatible 选项；不要仅凭模型展示名称猜 Provider。
- 创建或找到服务商 API Key。OpenAI 的官方快速入门说明应先在控制台创建 API Key；Anthropic 的 Claude Platform 文档说明密钥在 Claude Console 的 API keys 页面创建；Gemini 密钥在 Google AI Studio 管理；OpenRouter 则从其控制台创建 Key。可分别查看 OpenAI 官方快速入门、Anthropic 官方认证文档、Gemini 官方 API Key 文档 和 OpenRouter 官方开发者页面。
- 粘贴 API Key。只粘贴完整密钥，不要把引号、换行、前后空格或环境变量名称一起粘贴。密钥通常只在创建时完整显示，创建后无法查看时应重新生成，而不是猜测缺少的字符。
- 填写 Base URL。如果 Provider 已经预置官方端点，通常不要自行覆盖。若使用 OpenAI Compatible，应填写服务商明确给出的根地址；是否保留
/v1必须以该服务商文档为准，不要填写完整的/chat/completions路径，除非当前 Provider 明确要求这样做。对无法核实的中转域名、路径或版本，不要直接复制到配置中。 - 选择 Model ID。Model ID 必须来自服务商模型列表或当前 Provider 的可选项。展示名称和实际 ID 可能不同，例如 OpenRouter 官方接口使用作者与模型的 slug 形式，不能凭简称手写。
- 验证连接。如果页面有 Verify、Test 或保存后测试按钮，先执行验证；没有验证按钮时，发送一个短任务，例如“只回复 OK”。测试通过后再执行代码修改、工具调用或长上下文任务。
最小检查清单：Provider 是否对应密钥来源；Key 是否完整且无空格；Base URL 是否为服务商明确提供的地址；Model ID 是否真实存在；账户是否有额度、权限或项目访问权。
OpenAI Compatible 的通用配置模板
如果你使用的是兼容 OpenAI Chat Completions 格式的服务，配置通常围绕以下四项展开，但字段名称和界面仍可能随 Cline 版本变化：
| 字段 | 填写什么 | 不要怎么填 |
|---|---|---|
| API Provider | OpenAI Compatible 或当前版本中含义相同的选项 | 不要把服务商名称当成模型 ID |
| Base URL | 服务商文档给出的 API 根地址 | 不要默认追加或删除 /v1；不要填写完整接口路径 |
| API Key | 服务商生成的密钥原文 | 不要粘贴 Authorization: Bearer 前缀 |
| Model ID | 服务商返回或文档列出的真实模型标识 | 不要使用网页显示名、中文名或猜测的型号 |
以 OpenRouter 为例，其官方开发者页面公开的 OpenAI 兼容 API 根地址是 https://openrouter.ai/api/v1，请求使用 Bearer API Key，并通过模型作者与 slug 选择模型。若在 Cline 中选择了专用 OpenRouter Provider，应优先使用该 Provider 的预置逻辑；只有界面要求手动输入时，才按官方地址填写。
对其他网关或中转服务，不能因为它们声称“兼容 OpenAI”就推断路径、模型名、工具调用和流式响应一定相同。遇到未公开说明的字段，应以该服务当前文档为准。
Cline CLI：用 cline auth 配置密钥
本节只适用于 Cline CLI，不等同于 VS Code 插件设置。Cline 官方 CLI 文档提供交互式认证和非交互式参数，安装、Provider 和参数名称可能随版本更新，使用前可先运行 cline --help。
- 安装 CLI：
npm install -g cline。 - 启动交互式配置：
cline auth。 - 非交互式配置时，可按官方参数传入 Provider、Key、Model ID，必要时再传 Base URL：
cline auth --provider anthropic --apikey "$ANTHROPIC_API_KEY" --modelid claude-sonnet-4-6。 - 查看当前 CLI 是否可用：
cline version；配置完成后运行一个短任务：cline "Reply with OK only"。
官方 CLI 参考文档列出了 --provider、--apikey、--modelid 和 --baseurl 参数，也说明了 --key 会优先于环境变量。详情见 Cline CLI 官方参考 和 Cline CLI 官方 README。
安全做法：临时测试可使用当前终端的环境变量，不要把真实 Key 写进 Git 仓库、项目配置、截图、Issue 或提示词。CLI 还可能写入本地配置和日志；如果日志中出现密钥，应立即撤销并重建。命令行示例中的环境变量只是占位符，实际名称要按 Provider 和当前 CLI 文档确认。
401、403、404、429 怎么排查
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| 401 Unauthorized | Key 是否错误、过期、被撤销或粘贴了空格 | 重新复制密钥；确认 Provider 与密钥来源一致；必要时在服务商控制台重建 Key |
| 403 Forbidden | 项目、组织、工作区或模型权限 | 确认账户已开通 API、当前 Key 有对应项目权限，并检查服务商的组织或工作区限制 |
| 404 Not Found | Base URL、/v1、Model ID 或路径 | 删除手写的完整接口路径，回到服务商文档核对根地址和模型真实 ID |
| 429 Too Many Requests | 限速、并发、余额或账户额度 | 查看服务商用量与限额；降低并发和请求频率，等待后重试，不要只重复创建 Key |
| 模型不可用 | 模型是否属于当前 Provider、区域或账户 | 从当前模型列表重新选择，不要使用搜索结果中的旧模型名称 |
| 工具调用或代码编辑失败 | 模型是否支持工具、上下文和当前 Cline 能力 | 先用纯文本短任务验证，再确认模型能力与 Cline 当前版本要求 |
排错时一次只改一个变量：先确认 Key，再确认 Base URL，随后确认 Model ID，最后检查权限、额度和限速。这样可以避免把认证问题、路由问题和模型能力问题混在一起。
配置完成后的安全核对
- 不要把 API Key 提交到 Git，也不要把密钥放在前端代码或公开日志中。
- 为不同项目或环境使用不同 Key，便于撤销和定位用量。
- 能设置权限、有效期、额度或预算时，按最小权限原则配置；具体能力以服务商控制台为准。
- 怀疑泄露时，先创建替代 Key 并完成切换，再撤销旧 Key，最后检查用量记录。
- 如果 Cline 配置被同步到团队环境，先确认本地配置文件和日志不会被提交或共享。
OpenAI 官方提醒完整密钥通常只在创建时显示；Anthropic 官方文档支持为密钥设置类型、工作区和有效期；Gemini 官方文档也建议限制密钥并避免提交到源代码。可分别查看 OpenAI Key 管理说明、Anthropic 认证说明 和 Gemini Key 安全说明。
结论：先选 Provider，再核对三项参数
Cline 配置 API 密钥的核心不是“找一个能用的 Key”，而是让 Provider、API Key、Base URL 和 Model ID 四项信息彼此匹配。使用 Cline 登录或本地模型时可能无需云端 Key；使用 BYOK 时，应从对应服务商的官方控制台创建密钥，并以服务商当前文档核对接口地址、模型标识、权限和额度。
常见问题
Cline 一定要配置 API Key 吗？
不一定。选择 Cline Provider 时可以按官方流程登录；连接 Ollama 或 LM Studio 等本地运行时通常不需要云端 API Key。只有使用 Anthropic、OpenAI、Gemini、OpenRouter 或其他 BYOK Provider 时，才需要填写对应密钥。
Cline 的 Base URL 要不要加 /v1？
不能一概而论。应以服务商给出的 Base URL 为准：有的接口根地址包含 /v1，有的 Provider 会自动处理。不要默认填写 /chat/completions，也不要因为其他平台使用 /v1 就自行复制。
为什么 API Key 正确，Cline 仍然返回 404？
404 更常见地指向 Base URL、路径或 Model ID 不匹配。先确认 Provider，再核对服务商给出的根地址是否包含 /v1，最后从服务商模型列表复制真实 Model ID，不要使用展示名称。
Cline 返回 401 时应该先换 Key 吗？
先检查 Provider 是否与 Key 来源一致、密钥前后是否有空格、是否把 Bearer 前缀一起粘贴，以及密钥是否已撤销或过期。确认这些项目后仍失败，再到服务商控制台重建 Key。
VS Code 插件和 Cline CLI 的密钥配置一样吗？
认证逻辑相近，但入口不同。VS Code 插件在 Cline 面板设置中选择 Provider；CLI 使用 <code>cline auth</code>，也可以按官方参数传入 Provider、API Key、Model ID 和 Base URL。两者的配置字段和优先级应以当前版本文档为准。
相关阅读
参考资料
- Cline 官方 Authorization 文档
- Cline 官方安装文档
- Cline CLI 官方参考
- Cline CLI 官方 README
- OpenAI 官方 Developer quickstart
- OpenAI 官方 API Key 管理说明
- Anthropic 官方认证文档（platform.claude.com）
- Google Gemini 官方 API Key 文档
- OpenRouter 官方开发者页面（openrouter.ai）