API Key 创建后如何配置到本机工具

配置步骤

1. 1

   创建或展开 API Key

   进入控制台的 API 密钥页，新建一把 API Key，或在已有密钥卡片上点击“配置接入”。创建成功后，系统会自动展开这把 Key 的接入配置区。

2. 2

   根据你的本机环境选择一条路径

   按以下三种情况选一条，不需要三种都配置：

   1. 新手优先选择“推荐：CC Switch 一键导入”。
   2. 没有 CC Switch，但主要使用 Codex CLI、Claude Code 或 Gemini CLI：选择“备用：复制命令配置 CLI”。
   3. 已经知道 Cursor、Cline 或其他工具的设置页在哪里：选择“高级：手动填写配置”。
3. 3

   路径一：导入到 CC Switch

   默认路径是“推荐：CC Switch 一键导入”。点击对应工具按钮，例如“导入 Codex CLI”或“导入 Claude Code”。浏览器会打开本机 `ccswitch://` 导入链接，把 CoderPlan endpoint 和当前 API Key 交给 CC Switch。导入后在 CC Switch 内确认供应商、模型和启用状态。

4. 4

   路径二：复制命令配置 CLI

   选择“备用：复制命令配置 CLI”后，先确认 Codex CLI、Claude Code 或 Gemini CLI。控制台会自动识别 macOS 或 Windows，生成对应配置命令，并把当前 API Key 自动带入脚本，你不需要手动改 `sk-your-api-key`。

   macOS

   点击“复制并配置”，把复制出来的完整命令粘贴到终端执行。命令会写当前用户的 shell 配置文件，例如 `~/.zshrc`，同时让当前终端会话立即可用，不会写系统级配置，也不需要管理员权限。

   Windows

   点击“复制并配置”，把复制出来的完整 PowerShell 脚本粘贴到 PowerShell 执行；也可以下载 `.ps1` 脚本后运行。脚本使用当前用户 User scope 写入环境变量，同时设置当前 `$env:`，不使用 Machine scope，因此不会修改系统级环境变量。

   复制命令 vs 下载脚本

   “复制并配置”是主路径，适合直接粘贴到当前终端执行；“下载脚本”适合保存成 `.sh` 或 `.ps1` 文件后执行。两者写入的变量值一致。

5. 5

   路径三：高级手动配置

   选择“高级：手动填写配置”后，页面会展示常见工具的配置片段。你需要把 CoderPlan 的服务地址和当前 API Key 填到工具自己的设置页里。

   什么时候用

   适合已经知道工具设置页在哪里的用户，例如 Cursor、Cline 或其他支持 OpenAI Compatible 的工具。它不会写入系统环境变量，也不会依赖 CC Switch。

   复制什么

   OpenAI Compatible 工具通常复制 `/v1` Base URL 和 API Key。API Key 使用 CoderPlan 控制台生成的完整 `sk-` 密钥。

   复制

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

   填到哪里

   工具里常见字段名可能叫 OpenAI Compatible URL、Base URL、API Host、Endpoint、API Key 或 Token。字段名不同没关系，核心是服务地址填 Base URL，认证字段填 API Key。

   怎么验证

   保存设置后，新建一个短对话或短任务验证，例如让工具解释一句代码。能正常返回结果，再用于正式项目任务。

6. 6

   确认环境变量已经写入成功

   复制命令执行完成后，当前终端通常已经可以读取环境变量。看到正确的 Base URL 和“API Key 已设置”，就代表环境变量写入已经成功；这一步不要求真实 API 请求必须成功。

   macOS：在当前终端确认

   复制命令会写入 `~/.zshrc` 或当前 shell 的用户配置文件，并在当前终端 export 一次。运行以下命令，只检查 Key 是否存在，不打印完整 Key。

   复制

   printf "OPENAI_BASE_URL=%s\n" "$OPENAI_BASE_URL"if [ -n "$OPENAI_API_KEY" ]; then echo "OPENAI_API_KEY=已设置"; else echo "OPENAI_API_KEY=未设置"; fi

   Windows：在当前 PowerShell 确认

   复制命令会写入 User scope，并设置当前 `$env:`。运行以下命令，直接确认当前用户环境变量是否写入。

   复制

   [Environment]::GetEnvironmentVariable('OPENAI_BASE_URL', 'User')if ([Environment]::GetEnvironmentVariable('OPENAI_API_KEY', 'User')) { 'OPENAI_API_KEY=已设置' } else { 'OPENAI_API_KEY=未设置' }

   怎样算成功

   可以按以下三个层级判断：

   1. 脚本提示“配置已写入”：说明脚本已经执行完成。
   2. 当前终端能读取正确 Base URL，并显示“API Key 已设置”：说明本机环境变量写入链路已经成功。
   3. CLI 或 API 返回正常结果：说明 Key、Base URL、后端环境、额度和模型权限也都可用。

   为什么变量写入成功，真实请求仍可能失败

   如果 Key 来自本地测试后端，却请求生产 Base URL，或者 Key 已删除、禁用、复制不完整，真实请求仍可能返回 `Invalid token` 或 401。这不代表环境变量没有写入，需要继续检查 Key 与 Base URL 是否属于同一个后端环境。

7. 7

   用一个小任务验证工具能调用

   验证环境变量后，让 Codex CLI、Claude Code 或 Gemini CLI 执行一个很短的任务，例如解释一句代码或回答一句话。能正常返回，说明 API Key、Base URL、API 使用额度和模型权限基本都已生效。

8. 8

   如果贴错或泄露了 Key，先删除重建

   API Key 一旦出现在公开聊天、终端录屏、issue 或日志里，就应该在控制台删除并重新创建。然后重新复制配置命令覆盖旧配置。macOS 的自动配置会用 CoderPlan 标记块幂等更新，不会重复追加多份同一工具配置。