Routa Providers配置教程:Claude Code、Codex与OpenCode一站式接入多模型
Routa Providers配置教程:Claude Code、Codex与OpenCode一站式接入多模型
Routa 是一个 Workspace-first 的多智能体协作平台,支持通过统一的 Providers 配置接入 Claude Code、Codex、OpenCode 等主流 AI 编程 Agent,让多模型在 Web 与桌面端无缝协同工作。本文带你用最少的步骤完成第一个 Provider 的接入,理解「一个可用的 Provider 就足够上手」的核心理念。
为什么 Provider 配置如此简单?
Routa 的设计哲学是:所有 Agent 运行时都通过 ACP(Agent Client Protocol)做统一归一化,你不需要为每个模型单独写胶水代码。官方建议的路径非常清晰——docs/configuration/providers-and-models.md 中给出的推荐顺序是:
- 在 Providers 中让一个 Provider 可用
- 如有需要,在 Models 中创建一个模型别名
- 在 Role Defaults 中把该 Provider/模型绑定到角色
- 回到工作区,启动一个 Session
💡 实用规则:不需要配置所有 Provider,一个能跑通的就足够开始使用了。
四大配置面板:一次看懂
在 Routa 的设置界面中,Provider 配置分布在四个面板,各司其职:
| 面板 | 职责 |
|---|---|
| Providers | 可用运行时、可见性与 Provider 专属凭据 |
| Registry | 可安装的 ACP Agent 列表 |
| Role Defaults | 每个角色(ROUTA / CRAFTER / GATE / DEVELOPER)的默认 Provider 与模型 |
| Models | 带 Base URL 与 API Key 的模型别名 |
内置 Provider 类型:三大主力
当前内置的常见 Provider 选项包括(来源:docs/configuration/providers-and-models.md):
- Claude Code —— 通过 SDK 的 stream-json 协议接入 Claude 系列模型
- OpenCode / OpenCode SDK —— 原生 ACP 运行时,也支持连接远程 OpenCode 服务器
- Codex —— 通过 API Key 启用 Codex 流程
各 Provider 的命令行预置与能力元数据定义在 src/core/acp/acp-presets.ts,而 Web 端的 Provider 列表接口则在 src/app/api/providers/route.ts 实现,本地 Provider 可毫秒级返回、Registry 异步加载,界面不会卡住。
最快配置方法:环境变量一览
不同运行方式对应不同的凭据注入方式,最常用的环境变量如下(完整清单见 docs/configuration/environment-variables.md):
| 环境变量 | 作用 |
|---|---|
ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN |
启用 Anthropic(Claude Code)执行路径 |
OPENAI_API_KEY |
启用 OpenAI 系模型 |
CODEX_API_KEY |
启用 Codex 流程 |
OPENCODE_SERVER_URL / OPENCODE_API_KEY |
启用 OpenCode SDK 远程执行 |
ROUTA_RUST_BACKEND_URL |
Web 端指向本地后端服务器 |
实践建议:只设置你实际使用的那条 Provider 路径对应的变量即可。
- 🖥️ 桌面用户:通常在应用内直接填入 Provider 专属凭据
- 💻 CLI 用户:通常全局配置一个 Provider
- 🌐 Web 贡献者:本地开发时设置
ROUTA_RUST_BACKEND_URL
API 型 Provider 的自动探测逻辑(如检测到 ANTHROPIC_AUTH_TOKEN 即标记为 available)位于 src/core/acp/api-based-providers.ts。
验证接入是否成功:跑通第一个 Session
配置完成后,最短验证路径来自 docs/quick-start.md:
- 创建 Workspace 并启用一个 Provider
- 挂载一个真实代码仓库
- 打开 Session,提问:
Explain the architecture of this repository
如果得到了有用的回答,你的 Provider 配置就已经成功。CLI 用户同样可以用一行命令做冒烟测试:
routa -p "Explain the architecture of this repository"
还可以用以下命令检查运行时状态:
routa acp list
routa acp runtime-status
多模型协同的原理:Provider 归一化
理解这一点能帮你少走弯路:Routa 通过每个 Provider 的独立 Adapter 层把 Claude Code、OpenCode 等不同事件流统一归一为 ACP 会话更新(设计决策见 docs/adr/0002-provider-normalization-via-acp.md)。
Provider 进程或桥接层
→ 各 Provider 私有输出
→ Adapter 归一化
→ 统一会话更新
→ 持久化、Trace、UI 流式渲染
因此「哪个模型跑哪个角色」是 Provider 层的事,而角色默认值(Role Defaults)绑定发生在配置层——这正是你能一站式切换 Claude Code、Codex、OpenCode 的底层保障。
常见问题速查
Q:装了多个 Provider,界面显示不可用?
先确认对应环境变量已注入。API 型 Provider 只有在检测到 Key 或 Server URL 时才会标记为 available(逻辑见 src/core/acp/api-based-providers.ts)。
Q:Serverless 环境能用 CLI 型 Provider 吗? 不能。像 Codex 这类需要派生长驻子进程的 CLI Provider 在 Vercel 等 Serverless 环境不可用,建议改用 Claude Code SDK 或 OpenCode SDK 这类 HTTP API 路径(同样定义在 src/core/acp/api-based-providers.ts)。
Q:需要配置所有 Provider 吗? 不需要。一个可用的 Provider + 一条可用的模型路径,就是完整上手所需的全部。
小结
Routa 的 Providers 配置遵循「先跑通一个,再扩展更多」的原则:
- ✅ 在 Providers 中启用一个运行时(Claude Code / Codex / OpenCode)
- ✅ 按需配置 Models 与 Role Defaults 完成角色绑定
- ✅ 用一次真实仓库的 Session 提问验证结果
掌握这套流程后,你就可以在多模型协同的工作流中自由切换 Provider,把 AI 开发协作的复杂度降到最低。


