Roo Code是什么？
Roo Code 是一个开源 VS Code 编码代理，可以使用 OpenAI-compatible 提供程序、编辑文件并运行批准的工具。
本 Roo Code 指南通过其 OpenAI Compatible 提供程序设置添加了 TokenHub。首先测试只读任务，然后在启用文件编辑或终端命令之前验证 native tool calling。 Roo Code 可以从 VS Code 读取文件、建议编辑和运行终端工具，因此必须单独测试提供程序连接和代理功能。首次运行时保持自动批准关闭，使用一次性存储库，并审查每个请求的操作，直到所选模型通过本机工具调用证明是可靠的。
Roo Code 可以通过 OpenAI Compatible Provider 调用 TokenHub。TokenHub 的 OpenAI 兼容 Base URL 填 https://us-api.tokenhub.com/v1，Roo Code 会使用 Chat Completions 路径完成对话、代码分析和工具调用。
适合场景
Roo Code 是 VS Code 内的代码 Agent，适合阅读项目、解释报错、生成修改计划、编辑文件和辅助运行命令。首次接入 TokenHub 时，建议先在测试仓库里验证只读任务，再逐步允许文件修改和命令执行。
如果你的团队同时使用 Cline、Kilo Code 或 Cursor，字段含义基本一致：Provider 选择 OpenAI Compatible，Base URL 填 TokenHub 地址，API Key 填 TokenHub 密钥，Model ID 选择 TokenHub 模型列表中的真实模型。
安装 Roo Code
先参考 Roo Code OpenAI Compatible 官方文档。如果你还没有安装扩展，常见流程是：
- 打开 VS Code。
- 进入 Extensions。
- 搜索
Roo Code。 - 安装官方扩展并重新加载窗口。
- 打开 Roo Code 面板，进入 Provider 或 Configuration Profile 设置。
不同版本的菜单名可能略有变化，以当前安装版本和官方文档为准。
准备 TokenHub 凭证
export TOKENHUB_API_KEY="sk-..."为 Roo Code 选择一个适合代码任务的 TokenHub 模型。Code 模式通常需要模型具备稳定的工具调用能力；如果一个模型只能做普通聊天，先把它用于 Ask/Architect 类只读任务，不要直接用于会修改文件的 Code 任务。
持久化设置位置
Roo Code 推荐通过扩展的 Provider 设置或 Configuration Profile 保存服务商，而不是手写不确定的 VS Code 私有字段。
| 位置 | 用途 |
|---|---|
| Roo Code Provider 设置 | 保存 TokenHub 的 Base URL、API Key 和默认模型。 |
| Roo Code Configuration Profile | 为不同项目或模式保存不同模型和权限组合。 |
| 团队文档 | 只记录 Base URL、Model ID、权限建议；不要记录真实 API Key。 |
如果团队要共享配置，只共享 https://us-api.tokenhub.com/v1、推荐 Model ID 和权限策略。API Key 由每位开发者在本机 Roo Code 设置中填写。
配置 OpenAI Compatible Provider
在 Roo Code 的 Provider 设置中选择 OpenAI Compatible，并填写：
| 字段 | 值 |
|---|---|
| Provider | OpenAI Compatible |
| Base URL | https://us-api.tokenhub.com/v1 |
| API Key | TOKENHUB_API_KEY 对应的密钥值 |
| Model ID | TokenHub 模型列表中的 Model ID |
如果 Roo Code 提供 Code、Architect、Ask 等不同模式，可以第一次都指向同一个 TokenHub 模型。确认请求、工具调用和日志都正常后，再按成本、速度和上下文长度拆分模型。
推荐权限设置
| 权限 | 建议 |
|---|---|
| 文件读取 | 允许，便于分析项目结构。 |
| 文件写入 | 首次验证时逐次确认。 |
| 终端命令 | 逐次确认，尤其是安装依赖、删除文件、运行迁移命令。 |
| 浏览器访问 | 仅在任务需要时开启。 |
验证
先输入只读任务：
请只读分析当前工作区，说明构建命令和测试命令可能在哪里配置。不要修改文件。如果 Roo Code 能正常返回项目结构分析，再让它生成一个修改计划。最后才授权它编辑低风险文件，并用 git diff 审阅改动。
验证成功后，回到 TokenHub 请求日志中检查模型名、请求 endpoint、token 用量和计费分组，确认请求确实走 TokenHub。
故障排查
| 现象 | 处理方式 |
|---|---|
| 401 | 重新粘贴 TokenHub API Key，确认没有多余空格或换行。 |
| 404 | 确认 Base URL 是 https://us-api.tokenhub.com/v1，并使用 TokenHub 中存在的 Model ID。 |
| 工具调用失败 | 换用支持 OpenAI 工具调用的代码模型，先在 Ask/Architect 模式验证普通对话。 |
| 模型列表加载失败 | 手动填写 Model ID，不依赖自动拉取模型列表。 |
| 请求仍走其它服务商 | 检查当前 Configuration Profile 是否选中了 TokenHub provider。 |
| 改动范围太大 | 关闭自动批准，让 Roo Code 先输出计划，再逐步授权文件修改和命令执行。 |
推荐模型怎么选？
Roo Code API 提供商 FAQ
Roo Code中应该选择哪一个API Provider？
选择 OpenAI Compatible，然后输入 TokenHub、Base URL、API 密钥和准确的型号 ID。
如果聊天正常但工具调用失败怎么办？
首先切换到明确支持native tool calling的编码或Agent模型，然后检查Roo Code权限和批准模式。
如何降低第一次 Roo Code 测试期间的风险？
使用测试存储库，从只读解释开始，关闭自动批准，然后逐渐验证编辑和终端命令。
如何对 Roo Code 401 进行故障排除？
检查 API 键是否缺少字符或空格，并确认其已保存在活动配置文件中。重试简短请求并检查 TokenHub 日志。
如何对 Roo Code 404 进行故障排除？
使用以 /v1 结尾的 TokenHub API 根，避免重复的 /chat/completions 路径，并确认模型 ID 存在。
配置资料
本页配置以 TokenHub 教程和官方资料为依据，最后核验于 2026-09-04。
