T3 Code 接入国产大模型全流程：从 Ollama 本地模型到 OpenAI 兼容接口

T3 Code 接入国产大模型全流程：从 Ollama 本地模型到 OpenAI 兼容接口

【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code

开源 AI 编程工具圈在 2026 年出现了一个明显的分化：一边是 Cursor、Copilot 这类"编辑器内嵌助手"继续卷体验，另一边则是以 T3 Code 为代表的"Agent 控制台"流派——它不写一行补全代码，而是把 Claude Code、Codex、OpenCode 等命令行 Agent 收进同一个会话面，统一管理认证、上下文与成本。而对国内开发者来说，T3 Code 真正有吸引力的地方在于：它把"接哪个模型"这件事做成了开放的插槽。无论是本地跑的 Ollama，还是各家国内服务商提供的 OpenAI 兼容接口，都能以 Profile（Provider Instance）的形式接入、切换、混跑。本文结合仓库源码与社区实操反馈，拆解从本地模型到兼容接口的完整接入链路，并给出"本地省钱、云端攻坚"的混合调度思路。

一切从 Provider Instance 说起：驱动与实例分离的设计

要理解 T3 Code 为什么能轻松接上 Ollama 和五花八门的 OpenAI 兼容服务，得先看它在契约层的两个核心概念：ProviderDriverKind与ProviderInstanceId。

在 packages/contracts/src/providerInstance.ts 的模块注释中写得很清楚：ProviderDriverKind是"实现类型选择器"（例如codex、claudeAgent，或者某个 fork 的ollama），它决定由哪个 driver 包来处理协议、探针、适配器与文本生成；而ProviderInstanceId是路由键——线程、会话、持久化绑定只引用实例 ID，从不直接引用驱动类型。这意味着同一个 driver 可以配置出多个实例（比如codex_personal+codex_work），每个实例拥有完全独立的配置：

export const ProviderInstanceConfig = Schema.Struct({ driver: ProviderDriverKind, displayName: Schema.optional(TrimmedNonEmptyString), accentColor: Schema.optional(TrimmedNonEmptyString), environment: Schema.optionalKey(ProviderInstanceEnvironment), enabled: Schema.optionalKey(Schema.Boolean), config: Schema.optionalKey(Schema.Unknown), });

注意config字段的类型是Schema.Unknown——契约层刻意不关心 driver 的具体配置长什么样，每个 driver 自己注册解码器。这个"信封（envelope）"设计带来两个关键能力：一是用户可以在设置里塞入任何驱动 slug，二是即使当前构建不认识某个驱动，配置也能无损地 round-trip 持久化，不会因为回滚或切换 fork 分支而丢数据。

Ollama 本地模型的 Profile 配置

社区反馈中反复提到"Ollama 本地模型"的接入，而仓库源码里，ollama正是作为"未知驱动可无损落盘"的典型例子出现的。

在 packages/contracts/src/settings.test.ts 的多实例混合配置测试里，作者专门构造了一个官方构建并不内置ollamadriver 的场景，验证配置必须完整往返：

ollama_local: { driver: "ollama", displayName: "Ollama (local)", config: { endpoint: "http://localhost:11434" }, },

测试注释点明了设计意图：ollama不在内置ProviderDriverKind集合里，但这种配置必须 round-trip 不丢失，因为"驱动未安装"是运行时的事，契约层不该拒绝它。也就是说，Ollama 的接入路径在架构上被明确预留：本地起ollama serve（默认端口 11434），在 T3 Code 的 Provider 设置里新建一个实例，driver填ollama（或 fork 提供的对应驱动 slug），config指向本地端点即可。

再看 packages/contracts/src/modelSelection.test.ts，它展示了模型选择如何以实例为路由键：

const parsed = yield* decodeModelSelection({ provider: "ollama", model: "llama3:70b", options: [{ id: "temperature", value: "0.4" }], }); // parsed.instanceId === "ollama"

解码后统一收敛为{ instanceId, model, options }的规范形态——历史版本里provider字段被自动提升为默认实例 ID，新老数据无缝兼容。这就是为什么社区教程里"给 Ollama 配一个 Profile，选 llama3 或 qwen 系列本地模型"的操作，在 T3 Code 里是一条被设计者显式测试过的路径，而非临时 hack。

值得注意的还有实例级环境变量机制：packages/contracts/src/providerInstance.test.ts 展示了每个实例可以携带独立的environment数组，支持sensitive标记与名称校验。对于本地模型，这个插槽通常不需要（无 API Key），但它为下一节讲到的"兼容接口 + 国内服务商"场景提供了统一的密钥承载方式。

OpenAI 兼容接口与国内服务商接入适配

国内开发者接触最多的其实是另一条路：服务商（包括各类国产大模型 API 平台与中转站）几乎清一色提供 OpenAI 兼容的/v1/chat/completions接口。T3 Code 对这条路的适配，集中体现在 OpenCode 这条驱动链路上。

packages/provider-opencode/src/server/openCode2Catalog.test.ts 的测试夹具直接给出了一个典型的"OpenAI 兼容"驱动形态：

{ "id": "step-5-preview-free", "modelID": "step-5-preview-free", "providerID": "opencode-go", "package": "@opencode/ai/providers/openai-compatible", "settings": { "apiKey": "sk-demo-not-real", "baseURL": "http://127.0.0.1:48990/v1", "provider": "opencode-go" } }

package字段指名道姓地写着openai-compatible，settings里的baseURL指向任意实现了 OpenAI 协议的服务端点。这意味着：只要国产服务商给出baseURL + apiKey，就能作为一个 provider 注册进 OpenCode 的模型目录，再由 T3 Code 的 OpenCode 驱动统一拾取。模型目录加载逻辑在 openCode2Catalog.ts 中实现：一个实例可以同时"front"多个 provider（OpenCode Zen、OpenCode Go，以及用户自己添加的任何兼容端点），模型名可能重叠，因此目录读取会同时拉取 model list 与 provider list，用 provider 名称区分同名模型，避免选错服务商。

对走 OpenAI 官方协议但想自建网关的场景，契约层同样留好了路：实例信封上的environment数组允许注入任意环境变量，providerInstance.test.ts 里就有ANTHROPIC_BASE_URL+OPENROUTER_API_KEY的组合示例——把BASE_URL指向国内中转或兼容网关，把 Key 标为sensitive: true，即可在一个实例内完成"协议不变、端点替换"的适配。

混合调度：本地模型省钱、云端模型攻坚

社区讨论中最实用的一条经验是"别让一个 Profile 走天下"：日常的代码补全、命名、简单重构这类高频低难度任务，交给 Ollama 本地小模型（如 qwen2.5-coder 的 7B/14B 档位），零 API 费用、数据不出本机；遇到跨文件重构、架构设计、疑难 bug 定位这类需要长上下文与强推理的攻坚任务，再切到云端模型。T3 Code 的架构恰好为这种"双轨制"提供了原生支撑。

首先是多实例并行。前文已述，路由键是ProviderInstanceId而非驱动类型，因此ollama_local与某个云端兼容实例可以同时存在、互不干扰。注册表 ProviderInstanceRegistry.ts 会在设置变更时增量创建/拆除实例，每个实例运行在自己的子作用域（childScope）内，关闭注册表时统一清理——实例之间的状态天然隔离。

其次是按线程粒度切换。模型选择收敛为ModelSelection结构（packages/contracts/src/modelSelection.ts），线程、会话、持久化绑定都只认instanceId。也就是说，一个项目里可以并行开多个线程：A 线程绑ollama_local跑低成本的探索性改动，B 线程绑云端攻坚实例跑高价值的重构，两个线程共享同一份项目上下文，但模型路由彼此独立。

最后是降级与回滚的容错。设计者把"驱动未知"当作一等公民处理：unavailableProviderSnapshot.ts 会为当前构建不认识的驱动合成availability: "unavailable"的阴影快照，UI 正常渲染"缺失驱动"提示而不会崩溃。这意味着即使你某天切回旧版本、或某个 fork 的ollama驱动暂时不可用，已有的配置、线程与绑定都不会丢失，恢复构建后立即复活。

这套组合策略在社区评测里被反复验证：把日常 token 消耗压在本地模型上，把预算集中在真正值得的攻坚任务上，既能控制成本，又不牺牲关键任务的完成质量。

小结

T3 Code 接入国产大模型的全流程，本质上不是"对接某个厂商 SDK"，而是踩在三条设计原则上完成的：驱动与实例分离（一个驱动 N 个配置）、契约层对未知驱动无损兜底（fork 与回滚都安全）、模型选择按实例路由（线程级切换零成本）。Ollama 本地模型只需一个指向localhost:11434的实例；OpenAI 兼容接口只需baseURL + apiKey注册进 OpenCode 目录；两者的混合调度则由多实例并行与线程级路由天然支撑。对于既要数据本地化、又要云端算力的国内开发者，这几乎是当前最顺滑的接入路径。

【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code