API Key 接入配置教程

配置步骤

1. 1

   打开 API 密钥页并选择当前目标

   进入控制台的 API 密钥页。先在“我的 API 密钥”里创建或选择一把 Key；点击某张 Key 卡片上的“配置接入”后，页面会滚动到“本机接入向导”，并显示“当前正在配置”的 Key 名称和脱敏 Key。多把 Key 同时存在时，先看这里确认当前目标。

   去管理 API Key
2. 2

   没有 Key 就创建，有 Key 就选择

   如果账号还没有 API Key，先点击“创建 API 密钥”。如果已经有一把或多把 Key，不需要重复创建，直接在对应 Key 卡片上点击“配置接入”。Key 卡片负责管理密钥；本机接入向导负责后续配置和检测。

3. 3

   只选择一种接入路径

   本机接入向导进入“准备本机接入配置”后，会提供三条路径。三条路径是并列选择，不需要全部执行：

   1. 推荐：CC Switch 一键导入，适合本机已经安装 CC Switch，希望少手动复制配置的用户。
   2. 备用：复制命令配置 CLI，适合 Codex CLI、Claude Code、Gemini CLI，希望用脚本写入当前用户环境变量的用户。
   3. 高级：手动填写配置，适合 Cursor、Cline 或其他支持 OpenAI Compatible 的工具，也适合已经熟悉工具设置页的用户。
4. 4

   路径一：CC Switch 一键导入

   选择“推荐：CC Switch 一键导入”，再点击你要导入的工具，例如 Codex CLI、Claude Code 或 Gemini CLI。浏览器会尝试打开本机 CC Switch 导入链接，把当前 API Key 和服务地址交给 CC Switch。确认 CC Switch 已完成导入后，回到页面点击“已完成，开始检测”。

   为什么最简单

   如果你已经安装 CC Switch，这通常是三条路径里最省事的一条。你不需要打开终端，也不需要判断 Base URL 应该填哪个字段；页面把配置交给 CC Switch，CC Switch 再统一管理不同工具的供应商、模型和启用状态。适合不想手动改环境变量，也不想在多个工具设置页来回找入口的用户。

   什么时候适合

   适合已经安装 CC Switch，并希望由 CC Switch 统一管理多个工具配置的用户。如果你经常在 Codex CLI、Claude Code、Gemini CLI 之间切换，用 CC Switch 管理会比每个工具分别填写更省心。

   如果没有打开 CC Switch

   点击导入后，如果浏览器没有唤起 CC Switch，通常说明本机还没安装 CC Switch，或者系统没有注册 `ccswitch://` 打开方式。这时不需要重新创建 Key，也不代表 API Key 有问题；直接切到路径二复制命令配置 CLI，或使用路径三手动填写即可。

5. 5

   路径二：复制命令配置 CLI

   选择“备用：复制命令配置 CLI”后，按页面上的四步走：先确认工具和系统，再复制配置命令，把命令粘贴到终端或 PowerShell 执行，最后回到页面等待检测。它本质上是在替你完成路径三里那些手动填写 Base URL、API Key 和环境变量的动作，只是把容易填错的字段整理成一条命令。脚本会把当前 API Key 和对应 Base URL 写入当前用户配置，并尽量让当前会话立即生效，不要求管理员权限。

   它和路径三有什么区别

   路径二适合 Codex CLI、Claude Code、Gemini CLI 这类可以通过环境变量读取配置的 CLI 工具。你不需要知道配置文件在哪里，也不需要手动判断每个变量名，页面会按工具和系统生成命令。路径三则是直接把 Base URL 和 API Key 复制出来，交给你自己填到工具设置页里，更适合 Cursor、Cline 或其他有图形化设置入口的工具。

   四步怎么操作

   这一条路径不是让你手动理解每一行脚本，而是让页面生成完整命令，你按页面状态一步步做就可以。前三步完成后，本机配置通常已经写好；第四步是验证步骤，不强制，但建议做完，因为页面可以据此判断这把 Key 是否真的跑通过一次调用：

   1. 第一步：在页面里确认要配置的工具和系统，例如 Codex CLI + macOS，或 Claude Code + Windows。系统通常会默认选中你当前正在使用的系统，一般不需要切换；只有在为另一台电脑复制配置命令时，才需要手动改成对应系统。
   2. 第二步：点击“复制并配置”。复制成功后，页面会把复制动作标记为完成，说明命令已经进入剪贴板。
   3. 第三步：打开终端或 PowerShell，粘贴刚才复制的完整命令并回车执行。执行成功后，终端通常会显示类似“配置已写入”“请运行 codex / claude / gemini 并输入 hi coderplan 验证”的提示。到这里，本机环境变量通常已经写入完成。
   4. 第四步：建议按提示启动对应 CLI，并发送一次简单请求，例如 `hi coderplan`。如果你只是想先保存配置，可以暂时不做这一步；但完成它之后，页面能检测到当前 API Key 产生了新调用，并把验证状态标记为完成，后续排查也更有依据。

   终端里会看到什么

   不同工具的提示文字会略有差异，但成功路径通常是：先看到配置写入成功，再打开对应 CLI，最后让 CLI 正常返回一次简短回复。只要请求能返回，说明 Key、Base URL、额度和模型权限基本都已经连通；如果暂时不发请求，配置可能已经写好，但页面无法确认工具链是否真的可用。

   复制

   配置已写入当前用户环境请打开一个新终端，运行 codex / claude / gemini在 CLI 中输入：hi coderplan

   macOS

   命令会写入当前用户的 shell 配置文件，例如 `~/.zshrc` 或当前 shell 对应的用户配置文件，并在当前终端临时 export 一次，所以通常执行完成后可以直接运行 Codex CLI、Claude Code 或 Gemini CLI 发起一次简单请求。它不会修改系统级配置，也不会要求 sudo。若工具是从旧终端、IDE 或后台进程启动的，重开终端或重启 IDE 后再验证更可靠。

   Windows

   PowerShell 脚本会写入当前用户的 User scope 环境变量，同时设置当前 `$env:`，因此当前 PowerShell 窗口通常可以马上验证，不需要管理员权限，也不会写 Machine scope。已经打开的终端、IDE 或工具进程可能仍然读取旧环境变量；如果配置后请求仍走旧 Key 或旧 Base URL，先新开 PowerShell，再重启 IDE 或对应 CLI 工具。

6. 6

   路径三：高级手动填写配置

   选择“高级：手动填写配置”后，复制页面展示的 Base URL 和 API Key，粘贴到工具自己的设置页。它不会自动写入任何配置，也不会替你打开工具设置页；你需要知道这个工具在哪里填写服务地址、模型供应商或 API Key。OpenAI Compatible 工具通常使用 `/v1` Base URL；Claude Code、Gemini CLI 等工具按各自字段要求填写。

   适用场景

   适合 Cursor、Cline 或其他支持自定义模型服务地址的工具，也适合你已经知道设置入口，只需要复制 Base URL 和 API Key 的情况。如果你不知道工具设置页在哪里、字段名是什么意思，优先用路径一或路径二会更稳。

   需要你自己判断什么

   手动填写时，你要自己确认工具需要的是 OpenAI Compatible Base URL、Anthropic Base URL、Gemini Base URL，还是单独的 API Host / Endpoint 字段。字段名不同没关系，关键是不要把 `/v1` 随便加到所有工具里，也不要把 API Key 填到 Base URL 字段。

   和路径二的关系

   路径二其实就是把常见 CLI 工具的手动填写动作自动化：页面知道该写哪些环境变量，脚本帮你写进去。路径三则保留完整手动控制权，适合工具类型不在自动脚本范围内，或者你明确知道自己要改哪个设置项。

   不要混用字段

   API Key 使用 CoderPlan 控制台生成的完整 `sk-` 密钥。Base URL 是否需要 `/v1` 取决于工具类型，不要把同一个地址格式套到所有工具里。

   复制

   OpenAI Compatible Base URL: https://api.coderplan.ai/v1API Key: sk-your-api-key

7. 7

   发送一次简单请求完成检测

   配置完成后，运行对应工具并发送一次简单请求，例如“hi coderplan”。页面会检测当前这把 Key 是否产生新调用。检测成功说明 Key、Base URL、账户 API 使用额度和模型权限基本可用。

   没有检测到怎么办

   先确认正在配置的 Key 和工具里使用的 Key 是同一把，再检查 Base URL、API 使用额度和当前终端是否读取了新配置。不要同时修改多项配置，每次只改一项再重新发起小请求。

8. 8

   Key 贴错或泄露时删除重建

   只要完整 API Key 出现在公开聊天、终端录屏、issue、日志或截图里，就应该在控制台删除这把 Key 并重新创建。随后回到 API 密钥页，选择新 Key 重新走一次接入向导。