Roo Code 的 API Key 决定请求走哪家供应商、能调用哪些模型、费用记在谁头上，以及泄露后的影响范围。很多“Key 失效”其实是 Base URL、模型名或 Provider 类型选错。

本文按创建、兼容配置、多模型 Profile、密钥安全、轮换、团队制度和故障排查的顺序，给出一套可执行流程。迁移到社区分支 Zoo Code 后，大部分概念仍然适用。

说明：Roo Code 是其权利人的商标，VS Code 是 Microsoft 的商标。本文仅作技术说明，与相关厂商无隶属关系。Roo Code 扩展已于 2026 年 5 月 15 日停止维护，仓库同日归档；后续状态以官方仓库和文档为准。模型与价格以站内模型价格为准。

一、先确认现状和 Key 类型

Roo Code 是一款开源的 VS Code AI 编程代理，采用自带密钥（BYOK）模式：扩展不代收模型费，模型调用由你填写的供应商 Key 计费。它支持多家供应商，也支持 OpenAI 兼容端点。

需要先说明现状：根据公开信息，Roo Code 扩展已于 2026 年 5 月 15 日停止维护，原仓库归档，之后不再有功能更新、Bug 修复和安全补丁。现有安装通常仍可运行，但长期使用要把“无补丁”计入风险。社区分支 Zoo Code 基于原代码继续开发，采用 Apache-2.0 许可证。

“Roo Code API Key”通常指供应商 Key、网关兼容 Key，或本地模型（如 Ollama）的地址配置。本文讲第二种，它不用于登录 Roo Code，也不能调用其云服务。

二、创建 Key：先定边界再复制

创建前先想清楚：给谁用、用在哪个项目、最多允许花多少。这三项决定了出问题时能否快速定位和止损。

  1. 打开中商起航 AI 网关注册页，注册并登录控制台。
  2. 进入「API 密钥」页面，点击新建。
  3. 名称写清使用者和设备，例如 roo-zhang-macbook，不要只写 test。
  4. 设置额度上限和过期时间，测试 Key 先给低额度。
  5. 如果控制台支持模型范围，只勾选实际要用的模型。
  6. 复制完整 Key 存入密码管理器；多数控制台只完整显示一次。

Key 常以 sk- 开头，但前缀不能证明真伪或权限。复制时注意首尾空格和换行，这是 Invalid API Key 的高频原因。

三、配置 OpenAI 兼容端点

路径是 Settings → Providers，把 API Provider 选为 OpenAI Compatible。需要填的核心字段只有三个：

  • Base URL：填 https://ai.zhongshangqihang.com/v1 这类根地址，不要填网页首页，也不要填到 /chat/completions。
  • API Key：粘贴刚创建的网关 Key。
  • Model：填价格页展示的准确模型 ID，不要猜后缀。

展开 Model Configuration 还可设置 Max Output Tokens、Context Window、Image Support、Computer Use、Input Price 和 Output Price。后两项只用于本地估算费用，不改变实际扣费；上下文窗口不要虚报，否则长任务可能报错。

Roo Code 依赖模型的原生工具调用，没有 XML 回退。兼容端点不仅要能聊天，还要支持 OpenAI 风格 function calling；否则普通对话正常，Agent 一执行工具就失败。

curl https://ai.zhongshangqihang.com/v1/chat/completions \
  -H "Authorization: Bearer $ZSQH_ROO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<模型ID>","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'

curl 正常但 Roo Code 报错时，检查 Base URL 是否多了路径、模型 ID 是否一致、模型是否支持工具调用。

四、API Configuration Profiles：多模型的核心

API Configuration Profiles 是一组可保存、可切换的模型配置。每个 Profile 独立保存供应商、Key、模型、温度、思考预算、限流和差异编辑设置。对“规划用强模型、日常改动用便宜模型”的团队，这是最值得先学会的功能。

在 Settings → Providers 点击 Profile 选择器旁的 +，命名后选择供应商、填写 Key、选择模型，再按需设置 Rate Limit。Rate Limit 表示该 Profile 两次请求的最小间隔，默认关闭。Profile 可在设置面板或聊天界面的 API Configuration 下拉框切换，也可以固定常用项。

更细的控制在 Prompts 标签页：每个 Mode 可绑定一个 Profile，Roo Code 还会记住该 Mode 上次使用的配置。任务从开始就锁定当时的 Profile，从历史恢复也沿用原配置；Orchestrator 子任务会继承父任务 Profile，并在整个生命周期保持。因此不要把 Orchestrator 绑到昂贵模型后又指望子任务自动降级。

Profile 名称 用途 模型档位 Key 策略 备注
plan-strong 架构设计、复杂重构 强推理模型 独立 Key，限额较高 绑定 Architect
code-daily 日常编码、修 Bug 主力模型 每人一把 绑定 Code
ask-cheap 代码问答、解释 轻量模型 低额度 Key 绑定 Ask
batch-cheap 批量改注释、格式化 低价模型 项目专用 Key 限制速率
backup 主模型故障时切换 备用模型 独立 Key 定期验证

命名建议统一为“场景-档位”，方便切换和月底核对。模型 ID 与价格会调整，以模型价格页面为准。

五、密钥安全：存储、权限与数据边界

按文档，API Key 存放在 VS Code 的 Secret Storage 中，不以明文写进普通设置文件。这不等于绝对安全：保护依赖操作系统账户和本机环境，能登录你电脑的人、拥有你用户权限的进程，仍可能接触到它。

因此还要做几件事：开发机使用独立系统账户，共享电脑不长期保存 Key；公司设备明确扩展白名单；确认设置同步范围，不把敏感配置同步到不受控设备；不在 Prompt、代码注释或终端历史里粘贴 Key；截图前遮挡密钥字段；按数据分级选择通道，代码上下文会发往 Base URL 指向的服务。

最小权限的落点是“即使泄露，损失也有上限”：设置额度、过期时间、模型白名单；如果网关支持 IP 白名单或项目范围，一并启用。测试、个人日常、自动化任务分三把 Key，不要一把打通所有场景。

六、轮换、吊销与事故处理

建议每 90 天轮换一次，或在成员离职、设备丢失、怀疑泄露时立即执行。考虑到 Roo Code 已停止维护，老版本不再获得安全补丁，轮换周期可以更保守。

安全的顺序是“先并行、再切换、后停用”：新建带日期后缀的 Key；写入密码管理器，暂时保留旧 Key；在对应 Profile 中替换并发送测试请求；确认网关日志出现新 Key 记录；观察一两天错误率；最后停用旧 Key。

如果确认泄露，顺序反过来：先停用或删除 Key，再查异常用量、来源和时间段，然后检查仓库历史、日志和聊天记录。控制损失优先，不要先花时间复盘泄露路径。

七、团队使用：把个人设置变成制度

Roo Code 的 Key 存在每台开发机上，团队若只靠扩展本体，很难集中查看谁在用哪把 Key、花了多少。集中管控应放在网关侧：一人一 Key、按项目分 Key、统一额度、保留请求日志。

  • 实名 Key：名称含成员和用途，离职当天停用，不共用“团队 Key”。
  • 项目隔离：生产、实验、自动化各用独立 Key，额度分开。
  • 工作区去密钥化：仓库只放 Base URL、模型名、Mode 说明，Key 留在用户级存储。
  • 共享服务单独开户：CI、脚本、机器人使用服务 Key，不与成员混用。
  • 月度审计：检查长期未用的 Key、额度异常、鉴权失败突增。
  • 权限最小化：轻量场景不配强模型，只读任务不开放自动执行终端命令。

自动批准能提高效率，也会放大误操作和 token 消耗。团队应明确哪些命令可自动执行，哪些必须人工确认。

八、常见故障排查

  • Invalid API Key：Key 不完整、带空格，或填进了 Anthropic、Gemini 专用 Provider。改用 OpenAI Compatible 重试。
  • Model Not Found / 404：模型 ID 拼错，或 Base URL 多了 /chat/completions。从价格页原样复制，Base URL 只保留到 /v1。
  • 401 / 403：Key 被停用、额度用完、无模型权限。先看控制台状态和用量。
  • 429：触发限流或额度上限。降低并发，检查 Rate Limit 和 Key 限额。
  • 对话正常、工具调用失败：端点或模型不支持原生 function calling。换支持工具调用的模型或端点。
  • 长任务中途失败：Context Window 虚报或输出上限不合理。按真实能力填写。

排查坚持三层：配置层看 Provider、Base URL、模型名；请求层用 curl 复现；账单层看网关日志是否出现对应请求。三层对上，问题通常不在 Key。

常见问题

Roo Code 现在还能用吗？

截至目前，已安装的扩展通常仍可运行，但原团队已于 2026 年 5 月 15 日停止维护，仓库归档，不再提供更新和安全补丁。新项目建议评估社区分支 Zoo Code 或其他仍在维护的工具；继续使用老版本时，应控制 Key 权限并关注安全风险。

Key 存在哪里？

按文档存放在 VS Code Secret Storage，不以明文写入普通设置文件。它仍属于本机凭证，保护级别取决于操作系统账户和开发机安全。共享设备应使用独立账户，并避免把敏感配置同步到不受控环境。

一把 Key 能给多个 Profile 用吗？

技术上可以，但不建议。不同 Profile 对应不同模型和额度，分开 Key 才能在日志里看清谁、在哪个场景花了多少；一把 Key 出问题时也很难判断影响范围。

为什么普通对话正常，Agent 工具就报错？

Roo Code 只使用原生工具调用，没有 XML 回退。兼容端点必须实现 OpenAI 风格 function calling，模型也要支持。先换一个已知支持工具调用的模型测试，再判断是端点还是模型问题。

团队应该共用一把 Key 吗？

不建议人类成员共用。共用 Key 无法区分用量，离职后也难以安全回收。正确做法是一人一 Key，CI 或共享服务单独建服务 Key，并由网关统一设置额度和告警。

小结

如果你还在用 Roo Code 或 Zoo Code，先创建一把低额度测试 Key，用 curl 和一次真实 Agent 任务各验证一遍，再分发给团队。开始可以走注册入口；模型、额度和计费方式见模型价格，价格会随模型版本和上游政策调整。

相关阅读：