Roo Code 接入自定义 API 教程：Base URL、Key 与模型（2026）

Roo Code 是 VS Code 中常用的编程 Agent，支持多模式、按模式分配模型，以及 OpenAI 兼容的自定义 Provider。对国内团队来说，把它接到统一网关上，可以固定访问路径、集中账单，并按项目控制额度。

需要先说明一个变化：按 Roo Code 仓库公告，Roo Code Inc. 已于 2026 年 5 月 15 日停止 Roo Code 扩展，主仓库同日归档，最终版本为 v3.54.0。社区分叉 Zoo Code 接续维护，并保留了大部分原有配置方式。本文以 Zoo Code 为主，同时标注旧版 Roo Code 的差异。

说明：Roo Code 是 Roo Code, Inc. 的商标；Zoo Code 是社区分叉项目；VS Code 是 Microsoft Corporation 的商标；OpenAI 是 OpenAI, Inc. 的商标。本文仅作技术说明，与上述主体无隶属或合作关系。项目状态、界面和菜单以仓库公告及当前版本文档为准。

一、先确认你用的是 Roo Code 还是 Zoo Code

两者的面板和 Provider 配置很接近，但维护状态不同：

Roo Code：扩展 ID 为 RooVeterinaryInc.roo-cline，主仓库已于 2026 年 5 月 15 日归档，扩展停止更新。已安装的版本可能还能运行，但不会再收到修复和新模型适配。
Zoo Code：由 Roo Code 社区分叉而来，采用 Apache-2.0 许可，在 VS Code Marketplace 以 ZooCodeOrganization.zoo-code 发布，文档在 docs.zoocode.dev。它延续了 Code、Architect、Ask、Debug 等模式，并继续更新模型和 Provider。
原 Roo Code 的设置目录、.roomodes 和 .rooignore 等习惯被保留，迁移时通常可以沿用；具体迁移步骤以 Zoo Code 的迁移文档为准。
如果你在团队里统一配置，先确认所有人装的是同一个扩展。混用旧版 Roo Code 和 Zoo Code，菜单名称和个别设置项可能不一致，排错时容易互相误导。

二、准备 Key、Base URL 和模型

开始前准备三样东西：一个 API Key、一个 OpenAI 兼容地址、一个准确的模型 ID。

打开中商起航 AI 网关注册页，注册并登录控制台。
进入「API 密钥」，新建密钥，名称写清用途，例如 zoo-code-工作电脑。
设置额度上限和过期时间。个人账号也建议设置，避免异常消耗。
复制 Key，保存到密码管理器。控制台通常只完整显示一次。
打开模型价格，记下要用的模型 ID。价格和模型会调整，以页面当前展示为准。

三项配置的写法如下：

API Provider: OpenAI Compatible
Base URL:     https://ai.zhongshangqihang.com/v1
API Key:      sk-...（在控制台创建，只保存于密码管理器）
Model:        以站内模型价格页当前展示的模型 ID 为准

Base URL 使用 OpenAI 兼容地址，结尾是 /v1。不要填 Anthropic 的根地址，也不要自己补上 /chat/completions，否则容易出现路径重复和 404。

三、在 VS Code 中安装扩展

Zoo Code 要求 VS Code 1.84.0 或更高版本。安装步骤：

打开 VS Code，按 Cmd/Ctrl + Shift + X 进入扩展视图。
搜索 Zoo Code，选择发布者为 ZooCodeOrg 的条目并安装。
如果仍在使用旧版 Roo Code，搜索 Roo Code，发布者为 RooVeterinaryInc；装好后注意它已停止维护。
安装完成后按提示重载 VS Code。活动栏会出现对应图标，点击即可打开面板。
在 VSCodium、Windsurf 等没有 Marketplace 的编辑器里，改用 Open VSX 搜索同名扩展，或从 Releases 下载 VSIX 后手动安装。
安装后图标没有出现，先重启 VS Code，确认扩展已启用，再看 View → Output 里对应扩展的输出通道。

四、配置 OpenAI Compatible Provider

打开扩展设置面板，在 API Provider 下拉框里选择 OpenAI Compatible。这个选项专门用于非 OpenAI 官方地址的兼容服务，和内置的 OpenAI Provider 不是同一个入口。

需要填写和检查的字段：

Base URL：填 https://ai.zhongshangqihang.com/v1，不要带 /chat/completions。
API Key：粘贴控制台创建的 Key，注意不要带空格或换行。
Model：填写模型 ID，不是显示名称，也不是备注。
Model Configuration：按需填写 Context Window、Max Output Tokens、Image Support、Computer Use 以及输入/输出价格。价格字段只影响界面上的成本估算，不会改变实际计费；不确定就留空，以模型价格为准。
工具调用：Zoo Code 和 Roo Code 的 OpenAI Compatible Provider 只支持 OpenAI 原生工具调用，没有 XML 回退。所选模型必须支持 OpenAI 兼容的 function calling，否则普通聊天可能正常，Agent 读写文件时会失败。

如果网关或模型只实现了部分工具协议，先在普通对话里验证，再试读取一个小文件。不要一上来就跑多文件重构，否则很难判断是模型能力、Provider 配置还是项目本身的问题。

五、模型与模式怎么配

Roo Code 和 Zoo Code 都支持多模式，并可以为每个模式单独指定模型。这样可以在成本和能力之间做分配：

模式或场景	建议档位	配置要点
Code：日常改代码	主力代码模型	必须支持工具调用，上下文窗口填准确
Architect：方案设计	高能力模型	上下文可适当放大，注意成本
Ask：解释与问答	轻量快速模型	不跑工具时可用低成本档位
Debug：排查问题	主力或高能力模型	保留足够输出长度，避免截断
Orchestrator：多任务编排	工具调用稳定的模型	设一个回退模型，失败时可切换

每个模式都建议配置一个回退模型。主力模型限流或临时不可用时，切到同协议、同工具能力的备用模型，比反复重试更稳。模型是否可用、价格如何，以站内模型价格页当前展示为准。

六、验证配置是否生效

只看面板有没有回复不够，因为回复可能来自另一个模式或另一个 Provider。建议按下面顺序验证：

新建一个任务，避免历史上下文干扰。
在模型选择器里明确选中刚配置的模型，不要用默认或自动路由。
发送一个短请求，例如解释一段十行以内的代码。
打开网关控制台的用量或请求日志，确认出现同一时间、同一模型、同一 Key 的记录。
再让它读取一个小文件，验证工具调用链路是否通。
记录验证结果。日志没有记录，说明请求没有到达网关，应回到 Base URL 和 Provider 检查。

常见错误可以这样对照：

Invalid API Key：Key 错误、被禁用或额度用完，也可能填进了错误的 Provider 字段。
Model Not Found：模型 ID 拼错，或该模型未在当前账号开放。
Connection Errors：Base URL 不可达，或代理、TLS、防火墙有问题。
工具调用报错：模型不支持原生工具调用，或网关只兼容了部分协议。
结果与预期不符：先确认当前模式绑定的模型，再检查提示词和上下文。

Roo Code 和 Zoo Code 的文档主要按错误提示排查，没有强调独立的 Verify 按钮。实际对话请求才是最终确认，保存成功不等于请求可用。

七、权限与自动批准

编程 Agent 能读文件、改文件、执行命令，权限设置比模型选择更重要。扩展的 Auto-Approve 菜单在聊天输入框旁边，里面有总开关 Enabled，以及 Read、Write、Execute、Browser、MCP、模式切换、子任务等分类。

建议的安全起点：

先只开 Read，确认读文件的路径和范围符合预期。
Write 先关闭；需要时再开，并把写入延迟设为 1000 毫秒以上，方便检查 Problems 面板。
Execute 使用允许列表加拒绝列表，不要用 * 放开全部命令。
关闭工作区外读写，关闭受保护文件编辑。
生产仓库、含密钥的目录、客户数据目录，不要开启自动批准。
自动批准能跳过确认，可能造成数据丢失或文件损坏；命令执行尤其危险。

Roo Code 文档中的命令配置示例使用 roo-cline. 前缀：

{
  "roo-cline.allowedCommands": ["git status", "npm run", "python -m pytest"],
  "roo-cline.deniedCommands": ["git push", "npm publish", "rm", "sudo"]
}

Zoo Code 分叉保留了原设置习惯，但键名和菜单位置可能随版本变化，以扩展设置页显示为准。允许列表按前缀匹配，拒绝规则优先级更高；涉及危险替换的命令即使前缀命中也会被拦截。

八、安全清单

一个用途一个 Key，不跨设备、不跨项目复用。
设置额度上限和过期时间，定期轮换；怀疑泄露时先禁用，再排查。
不把 Key 写进代码、.env、.vscode/settings.json 或提交记录。
用 .rooignore 排除 .env、凭证、构建产物和日志，减少被读取的机会。
不要在不信任的仓库里开启自动批准；先确认工作区可信。
审查 Agent 的改动和终端命令，重要操作前先提交或创建检查点。
团队统一走网关，给每人独立 Key，保留请求日志，便于审计和离职回收。
确认代码和提示词会离开本机、流向网关和模型供应方；有数据保留要求的团队先做评估。

九、常见问题

Roo Code 现在还能用吗？

按仓库公告，Roo Code 扩展已于 2026 年 5 月 15 日停止，主仓库归档。已安装的版本可能还能运行，但没有后续修复和新模型适配。社区分叉 Zoo Code 继续维护，新项目建议直接用它。

Roo Code 和 Zoo Code 的配置步骤一样吗？

大体一样，都是选 OpenAI Compatible，填 Base URL、Key 和模型。个别菜单名称、设置键名和默认行为可能不同，以当前扩展的设置页和 docs.zoocode.dev 为准。

Base URL 应该填根地址还是 /v1？

走 OpenAI 兼容协议时填到 /v1，例如 https://ai.zhongshangqihang.com/v1。不要带 /chat/completions，否则客户端自动拼接后会出现路径重复。

报 Invalid API Key 或 Model Not Found 怎么办？

先确认 Key 填在 OpenAI Compatible 表单里，Base URL 与 Key 所属环境一致；再用 /v1/models 测试鉴权。Model Not Found 多数是模型 ID 拼错，或模型未对当前账号开放。

为什么工具调用失败？

OpenAI Compatible Provider 只支持原生工具调用，没有 XML 回退。模型或网关必须完整支持 OpenAI 兼容的 function calling；不支持时，普通聊天正常，但读写文件、执行命令会失败。换一个支持工具的模型再试。

下一步

先注册中商起航 AI 网关，创建一个 Zoo Code 专用 Key，按本文填入 Base URL 和模型。跑通普通对话和一次小文件读取后，再按模型价格调整各模式的主力模型与额度。